@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/dist/lib/task/commands/log.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { classifyAgent } from '../../agent-clients/tokens.js';
 import { formatTable } from '../../table.js';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
@@ -30,11 +31,11 @@ const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'];
 // with ` [started]`; the matching done entry carries the identical base action
 // without the suffix. Pairing therefore keys on the base action (including any
 // `(Round N)`), so every round and every repeated execution pairs on its own.
-// Short agent tokens that actually appear in activity logs for AI executors
-// (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
-// note these differ from the `.airc.json` long names claude-code/gemini-cli).
-// Any other executor token (a human name, possibly CJK) is treated as human.
-const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
+// Known AI tokens, long-name mapping, and loose rendering classification live
+// in lib/agent-clients/tokens.ts (single source of truth shared with the
+// write-side internal commands). Any other executor token (a human name,
+// possibly CJK, or an unknown value) is rendered as human with a visible
+// `(unknown)` marker.
 const REVIEW_STAGE_PREFIXES = [
     { prefix: 'Review Analysis', stage: 'analysis' },
     { prefix: 'Review Plan', stage: 'plan' },
@@ -83,12 +84,11 @@ function humanValidationCount(note) {
 function isHumanCountField(field) {
     return fieldNumber(field, 'manual-validation') !== undefined || fieldNumber(field, 'human-decision') !== undefined;
 }
-// A step is human-executed when its agent token is not a known AI token. Take
-// the first whitespace-delimited token and drop any trailing parenthetical
-// annotation (e.g. `张三 (executed on host)` -> `张三`) before the lookup.
-function isHumanAgent(agent) {
-    const token = agent.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
-    return token !== '' && !KNOWN_AI_AGENTS.has(token);
+// A step is human-executed when its agent token is not a known AI token.
+// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
+// AI; empty or unknown tokens classify as non-AI (human).
+export function isHumanAgent(agent) {
+    return classifyAgent(agent).status !== 'ai';
 }
 // Fold the two human counts into a review row's verdict NOTE: comma-joined, right
 // after the blockers/major/minor list and before the ` → artifact` link, mirroring
@@ -148,8 +148,9 @@ function log(args = []) {
         const note = stage
             ? foldHumanCounts(s.note, humanDecisionCounts.get(stage) ?? 0, humanValidationCount(s.note))
             : s.note;
-        const human = isHumanAgent(s.agent);
-        const agent = human ? 'human' : s.agent;
+        const { status, display } = classifyAgent(s.agent);
+        const human = status !== 'ai';
+        const agent = status === 'unknown' ? `${display} (unknown)` : display;
         const started = s.started || (human ? '-' : '');
         return [String(idx + 1), s.step, agent, started, s.done || (s.started ? '(in progress)' : ''), note];
     });
@@ -158,5 +159,5 @@ function log(args = []) {
     }
     process.stdout.write(`Total: ${steps.length} steps\n`);
 }
-export { log, isHumanAgent };
+export { log };
 //# sourceMappingURL=log.js.map

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

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+const MANAGED_AGENTS = {
+    'agent-infra-lifecycle-executor': 'executor',
+    'agent-infra-lifecycle-reviewer': 'reviewer'
+};
+function managedDelegationRole(nativeAgent) {
+    return MANAGED_AGENTS[nativeAgent] ?? null;
+}
+function fail(code, message) {
+    return { ok: false, code, message };
+}
+function prepareDelegation(input, options = {}) {
+    return Object.freeze({
+        ...input,
+        id: (options.id ?? randomUUID)(),
+        actualModel: null,
+        actualReasoningEffort: null,
+        modelFallbackReason: null,
+        reasoningEffortFallbackReason: null,
+        parentId: null,
+        childId: null,
+        spawnMode: null,
+        agent: null,
+        status: 'prepared',
+        afterFingerprint: null,
+        changedPaths: Object.freeze([]),
+        createdAt: (options.now ?? (() => new Date().toISOString()))(),
+        activatedAt: null,
+        sealedAt: null,
+        consumedAt: null
+    });
+}
+function activateDelegation(receipt, event, options = {}) {
+    const managedRole = managedDelegationRole(event.nativeAgent);
+    if (!managedRole)
+        return fail('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+    if (receipt.status !== 'prepared')
+        return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected prepared`);
+    if (managedRole !== receipt.role)
+        return fail('DELEGATION_ROLE_MISMATCH', `managed role ${managedRole} does not match ${receipt.role}`);
+    if (!event.parentId || (receipt.parentId !== null && event.parentId !== receipt.parentId) || !event.childId || event.childId === event.parentId) {
+        return fail('DELEGATION_IDENTITY_INVALID', 'native parent/child identity does not match the prepared delegation');
+    }
+    if (event.spawnMode !== 'fresh')
+        return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
+    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',
+            parentId: event.parentId,
+            childId: event.childId,
+            spawnMode: event.spawnMode,
+            actualModel,
+            actualReasoningEffort,
+            modelFallbackReason: event.modelFallbackReason ?? null,
+            reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
+            activatedAt: (options.now ?? (() => new Date().toISOString()))()
+        }) };
+}
+function completeDelegationStage(receipt, event) {
+    if (receipt.status !== 'activated')
+        return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected activated`);
+    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)) {
+        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 }) };
+}
+function sealDelegation(receipt, event, options = {}) {
+    if (receipt.status !== 'stage-completed')
+        return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected stage-completed`);
+    if (event.childId !== receipt.childId || event.exitCode !== 0)
+        return fail('DELEGATION_STOP_INVALID', 'native stop identity or exit status is invalid');
+    if (receipt.role === 'reviewer') {
+        const taskRoot = `.agents/workspace/active/${receipt.taskId}/`;
+        const allowed = new Set([
+            `${taskRoot}${receipt.artifact}`,
+            `${taskRoot}task.md`,
+            `${taskRoot}orchestration.json`
+        ]);
+        const disallowed = event.changedPaths.find((entry) => !allowed.has(entry));
+        if (disallowed)
+            return fail('DELEGATION_REVIEWER_WRITE_FORBIDDEN', `reviewer changed forbidden path '${disallowed}'`);
+    }
+    return { ok: true, receipt: Object.freeze({
+            ...receipt,
+            status: 'sealed',
+            afterFingerprint: event.afterFingerprint,
+            changedPaths: Object.freeze([...event.changedPaths]),
+            sealedAt: (options.now ?? (() => new Date().toISOString()))()
+        }) };
+}
+function consumeDelegation(receipt, options = {}) {
+    if (receipt.status === 'consumed')
+        return fail('DELEGATION_REPLAY', `delegation ${receipt.id} was already consumed`);
+    if (receipt.status !== 'sealed')
+        return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected sealed`);
+    return { ok: true, receipt: Object.freeze({
+            ...receipt,
+            status: 'consumed',
+            consumedAt: (options.now ?? (() => new Date().toISOString()))()
+        }) };
+}
+export { activateDelegation, completeDelegationStage, consumeDelegation, managedDelegationRole, prepareDelegation, sealDelegation };
+//# sourceMappingURL=delegation-receipts.js.map

package/dist/lib/task/events.js

@@ -3,8 +3,13 @@ import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-
 import { buildArtifactLinkSection, artifactName, parseArtifactName, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { consumeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
+import { parseReviewSummary } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { findSectionHeading } from './sections.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',
@@ -19,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'] }
 };
@@ -75,12 +80,75 @@ function validateTaskEventRequest(request) {
 const FAMILY = {
     analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
     'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review'], completed: ['requirement-analysis-review', 'technical-design-review'], target: 'technical-design', label: 'Plan Task' },
+    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
     'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
     code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
     'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
     'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
 };
+const REVIEW_LEDGER_STAGES = {
+    'review-analysis': 'analysis',
+    'review-plan': 'plan',
+    'review-code': 'code'
+};
+function validateReviewFindingCounts(request, content, family, artifactPath) {
+    const stage = REVIEW_LEDGER_STAGES[family];
+    if (!stage || !artifactPath)
+        return null;
+    const rows = parseLedger(content);
+    const invalid = validateLedgerRows(rows);
+    if (invalid)
+        return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
+    const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
+    const payload = {
+        blocker: request.blockers,
+        major: request.major,
+        minor: request.minor
+    };
+    let reportContent;
+    try {
+        reportContent = fs.readFileSync(artifactPath, 'utf8');
+    }
+    catch (error) {
+        return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: String(error) };
+    }
+    const parsed = parseReviewSummary(reportContent);
+    if (!parsed.ok || !parsed.summary.counts) {
+        return {
+            code: 'EVENT_FINDING_COUNT_MISMATCH',
+            message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
+        };
+    }
+    const report = parsed.summary.counts;
+    const reportVerdict = parsed.summary.verdict === 'Approved'
+        ? 'approved'
+        : parsed.summary.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+    const fields = [
+        ['blocker', 'blockers'],
+        ['major', 'major'],
+        ['minor', 'minor']
+    ];
+    const differences = fields.flatMap(([severity, cliField]) => {
+        const values = [
+            expected[severity] === payload[severity]
+                ? null
+                : `${cliField} ledger ${expected[severity]}, payload ${payload[severity]}`,
+            expected[severity] === report[severity]
+                ? null
+                : `${cliField} ledger ${expected[severity]}, report ${report[severity]}`
+        ];
+        return values.filter((value) => value !== null);
+    });
+    if (request.verdict !== reportVerdict) {
+        differences.push(`verdict report ${reportVerdict}, payload ${request.verdict}`);
+    }
+    if (differences.length === 0)
+        return null;
+    return {
+        code: 'EVENT_FINDING_COUNT_MISMATCH',
+        message: `review summary, payload, and ${stage} ledger do not match: ${differences.join('; ')}`
+    };
+}
 function eventParts(event) {
     const [family, suffix] = event.split('.');
     return { family, phase: suffix === 'started' ? 'started' : suffix === 'awaiting-input' ? 'waiting' : 'completed' };
@@ -163,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);
@@ -257,6 +325,31 @@ function applyTaskEvent(request, options = {}) {
     const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
     if (!allowed.includes(currentStep))
         return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    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 });
+    let orchestrationCompletion = null;
+    if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
+        const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+        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 (!execution.ok) {
+            return failed(normalized, {
+                code: 'EVENT_TRANSITION_INVALID',
+                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 {
         metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
@@ -295,6 +388,28 @@ 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 (!normalized.dryRun && orchestrationCompletion) {
+        try {
+            (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
+        }
+        catch (error) {
+            return failed(normalized, {
+                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 {
         status: result.status, changed: result.changed, event: normalized.event,
         requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,
@@ -305,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/lifecycle-execution.js

@@ -0,0 +1,46 @@
+import { inspectOrchestrationStage, pauseOrchestration, planOrchestrationStageCompletion, readRun } from './orchestration.js';
+import { resolveTaskRef } from './resolve-ref.js';
+function failure(mode, code, message) {
+    return { ok: false, mode, completionPlan: null, error: { code, message } };
+}
+function inspectLifecycleExecution(taskRef, request, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failure(request.mode, resolved.code, resolved.message);
+    if (request.mode === 'standalone') {
+        try {
+            const run = readRun(resolved.taskDir);
+            if (run?.pendingDelegation) {
+                return failure(request.mode, 'ORCHESTRATION_STANDALONE_BUSY', 'standalone lifecycle execution is blocked by a pending orchestration delegation');
+            }
+            return { ok: true, mode: request.mode, completionPlan: null, error: null };
+        }
+        catch (error) {
+            return failure(request.mode, 'ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (request.agent) {
+        const planned = planOrchestrationStageCompletion(taskRef, {
+            ...request.identity,
+            agent: request.agent
+        }, options);
+        if (planned.plan) {
+            return { ok: true, mode: request.mode, completionPlan: planned.plan, error: null };
+        }
+        return failure(request.mode, planned.result.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH', planned.result.error?.message ?? 'orchestration provenance validation failed');
+    }
+    const inspected = inspectOrchestrationStage(taskRef, request.identity, options);
+    if (inspected.status !== 'failed') {
+        return { ok: true, mode: request.mode, completionPlan: null, error: null };
+    }
+    return failure(request.mode, inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH', inspected.error?.message ?? 'orchestration provenance validation failed');
+}
+function validateLifecycleExecution(taskRef, request, options = {}) {
+    const inspected = inspectLifecycleExecution(taskRef, request, options);
+    if (inspected.ok || request.mode === 'standalone' || request.dryRun)
+        return inspected;
+    const paused = pauseOrchestration(taskRef, inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH', inspected.error?.message ?? 'orchestration provenance validation failed', true, options);
+    return failure(request.mode, paused.run?.pause?.code ?? inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH', paused.run?.pause?.message ?? inspected.error?.message ?? 'orchestration provenance validation failed');
+}
+export { inspectLifecycleExecution, validateLifecycleExecution };
+//# sourceMappingURL=lifecycle-execution.js.map