agy-worker-mcp 0.3.1

package/dist/broker/blockers.js

@@ -0,0 +1,390 @@
+import { ceilingAbsenceHint } from '../policy/ceiling.js';
+import { AGY_ENGINE_REFUSAL_SIGNATURES, } from '../contract/types.js';
+/**
+ * The single place that answers "who refused, and can the caller fix it".
+ *
+ * `outcome`, the judgement packet's `counts`, `verification.warnings` and
+ * `agy_start`'s own reply are all projections of the `Blocker` list built here.
+ * Before 0.1.1 each of those re-derived the rule for itself, and they disagreed:
+ * one real job came back with `counts.permission_denials: 1` next to
+ * `outcome: "success_unverified"`, because the packet counted every Class 1
+ * event while `decideOutcome` counted only the ones our gate authored.
+ *
+ * The mapping, and nothing may re-implement a row of it:
+ *
+ * | source           | what                                  | actionable | remedy                        | blocks_outcome |
+ * | ---------------- | ------------------------------------- | ---------- | ----------------------------- | -------------- |
+ * | `policy_ceiling` | `rejected_allow` entry (pre-flight)   | yes        | drop it / change profile      | n/a (no job yet) |
+ * | `gate`           | our gate's confirmed refusal          | yes        | its `required_rule`           | yes            |
+ * | `gate` (containment) | command left the workspace        | **no**     | none — no rule grants this    | yes            |
+ * | `agy_engine`     | agy's own permission engine refused   | no         | none — outside our policy     | **no**         |
+ * | `sandbox`        | Class 2 signature match, sandboxed job | depends    | why the job was sandboxed: `permissions.sandboxed` (retry without it), `research_readonly` (use general_worker), ceiling `sandboxed: true` (human) | yes |
+ * | `broker`         | missing `expected_artifacts` entry    | yes        | which artifact is missing     | yes            |
+ * | `broker`         | I4: gate never confirmed itself (`gate_confirmed === false`) | **no** | none — hooks.json never loaded, nothing to fix by rule | yes (and forces `outcome: 'process_error'` directly, not just `blocked` — see `decideOutcome`) |
+ * | `tool_error`     | a failing tool call, no signature     | no         | none — not a permission issue | **no**         |
+ *
+ * `agy_engine` and `tool_error` do not force `blocked` for the same reason:
+ * a non-gate `state: 'ERROR'` step is indistinguishable from an ordinary
+ * command failure by shape alone (finding 17), so treating them as blocks would
+ * report every failing test as a permission problem.
+ *
+ * The two `broker` rows are deliberately different shapes (`blockerFromMissingArtifact`
+ * is actionable, `blockerFromGateMissing` is not) — `source` alone does not
+ * imply a fixed `actionable`/`remedy`; read the specific constructor.
+ */
+/** Human label per source, used by both the warning lines and the headline. */
+const LABEL = {
+    policy_ceiling: 'ceiling rejection',
+    gate: 'gate denial',
+    agy_engine: 'agy-engine refusal',
+    sandbox: 'sandbox block',
+    broker: 'broker check',
+    tool_error: 'tool error',
+};
+/**
+ * Whether a non-gate refusal came from agy's own permission engine.
+ *
+ * Substring match against measured wording, the same technique `detectClass2`
+ * uses on environment blocks and for the same reason: agy emits no structured
+ * field saying who refused.
+ */
+export function isAgyEngineRefusal(message) {
+    return AGY_ENGINE_REFUSAL_SIGNATURES.some((sig) => message.includes(sig));
+}
+function asDetail(value) {
+    return value;
+}
+/**
+ * A Class 1 event → the blocker it actually is.
+ *
+ * Three outcomes, because three different next actions: our gate refused
+ * (fixable with a rule), agy's own engine refused (nothing of ours applies), or
+ * a command simply failed (not a permission matter at all).
+ */
+export function blockerFromDenial(d) {
+    const base = { tool: d.tool, command: d.command, detail: asDetail(d) };
+    if (d.source === 'gate') {
+        if (d.policy === 'containment') {
+            return {
+                ...base,
+                source: 'gate',
+                actionable: false,
+                remedy: null,
+                blocks_outcome: true,
+                message: `our gate refused this because it wrote outside the workspace; containment is checked before any rule, so no permissions.allow entry can grant it — change the command or the workspace. ${d.message}`,
+            };
+        }
+        if (d.policy === 'unsupported') {
+            // classifyToolCall (src/policy/tools.ts) marks this tool unconditionally —
+            // a subagent tool (M2) or one outside the 7-tool + manage_task table —
+            // before any rule list is even consulted, so no `permissions.allow`
+            // entry changes the outcome. required_rule is always null here (gate.ts).
+            return {
+                ...base,
+                source: 'gate',
+                actionable: false,
+                remedy: null,
+                blocks_outcome: true,
+                message: `our gate refused this because the tool itself is not one permissions.allow can grant (unsupported, checked before any rule list). ${d.message}`,
+            };
+        }
+        return {
+            ...base,
+            source: 'gate',
+            actionable: true,
+            remedy: d.required_rule,
+            blocks_outcome: true,
+            message: d.required_rule
+                ? `our permission gate refused this; nothing in the job's effective allow list covers it. Rule that would: ${d.required_rule}. If agy_capabilities shows the ceiling already covers it, retry without permissions.allow (allow only narrows); otherwise a human must add it to the ceiling's allow (or, for a rule the profile denies, exceptions). ${d.message}`
+                : `our permission gate refused this. ${d.message}`,
+        };
+    }
+    if (isAgyEngineRefusal(d.message)) {
+        return {
+            ...base,
+            source: 'agy_engine',
+            actionable: false,
+            remedy: null,
+            blocks_outcome: false,
+            message: `agy's own permission engine refused this. Since 0.2.0 that engine is disabled for our jobs (--dangerously-skip-permissions, measured on agy 1.1.24, M3), so this should not occur on a current job — if it does, the flag or the hook wiring regressed; report it. Seen on archived v1 results this is expected. No permissions.allow rule will help, and we cannot confirm it as a block either. ${d.message}`,
+        };
+    }
+    return {
+        ...base,
+        source: 'tool_error',
+        actionable: false,
+        remedy: null,
+        blocks_outcome: false,
+        message: `the tool call failed with no refusal signature we recognize, so this is not a permission problem we can confirm. ${d.message}`,
+    };
+}
+/** A Class 2 signature match. Recovery depends on whether and why the job ran sandboxed. */
+export function blockerFromEnvironmentBlock(b, policy) {
+    const base = {
+        source: 'sandbox',
+        blocks_outcome: true,
+        tool: b.tool,
+        command: b.command,
+        detail: asDetail(b),
+    };
+    // `verify.ts` never calls this for a job that ran with `bypass_sandbox:
+    // true` — without a sandbox the same signature is an ordinary command
+    // failure and goes to `warnings` instead. So every blocker built here comes
+    // from a job that really was sandboxed, and the only question is why.
+    // Job ran sandboxed. Identify which sandbox and why: request, ceiling, or profile.
+    if (policy?.sandbox === 'seatbelt') {
+        const source = policy.sandbox_source;
+        return {
+            ...base,
+            actionable: source === 'request',
+            remedy: source === 'request'
+                ? 'retry without permissions.sandbox, or add the directory to write_roots in the project ceiling if the write is legitimate'
+                : 'a human must add the directory to write_roots in the project ceiling (~/.agy-worker/projects/<hash>/policy.json), or set sandbox to "none" there',
+            message: `our seatbelt profile refused a write outside write_roots (signature "${b.signature}"; sandbox: seatbelt set by ${source}): ${b.excerpt}`,
+        };
+    }
+    const reason = policy?.sandbox_forced_by ??
+        (policy?.profile === 'research_readonly' ? 'profile' : null);
+    const additionalDirsGuidance = 'add the path to read_roots in the project ceiling (~/.agy-worker/projects/<hash>/policy.json) if it is a blocked read/exec of a toolchain outside the workspace.';
+    if (reason === 'request') {
+        return {
+            ...base,
+            actionable: true,
+            remedy: `retry without permissions.sandboxed; ${additionalDirsGuidance}`,
+            message: `agy's sandbox blocked this silently (signature "${b.signature}") because permissions.sandboxed was set for this job: ${b.excerpt}`,
+        };
+    }
+    if (reason === 'profile') {
+        return {
+            ...base,
+            actionable: true,
+            remedy: `start the job with profile "general_worker" if the task needs to write; ${additionalDirsGuidance}`,
+            message: `agy's sandbox blocked this silently (signature "${b.signature}") because profile "${policy?.profile ?? 'research_readonly'}" is always sandboxed: ${b.excerpt}`,
+        };
+    }
+    // reason === 'ceiling' or generic/unknown sandboxed (e.g. policy not provided)
+    const isCeiling = reason === 'ceiling';
+    return {
+        ...base,
+        actionable: false,
+        remedy: `a human must set "sandbox": "none" (or "seatbelt") in the project ceiling (~/.agy-worker/projects/<hash>/policy.json); ${additionalDirsGuidance}`,
+        message: isCeiling
+            ? `agy's sandbox blocked this silently (signature "${b.signature}") because the project ceiling has sandbox: agy: ${b.excerpt}`
+            : `agy's sandbox blocked this silently — signature "${b.signature}": ${b.excerpt}`,
+    };
+}
+/**
+ * I4: the runner's own gate watchdog
+ * killed the job because `jobs/<id>/gate-log.jsonl` never received a line
+ * within 3s of the first tool step — our PreToolUse hook never actually ran,
+ * so nothing before the kill was policy-checked at all. Never actionable — no
+ * `permissions.allow` entry fixes a hook that never loaded — and
+ * `decideOutcome` forces `outcome: 'process_error'` for this directly, not
+ * merely `blocked`, since `blocked` would imply the gate ran and refused.
+ */
+export function blockerFromGateMissing() {
+    return {
+        source: 'broker',
+        actionable: false,
+        remedy: null,
+        blocks_outcome: true,
+        tool: null,
+        command: null,
+        message: 'gate hook never fired; hooks.json was not loaded',
+    };
+}
+/** A broker-side check that failed. Today that is only a missing expected artifact. */
+export function blockerFromMissingArtifact(a) {
+    return {
+        source: 'broker',
+        actionable: true,
+        remedy: `have the job create ${a.path}, or drop it from expected_artifacts`,
+        blocks_outcome: true,
+        tool: null,
+        command: null,
+        message: `expected artifact missing: ${a.path} (${a.absolute})`,
+        detail: asDetail(a),
+    };
+}
+/**
+ * Build blockers from gate-log entries.
+ *
+ * When an entry carries `abort_reason: 'max_denials'`, emit an extra blocker
+ * reporting that the job was aborted after reaching the denial limit.
+ */
+export function blockersFromGateLog(log) {
+    let entries;
+    if (typeof log === 'string') {
+        entries = [];
+        for (const line of log.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed && typeof parsed === 'object') {
+                    entries.push(parsed);
+                }
+            }
+            catch {
+                // tolerate malformed lines
+            }
+        }
+    }
+    else {
+        entries = [...log];
+    }
+    const maxDenialEntry = entries.find((e) => e.abort_reason === 'max_denials');
+    if (!maxDenialEntry)
+        return [];
+    const denialCount = entries.filter((e) => e.decision === 'deny').length;
+    return [
+        {
+            source: 'gate',
+            actionable: true,
+            remedy: 'raise max_denials or fix the prompt so the job stops retrying denied actions',
+            blocks_outcome: true,
+            tool: null,
+            command: null,
+            message: `job aborted after ${denialCount} gate denials (max_denials)`,
+            detail: asDetail(maxDenialEntry),
+        },
+    ];
+}
+/**
+ * The "no project ceiling" line for a finished job, or null. Said only when a
+ * gate blocker's remedy is a rule string — exactly what a ceiling `allow` /
+ * `exceptions` entry would open — and the policy recorded that no ceiling
+ * file existed. A foreign hook's denial (no rule), containment, unsupported
+ * tools and sandbox blocks are not the ceiling's business, so they stay quiet.
+ * Legacy job files without `ceiling_present` never trigger it.
+ */
+export function ceilingAbsenceWarning(policy, blockers) {
+    if (!policy || policy.ceiling_present !== false)
+        return null;
+    const opensWithRule = blockers.some((b) => b.source === 'gate' && b.actionable && typeof b.remedy === 'string' && /^\w+\(/.test(b.remedy));
+    return opensWithRule ? ceilingAbsenceHint(policy.ceiling_path ?? null) : null;
+}
+/**
+ * Pre-flight blockers from a resolved policy: every `permissions.allow` entry
+ * the profile ceiling refused, every `permissions.read_roots` entry the
+ * human ceiling refused, plus the collapse case.
+ *
+ * `blocks_outcome` is false throughout — there is no job yet, so there is no
+ * outcome to block; these never reach `verification`.
+ */
+export function policyCeilingBlockers(policy) {
+    const blockers = policy.rejected_allow.map((rule) => ({
+        source: 'policy_ceiling',
+        actionable: true,
+        remedy: `drop ${rule} from permissions.allow, or start on a profile whose ceiling covers it`,
+        blocks_outcome: false,
+        tool: null,
+        command: null,
+        message: `permissions.allow entry ${rule} is outside the ${policy.profile} ceiling and was dropped; clients can only narrow a profile, never widen it`,
+        detail: { rule, profile: policy.profile },
+    }));
+    for (const dir of policy.rejected_read_roots) {
+        blockers.push({
+            source: 'policy_ceiling',
+            actionable: true,
+            remedy: `add a glob covering ${dir} to the project ceiling's read_roots, in ~/.agy-worker/projects/<hash>/policy.json — or drop it from permissions.read_roots`,
+            blocks_outcome: false,
+            tool: null,
+            command: null,
+            message: `permissions.read_roots entry ${dir} matched no glob in the project ceiling's read_roots, so it was dropped`,
+            detail: { dir, profile: policy.profile },
+        });
+    }
+    // The trap this exists for: `allow` is the *intersection* of the request with
+    // the ceiling, so a request that the ceiling refuses wholesale leaves `allow`
+    // empty — taking the profile's own defaults (read/write, git, pytest …) with
+    // it. Measured: a request of three build commands collapsed a general_worker
+    // job's allow list to [] and nothing in the reply said so.
+    if (policy.allow.length === 0) {
+        blockers.push({
+            source: 'policy_ceiling',
+            actionable: true,
+            remedy: 'start again with no permissions.allow at all, which restores the full profile ceiling',
+            blocks_outcome: false,
+            tool: null,
+            command: null,
+            message: `the effective allow list is empty: allow is intersected with the ${policy.profile} ceiling, so a fully rejected request also drops the profile's own default allowances. Nothing is explicitly allowed on this job.`,
+            detail: { profile: policy.profile, rejected_allow: policy.rejected_allow },
+        });
+    }
+    return blockers;
+}
+/**
+ * One warning line per blocker. The only renderer — a caller must never have to
+ * infer "can I fix this" from prose wording.
+ */
+export function renderBlocker(b) {
+    const where = b.tool ? ` [${b.tool}${b.command ? `: ${b.command}` : ''}]` : '';
+    const tail = b.actionable
+        ? ` — remedy: ${b.remedy ?? 'see message'}`
+        : ' — not actionable: no permissions.allow rule will change this.';
+    return `${LABEL[b.source]}${where}: ${b.message}${tail}`;
+}
+export function renderBlockers(blockers) {
+    return blockers.map(renderBlocker);
+}
+/**
+ * `1 gate denial (actionable), 1 sandbox block` — grouped by source, in first
+ * appearance order, so a headline says who refused without listing everything.
+ */
+export function summarizeBlockers(blockers) {
+    const order = [];
+    const groups = new Map();
+    for (const b of blockers) {
+        let g = groups.get(b.source);
+        if (!g) {
+            g = { count: 0, actionable: 0 };
+            groups.set(b.source, g);
+            order.push(b.source);
+        }
+        g.count++;
+        if (b.actionable)
+            g.actionable++;
+    }
+    return order
+        .map((source) => {
+        const g = groups.get(source);
+        const label = `${g.count} ${LABEL[source]}${g.count === 1 ? '' : 's'}`;
+        return g.actionable > 0 ? `${label} (actionable)` : label;
+    })
+        .join(', ');
+}
+export function countActionable(blockers) {
+    return blockers.filter((b) => b.actionable).length;
+}
+/** The single predicate `outcome` is decided by. */
+export function hasOutcomeBlocker(blockers) {
+    return blockers.some((b) => b.blocks_outcome);
+}
+/**
+ * Describe a resolved policy in the same vocabulary a finished job is judged
+ * in, for both the `dry_run` and the real `agy_start` reply.
+ *
+ * Built in one place so the two replies cannot drift: before 0.1.1 the real
+ * reply said nothing at all about permissions, and a caller whose
+ * `permissions.allow` had been rejected wholesale had no way to notice.
+ */
+export function describePolicy(policy) {
+    const blockers = policyCeilingBlockers(policy);
+    return {
+        policy_summary: {
+            profile: policy.profile,
+            allow_count: policy.allow.length,
+            bypass_sandbox: policy.bypass_sandbox,
+            sandbox_forced_by: policy.sandbox_forced_by,
+            sandbox: policy.sandbox,
+            sandbox_source: policy.sandbox_source,
+            add_dirs: policy.add_dirs,
+            add_dirs_source: policy.add_dirs_source,
+        },
+        blockers,
+        warnings: [...renderBlockers(blockers), ...(policy.warnings ?? [])],
+    };
+}
+//# sourceMappingURL=blockers.js.map

package/dist/broker/blockers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockers.js","sourceRoot":"","sources":["../../src/broker/blockers.ts"],"names":[],"mappings":"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"}

package/dist/broker/outcome.d.ts

@@ -0,0 +1,85 @@
+import type { AgentStatus, ContractStatus, Lifecycle, Outcome, Verification } from '../contract/types.js';
+/**
+ * Decide `outcome` and `headline` — the broker's verdict, kept strictly separate
+ * from agy's self-report.
+ *
+ * ⚠ Neither `exit_code === 0` nor `status === 'SUCCESS'` may be treated as
+ * success on its own. Measured: a hook denial and a sandbox network block both
+ * produce exit 0 and SUCCESS. `verified_success` requires that nothing
+ * was blocked *and* every expected artifact exists.
+ */
+export interface OutcomeInput {
+    lifecycle: Lifecycle;
+    exitCode: number | null;
+    /** agy's own claim. An input, never the decision. */
+    agentStatus: AgentStatus;
+    verification: Verification;
+    /** Set when the deadline fired. */
+    timedOut: boolean;
+    /** Set when `agy_cancel` killed it. */
+    canceled: boolean;
+    /**
+     * I4: `state.json.gate_confirmed
+     * === false` — the runner's own watchdog killed the job because
+     * `gate-log.jsonl` never received a line within 3s of the first tool step, so
+     * `hooks.json` never actually loaded and nothing before the kill was
+     * policy-checked at all. Forces `process_error`, never `blocked`: a
+     * `blocked` verdict implies our gate ran and refused something, which is
+     * exactly what did not happen here.
+     */
+    gateMissing: boolean;
+    /** Set when the runner vanished without writing `exit_code`. */
+    runnerLost: boolean;
+    /** Set when the recorded pid now belongs to a different process. */
+    pidReused: boolean;
+    /** Whether the caller asked for anything verifiable at all. */
+    hadExpectations: boolean;
+}
+export interface OutcomeDecision {
+    outcome: Outcome;
+    contract_status: ContractStatus;
+    /** One sentence. The first thing a calling agent reads. */
+    headline: string;
+    /** Reasons `verified_success` was withheld, in caller-facing wording. */
+    warnings: string[];
+}
+/**
+ * Fixed precedence, most certain fact first:
+ *
+ * 1. `canceled` — an explicit `agy_cancel` always wins, even over a deadline
+ *    that also happened to pass.
+ * 2. `timedOut` — the broker's own deadline enforcement fired.
+ * 3. `gateMissing` — our own watchdog killed the job because the gate never
+ *    confirmed itself (I4); nothing before that point was policy-checked, so
+ *    this outranks any verdict `verification.blockers` might otherwise imply.
+ * 4. `runnerLost` — the runner vanished without a trace; nothing below this
+ *    point can be trusted, because there was nothing to observe it.
+ * 5. `pidReused` — the recorded pid is alive but is provably not our process.
+ * 6. Otherwise: agy actually ran to some conclusion. Judge it from the exit
+ *    code and agy's own status first.
+ * 7. `hasOutcomeBlocker` — a confirmed refusal (gate, sandbox, missing
+ *    artifact) is `blocked`. Blockers outrank `verify` here on purpose:
+ *    "who refused" is a different
+ *    question from "did the check pass", and a job that was denied something
+ *    is `blocked` even if its `verify_command` also happened to fail.
+ * 8. `verify` — PR6. A configured `verify_command` that exited non-zero or hit
+ *    its own `verify_timeout_ms` is a job **failure**, never a `Blocker` (that
+ *    vocabulary means "who refused", and nothing refused here) — so this reads
+ *    `verification.verify` directly rather than going through
+ *    `hasOutcomeBlocker`.
+ * 9. Otherwise `verified_success` — either because `expected_artifacts`/
+ *    `json_schema` were requested and all satisfied, or because a configured
+ *    `verify_command` already passed (having survived step 8): a passing
+ *    check counts as "actually verified" on its own, even with no
+ *    `expected_artifacts` at all. With neither, `success_unverified`.
+ */
+export declare function decideOutcome(input: OutcomeInput): OutcomeDecision;
+/** True when every check that could run did run and did pass. */
+export declare function isVerifiedSuccess(input: OutcomeInput): boolean;
+/**
+ * One sentence that, together with the log tail, is enough to choose the next
+ * action. It states what the broker concluded and why — never a
+ * paraphrase of agy's own response text.
+ */
+export declare function buildHeadline(outcome: Outcome, input: OutcomeInput): string;
+//# sourceMappingURL=outcome.d.ts.map

package/dist/broker/outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../src/broker/outcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,SAAS,EACT,OAAO,EACP,YAAY,EACb,MAAM,sBAAsB,CAAA;AAG7B;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,qDAAqD;IACrD,WAAW,EAAE,WAAW,CAAA;IACxB,YAAY,EAAE,YAAY,CAAA;IAC1B,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAA;IACjB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;OAQG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAA;IAClB,+DAA+D;IAC/D,eAAe,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,cAAc,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CASlE;AAkCD,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAgD3E"}

package/dist/broker/outcome.js

@@ -0,0 +1,147 @@
+import { hasOutcomeBlocker, summarizeBlockers } from './blockers.js';
+/**
+ * Fixed precedence, most certain fact first:
+ *
+ * 1. `canceled` — an explicit `agy_cancel` always wins, even over a deadline
+ *    that also happened to pass.
+ * 2. `timedOut` — the broker's own deadline enforcement fired.
+ * 3. `gateMissing` — our own watchdog killed the job because the gate never
+ *    confirmed itself (I4); nothing before that point was policy-checked, so
+ *    this outranks any verdict `verification.blockers` might otherwise imply.
+ * 4. `runnerLost` — the runner vanished without a trace; nothing below this
+ *    point can be trusted, because there was nothing to observe it.
+ * 5. `pidReused` — the recorded pid is alive but is provably not our process.
+ * 6. Otherwise: agy actually ran to some conclusion. Judge it from the exit
+ *    code and agy's own status first.
+ * 7. `hasOutcomeBlocker` — a confirmed refusal (gate, sandbox, missing
+ *    artifact) is `blocked`. Blockers outrank `verify` here on purpose:
+ *    "who refused" is a different
+ *    question from "did the check pass", and a job that was denied something
+ *    is `blocked` even if its `verify_command` also happened to fail.
+ * 8. `verify` — PR6. A configured `verify_command` that exited non-zero or hit
+ *    its own `verify_timeout_ms` is a job **failure**, never a `Blocker` (that
+ *    vocabulary means "who refused", and nothing refused here) — so this reads
+ *    `verification.verify` directly rather than going through
+ *    `hasOutcomeBlocker`.
+ * 9. Otherwise `verified_success` — either because `expected_artifacts`/
+ *    `json_schema` were requested and all satisfied, or because a configured
+ *    `verify_command` already passed (having survived step 8): a passing
+ *    check counts as "actually verified" on its own, even with no
+ *    `expected_artifacts` at all. With neither, `success_unverified`.
+ */
+export function decideOutcome(input) {
+    const outcome = computeOutcome(input);
+    const headline = buildHeadline(outcome, input);
+    return {
+        outcome,
+        contract_status: input.verification.contract_status,
+        headline,
+        warnings: input.verification.warnings,
+    };
+}
+function computeOutcome(input) {
+    if (input.canceled)
+        return 'canceled';
+    if (input.timedOut)
+        return 'timed_out';
+    if (input.gateMissing)
+        return 'process_error';
+    if (input.runnerLost)
+        return 'process_error';
+    if (input.pidReused)
+        return 'orphaned';
+    const exitFailed = input.exitCode !== null && input.exitCode !== 0;
+    const agentFailed = input.agentStatus === 'ERROR';
+    if (exitFailed || agentFailed)
+        return 'failed';
+    // One predicate, defined once in `blockers.ts`. A gate denial, a Class 2
+    // sandbox block and a missing expected artifact all carry
+    // `blocks_outcome: true`; an agy-engine refusal and a plain tool error do
+    // not, exactly as before — but the rule now lives in one place instead of
+    // three special cases here.
+    if (hasOutcomeBlocker(input.verification.blockers))
+        return 'blocked';
+    // PR6: a configured `verify_command` that failed or timed out is a job
+    // failure, checked after blockers (a denial wins) and before the
+    // expected_artifacts / hadExpectations logic below.
+    const verify = input.verification.verify;
+    if (verify && (verify.exit_code !== 0 || verify.timed_out))
+        return 'failed';
+    // Reaching here with `verify` non-null means it passed (exit 0, not timed
+    // out) — that alone is "a check actually passed", so it counts toward
+    // verified_success even when nothing else (expected_artifacts/json_schema)
+    // was requested.
+    if (verify || input.hadExpectations)
+        return 'verified_success';
+    return 'success_unverified';
+}
+/** True when every check that could run did run and did pass. */
+export function isVerifiedSuccess(input) {
+    return computeOutcome(input) === 'verified_success';
+}
+/**
+ * One sentence that, together with the log tail, is enough to choose the next
+ * action. It states what the broker concluded and why — never a
+ * paraphrase of agy's own response text.
+ */
+export function buildHeadline(outcome, input) {
+    const blockers = input.verification.blockers;
+    const totalArtifacts = input.verification.expected_artifacts.length;
+    // Blockers that did not force the verdict are still worth a fragment: an
+    // agy-engine refusal is invisible everywhere else in the packet, and staying
+    // silent about it in a success headline is how a half-done job reads as done.
+    // It is a fragment, never the verdict.
+    const nonBlocking = blockers.filter((b) => !b.blocks_outcome);
+    const nonBlockingSuffix = nonBlocking.length > 0 ? ` (non-blocking: ${summarizeBlockers(nonBlocking)})` : '';
+    let headline;
+    switch (outcome) {
+        case 'verified_success':
+            headline = `verified success: exit 0, agy reported ${input.agentStatus}, ${totalArtifacts} expected artifact(s) confirmed, no permission or environment blocks.${nonBlockingSuffix}`;
+            break;
+        case 'success_unverified':
+            headline = `agy exited 0 and reported ${input.agentStatus}, but nothing verifiable (expected_artifacts, json_schema, or a passing verify_command) was requested — cannot confirm the work actually happened.${nonBlockingSuffix}`;
+            break;
+        case 'blocked': {
+            const blocking = blockers.filter((b) => b.blocks_outcome);
+            headline = `blocked despite exit ${input.exitCode ?? '?'} / status ${input.agentStatus}: ${summarizeBlockers(blocking)}.${nonBlockingSuffix}`;
+            break;
+        }
+        case 'failed':
+            headline =
+                input.agentStatus === 'ERROR'
+                    ? `failed: agy reported ERROR (exit ${input.exitCode ?? '?'}).`
+                    : `failed: agy exited ${input.exitCode ?? '?'}.`;
+            break;
+        case 'timed_out':
+            headline = 'timed out: the job exceeded its deadline and the process group was killed.';
+            break;
+        case 'canceled':
+            headline = 'canceled: agy_cancel stopped this job.';
+            break;
+        case 'process_error':
+            headline = input.gateMissing
+                ? 'process error: gate hook never fired; hooks.json was not loaded — the job was killed before any of its tool calls could be trusted.'
+                : 'process error: the runner vanished without recording an exit code.';
+            break;
+        case 'orphaned':
+            headline = 'orphaned: the recorded pid is alive but belongs to a different process (pid reuse); the job was abandoned.';
+            break;
+    }
+    return headline + verifyFragment(input);
+}
+/**
+ * ` verify: exit <code> (<duration>s).` / ` verify: timed out after <s>s.`,
+ * appended whenever `verify_command` ran (PR6 §6.3) — regardless of `outcome`,
+ * since a caller reading any headline should be able to see the check ran and
+ * how it went, not just when it happened to be the deciding fact.
+ */
+function verifyFragment(input) {
+    const v = input.verification.verify;
+    if (!v)
+        return '';
+    const seconds = (v.duration_ms / 1000).toFixed(1);
+    return v.timed_out
+        ? ` verify: timed out after ${seconds}s.`
+        : ` verify: exit ${v.exit_code ?? '?'} (${seconds}s).`;
+}
+//# sourceMappingURL=outcome.js.map

package/dist/broker/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../src/broker/outcome.ts"],"names":[],"mappings":"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"}