@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/lifecycle-recovery.js

@@ -0,0 +1,549 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.js';
+import { managedDelegationRole } from './delegation-receipts.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
+import { artifactName, parseArtifactName } from './artifact-name.js';
+import { locateActivityLog, pairEntries } from './activity-log.js';
+import { captureTaskWriteMetadata, writeTask } from './write.js';
+import { parseTypedTaskFrontmatter } from './frontmatter.js';
+import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.js';
+import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
+import { recoverActivatedOrchestrationDelegationUnderLock, readRun } from './orchestration.js';
+import { isRecoveryWarning, sameRecoveryWarning } from './recovery-warning.js';
+const RECOVERY_NOTE_PREFIX = 'lifecycle-recovery:v1 ';
+const RECOVERY_STAGES = ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'];
+const ACTIONS = {
+    analysis: 'Analyze Task',
+    'review-analysis': 'Review Analysis',
+    plan: 'Plan Task',
+    'review-plan': 'Review Plan',
+    code: 'Code Task',
+    'review-code': 'Review Code'
+};
+const RECOVERY_NOTE_KEYS = [
+    'version', 'taskId', 'stage', 'round', 'artifact', 'startedAgent', 'receiptId', 'childId',
+    'stopRevision', 'consumer', 'consumedAt', 'owner', 'reason'
+];
+const RECOVERY_RELEASE_RETRY_WARNING = Object.freeze({
+    code: 'RECOVERY_RELEASE_RETRY_REQUIRED',
+    message: 'recovery receipt and Activity Log are complete but the protected lifecycle claim could not be released',
+    action: 'retry recover-started with the same selector and reason'
+});
+function text(value) {
+    return typeof value === 'string' && value.length > 0 && value.trim() === value && !/[\r\n]/u.test(value);
+}
+function isReleaseRetryWarning(value) {
+    return sameRecoveryWarning(value, RECOVERY_RELEASE_RETRY_WARNING);
+}
+function timestamp(value) {
+    return text(value) && Number.isFinite(Date.parse(value));
+}
+function recoveryConsumer(taskId, receiptId) {
+    return `lifecycle-recovery:${taskId}:${receiptId}`;
+}
+function actionPattern(stage, round) {
+    const escaped = ACTIONS[stage].replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`^${escaped} \\(Round ${round}(?:, (?:fix for review-code(?:-r[2-9]|-r[1-9]\\d+)?.md|decision II-[1-9]\\d*))?\\)$`, 'u');
+}
+function baseStep(step) {
+    return step.replace(/\s*\[(?:started|aborted)\]\s*$/u, '');
+}
+function isRecoveryStage(value) {
+    return RECOVERY_STAGES.includes(value);
+}
+function parseRecoveryNote(note) {
+    if (!note.startsWith(RECOVERY_NOTE_PREFIX))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(note.slice(RECOVERY_NOTE_PREFIX.length));
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (Object.keys(record).sort().join(',') !== [...RECOVERY_NOTE_KEYS].sort().join(','))
+        return null;
+    if (record.version !== 1
+        || typeof record.taskId !== 'string' || !TASK_ID_RE.test(record.taskId)
+        || !isRecoveryStage(record.stage)
+        || !Number.isSafeInteger(record.round) || record.round < 1
+        || !text(record.artifact)
+        || !text(record.startedAgent)
+        || !text(record.receiptId)
+        || !text(record.childId)
+        || !Number.isSafeInteger(record.stopRevision) || record.stopRevision < 1
+        || !text(record.consumer)
+        || !timestamp(record.consumedAt)
+        || record.owner !== 'terminated'
+        || !text(record.reason))
+        return null;
+    const parsedArtifact = parseArtifactName(record.artifact);
+    if (!parsedArtifact || parsedArtifact.family !== record.stage || parsedArtifact.round !== record.round)
+        return null;
+    if (record.consumer !== recoveryConsumer(record.taskId, record.receiptId))
+        return null;
+    return record;
+}
+function renderRecoveryNote(note) {
+    return `${RECOVERY_NOTE_PREFIX}${JSON.stringify(note)}`;
+}
+function result(request, status, extra = {}) {
+    return {
+        status,
+        changed: status === 'applied',
+        targetState: 'active',
+        requestRef: request.taskRef,
+        intent: request.intent,
+        taskId: null,
+        stage: request.stage,
+        round: request.round,
+        artifact: request.artifact,
+        receiptId: null,
+        childId: null,
+        warning: null,
+        error: null,
+        ...extra
+    };
+}
+function failure(request, status, code, message, extra = {}) {
+    return result(request, status, { error: { code, message }, ...extra });
+}
+function recoveryFailure(request, status, code, message) {
+    return failure(request, status, code, message);
+}
+function normalizeRequest(request) {
+    if (!request || typeof request !== 'object'
+        || request.intent !== 'recover-started'
+        || typeof request.taskRef !== 'string' || !request.taskRef.trim()
+        || typeof request.agent !== 'string'
+        || !isRecoveryStage(request.stage)
+        || !Number.isSafeInteger(request.round) || request.round < 1
+        || typeof request.artifact !== 'string'
+        || typeof request.reason !== 'string' || !request.reason.trim() || /[\r\n]/u.test(request.reason))
+        return { code: 'RECOVERY_PAYLOAD_INVALID', message: 'recover-started requires a task, agent, stage, round, artifact, and single-line reason' };
+    const agent = normalizeAgentToken(request.agent);
+    if (!agent)
+        return { code: 'RECOVERY_PAYLOAD_INVALID', message: 'recovery agent is not a recognized agent token' };
+    const expectedArtifact = artifactName(request.stage, request.round);
+    if (request.artifact !== expectedArtifact) {
+        return { code: 'RECOVERY_PAYLOAD_INVALID', message: `artifact must be ${expectedArtifact} for ${request.stage} round ${request.round}` };
+    }
+    return { ...request, agent, reason: request.reason.trim() };
+}
+function targetRows(sectionEntries, stage, round) {
+    const pattern = actionPattern(stage, round);
+    const rows = pairEntries([...sectionEntries]).filter((row) => pattern.test(row.step));
+    const recoveryEntries = sectionEntries.filter((entry) => entry.step.endsWith(' [aborted]') && pattern.test(baseStep(entry.step)));
+    return { rows, recoveryEntries };
+}
+function validateStopRecord(record, receipt, consumer) {
+    const start = record.state.startEvidence;
+    const stop = record.state.stopEvidence;
+    const provenance = receipt.lifecycleProvenance;
+    const host = receipt.hostEvidence;
+    if (receipt.client !== 'codex'
+        || !provenance
+        || host?.kind !== 'codex-lifecycle-v2'
+        || !start
+        || !stop
+        || record.state.status !== 'stop-ready'
+        || stop.terminalStatus !== 'completed'
+        || stop.hookStopObserved !== true
+        || start.childThreadId !== receipt.childId
+        || start.parentThreadId !== receipt.parentId
+        || managedDelegationRole(start.nativeAgent) !== receipt.role
+        || start.hookDefinitionHash !== provenance.hookDefinitionHash
+        || host.hookDefinitionHash !== provenance.hookDefinitionHash
+        || host.capabilitySessionId !== provenance.capabilitySessionId
+        || host.capabilityTurnId !== provenance.capabilityTurnId
+        || host.capabilityToolUseId !== provenance.capabilityToolUseId
+        || host.spawnToolUseId !== start.spawnToolUseId
+        || !host.spawnObservedAt
+        || !record.spawnObservedAt
+        || host.spawnObservedAt !== record.spawnObservedAt
+        || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
+        || host.controlGeneration !== provenance.controlGeneration
+        || typeof host.controllerInstanceDigest !== 'string'
+        || typeof host.controlGeneration !== 'string'
+        || host.startRevision < 1
+        || record.revision <= host.startRevision)
+        return { ok: false, code: 'RECOVERY_STOP_EVIDENCE_INVALID', message: 'Codex stop evidence does not match the managed activated receipt' };
+    if (record.state.child?.childThreadId !== receipt.childId || record.state.stop?.childThreadId !== receipt.childId) {
+        return { ok: false, code: 'RECOVERY_STOP_EVIDENCE_INVALID', message: 'Codex stop evidence child identity is inconsistent' };
+    }
+    if (record.consumer !== null && record.consumer !== consumer) {
+        return { ok: false, code: 'RECOVERY_CONSUMER_CONFLICT', message: `Codex lifecycle evidence was consumed by '${record.consumer}'` };
+    }
+    if (record.consumer === null)
+        return { ok: true, stopRevision: record.revision, consumedAt: '' };
+    if (receipt.status === 'activated' && record.consumer === consumer && record.consumedAt) {
+        return { ok: true, stopRevision: record.revision, consumedAt: record.consumedAt };
+    }
+    if (record.consumer !== consumer
+        || !record.consumedAt
+        || receipt.hostEvidence?.stopRevision !== record.revision
+        || receipt.hostEvidence.consumer !== consumer
+        || receipt.hostEvidence.consumedAt !== record.consumedAt)
+        return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'recovery receipt references do not match the protected lifecycle claim' };
+    return { ok: true, stopRevision: record.revision, consumedAt: record.consumedAt };
+}
+function readLifecycleStore(options, repoRoot) {
+    if (options.lifecycleStore)
+        return options.lifecycleStore;
+    return createCodexLifecycleStore({
+        root: resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' }),
+        cliVersion: 'recovery',
+        now: options.now
+    });
+}
+function readStoredEvidence(store, childId) {
+    try {
+        return store.read(childId);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('was not found uniquely'))
+            return { missing: true };
+        return { error: error instanceof Error ? error : new Error(message) };
+    }
+}
+function taskNote(taskId, request, receipt, stopRevision, consumer, consumedAt) {
+    return {
+        version: 1,
+        taskId,
+        stage: request.stage,
+        round: request.round,
+        artifact: request.artifact,
+        startedAgent: request.agent,
+        receiptId: receipt.id,
+        childId: receipt.childId,
+        stopRevision,
+        consumer,
+        consumedAt,
+        owner: 'terminated',
+        reason: request.reason
+    };
+}
+function releaseResult(request, taskId, receipt, released, previousChange) {
+    if (released)
+        return result(request, 'applied', { taskId, receiptId: receipt.id, childId: receipt.childId });
+    return result(request, 'applied', {
+        changed: previousChange,
+        taskId,
+        receiptId: receipt.id,
+        childId: receipt.childId,
+        warning: RECOVERY_RELEASE_RETRY_WARNING
+    });
+}
+function isPostActivationAbortedReceipt(receipt, taskId, request) {
+    return receipt.status === 'aborted'
+        && receipt.activatedAt !== null
+        && receipt.agent === null
+        && receipt.taskId === taskId
+        && receipt.stage === request.stage
+        && receipt.round === request.round
+        && receipt.artifact === request.artifact;
+}
+function matchingPostActivationAbortedReceipts(run, taskId, request) {
+    return run.receipts.filter((receipt) => isPostActivationAbortedReceipt(receipt, taskId, request));
+}
+function sameRecoveryNote(left, right) {
+    return left.version === right.version
+        && left.taskId === right.taskId
+        && left.stage === right.stage
+        && left.round === right.round
+        && left.artifact === right.artifact
+        && left.startedAgent === right.startedAgent
+        && left.receiptId === right.receiptId
+        && left.childId === right.childId
+        && left.stopRevision === right.stopRevision
+        && left.consumer === right.consumer
+        && left.consumedAt === right.consumedAt
+        && left.owner === right.owner
+        && left.reason === right.reason;
+}
+function recoveryNoteMatchesRequest(note, taskId, request) {
+    return note.taskId === taskId
+        && note.stage === request.stage
+        && note.round === request.round
+        && note.artifact === request.artifact
+        && note.startedAgent === request.agent
+        && note.reason === request.reason;
+}
+function recoveryReferencesMatch(receipt, note, consumer) {
+    return receipt.childId === note.childId
+        && note.consumer === consumer
+        && receipt.hostEvidence?.stopRevision === note.stopRevision
+        && receipt.hostEvidence.consumer === consumer
+        && receipt.hostEvidence.consumedAt === note.consumedAt;
+}
+function recoveryRunIsStable(run) {
+    return run !== null && run.status === 'running' && run.pendingDelegation === null;
+}
+function recoveryTerminalFailureStatus(code) {
+    switch (code) {
+        case 'RECOVERY_LOG_CONFLICT':
+        case 'RECOVERY_NOTE_INVALID':
+        case 'RECOVERY_ORCHESTRATION_INVALID':
+        case 'RECOVERY_RECEIPT_INVALID':
+        case 'RECOVERY_REFERENCE_CONFLICT':
+        case 'RECOVERY_CONSUMER_CONFLICT':
+            return 'conflict';
+        default:
+            return 'owner-unknown';
+    }
+}
+function readRecoveryTerminalFacts(section, taskId, request, run, store) {
+    const targets = targetRows(section.entries, request.stage, request.round);
+    const paired = targets.rows.filter((row) => row.started !== '' && row.done !== '');
+    if (targets.recoveryEntries.length !== 1 || paired.length !== 1
+        || paired[0].done !== targets.recoveryEntries[0].time) {
+        return { ok: false, code: 'RECOVERY_LOG_CONFLICT', message: 'recovery Activity Log does not contain one completed started/aborted pair' };
+    }
+    const note = parseRecoveryNote(targets.recoveryEntries[0].note);
+    if (!note || !recoveryNoteMatchesRequest(note, taskId, request)) {
+        return { ok: false, code: 'RECOVERY_NOTE_INVALID', message: 'recovery Activity Log note does not match the selector' };
+    }
+    if (!recoveryRunIsStable(run)) {
+        return { ok: false, code: 'RECOVERY_ORCHESTRATION_INVALID', message: 'completed recovery state must be running with no pending delegation' };
+    }
+    const receipts = matchingPostActivationAbortedReceipts(run, taskId, request);
+    if (receipts.length !== 1 || receipts[0].id !== note.receiptId) {
+        return { ok: false, code: 'RECOVERY_RECEIPT_INVALID', message: 'there is not one matching post-activation aborted receipt' };
+    }
+    const receipt = receipts[0];
+    const consumer = recoveryConsumer(taskId, receipt.id);
+    if (!recoveryReferencesMatch(receipt, note, consumer)) {
+        return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'recovery receipt and Activity Log references do not match' };
+    }
+    const stored = readStoredEvidence(store, note.childId);
+    if ('error' in stored)
+        return { ok: false, code: 'RECOVERY_STORE_UNKNOWN', message: stored.error.message };
+    if ('missing' in stored)
+        return { ok: true, facts: { note, receipt, consumer, stored: null } };
+    const evidence = validateStopRecord(stored, receipt, consumer);
+    if (!evidence.ok)
+        return evidence;
+    if (stored.consumer !== consumer || !stored.consumedAt
+        || evidence.stopRevision !== note.stopRevision || evidence.consumedAt !== note.consumedAt) {
+        return { ok: false, code: 'RECOVERY_REFERENCE_CONFLICT', message: 'complete recovery facts do not reference the protected recovery claim' };
+    }
+    return { ok: true, facts: { note, receipt, consumer, stored } };
+}
+function verifyRecoveryCommit(taskMdPath, taskDir, taskId, request, note, options) {
+    try {
+        const content = fs.readFileSync(taskMdPath, 'utf8');
+        parseTypedTaskFrontmatter(content);
+        const section = locateActivityLog(content);
+        if (!section)
+            return { ok: false, message: 'recovery Activity Log cannot be reread uniquely' };
+        const run = readRun(taskDir, options.orchestration);
+        const store = readLifecycleStore(options, options.repoRoot ?? path.resolve(taskDir, '../../../..'));
+        const facts = readRecoveryTerminalFacts(section, taskId, request, run, store);
+        if (!facts.ok)
+            return { ok: false, message: facts.message };
+        if (!sameRecoveryNote(facts.facts.note, note)) {
+            return { ok: false, message: 'recovery Activity Log note changed during commit verification' };
+        }
+        if (!facts.facts.stored)
+            return { ok: false, message: 'protected lifecycle claim disappeared before release' };
+        return { ok: true, receipt: facts.facts.receipt };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}
+function recoveryDomainFailure() {
+    return { consistent: false, recovery: true, targetState: 'active' };
+}
+export function readLifecycleRecoveryDomainEvidence(repoRoot, requestInput, terminalResult, options = {}) {
+    const terminalStateValid = terminalResult.status === 'no-op'
+        ? terminalResult.changed === false
+        : terminalResult.status === 'applied'
+            && (terminalResult.changed === true || (terminalResult.changed === false && isReleaseRetryWarning(terminalResult.warning)));
+    const normalized = normalizeRequest(requestInput);
+    if ('code' in normalized || terminalResult.targetState !== 'active'
+        || !terminalStateValid)
+        return recoveryDomainFailure();
+    const request = normalized;
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot });
+    if (!resolved.ok)
+        return recoveryDomainFailure();
+    try {
+        const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        parseTypedTaskFrontmatter(content);
+        const section = locateActivityLog(content);
+        if (!section)
+            return recoveryDomainFailure();
+        const run = readRun(resolved.taskDir);
+        const store = readLifecycleStore(options, repoRoot);
+        const facts = readRecoveryTerminalFacts(section, resolved.taskId, request, run, store);
+        if (!facts.ok)
+            return recoveryDomainFailure();
+        if (!facts.facts.stored)
+            return { consistent: true, recovery: true, targetState: 'active', recoveryState: 'released' };
+        if (!isReleaseRetryWarning(terminalResult.warning))
+            return recoveryDomainFailure();
+        return {
+            consistent: true,
+            recovery: true,
+            targetState: 'active',
+            recoveryState: 'retry-required',
+            warning: terminalResult.warning
+        };
+    }
+    catch {
+        return recoveryDomainFailure();
+    }
+}
+function recoverStartedLifecycleUnderLock(requestInput, options = {}) {
+    const normalized = normalizeRequest(requestInput);
+    if ('code' in normalized)
+        return failure(requestInput, 'conflict', normalized.code, normalized.message);
+    const request = normalized;
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failure(request, 'conflict', resolved.code, resolved.message);
+    const taskId = resolved.taskId;
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return failure(request, 'owner-unknown', 'RECOVERY_TASK_READ_FAILED', String(error), { taskId });
+    }
+    try {
+        parseTypedTaskFrontmatter(content);
+    }
+    catch (error) {
+        return failure(request, 'conflict', 'RECOVERY_TASK_INVALID', error instanceof Error ? error.message : String(error), { taskId });
+    }
+    const section = locateActivityLog(content);
+    if (!section)
+        return failure(request, 'conflict', 'RECOVERY_LOG_INVALID', 'task has no unique Activity Log section', { taskId });
+    const targets = targetRows(section.entries, request.stage, request.round);
+    const open = targets.rows.filter((row) => row.started !== '' && row.done === '');
+    if (open.length > 1 || targets.recoveryEntries.length > 1) {
+        return failure(request, 'conflict', 'RECOVERY_SELECTOR_AMBIGUOUS', 'recovery selector does not identify one lifecycle attempt', { taskId });
+    }
+    let run;
+    try {
+        run = readRun(resolved.taskDir, options.orchestration);
+    }
+    catch (error) {
+        return failure(request, 'owner-unknown', 'RECOVERY_ORCHESTRATION_UNKNOWN', String(error), { taskId });
+    }
+    if (!run)
+        return failure(request, 'owner-unknown', 'RECOVERY_ORCHESTRATION_MISSING', 'no orchestration run exists for the open lifecycle execution', { taskId });
+    if (open.length === 0) {
+        if (targets.recoveryEntries.length !== 1) {
+            return failure(request, 'conflict', 'RECOVERY_TERMINAL_MISSING', 'there is no matching open or structured recovery lifecycle row', { taskId });
+        }
+        const store = readLifecycleStore(options, resolved.repoRoot);
+        const facts = readRecoveryTerminalFacts(section, taskId, request, run, store);
+        if (!facts.ok) {
+            return failure(request, recoveryTerminalFailureStatus(facts.code), facts.code, facts.message, { taskId });
+        }
+        const { note, receipt, consumer, stored } = facts.facts;
+        if (!stored)
+            return result(request, 'no-op', { taskId, receiptId: receipt.id, childId: receipt.childId });
+        let released = false;
+        try {
+            released = (options.releaseRecovery ?? store.releaseRecovery)(note.childId, consumer);
+        }
+        catch (error) {
+            return releaseResult(request, taskId, receipt, false, false);
+        }
+        return releaseResult(request, taskId, receipt, released, false);
+    }
+    const started = open[0];
+    if (normalizeAgentToken(started.agent) !== request.agent || started.note !== 'started') {
+        return failure(request, 'conflict', 'RECOVERY_SELECTOR_MISMATCH', 'open started lifecycle row does not match the recovery selector', { taskId });
+    }
+    if (targets.recoveryEntries.length > 0) {
+        return failure(request, 'conflict', 'RECOVERY_LOG_CONFLICT', 'open lifecycle execution already has a recovery terminal row', { taskId });
+    }
+    const pending = run.pendingDelegation;
+    const recovered = run.receipts.filter((candidate) => isPostActivationAbortedReceipt(candidate, taskId, request));
+    if (pending && recovered.length > 0) {
+        return failure(request, 'conflict', 'RECOVERY_RECEIPT_INVALID', 'open lifecycle execution has both a pending and an aborted matching delegation', { taskId });
+    }
+    const receipt = pending ?? (recovered.length === 1 ? recovered[0] : null);
+    if (!receipt || (pending && (receipt.status !== 'activated' || receipt.client !== 'codex')) || (!pending && receipt.status !== 'aborted')) {
+        return failure(request, 'owner-unknown', 'RECOVERY_DELEGATION_UNAVAILABLE', 'open lifecycle execution is not backed by one matching activated Codex delegation', { taskId });
+    }
+    if (normalizeAgentToken(started.agent) !== normalizeAgentToken(receipt.client)) {
+        return failure(request, 'conflict', 'RECOVERY_SELECTOR_MISMATCH', 'started agent does not match the delegation client', { taskId, receiptId: receipt.id, childId: receipt.childId });
+    }
+    const consumer = recoveryConsumer(taskId, receipt.id);
+    const store = readLifecycleStore(options, resolved.repoRoot);
+    const stored = readStoredEvidence(store, receipt.childId ?? '');
+    if ('error' in stored)
+        return failure(request, 'owner-unknown', 'RECOVERY_STORE_UNKNOWN', stored.error.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
+    if ('missing' in stored)
+        return failure(request, 'owner-unknown', 'RECOVERY_STOP_EVIDENCE_MISSING', 'matching Codex lifecycle stop evidence is missing', { taskId, receiptId: receipt.id, childId: receipt.childId });
+    const evidence = validateStopRecord(stored, receipt, consumer);
+    if (!evidence.ok)
+        return failure(request, evidence.code === 'RECOVERY_CONSUMER_CONFLICT' ? 'conflict' : 'owner-unknown', evidence.code, evidence.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
+    let claimed = stored;
+    if (stored.consumer === null) {
+        try {
+            claimed = store.claimRecovery(receipt.childId, taskId, receipt.id, receipt.hostEvidence?.hookDefinitionHash);
+        }
+        catch (error) {
+            return failure(request, 'owner-unknown', 'RECOVERY_CLAIM_FAILED', error instanceof Error ? error.message : String(error), { taskId, receiptId: receipt.id, childId: receipt.childId });
+        }
+    }
+    const stopRevision = claimed.revision;
+    const consumedAt = claimed.consumedAt;
+    if (!consumedAt)
+        return failure(request, 'owner-unknown', 'RECOVERY_CLAIM_INVALID', 'protected lifecycle claim has no consumed timestamp', { taskId, receiptId: receipt.id, childId: receipt.childId });
+    if (receipt.status === 'activated') {
+        const recoveredRun = recoverActivatedOrchestrationDelegationUnderLock(taskId, {
+            receiptId: receipt.id,
+            stage: request.stage,
+            round: request.round,
+            artifact: request.artifact,
+            startedAgent: request.agent,
+            childId: receipt.childId,
+            stopRevision,
+            consumer,
+            consumedAt
+        }, { ...options.orchestration, repoRoot: resolved.repoRoot, now: options.now });
+        if (recoveredRun.status === 'failed' || !recoveredRun.run) {
+            return failure(request, 'owner-unknown', recoveredRun.error?.code ?? 'RECOVERY_ORCHESTRATION_FAILED', recoveredRun.error?.message ?? 'orchestration recovery failed', { taskId, receiptId: receipt.id, childId: receipt.childId });
+        }
+    }
+    const note = taskNote(taskId, request, receipt, stopRevision, consumer, consumedAt);
+    const metadata = captureTaskWriteMetadata();
+    const updatedBody = `${section.body ? `${section.body}\n` : ''}- ${metadata.timestamp} — **${baseStep(started.step)} [aborted]** by ${request.agent} — ${renderRecoveryNote(note)}`;
+    const written = (options.writeTask ?? writeTask)({
+        taskRef: taskId,
+        expectedState: 'active',
+        mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body: updatedBody }]
+    }, { repoRoot: resolved.repoRoot, metadataProvider: () => metadata });
+    if (written.status === 'failed') {
+        return failure(request, 'owner-unknown', 'RECOVERY_LOG_WRITE_FAILED', written.error.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
+    }
+    const verified = (options.verifyRecoveryCommit ?? verifyRecoveryCommit)(resolved.taskMdPath, resolved.taskDir, taskId, request, note, options);
+    if (!verified.ok) {
+        return failure(request, 'owner-unknown', 'RECOVERY_COMMIT_VERIFY_FAILED', verified.message, { taskId, receiptId: receipt.id, childId: receipt.childId });
+    }
+    let released = false;
+    try {
+        released = (options.releaseRecovery ?? store.releaseRecovery)(receipt.childId, consumer);
+    }
+    catch {
+        released = false;
+    }
+    if (!released) {
+        return releaseResult(request, taskId, receipt, false, true);
+    }
+    return result(request, 'applied', { taskId, receiptId: receipt.id, childId: receipt.childId });
+}
+export { RECOVERY_NOTE_PREFIX, parseRecoveryNote, recoveryFailure, recoveryConsumer, recoverStartedLifecycleUnderLock, renderRecoveryNote };
+//# sourceMappingURL=lifecycle-recovery.js.map

package/dist/lib/task/lifecycle.js

@@ -2,15 +2,18 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendActivityEntry, locateActivityLog } from './activity-log.js';
-import { artifactFamilyCatalog, inspectArtifactDirectory, parseArtifactName } from './artifact-lifecycle.js';
+import { artifactFamilyCatalog, inspectArtifactDirectory } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { locateHotTaskDirs, resolveTaskRef, TASK_ID_RE } from './resolve-ref.js';
 import { configuredShortIdLength, executeShortIdCommand, loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { validateCurrentTaskContract } from './current-contract.js';
 import { isValidAgentInfraVersion } from '../version.js';
+import { taskIssueIdentity } from '../platform/task-identities.js';
+import { resourceIdentityEquals } from '../platform/resource-identity.js';
 const lifecycleIntentCatalog = [
-    'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore'
+    'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'
 ];
 const lifecycleFailureCatalog = [
     'LIFECYCLE_DIRECTORY_RENAME_FAILED',
@@ -147,6 +150,8 @@ function actionAndNote(request, restoredFiles = 0) {
         return { action: 'Close Codescan', note: `Code Scanning alert #${request.alertNumber} dismissed: ${request.reason}` };
     if (request.intent === 'close-dependabot')
         return { action: 'Close Dependabot', note: `Dependabot alert #${request.alertNumber} dismissed: ${request.reason}` };
+    if (request.intent === 'recover-started')
+        return { action: 'Recover Started', note: request.reason };
     return { action: 'Restore Task', note: `Restored ${restoredFiles} files from Issue #${request.issueNumber}` };
 }
 function matchingCompletion(content, request, restoredFiles = 0) {
@@ -196,8 +201,10 @@ function validateRestoreStaging(request, repoRoot, taskId) {
         return { code: 'LIFECYCLE_STAGING_INVALID', message: 'restore staging has no task.md' };
     try {
         const frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(taskFile, 'utf8'));
-        if (frontmatter.id !== taskId || Number(frontmatter.issue_number) !== request.issueNumber || frontmatter.current_step === 'completed') {
-            return { code: 'LIFECYCLE_STAGING_IDENTITY_INVALID', message: 'restore task identity, issue, or current_step is invalid' };
+        const issueIdentity = taskIssueIdentity(frontmatter);
+        const requestedIssueIdentity = { kind: 'number', value: request.issueNumber };
+        if (frontmatter.id !== taskId || !issueIdentity || !resourceIdentityEquals(issueIdentity, requestedIssueIdentity) || frontmatter.current_step === 'completed') {
+            return { code: 'LIFECYCLE_STAGING_IDENTITY_INVALID', message: 'restore task identity, platform issue identity, or current_step is invalid' };
         }
     }
     catch (error) {
@@ -296,6 +303,23 @@ function parseJournal(content) {
     }
     return value;
 }
+/** Recovery reads the same journal contract as the lifecycle writer. */
+export function readLifecycleJournalEvidence(repoRoot, taskId) {
+    const journalPath = locateHotTaskDirs(repoRoot, taskId)
+        .map((entry) => path.join(entry.taskDir, '.task-lifecycle.json'))
+        .find((candidate) => fs.existsSync(candidate));
+    if (!journalPath)
+        return { exists: false, completedSteps: [], failure: null };
+    try {
+        const journal = parseJournal(fs.readFileSync(journalPath, 'utf8'));
+        if (journal.taskId !== taskId)
+            throw new Error('journal task identity mismatch');
+        return { exists: true, completedSteps: journal.completedSteps, failure: journal.failure?.code ?? null };
+    }
+    catch {
+        return { exists: true, completedSteps: [], failure: 'SANDBOX_CONTROL_LIFECYCLE_JOURNAL_INVALID' };
+    }
+}
 function directoryManifest(root) {
     const entries = [];
     const visit = (current, relative = '') => {
@@ -356,6 +380,9 @@ function removeCopiedSource(source, target) {
     fs.rmSync(source, { recursive: true, force: false });
 }
 function applyTaskLifecycle(requestInput, options = {}) {
+    if (requestInput.intent === 'recover-started') {
+        return failed(requestInput, { code: 'LIFECYCLE_RECOVERY_REQUIRES_AUTHORITY', message: 'recover-started must be dispatched through task control authority' });
+    }
     const normalized = normalizedRequest(requestInput);
     if ('code' in normalized)
         return failed(requestInput, normalized);