@team-agent/installer 0.3.39 → 0.4.0

package/crates/team-agent/src/provider/command.rs

@@ -0,0 +1,71 @@
+//! unit-7 (Stage 3) — provider command-assembly boundary.
+//!
+//! The provider/adapter.rs monolith mixes three concerns:
+//!   1. The `ProviderAdapter` TRAIT and facade dispatch (the public API).
+//!   2. Per-provider COMMAND ASSEMBLY (argv plan, base/resume flags,
+//!      --session-id injection — adapter.rs:409-508 region).
+//!   3. SESSION SCANNING (capture polling + transcript scanning —
+//!      adapter.rs:511-546, 969-1078).
+//!
+//! This module CREATES the dedicated home for #2 so future work can
+//! migrate command-assembly fns here in small, behavior-neutral commits.
+//! Today it only carries the documented intent and a small typed helper —
+//! the bulk of the assembly fns are still in adapter.rs and reachable
+//! through the existing pub(crate) surface.
+//!
+//! Why incremental: every command-assembly fn touches multiple internal
+//! constants (`--session-id`, `--resume`, MCP-config-path conventions) and
+//! per-provider quirks. Moving them blindly is high-risk. The boundary
+//! exists so the next commit (or any contributor) has a documented target
+//! for relocations.
+
+use crate::provider::Provider;
+
+/// Lightweight tag for command-plan branches in the existing adapter
+/// (`Base` vs `Resume`). Distinct type so command-assembly code reads
+/// clearly even when it lives next to adapter dispatch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CommandPlanKind {
+    /// Initial spawn — `--session-id <uuid>` predetermined.
+    Base,
+    /// Resume an existing session — `--resume <sid>`, no fresh
+    /// `--session-id` injected.
+    Resume,
+}
+
+/// Returns true when the provider's command plan honors `--session-id`
+/// for fresh spawns. Mirrors the existing adapter logic but lives next to
+/// where future command-assembly fns will land.
+pub fn honors_session_id_for_base_spawn(provider: Provider) -> bool {
+    matches!(
+        provider,
+        Provider::Codex
+            | Provider::Claude
+            | Provider::ClaudeCode
+            | Provider::Copilot
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fake_provider_does_not_honor_session_id() {
+        assert!(!honors_session_id_for_base_spawn(Provider::Fake));
+    }
+
+    #[test]
+    fn real_providers_honor_session_id() {
+        for p in [Provider::Codex, Provider::Claude, Provider::Copilot] {
+            assert!(honors_session_id_for_base_spawn(p));
+        }
+    }
+
+    #[test]
+    fn command_plan_kind_is_copy() {
+        let a = CommandPlanKind::Base;
+        let b = a;
+        assert_eq!(a, b);
+    }
+}

package/crates/team-agent/src/provider/mod.rs

@@ -34,7 +34,10 @@ pub use crate::model::enums::{AuthMode, Provider};
 pub mod adapter;
 pub mod approvals;
 pub mod classify;
+pub mod command;
 pub mod faults;
+pub mod session;
+pub mod session_scan;
 pub mod startup_prompt;
 pub mod types;
 // helpers 全部原为模块私有(JSONL 解析 / 正则编译),非根可见 → 私有 mod,不参与 re-export。

package/crates/team-agent/src/{session_capture.rs → provider/session/capture.rs}

@@ -409,14 +409,87 @@ where
 }
 
 fn agent_session_complete(agent: &Value) -> bool {
-    agent
+    // RM-039-SESS-001 step 1 (architect verdict 2026-06-22): historically
+    // this returned true the moment `rollout_path` was non-empty — even when
+    // the file no longer existed on disk. That created a "stale-positive"
+    // capture tuple: the worker had a session_id + a stored rollout_path,
+    // but the provider had rotated/garbage-collected the actual transcript
+    // file. `pending_session_capture` skipped agents whose
+    // `agent_session_complete()` was true, so the runtime never recaptured
+    // the now-broken backing, and downstream consumers saw the stale tuple
+    // as authoritative.
+    //
+    // Fix: a non-empty `rollout_path` only counts as complete when the path
+    // actually exists. session_id remains a required non-empty check
+    // (architect directive: "Keep session_id non-empty as required; do not
+    // infer context from event log alone unless the referenced transcript
+    // path exists.").
+    //
+    // Blocker-2 Layer-1 (prerelease 0.4.0, architect bugs-prerelease-blockers.md §139):
+    // existence alone is not enough — a small Claude session-metadata JSON
+    // (~/.claude/sessions/<pid>.json, ~300-400 bytes, sessionId only, no
+    // assistant/user records) used to satisfy this and prevent recapture of
+    // the real .claude/projects/<cwd>/<sid>.jsonl transcript. For
+    // Claude/ClaudeCode rollout paths, additionally require a recognizable
+    // transcript lifecycle record (an assistant or user record). Other
+    // providers keep existence-only semantics (codex 不可改项).
+    let session_id_ok = agent
         .get("session_id")
         .and_then(Value::as_str)
-        .is_some_and(|session| !session.is_empty())
-        && agent
-            .get("rollout_path")
-            .and_then(Value::as_str)
-            .is_some_and(|path| !path.is_empty())
+        .is_some_and(|session| !session.is_empty());
+    if !session_id_ok {
+        return false;
+    }
+    let rollout_path = match agent
+        .get("rollout_path")
+        .and_then(Value::as_str)
+        .filter(|path| !path.is_empty())
+    {
+        Some(path) => path,
+        None => return false,
+    };
+    let path = std::path::Path::new(rollout_path);
+    if !path.exists() {
+        return false;
+    }
+    let provider_wire = agent.get("provider").and_then(Value::as_str).unwrap_or("");
+    if matches!(provider_wire, "claude" | "claude-code" | "claude_code") {
+        return claude_rollout_has_lifecycle_records(path);
+    }
+    true
+}
+
+/// Blocker-2 Layer-1 (prerelease 0.4.0): a Claude rollout file qualifies as
+/// activity backing only when it contains at least one recognizable transcript
+/// lifecycle record (top-level `type:"assistant"` or `type:"user"`). The
+/// ~/.claude/sessions/<pid>.json metadata file has neither, so this returns
+/// false for it and the runtime recaptures via the .claude/projects/<cwd>/
+/// scan in adapter.rs. Bounded read so a large transcript is not slurped.
+fn claude_rollout_has_lifecycle_records(path: &std::path::Path) -> bool {
+    use std::io::Read;
+    const MAX_BYTES: u64 = 65_536;
+    let Ok(file) = std::fs::File::open(path) else {
+        return false;
+    };
+    let mut bytes = Vec::new();
+    if file.take(MAX_BYTES).read_to_end(&mut bytes).is_err() {
+        return false;
+    }
+    let text = String::from_utf8_lossy(&bytes);
+    for line in text.lines() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        let Ok(value) = serde_json::from_str::<serde_json::Value>(trimmed) else {
+            continue;
+        };
+        let kind = value.get("type").and_then(Value::as_str).unwrap_or("");
+        if matches!(kind, "assistant" | "user") {
+            return true;
+        }
+    }
+    false
 }
 
 fn allocate_session_candidates(
@@ -874,4 +947,64 @@ mod u1_tests {
             }]
         );
     }
+
+    /// RM-039-SESS-001 step 1 (architect verdict 2026-06-22): the
+    /// `agent_session_complete` predicate must NOT treat a non-empty
+    /// `rollout_path` as complete when the file does not exist. The
+    /// historical bug was that a stale-positive capture tuple
+    /// (`session_id` + `rollout_path` both present, but the path had
+    /// been rotated away by the provider) was reported as complete and
+    /// blocked `pending_session_capture` from recapturing. Now the
+    /// predicate returns false if the path does not exist, so the
+    /// session is re-evaluated on the next convergence tick.
+    #[test]
+    fn rm039_sess001_agent_session_complete_requires_existing_rollout_path() {
+        // Case 1: session_id + rollout_path both non-empty, path absent.
+        let missing = "/tmp/ta-rm039-sess001-nonexistent-rollout.jsonl";
+        // Guard against a previous test run leaving the file behind.
+        let _ = std::fs::remove_file(missing);
+        let agent_stale = serde_json::json!({
+            "session_id": "sess-stale-positive",
+            "rollout_path": missing,
+        });
+        assert!(
+            !agent_session_complete(&agent_stale),
+            "RM-039-SESS-001: stale-positive tuple (session_id + missing rollout_path) \
+             must NOT be reported complete"
+        );
+
+        // Case 2: session_id + rollout_path both non-empty, path exists.
+        use std::sync::atomic::{AtomicU64, Ordering};
+        static N: AtomicU64 = AtomicU64::new(0);
+        let n = N.fetch_add(1, Ordering::Relaxed);
+        let existing = std::env::temp_dir().join(format!(
+            "ta-rm039-sess001-existing-{}-{}.jsonl",
+            std::process::id(),
+            n
+        ));
+        std::fs::write(&existing, b"{}\n").expect("write fixture rollout file");
+        let agent_complete = serde_json::json!({
+            "session_id": "sess-real",
+            "rollout_path": existing.to_string_lossy(),
+        });
+        assert!(
+            agent_session_complete(&agent_complete),
+            "an agent with session_id + an existing rollout file remains complete"
+        );
+        let _ = std::fs::remove_file(&existing);
+
+        // Case 3: empty session_id must still fail completeness regardless.
+        let agent_no_session = serde_json::json!({
+            "session_id": "",
+            "rollout_path": "/tmp/whatever",
+        });
+        assert!(!agent_session_complete(&agent_no_session));
+
+        // Case 4: empty rollout_path remains incomplete (legacy contract).
+        let agent_no_path = serde_json::json!({
+            "session_id": "sess-x",
+            "rollout_path": "",
+        });
+        assert!(!agent_session_complete(&agent_no_path));
+    }
 }

package/crates/team-agent/src/provider/session/mod.rs

@@ -0,0 +1,13 @@
+//! unit-6 (Stage 2) — provider session namespace.
+//!
+//! Houses session-specific provider concerns: resume preflight,
+//! session capture (moved from `crate::session_capture` in unit-6),
+//! session backing checks, etc.
+
+pub mod capture;
+pub mod resume;
+
+pub use resume::{
+    ProviderBackingCheck, RecoveryHint, ResumeDecisionDetail, ResumePreflight,
+    ResumePreflightOutcome, ResumeRefusalReason,
+};

package/crates/team-agent/src/provider/session/resume.rs

@@ -0,0 +1,417 @@
+//! unit-5 (Stage 2) — resume preflight + closed `ResumeRefusalReason` enum.
+//!
+//! Today the restart resume gate flattens every refusal into one of two
+//! opaque strings:
+//!
+//!   * `"no_persisted_session_id"` — no `session_id` in state
+//!   * `"session_unresumable"`     — `session_id` set but backing missing
+//!                                   OR provider can't resume OR session
+//!                                   ambiguous (all collapsed to one string)
+//!
+//! That string is the user-facing diagnostic, so debugging "why did restart
+//! refuse?" requires reading source. This unit replaces the catch-all
+//! `session_unresumable` with a closed enum carrying the structured
+//! distinction.
+//!
+//! Migration strategy: ADDITIVE. `UnresumableWorker.reason: String` stays
+//! (every CLI/JSON caller already reads it). A new optional
+//! `refusal_reason: Option<ResumeRefusalReason>` carries the structured
+//! value alongside. Callers that need actionable diagnostics flip to the
+//! enum; legacy callers see the same string they always saw.
+
+use std::path::PathBuf;
+
+/// Layer 2 self-healing hint (architect probe 2026-06-22, §Recommended
+/// design): operator-facing diagnostic that names the agent / cwd /
+/// provider for a missing-backing refusal so the operator can manually
+/// find / repair the dropped session. Carried alongside the refusal —
+/// NEVER consumed for automatic resume. Auto-recovery requires multi-key
+/// filtering + backing revalidation (Layer 3 follow-up, see
+/// `session.recovery.candidate_promoted` event design).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RecoveryHint {
+    /// Agent role label that was passed at launch as `--name` / `-n`
+    /// (Claude / Copilot). Codex has no launch-time name flag, so this
+    /// is `None` for Codex workers (probe verdict 2026-06-22).
+    pub provider_session_name_hint: Option<String>,
+    /// Spawn cwd recorded for the worker — the second key in the
+    /// "provider+cwd+name+updated_at" filter Layer 3 will require.
+    pub spawn_cwd: Option<PathBuf>,
+    /// Wire provider name (`codex` / `claude` / `claude_code` /
+    /// `copilot`). Used for picker hint string only.
+    pub provider: String,
+}
+
+impl RecoveryHint {
+    /// Build a human-readable picker hint (one line). Layer 2 surfaces
+    /// this in the CLI refusal message and in the
+    /// `session.recovery.candidate_hint` event payload.
+    pub fn picker_hint(&self) -> String {
+        match (&self.provider_session_name_hint, &self.spawn_cwd) {
+            (Some(name), Some(cwd)) => format!(
+                "{} session named '{}' under cwd {}",
+                self.provider,
+                name,
+                cwd.display()
+            ),
+            (Some(name), None) => {
+                format!("{} session named '{}'", self.provider, name)
+            }
+            (None, Some(cwd)) => format!("{} session under cwd {}", self.provider, cwd.display()),
+            (None, None) => format!("{} session", self.provider),
+        }
+    }
+}
+
+/// Structured reason a worker is unresumable. Closed enum — future
+/// reasons require a code change, which is the point.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResumeRefusalReason {
+    /// State has no `session_id` for this worker. Fresh start would be
+    /// safe iff `--allow-fresh` is set.
+    NoSessionId,
+    /// State has `session_id` but the provider backing file (Codex rollout
+    /// JSONL / Claude transcript) is missing on disk. Distinct from
+    /// "no session" because it implies provider lost the backing.
+    SessionBackingStoreMissing {
+        /// Paths the runtime probed for the backing file.
+        checked_paths: Vec<PathBuf>,
+        /// Layer 2 self-healing diagnostic (architect probe 2026-06-22):
+        /// agent / cwd / provider hint the operator can use to find or
+        /// repair the dropped session via the provider's own picker
+        /// (`claude --resume <name>`, `copilot --resume=<name>`).
+        /// **Never auto-consumed for resume** — auto-recovery requires
+        /// the Layer 3 multi-key filter + backing revalidation contract.
+        recovery_hint: Option<RecoveryHint>,
+    },
+    /// Provider does not support resume at the protocol level (e.g.
+    /// some auth modes).
+    ProviderResumeUnsupported {
+        /// Provider name (`codex` / `claude` / `copilot` / `fake`).
+        provider: String,
+    },
+    /// Session capture polling did not converge before the deadline
+    /// (the existing `RefusedResumeNotReady` shape).
+    SessionCaptureIncomplete,
+    /// State session_id differs from the provider's observed session
+    /// (T6 L5.5 drift). Caller should reconcile before resuming.
+    SessionDrift {
+        expected: String,
+        actual: String,
+    },
+    /// Catch-all for refusals the structured shape hasn't taxonomized
+    /// yet. Carries the legacy free-form string. This variant exists so
+    /// the enum is BACKWARD-COMPATIBLE with the historical
+    /// `session_unresumable` string — every value the old code emitted
+    /// can be lifted into the enum without losing fidelity.
+    Other { legacy_reason: String },
+}
+
+impl ResumeRefusalReason {
+    /// Stable wire string mirroring the historical
+    /// `UnresumableWorker.reason` values. Use this when emitting JSON or
+    /// log fields so downstream consumers see the same strings they
+    /// always have.
+    pub fn wire(&self) -> &'static str {
+        match self {
+            ResumeRefusalReason::NoSessionId => "no_persisted_session_id",
+            ResumeRefusalReason::SessionBackingStoreMissing { .. } => {
+                "session_backing_store_missing"
+            }
+            ResumeRefusalReason::ProviderResumeUnsupported { .. } => {
+                "provider_resume_unsupported"
+            }
+            ResumeRefusalReason::SessionCaptureIncomplete => "session_capture_incomplete",
+            ResumeRefusalReason::SessionDrift { .. } => "session_drift",
+            // For Other we still report the legacy wire so the existing
+            // `session_unresumable` JSON shape is preserved end-to-end.
+            ResumeRefusalReason::Other { .. } => "session_unresumable",
+        }
+    }
+
+    /// Lift a legacy free-form `reason` string into the structured enum.
+    /// Round-trip-safe with `wire()` for the canonical names.
+    pub fn from_legacy(reason: &str) -> Self {
+        match reason {
+            "no_persisted_session_id" => ResumeRefusalReason::NoSessionId,
+            "session_backing_store_missing" => {
+                ResumeRefusalReason::SessionBackingStoreMissing {
+                    checked_paths: Vec::new(),
+                    recovery_hint: None,
+                }
+            }
+            "provider_resume_unsupported" => ResumeRefusalReason::ProviderResumeUnsupported {
+                provider: String::new(),
+            },
+            "session_capture_incomplete" => ResumeRefusalReason::SessionCaptureIncomplete,
+            other => ResumeRefusalReason::Other {
+                legacy_reason: other.to_string(),
+            },
+        }
+    }
+}
+
+/// Outcome of `ResumePreflight::check`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResumePreflightOutcome {
+    /// Worker can resume from the named session.
+    Resume {
+        session_id: String,
+    },
+    /// `--allow-fresh` was set; worker will start fresh.
+    FreshStart,
+    /// Resume refused. Caller MUST NOT proceed with teardown/spawn.
+    Refuse {
+        reason: ResumeRefusalReason,
+    },
+}
+
+/// Information about whether a provider backing file is present on disk.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderBackingCheck {
+    pub paths: Vec<PathBuf>,
+    pub exists: bool,
+}
+
+/// Per-decision detail emitted to events / JSON.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResumeDecisionDetail {
+    pub agent_id: String,
+    pub session_id: Option<String>,
+    pub provider: String,
+    pub backing: Option<ProviderBackingCheck>,
+    pub outcome: ResumePreflightOutcome,
+}
+
+/// Pure resume preflight evaluator. No I/O — callers pass facts in.
+pub struct ResumePreflight;
+
+impl ResumePreflight {
+    /// Decide a single worker's resume outcome from the facts the
+    /// restart code already collected. Mirrors the existing
+    /// `classify_restart_plan_with_resume_validation` decision tree:
+    ///
+    ///   * session_id present + provider can resume + backing exists -> Resume
+    ///   * session_id present + (no resume OR no backing) + allow_fresh -> FreshStart
+    ///   * session_id present + (no resume OR no backing) + !allow_fresh -> Refuse
+    ///   * session_id absent + allow_fresh -> FreshStart
+    ///   * session_id absent + !allow_fresh -> Refuse(NoSessionId)
+    pub fn check(
+        session_id: Option<&str>,
+        provider_can_resume: bool,
+        backing: Option<&ProviderBackingCheck>,
+        provider_name: &str,
+        allow_fresh: bool,
+    ) -> ResumePreflightOutcome {
+        Self::check_with_hint(
+            session_id,
+            provider_can_resume,
+            backing,
+            provider_name,
+            allow_fresh,
+            None,
+        )
+    }
+
+    /// Layer 2 self-healing variant: same decision tree as
+    /// [`Self::check`], but propagates an optional `RecoveryHint` into
+    /// the `SessionBackingStoreMissing` refusal so the CLI / event log
+    /// can surface a "look for session named X under cwd Y" pointer to
+    /// the operator. The hint is for HUMAN consumption only — no
+    /// auto-resume happens off it (Layer 3 follow-up).
+    pub fn check_with_hint(
+        session_id: Option<&str>,
+        provider_can_resume: bool,
+        backing: Option<&ProviderBackingCheck>,
+        provider_name: &str,
+        allow_fresh: bool,
+        recovery_hint: Option<RecoveryHint>,
+    ) -> ResumePreflightOutcome {
+        match session_id {
+            Some(sid) if provider_can_resume => {
+                let backing_present = backing.map(|b| b.exists).unwrap_or(true);
+                if backing_present {
+                    ResumePreflightOutcome::Resume {
+                        session_id: sid.to_string(),
+                    }
+                } else if allow_fresh {
+                    ResumePreflightOutcome::FreshStart
+                } else {
+                    ResumePreflightOutcome::Refuse {
+                        reason: ResumeRefusalReason::SessionBackingStoreMissing {
+                            checked_paths: backing
+                                .map(|b| b.paths.clone())
+                                .unwrap_or_default(),
+                            recovery_hint,
+                        },
+                    }
+                }
+            }
+            Some(_) if allow_fresh => ResumePreflightOutcome::FreshStart,
+            Some(_) => ResumePreflightOutcome::Refuse {
+                reason: ResumeRefusalReason::ProviderResumeUnsupported {
+                    provider: provider_name.to_string(),
+                },
+            },
+            None if allow_fresh => ResumePreflightOutcome::FreshStart,
+            None => ResumePreflightOutcome::Refuse {
+                reason: ResumeRefusalReason::NoSessionId,
+            },
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn wire_round_trip_canonical_strings() {
+        for wire in [
+            "no_persisted_session_id",
+            "session_backing_store_missing",
+            "provider_resume_unsupported",
+            "session_capture_incomplete",
+        ] {
+            assert_eq!(ResumeRefusalReason::from_legacy(wire).wire(), wire);
+        }
+    }
+
+    #[test]
+    fn other_preserves_legacy_session_unresumable_wire() {
+        let r = ResumeRefusalReason::from_legacy("session_unresumable");
+        assert_eq!(r.wire(), "session_unresumable");
+        assert!(matches!(r, ResumeRefusalReason::Other { .. }));
+    }
+
+    #[test]
+    fn preflight_resume_when_session_and_backing_present() {
+        let backing = ProviderBackingCheck {
+            paths: vec![PathBuf::from("/tmp/x.jsonl")],
+            exists: true,
+        };
+        let out = ResumePreflight::check(Some("sess-1"), true, Some(&backing), "codex", false);
+        assert!(matches!(out, ResumePreflightOutcome::Resume { .. }));
+    }
+
+    #[test]
+    fn preflight_refuses_when_session_id_missing_without_allow_fresh() {
+        let out = ResumePreflight::check(None, true, None, "codex", false);
+        assert_eq!(
+            out,
+            ResumePreflightOutcome::Refuse {
+                reason: ResumeRefusalReason::NoSessionId
+            }
+        );
+    }
+
+    #[test]
+    fn preflight_distinguishes_backing_missing_from_no_session_id() {
+        let backing = ProviderBackingCheck {
+            paths: vec![PathBuf::from("/missing.jsonl")],
+            exists: false,
+        };
+        let out = ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", false);
+        match out {
+            ResumePreflightOutcome::Refuse { reason } => {
+                assert_eq!(reason.wire(), "session_backing_store_missing");
+            }
+            other => panic!("expected backing-missing refusal; got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn preflight_allow_fresh_converts_refusals_to_fresh() {
+        let backing = ProviderBackingCheck {
+            paths: vec![PathBuf::from("/missing.jsonl")],
+            exists: false,
+        };
+        assert_eq!(
+            ResumePreflight::check(None, true, None, "codex", true),
+            ResumePreflightOutcome::FreshStart
+        );
+        assert_eq!(
+            ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", true),
+            ResumePreflightOutcome::FreshStart
+        );
+    }
+
+    // Layer 2 self-healing tests ────────────────────────────────────────────
+
+    #[test]
+    fn recovery_hint_picker_string_with_all_fields() {
+        let hint = RecoveryHint {
+            provider_session_name_hint: Some("coder".to_string()),
+            spawn_cwd: Some(PathBuf::from("/repo/team-a")),
+            provider: "claude".to_string(),
+        };
+        assert_eq!(
+            hint.picker_hint(),
+            "claude session named 'coder' under cwd /repo/team-a"
+        );
+    }
+
+    #[test]
+    fn recovery_hint_picker_string_no_name_no_cwd() {
+        // Codex worker — no launch-time name, spawn_cwd missing.
+        let hint = RecoveryHint {
+            provider_session_name_hint: None,
+            spawn_cwd: None,
+            provider: "codex".to_string(),
+        };
+        assert_eq!(hint.picker_hint(), "codex session");
+    }
+
+    #[test]
+    fn preflight_with_hint_attaches_to_backing_missing_refusal() {
+        let backing = ProviderBackingCheck {
+            paths: vec![PathBuf::from("/missing.jsonl")],
+            exists: false,
+        };
+        let hint = RecoveryHint {
+            provider_session_name_hint: Some("coder".to_string()),
+            spawn_cwd: Some(PathBuf::from("/repo")),
+            provider: "claude".to_string(),
+        };
+        let out = ResumePreflight::check_with_hint(
+            Some("sess-1"),
+            true,
+            Some(&backing),
+            "claude",
+            false,
+            Some(hint.clone()),
+        );
+        match out {
+            ResumePreflightOutcome::Refuse {
+                reason: ResumeRefusalReason::SessionBackingStoreMissing {
+                    recovery_hint: Some(h),
+                    ..
+                },
+            } => {
+                assert_eq!(h, hint);
+            }
+            other => panic!("expected SessionBackingStoreMissing with hint; got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn preflight_no_hint_legacy_behavior_unchanged() {
+        // Default check() (no hint) still produces None recovery_hint —
+        // wire-string-compatible with pre-Layer-2 callers.
+        let backing = ProviderBackingCheck {
+            paths: vec![PathBuf::from("/missing.jsonl")],
+            exists: false,
+        };
+        let out = ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", false);
+        match out {
+            ResumePreflightOutcome::Refuse {
+                reason: ResumeRefusalReason::SessionBackingStoreMissing {
+                    recovery_hint, ..
+                },
+            } => {
+                assert!(recovery_hint.is_none());
+            }
+            other => panic!("expected backing-missing refusal; got {other:?}"),
+        }
+    }
+}