BDD Session Lifecycle cluster: implementation plan

At a glance

Scenarios this unblocks (and which to implement alongside the framework PR)

Implementing this plan means flipping these specific scenarios from @pending to validated. The list below is the full session-lifecycle cluster from the walks plan; the phasing in §Phasing says which PR each one lands in.

Count: 6 scenarios flip from @pending to validated. PR 1 (~1–1.5 days) flips the primary outcome scenario alone — that's the critical-path unblock. PR 2 adds the slash-command mechanism row. PR 3 needs #27 multi-persona to land first for the “public view of sessions” scenario's second-persona assertion. PR 4 fans out the remaining kept-separate scenarios.

What this list does not include: any scenarios outside session-recording.feature. The session-lifecycle cluster is bounded to the recording journey; agent-priming, team-context, and the rest of context-injection/ stay where they are.

Reframing the deferral

The walks plan deferred Walk 07 (“agent session recording”) and the entire session-recording.feature consolidation behind “TUI driver maturity.” The user has corrected this: the driver exists and works. The two real questions are:

1. What needs to be added to the verb catalog (CLI · filesystem · web) so the existing TUI verbs can be composed into a full session-lifecycle scenario?
2. Which assertions in the journey are best expressed as filesystem reads or ox CLI calls rather than re-entering the TUI for an LLM round-trip? The user's hint — “you need to consider using the file system and ox cli for verifying that sessions are recorded and landed” — is the load-bearing one. The ledger is a git repo on disk under ~/.cache/sageox/context/, and ox session list already merges local + ledger sessions into JSON. Most Then assertions can read that surface directly.

This plan is structured around those two questions.

Existing TUI driver inventory

Read in full: tests/acceptance/drivers/tui/claude-code/{start,stop,prompt}.ts. Summary below; the actual files are heavily commented and worth re-reading before authoring an adjacent verb.

What's NOT in the existing TUI driver:

• No verb wraps a slash command (/ox-session-start / /ox-session-stop). The slash command is — per extensions/claude/commands/ox-session-start.md — a thin wrapper that types ox agent session start into the TUI input box. So “slash command” is just tui/claude-code/prompt with the slash text. No new verb needed for the slash path.
• No verb does “execute a CLI command inside the workspace's host context.” The CLI path (ox agent <id> session start) needs a new cli/ox/session/* family.
• No verb reads the ledger filesystem to confirm artifacts landed.

agent-tui scope (clarification)

agent-tui is an external open-source project by Paulo Proença (github.com/pproenca/agent-tui), Rust-based, Unix-only, providing PTY emulation + keyboard/text input + screen capture + a JSON-RPC WebSocket for live preview. Not a SageOx package — we consume the published binary inside the bdd-tui Shuru checkpoint and talk to it via tui-drive (also external; the adapter that knows the Claude-Code-specific launch flags). Pinned to v1.0.1 in the BDD VM image.

Spec reference: ~/src/github.com/pproenca/agent-tui/README.md. Local IPC over AGENT_TUI_SOCKET, HTTP listener pinned to 127.0.0.1 inside the microVM. Session storage at ~/.agent-tui/* on the bdd user.

What this means for the plan: we don't own agent-tui's capability surface. New TUI verbs are limited to combinations of start / send-keys / prompt / screenshot / stop that tui-drive already exposes. The session-lifecycle journey doesn't need anything outside that surface.

The session recording journey (recap of walks-plan §Session lifecycle consolidation)

The journey: start recording → drive Claude interactions → stop → artifacts committed to the ledger → visible in N places. The walks plan collapses the current 6 split scenarios into:

## AFTER — one outcome scenario, mechanism as a column row
  Rule: Recording a session produces a committed, team-visible artifact
    Scenario Outline: Marcus records a session started via <mechanism>
      Given Claude has been primed in Marcus's repository
      When Marcus starts session recording via <mechanism>
      And he interacts with Claude
      And he stops the session recording
      Then the session should be committed to the repository's ledger with a summary and transcript
      And the session should appear on the "Acme Engineering" team's sessions page
      And the session should appear in the recent sessions on the repository detail page

      Examples:
        | mechanism                       |
        | /ox-session-start slash command |
        | ox session start CLI            |

Kept separately (legitimate distinct concerns):

1. Sessions from multiple repositories appear in one list composition-as-Given
2. Interrupted session is recovered by the daemon failure-recovery property
3. Team member previews the public view of sessions visibility toggle
4. Session artifacts reflect the interaction content content fidelity

Then-assertion machinery needed (where each clause lands):

System interactions needed (new verbs)

Mapped to the journey's three phases. Existing verbs in green; new in amber.

Tally of new work: 4 new CLI/FS verbs (all small — shell-out + JSON parse + assertion), 2 new web verbs (medium — new selectors needed but stock Playwright pattern), 0 new TUI verbs.

Filesystem + ox CLI verifications (the user's hint, made concrete)

The ledger is a git repo on disk. ox already maintains it. The cheapest, most deterministic verification surface is therefore the on-disk artifacts and ox's own read commands — not a re-entry into the TUI.

Driver implementation gaps

For each verb the cluster needs, here's whether it exists and what the work looks like.

Total effort: 6 small (each ~1 hour incl. tests) + 2 medium (each ~half-day, mostly figuring out the right Playwright selectors against the actual web app). Two days of focused work end-to-end. Compare to the walks-plan deferral framing which implied weeks of TUI driver work.

ox CLI surface pointers (for the BA author)

Findings from reading ~/src/github.com/sageox/ox/cmd/ox/. The user-facing surface is:

ox session                       # parent command (Short: "Manage AI coworker sessions")
├── list                          # JSON by default; merges local + ledger sessions
├── show [session-name]           # alias of `view`
├── view [session-name]           # render a session
├── stop                          # `Stop a recording session` (force-stop)
├── commit                        # `Commit pending sessions` (manual push)
├── lint [session-name]
├── export [session-name]
├── download <session-name>
├── upload <session-name>
├── regenerate [session-name]
└── (read-only ops; no `start` here — start is under `ox agent`)

ox agent <id> session            # the recording-control surface
├── start [--title "…"]           # begins recording; emits sessionStartGuidance
├── stop                          # ends recording; in sync mode returns summary_prompt
├── abort
├── log
├── recover
├── plan                          # pipe-in for plan capture
└── (other internal sub-tasks)

Key surface facts the BA author needs to know:

1. Start lives under ox agent <id> session start, not ox session start. The walks-plan Outline row labelled “ox session start CLI” is shorthand; the verb shells out to ox agent <id> session start --json. The Gherkin can keep the user-friendly phrasing.
2. JSON is the default output for session commands. No need to add --json — that's already the default per the comment in agent_session.go: “Agents are the primary consumers of these commands.” Pass --text only if asserting on human output (we shouldn't).
3. The session_id is opaque. Use whatever start returns; don't try to construct or parse it.
4. Stop has a sync/async mode. In sync mode the JSON includes a summary_prompt field that an agent uses to generate the summary itself. For BDD we use async (default) so summary generation happens in-daemon and we can poll ox session list for uploaded: true.
5. ox session commit is a manual push. Should not normally be needed — the ledger daemon (docs/ai/specs/ledger-daemon.md) syncs continuously. If the BDD VM doesn't run the daemon, the verification verb falls back to local-cache path (~/.cache/sageox/context/cache/sessions/) rather than the synced ledger; document this caveat in the verification's L2 contract.

The ledger as a verification target

Per CLAUDE.md: the ledger is a user-writable git repo; treat its content as untrusted. Per ox/docs/ai/specs/ledger-daemon.md: the ledger lives at ~/.cache/sageox/context/ with sparse-checkout of sessions/. Per ox/internal/session/pipeline/types.go: each session directory contains raw.jsonl, summary.md, session.md, and optionally plan.md.

Recommendation: verify via ox session list --json, fall back to FS stat.

• Why not git log: requires the ledger checkout to be at the right ref. The daemon's sync model can leave the local checkout transiently behind the upstream commit graph. We'd end up asserting on a race surface.
• Why not parse commit messages: commit-message format is implementation detail of the upload pipeline; not part of the user-facing contract. Brittle.
• Why ox session list wins: it's the same code path the user runs to confirm their session landed. Asserting against it asserts against the actual product surface, with all the caveats baked in (cache-vs-uploaded transition, ledger-available flag). It's also fast: one subprocess, JSON, no git.
• FS fallback is fine for tighter assertions: “summary.md contains >500 bytes” or “raw.jsonl has ≥3 lines” reads files directly, no subprocess. Use it where content shape matters.

Worked example: ox session start CLI Outline row

Walking the second Examples row of the consolidated Outline end-to-end. Picked over the slash-command row because the CLI path needs the most new wiring — if it lands, the slash row trivially follows (it's tui/claude-code/prompt with the slash text and existing TUI capture).

Gherkin (target)

  Scenario Outline: Marcus records a session started via <mechanism>
    Given Claude has been primed in Marcus's repository
    When Marcus starts session recording via <mechanism>
    And he asks Claude about widget pricing                      ## canned, nonce-seeded prompt
    And he stops the session recording
    Then the session should be committed to the repository's ledger with a summary and transcript
    And the session transcript should mention the widget pricing question

    Examples:
      | mechanism                       |
      | /ox-session-start slash command |
      | ox session start CLI            |

Step-by-step verb plan for the “CLI” Examples row

What each Then reads (concretely)

# session-be-committed-to-ledger, operation 1
ox session list --json
# expected JSON shape (per ox cmd/ox/session_list.go):
# {
#   "ledger_available": true,
#   "sessions": [
#     { "session_id": "<RECORDING_SID>", "uploaded": true, "title": "...", ... }
#   ]
# }
# Assertion: find a session row whose session_id matches $RECORDING_SID
# AND whose `uploaded` field is true. If `ledger_available` is false,
# surface that explicitly — it almost always means the ox daemon
# isn't running, which is a real BDD precondition gap not a product bug.

# session-be-committed-to-ledger, operation 2
stat ~/.cache/sageox/context/sessions/<RECORDING_SID>/raw.jsonl
stat ~/.cache/sageox/context/sessions/<RECORDING_SID>/summary.md
# both must exist and be non-empty.

# session-transcript-contains
grep -c "<WIDGET_NONCE>" ~/.cache/sageox/context/sessions/<RECORDING_SID>/raw.jsonl
# expected: >= 1.

What's NOT in this row's verification chain: the team-sessions-page and repo-detail-page Then assertions. Those go on a follow-up PR (see Phasing). The smallest-first PR proves the start→interact→stop→committed loop end-to-end without bringing in the web driver.

Dependencies on other plans (#26 Outline substitution, #27 multi-persona)

Resource considerations (LLM token cost)

The session-lifecycle journey unavoidably touches a real Claude Code TUI — that's the whole point. The dimensions of cost:

Per-scenario cost estimate: ~5-10k tokens of Sonnet, <$0.05 at current pricing. Two scenarios (slash + CLI mechanisms) = ~$0.10 per BDD run. Acceptable; comparable to the existing agent-priming scenario which is already in CI.

Should we mock the LLM? No. The whole journey is “real session got recorded & landed”; replacing Claude with a stub would gut the integration value. The cost is the price of admission for this cluster. If cost balloons later, the mitigation is to run the cluster nightly rather than per-PR, not to mock the model.

L1 verification: our existing TUI verbs already pay this cost in agent-priming's validated scenario. We're piggybacking on a budget the team has already accepted.

Phasing & smallest-first PR

PR 1 — ledger-FS verification proves the loop smallest first

Goal: one CLI-mechanism scenario, validated, end-to-end, with FS+CLI verifications only. No web. No Outline. No multi-persona.

Feature: AI Coworker Session Recording

  Rule: A recorded session is committed to the repository's ledger
    Scenario: Marcus records a session via the CLI and it lands in the ledger
      Given Claude has been primed in Marcus's repository
      When Marcus starts session recording via the ox CLI
      And he asks Claude a question seeded with a unique token
      And he stops the session recording via the ox CLI
      Then the session should be committed to the ledger with a summary and transcript
      And the transcript should contain the unique token

Ships in this PR:

• New BAs: start-session-recording (variant cli), stop-session-recording (variant cli), ask-claude-canned-question
• New verifications: session-be-committed-to-ledger, session-transcript-contains
• New driver verbs: cli/ox/session/{start,stop,list}, fs/ledger/{stat-session,grep-transcript}
• Audit + (if needed) wire the ox-daemon-start step into the Given chain
• No @pending tag — ships validated, per the tagging convention

That's 2 verifications + 5 driver verbs + 2 BAs in one PR. About 1-1.5 days of work including the daemon-state audit. Reuses 100% of the existing TUI driver.

PR 2 — slash-command mechanism row

Adds the /ox-session-start + /ox-session-stop path. Adds nothing new at the driver level — the slash command is just tui/claude-code/prompt with the slash text. Adds a second scenario (or, if #26 Outline substitution lands first, collapses both into one Outline). Wires the two BAs' slash variants alongside the cli variants that already exist.

PR 3 — team-page & repo-detail web verifications

Depends on #27 multi-persona (Marcus records; Tina views). Adds web/sessions/{list,repo-detail} drivers + matching verifications. Extends the Outline's Then clauses to include the page assertions.

PR 4 — the four kept-separate scenarios

One at a time, each in its own PR:

1. Multi-repo sessions list (depends on PR 3 + the recording-journey cluster's repo-connection verbs).
2. Interrupted-session daemon recovery (failure-recovery property; needs a verb to forcibly kill the active recording process and a verification that polls for eventual cleanup).
3. Public-view toggle on the sessions page (visibility test; reuse the existing public/private team plumbing the team-management cluster establishes).
4. Session artifacts reflect interaction content (sharpens the vague Then in today's pending scenario; mostly an FS-grep verification, low risk).

Critical-path: PR 1 unblocks the cluster's tag flip on the primary outcome scenario. PR 2 is one-day follow-up. PR 3 waits on #27. PR 4 fans out independently.

What this is NOT

• Not new TUI driver work. Three robust verbs ship today; they're reused as-is. The deferral framing in the walks plan was wrong; correcting it is half the value of this plan.
• Not a refactor of agent-priming.feature. That feature stays exactly as it is — the session-lifecycle cluster composes on top of the primed-Claude precondition that priming already establishes.
• Not multi-agent or multi-model. Only Claude Code is in scope. Other agent adapters (Codex, Aider, Amp, opencode, droid, pi) exist in the ox CLI but aren't part of this cluster.
• Not testing summary quality. We assert the summary exists and is non-empty; content correctness of Anthropic-generated summaries is a model-eval problem, not a BDD problem.
• Not testing ledger sync to remote. The push-to-remote path (ledger daemon → GitLab) is the ox CLI's problem and has its own integration tests upstream. BDD verifies up to the local ledger checkout, which is the surface the user sees on the team sessions page.
• Not testing ox session view --html rendering. That's a separate ox feature with its own unit tests.
• Not authoring new walks. Walk 07 (the original session-recording walk) was deferred as a walk-level artifact. We're going straight to BDD without re-creating a walk.