@team-agent/installer 0.3.14 → 0.3.15

package/crates/team-agent/src/messaging/tests/runtime.rs

@@ -1898,26 +1898,26 @@ fn r8_attach_requeue_exhausted_to_notify_failed_golden_attach_event() {
     );
 }
 
-// E15 (F4.4 双投修)·源码守卫:report_result 的 direct inject 必须被 `if !outcome.ok` 守为
+// E15/E23 双投守卫:report_result 的 pane fallback 必须被 `if !outcome.ok` 守为
 // deliver 失败时的真兜底,绝不在 deliver 成功后无条件再投一次(=用户看到两条同内容回复)。
 #[test]
 fn e15_direct_inject_is_gated_by_deliver_failure_not_unconditional() {
     let src = include_str!("../results.rs");
-    // 锁:inject_leader_notification_direct 调用点之前必须有 `if !outcome.ok` 门。
+    // E23:旧 private direct inject 已合并到 shared deliver_to_leader_fallback_pane primitive。
     let gate = "if !outcome.ok {";
-    let inject_call = "match inject_leader_notification_direct(";
+    let fallback_call = "deliver_to_leader_fallback_pane(";
     let gate_pos = src.find(gate);
-    let inject_pos = src.find(inject_call);
     assert!(
         gate_pos.is_some(),
-        "E15: direct inject must be gated by `if !outcome.ok` (deliver-fail fallback)"
+        "E15/E23: pane fallback must be gated by `if !outcome.ok` (deliver-fail fallback)"
     );
+    let fallback_after_gate = src[gate_pos.unwrap()..].find(fallback_call);
     assert!(
-        inject_pos.is_some(),
-        "inject_leader_notification_direct call site must exist (do NOT delete it; #230 fallback)"
+        fallback_after_gate.is_some(),
+        "E15/E23: report_result fallback must call the shared fallback pane primitive after the failure gate"
     );
     assert!(
-        gate_pos.unwrap() < inject_pos.unwrap(),
-        "E15: the `if !outcome.ok` gate must precede the direct-inject call (deliver-success must skip inject → leader gets exactly one copy)"
+        !src.contains("inject_leader_notification_direct"),
+        "E23: private direct inject must stay deleted; all callers use deliver_to_leader_fallback_pane"
     );
 }

package/crates/team-agent/src/os_probe.rs

@@ -35,6 +35,17 @@ pub(crate) fn probe_timeout() -> Option<ProbeTimeout> {
     PROBE_TIMEOUT.with(|timeout| timeout.borrow().clone())
 }
 
+#[cfg(test)]
+pub(crate) fn set_probe_timeout_for_test(probe: &'static str, pid: Option<u32>, timeout_ms: u64) {
+    PROBE_TIMEOUT.with(|current| {
+        *current.borrow_mut() = Some(ProbeTimeout {
+            probe,
+            pid,
+            timeout_ms,
+        });
+    });
+}
+
 pub(crate) fn bounded_command_output_with_probe(
     command: &mut Command,
     probe: &'static str,

package/crates/team-agent/src/state/persist.rs

@@ -419,7 +419,13 @@ fn backfill_capture_fields(incoming_agent: &mut Value, latest_agent: &Value) {
     let Some(incoming_row) = incoming_agent.as_object_mut() else {
         return;
     };
+    let incoming_session = incoming_row.get("session_id").and_then(Value::as_str);
+    let latest_session = latest_agent.get("session_id").and_then(Value::as_str);
+    let session_changed = incoming_session.is_some() && incoming_session != latest_session;
     for field in CAPTURE_FIELDS {
+        if session_changed && field != "session_id" {
+            continue;
+        }
         if incoming_row.get(field).is_none_or(Value::is_null) {
             if let Some(value) = latest_agent.get(field).filter(|value| !value.is_null()) {
                 incoming_row.insert(field.to_string(), value.clone());

package/crates/team-agent/src/tmux_backend.rs

@@ -180,6 +180,14 @@ enum TmuxSocketEndpoint {
     Path(String),
 }
 
+impl TmuxSocketEndpoint {
+    fn as_endpoint(&self) -> &str {
+        match self {
+            TmuxSocketEndpoint::Name(socket) | TmuxSocketEndpoint::Path(socket) => socket,
+        }
+    }
+}
+
 impl TmuxBackend {
     /// Backend bound to the real `tmux` subprocess on the SHARED default socket (no `-L`).
     /// Non-team callers + existing argv/unit tests stay unaffected.
@@ -514,6 +522,55 @@ impl TmuxBackend {
         })
     }
 
+    fn spawn_split(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        argv: &[String],
+        cwd: &Path,
+        env: &BTreeMap<String, String>,
+        env_unset: &[String],
+    ) -> Result<SpawnResult, TransportError> {
+        let command = shell_command(argv, cwd, env, env_unset);
+        let target = format!("{}:{}", session.as_str(), window.as_str());
+        let split_argv = vec![
+            "tmux".to_string(),
+            "split-window".to_string(),
+            "-t".to_string(),
+            target.clone(),
+            "-h".to_string(),
+            "-P".to_string(),
+            "-F".to_string(),
+            "#{pane_id}".to_string(),
+            "sh".to_string(),
+            "-lc".to_string(),
+            command,
+        ];
+        let output = self.run_spawn(&split_argv)?;
+        let pane = output.stdout.trim();
+        if pane.is_empty() {
+            return Err(TransportError::Subprocess {
+                argv: split_argv,
+                code: output.code,
+                stderr: format!("tmux split-window returned no pane id for {target}"),
+            });
+        }
+        let layout_argv = vec![
+            "tmux".to_string(),
+            "select-layout".to_string(),
+            "-t".to_string(),
+            target,
+            "tiled".to_string(),
+        ];
+        self.run_ok(&layout_argv)?;
+        Ok(SpawnResult {
+            pane_id: PaneId::new(pane),
+            session: session.clone(),
+            window: window.clone(),
+            child_pid: None,
+        })
+    }
+
     fn run_ok(&self, argv: &[String]) -> Result<(), TransportError> {
         let argv = self.tmux_argv(argv);
         let output = self.runner.run(&argv)?;
@@ -722,6 +779,12 @@ impl Transport for TmuxBackend {
         true
     }
 
+    fn tmux_endpoint(&self) -> Option<String> {
+        self.socket
+            .as_ref()
+            .map(|endpoint| endpoint.as_endpoint().to_string())
+    }
+
     fn spawn_first(
         &self,
         session: &SessionName,
@@ -768,6 +831,18 @@ impl Transport for TmuxBackend {
         self.spawn(session, window, argv, cwd, env, &[], false)
     }
 
+    fn spawn_split_with_env_unset(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        argv: &[String],
+        cwd: &Path,
+        env: &BTreeMap<String, String>,
+        env_unset: &[String],
+    ) -> Result<SpawnResult, TransportError> {
+        self.spawn_split(session, window, argv, cwd, env, env_unset)
+    }
+
     fn inject(
         &self,
         target: &Target,
@@ -1066,6 +1141,16 @@ impl Transport for TmuxBackend {
         self.run_ok(&argv)
     }
 
+    fn kill_pane(&self, pane: &PaneId) -> Result<(), TransportError> {
+        let argv = self.tmux_argv(&[
+            "tmux".to_string(),
+            "kill-pane".to_string(),
+            "-t".to_string(),
+            pane.as_str().to_string(),
+        ]);
+        self.run_ok(&argv)
+    }
+
     fn attach_session(&self, session: &SessionName) -> Result<AttachOutcome, TransportError> {
         let argv = [
             "tmux".to_string(),

package/crates/team-agent/src/transport/test_support.rs

@@ -15,6 +15,8 @@ use super::{
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SpawnRecord {
     pub kind: String,
+    pub session: SessionName,
+    pub window: WindowName,
     pub argv: Vec<String>,
 }
 
@@ -33,6 +35,7 @@ struct OfflineState {
     spawns: Vec<SpawnRecord>,
     inject_targets: Vec<Target>,
     inject_payloads: Vec<String>,
+    tmux_endpoint: Option<String>,
 }
 
 impl Default for OfflineState {
@@ -51,6 +54,7 @@ impl Default for OfflineState {
             spawns: Vec::new(),
             inject_targets: Vec::new(),
             inject_payloads: Vec::new(),
+            tmux_endpoint: None,
         }
     }
 }
@@ -116,6 +120,11 @@ impl OfflineTransport {
         self
     }
 
+    pub fn with_tmux_endpoint(self, endpoint: impl Into<String>) -> Self {
+        self.with_state(|state| state.tmux_endpoint = Some(endpoint.into()));
+        self
+    }
+
     pub fn calls(&self) -> Vec<&'static str> {
         self.with_state(|state| state.calls.clone())
     }
@@ -130,6 +139,16 @@ impl OfflineTransport {
         })
     }
 
+    pub fn spawn_window_records(&self) -> Vec<(String, String)> {
+        self.with_state(|state| {
+            state
+                .spawns
+                .iter()
+                .map(|record| (record.kind.clone(), record.window.as_str().to_string()))
+                .collect()
+        })
+    }
+
     pub fn inject_targets(&self) -> Vec<Target> {
         self.with_state(|state| state.inject_targets.clone())
     }
@@ -161,7 +180,12 @@ impl OfflineTransport {
     ) -> Result<SpawnResult, TransportError> {
         let pane_index = self.with_state(|state| {
             state.calls.push(kind);
-            state.spawns.push(SpawnRecord { kind: kind.to_string(), argv: argv.to_vec() });
+            state.spawns.push(SpawnRecord {
+                kind: kind.to_string(),
+                session: session.clone(),
+                window: window.clone(),
+                argv: argv.to_vec(),
+            });
             if let Some(error) = state.spawn_failures.get(window.as_str()) {
                 return Err(TransportError::Spawn {
                     backend: BackendKind::Tmux,
@@ -201,6 +225,10 @@ impl Transport for OfflineTransport {
         BackendKind::Tmux
     }
 
+    fn tmux_endpoint(&self) -> Option<String> {
+        self.with_state(|state| state.tmux_endpoint.clone())
+    }
+
     fn spawn_first(
         &self,
         session: &SessionName,
@@ -223,6 +251,18 @@ impl Transport for OfflineTransport {
         self.spawn_result("spawn_into", session, window, argv)
     }
 
+    fn spawn_split_with_env_unset(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        argv: &[String],
+        _cwd: &Path,
+        _env: &BTreeMap<String, String>,
+        _env_unset: &[String],
+    ) -> Result<SpawnResult, TransportError> {
+        self.spawn_result("spawn_split", session, window, argv)
+    }
+
     fn inject(
         &self,
         target: &Target,
@@ -330,6 +370,11 @@ impl Transport for OfflineTransport {
         Ok(())
     }
 
+    fn kill_pane(&self, _pane: &PaneId) -> Result<(), TransportError> {
+        self.record("kill_pane");
+        Ok(())
+    }
+
     fn attach_session(
         &self,
         _session: &SessionName,

package/crates/team-agent/src/transport.rs

@@ -405,6 +405,13 @@ pub trait Transport: Send + Sync {
         false
     }
 
+    /// Physical tmux endpoint used by this transport when known. For tmux this is
+    /// either a full `-S` socket path or a `-L` socket name; non-tmux/test
+    /// transports can leave it unknown.
+    fn tmux_endpoint(&self) -> Option<String> {
+        None
+    }
+
     // —— SPAWN(ST):所有后端天然满足;cwd/env 是 spawn 参数,无独立动词(§gap-setenv)——
 
     /// tmux=`new-session -d` / wezterm=`spawn --new-window` / conpty=`openpty`+spawn。
@@ -459,6 +466,22 @@ pub trait Transport: Send + Sync {
         self.spawn_into(session, window, argv, cwd, env)
     }
 
+    /// Spawn a worker as an additional pane in an existing session/window.
+    /// Backends without a split-pane primitive may conservatively fall back to
+    /// `spawn_into`; tmux overrides this with `split-window`.
+    fn spawn_split_with_env_unset(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        argv: &[String],
+        cwd: &Path,
+        env: &BTreeMap<String, String>,
+        env_unset: &[String],
+    ) -> Result<SpawnResult, TransportError> {
+        let _ = env_unset;
+        self.spawn_into(session, window, argv, cwd, env)
+    }
+
     // —— INJECT / CAPTURE / QUERY(RIE):按稳定 Target 寻址 ——
 
     /// 归并 set/load-buffer + paste-buffer + send submit;空文本走纯 send-keys
@@ -527,6 +550,10 @@ pub trait Transport: Send + Sync {
 
     fn kill_window(&self, target: &Target) -> Result<(), TransportError>;
 
+    fn kill_pane(&self, pane: &PaneId) -> Result<(), TransportError> {
+        self.kill_window(&Target::Pane(pane.clone()))
+    }
+
     /// 交互前台 attach(leader 用)。tmux=`attach-session`;wezterm=GUI 即 attach
     /// (`GuiAttachIsImplicit`);conpty=typed 不支持(`Unsupported`)。
     fn attach_session(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.3.14",
-    "@team-agent/cli-darwin-x64": "0.3.14",
-    "@team-agent/cli-linux-x64": "0.3.14"
+    "@team-agent/cli-darwin-arm64": "0.3.15",
+    "@team-agent/cli-darwin-x64": "0.3.15",
+    "@team-agent/cli-linux-x64": "0.3.15"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/references/recovery-runbook.md

@@ -0,0 +1,277 @@
+# Team Agent Recovery Reference
+
+This reference is for the Rust Team Agent runtime. This reference is a live document.
+
+When a Team Agent framework problem appears, check this reference first. After the problem is resolved, update this reference before closing the work, whether or not the final fix used an existing entry here. New recovery advice may be added only after RS validation on a real Team Agent environment; unverified Python-only procedures stay out of this external reference.
+
+## Validation Gate
+
+Every prescription below must carry an RS verification record. A command copied from Python 0.2.11 or from an incident note is not valid until it has been verified against the RS runtime. If RS behavior differs, document the RS behavior, not the Python behavior.
+
+Use placeholders only:
+
+- `$WORKSPACE` for the team workspace
+- `$TEAM` for the active team key when a command needs one
+- `$AGENT_ID` for a worker id
+- `$TASK_ID` for a task id
+
+Do not write recipes that depend on a user's private absolute paths, private specification fields, or unverified local state.
+
+## Recovery Levels
+
+| Level | Who may run it | Scope | Misuse consequence |
+| --- | --- | --- | --- |
+| L1 | Any agent, including a worker | Read-only diagnosis, file report handoff, status/log/result inspection, current-payload E23 fallback only | Low risk, but must not mutate bindings or lifecycle state |
+| L2 | Leader only | Resume-oriented lifecycle repair such as restart of an existing team or worker | A worker running L2 must be treated as `worker.privilege_escalation_attempt` |
+| L3 | User/operator only | Claiming/taking over leader ownership, state surgery, coordinator respawn, fresh/reset | E19/#232 class risk: wrong workspace or pane can steal ownership or destroy context |
+
+Spine for every incident:
+
+1. Diagnose with L1 read-only commands.
+2. Prefer resume or repair that preserves context.
+3. Use L3 surgery only when the user/operator explicitly approves and the coordinator/write owner is controlled.
+4. Use fresh/reset only as the last resort.
+
+Fresh/reset red line:
+
+> WARNING: context will be lost. Run this only after diagnostics, resume, and repair have all failed and the user has explicitly typed approval. Do not make it the default. Each use must emit `recovery.context_reset` with source and approval timestamp.
+
+## Symptom Index
+
+| Symptom | Root cause family | Prescription |
+| --- | --- | --- |
+| Status is confusing, messages/results may be pending, or a worker says it cannot report | Need a safe read-only picture first | §1 L1 Read-Only Triage |
+| Leader pane exists but messages say `leader_not_attached`, `rebind_required`, `team_owner_mismatch`, or leader 被抢 | Leader ownership or receiver binding drift | §2 L3 Claim Or Rebind Leader |
+| A live team must be recovered without losing worker context | Resume/restart path needed | §3 L2 Restart With Resume First |
+| Shutdown/restart cleanup status is ambiguous | Need residue-based truth, not a single `ok` field | §4 L1/L2 Cleanup Verification |
+| MCP tool call fails with `Transport closed` while the worker still has the payload | Provider-owned MCP stdio child died | §5 Superseded/Pending E23 Fallback Boundary |
+
+## 1. L1 Read-Only Triage
+
+[contextual: preserved] [level: L1] Any agent may run this. It reads state only and does not mutate the team.
+
+Diagnosis:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+team-agent collect --workspace "$WORKSPACE" --json
+```
+
+What to look for:
+
+- `leader_receiver.status`
+- `coordinator.status`
+- agent `status`
+- uncollected results
+- messages stuck in `accepted`, `failed`, or `rebind_required`
+
+Resume/repair:
+
+- If the answer identifies an L2/L3 condition, do not run the elevated command from a worker pane. Send the evidence to the leader/user.
+- If MCP reporting is broken, write a handoff artifact under the team's artifacts directory and tell the leader the relative path.
+
+Last resort:
+
+- None. This entry is read-only. Do not turn triage into fresh/reset.
+
+RS verification record:
+
+- `#249 Python 0.2.11 -> Rust 0.3.2 upgrade compatibility`: Rust `status`, `collect`, and `read` succeeded against an upgraded live team; restart resumed and post-restart MCP delivery worked. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `#249`.
+- Mac mini LOOP/G1-G4 evidence also captured status and command outputs after restart/shutdown flows; see `g1g4-macmini-confirm-report.md`.
+
+Python 0.2.11 compatibility note:
+
+- Python teams used equivalent `status`/`collect` verbs. Python-specific wrapper paths are deprecated and are intentionally not listed here.
+
+## 2. L3 Claim Or Rebind Leader
+
+[contextual: preserved] [level: L3] User/operator only. A worker must not run this. Misuse can steal the leader binding or recreate E19/#232 style ownership damage.
+
+Use this when L1 triage shows the leader pane is live but leader-bound delivery is blocked by ownership or receiver drift.
+
+Diagnosis:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+```
+
+Confirm:
+
+- The current pane is the intended leader/operator pane.
+- The workspace is the intended team workspace.
+- The target team is the intended `$TEAM` when multiple teams share a workspace.
+
+Resume/repair:
+
+```bash
+team-agent claim-leader --workspace "$WORKSPACE" --team "$TEAM" --json
+```
+
+If the previous owner is live and the user explicitly approves stealing ownership, add the product's confirmation flag:
+
+```bash
+team-agent claim-leader --workspace "$WORKSPACE" --team "$TEAM" --confirm --json
+```
+
+Validate:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+```
+
+The receiver should be attached and new leader-bound delivery should no longer report `leader_not_attached`.
+
+Extreme surgery:
+
+- Do not edit binding fields by hand unless a user/operator has approved the exact state repair and the coordinator/write owner is stopped or otherwise controlled.
+
+Last resort:
+
+- Fresh/reset is not a leader claim repair. Do not use it here.
+
+RS verification record:
+
+- Dogfood T2 R2: old live team restart/claim/takeover passed from the persistent leader pane. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `R2`.
+- RS #235 bug3 Mac mini run: `claim-leader` and `takeover` claimed live panes and persisted `leader_receiver.status="attached"` with `claimed_via="claim-leader"`. Evidence root id: `7b146ce-bug3-20260606T023011Z`.
+- G1-G4 report: help path for `claim-leader` exited 0 and did not trigger action validation. Evidence: `g1g4-macmini-confirm-report.md`, CR-063.
+
+Python 0.2.11 compatibility note:
+
+- Python had analogous claim/takeover verbs. Use RS commands above for RS teams.
+
+## 3. L2 Restart With Resume First
+
+[contextual: partial] [level: L2] Leader only. A worker must not run this. The goal is to preserve session context; resume is always before fresh.
+
+Use this when L1 triage shows a team or worker needs lifecycle repair but the state still carries enough runtime/session context to resume.
+
+Diagnosis:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+```
+
+Resume/repair:
+
+```bash
+team-agent restart "$WORKSPACE" --team "$TEAM" --json
+```
+
+For a single worker where the leader has explicitly selected that worker:
+
+```bash
+team-agent restart-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --json
+```
+
+Validate:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+team-agent collect --workspace "$WORKSPACE" --json
+```
+
+The expected result is `status="restarted"` or an equivalent running projection without duplicate-session errors. Do not treat a partial failure on one worker as permission to reset the whole team.
+
+Extreme surgery:
+
+- If restart reports a resume-integrity refusal, stop and escalate. Do not silently rerun with fresh flags.
+
+Last resort:
+
+```bash
+# Last resort only; see red line at top of this reference.
+team-agent restart "$WORKSPACE" --team "$TEAM" --allow-fresh --json
+```
+
+WARNING: context will be lost. Run this only after diagnostics, resume, and repair have all failed and the user has explicitly typed approval. Do not make it the default. Each use must emit `recovery.context_reset` with source and approval timestamp.
+
+RS verification record:
+
+- Dogfood T2 R2: restart returned restarted and status after restart showed a running team. Evidence ledger: `dogfood-execution-ledger-T2.md`.
+- Dogfood #249: Rust restart resumed session `019e9ffd-c99c-7b60-bff3-9612ab35bcf5`, post-restart MCP delivery worked, and cleanup residue was 0. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `#249`.
+- G1-G4 Mac mini reconfirmation: restart recovered the same fake team in CR-007, after acknowledge-idle context in CR-021, and in coordinator recovery context in CR-052. Evidence: `g1g4-macmini-confirm-report.md`.
+
+Python 0.2.11 compatibility note:
+
+- Python restart procedures are deprecated compatibility background only. For RS teams, use the RS commands above.
+
+## 4. L1/L2 Cleanup Verification
+
+[contextual: partial] [level: L1 for verification, L2 for shutdown command] A worker may inspect cleanup evidence. Only the leader should run lifecycle cleanup.
+
+Diagnosis:
+
+```bash
+team-agent status --workspace "$WORKSPACE" --json --detail
+```
+
+Resume/repair:
+
+- If a leader intentionally stops or shuts down a test team, verify by residue, not by a single top-level `ok` field.
+- For cleanup verification, inspect whether the team session is gone and whether residual process/session lists are empty in the command output or status evidence.
+
+Leader command:
+
+```bash
+team-agent shutdown --workspace "$WORKSPACE" --keep-logs --json
+```
+
+Validate:
+
+- `session_killed=true` is decisive for a session that was expected to be killed.
+- `residuals.sessions=[]` and `residuals.processes=[]` are decisive for cleanup.
+- A missing coordinator after a successful cleanup can be expected; do not classify it alone as a product failure.
+
+Extreme surgery:
+
+- Do not manually kill shared tmux servers from a worker pane.
+
+Last resort:
+
+- None. Cleanup verification is not a context reset path.
+
+RS verification record:
+
+- Dogfood T2 R3: quick-start with true Codex worker, MCP server live, shutdown returned `ok=true`, `session_killed=true`, endpoint `has-session` rc=1, and post MCP/node/codex/process residue lines were all 0. Evidence ledger: `dogfood-execution-ledger-T2.md`.
+- G1-G4 CR-005: stop returned `ok=true`, `status="stopped"`, `session_killed=true`; following shutdown reported missing without treating that alone as failure. Evidence: `g1g4-macmini-confirm-report.md`.
+
+Python 0.2.11 compatibility note:
+
+- Python cleanup notes may mention direct tmux commands. They are not listed here as RS recovery prescriptions.
+
+## 5. Superseded/Pending E23 Fallback Boundary
+
+[contextual: preserved] [level: L1] E23 fallback is the only narrow worker-scope exception to the normal tool boundary. It is for a current payload already in hand after a leader-bound MCP delivery failure.
+
+Current status:
+
+- Product implementation exists in the E23 branch for `fallback-send-leader` and `fallback-report-result`.
+- Local RS verification has covered CLI help and focused E23 tests.
+- This reference does not yet promote the fallback CLI to a general external prescription because the new documentation gate requires current-release RS validation in the Mac mini environment.
+
+Until that validation is added:
+
+- Workers should write a file handoff artifact for the current payload and ask for leader/user recovery.
+- Leaders should prefer restart/resume of the affected worker after the current payload is preserved.
+
+Do not use E23 fallback as a general message path. It does not permit arbitrary worker execution of L2/L3 recovery operations.
+
+RS verification record:
+
+- Local only at the time of this reference update: E23 focused tests and CLI help on the merged E23 documentation branch. Mac mini current-release validation is still required before adding exact fallback commands here.
+
+Python 0.2.11 compatibility note:
+
+- Python MCP stdio EOF had no durable reconnect. File handoff was the practical fallback. RS E23 adds product support, but this entry remains gated until real-machine validation is complete.
+
+## Held Out Of This Reference
+
+[contextual: unknown] Python-only procedures from older incident notes are intentionally not included as external RS prescriptions:
+
+- legacy roster block cloning
+- direct live runtime-state injection
+- raw coordinator respawn commands
+- direct tmux-server surgery
+- hard-coded runtime paths
+
+These may be useful forensic background for maintainers, but each must pass the RS validation gate before becoming a user-facing recipe.