very-happy-cli 0.2.90 → 0.2.92

package/dist/{types-BNGeiP1C.cjs → types-CjlB_fKT.cjs}

@@ -51,7 +51,7 @@ var z__namespace = /*#__PURE__*/_interopNamespaceDefault(z);
 var pty__namespace = /*#__PURE__*/_interopNamespaceDefault(pty);
 
 var name = "very-happy-cli";
-var version = "0.2.90";
+var version = "0.2.92";
 var description = "Remote multi-agent workspace CLI with deep Claude integration, native terminal streaming, and self-hosting.";
 var author = "Kirill Dubovitskiy";
 var contributors = [
@@ -164,12 +164,12 @@ var dependencies = {
 	zod: "^4.0.0"
 };
 var optionalDependencies = {
-	"very-happy-tools-arm64-darwin": "0.2.90",
-	"very-happy-tools-x64-darwin": "0.2.90",
-	"very-happy-tools-arm64-linux": "0.2.90",
-	"very-happy-tools-x64-linux": "0.2.90",
-	"very-happy-tools-arm64-win32": "0.2.90",
-	"very-happy-tools-x64-win32": "0.2.90"
+	"very-happy-tools-arm64-darwin": "0.2.92",
+	"very-happy-tools-x64-darwin": "0.2.92",
+	"very-happy-tools-arm64-linux": "0.2.92",
+	"very-happy-tools-x64-linux": "0.2.92",
+	"very-happy-tools-arm64-win32": "0.2.92",
+	"very-happy-tools-x64-win32": "0.2.92"
 };
 var devDependencies = {
 	"@slopus/happy-wire": "workspace:*",
@@ -661,9 +661,27 @@ const sessionToolCallStartEventSchema = z__namespace.object({
   description: z__namespace.string(),
   args: z__namespace.record(z__namespace.string(), z__namespace.unknown())
 });
+const sessionSubagentResultSchema = z__namespace.object({
+  text: z__namespace.string(),
+  truncated: z__namespace.boolean().optional()
+});
+const sessionSubagentUsageSchema = z__namespace.object({
+  toolUses: z__namespace.number().optional(),
+  totalTokens: z__namespace.number().optional(),
+  durationMs: z__namespace.number().optional()
+});
 const sessionToolCallEndEventSchema = z__namespace.object({
   t: z__namespace.literal("tool-call-end"),
-  call: z__namespace.string()
+  call: z__namespace.string(),
+  // Foreground Agent/Task completion: the sub-agent's final report + run
+  // totals (SDK `tool_use_result`). Absent for ordinary tools and for the
+  // background stub ("Async agent launched").
+  result: sessionSubagentResultSchema.extend({
+    isError: z__namespace.boolean().optional(),
+    stats: sessionSubagentUsageSchema.extend({
+      toolStats: z__namespace.record(z__namespace.string(), z__namespace.unknown()).optional()
+    }).optional()
+  }).optional()
 });
 const sessionFileEventSchema = z__namespace.object({
   t: z__namespace.literal("file"),
@@ -682,7 +700,10 @@ const sessionTurnStartEventSchema = z__namespace.object({
 });
 const sessionStartEventSchema = z__namespace.object({
   t: z__namespace.literal("start"),
-  title: z__namespace.string().optional()
+  title: z__namespace.string().optional(),
+  // B-260-P2: identity from SDK task_started / Agent tool input.
+  description: z__namespace.string().optional(),
+  subagentType: z__namespace.string().optional()
 });
 const sessionTurnEndStatusSchema = z__namespace.enum(["completed", "failed", "cancelled"]);
 const sessionTurnUsageSchema = z__namespace.object({
@@ -705,7 +726,21 @@ const sessionTurnEndEventSchema = z__namespace.object({
   usage: sessionTurnUsageSchema.optional()
 });
 const sessionStopEventSchema = z__namespace.object({
-  t: z__namespace.literal("stop")
+  t: z__namespace.literal("stop"),
+  // B-260-P2: from SDK task_notification. A second `stop` for the same
+  // subagent may follow carrying `result` once the notification user message
+  // (which holds the <result> block) arrives; consumers fold by subagent id.
+  status: z__namespace.enum(["completed", "failed", "stopped"]).optional(),
+  result: sessionSubagentResultSchema.optional(),
+  usage: sessionSubagentUsageSchema.optional()
+});
+const sessionProgressEventSchema = z__namespace.object({
+  t: z__namespace.literal("progress"),
+  toolUses: z__namespace.number(),
+  lastTool: z__namespace.string().optional(),
+  totalTokens: z__namespace.number().optional(),
+  durationMs: z__namespace.number().optional(),
+  summary: z__namespace.string().optional()
 });
 const sessionEventSchema = z__namespace.discriminatedUnion("t", [
   sessionTextEventSchema,
@@ -716,7 +751,8 @@ const sessionEventSchema = z__namespace.discriminatedUnion("t", [
   sessionTurnStartEventSchema,
   sessionStartEventSchema,
   sessionTurnEndEventSchema,
-  sessionStopEventSchema
+  sessionStopEventSchema,
+  sessionProgressEventSchema
 ]);
 const sessionEnvelopeSchema = z__namespace.object({
   id: z__namespace.string(),
@@ -747,7 +783,14 @@ const sessionEnvelopeSchema = z__namespace.object({
       path: ["role"]
     });
   }
-  if ((envelope.ev.t === "start" || envelope.ev.t === "stop") && envelope.role !== "agent") {
+  if (envelope.ev.t === "progress" && !envelope.subagent) {
+    ctx.addIssue({
+      code: z__namespace.ZodIssueCode.custom,
+      message: "progress events must carry a subagent",
+      path: ["subagent"]
+    });
+  }
+  if ((envelope.ev.t === "start" || envelope.ev.t === "stop" || envelope.ev.t === "progress") && envelope.role !== "agent") {
     ctx.addIssue({
       code: z__namespace.ZodIssueCode.custom,
       message: `${envelope.ev.t} events must use role "agent"`,
@@ -837,7 +880,11 @@ const UpdateSessionBodySchema = z__namespace.object({
   t: z__namespace.literal("update-session"),
   id: z__namespace.string(),
   metadata: VersionedEncryptedValueSchema.nullish(),
-  agentState: VersionedNullableEncryptedValueSchema.nullish()
+  agentState: VersionedNullableEncryptedValueSchema.nullish(),
+  /** B-265: server-owned archive intent (ms epoch, null = not archived).
+   *  Present only on the archive / unarchive transitions; absent elsewhere.
+   *  Old clients strip it (default z.object) and fall back to `active`. */
+  archivedAt: z__namespace.number().nullable().optional()
 });
 const VersionedMachineEncryptedValueSchema = z__namespace.object({
   version: z__namespace.number(),
@@ -976,7 +1023,9 @@ const WebTerminalListItemSchema = z.z.object({
   mirrorSessionId: z.z.string().optional(),
   /** B-150: auto-restored after a restart (ms epoch) — the directory and the
    *  conversation carried over, the processes did not. Cleared once opened. */
-  restoredAt: z.z.number().optional()
+  restoredAt: z.z.number().optional(),
+  /** B-265: @vh_title_manual is set (user renamed it). */
+  manual: z.z.boolean().optional()
 });
 const ClosedTerminalRecordSchema = z.z.object({
   id: z.z.string(),
@@ -990,6 +1039,9 @@ const ClosedTerminalRecordSchema = z.z.object({
   /** B-149: 'daemon-gap' = died while no daemon was watching (restart/reboot);
    *  absent means an ordinary observed close. */
   reason: z.z.enum(["closed", "daemon-gap"]).optional(),
+  /** B-265: tags + manual-rename flag at close time (restored verbatim). */
+  tags: z.z.array(z.z.string()).optional(),
+  manual: z.z.boolean().optional(),
   closedAt: z.z.number()
 });
 z.z.object({
@@ -1034,6 +1086,15 @@ z.z.object({
    * ignore the field; old daemons never write it (web renders nothing).
    */
   closedTerminals: z.z.array(ClosedTerminalRecordSchema).optional(),
+  /**
+   * B-265 capability flag: this daemon answers `restore-terminal`. Same trust
+   * rule as webTerminals — only `detectedAt >= startedAt` counts, because a
+   * downgraded daemon spreads the stale field forward on connect.
+   */
+  terminalRestore: z.z.object({
+    rpcAvailable: z.z.boolean(),
+    detectedAt: z.z.number()
+  }).optional(),
   /** Relay-owned CLI compatibility/update policy last checked by this daemon. */
   cliUpdate: CliUpdateStateSchema.optional()
 });
@@ -1484,7 +1545,7 @@ class RpcHandlerManager {
   }
 }
 
-const __dirname$1 = path$1.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('types-BNGeiP1C.cjs', document.baseURI).href))));
+const __dirname$1 = path$1.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('types-CjlB_fKT.cjs', document.baseURI).href))));
 function projectPath() {
   const path = path$1.resolve(__dirname$1, "..");
   return path;
@@ -2171,6 +2232,69 @@ function shouldReconnect() {
   return true;
 }
 
+const SUBAGENT_RESULT_MAX_CHARS = 16384;
+const SUBAGENT_PROGRESS_MIN_INTERVAL_MS = 5e3;
+function capSubagentText(text, max = SUBAGENT_RESULT_MAX_CHARS) {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return { text: trimmed };
+  return { text: trimmed.slice(0, max), truncated: true };
+}
+function toolUseResultToText(toolUseResult) {
+  if (!toolUseResult || typeof toolUseResult !== "object") return null;
+  const content = toolUseResult.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+function toolUseResultStatus(toolUseResult) {
+  if (!toolUseResult || typeof toolUseResult !== "object") return "unknown";
+  const status = toolUseResult.status;
+  if (status === "async_launched") return "async_launched";
+  if (status === "completed") return "completed";
+  return "unknown";
+}
+function toolUseResultStats(toolUseResult) {
+  if (!toolUseResult || typeof toolUseResult !== "object") return void 0;
+  const r = toolUseResult;
+  const stats = {};
+  if (typeof r.totalToolUseCount === "number") stats.toolUses = r.totalToolUseCount;
+  if (typeof r.totalTokens === "number") stats.totalTokens = r.totalTokens;
+  if (typeof r.totalDurationMs === "number") stats.durationMs = r.totalDurationMs;
+  if (r.toolStats && typeof r.toolStats === "object") stats.toolStats = r.toolStats;
+  return Object.keys(stats).length > 0 ? stats : void 0;
+}
+function parseTaskNotificationText(text) {
+  if (!/<task-notification>/i.test(text)) return null;
+  const pick = (tag) => text.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "i"))?.[1] ?? null;
+  const rawStatus = pick("status")?.trim().toLowerCase() ?? null;
+  const status = rawStatus === "completed" || rawStatus === "failed" || rawStatus === "stopped" ? rawStatus : null;
+  let resultText = pick("result");
+  let result = null;
+  if (resultText !== null) {
+    resultText = resultText.replace(/^\s*\[harness:[^\]]*\]\s*/i, "").replace(/<usage>[\s\S]*?<\/usage>/gi, "").trim();
+    if (resultText.length > 0) result = capSubagentText(resultText);
+  }
+  return {
+    toolUseId: pick("tool-use-id")?.trim() || null,
+    taskId: pick("task-id")?.trim() || null,
+    status,
+    summary: pick("summary")?.trim() || null,
+    result
+  };
+}
+function shouldEmitProgress(previous, toolUses, now) {
+  if (!previous) return true;
+  if (previous.lastToolUses === toolUses) return false;
+  return now - previous.lastAt >= SUBAGENT_PROGRESS_MIN_INTERVAL_MS;
+}
+
+const SUBAGENT_BUFFER_MAX_MESSAGES = 100;
 function isSubagentTool(name) {
   return name === "Task" || name === "Agent";
 }
@@ -2239,6 +2363,7 @@ function bufferSubagentMessage(state, subagent, message) {
   const buffer = getBufferedSubagentMessages(state);
   const queue = buffer.get(subagent) ?? [];
   queue.push(message);
+  while (queue.length > SUBAGENT_BUFFER_MAX_MESSAGES) queue.shift();
   buffer.set(subagent, queue);
 }
 function consumeBufferedSubagentMessages(state, subagent) {
@@ -2259,6 +2384,31 @@ function getActiveSubagents(state) {
   }
   return state.activeSubagents;
 }
+function getAgentToolCalls(state) {
+  if (!state.agentToolCalls) state.agentToolCalls = /* @__PURE__ */ new Set();
+  return state.agentToolCalls;
+}
+function getSubagentMeta(state) {
+  if (!state.subagentMeta) state.subagentMeta = /* @__PURE__ */ new Map();
+  return state.subagentMeta;
+}
+function getStubSubagents(state) {
+  if (!state.stubSubagents) state.stubSubagents = /* @__PURE__ */ new Set();
+  return state.stubSubagents;
+}
+function getProgressThrottle(state) {
+  if (!state.progressThrottle) state.progressThrottle = /* @__PURE__ */ new Map();
+  return state.progressThrottle;
+}
+function nowOf(state) {
+  return state.now ? state.now() : Date.now();
+}
+function rememberSubagentMeta(state, subagent, meta) {
+  const existing = getSubagentMeta(state).get(subagent) ?? {};
+  const description = typeof meta.description === "string" && meta.description.trim() ? meta.description.trim() : existing.description;
+  const subagentType = typeof meta.subagentType === "string" && meta.subagentType.trim() ? meta.subagentType.trim() : existing.subagentType;
+  getSubagentMeta(state).set(subagent, { ...description ? { description } : {}, ...subagentType ? { subagentType } : {} });
+}
 function pickAssistantUsage(message) {
   if (message.type !== "assistant") return void 0;
   const usage = message.message?.usage;
@@ -2435,13 +2585,26 @@ function maybeEmitSubagentStart(state, turn, subagent, envelopes) {
     return;
   }
   const title = getSubagentTitles(state).get(subagent);
+  const meta = getSubagentMeta(state).get(subagent);
   envelopes.push(createEnvelope("agent", {
     t: "start",
-    ...title ? { title } : {}
+    ...title ? { title } : {},
+    ...meta?.description ? { description: meta.description } : {},
+    ...meta?.subagentType ? { subagentType: meta.subagentType } : {}
   }, { turn, subagent }));
   started.add(subagent);
   getActiveSubagents(state).add(subagent);
 }
+function emitSubagentStopWithStatus(state, turn, subagent, envelopes, payload) {
+  envelopes.push(createEnvelope("agent", {
+    t: "stop",
+    ...payload.status ? { status: payload.status } : {},
+    ...payload.result ? { result: payload.result } : {},
+    ...payload.usage ? { usage: payload.usage } : {}
+  }, { ...turn ? { turn } : {}, subagent }));
+  getActiveSubagents(state).delete(subagent);
+  getStartedSubagents(state).delete(subagent);
+}
 function maybeEmitSubagentStop(state, turn, subagent, envelopes) {
   const active = getActiveSubagents(state);
   if (!active.has(subagent)) {
@@ -2453,8 +2616,6 @@ function maybeEmitSubagentStop(state, turn, subagent, envelopes) {
 function clearSubagentTracking(state) {
   getUuidToProviderSubagent(state).clear();
   getTaskPromptToSubagents(state).clear();
-  getProviderSubagentToSessionSubagent(state).clear();
-  getSubagentTitles(state).clear();
   getBufferedSubagentMessages(state).clear();
   getHiddenParentToolCalls(state).clear();
   getStartedSubagents(state).clear();
@@ -2515,6 +2676,58 @@ function closeClaudeTurnWithStatus(state, status, meta) {
 function mapClaudeLogMessageToSessionEnvelopes(message, state) {
   return mapClaudeLogMessageToSessionEnvelopesInternal(message, state);
 }
+function mapTaskLifecycleSystemMessage(message, state, envelopes) {
+  const raw = message;
+  const subtype = typeof raw.subtype === "string" ? raw.subtype : "";
+  if (!subtype.startsWith("task_")) return;
+  if (raw.skip_transcript === true) return;
+  const toolUseId = typeof raw.tool_use_id === "string" && raw.tool_use_id.length > 0 ? raw.tool_use_id : null;
+  if (!toolUseId || !getAgentToolCalls(state).has(toolUseId)) return;
+  const subagent = ensureSessionSubagentIdForProviderSubagent(state, toolUseId);
+  const usage = raw.usage && typeof raw.usage === "object" ? {
+    ...typeof raw.usage.tool_uses === "number" ? { toolUses: raw.usage.tool_uses } : {},
+    ...typeof raw.usage.total_tokens === "number" ? { totalTokens: raw.usage.total_tokens } : {},
+    ...typeof raw.usage.duration_ms === "number" ? { durationMs: raw.usage.duration_ms } : {}
+  } : void 0;
+  if (subtype === "task_started") {
+    rememberSubagentMeta(state, subagent, { description: raw.description, subagentType: raw.subagent_type });
+    const turn = ensureTurn(state, envelopes);
+    getStartedSubagents(state).delete(subagent);
+    maybeEmitSubagentStart(state, turn, subagent, envelopes);
+    return;
+  }
+  if (subtype === "task_progress") {
+    const toolUses = typeof raw.usage?.tool_uses === "number" ? raw.usage.tool_uses : 0;
+    const throttle = getProgressThrottle(state);
+    const now = nowOf(state);
+    if (!shouldEmitProgress(throttle.get(subagent), toolUses, now)) return;
+    throttle.set(subagent, { lastAt: now, lastToolUses: toolUses });
+    const turn = ensureTurn(state, envelopes);
+    maybeEmitSubagentStart(state, turn, subagent, envelopes);
+    envelopes.push(createEnvelope("agent", {
+      t: "progress",
+      toolUses,
+      ...typeof raw.last_tool_name === "string" && raw.last_tool_name ? { lastTool: raw.last_tool_name } : {},
+      ...usage?.totalTokens !== void 0 ? { totalTokens: usage.totalTokens } : {},
+      ...usage?.durationMs !== void 0 ? { durationMs: usage.durationMs } : {},
+      ...typeof raw.summary === "string" && raw.summary.trim() ? { summary: raw.summary.trim() } : {}
+    }, { turn, subagent }));
+    return;
+  }
+  if (subtype === "task_notification") {
+    const status = raw.status === "completed" || raw.status === "failed" || raw.status === "stopped" ? raw.status : "completed";
+    emitSubagentStopWithStatus(state, state.currentTurnId ?? void 0, subagent, envelopes, {
+      status,
+      ...usage ? { usage } : {}
+    });
+    getStubSubagents(state).delete(subagent);
+    getProgressThrottle(state).delete(subagent);
+    return;
+  }
+  if (subtype === "task_updated" && raw.patch?.is_backgrounded === true) {
+    getStubSubagents(state).add(subagent);
+  }
+}
 function mapClaudeLogMessageToSessionEnvelopesInternal(message, state) {
   const envelopes = [];
   const claudeUuid = pickUuid(message);
@@ -2535,6 +2748,7 @@ function mapClaudeLogMessageToSessionEnvelopesInternal(message, state) {
     };
   }
   if (message.type === "system") {
+    mapTaskLifecycleSystemMessage(message, state, envelopes);
     return {
       currentTurnId: state.currentTurnId,
       envelopes
@@ -2576,6 +2790,9 @@ function mapClaudeLogMessageToSessionEnvelopesInternal(message, state) {
             queueTaskPromptSubagent(state, prompt, call);
           }
           setSubagentTitle(state, sessionSubagentForCall, pickTaskTitle(block.input) ?? prompt);
+          getAgentToolCalls(state).add(call);
+          const input = block.input ?? {};
+          rememberSubagentMeta(state, sessionSubagentForCall, { description: input.description, subagentType: input.subagent_type });
         }
         if (shouldHideParentToolCall(name)) {
           getHiddenParentToolCalls(state).add(call);
@@ -2620,6 +2837,18 @@ function mapClaudeLogMessageToSessionEnvelopesInternal(message, state) {
         maybeEmitSubagentStart(state, turnId2, subagent, envelopes);
         envelopes.push(createEnvelope("agent", { t: "text", text: message.message.content }, { turn: turnId2, subagent, claudeUuid }));
       } else {
+        const origin = message.origin;
+        if (origin?.kind === "task-notification" || /<task-notification>/i.test(message.message.content)) {
+          const fields = parseTaskNotificationText(message.message.content);
+          const providerId = fields?.toolUseId ?? null;
+          const subagentForNotification = providerId && getAgentToolCalls(state).has(providerId) ? getSessionSubagentIdForProviderSubagent(state, providerId) : void 0;
+          if (fields && subagentForNotification && (fields.result || fields.status)) {
+            emitSubagentStopWithStatus(state, state.currentTurnId ?? void 0, subagentForNotification, envelopes, {
+              ...fields.status ? { status: fields.status } : {},
+              ...fields.result ? { result: fields.result } : {}
+            });
+          }
+        }
         closeTurn(state, "completed", envelopes);
         envelopes.push(createEnvelope("user", { t: "text", text: message.message.content }, { claudeUuid }));
       }
@@ -2650,6 +2879,31 @@ function mapClaudeLogMessageToSessionEnvelopesInternal(message, state) {
             getHiddenParentToolCalls(state).delete(block.tool_use_id);
             continue;
           }
+          if (sessionSubagentForToolResult && getAgentToolCalls(state).has(block.tool_use_id)) {
+            const toolUseResult = message.tool_use_result;
+            const resultStatus = toolUseResultStatus(toolUseResult);
+            if (resultStatus === "async_launched") {
+              getStubSubagents(state).add(sessionSubagentForToolResult);
+              envelopes.push(createEnvelope("agent", { t: "tool-call-end", call: block.tool_use_id }, { turn: turnId, subagent }));
+              continue;
+            }
+            if (resultStatus === "completed") {
+              const text = toolUseResultToText(toolUseResult);
+              const stats = toolUseResultStats(toolUseResult);
+              const result = text ? capSubagentText(text) : void 0;
+              emitSubagentStopWithStatus(state, turnId, sessionSubagentForToolResult, envelopes, {
+                status: "completed",
+                ...result ? { result } : {},
+                ...stats ? { usage: { toolUses: stats.toolUses, totalTokens: stats.totalTokens, durationMs: stats.durationMs } } : {}
+              });
+              envelopes.push(createEnvelope("agent", {
+                t: "tool-call-end",
+                call: block.tool_use_id,
+                ...result ? { result: { ...result, ...stats ? { stats } : {} } } : {}
+              }, { turn: turnId, subagent }));
+              continue;
+            }
+          }
           if (sessionSubagentForToolResult) {
             maybeEmitSubagentStop(state, turnId, sessionSubagentForToolResult, envelopes);
           }
@@ -2867,10 +3121,19 @@ class ApiSessionClient extends node_events.EventEmitter {
   directInboundLocalIds = /* @__PURE__ */ new Set();
   routedInboundLocalIds = /* @__PURE__ */ new Set();
   handoverInFlight = null;
-  constructor(token, session) {
+  /** B-265 reconnect: the message cursor was seeded from the server, so
+   *  nothing before it is history to replay — but socket fast-path routing
+   *  must wait for the first fetch, otherwise a message that lands between
+   *  the seed and the first fetch is routed twice (socket + fetch). */
+  awaitingInitialFetch = false;
+  constructor(token, session, opts) {
     super();
     this.token = token;
     this.sessionId = session.id;
+    if (opts?.initialSeq !== void 0 && opts.initialSeq >= 0) {
+      this.lastSeq = opts.initialSeq;
+      this.awaitingInitialFetch = true;
+    }
     this.metadata = session.metadata;
     this.metadataVersion = session.metadataVersion;
     this.agentState = session.agentState;
@@ -2930,7 +3193,7 @@ class ApiSessionClient extends node_events.EventEmitter {
         }
         if (data.body.t === "new-message") {
           const messageSeq = data.body.message?.seq;
-          if (this.lastSeq === 0) {
+          if (this.lastSeq === 0 || this.awaitingInitialFetch) {
             this.receiveSync.invalidate();
             return;
           }
@@ -3226,6 +3489,9 @@ class ApiSessionClient extends node_events.EventEmitter {
         if (message.localId && this.directInboundLocalIds.delete(message.localId)) {
           continue;
         }
+        if (message.localId && this.routedInboundLocalIds.has(message.localId)) {
+          continue;
+        }
         if (message.content?.t !== "encrypted") {
           continue;
         }
@@ -3255,6 +3521,7 @@ class ApiSessionClient extends node_events.EventEmitter {
         break;
       }
     }
+    this.awaitingInitialFetch = false;
   }
   static MAX_OUTBOX_BATCH_SIZE = 50;
   async flushOutbox() {
@@ -4502,6 +4769,101 @@ function registerTodoHandlers(manager) {
   });
 }
 
+function sanitizeTagList(value) {
+  if (!Array.isArray(value)) return void 0;
+  const out = [];
+  for (const tag of value) {
+    if (typeof tag !== "string") continue;
+    const clean = tag.trim();
+    if (clean && !out.includes(clean)) out.push(clean);
+    if (out.length >= 64) break;
+  }
+  return out;
+}
+const LIVE_SNAPSHOT_TTL_MS = 14 * 24 * 60 * 60 * 1e3;
+const LIVE_SNAPSHOT_MAX = 100;
+function sanitizeLiveSnapshot(raw, now, ttlMs = LIVE_SNAPSHOT_TTL_MS, max = LIVE_SNAPSHOT_MAX) {
+  const out = /* @__PURE__ */ new Map();
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  const rows = [];
+  for (const [id, value] of Object.entries(raw)) {
+    if (!id || !value || typeof value !== "object") continue;
+    const { title, cwd, seenAt, tags, manual } = value;
+    if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) continue;
+    if (now - seenAt >= ttlMs) continue;
+    const tagList = sanitizeTagList(tags);
+    rows.push([id, {
+      title: typeof title === "string" && title.trim() ? title : void 0,
+      cwd: typeof cwd === "string" && cwd ? cwd : void 0,
+      ...tagList !== void 0 ? { tags: tagList } : {},
+      ...manual === true ? { manual: true } : {},
+      seenAt
+    }]);
+  }
+  rows.sort((a, b) => b[1].seenAt - a[1].seenAt);
+  for (const [id, info] of rows.slice(0, max)) out.set(id, info);
+  return out;
+}
+function serializeLiveSnapshot(map, max = LIVE_SNAPSHOT_MAX) {
+  const rows = [...map.entries()].sort((a, b) => b[1].seenAt - a[1].seenAt).slice(0, max);
+  const out = {};
+  for (const [id, info] of rows) out[id] = info;
+  return out;
+}
+function liveSnapshotChanged(prev, next) {
+  if (prev.size !== next.size) return true;
+  for (const [id, info] of next) {
+    const before = prev.get(id);
+    if (!before) return true;
+    if (before.title !== info.title || before.cwd !== info.cwd) return true;
+    if (!!before.manual !== !!info.manual) return true;
+    if ((before.tags ?? []).join("\0") !== (info.tags ?? []).join("\0")) return true;
+  }
+  return false;
+}
+const CLAUDE_SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isClaudeSessionId(value) {
+  return typeof value === "string" && CLAUDE_SESSION_ID_RE.test(value);
+}
+function pickMirrorForTerminal(sessions, terminalId) {
+  if (!terminalId) return null;
+  let best = null;
+  for (const [id, session] of Object.entries(sessions || {})) {
+    const meta = session?.metadata;
+    if (!meta || meta.terminalId !== terminalId) continue;
+    const savedAt = typeof session.savedAt === "number" ? session.savedAt : 0;
+    if (best && savedAt <= best.savedAt) continue;
+    best = {
+      id,
+      savedAt,
+      claude: isClaudeSessionId(meta.claudeSessionId) ? meta.claudeSessionId : void 0
+    };
+  }
+  return best ? { sessionId: best.id, claudeSessionId: best.claude } : null;
+}
+
+const TERMINAL_ID_RE$1 = /^[a-zA-Z0-9_-]{1,64}$/;
+function planTerminalRestore(record, facts) {
+  if (facts.tmuxAlive) return { kind: "already-live" };
+  if (!record.cwd || !facts.cwdExists(record.cwd)) return { kind: "error", reason: "missing-cwd" };
+  const resumable = isClaudeSessionId(record.claudeSessionId) && facts.conversationExists(record.cwd, record.claudeSessionId);
+  return {
+    kind: "create",
+    terminalId: record.id,
+    cwd: record.cwd,
+    title: record.title,
+    manual: record.manual === true,
+    tags: record.tags,
+    ...resumable ? { command: `claude --resume ${record.claudeSessionId}` } : {}
+  };
+}
+
+function getProjectPath(workingDirectory) {
+  const projectId = path.resolve(workingDirectory).replace(/[^a-zA-Z0-9-]/g, "-");
+  const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+  return path.join(claudeConfigDir, "projects", projectId);
+}
+
 var xtermHeadless = {};
 
 var hasRequiredXtermHeadless;
@@ -9552,63 +9914,6 @@ function sendTerminalNotification(opts) {
   });
 }
 
-const LIVE_SNAPSHOT_TTL_MS = 14 * 24 * 60 * 60 * 1e3;
-const LIVE_SNAPSHOT_MAX = 100;
-function sanitizeLiveSnapshot(raw, now, ttlMs = LIVE_SNAPSHOT_TTL_MS, max = LIVE_SNAPSHOT_MAX) {
-  const out = /* @__PURE__ */ new Map();
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
-  const rows = [];
-  for (const [id, value] of Object.entries(raw)) {
-    if (!id || !value || typeof value !== "object") continue;
-    const { title, cwd, seenAt } = value;
-    if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) continue;
-    if (now - seenAt >= ttlMs) continue;
-    rows.push([id, {
-      title: typeof title === "string" && title.trim() ? title : void 0,
-      cwd: typeof cwd === "string" && cwd ? cwd : void 0,
-      seenAt
-    }]);
-  }
-  rows.sort((a, b) => b[1].seenAt - a[1].seenAt);
-  for (const [id, info] of rows.slice(0, max)) out.set(id, info);
-  return out;
-}
-function serializeLiveSnapshot(map, max = LIVE_SNAPSHOT_MAX) {
-  const rows = [...map.entries()].sort((a, b) => b[1].seenAt - a[1].seenAt).slice(0, max);
-  const out = {};
-  for (const [id, info] of rows) out[id] = info;
-  return out;
-}
-function liveSnapshotChanged(prev, next) {
-  if (prev.size !== next.size) return true;
-  for (const [id, info] of next) {
-    const before = prev.get(id);
-    if (!before) return true;
-    if (before.title !== info.title || before.cwd !== info.cwd) return true;
-  }
-  return false;
-}
-const CLAUDE_SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-function isClaudeSessionId(value) {
-  return typeof value === "string" && CLAUDE_SESSION_ID_RE.test(value);
-}
-function pickMirrorForTerminal(sessions, terminalId) {
-  if (!terminalId) return null;
-  let best = null;
-  for (const [id, session] of Object.entries(sessions || {})) {
-    const meta = session?.metadata;
-    if (!meta || meta.terminalId !== terminalId) continue;
-    const savedAt = typeof session.savedAt === "number" ? session.savedAt : 0;
-    if (best && savedAt <= best.savedAt) continue;
-    best = {
-      id,
-      savedAt,
-      claude: isClaudeSessionId(meta.claudeSessionId) ? meta.claudeSessionId : void 0
-    };
-  }
-  return best ? { sessionId: best.id, claudeSessionId: best.claude } : null;
-}
-
 const AUTO_RESTORE_DEFAULT_MAX = 6;
 const AUTO_RESTORE_DEFAULT_WINDOW_HOURS = 24;
 const AUTO_RESTORE_HARD_MAX = 20;
@@ -9667,6 +9972,8 @@ function selectAutoRestore(candidates, opts) {
     }
     plans.push({
       terminalId: c.id,
+      ...c.tags !== void 0 ? { tags: c.tags } : {},
+      ...c.manual ? { manual: true } : {},
       cwd: c.cwd,
       title: c.title,
       claudeSessionId: c.claudeSessionId,
@@ -9715,10 +10022,11 @@ function sanitizeClosedTerminals(raw, max = CLOSED_TERMINALS_MAX) {
   const out = [];
   for (const item of raw) {
     if (!item || typeof item !== "object") continue;
-    const { id, title, cwd, mirrorSessionId, claudeSessionId, reason, closedAt } = item;
+    const { id, title, cwd, mirrorSessionId, claudeSessionId, reason, closedAt, tags, manual } = item;
     if (typeof id !== "string" || id.length === 0 || typeof closedAt !== "number") continue;
     if (seen.has(id)) continue;
     seen.add(id);
+    const tagList = sanitizeTagList(tags);
     out.push({
       id,
       title: typeof title === "string" ? title : void 0,
@@ -9726,6 +10034,8 @@ function sanitizeClosedTerminals(raw, max = CLOSED_TERMINALS_MAX) {
       mirrorSessionId: typeof mirrorSessionId === "string" ? mirrorSessionId : void 0,
       claudeSessionId: typeof claudeSessionId === "string" ? claudeSessionId : void 0,
       reason: reason === "daemon-gap" || reason === "closed" ? reason : void 0,
+      ...tagList !== void 0 ? { tags: tagList } : {},
+      ...manual === true ? { manual: true } : {},
       closedAt
     });
   }
@@ -9849,6 +10159,9 @@ function startupInjectionArgs(tmuxSession, command) {
     ["send-keys", "-t", `=${tmuxSession}:`, "Enter"]
   ];
 }
+function seenInfoOf(t) {
+  return { title: t.title, cwd: t.cwd, tags: t.tags, manual: t.manual };
+}
 function terminalListSignature(items) {
   const canon = [...items].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((t) => [
     t.id,
@@ -10485,7 +10798,7 @@ class WebTerminalManager {
   }
   /** Refresh the per-id {title, cwd} cache from an observed live list. */
   noteSeen(list) {
-    this.lastSeenInfo = new Map(list.map((t) => [t.id, { title: t.title, cwd: t.cwd }]));
+    this.lastSeenInfo = new Map(list.map((t) => [t.id, seenInfoOf(t)]));
   }
   /** Record one terminal as closed (dedupe/cap in the pure module) and
    *  persist. The confirming daemonState push rides the list refresh that
@@ -10559,7 +10872,7 @@ class WebTerminalManager {
     const liveIds = new Set(list.map((t) => t.id));
     this.reconcileRestoredSnapshot(liveIds);
     const next = new Map(
-      list.map((t) => [t.id, { title: t.title, cwd: t.cwd }])
+      list.map((t) => [t.id, seenInfoOf(t)])
     );
     let changed = false;
     const now = Date.now();
@@ -10576,6 +10889,8 @@ class WebTerminalManager {
         id,
         title: info.title,
         cwd: info.cwd,
+        tags: info.tags,
+        manual: info.manual,
         // Live binding first (authoritative while it exists), persisted
         // metadata as the fallback once the mirror has been torn down.
         mirrorSessionId: this.mirrorResolver?.(id) ?? mirror?.sessionId,
@@ -10626,6 +10941,8 @@ class WebTerminalManager {
         id,
         title: info.title,
         cwd: info.cwd,
+        tags: info.tags,
+        manual: info.manual,
         mirrorSessionId: mirror?.sessionId,
         claudeSessionId: mirror?.claudeSessionId,
         reason: "daemon-gap",
@@ -10636,6 +10953,8 @@ class WebTerminalManager {
         id,
         title: info.title,
         cwd: info.cwd,
+        tags: info.tags,
+        manual: info.manual,
         seenAt: info.seenAt,
         claudeSessionId: mirror?.claudeSessionId
       });
@@ -10711,6 +11030,51 @@ class WebTerminalManager {
    * exactly like a terminal whose pty was reaped.
    */
   restoreOneTerminal(plan) {
+    return this.createDetachedTerminal(plan);
+  }
+  /**
+   * B-265: `restore-terminal` — bring ONE closed terminal back with its
+   * original id / cwd / title (+ manual flag) / tags and, when the record
+   * knows a claude conversation whose JSONL is still on disk, `claude
+   * --resume` injected. Idempotent: an id whose tmux session already exists
+   * is a success. The closed record is left to `pruneClosedAgainstLive` (the
+   * next tick sees the id live again); the tombstone is deliberately kept —
+   * a live tmux session attaches regardless, and dropping it would re-open
+   * the stale-client resurrection hole B-149 closed.
+   */
+  restoreClosedTerminal(terminalId) {
+    if (typeof terminalId !== "string" || !TERMINAL_ID_RE$1.test(terminalId)) return { type: "error", reason: "invalid-id" };
+    if (!isTmuxAvailable()) return { type: "error", reason: "no-tmux" };
+    const record = this.closedTerminals.find((r) => r.id === terminalId);
+    if (!record) return { type: "error", reason: "no-record" };
+    const env = ptyEnv();
+    const alive = node_child_process.spawnSync(
+      "tmux",
+      tmuxArgs(["has-session", "-t", `=vh-${terminalId}:`]),
+      { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+    ).status === 0;
+    const plan = planTerminalRestore(record, {
+      tmuxAlive: alive,
+      cwdExists: (cwd) => {
+        try {
+          return node_fs.existsSync(cwd) && node_fs.statSync(cwd).isDirectory();
+        } catch {
+          return false;
+        }
+      },
+      conversationExists: (cwd, claudeSessionId) => node_fs.existsSync(path.join(getProjectPath(cwd), `${claudeSessionId}.jsonl`))
+    });
+    if (plan.kind === "already-live") return { type: "success", terminalId };
+    if (plan.kind === "error") return { type: "error", reason: plan.reason };
+    if (!this.createDetachedTerminal(plan)) return { type: "error", reason: "create-failed" };
+    logger.info(`[WEB TERMINAL] restored closed terminal ${terminalId} in ${plan.cwd}${plan.command ? " (conversation resumed)" : ""}`);
+    this.kickListRefresh();
+    return { type: "success", terminalId };
+  }
+  /** Shared cold-create for auto-restore (B-150) and restore-terminal
+   *  (B-265): same create-only env as the interactive path, title/tags
+   *  written back, optional startup command injected. */
+  createDetachedTerminal(plan) {
     const env = ptyEnv();
     const name = `vh-${plan.terminalId}`;
     const exists = node_child_process.spawnSync(
@@ -10747,18 +11111,35 @@ class WebTerminalManager {
         tmuxArgs(["set-option", "-t", `=${name}:`, "@vh_title", plan.title]),
         { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
       );
+      if (plan.manual) {
+        node_child_process.spawnSync(
+          "tmux",
+          tmuxArgs(["set-option", "-t", `=${name}:`, "@vh_title_manual", "1"]),
+          { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+        );
+      }
+    }
+    const tags = plan.tags !== void 0 ? validateTerminalTags(plan.tags) : void 0;
+    if (tags && tags.length > 0) {
+      node_child_process.spawnSync(
+        "tmux",
+        tmuxArgs(["set-option", "-t", `=${name}:`, "@vh_tags", JSON.stringify(tags)]),
+        { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
+      );
     }
-    for (const argv of startupInjectionArgs(name, plan.command)) {
-      node_child_process.spawnSync("tmux", tmuxArgs(argv), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
+    if (plan.command) {
+      for (const argv of startupInjectionArgs(name, plan.command)) {
+        node_child_process.spawnSync("tmux", tmuxArgs(argv), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
+      }
     }
-    logger.info(`[WEB TERMINAL] auto-restored ${plan.terminalId} in ${plan.cwd}`);
+    logger.info(`[WEB TERMINAL] cold-created ${plan.terminalId} in ${plan.cwd}`);
     return true;
   }
   /** Mirror the in-memory cache to disk, but only when something a restart
    *  would care about changed (see liveSnapshotChanged). */
   persistLiveSnapshot(live, now) {
     const candidate = /* @__PURE__ */ new Map();
-    for (const [id, info] of live) candidate.set(id, { title: info.title, cwd: info.cwd, seenAt: now });
+    for (const [id, info] of live) candidate.set(id, { title: info.title, cwd: info.cwd, tags: info.tags, manual: info.manual, seenAt: now });
     if (!liveSnapshotChanged(this.lastPersistedSnapshot, candidate)) return;
     this.lastPersistedSnapshot = candidate;
     saveLiveSnapshot(candidate);
@@ -11333,6 +11714,8 @@ class WebTerminalManager {
         id: terminalId,
         title: info.title,
         cwd: info.cwd,
+        tags: info.tags,
+        manual: info.manual,
         mirrorSessionId: this.mirrorResolver?.(terminalId) ?? mirror?.sessionId,
         claudeSessionId: mirror?.claudeSessionId,
         reason: "closed",
@@ -11416,7 +11799,8 @@ class WebTerminalManager {
           // tmux last-activity (epoch s) → ms; optional so old daemons
           // simply omit it and web clients fall back to createdAt.
           activityAt: s.activity,
-          agentState: this.probeAgentState(s.name, s.paneCurrentCommand)
+          agentState: this.probeAgentState(s.name, s.paneCurrentCommand),
+          manual: s.manual
         });
       }
       return out;
@@ -11866,12 +12250,6 @@ function detectResumeSupport(happyHomeDir = configuration.happyHomeDir) {
   };
 }
 
-function getProjectPath(workingDirectory) {
-  const projectId = path.resolve(workingDirectory).replace(/[^a-zA-Z0-9-]/g, "-");
-  const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
-  return path.join(claudeConfigDir, "projects", projectId);
-}
-
 class ForkTruncateUuidNotFoundError extends Error {
   constructor(cutAfterUuid, sourcePath) {
     super(`Truncation UUID ${cutAfterUuid} not found in ${sourcePath}`);
@@ -13376,6 +13754,7 @@ class ApiMachineClient {
   cliUpdatePushChain = Promise.resolve();
   rpcHandlerManager;
   resumeSessionHandler = null;
+  restartSessionHandler = null;
   stopSessionHandler = null;
   listTrackedSessionIds = null;
   reconnectInterval = null;
@@ -13442,11 +13821,13 @@ class ApiMachineClient {
   setRPCHandlers({
     spawnSession,
     resumeSession,
+    restartSession,
     stopSession,
     listTrackedSessionIds,
     requestShutdown
   }) {
     this.resumeSessionHandler = resumeSession ?? null;
+    this.restartSessionHandler = restartSession ?? null;
     this.stopSessionHandler = stopSession;
     this.listTrackedSessionIds = listTrackedSessionIds ?? null;
     this.rpcHandlerManager.registerHandler("spawn-happy-session", async (params) => {
@@ -13468,6 +13849,7 @@ class ApiMachineClient {
       }
     });
     this.syncResumeSessionRpcRegistration();
+    this.syncRestartSessionRpcRegistration();
     this.rpcHandlerManager.registerHandler("open-terminal", async (params) => {
       const { terminalId, cols, rows, cwd, fromSeq, encStream, startupCommand, resub, attachOnly, streamMode } = params || {};
       const result = await this.webTerminal.open({
@@ -13543,6 +13925,14 @@ class ApiMachineClient {
       this.encTerminals.delete(terminalId);
       return { type: "success" };
     });
+    this.rpcHandlerManager.registerHandler("restore-terminal", async (params) => {
+      const { terminalId } = params || {};
+      const result = this.webTerminal.restoreClosedTerminal(terminalId);
+      if (result.type === "error") {
+        return { type: "error", reason: result.reason, errorMessage: `restore-terminal: ${result.reason}` };
+      }
+      return { type: "success", terminalId: result.terminalId };
+    });
     this.rpcHandlerManager.registerHandler("list-terminals", async () => {
       return { type: "success", terminals: this.webTerminal.buildTerminalList() };
     });
@@ -13694,6 +14084,40 @@ class ApiMachineClient {
       return { message: "Daemon stop request acknowledged, starting shutdown sequence..." };
     });
   }
+  // B-264: symmetric to resume, but the handler stops a live-but-broken
+  // wrapper first. Old web never calls it; new web calling an old daemon that
+  // lacks the handler gets "method not found" and shows an upgrade hint —
+  // never a double-spawn.
+  syncRestartSessionRpcRegistration() {
+    const method = "restart-session";
+    if (this.restartSessionHandler) {
+      if (!this.rpcHandlerManager.hasHandler(method)) {
+        this.rpcHandlerManager.registerHandler(method, async (params) => {
+          const { sessionId, model, permissionMode } = params || {};
+          if (!sessionId || typeof sessionId !== "string") {
+            throw new Error("Session ID is required");
+          }
+          const handler = this.restartSessionHandler;
+          if (!handler) {
+            throw new Error("Restart session handler not available");
+          }
+          const result = await handler(sessionId, { model, permissionMode });
+          switch (result.type) {
+            case "success":
+              return { type: "success", sessionId: result.sessionId };
+            case "requestToApproveDirectoryCreation":
+              return result;
+            case "error":
+              throw new Error(result.errorMessage);
+          }
+        });
+      }
+      return;
+    }
+    if (this.rpcHandlerManager.hasHandler(method)) {
+      this.rpcHandlerManager.unregisterHandler(method);
+    }
+  }
   syncResumeSessionRpcRegistration() {
     const method = "resume-happy-session";
     if (this.resumeSessionHandler) {
@@ -13901,6 +14325,9 @@ class ApiMachineClient {
         httpPort: this.machine.daemonState?.httpPort,
         startedAt: now,
         webTerminals: { updatedAt: now, terminals: initialTerminals },
+        // B-265 capability flag; restamped every connect so the
+        // web's `detectedAt >= startedAt` trust rule holds.
+        terminalRestore: { rpcAvailable: true, detectedAt: now },
         // B-084: closed records survive daemon restarts (persisted
         // in closed-terminals.json), so the connect snapshot ships
         // them too — not just the incremental pushes.
@@ -13910,6 +14337,7 @@ class ApiMachineClient {
     this.webTerminal.startListTracking((terminals) => this.pushTerminalList(terminals));
     if (!rpcAlreadyRegistered) this.rpcHandlerManager.onSocketConnect(socket);
     this.syncResumeSessionRpcRegistration();
+    this.syncRestartSessionRpcRegistration();
     this.startKeepAlive();
     void this.reconcileArchivedSessions();
     void this.refreshRelayConnection();
@@ -14145,6 +14573,7 @@ class ApiMachineClient {
         if (this.relaySocket !== relaySocket) return;
         this.rpcHandlerManager.onSocketConnect(relaySocket);
         this.syncResumeSessionRpcRegistration();
+        this.syncRestartSessionRpcRegistration();
         logger.debug(`[API MACHINE] Connected to regional relay ${selected.assignment.relayId}`);
       });
       relaySocket.on("disconnect", () => {
@@ -14919,8 +15348,8 @@ class ApiClient {
       throw error;
     }
   }
-  sessionSyncClient(session) {
-    return new ApiSessionClient(this.credential.token, session);
+  sessionSyncClient(session, opts) {
+    return new ApiSessionClient(this.credential.token, session, opts);
   }
   machineSyncClient(machine) {
     return new ApiMachineClient(this.credential.token, machine);
@@ -15096,6 +15525,56 @@ class ApiClient {
       return false;
     }
   }
+  /**
+   * B-265: one session by id — the message cursor (`seq`), metadata and
+   * agent state with their versions, decrypted with the session key the
+   * reconnecting process already holds. `unsupported` = the server has no
+   * such route (or the row is gone): callers fall back to the legacy
+   * skip-all-history reconnect. Transient failures are retried a few times
+   * first, because falling back silently discards the very message a restore
+   * is meant to deliver.
+   */
+  async getSession(sessionId, encryptionKey, encryptionVariant, opts) {
+    const attempts = opts?.attempts ?? 3;
+    const delays = opts?.delaysMs ?? [500, 1500];
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try {
+        const response = await axios.get(
+          `${configuration.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}`,
+          {
+            headers: {
+              "Authorization": `Bearer ${this.credential.token}`,
+              "X-Happy-Client": `cli-coding-session/${configuration.currentCliVersion}`
+            },
+            timeout: opts?.timeoutMs ?? 4e3,
+            validateStatus: () => true
+          }
+        );
+        if (response.status === 404 || response.status === 401 || response.status === 403) {
+          return { ok: false, reason: "unsupported" };
+        }
+        if (response.status >= 200 && response.status < 300) {
+          const row = response.data.session;
+          if (!row || typeof row.seq !== "number" || typeof row.metadata !== "string") {
+            return { ok: false, reason: "unsupported" };
+          }
+          const metadata = decrypt(encryptionKey, encryptionVariant, decodeBase64(row.metadata));
+          if (!metadata) return { ok: false, reason: "unavailable" };
+          const agentState = row.agentState ? decrypt(encryptionKey, encryptionVariant, decodeBase64(row.agentState)) : null;
+          return {
+            ok: true,
+            session: { seq: row.seq, metadata, metadataVersion: row.metadataVersion, agentState, agentStateVersion: row.agentStateVersion }
+          };
+        }
+        logger.debug(`[API] getSession ${sessionId}: status ${response.status} (attempt ${attempt + 1}/${attempts})`);
+      } catch (error) {
+        logger.debug(`[API] getSession ${sessionId} failed (attempt ${attempt + 1}/${attempts}):`, error);
+      }
+      const delayMs = delays[Math.min(attempt, delays.length - 1)];
+      if (attempt < attempts - 1 && delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+    }
+    return { ok: false, reason: "unavailable" };
+  }
   /** Clear the server-owned archive tombstone before an intentional resume.
    * Older servers return 404 because the endpoint does not exist; that is a
    * compatible no-op because those servers also have no durable tombstone. */
@@ -15232,6 +15711,7 @@ exports.getProjectPath = getProjectPath;
 exports.hardenPrivateFile = hardenPrivateFile;
 exports.hardenPrivateFileSync = hardenPrivateFileSync;
 exports.initializeSandbox = initializeSandbox;
+exports.isClaudeSessionId = isClaudeSessionId;
 exports.isValidSessionId = isValidSessionId;
 exports.isValidTerminalId = isValidTerminalId;
 exports.listVhTerminals = listVhTerminals;