@kylecheng3146/agent-ops 0.1.24 → 0.2.1

package/dist/packages/cli/src/args.js

@@ -284,8 +284,27 @@ export function parseArgs(argv) {
     if (helpSeen && versionSeen) {
         throw new CliArgumentError("CLI_CONFLICTING_ACTION", "--help and --version cannot be combined.");
     }
-    if ((helpSeen || versionSeen) && command !== undefined) {
-        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "Global help or version cannot be combined with a command.");
+    // `<command> --help` asks about that command, so it answers instead of
+    // failing: an agent that cannot read a command's own option shapes guesses
+    // at them one rejected call at a time. Other options are ignored rather than
+    // rejected, so `task create --criterion <wrong> --help` still explains the
+    // shape it got wrong.
+    if (helpSeen &&
+        command !== undefined &&
+        command !== "help" &&
+        command !== "version") {
+        return {
+            command: "help",
+            helpTopic: command,
+            ...(action === undefined ? {} : { helpAction: action }),
+            profiles: [],
+            dryRun: false,
+            json,
+            yes: false
+        };
+    }
+    if (versionSeen && command !== undefined) {
+        throw new CliArgumentError("CLI_CONFLICTING_ACTION", "Global version cannot be combined with a command.");
     }
     if (helpSeen || versionSeen) {
         if (scope !== undefined ||

package/dist/packages/cli/src/cli.js

@@ -27,7 +27,7 @@ Commands:
              Manage independent task acceptance state
   verify     Run configured verification
   review     Run an independent review
-  allow-stop Grant one fingerprint-bound agy Stop permit (requires --session)
+  allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
 
 Options:
@@ -37,7 +37,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>  Repeatable init option; external review
                                       targets in fallback-chain order
-  --completion-gate                  Init only: enable the agy project-loop gate
+  --completion-gate                  Init only: enable the project-loop completion gate
   --check-auth                        Doctor only: probe each review target's
                                       authentication with one real call
   --task <id>
@@ -55,6 +55,134 @@ Options:
   --help
   --version
 `;
+/**
+ * What `<command> --help` answers. Each entry states the option shapes that
+ * command actually accepts, because the global list cannot say which options
+ * belong to which command — and a caller that guesses learns only by being
+ * rejected.
+ */
+export const COMMAND_HELP_TEXT = {
+    init: `Usage: agent-ops init [options]
+
+Plan or install agent-ops into this repository.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --hook-target <harness=surface-id>   Repeatable
+  --profile <core|advisory|guardrails|loop>  Repeatable
+  --review-target <codex|agy|claude>   Repeatable, in fallback-chain order
+  --completion-gate                    Enable the project-loop completion gate
+  --dry-run                            Print the plan without writing
+  --json
+  --yes
+`,
+    config: `Usage: agent-ops config explain [options]
+
+Show where each effective configuration value came from.
+
+Options:
+  --scope <project|user>
+  --json
+`,
+    trust: `Usage: agent-ops trust <status|grant|revoke> [options]
+
+Manage the explicit trust record this repository's commands require.
+
+Options:
+  --scope <project|user>
+  --json
+  --yes
+`,
+    doctor: `Usage: agent-ops doctor [options]
+
+Diagnose the installation and report remediation for each failed check.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --check-auth   Probe each review target's authentication with one real call
+  --json
+`,
+    update: `Usage: agent-ops update [options]
+
+Update managed artifacts to this toolkit version.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --target-version <version>   Offline-capable update target
+  --dry-run
+  --json
+  --yes
+`,
+    uninstall: `Usage: agent-ops uninstall [options]
+
+Remove managed artifacts, leaving foreign handlers in place.
+
+Options:
+  --scope <project|user>
+  --harness <all|both|agy|claude|codex|opencode|comma-separated>
+  --dry-run
+  --json
+  --yes
+`,
+    task: `Usage: agent-ops task <create|status|attach|complete|archive|export> [options]
+
+Manage independent task acceptance state. Task commands accept none of
+--harness, --profile, --dry-run or --yes.
+
+Options:
+  --title <text>                        create
+  --criterion <json>                    create, repeatable, two to five total
+  --parent <task-id>                    create: record a subtask; status: list subtasks
+  --task <id>                           status, attach, complete, archive, export
+  --session <id>                        attach, status
+  --evidence <criterion-id=reference>   complete, repeatable
+  --base <git-ref>                      complete: a clean committed range
+  --json
+
+Each --criterion is one JSON object with exactly these keys:
+
+  {"id":"kebab-id","description":"what must hold","verifierIds":["node-test"]}
+
+Every criterion needs at least one verifierIds entry naming a verification
+command id configured in .agent-ops/config.json. No other key is accepted.
+`,
+    verify: `Usage: agent-ops verify [options]
+
+Run the configured verification commands and record their evidence.
+
+Options:
+  --task <id>
+  --session <id>
+  --base <git-ref>   Verify a clean committed range
+  --json
+`,
+    review: `Usage: agent-ops review [options]
+
+Run one independent read-only review against the configured target chain.
+
+Options:
+  --task <id>
+  --session <id>
+  --criterion <id>     Repeatable: review only these task criteria
+  --harness <target>   One configured review target
+  --base <git-ref>
+  --json
+  --yes                Authorize the review call
+`,
+    "allow-stop": `Usage: agent-ops allow-stop --session <id> [options]
+
+Grant one fingerprint-bound Stop permit for the completion gate, on agy or
+Claude Code. Requires user approval: the PreToolUse hook asks the user, so an
+agent cannot self-authorize it.
+
+Options:
+  --session <id>   Required
+  --json
+`
+};
 function wantsJson(argv) {
     return argv.includes("--json");
 }
@@ -80,7 +208,11 @@ export async function runCli(argv, io, services) {
         return writeAndReturn(io, errorEnvelope("CLI_INTERNAL_ERROR", "Unable to parse command arguments."), json, 1);
     }
     if (args.command === "help") {
-        return writeAndReturn(io, okEnvelope("CLI_HELP", { text: HELP_TEXT }), args.json, 0);
+        const topic = args.helpTopic;
+        return writeAndReturn(io, okEnvelope("CLI_HELP", {
+            text: topic === undefined ? HELP_TEXT : COMMAND_HELP_TEXT[topic],
+            ...(topic === undefined ? {} : { topic })
+        }), args.json, 0);
     }
     if (args.command === "version") {
         return writeAndReturn(io, okEnvelope("CLI_VERSION", { version: services.version }), args.json, 0);

package/dist/packages/cli/src/commands/hook.js

@@ -52,8 +52,12 @@ export async function runHookCommand(options) {
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {
-        if (options.harness === "agy" && options.event === "Stop" && options.completionGate !== undefined) {
-            return harnessDescriptor("agy").runtime.formatOutput(options.event, {
+        // Fail closed on every host that enforces the gate: an exception here is
+        // exactly the case where a silent empty output would wave the stop through.
+        if ((options.harness === "agy" || options.harness === "claude") &&
+            options.event === "Stop" &&
+            options.completionGate !== undefined) {
+            return harnessDescriptor(options.harness).runtime.formatOutput(options.event, {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_UNAVAILABLE",

package/dist/packages/cli/src/commands/init.js

@@ -108,17 +108,30 @@ export async function runInitCommand(options) {
             : { completionGateEnabled: args.completionGate })
     });
     const trust = await trustChange(options, plan);
-    const warnings = plan.harness.includes("agy") && options.agyWarning !== undefined
-        ? (() => {
-            try {
-                const warning = options.agyWarning();
-                return warning === undefined ? [] : [warning];
-            }
-            catch {
-                return ["agy could not be probed; run `agent-ops doctor` to verify it."];
-            }
-        })()
+    // An installation with no verifier looks finished and is not: every task
+    // completion needs current PASS evidence from a required verifier, so the
+    // loop can never close. Detection stays conservative on purpose — it will
+    // not guess a test command — which makes saying so out loud the whole fix.
+    const verificationWarnings = plan.config.verification.commands.length === 0
+        ? [
+            "No verification command is configured, so no task can be completed. " +
+                "Add verification.commands to .agent-ops/config.json." +
+                (plan.verificationBlockers.length === 0
+                    ? ""
+                    : ` Detection stopped because — ${plan.verificationBlockers.join("; ")}`)
+        ]
         : [];
+    const warnings = [...verificationWarnings, ...(plan.harness.includes("agy") && options.agyWarning !== undefined
+            ? (() => {
+                try {
+                    const warning = options.agyWarning();
+                    return warning === undefined ? [] : [warning];
+                }
+                catch {
+                    return ["agy could not be probed; run `agent-ops doctor` to verify it."];
+                }
+            })()
+            : [])];
     if (args.dryRun) {
         return okEnvelope("INIT_PLAN_READY", {
             applied: false,

package/dist/packages/cli/src/commands/review.js

@@ -124,11 +124,16 @@ async function currentEvidence(options, context, criterionId, commandId, configH
     return { current, hasReference, unreadable, stale };
 }
 async function preflightReview(options, context, sourceFingerprint) {
+    // A recorded failure is not stale evidence, and saying so sends the caller
+    // to re-run the verifier that just failed. The tests failed; that is the
+    // report.
+    if (context.failureFingerprint !== null) {
+        return { ok: false, reason: "verification-not-passed" };
+    }
     if (options.config === undefined ||
         options.evidenceStore === undefined ||
         options.root === undefined ||
-        options.gitRunner === undefined ||
-        context.failureFingerprint !== null) {
+        options.gitRunner === undefined) {
         return { ok: false, reason: "stale-verification" };
     }
     const configHash = calculateConfigHash(options.config);
@@ -313,6 +318,7 @@ export async function runReviewCommand(options) {
                 return notRunEnvelope({
                     ...resultBase,
                     status: "NOT_RUN", reason: preflight.reason,
+                    taskId: context.taskId,
                     scope
                 });
             }

package/dist/packages/cli/src/hook-process.js

@@ -214,7 +214,11 @@ function shouldBuildStopVerification(harness, event, config, rawInput) {
  */
 export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     const [harness, event] = argv;
-    const completionGateInstalled = harness === "agy" &&
+    // Both hosts whose Stop hook can actually refuse a stop. codex never fires
+    // Stop under `codex exec` and rejects `permissionDecision:ask`, so its
+    // escape hatch could not be user-approved; opencode can only deny a tool
+    // call, never a stop.
+    const completionGateInstalled = (harness === "agy" || harness === "claude") &&
         event === "Stop" &&
         argv.includes("--completion-gate");
     if (harness === undefined ||
@@ -225,12 +229,12 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         return 0;
     }
     try {
-        const root = dependencies.root ?? process.cwd();
+        let root = dependencies.root ?? process.cwd();
         const harnessId = harness;
         const hookEvent = event;
         if (process.env.AGENT_OPS_DISABLE === "1") {
             if (completionGateInstalled) {
-                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                     action: "block",
                     status: "UNKNOWN",
                     code: "COMPLETION_GATE_DISABLE_REJECTED",
@@ -243,10 +247,25 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         }
         const rawInput = await readStdin(io.stdin);
         const parsedInput = withInjectedSession(harnessId, parseInput(rawInput));
+        if (dependencies.root === undefined) {
+            const inputRoot = typeof parsedInput === "object" &&
+                parsedInput !== null &&
+                Array.isArray(parsedInput.workspacePaths) &&
+                typeof parsedInput.workspacePaths[0] === "string"
+                ? parsedInput.workspacePaths[0]
+                : typeof parsedInput === "object" &&
+                    parsedInput !== null &&
+                    typeof parsedInput.projectRoot === "string"
+                    ? parsedInput.projectRoot
+                    : undefined;
+            if (inputRoot !== undefined) {
+                root = inputRoot;
+            }
+        }
         const configOutcome = await hookConfigOutcome(root, dependencies.loadConfig);
         if (configOutcome.kind === "invalid") {
             if (completionGateInstalled) {
-                writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+                writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                     action: "block",
                     status: "UNKNOWN",
                     code: "COMPLETION_GATE_CONFIG_INVALID",
@@ -268,7 +287,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
         }
         const config = configOutcome.config;
         if (completionGateInstalled && !config.features.completionGate.enabled) {
-            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+            writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_CONFIG_DISABLED",
@@ -293,7 +312,12 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                 processRunner
             })
             : undefined;
-        const completionGate = harnessId === "agy" && config.features.completionGate.enabled
+        // Not `completionGateInstalled`: that is the Stop handler's own marker,
+        // and the gate also answers PreToolUse — where it turns a self-issued
+        // `allow-stop` into a question for the user. Narrowing this to Stop takes
+        // the escape hatch's approval step away.
+        const completionGate = (harnessId === "agy" || harnessId === "claude") &&
+            config.features.completionGate.enabled
             ? dependencies.completionGate ?? {
                 handle: async (normalized) => await new CompletionGateService({
                     root,
@@ -320,7 +344,7 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
     }
     catch {
         if (completionGateInstalled) {
-            writeHookOutput(io, harnessDescriptor("agy").runtime.formatOutput("Stop", {
+            writeHookOutput(io, harnessDescriptor(harness).runtime.formatOutput("Stop", {
                 action: "block",
                 status: "UNKNOWN",
                 code: "COMPLETION_GATE_UNAVAILABLE",

package/dist/runtime/src/adapters/claude/config.js

@@ -24,7 +24,13 @@ export function claudeSettingsTarget(scope) {
             requiresWorkspaceTrust: false
         };
 }
-function commandHook(event, runtimePath) {
+/**
+ * The gate flag trails the ownership marker rather than preceding it, unlike
+ * agy's flat command string. The marker's position is what identifies a
+ * managed handler here, and moving it would make every existing installation
+ * read as foreign.
+ */
+function commandHook(event, runtimePath, completionGate = false) {
     return {
         type: "command",
         command: "node",
@@ -32,15 +38,16 @@ function commandHook(event, runtimePath) {
             runtimePath,
             "claude",
             event,
-            CLAUDE_HOOK_MARKER
+            CLAUDE_HOOK_MARKER,
+            ...(completionGate ? ["--completion-gate"] : [])
         ],
         timeout: 30
     };
 }
-function matcherGroup(event, runtimePath) {
+function matcherGroup(event, runtimePath, completionGate = false) {
     return {
         ...(event === "PreToolUse" ? { matcher: "Bash" } : {}),
-        hooks: [commandHook(event, runtimePath)]
+        hooks: [commandHook(event, runtimePath, completionGate)]
     };
 }
 function powershellLoopCommand(event) {
@@ -82,6 +89,21 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
         for (const event of CLAUDE_LOOP_EVENTS) {
             hooks[event] = [loopMatcherGroup(event, platform)];
         }
+        // The loop launcher runs a different process, and the completion gate does
+        // not live there. Its PreToolUse role is narrow but load-bearing: it is
+        // what turns a self-issued `allow-stop` into a question for the user, so
+        // the gate needs a handler of its own beside the loop's.
+        if (capabilities.includes("completion-gate")) {
+            // SessionStart for the same reason: the gate records its per-session
+            // baseline there, and a gate that never sees a session start refuses
+            // every stop as uninitialized.
+            for (const event of ["SessionStart", "PreToolUse"]) {
+                hooks[event] = [
+                    ...(hooks[event] ?? []),
+                    matcherGroup(event, runtimePath)
+                ];
+            }
+        }
     }
     else {
         if (capabilities.includes("lifecycle-summary")) {
@@ -91,7 +113,12 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
             hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
-    if (capabilities.includes("optional-stop-verify")) {
+    // The gate supersedes report-only Stop verification: one managed Stop
+    // handler, and the gated one already reports everything the other would.
+    if (capabilities.includes("completion-gate")) {
+        hooks.Stop = [matcherGroup("Stop", runtimePath, true)];
+    }
+    else if (capabilities.includes("optional-stop-verify")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
     return { hooks };
@@ -99,6 +126,28 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * The argument vector `commandHook` produces, and nothing else. The ownership
+ * marker alone is not proof: it is a plain string anyone may write, and a
+ * handler mistaken for ours is a handler `update` rewrites and `uninstall`
+ * deletes.
+ */
+function isManagedNodeArgs(args) {
+    if (!Array.isArray(args) || args.length < 4 || args.length > 5) {
+        return false;
+    }
+    const [runtimePath, harness, event, marker, gate] = args;
+    // The event is checked for shape, not membership: a handler an older
+    // agent-ops wrote for an event this version no longer knows is still ours to
+    // remove, and rejecting it would orphan it in the user's settings forever.
+    return (typeof runtimePath === "string" &&
+        runtimePath.length > 0 &&
+        harness === "claude" &&
+        typeof event === "string" &&
+        event.length > 0 &&
+        marker === CLAUDE_HOOK_MARKER &&
+        (gate === undefined || gate === "--completion-gate"));
+}
 /**
  * Matches only the two command shapes agent-ops actually generates. This is
  * reused by installation inspection so a foreign hook cannot masquerade as
@@ -109,11 +158,12 @@ export function isClaudeManagedHandler(handler) {
         return false;
     }
     return ((handler.command === "node" &&
-        Array.isArray(handler.args) &&
-        handler.args[3] === CLAUDE_HOOK_MARKER) ||
+        isManagedNodeArgs(handler.args)) ||
         (handler.command === "bash" &&
             Array.isArray(handler.args) &&
+            handler.args.length === 3 &&
             handler.args[0] === CLAUDE_LOOP_LAUNCHER &&
+            CLAUDE_LOOP_EVENTS.includes(handler.args[1]) &&
             handler.args[2] === CLAUDE_HOOK_MARKER) ||
         (handler.shell === "powershell" &&
             handler.args === undefined &&

package/dist/runtime/src/adapters/claude/events.js

@@ -37,5 +37,13 @@ export const CLAUDE_CAPABILITY_REGISTRATIONS = [
         surfaceId: "claude-settings",
         support: "supported",
         runtimeFailure: "fail-open"
+    },
+    {
+        capability: "completion-gate",
+        normalizedEvent: "stop",
+        nativeEvent: "Stop",
+        surfaceId: "claude-settings",
+        support: "supported",
+        runtimeFailure: "fail-closed"
     }
 ];

package/dist/runtime/src/adapters/claude/input.js

@@ -13,17 +13,31 @@ export function normalizeClaudeHookInput(input) {
         return normalizeHookEvent(input);
     }
     const projectRoot = input.cwd;
+    // The completion gate keys its per-session baseline on this. Without it every
+    // Stop is refused for the wrong reason and no SessionStart ever records a
+    // baseline to refuse against.
+    const sessionId = typeof input.session_id === "string"
+        ? input.session_id
+        : undefined;
     if (input.hook_event_name === "SessionStart") {
-        return normalizeHookEvent({
-            event: "session-start",
-            projectRoot
-        });
+        return {
+            ...normalizeHookEvent({ event: "session-start", projectRoot }),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
     }
     if (input.hook_event_name === "Stop") {
-        return normalizeHookEvent({
+        // Claude publishes no termination reason: its Stop hook fires when the
+        // assistant has finished, which is agy's `model_stop`. The one distinction
+        // it does publish is recursion — a Stop the hook itself caused — and that
+        // is exactly the not-yet-idle case the gate lets through.
+        const stop = normalizeHookEvent({ event: "stop", projectRoot });
+        return {
             event: "stop",
-            projectRoot
-        });
+            projectRoot: stop.projectRoot,
+            ...(sessionId === undefined ? {} : { sessionId }),
+            terminationReason: "model_stop",
+            fullyIdle: input.stop_hook_active !== true
+        };
     }
     if (input.hook_event_name === "PreToolUse" &&
         input.tool_name === "Bash" &&

package/dist/runtime/src/adapters/claude/output.js

@@ -7,6 +7,30 @@ function json(value) {
 }
 export function claudeHookOutput(event, result) {
     const denialReason = result.remedy === undefined ? result.code : `${result.code}: ${result.remedy}`;
+    // The completion gate carries no verification evidence of its own — it reads
+    // evidence rather than producing it — so it never reaches the branch below
+    // and needs its own refusal.
+    if (event === "Stop" &&
+        result.action === "block" &&
+        result.code.startsWith("COMPLETION_GATE_")) {
+        return json({
+            decision: "block",
+            reason: `agent-ops: ${denialReason}`
+        });
+    }
+    if (event === "PreToolUse" &&
+        result.code === "COMPLETION_GATE_PERMIT_CONFIRMATION") {
+        // Asked, never allowed: a one-time Stop permit is the user's to grant, and
+        // an agent that could answer this for itself would hold the key to its own
+        // gate.
+        return json({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "ask",
+                permissionDecisionReason: denialReason
+            }
+        });
+    }
     if (event === "Stop" && result.evidence !== undefined) {
         if (result.status === "FAIL") {
             const failed = result.evidence.commandResults

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

@@ -133,7 +133,7 @@ export class CompletionGateService {
         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") {

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,