@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/internal/task-review.ts

@@ -1,6 +1,9 @@
 import { finalizeReviewSummary } from '../task/review-finalization.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run]\n';
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
 function failUsage(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -30,10 +33,13 @@ function taskReview(args: string[] = []): void {
   let artifact = '';
   let dryRun = false;
   let orchestrated = false;
+  let overrideTicket = '';
+  let overrideTarget = '';
+  let overrideScope = '';
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (!['--stage', '--artifact', '--orchestrated', '--dry-run'].includes(flag)) {
+    if (!['--stage', '--artifact', '--orchestrated', '--dry-run', '--override-ticket', '--override-target', '--override-scope'].includes(flag)) {
       failUsage(`unknown option '${flag}'`);
       return;
     }
@@ -56,15 +62,54 @@ function taskReview(args: string[] = []): void {
       return;
     }
     if (flag === '--stage') stage = value;
-    else artifact = value;
+    else if (flag === '--artifact') artifact = value;
+    else if (flag === '--override-ticket') overrideTicket = value;
+    else if (flag === '--override-target') overrideTarget = value;
+    else if (flag === '--override-scope') overrideScope = value;
   }
   if (!stage || !artifact) {
     failUsage("options '--stage' and '--artifact' are required");
     return;
   }
-  const result = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun });
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict({ dryRun, overrideTicket, overrideTarget, overrideScope });
+  if (dryRunConflict) { failUsage(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(args[0]!);
+  if (!resolved.ok) { failUsage(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => {
+      let current = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true });
+      if (current.status !== 'failed' || !overrideTicket) return current;
+      if (!overrideTarget || !overrideScope) { failUsage('override ticket requires target and scope'); return current; }
+      const consumed = consumeHumanOverride({
+        taskRef: args[0]!, ticketId: overrideTicket,
+        failureId: failureId('review-finalization', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: overrideTarget, scope: overrideScope
+      }, {
+        effectExecutor: (capability) => {
+          const retried = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no review effect was committed' : `${retried.error?.code ?? 'REVIEW_FAILED'}: ${retried.error?.message ?? 'manual review effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskReview };

package/lib/internal/task-verify.ts

@@ -1,6 +1,9 @@
 import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts';
+import { consumeHumanOverride, failureId } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text]\n';
+const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
 function fail(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'VERIFY_PAYLOAD_INVALID', message } })}\n`);
@@ -11,21 +14,67 @@ function fail(message: string): void {
 function taskVerify(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  const taskRef = args[0];
+  const event = args[1];
   let artifact: string | undefined;
   let format: 'json' | 'text' = 'json';
+  let overrideTicket: string | undefined;
+  let overrideTarget: string | undefined;
+  let overrideScope: string | undefined;
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (flag !== '--artifact' && flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (!['--artifact', '--format', '--override-ticket', '--override-target', '--override-scope'].includes(flag)) { fail(`unknown option '${flag}'`); return; }
     if (seen.has(flag)) { fail(`duplicate option '${flag}'`); return; }
     const value = args[++index];
     if (!value || value.startsWith('--')) { fail(`option '${flag}' requires a value`); return; }
     seen.add(flag);
     if (flag === '--artifact') artifact = value;
+    else if (flag === '--override-ticket') overrideTicket = value;
+    else if (flag === '--override-target') overrideTarget = value;
+    else if (flag === '--override-scope') overrideScope = value;
     else if (value === 'json' || value === 'text') format = value;
     else { fail("option '--format' requires 'json' or 'text'"); return; }
   }
-  const result = verifyTaskEvent({ taskRef: args[0], event: args[1], ...(artifact ? { artifact } : {}) });
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { fail(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-verify.${event}`, () => {
+      let current = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) });
+      if (current.status === 'pass' || !overrideTicket) return current;
+      if (!overrideTarget || !overrideScope) { fail('override ticket requires target and scope'); return current; }
+      const failureProducer = current.status === 'blocked' || current.status === 'fail'
+        ? 'verification-engine'
+        : 'task-verify';
+      const failureCode = current.status === 'blocked'
+        ? 'CHECK_BLOCKED'
+        : current.status === 'fail'
+          ? 'CHECK_FAILED'
+          : current.error?.code ?? 'VERIFY_TASK_STATE_MISMATCH';
+      const consumed = consumeHumanOverride({
+        taskRef, ticketId: overrideTicket,
+        failureId: failureId(failureProducer, failureCode),
+        target: overrideTarget, scope: overrideScope
+      }, {
+        effectExecutor: (capability) => {
+          const retried = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) }, { manualOverride: capability });
+          current = retried;
+          return retried.status !== 'pass'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'VERIFY_FAILED'}: ${retried.error?.message ?? 'manual verification effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    fail(`${error.code}: ${error.message}`);
+    return;
+  }
+  if (humanOverride) result = { ...result, humanOverride } as typeof result;
   process.stdout.write(format === 'text' ? renderTaskVerification(result) : `${JSON.stringify(result)}\n`);
   process.exitCode = result.status === 'pass' ? 0 : result.status === 'blocked' ? 2 : 1;
 }

package/lib/internal/task-warning.ts

@@ -1,10 +1,14 @@
 import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
 import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
 const FLAGS: Record<string, string> = {
   '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
   '--message': 'message', '--action': 'action', '--id': 'id', '--status': 'status', '--resolution': 'resolution'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 
 function usageFailure(message: string): void {
@@ -38,13 +42,50 @@ function taskWarning(args: string[] = []): void {
   };
   const optional = kind === 'list' ? ['status'] : [];
   const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...optional]);
+  allowed.add('overrideTicket'); allowed.add('overrideTarget'); allowed.add('overrideScope');
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
   const missing = required[kind]!.find((key) => values[key] === undefined);
   if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
   if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
-  const result = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { usageFailure(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-warning.${kind}`, () => {
+      let current = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
+      if (current.status !== 'failed' || !values.overrideTicket) return current;
+      if (!values.overrideTarget || !values.overrideScope) { usageFailure('override ticket requires target and scope'); return current; }
+      const consumed = consumeHumanOverride({
+        taskRef, ticketId: String(values.overrideTicket),
+        failureId: failureId('workflow-warning', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget), scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyWorkflowWarningIntent(values as WorkflowWarningIntent, { manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no workflow warning effect was committed' : `${retried.error?.code ?? 'WARNING_FAILED'}: ${retried.error?.message ?? 'manual warning effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskWarning };

package/lib/platform/pr-summary.ts

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 
 import { enumerateArtifacts } from '../task/artifacts.ts';
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { renderHumanOverrideAudit } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { resolvePlatformContext } from './context.ts';
 import { createGitHubClient } from './github-client.ts';
@@ -10,19 +11,32 @@ import type { GitHubClient } from './github-client.ts';
 import { listRemoteComments, normalizeCommentContent, writeComment } from './issue-comments.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
+import type { OperationWarning } from '../task/operation-outcome.ts';
 
 type SummaryComment = { id: number; body: string };
 type SummaryContextResult = PlatformResult & {
   task: { id: string | null; prNumber: number | null };
   artifacts: Array<{ family: string; name: string; path: string }>;
 };
+type PullRequestSummaryResult = PlatformResult & {
+  result: 'pr_created_with_warnings' | 'pr_reused_with_warnings' | 'no_op_with_warnings' | null;
+  warnings: readonly OperationWarning[];
+};
+type PullRequestPrimaryResult = 'pr_created' | 'pr_reused' | 'no_op';
+
+function warningResultForPrimary(primaryResult: PullRequestPrimaryResult): NonNullable<PullRequestSummaryResult['result']> {
+  if (primaryResult === 'pr_created') return 'pr_created_with_warnings';
+  if (primaryResult === 'pr_reused') return 'pr_reused_with_warnings';
+  return 'no_op_with_warnings';
+}
 
 function summaryMarker(taskId: string): string {
   return `<!-- sync-pr:${taskId}:summary -->`;
 }
 
-function buildPullRequestSummary(taskId: string, body: string, headSha: string): string {
-  return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${body.replace(/\s+$/, '')}\n`);
+function buildPullRequestSummary(taskId: string, body: string, headSha: string, humanOverrideAudit = ''): string {
+  const sections = [body.replace(/\s+$/, ''), humanOverrideAudit.trim()].filter(Boolean).join('\n\n');
+  return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${sections}\n`);
 }
 
 function reconcileSummaryComment(comments: SummaryComment[], taskId: string, desired: string):
@@ -59,32 +73,69 @@ function summaryContext(taskRef: string, options: { cwd?: string; client?: GitHu
   return { ...platformResult('no-op'), task: { id: resolved.taskId, prNumber }, artifacts: canonicalArtifacts(resolved.taskDir) };
 }
 
-function syncPullRequestSummary(taskRef: string, options: { agent: string; body: string; cwd?: string; client?: GitHubClient; dryRun?: boolean }): PlatformResult {
+function syncPullRequestSummary(taskRef: string, options: { agent: string; body: string; cwd?: string; client?: GitHubClient; dryRun?: boolean; primaryResult: PullRequestPrimaryResult }): PullRequestSummaryResult {
+  const warningResult = warningResultForPrimary(options.primaryResult);
+  let knownPrNumber: number | null = null;
+  const softenFailure = (output: PlatformResult): PullRequestSummaryResult => {
+    const prNumber = output.resource.kind === 'pull-request' && output.resource.number
+      ? output.resource.number
+      : knownPrNumber;
+    const warning = output.error && prNumber
+      && output.error.code !== 'PR_NOT_LINKED'
+      ? {
+        code: output.error.code,
+        message: output.error.message,
+        retryable: output.error.retryable,
+        step: 'pr-summary',
+        target: `pull-request:${prNumber}`,
+        severity: 'ACTION_REQUIRED' as const
+      }
+      : null;
+    return warning
+      ? {
+        ...output,
+        status: 'applied',
+        changed: false,
+        resource: { kind: 'pull-request', number: prNumber },
+        error: null,
+        result: warningResult,
+        warnings: [warning]
+      }
+      : { ...output, result: null, warnings: [] };
+  };
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
-  if (!resolved.ok) return platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } });
+  if (!resolved.ok) return softenFailure(platformResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }));
   const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
   const prNumber = Number(frontmatter.pr_number);
-  if (!Number.isInteger(prNumber) || prNumber <= 0) return platformResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } });
+  if (!Number.isInteger(prNumber) || prNumber <= 0) return softenFailure(platformResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } }));
+  knownPrNumber = prNumber;
   const client = options.client || createGitHubClient();
   const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
-  if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return context;
+  if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return softenFailure(context);
   let headSha: string;
   try {
     headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: resolved.repoRoot, encoding: 'utf8' }).trim();
   } catch (error) {
-    return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } });
+    return softenFailure(platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } }));
   }
-  const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha);
+  const desired = buildPullRequestSummary(
+    resolved.taskId,
+    options.body,
+    headSha,
+    renderHumanOverrideAudit(fs.readFileSync(resolved.taskMdPath, 'utf8'))
+  );
   const listed = listRemoteComments(client, context.platform.repository, prNumber, resolved.repoRoot);
-  if (!listed.ok) return platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error });
+  if (!listed.ok) return softenFailure(platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error }));
   const reconciliation = reconcileSummaryComment(listed.value, resolved.taskId, desired);
-  if (reconciliation.action === 'conflict') return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: { code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple PR comments contain the summary marker', retryable: false } });
-  if (reconciliation.action === 'no-op') return platformResult('no-op', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: [reconciliation.commentId!], parts: 1 }, error: null });
-  if (options.dryRun) return platformResult('planned', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }], error: null });
+  if (reconciliation.action === 'conflict') return softenFailure(platformResult('failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: { code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple PR comments contain the summary marker', retryable: false } }));
+  if (reconciliation.action === 'no-op') return softenFailure(platformResult('no-op', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: [reconciliation.commentId!], parts: 1 }, error: null }));
+  if (options.dryRun) return softenFailure(platformResult('planned', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }], error: null }));
   const written = writeComment(client, context.platform.repository, prNumber, resolved.repoRoot, desired, reconciliation.commentId || undefined);
-  if (!written.ok) return platformResult(written.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: written.error });
+  if (!written.ok) return softenFailure(platformResult(written.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: written.error }));
   const id = Number(written.value.id || reconciliation.commentId);
-  return platformResult('applied', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 }, operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }], error: null });
+  return softenFailure(platformResult('applied', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, comment: { kind: 'summary', marker: summaryMarker(resolved.taskId), ids: Number.isInteger(id) ? [id] : [], parts: 1 }, operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }], error: null }));
 }
 
 export { buildPullRequestSummary, reconcileSummaryComment, summaryContext, summaryMarker, syncPullRequestSummary };
+export type { PullRequestSummaryResult, SummaryContextResult };
+export { warningResultForPrimary };