@kylecheng3146/agent-ops 0.3.6 → 0.4.0

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

@@ -6,6 +6,7 @@ import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { FileTransaction } from "../fs/transaction.js";
 import { planHookRemoval } from "./hooks.js";
+import { applyPreauth, planPreauth } from "./preauth.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
 import { isOpencodeManagedPlugin } from "../adapters/opencode/config.js";
 import { isHarnessId } from "./harness.js";
@@ -207,7 +208,7 @@ async function planArtifactRemoval(root, artifact) {
         expectedHash: current.hash
     };
 }
-async function createFullUninstallPlan(root) {
+async function createFullUninstallPlan(root, options = {}) {
     const currentManifest = await readCurrentFile(root, MANIFEST_PATH);
     if (currentManifest === null) {
         return {
@@ -262,11 +263,19 @@ async function createFullUninstallPlan(root) {
         path: MANIFEST_PATH,
         expectedHash: currentManifest.hash
     });
+    const preauthorization = await planPreauth({
+        root,
+        scope: manifest.scope,
+        harness: manifest.harness,
+        desired: false,
+        ...(options.codexHome === undefined ? {} : { codexHome: options.codexHome })
+    });
     return {
         installed: true,
         manifest,
         manifestHash: currentManifest.hash,
-        operations
+        operations,
+        ...(preauthorization.length === 0 ? {} : { preauthorization })
     };
 }
 async function planLoopMarkerUpdate(root, marker, expected, remaining) {
@@ -300,7 +309,7 @@ async function planLoopMarkerUpdate(root, marker, expected, remaining) {
             }
     };
 }
-async function planSelectiveUninstall(root, currentManifest, manifest, expectedMarkers, selectedHarnesses) {
+async function planSelectiveUninstall(root, currentManifest, manifest, expectedMarkers, selectedHarnesses, planOptions = {}) {
     if (selectedHarnesses.length === 0 ||
         selectedHarnesses.some((id) => !isHarnessId(id)) ||
         new Set(selectedHarnesses).size !== selectedHarnesses.length ||
@@ -310,7 +319,7 @@ async function planSelectiveUninstall(root, currentManifest, manifest, expectedM
     const selected = selectedSet(selectedHarnesses);
     const remaining = manifest.harness.filter((id) => !selected.has(id));
     if (remaining.length === 0) {
-        return await createFullUninstallPlan(root);
+        return await createFullUninstallPlan(root, planOptions);
     }
     const operations = [];
     const removedArtifacts = manifest.artifacts.filter((artifact) => shouldRemove(artifactOwners(manifest, artifact), selected));
@@ -398,26 +407,34 @@ async function planSelectiveUninstall(root, currentManifest, manifest, expectedM
         content: formatInstallManifest(resultingManifest),
         expectedHash: currentManifest.hash
     });
+    const preauthorization = await planPreauth({
+        root,
+        scope: manifest.scope,
+        harness: selectedHarnesses,
+        desired: false,
+        ...(planOptions.codexHome === undefined ? {} : { codexHome: planOptions.codexHome })
+    });
     return {
         installed: true,
         manifest,
         manifestHash: currentManifest.hash,
         operations,
         selectedHarnesses,
-        resultingManifest
+        resultingManifest,
+        ...(preauthorization.length === 0 ? {} : { preauthorization })
     };
 }
-export async function createUninstallPlan(root, selectedHarnesses) {
+export async function createUninstallPlan(root, selectedHarnesses, options = {}) {
     if (selectedHarnesses === undefined) {
-        return await createFullUninstallPlan(root);
+        return await createFullUninstallPlan(root, options);
     }
     const currentManifest = await readCurrentFile(root, MANIFEST_PATH);
     if (currentManifest === null) {
-        return await createFullUninstallPlan(root);
+        return await createFullUninstallPlan(root, options);
     }
     const manifest = parseInstallManifest(currentManifest.content);
     const expectedMarkers = assertSupportedManifestOwnership(manifest, root);
-    return await planSelectiveUninstall(root, currentManifest, manifest, expectedMarkers, selectedHarnesses);
+    return await planSelectiveUninstall(root, currentManifest, manifest, expectedMarkers, selectedHarnesses, options);
 }
 function allowedPaths(plan) {
     if (plan.manifest === null) {
@@ -559,9 +576,9 @@ async function validateUninstalled(root, manifest, resultingManifest) {
         throw new AgentOpsError("UNINSTALL_VALIDATION_FAILED", "Installation manifest still exists.");
     }
 }
-export async function applyUninstallPlan(root, plan) {
+export async function applyUninstallPlan(root, plan, options = {}) {
     assertUninstallPlan(plan);
-    const currentPlan = await createUninstallPlan(root, plan.selectedHarnesses);
+    const currentPlan = await createUninstallPlan(root, plan.selectedHarnesses, options);
     if (JSON.stringify(currentPlan) !== JSON.stringify(plan)) {
         throw new AgentOpsError("INVALID_UNINSTALL_PLAN", "Uninstall plan no longer matches the current managed installation.");
     }
@@ -571,4 +588,5 @@ export async function applyUninstallPlan(root, plan) {
     }
     const transaction = new FileTransaction(root);
     await transaction.apply({ operations: plan.operations }, async () => await validateUninstalled(root, manifest, plan.resultingManifest));
+    await applyPreauth(plan.preauthorization ?? []);
 }

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

@@ -124,6 +124,7 @@ export async function createUpdatePlan(options) {
             value: configPreview.migrated,
             sourceHash: configPreview.sourceHash
         },
+        ...(options.codexHome === undefined ? {} : { codexHome: options.codexHome }),
         ...(options.worktree === undefined
             ? {}
             : { worktree: options.worktree })

package/dist/runtime/src/parallel/enter.js

@@ -0,0 +1,43 @@
+import { readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { canonicalPath } from "./guard.js";
+import { readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
+/**
+ * Whether Claude's EnterWorktree may switch this session into `path`. Only the
+ * worktree agent-ops recorded for the session is answered for the host, so an
+ * allow never lets the session move its permission root to a directory it did
+ * not get from `worktree add`.
+ */
+export async function evaluateWorktreeEnter(mainRoot, path, sessionId) {
+    if (sessionId === undefined) {
+        return { action: "continue", status: "UNKNOWN", code: "WORKTREE_ENTER_UNJUDGED" };
+    }
+    const directory = join(mainRoot, WORKTREE_DIRECTORY);
+    const target = await canonicalPath(path);
+    const name = relative(directory, target).split(sep)[0] ?? "";
+    const inside = !target.startsWith(`${directory}${sep}`) ? false : target === join(directory, name);
+    if (inside && (await readWorktreeRecord(target))?.sessionId === sessionId) {
+        return {
+            action: "continue",
+            status: "PASS",
+            code: "WORKTREE_ENTER_ALLOWED",
+            remedy: `${target} is the worktree agent-ops recorded for this session.`,
+            decision: "allow"
+        };
+    }
+    const owned = [];
+    for (const entry of await readdir(directory).catch(() => [])) {
+        if ((await readWorktreeRecord(join(directory, entry)))?.sessionId === sessionId) {
+            owned.push(join(directory, entry));
+        }
+    }
+    return {
+        action: "block",
+        status: "FAIL",
+        code: "WORKTREE_ENTER_DENIED",
+        remedy: `EnterWorktree may enter only a worktree this session owns. ` +
+            (owned.length > 0
+                ? `Yours: ${owned.join(", ")}.`
+                : `None yet: run agent-ops worktree add <name> --session ${sessionId} from ${mainRoot}.`)
+    };
+}

package/dist/runtime/src/parallel/finish.js

@@ -251,7 +251,8 @@ export async function finishWorktree(deps, options) {
                 await deps.tasks(record.path, base).complete(task.task.id, {});
             }
             catch (error) {
-                throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+                throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)} ` +
+                    "A task another session left here is not this session's to archive: its owner finishes or archives it, and finish never does.");
             }
         }
         const worktreeGate = await deps.gate(record.path, worktreeConfig);

package/dist/runtime/src/parallel/guard.js

@@ -1,6 +1,6 @@
 import { realpath } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
-import { insideWorktreeDirectory } from "./service.js";
+import { insideWorktreeDirectory, readWorktreeRecord, WORKTREE_DIRECTORY } from "./service.js";
 /** The main checkout of the repository `runner` runs in, or null. */
 export async function resolveMainRoot(runner) {
     const result = await runner.run(["rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -47,6 +47,25 @@ ensureWorktree) {
     for (const path of paths) {
         const target = await canonicalPath(path);
         const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
+        if (inMain && insideWorktreeDirectory(mainRoot, target) && sessionId !== undefined) {
+            // A worktree belongs to the session that made it: writing into another
+            // session's mixes two tasks' changes into one review and one merge.
+            const name = relative(join(mainRoot, WORKTREE_DIRECTORY), target).split(sep)[0] ?? "";
+            const owner = (await readWorktreeRecord(join(mainRoot, WORKTREE_DIRECTORY, name)))?.sessionId;
+            if (owner !== undefined && owner !== sessionId) {
+                let own = "";
+                if (ensureWorktree !== undefined) {
+                    own = await ensureWorktree(sessionId).then((worktree) => ` Your own worktree is ${worktree}: edit there instead.`, () => "");
+                }
+                return {
+                    action: "block",
+                    status: "FAIL",
+                    code: "WORKTREE_OWNED_BY_OTHER_SESSION",
+                    remedy: `${join(mainRoot, WORKTREE_DIRECTORY, name)} belongs to another session (${owner}); ` +
+                        `this session is ${sessionId}.${own || " Run agent-ops worktree add <name> --session " + sessionId + " from " + mainRoot + " and edit in the printed path."}`
+                };
+            }
+        }
         if (inMain && !insideWorktreeDirectory(mainRoot, target)) {
             let failure = "";
             if (sessionId !== undefined && ensureWorktree !== undefined) {

package/dist/runtime/src/parallel/manage.js

@@ -154,6 +154,44 @@ export async function resumeWorktree(deps, options) {
     await bindSession(deps, record, mainConfig, RESUMED_BASELINE);
     return record;
 }
+/**
+ * Commits everything in the calling session's own worktree. Git runs from
+ * here rather than the shell, where a host cannot prove a command stays inside
+ * the worktree; that is also why it refuses anything that is not the caller's.
+ *
+ * ponytail: stages all changes, so an untracked file Git does not ignore goes
+ * in too; narrow it with a path list if that ever commits something unwanted.
+ */
+export async function commitWorktree(deps, options) {
+    const { mainRoot, currentRoot } = await resolveCheckouts(deps, options.cwd);
+    if (currentRoot === mainRoot) {
+        throw manageError("WORKTREE_COMMIT_MAIN", `worktree commit works only inside an agent-ops worktree; this is the main checkout (${mainRoot}).`);
+    }
+    const record = await readWorktreeRecord(currentRoot);
+    if (record === null) {
+        throw manageError("WORKTREE_COMMIT_UNRECORDED", `${currentRoot} is not an agent-ops worktree; see agent-ops worktree list.`);
+    }
+    if (options.sessionId === undefined) {
+        throw manageError("WORKTREE_COMMIT_SESSION_REQUIRED", "Cannot tell which session is committing; pass --session <id> or set AGENT_OPS_SESSION_ID.");
+    }
+    if (record.sessionId !== options.sessionId) {
+        throw manageError("WORKTREE_COMMIT_FOREIGN", `${record.path} belongs to session ${record.sessionId}, not ${options.sessionId}.`);
+    }
+    const step = async (args, code, message) => {
+        const result = await deps.git(record.path, args);
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim().split("\n")[0];
+            throw manageError(code, detail === undefined || detail === "" ? message : `${message} ${detail}`);
+        }
+        return result.stdout.trim();
+    };
+    await step(["add", "-A"], "WORKTREE_COMMIT_FAILED", "Git could not stage the worktree.");
+    if ((await deps.git(record.path, ["diff", "--cached", "--quiet"])).exitCode === 0) {
+        throw manageError("WORKTREE_COMMIT_NOTHING", `${record.path} has no changes to commit.`);
+    }
+    await step(["commit", "-m", options.message], "WORKTREE_COMMIT_FAILED", "Git refused the commit.");
+    return { record, commit: await step(["rev-parse", "HEAD"], "WORKTREE_COMMIT_FAILED", "Git could not read the new commit.") };
+}
 /**
  * Deletes a worktree and its branch. Work that exists nowhere else — an
  * uncommitted change or a commit the target lacks — needs `force`.

package/dist/runtime/src/parallel/service.js

@@ -291,7 +291,9 @@ export async function addWorktree(deps, options) {
     const mainTrust = await deps.trust.status(mainRoot, mainConfig);
     const setupSteps = mainConfig.worktree?.setup ?? [];
     if (setupSteps.length > 0 && mainTrust !== "TRUSTED") {
-        throw worktreeError("WORKTREE_SETUP_UNTRUSTED", "worktree.setup runs repository commands; run agent-ops trust grant in the main checkout first.");
+        throw worktreeError("WORKTREE_SETUP_UNTRUSTED", "worktree.setup runs repository commands and the main checkout is not trusted: trust is bound to the config hash, " +
+            "so a hand edit of .agent-ops/config.json (adding worktree.setup, say) leaves it untrusted. " +
+            "Trust is the user's to grant, once: run agent-ops update in the main checkout, which lists the commands it will trust and asks.");
     }
     await ensureExcluded(deps, mainRoot, commonDir);
     await git(deps, mainRoot, ["worktree", "add", "-b", branch, path, base], "WORKTREE_ADD_FAILED", "Git could not create the worktree.");

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

@@ -8,7 +8,7 @@ import { answeredNothing, conversationIdOf, deniedToolsOf, extractFinalMessage,
 import { buildTargetInvocation } from "./invocation.js";
 import { reviewReportResults, reviewReportStatus, validateReviewReport } from "./report.js";
 import { detectHostTarget, planReviewTargets } from "./roles.js";
-import { detectHostRestriction } from "./host-sandbox.js";
+import { detectHostRestriction, isLoginFailure, isNetworkFailure } from "./host-sandbox.js";
 import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
 import { MAX_ADVERSARIAL_PROMPT_BYTES } from "./runner.js";
 import { extractUsage, sumUsage } from "./usage.js";
@@ -143,10 +143,14 @@ function preflightUnavailableReason(result) {
             return "timeout";
         case "unauthenticated":
             return "login-required";
+        case "network-unreachable":
+            return "network-unreachable";
         case "ineligible":
             return "capability-unavailable";
         case "capability-unavailable":
             return "capability-unavailable";
+        case "probe-failed":
+            return "probe-failed";
     }
 }
 /**
@@ -155,7 +159,7 @@ function preflightUnavailableReason(result) {
  * suppressed under `--json`: a machine consumer would otherwise be left with
  * the bare authentication guess this exists to qualify. Never evidence.
  */
-function firstComplaint(...streams) {
+export function firstComplaint(...streams) {
     for (const stream of streams) {
         const line = redactSecrets(stream)
             .split(/\r?\n/u)
@@ -171,9 +175,10 @@ function rejectedCallReason(output) {
     if (/\b(?:quota|rate limit|usage limit|too many requests)\b/iu.test(output)) {
         return "quota-exhausted";
     }
-    if (/\b(?:not logged in|login required|log in to|authentication required|unauthenticated|unauthorized)\b/iu.test(output) ||
-        /\b(?:invalid|expired)\s+(?:api key|token|credential)/iu.test(output) ||
-        /\b401\b/u.test(output)) {
+    if (isNetworkFailure(output)) {
+        return "network-unreachable";
+    }
+    if (isLoginFailure(output)) {
         return "login-required";
     }
     return "capability-unavailable";
@@ -735,15 +740,18 @@ export function createReviewExecutor(options) {
                         attempts: []
                     };
                 }
-                const result = await options.preflightTarget(target, {
+                const answer = await options.preflightTarget(target, {
                     timeoutMs: Math.max(1, remainingMs())
                 });
+                const result = typeof answer === "string" ? answer : answer.result;
                 if (result === "ok") {
                     preflight.push({ target, status: "PASS" });
                     continue;
                 }
                 const reason = preflightUnavailableReason(result);
-                const diagnostic = `target preflight returned ${result}`;
+                const complaint = typeof answer === "string" ? undefined : answer.diagnostic;
+                const diagnostic = `target preflight returned ${result}` +
+                    (complaint === undefined ? "" : `: ${complaint}`);
                 preflight.push({ target, status: "NOT_RUN", reason, diagnostic });
                 report(`${target}: preflight ${reason} (${diagnostic})`);
                 return {

package/dist/runtime/src/review/host-sandbox.js

@@ -1,7 +1,51 @@
-import { createServer } from "node:net";
+import { connect, createServer } from "node:net";
 /** Targets that need a loopback listener of their own to answer at all. */
 export const BIND_DEPENDENT_TARGETS = ["agy"];
 const BIND_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * A reviewer that cannot reach its API host says so in its own words. Reading
+ * that as "not logged in" sent users to re-login an authenticated CLI when the
+ * host sandbox was what withheld the network.
+ */
+const NETWORK_FAILURE = /\b(?:ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)\b|getaddrinfo|fetch failed|network is unreachable|could not resolve host|no such host|dial tcp/iu;
+export function isNetworkFailure(output) {
+    return NETWORK_FAILURE.test(output);
+}
+/**
+ * Only output that says so is a login problem. A CLI that dies for any other
+ * reason (a sandbox denying its state directory, a crash) used to be reported
+ * as "not logged in" too, which sent users to re-login a working install.
+ */
+const LOGIN_FAILURE = /\b(?:not logged in|login required|log in to|authentication required|unauthenticated|unauthorized)\b|\b(?:invalid|expired)\s+(?:api key|token|credential)|\b401\b/iu;
+export function isLoginFailure(output) {
+    return LOGIN_FAILURE.test(output);
+}
+/** The host each reviewer talks to, so a reachability check tests its real path. */
+export const TARGET_API_HOST = {
+    agy: "cloudcode-pa.googleapis.com",
+    codex: "api.openai.com",
+    claude: "api.anthropic.com"
+};
+export const REACH_TIMEOUT_MS = 2_000;
+/**
+ * DNS plus a TCP connect to `host:443`, nothing sent. Diagnostic only: it
+ * refines a failed probe's reason and never gates a review, so a proxy-only
+ * network that fails it still gets the review attempted.
+ */
+export async function probeHostReachable(host, port = 443) {
+    return await new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const finish = (value) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(false), REACH_TIMEOUT_MS);
+        timer.unref();
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+    });
+}
 /**
  * Opens and immediately closes a loopback listener on an ephemeral port.
  * Cheap enough to run before every review, and it exercises exactly the

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

@@ -1,10 +1,16 @@
 import { runVerificationCommand } from "../verify/spawn.js";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { extractFinalMessage } from "./extract.js";
-import { isolatedReviewEnvironment } from "./execute.js";
+import { firstComplaint, isolatedReviewEnvironment } from "./execute.js";
+import { isLoginFailure, isNetworkFailure, probeHostReachable, TARGET_API_HOST } from "./host-sandbox.js";
 import { buildProbeInvocation } from "./invocation.js";
+/** A log's last non-empty line: where a CLI that logs to a file puts its error. */
+async function lastLogLine(path) {
+    const text = await readFile(path, "utf8").catch(() => "");
+    return text.split(/\r?\n/u).filter((line) => line.trim().length > 0).at(-1) ?? "";
+}
 const PROBE_PROMPT = "Reply with the single word OK and nothing else.";
 /**
  * Matches the review timeout rather than being "quick": codex at high
@@ -29,6 +35,9 @@ export function probeTimeoutMs(requested) {
  * is not evidence at all.
  */
 export async function probeReviewTarget(target, options) {
+    return (await probeReviewTargetDetailed(target, options)).result;
+}
+export async function probeReviewTargetDetailed(target, options) {
     const deep = options.deep === true;
     const directory = deep
         ? await mkdtemp(join(tmpdir(), "agent-ops-review-probe-"))
@@ -66,7 +75,7 @@ export async function probeReviewTarget(target, options) {
                 : {})
         });
         if (invocation === undefined) {
-            return "ineligible";
+            return { result: "ineligible" };
         }
         const spawned = await runVerificationCommand({
             id: `review-probe-${target}`,
@@ -88,21 +97,44 @@ export async function probeReviewTarget(target, options) {
                 : {})
         });
         if (spawned.failureClass === "missing-executable") {
-            return "missing-executable";
+            return { result: "missing-executable" };
         }
         if (spawned.timedOut) {
-            return "timeout";
+            return { result: "timeout" };
         }
-        if (/(?:operation not permitted|permission denied|bind(?:ing)?[^\n]*(?:failed|denied))/iu.test(`${spawned.stderr}\n${spawned.stdout}`)) {
-            return "capability-unavailable";
+        const output = `${spawned.stderr}\n${spawned.stdout}`;
+        // The target's own words, so a failure is never reduced to a guess. agy
+        // writes its errors to the log file the probe hands it, not to stderr.
+        const complaint = async () => firstComplaint(spawned.stderr, spawned.stdout) ??
+            (deep && target === "agy"
+                ? firstComplaint(await lastLogLine(join(directory, "agy.log")))
+                : undefined);
+        if (/(?:operation not permitted|permission denied|bind(?:ing)?[^\n]*(?:failed|denied))/iu.test(output)) {
+            return { result: "capability-unavailable", diagnostic: await complaint() };
         }
         if (!deep) {
-            return spawned.status === "PASS" ? "ok" : "unauthenticated";
+            return spawned.status === "PASS"
+                ? { result: "ok" }
+                : { result: "probe-failed", diagnostic: await complaint() };
+        }
+        if (spawned.status === "PASS" &&
+            extractFinalMessage(target, spawned.stdout) !== undefined) {
+            return { result: "ok" };
+        }
+        // An unreachable API host outranks whatever the CLI printed: a sandbox that
+        // withholds the network makes an authenticated CLI say "not logged in".
+        if (isNetworkFailure(output)) {
+            return { result: "network-unreachable", diagnostic: await complaint() };
+        }
+        if (!await (options.reachable ?? probeHostReachable)(TARGET_API_HOST[target])) {
+            return { result: "network-unreachable", diagnostic: await complaint() };
         }
-        return spawned.status === "PASS" &&
-            extractFinalMessage(target, spawned.stdout) !== undefined
-            ? "ok"
-            : "unauthenticated";
+        const diagnostic = await complaint();
+        // Login is what the output says it is; anything else is a probe that could
+        // not run, and the diagnostic is all the evidence there is.
+        return isLoginFailure(`${output}\n${diagnostic ?? ""}`)
+            ? { result: "unauthenticated", diagnostic }
+            : { result: "probe-failed", diagnostic };
     }
     finally {
         if (deep) {

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

@@ -83,6 +83,15 @@ export function renderReviewResult(result) {
             result.attempts?.some((attempt) => attempt.reason === "login-required")) {
             lines.push("Run: agent-ops doctor --check-auth to verify target authentication.");
         }
+        if (result.reason === "network-unreachable" ||
+            result.attempts?.some((attempt) => attempt.reason === "network-unreachable")) {
+            lines.push("The reviewer could not reach the network. This is not a login " +
+                "problem: run agent-ops outside the sandbox, or grant it escalated execution.");
+        }
+        if (result.reason === "probe-failed") {
+            lines.push("The reviewer CLI failed its probe for the reason quoted above. This " +
+                "is not a login problem: fix that cause instead of logging in again.");
+        }
         // Evidence is pinned to the source it was produced from, so any edit to a
         // changed file after the verifier ran — a doc rewritten by a later step
         // counts — voids it. Without the next command the caller reads

package/docs/en/guides/configuration.md

@@ -130,10 +130,21 @@ never rewritten.
 targets are permitted, `--yes` decides whether to spend money now.
 
 Reviewer failures are classified conservatively from their output: recognizable
-authentication messages become `login-required`, quota messages become
-`quota-exhausted`, and other non-zero exits become `capability-unavailable`.
-The review suggests `doctor --check-auth` only when an authentication failure
-was detected. Confirm target authentication with:
+network errors (`ENOTFOUND`, `fetch failed`, `getaddrinfo` and similar) become
+`network-unreachable`, authentication messages become `login-required`, quota
+messages become `quota-exhausted`, and other non-zero exits become
+`capability-unavailable`. A sandbox that withholds the network therefore is not
+reported as a logged-out CLI: `network-unreachable` tells you to run outside the
+sandbox instead of running `<target> login`. When a `--check-auth` probe or the
+review preflight finds a target unauthenticated, a 2-second TCP connection to
+that target's API host on port 443 (`cloudcode-pa.googleapis.com` for agy,
+`api.openai.com` for codex, `api.anthropic.com` for claude) decides between the
+two; it only refines the reported reason and never blocks a review. The review suggests
+`doctor --check-auth` only when an authentication failure was detected. A probe
+that fails without network or login wording is `probe-failed`, never
+`login-required`: the preflight record and `doctor` quote the target's own first
+line (for agy, the last line of its log file when stderr is empty) so the real
+cause is visible instead of guessed. Confirm target authentication with:
 
 ```bash
 agent-ops doctor              # presence only: no tokens, no network
@@ -196,6 +207,52 @@ evidence. Give each editing conversation its own worktree instead:
 - The session's completion gate follows it: Claude Code enters the worktree
   with EnterWorktree, and a host that cannot move a session (agy) is judged by
   the worktree's gate through a redirect the main checkout records.
+- A command knows its session from `--session`, then `AGENT_OPS_SESSION_ID`,
+  then `CODEX_THREAD_ID`, then the id a SessionStart recorded for the
+  checkout. Claude Code's SessionStart appends `AGENT_OPS_SESSION_ID` to its
+  `CLAUDE_ENV_FILE`, so every later Bash command carries it. When a different
+  session started in the same checkout within fifteen minutes, the recorded id
+  is contested: `task create`, `attach` and `status` fail with
+  `SESSION_ID_AMBIGUOUS` instead of acting as the wrong session.
+- A worktree belongs to the session that created it: a file write into
+  another session's worktree is denied (`WORKTREE_OWNED_BY_OTHER_SESSION`),
+  naming the session's own worktree. A session with no baseline (its
+  SessionStart never arrived) gets one at its first tool call, never at Stop.
+- Inside a worktree the project config is the main checkout's, so a branch
+  cannot change the gate, verifiers or trust that judge it before merging; a
+  worktree of a repository whose main checkout has no config uses its own.
+- `agent-ops worktree commit --message <text>` stages and commits every change
+  in the current worktree. Git runs inside agent-ops, not the shell, so a host
+  that cannot prove a shell command stays inside the worktree still lets the
+  session commit; it refuses the main checkout, a worktree another session
+  owns, a caller it cannot identify and an empty change. It stages everything
+  Git does not ignore, so keep stray files out of the worktree.
+- In auto mode the Claude PreToolUse hook also handles `EnterWorktree`: a
+  switch into exactly a worktree recorded for the calling session is allowed
+  without Claude Code's own confirmation, and any other path is denied
+  (`WORKTREE_ENTER_DENIED`, naming the session's worktrees). Run `agent-ops
+  update` once so the hook's matcher includes `EnterWorktree`; `doctor`
+  reports an older matcher as registration drift.
+- With `worktree.mode` auto, `init` and `update` also pre-authorize what a
+  session runs itself, and the plan lists it before you confirm: in
+  `.claude/settings.local.json`, `permissions.allow` for `agent-ops task`,
+  `verify`, `review`, `worktree` and `doctor` and `sandbox.excludedCommands`
+  for `agent-ops review` (your other entries are kept, and the plan describes
+  the file instead of printing it); and, when the CLI can see Codex's home
+  (`CODEX_HOME`, else `~/.codex`), `rules/agent-ops.rules` with allow rules
+  for `agent-ops review` and `doctor --check-auth`, with and without
+  `AGENT_OPS_HOST=`. `trust`, `allow-stop`, `init`, `update` and `uninstall`
+  are never pre-authorized. Turning auto mode off, or `uninstall`, takes
+  exactly those entries back out; a rules file of that name agent-ops did not
+  write is left alone.
+- `review` and `doctor` take `--output <file>`: the JSON envelope is written
+  there (mode 0600) and one summary line is printed. Use it instead of a shell
+  redirect, which Codex wraps in `zsh -lc` and can only allow by matching the
+  whole command string.
+- Trust is bound to the config hash, so a hand edit of `.agent-ops/config.json`
+  (adding `worktree.setup`, say) leaves the repository untrusted and
+  `WORKTREE_SETUP_UNTRUSTED` stops the next worktree. The one grant is the
+  user's: `agent-ops update` lists the commands it will trust and asks once.
 - In a worktree, verify and review each task but do not run `task complete`
   (Claude Code refuses it inside an isolated worktree session). `agent-ops
   worktree finish <name>` completes every non-archived task in the worktree,

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

@@ -111,9 +111,19 @@ task ID 必須明確指定，且永遠使用該 task 的原始 criteria；不能
 每次執行 review 仍需 `--yes`：init 的勾選決定「允許哪些目標」，
 `--yes` 決定「現在是否要花錢」。
 
-Reviewer 失敗會依輸出採保守分類：可辨識的認證訊息為 `login-required`，
+Reviewer 失敗會依輸出採保守分類：網路錯誤（`ENOTFOUND`、`fetch failed`、
+`getaddrinfo` 等）為 `network-unreachable`，可辨識的認證訊息為 `login-required`，
 quota 訊息為 `quota-exhausted`，其他非零退出則為 `capability-unavailable`。
+因此沙盒擋住網路時不會被誤報成 CLI 未登入：`network-unreachable` 會提示改在
+沙盒外執行，而不是執行 `<target> login`。當 `--check-auth` 探測或 review
+preflight 判定目標未認證時，會再對該目標的 API 主機（agy 為
+`cloudcode-pa.googleapis.com`、codex 為 `api.openai.com`、claude 為
+`api.anthropic.com`）的 443 埠做 2 秒 TCP 連線測試，據此在兩種原因間擇一；
+它只修正回報的原因，不會阻擋 review。
 只有偵測到認證失敗時，review 才會建議執行 `doctor --check-auth`。
+探測失敗但輸出沒有網路或登入字樣時為 `probe-failed`，不會被當成
+`login-required`：preflight 紀錄與 `doctor` 會引述目標自己的第一行輸出
+（agy 在 stderr 為空時取其 log 檔最後一行），讓真正原因可見而非猜測。
 可用以下指令確認目標的認證狀態：
 
 ```bash
@@ -170,6 +180,44 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
 - Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
   worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
   由 worktree 的 gate 判定。
+- 指令依序以 `--session`、`AGENT_OPS_SESSION_ID`、`CODEX_THREAD_ID`、SessionStart
+  為該 checkout 記錄的 id 得知自己的 session。Claude Code 的 SessionStart 會把
+  `AGENT_OPS_SESSION_ID` 寫入 `CLAUDE_ENV_FILE`，之後每個 Bash 指令都帶有它。
+  十五分鐘內若有另一個 session 在同一 checkout 啟動，記錄的 id 視為有爭議：
+  `task create`、`attach`、`status` 會以 `SESSION_ID_AMBIGUOUS` 失敗，而不是以
+  錯誤的 session 行動。
+- Worktree 屬於建立它的 session：寫入別的 session 的 worktree 會被拒絕
+  （`WORKTREE_OWNED_BY_OTHER_SESSION`），並指出該 session 自己的 worktree。沒有
+  baseline 的 session（SessionStart 沒送達）會在第一次呼叫工具時補建，絕不會在
+  Stop 時補建。
+- 在 worktree 內，專案 config 一律取自主 checkout，因此分支無法在合併前改變判定
+  它自己的 gate、verifier 或 trust；主 checkout 沒有 config 時才使用 worktree 自己的。
+- `agent-ops worktree commit --message <text>` 會暫存並 commit 目前 worktree 的
+  所有變更。Git 由 agent-ops 自己執行而非經過 shell，因此即使 host 無法證明某條
+  shell 指令停留在 worktree 內，session 仍能 commit；它會拒絕主 checkout、別的
+  session 擁有的 worktree、無法辨識的呼叫者，以及沒有變更的情況。它會暫存所有
+  Git 未忽略的檔案，所以請不要把雜檔留在 worktree 裡。
+- 在 auto 模式下，Claude 的 PreToolUse hook 也處理 `EnterWorktree`：切入恰好是
+  為呼叫 session 記錄的 worktree 時，不必經過 Claude Code 自己的確認即放行；其他
+  任何路徑一律拒絕（`WORKTREE_ENTER_DENIED`，並列出該 session 的 worktree）。請
+  執行一次 `agent-ops update`，讓 hook 的 matcher 包含 `EnterWorktree`；`doctor`
+  會把較舊的 matcher 回報為註冊漂移。
+- 當 `worktree.mode` 為 auto，`init` 與 `update` 也會預先授權 session 自己會執行的
+  指令，並在你確認前先列在計畫裡：在 `.claude/settings.local.json` 寫入
+  `agent-ops task`、`verify`、`review`、`worktree`、`doctor` 的 `permissions.allow`，
+  以及 `agent-ops review` 的 `sandbox.excludedCommands`（你原有的項目會保留，計畫只
+  描述該檔案而不印出內容）；若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則
+  `~/.codex`），另寫入 `rules/agent-ops.rules`，內含 `agent-ops review` 與
+  `doctor --check-auth` 的 allow 規則（含與不含 `AGENT_OPS_HOST=`）。`trust`、
+  `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
+  `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
+- `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），
+  並只印出一行摘要。請用它取代 shell 重導向；Codex 會把重導向包成 `zsh -lc`，只能
+  以整串指令比對來放行。
+- Trust 綁定 config hash，因此手動編輯 `.agent-ops/config.json`（例如加入
+  `worktree.setup`）會讓 repository 變成未受信任，`WORKTREE_SETUP_UNTRUSTED` 會擋下
+  下一個 worktree。唯一的授權點屬於使用者：`agent-ops update` 會列出它將信任的指令並
+  詢問一次。
 - 在 worktree 裡對每個 task 執行 verify 與 review，但不要執行 `task complete`
   （Claude Code 在隔離的 worktree session 中會拒絕它）。`agent-ops worktree finish
   <name>` 會在任何 rebase 之前 complete worktree 內每個未封存的 task，先 subtask