@lannguyensi/harness 0.50.0 → 0.52.0

package/dist/policy-packs/builtin/understanding-before-execution/auto-approve.js

@@ -0,0 +1,361 @@
+// `auto_approve` pack-config parsing and shared conventions, split out
+// alongside lifecycle.ts (structural sibling of the former monolithic
+// understanding-before-execution-runtime.ts, agent-tasks 348a4d42).
+// Implements slice 1 of docs/decisions/2026-08-27-ug-auto-mode-approval.md
+// (agent-tasks 74b4b17d): the strict pack-config block that lets an
+// operator opt a permission mode into the hook-written signed
+// auto-marker path, plus the shared `approvedBy` / ledger-tag
+// conventions the hook and doctor consume so there is one authority
+// for the string shapes instead of each caller reimplementing them.
+//
+// This module owns no gate decision and no marker write: it only
+// parses the opt-in config (fail-closed: any malformed shape is
+// treated as "not opted in", never as a partial default) and builds /
+// parses the string conventions the ADR's "Audit and doctor" section
+// documents. The PreToolUse hook (auto-path condition checks) and
+// `harness doctor` (auto-approval listing) are the consumers; both
+// land in later slice-1 tasks and import from here.
+//
+// Slice 3 (agent-tasks 37ad0b05) adds `report_scan.max_wait`: the bound
+// of the child's transcript poll under `claude -p` ("Report capture
+// under `-p`" in the ADR). It lives in this block because it tunes the
+// same opt-in path, and it is parsed here rather than at the hook so
+// the lint-time schema and the runtime hook agree on one parser.
+import { InvalidDurationError, parseDurationSeconds } from "../../../policies/index.js";
+/**
+ * Prefix every auto-minted marker's `approvedBy` carries, distinguishing
+ * it from a human `harness approve understanding` marker (which carries
+ * the operator's own identity string, never this prefix).
+ */
+export const AUTO_APPROVED_BY_PREFIX = "auto-mode:";
+/** The harness identifier the Claude Code PreToolUse hook mints markers for. */
+export const CLAUDE_CODE_HARNESS = "claude-code";
+/**
+ * The harness identifier the Codex PreToolUse hook mints markers for
+ * (slice 2 of the ADR: same auto path, same fail-closed conditions, a
+ * distinct `approvedBy` segment so an audit can tell the two runtimes
+ * apart). Deliberately NOT re-exported through
+ * `understanding-before-execution/index.ts`: its only consumer is
+ * `src/cli/pack/hook-codex-pre-tool-use.ts`, and widening the runtime
+ * shim's pinned public surface (tests/policy-packs/ube-export-surface.test.ts)
+ * is a separate, conscious act.
+ */
+export const CODEX_HARNESS = "codex";
+/**
+ * Build the `approvedBy` value the hook writes into a signed auto-marker:
+ * `auto-mode:<harness>:<mode>`, for example `auto-mode:claude-code:bypassPermissions`
+ * or `auto-mode:codex:bypassPermissions` ("Audit and doctor" in the ADR).
+ * Neither `harness` nor `mode` is validated here; callers pass
+ * already-known-good values (one of the fixed harness constants above and
+ * a `when`-matched mode string).
+ */
+export function autoApprovedByFor(harness, mode) {
+    return `${AUTO_APPROVED_BY_PREFIX}${harness}:${mode}`;
+}
+/**
+ * Parse an `approvedBy` string back into its harness/mode pair. Returns
+ * `null` for anything that is not exactly `auto-mode:<harness>:<mode>`
+ * with both segments non-empty, including a human marker's `approvedBy`
+ * (which never carries this prefix) and a malformed or truncated auto
+ * value. A slice 3 delegation suffix (`;delegated:<parent-sid>`) is
+ * tolerated: it is stripped before parsing and otherwise ignored, per
+ * the ADR's "Audit and doctor" convention that the delegation binding
+ * packs into the same field without changing the harness/mode shape.
+ */
+export function parseAutoApprovedBy(approvedBy) {
+    if (typeof approvedBy !== "string")
+        return null;
+    if (!approvedBy.startsWith(AUTO_APPROVED_BY_PREFIX))
+        return null;
+    const withoutPrefix = approvedBy.slice(AUTO_APPROVED_BY_PREFIX.length);
+    const [withoutDelegation] = withoutPrefix.split(";delegated:");
+    const segments = (withoutDelegation ?? "").split(":");
+    if (segments.length !== 2)
+        return null;
+    const [harness, mode] = segments;
+    if (!harness || !mode)
+        return null;
+    return { harness, mode };
+}
+/**
+ * Build the audit-only ledger fact the ADR's "Audit and doctor" section
+ * names: `understanding-auto-approved:<sid>`, distinct from the human
+ * `understanding-approved:<sid>` tag (`ledger.ts`), following the same
+ * `...:forced:<field>` suffix precedent the ADR cites. Ledger only, never
+ * consulted for the gate decision itself.
+ */
+export function autoApprovedLedgerTagFor(sessionId) {
+    return `understanding-auto-approved:${sessionId}`;
+}
+/**
+ * The harness identifiers `auto_approve.harnesses` accepts, in the order
+ * the schema and every diagnostic list them. Shared with the pack's zod
+ * `configSchema` (`../understanding-before-execution.ts`) so the lint-time
+ * enum and this runtime parser cannot drift apart.
+ */
+export const AUTO_APPROVE_HARNESS_VALUES = [CLAUDE_CODE_HARNESS, CODEX_HARNESS];
+/**
+ * What `auto_approve.harnesses` resolves to when the key is ABSENT.
+ * Claude Code only, deliberately: slice 1 shipped `auto_approve` as a
+ * Claude-only opt-in, so a repo that opted in before slice 2 must keep
+ * exactly the meaning it had — adding the Codex hook to the shared body
+ * must not silently extend an existing opt-in to a second runtime
+ * (reviewer round-1 finding on slice 2). Opting Codex in is an explicit,
+ * visible config edit.
+ */
+export const DEFAULT_AUTO_APPROVE_HARNESSES = [CLAUDE_CODE_HARNESS];
+/**
+ * What `auto_approve.report_scan.max_wait` resolves to when the key is
+ * ABSENT: the bound the child's PreToolUse hook waits for its own
+ * Understanding Report to reach the session transcript before it blocks
+ * (ADR "Report capture under `-p`", slice 3 acceptance criterion 3).
+ *
+ * The value is measured, not guessed: under `claude -p` the report is
+ * absent from the transcript at the instant PreToolUse fires and lands
+ * some time later, on a lag that scales with report length, so the
+ * bound is set from the real end-to-end runs (a full-length grill_me
+ * report), not only the shorter probe reports that first-guessed 500ms.
+ * The measurement and the retuning derivation are both in
+ * `docs/okf/understanding-gate-auto-mode-signals.md` ("Chosen
+ * `report_scan.max_wait` default" section), from
+ * `dogfood/ug-auto-mode-signals/`.
+ *
+ * ONE named constant on purpose: the hook, the schema default and every
+ * test read this symbol, so re-tuning the bound against a new
+ * measurement is a one-line change with no literal to hunt down.
+ */
+export const DEFAULT_REPORT_SCAN_MAX_WAIT_MS = 2_000;
+/**
+ * Hard ceiling for `auto_approve.report_scan.max_wait`. A larger value
+ * is a `harness validate` schema error AND a runtime parse failure (which
+ * fails the whole `auto_approve` block closed), so no configuration can
+ * make a PreToolUse hook sit on a session for an arbitrary time. 5 s is
+ * an order of magnitude above the measured worst-case flush, which is
+ * generous for a bound whose only job is to cover a transcript write
+ * already in flight.
+ */
+export const REPORT_SCAN_MAX_WAIT_CEILING_MS = 5_000;
+const KNOWN_AUTO_APPROVE_KEYS = new Set([
+    "when",
+    "harnesses",
+    "require_report",
+    "report_scan",
+]);
+/** The only key `auto_approve.report_scan` accepts. */
+const KNOWN_REPORT_SCAN_KEYS = new Set(["max_wait"]);
+/** Sub-second shorthand the shared duration parser does not model. */
+const MILLISECOND_SHORTHAND = /^(\d+)ms$/;
+/**
+ * Parse `auto_approve.report_scan.max_wait` into milliseconds.
+ *
+ * Duration grammar: the pack's SHARED parser
+ * ({@link parseDurationSeconds}, the same one `approval_lifecycle.max_age`
+ * uses), plus an `<n>ms` shorthand it does not model. The extension is
+ * not cosmetic: this bound is a transcript-flush allowance measured in
+ * tens of milliseconds, so a second-granularity grammar could not express
+ * the values the measurement actually argues for, and widening
+ * `parseDurationSeconds` itself would change the grammar of every
+ * `within:` / `max_age:` / `--since` value in the repo for one key's sake.
+ *
+ * Both bounds are errors, never clamps: zero or negative (a bound that
+ * would disable the poll while the block still claimed to have one) and
+ * anything above {@link REPORT_SCAN_MAX_WAIT_CEILING_MS} (a bound that
+ * could park a PreToolUse hook). Returning a RESULT rather than throwing
+ * keeps the two consumers symmetric: the zod schema turns it into a
+ * `harness validate` diagnostic, the runtime parser into one stderr line
+ * and a fail-closed `null`.
+ */
+export function parseReportScanMaxWait(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return {
+            ok: false,
+            reason: `expected a duration string like "500ms", "1500ms" or "2s", got ${typeof raw === "string" ? "an empty string" : typeof raw}`,
+        };
+    }
+    const trimmed = raw.trim();
+    let maxWaitMs;
+    const ms = MILLISECOND_SHORTHAND.exec(trimmed);
+    if (ms) {
+        maxWaitMs = Number.parseInt(ms[1], 10);
+    }
+    else {
+        try {
+            maxWaitMs = parseDurationSeconds(trimmed) * 1_000;
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: err instanceof InvalidDurationError ? err.message : String(err),
+            };
+        }
+    }
+    if (!Number.isFinite(maxWaitMs) || maxWaitMs <= 0) {
+        return {
+            ok: false,
+            reason: `must be greater than zero, got ${JSON.stringify(trimmed)}`,
+        };
+    }
+    if (maxWaitMs > REPORT_SCAN_MAX_WAIT_CEILING_MS) {
+        return {
+            ok: false,
+            reason: `must not exceed the ${REPORT_SCAN_MAX_WAIT_CEILING_MS}ms hard ceiling (a PreToolUse hook must never park a session), got ${JSON.stringify(trimmed)}`,
+        };
+    }
+    return { ok: true, maxWaitMs };
+}
+/**
+ * Parse the optional `auto_approve` pack-config block
+ * (docs/decisions/2026-08-27-ug-auto-mode-approval.md, "Option A").
+ *
+ * FAIL CLOSED, unlike {@link parseApprovalLifecycle}'s best-effort
+ * fallback: this block is an opt-IN to a hook-side signing path
+ * (hardening item 3 in the ADR's threat model (b) — `require_report:
+ * false` must be a schema error, not a silently-ignored key), so any
+ * malformed shape here means "not opted in" (`null`), never a partial
+ * or default-filled config that could still enable the auto path. The
+ * `configSchema` zod block in `../understanding-before-execution.ts` is
+ * the first line of defence (`harness validate` / `harness doctor`
+ * reject a malformed manifest at lint time); this parser is the second,
+ * defensive line for the runtime hook, which must not trust that every
+ * config it sees on disk passed the schema.
+ *
+ * `undefined` / `null` (the block is simply absent) returns `null`
+ * silently — that is the ordinary "not opted in" case, not a warning.
+ * Every other malformed shape writes exactly one stderr line and
+ * returns `null`.
+ *
+ * `label` is the stderr prefix of the calling hook, so a Codex-side
+ * warning reads `harness pack hook codex: ...` like every other line
+ * that hook writes. The default reproduces the Claude Code hook's
+ * wording byte-for-byte.
+ */
+export function parseAutoApprove(raw, stderr, label = "harness pack hook") {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        stderr?.write(`${label}: config.auto_approve ignored (expected object, got ${typeof raw})\n`);
+        return null;
+    }
+    const obj = raw;
+    const unknownKeys = Object.keys(obj).filter((k) => !KNOWN_AUTO_APPROVE_KEYS.has(k));
+    if (unknownKeys.length > 0) {
+        stderr?.write(`${label}: config.auto_approve ignored (unknown key(s): ${unknownKeys.join(", ")})\n`);
+        return null;
+    }
+    const whenRaw = obj["when"];
+    if (!Array.isArray(whenRaw) || whenRaw.length === 0) {
+        stderr?.write(`${label}: config.auto_approve.when ignored (expected a non-empty string[], got ${Array.isArray(whenRaw) ? "empty array" : typeof whenRaw})\n`);
+        return null;
+    }
+    const when = [];
+    for (const v of whenRaw) {
+        if (typeof v !== "string" || v.length === 0) {
+            stderr?.write(`${label}: config.auto_approve.when ignored (every entry must be a non-empty string, got ${typeof v})\n`);
+            return null;
+        }
+        when.push(v);
+    }
+    // `harnesses`: absent means the slice-1 default (Claude Code only).
+    // Present means an exact, non-empty, duplicate-free list of the known
+    // harness identifiers — anything else fails the whole block closed,
+    // like every other malformed shape here, so a typo'd entry can never
+    // widen the opt-in to a runtime the operator did not name.
+    const harnessesRaw = obj["harnesses"];
+    let harnesses = [...DEFAULT_AUTO_APPROVE_HARNESSES];
+    if (harnessesRaw !== undefined) {
+        if (!Array.isArray(harnessesRaw) || harnessesRaw.length === 0) {
+            stderr?.write(`${label}: config.auto_approve.harnesses ignored (expected a non-empty array of ${AUTO_APPROVE_HARNESS_VALUES.join(" | ")}, got ${Array.isArray(harnessesRaw) ? "empty array" : typeof harnessesRaw})\n`);
+            return null;
+        }
+        const seen = [];
+        for (const v of harnessesRaw) {
+            if (typeof v !== "string" || !AUTO_APPROVE_HARNESS_VALUES.includes(v)) {
+                stderr?.write(`${label}: config.auto_approve.harnesses ignored (every entry must be one of ${AUTO_APPROVE_HARNESS_VALUES.join(", ")}, got ${typeof v === "string" ? `"${v}"` : typeof v})\n`);
+                return null;
+            }
+            if (seen.includes(v)) {
+                stderr?.write(`${label}: config.auto_approve.harnesses ignored (duplicate entry "${v}")\n`);
+                return null;
+            }
+            seen.push(v);
+        }
+        harnesses = seen;
+    }
+    // `report_scan`: absent means the measured default
+    // ({@link DEFAULT_REPORT_SCAN_MAX_WAIT_MS}). Present means an object
+    // carrying exactly `max_wait` and nothing else, parsed and
+    // range-checked by `parseReportScanMaxWait`. Anything else fails the
+    // WHOLE block closed, like every other malformed shape here, so a
+    // typo'd bound can never silently fall back to the default while the
+    // operator believes they tuned it.
+    const reportScanRaw = obj["report_scan"];
+    let reportScanMaxWaitMs = DEFAULT_REPORT_SCAN_MAX_WAIT_MS;
+    if (reportScanRaw !== undefined) {
+        if (reportScanRaw === null || typeof reportScanRaw !== "object" || Array.isArray(reportScanRaw)) {
+            stderr?.write(`${label}: config.auto_approve.report_scan ignored (expected object, got ${reportScanRaw === null ? "null" : Array.isArray(reportScanRaw) ? "array" : typeof reportScanRaw})\n`);
+            return null;
+        }
+        const reportScanObj = reportScanRaw;
+        const unknownScanKeys = Object.keys(reportScanObj).filter((k) => !KNOWN_REPORT_SCAN_KEYS.has(k));
+        if (unknownScanKeys.length > 0) {
+            stderr?.write(`${label}: config.auto_approve.report_scan ignored (unknown key(s): ${unknownScanKeys.join(", ")})\n`);
+            return null;
+        }
+        const maxWait = parseReportScanMaxWait(reportScanObj["max_wait"]);
+        if (!maxWait.ok) {
+            stderr?.write(`${label}: config.auto_approve.report_scan.max_wait ignored (${maxWait.reason})\n`);
+            return null;
+        }
+        reportScanMaxWaitMs = maxWait.maxWaitMs;
+    }
+    const requireReport = obj["require_report"];
+    if (requireReport !== true) {
+        stderr?.write(`${label}: config.auto_approve ignored (require_report must be true, got ${requireReport === false ? "false" : typeof requireReport})\n`);
+        return null;
+    }
+    return { when, harnesses, reportScan: { maxWaitMs: reportScanMaxWaitMs } };
+}
+/**
+ * ADR "Additional hardening to specify" item 2: `when` is an allowlist
+ * of payload literals, membership by exact string equality, no case
+ * folding, no substring, no wildcards. `mode` absent, empty, or not a
+ * string means no auto-approval, and `cfg === null` (block absent or
+ * malformed) means no auto-approval regardless of `mode`.
+ *
+ * Takes only the `when` slice of the config rather than the whole block:
+ * this predicate reads exactly one field, and saying so in the signature
+ * keeps it honest as the block grows further keys (`harnesses`,
+ * `report_scan`) that have nothing to do with mode membership.
+ */
+export function permissionModeAllowed(cfg, mode) {
+    if (cfg === null)
+        return false;
+    if (typeof mode !== "string" || mode.length === 0)
+        return false;
+    return cfg.when.includes(mode);
+}
+/**
+ * Per-harness opt-in membership, the same exact-string-equality
+ * discipline {@link permissionModeAllowed} applies to `when`. `cfg ===
+ * null` (block absent or malformed) means no auto-approval regardless of
+ * the harness, and an unlisted harness means no auto-approval regardless
+ * of `when` — the two allowlists are independent AND conditions, not
+ * alternatives.
+ *
+ * Re-exported through `understanding-before-execution/index.ts` (round-2
+ * review finding on slice 2): its call site (`src/cli/pack/auto-approve-path.ts`)
+ * imports every sibling symbol it needs (`parseAutoApprove`,
+ * `permissionModeAllowed`, ...) through the runtime shim already, so this
+ * one was pulled onto the pinned shim surface
+ * (tests/policy-packs/ube-export-surface.test.ts) to match, unlike
+ * {@link CODEX_HARNESS} which still has exactly one consumer and stays a
+ * direct import.
+ */
+export function harnessAllowed(cfg, harness) {
+    if (cfg === null)
+        return false;
+    if (typeof harness !== "string" || harness.length === 0)
+        return false;
+    return cfg.harnesses.includes(harness);
+}
+//# sourceMappingURL=auto-approve.js.map

package/dist/policy-packs/builtin/understanding-before-execution/auto-approve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-approve.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/auto-approve.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/understanding-before-execution/delegation-markers.d.ts

@@ -0,0 +1,223 @@
+/** Directory holding delegation markers, a sibling of `.approvals/` under `generatedDir`. */
+export declare const DELEGATION_MARKER_DIRNAME = ".delegations";
+/**
+ * The signed markerId for a child session: `delegation-<child-sid>`.
+ * Binding it into the signed payload is what stops a validly signed
+ * delegation from being copied onto another child id, or onto a session
+ * marker's id, and still verifying (`task-markers.ts` precedent).
+ */
+export declare function delegationMarkerIdFor(childSessionId: string): string;
+/**
+ * Filesystem path of a child session's delegation marker. Rejects a
+ * malformed session id the same way `approvalMarkerPathFor` does (the
+ * value lands in a `path.join` verbatim).
+ */
+export declare function delegationMarkerPathFor(generatedDir: string, childSessionId: string): string;
+/**
+ * sha256 hex of a filesystem path, canonicalized through `realpathSync`
+ * when the path exists and through `path.resolve` when it does not.
+ *
+ * The canonicalization is the point, not an optimization: the parent
+ * writing the delegation and the child reporting its cwd routinely spell
+ * the same directory differently (on macOS `os.tmpdir()` hands out
+ * `/var/folders/...` while the process reports `/private/var/folders/...`,
+ * because `/var` is a symlink), and an uncanonicalized comparison would
+ * refuse a perfectly legitimate delegation. Falling back to `resolve` for
+ * a non-existent path keeps the function total: a path that cannot be
+ * canonicalized still hashes deterministically, and a delegation bound to
+ * it simply will not match a cwd that resolves elsewhere.
+ *
+ * Named for its primary use; the fallback shape hashes the launcher-
+ * supplied report file's PATH with the same function, so that WHERE the
+ * parent put the report is part of what was signed.
+ */
+export declare function hashDelegationCwd(targetPath: string): string;
+/** The bindings packed into a delegation's `approvedBy` string. */
+export interface DelegationApprovedByFields {
+    parentSessionId: string;
+    /** sha256 of the child's expected cwd, or `null` for a task-only delegation. */
+    cwdHash: string | null;
+    /** The task id the child is delegated for, or `null` for a cwd-only delegation. */
+    taskId: string | null;
+    /** ISO-8601 instant at which the delegation stops being valid. */
+    expiresAt: string;
+    /** sha256 of the launcher-supplied report file's PATH; present only in the fallback shape. */
+    reportPathHash?: string;
+}
+/**
+ * Build the `approvedBy` string a delegation signs:
+ * `delegated:<parent>;cwd=<sha256|->;task=<id|->;expires=<iso>` plus
+ * `;report=<sha256>` in the fallback shape.
+ *
+ * Throws on any input that would corrupt the encoding (an empty value, a
+ * value carrying a `;` or `=` delimiter or a control character, a
+ * malformed parent session id (`rejectMalformedSessionId`), a cwd/report
+ * hash that is not a sha256 digest, a non-ISO expiry, or the literal `-`
+ * as a task id, which would round-trip as "no task bound"). A silently
+ * mis-encoded delegation would be signed and then read back with
+ * different bindings than the caller intended, so this fails loudly at
+ * the only place that can still tell the difference.
+ */
+export declare function buildDelegationApprovedBy(fields: DelegationApprovedByFields): string;
+/** Bindings read back out of a delegation's `approvedBy` string. */
+export interface ParsedDelegationApprovedBy {
+    parentSessionId: string;
+    /** `null` when the delegation binds no cwd (`cwd=-`). */
+    cwdHash: string | null;
+    /** `null` when the delegation binds no task (`task=-`). */
+    taskId: string | null;
+    expiresAt: string;
+    /** Present only in the fallback shape. */
+    reportPathHash?: string;
+}
+export type DelegationApprovedByParse = {
+    ok: true;
+    value: ParsedDelegationApprovedBy;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Strict inverse of {@link buildDelegationApprovedBy}. All four of
+ * `delegated`, `cwd`, `task` and `expires` are required and `report` is
+ * optional; a missing, duplicated, unknown, empty or malformed segment is
+ * an error RESULT, never a default. Segment order is not enforced (the
+ * signature already pins the exact bytes), but every other deviation is
+ * refused: this string is the only place a delegation's bindings live, so
+ * "read it partially and assume the rest" is the one failure mode that
+ * would quietly widen a delegation past what the parent signed.
+ */
+export declare function parseDelegationApprovedBy(approvedBy: unknown): DelegationApprovedByParse;
+export interface WriteDelegationMarkerOptions {
+    generatedDir: string;
+    /** Session id of the `claude -p` child this delegation authorizes. Becomes the file name. */
+    childSessionId: string;
+    /** Session id of the already-approved parent issuing the delegation. */
+    parentSessionId: string;
+    /** {@link hashDelegationCwd} of the child's expected cwd, or `null` for a task-only delegation. */
+    cwdHash: string | null;
+    /** Task id the child is delegated for, or `null` for a cwd-only delegation. */
+    taskId: string | null;
+    /** ISO-8601 instant the delegation expires at. */
+    expiresAt: string;
+    /** Fallback shape: {@link hashDelegationCwd} of the launcher-supplied report file's path. */
+    reportPathHash?: string;
+    /** Fallback shape: sha256 of that file's CONTENT. Omitted (written as `null`) in the base shape. */
+    reportContentHash?: string;
+    /** Override the issue timestamp for deterministic tests. */
+    now?: Date;
+}
+export type WriteDelegationMarkerResult = {
+    ok: true;
+    filePath: string;
+    markerId: string;
+    approvedAt: string;
+    approvedBy: string;
+} | {
+    ok: false;
+    reason: "signing-key-absent" | "invalid-input" | "write-failed";
+    detail: string;
+};
+/**
+ * Write a signed delegation marker through the shared `signMarker` path,
+ * under markerId `delegation-<child-sid>`, at
+ * `<generatedDir>/.delegations/<child-sid>`. Atomic and mode 0600, like
+ * every other marker write.
+ *
+ * NEVER CREATES THE SIGNING KEY. `signMarker` -> `getOrCreateSigningKey`
+ * treats a missing key as a case to REPAIR, generating one and signing
+ * with it; key creation is an operator-side act (`harness init`,
+ * `harness approve`), and a delegation minted on a machine that never had
+ * a key would be a marker signed by whoever asked for it. So this
+ * prechecks `signingKeyExists` and returns `signing-key-absent` without
+ * reaching the write path at all (ADR threat model (b) item 5, the same
+ * rule slice 1's auto path follows).
+ *
+ * Returns a result rather than throwing, for every failure mode: the
+ * callers are a CLI verb and, later, a hook, and both must fail closed
+ * with a diagnostic instead of unwinding.
+ *
+ * Deliberately does NOT refuse a delegation that binds neither cwd nor
+ * task. That refusal belongs to the issuing verb (ADR slice 3 acceptance
+ * criterion 1) and to `verifyDelegation`, which reports `no_binding`;
+ * keeping the writer able to produce one is what lets the test suite
+ * exercise that verifier branch against a genuinely signed artifact
+ * rather than a hand-rolled fake.
+ */
+export declare function writeDelegationMarker(opts: WriteDelegationMarkerOptions): WriteDelegationMarkerResult;
+/**
+ * Why a delegation was refused. Every value is reachable and distinct;
+ * there is no "unknown" bucket and no branch that falls through to
+ * allow.
+ */
+export type DelegationRefusalReason = 
+/** No delegation file for this child session (also: a child session id that cannot name a file). */
+"missing"
+/** The file exists but its integrity cannot be established right now: symlink, non-regular, I/O error, or an unavailable signing key. Not a claim of tampering. */
+ | "unreadable"
+/** A file was there and its signature does not verify against `delegation-<child-sid>`: unsigned, wrong alg, tampered, or copied from another child's delegation. */
+ | "forged"
+/** Validly signed, but its `approvedBy` bindings cannot be read in full. */
+ | "unparseable" | "expired" | "cwd_mismatch" | "task_mismatch"
+/** Binds neither a cwd nor a task, so it would authorize the child anywhere, for anything. */
+ | "no_binding"
+/** Fallback shape: the launcher report is not at the path the parent signed. */
+ | "report_path_mismatch"
+/** Fallback shape: the launcher report's content is not what the parent signed (including a report that cannot be read). */
+ | "report_content_mismatch";
+export type DelegationVerification = {
+    ok: true;
+    parentSessionId: string;
+    expiresAt: string;
+    boundCwdHash: string | null;
+    boundTaskId: string | null;
+    reportPathHash?: string;
+} | {
+    ok: false;
+    reason: DelegationRefusalReason;
+    detail: string;
+};
+export interface VerifyDelegationOptions {
+    generatedDir: string;
+    /** The child session whose delegation is being checked. */
+    childSessionId: string;
+    /** The child's actual cwd, or `null` when the caller has none to offer. */
+    cwd: string | null;
+    /** The child's actual task id, or `null` when the caller has none to offer. */
+    taskId: string | null;
+    /** Fallback shape: the launcher-supplied report file the parent bound. */
+    launcherReportPath?: string;
+    /** Override "now" for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Gate-side: is there a valid, unexpired, matching delegation for this
+ * child session? Checks, in order (ADR slice 3 acceptance criterion 2):
+ *
+ *   1. the file is present and JSON-readable,
+ *   2. its signature verifies against markerId `delegation-<child-sid>`,
+ *   3. its `approvedBy` segments parse in full,
+ *   4. it binds at least one of cwd / task,
+ *   5. it has not expired,
+ *   6. the bound cwd hash-matches the caller's cwd,
+ *   7. the bound task equals the caller's task,
+ *   8. in the fallback shape, the launcher report sits at the bound path
+ *      AND hashes to the bound content.
+ *
+ * Reads only `.delegations/`; an artifact in `.approvals/` is `missing`
+ * here, whatever it contains.
+ *
+ * NEVER CREATES THE SIGNING KEY, on the READ path either.
+ * `verifyMarkerSignature` obtains the key through
+ * `getOrCreateSigningKey`, which treats a missing key as a case to
+ * REPAIR and generates one; on a machine the operator never initialized
+ * that would make a mere gate-time read perform the operator-side act of
+ * minting the key. It cannot make a foreign-signed delegation verify, but
+ * it does leave a key behind that every LATER write path would then
+ * happily sign with, so the never-create rule applies here exactly as it
+ * does to `writeDelegationMarker` and to slice 1's auto path. An absent
+ * key is reported as `unreadable` (we could not check, not "we checked
+ * and it is a forgery"), the same class `verifyMarkerSignature`'s own
+ * `key-unavailable` lands in below.
+ */
+export declare function verifyDelegation(opts: VerifyDelegationOptions): DelegationVerification;