@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/task/lifecycle.ts

@@ -3,7 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
-import { artifactFamilyCatalog, inspectArtifactDirectory, parseArtifactName } from './artifact-lifecycle.ts';
+import { artifactFamilyCatalog, inspectArtifactDirectory } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import { locateHotTaskDirs, resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import {
@@ -337,6 +338,21 @@ function parseJournal(content: string): LifecycleJournal {
   return value as LifecycleJournal;
 }
 
+/** Recovery reads the same journal contract as the lifecycle writer. */
+export function readLifecycleJournalEvidence(repoRoot: string, taskId: string): Readonly<{
+  exists: boolean; completedSteps: readonly string[]; failure: string | null;
+}> {
+  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' }; }
+}
+
 type DirectoryEntry = Readonly<{ relativePath: string; kind: 'file' | 'directory'; size: number; digest: string }>;
 
 function directoryManifest(root: string): DirectoryEntry[] {

package/lib/task/local-artifact-finalization.ts

@@ -1,8 +1,11 @@
 import fs from 'node:fs';
 
-import { inspectDecisionDetailDuplicates, scanVisibleMarkdown } from './decision-details.ts';
+import { inspectDecisionDetailDuplicates } from './decision-details.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import {
-  parseArtifactName,
+  hasOpenArtifactRound,
+  validateArtifactPublication,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
@@ -11,6 +14,12 @@ import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStruct
 import { getArtifactSchema } from './artifact-schema.ts';
 import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
 import type { ArtifactRepairIntent } from './artifact-repair-intent.ts';
+import {
+  consumeLifecycleRecoveryAttestation,
+  lifecycleRecoveryAttestationDigest,
+  validateLifecycleRecoveryAttestation
+} from './control-authority.ts';
+import type { LifecycleRecoveryAttestationV1 } from './control-authority.ts';
 
 type LocalArtifactFamily = 'analysis' | 'plan' | 'code';
 
@@ -82,17 +91,26 @@ type LocalArtifactFinalizationResult = {
 
 type LocalArtifactFinalizationIntent = ArtifactRepairIntent;
 
-function readLocalArtifactFinalizationIntent(
-  repoRoot: string,
-  taskId: string,
-  family: LocalArtifactFamily,
-  artifact: string
-): LocalArtifactFinalizationIntent | null {
-  return readArtifactRepairIntent(repoRoot, taskId, family, artifact);
+function authorityDigest(authority: LifecycleRecoveryAttestationV1): string {
+  return lifecycleRecoveryAttestationDigest(authority);
 }
 
-function writeLocalArtifactFinalizationIntent(repoRoot: string, value: LocalArtifactFinalizationIntent): void {
-  writeArtifactRepairIntent(repoRoot, value);
+function validFinalizerAuthority(
+  authority: LifecycleRecoveryAttestationV1 | undefined,
+  request: LocalArtifactFinalizationRequest,
+  taskId: string
+): boolean {
+  if (!authority) return false;
+  try { validateLifecycleRecoveryAttestation(authority); }
+  catch { return false; }
+  return authority.version === 1
+    && authority.phase === 'artifact.finalize-local'
+    && authority.taskId === taskId
+    && authority.family === request.family
+    && authority.artifact === request.artifact
+    && authority.round === (parseArtifactName(request.artifact)?.round ?? 0)
+    && authority.requestId.length > 0
+    && authority.operationId.length > 0;
 }
 
 function consumeLocalArtifactFinalizationIntent(
@@ -101,8 +119,8 @@ function consumeLocalArtifactFinalizationIntent(
 ): LocalArtifactFinalizationIntent {
   if (intent.state === 'consumed') return intent;
   if (intent.state !== 'passed') throw new Error('LOCAL_FINALIZATION_INTENT_INVALID: only passed provenance can be consumed');
-  const consumed = { ...intent, state: 'consumed' as const };
-  writeLocalArtifactFinalizationIntent(repoRoot, consumed);
+  const consumed = { ...intent, state: 'consumed' as const, updatedAt: Date.now() };
+  writeArtifactRepairIntent(repoRoot, consumed, { expected: intent });
   return consumed;
 }
 
@@ -222,200 +240,147 @@ function failedFinalization(
   };
 }
 
-function provenanceFailure(
+type LocalArtifactPreparation = Readonly<{
+  result: LocalArtifactFinalizationResult;
+  content: string;
+  repoRoot?: string;
+  provenance?: ArtifactRepairIntent;
+  expectedIntent?: ArtifactRepairIntent | null;
+}>;
+
+/** Read and validate once; callers publish this content before committing provenance. */
+function prepareLocalArtifact(
   request: LocalArtifactFinalizationRequest,
-  resolved: { taskId: string; taskDir: string },
-  content: string,
-  artifactSha256: string,
-  semanticDigestValue: string,
-  code: LocalArtifactDiagnosticCode,
-  message: string
-): LocalArtifactFinalizationResult {
-  return failedFinalization(request, { code, message }, {
-    taskId: resolved.taskId,
-    taskDir: resolved.taskDir,
-    artifactSha256,
-    semanticDigest: semanticDigestValue,
-    diagnostics: [{ code, message, repairable: false, line: null }]
+  candidate?: string,
+  authority?: LifecycleRecoveryAttestationV1
+): LocalArtifactPreparation {
+  const failed = (code: string, message: string): LocalArtifactPreparation => ({
+    result: failedFinalization(request, { code, message }), content: candidate ?? ''
   });
-}
-
-function finalizeLocalArtifact(request: LocalArtifactFinalizationRequest): LocalArtifactFinalizationResult {
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: request.repoRoot });
-  if (!resolved.ok) return failedFinalization(request, { code: resolved.code, message: resolved.message });
+  if (!resolved.ok) return failed(resolved.code, resolved.message);
   const parsed = parseArtifactName(request.artifact);
-  if (!parsed || parsed.family !== request.family) {
-    return failedFinalization(request, {
-      code: 'ARTIFACT_IDENTITY_INVALID',
-      message: `artifact '${request.artifact}' does not match ${request.family}`
-    }, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-  }
-  const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
-  if (!validated.ok) {
-    return failedFinalization(request, validated.error, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-  }
+  if (!parsed || parsed.family !== request.family) return failed('ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${request.family}`);
   let content: string;
-  try { content = fs.readFileSync(validated.artifact.path, 'utf8'); }
-  catch (error) {
-    return failedFinalization(request, { code: 'ARTIFACT_NOT_READABLE', message: String(error) }, {
-      taskId: resolved.taskId, taskDir: resolved.taskDir
-    });
-  }
   let taskContent: string;
-  try { taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
-  catch (error) {
-    return failedFinalization(request, { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) }, {
-      taskId: resolved.taskId, taskDir: resolved.taskDir
-    });
-  }
-  const result = validateLocalArtifact(content, {
-    family: request.family,
-    requiredSections: request.requiredSections,
-    taskContent,
-    artifact: request.artifact
-  });
-  const artifactSha256 = sha256Content(content);
-  let intent: LocalArtifactFinalizationIntent | null;
   try {
-    intent = readLocalArtifactFinalizationIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
-  } catch (error) {
-    return failedFinalization(request, {
-      code: 'LOCAL_FINALIZATION_INTENT_INVALID',
-      message: error instanceof Error ? error.message : String(error)
-    }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
-  }
-  if (result.repairable) {
-    if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== result.semanticDigest)) {
-      return provenanceFailure(
-        request, resolved, content, artifactSha256, result.semanticDigest,
-        'LOCAL_REPAIR_PROVENANCE_CONFLICT',
-        'a different local repair baseline is already recorded for this artifact'
-      );
-    }
-    if (!intent) {
-      try {
-        writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-          version: 1,
-          taskId: resolved.taskId,
-          family: request.family,
-          artifact: request.artifact,
-          state: 'awaiting-repair',
-          baselineSemanticDigest: result.semanticDigest,
-          artifactSha256,
-          semanticDigest: result.semanticDigest
-        });
-      } catch (error) {
-        return failedFinalization(request, {
-          code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-          message: error instanceof Error ? error.message : String(error)
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+    taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    if (candidate !== undefined) {
+      const error = validateArtifactPublication(resolved.taskDir, request.family, request.artifact);
+      if (error) return failed(error.code, error.message);
+      if (resolved.state !== 'active' || !hasOpenArtifactRound(taskContent, request.family, parsed.round)) {
+        return failed('ARTIFACT_IDENTITY_INVALID', 'candidate must match one open started round in an active task');
       }
+      content = candidate;
+    } else {
+      const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
+      if (!validated.ok) return failed(validated.error.code, validated.error.message);
+      content = fs.readFileSync(validated.artifact.path, 'utf8');
     }
+  } catch (error) { return failed('ARTIFACT_NOT_READABLE', String(error)); }
+  const validation = validateLocalArtifact(content, {
+    family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
+  });
+  const artifactSha256 = sha256Content(content);
+  const { semanticDigest, repairable, diagnostics } = validation;
+  const result = failedFinalization(request, {
+    code: 'LOCAL_ARTIFACT_INVALID', message: diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+  }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest, repairable, diagnostics });
+  const preparedBase = { result, content, repoRoot: resolved.repoRoot };
+  if (authority !== undefined && !validFinalizerAuthority(authority, request, resolved.taskId)) {
     return {
-      status: 'failed',
-      changed: false,
-      taskId: resolved.taskId,
-      taskDir: resolved.taskDir,
-      family: request.family,
-      artifact: request.artifact,
-      artifactSha256,
-      semanticDigest: result.semanticDigest,
-      repairable: true,
-      diagnostics: result.diagnostics,
-      error: {
-        code: 'LOCAL_ARTIFACT_INVALID',
-        message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-      }
-    };
-  }
-  if (!result.ok) {
-    return {
-      status: 'failed',
-      changed: false,
-      taskId: resolved.taskId,
-      taskDir: resolved.taskDir,
-      family: request.family,
-      artifact: request.artifact,
-      artifactSha256,
-      semanticDigest: result.semanticDigest,
-      repairable: false,
-      diagnostics: result.diagnostics,
-      error: {
-        code: 'LOCAL_ARTIFACT_INVALID',
-        message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-      }
+      ...preparedBase,
+      result: { ...result, repairable: false, error: {
+        code: 'LOCAL_EXECUTION_AUTHORITY_INVALID',
+        message: 'finalizer authority does not match the artifact tuple'
+      }, diagnostics: [] }
     };
   }
-  if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== result.semanticDigest) {
-    return provenanceFailure(
-      request, resolved, content, artifactSha256, result.semanticDigest,
-      'LOCAL_REPAIR_BASELINE_MISMATCH',
-      'the repaired artifact semantic digest does not match the recorded repair baseline'
-    );
+  const reject = (code: LocalArtifactDiagnosticCode, message: string): LocalArtifactPreparation => ({
+    ...prepared, result: { ...result, repairable: false, error: { code, message },
+      diagnostics: [{ code, message, repairable: false, line: null }] }
+  });
+  let intent: ArtifactRepairIntent | null;
+  try { intent = readArtifactRepairIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact); }
+  catch (error) {
+    return { ...preparedBase, result: { ...result, repairable: false, diagnostics: [],
+      error: { code: 'LOCAL_FINALIZATION_INTENT_INVALID', message: String(error) } } };
   }
-  if ((intent?.state === 'passed' || intent?.state === 'consumed')
-    && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== result.semanticDigest)) {
-    return provenanceFailure(
-      request, resolved, content, artifactSha256, result.semanticDigest,
-      'LOCAL_REPAIR_PROVENANCE_CONFLICT',
-      'the artifact changed after its finalization provenance was recorded'
-    );
+  const prepared = { ...preparedBase, expectedIntent: intent };
+  if (intent && intent.recoveryOperationId !== null
+    && (!authority || intent.recoveryOperationId !== authority.operationId)) {
+    return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'local repair provenance is owned by another recovery operation');
   }
-  if (intent?.state === 'consumed') {
-    return {
-      status: 'passed',
-      changed: false,
-      taskId: resolved.taskId,
-      taskDir: resolved.taskDir,
-      family: request.family,
-      artifact: request.artifact,
-      artifactSha256,
-      semanticDigest: result.semanticDigest,
-      repairable: false,
-      diagnostics: result.diagnostics,
-      error: null
-    };
+  if (repairable) {
+    if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== semanticDigest)) {
+      return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'a different local repair baseline is already recorded for this artifact');
+    }
+    if (intent && !authority) return prepared;
+  } else {
+    if (!validation.ok) return prepared;
+    if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== semanticDigest) {
+      return reject('LOCAL_REPAIR_BASELINE_MISMATCH', 'the repaired artifact semantic digest does not match the recorded repair baseline');
+    }
+    if ((intent?.state === 'passed' || intent?.state === 'consumed')
+      && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== semanticDigest)) {
+      return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'the artifact changed after its finalization provenance was recorded');
+    }
+    prepared.result = { ...result, status: 'passed', error: null };
+    if (intent?.state === 'consumed') return prepared;
   }
+  const timestamp = Date.now();
+  return { ...prepared, provenance: {
+    version: 2, taskId: resolved.taskId, family: request.family, artifact: request.artifact,
+    state: repairable ? 'awaiting-repair' : 'passed',
+    baselineSemanticDigest: repairable ? semanticDigest : intent?.baselineSemanticDigest ?? null,
+    artifactSha256, semanticDigest,
+    recoveryOperationId: authority?.operationId ?? intent?.recoveryOperationId ?? null,
+    phase: authority?.phase ?? intent?.phase ?? null,
+    authorityDigest: authority ? authorityDigest(authority) : intent?.authorityDigest ?? null,
+    requestId: authority?.lifecycleRequestId ?? intent?.requestId ?? `local-finalize:${resolved.taskId}`,
+    createdAt: intent?.createdAt ?? timestamp,
+    updatedAt: timestamp
+  } };
+}
+
+function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): LocalArtifactFinalizationResult {
   try {
-    writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-      version: 1,
-      taskId: resolved.taskId,
-      family: request.family,
-      artifact: request.artifact,
-      state: 'passed',
-      baselineSemanticDigest: intent?.baselineSemanticDigest ?? null,
-      artifactSha256,
-      semanticDigest: result.semanticDigest
-    });
+    if (prepared.provenance) {
+      writeArtifactRepairIntent(prepared.repoRoot!, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+    }
+    return prepared.result;
   } catch (error) {
-    return failedFinalization(request, {
-      code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-      message: error instanceof Error ? error.message : String(error)
-    }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+    return { ...prepared.result, status: 'failed', error: {
+      code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED', message: String(error)
+    } };
   }
-  return {
-    status: result.ok ? 'passed' : 'failed',
-    changed: false,
-    taskId: resolved.taskId,
-    taskDir: resolved.taskDir,
-    family: request.family,
-    artifact: request.artifact,
-    artifactSha256,
-    semanticDigest: result.semanticDigest,
-    repairable: result.repairable,
-    diagnostics: result.diagnostics,
-    error: result.ok ? null : {
-      code: 'LOCAL_ARTIFACT_INVALID',
-      message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+}
+
+function finalizeLocalArtifact(
+  request: LocalArtifactFinalizationRequest,
+  authority?: LifecycleRecoveryAttestationV1,
+  options: Readonly<{ deferLifecycleRecoveryConsumption?: boolean }> = {}
+): LocalArtifactFinalizationResult {
+  const result = commitLocalArtifactProvenance(prepareLocalArtifact(request, undefined, authority));
+  if (authority && !options.deferLifecycleRecoveryConsumption && result.status === 'passed') {
+    try { consumeLifecycleRecoveryAttestation(authority); }
+    catch (error) {
+      return { ...result, status: 'failed', error: {
+        code: 'LOCAL_EXECUTION_AUTHORITY_CONSUME_FAILED',
+        message: error instanceof Error ? error.message : String(error)
+      } };
     }
-  };
+  }
+  return result;
 }
 
 export {
   LOCAL_ARTIFACT_REQUIRED_SECTIONS,
   consumeLocalArtifactFinalizationIntent,
   finalizeLocalArtifact,
-  readLocalArtifactFinalizationIntent,
+  prepareLocalArtifact,
+  commitLocalArtifactProvenance,
+  readArtifactRepairIntent as readLocalArtifactFinalizationIntent,
   canonicalSemanticDigest as semanticDigest,
   sha256Content,
   validateLocalArtifact
@@ -427,6 +392,7 @@ export type {
   LocalArtifactFinalizationRequest,
   LocalArtifactFinalizationResult,
   LocalArtifactFinalizationIntent,
+  LocalArtifactPreparation,
   LocalArtifactValidationOptions,
   LocalArtifactValidationResult
 };

package/lib/task/manual-validation-completion.ts

@@ -0,0 +1,40 @@
+import { readManualValidationReceipt } from './manual-validation-receipt.ts';
+import type { ManualValidationReceipt, ManualValidationReceiptError, ManualValidationReceiptIdentity } from './manual-validation-receipt.ts';
+import { readManualValidationTransaction } from './manual-validation-transaction.ts';
+import type { ManualValidationTransaction, ManualValidationTransactionError } from './manual-validation-transaction.ts';
+
+type ManualValidationCompletionIdentity = ManualValidationReceiptIdentity & Readonly<{
+  receiptDigest?: string;
+}>;
+type ManualValidationCompletion = Readonly<{
+  receipt: ManualValidationReceipt;
+  transaction: ManualValidationTransaction;
+}>;
+type ManualValidationCompletionError = ManualValidationReceiptError | ManualValidationTransactionError;
+type ManualValidationCompletionResult =
+  | { ok: true; value: ManualValidationCompletion }
+  | { ok: false; error: ManualValidationCompletionError };
+
+function readManualValidationCompletion(taskDir: string, expected: ManualValidationCompletionIdentity = {}): ManualValidationCompletionResult {
+  const { receiptDigest: expectedReceiptDigest, ...receiptIdentity } = expected;
+  const receipt = readManualValidationReceipt(taskDir, receiptIdentity);
+  if (!receipt.ok) return receipt;
+  if (expectedReceiptDigest !== undefined && receipt.value.receiptDigest !== expectedReceiptDigest) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH', message: 'receipt digest does not match the expected completion' } };
+  }
+  const transaction = readManualValidationTransaction(taskDir, {
+    transactionId: receipt.value.transactionId,
+    taskId: receipt.value.taskId,
+    prNumber: receipt.value.prNumber,
+    prHeadSha: receipt.value.prHeadSha,
+    artifact: receipt.value.artifact
+  });
+  if (!transaction.ok) return transaction;
+  if (transaction.value.committedReceipt !== receipt.value.receiptDigest) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'completion transaction is not bound to the canonical receipt' } };
+  }
+  return { ok: true, value: { receipt: receipt.value, transaction: transaction.value } };
+}
+
+export { readManualValidationCompletion };
+export type { ManualValidationCompletion, ManualValidationCompletionError, ManualValidationCompletionIdentity, ManualValidationCompletionResult };