@cjhyy/code-shell-core 0.6.0-rc.12 → 0.6.0-rc.13

package/dist/protocol/server.js

@@ -73,6 +73,14 @@ export class AgentServer {
     approvalTimers = new Map();
     /** Default approval timeout: 5 minutes */
     static APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
+    /**
+     * Wall-clock timeout for AskUserQuestion during a GOAL run (10 minutes).
+     * Plain interactive asks stay untimed; only a self-driving goal run arms this
+     * so a mid-goal question can't suspend the loop forever with nobody watching.
+     * Longer than the tool-approval timeout — a user who IS present deserves more
+     * time to compose a real answer before we assume-and-continue.
+     */
+    static GOAL_ASKUSER_TIMEOUT_MS = 10 * 60 * 1000;
     /**
      * Unsubscribe handle for the process-local `agentNotificationBus`
      * subscription set up in the constructor. Called from `close()` so a
@@ -467,9 +475,7 @@ export class AgentServer {
             // the user already knows they pressed stop; clients should
             // just clear busy.
             const errName = err.name;
-            const aborted = runController.signal.aborted ||
-                errName === "AbortError" ||
-                errName === "APIUserAbortError";
+            const aborted = runController.signal.aborted || errName === "AbortError" || errName === "APIUserAbortError";
             if (aborted) {
                 const cancelledResult = {
                     text: "",
@@ -1239,8 +1245,7 @@ export class AgentServer {
                     const key = params.key;
                     if (!key)
                         throw new Error("provider_refresh: key required");
-                    const providers = engine.readSetting("providers") ??
-                        [];
+                    const providers = engine.readSetting("providers") ?? [];
                     const p = providers.find((x) => x.key === key);
                     if (!p)
                         throw new Error(`provider not found: ${key}`);
@@ -1276,8 +1281,7 @@ export class AgentServer {
                     if (refs.length > 0) {
                         throw new Error(`provider ${key} referenced by models: ${refs.join(", ")}`);
                     }
-                    const providers = engine.readSetting("providers") ??
-                        [];
+                    const providers = engine.readSetting("providers") ?? [];
                     const next = providers.filter((p) => p.key !== key);
                     engine.updateConfig("providers", next);
                     this.transport.send(createResponse(req.id, { type: "provider_delete", data: { ok: true } }));
@@ -1461,7 +1465,9 @@ export class AgentServer {
                 this.clearApprovalTimer(requestId);
                 const result = decision;
                 if (result && typeof result === "object" && "approved" in result) {
-                    resolve(result.approved ? (result.answer ?? "") : (result.reason ?? "(user declined to answer)"));
+                    resolve(result.approved
+                        ? (result.answer ?? "")
+                        : (result.reason ?? "(user declined to answer)"));
                 }
                 else {
                     // chatManager approve handler resolves with the raw decision value.
@@ -1487,6 +1493,37 @@ export class AgentServer {
                     riskLevel: "low",
                 },
             });
+            // Goal mode is an unattended, self-driving run: nobody may be watching to
+            // answer, and this ask channel otherwise has NO wall-clock timeout — so a
+            // model that calls AskUserQuestion mid-goal would suspend the turn loop
+            // forever (only a manual Stop could unblock it). When a goal is active,
+            // arm the shared 10-minute approval timeout: on expiry, drain the pending
+            // ask and resolve with a nudge so the loop keeps making progress instead
+            // of hanging. Plain interactive (no-goal) asks keep their intentional
+            // no-timeout behavior — a human can take as long as they like.
+            let goalActive = false;
+            try {
+                goalActive = !!session.getGoal();
+            }
+            catch {
+                goalActive = false;
+            }
+            if (goalActive) {
+                const timer = setTimeout(() => {
+                    const resolveFn = session.pendingApprovals.get(requestId);
+                    if (resolveFn) {
+                        session.pendingApprovals.delete(requestId);
+                        this.approvalTimers.delete(requestId);
+                        resolveFn("(用户未在限定时间内回答;目标运行中请自行做出合理假设并继续推进。)");
+                        // Tell every client the ask is resolved (nobody answered) so the
+                        // stale AskUserQuestion card is dismissed instead of lingering as
+                        // if still waiting. Reuses the same envelope shape the desktop main
+                        // already broadcasts / the renderer's onApprovalResolved consumes.
+                        this.notify(Methods.ApprovalResolved, { sessionId, requestId });
+                    }
+                }, AgentServer.GOAL_ASKUSER_TIMEOUT_MS);
+                this.approvalTimers.set(requestId, timer);
+            }
         });
     }
     /**

package/dist/protocol/types.d.ts

@@ -293,6 +293,10 @@ export declare const Methods: {
     readonly BackgroundWork: "agent/backgroundWork";
     readonly StreamEvent: "agent/streamEvent";
     readonly ApprovalRequest: "agent/approvalRequest";
+    /** Server-initiated resolution of a pending approval/ask (e.g. a goal-mode
+     *  AskUserQuestion that timed out) so every client can dismiss its stale card
+     *  without a user decision. Same envelope the desktop main broadcasts. */
+    readonly ApprovalResolved: "agent/approvalResolved";
     readonly Status: "agent/status";
 };
 export declare function createRequest(method: string, params?: Record<string, unknown>): RpcRequest;

package/dist/protocol/types.js

@@ -56,6 +56,10 @@ export const Methods = {
     // Server → Client (notifications, no id)
     StreamEvent: "agent/streamEvent",
     ApprovalRequest: "agent/approvalRequest",
+    /** Server-initiated resolution of a pending approval/ask (e.g. a goal-mode
+     *  AskUserQuestion that timed out) so every client can dismiss its stale card
+     *  without a user decision. Same envelope the desktop main broadcasts. */
+    ApprovalResolved: "agent/approvalResolved",
     Status: "agent/status",
 };
 // ─── Helpers ────────────────────────────────────────────────────────

package/dist/run/FileRunStore.js

@@ -12,6 +12,8 @@
 import { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync, readdirSync, renameSync, rmSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
 export class FileRunStore {
     runsDir;
     constructor(storageDir) {
@@ -20,6 +22,7 @@ export class FileRunStore {
     }
     // ─── Helpers ───────────────────────────────────────────────────
     runDir(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId);
     }
     ensureRunDir(runId) {
@@ -31,7 +34,7 @@ export class FileRunStore {
         return dir;
     }
     writeJson(filePath, data) {
-        const tmp = filePath + ".tmp";
+        const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
         try {
             writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
             // Atomic rename — prevents partial writes on crash
@@ -153,6 +156,8 @@ export class FileRunStore {
     }
     // ─── Checkpoints ───────────────────────────────────────────────
     async saveCheckpoint(cp) {
+        assertSafeRunId(cp.runId);
+        assertSafeRunFileId(cp.checkpointId, "checkpoint id");
         const dir = this.runDir(cp.runId);
         this.writeJson(join(dir, "checkpoints", `${cp.checkpointId}.json`), cp);
     }
@@ -175,10 +180,14 @@ export class FileRunStore {
     }
     // ─── Approvals ─────────────────────────────────────────────────
     async saveApproval(approval) {
+        assertSafeRunId(approval.runId);
+        assertSafeRunFileId(approval.approvalId, "approval id");
         const dir = this.runDir(approval.runId);
         this.writeJson(join(dir, "approvals", `${approval.approvalId}.json`), approval);
     }
     async getApproval(runId, approvalId) {
+        assertSafeRunId(runId);
+        assertSafeRunFileId(approvalId, "approval id");
         return this.readJson(join(this.runDir(runId), "approvals", `${approvalId}.json`));
     }
     async getPendingApproval(runId) {

package/dist/run/Heartbeat.js

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { assertSafeRunId } from "./ids.js";
 export class Heartbeat {
     runsDir;
     intervalMs;
@@ -23,6 +24,12 @@ export class Heartbeat {
      * Start heartbeat for a run. Writes immediately, then repeats on interval.
      */
     start(runId) {
+        assertSafeRunId(runId);
+        const existing = this.timers.get(runId);
+        if (existing) {
+            clearInterval(existing);
+            this.timers.delete(runId);
+        }
         // Write first heartbeat immediately
         this.write(runId);
         // Schedule periodic heartbeats
@@ -37,6 +44,7 @@ export class Heartbeat {
      * Stop heartbeat for a run and remove the heartbeat file.
      */
     stop(runId) {
+        assertSafeRunId(runId);
         const timer = this.timers.get(runId);
         if (timer) {
             clearInterval(timer);
@@ -56,6 +64,7 @@ export class Heartbeat {
      * Read the last heartbeat for a run. Returns null if no heartbeat exists.
      */
     read(runId) {
+        assertSafeRunId(runId);
         const filePath = this.filePath(runId);
         if (!existsSync(filePath))
             return null;
@@ -71,6 +80,7 @@ export class Heartbeat {
      * Returns true if stale or missing, false if recent.
      */
     isStale(runId, thresholdMs) {
+        assertSafeRunId(runId);
         const threshold = thresholdMs ?? this.intervalMs * 3;
         const data = this.read(runId);
         if (!data)
@@ -81,6 +91,7 @@ export class Heartbeat {
      * Check if the process that wrote the heartbeat is still alive.
      */
     isProcessAlive(runId) {
+        assertSafeRunId(runId);
         const data = this.read(runId);
         if (!data)
             return false;
@@ -118,6 +129,7 @@ export class Heartbeat {
         }
     }
     filePath(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId, "heartbeat");
     }
 }

package/dist/run/RunApprovalBackend.d.ts

@@ -16,6 +16,7 @@ import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
 export interface PendingApproval {
     resolve: (result: ApprovalResult) => void;
     request: ApprovalRequest;
+    timer: ReturnType<typeof setTimeout>;
 }
 export interface PendingInput {
     resolve: (answer: string) => void;
@@ -32,6 +33,7 @@ export interface RunLifecycleHooks {
 export declare class RunApprovalBackend implements ApprovalBackend {
     private pendingApproval;
     private hooks;
+    private approvalRequestSeq;
     setHooks(hooks: RunLifecycleHooks): void;
     /** Max time (ms) to wait for approval before auto-rejecting. Default: 24h */
     private timeoutMs;
@@ -42,6 +44,7 @@ export declare class RunApprovalBackend implements ApprovalBackend {
      */
     resolveApproval(result: ApprovalResult): boolean;
     hasPendingApproval(): boolean;
+    private supersedePendingApproval;
 }
 /**
  * Creates an AskUserFn that suspends the run when user input is needed.

package/dist/run/RunApprovalBackend.js

@@ -14,6 +14,7 @@
 export class RunApprovalBackend {
     pendingApproval = null;
     hooks = null;
+    approvalRequestSeq = 0;
     setHooks(hooks) {
         this.hooks = hooks;
     }
@@ -23,7 +24,8 @@ export class RunApprovalBackend {
         this.timeoutMs = ms;
     }
     async requestApproval(request) {
-        if (!this.hooks) {
+        const hooks = this.hooks;
+        if (!hooks) {
             // No hooks wired — fail CLOSED. This backend is the engine's approval
             // path for an interactive run; if a host forgot to setHooks() there is
             // no UI to ask, so auto-approving every tool (the old behavior) silently
@@ -34,11 +36,8 @@ export class RunApprovalBackend {
                 reason: "run approval backend has no lifecycle hooks wired (denied fail-closed)",
             };
         }
-        // Notify RunManager that approval is needed
-        const { approvalId } = await this.hooks.onApprovalNeeded(request);
-        // Suspend execution until resolved (with timeout safety net)
+        const requestSeq = ++this.approvalRequestSeq;
         return new Promise((resolve) => {
-            this.pendingApproval = { resolve, request };
             const timer = setTimeout(() => {
                 if (this.pendingApproval?.resolve === resolve) {
                     this.pendingApproval = null;
@@ -48,6 +47,30 @@ export class RunApprovalBackend {
             if (typeof timer === "object" && "unref" in timer) {
                 timer.unref();
             }
+            this.supersedePendingApproval();
+            this.pendingApproval = { resolve, request, timer };
+            void Promise.resolve()
+                .then(() => hooks.onApprovalNeeded(request))
+                .then(() => {
+                if (requestSeq !== this.approvalRequestSeq &&
+                    this.pendingApproval?.resolve === resolve) {
+                    this.pendingApproval = null;
+                    clearTimeout(timer);
+                    resolve({
+                        approved: false,
+                        reason: "superseded: a newer approval request replaced this one before it was answered",
+                    });
+                }
+            }, (err) => {
+                if (this.pendingApproval?.resolve !== resolve)
+                    return;
+                this.pendingApproval = null;
+                clearTimeout(timer);
+                resolve({
+                    approved: false,
+                    reason: `approval request failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            });
         });
     }
     /**
@@ -56,14 +79,26 @@ export class RunApprovalBackend {
     resolveApproval(result) {
         if (!this.pendingApproval)
             return false;
-        const { resolve } = this.pendingApproval;
+        const { resolve, timer } = this.pendingApproval;
         this.pendingApproval = null;
+        clearTimeout(timer);
         resolve(result);
         return true;
     }
     hasPendingApproval() {
         return this.pendingApproval !== null;
     }
+    supersedePendingApproval() {
+        if (!this.pendingApproval)
+            return;
+        const { resolve, timer } = this.pendingApproval;
+        this.pendingApproval = null;
+        clearTimeout(timer);
+        resolve({
+            approved: false,
+            reason: "superseded: a newer approval request replaced this one before it was answered",
+        });
+    }
 }
 // ─── RunAskUserAdapter ───────────────────────────────────────────
 /**

package/dist/run/RunLock.js

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { lock, check, unlock } from "../utils/lockfile.js";
 import { logger } from "../logging/logger.js";
+import { assertSafeRunId } from "./ids.js";
 export class RunLock {
     runsDir;
     staleMs;
@@ -135,6 +136,7 @@ export class RunLock {
         }
     }
     lockTarget(runId) {
+        assertSafeRunId(runId);
         return join(this.runsDir, runId, "run.json");
     }
 }

package/dist/run/RunManager.d.ts

@@ -66,6 +66,7 @@ export declare class RunManager {
     resume(runId: string, input?: ResumeRunInput): Promise<void>;
     private resumeInner;
     cancel(runId: string, reason?: string): Promise<void>;
+    private cancelInner;
     get(runId: string): Promise<RunSnapshot | null>;
     list(query?: ListRunsQuery): Promise<RunSnapshot[]>;
     getEvents(runId: string): Promise<RunEvent[]>;
@@ -90,5 +91,6 @@ export declare class RunManager {
     private transition;
     private emitRunEvent;
     private notifySubscribers;
+    private getPendingApprovalForResume;
     private getOrThrow;
 }

package/dist/run/RunManager.js

@@ -19,7 +19,13 @@ import { ArtifactTracker } from "./ArtifactTracker.js";
 import { RunLock } from "./RunLock.js";
 import { Heartbeat } from "./Heartbeat.js";
 import { NoopEvaluator } from "./Evaluator.js";
+import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
 import { VALID_TRANSITIONS } from "./types.js";
+function hasOwnString(value, key) {
+    return (value !== undefined &&
+        Object.prototype.hasOwnProperty.call(value, key) &&
+        typeof value[key] === "string");
+}
 export class RunManager {
     store;
     queue;
@@ -69,6 +75,9 @@ export class RunManager {
     async submit(input) {
         const now = Date.now();
         const runId = nanoid(16);
+        if (input.parentRunId !== undefined && input.parentRunId !== null) {
+            assertSafeRunId(input.parentRunId);
+        }
         const snapshot = {
             runId,
             objective: input.objective,
@@ -110,6 +119,7 @@ export class RunManager {
     }
     // ─── Resume ────────────────────────────────────────────────────
     async resume(runId, input) {
+        assertSafeRunId(runId);
         // Serialize resume/cancel decisions per run. Without this, two concurrent
         // resumes (or resume racing cancel) both pass the status check below —
         // status stays `waiting_*` until a later `await transition()` — and both
@@ -139,18 +149,15 @@ export class RunManager {
         if (handle) {
             if (run.status === "waiting_approval" && input?.approvalDecision) {
                 const { approvalId, approved, reason } = input.approvalDecision;
-                // Persist the approval decision
-                const approval = await this.store.getApproval(runId, approvalId);
-                if (approval && approval.status === "pending") {
-                    approval.status = approved ? "approved" : "rejected";
-                    approval.resolvedAt = Date.now();
-                    await this.store.saveApproval(approval);
-                    await this.emitRunEvent(runId, "approval_resolved", {
-                        approvalId,
-                        approved,
-                        reason,
-                    });
-                }
+                const approval = await this.getPendingApprovalForResume(run, approvalId);
+                approval.status = approved ? "approved" : "rejected";
+                approval.resolvedAt = Date.now();
+                await this.store.saveApproval(approval);
+                await this.emitRunEvent(runId, "approval_resolved", {
+                    approvalId,
+                    approved,
+                    reason,
+                });
                 // Transition back to running and resolve the suspended Engine
                 await this.transition(run, "queued");
                 await this.transition(run, "running");
@@ -158,7 +165,7 @@ export class RunManager {
                 handle.resolveApproval(approved, reason);
                 return;
             }
-            if (run.status === "waiting_input" && input?.userInput) {
+            if (run.status === "waiting_input" && hasOwnString(input, "userInput")) {
                 await this.transition(run, "queued");
                 await this.transition(run, "running");
                 await this.emitRunEvent(runId, "run_resumed", { userInput: input.userInput });
@@ -177,17 +184,15 @@ export class RunManager {
         // Re-queue the run for a fresh execution attempt
         if (input?.approvalDecision) {
             const { approvalId, approved, reason } = input.approvalDecision;
-            const approval = await this.store.getApproval(runId, approvalId);
-            if (approval && approval.status === "pending") {
-                approval.status = approved ? "approved" : "rejected";
-                approval.resolvedAt = Date.now();
-                await this.store.saveApproval(approval);
-                await this.emitRunEvent(runId, "approval_resolved", {
-                    approvalId,
-                    approved,
-                    reason,
-                });
-            }
+            const approval = await this.getPendingApprovalForResume(run, approvalId);
+            approval.status = approved ? "approved" : "rejected";
+            approval.resolvedAt = Date.now();
+            await this.store.saveApproval(approval);
+            await this.emitRunEvent(runId, "approval_resolved", {
+                approvalId,
+                approved,
+                reason,
+            });
         }
         await this.transition(run, "queued");
         await this.emitRunEvent(runId, "run_resumed", {
@@ -197,6 +202,19 @@ export class RunManager {
     }
     // ─── Cancel ────────────────────────────────────────────────────
     async cancel(runId, reason) {
+        assertSafeRunId(runId);
+        if (this.resolvingRuns.has(runId)) {
+            throw new Error(`Cannot cancel run ${runId}: another resume/cancel is already in progress`);
+        }
+        this.resolvingRuns.add(runId);
+        try {
+            await this.cancelInner(runId, reason);
+        }
+        finally {
+            this.resolvingRuns.delete(runId);
+        }
+    }
+    async cancelInner(runId, reason) {
         const run = await this.getOrThrow(runId);
         if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
             throw new Error(`Cannot cancel run ${runId}: already in terminal state ${run.status}`);
@@ -225,16 +243,19 @@ export class RunManager {
     }
     // ─── Query ─────────────────────────────────────────────────────
     async get(runId) {
+        assertSafeRunId(runId);
         return this.store.get(runId);
     }
     async list(query) {
         return this.store.list(query);
     }
     async getEvents(runId) {
+        assertSafeRunId(runId);
         return this.store.listEvents(runId);
     }
     // ─── Attach (live stream) ──────────────────────────────────────
     attach(runId, cb) {
+        assertSafeRunId(runId);
         if (!this.subscribers.has(runId)) {
             this.subscribers.set(runId, new Set());
         }
@@ -326,6 +347,7 @@ export class RunManager {
     }
     // ─── Internal: Execute a run ───────────────────────────────────
     async executeRun(runId) {
+        assertSafeRunId(runId);
         const run = await this.getOrThrow(runId);
         // Acquire run lock — prevents concurrent execution by multiple workers
         const lockResult = await this.lock.acquire(runId);
@@ -657,7 +679,25 @@ export class RunManager {
         }
     }
     // ─── Helpers ───────────────────────────────────────────────────
+    async getPendingApprovalForResume(run, approvalId) {
+        assertSafeRunFileId(approvalId, "approval id");
+        if (run.latestApprovalId !== approvalId) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} is not the latest pending approval`);
+        }
+        const approval = await this.store.getApproval(run.runId, approvalId);
+        if (!approval) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} was not found`);
+        }
+        if (approval.runId !== run.runId || approval.approvalId !== approvalId) {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} does not match this run`);
+        }
+        if (approval.status !== "pending") {
+            throw new Error(`Cannot resume run ${run.runId}: approval ${approvalId} is ${approval.status}, not pending`);
+        }
+        return approval;
+    }
     async getOrThrow(runId) {
+        assertSafeRunId(runId);
         const run = await this.store.get(runId);
         if (!run)
             throw new Error(`Run not found: ${runId}`);

package/dist/run/ids.d.ts

@@ -0,0 +1,2 @@
+export declare function assertSafeRunId(runId: unknown): asserts runId is string;
+export declare function assertSafeRunFileId(value: unknown, label: string): asserts value is string;

package/dist/run/ids.js

@@ -0,0 +1,23 @@
+function assertSafeRunSegment(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`invalid ${label}: must be a non-empty string`);
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        throw new Error(`invalid ${label}: contains path separator: ${value}`);
+    }
+    if (value === "." || value === ".." || value.includes("..")) {
+        throw new Error(`invalid ${label}: contains parent-dir token: ${value}`);
+    }
+    if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+        throw new Error(`invalid ${label}: unexpected characters: ${value}`);
+    }
+    if (value.length > 128) {
+        throw new Error(`invalid ${label}: too long (max 128 chars)`);
+    }
+}
+export function assertSafeRunId(runId) {
+    assertSafeRunSegment(runId, "run id");
+}
+export function assertSafeRunFileId(value, label) {
+    assertSafeRunSegment(value, label);
+}

package/dist/session/session-manager.d.ts

@@ -1,12 +1,25 @@
 /**
  * Session lifecycle manager.
  */
-import type { SessionState } from "../types.js";
+import type { SessionState, SessionWorkspace } from "../types.js";
 import { Transcript } from "./transcript.js";
 export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+export type SessionWorkspaceResumeResolution = {
+    ok: true;
+    cwd: string;
+    workspace: SessionWorkspace;
+    message?: string;
+    reason?: "main" | "worktree" | "legacy" | "worktree_missing_branch_gone";
+} | {
+    ok: false;
+    cwd: string;
+    workspace: SessionWorkspace;
+    message: string;
+    reason: "worktree_missing_branch_exists";
+};
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -57,6 +70,27 @@ export declare class SessionManager {
      * caller treats "no recoverable cwd" the same as "not given".
      */
     readCwd(sessionId: string): string | undefined;
+    /**
+     * Disk-only workspace pointer reader. Legacy sessions written before
+     * `workspace` existed are treated as main-workspace sessions rooted at
+     * `state.cwd`; the read is intentionally non-mutating.
+     */
+    getSessionWorkspace(sessionId: string): SessionWorkspace | undefined;
+    /**
+     * Persist the current session workspace pointer without changing legacy
+     * `cwd`. P1 will teach ToolContext to resolve cwd from this field; for P0 it
+     * is a safety pointer and resume breadcrumb.
+     */
+    setSessionWorkspace(sessionId: string, workspace: SessionWorkspace): void;
+    recordWorkspaceHandoff(sessionId: string, from: SessionWorkspace | undefined, to: SessionWorkspace): void;
+    /**
+     * Resolve the cwd a resumed session must run in from its persisted workspace
+     * pointer. A missing worktree directory is never silently treated as the main
+     * repo: if the branch still exists callers get a blocking recreate message;
+     * if the branch is gone the workspace pointer is reset to main and a warning
+     * message is returned for the host to surface before continuing.
+     */
+    resolveSessionWorkspaceForResume(sessionId: string): SessionWorkspaceResumeResolution;
     /**
      * Cheap "does this session have a persisted goal?" probe — reads only
      * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY