@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/manual-validation-receipt.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { MANUAL_VALIDATION_ARTIFACT as ARTIFACT, MANUAL_VALIDATION_SHA40 as SHA40, MANUAL_VALIDATION_SHA64 as SHA64, MANUAL_VALIDATION_TASK_ID as TASK_ID, exactKeys, isRecord, validTimestamp, writeJsonAtomic } from './manual-validation-shared.js';
+const MANUAL_VALIDATION_RECEIPT_SCHEMA = 'agent-infra/manual-validation-receipt';
+const MANUAL_VALIDATION_RECEIPT_VERSION = 1;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_INVALID', message } };
+}
+function canonicalPayload(receipt) {
+    return {
+        schema: MANUAL_VALIDATION_RECEIPT_SCHEMA,
+        version: MANUAL_VALIDATION_RECEIPT_VERSION,
+        transactionId: receipt.transactionId,
+        taskId: receipt.taskId,
+        prNumber: receipt.prNumber,
+        prHeadSha: receipt.prHeadSha,
+        evidenceDigest: receipt.evidenceDigest,
+        artifact: receipt.artifact,
+        artifactSha256: receipt.artifactSha256,
+        pendingSummaryDigest: receipt.pendingSummaryDigest,
+        finalSummaryDigest: receipt.finalSummaryDigest,
+        committedAt: receipt.committedAt
+    };
+}
+function manualValidationReceiptDigest(receipt) {
+    return createHash('sha256').update(JSON.stringify(canonicalPayload(receipt)), 'utf8').digest('hex');
+}
+function manualValidationFinalSummaryDigest(body) {
+    const heading = /^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.exec(body);
+    const afterHeading = heading ? body.slice(heading.index + heading[0].length) : '';
+    const nextSection = heading ? /^#{1,3}\s/mu.exec(afterHeading) : null;
+    const projection = heading
+        ? body.slice(heading.index, heading.index + heading[0].length + (nextSection?.index ?? afterHeading.length)).replace(/\s+$/u, '')
+        : body;
+    const preimage = projection.replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
+    return createHash('sha256').update(preimage, 'utf8').digest('hex');
+}
+function manualValidationFinalSummaryProjectionMatches(body, receipt) {
+    const identity = `transaction=${receipt.transactionId}; receipt=${receipt.receiptDigest}; evidence=${receipt.evidenceDigest}; head=${receipt.prHeadSha}`;
+    return body.includes(identity) && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
+}
+function validateManualValidationReceipt(value, expected) {
+    if (!isRecord(value))
+        return invalid('receipt must be a JSON object');
+    const keys = ['schema', 'version', 'transactionId', 'taskId', 'prNumber', 'prHeadSha', 'evidenceDigest', 'artifact', 'artifactSha256', 'pendingSummaryDigest', 'finalSummaryDigest', 'committedAt', 'receiptDigest'];
+    const keyError = exactKeys(value, keys, 'receipt');
+    if (keyError)
+        return invalid(keyError);
+    if (value.schema !== MANUAL_VALIDATION_RECEIPT_SCHEMA || value.version !== MANUAL_VALIDATION_RECEIPT_VERSION)
+        return invalid('receipt schema or version is unsupported');
+    if (typeof value.transactionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value.transactionId))
+        return invalid('transactionId is invalid');
+    if (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId))
+        return invalid('taskId is invalid');
+    const prNumber = value.prNumber;
+    if (!Number.isSafeInteger(prNumber) || prNumber <= 0)
+        return invalid('prNumber is invalid');
+    for (const [name, pattern] of [['prHeadSha', SHA40], ['evidenceDigest', SHA64], ['artifactSha256', SHA64], ['pendingSummaryDigest', SHA64], ['finalSummaryDigest', SHA64], ['receiptDigest', SHA64]]) {
+        if (typeof value[name] !== 'string' || !pattern.test(value[name]))
+            return invalid(`${name} is invalid`);
+    }
+    if (typeof value.artifact !== 'string' || !ARTIFACT.test(value.artifact))
+        return invalid('artifact is not a canonical manual-validation artifact');
+    if (!validTimestamp(value.committedAt))
+        return invalid('committedAt is invalid');
+    const receipt = value;
+    if (manualValidationReceiptDigest(receipt) !== receipt.receiptDigest)
+        return invalid('receiptDigest does not match receipt contents');
+    if (expected && Object.entries(expected).some(([key, expectedValue]) => expectedValue !== undefined && receipt[key] !== expectedValue)) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH', message: 'receipt identity does not match the expected transaction' } };
+    }
+    return { ok: true, value: receipt };
+}
+function createManualValidationReceipt(input) {
+    const payload = canonicalPayload(input);
+    const receipt = { ...payload, receiptDigest: manualValidationReceiptDigest(input) };
+    const checked = validateManualValidationReceipt(receipt);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+function manualValidationReceiptPath(taskDir) {
+    return path.join(taskDir, '.manual-validation', 'receipt.json');
+}
+function writeManualValidationReceiptAtomic(taskDir, receipt) {
+    const checked = validateManualValidationReceipt(receipt);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    const target = manualValidationReceiptPath(taskDir);
+    return writeJsonAtomic(target, receipt);
+}
+function readManualValidationReceipt(taskDir, expected) {
+    const file = manualValidationReceiptPath(taskDir);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, error: { code: error.code === 'ENOENT' ? 'MANUAL_VALIDATION_RECEIPT_MISSING' : 'MANUAL_VALIDATION_RECEIPT_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationReceipt(value, expected);
+}
+export { MANUAL_VALIDATION_RECEIPT_SCHEMA, MANUAL_VALIDATION_RECEIPT_VERSION, createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, manualValidationReceiptDigest, manualValidationReceiptPath, readManualValidationReceipt, validateManualValidationReceipt, writeManualValidationReceiptAtomic };
+//# sourceMappingURL=manual-validation-receipt.js.map

package/dist/lib/task/manual-validation-shared.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const MANUAL_VALIDATION_TASK_ID = /^TASK-\d{8}-\d{6}$/u;
+const MANUAL_VALIDATION_SHA40 = /^[a-f0-9]{40}$/u;
+const MANUAL_VALIDATION_SHA64 = /^[a-f0-9]{64}$/u;
+const MANUAL_VALIDATION_ARTIFACT = /^manual-validation(?:-r[2-9]|-r[1-9]\d+)?.md$/u;
+const MANUAL_VALIDATION_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function exactKeys(value, keys, label) {
+    const allowed = new Set(keys);
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown)
+        return `${label} contains unknown field '${unknown}'`;
+    const missing = keys.find((key) => !Object.hasOwn(value, key));
+    return missing ? `${label} is missing '${missing}'` : null;
+}
+function validTimestamp(value) {
+    return typeof value === 'string' && MANUAL_VALIDATION_TIMESTAMP.test(value) && Number.isFinite(Date.parse(value));
+}
+function writeJsonAtomic(file, value) {
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort cleanup of our own temp file */ }
+        throw error;
+    }
+    return file;
+}
+export { MANUAL_VALIDATION_ARTIFACT, MANUAL_VALIDATION_SHA40, MANUAL_VALIDATION_SHA64, MANUAL_VALIDATION_TASK_ID, MANUAL_VALIDATION_TIMESTAMP, exactKeys, isRecord, validTimestamp, writeJsonAtomic };
+//# sourceMappingURL=manual-validation-shared.js.map

package/dist/lib/task/manual-validation-transaction.js

@@ -0,0 +1,243 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateManualValidationReceipt } from './manual-validation-receipt.js';
+import { MANUAL_VALIDATION_ARTIFACT as ARTIFACT, MANUAL_VALIDATION_SHA40 as SHA40, MANUAL_VALIDATION_SHA64 as SHA64, MANUAL_VALIDATION_TASK_ID as TASK_ID, exactKeys, isRecord, validTimestamp, writeJsonAtomic } from './manual-validation-shared.js';
+const MANUAL_VALIDATION_TRANSACTION_SCHEMA = 'agent-infra/manual-validation-transaction';
+const MANUAL_VALIDATION_TRANSACTION_VERSION = 1;
+const TRANSACTION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_INVALID', message } };
+}
+function summaryPreimageDigest(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+function validateManualValidationTransaction(value, expected) {
+    if (!isRecord(value))
+        return invalid('transaction must be a JSON object');
+    const keys = ['schema', 'version', 'transactionId', 'taskId', 'prNumber', 'prHeadSha', 'evidenceDigest', 'summaryPreimage', 'pendingSummaryDigest', 'finalSummaryDigest', 'artifact', 'phase', 'committedReceipt', 'eventAppended', 'attempt', 'postWriteVerified', 'createdAt', 'updatedAt', 'error'];
+    const keyError = exactKeys(value, keys, 'transaction');
+    if (keyError)
+        return invalid(keyError);
+    if (value.schema !== MANUAL_VALIDATION_TRANSACTION_SCHEMA || value.version !== MANUAL_VALIDATION_TRANSACTION_VERSION)
+        return invalid('transaction schema or version is unsupported');
+    if (typeof value.transactionId !== 'string' || !TRANSACTION_ID.test(value.transactionId))
+        return invalid('transactionId is invalid');
+    if (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId))
+        return invalid('taskId is invalid');
+    const prNumber = value.prNumber;
+    if (!Number.isSafeInteger(prNumber) || prNumber <= 0)
+        return invalid('prNumber is invalid');
+    if (typeof value.prHeadSha !== 'string' || !SHA40.test(value.prHeadSha))
+        return invalid('prHeadSha is invalid');
+    if (typeof value.evidenceDigest !== 'string' || !SHA64.test(value.evidenceDigest))
+        return invalid('evidenceDigest is invalid');
+    if (!isRecord(value.summaryPreimage))
+        return invalid('summaryPreimage is invalid');
+    const preimage = value.summaryPreimage;
+    const preimageKeyError = exactKeys(preimage, ['commentId', 'body', 'digest'], 'summaryPreimage');
+    if (preimageKeyError)
+        return invalid(preimageKeyError);
+    if (preimage.commentId !== null && typeof preimage.commentId !== 'number' && typeof preimage.commentId !== 'string')
+        return invalid('summaryPreimage.commentId is invalid');
+    if (typeof preimage.body !== 'string' || typeof preimage.digest !== 'string' || !SHA64.test(preimage.digest) || summaryPreimageDigest(preimage.body) !== preimage.digest)
+        return invalid('summaryPreimage digest is invalid');
+    for (const field of ['pendingSummaryDigest', 'finalSummaryDigest'])
+        if (typeof value[field] !== 'string' || !SHA64.test(value[field]))
+            return invalid(`${field} is invalid`);
+    if (typeof value.artifact !== 'string' || !ARTIFACT.test(value.artifact))
+        return invalid('artifact is invalid');
+    if (!['prepared', 'summary-staged', 'receipt-committed', 'final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'].includes(value.phase))
+        return invalid('phase is invalid');
+    if (value.committedReceipt !== null && (typeof value.committedReceipt !== 'string' || !SHA64.test(value.committedReceipt)))
+        return invalid('committedReceipt is invalid');
+    if (typeof value.eventAppended !== 'boolean' || typeof value.postWriteVerified !== 'boolean')
+        return invalid('transaction completion flags are invalid');
+    const attempt = value.attempt;
+    if (!Number.isSafeInteger(attempt) || attempt < 1)
+        return invalid('attempt is invalid');
+    if (!validTimestamp(value.createdAt) || !validTimestamp(value.updatedAt))
+        return invalid('transaction timestamps are invalid');
+    if (value.error !== null && (typeof value.error !== 'string' || !value.error || /[\r\n]/u.test(value.error)))
+        return invalid('transaction error is invalid');
+    if (['receipt-committed', 'final-promotion-in-progress', 'committed'].includes(value.phase) && value.committedReceipt === null)
+        return invalid('receipt-backed phases require committedReceipt');
+    if (['final-promotion-in-progress', 'committed'].includes(value.phase) && !value.eventAppended)
+        return invalid('final promotion requires an appended completion event');
+    if (value.phase === 'committed' && !value.postWriteVerified)
+        return invalid('committed phase requires post-write verification');
+    const transaction = value;
+    if (expected && Object.entries(expected).some(([key, expectedValue]) => expectedValue !== undefined && transaction[key] !== expectedValue)) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH', message: 'transaction identity does not match the expected operation' } };
+    }
+    return { ok: true, value: transaction };
+}
+function createManualValidationTransaction(input) {
+    const transaction = {
+        schema: MANUAL_VALIDATION_TRANSACTION_SCHEMA,
+        version: MANUAL_VALIDATION_TRANSACTION_VERSION,
+        transactionId: input.transactionId ?? `mv-${randomUUID()}`,
+        taskId: input.taskId,
+        prNumber: input.prNumber,
+        prHeadSha: input.prHeadSha,
+        evidenceDigest: input.evidenceDigest,
+        summaryPreimage: input.summaryPreimage,
+        pendingSummaryDigest: input.pendingSummaryDigest,
+        finalSummaryDigest: input.finalSummaryDigest,
+        artifact: input.artifact,
+        phase: 'prepared',
+        committedReceipt: null,
+        eventAppended: false,
+        attempt: input.attempt,
+        postWriteVerified: false,
+        createdAt: input.createdAt,
+        updatedAt: input.updatedAt,
+        error: null
+    };
+    const checked = validateManualValidationTransaction(transaction);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+const allowedTransitions = {
+    prepared: ['prepared', 'summary-staged', 'aborted', 'recovery-required'],
+    'summary-staged': ['summary-staged', 'receipt-committed', 'aborted', 'recovery-required'],
+    'receipt-committed': ['receipt-committed', 'final-promotion-in-progress', 'aborted', 'recovery-required'],
+    'final-promotion-in-progress': ['final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'],
+    committed: ['committed'],
+    aborted: ['aborted', 'prepared'],
+    'recovery-required': ['recovery-required', 'prepared']
+};
+function transitionManualValidationTransaction(current, phase, patch = {}) {
+    if (!allowedTransitions[current.phase].includes(phase))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: `cannot transition from ${current.phase} to ${phase}` } };
+    if (phase === 'final-promotion-in-progress' && (!current.eventAppended && patch.eventAppended !== true))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final promotion requires an appended completion event' } };
+    const next = {
+        ...current,
+        phase,
+        committedReceipt: patch.committedReceipt !== undefined ? patch.committedReceipt : current.committedReceipt,
+        eventAppended: patch.eventAppended ?? current.eventAppended,
+        postWriteVerified: patch.postWriteVerified ?? current.postWriteVerified,
+        attempt: patch.attempt ?? current.attempt,
+        error: patch.error !== undefined ? patch.error : current.error,
+        updatedAt: patch.updatedAt ?? new Date().toISOString()
+    };
+    const checked = validateManualValidationTransaction(next);
+    if (!checked.ok)
+        return checked;
+    return checked;
+}
+function retryManualValidationTransaction(current, now = new Date().toISOString()) {
+    if (!['aborted', 'recovery-required'].includes(current.phase))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'only aborted or recovery-required transactions can be retried' } };
+    return transitionManualValidationTransaction(current, 'prepared', {
+        updatedAt: now,
+        error: null,
+        committedReceipt: null,
+        eventAppended: false,
+        postWriteVerified: false,
+        attempt: current.attempt + 1
+    });
+}
+function manualValidationTransactionPath(taskDir) {
+    return path.join(taskDir, '.manual-validation', 'transaction.json');
+}
+function manualValidationGenerationPaths(taskDir, transaction) {
+    const stateDir = path.join(taskDir, '.manual-validation');
+    const historyDir = path.join(stateDir, 'history');
+    return {
+        receipt: {
+            current: path.join(stateDir, 'receipt.json'),
+            history: path.join(historyDir, `receipt-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+        },
+        transaction: {
+            current: manualValidationTransactionPath(taskDir),
+            history: path.join(historyDir, `transaction-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+        }
+    };
+}
+function readReceiptAt(file, transaction) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'missing';
+        throw new Error(`manual-validation receipt is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const checked = validateManualValidationReceipt(value, {
+        transactionId: transaction.transactionId,
+        taskId: transaction.taskId,
+        prNumber: transaction.prNumber,
+        prHeadSha: transaction.prHeadSha,
+        evidenceDigest: transaction.evidenceDigest,
+        artifact: transaction.artifact
+    });
+    if (!checked.ok)
+        throw new Error(`manual-validation receipt is invalid: ${checked.error.message}`);
+    if (transaction.committedReceipt !== null && checked.value.receiptDigest !== transaction.committedReceipt) {
+        throw new Error('manual-validation receipt does not match the committed transaction');
+    }
+    return 'valid';
+}
+function validateManualValidationGenerationArchive(taskDir, transaction, requireReceipt = false) {
+    const paths = manualValidationGenerationPaths(taskDir, transaction);
+    const currentTransaction = fs.existsSync(paths.transaction.current);
+    const archivedTransaction = fs.existsSync(paths.transaction.history);
+    if (currentTransaction && archivedTransaction)
+        throw new Error(`manual-validation archive has conflicting transaction files for ${transaction.transactionId}`);
+    if (!currentTransaction && !archivedTransaction)
+        throw new Error(`manual-validation archive source is missing: ${paths.transaction.current}`);
+    const currentReceipt = requireReceipt
+        ? readReceiptAt(paths.receipt.current, transaction)
+        : (fs.existsSync(paths.receipt.current) ? 'valid' : 'missing');
+    const archivedReceipt = requireReceipt
+        ? readReceiptAt(paths.receipt.history, transaction)
+        : (fs.existsSync(paths.receipt.history) ? 'valid' : 'missing');
+    if (requireReceipt && currentReceipt === 'missing' && archivedReceipt === 'missing') {
+        throw new Error(`manual-validation receipt is missing for transaction ${transaction.transactionId}`);
+    }
+    if (currentReceipt === 'valid' && archivedReceipt === 'valid') {
+        throw new Error(`manual-validation archive has conflicting receipt files for ${transaction.transactionId}`);
+    }
+}
+function archiveManualValidationGeneration(taskDir, transaction, requireReceipt = false, options = {}) {
+    const paths = manualValidationGenerationPaths(taskDir, transaction);
+    validateManualValidationGenerationArchive(taskDir, transaction, requireReceipt);
+    fs.mkdirSync(path.dirname(paths.receipt.history), { recursive: true });
+    const move = (source, target, required) => {
+        if (!fs.existsSync(source)) {
+            if (fs.existsSync(target) || !required)
+                return;
+            throw new Error(`manual-validation archive source is missing: ${source}`);
+        }
+        if (fs.existsSync(target))
+            throw new Error(`manual-validation archive target already exists: ${target}`);
+        fs.renameSync(source, target);
+    };
+    move(paths.receipt.current, paths.receipt.history, requireReceipt);
+    options.afterReceiptMove?.();
+    move(paths.transaction.current, paths.transaction.history, true);
+}
+function writeManualValidationTransactionAtomic(taskDir, transaction) {
+    const checked = validateManualValidationTransaction(transaction);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    const target = manualValidationTransactionPath(taskDir);
+    return writeJsonAtomic(target, transaction);
+}
+function readManualValidationTransaction(taskDir, expected) {
+    const file = manualValidationTransactionPath(taskDir);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, error: { code: error.code === 'ENOENT' ? 'MANUAL_VALIDATION_TRANSACTION_MISSING' : 'MANUAL_VALIDATION_TRANSACTION_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationTransaction(value, expected);
+}
+export { MANUAL_VALIDATION_TRANSACTION_SCHEMA, MANUAL_VALIDATION_TRANSACTION_VERSION, archiveManualValidationGeneration, createManualValidationTransaction, manualValidationTransactionPath, validateManualValidationGenerationArchive, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationTransaction, writeManualValidationTransactionAtomic };
+//# sourceMappingURL=manual-validation-transaction.js.map

package/dist/lib/task/markdown.js

@@ -0,0 +1,47 @@
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)\s*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})\s*$/;
+const ANCHOR = /^\s*<a\s+id=(['"])([^'"]+)\1\s*><\/a>\s*$/;
+function sourceLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        const newline = content.indexOf('\n', start);
+        const end = newline === -1 ? content.length : newline;
+        lines.push({ start, end, text: content.slice(start, end).replace(/\r$/, '') });
+        start = newline === -1 ? content.length : newline + 1;
+    }
+    return lines;
+}
+function scanVisibleMarkdown(content) {
+    const lines = sourceLines(content);
+    const visible = [];
+    const headings = [];
+    const anchors = [];
+    let fence = null;
+    for (const line of lines) {
+        if (fence) {
+            const close = line.text.match(FENCE_CLOSE);
+            if (close && close[1][0] === fence.character && close[1].length >= fence.length)
+                fence = null;
+            continue;
+        }
+        const open = line.text.match(FENCE_OPEN);
+        const marker = open?.[1];
+        const info = open?.[2] ?? '';
+        if (marker && !(marker[0] === '`' && info.includes('`'))) {
+            fence = { character: marker[0], length: marker.length };
+            continue;
+        }
+        visible.push(line);
+        const heading = line.text.match(HEADING);
+        if (heading)
+            headings.push({ ...line, level: heading[1].length, text: heading[2].trim() });
+        const anchor = line.text.match(ANCHOR);
+        if (anchor)
+            anchors.push({ ...line, id: anchor[2] });
+    }
+    return { lines: visible, headings, anchors, hasUnclosedFence: fence !== null };
+}
+export { scanVisibleMarkdown };
+//# sourceMappingURL=markdown.js.map

package/dist/lib/task/orchestration.js

@@ -1,12 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
+import { artifactName, maxArtifactRound } from './artifact-name.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { validateCurrentTaskContract } from './current-contract.js';
 import { parseReviewSummary } from './review-artifacts.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
+import { activateDelegation, abortActivatedDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
 import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
@@ -20,6 +21,7 @@ import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './del
 import { buildLifecycleFacts, canStart, recommendNext } from './capabilities.js';
 import { hasOpenLifecycleExecution } from './activity-log.js';
 import { invalidationBlocks } from './invalidation.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
 function supportsLifecycleDelegation(client) {
     return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
         && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
@@ -101,7 +103,7 @@ function isRecovery(value) {
         && guards.completionEvidenceAbsent === true
         && value.resultingStatus === 'running';
 }
-function isCompletionEvidence(value) {
+export function isCompletionEvidence(value) {
     return hasExactKeys(value, [
         'kind', 'observedAt', 'head', 'headTree', 'worktreeTree', 'lastReviewedCommit', 'prNumber', 'prHead'
     ])
@@ -437,18 +439,8 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
     atomicWrite(orchestrationPath(resolved.taskDir), run);
     return { status: 'running', changed: true, taskId: resolved.taskId, run, next: null, error: null };
 }
-function highestRound(taskDir, family) {
-    const pattern = new RegExp(`^${family}(?:-r(\\d+))?\\.md$`);
-    return fs.readdirSync(taskDir).reduce((max, name) => {
-        const match = pattern.exec(name);
-        return match ? Math.max(max, match[1] ? Number(match[1]) : 1) : max;
-    }, 0);
-}
-function artifactName(family, round) {
-    return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
-}
 function validateSavedCurrentDiffBase(repoRoot, metadata, taskDir, reviewedHead) {
-    const reviewRound = highestRound(taskDir, 'review-code');
+    const reviewRound = maxArtifactRound(fs.readdirSync(taskDir), 'review-code');
     const reviewContent = fs.readFileSync(path.join(taskDir, artifactName('review-code', reviewRound)), 'utf8');
     const savedTargetHead = extractReviewTargetHead(reviewContent);
     const savedDiffBase = extractReviewDiffBase(reviewContent);
@@ -492,10 +484,9 @@ function routeFromFacts(facts) {
     if (action === 'manual-validation' || action === 'validation-run')
         return null;
     const family = action === 'analysis' ? 'analysis' : action;
-    const round = Math.max(0, ...[...(facts.artifacts[family] ?? []), ...(facts.staleArtifacts?.[family] ?? [])].map((name) => {
-        const match = /-r(\d+)\.md$/.exec(name);
-        return match ? Number(match[1]) : 1;
-    })) + 1;
+    const round = maxArtifactRound([
+        ...(facts.artifacts[family] ?? []), ...(facts.staleArtifacts?.[family] ?? [])
+    ], family) + 1;
     const command = action === 'analysis' ? 'analyze-task' : action === 'plan' ? 'plan-task' : action === 'code' ? 'code-task' : action;
     const role = action.startsWith('review-') ? 'reviewer' : 'executor';
     return { action: command, role, stage: action, round, artifact: artifactName(family, round) };
@@ -554,7 +545,7 @@ function routeOrchestration(taskRef, options = {}) {
     if (!routed)
         return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
     if ('completion' in routed) {
-        const reviewRound = highestRound(resolved.taskDir, 'review-code');
+        const reviewRound = maxArtifactRound(fs.readdirSync(resolved.taskDir), 'review-code');
         const review = parseReviewSummary(fs.readFileSync(path.join(resolved.taskDir, artifactName('review-code', reviewRound)), 'utf8'));
         if (!review.ok || review.summary.manualValidation === null) {
             return failed('ORCHESTRATION_REVIEW_INVALID', 'latest code review has no numeric manual-validation count', resolved.taskId);
@@ -692,6 +683,13 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     if (input.client === 'codex' && !input.lifecycleProvenance) {
         return failed('ORCHESTRATION_CODEX_PROVENANCE_REQUIRED', 'Codex prepare requires lifecycle provenance', resolved.taskId);
     }
+    if (input.lifecycleRecoveryAttestation
+        && (input.lifecycleRecoveryAttestation.phase !== 'orchestration.prepare'
+            || input.lifecycleRecoveryAttestation.taskId !== resolved.taskId
+            || input.lifecycleRecoveryAttestation.artifact !== next.artifact
+            || input.lifecycleRecoveryAttestation.round !== next.round)) {
+        return failed('LIFECYCLE_AUTHORITY_TUPLE_MISMATCH', 'orchestration authority does not match the routed stage', resolved.taskId);
+    }
     const expectedPolicy = run.modelPolicy[next.role];
     if (input.requestedModel !== expectedPolicy.model) {
         return failed('ORCHESTRATION_REQUESTED_MODEL_MISMATCH', `requested model does not match the persisted ${next.role} model`, resolved.taskId);
@@ -1093,6 +1091,55 @@ function recoverPreparedOrchestrationDelegation(taskRef, options = {}) {
         return failed('ORCHESTRATION_PREPARED_RECOVERY_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
 }
+function recoverActivatedOrchestrationDelegationUnderLock(taskRef, event, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    const run = readRun(resolved.taskDir, options);
+    if (!run)
+        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
+    const matches = [
+        ...(run.pendingDelegation ? [run.pendingDelegation] : []),
+        ...run.receipts.filter((receipt) => receipt.id === event.receiptId)
+    ];
+    const receipt = matches.find((candidate) => candidate.id === event.receiptId);
+    if (!receipt)
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'recovery receipt does not exist', resolved.taskId);
+    if (receipt.taskId !== resolved.taskId
+        || receipt.stage !== event.stage
+        || receipt.round !== event.round
+        || receipt.artifact !== event.artifact
+        || receipt.childId !== event.childId
+        || normalizeAgentToken(event.startedAgent) !== normalizeAgentToken(receipt.client)) {
+        return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'recovery selector does not match the delegation receipt', resolved.taskId);
+    }
+    if (receipt.status === 'aborted' && run.pendingDelegation === null) {
+        return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
+    }
+    if (run.pendingDelegation?.id !== receipt.id || receipt.status !== 'activated') {
+        return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'recovery requires one matching activated pending delegation', resolved.taskId);
+    }
+    if (run.receipts.some((candidate) => candidate.id === receipt.id)) {
+        return failed('ORCHESTRATION_RECEIPT_DUPLICATE', 'recovery receipt already exists in the completed receipt history', resolved.taskId);
+    }
+    const aborted = abortActivatedDelegation(receipt, {
+        childId: event.childId,
+        stopRevision: event.stopRevision,
+        consumer: event.consumer,
+        consumedAt: event.consumedAt
+    });
+    if (!aborted.ok)
+        return failed(aborted.code, aborted.message, resolved.taskId);
+    const updated = withUpdatedRun(run, {
+        status: 'running',
+        pause: null,
+        nextStage: null,
+        pendingDelegation: null,
+        receipts: Object.freeze([...run.receipts, aborted.receipt])
+    }, options.now);
+    saveRun(resolved.taskDir, updated);
+    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
+}
 function completeOrchestrationStage(taskRef, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -1207,5 +1254,5 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     saveRun(resolved.taskDir, updated);
     return { status: 'paused', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
-export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, orchestrationPath, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverPreparedOrchestrationDelegation, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, sealOrchestrationDelegation, statusOrchestration, };
+export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, orchestrationPath, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverPreparedOrchestrationDelegation, recoverActivatedOrchestrationDelegationUnderLock, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, sealOrchestrationDelegation, statusOrchestration, };
 //# sourceMappingURL=orchestration.js.map