mcp-pacemaker 2.0.2 → 2.1.0

package/tools/windows-legacy/README.md

@@ -0,0 +1,225 @@
+# Legacy observed-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.
+
+Child discovery uses one documented `TH32CS_SNAPPROCESS` snapshot per capture
+or revalidation phase. 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 the whole operation without retry.
+
+Snapshot pairs are discovery hints, not process authority or an atomic tree.
+Every candidate must still bind to an already-held live parent through native
+parent/creation/owner checks. Unknown historical branches remain unproven.
+Fresh revalidation refuses added or changed generations; a reused numeric PID
+cannot replace an exited captured handle.
+
+Argv queries cover only held live IDs, at most 32 per query and four concurrent
+workers. Each worker owns its connected WMI scope/searcher/cursor. Missing,
+extra, duplicate or stale rows refuse the entire phase. Failed waves stop new
+dispatch and join before a response; the native watchdog remains the hard
+whole-helper bound for blocked calls. Descendant argv is discarded after
+hashing. Already-exited captured descendants remain recorded as gone rather
+than being adopted by PID.
+
+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 the roots and a bounded set of currently
+provable descendants **before any stop**. Each ancestry edge is checked against
+a held, still-live parent and child creation time. 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: [captured identities]
+excluded: [proven older nonmembers; never termination targets]
+observedSetSha256
+treeCompleteness: "unproven"
+scope
+planSha256
+```
+
+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 full `plan` as `expected` requires exact equality, including
+all root generations, hashes and observed members. Changes require a new plan
+and confirmation; no new set is silently substituted.
+
+If a query returns a candidate whose actual creator PID equals a still-live held
+parent, but whose creation time predates that parent's held generation, it is
+excluded with PID/birth/parent-birth evidence and reason `predates-held-parent`.
+Only query/synchronize access is opened for this check; an excluded candidate
+never receives terminate access and is not traversed. This handles older
+survivors whose creator's numeric PID was reused. The plan digest binds the
+excluded evidence too. A dead parent, changed live edge, inaccessible query or
+other ambiguous ownership still refuses. Stop rechecks any excluded candidate
+still returned by the same rooted query; changed generations require replanning.
+
+Cached identities repeat the native generation, parent, owner and liveness
+checks before reuse. If a selected root predates a newer held generation of its
+numeric creator PID, only that false descendant edge is ignored. The root
+remains selected, its parent-birth binding is not rewritten, and it is not added
+to `excluded`. Non-root or unproven cached edges still refuse. Revalidation uses
+the same classification; depth eight and the combined identity limit do not
+change.
+
+Only after explicit per-plan interruption/uncertain-HTTP confirmation and holding
+and rechecking the **exact selected** autostart registration may the caller invoke
+`stop()`. This broker does not attest that the user has paused callers or held the
+task. It rechecks roots, listener, argv/image identity and currently reachable
+members. A newly observed child before commit causes refusal, not silent expansion.
+Then it terminates the selected supervisor, bridge, and admitted descendants
+through their retained native handles, never by a fresh PID lookup.
+
+All 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 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`. Existing
+ancestry-refusal details are retained. 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
+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 capture can leave an unprovable descendant. Matching snapshots and empty
+captured sets do not prove no such processes exist. This broker neither counts
+nor kills historical/unattributed orphans.
+
+`verifyLegacyProcessesGone(plan)` validates the protected plan's shape/digest,
+then opens **only its captured IDs** 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. 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.
+
+Excluded candidates are never opened by recovery verification and are never
+required to exit. Counts describe this bounded observation, not all historical
+orphans or complete tree coverage.
+
+## Bounds and lifecycle
+
+- At most 512 **combined held and excluded identities**, including both roots,
+  and eight ancestry levels. Any count/depth/byte/query failure refuses the
+  whole plan; no subset is silently accepted.
+- At most 48 argv queries during capture and 32 during revalidation.
+- Initial capture: 15-second native watchdog, 20-second Node response bound.
+- Uncommitted session: 120 seconds; expiration requires fresh prepare.
+- Stop revalidation: 15 seconds; termination/waits share **one eight-second**
+  budget. Node's whole stop exchange is bounded to 30 seconds.
+- Close/exit verification: three seconds.
+- Plans: at most 240 KiB UTF-8 before emit/accept. Complete encoded requests:
+  at most 256 KiB; no full command lines or config contents 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. Termination order and its
+  single shared eight-second budget are unchanged. 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.

package/tools/windows-legacy/build.ps1

@@ -0,0 +1,122 @@
+<#
+.SYNOPSIS
+Builds or verifies the separate Windows legacy observed-set broker.
+.DESCRIPTION
+Uses installed Visual Studio Roslyn and .NET Framework 4.6.2 reference assemblies.
+Compiles twice under different paths, records every input, and downloads nothing.
+#>
+[CmdletBinding()]
+param(
+    [switch]$Verify,
+    [string]$CompilerPath,
+    [string]$ReferenceAssemblyPath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Get-Digest([string]$Path, [switch]$Text) {
+    $bytes = [IO.File]::ReadAllBytes($Path)
+    if ($Text) {
+        $bytes = [Text.Encoding]::UTF8.GetBytes([IO.File]::ReadAllText($Path).Replace("`r`n", "`n"))
+    }
+    $hash = [Security.Cryptography.SHA256]::Create()
+    try { return [BitConverter]::ToString($hash.ComputeHash($bytes)).Replace('-', '').ToLowerInvariant() }
+    finally { $hash.Dispose() }
+}
+
+if ($env:OS -ne 'Windows_NT') { throw 'Build on Windows with installed Roslyn and .NET Framework 4.6.2 references.' }
+$root = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..\..'))
+$directory = Join-Path $root 'bin\windows-legacy'
+$binary = 'LegacyProcessBroker.exe'
+$metadataPath = Join-Path $directory 'LegacyProcessBroker.build.json'
+$sources = @('AssemblyInfo.cs', 'LegacyNative.cs', 'LegacyProcessBroker.cs')
+$references = @('mscorlib.dll', 'System.dll', 'System.Core.dll', 'System.Management.dll', 'System.Web.Extensions.dll')
+if (-not $CompilerPath) {
+    $vswhere = Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe'
+    if (-not (Test-Path -LiteralPath $vswhere)) { throw 'Specify an installed Roslyn -CompilerPath; no tools are installed.' }
+    $installation = & $vswhere -latest -products '*' -requires Microsoft.Component.MSBuild -property installationPath
+    if ($LASTEXITCODE -ne 0 -or
+        -not $installation) { throw 'No installed Visual Studio MSBuild compiler found.' }
+    $CompilerPath = Join-Path $installation 'MSBuild\Current\Bin\Roslyn\csc.exe'
+}
+if (-not $ReferenceAssemblyPath) {
+    $ReferenceAssemblyPath = Join-Path ${env:ProgramFiles(x86)} 'Reference Assemblies\Microsoft\Framework\.NETFramework\v4.6.2'
+}
+$CompilerPath = (Resolve-Path -LiteralPath $CompilerPath).Path
+$ReferenceAssemblyPath = (Resolve-Path -LiteralPath $ReferenceAssemblyPath).Path
+$framework = [xml][IO.File]::ReadAllText((Join-Path $ReferenceAssemblyPath 'RedistList\FrameworkList.xml'))
+if ($framework.FileList.Name -cne '.NET Framework 4.6.2') { throw 'Wrong reference assembly targeting pack.' }
+$version = (& $CompilerPath /version | Out-String).Trim()
+if ($LASTEXITCODE -ne 0) { throw 'Roslyn version probe failed.' }
+$options = @('/nologo', '/noconfig', '/nostdlib+', '/target:exe', '/platform:anycpu',
+    '/langversion:7.3', '/optimize+', '/debug-', '/deterministic+', '/checked-',
+    '/unsafe-', '/warn:4', '/warnaserror+', '/utf8output')
+$sourceHashes = [ordered]@{}
+foreach ($name in $sources) { $sourceHashes[$name] = Get-Digest (Join-Path $directory "src\$name") -Text }
+$referenceHashes = [ordered]@{}
+foreach ($name in $references) { $referenceHashes[$name] = Get-Digest (Join-Path $ReferenceAssemblyPath $name) }
+$inputs = [ordered]@{
+    targetFramework = '.NETFramework,Version=v4.6.2'
+    platform = 'AnyCPU'
+    compilerVersion = $version
+    compilerSha256 = Get-Digest $CompilerPath
+    compilerArguments = $options
+    pathMap = '/_/mcp-pacemaker/windows-legacy'
+    sourceEncoding = 'UTF-8 without BOM, LF line endings'
+    sourceSha256 = $sourceHashes
+    buildScriptSha256 = Get-Digest $PSCommandPath -Text
+    referenceSha256 = $referenceHashes
+}
+$expected = $null
+if ($Verify) {
+    $expected = [IO.File]::ReadAllText($metadataPath) | ConvertFrom-Json
+    if ($expected.schemaVersion -ne 1 -or
+        $expected.binary -cne $binary -or
+        (ConvertTo-Json $inputs -Depth 6 -Compress) -cne (ConvertTo-Json $expected.inputs -Depth 6 -Compress) -or
+        (Get-Digest (Join-Path $directory $binary)) -cne $expected.binarySha256) {
+        throw 'Packaged legacy broker inputs/toolchain/bytes do not match metadata. Verification changes nothing.'
+    }
+}
+$temporary = Join-Path ([IO.Path]::GetTempPath()) ('mcp-legacy-build-' + [Guid]::NewGuid().ToString('N'))
+$files = [Collections.Generic.List[string]]::new()
+$directories = [Collections.Generic.List[string]]::new()
+$outputs = [Collections.Generic.List[string]]::new()
+try {
+    $null = [IO.Directory]::CreateDirectory($temporary)
+    $directories.Add($temporary)
+    foreach ($pass in @('first', 'second')) {
+        $scratch = Join-Path $temporary $pass
+        $null = [IO.Directory]::CreateDirectory($scratch)
+        $directories.Add($scratch)
+        $paths = foreach ($name in $sources) {
+            $path = Join-Path $scratch $name
+            $files.Add($path)
+            $text = [IO.File]::ReadAllText((Join-Path $directory "src\$name")).Replace("`r`n", "`n")
+            [IO.File]::WriteAllText($path, $text, [Text.UTF8Encoding]::new($false))
+            $path
+        }
+        $output = Join-Path $scratch $binary
+        $files.Add($output)
+        $arguments = $options + @("/out:$output", "/pathmap:$scratch=$($inputs.pathMap)")
+        foreach ($name in $references) { $arguments += '/reference:' + (Join-Path $ReferenceAssemblyPath $name) }
+        & $CompilerPath @arguments @paths
+        if ($LASTEXITCODE -ne 0) { throw "Legacy broker compile failed: $pass" }
+        $outputs.Add($output)
+    }
+    $digest = Get-Digest $outputs[0]
+    if ($digest -cne (Get-Digest $outputs[1])) { throw 'Two builds differ; no package assets changed.' }
+    if ($Verify) {
+        if ($digest -cne $expected.binarySha256) { throw 'Rebuilt bytes differ; no package assets changed.' }
+        Write-Output "Verified legacy broker source, toolchain and byte-for-byte rebuild: SHA256 $digest"
+    } else {
+        $metadata = [ordered]@{ schemaVersion = 1; binary = $binary; binarySha256 = $digest; inputs = $inputs }
+        [IO.File]::Copy($outputs[0], (Join-Path $directory $binary), $true)
+        [IO.File]::WriteAllText($metadataPath,
+            (ConvertTo-Json $metadata -Depth 8).Replace("`r`n", "`n") + "`n", [Text.UTF8Encoding]::new($false))
+        Write-Output "Built two matching legacy brokers with Roslyn ${version}: SHA256 $digest"
+    }
+} finally {
+    foreach ($path in $files) { Remove-Item -LiteralPath $path -ErrorAction SilentlyContinue }
+    for ($index = $directories.Count - 1; $index -ge 0; $index--) { [IO.Directory]::Delete($directories[$index]) }
+}

package/tools/windows-legacy/inventory.mjs

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LEGACY_BROKER_FILES = Object.freeze([
+  'bin/windows-legacy-process.mjs',
+  'bin/windows-legacy/LegacyProcessBroker.exe',
+  'bin/windows-legacy/LegacyProcessBroker.build.json',
+  'bin/windows-legacy/src/AssemblyInfo.cs',
+  'bin/windows-legacy/src/LegacyNative.cs',
+  'bin/windows-legacy/src/LegacyProcessBroker.cs',
+  'tools/windows-legacy/build.ps1',
+  'tools/windows-legacy/inventory.mjs',
+  'tools/windows-legacy/README.md',
+]);
+export const LEGACY_BROKER_TEST = 'test/windows-legacy-process.test.mjs';
+export const LEGACY_BROKER_REQUIRED_TESTS = Object.freeze([
+  'legacy API denials preserve refusal and bounded stored-only failure diagnostics',
+  'legacy failure metadata cannot mask errors or cross concurrent operation identities',
+  'legacy cached selected-root creator-PID reuse skips only the older edge and retains strict refusals',
+  'legacy protected-plan model enforces 512 combined identities and UTF8 byte bounds without process queries',
+  'legacy expected request refuses oversized UTF8 framing before native discovery',
+  ...['relative', 'drive-relative', 'root-relative'].flatMap((spelling) =>
+    ['bridge', 'supervisor'].map((affected) =>
+      `legacy script identity rejects ${affected} ${spelling} argv without stopping targets`)),
+  'legacy script identity accepts fully qualified Unicode and space paths',
+  'legacy script qualification recognizes drive and UNC forms without cwd resolution',
+  'legacy script identity preserves fully qualified short-path handling',
+  'legacy script identity does not equate a junction spelling with a different canonical root',
+  'legacy broker captures held roots and stops only its observed set with partial receipt',
+  'legacy broker close is read-only and an identical expected plan can be reopened',
+  'legacy broker preserves an already-exited captured descendant without adopting a replacement PID',
+  'legacy broker rejects stale generation or expanded observed plan without stopping roots',
+  'legacy broker rejects wrong root and malformed protected verification plan',
+  'legacy broker refuses extra supervisor argv and a foreign listener without process mutation',
+  'legacy read-only recovery does not stop an unrelated process reusing the endpoint',
+  'legacy native inventory rejects changed executable, source and build metadata',
+  'legacy prepare and recovery verify refuse wrong-hash packaged helper before any discovery',
+  'legacy broker parent loss releases read-only capture without stopping legacy roots',
+  'legacy broker reports captured descendant termination failure without certifying stop',
+  'legacy broker preserves Unicode plan identity across fragmented UTF8 pipe messages',
+  'legacy broker excludes a proven older nonmember without terminating or verifying its exit',
+]);
+
+export function verifyLegacyBrokerAssets(root) {
+  for (const path of ['bin', 'bin/windows-legacy', 'bin/windows-legacy/src',
+    'tools', 'tools/windows-legacy']) {
+    const stat = lstatSync(join(root, path));
+    assert.ok(stat.isDirectory() &&
+      !stat.isSymbolicLink(), `Linked or invalid legacy broker directory: ${path}`);
+  }
+  const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+  const files = LEGACY_BROKER_FILES.map((path) => {
+    const full = join(root, path);
+    const stat = lstatSync(full);
+    assert.ok(stat.isFile() &&
+      !stat.isSymbolicLink() &&
+      stat.size > 0, `Invalid legacy broker asset: ${path}`);
+    return { path, sha256: hash(readFileSync(full)) };
+  });
+  assert.deepEqual(readdirSync(join(root, 'bin/windows-legacy')).sort(), [
+    'LegacyProcessBroker.build.json', 'LegacyProcessBroker.exe', 'src',
+  ]);
+  const sources = ['AssemblyInfo.cs', 'LegacyNative.cs', 'LegacyProcessBroker.cs'];
+  assert.deepEqual(readdirSync(join(root, 'bin/windows-legacy/src')).sort(), sources);
+  const metadata = JSON.parse(readFileSync(join(root, 'bin/windows-legacy/LegacyProcessBroker.build.json')));
+  assert.equal(metadata.schemaVersion, 1);
+  assert.equal(metadata.binary, 'LegacyProcessBroker.exe');
+  assert.equal(metadata.inputs.targetFramework, '.NETFramework,Version=v4.6.2');
+  assert.equal(metadata.inputs.platform, 'AnyCPU');
+  assert.deepEqual(Object.keys(metadata.inputs.sourceSha256).sort(), sources);
+  assert.deepEqual(Object.keys(metadata.inputs.referenceSha256).sort(),
+    ['System.Core.dll', 'System.Management.dll', 'System.Web.Extensions.dll', 'System.dll', 'mscorlib.dll']);
+  assert.match(metadata.inputs.compilerSha256, /^[a-f0-9]{64}$/);
+  assert.deepEqual(metadata.inputs.compilerArguments, [
+    '/nologo', '/noconfig', '/nostdlib+', '/target:exe', '/platform:anycpu', '/langversion:7.3',
+    '/optimize+', '/debug-', '/deterministic+', '/checked-', '/unsafe-', '/warn:4', '/warnaserror+', '/utf8output',
+  ]);
+  assert.equal(files.find((file) => file.path.endsWith('.exe')).sha256, metadata.binarySha256);
+  const inputs = sources.map((name) => [`bin/windows-legacy/src/${name}`, metadata.inputs.sourceSha256[name]]);
+  inputs.push(['tools/windows-legacy/build.ps1', metadata.inputs.buildScriptSha256]);
+  for (const [path, expected] of inputs) {
+    assert.equal(hash(readFileSync(join(root, path), 'utf8').replaceAll('\r\n', '\n')), expected,
+      `Changed legacy broker input: ${path}`);
+  }
+  return { status: 'source-and-binary-hashes-verified', files,
+    binarySha256: metadata.binarySha256, compilerSha256: metadata.inputs.compilerSha256,
+    reproducibilityBuild: 'requires-recorded-toolchain-verify' };
+}

package/tools/windows-process-lifetime/README.md

@@ -0,0 +1,119 @@
+# Windows process lifetime helper
+
+The bridge awaits this packaged, own-source .NET Framework 4.6.2 program before
+reading config, listening, or spawning workloads. It has no npm dependencies,
+runtime compilation, PowerShell invocation, downloads, elevation, or service setup.
+
+Before **each owner and observer launch**, the Node module hashes the actual
+executable bytes and compares them with the packaged metadata's recorded SHA256.
+Missing files, invalid metadata and mismatched bytes fail before native spawn.
+This is a packaged-identity guard, not protection against a same-user actor
+replacing both the executable and metadata, or replacing the whole package.
+
+## Ownership
+
+The helper opens its **actual parent** from native process information and retains
+that process handle. It requires `watch-parent <caller PID>` and checks that PID
+against its actual parent; it cannot select an unrelated target. Bare invocation
+fails before assigning any process. This is an internal bridge launch contract,
+not a standalone command to run in a shell.
+
+Creation-time ordering rejects a reused parent PID, and an already exited parent
+is refused. It creates an unnamed, non-inheritable Job Object
+with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, without either breakaway flag, assigns
+the bridge, verifies membership, and only then writes `MCP_JOB_READY`.
+
+The bridge is not suspended: it is awaiting that acknowledgement and cannot start
+any work yet. Every later Windows child inherits the job **during process
+creation**, before its first instruction. This covers isolated, pool, shared,
+auth-command, and config-write helper spawns, including cmd/npx wrappers. There is
+no start-then-assign race, post-crash PID sweep, process enumeration in production,
+or fallback to uncontained spawning.
+
+The owner was started before the bridge joined this job and remains outside it.
+It alone holds the non-inheritable job handle. On bridge exit, the held process
+handle signals and the owner closes the job, terminating surviving descendants.
+Both native roles use detached Windows launches, so Node's automatic direct-child
+termination does not kill the owner before it can drain. These are not unowned
+daemons: each role watches its actual parent's held process handle and exits when
+that parent is lost. Owner stdio/process references do not keep an otherwise
+finished bridge alive.
+Killing the owner also closes the job and terminates the bridge and descendants.
+Normal DELETE/recycle still uses the existing per-session tree cleanup; shared
+detach, counters and request replay rules are unchanged. POSIX does not launch
+this helper or change its process behavior.
+
+A bridge exit notification can precede final job teardown. This mechanism does
+not adopt or clean processes abandoned by an earlier runtime.
+
+## Verified managed stop
+
+`ensureWindowsProcessLifetime()` returns
+`{protocol:1, ownerPid, ownerCreationTime}` on Windows (`null` on POSIX).
+The creation identity is a decimal **Windows FILETIME string**, not a rounded
+JavaScript timestamp or .NET DateTime tick count. The identity comes from the
+native owner after assignment and its PID must match the spawned child.
+
+The supervisor calls `await observeWindowsProcessLifetime(identity)` before
+declaring the bridge ready or permitting stop. It returns `{done, pid}` after a
+separate native observer has opened the owner, checked its exact creation time
+and same helper image, and retained that process handle. It also opens a
+read-only synchronization handle to the owner's initially-unsignaled drain
+event. The owner creates that event before readiness, names it from its PID and
+creation time, and refuses a pre-existing event. Neither handle is inherited.
+The observer is outside
+the bridge job, read-only, and also watches its own parent: losing the supervisor
+does not orphan the observer. Unavailable/reused identities fail closed.
+
+After root exit the owner calls `TerminateJobObject`, then queries actual job
+accounting until `ActiveProcesses == 0`, bounded to five seconds. Only successful
+drain signals that held event and returns exit code zero. Kill-on-close remains
+the failure backstop. The observer waits on the held owner handle, checks both
+successful exit and the signaled event, emits the
+drain receipt, then exits itself. Only after observer exit and complete output
+does `done` resolve to `{verified:true, ownerExited:true, activeProcesses:0}`.
+Forced owner death (including a forced exit code zero) or a failed drain rejects
+`done`; PID disappearance or an exit code alone is never accepted as proof.
+These session-local kernel events leave no files or persistent settings.
+
+Managed startup sends the owner identity early and waits for the supervisor's
+observer acknowledgement before config initialization. This avoids losing the
+owner before failed-start cleanup can arm observation. Budget root exit and
+`observer.done` inside one existing stop deadline, not two sequential deadlines.
+
+Windows 10/11 and Server 2016+ with .NET Framework 4.6.2+ are required. An outer job
+whose restrictions prevent nested assignment causes explicit startup failure,
+not an uncontained bridge. ARM64 execution remains an outstanding platform gate.
+The historical configuration security helper is separate and unchanged.
+
+## Build and verify
+
+Use the already installed Visual Studio Roslyn compiler and 4.6.2 targeting pack:
+
+```powershell
+.\tools\windows-process-lifetime\build.ps1
+.\tools\windows-process-lifetime\build.ps1 -Verify
+# Optional: select the exact recorded, installed compiler/reference directory.
+.\tools\windows-process-lifetime\build.ps1 -Verify -CompilerPath C:\path\to\Roslyn\csc.exe
+```
+
+Both modes compile twice in different owned temporary directories and require
+identical bytes. Verification also requires the recorded compiler, references,
+normalized source/build-script hashes and packaged binary hash; it updates
+nothing. Builds install no tools and clean their explicitly recorded scratch
+files. Only the entry point and P/Invoke declarations are static.
+
+`inventory.mjs` checks the exact separate asset layout and normalized build inputs
+on every platform. It does not substitute for the byte-for-byte Windows rebuild.
+Package/native gates require these assets for current versions starting at 2.0.2;
+the immutable 1.3.1 security-helper baseline is not relabeled or modified.
+
+## Regression
+
+`test/windows-process-lifetime.test.mjs` uses only owned synthetic nested
+`cmd -> Node stand-in -> cmd -> Node worker` processes, dynamic loopback TCP
+heartbeats, MCP readiness, 45-second expiry backstops and captured
+PID/creation-time/held-handle cleanup. DELETE/recycle are controls; abrupt bridge
+loss must stop both heartbeats and terminate every captured descendant. Evidence
+is retained outside Git; set `MCP_LIFETIME_TEST_EVIDENCE` to an existing private
+evidence parent. The known historical live bridge exit trigger remains unknown.