@cjhyy/code-shell-core 0.9.2 → 0.9.3

package/dist/cli/agent-server-stdio.js

@@ -30,10 +30,11 @@
  * bootstrap is invisible to them.
  */
 import { join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
 import { Engine } from "../engine/engine.js";
 import { EngineRuntime } from "../engine/runtime.js";
 import { ChatSessionManager } from "../protocol/chat-session-manager.js";
-import { SessionManager } from "../session/session-manager.js";
+import { assertSafeSessionId, SessionManager, sessionsRoot } from "../session/session-manager.js";
 import { validateSettings } from "../settings/schema.js";
 import { AgentServer } from "../protocol/server.js";
 import { StdioTransport } from "../protocol/transport.js";
@@ -122,6 +123,29 @@ const composition = compileComposition({ modules: await loadConfiguredAgentModul
 // byte-for-byte.
 const dataRoot = process.env.CODE_SHELL_DATA_ROOT?.trim() || undefined;
 const dataSessionsDir = dataRoot ? join(dataRoot, "sessions") : undefined;
+const notificationSessionsDir = dataSessionsDir ?? sessionsRoot();
+const notificationPersistence = {
+    fileForSession(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            return join(notificationSessionsDir, sessionId, "pending-notifications.json");
+        }
+        catch {
+            return null;
+        }
+    },
+    listSessionIds() {
+        try {
+            return readdirSync(notificationSessionsDir, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() &&
+                existsSync(join(notificationSessionsDir, entry.name, "pending-notifications.json")))
+                .map((entry) => entry.name);
+        }
+        catch {
+            return [];
+        }
+    },
+};
 // Load settings once to derive llm config for the seed engine.
 // Desktop is a host application: read the full disk hierarchy (incl. the
 // user's ~/.code-shell). The SDK default 'project' would skip user config.
@@ -364,6 +388,7 @@ const agentServer = new AgentServer({
     // Cold background-wakeup rehydrate must read the same sessions store the
     // engines write when the data root is relocated (undefined → default root).
     sessionDiskRoot: dataSessionsDir,
+    notificationPersistence,
     // Config hot-reload (layer 2) reads disk through the SAME closure the
     // engineFactory uses for new sessions, so a reloaded running session and a
     // newly-created session converge on identical disk config (no divergence).

package/dist/cli/agent-server-tcp.js

@@ -34,11 +34,39 @@ import { startAutomation } from "../automation/index.js";
 import { CronStore, defaultCronStorePath } from "../automation/store.js";
 import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.js";
 import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
 import { getApprovalRouter } from "../tool-system/permission.js";
-import { SessionManager } from "../session/session-manager.js";
+import { assertSafeSessionId, SessionManager, sessionsRoot } from "../session/session-manager.js";
+import { notificationQueue } from "../tool-system/builtin/agent-notifications.js";
 const cwd = process.env.AGENT_CWD ?? process.cwd();
 const port = Number(process.env.AGENT_TCP_PORT ?? "4321");
 const host = process.env.AGENT_TCP_HOST ?? "127.0.0.1";
+const dataRoot = process.env.CODE_SHELL_DATA_ROOT?.trim() || undefined;
+const dataSessionsDir = dataRoot ? join(dataRoot, "sessions") : undefined;
+const notificationSessionsDir = dataSessionsDir ?? sessionsRoot();
+notificationQueue.attachPersistence({
+    fileForSession(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+            return join(notificationSessionsDir, sessionId, "pending-notifications.json");
+        }
+        catch {
+            return null;
+        }
+    },
+    listSessionIds() {
+        try {
+            return readdirSync(notificationSessionsDir, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() &&
+                existsSync(join(notificationSessionsDir, entry.name, "pending-notifications.json")))
+                .map((entry) => entry.name);
+        }
+        catch {
+            return [];
+        }
+    },
+});
 const settingsManager = new SettingsManager(cwd, "full");
 // Read once at startup and reuse for every session (see engineFactory below).
 // This is intentional for the TCP host: it's a headless long-running server,
@@ -53,7 +81,12 @@ if (!seedLlm) {
 }
 const llmConfig = seedLlm;
 // ── Shared runtime (same bootstrap as stdio) ─────────────────────
-const seedEngine = new Engine({ llm: llmConfig, cwd, settingsScope: "full" });
+const seedEngine = new Engine({
+    llm: llmConfig,
+    cwd,
+    settingsScope: "full",
+    sessionStorageDir: dataSessionsDir,
+});
 const modelPool = seedEngine.getModelPool();
 const toolRegistry = seedEngine.getRuntimeToolRegistry();
 const resolvedLlmConfig = seedEngine.getConfig().llm;
@@ -92,11 +125,13 @@ const chatManager = new ChatSessionManager({
             ...personalizationFrom(settings.agent),
             maxTurns: slice.maxTurns,
             maxContextTokens: slice.maxContextTokens,
+            sessionStorageDir: slice.sessionStorageDir ?? dataSessionsDir,
             ...(slice.cwd ? { cwd: slice.cwd } : {}),
         });
     },
     maxSessions: 16,
     idleTtlMs: 30 * 60 * 1000,
+    ...(dataRoot ? { dataRoot } : {}),
 });
 chatManager.startIdleSweeper();
 // ── Automation (same module the desktop loads) ──────────────────
@@ -109,23 +144,38 @@ const automationRunManager = createRunManager({
     approvalBackend: new HeadlessApprovalBackend("approve-read-only"),
 });
 const automation = startAutomation({
-    store: new CronStore(defaultCronStorePath()),
+    store: new CronStore(defaultCronStorePath(dataRoot)),
     runManager: automationRunManager,
 });
 // ── Serve over TCP ──────────────────────────────────────────────
 // One AgentServer per accepted connection, all sharing the same chatManager.
 const servers = new Set();
-const goalDiskManager = new SessionManager();
-listenTcp({ port, host }, (transport, socket) => {
-    const server = new AgentServer({
+const goalDiskManager = new SessionManager(dataSessionsDir);
+function createTcpAgentServer(transport, connectionId, ownsBackgroundWakeups) {
+    return new AgentServer({
         chatManager,
         transport,
-        connectionId: randomUUID(),
+        connectionId,
         approvalRouter: getApprovalRouter(),
+        sessionDiskRoot: dataSessionsDir,
+        ownsBackgroundWakeups,
         readActiveGoalFromDisk: (sessionId) => goalDiskManager.readActiveGoal(sessionId),
         updateActiveGoalOnDisk: (sessionId, patch) => goalDiskManager.updateActiveGoal(sessionId, patch)?.goal,
         clearActiveGoalOnDisk: (sessionId, expected) => goalDiskManager.clearActiveGoal(sessionId, expected),
     });
+}
+// Own restoration for the whole TCP process, not for the first client. This
+// wakes pending chats immediately after a headless restart even if nobody has
+// connected a UI yet. Per-connection servers still forward live observations
+// but do not race this owner for mailbox consumption.
+const backgroundWakeTransport = {
+    send() { },
+    onMessage() { },
+    close() { },
+};
+const backgroundWakeServer = createTcpAgentServer(backgroundWakeTransport, "tcp-background-wakeup", true);
+listenTcp({ port, host }, (transport, socket) => {
+    const server = createTcpAgentServer(transport, randomUUID(), false);
     servers.add(server);
     socket.once("close", () => {
         server.disconnect();
@@ -138,6 +188,7 @@ listenTcp({ port, host }, (transport, socket) => {
         automation.stop();
         for (const s of servers)
             s.close();
+        backgroundWakeServer.close();
         void listener.close().then(() => process.exit(0));
     };
     process.on("SIGTERM", shutdown);

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.9.2";
+export declare const VERSION = "0.9.3";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionProjectBinding, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.9.2";
+export const VERSION = "0.9.3";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Composition (AgentModule / ResolvedComposition) ─────────────

package/dist/onboarding.js

@@ -4,7 +4,7 @@
  * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
  * pure(-ish) helpers it consumes, so there's a single input stack.
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { userHome } from "./settings/manager.js";
 import { getOpenRouterModels } from "./data/openrouter-models.js";
@@ -14,6 +14,7 @@ import { KNOWN_MAX_OUTPUT, KNOWN_CONTEXT_WINDOWS, OPENROUTER_VENDORS, PROVIDERS,
 export { PROVIDERS };
 import { sanitizeApiKey } from "./llm/api-key-sanitize.js";
 import { getMergedCatalog } from "./model-catalog/index.js";
+import { mutateJsonFile } from "./utils/file-mutex.js";
 // ProviderDef 类型 + PROVIDERS 目录已外移到 data/model-metadata.json
 // (loader: data/model-metadata.ts),并在文件顶部 re-export。core 只读目录数据。
 // ─── Dynamic model list (OpenRouter snapshot) ────────────────────
@@ -115,7 +116,7 @@ export async function validateApiKey(baseUrl, apiKey) {
                 headers: { Authorization: `Bearer ${apiKey}` },
                 signal: AbortSignal.timeout(10_000),
             });
-            const data = await res.json();
+            const data = (await res.json());
             return !data.error;
         }
         const url = baseUrl.replace(/\/$/, "") + "/models";
@@ -162,6 +163,8 @@ export function hasApiKey() {
     // Reads ~/.code-shell/ only — ~/.claude/ compat was dropped because Claude
     // Code's settings schema diverges and merging broke boot.
     const p = join(userHome(), ".code-shell", "settings.json");
+    // This is only a boot-time hint. A slightly stale read can show onboarding
+    // once; all mutations below still re-read under the shared file lock.
     if (existsSync(p)) {
         try {
             const data = JSON.parse(readFileSync(p, "utf-8"));
@@ -170,7 +173,9 @@ export function hasApiKey() {
             if (Array.isArray(data?.modelConnections) && data.modelConnections.length > 0)
                 return true;
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
     }
     return false;
 }
@@ -297,50 +302,68 @@ export function appendOnboardingResult(opts) {
     const tag = opts.tag ?? "text";
     const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
-    mkdirSync(dir, { recursive: true });
-    let existing = {};
-    if (existsSync(file)) {
-        try {
-            existing = JSON.parse(readFileSync(file, "utf-8"));
-        }
-        catch { /* corrupt → replace */ }
-    }
-    const creds = Array.isArray(existing.credentials)
-        ? [...existing.credentials] : [];
-    const conns = Array.isArray(existing.modelConnections)
-        ? [...existing.modelConnections] : [];
-    for (const m of opts.models) {
-        const catalogId = catalogIdForKind(m.kind);
-        const credId = `${m.instanceId}-key`;
-        if (!creds.some((c) => c?.id === credId)) {
-            creds.push({ id: credId, catalogId, apiKey: m.apiKey, baseUrl: m.baseUrl });
-        }
-        if (!conns.some((c) => c?.id === m.instanceId)) {
-            conns.push({
-                id: m.instanceId, catalogId, tag, model: m.model, credentialId: credId,
-                ...(m.baseUrl ? { baseUrl: m.baseUrl } : {}),
-            });
-        }
-    }
-    const existingDefaults = (typeof existing.defaults === "object" && existing.defaults)
-        ? existing.defaults : {};
-    const updated = {
-        ...existing,
-        credentials: creds,
-        modelConnections: conns,
-        defaults: { ...existingDefaults, [tag]: opts.activeId },
-    };
-    // Atomic write: tmp file in the same dir, then rename (atomic on POSIX).
-    // mode 0o600 — settings.json holds plaintext API keys, must be owner-only.
-    const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
-    try {
-        renameSync(tmp, file);
-    }
-    catch {
-        // Fallback: best-effort direct write if rename fails (e.g. cross-device),
-        // then remove the orphaned temp file the failed rename left behind.
-        writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
-        rmSync(tmp, { force: true });
-    }
+    mutateJsonFile(file, {
+        parse: (raw) => {
+            if (raw === undefined)
+                return {};
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                throw new Error("settings.json is unreadable; onboarding did not overwrite it", {
+                    cause: error,
+                });
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("settings.json must contain a JSON object");
+            }
+            return parsed;
+        },
+        serialize: (value) => `${JSON.stringify(value, null, 2)}\n`,
+        mutation: (existing) => {
+            const creds = Array.isArray(existing.credentials)
+                ? [...existing.credentials]
+                : [];
+            const conns = Array.isArray(existing.modelConnections)
+                ? [...existing.modelConnections]
+                : [];
+            for (const model of opts.models) {
+                const catalogId = catalogIdForKind(model.kind);
+                const credentialId = `${model.instanceId}-key`;
+                if (!creds.some((credential) => credential?.id === credentialId)) {
+                    creds.push({
+                        id: credentialId,
+                        catalogId,
+                        apiKey: model.apiKey,
+                        baseUrl: model.baseUrl,
+                    });
+                }
+                if (!conns.some((connection) => connection?.id === model.instanceId)) {
+                    conns.push({
+                        id: model.instanceId,
+                        catalogId,
+                        tag,
+                        model: model.model,
+                        credentialId,
+                        ...(model.baseUrl ? { baseUrl: model.baseUrl } : {}),
+                    });
+                }
+            }
+            const existingDefaults = existing.defaults &&
+                typeof existing.defaults === "object" &&
+                !Array.isArray(existing.defaults)
+                ? existing.defaults
+                : {};
+            return {
+                value: {
+                    ...existing,
+                    credentials: creds,
+                    modelConnections: conns,
+                    defaults: { ...existingDefaults, [tag]: opts.activeId },
+                },
+            };
+        },
+        mode: 0o600,
+    });
 }

package/dist/protocol/background-result-wakeup.d.ts

@@ -1,4 +1,5 @@
 import type { StreamEvent } from "../types.js";
+import { type NotificationQueue } from "../tool-system/builtin/agent-notifications.js";
 import type { ApprovalRouter } from "../tool-system/permission.js";
 import type { ChatSession } from "./chat-session.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
@@ -8,11 +9,12 @@ interface BackgroundResultWakeOptions {
     rehydrate(sessionId: string): Promise<ChatSession | null>;
     approvalRouter: ApprovalRouter;
     onStream(event: StreamEvent): void;
+    notificationMailbox?: NotificationQueue;
 }
 /**
  * Drain pending background results into exactly one synthetic continuation.
  * Busy sessions are awaited so a completion cannot fall into the gap between
  * the notification bus callback and the interactive run-boundary re-check.
  */
-export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }: BackgroundResultWakeOptions): Promise<boolean>;
+export declare function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox, }: BackgroundResultWakeOptions): Promise<boolean>;
 export {};

package/dist/protocol/background-result-wakeup.js

@@ -5,7 +5,7 @@ import { buildNotificationMessage, notificationQueue, } from "../tool-system/bui
  * Busy sessions are awaited so a completion cannot fall into the gap between
  * the notification bus callback and the interactive run-boundary re-check.
  */
-export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, }) {
+export async function wakeSessionForBackgroundResults({ sessionId, manager, rehydrate, approvalRouter, onStream, notificationMailbox = notificationQueue, }) {
     if (!manager) {
         logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_chat_manager" });
         return false;
@@ -22,7 +22,7 @@ export async function wakeSessionForBackgroundResults({ sessionId, manager, rehy
     while (session.isBusy()) {
         logger.debug("bg_wakeup.waiting_for_idle", {
             sessionId,
-            pendingCount: notificationQueue.getSnapshot(sessionId).length,
+            pendingCount: notificationMailbox.getSnapshot(sessionId).length,
         });
         await session.settled;
         if (manager.isUnavailable(sessionId)) {
@@ -63,7 +63,7 @@ export async function wakeSessionForBackgroundResults({ sessionId, manager, rehy
         });
         return false;
     }
-    const pending = notificationQueue.drainAll(sessionId);
+    const pending = notificationMailbox.drainAll(sessionId);
     if (pending.length === 0) {
         logger.debug("bg_wakeup.skipped", { sessionId, reason: "no_pending_results" });
         return false;
@@ -77,7 +77,7 @@ export async function wakeSessionForBackgroundResults({ sessionId, manager, rehy
             approvalRouter,
         });
         if (result.turnCount === 0) {
-            const restored = notificationQueue.restoreResults(sessionId, pending);
+            const restored = notificationMailbox.restoreResults(sessionId, pending);
             logger.warn("bg_wakeup.turn_not_started", {
                 sessionId,
                 restored,
@@ -89,7 +89,7 @@ export async function wakeSessionForBackgroundResults({ sessionId, manager, rehy
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const restored = notificationQueue.restoreResults(sessionId, pending);
+        const restored = notificationMailbox.restoreResults(sessionId, pending);
         logger.warn("bg_wakeup.turn_failed", { sessionId, error: message, restored });
         // A setup failure can occur before the turn loop emits its own terminal
         // event. Emit an error so every renderer clears its busy state, but keep

package/dist/protocol/server.d.ts

@@ -17,6 +17,7 @@ import type { Transport } from "./transport.js";
 import type { Engine } from "../engine/engine.js";
 import type { ValidatedSettings } from "../settings/schema.js";
 import { type ApprovalRouter } from "../tool-system/permission.js";
+import { type NotificationQueue, type NotificationQueuePersistence } from "../tool-system/builtin/agent-notifications.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
 import type { ResolvedComposition } from "../composition/types.js";
 /**
@@ -106,6 +107,16 @@ export interface AgentServerOptions {
      * write.
      */
     sessionDiskRoot?: string;
+    /** Durable per-session result mailbox. Omitted keeps the in-memory behavior. */
+    notificationPersistence?: NotificationQueuePersistence;
+    /** Test/host seam; production uses the process singleton. */
+    notificationMailbox?: NotificationQueue;
+    /**
+     * Whether this server instance owns durable result restoration and idle
+     * wakeups. Defaults to true. Multi-connection hosts set one process-lifetime
+     * owner and leave connection servers as observation-only forwarders.
+     */
+    ownsBackgroundWakeups?: boolean;
     /** Shared owner router; injectable for hosts/tests, process singleton by default. */
     approvalRouter?: ApprovalRouter;
     /**
@@ -197,8 +208,10 @@ export declare class AgentServer {
      * itself outlives the server (it's a process-local singleton).
      */
     private bgAgentBusUnsubscribe;
+    private readonly ownsBackgroundWakeups;
     private readonly wakeupsInFlight;
     private readonly sessionWorkspaceRpc;
+    private readonly notificationMailbox;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —

package/dist/protocol/server.js

@@ -381,8 +381,10 @@ export class AgentServer {
      * itself outlives the server (it's a process-local singleton).
      */
     bgAgentBusUnsubscribe = null;
+    ownsBackgroundWakeups;
     wakeupsInFlight = new Set();
     sessionWorkspaceRpc;
+    notificationMailbox;
     /**
      * Effective session manager for the connection this server serves. Without
      * a resolveIdentity hook this is exactly the host-supplied manager —
@@ -407,6 +409,11 @@ export class AgentServer {
         return manager;
     }
     constructor(options) {
+        this.notificationMailbox = options.notificationMailbox ?? notificationQueue;
+        this.ownsBackgroundWakeups = options.ownsBackgroundWakeups !== false;
+        if (options.notificationPersistence) {
+            this.notificationMailbox.attachPersistence(options.notificationPersistence);
+        }
         this.baseChatManager = options.chatManager ?? null;
         this.resolveIdentity = options.resolveIdentity ?? null;
         this.sessionDiskRoot = options.sessionDiskRoot;
@@ -509,8 +516,9 @@ export class AgentServer {
                 // legacy UI event is only an observation path. A renderer transport
                 // failure after accepting the event must not strand the result in the
                 // queue, so schedule the wake from finally.
-                if (envelope.kind === "result")
+                if (this.ownsBackgroundWakeups && envelope.kind === "result") {
                     this.maybeWakeIdleSession(sessionId);
+                }
             }
             // Background work that finishes while the session is idle (a
             // run_in_background Bash like a download, a background sub-agent, or a
@@ -523,6 +531,14 @@ export class AgentServer {
             // continuation. A never-exiting dev server emits no completion, so it
             // never wakes anything (no task/service classification needed).
         });
+        // Results restored from disk are deliberately not republished on the
+        // observation bus: their required destination is the original chat. Feed
+        // them into the same guarded wake path as live completions instead.
+        if (this.ownsBackgroundWakeups) {
+            for (const sessionId of this.notificationMailbox.restorePersistedSessions()) {
+                this.maybeWakeIdleSession(sessionId);
+            }
+        }
         // Notify client we're ready
         this.notify(Methods.Status, { status: "ready" });
     }
@@ -549,13 +565,15 @@ export class AgentServer {
      * wakeup turns while getOrCreate waits for a closing generation to settle.
      */
     maybeWakeIdleSession(sessionId) {
+        if (!this.ownsBackgroundWakeups)
+            return;
         if (this.wakeupsInFlight.has(sessionId))
             return;
         this.wakeupsInFlight.add(sessionId);
         void this.wakeIdleSession(sessionId)
             .then((ranTurn) => {
             this.wakeupsInFlight.delete(sessionId);
-            if (ranTurn && notificationQueue.getSnapshot(sessionId).length > 0) {
+            if (ranTurn && this.notificationMailbox.getSnapshot(sessionId).length > 0) {
                 this.maybeWakeIdleSession(sessionId);
             }
         })
@@ -574,6 +592,7 @@ export class AgentServer {
             rehydrate: (id) => this.rehydrateSessionForWake(id),
             approvalRouter: this.approvalRouter,
             onStream: (event) => this.notify(Methods.StreamEvent, { sessionId, event }),
+            notificationMailbox: this.notificationMailbox,
         });
     }
     async rehydrateSessionForWake(sessionId) {
@@ -582,7 +601,7 @@ export class AgentServer {
         if (this.chatManager.isUnavailable(sessionId))
             return null;
         try {
-            const pending = notificationQueue.getSnapshot(sessionId);
+            const pending = this.notificationMailbox.getSnapshot(sessionId);
             if (pending.length === 0) {
                 logger.debug("bg_wakeup.rehydrate_skipped_no_pending", { sessionId });
                 return null;

package/dist/services/index.d.ts

@@ -3,7 +3,6 @@
  */
 export { analytics, trackEvent } from "./analytics.js";
 export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, type OAuthConfig, type OAuthTokens, type OAuthAuthorizeOptions, type OAuthRefreshOptions, type HardenedOAuthFetchOptions, } from "./oauth.js";
-export { notify, notifyComplete, notifyError } from "./notifier.js";
 export { diagnostics } from "./diagnostics.js";
 export { buildExtractionPrompt, parseExtractionResponse, type ExtractedMemory, } from "./extract-memories.js";
 export { shouldAutoDream, recordSession, recordDreamComplete, buildDreamSystemPrompt, buildDreamUserPrompt, } from "./auto-dream.js";

package/dist/services/index.js

@@ -9,7 +9,6 @@ export { analytics, trackEvent } from "./analytics.js";
 // to the tool_result-based microcompact in ContextManager). Removed to end
 // the "which microcompact?" ambiguity — the source of truth is ContextManager.
 export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, } from "./oauth.js";
-export { notify, notifyComplete, notifyError } from "./notifier.js";
 export { diagnostics } from "./diagnostics.js";
 export { buildExtractionPrompt, parseExtractionResponse, } from "./extract-memories.js";
 export { shouldAutoDream, recordSession, recordDreamComplete, buildDreamSystemPrompt, buildDreamUserPrompt, } from "./auto-dream.js";

package/dist/session/memory.js

@@ -23,7 +23,7 @@
  * Deletes are SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
  * rather than removed, so accidental deletions are recoverable.
  */
-import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, renameSync, statSync, } from "node:fs";
+import { mkdirSync, existsSync, readFileSync, readdirSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
@@ -174,7 +174,7 @@ export class MemoryManager {
             frontmatterLine("updateCount", updateCount) +
             `---\n\n` +
             `${entry.content}\n`;
-        writeFileSync(filePath, content, "utf-8");
+        writeFileAtomic(filePath, content, 0o600);
         // Incremental index update. Initialize the cache on first
         // save by paying one loadAll() — every save after that just
         // mutates the cache and rewrites MEMORY.md.

package/dist/tool-system/builtin/agent-notifications.d.ts

@@ -119,12 +119,23 @@ export type NotificationItem = {
     enqueuedAt: number;
 };
 type Listener = () => void;
-declare class NotificationQueue {
+export interface NotificationQueuePersistence {
+    fileForSession(sessionId: string): string | null;
+    /** Optional startup inventory. Lazy per-session restore works without it. */
+    listSessionIds?(): readonly string[];
+}
+export declare class NotificationQueue {
     private buckets;
     private listeners;
     private sequences;
     private sequenceRoutes;
+    private persistence;
+    private restoredSessions;
     private readonly maxSequenceRoutes;
+    attachPersistence(persistence: NotificationQueuePersistence | null): void;
+    /** Restore every persisted mailbox discovered by the host during startup. */
+    restorePersistedSessions(): string[];
+    restorePersistedSession(sessionId: string): number;
     enqueue(draft: NotificationEnvelopeDraft): NotificationEnvelope | undefined;
     enqueue(item: NotificationItem, sessionId: string): ResultEnvelope | undefined;
     subscribe: (listener: Listener) => (() => void);
@@ -143,6 +154,19 @@ declare class NotificationQueue {
     clearProgress(sessionId: string, agentId: string, runtimeGeneration?: number): boolean;
     clearDirections(sessionId: string, runtimeGeneration: number): boolean;
     reset(sessionId?: string): void;
+    private resultSnapshot;
+    private persistAddedResults;
+    private persistRemovedResults;
+    private replacePersistedResults;
+    /**
+     * Cross-process mailbox mutation. The directory lock exists before the JSON
+     * file does, and the current contents are re-read inside that lock. This
+     * avoids both the old lock-outside seed race and stale-snapshot overwrite.
+     */
+    private mutatePersistedResults;
+    private parsePersistedResultsForMutation;
+    private quarantineCorruptFile;
+    private reseedSequence;
     private notify;
 }
 type EnvelopeBusHandler = (envelope: NotificationEnvelope) => void;

package/dist/tool-system/builtin/agent-notifications.js

@@ -1,9 +1,78 @@
 import { nanoid } from "nanoid";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, renameSync, } from "node:fs";
 import { logger } from "../../logging/logger.js";
+import { mutateJsonFile } from "../../utils/file-mutex.js";
 const EMPTY = Object.freeze([]);
+const PERSISTENCE_SCHEMA_VERSION = 1;
+const MAX_PERSISTED_BYTES = 16 * 1024 * 1024;
 function isValidSessionId(value) {
     return typeof value === "string" && value.length > 0;
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNotificationAuthority(value) {
+    return value === "user" || value === "agent" || value === "system" || value === "policy";
+}
+function isEndpoint(value) {
+    if (!isRecord(value) || !isValidSessionId(value.sessionId))
+        return false;
+    if (value.agentId !== undefined && typeof value.agentId !== "string")
+        return false;
+    return isNotificationAuthority(value.authority);
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+function isResultPayload(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isValidSessionId(value.workId) || typeof value.description !== "string")
+        return false;
+    if (value.status !== "completed" && value.status !== "failed" && value.status !== "cancelled") {
+        return false;
+    }
+    if (value.workKind !== "agent" &&
+        value.workKind !== "shell" &&
+        value.workKind !== "video" &&
+        value.workKind !== "cc") {
+        return false;
+    }
+    if (!Number.isFinite(value.finishedAt))
+        return false;
+    if (!isOptionalString(value.name) ||
+        !isOptionalString(value.finalText) ||
+        !isOptionalString(value.error) ||
+        !isOptionalString(value.command) ||
+        !isOptionalString(value.ccSessionId) ||
+        !isOptionalString(value.cwd) ||
+        !isOptionalString(value.originClientMessageId)) {
+        return false;
+    }
+    return (value.changedFiles === undefined ||
+        (Array.isArray(value.changedFiles) &&
+            value.changedFiles.every((item) => typeof item === "string")));
+}
+function isPersistedResultEnvelope(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.schemaVersion !== 1 ||
+        value.kind !== "result" ||
+        value.delivery !== "idle-drain" ||
+        !isValidSessionId(value.id) ||
+        !isEndpoint(value.from) ||
+        !isEndpoint(value.to) ||
+        !Number.isSafeInteger(value.sequence) ||
+        value.sequence < 1 ||
+        !Number.isFinite(value.createdAt) ||
+        !isResultPayload(value.payload)) {
+        return false;
+    }
+    if (value.teamId !== undefined || !isOptionalString(value.correlationId))
+        return false;
+    return (value.runtimeGeneration === undefined ||
+        (Number.isSafeInteger(value.runtimeGeneration) && value.runtimeGeneration > 0));
+}
 function routeSequenceKey(draft) {
     return [
         draft.teamId ?? "tree",
@@ -83,12 +152,122 @@ function installLegacyResultAliases(envelope) {
         Object.defineProperty(envelope, name, { configurable: false, enumerable: false, get });
     }
 }
-class NotificationQueue {
+export class NotificationQueue {
     buckets = new Map();
     listeners = new Set();
     sequences = new Map();
     sequenceRoutes = new Map();
+    persistence = null;
+    restoredSessions = new Set();
     maxSequenceRoutes = 4_096;
+    attachPersistence(persistence) {
+        this.persistence = persistence;
+        this.restoredSessions.clear();
+    }
+    /** Restore every persisted mailbox discovered by the host during startup. */
+    restorePersistedSessions() {
+        const restored = [];
+        for (const sessionId of this.persistence?.listSessionIds?.() ?? []) {
+            if (!isValidSessionId(sessionId) || this.restoredSessions.has(sessionId))
+                continue;
+            this.restorePersistedSession(sessionId);
+            if (this.resultSnapshot(sessionId).length > 0)
+                restored.push(sessionId);
+        }
+        return restored;
+    }
+    restorePersistedSession(sessionId) {
+        if (!isValidSessionId(sessionId) || this.restoredSessions.has(sessionId))
+            return 0;
+        this.restoredSessions.add(sessionId);
+        const file = this.persistence?.fileForSession(sessionId) ?? null;
+        if (!file || !existsSync(file))
+            return 0;
+        let pathInfo;
+        try {
+            pathInfo = lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return 0;
+            this.restoredSessions.delete(sessionId);
+            logger.warn("notification_queue.persistence_read_failed", {
+                file,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return 0;
+        }
+        if (pathInfo.isSymbolicLink() || !pathInfo.isFile() || pathInfo.size > MAX_PERSISTED_BYTES) {
+            this.quarantineCorruptFile(file, new Error("pending notification file is not a bounded regular file"));
+            return 0;
+        }
+        let raw;
+        try {
+            const descriptor = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            try {
+                const opened = fstatSync(descriptor);
+                if (!opened.isFile() || opened.size > MAX_PERSISTED_BYTES) {
+                    throw new Error("pending notification file is not a bounded regular file");
+                }
+                raw = readFileSync(descriptor, "utf8");
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        }
+        catch (error) {
+            this.restoredSessions.delete(sessionId);
+            logger.warn("notification_queue.persistence_read_failed", {
+                file,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return 0;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            this.quarantineCorruptFile(file, error);
+            return 0;
+        }
+        if (!isRecord(parsed) ||
+            parsed.schemaVersion !== PERSISTENCE_SCHEMA_VERSION ||
+            !Array.isArray(parsed.results)) {
+            this.quarantineCorruptFile(file, new Error("invalid pending notification schema"));
+            return 0;
+        }
+        const valid = [];
+        const invalid = [];
+        for (const candidate of parsed.results) {
+            if (isPersistedResultEnvelope(candidate) && candidate.to.sessionId === sessionId) {
+                installLegacyResultAliases(candidate);
+                valid.push(candidate);
+            }
+            else {
+                invalid.push(candidate);
+            }
+        }
+        if (invalid.length > 0) {
+            this.quarantineCorruptFile(file, new Error(`${invalid.length} invalid pending notification entries`));
+            // Merge the salvaged rows back under the directory lock. A concurrent
+            // writer may already have recreated the active path after quarantine;
+            // replacing it with this earlier snapshot would lose that new result.
+            this.persistAddedResults(sessionId, valid);
+        }
+        if (valid.length === 0)
+            return 0;
+        const bucket = this.buckets.get(sessionId) ?? [];
+        const ids = new Set(bucket.map((item) => item.id));
+        const restored = valid.filter((item) => !ids.has(item.id));
+        if (restored.length === 0)
+            return 0;
+        this.buckets.set(sessionId, [...restored, ...bucket]);
+        for (const envelope of restored)
+            this.reseedSequence(envelope);
+        this.notify();
+        return restored.length;
+    }
     enqueue(draftOrItem, legacySessionId) {
         const draft = legacySessionId !== undefined || !("kind" in draftOrItem)
             ? legacyItemToDraft(draftOrItem, legacySessionId)
@@ -112,6 +291,7 @@ class NotificationQueue {
             logger.warn("notification_queue.invalid_direction_draft");
             return undefined;
         }
+        this.restorePersistedSession(draft.to.sessionId);
         const sequenceKey = routeSequenceKey(draft);
         const sequence = (this.sequences.get(sequenceKey) ?? 0) + 1;
         const id = nanoid();
@@ -154,6 +334,9 @@ class NotificationQueue {
             this.sequences.delete(oldest);
         }
         this.buckets.set(envelope.to.sessionId, [...next, envelope]);
+        if (envelope.kind === "result") {
+            this.persistAddedResults(envelope.to.sessionId, [envelope]);
+        }
         this.notify();
         agentNotificationBus.publish(envelope);
         return envelope;
@@ -165,11 +348,13 @@ class NotificationQueue {
     getSnapshot = (sessionId) => {
         if (!isValidSessionId(sessionId))
             return EMPTY;
+        this.restorePersistedSession(sessionId);
         return this.buckets.get(sessionId) ?? EMPTY;
     };
     drain(sessionId, predicate) {
         if (!isValidSessionId(sessionId))
             return [];
+        this.restorePersistedSession(sessionId);
         const bucket = this.buckets.get(sessionId);
         if (!bucket?.length)
             return [];
@@ -184,6 +369,9 @@ class NotificationQueue {
             this.buckets.set(sessionId, retained);
         else
             this.buckets.delete(sessionId);
+        this.persistRemovedResults(sessionId, drained
+            .filter((item) => item.kind === "result")
+            .map((item) => item.id));
         this.notify();
         return drained;
     }
@@ -201,12 +389,16 @@ class NotificationQueue {
     restoreResults(sessionId, envelopes) {
         if (!isValidSessionId(sessionId) || envelopes.length === 0)
             return 0;
+        this.restorePersistedSession(sessionId);
         const bucket = this.buckets.get(sessionId) ?? [];
         const ids = new Set(bucket.map((item) => item.id));
         const restored = envelopes.filter((item) => item.kind === "result" && item.to.sessionId === sessionId && !ids.has(item.id));
         if (restored.length === 0)
             return 0;
         this.buckets.set(sessionId, [...restored, ...bucket]);
+        for (const envelope of restored)
+            this.reseedSequence(envelope);
+        this.persistAddedResults(sessionId, restored);
         this.notify();
         return restored.length;
     }
@@ -242,13 +434,23 @@ class NotificationQueue {
     }
     reset(sessionId) {
         if (sessionId === undefined) {
-            if (this.buckets.size === 0 && this.sequences.size === 0)
+            if (this.buckets.size === 0 && this.sequences.size === 0) {
+                this.restoredSessions.clear();
                 return;
+            }
+            const persistedSessions = [...this.buckets.keys()];
             this.buckets.clear();
             this.sequences.clear();
             this.sequenceRoutes.clear();
+            for (const persistedSession of persistedSessions) {
+                const file = this.persistence?.fileForSession(persistedSession) ?? null;
+                if (file)
+                    this.replacePersistedResults(file, []);
+            }
+            this.restoredSessions.clear();
         }
         else {
+            this.restorePersistedSession(sessionId);
             const hadBucket = this.buckets.delete(sessionId);
             let clearedRoute = false;
             for (const [key, route] of this.sequenceRoutes) {
@@ -260,9 +462,139 @@ class NotificationQueue {
             }
             if (!hadBucket && !clearedRoute)
                 return;
+            const file = this.persistence?.fileForSession(sessionId) ?? null;
+            if (file)
+                this.replacePersistedResults(file, []);
+            this.restoredSessions.delete(sessionId);
         }
         this.notify();
     }
+    resultSnapshot(sessionId) {
+        return (this.buckets.get(sessionId) ?? []).filter((item) => item.kind === "result");
+    }
+    persistAddedResults(sessionId, results) {
+        if (results.length === 0)
+            return;
+        const file = this.persistence?.fileForSession(sessionId) ?? null;
+        if (!file)
+            return;
+        try {
+            this.mutatePersistedResults(file, (current) => {
+                const merged = [...current.results];
+                const ids = new Set(merged.map((item) => item.id));
+                for (const result of results) {
+                    if (ids.has(result.id))
+                        continue;
+                    ids.add(result.id);
+                    merged.push(result);
+                }
+                // Always return the validated state: parse may have quarantined a
+                // mixed-validity file, in which case even a duplicate add must reseed
+                // the active path with the valid rows.
+                return merged;
+            });
+        }
+        catch (error) {
+            logger.error("notification_queue.persistence_write_failed", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    persistRemovedResults(sessionId, resultIds) {
+        if (resultIds.length === 0)
+            return;
+        const file = this.persistence?.fileForSession(sessionId) ?? null;
+        if (!file)
+            return;
+        try {
+            const removed = new Set(resultIds);
+            this.mutatePersistedResults(file, (current) => {
+                const retained = current.results.filter((item) => !removed.has(item.id));
+                return retained;
+            });
+        }
+        catch (error) {
+            logger.error("notification_queue.persistence_write_failed", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    replacePersistedResults(file, results) {
+        this.mutatePersistedResults(file, () => [...results]);
+    }
+    /**
+     * Cross-process mailbox mutation. The directory lock exists before the JSON
+     * file does, and the current contents are re-read inside that lock. This
+     * avoids both the old lock-outside seed race and stale-snapshot overwrite.
+     */
+    mutatePersistedResults(file, mutation) {
+        mutateJsonFile(file, {
+            parse: (raw) => this.parsePersistedResultsForMutation(file, raw),
+            serialize: (value) => `${JSON.stringify(value, null, 2)}\n`,
+            mutation: (current) => {
+                const results = mutation(current);
+                return results === undefined
+                    ? {}
+                    : {
+                        value: {
+                            schemaVersion: PERSISTENCE_SCHEMA_VERSION,
+                            results,
+                        },
+                    };
+            },
+            mode: 0o600,
+            maxBytes: MAX_PERSISTED_BYTES,
+        });
+    }
+    parsePersistedResultsForMutation(file, raw) {
+        if (raw === undefined) {
+            return { schemaVersion: PERSISTENCE_SCHEMA_VERSION, results: [] };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            this.quarantineCorruptFile(file, error);
+            return { schemaVersion: PERSISTENCE_SCHEMA_VERSION, results: [] };
+        }
+        if (!isRecord(parsed) ||
+            parsed.schemaVersion !== PERSISTENCE_SCHEMA_VERSION ||
+            !Array.isArray(parsed.results)) {
+            this.quarantineCorruptFile(file, new Error("invalid pending notification schema"));
+            return { schemaVersion: PERSISTENCE_SCHEMA_VERSION, results: [] };
+        }
+        const valid = parsed.results.filter(isPersistedResultEnvelope);
+        if (valid.length !== parsed.results.length) {
+            this.quarantineCorruptFile(file, new Error(`${parsed.results.length - valid.length} invalid pending notification entries`));
+        }
+        return { schemaVersion: PERSISTENCE_SCHEMA_VERSION, results: valid };
+    }
+    quarantineCorruptFile(file, error) {
+        const corruptFile = `${file}.${Date.now()}.${nanoid(6)}.corrupt`;
+        try {
+            renameSync(file, corruptFile);
+            logger.warn("notification_queue.persistence_quarantined", {
+                file,
+                corruptFile,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        catch (quarantineError) {
+            logger.warn("notification_queue.persistence_quarantine_failed", {
+                file,
+                error: quarantineError instanceof Error ? quarantineError.message : String(quarantineError),
+            });
+        }
+    }
+    reseedSequence(envelope) {
+        const key = routeSequenceKey(envelope);
+        this.sequences.set(key, Math.max(this.sequences.get(key) ?? 0, envelope.sequence));
+        this.sequenceRoutes.delete(key);
+        this.sequenceRoutes.set(key, { from: envelope.from.sessionId, to: envelope.to.sessionId });
+    }
     notify() {
         for (const listener of this.listeners) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",

package/dist/services/notifier.d.ts

@@ -1,33 +0,0 @@
-/**
- * Notifier service — desktop/system notifications.
- *
- * Sends notifications when tasks complete, agents finish, or errors occur.
- * Falls back gracefully when no notification system is available.
- */
-export interface NotificationOptions {
-    title: string;
-    message: string;
-    sound?: boolean;
-    /** Urgency level: low, normal, critical */
-    urgency?: "low" | "normal" | "critical";
-}
-/**
- * Send a desktop notification.
- */
-export declare function notify(options: NotificationOptions): void;
-/** Escape a string for embedding inside an AppleScript double-quoted literal. */
-export declare function escapeAppleScriptString(str: string): string;
-/** Build the osascript argv (a single `-e <script>` pair). */
-export declare function buildOsascriptArgs(title: string, message: string, sound: boolean): string[];
-/** Build the notify-send argv with title/message as separate tokens. */
-export declare function buildNotifySendArgs(title: string, message: string, urgency: "low" | "normal" | "critical"): string[];
-/** Build the powershell.exe argv (a single `-Command <script>` element). */
-export declare function buildPowershellArgs(title: string, message: string): string[];
-/**
- * Send a notification that a task/agent has completed.
- */
-export declare function notifyComplete(taskName: string, duration?: number): void;
-/**
- * Send an error notification.
- */
-export declare function notifyError(context: string, error: string): void;

package/dist/services/notifier.js

@@ -1,83 +0,0 @@
-/**
- * Notifier service — desktop/system notifications.
- *
- * Sends notifications when tasks complete, agents finish, or errors occur.
- * Falls back gracefully when no notification system is available.
- */
-import { execFileSync } from "node:child_process";
-/**
- * Send a desktop notification.
- */
-export function notify(options) {
-    const { title, message, sound = false, urgency = "normal" } = options;
-    try {
-        if (process.platform === "darwin") {
-            // macOS: osascript. Pass the script as a single -e argv element via
-            // execFileSync (no shell), so title/message are never seen by the shell.
-            execFileSync("osascript", buildOsascriptArgs(title, message, sound), { timeout: 5000 });
-        }
-        else if (process.platform === "linux") {
-            // Linux: notify-send. argv keeps title/message as separate tokens.
-            execFileSync("notify-send", buildNotifySendArgs(title, message, urgency), { timeout: 5000 });
-        }
-        else if (process.platform === "win32") {
-            // Windows: PowerShell toast. The script is one -Command argv element
-            // (no outer shell); title/message are escaped for PowerShell single
-            // quotes (' → '').
-            execFileSync("powershell.exe", buildPowershellArgs(title, message), { timeout: 5000 });
-        }
-    }
-    catch {
-        // Silently fail — notifications are best-effort
-    }
-}
-/** Escape a string for embedding inside an AppleScript double-quoted literal. */
-export function escapeAppleScriptString(str) {
-    return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");
-}
-/** Build the osascript argv (a single `-e <script>` pair). */
-export function buildOsascriptArgs(title, message, sound) {
-    const soundClause = sound ? ' sound name "default"' : "";
-    const script = `display notification "${escapeAppleScriptString(message)}"` +
-        ` with title "${escapeAppleScriptString(title)}"${soundClause}`;
-    return ["-e", script];
-}
-/** Build the notify-send argv with title/message as separate tokens. */
-export function buildNotifySendArgs(title, message, urgency) {
-    return ["-u", urgency, title, message];
-}
-/** Build the powershell.exe argv (a single `-Command <script>` element). */
-export function buildPowershellArgs(title, message) {
-    const esc = (s) => s.replace(/'/g, "''").replace(/\n/g, " ");
-    const ps = [
-        "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null",
-        "$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
-        "$text = $xml.GetElementsByTagName('text')",
-        `$text[0].AppendChild($xml.CreateTextNode('${esc(title)}')) | Out-Null`,
-        `$text[1].AppendChild($xml.CreateTextNode('${esc(message)}')) | Out-Null`,
-        "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
-        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('CodeShell').Show($toast)",
-    ].join("; ");
-    return ["-NoProfile", "-Command", ps];
-}
-/**
- * Send a notification that a task/agent has completed.
- */
-export function notifyComplete(taskName, duration) {
-    const durationStr = duration ? ` (${(duration / 1000).toFixed(1)}s)` : "";
-    notify({
-        title: "Code Shell",
-        message: `✓ ${taskName} completed${durationStr}`,
-        sound: true,
-    });
-}
-/**
- * Send an error notification.
- */
-export function notifyError(context, error) {
-    notify({
-        title: "Code Shell Error",
-        message: `✗ ${context}: ${error.slice(0, 100)}`,
-        urgency: "critical",
-    });
-}