Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Keep process cleanup owned through cancellation and shutdown

wyt5d14facb9f96
diff --git a/src/core-agent/src/sandbox/windows-process-tree.ts b/src/core-agent/src/sandbox/windows-process-tree.ts
index 787fbfcc..06a1182e 100644
--- a/src/core-agent/src/sandbox/windows-process-tree.ts
+++ b/src/core-agent/src/sandbox/windows-process-tree.ts
@@ -87,6 +87,11 @@ try {
}
} while ($added -gt 0)
+ # The pinned root has already exited. If the first snapshot contains no
+ # live descendants, no owned producer can create another child. Avoid a
+ # redundant WMI query in this common shell-startup cancellation path.
+ if ($ordered.Count -eq 1) { $result = 0; break }
+
# Stop producers first, retaining their handles for the next snapshot.
# A child created during this sweep remains linked to a pinned parent.
# Discovery only adds a child after its parent, so this order already
diff --git a/src/core-agent/src/tools/process-session.ts b/src/core-agent/src/tools/process-session.ts
index 98c6af06..a5239ece 100644
--- a/src/core-agent/src/tools/process-session.ts
+++ b/src/core-agent/src/tools/process-session.ts
@@ -46,6 +46,7 @@ interface ProcessSession {
lifetimeTimer: NodeJS.Timeout;
cleanupTimer?: NodeJS.Timeout;
killTimer?: NodeJS.Timeout;
+ termination?: Promise<void>;
}
const PROCESS_OUTPUT_BUFFER_CHARS = 1_000_000;
@@ -141,13 +142,21 @@ function finishSession(
scheduleCleanup(session);
}
-function killSession(session: ProcessSession, signal: NodeJS.Signals = "SIGTERM"): void {
- try { killProcessTree(session.child, signal); } catch { /* best effort */ }
+function killSession(session: ProcessSession, signal: NodeJS.Signals = "SIGTERM"): Promise<void> {
+ if (session.termination) return session.termination;
+ session.termination = new Promise<void>((resolve) => {
+ try { killProcessTree(session.child, signal, { onComplete: resolve }); }
+ catch { resolve(); }
+ });
+ // Windows performs its bounded forceful sweep in the existing helper.
+ // POSIX still escalates the process group even if its shell exited first.
+ if (process.platform === "win32") return session.termination;
if (session.killTimer) clearTimeout(session.killTimer);
session.killTimer = setTimeout(() => {
try { killProcessTree(session.child, "SIGKILL"); } catch { /* best effort */ }
}, 5_000);
if (typeof session.killTimer.unref === "function") session.killTimer.unref();
+ return session.termination;
}
function ownedSession(ctx: ToolContext, sessionId: unknown): ProcessSession | ToolResult {
@@ -546,8 +555,11 @@ export const processStopTool: AgentTool = defineTool({
if (session.status === "running") {
killSession(session);
finishSession(session, "stopped", { signal: "agent" });
- await waitForProcessClose(session);
}
+ // A shell closing is not proof that its descendants have been reaped.
+ // Repeated/concurrent stops share the original ownership receipt.
+ await session.termination;
+ await waitForProcessClose(session);
return terminalResultJson(session, session.outputEnd, PROCESS_READ_DEFAULT_CHARS);
},
});
@@ -672,7 +684,10 @@ export async function _resetProcessSessionsForTest(): Promise<void> {
try { killProcessTree(session.child, "SIGKILL"); } catch { /* best effort */ }
}
}
- await Promise.all(active.map((session) => waitForProcessClose(session, 2_000)));
+ await Promise.all(active.map(async (session) => {
+ await session.termination;
+ await waitForProcessClose(session, 2_000);
+ }));
for (const session of active) {
clearTimers(session);
}
diff --git a/src/core-agent/test/process-session.test.ts b/src/core-agent/test/process-session.test.ts
index 8613ba5c..cc758f85 100644
--- a/src/core-agent/test/process-session.test.ts
+++ b/src/core-agent/test/process-session.test.ts
@@ -133,7 +133,9 @@ process.stdin.resume();`);
await tool("process_session").execute({ action: "write", session_id: sessionId, chars: "listen\n" }, ctx);
await waitForProcessRead(owner, sessionId, 0, value => value.output.includes("LISTENING"));
expect(await request()).toEqual({ status: 200, body: "local-service-ready" });
- await tool("process_session").execute({ action: "stop", session_id: sessionId }, ctx);
+ const stops = await Promise.all([0, 1].map(() =>
+ tool("process_session").execute({ action: "stop", session_id: sessionId }, ctx)));
+ expect(stops.every(result => !result.isError)).toBe(true);
expect(await request()).toEqual({ error: "ECONNREFUSED" });
});
diff --git a/src/core-agent/test/sandbox-windows-tree.test.ts b/src/core-agent/test/sandbox-windows-tree.test.ts
index 5838a9f0..1af3e39f 100644
--- a/src/core-agent/test/sandbox-windows-tree.test.ts
+++ b/src/core-agent/test/sandbox-windows-tree.test.ts
@@ -78,7 +78,7 @@ it.runIf(process.platform === "win32")("cleans up eight simultaneous deadlines w
}
}, 15_000);
-it.runIf(process.platform === "win32")("reaps a child born after the cleanup snapshot without killing an unrelated producer", async () => {
+it.runIf(process.platform === "win32").each([0, 3])("reaps a child born after the cleanup snapshot without killing an unrelated producer (extra launcher depth %s)", async (extraDepth) => {
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-late-child-"));
let root: ChildProcess | undefined;
let sibling: ChildProcess | undefined;
@@ -90,7 +90,12 @@ it.runIf(process.platform === "win32")("reaps a child born after the cleanup sna
+ "console.log('ready');setTimeout(()=>process.exit(0),10000)";
// Detached descendants model shells that do not automatically reap their
// children, while retaining real parent identities and inherited pipes.
- const rootScript = `require('child_process').spawn(process.execPath,['-e',${JSON.stringify(producerScript)}],`
+ let descendantScript = producerScript;
+ for (let depth = 0; depth < extraDepth; depth++) {
+ descendantScript = `require('child_process').spawn(process.execPath,['-e',${JSON.stringify(descendantScript)}],`
+ + "{windowsHide:true,detached:true,stdio:'inherit'});setInterval(()=>{},1000);setTimeout(()=>process.exit(0),10000)";
+ }
+ const rootScript = `require('child_process').spawn(process.execPath,['-e',${JSON.stringify(descendantScript)}],`
+ "{windowsHide:true,detached:true,stdio:'inherit'});setInterval(()=>{},1000);setTimeout(()=>process.exit(0),10000)";
sibling = spawn(node, ["-e", "console.log('ready');setInterval(()=>{},1000);setTimeout(()=>process.exit(0),10000)"], { windowsHide: true });
await new Promise<void>((resolve, reject) => {
diff --git a/src/main/features/connectors/local-cli.ts b/src/main/features/connectors/local-cli.ts
index 8be835a9..69811829 100644
--- a/src/main/features/connectors/local-cli.ts
+++ b/src/main/features/connectors/local-cli.ts
@@ -7,6 +7,7 @@
import { spawn } from 'node:child_process';
import * as crypto from 'node:crypto';
import * as fs from 'node:fs';
+import * as os from 'node:os';
import * as path from 'node:path';
import { app, shell } from 'electron';
@@ -52,6 +53,12 @@ interface LocalCliInstallRunResult {
exitCode: number | null;
stderr: string;
timedOut?: boolean;
+ spawnCode?: string;
+ signal?: string;
+}
+
+function knownSystemCode(value: unknown): string | undefined {
+ return typeof value === 'string' && Object.hasOwn(os.constants.errno, value) ? value : undefined;
}
interface LocalCliInstallRunOptions {
@@ -325,6 +332,12 @@ function runLocalCliProcess(options: LocalCliInstallRunOptions): Promise<LocalCl
let stderr = '';
let settled = false;
let timedOut = false;
+ let terminating = false;
+ let cleanupPending = false;
+ let closed = false;
+ let closeCode: number | null = null;
+ let spawnCode: string | undefined;
+ let closeSignal: string | undefined;
let timer: NodeJS.Timeout | undefined;
const child = spawn(options.command, options.args, {
cwd: options.cwd,
@@ -334,26 +347,43 @@ function runLocalCliProcess(options: LocalCliInstallRunOptions): Promise<LocalCl
detached: process.platform !== 'win32',
});
const finish = (exitCode: number | null) => {
- if (settled) return;
+ if (settled || cleanupPending) return;
settled = true;
clearTimeout(timer);
options.signal?.removeEventListener('abort', abort);
- resolve({ exitCode, stderr, timedOut });
+ resolve({ exitCode, stderr, timedOut, ...(spawnCode ? { spawnCode } : {}),
+ ...(closeSignal ? { signal: closeSignal } : {}) });
};
child.stderr?.on('data', (chunk) => {
if (stderr.length < 64 * 1024) stderr += String(chunk).slice(0, 64 * 1024 - stderr.length);
});
child.once('error', (error) => {
+ spawnCode = knownSystemCode((error as NodeJS.ErrnoException)?.code);
stderr = String(error && error.message ? error.message : error).slice(0, 64 * 1024);
finish(null);
});
- child.once('close', (code) => finish(code));
+ child.once('close', (code, signal) => {
+ closed = true;
+ closeCode = code;
+ if (signal && Object.hasOwn(os.constants.signals, signal)) closeSignal = signal;
+ finish(code);
+ });
const abort = () => {
+ if (settled || terminating) return;
+ terminating = true;
+ cleanupPending = true;
clearTimeout(timer);
- try { killProcessTree(child, 'SIGKILL'); } catch { /* child already exited */ }
- // Prefer close so Windows releases package/config file handles before cleanup.
- timer = setTimeout(() => finish(null), 3000);
+ // The root can close before the Windows helper finishes its descendant
+ // sweep. Keep ownership until that receipt and the child's close event.
+ // The helper has a five-second deadline; retain a bounded settlement tail.
+ timer = setTimeout(() => { cleanupPending = false; finish(null); }, 6000);
timer.unref?.();
+ const cleanupComplete = () => {
+ cleanupPending = false;
+ if (closed) finish(closeCode);
+ };
+ try { killProcessTree(child, 'SIGKILL', { onComplete: cleanupComplete }); }
+ catch { cleanupComplete(); }
};
options.signal?.addEventListener('abort', abort, { once: true });
timer = setTimeout(() => { timedOut = true; abort(); }, options.timeoutMs);
@@ -385,32 +415,41 @@ export function installLocalCli(
const key = `${uid}\0${entry.id}`;
const active = localCliInstallLocks.get(key);
if (active) return active;
+ // One bounded local receipt per failed install, including coalesced callers.
+ // Never retain installer output, paths, account identity or untrusted codes.
+ let phase = 'preflight';
+ let processResult: LocalCliInstallRunResult | undefined;
const task = (async () => {
const before = localCliInstallStatus(uid, entry);
if (before.installed) return before;
if (!before.runtime_ready) throw localCliError('local_cli_runtime_missing');
const runtime = resolveBackgroundNodeRuntime();
+ phase = 'proxy';
const proxyEnv = await buildChildProxyEnvironment();
+ phase = 'cache_cleanup';
const cwd = localCliRuntimeDir(uid, entry.id);
// A prior interrupted or tampered npx extraction must not poison every retry. These paths are
// fully connector-owned; credentials/config elsewhere in runtimeDir are deliberately kept.
- try { fs.rmSync(path.join(cwd, 'npm-cache', '_npx'), { recursive: true, force: true }); }
- catch { throw localCliError('local_cli_install_failed'); }
- try { fs.rmSync(path.join(cwd, '.orkas-cli-integrity.json'), { force: true }); }
- catch { throw localCliError('local_cli_install_failed'); }
+ fs.rmSync(path.join(cwd, 'npm-cache', '_npx'), { recursive: true, force: true });
+ fs.rmSync(path.join(cwd, '.orkas-cli-integrity.json'), { force: true });
+ phase = 'environment';
+ const env = buildSandboxEnv({
+ ...localCliEnv(uid, entry),
+ ...proxyEnv,
+ ORKAS_LOCAL_CLI_INSTALL_ONLY: '1',
+ });
+ phase = 'execute';
const result = await (options.runHelper || runLocalCliProcess)({
command: runtime.executable,
args: [path.join(pcDirForChild(), 'bin/local-cli-auth.cjs')],
cwd,
- env: buildSandboxEnv({
- ...localCliEnv(uid, entry),
- ...proxyEnv,
- ORKAS_LOCAL_CLI_INSTALL_ONLY: '1',
- }),
+ env,
timeoutMs: LOCAL_CLI_INSTALL_TIMEOUT_MS,
});
+ processResult = result;
if (result.timedOut || result.exitCode !== 0) throw localCliError(classifyLocalCliInstallError(result));
+ phase = 'verify';
const after = localCliInstallStatus(uid, entry);
if (!after.installed) throw localCliError('local_cli_install_failed');
return after;
@@ -418,7 +457,16 @@ export function installLocalCli(
const code = error && typeof error === 'object' && 'code' in error
? String((error as { code?: unknown }).code || '')
: '';
- throw LOCAL_CLI_INSTALL_ERROR_CODES.has(code) ? error : localCliError('local_cli_install_failed');
+ const errorCode = LOCAL_CLI_INSTALL_ERROR_CODES.has(code) ? code : 'local_cli_install_failed';
+ const systemCode = knownSystemCode(code) || knownSystemCode(processResult?.spawnCode);
+ const signal = processResult?.signal;
+ log.warn('Official CLI installation failed', {
+ provider: config.provider, phase, error_code: errorCode,
+ ...(processResult ? { exit_code: Number.isSafeInteger(processResult.exitCode) ? processResult.exitCode : null } : {}),
+ ...(systemCode ? { system_code: systemCode } : {}),
+ ...(signal && Object.hasOwn(os.constants.signals, signal) ? { signal } : {}),
+ });
+ throw LOCAL_CLI_INSTALL_ERROR_CODES.has(code) ? error : localCliError(errorCode);
}).finally(() => {
localCliInstallLocks.delete(key);
});
diff --git a/src/main/features/local_agents/backends/base.ts b/src/main/features/local_agents/backends/base.ts
index 2a3fd692..a8113437 100644
--- a/src/main/features/local_agents/backends/base.ts
+++ b/src/main/features/local_agents/backends/base.ts
@@ -501,7 +501,9 @@ function terminateCliTree(child: ChildProcessWithoutNullStreams, graceMs: number
const terminate = () => {
if (closed) { onComplete?.(); return; }
killProcessTree(child, 'SIGTERM', { onComplete });
- if (!closed) {
+ // taskkill /f is already forceful and owns its bounded fallback. A second
+ // Windows taskkill can race the first and target an already-exited root.
+ if (!closed && (process.platform !== 'win32' || !child.pid)) {
hardKill = setTimeout(() => {
hardKill = undefined;
killProcessTree(child, 'SIGKILL');
diff --git a/src/main/features/local_agents/backends/codex.ts b/src/main/features/local_agents/backends/codex.ts
index ebb8e7c2..7677a16c 100644
--- a/src/main/features/local_agents/backends/codex.ts
+++ b/src/main/features/local_agents/backends/codex.ts
@@ -41,7 +41,6 @@ import {
type LocalCliPermissionDecision,
StderrTail,
spawnCli,
- killProcessTree,
reapCliAfterProtocolTerminal,
armKillWatchdog,
LineSplitter,
@@ -1283,13 +1282,10 @@ export const codexBackend: LocalBackend = {
// A JSON-RPC setup failure resolves before the normal close-driven
// lifecycle. Explicitly terminate the detached process group so a CLI
// that keeps its event loop alive cannot outlive the failed dispatch.
- // A short hard-kill fallback also bounds teardown of an uncooperative
- // process. Submission, not a missing acknowledgement, decides replay safety.
- const hardKill = setTimeout(() => killProcessTree(child, 'SIGKILL'), 250);
- if (typeof hardKill.unref === 'function') hardKill.unref();
- child.once('close', () => clearTimeout(hardKill));
- try { child.stdin.end(); } catch { /* already closed */ }
- killProcessTree(child, 'SIGTERM');
+ // Use the existing terminal cleanup owner: on Windows EOF must wait
+ // until taskkill has traversed the live parent. POSIX retains the short
+ // escalation. Submission, not a missing acknowledgement, decides replay safety.
+ reapCliAfterProtocolTerminal(child, 250);
finish('failed', {
error,
stderrTail: tail.toString(),
diff --git a/src/main/util/renderer-channel.ts b/src/main/util/renderer-channel.ts
index 980ef66f..01d4e4a7 100644
--- a/src/main/util/renderer-channel.ts
+++ b/src/main/util/renderer-channel.ts
@@ -1,8 +1,8 @@
/**
* Renderer notification channel with a bounded replay buffer.
*
- * Main-process events that the renderer must see (telemetry rows, task
- * terminal projections, update notices) are emitted while the window may
+ * Main-process events that the renderer must see (task terminal
+ * projections and product notices) are emitted while the window may
* be loading, reloading or gone. Each channel keeps the rows it could not
* deliver and replays them on the next `flush()` (the window's
* `did-finish-load`), newest-`maxPending` only.
@@ -39,6 +39,7 @@ export type RendererChannelOptions = {
};
export type RendererChannel = {
+ clear: () => void;
readonly channel: string;
/** Deliver now or buffer. `ownerUserId` is required on owner-scoped channels. */
emit: (payload: unknown, ownerUserId?: string) => void;
@@ -90,5 +91,6 @@ export function createRendererChannel(
}
};
- return { channel, emit, flush, pending: () => pending.length };
+ return { channel, emit, flush, pending: () => pending.length,
+ clear: () => { pending.length = 0; } };
}
diff --git a/src/main/util/shutdown.ts b/src/main/util/shutdown.ts
index 7c6fb98c..c4b9aa28 100644
--- a/src/main/util/shutdown.ts
+++ b/src/main/util/shutdown.ts
@@ -1,29 +1,77 @@
-interface ShutdownTask {
+export interface ShutdownTask {
name: string;
run: () => void | Promise<void>;
}
-/** Start and await each local durability task exactly once before exit. */
-export function createShutdownCoordinator({ localTasks, onFailure }: {
+export interface ShutdownProcesses {
+ terminate(): Promise<void>;
+ dispose(): void;
+}
+
+/** Archive active work before closing dependencies and owned processes. */
+export function createShutdownCoordinator({ captureProcesses, quiesce, localTasks, onFailure, onIncomplete }: {
+ captureProcesses?: () => Promise<ShutdownProcesses>;
+ quiesce?: () => Promise<void>;
localTasks: readonly ShutdownTask[];
onFailure: (name: string) => void;
+ onIncomplete?: () => void | Promise<void>;
}) {
let pending: Promise<void> | null = null;
let complete = false;
+ let quiescent = false;
const run = async (task: ShutdownTask) => {
try { await task.run(); }
catch { onFailure(task.name); }
};
return {
get complete() { return complete; },
- prepare(): Promise<void> {
+ get quiescent() { return quiescent; },
+ prepare(mode: 'quit' | 'relaunch' = 'quit'): Promise<void> {
if (pending) return pending;
// Publish the shared promise before any cleanup can synchronously emit
// another quit (for example while Electron loads a native module).
+ quiescent = false;
pending = Promise.resolve().then(async () => {
- // Start every local save/close even if another one is slow or fails.
- await Promise.all(localTasks.map(run));
- }).finally(() => { complete = true; });
+ let processes: ShutdownProcesses | undefined;
+ try {
+ // Pin descendants while their parents still exist. Development's
+ // detached replacement launcher belongs to the next app lifetime.
+ if (mode !== 'relaunch' && captureProcesses) {
+ try { processes = await captureProcesses(); }
+ catch (cause) {
+ throw Object.assign(new Error('Process shutdown preparation failed', { cause }), {
+ code: 'E_SHUTDOWN_PROCESSES_FAILED',
+ });
+ }
+ }
+ // Active tasks still own these dependencies. Failure to archive is
+ // critical: leave the app open so the same quit can be retried.
+ try { if (quiesce) await quiesce(); }
+ catch (cause) {
+ throw Object.assign(new Error('Active task archival failed', { cause }), {
+ code: 'E_SHUTDOWN_ARCHIVE_FAILED',
+ });
+ }
+ quiescent = true;
+ // Start every local save/close even if another one is slow or fails.
+ await Promise.all(localTasks.map(run));
+ try { await processes?.terminate(); }
+ catch (cause) {
+ throw Object.assign(new Error('Owned processes could not be stopped', { cause }), {
+ code: 'E_SHUTDOWN_PROCESSES_FAILED',
+ });
+ }
+ complete = true;
+ } finally { processes?.dispose(); }
+ }).catch(async (error) => {
+ quiescent = false;
+ // A failed exit leaves the application open. Re-admit new work only
+ // after this attempt has finished disposing its old dependencies.
+ try { await onIncomplete?.(); }
+ catch { onFailure('resume'); }
+ pending = null;
+ throw error;
+ });
return pending;
},
};
diff --git a/src/main/util/windows-shutdown-processes.ts b/src/main/util/windows-shutdown-processes.ts
new file mode 100644
index 00000000..3ce9570e
--- /dev/null
+++ b/src/main/util/windows-shutdown-processes.ts
@@ -0,0 +1,213 @@
+import { spawn } from 'node:child_process';
+import * as path from 'node:path';
+import type { ShutdownProcesses } from './shutdown';
+
+const DEADLINE_MS = 15_000;
+const appCaptures = new Set<ReadonlySet<number>>();
+
+/** Reuse only a snapshot that already pinned this specific connector root. */
+export function hasCapturedWindowsAppProcess(pid: number): boolean {
+ for (const captured of appCaptures) if (captured.has(pid)) return true;
+ return false;
+}
+
+/**
+ * A short-lived Windows helper holds process handles before graceful shutdown
+ * can orphan children. It only terminates descendants of this app instance,
+ * never processes selected by executable name or installation-directory prefix.
+ * The installer is launched after this helper has exited.
+ */
+export async function captureWindowsShutdownProcesses(
+ platform: NodeJS.Platform = process.platform,
+ ownerPid = process.pid,
+ spawnProcess: typeof spawn = spawn,
+): Promise<ShutdownProcesses> {
+ if (platform !== 'win32') return { terminate: async () => {}, dispose() {} };
+ if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0) throw new Error('Invalid shutdown owner');
+ const root = process.env.SystemRoot || 'C:\\Windows';
+ const child = spawnProcess(
+ path.win32.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+ ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand',
+ Buffer.from(`$ownerProcessId = ${ownerPid}\n$reportOwned = $${ownerPid === process.pid}\n${SCRIPT}`, 'utf16le').toString('base64')],
+ { windowsHide: true, stdio: ['pipe', 'pipe', 'ignore'] },
+ );
+ let ready = false;
+ let finished = false;
+ let failed = false;
+ let registered: ReadonlySet<number> | undefined;
+ const unregister = () => {
+ if (registered) { appCaptures.delete(registered); registered = undefined; }
+ };
+ let output = '';
+ let resolveReady!: () => void;
+ let rejectReady!: (error: Error) => void;
+ let resolveExit!: () => void;
+ let rejectExit!: (error: Error) => void;
+ const prepared = new Promise<void>((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+ const exited = new Promise<void>((resolve, reject) => { resolveExit = resolve; rejectExit = reject; });
+ // The helper can fail while the app is still flushing local state.
+ void exited.catch(() => {});
+ const fail = () => {
+ failed = true;
+ unregister();
+ const error = new Error('Windows process cleanup failed');
+ rejectReady(error);
+ rejectExit(error);
+ };
+ child.on('error', fail);
+ child.stdin!.on('error', fail);
+ child.stdout!.on('data', (chunk: Buffer) => {
+ output += chunk.toString('utf8');
+ if (output.length > (ownerPid === process.pid ? 65_536 : 64)) { fail(); child.kill(); return; }
+ if (output.includes('ready\n') || output.includes('ready\r\n')) {
+ ready = true;
+ resolveReady();
+ }
+ });
+ child.once('exit', (code) => {
+ finished = true;
+ unregister();
+ if (ready && code === 0) resolveExit();
+ else fail();
+ });
+ const bounded = async (work: Promise<void>) => {
+ let timer: NodeJS.Timeout | undefined;
+ try {
+ await Promise.race([work, new Promise<never>((_, reject) => {
+ timer = setTimeout(() => {
+ child.kill();
+ reject(new Error('Windows process cleanup timed out'));
+ }, DEADLINE_MS);
+ })]);
+ } finally { if (timer) clearTimeout(timer); }
+ };
+ const dispose = () => {
+ unregister();
+ if (!finished) child.kill();
+ };
+ try { await bounded(prepared); }
+ catch (error) { dispose(); throw error; }
+ if (!finished && !failed && ownerPid === process.pid) {
+ // The helper pins at most 4096 process handles. Unknown/late roots need
+ // their own capture; an app-wide snapshot is not continuous supervision.
+ const record = /^owned:([0-9,]+)\r?$/m.exec(output);
+ const ids = record?.[1].split(',').map(Number);
+ if (!ids || ids.length > 4096 || !ids.includes(ownerPid)
+ || ids.some(id => !Number.isSafeInteger(id) || id <= 0)) {
+ dispose();
+ throw new Error('Windows process snapshot is invalid');
+ }
+ registered = new Set(ids);
+ appCaptures.add(registered);
+ }
+ return {
+ async terminate() {
+ if (finished) throw new Error('Windows process cleanup ended before handoff');
+ child.stdin!.end('stop\n');
+ await bounded(exited);
+ },
+ dispose,
+ };
+}
+
+// Use .NET/WMI directly: no optional modules, shell interpolation of paths,
+// native dependencies, or user data in the helper protocol.
+const SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$owned = @{}
+$ordered = [Collections.Generic.List[object]]::new()
+$result = 1
+function Capture-Descendants {
+ $since = [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($owned[$ownerProcessId].Started)
+ $query = [System.Management.ManagementObjectSearcher]::new("SELECT ProcessId,ParentProcessId,CreationDate,ExecutablePath,CommandLine FROM Win32_Process WHERE CreationDate >= '$since'")
+ $rows = [Collections.Generic.List[object]]::new()
+ $found = $null
+ try {
+ $found = $query.Get()
+ foreach ($row in $found) {
+ try {
+ $rows.Add([pscustomobject]@{
+ Id = [int]$row.ProcessId
+ Parent = [int]$row.ParentProcessId
+ Started = [System.Management.ManagementDateTimeConverter]::ToDateTime([string]$row.CreationDate).ToUniversalTime()
+ Electron = [string]::Equals([string]$row.ExecutablePath, $rootExecutable, [StringComparison]::OrdinalIgnoreCase) -and
+ ([string]$row.CommandLine -match '(?:^|\s)--type=[a-z-]+(?:\s|$)')
+ })
+ } finally { $row.Dispose() }
+ if ($rows.Count -gt 16384) { throw 'snapshot_limit' }
+ }
+ } finally {
+ if ($null -ne $found) { $found.Dispose() }
+ $query.Dispose()
+ }
+ $children = @{}
+ foreach ($row in $rows) {
+ if (-not $children.ContainsKey($row.Parent)) { $children[$row.Parent] = [Collections.Generic.List[object]]::new() }
+ $children[$row.Parent].Add($row)
+ }
+ $queue = [Collections.Generic.List[int]]::new()
+ foreach ($id in $owned.Keys) { $queue.Add($id) }
+ for ($index = 0; $index -lt $queue.Count; $index++) {
+ foreach ($row in $children[$queue[$index]]) {
+ $id = $row.Id
+ $parent = $owned[$row.Parent]
+ if ($id -eq $PID -or $owned.ContainsKey($id) -or $null -eq $parent) { continue }
+ if ($row.Started -lt $parent.Started) { continue }
+ $candidate = $null
+ try {
+ $candidate = [Diagnostics.Process]::GetProcessById($id)
+ $null = $candidate.Handle
+ $started = $candidate.StartTime.ToUniversalTime()
+ # WMI truncates creation time to microseconds. Reject a recycled PID.
+ if (($started.Ticks - ($started.Ticks % 10)) -ne $row.Started.Ticks) { continue }
+ if ($owned.Count -ge 4096) { throw 'descendant_limit' }
+ $entry = @{ Process = $candidate; Started = $started; Electron = $row.Electron }
+ $owned[$id] = $entry
+ $ordered.Add($entry)
+ $candidate = $null
+ $queue.Add($id)
+ } catch [ArgumentException] {
+ # The candidate exited between the snapshot and opening its handle.
+ } finally {
+ if ($null -ne $candidate) { $candidate.Dispose() }
+ }
+ }
+ }
+}
+try {
+ $root = [Diagnostics.Process]::GetProcessById($ownerProcessId)
+ $null = $root.Handle
+ $rootExecutable = $root.MainModule.FileName
+ $owned[$ownerProcessId] = @{ Process = $root; Started = $root.StartTime.ToUniversalTime() }
+ $null = Capture-Descendants
+ if ($reportOwned) { [Console]::Out.WriteLine('owned:' + ($owned.Keys -join ',')) }
+ [Console]::Out.WriteLine('ready')
+ [Console]::Out.Flush()
+ if ([Console]::In.ReadLine() -cne 'stop') { return }
+ for ($pass = 0; $pass -lt 4; $pass++) {
+ $null = Capture-Descendants
+ # Keep handles open across all passes, including exited parents, so late
+ # grandchildren cannot escape merely by being reparented during cleanup.
+ foreach ($entry in $ordered) {
+ # Electron owns the renderer/GPU/utility exit. Keep the UI alive if a
+ # helper cannot be stopped; app.quit closes it after successful handoff.
+ # Electron-as-Node helpers have no Chromium --type flag and are swept.
+ if ($entry.Electron) { continue }
+ try {
+ if (-not $entry.Process.HasExited) { $entry.Process.Kill() }
+ if (-not $entry.Process.WaitForExit(500)) { throw 'termination_incomplete' }
+ } catch {
+ if (-not $entry.Process.HasExited) { throw }
+ }
+ }
+ $null = Capture-Descendants
+ $alive = @($ordered | Where-Object { -not $_.Electron -and -not $_.Process.HasExited })
+ if ($alive.Count -eq 0) { $result = 0; break }
+ }
+} catch {
+ $result = 1
+} finally {
+ foreach ($entry in $owned.Values) { $entry.Process.Dispose() }
+}
+exit $result
+`;
diff --git a/test/helpers/windows-shutdown-scenario.ts b/test/helpers/windows-shutdown-scenario.ts
new file mode 100644
index 00000000..4dbe68d5
--- /dev/null
+++ b/test/helpers/windows-shutdown-scenario.ts
@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { captureWindowsShutdownProcesses } from '../../src/main/util/windows-shutdown-processes';
+
+/**
+ * Shared by Vitest's Windows lane and a dependency-free bundle for remote
+ * verification. Assertions use actual process liveness and file replacement,
+ * so a helper reporting success without releasing resources cannot pass.
+ */
+export async function exerciseWindowsShutdown(
+ node: string,
+ capture = captureWindowsShutdownProcesses,
+) {
+ assert.equal(process.platform, 'win32', 'This scenario requires native Windows');
+ assert.ok(node, 'A stock Node executable is required');
+ const directory = await mkdtemp(join(tmpdir(), 'Orkas shutdown 测试 '));
+ const lockedFile = join(directory, 'runtime.dll');
+ const replacement = join(directory, 'replacement.dll');
+ await writeFile(lockedFile, 'old version');
+ await writeFile(replacement, 'new version');
+ const stderr: string[] = [];
+ const launch = (code: string) => {
+ const child = spawn(node, ['-e', code], {
+ stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
+ env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined, ORKAS_SHUTDOWN_LOCK_FILE: lockedFile },
+ });
+ child.stderr!.on('data', chunk => { stderr.push(String(chunk)); });
+ return child;
+ };
+ // Fixtures also expire if the surrounding test process is interrupted.
+ const sleeper = 'setTimeout(() => {}, 90000)';
+ const branchCode = `const {spawn}=require('node:child_process');
+ const child=spawn(process.execPath,['-e',${JSON.stringify(sleeper)}],{stdio:'ignore',windowsHide:true});
+ console.log(child.pid);setTimeout(()=>{},90000);`;
+ const lockScript = `$ErrorActionPreference='Stop'
+ $file=[IO.File]::Open($env:ORKAS_SHUTDOWN_LOCK_FILE,[IO.FileMode]::Open,[IO.FileAccess]::ReadWrite,[IO.FileShare]::None)
+ try { [Console]::Out.WriteLine('locked'); [Console]::Out.Flush(); [Threading.Thread]::Sleep(90000) }
+ finally { $file.Dispose() }`;
+ const rootCode = `const {spawn}=require('node:child_process');
+ const {join}=require('node:path');
+ require('node:readline').createInterface({input:process.stdin}).on('line',command=>{
+ const lock=command==='lock';
+ const child=spawn(lock ? join(process.env.SystemRoot,'System32','WindowsPowerShell','v1.0','powershell.exe') : process.execPath,
+ lock ? ['-NoLogo','-NoProfile','-NonInteractive','-EncodedCommand',${JSON.stringify(Buffer.from(lockScript, 'utf16le').toString('base64'))}]
+ : ['-e',${JSON.stringify(branchCode)}],
+ {stdio:['ignore','pipe','pipe'],windowsHide:true});
+ child.stderr.pipe(process.stderr);
+ child.stdout.once('data',data=>console.log(JSON.stringify({parent:child.pid,child:lock?null:Number(String(data).trim())})));
+ });setTimeout(()=>process.exit(),90000);`;
+ const owner = launch(rootCode);
+ const other = launch(sleeper);
+ const ownedPids: number[] = [];
+ let processes: Awaited<ReturnType<typeof capture>> | undefined;
+ const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+ const waitForExit = async (pid: number) => {
+ for (let attempt = 0; attempt < 100 && alive(pid); attempt++) await delay(30);
+ assert.equal(alive(pid), false, 'Fixture process did not exit');
+ };
+ const request = async (command: string) => {
+ const line = once(owner.stdout!, 'data', { signal: AbortSignal.timeout(10_000) });
+ owner.stdin!.write(`${command}\n`);
+ const [bytes] = await line;
+ const result = JSON.parse(String(bytes).trim()) as { parent: number; child: number | null };
+ ownedPids.push(result.parent);
+ if (result.child) ownedPids.push(result.child);
+ return result;
+ };
+ const stop = async (child: ChildProcess) => {
+ if (child.exitCode !== null || child.signalCode !== null) return;
+ const exited = once(child, 'close', { signal: AbortSignal.timeout(5_000) });
+ child.kill();
+ await exited;
+ };
+ try {
+ const early = await request('branch');
+ await request('lock');
+ // Negative control: prove the fixture really prevents replacement.
+ await assert.rejects(rename(replacement, lockedFile), { code: 'EPERM' });
+ processes = await capture('win32', owner.pid!);
+ processes.dispose();
+ for (const pid of ownedPids) assert.equal(alive(pid), true, 'Cancelling shutdown killed active work');
+ await assert.rejects(rename(replacement, lockedFile), { code: 'EPERM' });
+
+ // Retry after cancellation, then orphan a child during graceful shutdown.
+ processes = await capture('win32', owner.pid!);
+ process.kill(early.parent);
+ await waitForExit(early.parent);
+ assert.equal(alive(early.child!), true, 'The orphan fixture exited before cleanup');
+ await request('branch');
+ await processes.terminate();
+ for (const pid of ownedPids) assert.equal(alive(pid), false, 'Owned descendant remains alive');
+ assert.equal(alive(owner.pid!), true, 'Cleanup terminated the owner before handoff');
+ assert.equal(alive(other.pid!), true, 'Cleanup terminated an unrelated Node process');
+ await rename(replacement, lockedFile);
+ assert.equal(await readFile(lockedFile, 'utf8'), 'new version', 'Installer could not replace the locked file');
+ return { descendants: ownedPids.length, cancellationPreservedWork: true, fileReplaced: true, ownerPreserved: true, unrelatedPreserved: true };
+ } finally {
+ processes?.dispose();
+ for (const pid of ownedPids) { try { process.kill(pid); } catch { /* already exited */ } }
+ await Promise.all([stop(owner), stop(other)]);
+ for (const pid of ownedPids) await waitForExit(pid);
+ await rm(directory, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+ assert.equal(stderr.join(''), '', 'Fixture emitted unexpected stderr');
+ }
+}
diff --git a/test/main/features/connectors/local-cli.test.ts b/test/main/features/connectors/local-cli.test.ts
index da840c64..44a14ff4 100644
--- a/test/main/features/connectors/local-cli.test.ts
+++ b/test/main/features/connectors/local-cli.test.ts
@@ -851,10 +851,121 @@ describe('official local CLI connector runtime', () => {
bundledRuntime.node = previousNode;
vi.unstubAllEnvs();
fs.rmSync(runtimeDir, { recursive: true, force: true });
+ // Remove the directory link itself before recursive Windows cleanup;
+ // the selected runtime belongs to the host, outside this fixture.
+ fs.unlinkSync(nodeDir);
fs.rmSync(fixture, { recursive: true, force: true });
}
});
+ it('records one private-data-free install receipt for coalesced failures and permits a clean retry', async () => {
+ const entry = findCatalogEntry('wecom')!;
+ const uid = 'install-failure-receipt';
+ const runtimeDir = localCliRuntimeDir(uid, entry.id);
+ diagnostics.warn.mockClear();
+ let release!: () => void;
+ const pending = new Promise<void>(resolve => { release = resolve; });
+ const runner = vi.fn(async () => {
+ await pending;
+ return { exitCode: 127, stderr: 'private account token and /private/installer/path',
+ spawnCode: 'private-untrusted-code', signal: 'private-untrusted-signal' };
+ });
+ try {
+ const first = installLocalCli(uid, entry, { runHelper: runner });
+ const duplicate = installLocalCli(uid, entry, { runHelper: runner });
+ expect(duplicate).toBe(first);
+ release();
+ await expect(first).rejects.toMatchObject({ code: 'local_cli_install_failed' });
+ expect(runner).toHaveBeenCalledOnce();
+ expect(diagnostics.warn).toHaveBeenCalledExactlyOnceWith('Official CLI installation failed', {
+ provider: 'wecom', phase: 'execute', error_code: 'local_cli_install_failed', exit_code: 127,
+ });
+ expect(localCliInstallStatus(uid, entry).installed).toBe(false);
+ await expect(installLocalCli(uid, entry, { runHelper: async () => {
+ seedInstalled(uid, entry);
+ return { exitCode: 0, stderr: '' };
+ } })).resolves.toMatchObject({ installed: true });
+ expect(diagnostics.warn).toHaveBeenCalledOnce();
+ } finally { fs.rmSync(runtimeDir, { recursive: true, force: true }); }
+ });
+
+ it('distinguishes an installation postcheck failure from a successful helper exit', async () => {
+ const entry = findCatalogEntry('wecom')!;
+ const uid = 'install-postcheck-receipt';
+ diagnostics.warn.mockClear();
+ try {
+ await expect(installLocalCli(uid, entry, { runHelper: async () => ({ exitCode: 0, stderr: '' }) }))
+ .rejects.toMatchObject({ code: 'local_cli_install_failed' });
+ expect(diagnostics.warn).toHaveBeenCalledExactlyOnceWith('Official CLI installation failed', {
+ provider: 'wecom', phase: 'verify', error_code: 'local_cli_install_failed', exit_code: 0,
+ });
+ expect(localCliInstallStatus(uid, entry).installed).toBe(false);
+ } finally { fs.rmSync(localCliRuntimeDir(uid, entry.id), { recursive: true, force: true }); }
+ });
+
+ it.each(['ENOENT', 'private-untrusted-code'])('keeps only a known OS spawn code for %s', async code => {
+ const entry = findCatalogEntry('wecom')!;
+ const uid = 'install-spawn-receipt';
+ diagnostics.warn.mockClear();
+ vi.mocked(spawn).mockImplementationOnce(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit('error', Object.assign(new Error('private spawn path'), { code })));
+ return child as ReturnType<typeof spawn>;
+ });
+ try {
+ await expect(installLocalCli(uid, entry)).rejects.toMatchObject({ code: 'local_cli_install_failed' });
+ expect(diagnostics.warn).toHaveBeenCalledExactlyOnceWith('Official CLI installation failed', {
+ provider: 'wecom', phase: 'execute', error_code: 'local_cli_install_failed', exit_code: null,
+ ...(code === 'ENOENT' ? { system_code: 'ENOENT' } : {}),
+ });
+ expect(localCliInstallStatus(uid, entry).installed).toBe(false);
+ } finally { fs.rmSync(localCliRuntimeDir(uid, entry.id), { recursive: true, force: true }); }
+ });
+
+ it.each(['SIGTERM', 'private-untrusted-signal'])('retains only a known termination signal for %s', async signal => {
+ const entry = findCatalogEntry('wecom')!;
+ const uid = 'install-signal-receipt';
+ diagnostics.warn.mockClear();
+ vi.mocked(spawn).mockImplementationOnce(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit('close', null, signal));
+ return child as ReturnType<typeof spawn>;
+ });
+ try {
+ await expect(installLocalCli(uid, entry)).rejects.toMatchObject({ code: 'local_cli_install_failed' });
+ expect(diagnostics.warn).toHaveBeenCalledExactlyOnceWith('Official CLI installation failed', {
+ provider: 'wecom', phase: 'execute', error_code: 'local_cli_install_failed', exit_code: null,
+ ...(signal === 'SIGTERM' ? { signal } : {}),
+ });
+ expect(localCliInstallStatus(uid, entry).installed).toBe(false);
+ } finally { fs.rmSync(localCliRuntimeDir(uid, entry.id), { recursive: true, force: true }); }
+ });
+
+ it('records an invalid cache layout without starting an installer or deleting existing credentials', async () => {
+ const entry = findCatalogEntry('wecom')!;
+ const uid = 'install-cleanup-receipt';
+ const runtime = localCliRuntimeDir(uid, entry.id);
+ fs.mkdirSync(runtime, { recursive: true });
+ const credentials = path.join(runtime, 'credentials.json');
+ fs.writeFileSync(credentials, 'preserve-existing-credentials');
+ // An invalid marker directory cannot be removed by the file-only cleanup.
+ // Unlike ENOTDIR under force=true, this is stable across Node versions.
+ const marker = path.join(runtime, '.orkas-cli-integrity.json');
+ fs.mkdirSync(marker);
+ fs.writeFileSync(path.join(marker, 'preserve'), 'invalid-marker-layout');
+ const runner = vi.fn();
+ diagnostics.warn.mockClear();
+ try {
+ await expect(installLocalCli(uid, entry, { runHelper: runner }))
+ .rejects.toMatchObject({ code: 'local_cli_install_failed' });
+ expect(runner).not.toHaveBeenCalled();
+ expect(diagnostics.warn).toHaveBeenCalledExactlyOnceWith('Official CLI installation failed', {
+ provider: 'wecom', phase: 'cache_cleanup', error_code: 'local_cli_install_failed',
+ });
+ expect(fs.readFileSync(credentials, 'utf8')).toBe('preserve-existing-credentials');
+ } finally { fs.rmSync(runtime, { recursive: true, force: true }); }
+ });
+
it('maps registry verification failures to a stable renderer-safe install code', async () => {
const entry = findCatalogEntry('wecom');
expect(entry).toBeTruthy();
diff --git a/test/main/util/shutdown.test.ts b/test/main/util/shutdown.test.ts
index 7225f1e4..e953c317 100644
--- a/test/main/util/shutdown.test.ts
+++ b/test/main/util/shutdown.test.ts
@@ -1,4 +1,8 @@
import { describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as vm from 'node:vm';
+import * as ts from 'typescript';
import { createShutdownCoordinator } from '../../../src/main/util/shutdown';
function gate() {
@@ -8,6 +12,194 @@ function gate() {
}
describe('application shutdown durability and latency', () => {
+ it('restores admission only after failed shutdown cleanup and before allowing retry', async () => {
+ const events: string[] = [];
+ const terminate = vi.fn().mockRejectedValueOnce(new Error('controlled failure')).mockResolvedValue(undefined);
+ const shutdown = createShutdownCoordinator({
+ captureProcesses: async () => ({ terminate, dispose: () => { events.push('disposed'); } }),
+ quiesce: async () => { events.push('stopped'); },
+ localTasks: [{ name: 'close', run: () => { events.push('closed'); } }],
+ onFailure: vi.fn(),
+ onIncomplete: async () => { events.push('resumed'); },
+ });
+ await expect(shutdown.prepare()).rejects.toMatchObject({ code: 'E_SHUTDOWN_PROCESSES_FAILED' });
+ expect(events).toEqual(['stopped', 'closed', 'disposed', 'resumed']);
+ await shutdown.prepare();
+ expect(shutdown.complete).toBe(true);
+ expect(events.filter(e => e === 'resumed')).toHaveLength(1);
+ });
+ it.each(['quit', 'relaunch'] as const)('runs the real app shutdown wiring for CLI, Office, workers and browser persistence: %s', async mode => {
+ // Execute the production composition without booting Electron or touching
+ // a real account. This catches an omitted owner in index.ts, not just a
+ // correctly behaving coordinator used with a test-only list of owners.
+ const source = fs.readFileSync(path.resolve('src/main/index.ts'), 'utf8');
+ const parsed = ts.createSourceFile('index.ts', source, ts.ScriptTarget.Latest, true);
+ const compositions: string[] = [];
+ const visit = (node: ts.Node) => {
+ if (ts.isCallExpression(node) && node.expression.getText(parsed) === 'createShutdownCoordinator') compositions.push(node.getText(parsed));
+ ts.forEachChild(node, visit);
+ };
+ visit(parsed);
+ expect(compositions).toHaveLength(1);
+ const archived = gate();
+ const browserSaved = gate();
+ const lifecycleSaved = gate();
+ const appDataDrained = gate();
+ const exited = gate();
+ const events: string[] = [];
+ const mark = (name: string) => () => { events.push(name); };
+ const dependencies: Record<string, unknown> = {
+ './util/boot_init': { stopBootWork: mark('boot-work') },
+ './features/library_corpus': { closeAllLibraryCorpora: mark('library-owners') },
+ './features/local_agents/runner.js': { stopBackgroundRuns: mark('background-cli') },
+ './features/kb_vector': { closeAllKb: mark('kb-database') },
+ './features/kb_embed': { closeEmbedder: mark('embed-worker') },
+ './util/sharp-runtime': { closeImageRuntime: mark('image-worker') },
+ './util/office-extract': { closeOfficeExtraction: mark('office-extract') },
+ './features/office/office_engine': { closeAllOfficeResidents: mark('office') },
+ './features/web_assist_session': { flushWebAssistSessions: () => { events.push('browser-save'); return browserSaved.promise; } },
+ './features/web_apps/host': { runtime: {
+ closeUser: (uid: string) => { expect(uid).toBe('isolated-owner'); events.push('app-close'); },
+ drainData: () => { events.push('app-databases'); return appDataDrained.promise; },
+ } },
+ };
+ const mod = { exports: {} as ReturnType<typeof createShutdownCoordinator> };
+ vm.runInNewContext(ts.transpileModule(`module.exports = ${compositions[0]};`, {
+ compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+ }).outputText, {
+ module: mod, createShutdownCoordinator,
+ require: (name: string) => { if (!(name in dependencies)) throw new Error(`Uncontrolled shutdown dependency: ${name}`); return dependencies[name]; },
+ captureWindowsShutdownProcesses: async () => {
+ events.push('capture');
+ return { terminate: () => { events.push('terminate'); return exited.promise; }, dispose: mark('dispose') };
+ },
+ prepareForShutdown: () => { events.push('archive'); return archived.promise; },
+ connectorsFeature: { shutdown: mark('connectors') },
+ searchFeature: { flushAll: mark('search-workers') },
+ openLifecycleTracking: { flushQuit: () => { events.push('open-lifecycle'); return lifecycleSaved.promise; } },
+ users: { getActiveUserId: () => 'isolated-owner' },
+ createLogger: (name: string) => ({ warn: mark(`failure:${name}`) }),
+ });
+ const shutdown = mod.exports;
+ const pending = shutdown.prepare(mode);
+ expect(shutdown.prepare(mode)).toBe(pending);
+ await vi.waitFor(() => expect(events).toContain('background-cli'));
+ expect(events).toEqual(mode === 'quit' ? ['capture', 'archive', 'background-cli'] : ['archive', 'background-cli']);
+ archived.release();
+ await vi.waitFor(() => expect(events).toContain('browser-save'));
+ expect(events.indexOf('library-owners')).toBeLessThan(events.indexOf('kb-database'));
+ expect(events.indexOf('library-owners')).toBeLessThan(events.indexOf('embed-worker'));
+ expect(events.indexOf('boot-work')).toBeLessThan(events.indexOf('library-owners'));
+ expect(events).not.toContain('terminate');
+ expect(shutdown.complete).toBe(false);
+ browserSaved.release();
+ await Promise.resolve();
+ expect(shutdown.complete).toBe(false);
+ expect(events).not.toContain('terminate');
+ lifecycleSaved.release();
+ await Promise.resolve();
+ expect(shutdown.complete).toBe(false);
+ expect(events).not.toContain('terminate');
+ expect(events.indexOf('app-close')).toBeLessThan(events.indexOf('app-databases'));
+ appDataDrained.release();
+ if (mode === 'quit') {
+ await vi.waitFor(() => expect(events).toContain('terminate'));
+ expect(shutdown.complete).toBe(false);
+ expect(events.indexOf('app-databases')).toBeLessThan(events.indexOf('terminate'));
+ expect(events.indexOf('open-lifecycle')).toBeLessThan(events.indexOf('terminate'));
+ exited.release();
+ }
+ await pending;
+ const owners = ['archive', 'background-cli', 'boot-work', 'library-owners', 'connectors', 'search-workers', 'kb-database', 'embed-worker', 'image-worker', 'office-extract', 'office', 'browser-save', 'open-lifecycle', 'app-close', 'app-databases'];
+ expect([...events].sort()).toEqual([...owners, ...(mode === 'quit' ? ['capture', 'terminate', 'dispose'] : [])].sort());
+ expect(shutdown.complete).toBe(true);
+ });
+
+ it('pins owned processes before stopping producers and confirms their exit before installer handoff', async () => {
+ const exited = gate();
+ const order: string[] = [];
+ const shutdown = createShutdownCoordinator({
+ captureProcesses: async () => {
+ order.push('capture');
+ return { terminate: async () => { order.push('terminate'); await exited.promise; }, dispose: () => { order.push('dispose'); } };
+ },
+ quiesce: async () => { order.push('archive'); },
+ localTasks: [{ name: 'connectors', run: () => { order.push('connectors'); } }],
+ onFailure: vi.fn(),
+ });
+ const pending = shutdown.prepare();
+ await vi.waitFor(() => expect(order).toContain('terminate'));
+ expect(order).toEqual(['capture', 'archive', 'connectors', 'terminate']);
+ expect(shutdown.complete).toBe(false);
+ exited.release();
+ await pending;
+ expect(shutdown.complete).toBe(true);
+ expect(order.at(-1)).toBe('dispose');
+ });
+
+ it.each(['capture', 'terminate'])('blocks handoff after a process %s failure and allows a successful retry', async phase => {
+ const dispose = vi.fn();
+ const terminate = vi.fn().mockResolvedValue(undefined);
+ if (phase === 'terminate') terminate.mockRejectedValueOnce(new Error('access denied'));
+ const captureProcesses = vi.fn().mockResolvedValue({ terminate, dispose });
+ if (phase === 'capture') captureProcesses.mockRejectedValueOnce(new Error('PowerShell unavailable'));
+ const archive = vi.fn();
+ const shutdown = createShutdownCoordinator({
+ captureProcesses, quiesce: archive,
+ localTasks: [], onFailure: vi.fn(),
+ });
+ await expect(shutdown.prepare()).rejects.toMatchObject({ code: 'E_SHUTDOWN_PROCESSES_FAILED' });
+ expect(shutdown.complete).toBe(false);
+ expect(archive).toHaveBeenCalledTimes(phase === 'capture' ? 0 : 1);
+ expect(dispose).toHaveBeenCalledTimes(phase === 'capture' ? 0 : 1);
+ await shutdown.prepare();
+ expect(shutdown.complete).toBe(true);
+ expect(captureProcesses).toHaveBeenCalledTimes(2);
+ expect(terminate).toHaveBeenCalledTimes(phase === 'capture' ? 1 : 2);
+ expect(dispose).toHaveBeenCalledTimes(phase === 'capture' ? 1 : 2);
+ });
+
+ it('releases process identities without killing work when archival fails', async () => {
+ const terminate = vi.fn();
+ const dispose = vi.fn();
+ const shutdown = createShutdownCoordinator({
+ captureProcesses: async () => ({ terminate, dispose }),
+ quiesce: async () => { throw new Error('save failed'); },
+ localTasks: [], onFailure: vi.fn(),
+ });
+ await expect(shutdown.prepare()).rejects.toMatchObject({ code: 'E_SHUTDOWN_ARCHIVE_FAILED' });
+ expect(terminate).not.toHaveBeenCalled();
+ expect(dispose).toHaveBeenCalledOnce();
+ });
+
+ it('archives active work before closing dependencies', async () => {
+ const archived = gate();
+ const order: string[] = [];
+ const shutdown = createShutdownCoordinator({
+ quiesce: async () => { order.push('stop'); await archived.promise; order.push('archived'); },
+ localTasks: [{ name: 'office', run: () => { order.push('office'); } }],
+ onFailure: vi.fn(),
+ });
+ const pending = shutdown.prepare();
+ await Promise.resolve();
+ expect(order).toEqual(['stop']);
+ archived.release();
+ await pending;
+ expect(order).toEqual(['stop', 'archived', 'office']);
+ });
+
+ it('keeps exit incomplete after an archival failure and retries without closing dependencies', async () => {
+ const quiesce = vi.fn().mockRejectedValueOnce(new Error('controlled save failure')).mockResolvedValue(undefined);
+ const close = vi.fn();
+ const shutdown = createShutdownCoordinator({ quiesce, localTasks: [{ name: 'office', run: close }], onFailure: vi.fn() });
+ await expect(shutdown.prepare()).rejects.toMatchObject({ code: 'E_SHUTDOWN_ARCHIVE_FAILED', cause: new Error('controlled save failure') });
+ expect(shutdown.complete).toBe(false);
+ expect(close).not.toHaveBeenCalled();
+ await shutdown.prepare();
+ expect(close).toHaveBeenCalledOnce();
+ expect(shutdown.complete).toBe(true);
+ });
+
it('coalesces a quit emitted synchronously by local cleanup', async () => {
let reentered: Promise<void> | undefined;
let calls = 0;
@@ -63,3 +255,22 @@ describe('application shutdown durability and latency', () => {
});
});
+
+
+it('revokes the critical phase during failed cleanup before a retry is admitted', async () => {
+ const entered = gate(), resume = gate();
+ const terminate = vi.fn().mockRejectedValueOnce(new Error('controlled termination failure')).mockResolvedValue(undefined);
+ const shutdown = createShutdownCoordinator({
+ captureProcesses: async () => ({ terminate, dispose() {} }),
+ quiesce: async () => {}, localTasks: [], onFailure: vi.fn(),
+ onIncomplete: async () => { entered.release(); await resume.promise; },
+ });
+ const failure = shutdown.prepare().catch(error => error);
+ try {
+ await entered.promise;
+ expect((shutdown as any).quiescent).toBe(false);
+ } finally { resume.release(); await failure; }
+ await shutdown.prepare();
+ expect((shutdown as any).quiescent).toBe(true);
+ expect(shutdown.complete).toBe(true);
+});
diff --git a/test/main/util/windows-shutdown-processes.test.ts b/test/main/util/windows-shutdown-processes.test.ts
new file mode 100644
index 00000000..d4f39337
--- /dev/null
+++ b/test/main/util/windows-shutdown-processes.test.ts
@@ -0,0 +1,116 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { captureWindowsShutdownProcesses, hasCapturedWindowsAppProcess } from '../../../src/main/util/windows-shutdown-processes';
+import { exerciseWindowsShutdown } from '../../helpers/windows-shutdown-scenario';
+
+function helper(ownerPid = 1000) {
+ const child = Object.assign(new EventEmitter(), {
+ stdout: new PassThrough(), stdin: new PassThrough(),
+ kill: vi.fn(),
+ });
+ const launch = vi.fn(() => child);
+ return { child, launch, capture: () => captureWindowsShutdownProcesses('win32', ownerPid, launch as never) };
+}
+
+describe('Windows app-owned process shutdown', () => {
+ it.each(['ready\n', 'owned:42\nready\n', `owned:${process.pid},0\nready\n`])(
+ 'rejects incomplete process ownership before app handoff: %s', async output => {
+ const { child, capture } = helper(process.pid);
+ const captured = capture();
+ child.stdout.write(output);
+ await expect(captured).rejects.toThrow('snapshot is invalid');
+ expect(hasCapturedWindowsAppProcess(process.pid)).toBe(false);
+ expect(child.kill).toHaveBeenCalledOnce();
+ },
+ );
+
+ it.each(['dispose', 'exit', 'error'])('only reuses an app-wide process snapshot until %s', async outcome => {
+ const { child, capture } = helper(process.pid);
+ const captured = capture();
+ expect(hasCapturedWindowsAppProcess(42)).toBe(false);
+ child.stdout.write(`owned:${process.pid},42\nready\n`);
+ const processes = await captured;
+ expect(hasCapturedWindowsAppProcess(42)).toBe(true);
+ expect(hasCapturedWindowsAppProcess(43)).toBe(false);
+ try {
+ if (outcome === 'dispose') processes.dispose();
+ else if (outcome === 'exit') child.emit('exit', 1);
+ else child.emit('error', new Error('helper unavailable'));
+ expect(hasCapturedWindowsAppProcess(42)).toBe(false);
+ } finally { processes.dispose(); }
+ });
+
+ it('keeps graceful saves separate from forced cleanup and waits for helper exit', async () => {
+ const { child, capture, launch } = helper();
+ const captured = capture();
+ child.stdout.write('ready\r\n');
+ const processes = await captured;
+ expect(launch.mock.calls[0][2]).toMatchObject({ windowsHide: true, stdio: ['pipe', 'pipe', 'ignore'] });
+ expect(child.stdin.read()).toBeNull();
+ let done = false;
+ const pending = processes.terminate().then(() => { done = true; });
+ expect(child.stdin.read().toString()).toBe('stop\n');
+ await Promise.resolve();
+ expect(done).toBe(false);
+ child.emit('exit', 0);
+ await pending;
+ expect(done).toBe(true);
+ processes.dispose();
+ expect(child.kill).not.toHaveBeenCalled();
+ });
+
+ it.each(['startup', 'cleanup'])('fails closed on a %s timeout without retaining a timer', async phase => {
+ vi.useFakeTimers();
+ try {
+ const { child, capture } = helper();
+ const captured = capture();
+ let pending: Promise<unknown> = captured;
+ if (phase === 'cleanup') {
+ child.stdout.write('ready\n');
+ pending = (await captured).terminate();
+ }
+ const rejected = expect(pending).rejects.toThrow('timed out');
+ await vi.advanceTimersByTimeAsync(15_000);
+ await rejected;
+ expect(child.kill).toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ } finally { vi.useRealTimers(); }
+ });
+
+ it('rejects a failed descendant sweep instead of allowing installer handoff', async () => {
+ const { child, capture } = helper();
+ const captured = capture();
+ child.stdout.write('ready\n');
+ const processes = await captured;
+ const failed = expect(processes.terminate()).rejects.toThrow('cleanup failed');
+ child.emit('exit', 1);
+ await failed;
+ processes.dispose();
+ });
+
+ it('releases the helper without requesting termination when a save is cancelled', async () => {
+ const { child, capture } = helper();
+ const captured = capture();
+ child.stdout.write('ready\n');
+ (await captured).dispose();
+ expect(child.stdin.read()).toBeNull();
+ expect(child.kill).toHaveBeenCalledOnce();
+ child.emit('exit', null);
+ });
+
+ it('does not create a Windows helper on other platforms', async () => {
+ const launch = vi.fn();
+ const processes = await captureWindowsShutdownProcesses('darwin', 1000, launch as never);
+ await processes.terminate();
+ processes.dispose();
+ expect(launch).not.toHaveBeenCalled();
+ });
+
+ it.runIf(process.platform === 'win32')(
+ 'stops orphaned and late Windows descendants, releases locked files, and preserves unrelated work',
+ async () => {
+ await exerciseWindowsShutdown(process.env.ORKAS_TEST_NODE!);
+ }, 60_000,
+ );
+});