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.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
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.tsindex 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 alreadydiff --git a/src/core-agent/src/tools/process-session.ts b/src/core-agent/src/tools/process-session.tsindex 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.tsindex 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.tsindex 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.tsindex 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<LocalCllet 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<LocalCldetached: 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.tsindex 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: numberconst 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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,+ );+});