@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/protocol/server.js

@@ -24,6 +24,7 @@ import { backgroundJobRegistry } from "../tool-system/builtin/background-jobs.js
 import { listBackgroundWorkForUI } from "../tool-system/builtin/background-work.js";
 import { logger } from "../logging/logger.js";
 import { nanoid } from "nanoid";
+import { SessionManager } from "../session/session-manager.js";
 import { redactLlmConfig, maskSecretValue } from "./redact.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
 const COMPACT_STREAM_STRATEGIES = new Set([
@@ -48,6 +49,15 @@ export class AgentServer {
     settingsReader;
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     readActiveGoalFromDisk;
+    workspaceBridgeEnabled;
+    /**
+     * Last per-session EngineConfigSlice supplied by agent/run. Kept even after
+     * idle eviction so background-completion wakeups can rebuild the ChatSession
+     * with the same cwd/permission/trust inputs before draining the queue.
+     */
+    lastSliceBySession = new Map();
+    /** Lazy disk reader for cold wakeup rehydrate when this process lacks a slice. */
+    diskSessionReader = null;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -73,6 +83,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
@@ -85,6 +103,7 @@ export class AgentServer {
         this.legacyEngine = options.engine ?? null;
         this.settingsReader = options.settingsReader ?? null;
         this.readActiveGoalFromDisk = options.readActiveGoalFromDisk ?? null;
+        this.workspaceBridgeEnabled = options.workspaceBridge === true;
         if (!this.chatManager && !this.legacyEngine) {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
@@ -169,7 +188,7 @@ export class AgentServer {
     maybeWakeIdleSession(sessionId) {
         if (!this.chatManager)
             return;
-        const session = this.chatManager.get(sessionId);
+        const session = this.chatManager.get(sessionId) ?? this.rehydrateSessionForWake(sessionId);
         if (!session || session.isBusy())
             return;
         // Headless / automation runs are one-shot: the caller takes result.text and
@@ -229,6 +248,76 @@ export class AgentServer {
             this.maybeWakeIdleSession(sessionId);
         });
     }
+    rehydrateSessionForWake(sessionId) {
+        if (!this.chatManager)
+            return null;
+        try {
+            const pending = notificationQueue.getSnapshot(sessionId);
+            if (pending.length === 0) {
+                logger.debug("bg_wakeup.rehydrate_skipped_no_pending", { sessionId });
+                return null;
+            }
+            const slice = this.sliceForWakeRehydrate(sessionId);
+            if (!slice) {
+                logger.warn("bg_wakeup.rehydrate_skipped_missing_disk_session", {
+                    sessionId,
+                    pendingCount: pending.length,
+                    reason: "state_json_cwd_missing",
+                });
+                return null;
+            }
+            if (!this.chatManager.sessionExistsOnDisk(sessionId, slice)) {
+                logger.warn("bg_wakeup.rehydrate_skipped_missing_disk_session", {
+                    sessionId,
+                    pendingCount: pending.length,
+                });
+                return null;
+            }
+            const session = this.chatManager.getOrCreate(sessionId, slice);
+            this.wireInteractiveSession(session, sessionId);
+            logger.debug("bg_wakeup.rehydrated_session", {
+                sessionId,
+                pendingCount: pending.length,
+                source: this.lastSliceBySession.has(sessionId) ? "last_slice" : "state_json",
+            });
+            return session;
+        }
+        catch (err) {
+            logger.warn("bg_wakeup.rehydrate_failed", {
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }
+    sliceForWakeRehydrate(sessionId) {
+        const cached = this.lastSliceBySession.get(sessionId);
+        if (cached)
+            return { ...cached };
+        if (!this.diskSessionReader)
+            this.diskSessionReader = new SessionManager();
+        const cwd = this.diskSessionReader.readCwd(sessionId);
+        if (!cwd)
+            return null;
+        return {
+            permissionMode: "default",
+            projectTrusted: false,
+            cwd,
+        };
+    }
+    rememberSessionSlice(sessionId, slice) {
+        this.lastSliceBySession.set(sessionId, { ...slice });
+    }
+    wireInteractiveSession(session, sid) {
+        if (session.engine.isHeadless())
+            return;
+        session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
+        session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
+        session.engine.setInjectCredential((credentialId, credentialScope) => this.requestCredentialInjectForSession(session, sid, credentialId, credentialScope));
+        if (this.workspaceBridgeEnabled && typeof session.engine.setWorkspaceBridge === "function") {
+            session.engine.setWorkspaceBridge(this.makeWorkspaceBridge(session, sid));
+        }
+    }
     // ─── Request Dispatch ───────────────────────────────────────────
     async handleRequest(req) {
         switch (req.method) {
@@ -259,6 +348,9 @@ export class AgentServer {
             case Methods.CloseSession:
                 this.handleCloseSession(req);
                 break;
+            case Methods.ReleaseWorkspace:
+                this.handleReleaseWorkspace(req);
+                break;
             case Methods.GoalExtend:
                 this.handleGoalExtend(req);
                 break;
@@ -298,28 +390,39 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "task is required"));
             return;
         }
+        const sessionConfig = {
+            permissionMode: params.permissionMode,
+            cwd: params.cwd,
+            projectTrusted: params.projectTrusted,
+            goal: typeof params.goal === "string" || (params.goal != null && typeof params.goal === "object")
+                ? params.goal
+                : undefined,
+        };
+        if (params.requireExisting === true && !cm.get(params.sessionId)) {
+            let existsOnDisk = false;
+            try {
+                existsOnDisk = cm.sessionExistsOnDisk(params.sessionId, sessionConfig);
+            }
+            catch (err) {
+                const code = err.code ?? ErrorCodes.InternalError;
+                this.transport.send(createErrorResponse(req.id, code, err.message));
+                return;
+            }
+            if (!existsOnDisk) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `session ${params.sessionId} does not exist`));
+                return;
+            }
+        }
         let session;
         try {
-            session = cm.getOrCreate(params.sessionId, {
-                permissionMode: params.permissionMode,
-                cwd: params.cwd,
-                projectTrusted: params.projectTrusted,
-            });
+            session = cm.getOrCreate(params.sessionId, sessionConfig);
         }
         catch (err) {
             const code = err.code ?? ErrorCodes.InternalError;
             this.transport.send(createErrorResponse(req.id, code, err.message));
             return;
         }
-        // `requireExisting`: reject if the target session isn't on disk rather than
-        // running the prompt against a freshly-created blank session. A cron
-        // "continue this conversation" job whose session the user deleted must fail
-        // loudly here (SessionNotFound) so the scheduler can auto-disable it,
-        // instead of silently executing with no transcript/goal/context.
-        if (params.requireExisting === true && !session.engine.sessionExistsOnDisk(params.sessionId)) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `session ${params.sessionId} does not exist`));
-            return;
-        }
+        this.rememberSessionSlice(params.sessionId, sessionConfig);
         if (params.model !== undefined) {
             if (typeof params.model !== "string" || params.model.length === 0) {
                 this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "model must be a non-empty string"));
@@ -337,29 +440,14 @@ export class AgentServer {
             session.engine.setPlanMode(params.planMode);
         }
         const sid = params.sessionId;
-        // Wire AskUserQuestion for this interactive session. The chatManager path
-        // builds a fresh per-session Engine via engineFactory, which (unlike the
-        // legacy single-engine path) never had askUser wired — so AskUserQuestion
-        // always fell into its "not available in headless mode" branch in normal
-        // chat (and in a resumed automation session). Route it to the client with
-        // this session's id so the renderer attributes the question to the right
-        // tab, resolving via the session's own pendingApprovals. Skip genuinely
-        // headless engines (no human to answer).
-        if (!session.engine.isHeadless()) {
-            session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
-            // Browser automation bridge: each method routes a browser action to the
-            // client (Electron main drives the webview via CDP) over the SAME
-            // request/response channel as askUser (pendingApprovals + requestId).
-            // Browser actions still keep their own bounded timeout; AskUserQuestion
-            // waits for a real answer or Stop/cancel.
-            session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
-            // Cookie→browser injection (InjectCredential tool): same cross-process
-            // channel; main restores the cookie jar into the built-in browser.
-            session.engine.setInjectCredential((credentialId) => this.requestCredentialInjectForSession(session, sid, credentialId));
-        }
+        // Wire AskUserQuestion and host bridges for this interactive session. The
+        // chatManager path builds a fresh per-session Engine via engineFactory, so
+        // these host callbacks must be installed after every create/recreate.
+        this.wireInteractiveSession(session, sid);
         try {
             const result = await session.enqueueTurn(params.task, {
                 cwd: params.cwd,
+                attachments: Array.isArray(params.attachments) ? params.attachments : undefined,
                 goal: typeof params.goal === "string" ||
                     (params.goal != null && typeof params.goal === "object")
                     ? params.goal
@@ -467,9 +555,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: "",
@@ -623,6 +709,12 @@ export class AgentServer {
             : params.sessionId
                 ? (this.legacyEngine.clearGoal(params.sessionId) ?? false)
                 : false;
+        if (cleared && typeof params.sessionId === "string" && params.sessionId.length > 0) {
+            this.notify(Methods.StreamEvent, {
+                sessionId: params.sessionId,
+                event: { type: "goal_cleared" },
+            });
+        }
         this.transport.send(createResponse(req.id, { ok: true, cleared }));
     }
     /**
@@ -720,7 +812,8 @@ export class AgentServer {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
             return;
         }
-        const items = listBackgroundWorkForUI(sessionId);
+        const scope = params.scope === "all" ? "all" : "session";
+        const items = listBackgroundWorkForUI(sessionId, { scope });
         this.transport.send(createResponse(req.id, { items }));
     }
     // ─── CloseSession ───────────────────────────────────────────────
@@ -747,6 +840,28 @@ export class AgentServer {
         backgroundJobRegistry.dropForSession(params.sessionId);
         this.transport.send(createResponse(req.id, { ok: true }));
     }
+    // ─── ReleaseWorkspace ──────────────────────────────────────────
+    handleReleaseWorkspace(req) {
+        const params = (req.params ?? {});
+        if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
+            this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "sessionId is required"));
+            return;
+        }
+        if (this.chatManager) {
+            const session = this.chatManager.get(params.sessionId);
+            if (!session) {
+                this.transport.send(createResponse(req.id, { ok: true, workspace: null }));
+                return;
+            }
+            const engine = session.engine;
+            const workspace = engine.releaseSessionWorkspace?.(params.sessionId) ?? null;
+            this.transport.send(createResponse(req.id, { ok: true, workspace }));
+            return;
+        }
+        const engine = this.legacyEngine;
+        const workspace = engine?.releaseSessionWorkspace?.(params.sessionId) ?? null;
+        this.transport.send(createResponse(req.id, { ok: true, workspace }));
+    }
     // ─── Configure ──────────────────────────────────────────────────
     handleConfigure(req) {
         const params = (req.params ?? {});
@@ -1239,8 +1354,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 +1390,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 } }));
@@ -1380,7 +1493,7 @@ export class AgentServer {
             return;
         }
         try {
-            const result = engine.enqueueSteer(params.sessionId, params.text, params.id, params.clientMessageId);
+            const result = engine.enqueueSteer(params.sessionId, params.text, params.id, params.clientMessageId, params.attachments);
             this.transport.send(createResponse(req.id, { ok: true, ...result }));
         }
         catch (err) {
@@ -1461,7 +1574,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 +1602,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;
+            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);
+            }
         });
     }
     /**
@@ -1568,7 +1714,7 @@ export class AgentServer {
      * calls restoreCookiesToBrowser and replies with a JSON result string we
      * parse into { ok, count?, error? }. Degrades to ok:false on timeout/malformed.
      */
-    requestCredentialInjectForSession(session, sessionId, credentialId) {
+    requestCredentialInjectForSession(session, sessionId, credentialId, credentialScope = "full") {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
             session.pendingApprovals.set(requestId, (decision) => {
@@ -1605,13 +1751,67 @@ export class AgentServer {
                 requestId,
                 request: {
                     toolName: "__credential_action__",
-                    args: { action: "injectCookie", credentialId },
+                    args: { action: "injectCookie", credentialId, credentialScope },
                     description: `credential:inject:${credentialId}`,
                     riskLevel: "low",
                 },
             });
         });
     }
+    makeWorkspaceBridge(session, sessionId) {
+        return {
+            switch: (target) => this.requestWorkspaceSwitchForSession(session, sessionId, target),
+        };
+    }
+    requestWorkspaceSwitchForSession(session, sessionId, target) {
+        return new Promise((resolve, reject) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                let raw;
+                if (decision && typeof decision === "object" && "approved" in decision) {
+                    const r = decision;
+                    raw = r.approved ? r.answer : undefined;
+                }
+                else if (typeof decision === "string") {
+                    raw = decision;
+                }
+                if (raw === undefined) {
+                    reject(new Error("workspace switch declined or unavailable"));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(raw);
+                    if ("ok" in parsed && parsed.ok === false) {
+                        reject(new Error(parsed.error ?? "workspace switch failed"));
+                        return;
+                    }
+                    resolve(parsed);
+                }
+                catch {
+                    reject(new Error("malformed workspace switch result"));
+                }
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    session.pendingApprovals.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    reject(new Error("workspace switch timed out"));
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            this.notify(Methods.ApprovalRequest, {
+                sessionId,
+                requestId,
+                request: {
+                    toolName: "__workspace_action__",
+                    args: { action: "switch", target },
+                    description: `workspace:switch:${target}`,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
     /**
      * Ask the client to answer a question from the agent (legacy single-engine
      * path). This intentionally has no wall-clock timeout; Stop/cancel drains

package/dist/protocol/types.d.ts

@@ -47,10 +47,41 @@ export declare const ErrorCodes: {
      */
     readonly Cancelled: -32005;
 };
+export type InputAttachmentKind = "image" | "file" | "directory";
+export type InputAttachmentOrigin = "paste" | "os-drop" | "file-panel" | "picker" | "mention" | "generated" | "tool";
+export interface InputAttachmentMeta {
+    id: string;
+    sessionId: string;
+    kind: InputAttachmentKind;
+    origin: InputAttachmentOrigin;
+    path: string;
+    absPath: string;
+    relPath?: string;
+    mime?: string;
+    size: number;
+    sha256: string;
+    originalName?: string;
+    createdAt: number;
+    sourcePath?: string;
+    width?: number;
+    height?: number;
+    vision?: {
+        include: boolean;
+        mediaPath?: string;
+        detail?: "low" | "standard" | "high";
+    };
+    directory?: {
+        treePath?: string;
+        truncated?: boolean;
+        entryCount?: number;
+    };
+}
 /** Start an agent run with a user task. */
 export interface RunParams {
     sessionId: string;
     task: string;
+    /** Structured input attachments. Legacy `<codeshell-image>` task blocks remain supported. */
+    attachments?: InputAttachmentMeta[];
     /** Stable id for the user's submit intent; duplicate ids are idempotent. */
     clientMessageId?: string;
     /**
@@ -123,6 +154,10 @@ export interface CancelParams {
 export interface CloseSessionParams {
     sessionId: string;
 }
+/** Reset a live session's workspace binding back to main. */
+export interface ReleaseWorkspaceParams {
+    sessionId: string;
+}
 /** Inject context into a session transcript. */
 export interface InjectParams {
     sessionId: string;
@@ -132,6 +167,8 @@ export interface InjectParams {
 export interface SteerParams {
     sessionId: string;
     text: string;
+    /** Structured input attachments that should ride with this queued steer. */
+    attachments?: InputAttachmentMeta[];
     /** Stable host-side id for this queued draft. Rides through to the
      *  steer_injected event and is the handle Unsteer uses to revoke it. */
     id?: string;
@@ -260,6 +297,12 @@ export interface ApprovalRequestNotification {
     requestId: string;
     request: ApprovalRequest;
 }
+/** Server tells clients a pending approval/ask has been resolved elsewhere. */
+export interface ApprovalResolvedNotification {
+    /** Originating engine session when known. */
+    sessionId?: string;
+    requestId: string;
+}
 /** Server status changed. */
 export interface StatusNotification {
     status: "ready" | "running" | "error" | "shutdown";
@@ -279,6 +322,8 @@ export declare const Methods: {
     readonly Unsteer: "agent/unsteer";
     /** Close (destroy) a session. */
     readonly CloseSession: "agent/closeSession";
+    /** Reset a session's workspace binding to main without closing it. */
+    readonly ReleaseWorkspace: "agent/releaseWorkspace";
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     readonly GoalExtend: "agent/goalExtend";
     /** Clear a session's persisted active goal (CC /goal clear). */
@@ -293,6 +338,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

@@ -41,6 +41,8 @@ export const Methods = {
     Unsteer: "agent/unsteer",
     /** Close (destroy) a session. */
     CloseSession: "agent/closeSession",
+    /** Reset a session's workspace binding to main without closing it. */
+    ReleaseWorkspace: "agent/releaseWorkspace",
     /** Extend a running goal's turn/budget ceilings mid-run (TODO 3.1). */
     GoalExtend: "agent/goalExtend",
     /** Clear a session's persisted active goal (CC /goal clear). */
@@ -56,6 +58,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");
     }
 }