feat(freshclaude): real-CLI ground truth, CLI simulator, Stop without a banner or a lost bell, and structured sidecar logs (core PR-A)

crates/freshell-claude-sidecar/checkpoint-identity.mjs

@@ -0,0 +1,52 @@
+// Checkpoint identity at the SDK replay boundary (pure; used by index.mjs).
+//
+// A checkpointed send carries a v4 uuid on its SDKUserMessage. The CLI echoes
+// a message it takes back as a user row with `isReplay: true` and that uuid
+// (the sidecar opts in with `replay-user-messages`). Only that replay binds the
+// attempt to its native turn id: assistant, tool and result frames, ordinary
+// user rows, and replays of uuids we did not send are never identity evidence.
+
+export const MAX_PENDING_CHECKPOINT_ATTEMPTS = 128
+
+export function isUuid(value) {
+  return typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+}
+
+/** The checkpoint attempt of a `send` request, or undefined when it is absent or incomplete. */
+export function checkpointAttemptOf(raw) {
+  return raw && isUuid(raw.uuid)
+    && typeof raw.logicalAttemptId === 'string' && raw.logicalAttemptId.length > 0
+    && typeof raw.requestId === 'string' && raw.requestId.length > 0
+    ? { uuid: raw.uuid, logicalAttemptId: raw.logicalAttemptId, requestId: raw.requestId }
+    : undefined
+}
+
+/**
+ * Remember an attempt until its replay arrives. The set is bounded: an evicted
+ * attempt simply never gets an identity, which is never approximated by
+ * request order or prompt text.
+ */
+export function rememberCheckpointAttempt(pending, attempt) {
+  pending.delete(attempt.uuid)
+  pending.set(attempt.uuid, attempt)
+  while (pending.size > MAX_PENDING_CHECKPOINT_ATTEMPTS) {
+    pending.delete(pending.keys().next().value)
+  }
+}
+
+/** The `sdk.checkpointTurnIdentity` frame this SDK message proves, consuming its attempt; else undefined. */
+export function takeCheckpointIdentity(pending, sessionId, msg) {
+  if (msg?.type !== 'user' || msg.isReplay !== true || msg.message?.role !== 'user' || !isUuid(msg.uuid)) return undefined
+  const attempt = pending.get(msg.uuid)
+  if (!attempt) return undefined
+  pending.delete(msg.uuid)
+  return {
+    type: 'sdk.checkpointTurnIdentity',
+    sessionId,
+    logicalAttemptId: attempt.logicalAttemptId,
+    requestId: attempt.requestId,
+    nativeTurnId: msg.uuid,
+    displayTurnId: msg.uuid,
+  }
+}

crates/freshell-claude-sidecar/exec-profile.mjs

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process'
 import { openSync, readSync, closeSync, statSync, accessSync, constants } from 'node:fs'
 import { endianness } from 'node:os'
 import path from 'node:path'
+import { usesHostedClaudeRuntime } from './hosted.mjs'
 
 const fail = kind => { throw new Error(`provider exec profile ${kind}: repair inputs before dispatch`) }
 function readBounded(file, limit) {
@@ -79,7 +80,7 @@ export function checkSdkExec(options) {
 }
 
 export function managedSdkSpawn(stderr, environment = process.env) {
-  if (process.platform !== 'linux' || environment.FRESHELL_HOSTED_FRESH_AGENT !== 'claude') return undefined
+  if (process.platform !== 'linux' || !usesHostedClaudeRuntime(environment)) return undefined
   return options => {
     checkSdkExec(options)
     const child = spawn(options.command, options.args, {

crates/freshell-claude-sidecar/hosted-mcp.mjs

@@ -1,6 +1,8 @@
+import { usesHostedClaudeRuntime } from './hosted.mjs'
+
 // The managed launch context selects one fixed recipe. Scoped authentication
 // stays in the inherited child environment and never enters SDK argv/IPC.
 export function hostedMcpServers(selected, env = process.env) {
-  if (selected !== true || env.FRESHELL_HOSTED_FRESH_AGENT !== 'claude') return undefined
+  if (selected !== true || !usesHostedClaudeRuntime(env)) return undefined
   return { freshell: { command: 'node', args: ['/opt/freshell-mcp/server.js'] } }
 }

crates/freshell-claude-sidecar/hosted.mjs

@@ -0,0 +1,25 @@
+// hosted.mjs — whether this sidecar runs inside a hosted session host, and
+// which hosted rules apply. The ONE reader of FRESHELL_HOSTED_FRESH_AGENT:
+// the session host sets it to the provider it hosts, which for this runtime
+// is `claude` (freshclaude) or `kilroy` (crates/freshell-supervisor/src/
+// backend.rs). Two rules read it, and they differ on purpose:
+//   - every hosted sidecar logs CLI output by size only (isHostedSidecar);
+//   - the managed spawn check and the fixed hosted MCP recipe apply to hosted
+//     claude alone (usesHostedClaudeRuntime). Extending them to hosted kilroy
+//     is an explicit item of the api-hosted-ops workstream
+//     (docs/plans/2026-10-22-freshclaude-api-hosted-ops.md §2.4).
+
+/** The provider the session host hosts, or undefined outside a session host. */
+export function hostedProvider(env = process.env) {
+  return env.FRESHELL_HOSTED_FRESH_AGENT || undefined
+}
+
+/** Any hosted sidecar, freshclaude or kilroy: its CLI output is logged by size only. */
+export function isHostedSidecar(env = process.env) {
+  return hostedProvider(env) !== undefined
+}
+
+/** Hosted claude: the SDK spawn is checked against the managed exec profile and the fixed MCP recipe is offered. */
+export function usesHostedClaudeRuntime(env = process.env) {
+  return hostedProvider(env) === 'claude'
+}