fix(codex): sidecar lifecycle — persistent tracking, reattach on restore, conservative reaping (kata ynfn, da92)

crates/freshell-codex/Cargo.toml

@@ -34,6 +34,10 @@ default = []
 real-transport = ["dep:tokio-tungstenite", "dep:futures-util", "dep:libc", "tokio/net", "tokio/io-util", "tokio/process"]
 
 [dependencies]
+# Derive for the durable sidecar record rows (`sidecar_store`) — the versioned
+# camelCase JSON schema a restarted server reads back (BindingRow precedent,
+# pane_ledger.rs:93-130).
+serde = { workspace = true }
 # Dynamic JSON parsing that mirrors the TS `Record<string, unknown>` params/result model
 # (JSON.parse parity, corruption-tolerant). preserve_order matches the wire object model.
 serde_json = { workspace = true }
@@ -57,3 +61,8 @@ futures-util = { version = "0.3", default-features = false, features = ["sink",
 # FRESHELL_CODEX_SIDECAR_ID tag (runtime.ts:494) so no orphan survives (the oracle
 # `ownership.cleanup` invariant). Only needed by the real transport.
 libc = { version = "0.2", optional = true }
+
+[dev-dependencies]
+# Tempdirs for the sidecar-store unit tests — no global state, nothing outside
+# each test's own temp dir (never `~/.freshell/`).
+tempfile = "3"

crates/freshell-codex/src/app_server.rs

@@ -413,6 +413,31 @@ impl CodexAppServerClient {
         .await
     }
 
+    /// `thread/loaded/list` — the ids of threads this app-server currently
+    /// has loaded in memory (result shape `{ data: string[], nextCursor? }`,
+    /// contract-foundation plan §thread/loaded/list; the committed fixture
+    /// returns `{ data: behavior.loadedThreadIds }`). NOTE: `loaded` alone
+    /// does NOT mean mid-turn — idle threads stay loaded forever
+    /// (reports/V1.md); pair with [`Self::read_thread`]'s status. Added for
+    /// Task 9's sweep probe.
+    pub async fn list_loaded_threads(&self) -> Result<Vec<String>, CodexAppServerError> {
+        let result = self.request("thread/loaded/list", json!({})).await?;
+        // Absent/non-array `data` is NOT an empty list: the sweep probe reads
+        // Ok(vec![]) as proof of "reachable, no loaded threads" and may REAP
+        // on it — a malformed payload must fail loudly instead, sending the
+        // caller down the conservative writer-evidence path (final review F2).
+        let Some(ids) = result.get("data").and_then(Value::as_array) else {
+            return Err(CodexAppServerError::InvalidResponse {
+                method: "thread/loaded/list".to_string(),
+                detail: format!("expected result.data to be an array, got: {result}"),
+            });
+        };
+        Ok(ids
+            .iter()
+            .filter_map(|id| id.as_str().map(str::to_string))
+            .collect())
+    }
+
     /// Send a notification frame (no response awaited) — `notify`, `client.ts:805-808`.
     pub async fn notify(
         &self,

crates/freshell-codex/src/lib.rs

@@ -52,6 +52,18 @@ pub mod launch_lifecycle;
 #[cfg(feature = "real-transport")]
 pub mod remote_proxy;
 #[cfg(feature = "real-transport")]
+pub mod runtime_select;
+#[cfg(feature = "real-transport")]
+pub mod sidecar_reconcile;
+#[cfg(feature = "real-transport")]
+pub mod sidecar_store;
+#[cfg(feature = "real-transport")]
+pub mod sidecar_sweep;
+// Shared helpers for the sidecar lifecycle test suites (never shipped;
+// Linux-only like the suites themselves — they read `/proc` evidence).
+#[cfg(all(test, target_os = "linux", feature = "real-transport"))]
+pub(crate) mod sidecar_test_support;
+#[cfg(feature = "real-transport")]
 pub mod transport;
 
 pub use app_server::{
@@ -72,6 +84,22 @@ pub use model::{
     CodexEffortError, CHEAPEST_T2_MODEL, FRESHCODEX_DEFAULT_EFFORT, FRESHCODEX_DEFAULT_MODEL,
     FRESHCODEX_EFFORTS_VERBATIM,
 };
+#[cfg(feature = "real-transport")]
+pub use runtime_select::select_codex_runtime;
+#[cfg(feature = "real-transport")]
+pub use sidecar_reconcile::{
+    codex_sidecar_reconciler, set_codex_sidecar_reconciler, BootReconcileReport,
+    ReattachedCodexAppServerRuntime, SidecarReconciler,
+};
+#[cfg(feature = "real-transport")]
+pub use sidecar_store::{
+    proc_cmdline, proc_starttime, set_codex_sidecar_store, verify_sidecar_identity,
+    CodexSidecarRecord, CodexSidecarStore, IdentityVerdict, SidecarRecordState,
+    SIDECAR_RECORD_VERSION,
+};
+#[cfg(feature = "real-transport")]
+pub use sidecar_sweep::{kill_verified_sidecar_tree, KillOutcome, KillTreeOutcome};
+
 pub use protocol::{
     build_notification_frame, build_request_frame, classify_notification,
     extract_turn_notification_event, parse_client_frame, parse_incoming_frame, turn_status,

crates/freshell-codex/src/runtime_select.rs

@@ -0,0 +1,40 @@
+//! Plan-aware runtime selection (Task 7) — the reattach-vs-spawn seam the
+//! production [`CodexRuntimeFactory`] dispatches through.
+//!
+//! Sibling of [`crate::sidecar_reconcile`] (the pre-authorized split: the
+//! reconcile module sits at its 1,000-line ceiling): the reconciler owns the
+//! CLAIM; this module owns the SELECTION the claim's outcome drives.
+//!
+//! [`CodexRuntimeFactory`]: crate::launch_lifecycle::CodexRuntimeFactory
+
+use std::sync::Arc;
+
+use crate::launch_lifecycle::{CodexLaunchRuntime, SpawnedCodexAppServerRuntime};
+use crate::launch_plan::CodexLaunchPlan;
+use crate::sidecar_reconcile::{ReattachedCodexAppServerRuntime, SidecarReconciler};
+use crate::sidecar_store::CodexSidecarStore;
+
+/// The production selection: a claimable verified survivor for the plan's
+/// resume session ⇒ reattach; otherwise the spawn runtime. Reattach applies
+/// only to resume plans (`plan.session_id` is `Some` ⇔ resume,
+/// [`CodexLaunchPlan::session_id`]), so the A4 fresh-restore exclusion and
+/// the 45s candidate-capture timer are untouched. `None` reconciler/store
+/// (nothing installed at boot) ⇒ spawn — behavior identical to the
+/// pre-reconciler world.
+pub async fn select_codex_runtime(
+    reconciler: Option<&Arc<SidecarReconciler>>,
+    store: Option<&Arc<CodexSidecarStore>>,
+    plan: &CodexLaunchPlan,
+) -> Arc<dyn CodexLaunchRuntime> {
+    if let (Some(reconciler), Some(store), Some(session_id)) =
+        (reconciler, store, plan.session_id.as_deref())
+    {
+        if let Some(record) = reconciler.claim_for_session(session_id).await {
+            return Arc::new(ReattachedCodexAppServerRuntime::new(
+                record,
+                Arc::clone(store),
+            ));
+        }
+    }
+    Arc::new(SpawnedCodexAppServerRuntime::new())
+}