approval-md 0.3.0 → 0.4.1

package/dist/src/core/gate.js

@@ -37,9 +37,12 @@
  *
  * ## Lazy expiry — the named requirement
  *
- * A request expires when `ts > requestTs + defaults.approval_ttl`, **whether or
- * not** an `approval.expired` event exists. Nothing may depend on a daemon
- * having run: if the expiry sweep is asleep, a late grant must still be refused.
+ * A request expires when `ts > requestTs + effective window`, **whether or
+ * not** an `approval.expired` event exists. The effective window is
+ * `defaults.approval_ttl`, narrowed since APRV-423 by whatever harness ceiling
+ * the requesting hook declared on `payload.harness_cap_ms` (a self-reported
+ * bound that can only shorten; see `core/harness-wait.ts`). Nothing may depend
+ * on a daemon having run: if the expiry sweep is asleep, a late grant must still be refused.
  * {@link requestState} therefore computes expiry two ways — from the event, and
  * lazily from the arithmetic — and treats them as equivalent.
  *
@@ -124,7 +127,7 @@ import { normalizeUsd, usdOrZero } from "./money.js";
 import { isPayloadHash, payloadHash as hashOfPayload } from "./payload.js";
 import { loadPayload, payloadPath, payloadStoreDirFor, storePayload } from "./payload-store.js";
 import { loadPolicyText, policyUnreadable, POLICY_FILENAMES, tokenDeliveryOf, } from "./policy-load.js";
-import { harnessLaunchNeedsRule, harnessLaunchUnruledRefusal, humanOnlyRefusal, resolve, } from "./policy-match.js";
+import { agentRequestability, harnessLaunchNeedsRule, harnessLaunchUnruledRefusal, humanOnlyRefusal, resolve, } from "./policy-match.js";
 import { DRAW_PROTOCOL_VERSION, askDaemonDraw, } from "./live-draw.js";
 import { LIVE_SELECTION, resolveLiveSelector, } from "./sampler.js";
 import { forgetPrivateKey, isRecipientKey, keyStoreDirFor, mintRecipientKeypair, RECIPIENT_KEY_FIELD, sealToken, SEALED_TOKEN_FIELD, SELF_DELIVERY_FIELD, writePrivateKey, } from "./seal.js";
@@ -161,8 +164,12 @@ const HUMAN_ACTOR = /^human:.+/u;
  * language. An empty list names nobody and therefore matches nobody;
  * `approvers` carries `minItems: 1`, so a valid policy cannot produce one, and
  * that branch stays a fail-closed backstop rather than a reachable path.
+ *
+ * Exported for `core/audit.ts` (APRV-483), whose review check is this one
+ * comparison applied to a reviewer, so a grant and a review can never disagree
+ * about who is on a roster.
  */
-function namesApprover(approvers, actor) {
+export function namesApprover(approvers, actor) {
     const bare = actor.startsWith("human:") ? actor.slice("human:".length) : actor;
     return approvers.some((name) => name === actor || name === bare);
 }
@@ -533,6 +540,50 @@ export const GATE_REFUSAL_CODES = [
      * nothing can ever open. Nothing is appended; the next attempt asks again.
      */
     "token-delivery-unavailable",
+    /**
+     * `approval propose` named a class the policy has not opened to agents
+     * (APRV-445, amended SPEC.md §5.2): the class is not an exact key of
+     * `policy.classes`, or neither that key nor a declared `<prefix>.*` family of
+     * it sets `agent_may_request: true`. Nothing is registered and nothing is
+     * appended. The repair is the operator's, a policy edit and a re-attestation;
+     * no retry by the agent changes it.
+     */
+    "class-not-agent-requestable",
+    /**
+     * `approval propose` / `approval start` carried a payload larger than
+     * {@link PROPOSE_PAYLOAD_MAX_BYTES} (APRV-445). Refused before the bytes are
+     * parsed or hashed; nothing is stored and nothing is appended.
+     */
+    "payload-too-large",
+    /**
+     * `approval request` (or a task FILE's registration) named a `propose:` task
+     * (APRV-445 refutation, S1). A proposal is requested only through `propose`,
+     * which re-checks the operator's opening of its class; a plain request on the
+     * same task would skip that check, and a file-registered `propose:` id would
+     * borrow the exclusions proposals get from the harness hook.
+     */
+    "task-is-proposal",
+    /**
+     * `approval start` named a task `propose` did not register (APRV-445, L9).
+     * `start` records executions of proposals and of nothing else; every other
+     * action executes through `approval run`, an adapter, or the hook.
+     */
+    "task-not-proposal",
+    /**
+     * `approval propose --key` does not begin with `<class>:` (APRV-445, S4). The
+     * key names the class it was proposed under, so a key cannot be read back
+     * later as belonging to a different class than its record says.
+     */
+    "key-class-mismatch",
+    /**
+     * `approval propose` found the log moving under it on every one of its
+     * bounded attempts (APRV-445 recheck 3): each re-read showed an answer the
+     * next append was refused for. Exit 1, nothing more was appended, and the
+     * proposal's standing is whatever the log now says; read it with `wait
+     * --timeout 0` or call again. Distinct from `already-decided`, which would
+     * tell a caller a proposal is answered when it may stand granted or pending.
+     */
+    "contended",
 ];
 function refuse(code, message, extra = {}) {
     return { ok: false, code, message, ...extra };
@@ -571,7 +622,13 @@ export function readGateRecords(logPath, schemaDir) {
  * `checkAttestation` reports `unreadable` and the gate refuses — a missing
  * policy is never a pass.
  */
-function policyPathOf(options) {
+/**
+ * The policy file a gate operation reads: `policy.file`, or the first policy
+ * filename found in `policy.dir` (default: the working directory). Exported for
+ * `core/audit.ts` (APRV-483), whose roster check must read the same file a
+ * grant would and hold it to the same attestation.
+ */
+export function policyPathOf(options) {
     const policy = options.policy ?? {};
     if (policy.file !== undefined)
         return policy.file;
@@ -665,6 +722,21 @@ function requireAttestation(records, read) {
 function ttlOf(load) {
     return load.ok ? load.durations.approvalTtlMs : null;
 }
+/**
+ * The clause a refusal adds when a harness ceiling, rather than the policy,
+ * fixed this request's deadline (APRV-423).
+ *
+ * Empty for every request that declared no cap, which is every request made
+ * outside a harness hook — so the messages a human has been reading since v0.1
+ * are unchanged, and the one new sentence appears exactly where it explains
+ * something the policy alone does not.
+ */
+function cappedBy(derivation) {
+    const cap = derivation.declared.harness_cap_ms;
+    if (cap === null)
+        return "";
+    return ` (shortened from the policy's own TTL: the requesting hook declared a ${String(cap)}ms harness ceiling, and the window ends a margin before it so the expiry is recorded while the harness is still listening)`;
+}
 function budgetScopeOf(load, resolution) {
     return {
         classLimits: resolution.limits,
@@ -910,6 +982,15 @@ function attemptRegister(logPath, source, actor, options) {
         }
         return resolved.refusal;
     }
+    // APRV-445 refutation (S1). The `propose:` namespace belongs to `propose`;
+    // a task FILE claiming an id in it would borrow the exclusions proposals get
+    // from the harness hook (its sweep and its carry).
+    // Recheck L-c: the in-memory sources too (the muse `POST /v1/registrations`
+    // route registers whatever task id its caller names); only `propose` itself
+    // passes `proposal: true`.
+    if (isProposalTask(resolved.task) && options.proposal !== true) {
+        return refuse("task-is-proposal", `task id ${resolved.task} is in the namespace \`approval propose\` derives its ids in (${PROPOSE_TASK_PREFIX}); only propose registers there. Nothing was appended.`);
+    }
     const validation = validate("envelope", resolved.envelope, options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir });
     if (!validation.ok) {
         return refuse("envelope-invalid", `the envelope failed schema validation; nothing was appended`, { errors: validation.errors });
@@ -965,13 +1046,17 @@ function attemptRegister(logPath, source, actor, options) {
     return { ok: true, record: appended.record, task: resolved.task, actions };
 }
 /**
- * The declared action for `(task, actionKey)`, as registered in the log.
- *
- * SPEC.md §7: "an action's class MUST be declared before an execution token can
- * be requested for it". The declaration lives in `task.registered`, so the log —
- * not the file, which may have been edited since — is what the gate reads back.
+ * The `task.registered` record for `task`, or the `not-registered` refusal.
+ *
+ * The one raise site for SPEC.md §11.2's `not-registered` ("no task.registered
+ * record exists for the task id"). `request` reaches it through
+ * {@link registeredAction}; `approval wait` calls it directly (APRV-428), so a
+ * wait on a task the log has never seen is refused in the same words rather
+ * than answered as a vacuous grant. The latest registration wins, as it always
+ * has for `registeredAction`; the register path refuses a second one, so a log
+ * carrying two was written by something else.
  */
-export function registeredAction(records, task, actionKey) {
+export function taskRegistration(records, task) {
     let registration = null;
     for (const record of records) {
         if (record.event === "task.registered" && record.task === task)
@@ -980,6 +1065,20 @@ export function registeredAction(records, task, actionKey) {
     if (registration === null) {
         return refuse("not-registered", `task ${task} has no task.registered record; run \`approval register <task-file>\` first`);
     }
+    return { ok: true, record: registration };
+}
+/**
+ * The declared action for `(task, actionKey)`, as registered in the log.
+ *
+ * SPEC.md §7: "an action's class MUST be declared before an execution token can
+ * be requested for it". The declaration lives in `task.registered`, so the log —
+ * not the file, which may have been edited since — is what the gate reads back.
+ */
+export function registeredAction(records, task, actionKey) {
+    const registered = taskRegistration(records, task);
+    if (!registered.ok)
+        return registered;
+    const registration = registered.record;
     const declared = payloadOf(registration)["actions"];
     const actions = Array.isArray(declared) ? declared : [];
     for (const entry of actions) {
@@ -1340,6 +1439,21 @@ function attemptRequest(logPath, input, actor, options) {
         return attested;
     const load = parsePolicy(policyRead, options);
     const resolution = resolve(load, input.cls, input.reversible === undefined ? {} : { reversible: input.reversible });
+    // APRV-445 refutation (S1). A `propose:` task is requested through `propose`
+    // and nothing else, so its agent-requestability check cannot be skipped by
+    // asking for the same registration with a plain `request`.
+    if (isProposalTask(input.task) && input.agentProposal !== true) {
+        return refuse("task-is-proposal", `task ${input.task} was registered by \`approval propose\` and is requested only through it; nothing was appended`);
+    }
+    // APRV-445. A proposal's class came from the requester, so the operator's
+    // opening of that class to agents is re-read here, from the same bytes the
+    // attestation above verified, before anything else can be decided for it.
+    if (input.agentProposal === true) {
+        const opened = agentRequestability(load, input.cls);
+        if (!opened.allowed) {
+            return refuse("class-not-agent-requestable", notAgentRequestable(input.cls, opened));
+        }
+    }
     // APRV-185, amended SPEC.md §5.2, and the first thing intake asks once the
     // class has an autonomy: a `human-only` class is not requestable. The policy
     // itself answers, so nothing is put in front of a human, nothing is drawn,
@@ -1547,6 +1661,17 @@ function attemptRequest(logPath, input, actor, options) {
     if (derivation.execution.started !== null) {
         return refuse("already-executed", `action ${input.actionKey} already executed (execution.started at seq ${String(derivation.execution.started)}); an idempotency key is single-use`, { state: derivation.state });
     }
+    // APRV-445 recheck (SF1). A proposal is asked again only when its last
+    // answer can no longer be used, and that is judged HERE, against the records
+    // this attempt appends on, not against whatever its caller read earlier. A
+    // usable grant (unexpired, under the policy in force) or a human's refusal
+    // stands: a stale caller may not put a fresh question over it.
+    if (input.agentProposal === true) {
+        const standing = requestStanding(read.records, input.actionKey, ts, ttlOf(load), attested.sha256);
+        if (standing === "granted" || standing === "rejected" || standing === "revoked") {
+            return refuse("already-decided", `action ${input.actionKey} already carries a ${standing} answer that still stands at seq ${String(derivation.decisionSeq)}; a proposal is asked again only when its answer can no longer be used. Nothing was appended.`, { state: derivation.state });
+        }
+    }
     // APRV-173, SPEC.md §5.2's request-volume limits, enforced here and nowhere
     // else. Placed AFTER the legality checks above and BEFORE budgets, and both
     // halves of that placement are deliberate.
@@ -1715,6 +1840,13 @@ function attemptRequest(logPath, input, actor, options) {
         payload["execution"] = input.execution;
     if (input.wait_until !== undefined)
         payload["wait_until"] = input.wait_until;
+    // APRV-423, on the same terms as the two above: recorded because the log is
+    // the only place a later reader — the daemon's sweep, a channel, the retry
+    // that adopts this question — can learn what bounded it, and it cannot
+    // lengthen anything. `core/state.ts` takes the minimum of this and the
+    // policy's TTL; see `RequestInput.harnessCapMs`.
+    if (input.harnessCapMs !== undefined)
+        payload["harness_cap_ms"] = input.harnessCapMs;
     const appended = append(logPath, {
         ts,
         event: "approval.requested",
@@ -1889,7 +2021,7 @@ function attemptDecide(logPath, actionKey, decision, actor, options) {
                 materialised = logged.record;
         }
         const message = derivation.expiredLazily
-            ? `action ${actionKey} expired: the request at ${String(derivation.requestTs)} lapsed its ${String(ttlMs)}ms TTL before ${ts}. The lapse is judged from the request's own timestamp, so a decision is refused whether or not an approval.expired event had been observed.`
+            ? `action ${actionKey} expired: the request at ${String(derivation.requestTs)} lapsed its ${String(derivation.effectiveTtlMs)}ms window before ${ts}${cappedBy(derivation)}. The lapse is judged from the request's own timestamp, so a decision is refused whether or not an approval.expired event had been observed.`
             : `action ${actionKey} expired at ${String(derivation.decisionTs)} (approval.expired, seq ${String(derivation.decisionSeq)}); an expired request is terminal`;
         return refuse("expired", message, materialised === undefined
             ? { state: derivation.state }
@@ -2001,6 +2133,16 @@ function attemptDecide(logPath, actionKey, decision, actor, options) {
         if (options.senderSource !== undefined)
             payload["sender_source"] = options.senderSource;
     }
+    // APRV-489. Grant and reject only, the two answers a prompt collects, and only
+    // when the surface drew (or was asked for) a non-default layout. Copied in a
+    // fixed shape so nothing else a caller hangs on the object reaches the log.
+    if (decision !== "revoke" && options.rendering !== undefined) {
+        payload["rendering"] = {
+            style: options.rendering.style,
+            ...(options.rendering.fallback === undefined ? {} : { fallback: options.rendering.fallback }),
+            ...(options.rendering.say_does_ignored === true ? { say_does_ignored: true } : {}),
+        };
+    }
     if (decision === "grant") {
         const cls = derivation.declared.class ?? "";
         const resolution = resolve(load, cls, derivation.declared.reversible === null ? {} : { reversible: derivation.declared.reversible });
@@ -2227,13 +2369,20 @@ function attemptWithdraw(logPath, actionKey, actor, options) {
             if (logged.ok)
                 materialised = logged.record;
         }
-        return refuse("expired", `action ${actionKey} expired: the request at ${String(derivation.requestTs)} lapsed its ${String(ttlMs)}ms TTL before ${ts}. A lapsed request has already ended; there is nothing left to withdraw.`, materialised === undefined
+        return refuse("expired", `action ${actionKey} expired: the request at ${String(derivation.requestTs)} lapsed its ${String(derivation.effectiveTtlMs)}ms window before ${ts}${cappedBy(derivation)}. A lapsed request has already ended; there is nothing left to withdraw.`, materialised === undefined
             ? { state: derivation.state }
             : { state: derivation.state, record: materialised });
     }
     if (derivation.state !== "requested") {
         return refuse("already-decided", `action ${actionKey} was already ${derivation.state} at seq ${String(derivation.decisionSeq)}; a human's answer stands, and withdrawing a question that has been answered would erase the answer`, { state: derivation.state });
     }
+    if (options.onlyIfVoid === true) {
+        const attested = requireAttestation(read.records, readPolicyOnce(options));
+        const pinned = derivation.declared.policy_sha256;
+        if (!attested.ok || pinned === null || pinned === attested.sha256) {
+            return refuse("duplicate-request", `action ${actionKey} has a live request at seq ${String(derivation.requestSeq)} routed under the policy in force, so it is not void and was not withdrawn`, { state: derivation.state });
+        }
+    }
     if (derivation.requestActor !== actor) {
         return refuse("not-requester", `action ${actionKey} was requested by ${JSON.stringify(derivation.requestActor)} and cannot be withdrawn by ${JSON.stringify(actor)}; only the party that asked may take the question back. To end a pending request as someone else, reject it — that is a decision, and it is recorded as one.`, { state: derivation.state });
     }
@@ -2282,8 +2431,9 @@ function attemptWithdraw(logPath, actionKey, actor, options) {
  *    refused at the append in {@link consumeHarnessGrant}. The single-use rule
  *    is the gate's existing one; this only stops the caller from queueing up a
  *    write that would be refused.
- *  - *within the TTL*: state is derived at `ts` with `ttlMs`, so a lapsed
- *    request reads `expired` and carries nothing, whether or not the daemon has
+ *  - *within the TTL*: state is derived at `ts` with `ttlMs`, narrowed by the
+ *    candidate's own declared harness ceiling (APRV-423), so a lapsed request
+ *    reads `expired` and carries nothing, whether or not the daemon has
  *    materialised an `approval.expired` record.
  *
  * PURE, and reads only records the caller verified — the enforcement path never
@@ -2292,7 +2442,7 @@ function attemptWithdraw(logPath, actionKey, actor, options) {
  * request that came after it, exactly as {@link requestState} treats cycles.
  */
 /**
- * Has a GRANTED request outlived `defaults.approval_ttl`?
+ * Has a GRANTED request outlived the window it was asked under?
  *
  * `requestState` reports a decided request by its decision forever: the TTL
  * bounds the window in which a human may answer, not the answer's shelf life.
@@ -2305,7 +2455,14 @@ function attemptWithdraw(logPath, actionKey, actor, options) {
  * Unparseable instants read as lapsed, and a policy with no TTL declares no
  * lapse at all — both exactly as `core/token.ts` reads them.
  */
-function grantLapsed(derivation, ts, ttlMs) {
+function grantLapsed(derivation, ts) {
+    // APRV-423: the SAME window the request was judged by, read off the
+    // derivation rather than recomputed from the policy. A grant whose question
+    // was bounded by a harness ceiling keeps that bound; a retry a few seconds
+    // later then asks again instead of carrying an answer the request's own
+    // clock had already run out on. The stricter of the two readings, and the
+    // one that keeps `requestState` the single place the deadline is decided.
+    const ttlMs = derivation.effectiveTtlMs;
     if (ttlMs === null)
         return false;
     const requestedAt = Date.parse(derivation.requestTs ?? "");
@@ -2314,7 +2471,63 @@ function grantLapsed(derivation, ts, ttlMs) {
         return true;
     return asked > requestedAt + ttlMs;
 }
-export function findHarnessCarry(records, payloadHash, cls, ts, ttlMs) {
+/**
+ * Was the question already abandoned when it was answered? (APRV-410.)
+ *
+ * The state this names, observed 2026-09-20 in this repository's own log. A
+ * hook wait expired at 18:52:37 on a request opened at 18:43:37; the retry
+ * grace ran out at 18:57:37 with nothing retrying; a human tapped approve at
+ * 19:03:32 and `approval.granted` seq 64473 was recorded, six minutes past the
+ * grace, on a question no hook process was holding. The grant authorized
+ * nothing that ran on the day only because the session had already moved on. It
+ * was still live: a retry of that exact command in that directory inside the
+ * TTL would have found it here and proceeded on it, which is one human tap
+ * authorizing an execution nobody connected to the tap.
+ *
+ * {@link grantLapsed} bounds a grant by the request's TTL, which is the shelf
+ * life of an ANSWER. This bounds it by the life of the QUESTION: past
+ * `requestTs + abandonAfterMs` the asker is gone (`core/harness-wait.ts` is
+ * where that duration and its reasoning live), so an answer arriving after it
+ * answered nobody. Both bounds apply; either one alone lets a case through.
+ *
+ * Two facts and no third. The request's own runtime-assigned timestamp and the
+ * decision record's own runtime-assigned timestamp, both read from the log the
+ * caller verified. Nothing self-reported enters it, and the caller's
+ * `abandonAfterMs` is the window the CALLER is configured for rather than
+ * anything the requester said about itself, which is why a false claim cannot
+ * widen it.
+ *
+ * Strictly stricter, and opt-in. A caller that passes no window gets exactly
+ * today's behaviour, and a caller that passes one can only lose a carry it
+ * would otherwise have had. Losing one costs a fresh question; keeping one
+ * costs an execution on an answer nobody was waiting for.
+ *
+ * An unparseable instant on either side reads as abandoned, exactly as
+ * {@link grantLapsed} reads one as lapsed: the strict direction is the one a
+ * corrupt byte must resolve to.
+ */
+function questionAbandoned(derivation, abandonAfterMs) {
+    if (abandonAfterMs === null)
+        return false;
+    const requestedAt = Date.parse(derivation.requestTs ?? "");
+    const answeredAt = Date.parse(derivation.decisionTs ?? "");
+    if (Number.isNaN(requestedAt) || Number.isNaN(answeredAt))
+        return true;
+    return answeredAt > requestedAt + Math.max(0, abandonAfterMs);
+}
+export function findHarnessCarry(records, payloadHash, cls, ts, ttlMs, 
+/**
+ * How long a question of this caller's outlives the wait that opened it
+ * (APRV-410, `core/harness-wait.ts`'s `abandonedAfterMs`), or `null` for a
+ * caller that declares no such window.
+ *
+ * Only a GRANTED candidate is bounded by it. A pending one is the question
+ * this invocation is about to adopt, and the withdrawal of an abandoned
+ * pending question is the requester's own business, not this function's:
+ * `cli/hook.ts` sweeps those through `withdraw`, which is requester-only by
+ * design (APRV-106 rule 1).
+ */
+abandonAfterMs = null) {
     if (!isPayloadHash(payloadHash))
         return null;
     // Distinct keys, latest request first: a later question about the same bytes
@@ -2331,6 +2544,11 @@ export function findHarnessCarry(records, payloadHash, cls, ts, ttlMs) {
             continue;
         if (keys.includes(record.action_key))
             continue;
+        // APRV-445. A proposal's harness grant belongs to `approval start` and to
+        // nothing else: a hook call that happened to present the same bytes in the
+        // same class must not carry or adopt it.
+        if (isProposalTask(record.task))
+            continue;
         const payload = payloadOf(record);
         if (payload["execution"] !== "harness")
             continue;
@@ -2354,7 +2572,13 @@ export function findHarnessCarry(records, payloadHash, cls, ts, ttlMs) {
             continue;
         if (derivation.state === "granted") {
             // An answer has a shelf life, and it is its request's TTL.
-            if (grantLapsed(derivation, ts, ttlMs))
+            // APRV-423: judged by the request's own effective window, read off the
+            // derivation, never the raw policy TTL.
+            if (grantLapsed(derivation, ts))
+                continue;
+            // And a question has a life of its own: an answer that landed after the
+            // asker was gone authorized nobody (APRV-410).
+            if (questionAbandoned(derivation, abandonAfterMs))
                 continue;
             return {
                 actionKey,
@@ -2424,6 +2648,43 @@ export const HARNESS_GRANT_ORIGIN = "grant_origin";
  * every reader treats absence as "no second name" rather than as a fault.
  */
 export const HARNESS_SPENDING_TASK = "spent_by_task";
+/**
+ * The policy stamp every harness `execution.started` carries (APRV-447).
+ *
+ * `payload.policy_sha256` names the attested policy the write boundary
+ * re-checked this start's class against: the hash {@link requireAttestation}
+ * returned for the one policy read the appending attempt made, which is the
+ * read the class was resolved from and the attestation was judged on. On the
+ * hook route the verdict itself was drawn from the hook's own, earlier read;
+ * a re-attest landing between that read and this append leaves the stamp
+ * naming the policy in force at the append (the two-read window predates this
+ * field, and is a follow-up to close). Before this field a
+ * policy-authorized start (autonomous, supervised, an unselected live draw)
+ * carried no policy at all, and a reader had to reconstruct the rules in force
+ * from the latest `policy.updated` before the record's seq. A granted start
+ * could recover it through `grant_seq`; it is stamped too, by the same line, so
+ * every harness start answers the question the same way.
+ *
+ * WRITTEN, never accepted. The value is passed in from the attempt's own
+ * attestation check and from nowhere else: neither {@link HarnessStartInput}
+ * nor {@link ConsumeHarnessOptions} has a field for it, and the payload object
+ * is built here from runtime-held values, so a caller's input, option bag or
+ * action payload that happens to carry the same name changes nothing (§11.1
+ * invariant 1: the stamp comes from the verified attestation the gate already
+ * resolved, never from an envelope). An unattested or edited policy never
+ * reaches this line: both write paths refuse `policy-not-attested` first, and
+ * a grant spend under a policy other than the one the grant pinned is refused
+ * `policy-drift` before its payload is built.
+ *
+ * READ by nothing that decides. No verdict, budget, draw, loop floor or
+ * single-use check consults it, and `core/state.ts` reads `policy_sha256` from
+ * `approval.requested` alone. Its readers are downstream followers of the log
+ * that join a start to the rules it ran under, so the field NAME is a stable
+ * contract.
+ */
+function harnessStartPolicyStamp(attestedSha256) {
+    return { [POLICY_HASH_FIELD]: attestedSha256 };
+}
 /**
  * Spend a harness grant, exactly once (APRV-117).
  *
@@ -2537,8 +2798,8 @@ function attemptHarnessConsume(logPath, actionKey, actor, options) {
     if (derivation.declared.execution !== "harness") {
         return refuse("not-granted", `action ${actionKey} was granted as an ordinary request and minted an execution token; it is spent by presenting that token to \`approval run\`, not by a harness proceeding on it. Two spenders of one authorization is the property this refuses.`, { state: derivation.state });
     }
-    if (grantLapsed(derivation, ts, ttlOf(load))) {
-        return refuse("expired", `action ${actionKey}'s grant expired: the request at ${String(derivation.requestTs)} lapsed its TTL before ${ts}. There is no separate grant TTL — an approval lives exactly as long as its parent request, which is the rule \`core/token.ts\` applies to a token-bearing grant.`, { state: derivation.state });
+    if (grantLapsed(derivation, ts)) {
+        return refuse("expired", `action ${actionKey}'s grant expired: the request at ${String(derivation.requestTs)} lapsed its ${String(derivation.effectiveTtlMs)}ms window before ${ts}${cappedBy(derivation)}. There is no separate grant TTL — an approval lives exactly as long as its parent request, which is the rule \`core/token.ts\` applies to a token-bearing grant.`, { state: derivation.state });
     }
     if (derivation.task === null) {
         return refuse("not-registered", `action ${actionKey} has a grant but no task on its request record; an execution event names both (SPEC.md §8) and nothing here invents one`, { state: derivation.state });
@@ -2614,6 +2875,11 @@ function attemptHarnessConsume(logPath, actionKey, actor, options) {
             options.spendingTask === derivation.task
             ? "direct"
             : "carried"),
+        // APRV-447: the attested policy this spend was judged under, the same
+        // value `policy-drift` compared against the grant's pin above, so on this
+        // path it equals that pin wherever the grant carries one. See
+        // `harnessStartPolicyStamp` for why it is stamped and who reads it.
+        ...harnessStartPolicyStamp(attested.sha256),
     };
     // APRV-287. A carried spend records WHICH tool call spent it, so the
     // completion counterpart can find this start from the event that reports how
@@ -2765,6 +3031,16 @@ function attemptHarnessStart(logPath, input, actor, options) {
     if (!isPayloadHash(bytes)) {
         return refuse("payload-hash-required", `recording a harness execution of ${input.actionKey} requires the payload_hash of what is about to run (amended SPEC.md §6.2, APRV-140), and this caller presented ${bytes === undefined ? "none" : JSON.stringify(bytes)}. A start event that cannot state its bytes says only that something ran; the harness computes the hash of the payload it is about to execute and passes it here. Nothing was appended.`);
     }
+    // APRV-445 security pass. A proposal's start reaches this function only when
+    // its key holds no live request, and the task id alone says it is a proposal
+    // (read from the task, never from a caller flag). Re-judged here, inside the
+    // attempt that appends, so a request filed or decided after `startProposed`
+    // looked cannot slip past. Checked before the budget verdict, which writes.
+    if (isProposalTask(input.task)) {
+        const refusal = proposalPolicyStartRefusal(logPath, read.records, input.actionKey, bytes, load, resolution, attested.sha256, ts, options);
+        if (refusal !== null)
+            return refusal;
+    }
     const cost = costOf(input.est_cost_usd);
     const budget = evaluateBudgetsWithTask(read.records, budgetScopeOf(load, resolution), { class: input.cls, est_cost_usd: cost }, ts, input.task);
     if (!budget.pass) {
@@ -2787,7 +3063,14 @@ function attemptHarnessStart(logPath, input, actor, options) {
             .join(", ")}`;
         return logged.ok
             ? refuse("budget-exceeded", message, { verdicts: failed, record: logged.record })
-            : refuse("budget-exceeded", `${message}; the budget.exceeded event could not be appended: ${logged.message}`, { verdicts: failed });
+            : refuse("budget-exceeded", `${message}; the budget.exceeded event could not be appended: ${logged.message}`, 
+            // APRV-478: the writer's own error rides along, so a caller that
+            // waits for the log's lock on its event loop (the harness hook's
+            // `spendUnderLock`) can see that the evidence lost a lock race,
+            // re-run the whole attempt and give the record the same chance to
+            // land that a synchronous lock wait gave it. The verdict is the
+            // budget refusal either way.
+            logged.append === undefined ? { verdicts: failed } : { verdicts: failed, append: logged.append });
     }
     const payload = {
         // The budgets contract: class and est_cost_usd on every start event.
@@ -2798,6 +3081,11 @@ function attemptHarnessStart(logPath, input, actor, options) {
         // APRV-146: unconditional, because a caller that states no bytes was refused
         // above. The record says what ran, not only that something did.
         payload_hash: bytes,
+        // APRV-447: the attested policy this write boundary re-checked the class
+        // against (see `harnessStartPolicyStamp` for the hook's two-read window).
+        // Without it a reader of a policy-authorized start had to reconstruct the
+        // rules in force from the latest `policy.updated` before this seq.
+        ...harnessStartPolicyStamp(attested.sha256),
     };
     const appended = append(logPath, {
         ts,
@@ -2814,6 +3102,54 @@ function attemptHarnessStart(logPath, input, actor, options) {
         return appended;
     return { ok: true, record: appended.record };
 }
+/**
+ * Why a proposal may NOT start on the policy path, or `null` when it may
+ * (APRV-445 security pass).
+ *
+ * The policy path records an execution the policy itself authorizes. For a
+ * proposal that is true only when no human question about these bytes is open
+ * or answered no under the policy in force, and when the class would not have
+ * put this action in front of a human at all. Three refusals, all `not-granted`:
+ *
+ * - a request for the key is pending or granted and unspent: the key is bound to
+ *   the grant path, and `start` must spend the grant (or wait for the decision);
+ * - the key's latest request was rejected or revoked under the attested policy
+ *   (or pinned no policy): a human's no under the rules in force stands. After a
+ *   re-attest the rules that asked are gone, and the action is judged afresh;
+ * - the class is `supervised-live` and the draw selects these bytes: the draw is
+ *   deterministic over the policy and the payload hash, so it reproduces the
+ *   intake answer, and a selected action is authorized by a grant, never by the
+ *   policy. Without this a withdrawn, expired, rejected or never-filed request
+ *   for a selected live action turned into a policy-authorized start.
+ *
+ * Asking the draw appends nothing; a draw that cannot be made gates, so this
+ * fails closed.
+ */
+function proposalPolicyStartRefusal(logPath, records, actionKey, payloadHash, load, resolution, attestedSha256, ts, options) {
+    const derivation = requestState(records, actionKey, ts, ttlOf(load));
+    if (derivation.execution.started === null &&
+        (derivation.state === "requested" || derivation.state === "granted")) {
+        return refuse("not-granted", `action ${actionKey} has a ${derivation.state} request (seq ${String(derivation.requestSeq)}), so it is bound to the grant path: a pending request is decided by a human and a granted one is spent by start through the grant. Start it again; nothing was appended.`);
+    }
+    if (derivation.state === "rejected" || derivation.state === "revoked") {
+        const pinned = derivation.declared.policy_sha256;
+        if (pinned === null || pinned === attestedSha256) {
+            return refuse("not-granted", `action ${actionKey} was ${derivation.state} by a human (seq ${String(derivation.decisionSeq)}) under the policy in force, and a human's no is not turned into a policy-authorized start. Propose it again only after the policy changes; nothing was appended.`);
+        }
+    }
+    if (resolution.supervision === "live") {
+        const live = liveVerdict(load, resolution, payloadHash, options.env, {
+            logPath,
+            policyHash: attestedSha256,
+            actionKey,
+            ask: options.drawAsk ?? askDaemonDraw,
+        });
+        if (live.gated) {
+            return refuse("not-granted", `class ${String(derivation.declared.class)} of ${actionKey} is supervised-live and the draw put these bytes in front of a human (${live.reason}); a selected action is authorized by a human's grant, never by the policy. Propose it and spend the grant; nothing was appended.`);
+        }
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // finishHarnessExecution — the completion counterpart (APRV-145)
 // ---------------------------------------------------------------------------
@@ -3008,9 +3344,19 @@ function appendExpiry(logPath, derivation, load, ts, options, expectedHead) {
     const payload = {};
     if (derivation.requestTs !== null)
         payload["requested_ts"] = derivation.requestTs;
-    const ttlMs = ttlOf(load);
+    // The window this request was ACTUALLY judged by, which is the policy's TTL
+    // narrowed by whatever harness ceiling the requester declared (APRV-423).
+    // Recording the policy's number here while expiring on a shorter one would
+    // leave the record disagreeing with the arithmetic that produced it, and the
+    // reader's obvious check — requested_ts + ttl_ms against ts — would fail on a
+    // correct expiry. The cap rides along beside it so a reader can see WHY the
+    // window was short without holding the request record too.
+    const ttlMs = derivation.effectiveTtlMs;
     if (ttlMs !== null)
         payload["ttl_ms"] = ttlMs;
+    if (derivation.declared.harness_cap_ms !== null) {
+        payload["harness_cap_ms"] = derivation.declared.harness_cap_ms;
+    }
     const onExpiry = load.ok ? load.policy.defaults?.on_expiry : undefined;
     if (onExpiry !== undefined)
         payload["on_expiry"] = onExpiry;
@@ -3063,9 +3409,9 @@ export function expire(logPath, actionKey, options = {}) {
         if (derivation.state !== "requested") {
             return refuse("already-decided", `action ${actionKey} was already ${derivation.state} at seq ${String(derivation.decisionSeq)}; only a live request can expire`, { state: derivation.state });
         }
-        return refuse("not-expired", ttlMs === null
-            ? `action ${actionKey} cannot expire: the policy declares no defaults.approval_ttl, so the request is not bounded by a TTL`
-            : `action ${actionKey} has not expired: the request at ${String(derivation.requestTs)} has not lapsed its ${String(ttlMs)}ms TTL as of ${ts}`, { state: derivation.state });
+        return refuse("not-expired", derivation.effectiveTtlMs === null
+            ? `action ${actionKey} cannot expire: the policy declares no defaults.approval_ttl and the request declares no harness cap, so it is not bounded by any deadline`
+            : `action ${actionKey} has not expired: the request at ${String(derivation.requestTs)} has not lapsed its ${String(derivation.effectiveTtlMs)}ms window as of ${ts}${cappedBy(derivation)}`, { state: derivation.state });
     }
     const expired = appendExpiry(logPath, derivation, load, ts, options, read.head);
     if (expired.ok) {
@@ -3079,4 +3425,433 @@ export function expire(logPath, actionKey, options = {}) {
     }
     return expired;
 }
+// ---------------------------------------------------------------------------
+// propose (APRV-445)
+// ---------------------------------------------------------------------------
+/**
+ * The largest payload `approval propose` and `approval start` accept, in UTF-8
+ * bytes of the JSON text as the caller sent it: 256 KiB.
+ *
+ * Well under `approval serve`'s 1 MiB body cap, so the refusal a caller meets is
+ * this named one rather than a transport's. A proposal is a sentence or a
+ * paragraph a human will read on a phone; a payload this size is not one.
+ */
+export const PROPOSE_PAYLOAD_MAX_BYTES = 256 * 1024;
+/** The longest `--key` `propose` accepts, in UTF-8 bytes (APRV-445, L6). */
+export const PROPOSE_KEY_MAX_BYTES = 1024;
+/** The longest `--summary` `propose` accepts, in UTF-8 bytes (APRV-445, L6). */
+export const PROPOSE_SUMMARY_MAX_BYTES = 4096;
+/**
+ * The id after `<class>:` (APRV-445 recheck L-b): one or more printable
+ * characters, no whitespace, no control, format, private-use, unassigned or
+ * surrogate code points, so a key reads back the same in a log, a phone and a
+ * shell.
+ */
+const PROPOSE_KEY_ID = /^[^\s\p{C}]+$/u;
+/** How many times `propose` starts again on a log that moved under it (SF1). */
+const PROPOSE_MAX_ATTEMPTS = 4;
+/** `origin.app` on every envelope `propose` registers. */
+export const PROPOSE_ORIGIN_APP = "approval-propose";
+/** The task-id prefix `propose` derives under. */
+export const PROPOSE_TASK_PREFIX = "propose:";
+/**
+ * Was this task registered by `propose` (APRV-445)?
+ *
+ * A proposal's request carries `execution: "harness"` like a hook's, so the two
+ * hook-side readers of that marker (the carry and the abandoned-question sweep)
+ * ask this first: a proposal waits days for a human, is spent only by `start`,
+ * and is withdrawn only by its requester's own call.
+ */
+export function isProposalTask(task) {
+    return typeof task === "string" && task.startsWith(PROPOSE_TASK_PREFIX);
+}
+/** A concrete class, as `schema/envelope.schema.json` spells one: no wildcard. */
+const CONCRETE_CLASS = /^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/u;
+/**
+ * The task id `propose` registers under, from who is asking, the class and the
+ * key: `propose:` and the first 32 hex digits of the SHA-256 over the RFC 8785
+ * canonical JSON of `[actor, class, key]`.
+ *
+ * Deterministic, so a retry lands on the task its first attempt registered and
+ * is recognised as a retry. The ACTOR is the tenant half of the derivation: one
+ * `approval serve` process serves one store as one fixed `agent:<id>`, so within
+ * a store the actor is who the tenant's agent is, and two actors proposing the
+ * same key derive two different tasks, the second of which `register` refuses
+ * because the key is already declared under the first (`task-already-registered`).
+ * The class is in it so that the same key proposed under a second class is a
+ * different task rather than a silent re-declaration.
+ */
+export function proposedTaskId(actor, cls, actionKey) {
+    return `${PROPOSE_TASK_PREFIX}${hashOfPayload([actor, cls, actionKey]).slice(0, 32)}`;
+}
+/** The sentence a `class-not-agent-requestable` refusal says. */
+function notAgentRequestable(cls, opened) {
+    const why = !opened.explicit
+        ? `${JSON.stringify(cls)} is not a key of the policy's \`classes\` map, and propose takes only a class the operator declared by name (a wildcard rule that happens to match does not count)`
+        : opened.pattern === null
+            ? `neither ${JSON.stringify(cls)} nor any declared \`<prefix>.*\` family of it sets agent_may_request: true`
+            : `${JSON.stringify(opened.pattern)} sets agent_may_request: false`;
+    return `class ${cls} is not open to agent requests: ${why}. Nothing was registered and nothing was appended. Opening a class to agents is a policy edit (agent_may_request: true on the class or its family) and a human re-attestation (amended SPEC.md §5.2).`;
+}
+/**
+ * `approval propose` (APRV-445, amended SPEC.md §5.2): register and request one
+ * action in one call, for a requester that holds the payload inline and no file
+ * on the gate's machine.
+ *
+ * ## Why this verb may name its class when `request` may not
+ *
+ * `approval request` reads the class from the log's `task.registered` record so
+ * that an agent cannot call a `financial.spend` a `read.web`. Here the agent is
+ * also the registrant, so that rule alone would prove nothing, and the bound is
+ * the operator's instead: the class must be an EXACT key of `policy.classes`, and
+ * that key or a declared `<prefix>.*` family of it must say
+ * `agent_may_request: true`. A class reached only through a wildcard is refused,
+ * so the set of classes an agent can propose in is a set of lines the operator
+ * wrote and attested by name. What the agent chooses among them is still its own
+ * statement (SPEC.md §11.1 invariant 4 is why the choice is bounded at all), and
+ * an operator opening two classes of different autonomy to agents is trusting
+ * the agent to pick the right one; the record names the class it picked.
+ *
+ * ## Order
+ *
+ * Attestation, then the agent-requestability gate and the class's own autonomy
+ * (`human-only`, an unruled `harness.launch.*`), all BEFORE anything is
+ * registered, so a refused class leaves no registration behind. Then the
+ * registration, then {@link request} with `agentProposal: true`, which repeats
+ * the gate against the bytes its own attempt reads. `execution: "harness"` on the
+ * request: nothing ever presents a token for a proposal, the requester proceeds
+ * on the grant itself and records that with `approval start`, so a minted token
+ * would be a live credential with no spender.
+ *
+ * ## Idempotency
+ *
+ * The task id is {@link proposedTaskId}. A second call with the same actor,
+ * class, key and payload hash finds its own registration and appends nothing
+ * while the request is live or decided, answering with the request's state and
+ * `idempotent: true`. A withdrawn or expired request (a re-attestation voids
+ * pending requests as `policy-drift`) is asked again under the same registration.
+ * The same key with DIFFERENT bytes refuses: `duplicate-request` while a request
+ * is live, `payload-mismatch` otherwise, because a key is bound to the bytes it
+ * was first registered with and new bytes need a new key.
+ */
+export function propose(logPath, input, actor, options = {}, attempt = 0, appendedEarlier = false) {
+    // APRV-445 recheck (SF1). Every decision below is re-checked by the append
+    // it leads to (`withdraw` with `onlyIfVoid`, `request` with
+    // `agentProposal`), so a caller that read a stale log is refused there
+    // rather than writing over a concurrent caller. A refusal of that kind means
+    // the log moved under this call; the call starts again from a fresh read, a
+    // bounded number of times, and answers what it then finds.
+    const again = (refusal) => attempt < PROPOSE_MAX_ATTEMPTS
+        ? propose(logPath, input, actor, options, attempt + 1, appendedEarlier || withdrewNow || registeredNow)
+        : refuse("contended", `the log moved under propose on each of its ${String(PROPOSE_MAX_ATTEMPTS + 1)} attempts for ${input.actionKey} (last refusal: ${refusal.code}); nothing more was appended. Read the proposal's standing with \`approval wait <task> --timeout 0\`, or call again.`);
+    if (!isPrincipalActor(actor)) {
+        return refuse("actor-invalid", `propose requires a human: or agent: actor, got ${JSON.stringify(actor)}`);
+    }
+    if (!CONCRETE_CLASS.test(input.cls)) {
+        return refuse("envelope-invalid", `class ${JSON.stringify(input.cls)} is not a concrete action class: lowercase dot-separated segments of [a-z0-9_-], no wildcard. Nothing was registered and nothing was appended.`);
+    }
+    if (input.actionKey.length === 0) {
+        return refuse("envelope-invalid", "the action key is empty; nothing was registered and nothing was appended.");
+    }
+    // APRV-445 refutation (S4): the key carries its class, so a consumer that
+    // parses the key can never attribute it to a class its record does not name.
+    // Consumers read the class from the record; this keeps the key from lying.
+    if (!input.actionKey.startsWith(`${input.cls}:`) ||
+        !PROPOSE_KEY_ID.test(input.actionKey.slice(input.cls.length + 1))) {
+        return refuse("key-class-mismatch", `key ${JSON.stringify(input.actionKey)} is not ${JSON.stringify(`${input.cls}:`)} followed by an identifier of printable characters with no whitespace or control characters; a proposal's key names the class it is proposed under. Nothing was registered and nothing was appended.`);
+    }
+    if (Buffer.byteLength(input.actionKey, "utf8") > PROPOSE_KEY_MAX_BYTES) {
+        return refuse("envelope-invalid", `the key is over ${String(PROPOSE_KEY_MAX_BYTES)} bytes; nothing was registered and nothing was appended.`);
+    }
+    if (Buffer.byteLength(input.summary, "utf8") > PROPOSE_SUMMARY_MAX_BYTES) {
+        return refuse("envelope-invalid", `the summary is over ${String(PROPOSE_SUMMARY_MAX_BYTES)} bytes; nothing was registered and nothing was appended.`);
+    }
+    let hash;
+    try {
+        hash = hashOfPayload(input.payload);
+    }
+    catch (cause) {
+        return refuse("payload-store-failed", `the payload for ${input.actionKey} could not be canonicalized: ${cause instanceof Error ? cause.message : String(cause)}. Nothing was registered and nothing was appended.`);
+    }
+    const task = proposedTaskId(actor, input.cls, input.actionKey);
+    const read = readGateRecords(logPath);
+    if (!read.ok)
+        return read;
+    const policyRead = readPolicyOnce(options);
+    const attested = requireAttestation(read.records, policyRead);
+    if (!attested.ok)
+        return attested;
+    const load = parsePolicy(policyRead, options);
+    const opened = agentRequestability(load, input.cls);
+    const resolution = resolve(load, input.cls);
+    if (!opened.allowed && !(opened.humanOnly && opened.explicit && opened.pattern !== null)) {
+        return refuse("class-not-agent-requestable", notAgentRequestable(input.cls, opened));
+    }
+    if (harnessLaunchNeedsRule(input.cls, resolution)) {
+        return refuse("harness-launch-unruled", harnessLaunchUnruledRefusal(input.cls, `the proposal ${input.actionKey} was not registered and nothing was appended`));
+    }
+    if (resolution.autonomy === "human-only") {
+        return refuse("class-human-only", humanOnlyRefusal(input.cls, `the proposal ${input.actionKey} was not registered and nothing was appended`));
+    }
+    const answered = (decision, state, seq, idempotent) => ({
+        ok: true,
+        task,
+        actionKey: input.actionKey,
+        cls: input.cls,
+        payloadHash: hash,
+        decision,
+        state,
+        seq,
+        idempotent: idempotent && !appendedEarlier,
+    });
+    const existing = registeredAction(read.records, task, input.actionKey);
+    let registeredNow = false;
+    let withdrewNow = false;
+    if (existing.ok) {
+        const derivation = requestState(read.records, input.actionKey, tick(options), ttlOf(load));
+        if (existing.action.payload_hash !== hash) {
+            if (derivation.state === "requested") {
+                return refuse("duplicate-request", `action ${input.actionKey} already has a live request at seq ${String(derivation.requestSeq)} awaiting a decision, over different bytes (${String(existing.action.payload_hash)}; this call presents ${hash}). A key is bound to the bytes it was first proposed with: wait for that request, withdraw it, or propose the new bytes under a new key. Nothing was appended.`, { state: derivation.state });
+            }
+            return refuse("payload-mismatch", `action ${input.actionKey} is registered under task ${task} with payload ${String(existing.action.payload_hash)}, and this call presents ${hash}. A key is bound to the bytes it was first proposed with; propose new bytes under a new key. Nothing was appended.`, { state: derivation.state });
+        }
+        // APRV-445 refutation (B1): the retry is judged by what the request still
+        // AUTHORIZES, not by what it recorded. A live question, a usable grant, a
+        // human's no and a started execution are answered from the log and append
+        // nothing. A question that can no longer be answered usefully is asked
+        // again under the same registration: a lapsed or withdrawn request, a grant
+        // whose window ran out (a tap at hour 71 of 72 authorizes nothing at 73),
+        // and a grant or pending request pinned to a policy that has since been
+        // re-attested (`void`: the spend and the decision both refuse it).
+        const standing = requestStanding(read.records, input.actionKey, tick(options), ttlOf(load), attested.sha256);
+        const seqOf = derivation.decisionSeq ?? derivation.requestSeq;
+        if (standing === "executed") {
+            return answered(derivation.requestSeq !== null
+                ? "requested"
+                : resolution.autonomy === "autonomous"
+                    ? "autonomous"
+                    : "supervised", "executed", seqOf, true);
+        }
+        if (standing === "requested" ||
+            standing === "granted" ||
+            standing === "rejected" ||
+            standing === "revoked") {
+            return answered("requested", standing, seqOf, true);
+        }
+        if (standing === "void" && derivation.state === "requested") {
+            // A pending question no human may decide any more. Taken back by its own
+            // requester (the gate's only way to end a request early that is not a
+            // decision), then asked again below.
+            const retracted = withdraw(logPath, input.actionKey, actor, {
+                ...options,
+                onlyIfVoid: true,
+                reason: "superseded",
+                note: "the policy this proposal was routed under has been re-attested, so the request is void; the same proposal is asked again under the policy in force",
+            });
+            if (!retracted.ok) {
+                // A concurrent caller withdrew it, re-asked it, or a human answered it.
+                if (retracted.code === "request-withdrawn" ||
+                    retracted.code === "already-decided" ||
+                    retracted.code === "duplicate-request" ||
+                    retracted.code === "expired") {
+                    return again(retracted);
+                }
+                return retracted;
+            }
+            withdrewNow = true;
+        }
+    }
+    else if (existing.code === "not-registered") {
+        const registered = register(logPath, {
+            task,
+            envelope: {
+                origin: { app: PROPOSE_ORIGIN_APP, created_by: actor },
+                state: "proposed",
+                actions: [
+                    {
+                        class: input.cls,
+                        summary: input.summary,
+                        idempotency_key: input.actionKey,
+                        payload_hash: hash,
+                    },
+                ],
+            },
+        }, actor, { ...options, proposal: true });
+        if (!registered.ok) {
+            // APRV-445 (L5). Two identical proposals racing: the other one registered
+            // this exact task first. Its registration is ours byte for byte, so the
+            // call is a retry and is answered as one.
+            if (registered.code === "task-already-registered")
+                return again(registered);
+            return registered;
+        }
+        registeredNow = true;
+    }
+    else {
+        // The derived task exists and declares some other key: nothing `propose`
+        // registers looks like that, so somebody else registered this id.
+        return refuse("task-already-registered", `task ${task} is already registered without action ${input.actionKey}; propose registers each derived task with exactly one action, so this id was registered by something else and is not reused. Nothing was appended.`);
+    }
+    const result = request(logPath, {
+        task,
+        actionKey: input.actionKey,
+        cls: input.cls,
+        summary: input.summary,
+        payload_hash: hash,
+        payload: { value: input.payload },
+        execution: "harness",
+        agentProposal: true,
+    }, actor, options);
+    if (!result.ok) {
+        if (result.code === "duplicate-request" || result.code === "already-decided" || result.code === "already-executed") {
+            return again(result);
+        }
+        return result;
+    }
+    if (result.record === null) {
+        return answered(result.autonomy === "autonomous" ? "autonomous" : "supervised", null, null, 
+        // APRV-445 recheck (L-a): a call that withdrew a void request appended
+        // something, so it is not an idempotent answer.
+        !registeredNow && !withdrewNow);
+    }
+    return answered("requested", "requested", result.record.seq, false);
+}
+/**
+ * `approval start <task> --action <key> --payload-json <json>` (APRV-445): record
+ * the `execution.started` for an action its requester is about to carry out
+ * itself, outside any harness hook.
+ *
+ * Until this verb an agent holding only the serve agent credential could ask and
+ * wait, and could not say that it then acted: `approval run` spawns argv on the
+ * gate's machine, and the harness hook writes starts only for tool calls it
+ * classified. A proposal the policy authorizes outright (`autonomous`,
+ * `supervised`) therefore left no record at all, and one a human granted left a
+ * grant nobody spent, so a second publication of the same key was indistinguishable
+ * from the first.
+ *
+ * It adds no authority. It writes through the two existing spenders and through
+ * nothing else: {@link consumeHarnessGrant} when the key carries a request (it
+ * refuses unless that request is granted, unexpired, harness-executed and
+ * unspent, under the policy it was asked under), and {@link startHarnessExecution}
+ * when it carries none (it refuses a `manual` or `human-only` class, an escalated
+ * loop and a spent key, and charges the budgets). Both pin the single-use rule:
+ * a second start of one key is `already-executed`.
+ *
+ * Two checks of its own, both before either spender runs. REQUESTER-ONLY: the
+ * actor must be the one that registered the task (`not-requester` otherwise), as
+ * `withdraw` is, so an agent cannot spend or exhaust a key someone else declared.
+ * And the bytes: the caller presents the payload it is about to act on, and its
+ * hash must equal the registered `payload_hash` (`payload-mismatch` otherwise),
+ * so the thing done is the thing that was approved, which the grant path checks
+ * again against the grant's own binding.
+ */
+export function startProposed(logPath, task, actionKey, payload, actor, options = {}) {
+    if (!isPrincipalActor(actor)) {
+        return refuse("actor-invalid", `start requires a human: or agent: actor, got ${JSON.stringify(actor)}`);
+    }
+    let hash;
+    try {
+        hash = hashOfPayload(payload);
+    }
+    catch (cause) {
+        return refuse("payload-store-failed", `the payload for ${actionKey} could not be canonicalized: ${cause instanceof Error ? cause.message : String(cause)}. Nothing was appended.`);
+    }
+    if (!isProposalTask(task)) {
+        return refuse("task-not-proposal", `task ${task} was not registered by \`approval propose\`; start records the executions of proposals only. Nothing was appended.`);
+    }
+    const read = readGateRecords(logPath);
+    if (!read.ok)
+        return read;
+    const declared = registeredAction(read.records, task, actionKey);
+    if (!declared.ok)
+        return declared;
+    let registrant = null;
+    for (const record of read.records) {
+        if (record.event === "task.registered" && record.task === task)
+            registrant = record.actor;
+    }
+    if (registrant !== actor) {
+        return refuse("not-requester", `task ${task} was registered by ${String(registrant)}, and only its registrant may record that it is carrying the action out; ${actor} may not. Nothing was appended.`);
+    }
+    if (declared.action.payload_hash !== hash) {
+        return refuse("payload-mismatch", `the payload presented for ${actionKey} hashes to ${hash}, but the action is registered with ${String(declared.action.payload_hash)}. What is carried out must be the bytes that were proposed; nothing was appended.`);
+    }
+    // APRV-445 refutation (S5). Only a request that can still answer binds the
+    // key to the grant path: one that is pending (spending it refuses until a
+    // human decides) or granted and unspent. A withdrawn, expired, rejected or
+    // revoked request says nothing about an action the policy authorizes on its
+    // own now, so after a re-tiering to autonomous the start is the policy's.
+    // This read only routes; the policy path re-judges inside its own append
+    // (`proposalPolicyStartRefusal`): a live request, a human's no under the
+    // policy in force, and a selected supervised-live draw each refuse there.
+    const derivation = requestState(read.records, actionKey, tick(options), ttlOf(parsePolicy(readPolicyOnce(options), options)));
+    const binding = derivation.execution.started === null &&
+        (derivation.state === "requested" || derivation.state === "granted");
+    if (binding) {
+        const spent = consumeHarnessGrant(logPath, actionKey, actor, {
+            ...options,
+            presentedPayloadHash: hash,
+            spendingTask: task,
+        });
+        if (!spent.ok)
+            return spent;
+        return { ok: true, task, actionKey, cls: declared.action.class, authorization: "grant", record: spent.record };
+    }
+    const started = startHarnessExecution(logPath, {
+        task,
+        actionKey,
+        cls: declared.action.class,
+        payload_hash: hash,
+        ...(declared.action.est_cost_usd === undefined ? {} : { est_cost_usd: declared.action.est_cost_usd }),
+    }, actor, options);
+    if (!started.ok)
+        return started;
+    return { ok: true, task, actionKey, cls: declared.action.class, authorization: "policy", record: started.record };
+}
+export function requestStanding(records, actionKey, ts, ttlMs, attestedSha256) {
+    const derivation = requestState(records, actionKey, ts, ttlMs);
+    if (derivation.execution.started !== null)
+        return "executed";
+    if (derivation.state === "granted") {
+        if (grantLapsed(derivation, ts))
+            return "expired";
+        // APRV-445 recheck (B). A grant is void only where its SPEND refuses
+        // `policy-drift`, which is the harness spend (`consumeHarnessGrant`) and
+        // therefore every proposal. A token grant is spent by `approval run`
+        // through `consumeToken`, which does not compare policy hashes, so after a
+        // re-attest that grant still runs: calling it void would abort the
+        // documented `wait && run` flow and send an agent to ask again over a live
+        // human grant.
+        const driftEnforced = derivation.declared.execution === "harness" || isProposalTask(derivation.task);
+        const pinned = grantedPolicyHash(records, derivation.decisionSeq) ?? derivation.declared.policy_sha256;
+        if (driftEnforced && attestedSha256 !== null && pinned !== null && pinned !== attestedSha256) {
+            return "void";
+        }
+        return "granted";
+    }
+    if (derivation.state === "requested") {
+        const pinned = derivation.declared.policy_sha256;
+        if (attestedSha256 !== null && pinned !== null && pinned !== attestedSha256)
+            return "void";
+        return "requested";
+    }
+    if (derivation.state === "withdrawn" && derivation.decisionSeq !== null) {
+        for (const record of records) {
+            if (record.seq !== derivation.decisionSeq)
+                continue;
+            if (payloadOf(record)["reason"] === "policy-drift")
+                return "void";
+        }
+    }
+    return derivation.state;
+}
+/**
+ * The SHA-256 the live policy bytes are attested under, or `null` when they are
+ * not attested (unread, unattested, or changed since). One read of the file
+ * through the same seam every gate operation uses.
+ */
+export function attestedPolicySha256(records, options = {}) {
+    const attested = requireAttestation(records, readPolicyOnce(options));
+    return attested.ok ? attested.sha256 : null;
+}
 //# sourceMappingURL=gate.js.map