95362134aa
A stage's session was exported twice, as session.md and session.html, and both files were presented. It is now one html file; the markdown export is retired. - internal/stage/session_export.go: ExportSession renders and writes exactly one file, session.html, via writeSessionFile; renderSessionMarkdown and its helpers are gone; SessionExportResult carries HTML/HTMLBytes only. The source read, the 8 MiB source / 2 MiB rendered bounds, the truncation banner, the never-overwrite rule and the honest empty-session handling are unchanged. - internal/protocol/runs.go: SessionExport drops markdown/markdown_bytes (a record written before the change still decodes; unknown fields are ignored), and adds LegacySessionMarkdownArtifact with RunStep.PresentedArtifacts(), the one Go rule that hides the retired session.md from every artifact listing. - internal/server/runner.go: evidence.Markdown/MarkdownBytes are no longer copied. - internal/tui: the artifacts panel, the recorded count and the per-visit summary derive from PresentedArtifacts(), so the terminal never lists session.md. - web/src/app.js: the spike's renderArtifacts applies the same filter. - android: the Session section is the html export alone in a WebView — SessionView, the Markdown/HTML toggle and the session markdown path are removed; presentedArtifacts(step) filters the retired session.md out of the per-visit gallery, the run gallery and its count, the verdict/selection lists and the timeline indicator; data/protocol SessionExport drops the markdown fields. - Tests pin the single html file, prove no session.md is written and that a pre-existing one is neither overwritten nor presented, and prove a legacy export record still loads and its session.md is hidden. The legacy session.md of an older run stays on disk (dated evidence); it is only no longer produced and no longer presented. Checks (macOS, Go 1.24, Android Gradle 8.11.1, 18 Oct 2026): gofmt -l . prints nothing; go build ./... && go vet ./... clean; go test ./internal/... ./cmd/... -> 19 packages ok, 0 failures; node --check web/src/app.js ok and node --test web/test -> 20/20; gradle --offline --no-daemon :app:assembleDebug :app:testDebugUnitTest -> BUILD SUCCESSFUL. Packaged references checked: internal/author/skill/references/delivery.md and operations.md both described the session.md+session.html pair, so both are updated here to describe the single session.html export and the retired, hidden session.md. README.md and internal/author/skill/SKILL.md carry no session.md reference and install.go's managed inventory is unchanged (no reference added or removed). docs/notes/session-html-only.md records the remaining stale shared documentation (docs/stage-artifacts.md, docs/app-integration-verification.md) for the docs-fold writer; shared docs are not edited by this item.
149 lines
8.9 KiB
Markdown
149 lines
8.9 KiB
Markdown
# Session export: html only, the markdown export retired
|
||
|
||
## What this item changed
|
||
|
||
A stage's session was exported twice, as `session.md` and `session.html`, and both
|
||
files were presented. It is now one html file; the markdown export is retired.
|
||
|
||
Server side (`internal/stage`, `internal/protocol`, `internal/server`,
|
||
`internal/pipeline`):
|
||
|
||
- `internal/stage/session_export.go` — `ExportSession` renders and writes exactly
|
||
one file, `session.html`, via `writeSessionFile`; the markdown renderer
|
||
(`renderSessionMarkdown` and its message/part/tool helpers), the
|
||
`markdownTruncationBanner` and `dynamicFence` are gone, and
|
||
`SessionExportResult` carries `HTML`/`HTMLBytes` only. `SessionMarkdownFile =
|
||
"session.md"` is kept as the single definition of the retired name. The source
|
||
read, the size bounds (`SessionExportSourceLimit`, `SessionExportFileLimit`),
|
||
the truncation banner, the never-overwrite rule and the honest empty-session
|
||
handling are unchanged.
|
||
- `internal/protocol/runs.go` — `SessionExport` drops `markdown` and
|
||
`markdown_bytes`; a record written before this change still decodes (Go's JSON
|
||
decoder ignores the unknown fields). It also carries the shared
|
||
`LegacySessionMarkdownArtifact = "session.md"` name and
|
||
`RunStep.PresentedArtifacts()`, the one Go rule that filters the retired
|
||
markdown out of every artifact listing (mirroring the app's
|
||
`presentedArtifacts`); the stored record is untouched.
|
||
- `internal/server/runner.go` — `evidence.Markdown`/`MarkdownBytes` are no longer
|
||
copied into the recorded step evidence.
|
||
- `internal/stage/session_export.go` keeps `SessionMarkdownFile =
|
||
protocol.LegacySessionMarkdownArtifact` as the single definition of the retired
|
||
name; the artifact inventory still lists whatever is on disk, so an older run's
|
||
recorded `session.md` is filtered where it is presented, not in the server's
|
||
evidence.
|
||
- `internal/tui/artifacts.go` and `internal/tui/file_changes.go` — the TUI's
|
||
artifacts panel, its recorded count and its per-visit summary
|
||
(`runArtifactVisits`, `artifactsSummary`, `artifactCaptureNotes`) all derive
|
||
from `RunStep.PresentedArtifacts()`, so the terminal never lists a session
|
||
markdown beside the session html either.
|
||
- `web/src/app.js` — the web spike's `renderArtifacts` applies the same filter,
|
||
so a legacy `session.md` is not linked beside `session.html` there either.
|
||
|
||
App side (`android/`):
|
||
|
||
- `ui/graph/SessionExport.kt` — the Session section is the html export alone in a
|
||
WebView. `SessionView`, the Markdown/HTML toggle, `defaultSessionView`,
|
||
`sessionViewToggle`, `sessionArtifact` and the `SessionLoad.Markdown` branch
|
||
(its use of the shared markdown renderer) are removed; `sessionExportFile`
|
||
resolves the recorded html name against the visit's artifacts.
|
||
- `data/protocol/Message.kt` — `SessionExport` drops `markdown`/`markdown_bytes`
|
||
(the app's `Json` already sets `ignoreUnknownKeys`).
|
||
- `ui/ArtifactGroups.kt` — new `presentedArtifacts(step)` filters the retired
|
||
`session.md` out of every artifact listing, and
|
||
`LEGACY_SESSION_MARKDOWN_ARTIFACT` names it. It is used by `artifactsSummary`
|
||
and `artifactCaptureNotes` (`ui/Format.kt`), the run gallery and its count
|
||
(`runArtifactGroups`, `runArtifactsHeader`), the per-visit gallery
|
||
(`ui/graph/Artifacts.kt`), the verdict block and the selection candidates
|
||
(`ui/graph/StageDetailPane.kt`) and the timeline indicator
|
||
(`ui/screens/Timeline.kt`). The app hides the legacy file because a run
|
||
recorded before the change carries it in its stored artifact list and the
|
||
server it talks to during review is not redeployed, so the list still arrives
|
||
with `session.md` in it.
|
||
|
||
Tests were updated to pin the single html file and to prove no `session.md` is
|
||
written, a pre-existing one is neither overwritten nor presented, and a legacy
|
||
export record still loads. `internal/protocol` and `internal/tui` gained cases
|
||
proving `PresentedArtifacts` hides the retired name, leaves the stored record
|
||
untouched, and that the TUI panel, recorded count and per-visit summary hide it
|
||
(the follow-up that the review's MUST-FIX named).
|
||
|
||
## Evidence (macOS, Go 1.24 toolchain, Android Gradle 8.11.1, 18 Oct 2026)
|
||
|
||
- `go build ./... && go vet ./...` → clean; `gofmt -l .` → prints nothing.
|
||
- `go test ./internal/stage ./internal/pipeline ./internal/protocol` → all `ok`;
|
||
`go test ./internal/server` → `ok` (12.5 s); `go test ./...` → ok.
|
||
- Real export through the server's own live test path (a fresh OpenCode stage on
|
||
a temporary store, no inference budget beyond one stage):
|
||
`PIPELINES_SESSION_EXPORT_LIVE=1 PIPELINES_SESSION_EXPORT_MODEL=opencode-go/deepseek-v4.1-flash
|
||
go test ./internal/server -run TestSessionExportLive -v` → `PASS`, one
|
||
`session.html` (5120 bytes, 3 messages) listed and served HTTP 200, no
|
||
`session.md`. The exported document is saved as
|
||
`session-export-live-evidence.html`.
|
||
- Android: `:app:assembleDebug` and `:app:testDebugUnitTest` → both BUILD
|
||
SUCCESSFUL.
|
||
- Follow-up addressing the review's MUST-FIX (18 Oct 2026): `gofmt -l .` prints
|
||
nothing; `go build ./... && go vet ./...` → clean;
|
||
`go test ./internal/... ./cmd/...` → `GO-EXIT=0`, 19 packages `ok`, no
|
||
failures; `go test ./internal/tui ./internal/protocol` → both `ok`. The web
|
||
spike's `src/app.js` passes `node --check` and `node --test test/` → 20/20
|
||
pass (the spike has no DOM test for its render helpers). The advisory's
|
||
non-allocating `hasArtifacts` (`ui/screens/Timeline.kt`) is applied too; the
|
||
Android `:app:assembleDebug` and `:app:testDebugUnitTest` → BUILD SUCCESSFUL
|
||
after it.
|
||
- On screen (Pixel 9 Pro XL `47241FDAS00DLK`, the deployed server at
|
||
`ws://10.0.0.75:8080/connect`, never restarted): a run recorded before the
|
||
change (run 344) shows `Artifacts · 3 recorded` where the old build showed
|
||
`5 recorded`, the committer visit shows `Artifacts · 1 recorded` listing only
|
||
`session.html 67.2 KiB` (the `session.md 60.9 KiB` tile is gone), and the
|
||
Session section renders the html document in the WebView with no
|
||
Markdown/HTML toggle. Captures are attached to this stage. The device was
|
||
contended by a concurrent lane (another build was installed over this one and
|
||
taps were interleaved), which is why some intermediate captures show the old
|
||
build; the proofs are the ones with the WIP md5 `36a6ffc7…` verified installed.
|
||
The phone was left on main's build (`deploy-app.sh main`, md5 verified).
|
||
|
||
## Shared documents this change makes stale
|
||
|
||
The note is written here rather than edited in place; the `docs-fold` writer
|
||
should update these.
|
||
|
||
- `docs/stage-artifacts.md` — the "Session export" section (about lines 55–83)
|
||
says the export writes `session.md` and `session.html` "in markdown … and
|
||
html", that "the bounded inventory lists them" and that
|
||
`GET /artifacts/<run>/<step>/session.md` (or `.html`) serves them, that
|
||
"both files carry a visible truncation banner", that the step records
|
||
`session_export` with `markdown`, `html`, `markdown_bytes`, `html_bytes`, and
|
||
that an existing `session.md`/`session.html` is never overwritten. It should
|
||
say the export writes exactly one file, `session.html`; that the retired
|
||
`session.md` is no longer produced and is not presented (a run recorded before
|
||
the change still lists it in its stored artifacts, and the app hides it); that
|
||
the one rendered file carries the banner; and that the recorded
|
||
`session_export` is `session_id`, `backend`, `source`, `html`, `html_bytes`,
|
||
`messages`, `truncated`, `diagnostic`, with a record written before the change
|
||
still decoding because the retired fields are ignored.
|
||
- `internal/author/skill/references/operations.md` (around lines 235–250) and
|
||
`internal/author/skill/references/delivery.md` (around lines 20–21) — both
|
||
still describe the `session.md`+`session.html` pair, the two-file bounds and
|
||
the pair's never-overwrite rule. The brief assigns these packaged references to
|
||
the committer; they should describe the single `session.html` export, the
|
||
2 MiB rendered-file cap, and that the retired `session.md` is neither produced
|
||
nor presented.
|
||
- `docs/app-integration-verification.md` line 38 — a dated verification record of
|
||
run 330 whose artifacts-gallery row lists `session.md 81.7 KiB` beside
|
||
`session.html`. It is a historical record for that run and date; if it is kept
|
||
as dated evidence it needs no edit, but a reader should not take it as current
|
||
behaviour.
|
||
|
||
## Not stale
|
||
|
||
- `README.md` and `internal/author/skill/SKILL.md` carry no `session.md`
|
||
reference.
|
||
- No reference file is added or removed, so `internal/author/install.go`'s
|
||
managed inventory is unchanged.
|
||
- `docs/cli.md` does not enumerate the `session_export` fields.
|
||
- `internal/tui`'s artifacts panel did reference the recorded artifact list, so it
|
||
was changed with this item (it and the web spike now filter the retired
|
||
`session.md` the same way the app does).
|
||
- `web/src/app.js` is a throwaway spike with no test for its render helpers; its
|
||
artifact list now applies the same filter.
|