@kylecheng3146/agent-ops 0.9.0 → 0.10.2

package/dist/runtime/src/escape/rules.js

@@ -0,0 +1,252 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { globMatcher } from "../surface/schema.js";
+import { ESCAPE_LABELS } from "./origin.js";
+/** Escape Loop R2: learned, tracked, data-only rules. They can only add places a task must classify. */
+export const RULES_DIRECTORY = ".agent-ops-escapes/rules";
+export const RULE_LABELS = [...ESCAPE_LABELS, "surface-excluded", "surface-unseen"];
+/** Labels whose proof is a rule replayed at the escaped commit. */
+export const SURFACE_LABELS = ["surface", "surface-excluded", "surface-unseen"];
+/** Labels whose proof is a promoted red-to-green behavioral check of the fixing task. */
+export const CHECK_LABELS = ["criteria", "verify"];
+export const RULE_LIMITS = { backtestCommits: 200, maxFireRate: 0.3, backtestBudgetMs: 60_000, queryTimeoutMs: 30_000 };
+/** argv only: rule strings are repository data and must never meet a shell or a regex engine. */
+export function runGit(root, args, timeoutMs) {
+    return new Promise(resolve => {
+        execFile("git", [...args], { cwd: root, encoding: "buffer", timeout: Math.max(1, timeoutMs), maxBuffer: 256 * 1024 * 1024, shell: false }, (error, stdout) => {
+            const failure = error;
+            resolve({ code: failure === null ? 0 : typeof failure.code === "number" ? failure.code : null,
+                stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0), timedOut: failure?.killed === true });
+        });
+    });
+}
+export const gitRunner = (root) => ({ run: async (args) => {
+        const result = await runGit(root, args, RULE_LIMITS.queryTimeoutMs);
+        return { exitCode: result.code ?? 128, stdout: result.stdout };
+    } });
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const exact = (v, keys) => keys.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => keys.includes(k));
+const line = (v, min) => typeof v === "string" && v.trim().length >= min && v.length <= 256 && !/[\0\n\r]/u.test(v);
+const glob = (v) => line(v, 1) && !v.startsWith("/") && !v.includes("\\") &&
+    v.split("/").every(part => part !== "" && part !== "." && part !== "..");
+const strings = (v, check) => Array.isArray(v) && v.length <= 32 && v.every(check) && new Set(v).size === v.length;
+function invalid(file, message) {
+    throw new AgentOpsError("ESCAPE_RULE_INVALID", `${RULES_DIRECTORY}/${file}: ${message}`);
+}
+/** Strict: there is no field that removes a query, adds an exclusion or relaxes a gate. */
+export function parseRule(value, file) {
+    if (!record(value) || !exact(value, ["id", "escape", "label", "trigger", "expand", "noExclude"]))
+        invalid(file, "a rule is exactly {id, escape, label, trigger: {paths, tokens}, expand: {paths, queries}, noExclude}.");
+    if (typeof value.id !== "string" || !/^[a-z][a-z0-9-]{0,63}$/u.test(value.id) || file !== `${value.id}.json`)
+        invalid(file, "id is lowercase kebab-case and names the file <id>.json.");
+    if (typeof value.escape !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.escape))
+        invalid(file, "escape is the full escaped commit SHA.");
+    if (!RULE_LABELS.includes(value.label))
+        invalid(file, `label is one of ${RULE_LABELS.join(", ")}.`);
+    const { trigger, expand } = value;
+    if (!record(trigger) || !exact(trigger, ["paths", "tokens"]) || !strings(trigger.paths, glob) || !strings(trigger.tokens, v => line(v, 3)) ||
+        trigger.paths.length + trigger.tokens.length === 0)
+        invalid(file, "trigger needs 1-32 path globs and/or fixed-string tokens (3+ characters).");
+    if (!record(expand) || !exact(expand, ["paths", "queries"]) || !strings(expand.paths, glob) || !strings(expand.queries, v => line(v, 3)) ||
+        expand.paths.length + expand.queries.length === 0)
+        invalid(file, "expand needs 1-32 path globs and/or fixed-string queries (3+ characters).");
+    if (typeof value.noExclude !== "boolean")
+        invalid(file, "noExclude is true or false.");
+    return { id: value.id, escape: value.escape, label: value.label,
+        trigger: { paths: [...trigger.paths], tokens: [...trigger.tokens] }, expand: { paths: [...expand.paths], queries: [...expand.queries] },
+        noExclude: value.noExclude };
+}
+async function kind(path) {
+    try {
+        const stat = await lstat(path);
+        return stat.isSymbolicLink() ? "other" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+const unsafe = () => {
+    throw new AgentOpsError("ESCAPE_RULE_UNSAFE", `${RULES_DIRECTORY} must be a real directory of regular <id>.json files.`);
+};
+/** Fails closed: a broken or symlinked rule never silently stops tightening. */
+export async function loadRules(root) {
+    for (const directory of [".agent-ops-escapes", RULES_DIRECTORY]) {
+        const found = await kind(join(root, directory));
+        if (found === "missing")
+            return [];
+        if (found !== "directory")
+            unsafe();
+    }
+    const rules = [];
+    for (const name of (await readdir(join(root, RULES_DIRECTORY))).sort()) {
+        const path = join(root, RULES_DIRECTORY, name);
+        if (await kind(path) !== "file")
+            unsafe();
+        if (!name.endsWith(".json"))
+            invalid(name, "only <id>.json rule files belong here.");
+        // O_NOFOLLOW closes the lstat-to-open race on POSIX; Windows has no such flag.
+        const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let source;
+        try {
+            source = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch {
+            invalid(name, "not JSON.");
+        }
+        rules.push({ rule: parseRule(value, name), hash: sha256(source) });
+    }
+    return rules;
+}
+/** Added and removed lines only: headers and context never trigger. */
+function changedLines(diff) {
+    return diff.split("\n").filter(l => /^[+-]/u.test(l) && !l.startsWith("+++") && !l.startsWith("---")).map(l => l.slice(1));
+}
+/** A rule fires when a changed path matches a trigger glob or a changed line contains a trigger token. */
+export function ruleFires(rule, paths, diff) {
+    const globs = rule.trigger.paths.map(globMatcher);
+    if (paths.some(path => globs.some(match => match(path))))
+        return true;
+    if (rule.trigger.tokens.length === 0)
+        return false;
+    const lines = changedLines(diff);
+    return rule.trigger.tokens.some(token => lines.some(l => l.includes(token)));
+}
+const zList = (value) => value.toString("utf8").split("\0").filter(Boolean);
+/** Files a fired rule puts in front of the task: path globs over tracked files plus git grep -F queries; ref absent = working tree. */
+export async function ruleHits(root, rule, ref, timeoutMs = RULE_LIMITS.queryTimeoutMs) {
+    const hits = new Set();
+    const fail = () => { throw new AgentOpsError("SURFACE_BUDGET_EXCEEDED", `Rule ${rule.id} could not list its expand hits in time.`); };
+    if (rule.expand.paths.length > 0) {
+        const files = await runGit(root, ref === undefined ? ["ls-files", "-z"] : ["ls-tree", "-r", "-z", "--name-only", ref], timeoutMs);
+        if (files.code !== 0)
+            fail();
+        const globs = rule.expand.paths.map(globMatcher);
+        for (const path of zList(files.stdout))
+            if (globs.some(match => match(path)))
+                hits.add(path);
+    }
+    for (const query of rule.expand.queries) {
+        const result = await runGit(root, ["grep", "-F", "-l", "-z", "-I", "--no-color", "-e", query, ...(ref === undefined ? [] : [ref]), "--"], timeoutMs);
+        if (result.timedOut || (result.code !== 0 && result.code !== 1))
+            fail();
+        for (const hit of zList(result.stdout))
+            hits.add(ref === undefined ? hit : hit.slice(ref.length + 1));
+    }
+    // A rule's own text names its queries; the ledger is never a product surface.
+    return [...hits].filter(path => !path.startsWith(".agent-ops-escapes/")).sort();
+}
+/** One commit's own change against its first parent (the empty tree for a root commit). */
+export async function commitChange(root, commit) {
+    const names = await runGit(root, ["show", "-m", "--first-parent", "--format=", "--name-only", "-z", "--no-renames", commit, "--"], RULE_LIMITS.queryTimeoutMs);
+    const diff = await runGit(root, ["show", "-m", "--first-parent", "--format=", "-U0", "--no-color", "--no-ext-diff", "--no-textconv",
+        "--no-renames", commit, "--"], RULE_LIMITS.queryTimeoutMs);
+    if (names.code !== 0 || diff.code !== 0)
+        throw new AgentOpsError("ESCAPE_GIT_FAILED", `git show ${commit} failed.`);
+    return { paths: zList(names.stdout), diff: diff.stdout.toString("utf8") };
+}
+/** Product files a past fix commit touched (tests and agent-ops data are not missed surfaces). */
+export async function fixPaths(root, fix) {
+    return (await commitChange(root, fix)).paths.filter(path => !path.startsWith(".agent-ops") &&
+        !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort().slice(0, 200);
+}
+/**
+ * The trigger against the last 200 first-parent commits, in one argv git call.
+ * ponytail: one `git log -p` buffered in memory (256 MiB cap); stream it if huge histories need it.
+ */
+export async function backtestRule(root, loaded, budgetMs = RULE_LIMITS.backtestBudgetMs) {
+    const head = (await runGit(root, ["rev-parse", "HEAD"], RULE_LIMITS.queryTimeoutMs)).stdout.toString("utf8").trim();
+    const cachePath = join(root, ".agent-ops", "tasks", "escape", "backtest", sha256(canonicalJson({ head, rule: loaded.hash, limit: RULE_LIMITS.backtestCommits })) + ".json");
+    try {
+        const cached = await readPrivateFile(cachePath, root);
+        if (cached !== null)
+            return JSON.parse(cached);
+    }
+    catch { /* recompute */ }
+    const log = await runGit(root, ["log", "--first-parent", "-m", "-n", String(RULE_LIMITS.backtestCommits), "-p", "-U0", "--no-color",
+        "--no-ext-diff", "--no-textconv", "--no-renames", "--format=%x00commit %H", "HEAD", "--"], budgetMs);
+    if (log.timedOut)
+        throw new AgentOpsError("SURFACE_BUDGET_EXCEEDED", `Backtest of rule ${loaded.rule.id} exceeded its ${budgetMs} ms budget.`);
+    if (log.code !== 0)
+        throw new AgentOpsError("ESCAPE_GIT_FAILED", "git log failed during the rule backtest.");
+    const commits = log.stdout.toString("utf8").split("\0commit ").slice(1);
+    let fires = 0;
+    for (const chunk of commits) {
+        const paths = [...chunk.matchAll(/^diff --git a\/.+? b\/(.+)$/gmu)].map(m => m[1]);
+        if (ruleFires(loaded.rule, paths, chunk))
+            fires += 1;
+    }
+    const result = { commits: commits.length, fires, rate: commits.length === 0 ? 0 : Math.round(fires / commits.length * 1000) / 1000 };
+    await writePrivateFile(cachePath, JSON.stringify(result), root).catch(() => undefined);
+    return result;
+}
+/**
+ * Proof per label. Surface labels need a rule for this escape that fires on the
+ * escaped commit's own diff and whose hits at that commit cover every missed
+ * path that existed there; no test or review ever runs at the escaped commit.
+ */
+export async function proveEscape(input) {
+    if (CHECK_LABELS.includes(input.label))
+        return { status: "check", check: input.promote ?? null };
+    if (!SURFACE_LABELS.includes(input.label))
+        return { status: "lesson", reason: `${input.label}: no mechanical replay exists for this gate; recorded as an unproven lesson.` };
+    const rules = (await loadRules(input.root)).filter(r => r.rule.escape === input.escapeOf);
+    if (rules.length === 0)
+        return { status: "unproven", code: "ESCAPE_RULE_UNPROVEN",
+            reason: `No ${RULES_DIRECTORY}/<id>.json rule names escape ${input.escapeOf}.` };
+    const change = await commitChange(input.root, input.escapeOf);
+    const required = [];
+    for (const path of input.missedPaths)
+        if ((await runGit(input.root, ["cat-file", "-e", `${input.escapeOf}:${path}`], RULE_LIMITS.queryTimeoutMs)).code === 0)
+            required.push(path);
+    const reasons = [];
+    for (const loaded of rules) {
+        if (!ruleFires(loaded.rule, change.paths, change.diff)) {
+            reasons.push(`${loaded.rule.id} does not fire on the escaped commit`);
+            continue;
+        }
+        const hits = new Set(await ruleHits(input.root, loaded.rule, input.escapeOf));
+        const missing = required.filter(path => !hits.has(path));
+        if (missing.length > 0) {
+            reasons.push(`${loaded.rule.id} misses ${missing.slice(0, 5).join(", ")}`);
+            continue;
+        }
+        let backtest;
+        try {
+            backtest = await backtestRule(input.root, loaded, input.budgetMs);
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError && error.code === "SURFACE_BUDGET_EXCEEDED")
+                return { status: "unproven", code: "SURFACE_BUDGET_EXCEEDED", reason: error.message, rule: loaded.rule.id };
+            throw error;
+        }
+        if (backtest.rate > RULE_LIMITS.maxFireRate)
+            return { status: "unproven", code: "ESCAPE_RULE_TOO_BROAD", rule: loaded.rule.id, backtest,
+                reason: `${loaded.rule.id} fires on ${backtest.fires} of the last ${backtest.commits} first-parent commits (> ${RULE_LIMITS.maxFireRate * 100}%).` };
+        return { status: "proven", rule: loaded.rule.id, ruleHash: loaded.hash, backtest };
+    }
+    return { status: "unproven", code: "ESCAPE_RULE_UNPROVEN", reason: reasons.join("; ") };
+}
+/** Printed only: agent-ops never writes .agent-ops/config.json for an executable rule. */
+export function configProposal(promote, config) {
+    const [runnerId, checkId] = promote.split(":");
+    const runner = config?.verification.acceptanceRunners?.find(r => r.id === runnerId);
+    return { note: "Proposal only: review it, then apply it yourself and confirm trust with agent-ops update; agent-ops never writes this config.",
+        promote: { runnerId, checkId },
+        verification: { commands: [{ id: `escape-${checkId}`.slice(0, 64), command: runner?.command ?? "<runner command>", args: [...runner?.args ?? []],
+                    cwd: runner?.cwd ?? ".", required: true, evidence: { kind: "exit-code" } }] } };
+}

package/dist/runtime/src/fs/temporary.js

@@ -0,0 +1,10 @@
+import { rm } from "node:fs/promises";
+/**
+ * Removes a scratch directory without letting cleanup hide the result it served.
+ * Windows can hold a just-killed child's files open for a moment (EBUSY), so rm
+ * retries; a directory that still cannot be removed stays in the OS temp dir.
+ */
+export async function removeTemporary(path) {
+    // ponytail: a leaked temp directory is the ceiling; the OS temp cleaner reclaims it.
+    await rm(path, { recursive: true, force: true, maxRetries: 10 }).catch(() => undefined);
+}

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

@@ -340,8 +340,11 @@ function autoRunInstruction(descriptor, context) {
         "`WORKTREE_NESTED`, say so in one line naming the code and fall back to",
         "the subtask flow (`task create --parent`, then batch or advance).",
         "`RUN_REPO_UNTRUSTED` means stop and ask the user; never work",
-        "around trust. If the run ends without completing (blocked, budget",
-        "exhausted, stopped, failing review), report the `agent-ops run status",
+        "around trust. New runs have no total time cap; legacy finite runs upgrade",
+        "only on manual resume, preserving accounting and independent blockers.",
+        "Command/review timeouts, provider limits and DEBUG budgets remain effective.",
+        "If the run ends without completing (blocked, stopped, failing review),",
+        "report the `agent-ops run status",
         "<id>` state and code, the last `agent-ops run logs <id>` events, and the",
         "exact `agent-ops run resume <id>` and `agent-ops run stop <id>` commands,",
         "then stop: never resume automatically or take over the run's work.",
@@ -362,9 +365,9 @@ export function managedRules(descriptor, context) {
         ""
     ];
     if (context.capabilities.includes("task-debug"))
-        lines.push("Task DEBUG routing is enabled for investigation/bugfix issues. Native prompt hooks create the issue task when a session identity is available; otherwise use agent-ops task create --debug --goal <verbatim issue> with two to five issue-specific criteria. Explain/read-only, feature and refactor requests use the existing normal task flow.", "For DEBUG: understand the issue, investigate with task debug --debug-action investigate --command-id <trusted verifier>, record falsifiable hypotheses with --debug-action hypothesis --payload-file <json>, reproduce, fix, verify, then obtain two fresh independent reviews and finish automatically. A clean HEAD is the automatic baseline; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Replace provisional intake criteria with relevant behavioral acceptance; baseline setup/skip/timeout/UNKNOWN is never reproduction. Never report success from edits or unrelated green checks.", "DEBUG defaults are 60 cumulative active minutes and 5 material repair candidates across the original issue, revisions, sessions and children. After two stagnant candidates document one substantive strategy switch; two further stagnant candidates block. Save task debug --debug-action checkpoint before stopping. Resume preserves budgets and blockers. A human continue event may authorize --debug-action extend --event-id latest; unsupported native event sources fail closed. Never use allow-stop for DEBUG.", "DEBUG human control comes only from native human events: '只診斷' / 'diagnosis only' keeps investigating without product repairs until current sealed baseline assertion FAIL confirms a hypothesis or runtime limits/blockers permit non-success Stop. '暫停' / 'pause' saves progress and stops immediately. '繼續' / 'continue' resumes the existing scope; '繼續修復' / 'resume repair' restores the full loop. Codex Interrupt is a pause. Preserve the original task, evidence, consumed time and rounds; diagnosis or pause never marks repair complete. CLI actor/text fields and synthetic instructions cannot authorize these changes.", "DEBUG is foreground work. On Claude, agy and native Codex, Stop refuses an active DEBUG issue without a valid stop checkpoint, with or without the completion gate. Codex uses decision:block to continue the original task even on repeated Stop; stop_hook_active does not waive it. Codex's generic completion gate remains unsupported; opencode has no supported foreground lifecycle. DEBUG gate faults get one targeted task/config reload, then an explicit UNKNOWN/incomplete diagnostic and non-success Stop, preserving state. Without reliable native session identity, automatic hook intake is unsupported; the existing native Agent can use the task CLI. Only a matching owned debug worktree checkpoint permits dirty recovery; preserve all original user edits.", "");
+        lines.push("Task DEBUG routing is enabled for investigation/bugfix issues. Native prompt hooks create the issue task when a session identity is available; otherwise use agent-ops task create --debug --goal <verbatim issue> with two to five issue-specific criteria. Explain/read-only, feature and refactor requests use the existing normal task flow.", "For DEBUG: understand the issue, investigate with task debug --debug-action investigate --command-id <trusted verifier>, record falsifiable hypotheses with --debug-action hypothesis --payload-file <json>, reproduce, fix, then once a hypothesis is confirmed declare the origin with --debug-action origin --payload-file <json> (escape-of <commit> with the earliest-gate label, or pre-existing/external with a reason; finish refuses ESCAPE_ORIGIN_MISSING without it; a surface label also needs a tracked .agent-ops-escapes/rules/<id>.json rule that replays at the escaped commit, and a criteria/verify label payload promote or --escape-promote <runnerId:checkId>, else ESCAPE_RULE_UNPROVEN), verify, re-record the confirmed hypothesis, commit the .agent-ops-escapes record with the fix, then obtain two fresh independent reviews and finish automatically. A normal task fixing an escaped bug may declare task create --escape-of <commit> --escape-label <label>. A clean HEAD is the automatic baseline; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Replace provisional intake criteria with relevant behavioral acceptance; baseline setup/skip/timeout/UNKNOWN is never reproduction. Never report success from edits or unrelated green checks.", "DEBUG defaults are 60 cumulative active minutes and 5 material repair candidates across the original issue, revisions, sessions and children. After two stagnant candidates document one substantive strategy switch; two further stagnant candidates block. Save task debug --debug-action checkpoint before stopping. Resume preserves budgets and blockers. A human continue event may authorize --debug-action extend --event-id latest; unsupported native event sources fail closed. Never use allow-stop for DEBUG.", "DEBUG human control comes only from native human events: '只診斷' / 'diagnosis only' keeps investigating without product repairs until current sealed baseline assertion FAIL confirms a hypothesis or runtime limits/blockers permit non-success Stop. '暫停' / 'pause' saves progress and stops immediately. '繼續' / 'continue' resumes the existing scope; '繼續修復' / 'resume repair' restores the full loop. Codex Interrupt is a pause. Preserve the original task, evidence, consumed time and rounds; diagnosis or pause never marks repair complete. CLI actor/text fields and synthetic instructions cannot authorize these changes.", "DEBUG is foreground work. On Claude, agy and native Codex, Stop refuses an active DEBUG issue without a valid stop checkpoint, with or without the completion gate. Codex uses decision:block to continue the original task even on repeated Stop; stop_hook_active does not waive it. Codex's generic completion gate remains unsupported; opencode has no supported foreground lifecycle. DEBUG gate faults get one targeted task/config reload, then an explicit UNKNOWN/incomplete diagnostic and non-success Stop, preserving state. Without reliable native session identity, automatic hook intake is unsupported; the existing native Agent can use the task CLI. Only a matching owned debug worktree checkpoint permits dirty recovery; preserve all original user edits.", "");
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria and verification; final review covers all", "tasks together when their worktrees are integrated;", "completing one never completes its parent.", "", ...autoRunInstruction(descriptor, context), "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "For subagents in separate worktrees, use `task advance` instead.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "", "For a session with writing subagents, record each child task's complete", "modification intent with `task create --intent <text>` before editing.", "Each child commits and runs local `verify --task` in its own worktree.", "From the main checkout run `agent-ops task advance --task <parent-id>", "--session <session-id> --yes` through the trusted outer host runner,", "unsetting `CODEX_SANDBOX_NETWORK_DISABLED` on Codex. Advance integrates", "child commits and intent into the coordinator worktree, verifies every", "task on the final candidate, then runs one two-round tree review.", "Only `NOT_RUN / scope-too-large` falls back to per-task two-round review;", "a substantive FAIL must be fixed. After PASS, advance writes a local", "receipt under the main checkout's Git common directory and calls finish.", "If the target moves, it retries the final gate once. An unresolved", "failure preserves worktrees and cannot be reported as finished.", "");

package/dist/runtime/src/logging/local-log.js

@@ -1,5 +1,7 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { AgentOpsError } from "../fs/paths.js";
-import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { localStatePaths, readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { redactSecrets } from "../security/redact.js";
 const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
 const DEFAULT_MAX_BYTES = 1024 * 1024;
@@ -125,6 +127,21 @@ function sanitizeEvent(value) {
             residualRisks: value.residualRisks
         };
     }
+    if (value.type === "gate-catch") {
+        if (!hasExactKeys(value, ["code", "taskId", "type"]) || typeof value.code !== "string" || !ID_PATTERN.test(value.code) ||
+            typeof value.taskId !== "string" || !ID_PATTERN.test(value.taskId)) {
+            return invalidEvent();
+        }
+        return { type: "gate-catch", code: value.code, taskId: value.taskId };
+    }
+    if (value.type === "escape-rule") {
+        if (!hasExactKeys(value, ["excluded", "included", "ruleId", "type"]) || typeof value.ruleId !== "string" ||
+            !/^[a-z][a-z0-9-]{0,63}$/u.test(value.ruleId) ||
+            [value.included, value.excluded].some((n) => !Number.isSafeInteger(n) || n < 0)) {
+            return invalidEvent();
+        }
+        return { type: "escape-rule", ruleId: value.ruleId, included: value.included, excluded: value.excluded };
+    }
     return invalidEvent();
 }
 function serialize(stored) {
@@ -198,3 +215,29 @@ export async function appendLocalLog(path, event, options) {
         await writePrivateFile(path, serialized.join(""), options.anchorDirectory);
     });
 }
+/** Advisory and fail-open: a logging fault never changes the gate that caught something. */
+export async function logGateCatch(code, taskId, home = process.env.AGENT_OPS_HOME ?? homedir()) {
+    try {
+        const state = localStatePaths(home);
+        await appendLocalLog(join(state.logDirectory, "events.ndjson"), { type: "gate-catch", code, taskId }, { anchorDirectory: state.anchorDirectory });
+    }
+    catch { /* advisory only */ }
+}
+/** Read-only and fail-open for reports: unreadable lines are skipped, a missing log is empty. */
+export async function readLocalLog(home = process.env.AGENT_OPS_HOME ?? homedir()) {
+    try {
+        const state = localStatePaths(home);
+        const source = await readPrivateFile(join(state.logDirectory, "events.ndjson"), state.anchorDirectory);
+        return (source ?? "").split("\n").filter(Boolean).flatMap((line) => {
+            try {
+                return [parseStoredLine(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/runtime/src/office/scene.js

@@ -122,7 +122,7 @@ export function sceneModel(snapshot) {
         return { key, sourceIndex: index, kind: "run", title: titled(repo, run.title), top: 0, props, actors, phaseAreas: makeAreas(), questions, criteria,
             activities: activitiesOf(optional(run).activities),
             board: boardFor(rootProgress, run.status, taskId, questions.length), papers, books: { lit: rootProgress?.passed ?? 0, total: rootProgress?.total ?? 0 },
-            clock: run.budget.limitMs > 0 ? run.budget.remainingMs / run.budget.limitMs : 0, phase: run.phase, status: run.status,
+            clock: run.budget.limitMs !== null && run.budget.remainingMs !== null && run.budget.limitMs > 0 ? run.budget.remainingMs / run.budget.limitMs : 1, phase: run.phase, status: run.status,
             completedAt, repo, overview: { x: 0, y: 0, width: 0, height: 0 } };
     };
     const activitiesOf = (value) => (Array.isArray(value) ? value : []).map(raw => {

package/dist/runtime/src/office/server.js

@@ -25,7 +25,7 @@ function send(res, status, type, body, headers = {}) {
 }
 /** Loopback-only, token-gated, GET-only view of the building. */
 export function createOfficeServer(options) {
-    const token = options.token ?? randomBytes(24).toString("base64url");
+    let token = options.token ?? randomBytes(24).toString("base64url");
     const now = options.now ?? Date.now;
     const idleMs = options.idleMs ?? OFFICE_IDLE_MS;
     let lastActive = now();
@@ -40,6 +40,8 @@ export function createOfficeServer(options) {
         const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
         if (!same(url.searchParams.get("token") ?? "", token))
             return send(res, 403, "text/plain", "Forbidden\n");
+        if (url.pathname === "/health")
+            return send(res, 200, "text/plain", "ok\n");
         if (url.pathname === "/") {
             const nonce = randomBytes(16).toString("base64");
             return send(res, 200, "text/html; charset=utf-8", officePage(nonce), { "Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'` });
@@ -54,16 +56,25 @@ export function createOfficeServer(options) {
         else
             res.end(); });
     });
+    const bind = (candidate) => new Promise((resolve, reject) => {
+        const onError = (error) => { server.removeListener("listening", onListening); reject(error); };
+        const onListening = () => {
+            server.removeListener("error", onError);
+            const address = server.address();
+            port = typeof address === "object" && address !== null ? address.port : 0;
+            resolve(port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(candidate, "127.0.0.1");
+    });
     return {
-        server, token,
-        listen: async () => await new Promise((resolve, reject) => {
-            server.once("error", reject);
-            server.listen(0, "127.0.0.1", () => {
-                const address = server.address();
-                port = typeof address === "object" && address !== null ? address.port : 0;
-                resolve(port);
-            });
-        }),
+        server,
+        get token() { return token; },
+        set token(value) { token = value; },
+        listen: async (preferredPort = 0) => preferredPort > 0
+            ? await bind(preferredPort).catch(async () => await bind(0))
+            : await bind(0),
         tick: async () => {
             const snapshot = await options.snapshot().catch(() => null);
             const sessionIsPresent = snapshot?.lobby.some(desk => (desk.sessionActive ?? desk.status === "active") && (desk.completedAt === undefined || desk.completedAt === null)) ?? false;
@@ -86,16 +97,29 @@ function alive(pid) {
         return error.code === "EPERM";
     }
 }
-/** A recorded server counts only if its process lives and it answers with its own token. */
-export async function readLiveOffice(home) {
+export async function readOfficeRecord(home) {
     const source = await readPrivateFile(officeRecordPath(home), home.anchor).catch(() => null);
     if (source === null)
         return null;
     try {
         const record = JSON.parse(source);
-        if (!Number.isSafeInteger(record.pid) || !Number.isSafeInteger(record.port) || typeof record.token !== "string" || !alive(record.pid))
-            return null;
-        const response = await fetch(`http://127.0.0.1:${record.port}/snapshot.json?token=${encodeURIComponent(record.token)}`, { signal: AbortSignal.timeout(2000) });
+        return Number.isSafeInteger(record.pid) && Number.isSafeInteger(record.port) &&
+            record.port > 0 && record.port <= 65535 &&
+            typeof record.token === "string" && record.token.length > 0
+            ? record
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A recorded server counts only if its process lives and it answers with its own token. */
+export async function readLiveOffice(home) {
+    const record = await readOfficeRecord(home);
+    if (record === null || !alive(record.pid))
+        return null;
+    try {
+        const response = await fetch(`http://127.0.0.1:${record.port}/health?token=${encodeURIComponent(record.token)}`, { signal: AbortSignal.timeout(2000) });
         await response.body?.cancel();
         return response.status === 200 ? record : null;
     }
@@ -111,7 +135,10 @@ export async function claimOffice(home, office, pid = process.pid) {
     return await withPrivateFileLock(officeRecordPath(home), home.anchor, async () => {
         if (await readLiveOffice(home) !== null)
             return null;
-        const record = { pid, port: await office.listen(), token: office.token, startedAt: new Date().toISOString() };
+        const previous = await readOfficeRecord(home);
+        if (previous !== null)
+            office.token = previous.token;
+        const record = { pid, port: await office.listen(previous?.port), token: office.token, startedAt: new Date().toISOString() };
         await writePrivateFile(officeRecordPath(home), JSON.stringify(record) + "\n", home.anchor);
         return record;
     });

package/dist/runtime/src/office/snapshot.js

@@ -52,7 +52,7 @@ export function buildOfficeSnapshot(input) {
             ...(rootTaskId === null ? {} : { progress: rootTree?.progress ?? rootTask?.progress ?? null,
                 ...(rootTree?.criteria === undefined ? {} : { criteria: rootTree.criteria }) }),
             status: run.status, phase: run.phase ?? "unknown",
-            budget: { limitMs: run.budget.limitMs, usedMs, remainingMs: Math.max(0, run.budget.limitMs - usedMs) },
+            budget: { limitMs: run.budget.limitMs, usedMs, remainingMs: run.budget.limitMs === null ? null : Math.max(0, run.budget.limitMs - usedMs) },
             questions, agents, reviewers,
             ...(run.status === "complete" || run.status === "failed" ? { completedAt: run.updatedAt } : {}),
             commands: [`agent-ops run status ${run.runId}`, `agent-ops run logs ${run.runId}`,