@fitlab-ai/agent-infra 0.11.7 → 0.11.8

package/lib/task/finalization.ts

@@ -7,13 +7,19 @@ import { canonicalizeSummaryBody } from '../platform/comment-safety.ts';
 import { backfillCompletionComments, inspectCompletionBackfillEligibility } from '../platform/completion-backfill.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { taskIssueIdentity } from '../platform/task-identities.ts';
+import { inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.ts';
+import type { IssueResult, SyncOptions as IssueSyncOptions } from '../platform/issues.ts';
+import { resourceIdentityEquals } from '../platform/resource-identity.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
+import { recoverPlatformOperations } from './platform-operation-recovery.ts';
 import {
   applyTaskLifecycle,
   inspectTaskLifecycleProgress,
   type TaskLifecycleOptions,
   type TaskLifecycleRequest,
-  type TaskLifecycleResult
+  type TaskLifecycleResult,
+  type TaskCompletionProjection,
+  previewTaskCompletion
 } from './lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { inspectShortIdRegistry } from './short-id.ts';
@@ -71,6 +77,8 @@ type TaskFinalizationOptions = Readonly<{
   lifecycle?: typeof applyTaskLifecycle;
   backfill?: typeof backfillCompletionComments;
   commentSync?: typeof syncPlatformComment;
+  issueSync?: typeof syncPlatformIssue;
+  issueInspect?: typeof inspectPlatformIssue;
   verify?: typeof verifyTaskEvent;
   preflight?: typeof verifyTaskEvent;
 }>;
@@ -471,13 +479,13 @@ function capabilityError(code: 'FINALIZATION_CAPABILITY_STALE' | 'FINALIZATION_S
   return error;
 }
 
-function hasPreparedTaskDocument(repoRoot: string, taskId: string): boolean {
+function hasFinalizationTaskDocument(repoRoot: string, taskId: string): boolean {
   const resolved = resolveTaskRef(taskId, { repoRoot });
-  if (!resolved.ok) return false;
-  if (resolved.state === 'completed') return true;
-  if (resolved.state !== 'active') return false;
-  try { return parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed'; }
-  catch { return false; }
+  if (!resolved.ok || (resolved.state !== 'active' && resolved.state !== 'completed')) return false;
+  try {
+    const journal = JSON.parse(fs.readFileSync(path.join(resolved.taskDir, '.task-lifecycle.json'), 'utf8')) as Record<string, unknown>;
+    return journal.taskId === taskId && journal.intent === 'complete';
+  } catch { return resolved.state === 'completed'; }
 }
 
 function mutationKeys(value: FinalizationMutation): string[] {
@@ -525,7 +533,14 @@ function mutationPatch(current: TaskFinalizationReceipt, mutation: FinalizationM
   if (mutation.scope === 'task-comment') {
     if (mutation.operation === 'succeeded') {
       const warnings = resolveStepWarnings(current, 'task-comment');
-      return { taskComment: mutation.state, warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null };
+      const retryWithResolvedWarning = mutation.state === 'done'
+        && current.warnings.some((warning) => warning.step === 'task-comment' && warning.status === 'open');
+      return {
+        taskComment: retryWithResolvedWarning ? 'pending' : mutation.state,
+        warningProjection: warnings.length > 0 || retryWithResolvedWarning ? 'pending' : 'done',
+        warnings,
+        lastError: null
+      };
     }
     const warnings = replaceWarning(current, warningFromError('task-comment', mutation.error), 'open');
     return { taskComment: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
@@ -557,8 +572,8 @@ function applyFinalizationReceiptMutationUnderLock(
   mutation: FinalizationMutation,
   consumed: Set<string>
 ): TaskFinalizationReceipt {
-  if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
-    throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
+  if (!hasFinalizationTaskDocument(repoRoot, receipt.taskId)) {
+    throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active task or a completed task');
   }
   const current = readReceipt(repoRoot, receipt.taskId);
   if (!current || current.receiptId !== receipt.receiptId || current.revision !== receipt.revision) {
@@ -576,8 +591,8 @@ function applyFinalizationReceiptMutation(
   capability: FinalizationCapability,
   mutation: FinalizationMutation
 ): TaskFinalizationReceipt {
-  if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
-    throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
+  if (!hasFinalizationTaskDocument(repoRoot, receipt.taskId)) {
+    throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active task or a completed task');
   }
   return withTaskExecutionLock(repoRoot, receipt.taskId, 'task-finalization.receipt-mutation', () =>
     applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set<string>())
@@ -627,6 +642,8 @@ async function syncPendingTaskComment(input: {
   taskId: string;
   agent: string;
   receipt: TaskFinalizationReceipt;
+  projection?: TaskCompletionProjection;
+  refreshProjection?: () => TaskCompletionProjection | undefined;
   commentSync: typeof syncPlatformComment;
   consumedCapabilities: Set<string>;
 }): Promise<TaskCommentSyncOutcome> {
@@ -641,7 +658,15 @@ async function syncPendingTaskComment(input: {
     };
   }
   try {
-    const result = await commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+    const result = await commentSync(taskId, {
+      kind: 'task', agent, cwd: repoRoot, dependency: 'required',
+      ...(input.projection ? {
+        taskProjection: {
+          content: input.projection.content,
+          sha256: createHash('sha256').update(input.projection.content).digest('hex')
+        }
+      } : {})
+    });
     const step = commentStep(result);
     if (result.status === 'applied' || result.status === 'no-op') {
       const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
@@ -650,6 +675,14 @@ async function syncPendingTaskComment(input: {
         scope: 'task-comment', operation: 'succeeded', state: skipped ? 'skipped' : 'done'
       }, consumedCapabilities);
       receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+      if (!skipped && receipt.taskComment === 'pending') {
+        const retry = await syncPendingTaskComment({
+          ...input,
+          receipt,
+          projection: input.refreshProjection?.() ?? input.projection
+        });
+        return { ...retry, changed: result.changed || retry.changed };
+      }
       return { receipt, step: skipped ? { ...step, status: 'skipped' } : step, changed: result.changed, error: null };
     }
     const detail = step.error ?? { code: 'COMMENT_SYNC_FAILED', message: 'task comment synchronization failed', retryable: true };
@@ -702,7 +735,7 @@ async function syncPendingSummary(input: {
   let { receipt } = input;
   try {
     const resolved = resolveTaskRef(input.taskId, { repoRoot: input.repoRoot });
-    if (!resolved.ok || !hasPreparedTaskDocument(input.repoRoot, input.taskId)) throw Object.assign(new Error('prepared task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
+    if (!resolved.ok || (resolved.state !== 'active' && resolved.state !== 'completed')) throw Object.assign(new Error('task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
     if (!fs.existsSync(path.join(resolved.taskDir, '.delivery-summary.json'))) {
       receipt = updateReceipt(input.repoRoot, receipt, { summary: 'skipped', lastError: null });
       return { receipt, step: { status: 'skipped', changed: false, error: null }, changed: false, error: null };
@@ -716,7 +749,8 @@ async function syncPendingSummary(input: {
     const summary = readDeliverySummary(resolved.taskDir, input.taskId);
     const result = await input.commentSync(input.taskId, {
       kind: 'summary', agent: input.agent, body: summary.body, cwd: input.repoRoot,
-      summaryAuthorization: { sha256: summary.sha256 }
+      summaryAuthorization: { sha256: summary.sha256 },
+      dependency: 'required'
     });
     const step = commentStep(result);
     if (result.status === 'applied' || result.status === 'no-op') {
@@ -726,7 +760,7 @@ async function syncPendingSummary(input: {
       receipt = updateReceipt(input.repoRoot, receipt, {
         summary: skipped ? 'skipped' : 'done',
         taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
-        warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done',
+        warningProjection: warnings.some((warning) => warning.status === 'open') || resolvedWarning ? 'pending' : 'done',
         warnings,
         lastError: null
       });
@@ -814,6 +848,8 @@ async function prepareUnderLock(
   const lifecycle = options.lifecycle ?? applyTaskLifecycle;
   const backfill = options.backfill ?? backfillCompletionComments;
   const commentSync = options.commentSync ?? syncPlatformComment;
+  const issueSync = options.issueSync ?? syncPlatformIssue;
+  const issueInspect = options.issueInspect ?? inspectPlatformIssue;
   const verify = options.verify ?? verifyTaskEvent;
   const consumedCapabilities = new Set<string>();
   let receipt: TaskFinalizationReceipt;
@@ -858,6 +894,90 @@ async function prepareUnderLock(
     }
   }
 
+  if (preflightState.ok && preflightState.state === 'active') {
+    const recovery = await recoverPlatformOperations(taskId, 'all', { agent: request.agent, cwd: repoRoot });
+    if (recovery.status !== 'applied' && recovery.status !== 'no-op') {
+      return failed(taskId, recovery.error ?? {
+        code: 'PLATFORM_OPERATION_RECOVERY_PENDING',
+        message: 'Pending platform operations remain unresolved',
+        retryable: true
+      });
+    }
+    const taskContent = fs.readFileSync(preflightState.taskMdPath, 'utf8');
+    const taskFrontmatter = parseTaskFrontmatter(taskContent);
+    const issueIdentity = taskIssueIdentity(taskFrontmatter);
+    if (issueIdentity) {
+      const base = typeof taskFrontmatter.delivery_base_ref === 'string' ? taskFrontmatter.delivery_base_ref.trim() : '';
+      let synced: IssueResult;
+      try {
+        synced = await issueSync(taskId, {
+          agent: request.agent, cwd: repoRoot, requirements: true, issueType: true, fields: true,
+          ...(base ? { inLabels: 'from-diff', base } : {}), dependency: 'required'
+        } satisfies IssueSyncOptions);
+      } catch (error) {
+        const detail = errorOf(error, 'FINALIZATION_ISSUE_METADATA_FAILED', true);
+        return failed(taskId, detail);
+      }
+      const issueOperations = synced.operations as Array<{ name: string; status: string; reasonCode: string | null; value?: unknown }>;
+      const badOperation = issueOperations?.find((operation) =>
+        ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])].includes(operation.name)
+        && operation.status !== 'applied' && operation.status !== 'no-op'
+      );
+      if ((synced.status !== 'applied' && synced.status !== 'no-op') || synced.error || badOperation) {
+        const error = synced.error ?? {
+          code: badOperation?.reasonCode || 'FINALIZATION_ISSUE_METADATA_UNCONFIRMED',
+          message: `Required Issue metadata operation '${badOperation?.name ?? 'sync'}' was not confirmed`,
+          retryable: true
+        };
+        return failed(taskId, errorOf(error, 'FINALIZATION_ISSUE_METADATA_FAILED', true));
+      }
+      let inspected: IssueResult;
+      try { inspected = await issueInspect(taskId, { cwd: repoRoot }); }
+      catch (error) { return failed(taskId, errorOf(error, 'FINALIZATION_ISSUE_INSPECT_FAILED', true)); }
+      if (inspected.status !== 'no-op' || inspected.error || !inspected.issue
+        || !resourceIdentityEquals(inspected.issue.identity, issueIdentity)) {
+        return failed(taskId, inspected.error ?? {
+          code: 'FINALIZATION_ISSUE_IDENTITY_UNCONFIRMED',
+          message: 'Required Issue metadata could not be reread under the bound Issue identity',
+          retryable: true
+        });
+      }
+      for (const name of ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])]) {
+        const operation = issueOperations?.find((candidate) => candidate.name === name);
+        if (!operation) return failed(taskId, {
+          code: 'FINALIZATION_ISSUE_METADATA_UNCONFIRMED',
+          message: `Required Issue metadata operation '${name}' was not reported`, retryable: true
+        });
+        const before = synced.issue;
+        const remote = inspected.issue;
+        if (name === 'requirements') {
+          const expected = typeof operation.value === 'string' ? operation.value : before?.body;
+          if (expected === undefined || remote.body !== expected) return failed(taskId, {
+            code: 'FINALIZATION_ISSUE_REQUIREMENTS_UNCONFIRMED', message: 'Issue requirements did not match the verified target', retryable: true
+          });
+        } else if (name === 'issue-type') {
+          const expected = typeof operation.value === 'string' ? operation.value : before?.issueType;
+          if (!expected || remote.issueType !== expected) return failed(taskId, {
+            code: 'FINALIZATION_ISSUE_TYPE_UNCONFIRMED', message: 'Issue Type did not match the verified target', retryable: true
+          });
+        } else if (name === 'labels:in') {
+          const expected = Array.isArray(operation.value) ? operation.value as string[] : before?.labels;
+          if (!expected || expected.filter((label) => label.startsWith('in:')).sort().join('\0')
+            !== remote.labels.filter((label) => label.startsWith('in:')).sort().join('\0')) return failed(taskId, {
+            code: 'FINALIZATION_IN_LABELS_UNCONFIRMED', message: 'Issue in-labels did not match the verified target', retryable: true
+          });
+        } else {
+          const expected = operation.value && typeof operation.value === 'object'
+            ? operation.value as Record<string, string | number>
+            : before?.fields;
+          if (!expected || Object.entries(expected).some(([field, value]) => remote.fields[field] !== value)) return failed(taskId, {
+            code: 'FINALIZATION_ISSUE_FIELDS_UNCONFIRMED', message: 'Pinned Issue fields did not match the verified target', retryable: true
+          });
+        }
+      }
+    }
+  }
+
   let changed = false;
   let backfillResult: TaskFinalizationStep | null = null;
   let runBackfill = shouldRunBackfill(receipt);
@@ -921,9 +1041,10 @@ async function prepareUnderLock(
   } else backfillResult = { status: 'no-op', changed: false, error: null };
 
   let lifecycleResult: TaskFinalizationStep | null = null;
+  let projection: TaskCompletionProjection | undefined;
   try {
     const resolved = resolveTaskRef(taskId, { repoRoot });
-    if (receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed') {
+    if (resolved.ok && resolved.state === 'completed') {
       lifecycleResult = { status: 'no-op', changed: false, error: null };
       receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
     } else {
@@ -937,6 +1058,12 @@ async function prepareUnderLock(
         return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
       }
       changed = changed || result.changed;
+      if (result.timestamp && result.agentInfraVersion) {
+        projection = previewTaskCompletion(taskId, request.agent, {
+          repoRoot,
+          metadataProvider: () => ({ timestamp: result.timestamp!, agentInfraVersion: result.agentInfraVersion! })
+        });
+      }
     }
   } catch (error) {
     const detail = errorOf(error, 'TASK_FINALIZATION_LIFECYCLE_FAILED');
@@ -946,6 +1073,12 @@ async function prepareUnderLock(
 
   let taskComment: TaskFinalizationStep | null = null;
   receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+  const currentProjection = (): TaskCompletionProjection | undefined => projection
+    ? previewTaskCompletion(taskId, request.agent, {
+      repoRoot,
+      metadataProvider: () => ({ timestamp: projection!.timestamp, agentInfraVersion: projection!.agentInfraVersion })
+    })
+    : undefined;
 
   let verification: TaskFinalizationStep | null = null;
   if (receipt.verification !== 'pending') {
@@ -971,7 +1104,7 @@ async function prepareUnderLock(
       });
       receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
       const finalComment = await syncPendingTaskComment({
-        repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+        repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
       });
       receipt = finalComment.receipt;
       if (finalComment.step.status !== 'no-op') taskComment = finalComment.step;
@@ -987,7 +1120,7 @@ async function prepareUnderLock(
       });
       receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
       const warningComment = await syncPendingTaskComment({
-        repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+        repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
       });
       receipt = warningComment.receipt;
       taskComment = warningComment.step;
@@ -1017,7 +1150,7 @@ async function prepareUnderLock(
       }, changed, hardError);
     }
     try {
-      const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
+    const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities });
       receipt = warningComment.receipt;
       if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
       changed = changed || warningComment.changed;
@@ -1038,7 +1171,7 @@ async function prepareUnderLock(
   receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
   if (receipt.taskComment === 'pending') {
     const finalComment = await syncPendingTaskComment({
-      repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+      repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
     });
     receipt = finalComment.receipt;
     taskComment = finalComment.step;

package/lib/task/lifecycle.ts

@@ -5,7 +5,8 @@ import path from 'node:path';
 import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
 import { artifactFamilyCatalog, inspectArtifactDirectory } from './artifact-lifecycle.ts';
 import { parseArtifactName } from './artifact-name.ts';
-import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.ts';
+import { upsertSection } from './sections.ts';
 import { locateHotTaskDirs, resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import {
   configuredShortIdLength, executeShortIdCommand, loadShortIdByTaskId,
@@ -112,6 +113,8 @@ type TaskLifecycleOptions = {
   prepareOnly?: boolean;
 };
 
+type TaskCompletionProjection = Readonly<{ taskId: string; content: string; timestamp: string; agentInfraVersion: string }>;
+
 const STEPS: readonly LifecycleStep[] = ['task-written', 'directory-moved', 'registry-committed'];
 const DEFAULT_IO: LifecycleFileSystem = {
   renameSync: (source, target) => fs.renameSync(source, target),
@@ -304,6 +307,25 @@ function mutationsFor(request: TaskLifecycleRequest, content: string, metadata:
   return mutations;
 }
 
+function previewTaskCompletion(taskRef: string, agent: string, options: Pick<TaskLifecycleOptions, 'repoRoot' | 'metadataProvider'> = {}): TaskCompletionProjection {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) throw Object.assign(new Error(resolved.message), { code: resolved.code });
+  if (resolved.state !== 'active') throw Object.assign(new Error(`task ${resolved.taskId} is ${resolved.state}, expected active`), { code: 'TASK_STATE_MISMATCH' });
+  const original = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+  if (!isValidAgentInfraVersion(metadata.agentInfraVersion)) throw Object.assign(new Error('metadata agentInfraVersion is invalid'), { code: 'LIFECYCLE_METADATA_FAILED' });
+  const mutations = mutationsFor({ taskRef: resolved.taskId, intent: 'complete', agent }, original, metadata, 0);
+  if (!Array.isArray(mutations)) throw Object.assign(new Error(mutations.message), { code: mutations.code });
+  let content = original;
+  for (const mutation of mutations) {
+    if (mutation.kind === 'frontmatter') content = updateTaskFrontmatter(content, mutation.set, mutation.remove);
+    else if (mutation.kind === 'section') content = upsertSection(content, mutation).content;
+    else throw Object.assign(new Error('completion projection contains an unsupported mutation'), { code: 'LIFECYCLE_PROJECTION_INVALID' });
+  }
+  content = updateTaskFrontmatter(content, { updated_at: metadata.timestamp, agent_infra_version: metadata.agentInfraVersion });
+  return { taskId: resolved.taskId, content, timestamp: metadata.timestamp, agentInfraVersion: metadata.agentInfraVersion };
+}
+
 function writeJournal(file: string, journal: LifecycleJournal, io: LifecycleFileSystem, create = false): void {
   const temporary = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
   io.writeFileSync(temporary, `${JSON.stringify(journal, null, 2)}\n`, 'wx');
@@ -590,6 +612,16 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     if (completed.has('directory-moved')) completed.add('registry-committed');
   }
   let taskOperations: readonly TaskOperationSummary[] = [];
+  if (options.prepareOnly && !matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles)) {
+    return {
+      ...failed(request, { code: '', message: '' }), status: 'applied', changed: true, error: null,
+      taskId, sourceState, targetState: spec.target, sourcePath, targetPath,
+      task: { operations: [] }, directory: { effect: 'unchanged', changed: false },
+      shortId: { effect: 'unchanged', shortId: null, changed: false },
+      timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion,
+      journalPath, completedSteps: [...completed], pendingSteps: STEPS.filter((step) => !completed.has(step))
+    };
+  }
   if (matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles)) completed.add('task-written');
   if (!completed.has('task-written')) {
     const current = io.readFileSync(path.join(sourcePath, 'task.md'));
@@ -687,8 +719,8 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   };
 }
 
-export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle };
+export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle, previewTaskCompletion };
 export type {
   TaskLifecycleIntent, TaskLifecycleRequest, TaskLifecycleResult, TaskLifecycleOptions,
-  LifecycleError, LifecycleJournal, LifecycleStep
+  LifecycleError, LifecycleJournal, LifecycleStep, TaskCompletionProjection
 };

package/lib/task/platform-operation-journal.ts

@@ -0,0 +1,230 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+import { isResourceIdentity } from '../platform/resource-identity.ts';
+import type { ResourceIdentity } from '../platform/resource-identity.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+
+const JOURNAL_FILE = '.platform-operations.json';
+const MAX_ATTEMPTS = 3;
+
+type PlatformOperationKind = 'task-comment' | 'artifact-comment' | 'summary-comment' | 'cancel-comment' | 'issue-create' | 'issue-metadata' | 'pull-request' | 'pull-request-summary' | 'pull-request-review';
+type PlatformOperationState = 'queued' | 'pending' | 'unknown' | 'succeeded' | 'failed';
+type PlatformIssueMetadataIntent = Readonly<{
+  requirements: boolean;
+  issueType: boolean;
+  fields: boolean;
+  status?: string;
+  assignees?: 'current' | 'none';
+  milestone?: 'initial' | 'specific' | 'none';
+  inLabels?: 'from-diff' | 'none';
+  base?: string;
+  fromDiffFiles?: readonly string[];
+  inLabelMappingDigest?: string;
+  state?: 'open' | 'closed';
+  closeReason?: 'completed' | 'not_planned';
+}>;
+type PlatformPullRequestIntent = Readonly<{
+  action: 'create' | 'bind' | 'sync';
+  baseRef?: string;
+  headRef?: string;
+  prToken?: string;
+  metadata?: boolean;
+  closingIssue?: boolean;
+}>;
+type PlatformIssueCreateIntent = Readonly<{ title: string; bodyDigest: string }>;
+type PlatformPullRequestSummaryIntent = Readonly<{ body: string; changeReportFile: string }>;
+type PlatformPullRequestReviewIntent = Readonly<{
+  prNumber: string;
+  resource: ResourceIdentity;
+  providerScopeId: string;
+  scope: string;
+  round: number;
+  commitSha: string;
+  event: 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
+  artifactFile: string;
+  bodyDigest: string;
+}>;
+type PlatformOperation = Readonly<{
+  id: string;
+  kind: PlatformOperationKind;
+  target: string;
+  expectedDigest: string;
+  dependency: 'deferred' | 'required';
+  state: PlatformOperationState;
+  attempts: number;
+  maxAttempts: typeof MAX_ATTEMPTS;
+  lastCode: string | null;
+  issueMetadata?: PlatformIssueMetadataIntent;
+  issueCreate?: PlatformIssueCreateIntent;
+  pullRequest?: PlatformPullRequestIntent;
+  pullRequestSummary?: PlatformPullRequestSummaryIntent;
+  pullRequestReview?: PlatformPullRequestReviewIntent;
+  updatedAt: string;
+}>;
+type PlatformOperationJournal = Readonly<{
+  version: 1;
+  taskId: string;
+  operations: readonly PlatformOperation[];
+}>;
+
+type RecordOperationInput = Readonly<{
+  taskRef: string;
+  kind: PlatformOperationKind;
+  target: string;
+  expectedDigest: string;
+  dependency: 'deferred' | 'required';
+  state: PlatformOperationState;
+  lastCode?: string | null;
+  issueMetadata?: PlatformIssueMetadataIntent;
+  issueCreate?: PlatformIssueCreateIntent;
+  pullRequest?: PlatformPullRequestIntent;
+  pullRequestSummary?: PlatformPullRequestSummaryIntent;
+  pullRequestReview?: PlatformPullRequestReviewIntent;
+  cwd?: string;
+}>;
+
+function operationId(input: Pick<RecordOperationInput, 'kind' | 'target' | 'expectedDigest'>): string {
+  return createHash('sha256')
+    .update(`${input.kind}\0${input.target}\0${input.expectedDigest}`)
+    .digest('hex');
+}
+
+function journalPath(taskDir: string): string {
+  return path.join(taskDir, JOURNAL_FILE);
+}
+
+function parseJournal(file: string, taskId: string): PlatformOperationJournal {
+  let value: unknown;
+  try { value = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { version: 1, taskId, operations: [] };
+    throw Object.assign(new Error(`Platform operation journal is unreadable: ${String(error)}`), { code: 'PLATFORM_OPERATION_JOURNAL_INVALID' });
+  }
+  if (!value || typeof value !== 'object') throw Object.assign(new Error('Platform operation journal is invalid'), { code: 'PLATFORM_OPERATION_JOURNAL_INVALID' });
+  const journal = value as Partial<PlatformOperationJournal>;
+  if (journal.version !== 1 || journal.taskId !== taskId || !Array.isArray(journal.operations)) {
+    throw Object.assign(new Error('Platform operation journal identity or version is invalid'), { code: 'PLATFORM_OPERATION_JOURNAL_INVALID' });
+  }
+  for (const item of journal.operations) {
+    if (!item || typeof item !== 'object' || !/^[a-f0-9]{64}$/u.test(item.id)
+      || !['task-comment', 'artifact-comment', 'summary-comment', 'cancel-comment', 'issue-create', 'issue-metadata', 'pull-request', 'pull-request-summary', 'pull-request-review'].includes(item.kind)
+      || typeof item.target !== 'string' || !item.target
+      || !/^[a-f0-9]{64}$/u.test(item.expectedDigest)
+      || !['deferred', 'required'].includes(item.dependency)
+      || !['queued', 'pending', 'unknown', 'succeeded', 'failed'].includes(item.state)
+      || !Number.isSafeInteger(item.attempts) || item.attempts < 0 || item.attempts > MAX_ATTEMPTS
+      || item.maxAttempts !== MAX_ATTEMPTS
+      || !(item.lastCode === null || typeof item.lastCode === 'string')
+      || (item.kind === 'issue-metadata'
+        ? !item.issueMetadata || typeof item.issueMetadata.requirements !== 'boolean'
+          || typeof item.issueMetadata.issueType !== 'boolean' || typeof item.issueMetadata.fields !== 'boolean'
+          || (item.issueMetadata.status !== undefined && typeof item.issueMetadata.status !== 'string')
+          || (item.issueMetadata.assignees !== undefined && !['current', 'none'].includes(item.issueMetadata.assignees))
+          || (item.issueMetadata.milestone !== undefined && !['initial', 'specific', 'none'].includes(item.issueMetadata.milestone))
+          || (item.issueMetadata.inLabels !== undefined && !['from-diff', 'none'].includes(item.issueMetadata.inLabels))
+          || (item.issueMetadata.base !== undefined && (typeof item.issueMetadata.base !== 'string' || !item.issueMetadata.base.trim()))
+          || (item.issueMetadata.fromDiffFiles !== undefined && (!Array.isArray(item.issueMetadata.fromDiffFiles)
+            || item.issueMetadata.fromDiffFiles.some((file: unknown) => typeof file !== 'string')))
+          || (item.issueMetadata.inLabelMappingDigest !== undefined && !/^[a-f0-9]{64}$/u.test(item.issueMetadata.inLabelMappingDigest))
+          || (item.issueMetadata.state !== undefined && !['open', 'closed'].includes(item.issueMetadata.state))
+          || (item.issueMetadata.closeReason !== undefined && !['completed', 'not_planned'].includes(item.issueMetadata.closeReason))
+          || (!item.issueMetadata.requirements && !item.issueMetadata.issueType && !item.issueMetadata.fields
+            && item.issueMetadata.status === undefined && item.issueMetadata.assignees === undefined
+            && item.issueMetadata.milestone === undefined && item.issueMetadata.inLabels === undefined && item.issueMetadata.state === undefined)
+        : item.issueMetadata !== undefined)
+      || (item.kind === 'pull-request'
+        ? !item.pullRequest || !['create', 'bind', 'sync'].includes(item.pullRequest.action)
+          || Object.entries(item.pullRequest).some(([key, field]) => key !== 'action'
+            && key !== 'metadata' && key !== 'closingIssue' && (typeof field !== 'string' || !field.trim()))
+          || (item.pullRequest.metadata !== undefined && typeof item.pullRequest.metadata !== 'boolean')
+          || (item.pullRequest.closingIssue !== undefined && typeof item.pullRequest.closingIssue !== 'boolean')
+        : item.pullRequest !== undefined)
+      || (item.kind === 'issue-create'
+        ? !item.issueCreate || typeof item.issueCreate.title !== 'string' || !item.issueCreate.title.trim()
+          || !/^[a-f0-9]{64}$/u.test(item.issueCreate.bodyDigest)
+        : item.issueCreate !== undefined)
+      || (item.kind === 'pull-request-summary'
+        ? !item.pullRequestSummary || typeof item.pullRequestSummary.body !== 'string'
+          || !item.pullRequestSummary.body.trim() || typeof item.pullRequestSummary.changeReportFile !== 'string'
+          || !item.pullRequestSummary.changeReportFile.trim()
+        : item.pullRequestSummary !== undefined)
+      || (item.kind === 'pull-request-review'
+        ? !item.pullRequestReview || typeof item.pullRequestReview.prNumber !== 'string'
+          || !isResourceIdentity(item.pullRequestReview.resource)
+          || typeof item.pullRequestReview.providerScopeId !== 'string' || !item.pullRequestReview.providerScopeId.trim()
+          || !item.pullRequestReview.prNumber.trim() || !/^TASK-\d{8}-\d{6}$|^pr\d+$/u.test(item.pullRequestReview.scope)
+          || !Number.isSafeInteger(item.pullRequestReview.round) || item.pullRequestReview.round <= 0
+          || !/^[0-9a-f]{7,40}$/iu.test(item.pullRequestReview.commitSha)
+          || !['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(item.pullRequestReview.event)
+          || typeof item.pullRequestReview.artifactFile !== 'string'
+          || !/^pr-review(?:-r\d+)?\.md$/u.test(item.pullRequestReview.artifactFile)
+          || (item.pullRequestReview.artifactFile === 'pr-review.md'
+            ? item.pullRequestReview.round !== 1
+            : item.pullRequestReview.artifactFile !== `pr-review-r${item.pullRequestReview.round}.md`)
+          || !/^[a-f0-9]{64}$/u.test(item.pullRequestReview.bodyDigest)
+        : item.pullRequestReview !== undefined)
+      || typeof item.updatedAt !== 'string') {
+      throw Object.assign(new Error('Platform operation journal contains an invalid operation'), { code: 'PLATFORM_OPERATION_JOURNAL_INVALID' });
+    }
+  }
+  return journal as PlatformOperationJournal;
+}
+
+function writeJournal(file: string, journal: PlatformOperationJournal): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(journal, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch { /* renamed or already removed */ }
+  }
+}
+
+function resolveJournal(taskRef: string, cwd?: string): { taskId: string; file: string } {
+  const resolved = resolveTaskRef(taskRef, cwd ? { repoRoot: cwd } : {});
+  if (!resolved.ok) throw Object.assign(new Error(resolved.message), { code: resolved.code });
+  return { taskId: resolved.taskId, file: journalPath(resolved.taskDir) };
+}
+
+function recordPlatformOperation(input: RecordOperationInput): PlatformOperation {
+  if (!/^[a-f0-9]{64}$/u.test(input.expectedDigest) || !input.target.trim()) {
+    throw Object.assign(new Error('Platform operation requires a stable target and SHA-256 digest'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+  }
+  const { taskId, file } = resolveJournal(input.taskRef, input.cwd);
+  const journal = parseJournal(file, taskId);
+  const id = operationId(input);
+  const previous = journal.operations.find((item) => item.id === id);
+  const next: PlatformOperation = {
+    id,
+    kind: input.kind,
+    target: input.target,
+    expectedDigest: input.expectedDigest,
+    dependency: input.dependency,
+    state: input.state,
+    attempts: Math.min(MAX_ATTEMPTS, (previous?.attempts ?? 0) + (input.state === 'pending' ? 1 : 0)),
+    maxAttempts: MAX_ATTEMPTS,
+    lastCode: input.lastCode ?? null,
+    ...(input.issueMetadata ? { issueMetadata: input.issueMetadata } : {}),
+    ...(input.issueCreate ? { issueCreate: input.issueCreate } : {}),
+    ...(input.pullRequest ? { pullRequest: input.pullRequest } : {}),
+    ...(input.pullRequestSummary ? { pullRequestSummary: input.pullRequestSummary } : {}),
+    ...(input.pullRequestReview ? { pullRequestReview: input.pullRequestReview } : {}),
+    updatedAt: new Date().toISOString()
+  };
+  const operations = previous
+    ? journal.operations.map((item) => item.id === id ? next : item)
+    : [...journal.operations, next];
+  writeJournal(file, { version: 1, taskId, operations });
+  return next;
+}
+
+function readPlatformOperationJournal(taskRef: string, cwd?: string): PlatformOperationJournal {
+  const { taskId, file } = resolveJournal(taskRef, cwd);
+  return parseJournal(file, taskId);
+}
+
+export { JOURNAL_FILE as PLATFORM_OPERATION_JOURNAL_FILE, MAX_ATTEMPTS as PLATFORM_OPERATION_MAX_ATTEMPTS, operationId, recordPlatformOperation, readPlatformOperationJournal };
+export type { PlatformIssueCreateIntent, PlatformIssueMetadataIntent, PlatformOperation, PlatformOperationJournal, PlatformOperationKind, PlatformOperationState, PlatformPullRequestIntent, PlatformPullRequestReviewIntent, PlatformPullRequestSummaryIntent, RecordOperationInput };