instar 1.3.244 → 1.3.246

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T16:26:00.075Z",
-  "instarVersion": "1.3.244",
+  "generatedAt": "2026-06-04T18:56:49.668Z",
+  "instarVersion": "1.3.246",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-preflight": {
@@ -1010,7 +1010,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-ci-failures": {
@@ -1018,7 +1018,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-profile-node": {
@@ -1026,7 +1026,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {
@@ -1506,7 +1506,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "d01eb671ddb9e21b1aeef11fb0b79a63db7a088baf94352fce58a3f0a7c4fd60",
+      "contentHash": "4d50cc3ebd4b430069d5957fbed44bdadd487c17386b680f0cafe66a33c381e2",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.3.245.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the in-session server lifecycle guard so it only blocks the current
+session's own managing server. Restarting a sibling agent server by target
+directory or agent name is now allowed from inside a session.
+
+Self-targeted server lifecycle commands are still blocked, and the error now
+points operators to the supervisor path for bouncing that agent safely.
+
+The CLI import shape remains compatible with the version-detection regression
+test, and the exported guard is documented so docs coverage stays above the core
+floor.
+
+## What to Tell Your User
+
+- **Sibling agent restarts**: "I can now bounce another agent's server during
+  mentoring or fleet maintenance without being blocked by my own session guard.
+  My own managing server is still protected, so the active conversation is not
+  stranded by accident."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Restart a sibling agent server from inside a session | Use the existing server lifecycle command with a sibling target |
+| Safer self-server failure message | Automatic when an agent targets its own managing server |
+
+## Evidence
+
+Reproduced the failing shape in a unit boundary test: a session with current
+project Codey and target Gemini now returns allow, while current project Codey
+targeting Codey still returns reject. The same targeted suite also verifies that
+a symlink pointing back to Codey is rejected after realpath normalization. The
+targeted server command test file passes with all ten tests green.

package/upgrades/1.3.246.md

@@ -0,0 +1,97 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Phase 2 of the Threadline agent-to-agent (A2A) continuity work: **warm sessions**.
+
+The turn-based fix (#746) made a peer's spaced follow-up *resume* the same
+conversation via `claude --resume`. But rapid-fire bursts (several messages in
+seconds) still cold-spawned, because each A2A reply ran as a throwaway `-p`
+session that answered once and exited — there was nothing alive to hand the next
+message to — and a fresh thread could even hit the 30s per-peer spawn cooldown.
+
+This change keeps the reply session **alive between messages** for a warm-enabled
+peer and **injects** follow-ups into it:
+
+- The first message from a verified, non-topic-bound peer spawns a **persistent
+  interactive** reply session (not a throwaway `-p`), carrying the full grounded
+  prompt as its first turn, and registers it in a new `WarmSessionPool` keyed by
+  threadId (caps: globalCap 3, perPeerCap 1, ttlMs 600000, trustFloor `verified`).
+- The next message on that thread is **injected** into the same live session — no
+  cold-spawn, no cooldown — and refreshes its TTL.
+- A periodic reap tick evicts on TTL/pressure; on eviction the **next message
+  falls back losslessly to the proven `--resume` path (#746)** — nothing is lost.
+
+Three correctness/security fixes ride along, each independently load-bearing:
+
+- **`claude.exe` allowlist fix** — live macOS Claude panes report
+  `pane_current_command = claude.exe`, which the inject allowlist
+  (`ALLOWED_INJECTION_PROCESSES`) did not contain, so A2A live-inject was
+  **dead-on-arrival on macOS**. Added `claude.exe`.
+- **Grounding-on-inject** — injected follow-ups are now wrapped in the same
+  untrusted-data grounding preamble used on spawn/resume (they previously injected
+  the raw envelope body).
+- **Per-thread isolation + peer-conflict guard** — each thread gets its own
+  private session (no shared listener, nothing to leak across peers), and
+  `WarmSessionPool.admit` throws `WarmSessionPeerConflictError` rather than letting
+  a different peer hijack an existing thread's warm session; a pre-spawn `peek`
+  check makes the conflict path fall back to a normal cold-spawn.
+
+Dark-shipped behind `threadline.warmSessionA2A.enabled`, resolved via the
+`developmentAgent` dev-gate (`enabled ?? !!config.developmentAgent`): **live on the
+development agent, dark on the fleet**. With the flag absent and `developmentAgent`
+false, behavior is byte-for-byte the current cold-spawn path.
+
+**Framework-general (not Claude-specific).** The warm worker runs in the LOCAL
+agent's framework (claude-code / codex-cli / gemini-cli / future), not hardcoded
+Claude: the inject allowlist is now DERIVED from a per-framework process-name
+registry (`Record<IntelligenceFramework, …>`), and the warm spawn passes the local
+framework so the right CLI + resume mechanism applies. Enforced by compiler
+exhaustiveness + `tests/unit/framework-agnosticism.test.ts` + a new `/instar-dev`
+precommit gate that requires any launch/inject-abstraction change to state its
+framework generality (standard: **Framework-Agnostic — and Framework-Optimizing**).
+
+## What to Tell Your User
+
+When another agent and I go back and forth quickly, I now keep the same live
+conversation open and type each new message into it — instead of starting a fresh,
+memoryless reply every time. So a rapid exchange holds its thread end-to-end, not
+just the slower turn-by-turn case. It's an internal robustness improvement that
+ships active only on the development agent (dark on everyone else) and falls back
+to the already-shipped resume path if a warm session is ever retired. Nothing to
+turn on.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Warm A2A sessions (keep-alive + inject) | Automatic for verified, non-topic-bound Threadline peers when `threadline.warmSessionA2A.enabled` is on (defaults to the `developmentAgent` flag). Rapid follow-ups inject into the live session instead of cold-spawning. |
+| Tunable warm-session pool | `.instar/config.json` → `threadline.warmSessionA2A`: `globalCap` (3), `perPeerCap` (1), `ttlMs` (600000), `trustFloor` (`verified`). |
+| Lossless eviction fallback | On TTL/pressure eviction, the next message resumes via the `--resume` path (#746) — no continuity lost. |
+
+## Evidence
+
+**The `claude.exe` bug (reproduced in dev):** `ALLOWED_INJECTION_PROCESSES`
+(`src/messaging/types.ts`) listed `claude` but not `claude.exe`. On macOS a live
+Claude pane reports `pane_current_command = claude.exe`, so the inject guard
+`isInjectableProcess()` returned **false for every live A2A reply session** —
+agent-to-agent live-inject was dead-on-arrival on macOS.
+
+- *Before:* the prior live Echo↔Dawn round-trip recorded `2× Spawned, 0× Resumed,
+  1× spawn-denied (cooldown)` on a fresh thread — every follow-up cold-started; the
+  inject path was never reachable because the allowlist check rejected `claude.exe`.
+- *After:* unit test asserts `claude.exe ∈ ALLOWED_INJECTION_PROCESSES`; the
+  integration test "2nd message on a thread with a live warm session → inject (no
+  2nd spawn, no cooldown)" passes — the inject path is now reachable and exercised.
+
+**Test evidence (re-run on top of current main, v1.3.243):** tsc `--noEmit` clean;
+warm-session unit (105) + integration (5: incl. flag-on inject, flag-off
+byte-identical cold-spawn, peer-conflict → cold fallback) + e2e (1: continuity then
+evict → resume via #746) all green; esm / no-empty-catch / no-direct-destructive /
+no-silent-fallbacks gates green (warm fail-opens annotated `@silent-fallback-ok`,
+net silent-fallback count unchanged). The live Echo↔Dawn production round-trip
+("Resumed not Spawned" + rapid inject with no cooldown) is the post-deploy
+standards-met gate, run by the orchestrator after merge.

package/upgrades/side-effects/server-restart-sibling-target.md

@@ -0,0 +1,96 @@
+# Side-effects review — session-safe sibling server restarts
+
+**Scope**: `instar server start|stop|restart` now checks whether the requested
+server target is the current session's own project before blocking lifecycle
+commands from inside a session. Sibling targets are allowed. Self-targets remain
+blocked and now print an actionable supervisor command.
+
+Framework-ledger ref: `57ecfb92`.
+
+## Decision audit
+
+**Candidate A: keep the blanket block and only improve the error.**
+
+This would have preserved the original safety invariant, but it would not remove
+the operational friction that caused this task. A mentoring agent still could
+not bounce a sibling agent's server from the correct workflow.
+
+**Candidate B: make the guard target-aware and keep a supervisor hint for
+self-targets.**
+
+Chosen. It preserves the invariant that a session cannot restart its own
+managing server, while allowing maintenance of sibling agents. The supervisor
+hint covers the remaining blocked case with an explicit human/operator path.
+
+## Over-block risk
+
+Low. The guard normalizes the current project and target project through
+`realpath` when possible. Sibling directories compare different and are allowed.
+The only expected block is the current managing server, including symlink aliases
+that point back to it.
+
+One residual over-block case remains intentional: if no target is provided from
+inside a session, the command targets the current project and is blocked.
+
+## Under-block risk
+
+Low. A symlink to the current project is rejected after realpath normalization.
+If a target path does not exist yet, normalization falls back to `path.resolve`;
+that could only affect non-existing paths before the server command validates
+them. Existing self-targets are protected.
+
+## Level-of-abstraction fit
+
+The comparison lives in a pure core helper. The CLI resolves the optional agent
+name before asking the helper for a decision, then formats any rejection for the
+terminal. This keeps policy separate from command output and makes the behavior
+directly unit-testable.
+
+## Signal vs authority
+
+The helper is authority for this CLI guard only. It does not change supervisor,
+launchd, systemd, or server internals. The server lifecycle implementation still
+owns the actual start/stop/restart mechanics.
+
+## Interactions
+
+- `server start [name]`, `server stop [name]`, and `server restart [name]` now
+  resolve the agent name before applying the guard.
+- `--dir` targets are compared directly.
+- `status [name]` is unchanged except that `resolveAgentDir` is now statically
+  imported by the CLI.
+- Supervisor-managed restarts remain the documented path for the current agent.
+
+## External surfaces
+
+User-facing behavior changes only for CLI output and command allowance:
+
+- Sibling server lifecycle commands from inside a session can proceed.
+- Self server lifecycle commands still fail, with a clearer message and
+  `launchctl kickstart -k gui/$UID/ai.instar.<name>` hint.
+
+No API keys, credentials, network calls, or config migrations are involved.
+
+## Rollback cost
+
+Small. Reverting the helper, CLI call-site changes, tests, and upgrade artifacts
+restores the prior blanket in-session block.
+
+## Tests
+
+Narrow regression coverage checks:
+
+- no session id allows lifecycle commands;
+- current managing server rejects;
+- sibling target allows;
+- symlink target resolving to the current managing server rejects.
+- docs coverage documents `SessionServerGuard` in two indexed docs so the core
+  category stays at its configured floor.
+
+Local verification intentionally uses targeted tests and static gates under the
+current host load; CI remains the full matrix authority.
+
+## Conclusion
+
+This change removes the Gemini-onboarding friction without weakening the
+conversation-safety invariant that motivated the guard in the first place.