feat(session): amicode_session tool — spawn sessions as background tabs

[aarontrowbridge]

Closes #639

What

A session can now spawn new sessions that surface as background tabs beside the parent — fan-out for parallel work, fork-mode for branching a thread mid-conversation.

Piece	What it does
amicode_session tool	Creates 1–4 child sessions via the engine-provided PluginInput.client (first server-mutating tool in the pack), posts the prompt immediately (explicit model bypasses draft-readiness retries), stamps metadata {spawned_by, spawned_depth}. mode: "fork" seeds from this session's history via the native fork endpoint + metadata PATCH.
Spawn policy (session_spawn.ts)	Pure + unit-tested: count cap 4/call, soft depth cap 2 overridable with force, model precedence (arg > parent's model > server default), hey-api unwrap, honest summaries.
Session route effect	Watches the server session store for spawned_by == this route's session; opens each child as a background tab (tabs.addSessionTab — never navigates, no focus steal); idempotent via opened-set. Selection logic in session/spawn-tabs.ts (bun tests).
Manifest	Per-file hashes updated for the modified session.tsx + the two new overlay files — drift gate green locally.

Design decisions (from #639 discussion)

• Auto-open, background — addSessionTab never navigates; spawning cannot steal focus.
• Start immediately — promptAsync with explicit model; children churn from birth (cost noted in the tool description).
• Soft depth cap — default 2, force: true overrules; depth is derived from the session's OWN stamp, not the caller's claim, so the cap is enforced by construction.
• Honest fallback — if no pane shows the parent, the child still spawns and is discoverable in the session list; the fork-mode metadata PATCH is tolerated to fail (child runs, just won't auto-open).

Test evidence

• test/session_spawn.test.ts — 20 tests, green.
• spawn-tabs.test.ts — 8 tests, green (bun).
• tsc --noEmit clean; agents_md + amicode_tools suites green.
• Full extension suite: the 7 failures are pre-existing on current main (environmental: vendored binary absent, pin fixtures, staged bins, pasqal venv) — verified by re-running the same files on a clean tree; this branch adds zero new failures.
• drift_gate.mjs: PASS (556 files) — including the Complete the .18 pin: re-extract the app-bundle overlay + re-record the service-contract fixtures (unblocks #622 and main) #636-re-extracted state this branch rebased onto.
• Overlay app typecheck is not a CI lane (composition proof remains the pre-cutover gate); session.tsx passes esbuild parse + review, consistent with current overlay-PR practice.

Sequencing note

Rebased onto the post-#636 main — the app-bundle-gate red that #639 was originally sequenced behind is resolved on this base.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}