agy-worker-mcp 0.3.1

package/dist/broker/result.js

@@ -0,0 +1,234 @@
+import { BROKER_RESULT_VERSION } from '../contract/types.js';
+import { ValidationError } from '../contract/errors.js';
+import { readJsonIfExists, writeJsonAtomic } from '../contract/paths.js';
+import { normalizeEvent, tailSummary } from '../events/normalize.js';
+import { lastResult } from '../events/parse.js';
+import { blockerFromDenial, blockerFromEnvironmentBlock, blockerFromGateMissing, blockerFromMissingArtifact, countActionable, renderBlocker, } from './blockers.js';
+import { decideOutcome } from './outcome.js';
+import { verifyJob } from './verify.js';
+const DEFAULT_LOG_TAIL_LINES = 40;
+export function buildBrokerResult(store, input) {
+    const verification = verifyJob(store, {
+        job: input.job,
+        events: input.events,
+        expectedArtifacts: input.expectedArtifacts,
+        cwd: input.job.cwd,
+        // Where a captured --json-schema payload actually lands on the wire is
+        // unmeasured (see verify.ts checkContract) — nothing to pass through yet.
+        structuredOutput: undefined,
+        jsonSchemaPath: input.jsonSchemaPath,
+    });
+    if (input.idleClosedAfterMs !== null) {
+        verification.warnings.push(`session closed by idle_timeout_ms (${input.idleClosedAfterMs} ms) with no agy_send after the last turn — resume with agy_start({ session_id })`);
+    }
+    // I4: fold the gate watchdog's own verdict into the same `blockers` list
+    // everything else uses, so `agy_result`'s verification section carries this
+    // exactly like any other blocker instead of a special-cased field.
+    if (input.gateConfirmed === false) {
+        const gateBlocker = blockerFromGateMissing();
+        verification.blockers.push(gateBlocker);
+        verification.warnings.push(renderBlocker(gateBlocker));
+    }
+    const agentReport = buildAgentReport(input.events);
+    const hadExpectations = input.expectedArtifacts.length > 0 || input.jsonSchemaPath !== null;
+    const decision = decideOutcome({
+        lifecycle: input.job.lifecycle,
+        exitCode: input.exitCode,
+        agentStatus: agentReport.status,
+        verification,
+        timedOut: input.timedOut,
+        canceled: input.canceled,
+        gateMissing: input.gateConfirmed === false,
+        runnerLost: input.runnerLost,
+        pidReused: input.pidReused,
+        hadExpectations,
+    });
+    const counts = countEvents(input.events, input.malformedLines);
+    const normalized = input.events
+        .map((e) => normalizeEvent(e))
+        .filter((n) => n !== null);
+    const logTail = tailSummary(normalized, DEFAULT_LOG_TAIL_LINES);
+    const finishedAt = input.finishedAt ?? input.now;
+    const durationMs = input.job.started_at !== null ? Math.max(0, finishedAt - input.job.started_at) : null;
+    const brokerSummary = {
+        headline: decision.headline,
+        outcome: decision.outcome,
+        exit_code: input.exitCode,
+        duration_ms: durationMs,
+        counts,
+        log_tail: logTail,
+    };
+    return {
+        schema_version: BROKER_RESULT_VERSION,
+        job_id: input.job.job_id,
+        session_id: input.job.session_id,
+        conversation_id: agentReport.conversation_id,
+        lifecycle: 'finished',
+        cwd: input.job.cwd,
+        profile: input.job.profile,
+        session_mode: input.job.session_mode,
+        created_at: input.job.created_at,
+        started_at: input.job.started_at,
+        finished_at: finishedAt,
+        agent_report: agentReport,
+        broker_summary: brokerSummary,
+        verification,
+        agent_status: agentReport.status,
+        contract_status: decision.contract_status,
+        structured_output: null,
+        finalized_at: input.now,
+    };
+}
+function countEvents(events, malformedLines) {
+    let steps = 0;
+    let toolCalls = 0;
+    let toolErrors = 0;
+    let turns = 0;
+    for (const e of events) {
+        if (e.event === 'result') {
+            turns++;
+            continue;
+        }
+        if (e.event !== 'step_update')
+            continue;
+        steps++;
+        const su = e.step_update;
+        if (su.step_type !== 'tool')
+            continue;
+        if (su.state === 'DONE')
+            toolCalls++;
+        if (su.state === 'ERROR')
+            toolErrors++;
+    }
+    return {
+        events: events.length,
+        steps,
+        tool_calls: toolCalls,
+        tool_errors: toolErrors,
+        turns,
+        malformed_lines: malformedLines,
+    };
+}
+/** Extract agy's unverified self-report. Quarantined from `broker_summary` on purpose. */
+export function buildAgentReport(events) {
+    const r = lastResult(events);
+    if (!r) {
+        return { status: 'unknown', response: null, error: null, num_turns: null, usage: null, conversation_id: null };
+    }
+    const status = r.result.status === 'SUCCESS' || r.result.status === 'ERROR' ? r.result.status : 'unknown';
+    return {
+        status,
+        response: r.result.response ?? null,
+        error: r.result.error ?? null,
+        num_turns: r.result.num_turns ?? null,
+        usage: r.result.usage ?? null,
+        conversation_id: r.result.conversation_id ?? null,
+    };
+}
+/** Atomic write, so a concurrent reader never sees a half-written result. */
+export function writeBrokerResult(paths, result) {
+    writeJsonAtomic(paths.brokerResult, result);
+}
+/**
+ * Null when the job has not been finalized yet.
+ *
+ * A `broker-result.json` written by an older server is migrated in memory
+ * (see {@link migrateBrokerResult}) rather than crashing a tool call — job
+ * directories outlive an upgrade, and `agy_result` on yesterday's job must keep
+ * working. A version we do not know how to read is refused loudly instead of
+ * being handed on half-typed.
+ *
+ * @throws {import('../contract/errors.js').ValidationError} on an unknown version.
+ */
+export function loadBrokerResult(paths) {
+    const raw = readJsonIfExists(paths.brokerResult);
+    if (raw === null)
+        return null;
+    return migrateBrokerResult(raw, paths.brokerResult);
+}
+/**
+ * Bring a stored result up to {@link BROKER_RESULT_VERSION}.
+ *
+ * Version 1 kept `verification.permission_denials` and
+ * `verification.environment_blocks`; version 2 collapsed those into the single
+ * `verification.blockers`; version 3 adds `verification.verify` (PR6,
+ * `verify_command`) — always `null` on a migrated file, since no job written
+ * before 0.2.0 ever ran a verify command. The version-1 migration runs the
+ * same constructors the live path uses, so an old job is judged by exactly
+ * today's rules — and nothing in the old records is dropped, since each one is
+ * carried in `Blocker.detail`.
+ */
+export function migrateBrokerResult(raw, path) {
+    const version = raw.schema_version;
+    if (version === BROKER_RESULT_VERSION)
+        return raw;
+    if (version !== 1 && version !== 2) {
+        throw new ValidationError({
+            field: `schema_version of ${path}`,
+            value: version,
+            expected: `a broker-result.json version this server can read (1, 2 or ${BROKER_RESULT_VERSION}) — this file was written by a newer server`,
+        });
+    }
+    let verification;
+    if (version === 1) {
+        const legacy = raw.verification;
+        const artifacts = legacy.expected_artifacts ?? [];
+        const blockers = [
+            ...(legacy.permission_denials ?? []).map(blockerFromDenial),
+            ...(legacy.environment_blocks ?? []).map((b) => blockerFromEnvironmentBlock(b)),
+            ...artifacts.filter((a) => !a.exists).map(blockerFromMissingArtifact),
+        ];
+        verification = {
+            blockers,
+            expected_artifacts: artifacts,
+            changed_files: legacy.changed_files ?? [],
+            warnings: legacy.warnings ?? [],
+            contract_status: legacy.contract_status,
+            checked_at: legacy.checked_at,
+            verify: null,
+        };
+    }
+    else {
+        // version === 2: everything but `verify` is already in today's shape.
+        verification = { ...raw.verification, verify: null };
+    }
+    return {
+        ...raw,
+        schema_version: BROKER_RESULT_VERSION,
+        verification,
+    };
+}
+/**
+ * Project the judgement packet `agy_wait` returns: counts, warnings, headline,
+ * and a short log tail. No lists, no raw response text — those live in
+ * `agy_result`.
+ */
+export function projectJudgementPacket(result, opts) {
+    const maxLines = opts?.maxLogTailLines;
+    const logTail = maxLines !== undefined && maxLines < result.broker_summary.log_tail.length
+        ? result.broker_summary.log_tail.slice(-maxLines)
+        : result.broker_summary.log_tail;
+    return {
+        job_id: result.job_id,
+        lifecycle: result.lifecycle,
+        outcome: result.broker_summary.outcome,
+        headline: result.broker_summary.headline,
+        exit_code: result.broker_summary.exit_code,
+        duration_ms: result.broker_summary.duration_ms,
+        agent_status: result.agent_status,
+        contract_status: result.contract_status,
+        counts: {
+            // Two numbers instead of four differently-defined ones: how much stood in
+            // the way, and how much of it the caller can act on. `headline` names the
+            // sources; `agy_result`'s `verification.blockers` has each one in full.
+            blockers: result.verification.blockers.length,
+            actionable: countActionable(result.verification.blockers),
+            tool_errors: result.broker_summary.counts.tool_errors,
+            turns: result.broker_summary.counts.turns,
+        },
+        warnings: result.verification.warnings,
+        log_tail: logTail,
+        cursor: opts?.cursor ?? 0,
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/broker/result.js.map

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

package/dist/broker/verify.d.ts

@@ -0,0 +1,52 @@
+import type { AgyEvent, ArtifactCheck, ContractStatus, EffectivePolicy, JobRow, Verification } from '../contract/types.js';
+import type { Store } from '../store/db.js';
+/**
+ * Independent checks the broker runs on its own, without asking agy anything.
+ *
+ * Verification scope: expected-artifact existence, `git status` changed files,
+ * and Class 1 / Class 2 denial aggregation. Running arbitrary commands here in
+ * the broker is deliberately out — that needs its own allowlist design; PR6's
+ * `verify_command` instead runs once, in the *runner*, before this ever sees
+ * the job. This module's only job re: that
+ * is `readVerifyResult` below, which reads back what the runner already wrote.
+ */
+export interface VerifyInput {
+    job: JobRow;
+    events: AgyEvent[];
+    expectedArtifacts: string[];
+    /** Canonical workspace. */
+    cwd: string;
+    /** Raw structured output, when `--json-schema` was requested. */
+    structuredOutput?: unknown;
+    jsonSchemaPath?: string | null;
+    policy?: EffectivePolicy | null;
+}
+export declare function verifyJob(store: Store, input: VerifyInput): Verification;
+/**
+ * Existence and size of each expected artifact.
+ *
+ * Paths are workspace-relative and containment-checked before use, so a job
+ * cannot claim success by writing outside its workspace. A path that escapes the
+ * workspace is treated as missing, not as an error — the caller asked for a
+ * verifiable fact, and "escaped the sandbox" is not a fact in its favour.
+ */
+export declare function checkExpectedArtifacts(cwd: string, expected: string[]): ArtifactCheck[];
+/**
+ * `git status --porcelain` inside the workspace, via an argv array (never a shell
+ * string). Empty when the workspace is not a git repo — that is not an error.
+ */
+export declare function changedFiles(cwd: string): string[];
+/**
+ * Whether the structured output honoured the requested schema. `not_required`
+ * when no schema was asked for; `violated` keeps the raw payload regardless, since
+ * a schema miss must never destroy the response.
+ *
+ * ⚠ agy's actual `--json-schema` failure signalling is unmeasured.
+ * This is a conservative, documented placeholder:
+ * presence of a non-null payload is treated as satisfying the schema; its
+ * absence when one was requested is `unknown` rather than a confident
+ * `violated`, since we have no measured evidence of what an actual schema
+ * failure looks like on the wire.
+ */
+export declare function checkContract(structuredOutput: unknown, jsonSchemaPath: string | null): ContractStatus;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/broker/verify.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EAEb,cAAc,EAEd,eAAe,EACf,MAAM,EACN,YAAY,EAGb,MAAM,sBAAsB,CAAA;AAG7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAW3C;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,QAAQ,EAAE,CAAA;IAClB,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;CAChC;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,CAmExE;AAgCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAevF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,cAAc,CAIhB"}

package/dist/broker/verify.js

@@ -0,0 +1,174 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { canonicalize, containedOrNull, jobPaths, readJsonIfExists } from '../contract/paths.js';
+import { scanDenials } from '../events/detect.js';
+import { now } from '../store/db.js';
+import { blockerFromDenial, blockerFromEnvironmentBlock, blockerFromMissingArtifact, blockersFromGateLog, ceilingAbsenceWarning, renderBlockers, } from './blockers.js';
+export function verifyJob(store, input) {
+    const paths = jobPaths(store.paths, input.job.job_id);
+    const policy = input.policy ??
+        readJsonIfExists(paths.policy) ??
+        readJsonIfExists(paths.effectiveConfig)?.policy ??
+        null;
+    const denials = scanDenials(input.events);
+    const artifacts = checkExpectedArtifacts(input.cwd, input.expectedArtifacts);
+    const changed = changedFiles(input.cwd);
+    const contractStatus = checkContract(input.structuredOutput, input.jsonSchemaPath ?? null);
+    const verify = readVerifyResult(store, input.job.job_id);
+    // One list, one vocabulary. Which of these force `outcome: 'blocked'` and
+    // which are only reported is decided in `blockers.ts` and nowhere else.
+    // A Class 2 signature only means "the sandbox refused" when the job actually
+    // ran sandboxed. With `bypass_sandbox: true` there is no sandbox to refuse
+    // anything, so the same text is an ordinary command failure (a real EACCES,
+    // a network that is really down) — reported as a warning, never a blocker,
+    // and never a reason to call the job `blocked`.
+    let gateLogBlockers = [];
+    if (existsSync(paths.gateLog)) {
+        try {
+            gateLogBlockers = blockersFromGateLog(readFileSync(paths.gateLog, 'utf8'));
+        }
+        catch {
+            // tolerate missing or unreadable gate log
+        }
+    }
+    // `sandbox` is the 0.3.0 field; a pre-0.3.0 policy file only has bypass_sandbox.
+    const ranUnsandboxed = policy ? (policy.sandbox ?? (policy.bypass_sandbox ? 'none' : 'agy')) === 'none' : false;
+    const blockers = [
+        ...denials.permission_denials.map(blockerFromDenial),
+        ...(ranUnsandboxed ? [] : denials.environment_blocks.map((b) => blockerFromEnvironmentBlock(b, policy))),
+        ...artifacts.filter((a) => !a.exists).map(blockerFromMissingArtifact),
+        ...gateLogBlockers,
+    ];
+    const warnings = renderBlockers(blockers);
+    // A gate refusal whose remedy is a rule string is exactly what a ceiling
+    // would open. Without a ceiling file the agent has no `agy_capabilities`
+    // entry to point at, so say it here, once, next to the blocker.
+    const ceilingHint = ceilingAbsenceWarning(policy, blockers);
+    if (ceilingHint)
+        warnings.push(ceilingHint);
+    if (ranUnsandboxed) {
+        for (const b of denials.environment_blocks) {
+            warnings.push(`${b.tool}${b.command ? ` (${b.command})` : ''} printed sandbox signature "${b.signature}", but this job ran with no OS sandbox (sandbox: none), so it is the command's own failure, not a sandbox block: ${b.excerpt}`);
+        }
+    }
+    if (contractStatus === 'violated') {
+        // Not a blocker: `checkContract` never returns 'violated' on measured
+        // evidence (see below), so there is nothing here we could claim to confirm.
+        warnings.push('structured output did not honour the requested --json-schema');
+    }
+    return {
+        blockers,
+        expected_artifacts: artifacts,
+        changed_files: changed,
+        warnings,
+        contract_status: contractStatus,
+        checked_at: now(),
+        verify,
+    };
+}
+/**
+ * `Verification.verify` (PR6 §6.3): `null` when `jobs/<id>/verify.json` was
+ * never written — no `verify_command` was requested, or the job's own
+ * deadline killed agy before the runner could get to it (`runner.ts` skips
+ * verify entirely when `timedOut === true`). Deliberately re-read from disk
+ * rather than threaded through as an extra `VerifyInput` field: `jobPaths` is
+ * already the one place that knows where the runner wrote it, and every
+ * caller of `verifyJob` already has a `Store` (and so a `ProjectPaths`) in
+ * hand.
+ */
+function readVerifyResult(store, jobId) {
+    const paths = jobPaths(store.paths, jobId);
+    const record = readJsonIfExists(paths.verifyJson);
+    if (!record)
+        return null;
+    return { ...record, output_tail: readOutputTail(paths.verifyLog) };
+}
+/** Last 2 KiB of `verify.log`, byte-accurate; `''` when the file is empty or missing. */
+const OUTPUT_TAIL_BYTES = 2048;
+function readOutputTail(logPath) {
+    try {
+        const buf = readFileSync(logPath);
+        if (buf.length <= OUTPUT_TAIL_BYTES)
+            return buf.toString('utf8');
+        return buf.subarray(buf.length - OUTPUT_TAIL_BYTES).toString('utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Existence and size of each expected artifact.
+ *
+ * Paths are workspace-relative and containment-checked before use, so a job
+ * cannot claim success by writing outside its workspace. A path that escapes the
+ * workspace is treated as missing, not as an error — the caller asked for a
+ * verifiable fact, and "escaped the sandbox" is not a fact in its favour.
+ */
+export function checkExpectedArtifacts(cwd, expected) {
+    const canonicalCwd = canonicalize(cwd);
+    return expected.map((rel) => {
+        const attempted = isAbsolute(rel) ? rel : join(canonicalCwd, rel);
+        const contained = containedOrNull(attempted, [canonicalCwd]);
+        if (contained === null) {
+            return { path: rel, absolute: canonicalize(attempted), exists: false, size: null };
+        }
+        try {
+            const st = statSync(contained);
+            return { path: rel, absolute: contained, exists: true, size: st.size };
+        }
+        catch {
+            return { path: rel, absolute: contained, exists: false, size: null };
+        }
+    });
+}
+/**
+ * `git status --porcelain` inside the workspace, via an argv array (never a shell
+ * string). Empty when the workspace is not a git repo — that is not an error.
+ */
+export function changedFiles(cwd) {
+    try {
+        // This call runs inside `finalizeCore`'s `BEGIN IMMEDIATE` transaction,
+        // so an unbounded `git status` — blocked on a network
+        // FS or an `index.lock` — would hold the SQLite write lock for as long as
+        // git hangs. Bounding it here is a minimal mitigation for finding 7;
+        // moving this work outside the transaction entirely is the fuller fix and
+        // is not done here.
+        const out = execFileSync('git', ['status', '--porcelain'], {
+            cwd: canonicalize(cwd),
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+            killSignal: 'SIGKILL',
+        });
+        return out
+            .split('\n')
+            .map((l) => l.trimEnd())
+            .filter((l) => l.length > 0);
+    }
+    catch {
+        // Not a git repo, git not installed, or the command failed. None of these
+        // are fatal to the job — they just mean nothing to report here.
+        return [];
+    }
+}
+/**
+ * Whether the structured output honoured the requested schema. `not_required`
+ * when no schema was asked for; `violated` keeps the raw payload regardless, since
+ * a schema miss must never destroy the response.
+ *
+ * ⚠ agy's actual `--json-schema` failure signalling is unmeasured.
+ * This is a conservative, documented placeholder:
+ * presence of a non-null payload is treated as satisfying the schema; its
+ * absence when one was requested is `unknown` rather than a confident
+ * `violated`, since we have no measured evidence of what an actual schema
+ * failure looks like on the wire.
+ */
+export function checkContract(structuredOutput, jsonSchemaPath) {
+    if (!jsonSchemaPath)
+        return 'not_required';
+    if (structuredOutput === undefined || structuredOutput === null)
+        return 'unknown';
+    return 'satisfied';
+}
+//# sourceMappingURL=verify.js.map

package/dist/broker/verify.js.map

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

package/dist/contract/errors.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Structured errors. READ-ONLY after Stage 1.
+ *
+ * Every error carries a machine-readable `detail` so the *calling agent* can
+ * repair itself without another round trip: which job holds the lock, which rule
+ * string to add, which enum values exist.
+ */
+import type { LockRequestScope, OnDenial, RuleVerb } from './types.js';
+export type ErrorCode = 'LOCK_CONFLICT' | 'POLICY_DENIED' | 'PATH_ESCAPE' | 'JOB_NOT_FOUND' | 'VALIDATION';
+/** Wire shape of any error surfaced through MCP. */
+export interface ErrorEnvelope<D = unknown> {
+    error: ErrorCode;
+    message: string;
+    detail: D;
+    /** Concrete next action for the caller. Always present. */
+    remedy: string;
+}
+/** Base for everything in this module. `instanceof` works across all subclasses. */
+export declare abstract class AgyWorkerError<D = unknown> extends Error {
+    abstract readonly code: ErrorCode;
+    readonly detail: D;
+    readonly remedy: string;
+    protected constructor(message: string, detail: D, remedy: string);
+    toJSON(): ErrorEnvelope<D>;
+}
+export declare function isAgyWorkerError(e: unknown): e is AgyWorkerError;
+/** Normalizes anything thrown into an envelope so a tool handler never leaks a stack. */
+export declare function toErrorEnvelope(e: unknown): ErrorEnvelope;
+export interface LockConflictDetail {
+    /** `running_limit` means the project-wide concurrency ceiling, not a row. */
+    scope: LockRequestScope;
+    /** Canonical cwd, session id, or `'*'` for the running limit. */
+    key: string;
+    /** Whether an existing holder blocked it, or the ceiling did. */
+    reason: 'held' | 'limit';
+    /** Job currently holding the lock. Null for `reason: 'limit'`. */
+    holder_job_id: string | null;
+    holder_pid: number | null;
+    holder_started_at: number | null;
+    acquired_at: number | null;
+    /** Every job counted against the ceiling, for `reason: 'limit'`. */
+    running_job_ids: string[];
+    limit: number | null;
+}
+/**
+ * Losing a lock race is an error, never a silent serialization.
+ * The caller decides whether to wait on the holder or pick a different cwd.
+ */
+export declare class LockConflictError extends AgyWorkerError<LockConflictDetail> {
+    readonly code: "LOCK_CONFLICT";
+    constructor(detail: LockConflictDetail, message?: string);
+}
+export interface PolicyDeniedDetail {
+    job_id: string | null;
+    profile: string;
+    tool: string;
+    command: string | null;
+    /**
+     * Rule string that would have permitted this, e.g. `command(python -m pytest)`.
+     * Paste it into the next `agy_start`'s `permissions.allow`.
+     */
+    required_rule: string | null;
+    /** The deny entry that matched, when the refusal came from a deny list. */
+    matched_rule: string | null;
+    /** Which stage of the decision order refused. */
+    policy: 'unsupported' | 'control' | 'containment' | 'deny_list' | 'profile_allowlist' | 'default';
+    /** True when no client request can lift it (hard deny / profile ceiling). */
+    immutable: boolean;
+    on_denial: OnDenial;
+}
+/** A policy refusal, whether reported by the gate or replayed by the broker. */
+export declare class PolicyDeniedError extends AgyWorkerError<PolicyDeniedDetail> {
+    readonly code: "POLICY_DENIED";
+    constructor(detail: PolicyDeniedDetail, message?: string);
+}
+export interface PathEscapeDetail {
+    /** What the caller supplied. */
+    input_path: string;
+    /** After realpath + `..` resolution. This is what actually escaped. */
+    resolved_path: string;
+    /** Whether read or write containment was violated. */
+    kind: 'read' | 'write';
+    /** Canonical roots that were allowed. */
+    roots: string[];
+    /** True when a symlink was what carried the path outside. */
+    via_symlink: boolean;
+}
+/** Containment failure. Checked *after* realpath, never before (see docs/permissions.md). */
+export declare class PathEscapeError extends AgyWorkerError<PathEscapeDetail> {
+    readonly code: "PATH_ESCAPE";
+    constructor(detail: PathEscapeDetail, message?: string);
+}
+export interface JobNotFoundDetail {
+    job_id: string;
+    /** A few recent job ids so the caller can spot a typo without another call. */
+    known_recent: string[];
+    project_root: string;
+}
+export declare class JobNotFoundError extends AgyWorkerError<JobNotFoundDetail> {
+    readonly code: "JOB_NOT_FOUND";
+    constructor(detail: JobNotFoundDetail, message?: string);
+}
+export interface ValidationDetail {
+    /** Dotted path of the offending input, e.g. `permissions.allow[0]`. */
+    field: string;
+    /** What arrived. Truncated by the thrower if large. */
+    value: unknown;
+    /** Human description of what was required. */
+    expected: string;
+    /** Complete enum when the field is an enum. Lets the caller self-correct. */
+    allowed?: string[];
+    /** Rule verbs, when the failure was an unparsable permission rule. */
+    allowed_verbs?: RuleVerb[];
+}
+export declare class ValidationError extends AgyWorkerError<ValidationDetail> {
+    readonly code: "VALIDATION";
+    constructor(detail: ValidationDetail, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/contract/errors.d.ts.map

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