Make Claude session identity durable across recovery and automation

README.md

@@ -269,6 +269,13 @@ turning it off removes the server from Freshclaude and Kilroy agents started or
 resumed after the change, with no restart. Terminal panes do not follow the
 switch yet.
 
+With fresh agents enabled, the CLI and MCP client can create Freshclaude or
+Kilroy tabs, split them into panes, send prompts, and capture their conversation
+as plain text. These operations also work without an open browser. Use
+`agent: "claude"` or `agent: "kilroy"` with MCP `new-tab` and `split-pane`, or
+`--agent claude` / `--agent kilroy` with the CLI. Both support resuming a saved
+Claude conversation through `resume`.
+
 ### Rust server scope
 
 The Rust server supports the browser UI, terminal and session workflows, the

config/vitest/vitest.config.ts

@@ -30,6 +30,7 @@ export default defineConfig({
   test: {
     environment: 'jsdom',
     setupFiles: ['./test/setup/dom.ts'],
+    globalSetup: ['./test/setup/runtime-build-preflight.ts'],
     exclude: [
       'test/runtime/**',
       '**/node_modules/**',

crates/freshell-agent-runtime/src/lib.rs

@@ -28,6 +28,7 @@ pub use qualification_policy::{
 };
 pub mod host_actor;
 pub mod snapshot_projection;
+pub mod snapshot_text;
 
 #[cfg(test)]
 #[path = "snapshot_projection_tests.rs"]

crates/freshell-agent-runtime/src/snapshot_text.rs

@@ -0,0 +1,95 @@
+//! Plain-text capture shared by local and hosted fresh-agent REST lanes.
+//! The byte cap always ends at a UTF-8 boundary.
+
+use serde_json::Value;
+
+/// Render role-prefixed turn text, commands, output and error-only turns.
+pub fn render_snapshot_text(snapshot: &Value, max_bytes: usize) -> (String, bool) {
+    let mut output = String::new();
+    if let Some(turns) = snapshot.get("turns").and_then(Value::as_array) {
+        for turn in turns {
+            let role = turn
+                .get("role")
+                .and_then(Value::as_str)
+                .unwrap_or("assistant");
+            let mut body = Vec::new();
+            if let Some(items) = turn.get("items").and_then(Value::as_array) {
+                for item in items {
+                    if let Some(text) = item.get("text").and_then(Value::as_str) {
+                        body.push(text);
+                    } else if let Some(command) = item.get("command").and_then(Value::as_str) {
+                        body.push(command);
+                    } else if let Some(result) = item.get("output").and_then(Value::as_str) {
+                        body.push(result);
+                    }
+                }
+            }
+            if body.is_empty() {
+                // An item-less turn carrying only the durable error module
+                // (a claude API error or failed local command) reads as its
+                // error; anything else falls back to the summary.
+                if let Some(message) = turn.pointer("/error/message").and_then(Value::as_str) {
+                    body.push(message);
+                } else if let Some(summary) = turn.get("summary").and_then(Value::as_str) {
+                    body.push(summary);
+                }
+            }
+            if !body.is_empty() {
+                output.push_str(role);
+                output.push_str(": ");
+                output.push_str(&body.join("\n"));
+                output.push('\n');
+            }
+        }
+    }
+    if output.len() <= max_bytes {
+        return (output, false);
+    }
+    let mut boundary = max_bytes;
+    while boundary > 0 && !output.is_char_boundary(boundary) {
+        boundary -= 1;
+    }
+    output.truncate(boundary);
+    (output, true)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn snapshot_text_renderer_is_plain_and_utf8_bounded() {
+        let snapshot = json!({"turns":[
+            {"role":"user","summary":"ignored","items":[{"kind":"text","text":"héllo"}]},
+            {"role":"assistant","summary":"world","items":[]}
+        ]});
+        let (full, truncated) = render_snapshot_text(&snapshot, 100);
+        assert_eq!(full, "user: héllo\nassistant: world\n");
+        assert!(!truncated);
+        let (short, truncated) = render_snapshot_text(&snapshot, 8);
+        assert!(short.len() <= 8);
+        assert!(short.is_char_boundary(short.len()));
+        assert!(truncated);
+    }
+
+    #[test]
+    fn snapshot_text_renders_error_only_turns_by_their_error_message() {
+        // Real claude snapshots (pinned CLI 2.1.237 goldens): a failed /compact
+        // and an API error are item-less turns carrying only the error module.
+        for (golden, expected) in [
+            (
+                include_str!("../../../test/fixtures/fresh-agent/claude/real-cli-2.1.237/compact-fail/snapshot.golden.json"),
+                "system: Error during compaction: API Error: 400 compaction refused by fake\n",
+            ),
+            (
+                include_str!("../../../test/fixtures/fresh-agent/claude/real-cli-2.1.237/api-error/snapshot.golden.json"),
+                "assistant: API Error: 400 fixture bad request\n",
+            ),
+        ] {
+            let snapshot: Value = serde_json::from_str(golden).unwrap();
+            let (text, _) = render_snapshot_text(&snapshot, 1 << 20);
+            assert!(text.contains(expected), "{text}");
+        }
+    }
+}

crates/freshell-claude-sidecar/index.mjs

@@ -36,8 +36,10 @@
 //   sidecar → Rust (stdout, one JSON per line):
 //     { type:'created',                 requestId, sessionId, protocol:2, cliPid }
 //                                  — sent only once the CLI booted (initializationResult() resolved,
-//                                    T2); sessionId is the SDK bridge's BARE nanoid placeholder and
-//                                    cliPid the CLI's pid. The command catalog follows it.
+//                                    T2); sessionId is the bridge's control id (the requested UUID
+//                                    when provided), and cliPid the CLI's pid. The command catalog
+//                                    follows it. Control messages keep using this bridge id after
+//                                    a conversation reset; Rust follows the new durable id below.
 //     { type:'create.failed',           requestId, code, message }
 //                                  — the CLI refused the boot (boot.mjs names the codes) or the
 //                                    request is not protocol v2. Nothing from the refused boot is
@@ -46,6 +48,9 @@
 //     { type:'sdk.configured',          sessionId, requestId, ok, settings?, message? }
 //     { type:'sdk.session.init',        sessionId, cliSessionId, model, cwd, tools, capabilities? }  // durable Claude UUID;
 //                                  capabilities: the CLI's (msg_lifecycle_v1 says it reports every sent command's lifecycle)
+//     { type:'sdk.session.rekeyed',     sessionId, newSessionId, reason:'conversation_reset' }
+//                                  — before the post-reset init, names its actual durable UUID.
+//                                    conversation_reset.new_conversation_id is only a reset nonce.
 //     { type:'sdk.assistant',           sessionId, content, model, uuid, messageId, parentToolUseId }
 //                                  — one per completed content block (blocks of one API message share
 //                                    messageId); parentToolUseId is set inside a subagent, else null
@@ -109,10 +114,9 @@
 //     ({ severity, component, event, ...ids }, log.mjs). Rust re-emits each
 //     through `tracing` at its severity (claude_sidecar_io.rs).
 //
-// The Rust side normalizes `sdk.* -> freshAgent.*` (a port of
-// server/fresh-agent/sdk-events.ts) and wraps each in a `freshAgent.event`
-// envelope — so this sidecar is the faithful analog of server/sdk-bridge.ts's
-// SdkBridge (it emits the SAME `sdk.*` shapes SdkBridge broadcasts).
+// Rust maps content facts into `freshAgent.event` envelopes. Its per-session
+// turn ledger owns busy status, single-command Stop targets, and attention
+// edges; process EOF owns death and recovery. This bridge forwards CLI facts.
 //
 // This sidecar makes no turn or attention decision (design §3.1, C18): it
 // forwards facts, and the server owns busy, the user's Stop, and every
@@ -286,6 +290,12 @@ function handleSdkMessage(sessionId, msg) {
   for (const frame of lifecycleFrames(sessionId, msg, st.lifecycle)) emit(frame)
 
   switch (msg.type) {
+    case 'conversation_reset': {
+      // The reset's new_conversation_id is a nonce, not the next session UUID
+      // (pinned CLI T16). Its next init identifies the conversation to follow.
+      st.pendingConversationReset = true
+      break
+    }
     case 'user': {
       // The SDK replays actual persisted user messages when this query opts in.
       // Only the unique UUID that this sidecar supplied for a checkpointed send
@@ -296,6 +306,10 @@ function handleSdkMessage(sessionId, msg) {
     }
     case 'system': {
       if (msg.subtype === 'init') {
+        if (st.pendingConversationReset && isUuid(msg.session_id)) {
+          st.pendingConversationReset = false
+          emit({ type: 'sdk.session.rekeyed', sessionId, newSessionId: msg.session_id, reason: 'conversation_reset' })
+        }
         st.cliSessionId = msg.session_id
         st.settings.cwd ??= msg.cwd
         st.terminalCommandNames = Array.isArray(msg.terminal_slash_commands) ? msg.terminal_slash_commands : []
@@ -447,6 +461,7 @@ function handleCreate(req) {
     abort,
     permissionMode: req.permissionMode,
     settings: { model: req.model, effort: req.effort, permissionMode: req.permissionMode, cwd: req.cwd },
+    pendingConversationReset: false,
     // False until `created` is sent; until then nothing reaches Rust and
     // bootEvidence collects what a refusal is named from (boot.mjs).
     booted: false,