@kylecheng3146/agent-ops 0.1.22 → 0.2.0

package/dist/runtime/src/hooks/completion-gate.js

@@ -1,11 +1,8 @@
 import { join } from "node:path";
-import { calculateConfigHash } from "../config/hash.js";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { findReviewAttestation } from "../review/attestation.js";
-import { validateEvidence, validateTaskAgainstConfig } from "../schema/validate.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
-import { isPassingVerificationEvidence } from "../verify/evidence.js";
+import { checkTaskCompletionEvidence, findIncompleteSubtask } from "../task/completion.js";
 import { collectChangeSurface } from "../verify/change-surface.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
@@ -101,34 +98,10 @@ export class CompletionGateService {
             return { ...state, permitFingerprint: fingerprint };
         });
     }
-    #isPermitCommand(event, sessionId) {
-        if (event.event !== "command")
-            return false;
-        const tokens = [event.command, ...event.args];
-        const commandIndex = tokens.indexOf("allow-stop");
-        return commandIndex >= 0 &&
-            tokens[commandIndex + 1] === "--session" &&
-            (tokens[commandIndex + 2] === sessionId ||
-                tokens[commandIndex + 2] === "$AGENT_OPS_SESSION_ID");
-    }
-    async #hasCurrentEvidence(taskId, criterionId, command, references, configHash, sourceFingerprint) {
-        for (const reference of references) {
-            if (reference.startsWith("review:"))
-                continue;
-            const validation = validateEvidence(await this.#options.evidenceStore.load(reference));
-            if (!validation.ok)
-                continue;
-            const evidence = validation.value;
-            if (evidence.taskId === taskId &&
-                evidence.criterionId === criterionId &&
-                evidence.commandId === command.id &&
-                evidence.configHash === configHash &&
-                evidence.sourceFingerprint === sourceFingerprint &&
-                isPassingVerificationEvidence(command, evidence)) {
-                return true;
-            }
-        }
-        return false;
+    #isPermitCommand(event) {
+        const commands = event.event === "command" ? [event] :
+            event.event === "command-batch" ? event.commands : [];
+        return commands.some(({ command, args }) => [command, ...args].includes("allow-stop"));
     }
     async #validateTask(sessionId, sourceFingerprint) {
         let stored;
@@ -143,44 +116,35 @@ export class CompletionGateService {
         if (stored.status !== "complete") {
             return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_INCOMPLETE", "Complete the attached task after verification and review.");
         }
-        const taskValidation = validateTaskAgainstConfig(stored.task, this.#options.config);
-        const configHash = calculateConfigHash(this.#options.config);
-        if (!taskValidation.ok || stored.policyConfigHash !== configHash) {
-            return gateResult("block", "FAIL", "COMPLETION_GATE_TASK_STALE", "Recreate or re-verify the task against the current config.");
-        }
-        for (const criterion of stored.task.criteria) {
-            for (const commandId of criterion.verifierIds) {
-                const command = this.#options.config.verification.commands.find(({ id }) => id === commandId);
-                if (command === undefined) {
-                    return gateResult("block", "UNKNOWN", "COMPLETION_GATE_EVIDENCE_UNAVAILABLE", "Configured task evidence cannot be resolved.");
-                }
-                if (command.required &&
-                    !(await this.#hasCurrentEvidence(stored.task.id, criterion.id, command, stored.evidence[criterion.id] ?? [], configHash, sourceFingerprint))) {
-                    return gateResult("block", "FAIL", "COMPLETION_GATE_EVIDENCE_REQUIRED", "Run agent-ops verify and complete the task with current PASS evidence.");
-                }
-            }
+        const unfinished = findIncompleteSubtask(await this.#options.taskService.list(), stored.task.id);
+        if (unfinished !== undefined) {
+            return gateResult("block", "FAIL", "COMPLETION_GATE_SUBTASK_INCOMPLETE", `Complete subtask ${unfinished.task.id} before its parent.`);
         }
-        const attestation = await findReviewAttestation(this.#options.root, sourceFingerprint);
-        if (attestation === null || attestation.taskId !== stored.task.id) {
-            return gateResult("block", "FAIL", "COMPLETION_GATE_REVIEW_REQUIRED", "Run agent-ops review --yes for the attached task and current source.");
+        const problem = await checkTaskCompletionEvidence(stored, { ...this.#options, sourceFingerprint });
+        if (problem !== null) {
+            return gateResult("block", problem.status, `COMPLETION_GATE_${problem.code}`, problem.remedy);
         }
         return null;
     }
     async handle(event) {
+        if (this.#isPermitCommand(event)) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
+        }
         const sessionId = event.sessionId;
         if (sessionId === undefined) {
             return event.event === "stop"
-                ? gateResult("block", "UNKNOWN", "COMPLETION_GATE_SESSION_REQUIRED", "Agy did not provide conversationId; run doctor and use a one-time permit only after restoring hook input.")
+                ? gateResult("block", "UNKNOWN", "COMPLETION_GATE_SESSION_REQUIRED", "The host did not provide a session identifier; run doctor and use a one-time permit only after restoring hook input.")
                 : null;
         }
         if (event.event === "session-start") {
             return await this.initialize(sessionId);
         }
-        if (this.#isPermitCommand(event, sessionId)) {
-            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
-        }
         if (event.event !== "stop")
             return null;
+        if (event.terminationReason === undefined ||
+            (event.terminationReason === "model_stop" && event.fullyIdle === undefined)) {
+            return gateResult("block", "UNKNOWN", "COMPLETION_GATE_STOP_INPUT_INVALID", "Restore the Stop termination reason and fullyIdle metadata before stopping.");
+        }
         if (event.terminationReason !== "model_stop" || event.fullyIdle !== true) {
             return gateResult("continue", "PASS", "COMPLETION_GATE_NON_FINAL_STOP");
         }

package/dist/runtime/src/hooks/dispatch.js

@@ -1,3 +1,4 @@
+import { AgentOpsError } from "../fs/paths.js";
 import { evaluateGuardrail } from "../guardrails/evaluate.js";
 import { runStopVerification } from "./stop-verify.js";
 function continueWith(status, code) {
@@ -36,9 +37,16 @@ function evaluateCommands(commands, scope) {
 }
 export async function dispatchHookEvent(event, options) {
     if (options.completionGate !== undefined) {
-        const result = await options.completionGate.handle(event);
-        if (result !== null) {
-            return result;
+        try {
+            const result = await options.completionGate.handle(event);
+            if (result !== null)
+                return result;
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError && error.code === "CHANGE_SURFACE_TRACKED_RUNTIME") {
+                return { action: "block", status: "FAIL", code: "COMPLETION_GATE_TRACKED_RUNTIME", remedy: error.message };
+            }
+            throw error;
         }
     }
     if (event.event === "unsupported") {

package/dist/runtime/src/install/doctor.js

@@ -4,6 +4,7 @@ import { sha256 } from "../fs/hash.js";
 import { parseInstallManifest, PROJECT_MANIFEST_PATH } from "../fs/manifest.js";
 import { resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
+import { BIND_DEPENDENT_TARGETS, detectHostRestriction } from "../review/host-sandbox.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { harnessDescriptor, managedRules } from "./harness.js";
@@ -371,6 +372,49 @@ async function checkRegistrationDrift(root, manifest, config) {
         return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.", undefined, "No action needed; drift could not be computed.");
     }
 }
+/**
+ * Whether anything can ever be verified here. Completion requires current PASS
+ * evidence from a required verifier, so an empty list is not a light
+ * configuration — it is a loop that cannot close, and an installation reaches
+ * that state quietly whenever stack detection declines to guess.
+ */
+function checkVerificationCommands(config) {
+    if (config === undefined) {
+        return check("verification-commands", "UNKNOWN", "Configuration could not be read, so verifiers are unknown.");
+    }
+    if (config.verification.commands.length === 0) {
+        return check("verification-commands", "DEGRADED", "No verification command is configured, so no task can be completed.", 
+        // Codeless on purpose: the fix is an edit to the configuration file, not
+        // an agent-ops command, and a code here would force a non-zero exit on
+        // every installation whose stack detection declined to guess.
+        undefined, `Add verification.commands to ${CONFIG_PATH}, then run doctor again.`);
+    }
+    const required = config.verification.commands.filter(({ required: isRequired }) => isRequired);
+    if (required.length === 0) {
+        return check("verification-commands", "DEGRADED", "Every configured verification command is optional, so no criterion can " +
+            "be satisfied by one.", undefined, `Mark at least one command in ${CONFIG_PATH} as required.`);
+    }
+    return check("verification-commands", "PASS", `Required verifiers: ${required.map(({ id }) => id).join(", ")}.`);
+}
+/**
+ * What the surrounding host withholds from a reviewer. Reported separately
+ * from `review-targets` on purpose: a sandbox that blocks the network makes an
+ * authenticated CLI answer "not logged in", and reading that verdict as a
+ * credential problem is the misdiagnosis this check exists to prevent.
+ */
+async function checkHostSandbox(detect) {
+    const restriction = await (detect ?? detectHostRestriction)();
+    if (restriction === "network-blocked") {
+        return check("host-sandbox", "DEGRADED", "This process runs in a sandbox with no network access, so no review " +
+            "target can answer. Any authentication verdict below is unreliable.", undefined, "Run agent-ops outside the sandbox, or grant it escalated execution.");
+    }
+    if (restriction === "bind-blocked") {
+        return check("host-sandbox", "DEGRADED", `This process cannot open a loopback listener, so review targets that ` +
+            `need one (${BIND_DEPENDENT_TARGETS.join(", ")}) run last and may be ` +
+            "unable to answer.", undefined, "Run agent-ops outside the sandbox, or grant it escalated execution.");
+    }
+    return check("host-sandbox", "PASS", "No host sandbox restriction affects review targets.");
+}
 async function checkReviewTargets(config, probe, checkAuth) {
     const targets = config?.reviewRoles?.find((role) => role.role === "independent-review")?.targets ?? [];
     if (targets.length === 0) {
@@ -439,7 +483,9 @@ export async function doctorInstallation(options) {
             : []),
         await checkProbe("repository-trust", options.probes?.repositoryTrust),
         await checkProbe("smoke-availability", options.probes?.smokeAvailability),
-        await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true)
+        await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true),
+        await checkHostSandbox(options.probes?.hostRestriction),
+        checkVerificationCommands(config.config)
     ];
     return {
         checks,

package/dist/runtime/src/install/harness.js

@@ -308,7 +308,7 @@ export function managedRules(descriptor, context) {
         lines.push("Command policy guards high-confidence unsafe actions. Explicitly enabled", "Stop verification is report-only and never marks a task complete by itself.", "");
     }
     if (context.capabilities.includes("completion-gate")) {
-        lines.push("The agy completion gate applies only when this conversation creates a", "Git-visible net change after its first PreInvocation baseline. Read-only", "questions and analysis stop normally. A changed conversation must be", "attached to one task with two to five acceptance criteria; current PASS", "verification evidence, a PASS review attestation, and completed task state", "are all required before Stop. Error, max-step, and non-idle stops are not", "blocked. The gate inspects evidence but never runs tests or review itself.", "A user may approve `agent-ops allow-stop --session <conversationId>` for", "one Stop bound to the current source fingerprint; the PreToolUse hook must", "return `force_ask`, so the agent cannot self-authorize this escape hatch.", "For headless or CI enforcement, launch agy through", "`agent-ops agy-run -- <agy arguments>`.", "");
+        lines.push("The completion gate runs on agy and Claude Code. It applies only when", "this conversation creates a Git-visible net change after its first", "session baseline. Read-only", "questions and analysis stop normally. A changed conversation must be", "attached to one task with two to five acceptance criteria; current PASS", "verification evidence, a PASS review attestation, and completed task state", "are all required before Stop. Error, max-step, and non-idle stops are not", "blocked. The gate inspects evidence but never runs tests or review itself.", "A user may approve `agent-ops allow-stop --session <conversationId>` for", "one Stop bound to the current source fingerprint; the PreToolUse hook", "asks the user, so the agent cannot self-authorize this escape hatch.", "For headless or CI enforcement, launch agy through", "`agent-ops agy-run -- <agy arguments>`.", "");
     }
     lines.push(`This file is routed from the active ${descriptor.control.instructionFile}.`, "");
     return lines.join("\n");

package/dist/runtime/src/install/ownership.js

@@ -86,6 +86,13 @@ export function assertSupportedManifestOwnership(manifest, root) {
         pathKey(".agent-ops/config.json")
     ]);
     const optionalArtifactPaths = new Set();
+    // Optional for manifests installed before runtime output was ignored.
+    if (manifest.scope === "project") {
+        expectedArtifactPaths.set(".agent-ops/.gitignore", {
+            path: ".agent-ops/.gitignore", ids: new Set(["runtime-ignore"])
+        });
+        optionalArtifactPaths.add(".agent-ops/.gitignore");
+    }
     const expectedMarkers = new Map();
     const expectedMarkerPaths = new Set();
     const loopHarnesses = selectedLoopHarnesses(harnesses);

package/dist/runtime/src/install/plan.js

@@ -65,11 +65,18 @@ function verificationCommandFromProposal(proposal) {
 async function detectVerificationCommands(root) {
     const discovery = await discoverProject(root);
     if (discovery.kind !== "project") {
-        return [];
+        return { commands: [], blockers: [discovery.message] };
     }
-    return discovery.proposals
+    const commands = discovery.proposals
         .filter((proposal) => proposal.confidence === "high")
         .map(verificationCommandFromProposal);
+    // What detection could not settle on its own. Kept even when commands were
+    // found, because an installation that ends with no verifier has to be able
+    // to say why: silence there leaves a loop that can never complete a task.
+    return {
+        commands,
+        blockers: discovery.decisions.map((decision) => `${decision.adapter}: ${decision.message}`)
+    };
 }
 function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
     // Absent reviewRoles means external review is disabled; an empty selection
@@ -130,11 +137,11 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         }
         existingConfig = result.value;
     }
-    const detectedCommands = existingConfig === undefined ||
+    const detected = existingConfig === undefined ||
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
-        : [];
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detectedCommands, completionGateEnabled);
+        : { commands: [], blockers: [] };
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -150,7 +157,8 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
             owner: "agent-ops"
         },
         config,
-        detectedVerification: detectedCommands
+        detectedVerification: detected.commands,
+        verificationBlockers: detected.blockers
     };
 }
 function pathKey(path) {
@@ -381,11 +389,16 @@ export async function createInstallPlan(options) {
     assertLoopProfileSupport(options.scope, options.harness, resolved.capabilities);
     const completionGateEnabled = options.existingConfig?.value.features.completionGate.enabled ??
         options.completionGateEnabled === true;
+    // agy and Claude Code are the hosts whose Stop hook can refuse a stop.
+    // codex never fires Stop under `codex exec` and rejects
+    // `permissionDecision:ask`, so its permit could not be user-approved;
+    // opencode's plugin can only deny a tool call.
+    const gateHosts = ["agy", "claude"];
     if (completionGateEnabled &&
         (options.scope !== "project" ||
-            !options.harness.includes("agy") ||
+            !gateHosts.some((host) => options.harness.includes(host)) ||
             !resolved.capabilities.includes("project-loop"))) {
-        throw new AgentOpsError("COMPLETION_GATE_UNSUPPORTED", "The completion gate requires project scope with the agy harness and loop profile.");
+        throw new AgentOpsError("COMPLETION_GATE_UNSUPPORTED", "The completion gate requires project scope with the agy or claude harness and loop profile.");
     }
     if (completionGateEnabled &&
         !resolved.capabilities.includes("completion-gate")) {
@@ -435,6 +448,7 @@ export async function createInstallPlan(options) {
     });
     const contribution = {
         artifacts: [
+            ...(options.scope === "project" ? [{ id: "runtime-ignore", path: ".agent-ops/.gitignore", content: "/tasks/\n/reviews/\n" }] : []),
             ...baseContribution.artifacts,
             ...loopContribution.artifacts
         ],
@@ -588,6 +602,7 @@ export async function createInstallPlan(options) {
         config: config.config,
         manifest,
         operations,
-        detectedVerification: config.detectedVerification
+        detectedVerification: config.detectedVerification,
+        verificationBlockers: config.verificationBlockers
     };
 }

package/dist/runtime/src/install/probes.js

@@ -7,6 +7,23 @@ export function agyVersionSupported(versionOutput) {
     return version !== undefined && !version.some((part, index) => part < MINIMUM_AGY_VERSION[index] &&
         version.slice(0, index).every((prior, priorIndex) => prior === MINIMUM_AGY_VERSION[priorIndex]));
 }
+/**
+ * Whether a loaded hook command is the managed handler for this event. The
+ * event and the ownership marker are both required, but flags may sit between
+ * them: the Stop handler carries `--completion-gate` when the project loop is
+ * enabled, and matching the whole tail as one string reported every gated
+ * installation as unmanaged — a failure `agent-ops update` could never fix,
+ * because update installs exactly the command being rejected.
+ */
+function isManagedHookCommand(command, event) {
+    const marker = " --managed-by=agent-ops";
+    if (!command.endsWith(marker)) {
+        return false;
+    }
+    const flags = command.slice(0, -marker.length);
+    return flags.endsWith(` agy ${event}`) ||
+        flags.includes(` agy ${event} --`);
+}
 export function agyRuntimeStatus(versionOutput, hooksOutput, expectedEvents = []) {
     const match = /\b(\d+)\.(\d+)\.(\d+)\b/u.exec(versionOutput);
     if (!agyVersionSupported(versionOutput)) {
@@ -35,7 +52,7 @@ export function agyRuntimeStatus(versionOutput, hooksOutput, expectedEvents = []
                 return (typeof action === "object" && action !== null && !Array.isArray(action) &&
                     action.event === nativeEvent &&
                     typeof action.command === "string" &&
-                    action.command.endsWith(` agy ${expected} --managed-by=agent-ops`));
+                    isManagedHookCommand(action.command, expected));
             }));
         });
         if (!Array.isArray(hooks) || (expectedEvents.length > 0 && !loaded)) {

package/dist/runtime/src/install/uninstall.js

@@ -22,6 +22,8 @@ function selectedSet(harnesses) {
 function artifactOwners(manifest, artifact) {
     if (artifact.id === "config")
         return [];
+    if (artifact.id === "runtime-ignore")
+        return manifest.harness;
     if (artifact.id === "opencode-plugin")
         return ["opencode"];
     if (artifact.id === "claude-loop-launcher" ||

package/dist/runtime/src/review/attestation.js

@@ -57,9 +57,20 @@ export async function findReviewAttestation(root, sourceFingerprint) {
         return null;
     }
     try {
-        return parseAttestation(JSON.parse(source));
+        const attestation = parseAttestation(JSON.parse(source));
+        return attestation?.sourceFingerprint === sourceFingerprint ? attestation : null;
     }
     catch {
         return null;
     }
 }
+/** A new authorized attempt supersedes any earlier PASS for this source. */
+export async function invalidateReviewAttestation(root, sourceFingerprint) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
+        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+    }
+    const path = attestationPath(root, sourceFingerprint);
+    if (await readPrivateFile(path, root) !== null) {
+        await writePrivateFile(path, "null\n", root);
+    }
+}

package/dist/runtime/src/review/execute.js

@@ -1,4 +1,4 @@
-import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runVerificationCommand } from "../verify/spawn.js";
@@ -7,6 +7,7 @@ import { extractReviewObject } from "./extract.js";
 import { buildTargetInvocation } from "./invocation.js";
 import { reviewReportResults, reviewReportStatus, validateReviewReport } from "./report.js";
 import { detectHostTarget, orderChain } from "./roles.js";
+import { BIND_DEPENDENT_TARGETS, detectHostRestriction } from "./host-sandbox.js";
 import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
 /**
  * Full repository reviews need far more headroom than the lightweight auth
@@ -15,6 +16,15 @@ import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
  * review while looking like an unavailable target.
  */
 export const DEFAULT_REVIEW_TIMEOUT_MS = 900_000;
+/**
+ * How long a reviewer may produce nothing at all before it is treated as
+ * wedged rather than slow. A reviewer the host sandbox has blocked never
+ * writes another byte, and waiting out the full review timeout spends 15
+ * minutes per target — 45 for a three-target chain — to learn that. Progress
+ * output and a growing log file both count, so a reviewer that is merely
+ * thinking hard is never cut off.
+ */
+export const DEFAULT_STALL_IDLE_MS = 90_000;
 export class ReviewInterruptedError extends Error {
     signal;
     constructor(signal) {
@@ -121,6 +131,54 @@ function rejectedCallReason(output) {
     }
     return "capability-unavailable";
 }
+/**
+ * Watches one reviewer for silence. Two things count as a sign of life: a byte
+ * on either stream, reported through `beat`, and growth of the target's own log
+ * file, polled here because a target that buffers stdout until it answers has
+ * no other observable heartbeat.
+ */
+function watchForStall(logFile, parent, idleMs) {
+    const controller = new AbortController();
+    const pollMs = Math.max(20, Math.min(5_000, Math.floor(idleMs / 3)));
+    let lastBeat = Date.now();
+    let logSize = -1;
+    let stalled = false;
+    const beat = () => {
+        lastBeat = Date.now();
+    };
+    const check = async () => {
+        if (logFile !== undefined) {
+            try {
+                const info = await stat(logFile);
+                if (info.size > logSize) {
+                    logSize = info.size;
+                    beat();
+                }
+            }
+            catch {
+                // The target has not created its log yet, which is not a heartbeat.
+            }
+        }
+        if (!stalled && Date.now() - lastBeat >= idleMs) {
+            stalled = true;
+            controller.abort("stalled");
+        }
+    };
+    const timer = setInterval(() => {
+        void check();
+    }, pollMs);
+    timer.unref();
+    return {
+        signal: parent === undefined
+            ? controller.signal
+            : AbortSignal.any([parent, controller.signal]),
+        stalled: () => stalled,
+        beat,
+        stop: () => {
+            clearInterval(timer);
+        }
+    };
+}
 function throwIfInterrupted(target, options, failureClass) {
     if (failureClass !== "aborted" && options.signal?.aborted !== true) {
         return;
@@ -187,13 +245,14 @@ async function attemptTarget(request, options) {
     });
     const attemptDirectory = await mkdtemp(join(tmpdir(), "agent-ops-review-"));
     try {
+        const agyLog = target === "agy"
+            ? join(attemptDirectory, "agy.log")
+            : undefined;
         const invocationRequest = {
             target,
             prompt: request.prompt,
             repositoryRoot: request.repositoryRoot,
-            ...(target === "agy"
-                ? { logFile: join(attemptDirectory, "agy.log") }
-                : {}),
+            ...(agyLog === undefined ? {} : { logFile: agyLog }),
             ...(options.model === undefined ? {} : { model: options.model }),
             ...(options.effort === undefined ? {} : { effort: options.effort })
         };
@@ -237,6 +296,14 @@ async function attemptTarget(request, options) {
                     : firstComplaint(capability.stderr, capability.stdout) ??
                         `help probe failed (${capability.failureClass})`, "skipping");
         }
+        // agy takes its log file unconditionally; claude's equivalent is passed
+        // only when this install advertises it, so an older CLI keeps reviewing
+        // and merely loses the file heartbeat.
+        const heartbeatLog = target === "agy"
+            ? agyLog
+            : target === "claude" && help.includes("--debug-file")
+                ? join(attemptDirectory, "claude-debug.log")
+                : undefined;
         const snapshotRoot = join(attemptDirectory, "repository");
         const snapshotError = await snapshotRepository(request, snapshotRoot, options);
         if (snapshotError !== undefined) {
@@ -251,10 +318,20 @@ async function attemptTarget(request, options) {
                         "Run every repository-relative inspection in that directory.",
                         "For terminal commands, use only git status, git diff, git log, or git show; " +
                             "read specific files with file-reading tools instead of ls, find, cat, or rg.",
+                        // agy's only read-only mode is plan mode, and plan mode's default
+                        // job is to author an implementation plan and then ask the caller
+                        // whether to proceed. Under `--print` that question ends the one
+                        // turn it gets, so the review comes back empty after minutes of
+                        // work. Saying what the turn is for is what keeps it answering.
+                        "You are answering a review question, not planning work. Do not write " +
+                            "an implementation plan. Do not create or edit any file. Do not ask " +
+                            "the user anything. Reply with the JSON object the schema requires " +
+                            "and nothing else.",
                         request.prompt
                     ].join("\n")
                 }
                 : {}),
+            ...(heartbeatLog === undefined ? {} : { logFile: heartbeatLog }),
             repositoryRoot: snapshotRoot
         });
         executionDirectory = snapshotRoot;
@@ -263,25 +340,42 @@ async function attemptTarget(request, options) {
         }
         throwIfInterrupted(target, options);
         options.onProgress?.(`${target}: review started (timeout: ${Math.ceil((options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS) / 1_000)}s)`);
-        const spawned = await runVerificationCommand({
-            id: `review-${request.label}`,
-            command: invocation.command,
-            args: [...invocation.args],
-            cwd: executionDirectory,
-            required: true,
-            evidence: { kind: "exit-code" },
-            timeoutMs: options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS
-        }, {
-            cwd: executionDirectory,
-            ...(options.runner === undefined ? {} : { runner: options.runner }),
-            ...(options.outputLimitBytes === undefined
-                ? {}
-                : { outputLimitBytes: options.outputLimitBytes }),
-            stdin: invocation.stdin,
-            env: environment,
-            replaceEnv: true,
-            ...(options.signal === undefined ? {} : { signal: options.signal })
-        });
+        const stallIdleMs = options.stallIdleMs ?? DEFAULT_STALL_IDLE_MS;
+        const stallWatch = watchForStall(heartbeatLog, options.signal, stallIdleMs);
+        let spawned;
+        try {
+            spawned = await runVerificationCommand({
+                id: `review-${request.label}`,
+                command: invocation.command,
+                args: [...invocation.args],
+                cwd: executionDirectory,
+                required: true,
+                evidence: { kind: "exit-code" },
+                timeoutMs: options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS
+            }, {
+                cwd: executionDirectory,
+                ...(options.runner === undefined ? {} : { runner: options.runner }),
+                ...(options.outputLimitBytes === undefined
+                    ? {}
+                    : { outputLimitBytes: options.outputLimitBytes }),
+                stdin: invocation.stdin,
+                env: environment,
+                replaceEnv: true,
+                signal: stallWatch.signal,
+                onActivity: stallWatch.beat
+            });
+        }
+        finally {
+            stallWatch.stop();
+        }
+        // Ahead of `throwIfInterrupted`, which reads the same `aborted` failure
+        // class as a user interrupt. A stall is this executor's own abort, and
+        // ends one target rather than the whole review.
+        if (stallWatch.stalled() && options.signal?.aborted !== true) {
+            return skip("stalled", `no output for ${Math.max(1, Math.round(stallIdleMs / 1_000))}s; the reviewer is ` +
+                "probably blocked by the host sandbox, and retrying with more " +
+                "permission will not help");
+        }
         throwIfInterrupted(target, options, spawned.failureClass);
         if (spawned.failureClass === "timeout") {
             return skip("timeout", "the reviewer exceeded its timeout");
@@ -345,8 +439,38 @@ async function attemptTarget(request, options) {
 export function createReviewExecutor(options) {
     const report = options.onProgress ?? (() => { });
     const host = detectHostTarget(options.env ?? process.env);
-    const chain = orderChain(options.targets, host);
+    const ordered = orderChain(options.targets, host);
     return async (request) => {
+        // Asked before anything is spent. A reviewer inherits this process's
+        // sandbox, so a restriction found here is a restriction every target in
+        // the chain would hit — one at a time, minutes apart.
+        const restriction = await detectHostRestriction({
+            env: options.env ?? process.env,
+            ...(options.probeBind === undefined ? {} : { probeBind: options.probeBind })
+        });
+        if (restriction === "network-blocked") {
+            report("host: the sandbox around this process blocks network access, so no " +
+                "reviewer can answer → not running the chain");
+            return {
+                status: "NOT_RUN",
+                reason: "host-sandboxed",
+                ...(host === undefined ? {} : { harness: host }),
+                attempts: []
+            };
+        }
+        // Only agy needs a loopback listener, so a bind-blocked host is not a dead
+        // end — it is a reason to spend the other targets first rather than
+        // discovering the same failure at the head of the chain every time.
+        const chain = restriction === "bind-blocked"
+            ? [
+                ...ordered.filter((target) => !BIND_DEPENDENT_TARGETS.includes(target)),
+                ...ordered.filter((target) => BIND_DEPENDENT_TARGETS.includes(target))
+            ]
+            : ordered;
+        if (restriction === "bind-blocked" && chain.join() !== ordered.join()) {
+            report("host: this process cannot open a loopback listener, so targets that " +
+                `need one run last (chain: ${chain.join(" → ")})`);
+        }
         const expectedCriterionIds = request.invocation.packet.criteria.map((criterion) => criterion.id);
         const repositoryRoot = await realpath(options.cwd);
         const shared = {