fraim-hub 2.0.304 → 2.0.306

package/README.md

@@ -313,9 +313,8 @@ Use these defaults:
 - `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
 - `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
 - `test-authoring` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
-- `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
-- `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
-- `implementation-design-review` when you need to verify the code matches the approved technical design.
+- `iterative-quality-improvement` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
+- `independent-implementation-review` when you need an independent sign-off that the delivered behavior matches both the approved technical design and the feature spec.
 - `issue-retrospective` after the work is complete and you want durable learnings captured.
 
 Typical path for a larger feature:

package/dist/src/ai-hub/cert-store.js

@@ -3,12 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = void 0;
 exports.certPaths = certPaths;
 exports.loadOrCreateCert = loadOrCreateCert;
 exports.trustCert = trustCert;
+exports.untrustCert = untrustCert;
+exports.computeCertFingerprint = computeCertFingerprint;
+exports.isCertTrusted = isCertTrusted;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const crypto_1 = __importDefault(require("crypto"));
 const child_process_1 = require("child_process");
 function certDir() {
     const base = process.env.APPDATA ||
@@ -45,6 +50,15 @@ async function loadOrCreateCert() {
     // HTTPS loopback certificate to be trusted before it can render the task pane.
     return { key: pem.private, cert: pem.cert };
 }
+/**
+ * Test seam (issue #1589): the real OS command invocation goes through this mutable,
+ * module-owned indirection point instead of a bare `spawnSync` call, so a test can swap in
+ * a fake implementation and assert on the exact command/arguments `trustCert()`/`untrustCert()`
+ * would invoke, without spawning a process, touching PATH, or mutating the real trust store.
+ * Swapping the export on Node's built-in `child_process` module itself is not reliable for
+ * this (confirmed empirically while fixing this issue) - this repo-owned seam is.
+ */
+exports._internal = { spawnSync: child_process_1.spawnSync };
 /**
  * Installs the cert as a trusted root CA in the user's OS certificate store.
  * ONLY call this for explicit Word-Online support — it prompts a Windows security
@@ -55,7 +69,7 @@ async function loadOrCreateCert() {
  */
 function trustCert(certPath) {
     if (process.platform === 'win32') {
-        const result = (0, child_process_1.spawnSync)('certutil', ['-addstore', '-user', 'Root', certPath], { encoding: 'utf8' });
+        const result = exports._internal.spawnSync('certutil', ['-addstore', '-user', 'Root', certPath], { encoding: 'utf8' });
         if (result.status !== 0) {
             console.warn('[fraim] could not trust localhost certificate:', result.stderr || result.stdout);
         }
@@ -63,6 +77,56 @@ function trustCert(certPath) {
     }
     if (process.platform === 'darwin') {
         const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
-        (0, child_process_1.spawnSync)('security', ['add-trusted-cert', '-r', 'trustRoot', '-k', keychain, certPath], { stdio: 'ignore' });
+        exports._internal.spawnSync('security', ['add-trusted-cert', '-r', 'trustRoot', '-k', keychain, certPath], { stdio: 'ignore' });
+    }
+}
+/** Removes a specific cert from the trust store, by fingerprint. Test-only helper. */
+function untrustCert(fingerprint) {
+    if (process.platform === 'win32') {
+        exports._internal.spawnSync('certutil', ['-delstore', '-user', 'Root', fingerprint], { encoding: 'utf8' });
+        return;
+    }
+    if (process.platform === 'darwin') {
+        exports._internal.spawnSync('security', ['delete-certificate', '-Z', fingerprint], { stdio: 'ignore' });
+    }
+}
+/**
+ * SHA-1 fingerprint of an X.509 cert's DER bytes, in the lowercase hex form
+ * both `certutil -store` (Windows) and `security find-certificate -Z` (macOS)
+ * print, so it can be searched for directly in their output.
+ */
+function computeCertFingerprint(pemCert) {
+    const der = Buffer.from(pemCert
+        .replace('-----BEGIN CERTIFICATE-----', '')
+        .replace('-----END CERTIFICATE-----', '')
+        .replace(/\s+/g, ''), 'base64');
+    return crypto_1.default.createHash('sha1').update(der).digest('hex');
+}
+/**
+ * Live check: is this exact cert (by fingerprint, not just "a localhost cert")
+ * already present and trusted in the OS root store? Issue #1571: replaces a
+ * flag-file-based "did we already do this" record, which can silently drift
+ * from reality (a user or policy tool removes the cert from the trust store,
+ * a profile restore, etc.) with no way to recover once it does. This mirrors
+ * office-sideload.ts's isSideloaded(), which already queries the real
+ * registry/filesystem live rather than trusting a flag alone.
+ */
+function isCertTrusted(certPath) {
+    if (!fs_1.default.existsSync(certPath))
+        return false;
+    const fingerprint = computeCertFingerprint(fs_1.default.readFileSync(certPath, 'utf8'));
+    if (process.platform === 'win32') {
+        const result = (0, child_process_1.spawnSync)('certutil', ['-store', '-user', 'Root'], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return false;
+        return result.stdout.toLowerCase().includes(fingerprint);
+    }
+    if (process.platform === 'darwin') {
+        const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+        const result = (0, child_process_1.spawnSync)('security', ['find-certificate', '-a', '-c', 'localhost', '-Z', keychain], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return false;
+        return result.stdout.toLowerCase().replace(/:/g, '').includes(fingerprint);
     }
+    return false;
 }

package/dist/src/ai-hub/cli.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESKTOP_HUB_READY_TIMEOUT_ENV = void 0;
 exports.resolveDesktopReadyTimeoutMs = resolveDesktopReadyTimeoutMs;
 exports.waitForDesktopHubReady = waitForDesktopHubReady;
+exports.resolveLaunchProjectPath = resolveLaunchProjectPath;
 exports.runHub = runHub;
 // Hub-owned launcher used by the fraim-hub package. Keep this outside
 // src/cli/commands so the core fraim package has no Hub command implementation.
@@ -203,10 +204,38 @@ async function waitForDesktopHubReady(child, preferredPort, options = {}) {
         + `${stillRunning}`
         + ` Set ${exports.DESKTOP_HUB_READY_TIMEOUT_ENV} to a larger value if this machine needs longer.`);
 }
+/**
+ * Issue #1253: which project this launch is for, decided at the launch boundary.
+ *
+ * cwd affinity lives HERE rather than in the server, and the placement is the point.
+ * `resolveHubProjectPath` in server.ts has no access to a launch directory at all, so
+ * the #866 R2 guarantee — the server never substitutes `process.cwd()` — stays
+ * literally true rather than true by convention. What changes is only what the launch
+ * surface may hand it: an invocation directory that is already a FRAIM project is an
+ * intentional project and may be adopted; an uninitialized one never becomes one.
+ *
+ * An explicit `--project-path` is passed through verbatim. The server gates it (it is
+ * recorded only when it is a real FRAIM project), so the CLI does not second-guess a
+ * path the user typed.
+ *
+ * Exported for tests: this is the whole cwd-eligibility rule, and it is a pure
+ * function of (flag, cwd).
+ */
+function resolveLaunchProjectPath(explicitProjectPath, cwd = process.cwd()) {
+    if (explicitProjectPath)
+        return path_1.default.resolve(explicitProjectPath);
+    return (0, project_fraim_paths_1.workspaceFraimExists)(cwd) ? path_1.default.resolve(cwd) : undefined;
+}
 async function runHub(options) {
     const { AiHubServer, findAvailablePort } = await Promise.resolve().then(() => __importStar(require('./server')));
     const preferredPort = options.port || (0, git_utils_1.getPort)() + 100;
-    const projectPath = options.projectPath ? path_1.default.resolve(options.projectPath) : undefined;
+    // #1253: covers the desktop child and the in-process server alike — both already
+    // read this one local.
+    const projectPath = resolveLaunchProjectPath(options.projectPath);
+    if (projectPath && !options.projectPath) {
+        // A surprising project selection must be traceable to the launch directory.
+        console.log(`[ai-hub] launch project adopted from cwd: ${projectPath}`);
+    }
     const runtimeId = options.runtimeId || process.env.FRAIM_HUB_RUNTIME_ID || 'hub';
     if (options.open) {
         const wantDesktop = !options.browser;

package/dist/src/ai-hub/desktop-main.js

@@ -11,6 +11,7 @@ const fs_1 = __importDefault(require("fs"));
 const server_1 = require("./server");
 const cert_store_1 = require("./cert-store");
 const office_sideload_1 = require("./office-sideload");
+const office_setup_policy_1 = require("./office-setup-policy");
 const remote_hub_gateway_1 = require("./remote-hub-gateway");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const version_utils_1 = require("../cli/utils/version-utils");
@@ -214,6 +215,28 @@ function checkForRelaunchAttemptUpdate() {
 // ---------------------------------------------------------------------------
 // Word manifest sideload (runs once on first launch)
 // ---------------------------------------------------------------------------
+// Trusting the loopback cert prompts a one-time OS security dialog (Windows
+// "certutil" store-write, macOS Touch ID/password for keychain trust), so it
+// must not run on every launch. Issue #1571 PR feedback: rather than record
+// "already done" in a flag file that can drift from reality (the cert gets
+// removed from the OS trust store by a user, a policy tool, a profile
+// restore, with no way to recover once the flag lies), check the OS trust
+// store live via isCertTrusted() - the same live-check pattern office-sideload.ts's
+// isSideloaded() already uses instead of trusting a flag alone.
+function ensureCertTrustedOnce(certPath) {
+    if ((0, cert_store_1.isCertTrusted)(certPath))
+        return;
+    try {
+        (0, cert_store_1.trustCert)(certPath);
+    }
+    catch (err) {
+        console.warn('[fraim] could not trust localhost certificate:', err);
+    }
+}
+// Issue: Word add-in sideload must run once on initial install and then just be
+// checked (not re-run, not re-prompted) on every later Hub launch. isSideloaded()
+// plus the version+port flag below make this idempotent: unchanged state returns
+// immediately with no registry write and no dialog.
 function ensureWordSideload(projectPath, httpsPort) {
     // Flag version bump: bump this string when new manifests are added so all
     // users get re-sideloaded on their next launch.
@@ -238,12 +261,12 @@ function ensureWordSideload(projectPath, httpsPort) {
     fs_1.default.writeFileSync(flagPath, expectedFlag);
 }
 function shouldConfigureOfficeSideload() {
-    // Office sideload support requires installing a local HTTPS certificate into
-    // the OS trust store. On macOS that prompts "security wants to make changes
-    // to your certificate trust settings", so do not run it during ordinary Hub
-    // startup. It must be triggered by an explicit Office setup path.
-    return process.env.FRAIM_INSTALLER_LIFECYCLE_TEST !== '1'
-        && process.env.FRAIM_ENABLE_OFFICE_SIDELOAD === '1';
+    // Office setup (cert trust + manifest sideload) runs on every real Hub
+    // launch, but ensureCertTrustedOnce() and ensureWordSideload() are each
+    // internally idempotent, so in steady state neither does any work and no
+    // dialog reappears. Decision logic (env var + platform gating) lives in
+    // shouldRunOfficeSetup() (office-setup-policy.ts) — see #1571.
+    return (0, office_setup_policy_1.shouldRunOfficeSetup)(process.env, process.platform);
 }
 // ---------------------------------------------------------------------------
 // Tray setup
@@ -492,18 +515,14 @@ async function launchDesktopShell(options) {
     catch (err) {
         console.warn('[fraim] could not write hub runtime file:', err);
     }
-    // #1110: trusting the loopback cert in the OS store is a blocking `certutil` subprocess and
-    // is only needed so Word *Online* will render the task pane over HTTPS. Never do this during
-    // ordinary desktop startup; on macOS it prompts for Touch ID/password to change certificate
-    // trust settings. Keep it behind the explicit Office sideload setup path.
-    if (shouldConfigureOfficeSideload()) {
-        try {
-            (0, cert_store_1.trustCert)((0, cert_store_1.certPaths)().certPath);
-        }
-        catch (err) {
-            console.warn('[fraim] could not trust localhost certificate:', err);
-        }
-    }
+    // #1110: trusting the loopback cert in the OS store is only needed so Word
+    // *Online* will render the task pane over HTTPS, and the underlying `certutil`/
+    // `security` call can prompt an OS trust dialog (Touch ID/password on macOS).
+    // ensureCertTrustedOnce() runs this exactly once per cert, not on every launch,
+    // so the one-time Office setup happens at initial install and is just checked
+    // (no dialog, no re-run) on every later Hub launch.
+    if (shouldConfigureOfficeSideload())
+        ensureCertTrustedOnce((0, cert_store_1.certPaths)().certPath);
     if (shouldConfigureOfficeSideload())
         ensureWordSideload(resolvedProjectPath, httpsPort);
     const hubUrl = `http://127.0.0.1:${httpPort}/ai-hub/`;

package/dist/src/ai-hub/hosts.js

@@ -2250,9 +2250,19 @@ function normalizeGeminiPromptForMatch(value) {
     return String(value || '').replace(/\s+/g, ' ').trim();
 }
 class CliHostRuntime {
-    constructor(spawn = spawnHostProcess, killTree = (pid, signal) => (0, tree_kill_1.default)(pid, signal)) {
+    constructor(spawn = spawnHostProcess, killTree = (pid, signal) => (0, tree_kill_1.default)(pid, signal), 
+    // Issue #1570: a redirect's kill was previously fire-and-forget with no
+    // ceiling (see `killActiveChildWithEscalation`). Configurable (not just a
+    // module constant) so tests can prove the retry/escalation behavior in
+    // milliseconds instead of the real 5s production window.
+    killEscalationTimeoutMs = 5000, 
+    // Issue #1583: the initial SIGTERM counts as attempt 1; retries escalate
+    // to SIGKILL until this cap is exhausted.
+    maxKillEscalationAttempts = 10) {
         this.spawn = spawn;
         this.killTree = killTree;
+        this.killEscalationTimeoutMs = killEscalationTimeoutMs;
+        this.maxKillEscalationAttempts = maxKillEscalationAttempts;
         // Issue #1176: active continuation runs keyed by `${hostId}::${sessionId}` (R1,
         // R13, R14). Lives on this long-lived singleton instance, in-memory only (R15).
         // `spawn`/`killTree` are constructor-injectable so tests can prove queueing,
@@ -2307,6 +2317,8 @@ class CliHostRuntime {
         const active = this.activeContinueRuns.get(key);
         if (!active)
             return false;
+        if (active.escalationTimer != null)
+            clearTimeout(active.escalationTimer);
         active.pending.splice(0);
         this.activeContinueRuns.delete(key);
         if (active.child.pid == null)
@@ -2337,12 +2349,7 @@ class CliHostRuntime {
         if (entry.deliveryIntent === 'stop') {
             active.pending.unshift(entry);
             if (active.child.pid != null) {
-                try {
-                    this.killTree(active.child.pid, 'SIGTERM');
-                }
-                catch {
-                    // Best-effort: `close` still fires on normal process exit either way.
-                }
+                this.killActiveChildWithEscalation(key, active);
             }
         }
         else {
@@ -2357,11 +2364,75 @@ class CliHostRuntime {
     spawnAndRegister(key, hostId, sessionId, entry) {
         const plan = (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(entry.direct ? buildDirectContinuePlan(hostId, sessionId, entry.message) : buildContinuePlan(hostId, sessionId, entry.message), entry.launchContext?.agent, entry.launchContext?.env);
         const child = this.spawn(hostId, plan, entry.projectPath, entry.handlers);
-        const runEntry = { child, pending: [] };
+        const runEntry = { child, pending: [], handlers: entry.handlers };
         this.activeContinueRuns.set(key, runEntry);
-        child.once('close', () => this.dequeueNext(key, hostId, sessionId, runEntry));
+        child.once('close', () => {
+            // Issue #1570: a redirect kill that eventually takes (just slower than
+            // the escalation window) must not leave its retry timer dangling past
+            // this point — the process it was trying to kill is already gone.
+            if (runEntry.escalationTimer != null) {
+                clearTimeout(runEntry.escalationTimer);
+                runEntry.escalationTimer = undefined;
+            }
+            this.dequeueNext(key, hostId, sessionId, runEntry);
+        });
         return child;
     }
+    // Issue #1570 (Defect 1): the redirect kill was previously fire-and-forget
+    // — `killTree` was called once, with no way to know whether it actually
+    // took, and no ceiling on how long the queued correction could sit behind
+    // a stale turn if it silently didn't (a resistant/reparented descendant, a
+    // stuck `taskkill /T`). This bounds the wait: if the active child's `close`
+    // event hasn't fired within `killEscalationTimeoutMs`, retry the kill and
+    // signal the active turn's own handlers so the manager sees a visible
+    // "still interrupting" state instead of the old turn's output silently
+    // continuing forever. Retries are capped by `maxKillEscalationAttempts`, so
+    // a permanently wedged process produces a final failure signal instead of an
+    // unbounded escalation loop.
+    killActiveChildWithEscalation(key, active, attempt = 1) {
+        const pid = active.child.pid;
+        if (pid == null)
+            return;
+        const maxAttempts = Math.max(1, Math.floor(this.maxKillEscalationAttempts));
+        // Issue #1570: the first attempt is a normal SIGTERM; every retry escalates
+        // to SIGKILL, matching the issue's own suggested "re-issue a forceful kill"
+        // shape. On Windows this is a no-op (tree-kill's win32 branch always runs
+        // `taskkill /T /F` regardless of signal), but on POSIX a resistant process
+        // that ignored SIGTERM gets an unignorable SIGKILL from the second attempt on.
+        try {
+            this.killTree(pid, attempt === 1 ? 'SIGTERM' : 'SIGKILL');
+        }
+        catch {
+            // Best-effort: `close` still fires on normal process exit either way.
+        }
+        if (active.escalationTimer != null)
+            clearTimeout(active.escalationTimer);
+        active.escalationTimer = setTimeout(() => {
+            active.escalationTimer = undefined;
+            // The child already closed (and this entry was replaced/removed via
+            // dequeueNext) — nothing left to escalate.
+            if (this.activeContinueRuns.get(key) !== active)
+                return;
+            if (attempt >= maxAttempts) {
+                try {
+                    active.handlers.onInterruptFailed?.({ attempts: attempt, timeoutMs: this.killEscalationTimeoutMs });
+                }
+                catch (error) {
+                    console.warn('[ai-hub] onInterruptFailed handler threw:', error instanceof Error ? error.message : String(error));
+                }
+                console.warn('[ai-hub] redirect kill did not close after maximum escalation attempts:', { key, pid, attempts: attempt });
+                return;
+            }
+            try {
+                active.handlers.onInterruptStalled?.({ attempt, timeoutMs: this.killEscalationTimeoutMs });
+            }
+            catch (error) {
+                console.warn('[ai-hub] onInterruptStalled handler threw:', error instanceof Error ? error.message : String(error));
+            }
+            console.warn('[ai-hub] redirect kill did not close within the escalation window; retrying:', { key, pid, attempt });
+            this.killActiveChildWithEscalation(key, active, attempt + 1);
+        }, this.killEscalationTimeoutMs);
+    }
     // R4-R6, R9, R16 (batch-delivery per issue #1176 Round 2 design feedback):
     // when the active child closes, drain every pending continuation at once
     // (FIFO), join their messages into a single combined turn, and spawn exactly

package/dist/src/ai-hub/office-setup-policy.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Pure decision logic for desktop Office setup (loopback cert trust + Word/
+ * Excel/PowerPoint manifest sideload), extracted out of desktop-main.ts so it
+ * can be unit-tested without an Electron runtime (mirrors the
+ * window-open-decision.ts pure-function pattern - see architecture.md).
+ *
+ * All I/O (registry writes, certutil/security spawns) stays in desktop-main.ts
+ * and cert-store.ts; this module only decides whether to attempt it at all.
+ * Cert-trust idempotency itself is a live OS-state check (cert-store.ts's
+ * isCertTrusted()), not a flag file, so it has no decision logic to extract
+ * here - see #1571 PR feedback.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldRunOfficeSetup = shouldRunOfficeSetup;
+/**
+ * Issue #1571: a prior fix (commit 33764591c, "Avoid macOS trust prompt on
+ * normal Hub launch") gated Office setup behind FRAIM_ENABLE_OFFICE_SIDELOAD,
+ * an env var nothing else in the codebase ever set - so setup silently never
+ * ran on any platform. Office setup must run on every real launch on the
+ * platforms that support it; ensureCertTrustedOnce()/ensureWordSideload() in
+ * desktop-main.ts are each independently idempotent, so in steady state this
+ * returning true does no actual work and shows no dialog.
+ *
+ * Linux has no native Office desktop apps - office-sideload.ts and
+ * cert-store.ts both have no real implementation there - so it is excluded
+ * here rather than attempted and logged as "Unsupported platform" on every
+ * launch (FRAIM ships a Linux desktop build; see packages/fraim-hub/package.json).
+ */
+function shouldRunOfficeSetup(env, platform) {
+    return env.FRAIM_INSTALLER_LIFECYCLE_TEST !== '1'
+        && (platform === 'win32' || platform === 'darwin');
+}

package/dist/src/ai-hub/office-sideload.js

@@ -22,6 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = exports.WEF_DEVELOPER_KEY = void 0;
 exports.manifestXmlForPort = manifestXmlForPort;
 exports.shouldSkipSideloadForFlag = shouldSkipSideloadForFlag;
 exports.winDeveloperManifestSubkey = winDeveloperManifestSubkey;
@@ -32,7 +33,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
-const WEF_DEVELOPER_KEY = 'HKCU\\SOFTWARE\\Microsoft\\Office\\16.0\\WEF\\Developer';
+exports.WEF_DEVELOPER_KEY = 'HKCU\\SOFTWARE\\Microsoft\\Office\\16.0\\WEF\\Developer';
 const MANIFESTS = [
     {
         guid: 'd1090951-50cf-4cf2-9d12-b0f8541d265c',
@@ -93,7 +94,7 @@ function prepareManifestForSideload(entry, sourcePath, options) {
 // Windows registry helpers
 // ---------------------------------------------------------------------------
 function winDeveloperManifestSubkey(guid) {
-    return `${WEF_DEVELOPER_KEY}\\{${guid}}`;
+    return `${exports.WEF_DEVELOPER_KEY}\\{${guid}}`;
 }
 function parseRegSzValue(stdout) {
     const line = stdout.split(/\r?\n/).find(l => l.includes('REG_SZ'));
@@ -103,7 +104,7 @@ function parseRegSzValue(stdout) {
     return line.slice(idx + 'REG_SZ'.length).trim() || null;
 }
 function winRegisteredRootValue(guid) {
-    const r = (0, child_process_1.spawnSync)('reg', ['query', WEF_DEVELOPER_KEY, '/v', guid], { encoding: 'utf8' });
+    const r = (0, child_process_1.spawnSync)('reg', ['query', exports.WEF_DEVELOPER_KEY, '/v', guid], { encoding: 'utf8' });
     if (r.status !== 0 || !r.stdout.includes('REG_SZ'))
         return null;
     // Output line looks like: "    <guid>    REG_SZ    C:\path\to\manifest.xml"
@@ -122,14 +123,21 @@ function winRegisteredValue(guid) {
     // but treat the root value as the effective discovery registration.
     return winRegisteredRootValue(guid) ?? winRegisteredDefaultValue(guid);
 }
+/**
+ * Test seam (issue #1589): the registry-write invocations go through this mutable,
+ * module-owned indirection point instead of a bare `spawnSync` call, so a test can swap in a
+ * fake implementation and assert on the exact `reg` command/arguments `sideloadManifest()`
+ * would invoke, without spawning a process, touching PATH, or mutating the real registry.
+ */
+exports._internal = { spawnSync: child_process_1.spawnSync };
 function winWriteRegisteredValue(guid, manifestPath) {
-    const root = (0, child_process_1.spawnSync)('reg', [
-        'add', WEF_DEVELOPER_KEY,
+    const root = exports._internal.spawnSync('reg', [
+        'add', exports.WEF_DEVELOPER_KEY,
         '/v', guid, '/t', 'REG_SZ', '/d', manifestPath, '/f',
     ], { encoding: 'utf8' });
     if (root.status !== 0)
         return { ok: false, reason: root.stderr || `reg add failed for ${guid}` };
-    const r = (0, child_process_1.spawnSync)('reg', [
+    const r = exports._internal.spawnSync('reg', [
         'add', winDeveloperManifestSubkey(guid),
         '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f',
     ], { encoding: 'utf8' });
@@ -137,7 +145,7 @@ function winWriteRegisteredValue(guid, manifestPath) {
         return { ok: false, reason: r.stderr || `reg add failed for ${guid}` };
     // Remove an accidental unbraced subkey left by older debugger settings. This
     // is different from the root named value above, which Word needs.
-    (0, child_process_1.spawnSync)('reg', ['delete', `${WEF_DEVELOPER_KEY}\\${guid}`, '/f'], { encoding: 'utf8' });
+    exports._internal.spawnSync('reg', ['delete', `${exports.WEF_DEVELOPER_KEY}\\${guid}`, '/f'], { encoding: 'utf8' });
     return { ok: true };
 }
 // ---------------------------------------------------------------------------
@@ -195,8 +203,8 @@ function sideloadManifest(projectPath, options = {}) {
 function removeSideload() {
     for (const entry of MANIFESTS) {
         if (process.platform === 'win32') {
-            (0, child_process_1.spawnSync)('reg', ['delete', WEF_DEVELOPER_KEY, '/v', entry.guid, '/f'], { encoding: 'utf8' });
-            (0, child_process_1.spawnSync)('reg', ['delete', `${WEF_DEVELOPER_KEY}\\${entry.guid}`, '/f'], { encoding: 'utf8' });
+            (0, child_process_1.spawnSync)('reg', ['delete', exports.WEF_DEVELOPER_KEY, '/v', entry.guid, '/f'], { encoding: 'utf8' });
+            (0, child_process_1.spawnSync)('reg', ['delete', `${exports.WEF_DEVELOPER_KEY}\\${entry.guid}`, '/f'], { encoding: 'utf8' });
             (0, child_process_1.spawnSync)('reg', ['delete', winDeveloperManifestSubkey(entry.guid), '/f'], { encoding: 'utf8' });
         }
         else if (process.platform === 'darwin') {