@openrig/cli 0.6.11 → 0.6.13

package/daemon/dist/adapters/claude-code-adapter.js

@@ -5,11 +5,12 @@ import { createHash, randomUUID } from "node:crypto";
 import { claudePostureFlag, claudeClassicRendererEnvPrefix } from "./yolo-mode.js";
 import { resolveConcreteHint } from "../domain/runtime-adapter.js";
 import { assessNativeResumeProbe } from "../domain/native-resume-probe.js";
-import { observeClaudePaneProcess } from "../domain/native-process-lineage.js";
+import { resolveReadinessTimeoutMs } from "../domain/readiness-timeout.js";
+import { subtreeNamesClaudeExecutable, claudeCommandSessionToken, listNativeProcesses, observeClaudeDelivery, observeClaudePaneProcess, observeClaudePaneRuntime, observeCodexPaneProcess, verifyCodexPaneProcess, verifyPaneIdleShell } from "../domain/native-process-lineage.js";
 import { mergeManagedBlock, DEFAULT_CLAUDE_MANAGED_BLOCK_FILE } from "../domain/managed-blocks.js";
 import { claudeResumeLaunchEnv, claudeResumeLaunchPrefix } from "./claude-resume-launch.js";
 import { shellQuote } from "./shell-quote.js";
-import { validateClaudeActivityHookDelivery, claudeActivityRelayPath, CLAUDE_ACTIVITY_RELAY_RELATIVE_PATH } from "../domain/claude-activity-hooks.js";
+import { validateClaudeActivityHookDelivery, claudeActivityRelayPath, CLAUDE_ACTIVITY_RELAY_RELATIVE_PATH, parseManagedClaudeNodeCommand } from "../domain/claude-activity-hooks.js";
 import { isFilesystemRoot } from "../domain/cwd-resolution.js";
 import { observeClaudePermission } from "../domain/permission-drift.js";
 import { unresolvedClaudePermissionModes } from "../domain/native-permission-selection.js";
@@ -28,8 +29,10 @@ export class ClaudeCodeAdapter {
     sleep;
     stateDir;
     collectorAssetPath;
+    nodeExecutable;
     autoDriveProviderPrompts;
     listProcesses;
+    readinessTimeoutMs;
     autoLaunches = new Map();
     claudeManagedLaunch;
     activityRelayPath;
@@ -45,8 +48,10 @@ export class ClaudeCodeAdapter {
         this.sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
         this.stateDir = deps.stateDir ?? null;
         this.collectorAssetPath = deps.collectorAssetPath ?? null;
+        this.nodeExecutable = deps.nodeExecutable ?? process.execPath;
         this.autoDriveProviderPrompts = deps.autoDriveProviderPrompts ?? false;
         this.listProcesses = deps.listProcesses;
+        this.readinessTimeoutMs = deps.readinessTimeoutMs;
         this.claudeManagedLaunch = deps.claudeManagedLaunch;
         this.activityRelayPath = deps.activityRelayPath ?? null;
         this.claudeHooksManifestPath = deps.claudeHooksManifestPath ?? null;
@@ -279,7 +284,9 @@ export class ClaudeCodeAdapter {
         if (!enterResult.ok) {
             return { ok: false, error: `Failed to send Enter: ${enterResult.message}` };
         }
-        const launch = { binding, token: opts.resumeToken ?? generatedSessionId, executable: managed?.executable };
+        const launch = { binding, token: opts.resumeToken ?? generatedSessionId,
+            freshInPlace: opts.freshInPlace === true && !opts.resumeToken, executable: managed?.executable,
+            scriptLaunch: managed?.executableIsScript };
         this.autoLaunches.set(binding.nodeId, launch);
         if (opts.resumeToken) {
             const verification = await this.verifyResumeLaunch(binding);
@@ -304,7 +311,18 @@ export class ClaudeCodeAdapter {
         }
         const paneCommand = await this.tmux.getPaneCommand(binding.tmuxSession);
         const paneContent = (await this.tmux.capturePaneContent(binding.tmuxSession, 40)) ?? "";
-        const probe = await this.assessManagedProbe(binding, paneCommand, paneContent);
+        const historyProbe = await this.assessManagedProbe(binding, paneCommand, paneContent);
+        const probe = await this.assessFreshInPlaceProbe(binding, paneCommand, historyProbe);
+        // A script-launched Claude reads as `sh` until the script hands over the foreground, so the label alone
+        // is not a return to a shell. Say so only for a proven idle shell (the rule Codex's checkReady uses).
+        if (probe.code === "returned_to_shell"
+            && !await verifyPaneIdleShell({ target: binding.tmuxSession, tmux: this.tmux, listProcesses: this.listProcesses })) {
+            return {
+                ready: false,
+                reason: "The pane shows a shell that is not a proven idle shell; a launch script may still be starting Claude.",
+                code: "awaiting_runtime",
+            };
+        }
         if (probe.status === "resumed")
             return { ready: true };
         return { ready: false, reason: probe.detail, code: probe.code };
@@ -318,6 +336,50 @@ export class ClaudeCodeAdapter {
         this.provisionManagedBootstrap(binding);
     }
     // -- Private helpers --
+    /** A fresh in-place launch keeps the retiree's scrollback. Qualify a history-based ready result
+     * with the current frame, only for the exact launch that requested it. Unavailable observations
+     * retain the old admission (including its ambiguity); visible gates and conflicting identity do not. */
+    async assessFreshInPlaceProbe(binding, paneCommand, historyProbe) {
+        const launch = this.autoLaunches.get(binding.nodeId);
+        if (historyProbe.status !== "resumed" || !launch?.freshInPlace || !binding.tmuxPane || !binding.tmuxSession
+            || launch.binding.id !== binding.id || launch.binding.tmuxPane !== binding.tmuxPane
+            || launch.binding.tmuxSession !== binding.tmuxSession
+            || launch.binding.launchGeneration !== binding.launchGeneration)
+            return historyProbe;
+        let screen = null;
+        try {
+            screen = await this.tmux.capturePaneScreen(binding.tmuxPane);
+        }
+        catch { /* unavailable */ }
+        // Missing process evidence is unknown, not a conflicting recipient. Reuse the launch observer's
+        // positive conflict distinction without requiring process proof for ordinary ready frames.
+        let occupant = "unknown";
+        try {
+            occupant = await this.paneOccupant(binding, false, { positiveConflictOnly: true });
+        }
+        catch { /* unavailable */ }
+        if (this.autoLaunches.get(binding.nodeId) !== launch)
+            return {
+                status: "inconclusive", code: "awaiting_runtime", detail: "The fresh launch changed during readiness observation.",
+            };
+        if (occupant === "another")
+            return {
+                status: "inconclusive", code: "claude_launch_identity_conflict",
+                detail: "A different runtime identity occupies the fresh launch's pane.",
+            };
+        if (!screen?.trim())
+            return historyProbe;
+        const current = await this.assessManagedProbe(binding, paneCommand, screen);
+        if (this.autoLaunches.get(binding.nodeId) !== launch)
+            return {
+                status: "inconclusive", code: "awaiting_runtime", detail: "The fresh launch changed during readiness observation.",
+            };
+        // A shell prompt can also start with ❯. Keep the headerless fallback only when process
+        // evidence cannot rule Claude out; a readable shell/script-only pane uses the current result.
+        const withIdentity = assessNativeResumeProbe({ runtime: "claude-code", paneCommand, paneContent: screen,
+            claudeAutoIdentityVerified: true, claudeResumeIdentityVerified: true });
+        return withIdentity.status === "resumed" && occupant !== "absent" ? historyProbe : current;
+    }
     async assessManagedProbe(binding, paneCommand, paneContent) {
         const input = { runtime: "claude-code", paneCommand, paneContent };
         const probe = assessNativeResumeProbe(input);
@@ -339,36 +401,107 @@ export class ClaudeCodeAdapter {
             if (panes.length !== 1 || panes[0]?.id !== binding.tmuxPane)
                 return probe;
             const observation = { target: binding.tmuxPane, tmux: this.tmux,
-                listProcesses: this.listProcesses, expectedToken: launch.token, selectedExecutable: launch.executable };
+                listProcesses: this.listProcesses, expectedToken: launch.token, selectedExecutable: launch.executable,
+                scriptLaunch: launch.scriptLaunch };
             const first = await observeClaudePaneProcess(observation);
             if (!first)
                 return probe;
             // Pin the first exact process for this launch; retries cannot adopt a replacement. It is also
-            // the launch's record of the process it started (#1077).
-            if (!launch.fingerprint) {
+            // the launch's record of the process it started (#1077). A process found through a script launch
+            // is trusted on its first sight only once every other check has passed (below), so that an
+            // unconfirmed sample is not what the launch is held to.
+            const pin = () => {
                 launch.fingerprint = first.fingerprint;
                 if (first.process.startedAt)
                     launch.process = { pid: first.process.pid, startedAt: first.process.startedAt };
-            }
-            if (first.fingerprint !== launch.fingerprint)
+            };
+            if (!launch.fingerprint && !first.afterScript)
+                pin();
+            if (launch.fingerprint !== undefined && first.fingerprint !== launch.fingerprint)
                 return probe;
             const native = await observeClaudePaneProcess(observation);
-            if (native?.fingerprint !== launch.fingerprint)
+            if (native?.fingerprint !== first.fingerprint)
                 return probe;
             const currentPanes = await this.tmux.listPanes(binding.tmuxSession);
             if (this.autoLaunches.get(binding.nodeId) !== launch || currentPanes.length !== 1
                 || currentPanes[0]?.id !== binding.tmuxPane
                 || await this.tmux.getPanePid(binding.tmuxSession) !== native.panePid)
                 return probe;
+            if (!launch.fingerprint)
+                pin();
+            // Another check of this launch can pin while this one awaits; only the pinned process is verified.
+            if (launch.fingerprint !== first.fingerprint)
+                return probe;
             return verifiedProbe;
         }
         catch {
             return probe;
         }
     }
+    /** tmux names a shell for every OpenRig launch (the launch script is `sh`), so its word alone can't say
+     *  Claude is gone. With a bound pane, the process tree must show the pane's shell holding the terminal with
+     *  nothing under it; Claude, or a launch script about to start it, is a slow resume. */
+    async paneReturnedToShell(binding, paneCommand) {
+        if (!paneCommand || !SHELL_COMMANDS.has(paneCommand))
+            return false;
+        if (!binding.tmuxPane)
+            return true;
+        const observed = await observeClaudeDelivery({ target: binding.tmuxPane, tmux: this.tmux, listProcesses: this.listProcesses }, { unknownKeepsIdle: false });
+        return observed.state === "idle_shell";
+    }
+    /** Who holds the pane, by the observations already there. "another": positively something other than this launch's own
+     *  start: a ready screen whose lineage failed the check (with a process list that could be read), a Claude naming
+     *  another conversation, or a stable Codex. Waiting won't make any of them this launch's, and its token is not recorded
+     *  as an attempt. "own": this launch's Claude. "unknown": nothing seen yet (the launch script is starting it) or a
+     *  process list that can't be read, whatever the screen shows. One process listing serves the Claude observations. */
+    async paneOccupant(binding, looksReady, options = {}) {
+        const launch = this.autoLaunches.get(binding.nodeId);
+        if (!binding.tmuxPane || !launch)
+            return looksReady ? "another" : "unknown";
+        let rows;
+        try {
+            rows = await (this.listProcesses ?? (() => listNativeProcesses({ claudeLaunchPaths: launch.scriptLaunch === true })))();
+        }
+        catch {
+            return "unknown";
+        }
+        if (looksReady)
+            return "another";
+        const observation = { target: binding.tmuxPane, tmux: this.tmux, listProcesses: () => rows, selectedExecutable: launch.executable,
+            scriptLaunch: launch.scriptLaunch };
+        if (await observeClaudePaneProcess({ ...observation, expectedToken: launch.token }))
+            return "own";
+        const native = await observeClaudePaneRuntime(observation);
+        if (native) {
+            if (!options.positiveConflictOnly)
+                return "another";
+            // Fresh readiness keeps unidentified Claude processes unknown; strict resume callers above
+            // retain their existing rule. Reuse the exact argv parser, not a best-effort token search.
+            const named = claudeCommandSessionToken(native.process.command);
+            return named !== null && named !== launch.token ? "another" : "unknown";
+        }
+        if (await observeCodexPaneProcess(observation)) {
+            return await verifyCodexPaneProcess({ ...observation, listProcesses: this.listProcesses }) ? "another" : "unknown";
+        }
+        if (!options.positiveConflictOnly)
+            return "unknown";
+        const panePid = await this.tmux.getPanePid(binding.tmuxPane);
+        // Missing pane identity is unavailable evidence. A Claude elsewhere in this pane's subtree
+        // remains unproven, rather than absent, even if it is not a foreground candidate yet.
+        return panePid && rows.some(row => row.pid === panePid) && !subtreeNamesClaudeExecutable(rows, panePid)
+            ? "absent" : "unknown";
+    }
     async verifyResumeLaunch(binding) {
         const tmuxSession = binding.tmuxSession;
-        const attempts = 16;
+        // A quick window, then a longer one only while the boot is still in progress, as the Codex adapter does it.
+        // The longer one is the readiness setting less the quick window, as a number of polls counted from here; it is per
+        // seat, nothing is shared across the seats of a restore. A setting no longer than the quick window adds no polls, but
+        // an unresolved boot is still kept (attention_required) rather than failed.
+        const pollMs = 200;
+        const windowAttempts = 16;
+        const checkEvery = 5;
+        let attempts = windowAttempts;
+        let slowStart = false;
         for (let attempt = 0; attempt < attempts; attempt++) {
             const paneCommand = await this.tmux.getPaneCommand(tmuxSession);
             const paneContent = (await this.tmux.capturePaneContent(tmuxSession, 40)) ?? "";
@@ -396,6 +529,12 @@ export class ClaudeCodeAdapter {
                 };
             }
             if (this.autoDriveProviderPrompts && probe.code === "trust_gate") {
+                // In the longer wait the occupant has not been looked at since the window ended: press Enter only for this launch's
+                // own Claude. Anything else keeps main's result, as if the loop had ended.
+                if (slowStart && await this.paneOccupant(binding, false) !== "own") {
+                    slowStart = false;
+                    break;
+                }
                 const enterResult = await this.tmux.sendKeys(tmuxSession, ["Enter"]);
                 if (!enterResult.ok) {
                     return { ok: false, error: `Claude trust prompt auto-drive failed: ${enterResult.message}` };
@@ -403,8 +542,48 @@ export class ClaudeCodeAdapter {
                 await this.sleep(200);
                 continue;
             }
+            // Only a boot in progress (no verdict, no gate, a label that proves nothing) is worth waiting for; a real
+            // gate (login, trust or MCP approval, auto-mode identity) won't clear itself.
+            const booting = probe.code === "awaiting_runtime" || probe.code === "returned_to_shell";
+            if (slowStart && !booting) {
+                slowStart = false;
+                break;
+            }
+            // A start in progress can't have drawn Claude's ready screen. One that has, with its lineage unproven, keeps
+            // main's result whenever it draws: at the window's end, or at any poll of the longer wait.
+            const looksReady = (attempt === windowAttempts - 1 || slowStart) && booting
+                && assessNativeResumeProbe({ runtime: "claude-code", paneCommand, paneContent,
+                    claudeAutoIdentityVerified: true, claudeResumeIdentityVerified: true }).status === "resumed";
+            if (slowStart && looksReady && await this.paneOccupant(binding, true) === "another") {
+                slowStart = false;
+                break;
+            }
+            // Checked where the window ends and then about once a second of the longer wait (two listings for the shell, one for
+            // the occupant), not on every poll. A shell label can't tell Claude having exited from the launch script not having
+            // started it yet, and the occupant can change while we wait, so the process tree decides.
+            const windowEnd = attempt === windowAttempts - 1;
+            if (booting && (windowEnd || (slowStart && (attempt - windowAttempts + 1) % checkEvery === 0))) {
+                if (await this.paneReturnedToShell(binding, await this.tmux.getPaneCommand(tmuxSession))) {
+                    // Provably back at its shell: the final check reports it. If it isn't by then, the seat is kept.
+                    if (slowStart) {
+                        attempts = attempt + 1;
+                        break;
+                    }
+                }
+                else if (await this.paneOccupant(binding, looksReady) === "another") {
+                    // Not this launch's start: keep main's result.
+                    slowStart = false;
+                    break;
+                }
+                else if (windowEnd) {
+                    // A boot in progress, or one we can't see: keep the launch past the window even when the readiness setting
+                    // leaves no room for more polls (1 to 3 s), so it ends as attention_required, not as the failure that loses the token.
+                    attempts = windowAttempts + Math.floor(Math.max(0, resolveReadinessTimeoutMs(this.readinessTimeoutMs) - windowAttempts * pollMs) / pollMs);
+                    slowStart = true;
+                }
+            }
             if (attempt < attempts - 1) {
-                await this.sleep(200);
+                await this.sleep(pollMs);
             }
         }
         const finalCommand = await this.tmux.getPaneCommand(tmuxSession);
@@ -430,19 +609,34 @@ export class ClaudeCodeAdapter {
                 missingConversation: true,
             };
         }
-        if (finalCommand && SHELL_COMMANDS.has(finalCommand)) {
+        if (await this.paneReturnedToShell(binding, finalCommand)) {
             return {
                 ok: false,
                 error: "Claude resume failed: pane returned to shell instead of entering Claude",
                 recovery: "retry_fresh",
             };
         }
+        // The occupant can change after the last check in the loop, so the end of the wait looks once more, with the screen
+        // judged as in the loop: a different occupant (or a ready-looking screen on a readable list) keeps main's result.
+        if (slowStart && (finalProbe.code === "awaiting_runtime" || finalProbe.code === "returned_to_shell")
+            && await this.paneOccupant(binding, assessNativeResumeProbe({ runtime: "claude-code", paneCommand: finalCommand, paneContent: finalContent,
+                claudeAutoIdentityVerified: true, claudeResumeIdentityVerified: true }).status === "resumed") !== "another") {
+            // Claude, or the script about to start it, may still be coming up. Keep the launch and its resume token for
+            // a person (or the reconciler) rather than failing a seat that may be running. Never `resumed` from this.
+            return {
+                ok: false,
+                error: `Claude resume did not finish within ${Math.round(attempts * pollMs / 1000)}s; Claude may still be starting, so the launch was kept`,
+                recovery: "attention_required",
+                evidence: finalContent.split("\n").slice(-12).join("\n"),
+            };
+        }
         return { ok: false, error: "Claude resume failed: timed out waiting for Claude to become active" };
     }
     projectEntry(entry, cwd, managedBlockFile, warnings) {
-        if (entry.category === "runtime_resource" && this.applyRuntimeResource(entry, cwd)) {
-            return true;
-        }
+        // A skipped fragment is reported skipped; it never falls through to the generic extensions copy.
+        const handled = entry.category === "runtime_resource" ? this.applyRuntimeResource(entry, cwd, warnings) : false;
+        if (handled)
+            return handled === true;
         if (entry.category === "guidance" && entry.mergeStrategy === "managed_block") {
             const targetPath = nodePath.join(cwd, managedBlockFile);
             const content = this.fs.readFile(entry.absolutePath);
@@ -533,14 +727,13 @@ export class ClaudeCodeAdapter {
             default: return null;
         }
     }
-    applyRuntimeResource(entry, cwd) {
+    /** true when applied, "skipped" when handled but not applied, false when this isn't a resource it handles. */
+    applyRuntimeResource(entry, cwd, warnings) {
         switch (entry.resourceType) {
             case "claude_settings_fragment":
-                this.mergeJsonFragment(entry.absolutePath, nodePath.join(cwd, ".claude", "settings.local.json"));
-                return true;
+                return this.mergeJsonFragment(entry.absolutePath, nodePath.join(cwd, ".claude", "settings.local.json"), warnings) || "skipped";
             case "claude_mcp_fragment":
-                this.mergeJsonFragment(entry.absolutePath, nodePath.join(cwd, ".mcp.json"));
-                return true;
+                return this.mergeJsonFragment(entry.absolutePath, nodePath.join(cwd, ".mcp.json"), warnings) || "skipped";
             case "claude_activity_hooks":
                 // Handled (no generic .claude/extensions copy): the relay asset is
                 // delivered + the settings hooks reconciled by reconcileClaudeActivityHooks
@@ -550,12 +743,43 @@ export class ClaudeCodeAdapter {
                 return false;
         }
     }
-    mergeJsonFragment(sourcePath, targetPath) {
+    /** Merge a JSON fragment into a project file. An existing target that can't be read, or isn't a JSON object (it
+     *  doesn't parse, or it holds an array or a single value), belongs to its owner: it's left as it is, nothing is
+     *  merged, and a warning says so. Returns whether the fragment was applied. */
+    mergeJsonFragment(sourcePath, targetPath, warnings) {
         const fragment = this.readJsonObjectStrict(sourcePath);
-        const existing = this.readJsonObject(targetPath);
+        // The reasons are fixed text: a parser message can quote the file's content.
+        const leave = (reason) => {
+            warnings.push(`Left ${targetPath} as it is: ${reason}. The fragment ${sourcePath} wasn't applied; once the file is fixed, the next fresh launch applies it (resuming or restoring the session doesn't).`);
+            return false;
+        };
+        let existing = {};
+        if (this.fs.exists(targetPath)) {
+            let text;
+            try {
+                text = this.fs.readFile(targetPath);
+            }
+            catch {
+                return leave("it couldn't be read");
+            }
+            if (text.trim() !== "") {
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    return leave("it isn't valid JSON");
+                }
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                    return leave(`it holds ${Array.isArray(parsed) ? "a JSON array" : parsed === null ? "JSON null" : `a JSON ${typeof parsed}`}, not an object`);
+                }
+                existing = parsed;
+            }
+        }
         const merged = mergeJsonObjects(existing, fragment);
         this.fs.mkdirp(nodePath.dirname(targetPath));
         this.fs.writeFile(targetPath, JSON.stringify(merged, null, 2));
+        return true;
     }
     /**
      * Merge a managed block into the target guidance file. Returns `true` when
@@ -677,19 +901,6 @@ export class ClaudeCodeAdapter {
         }
         return Array.from(keys);
     }
-    readJsonObject(path) {
-        try {
-            if (!this.fs.exists(path))
-                return {};
-            const parsed = JSON.parse(this.fs.readFile(path));
-            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
-                ? parsed
-                : {};
-        }
-        catch {
-            return {};
-        }
-    }
     readJsonObjectStrict(path) {
         const parsed = JSON.parse(this.fs.readFile(path));
         if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
@@ -734,9 +945,9 @@ export class ClaudeCodeAdapter {
         const settingsPath = nodePath.join(binding.cwd, ".claude", "settings.local.json");
         this.fs.mkdirp(nodePath.dirname(settingsPath));
         // The seat cwd can be a shared repo whose project-local settings other sessions read (#421).
-        // Like the activity hooks, never clobber text we cannot parse. An empty file holds no settings
-        // and is treated as `{}`. Valid JSON that is not an object (for example `[]`) is still
-        // replaced, as before.
+        // Like the activity hooks, never clobber text we cannot parse, nor valid JSON that isn't an
+        // object (for example `[]`): the status line isn't installed there. An empty file holds no
+        // settings and is treated as `{}`.
         let existing = {};
         if (this.fs.exists(settingsPath)) {
             const text = this.fs.readFile(settingsPath);
@@ -748,8 +959,9 @@ export class ClaudeCodeAdapter {
                 catch {
                     return;
                 }
-                if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
-                    existing = parsed;
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                    return;
+                existing = parsed;
             }
         }
         const statusLine = typeof existing["statusLine"] === "object" && existing["statusLine"] !== null
@@ -757,10 +969,14 @@ export class ClaudeCodeAdapter {
         // A user's own status line command wins; only OpenRig's collector command is installed or refreshed.
         // If this command's shape changes, keep the old shape recognised in isOwnedCollectorCommand, or
         // seats holding it will never be refreshed.
-        const collectorCmd = `node ${shellQuote(collectorDest)} ${shellQuote(contextDir)} ${shellQuote(providerUsageDir)}`;
+        const collectorCmd = managedClaudeNodeCommand(this.nodeExecutable, collectorDest, contextDir, providerUsageDir);
         const current = statusLine["command"];
         if (typeof current === "string" && current.trim() !== "" && current !== collectorCmd && !isOwnedCollectorCommand(current))
             return;
+        // Already installed as wanted: no write. Compared by value, so another writer's key order or spacing isn't a
+        // change. This avoids rewriting on every poll; it doesn't make a needed write safe against a concurrent writer.
+        if (statusLine["type"] === "command" && current === collectorCmd)
+            return;
         existing["statusLine"] = { ...statusLine, type: "command", command: collectorCmd };
         this.fs.writeFile(settingsPath, JSON.stringify(existing, null, 2));
     }
@@ -775,14 +991,14 @@ export class ClaudeCodeAdapter {
      * commands) and report `sourceMissing` so the caller can surface a warning + not claim
      * projection. DISABLE: strip owned entries and prune emptied containers.
      *
-     * Ownership is the EXACT `node <quoted relay path>` command shape, so a stale/changed
+     * Ownership is the exact generated Node-command shape (legacy or pinned interpreter), so a stale/changed
      * absolute prefix is replaced (never duplicated) while a user command that merely CONTAINS
      * the path is preserved. Fail-closed: a settings file we cannot parse is left byte-for-byte
      * untouched. Not `mergeJsonFragment` (additive union-by-key can't strip on disable).
      */
     reconcileClaudeActivityHooks(cwd, enabled) {
         const relayDest = claudeActivityRelayPath(this.stateDir ?? undefined);
-        const ownedCmd = `node ${shellQuote(relayDest)}`;
+        const ownedCmd = managedClaudeNodeCommand(this.nodeExecutable, relayDest);
         const settingsPath = nodePath.join(cwd, ".claude", "settings.local.json");
         // PREVALIDATE BEFORE ANY MUTATION using the SHARED delivery validation (same gate
         // preflight uses — one parser, no drift). Enable is deliverable ONLY when BOTH the relay
@@ -873,10 +1089,16 @@ export class ClaudeCodeAdapter {
         return { changed: true, delivered: deliverable, sourceMissing: false, manifestUnavailable: false, settingsUnparseable: false };
     }
 }
-// OpenRig-owned relay path suffix. Ownership is the EXACT `node <arg>` command whose single
+// OpenRig-owned relay path suffix. Ownership is the generated Node command whose single
 // argument ends with this path — a changed prefix still matches (replace, not duplicate); a
 // user command that merely contains the path (echo, or node with extra args) does NOT.
 const LEGACY_OWNED_RELAY_SUFFIX = "/.openrig/hooks/scripts/activity-relay.cjs";
+function managedClaudeNodeCommand(executable, ...args) {
+    const quotedArgs = args.map(shellQuote).join(" ");
+    const pinned = `${shellQuote(executable)} ${quotedArgs}`;
+    // Keep legacy PATH resolution if this runtime's name is outside our ownership grammar.
+    return parseManagedClaudeNodeCommand(pinned) ? pinned : `node ${quotedArgs}`;
+}
 function hookCommand(hook) {
     return isPlainObject(hook) && typeof hook["command"] === "string" ? hook["command"] : undefined;
 }
@@ -887,13 +1109,9 @@ const OWNED_COLLECTOR_SUFFIX = nodePath.sep + nodePath.join(".openrig", "context
 function isOwnedCollectorCommand(cmd) {
     if (/[\r\n]/.test(cmd))
         return false;
-    const quoted = /^node ('(?:[^']|'"'"')*') ('(?:[^']|'"'"')*')(?: ('(?:[^']|'"'"')*'))?$/.exec(cmd.trim());
-    if (quoted) {
-        const tokens = quoted.slice(1).filter((token) => token !== undefined);
-        const decoded = tokens.map(unquoteSingleShellToken);
-        if (decoded.some((value, index) => value === null || shellQuote(value) !== tokens[index]))
-            return false;
-        return decoded[0].endsWith(OWNED_COLLECTOR_SUFFIX);
+    const parsed = parseManagedClaudeNodeCommand(cmd);
+    if (parsed && (parsed.args.length === 2 || parsed.args.length === 3)) {
+        return parsed.args[0].endsWith(OWNED_COLLECTOR_SUFFIX);
     }
     const tokens = cmd.trim().split(/\s+/);
     if ((tokens.length !== 3 && tokens.length !== 4) || tokens[0] !== "node")
@@ -905,31 +1123,12 @@ function isOwnedCollectorCommand(cmd) {
 function isOwnedRelayCommand(cmd) {
     if (!cmd)
         return false;
-    const m = /^node\s+(.+)$/.exec(cmd.trim());
-    if (!m)
-        return false;
-    const arg = m[1];
-    const decoded = unquoteSingleShellToken(arg);
-    if (decoded === null)
+    const parsed = parseManagedClaudeNodeCommand(cmd);
+    if (!parsed || parsed.args.length !== 1)
         return false;
-    // Canonical ONE-TOKEN round-trip: the argument must be EXACTLY one shellQuote token — re-encoding
-    // the decoded path must reproduce the argument VERBATIM. This is the ownership test's core: the
-    // command is `node ${shellQuote(relayDest)}`, so any owned entry re-encodes to itself (including
-    // an apostrophe cwd O'Brien via the '"'"' escape). It REJECTS a user command whose multiple quoted
-    // args merely concatenate to text ending in the relay suffix (e.g. `node 'x' '<relay>'`), which
-    // must never be recognised as owned and deleted.
-    if (shellQuote(decoded) !== arg)
-        return false;
-    return decoded.endsWith(LEGACY_OWNED_RELAY_SUFFIX)
-        || decoded.endsWith(`/${CLAUDE_ACTIVITY_RELAY_RELATIVE_PATH}`);
-}
-/** Decode ONE POSIX single-quoted shell token as produced by shellQuote (outer `'…'` with an
- *  embedded `'` escaped as `'"'"'`). Returns null when the token is not single-quote wrapped. The
- *  caller re-encodes to confirm the token is canonical/single — this decode alone does not. */
-function unquoteSingleShellToken(token) {
-    if (token.length < 2 || !token.startsWith("'") || !token.endsWith("'"))
-        return null;
-    return token.slice(1, -1).split(`'"'"'`).join("'");
+    const relay = parsed.args[0];
+    return relay.endsWith(LEGACY_OWNED_RELAY_SUFFIX)
+        || relay.endsWith(`/${CLAUDE_ACTIVITY_RELAY_RELATIVE_PATH}`);
 }
 function hashContent(content) {
     return createHash("sha256").update(content).digest("hex");