@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/dist/lib/task/commit-intent.js

@@ -0,0 +1,165 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+class CommitIntentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CommitIntentError';
+        this.code = code;
+    }
+}
+function commitIntentPath(taskDir) {
+    return path.join(taskDir, 'commit-intent.json');
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function atomicWrite(file, value) {
+    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temp, serialize(value), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        const handle = fs.openSync(temp, 'r+');
+        try {
+            fs.fsyncSync(handle);
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+        fs.renameSync(temp, file);
+        fs.chmodSync(file, 0o600);
+        try {
+            const directory = fs.openSync(path.dirname(file), 'r');
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EACCES', 'EISDIR', 'EINVAL', 'EPERM'].includes(code ?? ''))
+                throw error;
+        }
+    }
+    finally {
+        if (fs.existsSync(temp))
+            fs.unlinkSync(temp);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function keysEqual(value, expected) {
+    return Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+function validPushEvidence(value) {
+    return value === null || (isRecord(value)
+        && keysEqual(value, ['remote', 'ref', 'head'])
+        && ['remote', 'ref', 'head'].every((key) => typeof value[key] === 'string' && value[key] !== ''));
+}
+function validOrchestration(value) {
+    if (value === null)
+        return true;
+    if (!isRecord(value) || !keysEqual(value, [
+        'runId', 'receiptId', 'authorizationIssuedAt', 'sourceRunDigest', 'plannedRunDigest',
+        'completionUpdatedAt', 'plannedReceipt'
+    ]))
+        return false;
+    return [
+        'runId', 'receiptId', 'authorizationIssuedAt', 'sourceRunDigest', 'plannedRunDigest', 'completionUpdatedAt'
+    ].every((key) => typeof value[key] === 'string' && value[key] !== '') && isRecord(value.plannedReceipt);
+}
+function parseIntent(raw, taskId) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent is not valid JSON');
+    }
+    if (!isRecord(value) || !keysEqual(value, [
+        'schemaVersion', 'taskId', 'mode', 'phase', 'tokenDigest', 'baselineHead', 'committedHead',
+        'pushEvidence', 'orchestration', 'createdAt', 'updatedAt'
+    ])) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent has an invalid schema');
+    }
+    if (value.schemaVersion !== 1
+        || value.taskId !== taskId
+        || !['standalone', 'orchestrated'].includes(String(value.mode))
+        || !['prepared', 'committed', 'pushed'].includes(String(value.phase))
+        || typeof value.tokenDigest !== 'string'
+        || !/^[a-f0-9]{64}$/.test(value.tokenDigest)
+        || typeof value.baselineHead !== 'string'
+        || (value.committedHead !== null && typeof value.committedHead !== 'string')
+        || !validPushEvidence(value.pushEvidence)
+        || !validOrchestration(value.orchestration)
+        || typeof value.createdAt !== 'string'
+        || typeof value.updatedAt !== 'string'
+        || (value.mode === 'standalone') !== (value.orchestration === null)) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent has invalid field values');
+    }
+    return value;
+}
+function tokenMatches(actualDigest, token) {
+    const actual = Buffer.from(actualDigest, 'hex');
+    const supplied = Buffer.from(digest(token), 'hex');
+    return actual.length === supplied.length && timingSafeEqual(actual, supplied);
+}
+function readCommitIntent(taskDir, taskId, token) {
+    const file = commitIntentPath(taskDir);
+    const intent = parseIntent(fs.readFileSync(file, 'utf8'), taskId);
+    if (token !== undefined && !tokenMatches(intent.tokenDigest, token)) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_TOKEN_MISMATCH', 'commit intent token does not match');
+    }
+    return intent;
+}
+function createCommitIntent(taskDir, input, options = {}) {
+    const file = commitIntentPath(taskDir);
+    if (fs.existsSync(file)) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists');
+    }
+    const token = (options.token ?? (() => randomBytes(32).toString('base64url')))();
+    const intent = Object.freeze({ schemaVersion: 1, ...input, tokenDigest: digest(token) });
+    atomicWrite(file, intent);
+    return { intent, token };
+}
+function updateCommitIntent(taskDir, taskId, token, updates) {
+    const current = readCommitIntent(taskDir, taskId, token);
+    const nextPhase = updates.phase ?? current.phase;
+    const transitions = {
+        prepared: ['prepared', 'committed', 'pushed'],
+        committed: ['committed', 'pushed'],
+        pushed: ['pushed']
+    };
+    if (!transitions[current.phase].includes(nextPhase)) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_STATE_INVALID', `cannot move commit intent from ${current.phase} to ${nextPhase}`);
+    }
+    const updated = Object.freeze({ ...current, ...updates, phase: nextPhase });
+    atomicWrite(commitIntentPath(taskDir), updated);
+    return updated;
+}
+function removeCommitIntent(taskDir, taskId, token) {
+    readCommitIntent(taskDir, taskId, token);
+    fs.unlinkSync(commitIntentPath(taskDir));
+}
+function removeCommitIntentByDigest(taskDir, taskId, expectedDigest) {
+    const file = commitIntentPath(taskDir);
+    const raw = fs.readFileSync(file);
+    parseIntent(raw.toString('utf8'), taskId);
+    const actual = digest(raw);
+    const expected = Buffer.from(expectedDigest, 'hex');
+    const observed = Buffer.from(actual, 'hex');
+    if (!/^[a-f0-9]{64}$/.test(expectedDigest)
+        || expected.length !== observed.length
+        || !timingSafeEqual(expected, observed)) {
+        throw new CommitIntentError('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'commit intent changed after recovery inspection');
+    }
+    fs.unlinkSync(file);
+}
+export { CommitIntentError, commitIntentPath, createCommitIntent, digest, readCommitIntent, removeCommitIntent, removeCommitIntentByDigest, serialize, updateCommitIntent };
+//# sourceMappingURL=commit-intent.js.map

package/dist/lib/task/decision-intents.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { appendActivityEntry, locateActivityLog } from './activity-log.js';
 import { isDecisionItem, listDecisionItems, selectDecisionItem } from './decision-items.js';
-import { createImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
+import { createImplementationInput, finalizeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs, selectDeclaredImplementationInput } from './implementation-inputs.js';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, parseLedger } from './ledger.js';
 import { resolveTaskContext } from './resolve-ref.js';
 import { extractSection, extractSubSection, findSectionHeading } from './sections.js';
@@ -45,7 +45,7 @@ function existingDecision(content, row, decision, needsImplementation) {
             ? { recordId, implementationInputId: null }
             : { conflict: '--needs-implementation is only valid for code-stage decisions' };
     const inputs = parseImplementationInputs(content).rows.filter((input) => input.ledgerId === row.id && input.decisionEvidence === row.evidence);
-    if (inputs.length !== 1 || inputs[0].needsImplementation !== needsImplementation) {
+    if (inputs.length !== 1 || (needsImplementation !== undefined && inputs[0].needsImplementation !== needsImplementation)) {
         return { conflict: `implementation intent for '${row.id}' conflicts with the existing decision` };
     }
     return { recordId, implementationInputId: inputs[0].id };
@@ -87,10 +87,29 @@ function applyHumanDecision(request, options = {}) {
         return failed('DECISION_TARGET_INVALID', message, resolved.taskId);
     }
     const row = selected.row;
-    if (row.stage === 'code' && request.needsImplementation === undefined)
-        return failed('DECISION_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, row.id);
     if (row.stage !== 'code' && request.needsImplementation !== undefined)
         return failed('DECISION_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage decisions', resolved.taskId, row.id);
+    let parsedInputs = null;
+    let declaredInput = null;
+    let effectiveNeedsImplementation = request.needsImplementation;
+    if (row.stage === 'code') {
+        try {
+            parsedInputs = parseImplementationInputs(content);
+            declaredInput = selectDeclaredImplementationInput(parsedInputs.rows, row.id, row.evidence);
+        }
+        catch (error) {
+            return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, row.id);
+        }
+        if (declaredInput) {
+            if (request.needsImplementation !== undefined && request.needsImplementation !== declaredInput.needsImplementation) {
+                return failed('DECISION_CONFLICT', `implementation intent for '${row.id}' conflicts with its declaration`, resolved.taskId, row.id);
+            }
+            effectiveNeedsImplementation = declaredInput.needsImplementation;
+        }
+        else if (effectiveNeedsImplementation === undefined) {
+            return failed('DECISION_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false when no implementation intent was declared', resolved.taskId, row.id);
+        }
+    }
     let metadata;
     try {
         metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
@@ -119,22 +138,17 @@ function applyHumanDecision(request, options = {}) {
     ];
     let implementationInputId = null;
     if (row.stage === 'code') {
-        let parsed;
-        try {
-            parsed = parseImplementationInputs(content);
-        }
-        catch (error) {
-            return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, row.id);
-        }
-        const input = createImplementationInput(parsed.rows, {
-            ledgerId: row.id, decisionEvidence: evidence,
-            needsImplementation: request.needsImplementation, decidedAt: metadata.timestamp
-        });
-        implementationInputId = input.id;
+        const nextInputs = declaredInput
+            ? finalizeImplementationInput(parsedInputs.rows, declaredInput.id, evidence, metadata.timestamp)
+            : [...parsedInputs.rows, createImplementationInput(parsedInputs.rows, {
+                    ledgerId: row.id, decisionEvidence: evidence,
+                    needsImplementation: effectiveNeedsImplementation, decidedAt: metadata.timestamp
+                })];
+        implementationInputId = declaredInput?.id ?? nextInputs[nextInputs.length - 1].id;
         mutations.push({
             kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
             heading: findSectionHeading(content, [...IMPLEMENTATION_INPUT_ALIASES]),
-            body: renderImplementationInputs([...parsed.rows, input])
+            body: renderImplementationInputs(nextInputs)
         });
     }
     mutations.push({

package/dist/lib/task/delegation-receipts.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
 const MANAGED_AGENTS = {
     'agent-infra-lifecycle-executor': 'executor',
     'agent-infra-lifecycle-reviewer': 'reviewer'
@@ -14,7 +15,9 @@ function prepareDelegation(input, options = {}) {
         ...input,
         id: (options.id ?? randomUUID)(),
         actualModel: null,
+        actualReasoningEffort: null,
         modelFallbackReason: null,
+        reasoningEffortFallbackReason: null,
         parentId: null,
         childId: null,
         spawnMode: null,
@@ -41,10 +44,27 @@ function activateDelegation(receipt, event, options = {}) {
     }
     if (event.spawnMode !== 'fresh')
         return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
-    const actualModel = event.actualModel ?? null;
-    if (actualModel && receipt.requestedModel && actualModel !== receipt.requestedModel && !event.modelFallbackReason) {
+    const actualModel = event.actualModel;
+    if (!actualModel || actualModel.trim() !== actualModel) {
+        return fail('DELEGATION_MODEL_IDENTITY_MISSING', 'native start event must provide a non-empty actual model identity');
+    }
+    if (actualModel !== receipt.requestedModel && (!event.modelFallbackReason || event.modelFallbackReason.trim() === '')) {
         return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
     }
+    const actualReasoningEffort = event.actualReasoningEffort;
+    if (!actualReasoningEffort || actualReasoningEffort.trim() !== actualReasoningEffort) {
+        return fail('DELEGATION_REASONING_EFFORT_MISSING', 'native start event must provide a non-empty actual reasoning effort');
+    }
+    if (actualReasoningEffort !== receipt.requestedReasoningEffort
+        && (!event.reasoningEffortFallbackReason || event.reasoningEffortFallbackReason.trim() === '')) {
+        return fail('DELEGATION_REASONING_EFFORT_FALLBACK_UNRECORDED', 'actual reasoning effort differs from requested effort without a fallback reason');
+    }
+    if (actualModel === receipt.requestedModel && event.modelFallbackReason) {
+        return fail('DELEGATION_MODEL_FALLBACK_INVALID', 'model fallback reason is only valid when actual model differs');
+    }
+    if (actualReasoningEffort === receipt.requestedReasoningEffort && event.reasoningEffortFallbackReason) {
+        return fail('DELEGATION_REASONING_EFFORT_FALLBACK_INVALID', 'reasoning-effort fallback reason is only valid when actual effort differs');
+    }
     return { ok: true, receipt: Object.freeze({
             ...receipt,
             status: 'activated',
@@ -52,7 +72,9 @@ function activateDelegation(receipt, event, options = {}) {
             childId: event.childId,
             spawnMode: event.spawnMode,
             actualModel,
+            actualReasoningEffort,
             modelFallbackReason: event.modelFallbackReason ?? null,
+            reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
             activatedAt: (options.now ?? (() => new Date().toISOString()))()
         }) };
 }
@@ -62,8 +84,7 @@ function completeDelegationStage(receipt, event) {
     if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
         return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
     }
-    const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
-    if (!acceptedAgents.includes(event.agent)) {
+    if (normalizeAgentToken(event.agent) !== normalizeAgentToken(receipt.client)) {
         return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
     }
     return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };

package/dist/lib/task/events.js

@@ -7,7 +7,9 @@ import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.
 import { parseReviewSummary } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { findSectionHeading } from './sections.js';
-import { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.js';
+import { validateLifecycleExecution } from './lifecycle-execution.js';
+import { commitOrchestrationStageCompletion } from './orchestration.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 const eventCatalog = [
     'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -22,17 +24,17 @@ const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
 const SCHEMAS = {
     'analyze.started': { optional: ['round'] },
     'analyze.awaiting-input': { required: ['question'] },
-    'analyze.completed': { required: ['artifact'], optional: ['round'] },
+    'analyze.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
     'review-analysis.started': { optional: ['round'] },
-    'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'plan.started': { optional: ['round'] },
-    'plan.completed': { required: ['artifact'], optional: ['round'] },
+    'plan.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
     'review-plan.started': { optional: ['round'] },
-    'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
-    'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation'] },
+    'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
     'review-code.started': { optional: ['round'] },
-    'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'manual-validation.started': { optional: ['round'] },
     'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
 };
@@ -229,7 +231,7 @@ function openStartedIdentity(rows, family) {
     });
     return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true } : null;
 }
-function applyTaskEvent(request, options = {}) {
+function applyTaskEventUnlocked(request, options = {}) {
     const invalid = validateTaskEventRequest(request);
     if (invalid)
         return failed(request, invalid);
@@ -326,20 +328,27 @@ function applyTaskEvent(request, options = {}) {
     const findingCountError = validateReviewFindingCounts(normalized, content, eventIdentity.family, completedArtifact?.path ?? null);
     if (findingCountError)
         return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-    if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+    let orchestrationCompletion = null;
+    if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
         const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-        const provenance = validateOrchestrationStage(normalized.taskRef, {
-            stage: orchestrationStage,
-            round: normalized.round,
-            artifact: normalized.artifact,
-            role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+        const execution = validateLifecycleExecution(normalized.taskRef, {
+            mode: normalized.orchestrated ? 'orchestrated' : 'standalone',
+            identity: {
+                stage: orchestrationStage,
+                round: normalized.round,
+                artifact: normalized.artifact,
+                role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+            },
+            agent: normalized.agent,
+            dryRun: normalized.dryRun
         }, { repoRoot: options.repoRoot });
-        if (provenance.status === 'failed' || provenance.status === 'paused') {
+        if (!execution.ok) {
             return failed(normalized, {
                 code: 'EVENT_TRANSITION_INVALID',
-                message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+                message: `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`
             }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
         }
+        orchestrationCompletion = execution.completionPlan;
     }
     let metadata;
     try {
@@ -379,19 +388,26 @@ function applyTaskEvent(request, options = {}) {
     const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
     if (result.status === 'failed')
         return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
-    if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
-        const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-        const orchestration = completeOrchestrationStage(normalized.taskRef, {
-            stage: orchestrationStage,
-            round: normalized.round,
-            artifact: normalized.artifact,
-            agent: normalized.agent
-        }, { repoRoot: options.repoRoot });
-        if (orchestration.status === 'failed' || orchestration.status === 'paused') {
+    if (!normalized.dryRun && orchestrationCompletion) {
+        try {
+            (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
+        }
+        catch (error) {
             return failed(normalized, {
-                code: 'EVENT_TRANSITION_INVALID',
-                message: orchestration.error?.message ?? orchestration.run?.pause?.message ?? 'orchestration provenance validation failed'
-            }, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+                code: 'EVENT_ORCHESTRATION_COMMIT_FAILED',
+                message: `task.md was written but orchestration completion could not be persisted; manual recovery is required: ${error instanceof Error ? error.message : String(error)}`
+            }, {
+                taskId: result.taskId,
+                taskMdPath: result.taskMdPath,
+                fromStep: currentStep,
+                toStep: step,
+                action: eventIdentity.action,
+                phase: eventIdentity.phase,
+                timestamp: result.timestamp,
+                agentInfraVersion: result.agentInfraVersion,
+                operations: result.operations,
+                artifactContext
+            });
         }
     }
     return {
@@ -404,6 +420,29 @@ function applyTaskEvent(request, options = {}) {
         agentInfraVersion: result.agentInfraVersion, operations: result.operations, error: null
     };
 }
+function applyTaskEvent(request, options = {}) {
+    const invalid = validateTaskEventRequest(request);
+    if (invalid)
+        return failed(request, invalid);
+    const parts = eventParts(request.event);
+    if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
+        return applyTaskEventUnlocked(request, options);
+    }
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return applyTaskEventUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => applyTaskEventUnlocked(request, options));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        return failed(request, {
+            code: 'EVENT_TRANSITION_INVALID',
+            message: `${error.code}: ${error.message}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+}
 function successNoOp(request, taskId, taskMdPath, currentStep, eventIdentity, timestamp, frontmatter, artifactContext) {
     return {
         ...failed(request, { code: 'EVENT_LOG_CONFLICT', message: '' }), status: 'no-op', error: null,

package/dist/lib/task/finalization-artifacts.js

@@ -0,0 +1,35 @@
+import { assertWritableInventory, inspectTaskArtifacts } from './artifact-lifecycle.js';
+const COMPLETION_BACKFILL_FAMILIES = [
+    'analysis',
+    'review-analysis',
+    'plan',
+    'review-plan',
+    'code',
+    'review-code',
+    'manual-validation'
+];
+function inspectCompletionArtifacts(taskRef, options = {}) {
+    const artifacts = [];
+    let taskId = null;
+    let taskDir = null;
+    for (const family of COMPLETION_BACKFILL_FAMILIES) {
+        const inventory = inspectTaskArtifacts(taskRef, family, options);
+        taskId = inventory.taskId ?? taskId;
+        taskDir = inventory.taskDir ?? taskDir;
+        if (inventory.status === 'failed') {
+            return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error: inventory.error };
+        }
+        const writableError = assertWritableInventory(inventory);
+        const brokenReference = inventory.diagnostics.find((item) => item.code === 'BROKEN_REFERENCE');
+        const error = writableError ?? (brokenReference ? {
+            code: 'ARTIFACT_REFERENCE_INVALID',
+            message: brokenReference.message
+        } : null);
+        if (error)
+            return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error };
+        artifacts.push(...inventory.artifacts);
+    }
+    return { status: 'ready', changed: false, taskId, taskDir, artifacts, error: null };
+}
+export { COMPLETION_BACKFILL_FAMILIES, inspectCompletionArtifacts };
+//# sourceMappingURL=finalization-artifacts.js.map

package/dist/lib/task/implementation-inputs.js

@@ -13,12 +13,11 @@ function validateInput(row) {
         throw new Error(`implementation input ${row.id} has incomplete decision identity`);
     if (row.stage !== 'code')
         throw new Error(`implementation input ${row.id} has invalid stage`);
-    if (!TIMESTAMP_RE.test(row.decidedAt) || !Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')))) {
-        throw new Error(`implementation input ${row.id} has invalid decided_at`);
-    }
-    const valid = (row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
-        (!row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
-        (row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
+    const hasValidTimestamp = TIMESTAMP_RE.test(row.decidedAt) && Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')));
+    const valid = (row.status === 'declared' && row.decidedAt === '' && row.consumedBy === '') ||
+        (hasValidTimestamp && row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
+        (hasValidTimestamp && !row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
+        (hasValidTimestamp && row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
     if (!valid)
         throw new Error(`implementation input ${row.id} has an invalid state combination`);
 }
@@ -67,6 +66,54 @@ function createImplementationInput(rows, draft) {
     validateInput(row);
     return row;
 }
+function declareImplementationInput(rows, draft) {
+    const existing = rows.filter((row) => row.ledgerId === draft.ledgerId && row.status === 'declared');
+    if (existing.length > 1)
+        throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with existing rows`);
+    if (existing.length === 1) {
+        const row = existing[0];
+        if (row.decisionEvidence !== draft.decisionEvidence || row.needsImplementation !== draft.needsImplementation) {
+            throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with the existing row`);
+        }
+        return row;
+    }
+    const row = {
+        id: nextId(rows), ledgerId: draft.ledgerId, decisionEvidence: draft.decisionEvidence,
+        stage: 'code', needsImplementation: draft.needsImplementation, decidedAt: '',
+        status: 'declared', consumedBy: ''
+    };
+    validateInput(row);
+    return row;
+}
+function selectDeclaredImplementationInput(rows, ledgerId, decisionEvidence) {
+    const forLedger = rows.filter((row) => row.ledgerId === ledgerId && row.status === 'declared');
+    if (forLedger.length > 1)
+        throw new Error(`implementation input declaration for '${ledgerId}' is ambiguous`);
+    if (forLedger.length === 0)
+        return null;
+    if (forLedger[0].decisionEvidence !== decisionEvidence) {
+        throw new Error(`implementation input declaration for '${ledgerId}' has conflicting evidence`);
+    }
+    return forLedger[0];
+}
+function finalizeImplementationInput(rows, id, decisionEvidence, decidedAt) {
+    let found = false;
+    const next = rows.map((row) => {
+        if (row.id !== id)
+            return row;
+        found = true;
+        if (row.status !== 'declared')
+            throw new Error(`implementation input ${id} is not declared`);
+        return {
+            ...row, decisionEvidence, decidedAt,
+            status: row.needsImplementation ? 'pending' : 'not-required'
+        };
+    });
+    if (!found)
+        throw new Error(`implementation input ${id} was not found`);
+    next.forEach(validateInput);
+    return next;
+}
 function selectPendingImplementationInput(rows, reviewCompletedAt) {
     const reviewEpoch = Date.parse(reviewCompletedAt.replace(' ', 'T'));
     if (!Number.isFinite(reviewEpoch))
@@ -113,5 +160,5 @@ function renderImplementationInputs(rows) {
         })
     ].join('\n');
 }
-export { SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES, createImplementationInput, consumeImplementationInput, parseImplementationInputs, renderImplementationInputs, selectPendingImplementationInput };
+export { SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES, createImplementationInput, consumeImplementationInput, declareImplementationInput, finalizeImplementationInput, parseImplementationInputs, renderImplementationInputs, selectDeclaredImplementationInput, selectPendingImplementationInput };
 //# sourceMappingURL=implementation-inputs.js.map

package/dist/lib/task/ledger-intents.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { declareImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { writeTask } from './write.js';
@@ -66,6 +67,14 @@ function ledgerSectionMutation(content) {
             body: `| ${LEDGER_COLUMNS.join(' | ')} |\n|----|-------|-------|----------|--------|----------|`
         }];
 }
+function implementationInputMutation(content, rows) {
+    const english = /^##\s+Activity Log\s*$/m.test(content);
+    return {
+        kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+        heading: english ? 'Implementation Inputs' : '实现输入',
+        body: renderImplementationInputs(rows)
+    };
+}
 function mapWrite(intent, entityId, before, after, result) {
     if (result.status === 'failed')
         return failed(intent, result.error.code, result.error.message, result.taskId, entityId);
@@ -174,9 +183,34 @@ function applyLedgerIntent(intent, options = {}) {
             }
         }
     }
+    let implementationMutation = null;
+    if (intent.kind === 'decision-upsert' || intent.kind === 'finding-review') {
+        const stage = intent.kind === 'decision-upsert' ? intent.stage : after.stage;
+        const escalates = intent.kind === 'decision-upsert' || intent.status === 'needs-human-decision';
+        if (stage === 'code' && escalates && intent.needsImplementation === undefined) {
+            return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, after.id);
+        }
+        if ((stage !== 'code' || !escalates) && intent.needsImplementation !== undefined) {
+            return failed(intent, 'LEDGER_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage escalation', resolved.taskId, after.id);
+        }
+        if (stage === 'code' && escalates) {
+            try {
+                const parsed = parseImplementationInputs(content);
+                const declaration = declareImplementationInput(parsed.rows, {
+                    ledgerId: after.id, decisionEvidence: after.evidence,
+                    needsImplementation: intent.needsImplementation
+                });
+                const nextRows = parsed.rows.includes(declaration) ? parsed.rows : [...parsed.rows, declaration];
+                implementationMutation = implementationInputMutation(content, nextRows);
+            }
+            catch (error) {
+                return failed(intent, 'LEDGER_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, after.id);
+            }
+        }
+    }
     const result = writeTask({
         taskRef: intent.taskRef, expectedState: 'active',
-        mutations: [...ledgerSectionMutation(content), rowMutation(after)],
+        mutations: [...ledgerSectionMutation(content), rowMutation(after), ...(implementationMutation ? [implementationMutation] : [])],
         dryRun: 'dryRun' in intent ? intent.dryRun : false
     }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
     return mapWrite(intent, after.id, before, after, result);