@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/decide.ts

@@ -2,6 +2,9 @@ import { VERSION } from './version.ts';
 import { parseTaskScope } from './task/command-options.ts';
 import { applyHumanDecision } from './task/decision-intents.ts';
 import { canonicalTimestamp } from './task/write.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';
 
 type DecideOptions = {
   repoRoot?: string;
@@ -9,23 +12,33 @@ type DecideOptions = {
   version?: string;
 };
 
-function parseDecisionParts(parts: string[]): { decision: string; needsImplementation: boolean | undefined } {
+function parseDecisionParts(parts: string[]): { decision: string; needsImplementation: boolean | undefined; overrideTicket?: string; overrideTarget?: string; overrideScope?: string } {
   const decision: string[] = [];
   let needsImplementation: boolean | undefined;
+  let overrideTicket: string | undefined;
+  let overrideTarget: string | undefined;
+  let overrideScope: string | undefined;
   for (let index = 0; index < parts.length; index += 1) {
-    if (parts[index] !== '--needs-implementation') {
+    const part = parts[index];
+    if (part === '--needs-implementation') {
+      if (needsImplementation !== undefined) throw new Error("duplicate option '--needs-implementation'");
+      const value = parts[++index];
+      if (value !== 'true' && value !== 'false') {
+        throw new Error("--needs-implementation must be 'true' or 'false'");
+      }
+      needsImplementation = value === 'true';
+    } else if (part === '--override-ticket' || part === '--override-target' || part === '--override-scope') {
+      const value = parts[++index];
+      if (!value) throw new Error(`${part} requires a value`);
+      if (part === '--override-ticket') overrideTicket = value;
+      else if (part === '--override-target') overrideTarget = value;
+      else overrideScope = value;
+    } else {
       decision.push(parts[index]!);
-      continue;
     }
-    if (needsImplementation !== undefined) throw new Error("duplicate option '--needs-implementation'");
-    const value = parts[++index];
-    if (value !== 'true' && value !== 'false') {
-      throw new Error("--needs-implementation must be 'true' or 'false'");
-    }
-    needsImplementation = value === 'true';
   }
   if (decision.length === 0) throw new Error('decision content is required');
-  return { decision: decision.join(' '), needsImplementation };
+  return { decision: decision.join(' '), needsImplementation, overrideTicket, overrideTarget, overrideScope };
 }
 
 export async function decide(args: string[], options: DecideOptions = {}): Promise<number> {
@@ -64,17 +77,49 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
   try {
     const parsedDecision = parseDecisionParts(decisionParts);
     const now = (options.now ?? canonicalTimestamp)();
-    const result = applyHumanDecision({
+    const request = {
       taskRef, selector, decision: parsedDecision.decision,
       needsImplementation: parsedDecision.needsImplementation
-    }, {
+    };
+    const writeOptions = {
       repoRoot: options.repoRoot,
       metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
-    });
+    };
+    const resolved = taskRef ? resolveTaskRef(taskRef, { repoRoot: options.repoRoot }) : null;
+    let result;
+    const execute = () => {
+      let current = applyHumanDecision(request, writeOptions);
+      if (current.status !== 'failed' || !parsedDecision.overrideTicket) return current;
+      if (!parsedDecision.overrideTarget || !parsedDecision.overrideScope) throw new Error('override ticket requires --override-target and --override-scope');
+      const consumed = consumeHumanOverride({
+        taskRef: resolved?.ok ? resolved.taskId : String(taskRef ?? ''),
+        ticketId: parsedDecision.overrideTicket,
+        failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: parsedDecision.overrideTarget,
+        scope: parsedDecision.overrideScope
+      }, {
+        ...writeOptions,
+        effectExecutor: (capability) => {
+          const retried = applyHumanDecision(request, { ...writeOptions, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no decision effect was committed' : `${retried.error?.code ?? 'DECISION_FAILED'}: ${retried.error?.message ?? 'manual decision effect failed'}` }
+            : null;
+        }
+      });
+      if (consumed.status === 'failed') throw new Error(consumed.error.message);
+      return current;
+    };
+    result = resolved?.ok
+      ? withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute)
+      : execute();
     if (result.error) throw new Error(result.error.message);
     return 0;
   } catch (error) {
-    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+    const message = error instanceof TaskExecutionLockError
+      ? `${error.code}: ${error.message}`
+      : error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}\n`);
     return 1;
   }
 }

package/lib/defaults.json

@@ -56,7 +56,6 @@
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
-      ".agents/workspace/README.md",
       ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
@@ -84,6 +83,15 @@
       ".git-hooks/pre-commit",
       ".gitignore"
     ],
-    "ejected": []
+    "ejected": [],
+    "retiredManaged": [
+      {
+        "path": ".agents/workspace/README.md",
+        "templateHashes": [
+          "sha256:967b27ca4008154c5abf99a1df728242f80ed3ace9bd98eb2828bc1c76af826c",
+          "sha256:15aa21942cf2a1396d27834f1d3d723b61a46f8d14600b706f39f3bebc21aea3"
+        ]
+      }
+    ]
   }
 }

package/lib/git/workflow.ts

@@ -20,6 +20,10 @@ function value(runner: GitRunner, cwd: string, args: readonly string[], trim = t
   return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
 }
 
+function nulPaths(output: string): string[] {
+  return output.split('\0').filter(Boolean);
+}
+
 function cleanMessage(message: string): string {
   return message.replace(/(https?:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1***@').trim();
 }
@@ -68,8 +72,27 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
   const selected = new Set(input.paths);
   const unrelatedStaged = before.snapshot.staged.filter((candidate) => !selected.has(candidate));
   if (unrelatedStaged.length > 0) return { status: 'failed' as const, changed: false, snapshot: before.snapshot, operations: [], error: { code: 'GIT_STAGED_SCOPE_MISMATCH', message: `Unrelated staged paths: ${unrelatedStaged.join(', ')}` } };
-  const add = run(runner, input.cwd, ['add', '--', ...input.paths]);
-  if (add.status !== 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed' as const, message: add.stderr.trim() }], error: { code: 'GIT_STAGE_FAILED', message: add.stderr.trim() } };
+  const stageFailure = (message: string) => ({ status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed' as const, message }], error: { code: 'GIT_STAGE_FAILED', message } });
+  const indexed = run(runner, input.cwd, ['ls-files', '-z', '--', ...input.paths]);
+  if (indexed.status !== 0) return stageFailure(indexed.stderr.trim());
+  const headed = run(runner, input.cwd, ['ls-tree', '-r', '--name-only', '-z', 'HEAD', '--', ...input.paths]);
+  if (headed.status !== 0) return stageFailure(headed.stderr.trim());
+  const indexedPaths = new Set(nulPaths(indexed.stdout));
+  const headPaths = new Set(nulPaths(headed.stdout));
+  const trackedPaths: string[] = [];
+  const addPaths: string[] = [];
+  for (const candidate of input.paths) {
+    if (indexedPaths.has(candidate)) trackedPaths.push(candidate);
+    else if (!headPaths.has(candidate) || fs.existsSync(path.join(input.cwd, candidate))) addPaths.push(candidate);
+  }
+  if (trackedPaths.length > 0) {
+    const update = run(runner, input.cwd, ['add', '-u', '--', ...trackedPaths]);
+    if (update.status !== 0) return stageFailure(update.stderr.trim());
+  }
+  if (addPaths.length > 0) {
+    const add = run(runner, input.cwd, ['add', '--', ...addPaths]);
+    if (add.status !== 0) return stageFailure(add.stderr.trim());
+  }
   const staged = run(runner, input.cwd, ['diff', '--cached', '--quiet', '--']);
   if (staged.status === 0) return { status: 'no-op' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'no-op' as const }], error: null };
   if (input.expectedTree) {

package/lib/init.ts

@@ -249,7 +249,7 @@ async function cmdInit(): Promise<void> {
     agentClients: serializeAgentClients(defaultState)
   };
 
-  if (sandboxEngine) config.sandbox.engine = sandboxEngine;
+  if (sandboxEngine) config.sandbox.engine = { [currentPlatform]: sandboxEngine };
   if (templateSources.length > 0) config.templates = { sources: templateSources };
   if (skillSources.length > 0) config.skills = { sources: skillSources };
 

package/lib/internal/codex-lifecycle.ts

@@ -9,7 +9,11 @@ import {
   resolveCodexThread
 } from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
 import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
 import {
   activateCodexOrchestrationDelegation,
   activateCodexSpawnDelegation,
@@ -18,7 +22,7 @@ import {
   sealCodexParentDelegation
 } from '../task/codex-orchestration.ts';
 
-const USAGE = 'Usage: agent-infra-internal codex-lifecycle <hook-event|resolve-start|resolve-stop|preflight|consume> [options]\n';
+const USAGE = 'Usage: agent-infra-internal codex-lifecycle <capability-arm|hook-event|resolve-start|resolve-stop|preflight|consume> [options]\n';
 const MANAGED_AGENT = /^agent-infra-lifecycle-(executor|reviewer)$/;
 
 type Parsed = Readonly<{ operation: string; values: Readonly<Record<string, string>> }>;
@@ -53,6 +57,7 @@ function parse(args: string[]): Parsed | null {
     return null;
   }
   const allowed = {
+    'capability-arm': ['--task-id'],
     'hook-event': ['--event', '--bridge'],
     'resolve-start': ['--child-id'],
     'resolve-stop': ['--child-id'],
@@ -92,6 +97,16 @@ function hookDefinitionHash(): string {
   return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
 
+function controllerBinding(taskId: string) {
+  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+  if (!contextPath) return undefined;
+  const context = verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot: process.cwd() });
+  return {
+    instanceDigest: context.controllerInstanceDigest,
+    controlGeneration: context.controlGeneration
+  };
+}
+
 async function readStdin(): Promise<unknown> {
   let input = '';
   process.stdin.setEncoding('utf8');
@@ -171,6 +186,28 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       return;
     }
 
+    if (parsed.operation === 'capability-arm') {
+      const taskId = parsed.values['--task-id'];
+      if (!taskId) throw new Error('capability-arm requires --task-id');
+      const resolved = resolveTaskRef(taskId, { repoRoot: process.cwd() });
+      if (!resolved.ok) throw new Error(`${resolved.code}: ${resolved.message}`);
+      const armed = createCodexCapabilityStore().arm({
+        taskId: resolved.taskId,
+        buildIdentity: computeLifecycleBuildIdentity(process.cwd()),
+        controller: controllerBinding(resolved.taskId)
+      });
+      output({
+        status: 'armed',
+        changed: true,
+        capabilityToken: armed.token,
+        marker: armed.marker,
+        expiresAt: armed.expiresAt,
+        buildIdentity: armed.buildIdentity,
+        error: null
+      });
+      return;
+    }
+
     const store = createCodexLifecycleStore({ cliVersion: cliVersion() });
     if (parsed.operation === 'hook-event') {
       const phase = parsed.values['--event'];
@@ -181,6 +218,36 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
         throw new Error("hook-event --bridge must be 'true'");
       }
       const payload = await readStdin();
+      if (phase === 'post-tool') {
+        const capabilityToken = payloadText(payload, 'capabilityToken');
+        if (capabilityToken) {
+          const capabilityStore = createCodexCapabilityStore();
+          const armed = capabilityStore.inspect(capabilityToken);
+          const capability = createCodexCapabilityStore().attest({
+            token: capabilityToken,
+            sessionId: payloadText(payload, 'sessionId'),
+            turnId: payloadText(payload, 'turnId'),
+            toolUseId: payloadText(payload, 'toolUseId'),
+            hookDefinitionHash: payloadText(payload, 'hookDefinitionHash'),
+            buildIdentity: computeLifecycleBuildIdentity(process.cwd()),
+            controller: controllerBinding(armed.taskId)
+          });
+          output({
+            status: capability.status,
+            changed: true,
+            evidence: {
+              revision: capability.revision,
+              sessionId: capability.sessionId,
+              turnId: capability.turnId,
+              toolUseId: capability.toolUseId,
+              expiresAt: capability.expiresAt
+            },
+            diagnostics: [],
+            error: null
+          });
+          return;
+        }
+      }
       if (phase === 'post-tool' && parsed.values['--bridge'] === 'true') {
         const toolName = payloadText(payload, 'toolName');
         if (toolName === 'collaborationspawn_agent') {

package/lib/internal/codex-sandbox-controller.ts

@@ -0,0 +1,109 @@
+import {
+  runCodexSandboxController,
+  verifyCodexSandboxControllerContext
+} from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+
+const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
+
+function fail(code: string, message: string, exitCode = 1): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    error: { code, message }
+  })}\n`);
+  process.exitCode = exitCode;
+}
+
+function parse(args: string[]): Readonly<{ operation: string; values: Readonly<Record<string, string>> }> | null {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  const operation = args[0];
+  if (!operation || !['run', 'verify-context'].includes(operation)) {
+    process.stderr.write(USAGE);
+    fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', 'operation must be run or verify-context', 2);
+    return null;
+  }
+  const allowed = new Set([
+    '--task-id',
+    '--task-ref',
+    '--context',
+    '--executor-model',
+    '--executor-reasoning-effort',
+    '--reviewer-model',
+    '--reviewer-reasoning-effort'
+  ]);
+  const values: Record<string, string> = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    const value = args[++index];
+    if (!allowed.has(flag) || Object.hasOwn(values, flag) || !value || value.startsWith('--')) {
+      fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', `invalid option '${flag}'`, 2);
+      return null;
+    }
+    values[flag] = value;
+  }
+  return { operation, values };
+}
+
+async function codexSandboxController(args: string[] = []): Promise<void> {
+  const parsed = parse(args);
+  if (!parsed || process.exitCode) return;
+  const taskId = parsed.values['--task-id'];
+  if (!taskId) {
+    fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', '--task-id is required', 2);
+    return;
+  }
+  try {
+    if (parsed.operation === 'verify-context') {
+      const contextPath = parsed.values['--context']
+        ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+      if (!contextPath) throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');
+      const context = verifyCodexSandboxControllerContext(contextPath, taskId);
+      process.stdout.write(`${JSON.stringify({
+        status: 'ready',
+        changed: false,
+        context: {
+          taskId: context.taskId,
+          controlGeneration: context.controlGeneration,
+          controllerInstanceDigest: context.controllerInstanceDigest,
+          expiresAt: context.expiresAt,
+          buildIdentity: context.buildIdentity,
+          hookDefinitionHash: context.hookDefinitionHash,
+          lifecycleProfilesHash: context.lifecycleProfilesHash
+        },
+        error: null
+      })}\n`);
+      return;
+    }
+    const taskRef = parsed.values['--task-ref'];
+    if (!taskRef) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_REF_REQUIRED');
+    const policy = [
+      '--executor-model',
+      '--executor-reasoning-effort',
+      '--reviewer-model',
+      '--reviewer-reasoning-effort'
+    ];
+    if (policy.some((flag) => parsed.values[flag] !== undefined)
+      && policy.some((flag) => parsed.values[flag] === undefined)) {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_MODEL_POLICY_INVALID');
+    }
+    const exitCode = await runCodexSandboxController({
+      taskId,
+      taskRef,
+      executorModel: parsed.values['--executor-model'],
+      executorReasoningEffort: parsed.values['--executor-reasoning-effort'],
+      reviewerModel: parsed.values['--reviewer-model'],
+      reviewerReasoningEffort: parsed.values['--reviewer-reasoning-effort']
+    });
+    process.exitCode = exitCode;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1]
+      ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
+    fail(code, message);
+  }
+}
+
+export { codexSandboxController };

package/lib/internal/release-workflow.ts

@@ -36,9 +36,7 @@ const DEMO_INPUT_PATHS = [
   'lib/paths.ts',
   'lib/render.ts',
   'lib/builtin-tuis.ts',
-  'lib/sandbox/engines/',
-  'src/sync-templates.js',
-  'templates/'
+  'lib/sandbox/engines/'
 ] as const;
 const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';
 const DEMO_OUTPUT_PATH = 'assets/demo-init.gif';

package/lib/internal/task-activity.ts

@@ -6,6 +6,9 @@ import type {
   PrReviewActivityIntent,
   PrReviewInspectIntent
 } from '../task/activity-intent.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-activity <task-ref> pr-review-inspect
        agent-infra-internal task-activity <task-ref> pr-review-start --agent <agent> --artifact <canonical.md> --head <40hex> [--dry-run]
@@ -24,13 +27,14 @@ const FLAGS: Record<string, string> = {
   '--minor': 'minor',
   '--outcome': 'outcome',
   '--reason': 'reason'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const COMMON = ['agent', 'artifact', 'head'] as const;
 const ALLOWED: Record<string, ReadonlySet<string>> = {
   'pr-review-inspect': new Set(['kind', 'taskRef']),
-  'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun']),
-  'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun']),
-  'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun'])
+  'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
+  'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
+  'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope'])
 };
 
 function usageFailure(message: string): void {
@@ -83,9 +87,45 @@ function taskActivity(args: string[] = []): void {
   for (const key of operationRequired) {
     if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
   }
-  const result = applyPrReviewActivityIntent(values as PrReviewActivityIntent);
-  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-activity.${kind}`, () => {
+      let current = applyPrReviewActivityIntent(values as PrReviewActivityIntent, { lockAlreadyHeld: true });
+      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('activity-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget), scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyPrReviewActivityIntent(values as PrReviewActivityIntent, { 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 activity effect was committed' : `${retried.error?.code ?? 'ACTIVITY_FAILED'}: ${retried.error?.message ?? 'manual activity 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 { taskActivity };

package/lib/internal/task-event.ts

@@ -1,6 +1,9 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { applyTaskEvent, eventCatalog } from '../task/events.ts';
 import type { TaskEventRequest, Verdict } from '../task/events.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-event <N | TASK-id> <event> --agent <agent> [event options] [--orchestrated] [--dry-run]
 
@@ -13,7 +16,8 @@ const FLAGS: Record<string, keyof TaskEventRequest> = {
   '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
   '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
   '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
-  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult'
+  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult',
+  '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
 
@@ -51,9 +55,54 @@ function taskEvent(args: string[] = []): void {
   const agent = normalizeAgentToken(String(request.agent ?? ''));
   if (!agent) { usageFailure(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`); return; }
   request.agent = agent;
-  const result = applyTaskEvent(request);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(request.taskRef);
+  if (!resolved.ok) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => {
+      let current = applyTaskEvent(request, { lockAlreadyHeld: true });
+      const values = request as Record<string, unknown>;
+      if (current.status !== 'failed' || !values.overrideTicket) return current;
+      if (!values.overrideTarget || !values.overrideScope) {
+        return { ...current, humanOverride: { status: 'failed', error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires target and scope' } } } as typeof current & { humanOverride: unknown };
+      }
+      const consumed = consumeHumanOverride({
+        taskRef: request.taskRef,
+        ticketId: String(values.overrideTicket),
+        failureId: failureId('task-event', current.error?.code ?? 'EVENT_TRANSITION_INVALID'),
+        target: String(values.overrideTarget),
+        scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyTaskEvent(request, { 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 task event was committed' : `${retried.error?.code ?? 'EVENT_FAILED'}: ${retried.error?.message ?? 'manual task event 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 { taskEvent };

package/lib/internal/task-ledger.ts

@@ -2,14 +2,17 @@ import fs from 'node:fs';
 
 import { applyLedgerIntent } from '../task/ledger-intents.ts';
 import type { LedgerIntent } from '../task/ledger-intents.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, stage-status\n`;
 const FLAGS: Record<string, string> = {
   '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
   '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
   '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['ordinal', 'round']);
 const BOOLEAN = new Set(['needsImplementation']);
@@ -58,11 +61,16 @@ function taskLedger(args: string[] = []): void {
     'finding-review': ['needsImplementation'],
     'decision-upsert': ['needsImplementation']
   };
-  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? [])]);
+  const overrideFields = kind === 'stage-status' || kind === 'decision-next-id'
+    ? []
+    : ['overrideTicket', 'overrideTarget', 'overrideScope'];
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? []), ...overrideFields]);
   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 dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
   if (kind === 'stage-status') {
     if (!isReviewStage(String(values.stage))) { usageFailure(`stage-status requires a valid review stage`); return; }
     const resolved = resolveTaskRef(taskRef);
@@ -87,9 +95,45 @@ function taskLedger(args: string[] = []): void {
     }
     return;
   }
-  const result = applyLedgerIntent(values as LedgerIntent);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const lockResolved = resolveTaskRef(taskRef);
+  if (!lockResolved.ok) { usageFailure(lockResolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(lockResolved.repoRoot, lockResolved.taskId, `task-ledger.${kind}`, () => {
+      let current = applyLedgerIntent(values as LedgerIntent);
+      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('ledger-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget),
+        scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyLedgerIntent(values as LedgerIntent, { manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'LEDGER_FAILED'}: ${retried.error?.message ?? 'manual ledger 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 { taskLedger };