Files
pipelines/docs/notes/session-html-only.md
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

149 lines
8.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.