@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/dist/lib/task/orchestration.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+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';
@@ -33,10 +34,12 @@ const ORCHESTRATION_STATE_INVALID_MESSAGE = 'orchestration.json does not match t
 class OrchestrationStateError extends Error {
     code = 'ORCHESTRATION_STATE_INVALID';
     taskId;
-    constructor(taskId = null) {
+    reasonCodes;
+    constructor(taskId = null, reasonCodes = []) {
         super(ORCHESTRATION_STATE_INVALID_MESSAGE);
         this.name = 'OrchestrationStateError';
         this.taskId = taskId;
+        this.reasonCodes = Object.freeze([...reasonCodes]);
     }
 }
 function isRecord(value) {
@@ -99,7 +102,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'
     ])
@@ -117,48 +120,151 @@ const ORCHESTRATION_RUN_KEYS = [
     'modelPolicySource', 'recoveryHistory', 'baseline', 'pendingDelegation', 'receipts',
     'pause', 'commitAuthorization', 'completionEvidence', 'createdAt', 'updatedAt'
 ];
-function parseOrchestrationRun(value, expectedTaskId) {
-    if (!hasExactKeys(value, ORCHESTRATION_RUN_KEYS)
-        || !exactText(value.taskId)
-        || (expectedTaskId !== undefined && value.taskId !== expectedTaskId)
-        || !exactText(value.runId)
-        || !['running', 'paused', 'completed'].includes(value.status)
-        || !(value.nextStage === null || ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code', 'commit'].includes(value.nextStage))
-        || !Number.isSafeInteger(value.stepCount) || value.stepCount < 0
-        || !Number.isSafeInteger(value.maxSteps) || value.maxSteps < 1
-        || !isModelPolicy(value.modelPolicy)
-        || !isModelPolicySource(value.modelPolicySource)
-        || !Array.isArray(value.recoveryHistory) || !value.recoveryHistory.every(isRecovery)
-        || typeof value.baseline !== 'string'
-        || !(value.pendingDelegation === null || isDelegationReceipt(value.pendingDelegation))
-        || !Array.isArray(value.receipts) || !value.receipts.every(isDelegationReceipt)
-        || !(value.pause === null || isPause(value.pause))
-        || !hasExactKeys(value.commitAuthorization, ['issuedAt', 'consumedAt'])
-        || !nullableText(value.commitAuthorization.issuedAt)
-        || !nullableText(value.commitAuthorization.consumedAt)
-        || !(value.completionEvidence === null || isCompletionEvidence(value.completionEvidence))
-        || !exactText(value.createdAt)
-        || !exactText(value.updatedAt)) {
-        throw new OrchestrationStateError();
-    }
-    const receipts = [...value.receipts, ...(value.pendingDelegation ? [value.pendingDelegation] : [])];
-    if (receipts.some((receipt) => receipt.taskId !== value.taskId || receipt.runId !== value.runId)) {
-        throw new OrchestrationStateError();
+function orchestrationStateReasonCodes(value, expectedTaskId) {
+    if (!hasExactKeys(value, ORCHESTRATION_RUN_KEYS))
+        return ['top-level-keys'];
+    const record = value;
+    const reasons = [];
+    if (!exactText(record.taskId))
+        reasons.push('taskId');
+    else if (expectedTaskId !== undefined && record.taskId !== expectedTaskId)
+        reasons.push('taskId-mismatch');
+    if (!exactText(record.runId))
+        reasons.push('runId');
+    if (!['running', 'paused', 'completed'].includes(record.status))
+        reasons.push('status');
+    if (!(record.nextStage === null || ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code', 'commit'].includes(record.nextStage))) {
+        reasons.push('nextStage');
+    }
+    if (!Number.isSafeInteger(record.stepCount) || record.stepCount < 0)
+        reasons.push('stepCount');
+    if (!Number.isSafeInteger(record.maxSteps) || record.maxSteps < 1)
+        reasons.push('maxSteps');
+    if (!isModelPolicy(record.modelPolicy))
+        reasons.push('modelPolicy');
+    if (!isModelPolicySource(record.modelPolicySource))
+        reasons.push('modelPolicySource');
+    if (!Array.isArray(record.recoveryHistory) || !record.recoveryHistory.every(isRecovery))
+        reasons.push('recoveryHistory');
+    if (typeof record.baseline !== 'string')
+        reasons.push('baseline');
+    if (!(record.pendingDelegation === null || isDelegationReceipt(record.pendingDelegation)))
+        reasons.push('pendingDelegation');
+    if (!Array.isArray(record.receipts) || !record.receipts.every(isDelegationReceipt))
+        reasons.push('receipts');
+    if (!(record.pause === null || isPause(record.pause)))
+        reasons.push('pause');
+    if (!hasExactKeys(record.commitAuthorization, ['issuedAt', 'consumedAt'])) {
+        reasons.push('commitAuthorization');
+    }
+    else {
+        if (!nullableText(record.commitAuthorization.issuedAt))
+            reasons.push('commitAuthorization.issuedAt');
+        if (!nullableText(record.commitAuthorization.consumedAt))
+            reasons.push('commitAuthorization.consumedAt');
+    }
+    if (!(record.completionEvidence === null || isCompletionEvidence(record.completionEvidence)))
+        reasons.push('completionEvidence');
+    if (!exactText(record.createdAt))
+        reasons.push('createdAt');
+    if (!exactText(record.updatedAt))
+        reasons.push('updatedAt');
+    if (Array.isArray(record.receipts) && record.receipts.every(isDelegationReceipt)
+        && (record.pendingDelegation === null || isDelegationReceipt(record.pendingDelegation))) {
+        const receipts = [...record.receipts, ...(record.pendingDelegation ? [record.pendingDelegation] : [])];
+        if (receipts.some((receipt) => receipt.taskId !== record.taskId || receipt.runId !== record.runId)) {
+            reasons.push('receipt-identity');
+        }
     }
+    return reasons;
+}
+function emitDiagnostic(options, event, fields) {
+    try {
+        options?.diagnosticLog?.(event, fields);
+    }
+    catch {
+        // Diagnostics must never change lifecycle behavior.
+    }
+}
+function fileObservation(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        let realpath = null;
+        try {
+            realpath = fs.realpathSync.native(file);
+        }
+        catch { /* retain the lstat observation */ }
+        return {
+            file,
+            exists: true,
+            fileType: stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : 'other',
+            symbolicLink: stat.isSymbolicLink(),
+            bytes: stat.isFile() ? stat.size : null,
+            mtimeMs: stat.mtimeMs,
+            device: stat.dev,
+            inode: stat.ino,
+            realpath
+        };
+    }
+    catch (error) {
+        return {
+            file,
+            exists: false,
+            fileType: null,
+            symbolicLink: null,
+            bytes: null,
+            mtimeMs: null,
+            device: null,
+            inode: null,
+            realpath: null,
+            fsError: error instanceof Error && 'code' in error ? String(error.code) : null
+        };
+    }
+}
+function parseOrchestrationRun(value, expectedTaskId) {
+    const reasonCodes = orchestrationStateReasonCodes(value, expectedTaskId);
+    if (reasonCodes.length > 0)
+        throw new OrchestrationStateError(expectedTaskId ?? null, reasonCodes);
     return value;
 }
-function readRun(taskDir) {
+function readRun(taskDir, options = {}) {
     const file = orchestrationPath(taskDir);
-    if (!fs.existsSync(file))
-        return null;
     const taskId = path.basename(taskDir);
+    const observed = options.diagnosticLog ? fileObservation(file) : {};
+    if (!fs.existsSync(file)) {
+        emitDiagnostic(options, 'orchestration-state-missing', { taskId, taskDir, ...observed });
+        return null;
+    }
+    emitDiagnostic(options, 'orchestration-state-read-start', { taskId, taskDir, ...observed });
+    let rawBytes = null;
+    let rawSha256 = null;
     try {
-        return parseOrchestrationRun(JSON.parse(fs.readFileSync(file, 'utf8')), taskId);
+        const raw = fs.readFileSync(file, 'utf8');
+        if (options.diagnosticLog) {
+            rawBytes = Buffer.byteLength(raw, 'utf8');
+            rawSha256 = createHash('sha256').update(raw, 'utf8').digest('hex');
+        }
+        const run = parseOrchestrationRun(JSON.parse(raw), taskId);
+        emitDiagnostic(options, 'orchestration-state-read-ok', {
+            taskId, taskDir, file, rawBytes, rawSha256, status: run.status, runId: run.runId,
+            stepCount: run.stepCount, pendingDelegation: run.pendingDelegation !== null
+        });
+        return run;
     }
     catch (error) {
-        if (error instanceof OrchestrationStateError)
-            throw new OrchestrationStateError(taskId);
-        throw new OrchestrationStateError(taskId);
+        const reasonCodes = error instanceof OrchestrationStateError && error.reasonCodes.length > 0
+            ? error.reasonCodes
+            : [error instanceof SyntaxError ? 'json-parse' : 'file-read'];
+        emitDiagnostic(options, 'orchestration-state-read-failed', {
+            taskId,
+            taskDir,
+            ...observed,
+            rawBytes,
+            rawSha256,
+            reasonCodes: reasonCodes.join(','),
+            errorType: error instanceof Error ? error.name : typeof error,
+        });
+        throw new OrchestrationStateError(taskId, reasonCodes);
     }
 }
 function atomicWrite(file, value) {
@@ -232,7 +338,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
     }
     let existing;
     try {
-        existing = readRun(resolved.taskDir);
+        existing = readRun(resolved.taskDir, options);
     }
     catch (error) {
         return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -332,18 +438,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);
@@ -387,10 +483,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) };
@@ -437,7 +532,7 @@ function routeOrchestration(taskRef, options = {}) {
     }
     let run;
     try {
-        run = readRun(resolved.taskDir);
+        run = readRun(resolved.taskDir, options);
     }
     catch (error) {
         return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -449,7 +544,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);
@@ -543,7 +638,7 @@ function statusOrchestration(taskRef, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir);
+    const run = readRun(resolved.taskDir, options);
     if (!run)
         return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
     return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
@@ -555,7 +650,15 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     if (!(options.supportsLifecycleDelegation ?? supportsLifecycleDelegation)(input.client)) {
         return failed('ORCHESTRATION_CLIENT_UNSUPPORTED', `client '${input.client}' does not support lifecycle orchestration`, resolved.taskId);
     }
-    const run = readRun(resolved.taskDir);
+    emitDiagnostic(options, 'orchestration-prepare-start', {
+        taskId: resolved.taskId,
+        taskDir: resolved.taskDir,
+        repoRoot: resolved.repoRoot,
+        client: input.client,
+        requestedModel: input.requestedModel ?? null,
+        requestedReasoningEffort: input.requestedReasoningEffort ?? null
+    });
+    const run = readRun(resolved.taskDir, options);
     if (!run || run.status !== 'running')
         return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'a running orchestration is required', resolved.taskId);
     if (run.pendingDelegation)
@@ -579,6 +682,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);
@@ -643,7 +753,7 @@ function dispatchOrchestrationDelegationUnlocked(taskRef, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir);
+    const run = readRun(resolved.taskDir, options);
     if (!run?.pendingDelegation)
         return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
     if (run.status !== 'running') {
@@ -677,17 +787,44 @@ function matchingDelegations(predicate, options) {
     const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
     if (!fs.existsSync(activeRoot))
         return [];
-    return fs.readdirSync(activeRoot, { withFileTypes: true })
+    emitDiagnostic(options, 'orchestration-active-scan-start', {
+        activeRoot
+    });
+    const matches = fs.readdirSync(activeRoot, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
         .flatMap((entry) => {
-        const run = readRun(path.join(activeRoot, entry.name));
+        const candidateTaskId = entry.name;
+        const candidateTaskDir = path.join(activeRoot, candidateTaskId);
+        emitDiagnostic(options, 'orchestration-active-scan-candidate', {
+            candidateTaskId,
+            candidateTaskDir,
+            orchestrationPath: orchestrationPath(candidateTaskDir)
+        });
+        let run;
+        try {
+            run = readRun(candidateTaskDir, options);
+        }
+        catch (error) {
+            emitDiagnostic(options, 'orchestration-active-scan-candidate-failed', {
+                candidateTaskId,
+                candidateTaskDir,
+                errorType: error instanceof Error ? error.name : typeof error,
+                reasonCodes: error instanceof OrchestrationStateError ? error.reasonCodes.join(',') : null
+            });
+            throw error;
+        }
         if (!run || run.status !== 'running' || !run.pendingDelegation)
             return [];
         const receipt = run.pendingDelegation;
         return predicate(receipt)
-            ? [{ taskId: entry.name, run }]
+            ? [{ taskId: candidateTaskId, run }]
             : [];
     });
+    emitDiagnostic(options, 'orchestration-active-scan-finished', {
+        activeRoot,
+        matchingDelegations: matches.length
+    });
+    return matches;
 }
 function uniqueMatchingDelegation(client, predicate, options) {
     const matches = matchingDelegations((receipt) => receipt.client === client && predicate(receipt), options);
@@ -838,7 +975,7 @@ function activateOrchestrationDelegation(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);
+    const run = readRun(resolved.taskDir, options);
     if (!run?.pendingDelegation)
         return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
     if (run.status !== 'running') {
@@ -864,7 +1001,7 @@ async function awaitOrchestrationDelegationActivation(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);
+        const run = readRun(resolved.taskDir, options);
         if (!run?.pendingDelegation) {
             return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
         }
@@ -901,7 +1038,7 @@ function recoverPreparedOrchestrationDelegation(taskRef, options = {}) {
         return failed(resolved.code, resolved.message, resolved.taskId);
     try {
         return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-orchestration.recover-prepared', () => {
-            const run = readRun(resolved.taskDir);
+            const run = readRun(resolved.taskDir, options);
             const receipt = run?.pendingDelegation;
             if (!run || !receipt) {
                 return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
@@ -957,7 +1094,7 @@ function completeOrchestrationStage(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);
+    const run = readRun(resolved.taskDir, options);
     if (!run)
         return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
     if (!run.pendingDelegation)
@@ -975,7 +1112,7 @@ function inspectOrchestrationStage(taskRef, event, options = {}) {
         return failed(resolved.code, resolved.message, resolved.taskId);
     let run;
     try {
-        run = readRun(resolved.taskDir);
+        run = readRun(resolved.taskDir, options);
     }
     catch (error) {
         return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
@@ -1023,7 +1160,7 @@ function sealOrchestrationDelegation(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);
+    const run = readRun(resolved.taskDir, options);
     if (!run?.pendingDelegation)
         return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
     const result = sealDelegation(run.pendingDelegation, event, { now: options.now });
@@ -1037,7 +1174,7 @@ function advanceOrchestration(taskRef, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir);
+    const run = readRun(resolved.taskDir, options);
     if (!run?.pendingDelegation)
         return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
     const result = consumeDelegation(run.pendingDelegation, { now: options.now });
@@ -1060,7 +1197,7 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(resolved.code, resolved.message, resolved.taskId);
-    const run = readRun(resolved.taskDir);
+    const run = readRun(resolved.taskDir, options);
     if (!run)
         return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
     const updated = withUpdatedRun(run, { status: 'paused', pause: { code, message, recoverable } });