@dharma-ai-labs/agent-fabric-task-runner 0.1.5 → 0.1.7

package/dist/index.js

@@ -1,10 +1,18 @@
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
 import { isAbsolute, relative, resolve } from 'node:path';
-import { validateTaskEnvelopeContract, verifyCanonicalObject } from '@dharma-ai-labs/agent-fabric-contracts';
+import { buildActionDecisionAcknowledgement, validateActionDecisionAcknowledgementContract, validateTaskEnvelopeContract, verifyActionDecisionReceipt, verifyCanonicalObject, } from '@dharma-ai-labs/agent-fabric-contracts';
 import { assertPathWithinWorkspace, resolveRegisteredCommand } from '@dharma-ai-labs/agent-fabric-policy';
 import { executeProviderTask, } from '@dharma-ai-labs/agent-fabric-provider-adapters';
+export class ActionDecisionDeniedError extends Error {
+    receipt;
+    constructor(message, receipt) {
+        super(message);
+        this.receipt = receipt;
+        this.name = 'ActionDecisionDeniedError';
+    }
+}
 function normalizePolicyPath(value) {
     return value.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
 }
@@ -132,6 +140,48 @@ export function providerInstructionsForTask(task) {
         throw new Error('A2A provider instructions exceed the execution limit.');
     return instructions;
 }
+function receiptForDurableStorage(receipt) {
+    return {
+        ...receipt,
+        commandResults: receipt.commandResults.map((result) => ({ ...result, stdout: '', stderr: '' })),
+    };
+}
+function assertValidTaskReceipt(value, expectedTaskId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Task receipt is invalid.');
+    const receipt = value;
+    if (typeof receipt.taskId !== 'string' || !/^[0-9a-f-]{36}$/i.test(receipt.taskId)
+        || (expectedTaskId && receipt.taskId !== expectedTaskId)
+        || !['completed', 'failed', 'cancelled'].includes(String(receipt.status))
+        || typeof receipt.worktree !== 'string' || !isAbsolute(receipt.worktree)
+        || receipt.branch !== `dharma/task/${receipt.taskId}`
+        || !Array.isArray(receipt.commandResults) || receipt.commandResults.length > 100
+        || !Number.isFinite(Date.parse(String(receipt.startedAt || '')))
+        || !Number.isFinite(Date.parse(String(receipt.completedAt || '')))
+        || Date.parse(String(receipt.completedAt)) < Date.parse(String(receipt.startedAt))) {
+        throw new Error('Task receipt is invalid.');
+    }
+    for (const result of receipt.commandResults) {
+        if (!result || typeof result !== 'object' || Array.isArray(result))
+            throw new Error('Task receipt command result is invalid.');
+        const command = result;
+        if (typeof command.commandId !== 'string' || command.commandId.length < 1 || command.commandId.length > 200
+            || !(command.exitCode === null || Number.isInteger(command.exitCode))
+            || !(command.signal === null || typeof command.signal === 'string')
+            || typeof command.timedOut !== 'boolean'
+            || !/^sha256:[a-f0-9]{64}$/.test(String(command.stdoutSha256 || ''))
+            || !/^sha256:[a-f0-9]{64}$/.test(String(command.stderrSha256 || ''))
+            || typeof command.stdout !== 'string' || typeof command.stderr !== 'string') {
+            throw new Error('Task receipt command result is invalid.');
+        }
+    }
+    if (receipt.actionAcknowledgement !== undefined) {
+        const acknowledgement = validateActionDecisionAcknowledgementContract(receipt.actionAcknowledgement);
+        if (!acknowledgement.ok || receipt.actionAcknowledgement.taskId !== receipt.taskId) {
+            throw new Error('Task receipt action acknowledgement is invalid.');
+        }
+    }
+}
 export class FileTaskReceiptStore {
     directory;
     constructor(directory) {
@@ -139,7 +189,9 @@ export class FileTaskReceiptStore {
     }
     async get(taskId) {
         try {
-            return JSON.parse(await readFile(resolve(this.directory, `${taskId}.json`), 'utf8'));
+            const receipt = JSON.parse(await readFile(resolve(this.directory, `${taskId}.json`), 'utf8'));
+            assertValidTaskReceipt(receipt, taskId);
+            return receipt;
         }
         catch (error) {
             if (error.code === 'ENOENT')
@@ -148,15 +200,302 @@ export class FileTaskReceiptStore {
         }
     }
     async put(receipt) {
-        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        assertValidTaskReceipt(receipt, receipt.taskId);
         const target = resolve(this.directory, `${receipt.taskId}.json`);
-        const temp = `${target}.${process.pid}.tmp`;
-        await writeFile(temp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
-        await rename(temp, target);
+        await durableJsonWrite(target, receiptForDurableStorage(receipt));
+    }
+}
+async function durableJsonWrite(path, value) {
+    const directory = resolve(path, '..');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temp, 'wx', 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(value)}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(temp, path);
+    try {
+        const directoryHandle = await open(directory, 'r');
+        try {
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    catch {
+        // Directory fsync is unavailable on some supported hosts; the file itself
+        // has still been flushed before the atomic rename.
+    }
+}
+export class FileActionExecutionJournal {
+    directory;
+    pid;
+    now;
+    ownerId = randomUUID();
+    constructor(directory, pid = process.pid, now = () => new Date()) {
+        this.directory = directory;
+        this.pid = pid;
+        this.now = now;
+    }
+    recordPath(taskId) { return resolve(this.directory, `${taskId}.json`); }
+    claimPath(taskId) { return resolve(this.directory, `${taskId}.claim.json`); }
+    async get(taskId) {
+        try {
+            const record = JSON.parse(await readFile(this.recordPath(taskId), 'utf8'));
+            if (record.schema !== 'dharma.action-execution-journal/v1' || record.taskId !== taskId
+                || !/^[0-9a-f-]{36}$/i.test(record.taskId)
+                || !/^[0-9a-f-]{36}$/i.test(record.decisionId) || !/^[0-9a-f-]{36}$/i.test(record.endpointId)
+                || !/^sha256:[a-f0-9]{64}$/.test(record.actionDigest)
+                || typeof record.externalIdempotencyKey !== 'string' || !record.externalIdempotencyKey
+                || typeof record.worktree !== 'string' || !isAbsolute(record.worktree)
+                || record.branch !== `dharma/task/${record.taskId}`
+                || !['prepared', 'replay_authorization_started', 'replay_authorized', 'executing', 'effect_observed', 'receipt_recorded'].includes(record.state)
+                || !Number.isFinite(Date.parse(record.preparedAt)) || !Number.isFinite(Date.parse(record.updatedAt))
+                || (record.providerResultDigest !== undefined && !/^sha256:[a-f0-9]{64}$/.test(record.providerResultDigest))) {
+                throw new Error('Action execution journal record is invalid.');
+            }
+            if (record.state === 'receipt_recorded' && !record.receipt) {
+                throw new Error('Action execution journal is missing its recorded receipt.');
+            }
+            if (record.receipt) {
+                assertValidTaskReceipt(record.receipt, taskId);
+                const acknowledgement = record.receipt.actionAcknowledgement;
+                if (acknowledgement
+                    && (acknowledgement.endpointId !== record.endpointId || acknowledgement.actionDigest !== record.actionDigest)) {
+                    throw new Error('Action execution journal receipt conflicts with the signed decision.');
+                }
+            }
+            return record;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async getClaim(taskId) {
+        try {
+            const claim = JSON.parse(await readFile(this.claimPath(taskId), 'utf8'));
+            if (claim.schema !== 'dharma.action-execution-claim/v1' || claim.taskId !== taskId
+                || !/^[0-9a-f-]{36}$/i.test(claim.taskId) || !/^[0-9a-f-]{36}$/i.test(claim.decisionId)
+                || !/^sha256:[a-f0-9]{64}$/.test(claim.actionDigest)
+                || typeof claim.ownerId !== 'string' || !Number.isInteger(claim.pid) || claim.pid <= 0
+                || !Number.isFinite(Date.parse(claim.claimedAt)) || !Number.isFinite(Date.parse(claim.expiresAt))
+                || Date.parse(claim.expiresAt) <= Date.parse(claim.claimedAt)) {
+                throw new Error('Action execution claim is invalid.');
+            }
+            return claim;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async prepare(input) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const now = this.now().toISOString();
+        const record = {
+            schema: 'dharma.action-execution-journal/v1', ...input,
+            state: 'prepared', preparedAt: now, updatedAt: now,
+        };
+        try {
+            const handle = await open(this.recordPath(input.taskId), 'wx', 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            return { record, created: true };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await this.get(input.taskId);
+            if (!existing
+                || existing.decisionId !== input.decisionId
+                || existing.endpointId !== input.endpointId
+                || existing.actionDigest !== input.actionDigest
+                || existing.externalIdempotencyKey !== input.externalIdempotencyKey
+                || existing.worktree !== input.worktree
+                || existing.branch !== input.branch) {
+                throw new Error('Action execution journal conflicts with the signed task.');
+            }
+            return { record: existing, created: false };
+        }
+    }
+    async transition(taskId, allowed, state, patch = {}) {
+        const current = await this.get(taskId);
+        if (!current || !allowed.includes(current.state)) {
+            throw new Error(`Action execution journal transition to ${state} is invalid.`);
+        }
+        const next = { ...current, ...patch, state, updatedAt: this.now().toISOString() };
+        await durableJsonWrite(this.recordPath(taskId), next);
+        return next;
+    }
+    async claim(record, maximumAgeMs) {
+        if (record.state !== 'replay_authorized')
+            throw new Error('Action execution is not authorized for claiming.');
+        const boundedAgeMs = Math.min(Math.max(maximumAgeMs, 1), 24 * 60 * 60_000);
+        const claim = {
+            schema: 'dharma.action-execution-claim/v1', taskId: record.taskId,
+            decisionId: record.decisionId, actionDigest: record.actionDigest,
+            ownerId: this.ownerId, pid: this.pid, claimedAt: this.now().toISOString(),
+            expiresAt: new Date(this.now().getTime() + boundedAgeMs).toISOString(),
+        };
+        const handle = await open(this.claimPath(record.taskId), 'wx', 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(claim)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await this.transition(record.taskId, ['replay_authorized'], 'executing');
+        return claim;
+    }
+    isClaimOwnerAlive(claim) {
+        if (Date.parse(claim.expiresAt) <= this.now().getTime())
+            return false;
+        if (claim.ownerId === this.ownerId && claim.pid === this.pid)
+            return true;
+        try {
+            process.kill(claim.pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === 'EPERM';
+        }
+    }
+    async recordEffectObserved(taskId, providerResult) {
+        await this.transition(taskId, ['executing'], 'effect_observed', {
+            providerResultDigest: `sha256:${createHash('sha256').update(JSON.stringify(providerResult)).digest('hex')}`,
+        });
+    }
+    async recordReceipt(receipt) {
+        assertValidTaskReceipt(receipt, receipt.taskId);
+        await this.transition(receipt.taskId, [
+            'prepared', 'replay_authorization_started', 'replay_authorized', 'executing', 'effect_observed',
+        ], 'receipt_recorded', { receipt: receiptForDurableStorage(receipt) });
+        await rm(this.claimPath(receipt.taskId), { force: true });
+    }
+    async selfTest() {
+        const path = resolve(this.directory, `.self-test-${randomUUID()}.json`);
+        try {
+            await durableJsonWrite(path, { schema: 'dharma.action-execution-journal-self-test/v1' });
+            const value = JSON.parse(await readFile(path, 'utf8'));
+            if (value.schema !== 'dharma.action-execution-journal-self-test/v1')
+                throw new Error('Journal self-test readback failed.');
+        }
+        finally {
+            await rm(path, { force: true });
+        }
+    }
+}
+export class FileActionDecisionReplayGuard {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
     }
+    async consume(decisionId, actionDigest) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const target = resolve(this.directory, `${decisionId}.json`);
+        try {
+            const handle = await open(target, 'wx', 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({
+                    decisionId,
+                    actionDigest,
+                    consumedAt: new Date().toISOString(),
+                })}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+}
+export function canonicalTaskActionForTask(task, actionId) {
+    if (!task.target.endpointId)
+        throw new Error('Receipt-required task target endpoint is unavailable.');
+    return {
+        schema: 'dharma.task-action/v1',
+        organizationId: task.organizationId,
+        actionId,
+        taskId: task.taskId,
+        targetEndpointId: task.target.endpointId,
+        workspaceId: task.workspaceId,
+        taskType: task.taskType,
+        instructions: task.instructions,
+        requiredSkills: task.requiredSkills,
+        authority: task.authority,
+        execution: task.execution,
+        acceptance: task.acceptance,
+        budget: task.budget,
+        expiresAt: task.expiresAt,
+    };
+}
+export async function authorizeEmbeddedActionDecision(input) {
+    const receipt = verifyEmbeddedActionDecision(input.task, input.receiver);
+    const envelope = input.task.actionDecision;
+    if (!await input.replayGuard.consume(envelope.id, envelope.actionDigest)) {
+        throw new Error('Action-decision receipt replay was rejected.');
+    }
+    if (receipt.outcome !== 'release') {
+        throw new ActionDecisionDeniedError(`Action-decision outcome ${receipt.outcome} denied execution.`, receipt);
+    }
+    return receipt;
+}
+export function verifyEmbeddedActionDecision(task, receiver) {
+    const envelope = task.actionDecision;
+    if (!envelope)
+        throw new Error('Embedded action-decision receipt is unavailable; execution is denied.');
+    const action = canonicalTaskActionForTask(task, envelope.receipt.actionId);
+    const verification = verifyActionDecisionReceipt(envelope, action, receiver.resolvePublicKey, receiver.now?.() ?? new Date());
+    if (!verification.ok)
+        throw new Error(`Action-decision receipt is invalid: ${verification.reason}.`);
+    return envelope.receipt;
+}
+function requiresActionDecisionReceipt(task) {
+    return task.requiredCapabilities?.includes('action_decision_receipts_v1') ?? false;
+}
+function interruptedActionReceipt(record, now) {
+    const commandResults = [{
+            commandId: 'runner', exitCode: null, signal: null, timedOut: false,
+            stdoutSha256: `sha256:${'0'.repeat(64)}`,
+            stderrSha256: `sha256:${createHash('sha256').update('External effect outcome is unknown after receiver restart.').digest('hex')}`,
+            stdout: '', stderr: 'External effect outcome is unknown after receiver restart; execution was not repeated.',
+        }];
+    return {
+        taskId: record.taskId, status: 'failed', worktree: record.worktree, branch: record.branch,
+        commandResults,
+        actionAcknowledgement: buildActionDecisionAcknowledgement({
+            taskId: record.taskId, endpointId: record.endpointId, actionDigest: record.actionDigest,
+            disposition: 'unknown', externalIdempotencyKey: record.externalIdempotencyKey,
+            result: { status: 'failed', recovery: 'abandoned_execution_claim', commandResults },
+        }, now),
+        startedAt: record.preparedAt, completedAt: now.toISOString(),
+    };
 }
 export async function executeTask(input) {
     verifyTaskEnvelope(input.task, input.serverPublicKey);
+    const taskExpiresAt = Date.parse(input.task.expiresAt);
+    const remainingTaskMs = () => taskExpiresAt - Date.now();
+    if (!Number.isFinite(taskExpiresAt) || remainingTaskMs() <= 0)
+        throw new Error('Task envelope expired.');
     if (input.task.organizationId !== input.policy.organizationId)
         throw new Error('Task organization does not match policy.');
     const previous = await input.receiptStore.get(input.task.taskId);
@@ -175,96 +514,226 @@ export async function executeTask(input) {
         if (!allowed.has(commandId))
             throw new Error(`Acceptance command is outside task authority: ${commandId}`);
     }
+    const receiptRequired = requiresActionDecisionReceipt(input.task);
+    const journal = input.actionExecutionJournal
+        ?? new FileActionExecutionJournal(resolve(input.relayStateDirectory, 'action-execution-journal'));
     const worktreeRoot = resolve(input.relayStateDirectory, 'worktrees');
     const worktree = assertContained(worktreeRoot, resolve(worktreeRoot, input.task.taskId));
     const branch = `dharma/task/${input.task.taskId}`;
-    await mkdir(worktreeRoot, { recursive: true, mode: 0o700 });
-    await rm(worktree, { recursive: true, force: true });
-    await git(input.workspace, ['worktree', 'add', '--detach', worktree, 'HEAD']);
-    await git(worktree, ['switch', '-c', branch]);
-    const startingCommit = (await gitOutput(worktree, ['rev-parse', 'HEAD'])).trim();
+    let decisionReceipt = null;
+    let journalRecord = null;
+    let executionClaimed = false;
+    let contained = false;
     const startedAt = new Date().toISOString();
-    const commandResults = [];
-    let status = 'completed';
-    try {
-        const allowedCommands = input.task.authority.commands.map(({ commandId }) => resolveRegisteredCommand(input.policy, commandId).argv);
-        const providerResult = await (input.providerExecutor ?? executeProviderTask)({
-            provider: input.task.target.provider,
-            workspace: worktree,
-            instructions: providerInstructionsForTask(input.task),
-            timeoutSeconds: input.task.execution.timeoutSeconds,
-            allowedCommandArgv: allowedCommands,
-            allowWrites: input.task.authority.writePaths.length > 0,
-            signal: input.signal,
+    if (receiptRequired) {
+        if (!input.actionDecisions)
+            throw new Error('Action-decision public key resolver is unavailable; execution is denied.');
+        if (!input.task.target.endpointId)
+            throw new Error('Receipt-required task target endpoint is unavailable.');
+        decisionReceipt = verifyEmbeddedActionDecision(input.task, input.actionDecisions);
+        const prepared = await journal.prepare({
+            taskId: input.task.taskId, decisionId: decisionReceipt.decisionId,
+            endpointId: input.task.target.endpointId, actionDigest: decisionReceipt.actionDigest,
+            externalIdempotencyKey: decisionReceipt.decisionId, worktree, branch,
         });
-        commandResults.push({
-            commandId: `provider.${input.task.target.provider}`,
-            exitCode: providerResult.exitCode,
-            signal: providerResult.signal,
-            timedOut: providerResult.timedOut,
-            stdout: providerResult.stdout,
-            stderr: providerResult.stderr,
-            stdoutSha256: providerResult.stdoutSha256,
-            stderrSha256: providerResult.stderrSha256,
-        });
-        if (providerResult.exitCode !== 0 || providerResult.timedOut)
-            status = input.signal?.aborted ? 'cancelled' : 'failed';
-        const trackedChanges = await gitOutput(worktree, [
-            'diff', '--name-only', '--diff-filter=ACDMRTUXB', startingCommit, '--',
-        ]);
-        const untrackedChanges = await gitOutput(worktree, ['ls-files', '--others', '--exclude-standard']);
-        const changedPaths = `${trackedChanges}\n${untrackedChanges}`
-            .split(/\r?\n/)
-            .map((path) => path.trim())
-            .filter(Boolean);
-        if (changedPaths.length > 0) {
-            const writes = input.task.authority.writePaths;
-            if (writes.length === 0 || changedPaths.some((path) => !pathWithinPolicy(path, writes))) {
-                throw new Error('Provider changed a path outside the signed task authority.');
+        journalRecord = prepared.record;
+        if (journalRecord.state === 'receipt_recorded') {
+            if (!journalRecord.receipt)
+                throw new Error('Action execution journal is missing its recorded receipt.');
+            await input.receiptStore.put(journalRecord.receipt);
+            return journalRecord.receipt;
+        }
+        const priorClaim = await journal.getClaim(input.task.taskId);
+        if (priorClaim) {
+            if (priorClaim.decisionId !== journalRecord.decisionId || priorClaim.actionDigest !== journalRecord.actionDigest) {
+                throw new Error('Action execution claim conflicts with the signed decision.');
+            }
+            if (journal.isClaimOwnerAlive(priorClaim))
+                throw new Error('Action execution is already in progress.');
+            const recovered = interruptedActionReceipt(journalRecord, input.actionDecisions.now?.() ?? new Date());
+            await journal.recordReceipt(recovered);
+            await input.receiptStore.put(recovered);
+            return recovered;
+        }
+        if (journalRecord.state === 'replay_authorization_started'
+            || journalRecord.state === 'executing'
+            || journalRecord.state === 'effect_observed') {
+            const recovered = interruptedActionReceipt(journalRecord, input.actionDecisions.now?.() ?? new Date());
+            await journal.recordReceipt(recovered);
+            await input.receiptStore.put(recovered);
+            return recovered;
+        }
+        if (decisionReceipt.outcome !== 'release') {
+            contained = true;
+        }
+        else if (journalRecord.state === 'prepared') {
+            if (input.actionDecisions.replayGuard) {
+                journalRecord = await journal.transition(input.task.taskId, ['prepared'], 'replay_authorization_started');
+                if (!await input.actionDecisions.replayGuard.consume(decisionReceipt.decisionId, decisionReceipt.actionDigest)) {
+                    throw new Error('Action-decision receipt replay was rejected.');
+                }
+                journalRecord = await journal.transition(input.task.taskId, ['replay_authorization_started'], 'replay_authorized');
+            }
+            else {
+                journalRecord = await journal.transition(input.task.taskId, ['prepared'], 'replay_authorized');
             }
         }
-        for (const { commandId } of input.task.acceptance.commands) {
-            if (status !== 'completed')
-                break;
-            if (input.signal?.aborted) {
-                status = 'cancelled';
-                break;
+        if (!contained) {
+            if (journalRecord.state !== 'replay_authorized')
+                throw new Error('Action execution journal is not ready for execution.');
+            try {
+                await journal.claim(journalRecord, Math.min((input.task.execution.timeoutSeconds + input.task.execution.leaseSeconds + 300) * 1_000, remainingTaskMs()));
+                executionClaimed = true;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                throw new Error('Action execution is already claimed by another receiver.');
             }
-            const command = resolveRegisteredCommand(input.policy, commandId);
-            const cwd = command.workingDirectory
-                ? assertPathWithinWorkspace(worktree, command.workingDirectory)
-                : worktree;
-            const [executable, ...argv] = command.argv;
-            const result = await runProcess(executable, argv, {
-                cwd,
-                timeoutMs: Math.min(command.timeoutSeconds, input.task.execution.timeoutSeconds) * 1_000,
+        }
+    }
+    const commandResults = [];
+    let status = contained ? 'failed' : 'completed';
+    if (contained && decisionReceipt) {
+        commandResults.push({
+            commandId: 'runner', exitCode: null, signal: null, timedOut: false,
+            stdoutSha256: `sha256:${'0'.repeat(64)}`,
+            stderrSha256: `sha256:${createHash('sha256').update(`Action-decision outcome ${decisionReceipt.outcome} denied execution.`).digest('hex')}`,
+            stdout: '', stderr: `Action-decision outcome ${decisionReceipt.outcome} denied execution.`,
+        });
+    }
+    if (!contained) {
+        try {
+            await mkdir(worktreeRoot, { recursive: true, mode: 0o700 });
+            await rm(worktree, { recursive: true, force: true });
+            await git(input.workspace, ['worktree', 'add', '--detach', worktree, 'HEAD']);
+            await git(worktree, ['switch', '-c', branch]);
+            const startingCommit = (await gitOutput(worktree, ['rev-parse', 'HEAD'])).trim();
+            const allowedCommands = input.task.authority.commands.map(({ commandId }) => resolveRegisteredCommand(input.policy, commandId).argv);
+            const providerInstructions = providerInstructionsForTask(input.task);
+            const providerTimeBudgetSeconds = Math.min(input.task.execution.timeoutSeconds, Math.floor(remainingTaskMs() / 1_000));
+            if (providerTimeBudgetSeconds < 1)
+                throw new Error('Task expires before provider execution can start.');
+            const providerInput = {
+                provider: input.task.target.provider,
+                workspace: worktree,
+                instructions: providerInstructions,
+                timeoutSeconds: providerTimeBudgetSeconds,
+                allowedCommandArgv: allowedCommands,
+                allowWrites: input.task.authority.writePaths.length > 0,
+                ...(decisionReceipt ? {
+                    externalIdempotencyKey: decisionReceipt.decisionId,
+                    actionDigest: decisionReceipt.actionDigest,
+                } : {}),
                 signal: input.signal,
+            };
+            const providerResult = await (input.providerExecutor ?? executeProviderTask)(providerInput);
+            if (remainingTaskMs() <= 0)
+                throw new Error('Task expired during provider execution.');
+            if (executionClaimed)
+                await journal.recordEffectObserved(input.task.taskId, providerResult);
+            commandResults.push({
+                commandId: `provider.${input.task.target.provider}`,
+                exitCode: providerResult.exitCode,
+                signal: providerResult.signal,
+                timedOut: providerResult.timedOut,
+                stdout: providerResult.stdout,
+                stderr: providerResult.stderr,
+                stdoutSha256: providerResult.stdoutSha256,
+                stderrSha256: providerResult.stderrSha256,
             });
-            commandResults.push({ commandId, ...result });
-            if (result.exitCode !== 0 || result.timedOut) {
+            if (providerResult.exitCode !== 0 || providerResult.timedOut)
                 status = input.signal?.aborted ? 'cancelled' : 'failed';
-                break;
+            const trackedChanges = await gitOutput(worktree, [
+                'diff', '--name-only', '--diff-filter=ACDMRTUXB', startingCommit, '--',
+            ]);
+            const untrackedChanges = await gitOutput(worktree, ['ls-files', '--others', '--exclude-standard']);
+            const changedPaths = `${trackedChanges}\n${untrackedChanges}`
+                .split(/\r?\n/)
+                .map((path) => path.trim())
+                .filter(Boolean);
+            if (changedPaths.length > 0) {
+                const writes = input.task.authority.writePaths;
+                if (writes.length === 0 || changedPaths.some((path) => !pathWithinPolicy(path, writes))) {
+                    throw new Error('Provider changed a path outside the signed task authority.');
+                }
+            }
+            for (const { commandId } of input.task.acceptance.commands) {
+                if (status !== 'completed')
+                    break;
+                if (input.signal?.aborted) {
+                    status = 'cancelled';
+                    break;
+                }
+                const command = resolveRegisteredCommand(input.policy, commandId);
+                const cwd = command.workingDirectory
+                    ? assertPathWithinWorkspace(worktree, command.workingDirectory)
+                    : worktree;
+                const [executable, ...argv] = command.argv;
+                const acceptanceTimeBudgetMs = remainingTaskMs();
+                if (acceptanceTimeBudgetMs <= 0)
+                    throw new Error('Task expired before acceptance verification.');
+                const result = await runProcess(executable, argv, {
+                    cwd,
+                    timeoutMs: Math.min(command.timeoutSeconds * 1_000, input.task.execution.timeoutSeconds * 1_000, acceptanceTimeBudgetMs),
+                    signal: input.signal,
+                });
+                if (remainingTaskMs() <= 0)
+                    throw new Error('Task expired during acceptance verification.');
+                commandResults.push({ commandId, ...result });
+                if (result.exitCode !== 0 || result.timedOut) {
+                    status = input.signal?.aborted ? 'cancelled' : 'failed';
+                    break;
+                }
             }
         }
+        catch (error) {
+            status = input.signal?.aborted ? 'cancelled' : 'failed';
+            commandResults.push({
+                commandId: 'runner', exitCode: null, signal: null, timedOut: false,
+                stdoutSha256: `sha256:${'0'.repeat(64)}`,
+                stderrSha256: `sha256:${createHash('sha256').update(String(error)).digest('hex')}`,
+                stdout: '', stderr: error instanceof Error ? error.message : String(error),
+            });
+        }
     }
-    catch (error) {
-        status = input.signal?.aborted ? 'cancelled' : 'failed';
+    if (receiptRequired && !contained && status === 'completed' && input.task.authority.network !== 'deny') {
+        const message = 'Provider completion cannot prove an external network effect without a provider-specific effect receipt.';
+        status = 'failed';
         commandResults.push({
             commandId: 'runner', exitCode: null, signal: null, timedOut: false,
             stdoutSha256: `sha256:${'0'.repeat(64)}`,
-            stderrSha256: `sha256:${createHash('sha256').update(String(error)).digest('hex')}`,
-            stdout: '', stderr: error instanceof Error ? error.message : String(error),
+            stderrSha256: `sha256:${createHash('sha256').update(message).digest('hex')}`,
+            stdout: '', stderr: message,
         });
     }
+    const actionAcknowledgement = decisionReceipt && input.task.target.endpointId
+        ? buildActionDecisionAcknowledgement({
+            taskId: input.task.taskId,
+            endpointId: input.task.target.endpointId,
+            actionDigest: decisionReceipt.actionDigest,
+            disposition: contained ? 'contained' : status === 'completed' ? 'executed' : 'unknown',
+            externalIdempotencyKey: decisionReceipt.decisionId,
+            result: {
+                status,
+                commandResults: commandResults.map(({ commandId, exitCode, signal, timedOut, stdoutSha256, stderrSha256 }) => ({
+                    commandId, exitCode, signal, timedOut, stdoutSha256, stderrSha256,
+                })),
+            },
+        }, input.actionDecisions?.now?.() ?? new Date())
+        : undefined;
     const receipt = {
         taskId: input.task.taskId,
         status,
         worktree,
         branch,
         commandResults,
+        ...(actionAcknowledgement ? { actionAcknowledgement } : {}),
         startedAt,
         completedAt: new Date().toISOString(),
     };
+    if (receiptRequired)
+        await journal.recordReceipt(receipt);
     await input.receiptStore.put(receipt);
     return receipt;
 }