Files
pipelines/docs/notes/background-shell-visibility.md
T
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

2.5 KiB

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.