@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/task/events.ts

@@ -4,11 +4,16 @@ import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-
 import {
   buildArtifactLinkSection,
   artifactName,
+  inspectArtifactDirectory,
+  parseReviewedInputReference,
+  parseCodePlanInputReference,
   parseArtifactName,
   resolveArtifactContext,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
 import type { ArtifactContextResult, ArtifactErrorCode, ArtifactFamily, ArtifactIdentity } from './artifact-lifecycle.ts';
+import { ArtifactReceiptError, sha256File, upsertArtifactReceipt } from './artifact-receipts.ts';
+import type { ArtifactReceipt } from './artifact-receipts.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import {
   consumeImplementationInput,
@@ -27,6 +32,7 @@ import type { OrchestrationStageCompletion } from './orchestration.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
 
 const eventCatalog = [
   'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -48,6 +54,7 @@ type TaskEventErrorCode =
   | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
   taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean; orchestrated?: boolean;
+  overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
   verdict?: Verdict; blockers?: number; major?: number; minor?: number;
   manualValidation?: number; filesModified?: number; testsPassed?: number;
@@ -56,6 +63,7 @@ type TaskEventRequest = {
 type TaskEventError = { code: TaskEventErrorCode; message: string };
 type TaskEventOptions = TaskWriteOptions & {
   commitOrchestrationCompletion?: (plan: OrchestrationStageCompletion) => void;
+  lockAlreadyHeld?: boolean;
 };
 type TaskEventResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
@@ -68,7 +76,7 @@ type TaskEventResult = {
   operations: readonly TaskOperationSummary[]; error: TaskEventError | null;
 };
 
-const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
   'analyze.awaiting-input': { required: ['question'] },
@@ -273,12 +281,87 @@ function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: Event
   return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true as const } : null;
 }
 
+function reviewInputFamily(family: EventFamily): ArtifactFamily {
+  return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
+}
+
+function buildCompletionReceipt(
+  taskDir: string,
+  family: EventFamily,
+  artifact: ArtifactIdentity,
+  completedAt: string,
+  frontmatter: Record<string, unknown>
+): { ok: true; receipt: ArtifactReceipt } | { ok: false; message: string } | null {
+  if (family === 'code') {
+    let content: string;
+    try { content = fs.readFileSync(artifact.path, 'utf8'); }
+    catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
+    const input = parseCodePlanInputReference(content);
+    if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical plan artifact` };
+    const startedInput = typeof frontmatter.code_input_artifact === 'string' ? frontmatter.code_input_artifact : '';
+    const startedSha256 = typeof frontmatter.code_input_sha256 === 'string' ? frontmatter.code_input_sha256 : '';
+    if (!startedInput || !startedSha256) return { ok: false, message: 'code.started plan input context is missing' };
+    if (input.name !== startedInput) return { ok: false, message: `${artifact.name} plan input '${input.name}' does not match code.started input '${startedInput}'` };
+    const plan = inspectArtifactDirectory(taskDir, 'plan');
+    if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== input.name) {
+      return { ok: false, message: `code input '${input.name}' is not the latest plan artifact` };
+    }
+    try {
+      const inputSha256 = sha256File(plan.latest.path);
+      if (inputSha256 !== startedSha256) return { ok: false, message: `code input ${input.name} changed after code.started` };
+      return {
+        ok: true,
+        receipt: {
+          event: 'code.completed', output: artifact.name, input: input.name,
+          inputSha256, completedAt
+        }
+      };
+    } catch (error) {
+      return { ok: false, message: `cannot hash code input plan: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  if (!family.startsWith('review-')) return null;
+  const expectedFamily = reviewInputFamily(family);
+  let content: string;
+  try { content = fs.readFileSync(artifact.path, 'utf8'); }
+  catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
+  const input = parseReviewedInputReference(content, expectedFamily);
+  if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical ${expectedFamily} artifact` };
+  const startedInput = typeof frontmatter.review_input_artifact === 'string' ? frontmatter.review_input_artifact : '';
+  const startedSha256 = typeof frontmatter.review_input_sha256 === 'string' ? frontmatter.review_input_sha256 : '';
+  if (!startedInput || !startedSha256) return { ok: false, message: 'review started input context is missing' };
+  if (input.name !== startedInput) return { ok: false, message: `${artifact.name} input '${input.name}' does not match review.started input '${startedInput}'` };
+  const current = inspectArtifactDirectory(taskDir, expectedFamily);
+  if (current.status !== 'ready' || !current.latest || current.latest.name !== input.name) {
+    return { ok: false, message: `review input '${input.name}' is not the latest ${expectedFamily} artifact` };
+  }
+  const event = family === 'review-analysis'
+    ? 'review-analysis.completed' as const
+    : family === 'review-plan' ? 'review-plan.completed' as const : 'review-code.completed' as const;
+  try {
+    const stat = fs.lstatSync(current.latest.path);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('review input is not a regular file');
+    const inputSha256 = sha256File(current.latest.path);
+    if (inputSha256 !== startedSha256) return { ok: false, message: `review input ${input.name} changed after review.started` };
+    return {
+      ok: true,
+      receipt: {
+        event, output: artifact.name, input: input.name,
+        inputSha256, completedAt
+      }
+    };
+  } catch (error) {
+    return { ok: false, message: `cannot hash review input ${input.name}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
 function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
   const invalid = validateTaskEventRequest(request);
   if (invalid) return failed(request, invalid);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(request, { code: resolved.code, message: resolved.message }, { taskId: resolved.taskId });
-  if (resolved.state !== 'active') return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  const stateOverride = allowsManualOverride(options.manualOverride, 'task-event', 'TASK_STATE_MISMATCH');
+  if (resolved.state !== 'active' && !stateOverride) return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
   let content: string;
   try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
   catch (error) { return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
@@ -327,7 +410,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   const done = completedRows.find((item) => item.note === eventIdentity.note);
   if (eventIdentity.phase === 'completed' && done) return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, done.done, frontmatter, artifactContext);
   if (eventIdentity.phase === 'completed' && completedRows.length > 0 && openRows.length === 0) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity is already completed with a different payload' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-  if (eventIdentity.phase === 'completed' && !row?.started) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires one open matching started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed' && !row?.started && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_START_MISSING')) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires one open matching started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   if (eventIdentity.phase === 'completed') {
     const validated = validateCompletedArtifact(resolved.taskDir, FAMILY[eventIdentity.family].artifact, normalized.artifact!, normalized.round);
     if (!validated.ok) return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
@@ -338,7 +421,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, existing.time, frontmatter, artifactContext);
   }
   const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
-  if (!(allowed as readonly string[]).includes(currentStep)) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (!(allowed as readonly string[]).includes(currentStep) && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_TRANSITION_INVALID')) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   const findingCountError = validateReviewFindingCounts(
     normalized,
     content,
@@ -371,18 +454,60 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
+  let completionReceipt: ArtifactReceipt | null = null;
+  if (eventIdentity.phase === 'completed' && completedArtifact) {
+    const receipt = buildCompletionReceipt(resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp, frontmatter);
+    if (receipt && !receipt.ok) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: receipt.message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+    completionReceipt = receipt?.receipt ?? null;
+  }
   const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
   const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
   const body = appendActivityEntry(section, { time: metadata.timestamp, step: logStep, agent: normalized.agent, note: eventIdentity.note });
   const frontmatterSet: Record<string, string> = { current_step: step, assigned_to: normalized.agent };
+  let frontmatterRemove: string[] | undefined;
+  if (eventIdentity.phase === 'started' && eventIdentity.family === 'code') {
+    const planInput = artifactContext?.inputs.find((input) => input.family === 'plan');
+    if (!planInput) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: 'code.started plan input context is unavailable' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    try {
+      frontmatterSet.code_input_artifact = planInput.name;
+      frontmatterSet.code_input_sha256 = sha256File(planInput.path);
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot hash code.started plan input: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  } else if (eventIdentity.phase === 'completed' && eventIdentity.family === 'code') {
+    frontmatterRemove = ['code_input_artifact', 'code_input_sha256'];
+  } else if (eventIdentity.phase === 'started' && eventIdentity.family.startsWith('review-')) {
+    const expectedFamily = reviewInputFamily(eventIdentity.family);
+    const input = artifactContext?.inputs.find((candidate) => candidate.family === expectedFamily);
+    if (!input) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `review.started ${expectedFamily} input context is unavailable` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    try {
+      frontmatterSet.review_input_artifact = input.name;
+      frontmatterSet.review_input_sha256 = sha256File(input.path);
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot hash review.started input: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  } else if (eventIdentity.phase === 'completed' && eventIdentity.family.startsWith('review-')) {
+    frontmatterRemove = ['review_input_artifact', 'review_input_sha256'];
+  }
   if (eventIdentity.phase === 'started' && normalized.implementationInput) frontmatterSet.last_reviewed_commit = '';
   const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
-    { kind: 'frontmatter', set: frontmatterSet }
+    { kind: 'frontmatter', set: frontmatterSet, remove: frontmatterRemove }
   ];
   if (completedArtifact) {
     const link = buildArtifactLinkSection(content, completedArtifact);
     mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
   }
+  if (completionReceipt) {
+    try {
+      const receiptSection = upsertArtifactReceipt(content, completionReceipt);
+      mutations.push({ kind: 'section', aliases: receiptSection.aliases, heading: receiptSection.heading, body: receiptSection.body });
+    } catch (error) {
+      const message = error instanceof ArtifactReceiptError ? error.message : String(error);
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+  }
   if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
     let implementationRows;
     try {
@@ -401,7 +526,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     });
   }
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
-  const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
+  const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
   if (result.status === 'failed') return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
   if (!normalized.dryRun && orchestrationCompletion) {
     try {
@@ -439,6 +564,7 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskEventOptions = {
   const invalid = validateTaskEventRequest(request);
   if (invalid) return failed(request, invalid);
   const parts = eventParts(request.event);
+  if (options.lockAlreadyHeld) return applyTaskEventUnlocked(request, options);
   if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
     return applyTaskEventUnlocked(request, options);
   }

package/lib/task/guard-override.ts

@@ -0,0 +1,50 @@
+type ManualOverrideCapability = Readonly<{
+  failureId: string;
+  operator: string;
+  reason: string;
+}>;
+
+type GuardProducer = Readonly<{
+  producerId: string;
+  guardId: `G-${string}`;
+  code: string;
+}>;
+
+const guardProducerCatalog: readonly GuardProducer[] = [
+  { producerId: 'task.resolve', guardId: 'G-01', code: 'TASK_NOT_FOUND' },
+  { producerId: 'task.resolve', guardId: 'G-01', code: 'TASK_IDENTITY_CONFLICT' },
+  { producerId: 'task.write', guardId: 'G-02', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'task-event', guardId: 'G-04', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'task-event', guardId: 'G-04', code: 'EVENT_TRANSITION_INVALID' },
+  { producerId: 'task-event', guardId: 'G-04', code: 'EVENT_START_MISSING' },
+  { producerId: 'task-verify', guardId: 'G-05', code: 'VERIFY_TASK_STATE_MISMATCH' },
+  { producerId: 'task-verify', guardId: 'G-05', code: 'VERIFY_ARTIFACT_INVALID' },
+  { producerId: 'verification-engine', guardId: 'G-06', code: 'CHECK_FAILED' },
+  { producerId: 'verification-engine', guardId: 'G-06', code: 'CHECK_BLOCKED' },
+  { producerId: 'activity-intent', guardId: 'G-07', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'ledger-intent', guardId: 'G-07', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'decision-intent', guardId: 'G-07', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'workflow-warning', guardId: 'G-07', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'review-finalization', guardId: 'G-07', code: 'TASK_STATE_MISMATCH' },
+  { producerId: 'ledger-intent', guardId: 'G-08', code: 'LEDGER_TRANSITION_INVALID' },
+  { producerId: 'lifecycle-execution', guardId: 'G-09', code: 'ORCHESTRATION_STANDALONE_BUSY' },
+  { producerId: 'lifecycle-execution', guardId: 'G-09', code: 'ORCHESTRATION_PROVENANCE_MISMATCH' },
+  { producerId: 'lifecycle-execution', guardId: 'G-09', code: 'ORCHESTRATION_STATE_INVALID' },
+  { producerId: 'platform.issue', guardId: 'G-10', code: 'PLATFORM_BIND_FAILED' },
+  { producerId: 'platform.pull-request', guardId: 'G-10', code: 'PLATFORM_BIND_FAILED' }
+];
+
+function guardFailureId(producerId: string, code: string): string {
+  return `${producerId}:${code}`;
+}
+
+function allowsManualOverride(
+  capability: ManualOverrideCapability | undefined,
+  producerId: string,
+  code: string
+): boolean {
+  return capability?.failureId === guardFailureId(producerId, code);
+}
+
+export { allowsManualOverride, guardFailureId, guardProducerCatalog };
+export type { GuardProducer, ManualOverrideCapability };