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.
8.9 KiB
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—ExportSessionrenders and writes exactly one file,session.html, viawriteSessionFile; the markdown renderer (renderSessionMarkdownand its message/part/tool helpers), themarkdownTruncationBanneranddynamicFenceare gone, andSessionExportResultcarriesHTML/HTMLBytesonly.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—SessionExportdropsmarkdownandmarkdown_bytes; a record written before this change still decodes (Go's JSON decoder ignores the unknown fields). It also carries the sharedLegacySessionMarkdownArtifact = "session.md"name andRunStep.PresentedArtifacts(), the one Go rule that filters the retired markdown out of every artifact listing (mirroring the app'spresentedArtifacts); the stored record is untouched.internal/server/runner.go—evidence.Markdown/MarkdownBytesare no longer copied into the recorded step evidence.internal/stage/session_export.gokeepsSessionMarkdownFile = protocol.LegacySessionMarkdownArtifactas the single definition of the retired name; the artifact inventory still lists whatever is on disk, so an older run's recordedsession.mdis filtered where it is presented, not in the server's evidence.internal/tui/artifacts.goandinternal/tui/file_changes.go— the TUI's artifacts panel, its recorded count and its per-visit summary (runArtifactVisits,artifactsSummary,artifactCaptureNotes) all derive fromRunStep.PresentedArtifacts(), so the terminal never lists a session markdown beside the session html either.web/src/app.js— the web spike'srenderArtifactsapplies the same filter, so a legacysession.mdis not linked besidesession.htmlthere 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,sessionArtifactand theSessionLoad.Markdownbranch (its use of the shared markdown renderer) are removed;sessionExportFileresolves the recorded html name against the visit's artifacts.data/protocol/Message.kt—SessionExportdropsmarkdown/markdown_bytes(the app'sJsonalready setsignoreUnknownKeys).ui/ArtifactGroups.kt— newpresentedArtifacts(step)filters the retiredsession.mdout of every artifact listing, andLEGACY_SESSION_MARKDOWN_ARTIFACTnames it. It is used byartifactsSummaryandartifactCaptureNotes(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 withsession.mdin 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→ allok;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, onesession.html(5120 bytes, 3 messages) listed and served HTTP 200, nosession.md. The exported document is saved assession-export-live-evidence.html. - Android:
:app:assembleDebugand: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 packagesok, no failures;go test ./internal/tui ./internal/protocol→ bothok. The web spike'ssrc/app.jspassesnode --checkandnode --test test/→ 20/20 pass (the spike has no DOM test for its render helpers). The advisory's non-allocatinghasArtifacts(ui/screens/Timeline.kt) is applied too; the Android:app:assembleDebugand:app:testDebugUnitTest→ BUILD SUCCESSFUL after it. - On screen (Pixel 9 Pro XL
47241FDAS00DLK, the deployed server atws://10.0.0.75:8080/connect, never restarted): a run recorded before the change (run 344) showsArtifacts · 3 recordedwhere the old build showed5 recorded, the committer visit showsArtifacts · 1 recordedlisting onlysession.html 67.2 KiB(thesession.md 60.9 KiBtile 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 md536a6ffc7…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 writessession.mdandsession.html"in markdown … and html", that "the bounded inventory lists them" and thatGET /artifacts/<run>/<step>/session.md(or.html) serves them, that "both files carry a visible truncation banner", that the step recordssession_exportwithmarkdown,html,markdown_bytes,html_bytes, and that an existingsession.md/session.htmlis never overwritten. It should say the export writes exactly one file,session.html; that the retiredsession.mdis 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 recordedsession_exportissession_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) andinternal/author/skill/references/delivery.md(around lines 20–21) — both still describe thesession.md+session.htmlpair, the two-file bounds and the pair's never-overwrite rule. The brief assigns these packaged references to the committer; they should describe the singlesession.htmlexport, the 2 MiB rendered-file cap, and that the retiredsession.mdis neither produced nor presented.docs/app-integration-verification.mdline 38 — a dated verification record of run 330 whose artifacts-gallery row listssession.md 81.7 KiBbesidesession.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.mdandinternal/author/skill/SKILL.mdcarry nosession.mdreference.- No reference file is added or removed, so
internal/author/install.go's managed inventory is unchanged. docs/cli.mddoes not enumerate thesession_exportfields.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 retiredsession.mdthe same way the app does).web/src/app.jsis a throwaway spike with no test for its render helpers; its artifact list now applies the same filter.