@kylecheng3146/agent-ops 0.1.9 → 0.1.10

package/README.md

@@ -165,9 +165,21 @@ directory. `update` also requires that the project already has a valid managed
 `.agent-ops/manifest.json` created by `init`.
 
 The commands after `init --yes` are post-apply operations. `doctor` reports
-`UNKNOWN` for a probe that has nothing to verify yet: `repository-trust` until
-`trust grant` runs, and `smoke-availability` until the configuration declares a
-verification command.
+`UNKNOWN` for a probe that has nothing to verify yet: `repository-trust`
+until `trust grant` runs (only actionable once `verification.commands` is
+configured — a project that never runs verification has nothing for trust
+to unlock), and `smoke-availability` until the configuration declares a
+verification command. Every non-`PASS` check carries a `remediation` string
+explaining what, if anything, to do about it; text output prints it as an
+indented `  → ` line, and `--json` exposes it as a field. `doctor` never
+writes: it only reports what `agent-ops update` or `agent-ops trust grant`
+would fix.
+
+`doctor` exits non-zero only when a check `FAIL`s or names a specific
+agent-ops command to run. `UNKNOWN`, `UNSUPPORTED`, and a `DEGRADED` check
+with no such command (for example, a harness that only partially supports a
+capability by design, such as opencode's `lifecycle-summary`) are permanent,
+benign findings and exit 0 — there is nothing to fix.
 
 `artifact-staleness` reports `DEGRADED` with `UPDATE_REQUIRED` when a toolkit
 upgrade or effective profile or capability change makes intact managed rules

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { commonHarnessAdapters, harnessHookPath, HARNESS_IDS } from "../../../runtime/src/install/harness.js";
-import { hookRegistrationSatisfied, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
+import { hookRegistrationDrift, repositoryTrustStatus, smokeAvailabilityStatus } from "../../../runtime/src/install/probes.js";
 import { parseInstallManifest } from "../../../runtime/src/fs/manifest.js";
 import { NpmRegistryClient } from "../../../runtime/src/registry/npm.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
@@ -159,13 +159,61 @@ else {
                         root,
                         toolkitVersion: CLI_VERSION,
                         probes: {
-                            hookRegistration: async () => hookRegistrationSatisfied({
-                                harness: await installedHarness(root),
-                                config,
-                                sources: await hookSources(root, args.scope === "user" ? "user" : "project")
-                            }),
-                            repositoryTrust: async () => repositoryTrustStatus(await repositoryTrust(root, config, CLI_VERSION)),
-                            smokeAvailability: () => smokeAvailabilityStatus(config),
+                            hookRegistration: async () => {
+                                const drifted = hookRegistrationDrift({
+                                    harness: await installedHarness(root),
+                                    config,
+                                    sources: await hookSources(root, args.scope === "user" ? "user" : "project")
+                                });
+                                return drifted.length === 0
+                                    ? { status: "PASS" }
+                                    : {
+                                        status: "FAIL",
+                                        message: `Hook registration is missing for ${drifted.join(", ")}.`,
+                                        code: "UPDATE_REQUIRED",
+                                        remediation: "Run `agent-ops update`."
+                                    };
+                            },
+                            repositoryTrust: async () => {
+                                const trust = await repositoryTrust(root, config, CLI_VERSION);
+                                const status = repositoryTrustStatus(trust);
+                                if (trust === "STALE") {
+                                    return {
+                                        status,
+                                        message: "Repository trust binding is stale.",
+                                        code: "TRUST_REQUIRED",
+                                        remediation: "Run `agent-ops trust grant`."
+                                    };
+                                }
+                                if (trust === "UNTRUSTED") {
+                                    const verificationConfigured = config.verification.commands.length > 0;
+                                    return {
+                                        status,
+                                        message: verificationConfigured
+                                            ? "Repository is not trusted; Stop verification will not run."
+                                            : "Repository is not trusted.",
+                                        ...(verificationConfigured
+                                            ? {
+                                                code: "TRUST_REQUIRED",
+                                                remediation: "Run `agent-ops trust grant`."
+                                            }
+                                            : {
+                                                remediation: "No action needed; trust is only required once verification.commands is set."
+                                            })
+                                    };
+                                }
+                                return { status };
+                            },
+                            smokeAvailability: () => {
+                                const status = smokeAvailabilityStatus(config);
+                                return status === "UNKNOWN"
+                                    ? {
+                                        status,
+                                        message: "verification.commands is empty.",
+                                        remediation: "No action needed; add verification.commands to .agent-ops/config.json to enable smoke checks."
+                                    }
+                                    : { status };
+                            },
                             reviewTarget: async (target, deep) => await probeReviewTarget(target, { cwd: root, deep })
                         },
                         ...(args.checkAuth === true

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

@@ -3,13 +3,17 @@ function formatDoctorReport(report) {
     const surfaces = report.surfaces ?? [];
     return `${[
         "Installation doctor",
-        ...report.checks.map(({ id, status, message, code }) => `- ${status} ${id}${code === undefined ? "" : ` [${code}]`}: ${message}`),
+        ...report.checks.flatMap(({ id, status, message, code, remediation }) => [
+            `- ${status} ${id}${code === undefined ? "" : ` [${code}]`}: ${message}`,
+            ...(remediation === undefined ? [] : [`  → ${remediation}`])
+        ]),
         ...(surfaces.length === 0
             ? []
             : [
                 "Surfaces:",
-                ...surfaces.map(({ harness, surfaceId, path, status, managedHandlerCount, foreignHandlerCount }) => `- ${status} ${harness}/${surfaceId}: ${path} ` +
-                    `(managed ${managedHandlerCount}, foreign ${foreignHandlerCount})`)
+                ...surfaces.map(({ harness, surfaceId, path, status, managedHandlerCount, foreignHandlerCount, reason }) => `- ${status} ${harness}/${surfaceId}: ${path} ` +
+                    `(managed ${managedHandlerCount}, foreign ${foreignHandlerCount})` +
+                    (reason === undefined ? "" : ` (${reason})`))
             ])
     ].join("\n")}\n`;
 }
@@ -37,18 +41,19 @@ export async function runDoctorCommand(options) {
                 : hasDegraded
                     ? "Installation diagnostics found degraded checks."
                     : "Installation diagnostics passed.";
+    // Exit non-zero only when there is something to do: a hard failure, or a
+    // check that names an agent-ops command via `code`. UNKNOWN, UNSUPPORTED,
+    // and codeless DEGRADED (e.g. a harness-declared permanent degradation)
+    // are benign findings and must not force a non-zero exit.
+    const isActionable = report.checks.some(({ status, code: checkCode }) => status === "FAIL" || checkCode !== undefined);
     return {
         code,
-        status: hasFailure || hasUnsupported || hasUnknown || hasDegraded
-            ? "error"
-            : "ok",
+        status: isActionable ? "error" : "ok",
         data: {
             report,
             message,
             text: formatDoctorReport(report)
         },
-        errors: hasFailure || hasUnsupported || hasUnknown || hasDegraded
-            ? [{ code, message }]
-            : []
+        errors: isActionable ? [{ code, message }] : []
     };
 }

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

@@ -12,10 +12,14 @@ import { inspectHarnessSurfaces, inspectHarnessRegistrations } from "./surface-i
 const CONFIG_PATH = ".agent-ops/config.json";
 const MINIMUM_NODE_VERSION = [22, 14, 0];
 const MAX_DOCTOR_FILE_BYTES = 1024 * 1024;
-function check(id, status, message, code) {
-    return code === undefined
-        ? { id, status, message }
-        : { id, status, message, code };
+function check(id, status, message, code, remediation) {
+    return {
+        id,
+        status,
+        message,
+        ...(code === undefined ? {} : { code }),
+        ...(remediation === undefined ? {} : { remediation })
+    };
 }
 function parseNodeVersion(version) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
@@ -38,7 +42,7 @@ function meetsMinimumNodeVersion(version) {
 function checkNodeVersion(version) {
     const parsed = parseNodeVersion(version);
     if (parsed === null || !meetsMinimumNodeVersion(parsed)) {
-        return check("node-version", "FAIL", `Node ${version} does not meet the minimum version 22.14.0.`);
+        return check("node-version", "FAIL", `Node ${version} does not meet the minimum version 22.14.0.`, undefined, "Install Node 22.14.0 or newer.");
     }
     return check("node-version", "PASS", `Node ${version} meets the minimum version 22.14.0.`);
 }
@@ -94,7 +98,7 @@ async function checkManifest(root) {
     }
     catch {
         return {
-            check: check("manifest", "FAIL", "Installation manifest is missing, unsafe, or invalid.")
+            check: check("manifest", "FAIL", "Installation manifest is missing, unsafe, or invalid.", undefined, "Run `agent-ops init` to create a managed installation.")
         };
     }
 }
@@ -105,7 +109,7 @@ async function checkConfig(root) {
     }
     catch {
         return {
-            check: check("config", "FAIL", "Configuration is missing, unsafe, or invalid JSON.")
+            check: check("config", "FAIL", "Configuration is missing, unsafe, or invalid JSON.", undefined, `Fix ${CONFIG_PATH}. Do not run \`agent-ops init\` — it would discard configuration.`)
         };
     }
     const result = validateConfig(parsed);
@@ -114,7 +118,9 @@ async function checkConfig(root) {
         return {
             check: check("config", "FAIL", error === undefined
                 ? "Configuration failed validation."
-                : `Configuration failed validation: ${error.code} at ${error.path}.`)
+                : `Configuration failed validation: ${error.code} at ${error.path}.`, undefined, error === undefined
+                ? `Fix ${CONFIG_PATH}. Do not run \`agent-ops init\` — it would discard configuration.`
+                : `Fix ${error.path} in ${CONFIG_PATH}. Do not run \`agent-ops init\` — it would discard configuration.`)
         };
     }
     return {
@@ -125,7 +131,7 @@ async function checkConfig(root) {
 async function checkArtifacts(root, manifest) {
     if (manifest === undefined) {
         return {
-            check: check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest."),
+            check: check("artifacts", "FAIL", "Artifacts cannot be verified without a valid manifest.", undefined, "Run `agent-ops init` to create a managed installation."),
             hashesByPath: new Map()
         };
     }
@@ -151,19 +157,20 @@ async function checkArtifacts(root, manifest) {
     return {
         check: failures.length === 0
             ? check("artifacts", "PASS", "All managed artifacts match their hashes.")
-            : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`),
+            : check("artifacts", "FAIL", `Managed artifacts failed verification: ${failures.join(", ")}.`, "UPDATE_REQUIRED", `Run \`agent-ops update\` to restore managed artifacts. This overwrites ` +
+                `${failures.join(", ")}; any local edits to those files will be lost.`),
         hashesByPath
     };
 }
 function checkArtifactStaleness(manifest, config, artifacts, toolkitVersion) {
     if (manifest === undefined || config === undefined) {
-        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without a valid manifest and configuration.");
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without a valid manifest and configuration.", undefined, "No action needed; fix the manifest or config check above first.");
     }
     if (artifacts.check.status !== "PASS") {
-        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed until artifact integrity passes.");
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed until artifact integrity passes.", undefined, "No action needed; fix the artifacts check above first.");
     }
     if (toolkitVersion === undefined) {
-        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without the running toolkit version.");
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness cannot be assessed without the running toolkit version.", undefined, "No action needed; the CLI did not report its own version.");
     }
     const expectedHashesByPath = new Map();
     try {
@@ -184,13 +191,13 @@ function checkArtifactStaleness(manifest, config, artifacts, toolkitVersion) {
         }
     }
     catch {
-        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+        return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.", undefined, "No action needed; staleness could not be computed.");
     }
     const stalePaths = [];
     for (const [path, expectedHash] of expectedHashesByPath) {
         const actualHash = artifacts.hashesByPath.get(path);
         if (actualHash === undefined) {
-            return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.");
+            return check("artifact-staleness", "UNKNOWN", "Managed artifact staleness could not be assessed safely.", undefined, "No action needed; staleness could not be computed.");
         }
         if (actualHash !== expectedHash) {
             stalePaths.push(path);
@@ -198,11 +205,11 @@ function checkArtifactStaleness(manifest, config, artifacts, toolkitVersion) {
     }
     return stalePaths.length === 0
         ? check("artifact-staleness", "PASS", "Managed artifacts match the current toolkit and configuration.")
-        : check("artifact-staleness", "DEGRADED", `Managed artifacts need update: ${stalePaths.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
+        : check("artifact-staleness", "DEGRADED", `Managed artifacts need update: ${stalePaths.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
 }
 async function checkMarkers(root, manifest) {
     if (manifest === undefined) {
-        return check("markers", "FAIL", "Managed blocks cannot be verified without a valid manifest.");
+        return check("markers", "FAIL", "Managed blocks cannot be verified without a valid manifest.", undefined, "Run `agent-ops init` to create a managed installation.");
     }
     const failures = [];
     const legacyPaths = [];
@@ -225,25 +232,39 @@ async function checkMarkers(root, manifest) {
         }
     }
     if (failures.length > 0) {
-        return check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`);
+        return check("markers", "FAIL", `Managed block markers failed verification: ${failures.join(", ")}.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
     }
     if (legacyPaths.length > 0) {
-        return check("markers", "DEGRADED", `Legacy managed routing blocks need migration: ${legacyPaths.join(", ")}.`);
+        return check("markers", "DEGRADED", `Legacy managed routing blocks need migration: ${legacyPaths.join(", ")}.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
     }
     return check("markers", "PASS", "All managed block markers are intact.");
 }
+function defaultProbeRemediation(status) {
+    return status === "PASS" || status === "FAIL"
+        ? undefined
+        : "No action needed; nothing to verify yet.";
+}
 async function checkProbe(id, probe) {
     if (probe === undefined) {
-        return check(id, "UNKNOWN", "No probe was provided.");
+        return check(id, "UNKNOWN", "No probe was provided.", undefined, "No action needed; this check requires wiring from the CLI.");
     }
     try {
         const result = await probe();
+        if (typeof result === "object") {
+            const status = result.status;
+            return check(id, status, result.message ??
+                (status === "PASS"
+                    ? "Probe passed."
+                    : status === "FAIL"
+                        ? "Probe failed."
+                        : "Probe has nothing to verify yet."), result.code, result.remediation ?? defaultProbeRemediation(status));
+        }
         const status = typeof result === "boolean" ? (result ? "PASS" : "FAIL") : result;
         return check(id, status, status === "PASS"
             ? "Probe passed."
             : status === "FAIL"
                 ? "Probe failed."
-                : "Probe has nothing to verify yet.");
+                : "Probe has nothing to verify yet.", undefined, defaultProbeRemediation(status));
     }
     catch {
         return check(id, "FAIL", "Probe failed.");
@@ -251,7 +272,7 @@ async function checkProbe(id, probe) {
 }
 function checkLifecycleSummary(manifest, config) {
     if (manifest === undefined || config === undefined) {
-        return check("lifecycle-summary", "UNKNOWN", "Lifecycle summary cannot be assessed without a valid manifest and configuration.");
+        return check("lifecycle-summary", "UNKNOWN", "Lifecycle summary cannot be assessed without a valid manifest and configuration.", undefined, "No action needed; fix the manifest or config check above first.");
     }
     const hasLifecycleSummary = config.profiles.length > 0 &&
         resolveProfiles(config.profiles).capabilities.includes("lifecycle-summary");
@@ -266,32 +287,32 @@ function checkLifecycleSummary(manifest, config) {
         .filter(({ registration }) => registration === undefined)
         .map(({ id }) => id);
     if (missing.length > 0) {
-        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary registration is missing for ${missing.join(", ")}.`);
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary registration is missing for ${missing.join(", ")}.`, undefined, "No action needed; the named harness has no lifecycle-summary registration.");
     }
     const unsupported = registrations
         .filter(({ registration }) => registration?.support === "unsupported")
         .map(({ id }) => id);
     if (unsupported.length > 0) {
-        return check("lifecycle-summary", "UNSUPPORTED", `Lifecycle summary is not dispatched for ${unsupported.join(", ")}; advisory runtime wiring is unavailable.`);
+        return check("lifecycle-summary", "UNSUPPORTED", `Lifecycle summary is not dispatched for ${unsupported.join(", ")}; advisory runtime wiring is unavailable.`, undefined, "No action needed; the named harness does not dispatch lifecycle-summary.");
     }
     const degraded = registrations
         .filter(({ registration }) => registration?.support === "degraded")
         .map(({ id }) => id);
     if (degraded.length > 0) {
-        return check("lifecycle-summary", "DEGRADED", `Lifecycle summary is degraded for ${degraded.join(", ")}.`);
+        return check("lifecycle-summary", "DEGRADED", `Lifecycle summary is degraded for ${degraded.join(", ")}.`, undefined, "No action needed; the named harness only partially supports lifecycle-summary.");
     }
     const unknown = registrations
         .filter(({ registration }) => registration?.support === "unknown")
         .map(({ id }) => id);
     if (unknown.length > 0) {
-        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary support is unknown for ${unknown.join(", ")}.`);
+        return check("lifecycle-summary", "UNKNOWN", `Lifecycle summary support is unknown for ${unknown.join(", ")}.`, undefined, "No action needed; support for the named harness has not been characterized.");
     }
     return check("lifecycle-summary", "PASS", "Lifecycle summary is reachable for every selected harness.");
 }
 async function checkSurfaceInventory(root, manifest, config) {
     if (manifest === undefined || config === undefined) {
         return {
-            check: check("surface-inventory", "UNKNOWN", "Harness surfaces cannot be inventoried without a valid manifest and configuration."),
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces cannot be inventoried without a valid manifest and configuration.", undefined, "No action needed; fix the manifest or config check above first."),
             surfaces: []
         };
     }
@@ -306,20 +327,22 @@ async function checkSurfaceInventory(root, manifest, config) {
         return {
             check: check("surface-inventory", unknown.length > 0 ? "UNKNOWN" : "PASS", unknown.length > 0
                 ? `${unknown.length} harness surface(s) could not be inspected.`
-                : "Harness surfaces were inventoried without exposing settings values."),
+                : "Harness surfaces were inventoried without exposing settings values.", undefined, unknown.length > 0
+                ? "No action needed; see Surfaces below for which ones and why."
+                : undefined),
             surfaces
         };
     }
     catch {
         return {
-            check: check("surface-inventory", "UNKNOWN", "Harness surfaces could not be inspected safely."),
+            check: check("surface-inventory", "UNKNOWN", "Harness surfaces could not be inspected safely.", undefined, "No action needed; inspection failed safely."),
             surfaces: []
         };
     }
 }
 async function checkRegistrationDrift(root, manifest, config) {
     if (manifest === undefined || config === undefined) {
-        return check("registration-drift", "UNKNOWN", "Hook registration drift cannot be assessed without a valid manifest and configuration.");
+        return check("registration-drift", "UNKNOWN", "Hook registration drift cannot be assessed without a valid manifest and configuration.", undefined, "No action needed; fix the manifest or config check above first.");
     }
     try {
         const statuses = await inspectHarnessRegistrations({
@@ -332,19 +355,12 @@ async function checkRegistrationDrift(root, manifest, config) {
             .map(({ harness }) => harness);
         return drifted.length === 0
             ? check("registration-drift", "PASS", "Managed hook registrations match the desired capabilities.")
-            : check("registration-drift", "FAIL", `Hook registration drift detected for ${drifted.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED");
+            : check("registration-drift", "FAIL", `Hook registration drift detected for ${drifted.join(", ")}; run agent-ops update.`, "UPDATE_REQUIRED", "Run `agent-ops update`.");
     }
     catch {
-        return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.");
+        return check("registration-drift", "UNKNOWN", "Hook registration drift could not be assessed safely.", undefined, "No action needed; drift could not be computed.");
     }
 }
-/**
- * Guidance lives in `message` rather than a `remediation` field: as of this
- * check, `remediation` does not exist on DoctorCheck. Because target
- * authentication failures surface as one unexplained review failure — the
- * chain deliberately does not sniff stderr for "not logged in" — this text is
- * the operator's only route out, so it names the exact command.
- */
 async function checkReviewTargets(config, probe, checkAuth) {
     const targets = config?.reviewRoles?.find((role) => role.role === "independent-review")?.targets ?? [];
     if (targets.length === 0) {
@@ -357,20 +373,16 @@ async function checkReviewTargets(config, probe, checkAuth) {
     for (const target of targets) {
         const result = await probe(target, checkAuth);
         if (result === "missing-executable") {
-            return check("review-targets", "FAIL", `${target} not found. Install it, or remove "${target}" from ` +
-                "reviewRoles[].targets.", "UPDATE_REQUIRED");
+            return check("review-targets", "FAIL", `${target} not found.`, undefined, `Install ${target}, or remove "${target}" from reviewRoles[].targets.`);
         }
         if (result === "ineligible") {
-            return check("review-targets", "FAIL", `${target} has no read-only mode and cannot review. Remove ` +
-                `"${target}" from reviewRoles[].targets.`, "UPDATE_REQUIRED");
+            return check("review-targets", "FAIL", `${target} has no read-only mode and cannot review.`, undefined, `Remove "${target}" from reviewRoles[].targets.`);
         }
         if (result === "timeout") {
-            return check("review-targets", "FAIL", `${target} did not answer in time. Re-run: ` +
-                "agent-ops doctor --check-auth", "UPDATE_REQUIRED");
+            return check("review-targets", "FAIL", `${target} did not answer in time.`, undefined, "Re-run: agent-ops doctor --check-auth");
         }
         if (checkAuth && result !== "ok") {
-            return check("review-targets", "FAIL", `${target} is installed but not authenticated, or it rejected the ` +
-                `call. Run: ${target} login`, "UPDATE_REQUIRED");
+            return check("review-targets", "FAIL", `${target} is installed but not authenticated, or it rejected the call.`, undefined, `Run: ${target} login`);
         }
     }
     return check("review-targets", "PASS", checkAuth

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

@@ -1,19 +1,27 @@
 import { harnessDescriptor } from "./harness.js";
 import { resolveCapabilities } from "./profiles.js";
 /**
- * Hook registration is satisfied when every hook event implied by the
- * installed profiles carries an agent-ops owned handler for every installed
- * harness. Installations without hook capabilities have nothing to register.
+ * Returns the harness ids missing an agent-ops owned handler for the hook
+ * events implied by the installed profiles. Empty when installations without
+ * hook capabilities have nothing to register.
  */
-export function hookRegistrationSatisfied(input) {
+export function hookRegistrationDrift(input) {
     const capabilities = input.config.profiles.length === 0
         ? []
         : resolveCapabilities(input.config).capabilities;
-    return input.harness.every((id) => {
+    return input.harness.filter((id) => {
         const descriptor = harnessDescriptor(id);
-        return descriptor.control.hookRegistered(input.sources[id], capabilities);
+        return !descriptor.control.hookRegistered(input.sources[id], capabilities);
     });
 }
+/**
+ * Hook registration is satisfied when every hook event implied by the
+ * installed profiles carries an agent-ops owned handler for every installed
+ * harness. Installations without hook capabilities have nothing to register.
+ */
+export function hookRegistrationSatisfied(input) {
+    return hookRegistrationDrift(input).length === 0;
+}
 /**
  * Smoke availability stays UNKNOWN until the repository declares a
  * verification command; the toolkit never invents one.

package/dist/runtime/src/install/surface-inspection.js

@@ -242,7 +242,8 @@ export async function inspectHarnessSurfaces(options) {
                     path: surface.path,
                     status: "unknown",
                     managedHandlerCount: 0,
-                    foreignHandlerCount: 0
+                    foreignHandlerCount: 0,
+                    reason: "Outside the installation root; not inspected by design."
                 });
                 continue;
             }
@@ -255,7 +256,10 @@ export async function inspectHarnessSurfaces(options) {
                         path: surface.path,
                         status: "missing",
                         managedHandlerCount: 0,
-                        foreignHandlerCount: 0
+                        foreignHandlerCount: 0,
+                        ...(surface.access === "inspect-only"
+                            ? { reason: "Optional file that agent-ops never writes." }
+                            : {})
                     });
                     continue;
                 }

package/docs/en/guides/configuration.md

@@ -203,7 +203,16 @@ alters an intact path-independent managed rules artifact,
 `artifact-staleness` reports `DEGRADED` with `UPDATE_REQUIRED`. `agent-ops
 update` regenerates the artifact and clears that result; a missing or
 hash-mismatched artifact remains an `artifacts` `FAIL`. Without the new trust
-grant, trust-gated hooks remain stale. Stop is report-only: it continues the
+grant, trust-gated hooks remain stale.
+
+Doctor never writes, and some findings have no fix: a surface outside the
+installation root, or a capability a harness only partially supports by
+descriptor declaration (opencode's `lifecycle-summary`, for example), report
+`UNKNOWN` or `DEGRADED` permanently and exit 0. CI that wants automatic
+repair calls `agent-ops update` / `agent-ops trust grant` directly rather
+than parsing doctor's output.
+
+Stop is report-only: it continues the
 harness for `PASS`, `FAIL`, or `UNKNOWN`, emits only bounded command ID, exit
 code, test-count, config-hash, and timestamp evidence, and never completes a
 task. Config v1 migrates deterministically to v2 with Stop disabled; old

package/docs/zh-TW/guides/configuration.md

@@ -183,7 +183,15 @@ agent-ops trust grant
 path-independent managed rules artifact 改變時，`artifact-staleness` 會回報帶有
 `UPDATE_REQUIRED` 的 `DEGRADED`。`agent-ops update` 會重新產生 artifact 並清除
 這個結果；artifact 缺失或 hash 不符時，`artifacts` check 仍為 `FAIL`。未重新
-grant trust 時，trust-gated hook 仍會是 stale。Stop 是 report-only：`PASS`、`FAIL`
+grant trust 時，trust-gated hook 仍會是 stale。
+
+doctor 從不寫入檔案，部分結果本來就無法修復：安裝根目錄以外的 surface，
+或 harness 依 descriptor 宣告只部分支援的 capability（例如 opencode 的
+`lifecycle-summary`），會永久回報 `UNKNOWN` 或 `DEGRADED` 且 exit 0。若 CI
+需要自動修復，請直接呼叫 `agent-ops update` / `agent-ops trust grant`，
+不要解析 doctor 的輸出。
+
+Stop 是 report-only：`PASS`、`FAIL`
 與 `UNKNOWN` 都會讓 harness 繼續，只輸出有界的 command ID、exit code、test-count、
 config-hash 與 timestamp evidence，且永遠不會完成 task。Config v1 會決定性遷移
 為 Stop disabled 的 v2；舊 binary 無法讀取遷移後的 config，routing migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Evidence-driven development loops for Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",