@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/dist/lib/task/orchestration.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { parseReviewSummary } from './review-artifacts.js';
 import { inspectArtifactDirectory } from './artifact-lifecycle.js';
@@ -12,7 +13,12 @@ import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
 import { isAgentClientId } from '../agent-clients/types.js';
 import { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
+import { assertGitRepositoryBinding } from '../git/worktree-identity.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { CommitIntentError, commitIntentPath, createCommitIntent, digest, readCommitIntent, removeCommitIntent, removeCommitIntentByDigest, serialize, updateCommitIntent } from './commit-intent.js';
+import { inspectCommitFinalization, planCommitTaskFinalization } from './commit-finalization.js';
+import { captureTaskWriteMetadata, writeTask } from './write.js';
+import { appendActivityEntry, commitAttemptStartedNote, locateActivityLog, pairEntries } from './activity-log.js';
 function supportsLifecycleDelegation(client) {
     return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
         && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
@@ -51,12 +57,76 @@ function atomicWrite(file, value) {
 function saveRun(taskDir, run) {
     atomicWrite(orchestrationPath(taskDir), run);
 }
-function withUpdatedRun(run, updates) {
-    return Object.freeze({ ...run, ...updates, updatedAt: new Date().toISOString() });
+function withUpdatedRun(run, updates, now) {
+    return Object.freeze({ ...run, ...updates, updatedAt: (now ?? (() => new Date().toISOString()))() });
 }
 function failed(code, message, taskId = null, details = {}) {
     return { status: 'failed', changed: false, taskId, run: null, next: null, error: { code, message, ...details } };
 }
+function commitIntentFailed(code, message, taskId = null) {
+    return { status: 'failed', changed: false, taskId, intent: null, error: { code, message } };
+}
+function repositoryHead(repoRoot) {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    }).trim();
+}
+function gitRootFor(stateRoot, options) {
+    if (!options.gitWorktreeRoot)
+        return stateRoot;
+    return assertGitRepositoryBinding(stateRoot, options.gitWorktreeRoot).worktreeRoot;
+}
+function isAncestor(repoRoot, ancestor, descendant) {
+    return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+        cwd: repoRoot,
+        stdio: 'ignore'
+    }).status === 0;
+}
+function commitIntentView(intent, currentHead) {
+    return {
+        mode: intent.mode,
+        phase: intent.phase,
+        baselineHead: intent.baselineHead,
+        currentHead,
+        committedHead: intent.committedHead,
+        pushEvidence: intent.pushEvidence,
+        runId: intent.orchestration?.runId ?? null,
+        receiptId: intent.orchestration?.receiptId ?? null
+    };
+}
+function commitFinalizationView(inspection) {
+    return {
+        disposition: inspection.disposition,
+        code: inspection.code,
+        message: inspection.message,
+        currentHead: inspection.currentHead,
+        committedHead: inspection.committedHead,
+        needsAnchor: inspection.needsAnchor,
+        needsLog: inspection.needsLog,
+        attempt: inspection.attempt
+    };
+}
+function validCommitRun(run, taskId) {
+    return run !== null
+        && [1, 2].includes(run.schemaVersion)
+        && run.taskId === taskId
+        && ['running', 'paused', 'completed'].includes(run.status)
+        && Array.isArray(run.receipts)
+        && Object.prototype.hasOwnProperty.call(run, 'pendingDelegation')
+        && typeof run.commitAuthorization === 'object'
+        && run.commitAuthorization !== null
+        && Object.prototype.hasOwnProperty.call(run.commitAuthorization, 'issuedAt')
+        && Object.prototype.hasOwnProperty.call(run.commitAuthorization, 'consumedAt');
+}
+function mapCommitIntentError(error, taskId) {
+    if (error instanceof CommitIntentError)
+        return commitIntentFailed(error.code, error.message, taskId);
+    if (error instanceof TaskExecutionLockError)
+        return commitIntentFailed(error.code, error.message, taskId);
+    return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_INVALID', error instanceof Error ? error.message : String(error), taskId);
+}
 function validModel(value) {
     return typeof value === 'string' && value.length > 0 && value.trim() === value;
 }
@@ -337,6 +407,13 @@ function routeOrchestration(taskRef, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
+    let gitRoot;
+    try {
+        gitRoot = gitRootFor(resolved.repoRoot, options);
+    }
+    catch (error) {
+        return failed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
     let content;
     try {
         content = fs.readFileSync(resolved.taskMdPath, 'utf8');
@@ -407,7 +484,7 @@ function routeOrchestration(taskRef, options = {}) {
         const capture = options.captureRepository ?? captureRepositorySnapshot;
         let before;
         try {
-            before = capture(resolved.repoRoot);
+            before = capture(gitRoot);
         }
         catch (error) {
             return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -422,7 +499,7 @@ function routeOrchestration(taskRef, options = {}) {
         const inspect = options.inspectPullRequest ?? inspectPlatformPullRequest;
         let inspection;
         try {
-            inspection = inspect(resolved.taskId, { cwd: resolved.repoRoot });
+            inspection = inspect(resolved.taskId, { cwd: gitRoot });
         }
         catch (error) {
             return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -443,7 +520,7 @@ function routeOrchestration(taskRef, options = {}) {
         }
         let after;
         try {
-            after = capture(resolved.repoRoot);
+            after = capture(gitRoot);
         }
         catch (error) {
             return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -476,6 +553,401 @@ function routeOrchestration(taskRef, options = {}) {
     }
     return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
+function appendCommitActivity(resolved, step, agent, note) {
+    const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const activity = locateActivityLog(taskContent);
+    if (!activity)
+        return { code: 'ORCHESTRATION_TASK_INVALID', message: 'task activity log is missing or ambiguous' };
+    const metadata = captureTaskWriteMetadata();
+    const written = writeTask({
+        taskRef: resolved.taskId,
+        expectedState: 'active',
+        mutations: [{
+                kind: 'section',
+                aliases: ['活动日志', 'Activity Log'],
+                heading: activity.heading,
+                body: appendActivityEntry(activity, { time: metadata.timestamp, step, agent, note })
+            }]
+    }, { repoRoot: resolved.repoRoot, metadataProvider: () => metadata });
+    return written.status === 'failed' ? written.error : null;
+}
+function startCommitAttempt(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.start', () => {
+            if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
+            }
+            const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+            const activity = locateActivityLog(taskContent);
+            if (!activity)
+                return commitIntentFailed('ORCHESTRATION_TASK_INVALID', 'task activity log is missing or ambiguous', resolved.taskId);
+            const open = pairEntries(activity.entries).filter((row) => row.step === 'Commit' && row.started !== '' && row.done === '');
+            if (open.length > 0) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_ATTEMPT_BUSY', 'an open Commit activity entry already exists', resolved.taskId);
+            }
+            const currentHead = repositoryHead(gitRoot);
+            const attempt = (options.id ?? randomUUID)();
+            const error = appendCommitActivity(resolved, 'Commit [started]', input.agent, commitAttemptStartedNote({
+                attempt,
+                baseline: currentHead,
+                agent: input.agent
+            }));
+            if (error)
+                return commitIntentFailed(error.code, error.message, resolved.taskId);
+            const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+            return {
+                status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+                finalization: commitFinalizationView(inspection), error: null
+            };
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function terminateCommitAttempt(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.terminate', () => {
+            if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'an active commit intent must be aborted or recovered first', resolved.taskId);
+            }
+            const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+            if (inspection.disposition !== 'retryable-start'
+                || inspection.attempt?.attempt !== input.attempt
+                || inspection.attempt.agent !== input.agent
+                || inspection.attempt.baseline !== inspection.currentHead) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'commit attempt identity or repository HEAD has drifted', resolved.taskId);
+            }
+            const error = appendCommitActivity(resolved, 'Commit [aborted]', input.agent, `aborted; attempt=${input.attempt}; code=${input.code}`);
+            if (error)
+                return commitIntentFailed(error.code, error.message, resolved.taskId);
+            return {
+                status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+                finalization: commitFinalizationView(inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId)),
+                error: null
+            };
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function beginCommitIntent(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.begin', () => {
+            const currentHead = repositoryHead(gitRoot);
+            if (currentHead !== input.baselineHead) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_BASELINE_MISMATCH', 'baseline HEAD does not match the repository HEAD', resolved.taskId);
+            }
+            if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+                try {
+                    readCommitIntent(resolved.taskDir, resolved.taskId);
+                }
+                catch (error) {
+                    return mapCommitIntentError(error, resolved.taskId);
+                }
+                return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
+            }
+            const attemptInspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+            if (attemptInspection.disposition !== 'retryable-start'
+                || attemptInspection.attempt?.attempt !== input.attempt
+                || attemptInspection.attempt.agent !== input.agent
+                || attemptInspection.attempt.baseline !== input.baselineHead) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_ATTEMPT_MISMATCH', 'commit begin requires one matching retryable Commit attempt', resolved.taskId);
+            }
+            const runFile = orchestrationPath(resolved.taskDir);
+            let run = null;
+            let sourceRunBytes = null;
+            if (fs.existsSync(runFile)) {
+                sourceRunBytes = fs.readFileSync(runFile, 'utf8');
+                try {
+                    run = readRun(resolved.taskDir);
+                }
+                catch (error) {
+                    return commitIntentFailed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+                }
+                if (!validCommitRun(run, resolved.taskId)) {
+                    return commitIntentFailed('ORCHESTRATION_STATE_INVALID', 'orchestration state has an invalid schema', resolved.taskId);
+                }
+            }
+            const now = (options.now ?? (() => new Date().toISOString()))();
+            const failAndPause = (code, message) => {
+                if (run?.status === 'running') {
+                    saveRun(resolved.taskDir, withUpdatedRun(run, {
+                        status: 'paused', pause: { code, message, recoverable: true }
+                    }, () => now));
+                }
+                return commitIntentFailed(code, message, resolved.taskId);
+            };
+            let orchestration = null;
+            if (!input.orchestrated) {
+                if (run?.pendingDelegation) {
+                    return commitIntentFailed('ORCHESTRATION_STANDALONE_BUSY', 'standalone commit is blocked by a pending orchestration delegation', resolved.taskId);
+                }
+            }
+            else {
+                if (!run || run.status !== 'running') {
+                    return commitIntentFailed('ORCHESTRATION_RUN_NOT_RUNNING', 'orchestrated commit requires a running orchestration', resolved.taskId);
+                }
+                const receipt = run.pendingDelegation;
+                if (!receipt
+                    || receipt.status !== 'activated'
+                    || receipt.stage !== 'commit'
+                    || receipt.round !== 1
+                    || receipt.artifact !== 'commit'
+                    || receipt.role !== 'executor') {
+                    return failAndPause('ORCHESTRATION_PROVENANCE_MISMATCH', 'orchestrated commit requires one matching activated commit delegation');
+                }
+                if (!run.commitAuthorization.issuedAt || run.commitAuthorization.consumedAt) {
+                    return failAndPause('ORCHESTRATION_COMMIT_AUTHORIZATION_INVALID', 'orchestrated commit requires an unconsumed one-use authorization');
+                }
+                const planned = planOrchestrationStageCompletion(taskRef, {
+                    stage: 'commit', round: 1, artifact: 'commit', role: 'executor', agent: input.agent
+                }, { ...options, now: () => now });
+                if (planned.result.status === 'failed' || !planned.plan?.updatedRun.pendingDelegation) {
+                    return failAndPause(planned.result.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH', planned.result.error?.message ?? 'commit delegation could not be completed');
+                }
+                const plannedRunBytes = serialize(planned.plan.updatedRun);
+                orchestration = {
+                    runId: run.runId,
+                    receiptId: receipt.id,
+                    authorizationIssuedAt: run.commitAuthorization.issuedAt,
+                    sourceRunDigest: digest(sourceRunBytes),
+                    plannedRunDigest: digest(plannedRunBytes),
+                    completionUpdatedAt: planned.plan.updatedRun.updatedAt,
+                    plannedReceipt: planned.plan.updatedRun.pendingDelegation
+                };
+            }
+            const created = createCommitIntent(resolved.taskDir, {
+                taskId: resolved.taskId,
+                mode: input.orchestrated ? 'orchestrated' : 'standalone',
+                phase: 'prepared',
+                baselineHead: input.baselineHead,
+                committedHead: null,
+                pushEvidence: null,
+                orchestration,
+                createdAt: now,
+                updatedAt: now
+            }, { token: options.token });
+            return {
+                status: 'ready', changed: true, taskId: resolved.taskId,
+                intent: commitIntentView(created.intent, currentHead), token: created.token, error: null
+            };
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function checkpointCommitIntent(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.checkpoint', () => {
+            const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
+            const currentHead = repositoryHead(gitRoot);
+            if (currentHead !== input.head) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'checkpoint HEAD does not match the repository HEAD', resolved.taskId);
+            }
+            if (input.kind === 'committed' && !isAncestor(gitRoot, intent.baselineHead, input.head)) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'committed HEAD does not descend from the baseline', resolved.taskId);
+            }
+            if (input.kind === 'pushed') {
+                const expectedHead = intent.committedHead ?? intent.baselineHead;
+                if (input.head !== expectedHead || !input.remote || !input.ref) {
+                    return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_STATE_INVALID', 'pushed checkpoint requires matching remote, ref and HEAD', resolved.taskId);
+                }
+            }
+            const now = (options.now ?? (() => new Date().toISOString()))();
+            const updated = updateCommitIntent(resolved.taskDir, resolved.taskId, input.token, input.kind === 'committed'
+                ? { phase: 'committed', committedHead: input.head, updatedAt: now }
+                : {
+                    phase: 'pushed', committedHead: intent.committedHead ?? intent.baselineHead, updatedAt: now,
+                    pushEvidence: { remote: input.remote, ref: input.ref, head: input.head }
+                });
+            return {
+                status: 'ready', changed: true, taskId: resolved.taskId,
+                intent: commitIntentView(updated, currentHead), error: null
+            };
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function completeCommitOrchestration(resolved, intent, agent) {
+    if (intent.orchestration === null)
+        return null;
+    if (intent.orchestration.plannedReceipt.agent !== agent) {
+        return { code: 'ORCHESTRATION_PROVENANCE_MISMATCH', message: 'completion agent does not match the planned receipt' };
+    }
+    const runFile = orchestrationPath(resolved.taskDir);
+    if (!fs.existsSync(runFile)) {
+        return { code: 'ORCHESTRATION_RUN_MISSING', message: 'orchestration run disappeared' };
+    }
+    const currentBytes = fs.readFileSync(runFile, 'utf8');
+    const currentDigest = digest(currentBytes);
+    if (currentDigest === intent.orchestration.sourceRunDigest) {
+        const run = readRun(resolved.taskDir);
+        if (!run)
+            return { code: 'ORCHESTRATION_RUN_MISSING', message: 'orchestration run disappeared' };
+        const plannedRun = Object.freeze({
+            ...run,
+            pendingDelegation: intent.orchestration.plannedReceipt,
+            updatedAt: intent.orchestration.completionUpdatedAt
+        });
+        if (digest(serialize(plannedRun)) !== intent.orchestration.plannedRunDigest) {
+            return { code: 'ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', message: 'planned orchestration bytes no longer match the intent' };
+        }
+        atomicWrite(runFile, plannedRun);
+        if (digest(fs.readFileSync(runFile)) !== intent.orchestration.plannedRunDigest) {
+            return { code: 'ORCHESTRATION_COMMIT_COMPLETE_PARTIAL', message: 'orchestration completion could not be verified' };
+        }
+    }
+    else if (currentDigest !== intent.orchestration.plannedRunDigest) {
+        return { code: 'ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', message: 'orchestration state changed after commit begin' };
+    }
+    return null;
+}
+function finalizeCommitIntentUnlocked(resolved, inspection, agent, remove) {
+    if (inspection.disposition !== 'recoverable' || !inspection.intent) {
+        return commitIntentFailed(inspection.code ?? 'COMMIT_FINALIZATION_PENDING', inspection.message, resolved.taskId);
+    }
+    if (inspection.intent.orchestration !== null
+        && inspection.intent.orchestration.plannedReceipt.agent !== agent) {
+        return commitIntentFailed('ORCHESTRATION_PROVENANCE_MISMATCH', 'completion agent does not match the planned receipt', resolved.taskId);
+    }
+    const metadata = captureTaskWriteMetadata();
+    const taskPlan = planCommitTaskFinalization(resolved.taskDir, inspection, agent, metadata.timestamp);
+    const written = writeTask({
+        taskRef: resolved.taskId,
+        expectedState: 'active',
+        mutations: taskPlan.mutations
+    }, {
+        repoRoot: resolved.repoRoot,
+        metadataProvider: () => metadata
+    });
+    if (written.status === 'failed') {
+        return commitIntentFailed(written.error.code, written.error.message, resolved.taskId);
+    }
+    const orchestrationError = completeCommitOrchestration(resolved, inspection.intent, agent);
+    if (orchestrationError) {
+        return commitIntentFailed(orchestrationError.code, orchestrationError.message, resolved.taskId);
+    }
+    try {
+        remove();
+    }
+    catch (error) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_COMPLETE_PARTIAL', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    return { status: 'ready', changed: true, taskId: resolved.taskId, intent: null, error: null };
+}
+function completeCommitIntent(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.complete', () => {
+            readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
+            const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+            return finalizeCommitIntentUnlocked(resolved, inspection, input.agent, () => {
+                removeCommitIntent(resolved.taskDir, resolved.taskId, input.token);
+            });
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function recoverCommitIntent(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.recover', () => {
+            const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+            if (inspection.disposition === 'retryable-start') {
+                return {
+                    status: 'ready', changed: false, taskId: resolved.taskId, intent: null,
+                    finalization: commitFinalizationView(inspection), error: null
+                };
+            }
+            if (inspection.disposition === 'prepared' && inspection.intentDigest) {
+                removeCommitIntentByDigest(resolved.taskDir, resolved.taskId, inspection.intentDigest);
+                return { status: 'ready', changed: true, taskId: resolved.taskId, intent: null, error: null };
+            }
+            if (!inspection.intentDigest) {
+                return commitIntentFailed(inspection.code ?? 'COMMIT_FINALIZATION_EVIDENCE_MISSING', inspection.message, resolved.taskId);
+            }
+            return finalizeCommitIntentUnlocked(resolved, inspection, input.agent, () => {
+                removeCommitIntentByDigest(resolved.taskDir, resolved.taskId, inspection.intentDigest);
+            });
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function abortCommitIntent(taskRef, input, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    try {
+        const gitRoot = gitRootFor(resolved.repoRoot, options);
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.abort', () => {
+            const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
+            const currentHead = repositoryHead(gitRoot);
+            if (intent.phase !== 'prepared'
+                || intent.pushEvidence !== null
+                || input.expectedHead !== intent.baselineHead
+                || currentHead !== intent.baselineHead) {
+                return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'commit intent has side effects or repository drift', resolved.taskId);
+            }
+            removeCommitIntent(resolved.taskDir, resolved.taskId, input.token);
+            return { status: 'ready', changed: true, taskId: resolved.taskId, intent: null, error: null };
+        });
+    }
+    catch (error) {
+        return mapCommitIntentError(error, resolved.taskId);
+    }
+}
+function statusCommitIntent(taskRef, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+    let gitRoot;
+    try {
+        gitRoot = gitRootFor(resolved.repoRoot, options);
+    }
+    catch (error) {
+        return commitIntentFailed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+    return {
+        status: 'ready',
+        changed: false,
+        taskId: resolved.taskId,
+        intent: inspection.intent ? commitIntentView(inspection.intent, inspection.currentHead) : null,
+        finalization: commitFinalizationView(inspection),
+        error: null
+    };
+}
 function statusOrchestration(taskRef, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -489,6 +961,15 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
+    if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        try {
+            readCommitIntent(resolved.taskDir, resolved.taskId);
+        }
+        catch (error) {
+            return failed('ORCHESTRATION_COMMIT_INTENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+        }
+        return failed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent blocks delegation preparation', resolved.taskId);
+    }
     if (!(options.supportsLifecycleDelegation ?? supportsLifecycleDelegation)(input.client)) {
         return failed('ORCHESTRATION_CLIENT_UNSUPPORTED', `client '${input.client}' does not support lifecycle orchestration`, resolved.taskId);
     }
@@ -499,8 +980,7 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
         return failed('ORCHESTRATION_MODEL_EVIDENCE_MISSING', 'running orchestration has no persisted model policy', resolved.taskId);
     if (run.pendingDelegation)
         return failed('ORCHESTRATION_DELEGATION_BUSY', 'the run already has a pending delegation', resolved.taskId);
-    const repositoryPending = ['claude-code', 'codex']
-        .flatMap((client) => matchingDelegations(client, () => true, options));
+    const repositoryPending = matchingDelegations(() => true, options);
     if (repositoryPending.length > 0) {
         return failed('ORCHESTRATION_DELEGATION_BUSY', 'the repository already has a pending lifecycle delegation', resolved.taskId);
     }
@@ -525,7 +1005,11 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     }
     let beforeFingerprint;
     try {
-        beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
+        beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+            gitRoot: gitRootFor(resolved.repoRoot, options),
+            stateRoot: resolved.repoRoot,
+            taskId: resolved.taskId
+        });
     }
     catch (error) {
         return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -558,7 +1042,7 @@ function prepareOrchestrationDelegation(taskRef, input, options = {}) {
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
     try {
-        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-orchestration.prepare', () => prepareOrchestrationDelegationUnlocked(taskRef, input, options));
+        return withTaskExecutionLock(resolved.repoRoot, '__repository__', 'task-orchestration.prepare.repository', () => withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-orchestration.prepare.task', () => prepareOrchestrationDelegationUnlocked(taskRef, input, options)));
     }
     catch (error) {
         if (error instanceof TaskExecutionLockError)
@@ -566,7 +1050,7 @@ function prepareOrchestrationDelegation(taskRef, input, options = {}) {
         throw error;
     }
 }
-function matchingDelegations(client, predicate, options) {
+function matchingDelegations(predicate, options) {
     const repoRoot = options.repoRoot ?? process.cwd();
     const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
     if (!fs.existsSync(activeRoot))
@@ -578,13 +1062,13 @@ function matchingDelegations(client, predicate, options) {
         if (!run?.pendingDelegation)
             return [];
         const receipt = run.pendingDelegation;
-        return receipt.client === client && predicate(receipt)
+        return predicate(receipt)
             ? [{ taskId: entry.name, run }]
             : [];
     });
 }
 function uniqueMatchingDelegation(client, predicate, options) {
-    const matches = matchingDelegations(client, predicate, options);
+    const matches = matchingDelegations((receipt) => receipt.client === client && predicate(receipt), options);
     if (matches.length === 0)
         return failed('ORCHESTRATION_DELEGATION_MISSING', 'no matching lifecycle delegation exists');
     if (matches.length > 1)
@@ -616,9 +1100,14 @@ function sealMatchingOrchestrationDelegation(client, event, options = {}) {
     }
     const repoRoot = options.repoRoot ?? process.cwd();
     try {
+        const gitRoot = gitRootFor(repoRoot, options);
         const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
-        const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot, snapshotTaskId);
-        const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(repoRoot, receipt.beforeFingerprint, afterFingerprint);
+        const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+            gitRoot,
+            stateRoot: repoRoot,
+            taskId: snapshotTaskId
+        });
+        const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
         return sealOrchestrationDelegation(matched.taskId, {
             childId: event.childId,
             exitCode: 0,
@@ -700,7 +1189,7 @@ function planOrchestrationStageCompletion(taskRef, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return { result: failed(resolved.code, resolved.message, resolved.taskId), plan: null };
-    const updatedRun = withUpdatedRun(inspected.run, { pendingDelegation: completed.receipt });
+    const updatedRun = withUpdatedRun(inspected.run, { pendingDelegation: completed.receipt }, options.now);
     return {
         result: { status: 'running', changed: true, taskId: resolved.taskId, run: updatedRun, next: null, error: null },
         plan: {
@@ -713,24 +1202,6 @@ function planOrchestrationStageCompletion(taskRef, event, options = {}) {
 function commitOrchestrationStageCompletion(plan) {
     saveRun(plan.taskDir, plan.updatedRun);
 }
-function completeCommitOrchestrationStage(taskRef, agent, options = {}) {
-    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-    if (!resolved.ok)
-        return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir);
-    if (!run)
-        return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
-    const receipt = run.pendingDelegation;
-    if (!receipt || receipt.stage !== 'commit') {
-        return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending commit delegation', resolved.taskId);
-    }
-    return completeOrchestrationStage(taskRef, {
-        stage: receipt.stage,
-        round: receipt.round,
-        artifact: receipt.artifact,
-        agent
-    }, options);
-}
 function sealOrchestrationDelegation(taskRef, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -780,5 +1251,5 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     saveRun(resolved.taskDir, updated);
     return { status: 'paused', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
-export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeCommitOrchestrationStage, completeOrchestrationStage, inspectOrchestrationStage, orchestrationPath, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, statusOrchestration };
+export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, abortCommitIntent, beginCommitIntent, beginOrResumeOrchestration, checkpointCommitIntent, commitOrchestrationStageCompletion, completeCommitIntent, completeOrchestrationStage, inspectOrchestrationStage, orchestrationPath, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, recoverCommitIntent, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, startCommitAttempt, statusCommitIntent, statusOrchestration, terminateCommitAttempt };
 //# sourceMappingURL=orchestration.js.map