@fitlab-ai/agent-infra 0.9.8 → 0.9.9

package/dist/lib/task/finalization.js

@@ -0,0 +1,567 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { syncPlatformComment } from '../platform/issue-comments.js';
+import { applyTaskLifecycle } from './lifecycle.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { inspectShortIdRegistry } from './short-id.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { verifyTaskEvent } from './verification.js';
+import { projectFinalizationWarning } from './workflow-warning-intents.js';
+import { mergeOperationWarnings } from './operation-outcome.js';
+const RECEIPT_VERSION = 2;
+const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification'];
+function finalizationRoot(repoRoot) {
+    return path.join(repoRoot, '.agents', 'workspace', '.task-finalization');
+}
+function receiptPath(repoRoot, taskId) {
+    return path.join(finalizationRoot(repoRoot), `${taskId}.json`);
+}
+function now() {
+    return new Date().toISOString();
+}
+function errorOf(error, fallbackCode, retryable = false) {
+    const value = error;
+    const code = typeof value?.code === 'string' && value.code ? value.code : fallbackCode;
+    const message = typeof value?.message === 'string' && value.message ? value.message : String(error);
+    return { code, message, retryable: value?.retryable === true || retryable };
+}
+function failed(taskId, error, overrides = {}) {
+    return {
+        status: error.retryable ? 'blocked' : 'failed',
+        changed: false,
+        taskId,
+        lifecycle: null,
+        taskComment: null,
+        verification: null,
+        completedSteps: [],
+        pendingSteps: [...FINALIZATION_STEPS],
+        result: error.retryable ? 'blocked' : 'failed',
+        warnings: [],
+        error,
+        ...overrides
+    };
+}
+function emptyReceipt(taskId) {
+    return {
+        version: RECEIPT_VERSION,
+        taskId,
+        intent: 'complete',
+        receiptId: randomUUID(),
+        revision: 0,
+        lifecycle: 'pending',
+        taskComment: 'pending',
+        verification: 'pending',
+        warningProjection: 'done',
+        warnings: [],
+        updatedAt: now(),
+        lastError: null
+    };
+}
+function validWarning(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const warning = value;
+    if (Object.keys(warning).sort().join('\0') !== [
+        'code', 'message', 'retryable', 'step', 'target', 'severity', 'status', 'resolvedAt'
+    ].sort().join('\0'))
+        return false;
+    return typeof warning.code === 'string' && warning.code.length > 0
+        && typeof warning.message === 'string' && warning.message.length > 0
+        && typeof warning.retryable === 'boolean'
+        && typeof warning.step === 'string' && warning.step.length > 0
+        && typeof warning.target === 'string' && warning.target.length > 0
+        && (warning.severity === 'IMPORTANT' || warning.severity === 'ACTION_REQUIRED')
+        && (warning.status === 'open' || warning.status === 'resolved')
+        && (warning.resolvedAt === null || typeof warning.resolvedAt === 'string');
+}
+function validateReceipt(value, taskId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('receipt must be an object');
+    const receipt = value;
+    const states = ['pending', 'done', 'skipped'];
+    if (receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
+        || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+        || !Number.isSafeInteger(receipt.revision) || Number(receipt.revision) < 0
+        || !states.includes(String(receipt.lifecycle))
+        || !states.includes(String(receipt.taskComment))
+        || !states.includes(String(receipt.verification))
+        || !['pending', 'done'].includes(String(receipt.warningProjection))
+        || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
+        || typeof receipt.updatedAt !== 'string'
+        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError))))
+        throw new Error('receipt schema is invalid');
+    return receipt;
+}
+function readReceipt(repoRoot, taskId) {
+    const file = receiptPath(repoRoot, taskId);
+    if (!fs.existsSync(file))
+        return null;
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return validateReceipt(value, taskId);
+}
+function writeReceipt(repoRoot, receipt) {
+    const directory = finalizationRoot(repoRoot);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = receiptPath(repoRoot, receipt.taskId);
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(receipt)}\n`, { mode: 0o600, flag: 'wx' });
+        fs.renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* preserve the primary error */ }
+        throw error;
+    }
+}
+function updateReceipt(repoRoot, receipt, patch) {
+    const current = readReceipt(repoRoot, receipt.taskId);
+    if (!current || current.receiptId !== receipt.receiptId || current.revision !== receipt.revision) {
+        const error = new Error('finalization receipt revision is stale');
+        Object.assign(error, { code: 'FINALIZATION_CAPABILITY_STALE' });
+        throw error;
+    }
+    const next = { ...current, ...patch, revision: current.revision + 1, updatedAt: now() };
+    writeReceipt(repoRoot, next);
+    return next;
+}
+function completedSteps(receipt) {
+    return FINALIZATION_STEPS.filter((step) => receipt[step === 'task-comment' ? 'taskComment' : step] !== 'pending');
+}
+function pendingSteps(receipt) {
+    return FINALIZATION_STEPS.filter((step) => receipt[step === 'task-comment' ? 'taskComment' : step] === 'pending');
+}
+function lifecycleStep(result) {
+    return {
+        status: result.status,
+        changed: result.changed,
+        error: result.error ? errorOf(result.error, 'LIFECYCLE_FAILED') : null,
+        completedSteps: result.completedSteps ?? [],
+        pendingSteps: result.pendingSteps ?? []
+    };
+}
+function commentStep(result) {
+    return {
+        status: result.status,
+        changed: result.changed,
+        error: result.error ? errorOf(result.error, 'COMMENT_SYNC_FAILED') : null
+    };
+}
+function verificationStep(result) {
+    return {
+        status: result.status,
+        changed: false,
+        error: result.status === 'pass' ? null : verificationFailure(result)
+    };
+}
+function verificationFailure(result) {
+    if (result.error)
+        return errorOf(result.error, 'VERIFY_FAILED', result.status === 'blocked');
+    const invocation = [...result.invocations].reverse().find((item) => item.status !== 'pass');
+    const payload = invocation?.payload;
+    const details = [payload?.message, payload?.summary, payload?.action]
+        .filter((value) => typeof value === 'string' && value.length > 0);
+    const code = result.status === 'blocked' || invocation?.status === 'blocked'
+        ? 'CHECK_BLOCKED'
+        : result.status === 'fail' ? 'CHECK_FAILED' : 'VERIFY_FAILED';
+    return {
+        code,
+        message: details.length > 0 ? details.join(' - ') : `verification ${result.status}`,
+        retryable: code === 'CHECK_BLOCKED'
+    };
+}
+function warningFromError(step, error, severity = 'ACTION_REQUIRED') {
+    return {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        step,
+        target: step,
+        severity
+    };
+}
+function openWarnings(receipt) {
+    return mergeOperationWarnings(receipt.warnings.filter((warning) => warning.status === 'open').map(({ status: _status, resolvedAt: _resolvedAt, ...warning }) => warning));
+}
+function warningRecord(warning, status) {
+    return { ...warning, status, resolvedAt: status === 'resolved' ? now() : null };
+}
+function replaceWarning(receipt, warning, status) {
+    const next = warningRecord(warning, status);
+    const key = `${warning.step}\0${warning.code}\0${warning.target}`;
+    return [
+        ...receipt.warnings.filter((item) => `${item.step}\0${item.code}\0${item.target}` !== key),
+        next
+    ];
+}
+function resolveStepWarnings(receipt, step) {
+    return receipt.warnings.map((warning) => warning.step === step && warning.status === 'open'
+        ? { ...warning, status: 'resolved', resolvedAt: now() }
+        : warning);
+}
+function issueCapability(receipt, scope) {
+    return {
+        receiptId: receipt.receiptId,
+        baseRevision: receipt.revision,
+        scope,
+        nonce: randomUUID(),
+        issuedAt: now()
+    };
+}
+function capabilityError(code, message) {
+    const error = new Error(message);
+    error.name = 'OrchestrationStateError';
+    Object.assign(error, { code });
+    return error;
+}
+function mutationKeys(value) {
+    return Object.keys(value).sort();
+}
+function validateCapabilityMutation(current, capability, mutation, consumed) {
+    if (capability.receiptId !== current.receiptId || capability.baseRevision !== current.revision || consumed.has(capability.nonce)) {
+        throw capabilityError('FINALIZATION_CAPABILITY_STALE', 'finalization capability is stale or outside its scope');
+    }
+    if (capability.scope !== mutation.scope) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability mutation scope does not match its capability');
+    }
+    if (mutation.operation !== 'succeeded' && mutation.operation !== 'failed') {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability operation is invalid');
+    }
+    if (mutation.scope === 'task-comment') {
+        if (current.taskComment !== 'pending')
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability scope task-comment is not pending');
+        const expected = mutation.operation === 'succeeded' ? ['operation', 'scope', 'state'] : ['error', 'operation', 'scope'];
+        if (mutationKeys(mutation).join('\0') !== expected.join('\0'))
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability mutation shape is invalid');
+        if (mutation.operation === 'succeeded' && mutation.state !== 'done' && mutation.state !== 'skipped') {
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability transition is invalid');
+        }
+    }
+    else if (mutation.scope === 'verification') {
+        if (current.verification !== 'pending')
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability scope verification is not pending');
+        const expected = mutation.operation === 'succeeded' ? ['operation', 'scope'] : ['error', 'operation', 'scope'];
+        if (mutationKeys(mutation).join('\0') !== expected.join('\0'))
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability mutation shape is invalid');
+    }
+    else {
+        if (current.warningProjection !== 'pending')
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'warning projection capability is not pending');
+        const expected = mutation.operation === 'succeeded' ? ['operation', 'scope'] : ['error', 'operation', 'scope'];
+        if (mutationKeys(mutation).join('\0') !== expected.join('\0'))
+            throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability mutation shape is invalid');
+    }
+    if (mutation.operation === 'failed' && (!mutation.error.code || !mutation.error.message || typeof mutation.error.retryable !== 'boolean')) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability failure detail is invalid');
+    }
+}
+function mutationPatch(current, mutation) {
+    if (mutation.scope === 'task-comment') {
+        if (mutation.operation === 'succeeded') {
+            const warnings = resolveStepWarnings(current, 'task-comment');
+            return { taskComment: mutation.state, warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null };
+        }
+        const warnings = replaceWarning(current, warningFromError('task-comment', mutation.error), 'open');
+        return { taskComment: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
+    }
+    if (mutation.scope === 'verification') {
+        if (mutation.operation === 'succeeded') {
+            const warnings = resolveStepWarnings(current, 'verification');
+            return { verification: 'done', warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null };
+        }
+        const warnings = replaceWarning(current, warningFromError('verification', mutation.error), 'open');
+        return { verification: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
+    }
+    return mutation.operation === 'succeeded'
+        ? { warningProjection: 'done', lastError: null }
+        : { warningProjection: 'pending', lastError: mutation.error };
+}
+function applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, consumed) {
+    const resolved = resolveTaskRef(receipt.taskId, { repoRoot });
+    if (!resolved.ok || resolved.state !== 'completed') {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires a completed task');
+    }
+    const current = readReceipt(repoRoot, receipt.taskId);
+    if (!current || current.receiptId !== receipt.receiptId || current.revision !== receipt.revision) {
+        throw capabilityError('FINALIZATION_CAPABILITY_STALE', 'finalization receipt revision is stale');
+    }
+    validateCapabilityMutation(current, capability, mutation, consumed);
+    const next = updateReceipt(repoRoot, current, mutationPatch(current, mutation));
+    consumed.add(capability.nonce);
+    return next;
+}
+function applyFinalizationReceiptMutation(repoRoot, receipt, capability, mutation) {
+    const resolved = resolveTaskRef(receipt.taskId, { repoRoot });
+    if (!resolved.ok || resolved.state !== 'completed') {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires a completed task');
+    }
+    return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.receipt-mutation', () => applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set()));
+}
+function warningKey(warning) {
+    return `${warning.step}\0${warning.code}\0${warning.target}`;
+}
+function reconcileWarningProjection(repoRoot, taskId, receipt, consumed) {
+    if (receipt.warningProjection === 'done')
+        return receipt;
+    const warnings = [...new Map(receipt.warnings.map((warning) => [warningKey(warning), warning])).values()];
+    for (const warning of warnings) {
+        try {
+            const projected = projectFinalizationWarning(taskId, warning, { repoRoot });
+            if (projected.status === 'failed') {
+                const detail = {
+                    code: projected.error?.code || 'FINALIZATION_WARNING_PROJECTION_FAILED',
+                    message: projected.error?.message || 'workflow warning projection failed',
+                    retryable: true
+                };
+                const capability = issueCapability(receipt, 'warning-projection');
+                return applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, { scope: 'warning-projection', operation: 'failed', error: detail }, consumed);
+            }
+        }
+        catch (error) {
+            const detail = errorOf(error, 'FINALIZATION_WARNING_PROJECTION_FAILED', true);
+            try {
+                const capability = issueCapability(receipt, 'warning-projection');
+                return applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, { scope: 'warning-projection', operation: 'failed', error: detail }, consumed);
+            }
+            catch {
+                return receipt;
+            }
+        }
+    }
+    try {
+        const capability = issueCapability(receipt, 'warning-projection');
+        return applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, { scope: 'warning-projection', operation: 'succeeded' }, consumed);
+    }
+    catch {
+        return receipt;
+    }
+}
+function terminalResult(taskId, receipt, steps, changed, error = null) {
+    const pending = pendingSteps(receipt);
+    const blocked = [steps.lifecycle, steps.taskComment, steps.verification].some((step) => step?.status === 'blocked');
+    const warnings = openWarnings(receipt);
+    const postLifecyclePending = receipt.lifecycle === 'done' && (pending.some((step) => step !== 'lifecycle') || receipt.warningProjection === 'pending');
+    const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID';
+    return {
+        status: hardError ? (error?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
+        changed,
+        taskId,
+        ...steps,
+        completedSteps: completedSteps(receipt),
+        pendingSteps: pending,
+        result: postLifecyclePending && (warnings.length > 0 || receipt.warningProjection === 'pending')
+            ? 'completed_with_warnings'
+            : hardError
+                ? (error?.retryable ? 'blocked' : 'failed')
+                : pending.length === 0 || postLifecyclePending
+                    ? 'completed'
+                    : blocked
+                        ? 'blocked'
+                        : 'failed',
+        warnings,
+        error: hardError ? error : postLifecyclePending ? null : error
+    };
+}
+function applyUnderLock(request, taskId, options) {
+    const repoRoot = path.resolve(options.repoRoot);
+    const lifecycle = options.lifecycle ?? applyTaskLifecycle;
+    const commentSync = options.commentSync ?? syncPlatformComment;
+    const verify = options.verify ?? verifyTaskEvent;
+    const consumedCapabilities = new Set();
+    let receipt;
+    try {
+        const file = receiptPath(repoRoot, taskId);
+        const existed = fs.existsSync(file);
+        receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId);
+        if (!existed)
+            writeReceipt(repoRoot, receipt);
+    }
+    catch (error) {
+        return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
+    }
+    const preflightState = resolveTaskRef(taskId, { repoRoot });
+    if (options.preflight && preflightState.ok && preflightState.state === 'active') {
+        try {
+            const preflight = options.preflight({ taskRef: taskId, event: 'complete-task.preflight' }, { repoRoot });
+            if (preflight.status !== 'pass') {
+                const detail = verificationFailure(preflight);
+                return failed(taskId, detail, {
+                    lifecycle: null,
+                    taskComment: null,
+                    verification: null,
+                    completedSteps: completedSteps(receipt),
+                    pendingSteps: pendingSteps(receipt)
+                });
+            }
+        }
+        catch (error) {
+            return failed(taskId, errorOf(error, 'TASK_FINALIZATION_PREFLIGHT_FAILED', true));
+        }
+    }
+    let lifecycleResult = null;
+    let changed = false;
+    try {
+        const resolved = resolveTaskRef(taskId, { repoRoot });
+        const registry = resolved.ok && resolved.state === 'completed' ? inspectShortIdRegistry(repoRoot) : null;
+        if (registry && registry.status !== 'valid') {
+            const detail = {
+                code: 'TASK_FINALIZATION_SHORT_ID_REGISTRY_UNAVAILABLE',
+                message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
+                retryable: false
+            };
+            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
+            return terminalResult(taskId, receipt, {
+                lifecycle: { status: 'failed', changed: false, error: detail },
+                taskComment: null,
+                verification: null
+            }, changed, detail);
+        }
+        const shortIds = registry?.status === 'valid' ? registry.shortIds : null;
+        if (shortIds?.has(taskId)) {
+            const detail = {
+                code: 'TASK_FINALIZATION_CANONICAL_STATE_INVALID',
+                message: 'completed task still has an active short-id registry entry',
+                retryable: false
+            };
+            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
+            return terminalResult(taskId, receipt, {
+                lifecycle: { status: 'failed', changed: false, error: detail },
+                taskComment: null,
+                verification: null
+            }, changed, detail);
+        }
+        const lifecycleDone = receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed' && shortIds !== null;
+        if (lifecycleDone) {
+            lifecycleResult = { status: 'no-op', changed: false, error: null };
+            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+        }
+        else {
+            const result = lifecycle({ taskRef: taskId, intent: 'complete', agent: request.agent }, { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) });
+            lifecycleResult = lifecycleStep(result);
+            if (result.status !== 'applied' && result.status !== 'no-op') {
+                receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: lifecycleResult.error });
+                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
+            }
+            changed = result.changed;
+            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+        }
+    }
+    catch (error) {
+        const detail = errorOf(error, 'TASK_FINALIZATION_LIFECYCLE_FAILED');
+        try {
+            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
+        }
+        catch { /* preserve the primary error */ }
+        return failed(taskId, detail, { lifecycle: lifecycleResult });
+    }
+    let taskComment = null;
+    try {
+        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        if (receipt.taskComment !== 'pending') {
+            taskComment = {
+                status: receipt.taskComment === 'skipped' ? 'skipped' : 'no-op',
+                changed: false,
+                error: null
+            };
+        }
+        else {
+            const result = commentSync(taskId, { kind: 'task', agent: request.agent, cwd: repoRoot });
+            taskComment = commentStep(result);
+            if (result.status === 'applied' || result.status === 'no-op') {
+                const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
+                const capability = issueCapability(receipt, 'task-comment');
+                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                    scope: 'task-comment', operation: 'succeeded', state: skipped ? 'skipped' : 'done'
+                }, consumedCapabilities);
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+                taskComment = skipped ? { ...taskComment, status: 'skipped' } : taskComment;
+                changed = changed || result.changed;
+            }
+            else {
+                const detail = taskComment.error ?? { code: 'COMMENT_SYNC_FAILED', message: 'task comment synchronization failed', retryable: true };
+                const capability = issueCapability(receipt, 'task-comment');
+                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                    scope: 'task-comment', operation: 'failed', error: detail
+                }, consumedCapabilities);
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, taskComment.error);
+            }
+        }
+    }
+    catch (error) {
+        const detail = errorOf(error, 'COMMENT_SYNC_FAILED', true);
+        try {
+            const capability = issueCapability(receipt, 'task-comment');
+            receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                scope: 'task-comment', operation: 'failed', error: detail
+            }, consumedCapabilities);
+            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        }
+        catch { /* preserve the primary error */ }
+        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment: { status: 'blocked', changed: false, error: detail }, verification: null }, changed, detail);
+    }
+    let verification = null;
+    try {
+        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        if (receipt.verification !== 'pending') {
+            verification = { status: 'no-op', changed: false, error: null };
+        }
+        else {
+            const result = verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
+            verification = verificationStep(result);
+            if (result.status === 'pass') {
+                const capability = issueCapability(receipt, 'verification');
+                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                    scope: 'verification', operation: 'succeeded'
+                }, consumedCapabilities);
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+            }
+            else {
+                const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
+                const capability = issueCapability(receipt, 'verification');
+                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                    scope: 'verification', operation: 'failed', error: detail
+                }, consumedCapabilities);
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed, verification.error);
+            }
+        }
+    }
+    catch (error) {
+        const detail = errorOf(error, 'VERIFY_FAILED', true);
+        try {
+            const capability = issueCapability(receipt, 'verification');
+            receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+                scope: 'verification', operation: 'failed', error: detail
+            }, consumedCapabilities);
+            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        }
+        catch { /* preserve the primary error */ }
+        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
+    }
+    receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed);
+}
+function applyTaskFinalization(request, options) {
+    if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
+        return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
+    }
+    const repoRoot = path.resolve(options.repoRoot);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
+    try {
+        return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
+    }
+    catch (error) {
+        const detail = error instanceof TaskExecutionLockError
+            ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+            : errorOf(error, 'TASK_FINALIZATION_FAILED');
+        return failed(resolved.taskId, detail);
+    }
+}
+export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability };
+//# sourceMappingURL=finalization.js.map

package/dist/lib/task/operation-outcome.js

@@ -0,0 +1,33 @@
+function warningKey(warning) {
+    return `${warning.step}\0${warning.code}\0${warning.target}`;
+}
+function mergeOperationWarnings(...groups) {
+    const merged = new Map();
+    for (const group of groups) {
+        for (const warning of group) {
+            const canonical = {
+                code: warning.code,
+                message: warning.message,
+                retryable: warning.retryable,
+                step: warning.step,
+                target: warning.target,
+                severity: warning.severity
+            };
+            merged.set(warningKey(canonical), canonical);
+        }
+    }
+    return [...merged.values()];
+}
+const RETRY_HINTS = {
+    COMMIT_AUTOPUSH_PROTECTED_BRANCH: 'Review the protected branch policy; push the local commit manually if delivery is intended.',
+    COMMIT_PUSH_FAILED: 'Retry the commit push-only path after fixing the remote push failure.',
+    PR_METADATA_SYNC_FAILED: 'Retry create-pr metadata synchronization; do not create another pull request.',
+    PR_SUMMARY_SYNC_FAILED: 'Retry create-pr summary synchronization; do not create another pull request.',
+    FINALIZATION_WARNING_PENDING: 'Retry complete-task to process the pending finalization step.'
+};
+function retryHintForWarning(warning) {
+    return RETRY_HINTS[warning.code]
+        ?? `Retry the ${warning.step} operation after resolving ${warning.code}.`;
+}
+export { mergeOperationWarnings, retryHintForWarning, warningKey };
+//# sourceMappingURL=operation-outcome.js.map