Skip to content
sdlc

T-AD81-sdlc-p2-session-launch

State: closed/done · Impact: high · Complexity: medium

Goal

Section titled “Goal”

pr review is currently the only place that knows how to pick a host (orca/terminal/cmux) and start an interactive session. Phase 2’s loops need to launch sessions for many purposes (implement, define, pr-review, pr-respond), including headless (claude -p / codex exec) dispatch that writes an auditable session record. Extracting this into sdlc session launch makes pr review one consumer among several instead of the only implementation.

Today

Section titled “Today”
LocationRole today
solutions/ontological/lib/services/pr/ops/review.tstoday’s only session launcher: picks a host, starts an interactive review session
solutions/ontological/lib/services/host/HostParts contract, pickHost, engines.ts
solutions/ontological/lib/services/host/hosts/terminal.tsterminal host implementation
solutions/ontological/lib/services/host/hosts/orca.tsorca host implementation
solutions/ontological/lib/services/host/hosts/cmux.tscmux host implementation
packages/ts/agent-callheadless engines (claude, codex, gemini, opencode)
solutions/ontological/lib/util/command.tscommand seam: spawnRunnerAsync for long-lived/detached processes

Proposed

Section titled “Proposed”
  • A new op, sdlc session launch, taking --workflow <name> | --skill <name> | --prompt <text> (mutually exclusive), --engine, --host, --cwd, and --headless.
  • Interactive mode: resolves the host via the existing pickHost/HostParts machinery (orca, terminal, cmux — no new hosts in this phase) and starts the session there, same mechanics pr review uses today.
  • Headless mode: runs claude -p or codex exec detached via spawnRunnerAsync (in-code note: long-lived/detached process, per the command seam’s documented exception), and writes a session record — id, engine, host, cwd, workflow/skill/prompt, start/end timestamps, exit code, log path — to .sdlc/sessions/<id>/.
  • A per-engine mapping turns a resolved skill: workflow step into that engine’s first message (Claude: /sdlc:<skill> <args>; leave a documented seam for codex/cursor mappings Phase 6 adds hosts for, but only implement the Claude mapping now since Codex/Cursor as hosts don’t exist until Phase 6 — headless Codex dispatch via agent-call needs only a first-message string, not a host).
  • pr review is refactored to a thin consumer: it resolves its own workflow/skill and cwd, then calls session launch instead of duplicating host-pick + start logic.

Approach

Section titled “Approach”
  1. Read lib/services/pr/ops/review.ts in full to inventory exactly what it does today (host pick, session start, any pre/post steps specific to review) so nothing pr-review-specific leaks into the generic op.
  2. Add lib/services/session/ops/launch.ts (new session service) implementing the interactive path first, reusing pickHost/HostParts/engines.ts unchanged.
  3. Add the headless path: detached spawn via spawnRunnerAsync with the in-code command-seam-exception note, session record write/read helpers under lib/services/session/ (e.g. record.ts), landing files at .sdlc/sessions/<id>/.
  4. Add the skill→first-message mapping (Claude only) as a small pure function, documented as the seam Phase 6 extends per-engine.
  5. Refactor pr review (lib/services/pr/ops/review.ts) to call session launch for the actual session start, deleting the logic it duplicated.
  6. Register session launch in lib/registry.ts, wire the CLI command, write unit tests (fake engine binary for the headless path, per T-REME).

Areas

Section titled “Areas”
AreaNote
solutions/ontological/lib/services/session/ops/launch.tssession launch op, interactive + headless
solutions/ontological/lib/services/session/record.tssession record read/write under .sdlc/sessions/<id>/
solutions/ontological/lib/services/session/engine-message.tsskill/workflow-step → engine first-message mapping (Claude)
solutions/ontological/lib/services/pr/ops/review.tsconsume session launch instead of duplicating host/session logic
solutions/ontological/lib/registry.tsregister session launch
solutions/ontological/lib/services/session/launch.test.tsheadless-mode test against a fake engine binary

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: sdlc session launch --skill pr-review --host terminal --cwd <dir> starts an interactive terminal session the same way pr review does today (manually verified: pr review’s own tests still pass post-refactor).
  • AC-2: sdlc session launch --prompt "..." --engine claude --headless --cwd <dir> runs detached, exits, and leaves a session record at .sdlc/sessions/<id>/ with id, engine, host, cwd, start/end, exit code and log path all populated.
  • AC-3: a fake-engine-binary test proves the headless record’s exit field matches the fake binary’s real exit code (0 and nonzero cases).
  • AC-4: pr review’s existing tests pass unmodified in assertions (only wiring changes) after the refactor — no behavior regression.
  • AC-5: passing two of --workflow/--skill/--prompt together is a validation error.

Out of scope

Section titled “Out of scope”
  • The claude/codex/cursor hosts (interactive sessions in those apps) — Phase 6.
  • session list / session attach — Phase 6.
  • The sessions: config section — Phase 6.

Dependencies

Section titled “Dependencies”
  • [T-A7PL-sdlc-p2-workflows](/planning/tasks/sdlc-p2-workflows/) — --workflow resolution feeds a step list; session launch needs resolveWorkflow to turn a workflow name into the skill/prompt it launches.

Discovery context

Section titled “Discovery context”

Phase 2 of docs/planning/notes/N-S4AJ-sdlc-0-8-plan.md (“sdlc session launch”).

Depends on

Section titled “Depends on”

T-A7PL-sdlc-p2-workflows

← Back to Tasks