@0xmaxma/claude-gateway 1.7.9 → 1.8.0

package/dist/packages/registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Version detection and self-update for the two packages the gateway manages:
+ * itself and the Claude Code binary it drives.
+ *
+ * Shared by the HTTP API (src/api/packages.ts) and the CLI (`claude-gateway
+ * update`, `claude-gateway claude update`) so both apply exactly the same
+ * detect/update strategy — the CLI must never invent a second way to install
+ * a package, or the dashboard and the terminal would disagree about what is
+ * running.
+ */
+export interface PackageConfig {
+    npm: string;
+    detect: 'npm' | 'binary';
+    bin?: string;
+    update: 'npm' | 'native';
+}
+/**
+ * Package id (URL param / CLI noun) → config.
+ * claude-gateway is a genuine npm global — keep npm detect/update.
+ * claude-code ships via the native installer (no longer an npm global), so
+ * detect from the `claude` binary and update via its native updater.
+ */
+export declare const PACKAGES: Record<string, PackageConfig>;
+export interface PackageInfo {
+    package: string;
+    current: string | null;
+    latest: string | null;
+    hasUpdate: boolean;
+}
+export declare function getNpmListVersion(packageName: string): string | null;
+/** Resolve the currently-installed version per the package's detect strategy. */
+export declare function resolveCurrent(config: PackageConfig): string | null;
+export declare function updateAvailable(current: string | null, latest: string | null): boolean;
+export declare function getLatestVersion(packageName: string): Promise<string | null>;
+export declare function fetchAllPackageVersions(): Promise<PackageInfo[]>;
+/**
+ * Run the package's own native updater (`<bin> update`).
+ * Returns null on success, or the updater's error text.
+ */
+export declare function runNativeUpdate(config: PackageConfig): string | null;
+/**
+ * Install the latest version of an npm-global package.
+ *
+ * A previously interrupted install can leave `.<pkg>-<hash>` staging dirs in the
+ * npm global root that make the next install fail with ENOTEMPTY/ENOTDIR, so
+ * those are pre-cleaned and the install is retried once after removing the
+ * half-written package directory. Returns null on success, or the error text.
+ */
+export declare function installNpmLatest(packageName: string): string | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/packages/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/packages/registry.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAYH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAQlD,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYpE;AAwBD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAKnE;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEtF;AAED,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMlF;AAED,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBtE;AAsDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAUpE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8BnE"}

package/dist/packages/registry.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGES = void 0;
+exports.getNpmListVersion = getNpmListVersion;
+exports.resolveCurrent = resolveCurrent;
+exports.updateAvailable = updateAvailable;
+exports.getLatestVersion = getLatestVersion;
+exports.fetchAllPackageVersions = fetchAllPackageVersions;
+exports.runNativeUpdate = runNativeUpdate;
+exports.installNpmLatest = installNpmLatest;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const migrator_1 = require("../config/migrator");
+/**
+ * Package id (URL param / CLI noun) → config.
+ * claude-gateway is a genuine npm global — keep npm detect/update.
+ * claude-code ships via the native installer (no longer an npm global), so
+ * detect from the `claude` binary and update via its native updater.
+ */
+exports.PACKAGES = {
+    'claude-gateway': { npm: '@0xmaxma/claude-gateway', detect: 'npm', update: 'npm' },
+    'claude-code': {
+        npm: '@anthropic-ai/claude-code',
+        detect: 'binary',
+        bin: 'claude',
+        update: 'native',
+    },
+};
+function getNpmListVersion(packageName) {
+    try {
+        const output = (0, child_process_1.execSync)(`npm list -g ${packageName} --depth=0 --json`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10000,
+        });
+        const parsed = JSON.parse(output);
+        return parsed.dependencies?.[packageName]?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Resolve the installed version by shelling out to the binary on PATH
+// (e.g. `claude --version` → "2.1.207 (Claude Code)"). Parses the leading
+// semver (with optional prerelease) and returns null on any failure —
+// binary missing, non-zero exit, or unparseable output. `bin` is always a
+// trusted constant from PACKAGES, never request-derived.
+function getBinaryVersion(bin) {
+    try {
+        const output = (0, child_process_1.execSync)(`${bin} --version`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10000,
+        });
+        // `claude --version` prints the version first (e.g. "2.1.207 (Claude Code)").
+        // Anchor to the start of the trimmed output so a version-like token later in
+        // the line can never be mistaken for the installed version.
+        const match = output.trim().match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the currently-installed version per the package's detect strategy. */
+function resolveCurrent(config) {
+    if (config.detect === 'binary' && config.bin) {
+        return getBinaryVersion(config.bin);
+    }
+    return getNpmListVersion(config.npm);
+}
+// An update is available only when `latest` is strictly newer than `current`.
+// Using semver ordering (not `current !== latest`) avoids a false "update
+// available" when the installed version is *ahead* of the npm-registry latest
+// — e.g. a native-installer channel that leads the npm dist-tag.
+function updateAvailable(current, latest) {
+    return !!(current && latest && (0, migrator_1.compareSemver)(latest, current) > 0);
+}
+async function getLatestVersion(packageName) {
+    const encodedName = packageName.replace('/', '%2F');
+    const res = await fetch(`https://registry.npmjs.org/${encodedName}/latest`);
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.version ?? null;
+}
+async function fetchAllPackageVersions() {
+    const configs = Object.values(exports.PACKAGES);
+    // Run all synchronous current-version lookups before entering async Promise.all
+    const currents = configs.map(resolveCurrent);
+    return Promise.all(configs.map(async (config, i) => {
+        const current = currents[i];
+        const latest = await getLatestVersion(config.npm);
+        return {
+            package: config.npm,
+            current,
+            latest,
+            hasUpdate: updateAvailable(current, latest),
+        };
+    }));
+}
+function getNpmGlobalRoot() {
+    return (0, child_process_1.execSync)('npm root -g', {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+    }).trim();
+}
+function cleanStaleNpmTempDirs(npmRoot, packageName) {
+    const match = packageName.match(/^(@[^/]+)\/(.+)$/);
+    if (!match)
+        return;
+    const [, scope, basename] = match;
+    const scopeDir = (0, path_1.join)(npmRoot, scope);
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(scopeDir, { withFileTypes: false });
+    }
+    catch {
+        return;
+    }
+    const prefix = `.${basename}-`;
+    for (const entry of entries) {
+        if (entry.startsWith(prefix)) {
+            try {
+                (0, fs_1.rmSync)((0, path_1.join)(scopeDir, entry), { recursive: true, force: true });
+            }
+            catch {
+                // best-effort: ignore errors on individual temp dir removal
+            }
+        }
+    }
+}
+function removePackageDir(npmRoot, packageName) {
+    const match = packageName.match(/^(@[^/]+)\/(.+)$/);
+    if (!match)
+        return;
+    const [, scope, basename] = match;
+    try {
+        (0, fs_1.rmSync)((0, path_1.join)(npmRoot, scope, basename), { recursive: true, force: true });
+    }
+    catch {
+        // best-effort
+    }
+}
+function errorText(err, fallback) {
+    return (err.stderr?.toString() ||
+        err.message ||
+        fallback);
+}
+/**
+ * Run the package's own native updater (`<bin> update`).
+ * Returns null on success, or the updater's error text.
+ */
+function runNativeUpdate(config) {
+    // Guarded here as well as at the call sites: without a bin there is no
+    // updater to run, and shelling out would execute `undefined update`.
+    if (!config.bin)
+        return `no native updater configured for ${config.npm}`;
+    try {
+        (0, child_process_1.execSync)(`${config.bin} update`, { stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
+        return null;
+    }
+    catch (err) {
+        return errorText(err, 'update failed');
+    }
+}
+/**
+ * Install the latest version of an npm-global package.
+ *
+ * A previously interrupted install can leave `.<pkg>-<hash>` staging dirs in the
+ * npm global root that make the next install fail with ENOTEMPTY/ENOTDIR, so
+ * those are pre-cleaned and the install is retried once after removing the
+ * half-written package directory. Returns null on success, or the error text.
+ */
+function installNpmLatest(packageName) {
+    let npmRoot = '';
+    try {
+        npmRoot = getNpmGlobalRoot();
+    }
+    catch {
+        // non-fatal: skip pre-clean if npm root unavailable
+    }
+    if (npmRoot) {
+        cleanStaleNpmTempDirs(npmRoot, packageName);
+    }
+    try {
+        (0, child_process_1.execSync)(`npm install -g ${packageName}@latest`, { stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
+        return null;
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString() ?? '';
+        if (!npmRoot || !(stderr.includes('ENOTEMPTY') || stderr.includes('ENOTDIR'))) {
+            return errorText(err, 'install failed');
+        }
+        // Remove stale temp dirs and the partially-installed package dir, then retry once
+        cleanStaleNpmTempDirs(npmRoot, packageName);
+        removePackageDir(npmRoot, packageName);
+        try {
+            (0, child_process_1.execSync)(`npm install -g ${packageName}@latest`, { stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 });
+            return null;
+        }
+        catch (retryErr) {
+            return errorText(retryErr, 'install failed');
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/packages/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/packages/registry.ts"],"names":[],"mappings":"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"}

package/dist/session/process.d.ts

@@ -18,6 +18,8 @@ export declare class SessionProcess extends EventEmitter {
     readonly source: ChatChannelOrApi;
     private readonly sessionChannel;
     lastActivityAt: number;
+    private lastBackgroundAgentDispatchAt;
+    private backgroundWaitTimer;
     readonly spawnedAt: number;
     /** Backend used to run the subprocess. Set during start(); 'headless' until then. */
     backend: 'pty-shell' | 'headless';
@@ -100,9 +102,8 @@ export declare class SessionProcess extends EventEmitter {
     private resolveSharedKbDir;
     /**
      * "1" when the read-path retrieval recorder should log memory_search hits into
-     * kb_retrieval_log (planning-66) — the LRU/feedback signal the nightly staleness
-     * GC folds into per-entry recency. Off unless staleness AND recordRetrievals are
-     * both enabled. Mirrors resolveSharedKbDir's env-gate pattern.
+     * kb_retrieval_log. Either enabled lifecycle tier can consume the same
+     * append-only log: personal dreaming staleness or shared-KB staleness.
      */
     private resolveRecordRetrievals;
     private buildArgs;
@@ -143,6 +144,13 @@ export declare class SessionProcess extends EventEmitter {
     sendInput(data: string): boolean;
     query(prompt: string, timeoutMs?: number): Promise<string>;
     get isProcessing(): boolean;
+    private clearBackgroundWaitTimer;
+    /**
+     * Extend Telegram's working state only while a parent session is waiting for
+     * background Agent/Workflow work. A bounded expiry releases the state if the
+     * child task never sends its completion notification.
+     */
+    retainBackgroundWorkingState(): boolean;
     setProcessing(active: boolean): void;
     interrupt(): boolean;
     /**
@@ -175,6 +183,15 @@ export declare class SessionProcess extends EventEmitter {
     isRestartScheduled(): boolean;
     touch(): void;
     isIdle(idleMs: number): boolean;
+    /**
+     * True when this session's own turn has ended (not `isProcessing`) but it
+     * recently dispatched a BACKGROUND_DISPATCH_TOOLS tool_use — i.e. it looks
+     * idle from the outside while a sub-agent it launched may still be doing
+     * real work. `restartOrDefer` treats this the same as `isProcessing` so a
+     * config-driven restart never SIGKILLs a session mid-dispatch, regardless of
+     * which restart tier triggered it.
+     */
+    hasLikelyOutstandingBackgroundWork(): boolean;
     isRunning(): boolean;
     stop(): Promise<void>;
 }

package/dist/session/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/session/process.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/session/process.ts"],"names":[],"mappings":"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"}

package/dist/session/process.js

@@ -62,6 +62,22 @@ const CHANNEL_REPLY_TOOLS = new Set([
     'mcp__gateway__discord_reply',
     'mcp__gateway__line_reply',
 ]);
+// Tool names whose tool_use dispatches genuinely background work: the call
+// itself returns immediately (a task/agent id), and completion is delivered
+// later as a separate, asynchronously-injected turn (a task-notification) —
+// never as this tool_use's own tool_result. A session that ends its own turn
+// right after dispatching one of these is legitimately idle *from the CLI's
+// perspective* while real work is still in flight elsewhere. See
+// BACKGROUND_AGENT_GRACE_MS and hasLikelyOutstandingBackgroundWork() below.
+const BACKGROUND_DISPATCH_TOOLS = new Set(['Agent', 'Workflow']);
+// How long a session is treated as "may still have outstanding background
+// work" after dispatching one of BACKGROUND_DISPATCH_TOOLS, once its own turn
+// has ended. Generous enough to cover a multi-agent review of a large diff
+// (the incident that motivated this — a config-driven restart SIGHUP'd a
+// session mid-review, killing 3 in-flight review sub-agents with it, see
+// issue referenced in restartOrDefer below); bounded so a dispatch that never
+// reports back (crashed, errored) can't block a config rollout forever.
+const BACKGROUND_AGENT_GRACE_MS = 15 * 60 * 1000;
 // Shared wording for a turn that ended (gracefully or via a mid-turn exit) with no
 // assistant text at all — used both to patch the in-memory prompt fed to the next
 // spawn (buildInitialPrompt below) and, in AgentRunner, to persist a real assistant
@@ -122,6 +138,15 @@ class SessionProcess extends events_1.EventEmitter {
     constructor(sessionId, source, agentConfig, gatewayConfig, sessionStore, chatId) {
         super();
         this.lastActivityAt = Date.now(); // accessible by AgentRunner for eviction sort
+        // Wall-clock time of the most recent BACKGROUND_DISPATCH_TOOLS tool_use seen
+        // in this session's own turn, while no NEWER turn has started since. Cleared
+        // whenever a fresh turn begins (setProcessing(true)) since by then the
+        // dispatch either reported back (the notification woke this turn) or has
+        // been superseded by unrelated new work — either way the idle-window concern
+        // this field exists for no longer applies. Read via
+        // hasLikelyOutstandingBackgroundWork().
+        this.lastBackgroundAgentDispatchAt = null;
+        this.backgroundWaitTimer = null;
         this.spawnedAt = Date.now();
         /** Backend used to run the subprocess. Set during start(); 'headless' until then. */
         this.backend = 'headless';
@@ -443,6 +468,13 @@ class SessionProcess extends events_1.EventEmitter {
                         // Shared KB vault dir (planning-64 K3), so memory_search corpus:"shared"
                         // can reach the cross-agent vault. Empty when shared KB is disabled.
                         GATEWAY_SHARED_KB_DIR: this.resolveSharedKbDir(),
+                        // The Bun MCP subprocess's own `process.execPath` is the `bun` binary, not
+                        // `node` — spawning the compiled reindex-cli.js (needs `node:sqlite`) with
+                        // that would fail (`No such built-in module: node:sqlite`), silently, since
+                        // memory_shared_create/_update/_delete's reindex trigger runs detached/stdio:'ignore'. Forward the
+                        // GATEWAY PROCESS's own execPath (real Node, guaranteed >=22 by `engines`) so
+                        // the mcp side can spawn the CLI with the right runtime.
+                        GATEWAY_NODE_EXEC_PATH: process.execPath,
                         // planning-66: gate the read-path retrieval recorder (memory_search →
                         // kb_retrieval_log) so the staleness GC's LRU/feedback signal is only
                         // collected when the agent actually runs the GC.
@@ -499,13 +531,13 @@ class SessionProcess extends events_1.EventEmitter {
     }
     /**
      * "1" when the read-path retrieval recorder should log memory_search hits into
-     * kb_retrieval_log (planning-66) — the LRU/feedback signal the nightly staleness
-     * GC folds into per-entry recency. Off unless staleness AND recordRetrievals are
-     * both enabled. Mirrors resolveSharedKbDir's env-gate pattern.
+     * kb_retrieval_log. Either enabled lifecycle tier can consume the same
+     * append-only log: personal dreaming staleness or shared-KB staleness.
      */
     resolveRecordRetrievals() {
-        const s = (0, config_1.resolveDreamingConfig)(this.agentConfig.dreaming, this.gatewayConfig.gateway.dreaming).staleness;
-        return s.enabled && s.recordRetrievals ? '1' : '';
+        const personal = (0, config_1.resolveDreamingConfig)(this.agentConfig.dreaming, this.gatewayConfig.gateway.dreaming).staleness;
+        const shared = (0, knowledge_1.resolveSharedConfig)(this.agentConfig.knowledge?.shared, this.gatewayConfig.gateway.knowledge?.shared).staleness;
+        return (personal.enabled && personal.recordRetrievals) || (shared.enabled && shared.recordRetrievals) ? '1' : '';
     }
     buildArgs(mcpConfigPath, model) {
         const args = [
@@ -810,6 +842,19 @@ class SessionProcess extends events_1.EventEmitter {
                             }
                             lastPartialText = '';
                         }
+                        // Record a background-dispatch tool_use (see BACKGROUND_DISPATCH_TOOLS)
+                        // so restartOrDefer can tell "genuinely idle" apart from "idle because
+                        // it just fired off async work and is waiting on a task-notification".
+                        // Only the final (non-partial) message carries a fully materialised
+                        // tool_use block, same as the reply-mirror check above.
+                        if (!isPartial && !this.queryMode) {
+                            for (const block of obj.message.content) {
+                                if (block.type === 'tool_use' && BACKGROUND_DISPATCH_TOOLS.has(block.name)) {
+                                    this.lastBackgroundAgentDispatchAt = Date.now();
+                                    break;
+                                }
+                            }
+                        }
                         // Mirror channel replies (telegram_reply/discord_reply/line_reply) into
                         // the resumable session store at delivery time. The user-facing text is
                         // carried in the tool_use input, not a text block, so assistantBuffer
@@ -991,6 +1036,8 @@ class SessionProcess extends events_1.EventEmitter {
                 pty_stream_registry_1.ptyStreamRegistry.close(ptyStreamSocketPath);
             this.process = null;
             this._exited = true;
+            this.lastBackgroundAgentDispatchAt = null;
+            this.clearBackgroundWaitTimer();
             // Notify listeners that the underlying subprocess died. The runner relies
             // on this to tear down per-chat typing/processing state when a session is
             // stopped or restarted mid-turn (without a final result/session_idle).
@@ -1221,9 +1268,60 @@ class SessionProcess extends events_1.EventEmitter {
         });
     }
     get isProcessing() { return this._processing; }
+    clearBackgroundWaitTimer() {
+        if (this.backgroundWaitTimer !== null) {
+            clearTimeout(this.backgroundWaitTimer);
+            this.backgroundWaitTimer = null;
+        }
+    }
+    /**
+     * Extend Telegram's working state only while a parent session is waiting for
+     * background Agent/Workflow work. A bounded expiry releases the state if the
+     * child task never sends its completion notification.
+     */
+    retainBackgroundWorkingState() {
+        if (this.source !== 'telegram' || !this.hasLikelyOutstandingBackgroundWork())
+            return false;
+        const processingPath = path.join(this.typingDir, `${this.chatId}.processing`);
+        try {
+            fs.mkdirSync(this.typingDir, { recursive: true });
+            fs.writeFileSync(processingPath, String(Date.now()));
+        }
+        catch (err) {
+            this.logger.warn('Failed to retain .processing sentinel for background work', {
+                chatId: this.chatId,
+                error: err.message,
+            });
+        }
+        if (this.backgroundWaitTimer === null) {
+            const elapsed = Date.now() - this.lastBackgroundAgentDispatchAt;
+            const remaining = Math.max(0, BACKGROUND_AGENT_GRACE_MS - elapsed);
+            this.backgroundWaitTimer = setTimeout(() => {
+                this.backgroundWaitTimer = null;
+                this.lastBackgroundAgentDispatchAt = null;
+                if (!this._processing) {
+                    try {
+                        fs.rmSync(processingPath, { force: true });
+                    }
+                    catch { }
+                    this.emit('backgroundWorkExpired');
+                }
+            }, remaining);
+            this.backgroundWaitTimer.unref();
+        }
+        return true;
+    }
     setProcessing(active) {
         if (this._processing !== active) {
             this._processing = active;
+            if (active) {
+                // A fresh turn is starting — either the notification this dispatch was
+                // waiting on just woke it (resolved), or unrelated new work superseded
+                // it (moot either way). isProcessing now covers this session correctly
+                // on its own, so the idle-window concern this field exists for is over.
+                this.lastBackgroundAgentDispatchAt = null;
+                this.clearBackgroundWaitTimer();
+            }
             this.emit('processingChange', active);
             if (this.source === 'telegram') {
                 const processingPath = path.join(this.typingDir, `${this.chatId}.processing`);
@@ -1306,6 +1404,21 @@ class SessionProcess extends events_1.EventEmitter {
     isIdle(idleMs) {
         return Date.now() - this.lastActivityAt > idleMs;
     }
+    /**
+     * True when this session's own turn has ended (not `isProcessing`) but it
+     * recently dispatched a BACKGROUND_DISPATCH_TOOLS tool_use — i.e. it looks
+     * idle from the outside while a sub-agent it launched may still be doing
+     * real work. `restartOrDefer` treats this the same as `isProcessing` so a
+     * config-driven restart never SIGKILLs a session mid-dispatch, regardless of
+     * which restart tier triggered it.
+     */
+    hasLikelyOutstandingBackgroundWork() {
+        if (this._processing)
+            return false;
+        if (this.lastBackgroundAgentDispatchAt === null)
+            return false;
+        return Date.now() - this.lastBackgroundAgentDispatchAt < BACKGROUND_AGENT_GRACE_MS;
+    }
     isRunning() {
         // Use _exited (child's 'exit' observed), NOT .killed — .killed is true after
         // any signal send, including a /stop SIGINT the pty-shell survives, which
@@ -1314,6 +1427,8 @@ class SessionProcess extends events_1.EventEmitter {
     }
     async stop() {
         this.stopping = true;
+        this.lastBackgroundAgentDispatchAt = null;
+        this.clearBackgroundWaitTimer();
         await this.restartWatcher?.close();
         this.restartWatcher = null;
         try {