Files
pipelines/docs/notes/session-html-only.md
T
alan 95362134aa session export: write only session.html, retire the markdown export
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.
2026-10-18 10:06:49 +01:00

8.9 KiB
Raw Blame History

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.