Files
pipelines/docs/notes/background-shell-visibility.md
alan e9d902213e Preserve background shell visibility across readback races
Reconcile authoritative shell snapshots with bounded lifecycle journals so concurrent exits and creates cannot be overwritten, coalesce observation setup, and retain verified ownership across reconnects. Add deterministic reconciliation and cancellation regressions plus stable limited-visibility handling.\n\nChecked packaged templates and authoring skill references: none need updating. The task-owned docs note records the stale shared chat documentation for docs-fold; shared documentation was not edited.
2026-10-18 12:54:36 +01:00

38 lines
2.5 KiB
Markdown

# Background shell visibility
The chat server now opens the broker stream for read-only subscribers and reconciles verified running shell operations from OpenCode's authoritative `/api/shell` readback. The packaged OpenCode skill references and chat documentation should describe that shell visibility survives reconnects only when OpenCode reports explicit `metadata.sessionID` ownership; shared working directories are not ownership evidence.
## Current source behavior
Observers share one initial readback per room/stream attachment. The adapter and hub
fold bounded lifecycle journals over each snapshot, so a stale read cannot resurrect
an exited shell or erase a concurrent create. Shell replay and live delivery enqueue
in fold order. Cancellation rejects old-room callbacks and releases local identity
state before reconnect. Journals retain at most 256 identities and 1 MiB of id/command
text; capacity/read failures surface stable limited-visibility text, never broker
response bodies. No shell polling was added. OpenCode's terminal `timeout` and
`killed` statuses are excluded from retained running operations as well as `exited`.
## Verification evidence — 2026-10-18
`opencode api get /openapi.json` authenticated through supported service discovery.
The live schema advertises shell list/detail/output and generic `metadata`; it does
not type `metadata.sessionID`. A throwaway session
`ses_eb12ab7b3ffe0ZAle7PHpftHMG` and its own `sleep 1` shell
`sh_14ed57134001e6fuYqvn62pKit` verified actual create/detail readback preserving
explicit `metadata.sessionID`, status `running`, subsequent `exited`/exit 0, and
absence from the running list. This verifies explicit API metadata, not automatic
agent-tool ownership injection. The CLI event attempt yielded no captured events;
live-provider event ordering is **not tested**. Forced ordering evidence comes from
channel/barrier regressions, including a real WebSocket handler on a loopback scratch
server with fresh SQLite, not from the deployed service.
## Documentation follow-up / deployment
`docs/chat-verification.md` and the chat subscribe/replay section of `docs/cli.md`
are stale: docs-fold should describe authoritative ownership/readback, coalesced
observation, bounded reconciliation and limited-visibility errors, distinguishing
fixture ordering evidence from the live readback above. Shared docs and packaged
skill references were not edited here. No deployment, installation, service restart
or physical-phone/UI verification was performed; this changes no rendered layout.