mcp-pacemaker 2.0.2 → 2.1.1

package/supervisor/supervise.mjs

@@ -1,34 +1,38 @@
 import { fork } from 'node:child_process';
 import { randomBytes, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { homedir } from 'node:os';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { servicePaths, assertDurableRoot } from '../bin/service-control.mjs';
+import { requireUserRuntimeContext } from '../bin/runtime-context.mjs';
 
 const { values } = parseArgs({
-  options: { port: { type: 'string', default: '8791' }, config: { type: 'string' } },
+  options: { port: { type: 'string', default: '8791' }, config: { type: 'string' }, cwd: { type: 'string' } },
 });
-const port = Number(values.port);
+let port = Number(values.port);
 const root = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), '..'));
 const config = resolve(values.config || join(homedir(), '.mcp-pacemaker', 'servers.json'));
-const paths = servicePaths(config, port);
+let paths = port === 0 && process.connected && process.env.MCP_PACEMAKER_MANAGED_INSTANCE
+  ? undefined : servicePaths(config, port);
 assertDurableRoot(root);
 if (Number(process.versions.node.split('.')[0]) < 20) throw new Error('Node.js >=20 is required.');
 
-if (existsSync(paths.hold)) {
+if (paths && existsSync(paths.hold)) {
   console.log(`Service :${port} is held stopped. Use the matching CLI start --port ${port} to resume deliberately.`);
 } else {
   await supervise();
 }
 
 async function supervise() {
+  await requireUserRuntimeContext();
   const identity = {
-    protocol: 1, root, config, port, socket: paths.socket, pid: process.pid, execPath: process.execPath,
+    protocol: 1, root, config, port, socket: paths?.socket, pid: process.pid, execPath: process.execPath,
     id: randomUUID(), token: randomBytes(32).toString('hex'),
     version: JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version,
+    upgradeProtocol: 1, managedInstance: process.env.MCP_PACEMAKER_MANAGED_INSTANCE,
   };
   let child;
   let childExit;
@@ -37,6 +41,14 @@ async function supervise() {
   let stopRequested = false;
   let holdRequested = false;
   const clients = new Set();
+  const pending = new Map();
+  let readiness;
+  const failStartup = process.env.MCP_PACEMAKER_UPGRADE_PENDING === '1';
+  let initialStartup = failStartup;
+  let pendingStart = failStartup || Boolean(paths && existsSync(paths.admissionHold));
+  let quiescedInstanceId;
+  let stopAuthorization;
+  const lifetimes = [];
   const server = createServer((socket) => {
     clients.add(socket);
     socket.on('close', () => clients.delete(socket));
@@ -55,12 +67,47 @@ async function supervise() {
       catch { socket.destroy(); return; }
       if (request.id !== identity.id ||
           request.token !== identity.token ||
-          request.action !== 'stop') {
+          !['stop', 'inspect', 'quiesce', 'activate', 'resume'].includes(request.action)) {
         socket.destroy();
         return;
       }
+      if (request.action !== 'stop') {
+        if (request.action === 'quiesce') {
+          pendingStart = true;
+          writeFileSync(paths.admissionHold, JSON.stringify({ id: identity.id, root, config, port }) + '\n',
+            { mode: 0o600, flush: true });
+        }
+        bridgeRequest(request).then((result) => {
+          if (result.ok &&
+              result.instanceId === readiness?.instanceId) {
+            if (request.action === 'quiesce' &&
+                result.held) quiescedInstanceId = result.instanceId;
+            if (['activate', 'resume'].includes(request.action)) {
+              if (existsSync(paths.admissionHold)) unlinkSync(paths.admissionHold);
+              pendingStart = false;
+              initialStartup = false;
+              quiescedInstanceId = undefined;
+            }
+          }
+          socket.end(JSON.stringify({ ...result, id: identity.id }) + '\n');
+        }, (error) => socket.end(JSON.stringify({ id: identity.id, ok: false, error: error.message }) + '\n'));
+        return;
+      }
+      if (request.quiescedInstanceId !== undefined) {
+        const heldGeneration = !child ||
+          readiness?.instanceId === quiescedInstanceId ||
+          readiness?.held === true;
+        if (!pendingStart ||
+            request.quiescedInstanceId !== quiescedInstanceId ||
+            !heldGeneration) {
+          socket.end(JSON.stringify({ id: identity.id, stopped: false }) + '\n');
+          return;
+        }
+        stopAuthorization = request.quiescedInstanceId;
+      }
       stop().then(() => {
-        socket.end(JSON.stringify({ id: identity.id, stopped: true, autostartHeld: true }) + '\n');
+        socket.end(JSON.stringify({ id: identity.id, stopped: true, autostartHeld: true,
+          ...(stopAuthorization ? { quiescedInstanceId: stopAuthorization } : {}) }) + '\n');
       }, (error) => {
         console.error(error.message);
         socket.end(JSON.stringify({ id: identity.id, stopped: false }) + '\n');
@@ -69,14 +116,11 @@ async function supervise() {
   });
 
   mkdirSync(dirname(config), { recursive: true, mode: 0o700 });
-  await new Promise((resolveListen, reject) => {
-    server.once('error', reject);
-    server.listen(paths.socket, resolveListen);
-  });
+  if (paths) await listen();
   server.on('error', (error) => { console.error(error.message); process.exitCode = 1; });
   try {
-    writeFileSync(paths.record, JSON.stringify(identity) + '\n', { mode: 0o600 });
-    if (existsSync(paths.hold)) {
+    if (paths) writeFileSync(paths.record, JSON.stringify(identity) + '\n', { mode: 0o600 });
+    if (paths && existsSync(paths.hold)) {
       server.close();
       return;
     }
@@ -87,23 +131,152 @@ async function supervise() {
   }
   process.on('SIGINT', onSignal);
   process.on('SIGTERM', onSignal);
+  process.on('message', (message) => { if (message === 'stop') onSignal(); });
+  process.on('disconnect', onSignal);
+
+  function listen() {
+    return new Promise((resolveListen, reject) => {
+      server.once('error', reject);
+      server.listen(paths.socket, resolveListen);
+    });
+  }
+
+  function bridgeRequest(request) {
+    if (!child?.connected ||
+        !readiness) return Promise.reject(new Error('Bridge has no verified managed readiness.'));
+    const requestId = randomUUID();
+    const requestedChild = child;
+    return new Promise((resolveRequest, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(requestId);
+        reject(new Error('Bridge admission result is uncertain; recovery required.'));
+      }, 11000);
+      pending.set(requestId, (message) => {
+        clearTimeout(timer);
+        if (requestedChild !== child) {
+          reject(new Error('Bridge generation changed during admission; hold remains in effect.'));
+          return;
+        }
+        resolveRequest(message);
+      });
+      child.send({
+        type: 'upgrade-control', requestId, action: request.action, timeoutMs: 8000,
+        expectedAuthority: request.expectedAuthority, expectedSessionState: request.expectedSessionState,
+      });
+    });
+  }
+
+  function observeLifetime(identity) {
+    return (async () => {
+      const { observeWindowsProcessLifetime } = await import('../bin/windows-process-lifetime.mjs');
+      return observeWindowsProcessLifetime(identity);
+    })();
+  }
 
   function launch() {
     if (stopRequested ||
-        existsSync(paths.hold)) {
+        (paths && existsSync(paths.hold))) {
       server.close();
       return;
     }
-    child = fork(join(root, 'supervisor', 'bridge-child.mjs'), ['--port', String(port), '--config', config], {
+    let completeLifetime;
+    let failLifetime;
+    let lifetimeArmed;
+    if (process.platform === 'win32') {
+      const requiredLifetime = new Promise((resolveLifetime, rejectLifetime) => {
+        completeLifetime = resolveLifetime;
+        failLifetime = rejectLifetime;
+      });
+      const proof = requiredLifetime.then(observer => observer.done);
+      proof.catch(() => {});
+      lifetimes.push(proof);
+    }
+    const armLifetime = identity => {
+      lifetimeArmed = observeLifetime(identity);
+      if (completeLifetime) lifetimeArmed.then(completeLifetime, failLifetime);
+      return lifetimeArmed;
+    };
+    readiness = undefined;
+    const launched = fork(join(root, 'supervisor', 'bridge-child.mjs'), [
+      '--port', String(port), '--config', config, ...(values.cwd ? ['--cwd', values.cwd] : []),
+    ], {
       execPath: process.execPath, execArgv: [], stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true,
+      env: { ...process.env, MCP_PACEMAKER_UPGRADE_PENDING: pendingStart ? '1' : '0' },
+    });
+    child = launched;
+    launched.on('message', async (message) => {
+      if (message?.type === 'upgrade-lifetime') {
+        if (lifetimeArmed) return;
+        armLifetime(message.lifetime);
+        lifetimeArmed.then(() => {
+          if (launched.connected) launched.send('upgrade-lifetime-observed');
+        }, error => {
+          console.error(error.message);
+          onSignal();
+        });
+        return;
+      }
+      if (message?.type === 'upgrade-result') {
+        pending.get(message.requestId)?.(message);
+        pending.delete(message.requestId);
+      }
+      if (message?.type !== 'upgrade-ready') return;
+      try {
+        if (process.platform === 'win32' &&
+            !lifetimeArmed &&
+            message.lifetime) armLifetime(message.lifetime);
+        if (process.platform === 'win32' &&
+            !lifetimeArmed) throw new Error('Windows backend lacks verified process containment observation.');
+        if (lifetimeArmed) await lifetimeArmed;
+        if (stopRequested ||
+            launched !== child) return;
+        if (message.protocol !== 1 ||
+            message.version !== identity.version ||
+            !Number.isInteger(message.port) ||
+            message.port < 1 ||
+            (port !== 0 && port !== message.port)) throw new Error('Bridge readiness identity mismatch.');
+        if (port === 0) {
+          port = message.port;
+          paths = servicePaths(config, port);
+          identity.port = port;
+          identity.socket = paths.socket;
+          await listen();
+        }
+        readiness = message;
+        identity.instanceId = message.instanceId;
+        writeFileSync(paths.record, JSON.stringify(identity) + '\n', { mode: 0o600 });
+        if (process.connected) process.send({ ...message, type: 'supervisor-ready', supervisorId: identity.id });
+      } catch (error) {
+        console.error(error.message);
+        await stop(false);
+      }
     });
     childExit = new Promise((resolveExit, reject) => {
-      child.once('error', reject);
-      child.once('exit', (code) => {
+      launched.once('error', error => {
+        failLifetime?.(error);
+        reject(error);
+      });
+      launched.once('exit', (code) => {
         child = undefined;
         resolveExit();
+        if (process.platform === 'win32' &&
+            !lifetimeArmed) {
+          failLifetime(new Error('Current Windows bridge exited without lifetime ownership proof. Older unsupported protocols require separately verified shutdown; no completed receipt is available.'));
+          if (!stopRequested) {
+            process.exitCode = 1;
+            server.close();
+            if (process.connected) process.disconnect();
+          }
+          return;
+        }
         if (stopRequested) return;
-        if (code === 3) server.close();
+        if (code === 3 ||
+            initialStartup) {
+          process.exitCode = code || 1;
+          stop(false).then(() => {
+            if (process.connected) process.disconnect();
+          }, error => { console.error(error.message); process.exitCode = 1; });
+        }
         else retry = setTimeout(launch, 2000);
       });
     });
@@ -125,29 +298,42 @@ async function supervise() {
     stopRequested = true;
     clearTimeout(retry);
     stopping = (async () => {
-      if (child) {
-        if (child.connected) {
-          try {
-            await new Promise((resolveSend, reject) => child.send('stop', (error) => error ? reject(error) : resolveSend()));
-          } catch (error) {
-            if (error.code !== 'ERR_IPC_CHANNEL_CLOSED' &&
-                error.code !== 'EPIPE') throw error;
-          }
-        }
-        let timeout;
-        try {
-          await Promise.race([
-            childExit,
-            new Promise((_, reject) => {
-              timeout = setTimeout(() => reject(new Error('Bridge did not exit; do not replace its root. No force-kill attempted.')), 10000);
-            }),
-          ]);
-        } finally {
-          clearTimeout(timeout);
-        }
+      let timeout;
+      try {
+        await Promise.race([
+          (async () => {
+            if (child?.connected) {
+              try {
+                await new Promise((resolveSend, reject) => child.send('stop', error => error ? reject(error) : resolveSend()));
+              } catch (error) {
+                if (error.code !== 'ERR_IPC_CHANNEL_CLOSED' &&
+                    error.code !== 'EPIPE') throw error;
+              }
+            }
+            const [, ...receipts] = await Promise.all([childExit, ...lifetimes]);
+            for (const receipt of receipts) {
+              if (receipt?.verified !== true ||
+                  receipt.ownerExited !== true ||
+                  receipt.activeProcesses !== 0) throw new Error('Windows descendant teardown was not verified; retain the installation.');
+            }
+          })(),
+          new Promise((_, reject) => {
+            timeout = setTimeout(() => reject(new Error('Bridge did not exit; do not replace its root. No force-kill attempted.')), 10000);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timeout);
       }
       if (holdRequested) {
-        writeFileSync(paths.hold, JSON.stringify({ id: identity.id, root, config, port, stopped: true }) + '\n', { mode: 0o600 });
+        writeFileSync(paths.hold, JSON.stringify({ id: identity.id, root, config, port, stopped: true,
+          ...(stopAuthorization ? { quiescedInstanceId: stopAuthorization } : {}) }) + '\n', { mode: 0o600, flush: true });
+      }
+      if (process.connected) {
+        await new Promise((resolveSent, reject) => {
+          process.send({ type: 'supervisor-stopped', id: identity.id, stopped: true },
+            error => error ? reject(error) : resolveSent());
+        });
+        process.disconnect();
       }
       server.close();
       process.removeListener('SIGINT', onSignal);

package/tools/account-upgrade/qualify-two-account.ps1

@@ -0,0 +1,66 @@
+<#
+.SYNOPSIS
+Runs an explicitly authorized two-account Windows upgrade qualification.
+.DESCRIPTION
+Requires an existing elevated controller, existing logged-on target account and
+existing target task. Does not create accounts, request elevation, change ACLs or
+install toolchains. Without Execute it runs only the product's read-only plan.
+.PARAMETER TrustedRoot
+Existing protected, target-readable controller package directory.
+.PARAMETER NodePath
+Existing trusted Node executable.
+.PARAMETER TargetSid
+Canonical SID of the different existing target account.
+.PARAMETER TaskPath
+Exact existing per-user task.
+.PARAMETER Version
+Exact target version approved for this qualification.
+.PARAMETER ControllerRoot
+Existing protected operation-store parent, readable/traversable by the target.
+.PARAMETER Registry
+Explicit approved registry; use an owned registry for fixture qualification.
+.PARAMETER Execute
+Runs the interactive product transaction after its read-only plan succeeds.
+.OUTPUTS
+Product plan and operation results. This script does not attest readiness by itself.
+.EXAMPLE
+.\qualify-two-account.ps1 -TrustedRoot C:\ExistingProtectedTools\Pacemaker -NodePath C:\ExistingNode\node.exe -TargetSid S-1-5-21-1-2-3-1001 -TaskPath \OwnedPacemakerTask -Version 2.1.0 -ControllerRoot C:\ExistingProtectedOperations -Registry https://approved.example.test/npm/
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$TrustedRoot,
+    [Parameter(Mandatory)][string]$NodePath,
+    [Parameter(Mandatory)][string]$TargetSid,
+    [Parameter(Mandatory)][string]$TaskPath,
+    [Parameter(Mandatory)][string]$Version,
+    [Parameter(Mandatory)][string]$ControllerRoot,
+    [Parameter(Mandatory)][string]$Registry,
+    [switch]$Execute
+)
+$ErrorActionPreference = 'Stop'
+if (-not $IsWindows) { throw 'Windows qualification only.' }
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = [Security.Principal.WindowsPrincipal]::new($identity)
+if ($identity.User.Value -ceq $TargetSid -or
+    -not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+    throw 'Use an already-elevated different controller account. This script never elevates.'
+}
+foreach ($path in @($TrustedRoot, $ControllerRoot)) {
+    if (-not (Test-Path -LiteralPath $path -PathType Container)) { throw 'Required existing protected directory is absent.' }
+}
+if (-not (Test-Path -LiteralPath $NodePath -PathType Leaf)) { throw 'Required existing Node executable is absent.' }
+$cli = Join-Path $TrustedRoot 'bin\cli.mjs'
+$arguments = @(
+    $cli, '--user', $TargetSid, '--task', $TaskPath, 'upgrade', '--to', $Version,
+    '--controller-root', $ControllerRoot, '--registry', $Registry
+)
+& $NodePath @arguments --plan
+if ($LASTEXITCODE -ne 0) { throw 'Read-only account/task/path/session eligibility did not pass.' }
+if (-not $Execute) {
+    Write-Output 'Plan only. Actual two-account task mutation, original-account runtime and rollback remain NOT RUN.'
+    return
+}
+if ([Console]::IsInputRedirected) { throw 'Interactive confirmation is required; no unattended approval fallback.' }
+& $NodePath @arguments
+if ($LASTEXITCODE -ne 0) { throw 'Operation did not complete. Preserve both journals; do not force cleanup or replay calls.' }
+Write-Output 'Inspect recorded worker/backend SID, session, version, task full-SD continuity, protected state and cleanup receipts before accepting qualification.'

package/tools/windows-legacy/README.md

@@ -0,0 +1,251 @@
+# Legacy process broker
+
+This separate own-source .NET Framework 4.6.2 executable supports an explicitly
+partial, restart-only legacy handoff. It does not change the modern lifetime
+helper or its Job Object proof. No npm runtime dependencies, compiler, PowerShell,
+downloads, privilege changes or service/task mutations run inside this broker.
+
+## API and caller responsibilities
+
+```js
+const session = await prepareLegacyProcesses({ port, root, expected });
+const plan = session.plan;
+const current = await session.status(); // read-only held-handle status
+const receipt = await session.stop();   // consumes this session's stop once
+await session.close();                 // closes handles; does not stop targets
+const recovered = await verifyLegacyProcessesGone(plan); // read-only
+```
+
+`root` is an absolute existing package directory. `port` is an integer 1..65535.
+Discovery requires exactly one IPv4 127.0.0.1 listener on that port; wildcard or
+ambiguous listeners refuse. It opens the bridge and its native parent, verifies
+both user SIDs match the broker's user, and requires these parsed argument lists:
+
+- `node.exe <root>/bin/mcp-bridge.mjs --port <N>`
+- `pwsh.exe|powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden
+  -File <root>/supervisor/supervise.ps1 -Port <N>`
+
+Actual image paths and SHA256 values are recorded, not assumed to equal the
+upgrader's Node executable. Parsed argv is hashed and not emitted. Native
+creation time is an exact decimal Windows FILETIME string. WMI command-line
+reads are checked against the held process generation. No cwd/PEB read, process
+injection or debugging is used.
+
+Both script arguments must be fully qualified Windows drive-absolute or ordinary
+UNC paths before comparison. Relative, drive-relative (`C:script.ps1`),
+root-relative (`\script.ps1`) and device-namespace spellings refuse; the broker
+never resolves target arguments against its own cwd or guesses the target cwd.
+Existing case-insensitive full-path comparison and native executable identity
+queries are unchanged.
+
+Process discovery uses documented `TH32CS_SNAPPROCESS` snapshots: one per capture
+or revalidation phase to bind the two roots, and one per stop sweep round. At most
+16,384 PID/parent pairs are retained in memory. The native entry buffer also
+contains other OS fields; the broker reads only the PID/parent offsets, never
+marshals names, and clears that buffer after each entry. It closes the snapshot
+before opening candidates. No global pair list is returned or logged, and no
+unrelated entries receive process/token/image queries. Snapshot overflow,
+layout/duplicate/enumeration failure and `ERROR_BAD_LENGTH` refuse a capture or
+revalidation phase without retry; during a stop they are reported, and the sweep
+still stops every process it already holds and tries again in its next round.
+
+Snapshot pairs are discovery hints, not process authority or an atomic tree.
+A sweep candidate must still bind to a held process through its own native
+parent, creation-time and owner checks. Unknown historical branches stay
+untouched.
+
+The argv query covers only the two held roots, in one query per phase run by a
+worker that owns its connected WMI scope/searcher/cursor. Missing, extra,
+duplicate or stale rows refuse the entire phase; the native watchdog remains the
+hard whole-helper bound for a blocked call.
+
+Each phase separately hashes at most 64 executable files, 256 MiB per file and
+512 MiB total. Read handles deny writes/deletion until the phase finishes.
+Every process image path is reopened and matched by volume/file identity before
+reusing a digest; paths alone and prior-phase digests are not cache keys.
+
+The caller must independently verify the exact known legacy package, selected
+launcher/task ownership, source hashes, and config-directory nonce/revision.
+Matching process arguments and captured script hashes do **not** make an arbitrary
+script an approved legacy package. Cwd is not a supported config binding.
+
+Prepare is read-only. It captures **only the two roots** and binds them to the
+listener and to each other. It does not list the bridge's session processes: a
+busy 1.3 bridge starts and ends them every few seconds, so a list would be stale
+before the stop. It also walks its own parent chain, checking creation order at
+each step, and refuses with `Run the upgrade from a terminal the 1.3 bridge did
+not start` if that chain reaches the supervisor or the bridge: such an upgrade
+would stop itself. Script read handles deny script modification/deletion during
+this session. The plan contains:
+
+```text
+protocol: 1
+kind: "legacy-observed-process-set"
+roots: { supervisor, bridge }
+observed: []   (2.1.0 plans listed descendants here; recovery still verifies them)
+excluded: []
+observedSetSha256
+treeCompleteness: "unproven"
+scope
+planSha256
+```
+
+Root identities include PID, creation time, parent PID/creation time, owner SID,
+image path/hash, argv hash and root script hash. No opaque commit token is in
+`plan`. Passing a previous `plan` as `expected` binds its roots: protocol, kind,
+port, root, owner and both root identities must match exactly. Descendants are
+not compared, so sessions that started or ended since the plan do not refuse it.
+A changed root generation still requires a new plan and confirmation.
+
+Only after the caller's per-plan confirmation and holding and rechecking the
+**exact selected** autostart registration may the caller invoke `stop()`. This
+broker does not attest that the task is held. It rechecks the roots, listener and
+argv/image identity, then stops through retained native handles, never by a
+fresh PID lookup:
+
+1. Terminate the supervisor and wait for it, so it cannot start another bridge.
+2. Pin: take a snapshot and hold a handle to each process whose live parent PID
+   (read from its own handle, not the snapshot) is a held process and which
+   started no earlier than that process, walking the whole tree in one pass.
+   Repeat until a snapshot shows nothing new, at most eight times. Nothing is
+   stopped here.
+3. Terminate the bridge and wait for it.
+4. Sweep: pin again, then terminate every held process not yet stopped and wait
+   for them, even if that pin found the tree still growing or could not read a
+   snapshot. Repeat until a round's pin settles with nothing new and nothing is
+   left to stop.
+
+Pinning comes first because Node ends a process's direct children together with
+it through a job object, and 1.3 runs each bare server command under a `cmd.exe`
+wrapper. Without the pin, ending the bridge would end the wrappers at once and
+leave the real servers under them with a parent nobody holds. A process that has
+already exited is held too while it can still be opened, so its children stay
+traceable. A wrapper the bridge starts in the few milliseconds between the last
+pin snapshot and the bridge's exit is not held; if it has started its server by
+then, that server is left running like any other untraceable process.
+
+Held handles keep their PIDs from being reused, so a process that names a held
+PID as its parent and started no earlier than it was started by it. A process
+older than that parent got the PID from an earlier owner and is left alone; a
+held root that appears under a pinned process (its creator's PID was reused) is
+already held and is skipped. The broker and its own parent chain, matched by PID
+and creation time, are never adopted. A live process owned by another user is
+reported, not stopped.
+Processes whose parent had already exited before the stop cannot be traced and
+stay untouched.
+
+Root capture ambiguities refuse. After mutation starts, failures are explicit and
+may be partial; never automatically relaunch the old supervisor, replay tools, or
+broaden cleanup. The caller must preserve its task hold and journal when the root
+stop is uncertain.
+
+### Failure diagnostics
+
+The existing refusal envelope keeps its exception type, native error code,
+stage, reason and `mutationStarted` flag. When available, `captureFailure`
+contains fixed API/substage labels and nullable stored PID, creation, parent,
+liveness and owner-match facts. An initial query-handle denial reports the
+requested PID but `generationKnown: false` and `creationTime: null`. Other call
+sites can report an API with unknown substage/target; unknown fields are not
+inferred from a PID or exception.
+
+`observation: "stored-observations-not-fresh-proof"` identifies these as prior
+observations, not a new identity check or stop authority. No diagnostic recovery
+query, retry, stronger access, argv, image path, SID or raw exception text is
+added. Metadata is attached to the original exception, separately for each
+operation/argv worker; collection failures leave the original refusal intact.
+Success frames, plans, digests, approvals and stop behavior do not change.
+
+## Honest receipt
+
+```text
+legacyRootStopVerified: true|false
+observedDescendantsStopped: true|false   (every process the sweep found was stopped)
+descendantsFound
+descendantsStopped
+treeCompleteness: "unproven"
+observedCount
+excludedCount
+planSha256
+errors: [...]
+unattributed: "Not discovered or not provable; left untouched."
+```
+
+There is no `stopped:true` or `activeProcesses:0` field. A wrapper that exits
+before the stop leaves its children with no traceable parent. Matching snapshots
+do not prove no such processes exist. This broker neither counts nor kills
+historical/unattributed orphans. The caller requires `legacyRootStopVerified`;
+a process the sweep could not stop is reported in `errors` and left running.
+
+`verifyLegacyProcessesGone(plan)` validates the protected plan's shape/digest,
+then opens **only its captured IDs** (the roots, plus any descendants a 2.1.0 plan
+listed) with query/synchronize access. A different creation time is an unrelated
+reused PID and is untouched; a matching live identity keeps the receipt false;
+inaccessible identities keep it unverified. It never requests terminate access or
+performs discovery, so its `descendantsFound` and `descendantsStopped` are null,
+and for a plan that lists no descendants `observedDescendantsStopped` is false:
+the check cannot vouch for them. The journal's authentication/ownership and phase
+authorization belong to the caller. A hash inside the plan is an integrity check,
+not an authentication credential.
+
+## Bounds and lifecycle
+
+- Plans hold at most 512 identities, including both roots, so a 2.1.0 plan is
+  still accepted for recovery checks. A plan written now holds only the roots.
+- The stop holds at most 2048 processes and reads at most 2048 children of one
+  process. Each pin takes at most eight snapshots; a tree still growing after
+  that is pinned further by the next sweep round. The sweep runs at most 16
+  rounds. One busy 1.3 host had 533 processes in its tree. Reaching the process,
+  child or round bound is reported in `errors`; the root stop stands.
+- One argv query during capture and one during revalidation.
+- The native watchdog allows 15 seconds to receive the request. Capture and
+  revalidation then each have 120 seconds, timed from the request rather than
+  from broker start; verification is bounded by the watchdog alone. Each phase
+  adds a 10-second watchdog margin, longer than one 8-second WMI query, so a
+  phase refusal is reported rather than cut off. Node waits 150 seconds for a
+  prepare or verification response.
+- Uncommitted session: 120 seconds; expiration requires fresh prepare.
+- Stop: the supervisor, the pin, the bridge and every sweep round share **one
+  20-second** budget. Once it is spent, remaining exits are polled, not awaited,
+  and the sweep ends. Node's whole stop exchange, including revalidation, is
+  bounded to 170 seconds.
+- Close/exit verification: three seconds.
+- Plans: at most 240 KiB UTF-8 before emit/accept. Requests and responses: at most
+  256 KiB UTF-8. No full command lines or config contents are emitted.
+- Native parent watch: caller loss before commit releases handles without target
+  termination. After commit the already-authorized bounded stop finishes.
+
+  Prepare/stop responses include bounded phase timing/resource diagnostics and
+  the broker's own PID/FILETIME for owned exit evidence. These values confer no
+  target authority and are not part of the plan digest. A test-only outer
+  cleanup job is not proof that the production stop succeeded.
+
+Detached native launch avoids inherited console/Node child termination, but is
+not an unbounded daemon. Parent loss and deadlines end the broker. Native target
+handles are non-inherited. No elevation or privilege enablement is attempted.
+
+Both native launches (prepare and verify-only) first compare actual executable
+SHA256 to packaged metadata. This detects package drift, not malicious replacement
+of executable plus metadata or the whole package.
+It is not an atomic executable-replacement defense; supported upgrades stage
+separate immutable package roots rather than replacing a running helper in place.
+
+## Build, inventory and tests
+
+```powershell
+.\tools\windows-legacy\build.ps1
+.\tools\windows-legacy\build.ps1 -Verify
+node --test test/windows-legacy-process.test.mjs
+```
+
+The build reuses the installed recorded Roslyn and .NET Framework 4.6.2 reference
+assemblies, including built-in `System.Management` and `System.Web.Extensions`.
+It compiles twice under different owned paths and compares bytes, records source,
+build script, compiler and reference hashes, and installs nothing. `-Verify`
+updates no artifact. `inventory.mjs` checks the exact separate asset layout.
+The immutable historical security helper and modern lifetime binaries stay
+unchanged.
+
+Dedicated tests use a synthetic argument-compatible supervisor for bounded
+native identity cases. The upgrader owns the additional byte-exact known-1.3
+package/launcher/config/task E2E; passing these focused tests does not replace it.