@melra/runtime-core 0.3.0-alpha.12 → 0.3.0-alpha.13

package/README.md

@@ -10,8 +10,9 @@ npm install @melra/runtime-core
 
 `TaskController` owns the pipeline. `plan()` classifies the operation, evaluates
 policy, persists a `TaskRecord`, and returns any approval challenge — it never
-executes. `execute()` re-evaluates policy, validates the approval, runs the
-adapter under an `AbortSignal` armed with the duration budget, then verifies.
+executes. `execute()` re-evaluates policy, validates the approval (or, in
+enforced mode, requires an operator's out-of-band decision), runs the adapter
+under an `AbortSignal` armed with the duration budget, then verifies.
 
 Verification decides success, not the adapter. A task reaches
 `verified_success` only when the adapter succeeded *and* every declared evidence

package/dist/task-controller.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalResponse, EffectContract, EvidencePredicate, Operation, PolicyDecision, TaskRecord, TaskRequest } from "@melra/protocol";
+import type { ApprovalDecision, ApprovalResponse, EffectContract, EvidencePredicate, Operation, PolicyDecision, TaskRecord, TaskRequest } from "@melra/protocol";
 import { type CapabilityUsageReader, type LocalPolicy } from "@melra/policy-core";
 import { type ActionReceipt, type EvidenceItem, type ExecutionCertificate } from "@melra/receipt-schema";
 import { SqliteStore } from "@melra/storage-sqlite";
@@ -18,6 +18,12 @@ export interface ExecutionResult {
 export interface TaskPlanOptions {
     idempotencyKey?: string;
     attempt?: number;
+    /**
+     * Planned again from a workflow definition stored when it was accepted.
+     * Checks that only govern new work (an unused browser list) are not applied
+     * again, so a run accepted before a check existed does not stop mid-way.
+     */
+    stored?: boolean;
 }
 /**
  * A grant's durable draw-down, the way policy wants to read it.
@@ -35,6 +41,8 @@ export declare class TaskController {
     private readonly payloadCipher;
     private readonly active;
     private readonly breaker;
+    /** Whether approvals come only from an operator, out of band. */
+    get enforced(): boolean;
     constructor(store: SqliteStore, policy: LocalPolicy, executor: OperationExecutor, verifier: Verifier, payloadCipher: PayloadCipher, breaker?: CircuitBreaker);
     /**
      * The durable draw-down on each grant, as policy sees it.
@@ -45,10 +53,24 @@ export declare class TaskController {
      * with a way around it.
      */
     private readonly capabilityUsage;
+    /**
+     * Draws by tasks between their re-check and their record, per grant and
+     * task. The durable draw is written only once work is verified, so without
+     * this two tasks running at once both saw the grant unspent: two operations
+     * against `maxOperations: 1`, a parallel workflow node overspending
+     * `dailyMax`.
+     *
+     * ponytail: held in this process. Two servers sharing one database can
+     * still both pass a re-check at the same moment; a durable reservation row
+     * would close that if it ever matters.
+     */
+    private readonly reserved;
     plan(request: TaskRequest, options?: TaskPlanOptions): TaskRecord & {
         contract: EffectContract;
     };
-    preflight(request: TaskRequest): PolicyDecision;
+    preflight(request: TaskRequest, options?: {
+        stored?: boolean;
+    }): PolicyDecision;
     status(taskId: string): TaskRecord;
     execute(taskId: string, approval?: ApprovalResponse): Promise<ExecutionResult>;
     cancel(taskId: string): TaskRecord;
@@ -83,7 +105,57 @@ export declare class TaskController {
      * or an effect settled this way would be free to run again and free to spend.
      */
     private resolveAsVerified;
-    recoverInterrupted(): Promise<TaskRecord[]>;
+    /**
+     * With `failed`, each task that could not be recovered is recorded there by
+     * id instead of the first failure being thrown at the end.
+     */
+    recoverInterrupted(failed?: Map<string, unknown>): Promise<TaskRecord[]>;
+    private recoverTask;
+    /**
+     * What an approver is shown: the effect contract, minus the challenge and
+     * the policy verdict, which a recheck at execution rewrites. Its digest is
+     * what a decision is bound to, so a request that changed after it was
+     * shown cannot run on that decision.
+     */
+    private approvalRender;
+    /** A pending challenge as an operator surface shows it. */
+    approvalView(taskId: string): {
+        contract: {
+            contractVersion: string;
+            taskId: string;
+            identity: import("@melra/protocol").Identity;
+            capability: string;
+            operation: Operation;
+            effect: import("@melra/protocol").Effect;
+            risk: import("@melra/protocol").Risk;
+            target: string;
+            traits: import("@melra/protocol").CapabilityTrait[];
+            executionGuarantee: import("@melra/protocol").ExecutionGuarantee;
+            forbiddenEffects: import("@melra/protocol").Effect[];
+            postconditions: EvidencePredicate[];
+            budget: import("@melra/protocol").TaskBudget;
+            idempotencyKey?: string;
+            metadata: {
+                goal: string;
+            };
+        };
+        renderDigest: string;
+        task: TaskRecord;
+    };
+    /**
+     * Records an approver's yes to exactly the render they were shown. Never
+     * executes, and never touches the task row: the decision lives in its own
+     * insert-once table, and `execute` reads it. `out_of_band` only in enforced
+     * mode, where nothing the agent saw could have produced it.
+     */
+    decide(taskId: string, renderDigest: string, approver: string): ApprovalDecision;
+    /** The recorded decision for a pending task, while it can still be used. */
+    approvalDecision(task: TaskRecord): ApprovalDecision | undefined;
+    /**
+     * Made before the challenge expired, and used within a TTL of being made:
+     * an answer that came in time is not lost to the time it takes to act on.
+     */
+    private usable;
     receipts(input: {
         taskId?: string;
         receiptId?: string;
@@ -91,6 +163,12 @@ export declare class TaskController {
         receipts: ActionReceipt[];
         certificate?: ExecutionCertificate;
     };
+    /**
+     * The mode a task's effect ran under: recorded when it started running, or,
+     * for a task that started before that was recorded, the mode on its first
+     * receipt.
+     */
+    private runMode;
     private createReceipt;
     private loadRequest;
     private executeWithRetries;

package/dist/task-controller.d.ts.map

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

package/dist/task-controller.js

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 import { randomUUID } from "node:crypto";
 import { allowsRetry, delegationChain, effectContract, executionGuaranteeFor, isOutcomeUnknown, LOCAL_IDENTITY, TaskRequestSchema, } from "@melra/protocol";
-import { CAPABILITY_DAY_MS, classifyOperation, defaultEvidenceFor, evaluatePolicy, validateApproval, } from "@melra/policy-core";
-import { createCertificate, createReceiptId, evidenceStrength, redactStructuredValue, sha256, } from "@melra/receipt-schema";
+import { approvalTtl, CAPABILITY_DAY_MS, classifyOperation, defaultEvidenceFor, evaluatePolicy, validateApproval, } from "@melra/policy-core";
+import { createCertificate, createReceiptId, evidenceStrength, redactSecrets, redactStructuredValue, sha256, } from "@melra/receipt-schema";
 import { CircuitBreaker } from "./circuit-breaker.js";
 function now() {
     return new Date().toISOString();
@@ -83,6 +83,12 @@ export function capabilityUsageReader(store) {
         return { operations: drawn.operations, amountToday: drawn.amountInWindow };
     };
 }
+/** The one browser action that reads each list. */
+const BROWSER_LIST_ACTIONS = [
+    ["values", "select"],
+    ["fields", "fill_form"],
+    ["filePaths", "upload"],
+];
 export class TaskController {
     store;
     policy;
@@ -91,6 +97,10 @@ export class TaskController {
     payloadCipher;
     active = new Map();
     breaker;
+    /** Whether approvals come only from an operator, out of band. */
+    get enforced() {
+        return this.policy.mode === "enforced";
+    }
     constructor(store, policy, executor, verifier, payloadCipher, breaker) {
         this.store = store;
         this.policy = policy;
@@ -112,7 +122,26 @@ export class TaskController {
      * preflight — a bound that only one of the three enforced would be a bound
      * with a way around it.
      */
-    capabilityUsage = (grantId) => capabilityUsageReader(this.store)(grantId);
+    capabilityUsage = (grantId) => {
+        const drawn = capabilityUsageReader(this.store)(grantId);
+        const held = [...(this.reserved.get(grantId)?.values() ?? [])];
+        return {
+            operations: drawn.operations + held.length,
+            amountToday: drawn.amountToday + held.reduce((total, amount) => total + amount, 0),
+        };
+    };
+    /**
+     * Draws by tasks between their re-check and their record, per grant and
+     * task. The durable draw is written only once work is verified, so without
+     * this two tasks running at once both saw the grant unspent: two operations
+     * against `maxOperations: 1`, a parallel workflow node overspending
+     * `dailyMax`.
+     *
+     * ponytail: held in this process. Two servers sharing one database can
+     * still both pass a re-check at the same moment; a durable reservation row
+     * would close that if it ever matters.
+     */
+    reserved = new Map();
     plan(request, options = {}) {
         const parsedRequest = withDefaultEvidence(TaskRequestSchema.parse(request));
         if (options.idempotencyKey !== undefined &&
@@ -123,7 +152,7 @@ export class TaskController {
             (!Number.isInteger(options.attempt) || options.attempt < 1)) {
             throw new Error("idempotency_attempt_invalid");
         }
-        this.preflight(parsedRequest);
+        this.preflight(parsedRequest, options);
         const id = randomUUID();
         const policy = evaluatePolicy(id, parsedRequest, this.policy, this.capabilityUsage);
         const timestamp = now();
@@ -160,13 +189,22 @@ export class TaskController {
             contract: effectContract(planned, classifyOperation(parsedRequest.operation)),
         };
     }
-    preflight(request) {
+    preflight(request, options = {}) {
         const parsed = withDefaultEvidence(TaskRequestSchema.parse(request));
         const capabilities = this.executor.capabilities?.();
         if (capabilities !== undefined &&
             !capabilities.has(parsed.operation.kind)) {
             throw new Error(`operation_capability_unavailable:${parsed.operation.kind}`);
         }
+        // A list the browser action never reads would sit in the approval as a
+        // decoy: shown to the person approving, doing nothing.
+        if (parsed.operation.kind === "browser" && options.stored !== true) {
+            for (const [field, action] of BROWSER_LIST_ACTIONS) {
+                if (parsed.operation[field] !== undefined && parsed.operation.action !== action) {
+                    throw new Error(`browser_field_unused:${field}`);
+                }
+            }
+        }
         // Refused before anything is approved: a mutation run against evidence no
         // registered verifier can check would end `partial` after the effect.
         for (const predicate of parsed.requiredEvidence) {
@@ -225,22 +263,71 @@ export class TaskController {
                 task.approval?.actionDigest !== rechecked.challenge.actionDigest) {
                 throw new Error("approval_action_digest_mismatch");
             }
-            const approvalResult = validateApproval(task.approval, approval);
-            if (!approvalResult.ok) {
-                throw new Error(approvalResult.reason);
+            // Enforced mode asserts the agent holds no credential, so anything it
+            // sends is refused rather than ignored, and only an operator's
+            // out-of-band decision lets the effect run.
+            if (this.policy.mode === "enforced" && approval !== undefined) {
+                throw new Error("approval_in_band_refused");
+            }
+            // A decision an operator recorded wins over anything the caller sent.
+            const render = this.approvalRender(task, request).renderDigest;
+            const decision = this.store.getApprovalDecision(task.approval.approvalId);
+            // Waiting is only worth it while an operator could still say yes:
+            // `decide` refuses an expired challenge, so past it the task is re-planned.
+            if (this.policy.mode === "enforced" && decision?.channel !== "out_of_band") {
+                throw new Error(Date.parse(task.approval.expiresAt) <= Date.now() ? "approval_expired" : "approval_awaiting_operator");
+            }
+            if (decision !== undefined) {
+                if (decision.renderDigest !== render)
+                    throw new Error("approval_render_mismatch");
+                if (!this.usable(task, decision))
+                    throw new Error("approval_expired");
+                // Out of band is this kernel's claim to make, not the row's: a
+                // developer-mode kernel cannot vouch that nothing the agent touched
+                // wrote it, whatever mode the process that recorded it was in.
+                task.approvedBy = {
+                    ...decision,
+                    channel: decision.channel === "out_of_band" && this.policy.mode === "enforced"
+                        ? "out_of_band"
+                        : "in_band",
+                };
+            }
+            else {
+                const approvalResult = validateApproval(task.approval, approval);
+                if (!approvalResult.ok) {
+                    throw new Error(approvalResult.reason);
+                }
+                // The phrase is derivable by anyone who knows the task, so an echo of
+                // it says only that something echoed it.
+                task.approvedBy = {
+                    approvalId: task.approval.approvalId,
+                    taskId: task.id,
+                    renderDigest: render,
+                    channel: "in_band",
+                    approver: "phrase",
+                    decidedAt: now(),
+                };
             }
         }
         task.policyDecision = rechecked.decision;
         const controller = new AbortController();
         this.active.set(task.id, controller);
+        this.store.inFlight.add(task.id);
         task.status = "running";
+        task.mode = this.policy.mode;
         task.updatedAt = now();
-        this.store.saveTask(task);
+        // Status and owner land in one write, so no running row is ever unowned.
+        this.store.saveTask(task, this.store.ownerId());
         const startedAt = now();
         const classified = classifyOperation(request.operation);
         let timeout;
         let budgetExhausted = false;
         let shortCircuited = false;
+        if (rechecked.grantId !== undefined) {
+            const held = this.reserved.get(rechecked.grantId) ?? new Map();
+            held.set(task.id, classified.spend?.amount ?? 0);
+            this.reserved.set(rechecked.grantId, held);
+        }
         try {
             const opened = this.breaker.check(classified.target);
             if (opened !== undefined) {
@@ -295,7 +382,7 @@ export class TaskController {
                 rechecked.grantId !== undefined) {
                 this.store.recordCapabilityUse(rechecked.grantId, task.id, classified.spend?.amount ?? 0, now());
             }
-            const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, startedAt, actionSucceeded, result, evidence, approval);
+            const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, startedAt, actionSucceeded, result, evidence);
             this.store.saveReceipt(receipt);
             task.receiptIds.push(receipt.receiptId);
             if (task.status !== "cancelled") {
@@ -352,7 +439,7 @@ export class TaskController {
                         : message,
                 },
             ];
-            const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, startedAt, false, {}, evidence, approval, task.error);
+            const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, startedAt, false, {}, evidence, task.error);
             this.store.saveReceipt(receipt);
             task.receiptIds.push(receipt.receiptId);
             this.store.saveTask(task);
@@ -363,6 +450,9 @@ export class TaskController {
             if (timeout !== undefined)
                 clearTimeout(timeout);
             this.active.delete(task.id);
+            this.store.inFlight.delete(task.id);
+            if (rechecked.grantId !== undefined)
+                this.reserved.get(rechecked.grantId)?.delete(task.id);
         }
     }
     cancel(taskId) {
@@ -436,7 +526,7 @@ export class TaskController {
         task.error = "reconciliation_confirms_effect_not_applied";
         task.updatedAt = now();
         this.store.saveTask(task);
-        const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, task.updatedAt, false, { reconciliation: "provider_state_denies_effect" }, verification.evidence, undefined, task.error);
+        const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, task.updatedAt, false, { reconciliation: "provider_state_denies_effect" }, verification.evidence, task.error);
         this.store.saveReceipt(receipt);
         task.receiptIds.push(receipt.receiptId);
         const certificate = this.createAndSaveCertificate(task, verification.evidence);
@@ -456,15 +546,18 @@ export class TaskController {
             this.store.commitIdempotency(task.idempotencyKey, task.id, task.attempt ?? 1, now());
         }
         // Read for the grant id only. The work is already done, so this is
-        // accounting rather than permission — a grant that has since run out still
-        // pays for what it authorised.
-        const { grantId } = evaluatePolicy(task.id, request, this.policy, this.capabilityUsage);
+        // accounting rather than permission: a grant that has since run out still
+        // pays for what it authorised. Asked as if nothing were drawn, because
+        // policy names no grant at all for one that is now exhausted, and the
+        // effect then went uncharged.
+        const { grantId } = evaluatePolicy(task.id, request, this.policy, () => ({
+            operations: 0,
+            amountToday: 0,
+        }));
         if (grantId !== undefined) {
             this.store.recordCapabilityUse(grantId, task.id, classified.spend?.amount ?? 0, now());
         }
-        const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, task.updatedAt, true, observed, evidence, task.approval === undefined
-            ? undefined
-            : { approvalId: task.approval.approvalId, phrase: "recovered" });
+        const receipt = this.createReceipt(task, request, classified.capability, classified.target, classified.effect, task.updatedAt, true, observed, evidence);
         this.store.saveReceipt(receipt);
         task.receiptIds.push(receipt.receiptId);
         task.status = "verified_success";
@@ -473,43 +566,156 @@ export class TaskController {
         const certificate = this.createAndSaveCertificate(task, evidence);
         return { task, receipt, certificate };
     }
-    async recoverInterrupted() {
+    /**
+     * With `failed`, each task that could not be recovered is recorded there by
+     * id instead of the first failure being thrown at the end.
+     */
+    async recoverInterrupted(failed) {
         const recovered = [];
-        for (const task of this.store.listInterruptedTasks()) {
-            const request = this.loadRequest(task.id);
-            const classified = classifyOperation(request.operation);
-            if (task.status === "verifying" &&
-                classified.effect !== "read" &&
-                request.requiredEvidence.length > 0 &&
-                request.requiredEvidence.every((predicate) => ["file_exists", "file_absent", "file_hash"].includes(predicate.type))) {
-                const verification = await this.verifier.verify(request.requiredEvidence, {});
-                if (verification.verified) {
-                    this.resolveAsVerified(task, request, classified, verification.evidence, {
-                        recovery: "independent_reobservation",
-                    });
-                    recovered.push(task);
-                    continue;
+        const failures = failed ?? new Map();
+        for (const listed of this.store.listInterruptedTasks()) {
+            // Only tasks whose owning process is gone, and only once: a live peer's
+            // work is left to finish. This process's own rows are taken too when
+            // nothing here has them in flight, so a task whose final write failed,
+            // or whose recovery threw after the claim, is retried by the next pass
+            // instead of waiting for a restart.
+            const task = this.store.claimInterruptedTask(listed.id);
+            if (task === undefined)
+                continue;
+            this.store.inFlight.add(task.id);
+            try {
+                recovered.push(await this.recoverTask(task));
+            }
+            catch (error) {
+                // One task that cannot be recovered must not keep the rest waiting;
+                // the failure is still reported once every task has had its turn.
+                failures.set(task.id, error);
+                // Given back rather than kept: held by this live process, no other
+                // could take it, so an advance elsewhere could never learn why its
+                // run is stuck. Whoever claims it next meets the same failure.
+                try {
+                    this.store.releaseTaskClaim(task.id);
+                }
+                catch {
+                    // Still ours, then; this process retakes it on its next pass.
                 }
             }
-            const effect = classified.effect;
-            task.status = effect === "read" ? "planned" : "recovery_required";
-            task.error =
-                effect === "read"
-                    ? "interrupted_read_ready_for_retry"
-                    : "interrupted_mutation_requires_reconciliation";
-            task.updatedAt = now();
-            this.store.saveTask(task);
-            // A crash mid-flight is the same unknown a dropped reply is, so a task
-            // that declared how to settle one gets asked here rather than waiting for
-            // someone to notice it. Still parked if the provider cannot answer.
-            if (task.status === "recovery_required" && request.reconciliation.length > 0) {
-                recovered.push((await this.reconcile(task.id)).task);
-                continue;
+            finally {
+                this.store.inFlight.delete(task.id);
             }
-            recovered.push(task);
         }
+        if (failed === undefined && failures.size > 0)
+            throw failures.values().next().value;
         return recovered;
     }
+    async recoverTask(task) {
+        const request = this.loadRequest(task.id);
+        const classified = classifyOperation(request.operation);
+        if (task.status === "verifying" &&
+            classified.effect !== "read" &&
+            request.requiredEvidence.length > 0 &&
+            request.requiredEvidence.every((predicate) => ["file_exists", "file_absent", "file_hash"].includes(predicate.type))) {
+            // What the adapter reported before the crash, when it got that far.
+            // Evidence alone is not success: a build that exited 1 beside a dist/
+            // left by an earlier one would otherwise recover as verified.
+            const sealed = this.store.getTaskResult(task.id);
+            const reported = sealed === undefined
+                ? undefined
+                : this.payloadCipher.open(sealed, `task:${task.id}:result`);
+            const actionSucceeded = reported?.success !== false;
+            const verification = await this.verifier.verify(request.requiredEvidence, {});
+            if (actionSucceeded && verification.verified) {
+                this.resolveAsVerified(task, request, classified, verification.evidence, {
+                    recovery: "independent_reobservation",
+                });
+                return task;
+            }
+        }
+        const effect = classified.effect;
+        task.status = effect === "read" ? "planned" : "recovery_required";
+        task.error =
+            effect === "read"
+                ? "interrupted_read_ready_for_retry"
+                : "interrupted_mutation_requires_reconciliation";
+        task.updatedAt = now();
+        this.store.saveTask(task);
+        // A crash mid-flight is the same unknown a dropped reply is, so a task
+        // that declared how to settle one gets asked here rather than waiting for
+        // someone to notice it. Still parked if the provider cannot answer.
+        if (task.status === "recovery_required" && request.reconciliation.length > 0) {
+            return (await this.reconcile(task.id)).task;
+        }
+        return task;
+    }
+    /**
+     * What an approver is shown: the effect contract, minus the challenge and
+     * the policy verdict, which a recheck at execution rewrites. Its digest is
+     * what a decision is bound to, so a request that changed after it was
+     * shown cannot run on that decision.
+     */
+    approvalRender(task, request) {
+        const { authorization: _authorization, policy: _policy, ...contract } = effectContract({ ...task, request }, classifyOperation(request.operation));
+        return { contract, renderDigest: sha256(contract) };
+    }
+    /** A pending challenge as an operator surface shows it. */
+    approvalView(taskId) {
+        const task = this.status(taskId);
+        if (task.status !== "awaiting_approval" || task.approval === undefined) {
+            throw new Error(`task_not_awaiting_approval:${task.status}`);
+        }
+        return { task, ...this.approvalRender(task, this.loadRequest(taskId)) };
+    }
+    /**
+     * Records an approver's yes to exactly the render they were shown. Never
+     * executes, and never touches the task row: the decision lives in its own
+     * insert-once table, and `execute` reads it. `out_of_band` only in enforced
+     * mode, where nothing the agent saw could have produced it.
+     */
+    decide(taskId, renderDigest, approver) {
+        const { task, renderDigest: current } = this.approvalView(taskId);
+        // No phrase means an enforced kernel planned it, and would refuse this
+        // in-band decision while the insert-once row kept anyone from correcting it.
+        if (this.policy.mode !== "enforced" && task.approval.phrase === undefined) {
+            throw new Error("approval_needs_enforced_mode");
+        }
+        if (Date.parse(task.approval.expiresAt) <= Date.now())
+            throw new Error("approval_expired");
+        if (renderDigest !== current)
+            throw new Error("approval_render_mismatch");
+        const decision = {
+            approvalId: task.approval.approvalId,
+            taskId,
+            renderDigest,
+            channel: this.policy.mode === "enforced" ? "out_of_band" : "in_band",
+            approver,
+            decidedAt: now(),
+        };
+        if (!this.store.recordApprovalDecision(decision))
+            throw new Error("approval_already_decided");
+        return decision;
+    }
+    /** The recorded decision for a pending task, while it can still be used. */
+    approvalDecision(task) {
+        if (task.approval === undefined)
+            return undefined;
+        const decision = this.store.getApprovalDecision(task.approval.approvalId);
+        if (decision === undefined || !this.usable(task, decision))
+            return undefined;
+        // In enforced mode an in-band row is no decision at all, so a workflow node
+        // waits for an operator and is re-planned at expiry instead of failing on
+        // every advance.
+        return this.policy.mode === "enforced" && decision.channel !== "out_of_band" ? undefined : decision;
+    }
+    /**
+     * Made before the challenge expired, and used within a TTL of being made:
+     * an answer that came in time is not lost to the time it takes to act on.
+     */
+    usable(task, decision) {
+        const decidedAt = Date.parse(decision.decidedAt);
+        return (task.approval !== undefined &&
+            decidedAt <= Date.parse(task.approval.expiresAt) &&
+            Date.now() < decidedAt + approvalTtl(this.policy));
+    }
     receipts(input) {
         if (input.receiptId !== undefined) {
             const receipt = this.store.getReceipt(input.receiptId);
@@ -530,7 +736,23 @@ export class TaskController {
             ...(certificate === undefined ? {} : { certificate }),
         };
     }
-    createReceipt(task, request, capability, target, effect, startedAt, success, result, evidence, approval, error) {
+    /**
+     * The mode a task's effect ran under: recorded when it started running, or,
+     * for a task that started before that was recorded, the mode on its first
+     * receipt.
+     */
+    runMode(task) {
+        if (task.mode !== undefined)
+            return task.mode;
+        const [first] = task.receiptIds;
+        return first === undefined ? undefined : this.store.getReceipt(first)?.mode;
+    }
+    createReceipt(task, request, capability, target, effect, startedAt, success, result, evidence, error) {
+        // From the task, not the caller: recovery and reconciliation write
+        // receipts with no caller in sight. A task running since before
+        // `approvedBy` existed still names the challenge it was planned under.
+        const approvalId = task.approvedBy?.approvalId ??
+            (task.policyDecision.outcome === "confirm" ? task.approval?.approvalId : undefined);
         const sanitized = redactStructuredValue(result);
         const adapterRedactions = Array.isArray(result.redactions)
             ? result.redactions.filter((item) => typeof item === "string")
@@ -546,13 +768,25 @@ export class TaskController {
             principal: delegationChain(request.identity ?? LOCAL_IDENTITY),
             effect,
             executionGuarantee: executionGuaranteeFor(effect, request.reconciliation.length > 0),
-            mode: this.policy.mode,
+            mode: this.runMode(task) ?? this.policy.mode,
             policyDecision: {
                 outcome: task.policyDecision.outcome,
                 policyVersion: task.policyDecision.policyVersion,
-                ...(approval === undefined ? {} : { approvalId: approval.approvalId }),
+                ...(approvalId === undefined ? {} : { approvalId }),
+                ...(task.approvedBy === undefined
+                    ? {}
+                    : {
+                        approval: {
+                            channel: task.approvedBy.channel,
+                            renderDigest: task.approvedBy.renderDigest,
+                            approver: task.approvedBy.approver,
+                            decidedAt: task.approvedBy.decidedAt,
+                        },
+                    }),
             },
-            target,
+            // The target is built from the request (a URL, a memory key) and stored
+            // as it is, so it takes the same secret shapes out as everything else.
+            target: redactSecrets(target).value,
             inputDigest: sha256(request.operation),
             startedAt,
             endedAt: now(),
@@ -603,6 +837,16 @@ export class TaskController {
             : new Error("execution_failed_without_error");
     }
     createAndSaveCertificate(task, evidence) {
+        const approvalChannel = task.approvedBy?.channel ??
+            (task.policyDecision.outcome === "allow"
+                ? task.policyDecision.effect === "read"
+                    ? "not_required"
+                    : "bypassed"
+                : undefined);
+        // Sealed, so never guessed: a task that ran says how it ran, one that
+        // never did was decided here, and one that ran before the mode was
+        // recorded and left no receipt saying so goes without.
+        const mode = this.runMode(task) ?? (task.receiptIds.length === 0 ? this.policy.mode : undefined);
         const certificate = createCertificate({
             taskId: task.id,
             goal: task.request.goal,
@@ -611,6 +855,8 @@ export class TaskController {
             receiptIds: task.receiptIds,
             evidence,
             createdAt: now(),
+            ...(mode === undefined ? {} : { mode }),
+            ...(approvalChannel === undefined ? {} : { approvalChannel }),
         });
         task.certificateId = certificate.certificateId;
         task.updatedAt = now();