@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/dist/bin/internal-cli.js

@@ -132,6 +132,11 @@ else
             taskLifecycle(process.argv.slice(3));
             break;
         }
+        case 'task-override': {
+            const { taskOverride } = await import('../lib/internal/task-override.js');
+            taskOverride(process.argv.slice(3));
+            break;
+        }
         case 'task-short-id': {
             const { taskShortId } = await import('../lib/internal/task-short-id.js');
             taskShortId(process.argv.slice(3));

package/dist/lib/agent-clients/adapters/claude-code.js

@@ -11,7 +11,7 @@ const claudeCodeAdapter = defineAgentClientAdapter({
         commands: { level: 'integrated' },
         hooks: { level: 'integrated' },
         subagents: { level: 'experimental' },
-        orchestration: { level: 'unsupported' },
+        orchestration: { level: 'experimental' },
         sandbox: { level: 'integrated' },
         verification: { level: 'compatible' }
     },
@@ -21,8 +21,8 @@ const claudeCodeAdapter = defineAgentClientAdapter({
         guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
     },
     delegationEvidence: {
-        actualModel: 'unavailable',
-        actualReasoningEffort: 'unavailable'
+        actualModel: 'host-event',
+        actualReasoningEffort: 'spawn-ack'
     },
     project: {
         ownedPathPrefixes: ['.claude/'],

package/dist/lib/agent-clients/adapters/codex-lifecycle/app-server.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import semver from 'semver';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js';
 const LIFECYCLE_HOOKS = Object.freeze([
     Object.freeze({ event: 'PreToolUse', matcher: '^collaborationspawn_agent$', phase: 'pre-tool' }),
     Object.freeze({ event: 'PostToolUse', matcher: '', phase: 'post-tool' }),
@@ -482,7 +483,7 @@ async function preflightCodexLifecycleEvidence(repoRoot = process.cwd(), runtime
         fs.rmSync(schemaDir, { recursive: true, force: true });
     }
     const hookDefinitionHash = crypto.createHash('sha256').update(hooksRaw).digest('hex');
-    const runtimeRoot = path.join(repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+    const runtimeRoot = resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' });
     const runtimeLiveness = hasCodexRuntimeLiveness(runtimeRoot, hookDefinitionHash, runtimeIdentity);
     const transport = new CodexAppServerTransport();
     transport.start();

package/dist/lib/agent-clients/adapters/codex-lifecycle/capability-store.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { verifyLifecycleBuildIdentity } from './build-identity.js';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js';
 const DEFAULT_TTL_MS = 30_000;
 const DEFAULT_TOMBSTONE_MS = 86_400_000;
 const DEFAULT_MAX_RECORDS = 128;
@@ -22,7 +23,7 @@ function sameController(left, right) {
 }
 function createCodexCapabilityStore(options = {}) {
     const root = options.root
-        ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-capabilities');
+        ?? resolveAgentRuntimeStoreRoot({ store: 'capabilities' });
     const now = options.now ?? Date.now;
     const createToken = options.token ?? (() => crypto.randomBytes(32).toString('base64url'));
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;

package/dist/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.js

@@ -38,12 +38,39 @@ function controlFromEnvironment() {
     const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
     const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
     const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
-    if (!token || !generation || !channelDir || !statusDir) {
+    const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
+    if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
         throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
     }
-    return { token, generation, channelDir, statusDir };
+    return { token, generation, channelDir, statusDir, runtimeDir };
+}
+function verifyRuntime(runtimeDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(runtimeDir);
+    }
+    catch {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    const probe = path.join(runtimeDir, `.controller-${process.pid}-${crypto.randomUUID()}.probe`);
+    try {
+        fs.writeFileSync(probe, 'runtime-probe\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        if (fs.readFileSync(probe, 'utf8') !== 'runtime-probe\n') {
+            throw new Error('probe mismatch');
+        }
+    }
+    catch {
+        throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+    }
+    finally {
+        fs.rmSync(probe, { force: true });
+    }
 }
 function verifyControl(taskId, control) {
+    verifyRuntime(control.runtimeDir);
     let status = null;
     let lastError = null;
     for (let attempt = 0; attempt < 5; attempt += 1) {
@@ -153,6 +180,7 @@ function isolatedEnvironment(home, shimDir, contextPath, taskId, control, provid
         AGENT_INFRA_CONTROL_GENERATION: control.generation,
         AGENT_INFRA_CONTROL_DIR: control.channelDir,
         AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
+        AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,
         AGENT_INFRA_CODEX_CONTROLLER_CONTEXT: contextPath
     };
 }

package/dist/lib/agent-clients/adapters/codex-lifecycle/store.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createCodexLifecycleState, expireCodexLifecycleState, reduceCodexLifecycleEvent } from './evidence.js';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js';
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
@@ -58,7 +59,7 @@ function writeRecord(file, record, expectedRevision) {
     }
 }
 function createCodexLifecycleStore(options) {
-    const root = options.root ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+    const root = options.root ?? resolveAgentRuntimeStoreRoot({ store: 'lifecycle' });
     const now = options.now ?? (() => new Date().toISOString());
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
     fs.chmodSync(root, 0o700);

package/dist/lib/decide.js

@@ -2,25 +2,44 @@ import { VERSION } from './version.js';
 import { parseTaskScope } from './task/command-options.js';
 import { applyHumanDecision } from './task/decision-intents.js';
 import { canonicalTimestamp } from './task/write.js';
+import { consumeHumanOverride, failureId } from './task/human-override.js';
+import { resolveTaskRef } from './task/resolve-ref.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.js';
 function parseDecisionParts(parts) {
     const decision = [];
     let needsImplementation;
+    let overrideTicket;
+    let overrideTarget;
+    let overrideScope;
     for (let index = 0; index < parts.length; index += 1) {
-        if (parts[index] !== '--needs-implementation') {
-            decision.push(parts[index]);
-            continue;
+        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';
         }
-        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'");
+        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]);
         }
-        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, options = {}) {
     let scope;
@@ -79,19 +98,54 @@ export async function decide(args, options = {}) {
     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/dist/lib/init.js

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

package/dist/lib/internal/release-workflow.js

@@ -21,9 +21,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/'
 ];
 const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';
 const DEMO_OUTPUT_PATH = 'assets/demo-init.gif';

package/dist/lib/internal/task-activity.js

@@ -1,4 +1,7 @@
 import { applyPrReviewActivityIntent, inspectPrReviewActivity } from '../task/activity-intent.js';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 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]
        agent-infra-internal task-activity <task-ref> pr-review-complete --agent <agent> --artifact <canonical.md> --head <40hex> --verdict <approved|changes-requested|commented> --blockers <N> --major <N> --minor <N> [--dry-run]
@@ -14,14 +17,15 @@ const FLAGS = {
     '--major': 'major',
     '--minor': 'minor',
     '--outcome': 'outcome',
-    '--reason': 'reason'
+    '--reason': 'reason',
+    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const COMMON = ['agent', 'artifact', 'head'];
 const ALLOWED = {
     '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) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ACTIVITY_PAYLOAD_INVALID', message } })}\n`);
@@ -96,9 +100,55 @@ function taskActivity(args = []) {
             return;
         }
     }
-    const result = applyPrReviewActivityIntent(values);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (result.status === 'failed')
+    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 = null;
+    try {
+        result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, () => {
+            let current = applyPrReviewActivityIntent(values, { 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, { 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.status === 'failed');
+    if (result.status === 'failed' || overrideFailed)
         process.exitCode = 1;
 }
 export { taskActivity };

package/dist/lib/internal/task-event.js

@@ -1,5 +1,8 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { applyTaskEvent, eventCatalog } from '../task/events.js';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--orchestrated] [--dry-run]
 
 Apply one closed-set task lifecycle event and print a structured JSON result.
@@ -10,7 +13,8 @@ const FLAGS = {
     '--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']);
 function usageFailure(message) {
@@ -77,9 +81,58 @@ function taskEvent(args = []) {
         return;
     }
     request.agent = agent;
-    const result = applyTaskEvent(request);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (result.status === 'failed')
+    const dryRunConflict = overrideDryRunConflict(request);
+    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 = null;
+    try {
+        result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => {
+            let current = applyTaskEvent(request, { lockAlreadyHeld: true });
+            const values = request;
+            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' } } };
+            }
+            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.status === 'failed');
+    if (result.status === 'failed' || overrideFailed)
         process.exitCode = 1;
 }
 export { taskEvent };

package/dist/lib/internal/task-ledger.js

@@ -1,12 +1,15 @@
 import fs from 'node:fs';
 import { applyLedgerIntent } from '../task/ledger-intents.js';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 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 = {
     '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
     '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
-    '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation'
+    '--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']);
@@ -75,7 +78,10 @@ function taskLedger(args = []) {
         '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) {
@@ -86,6 +92,11 @@ function taskLedger(args = []) {
         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`);
@@ -114,9 +125,52 @@ function taskLedger(args = []) {
         }
         return;
     }
-    const result = applyLedgerIntent(values);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (result.status === 'failed')
+    const lockResolved = resolveTaskRef(taskRef);
+    if (!lockResolved.ok) {
+        usageFailure(lockResolved.message);
+        return;
+    }
+    let result;
+    let humanOverride = null;
+    try {
+        result = withTaskExecutionLock(lockResolved.repoRoot, lockResolved.taskId, `task-ledger.${kind}`, () => {
+            let current = applyLedgerIntent(values);
+            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, { 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.status === 'failed');
+    if (result.status === 'failed' || overrideFailed)
         process.exitCode = 1;
 }
 export { taskLedger };

package/dist/lib/internal/task-lifecycle.js

@@ -1,12 +1,14 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.js';
-import { resolveTaskRef } from '../task/resolve-ref.js';
+import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
 const FLAGS = {
     '--agent': 'agent', '--reason': 'reason', '--unblock-condition': 'unblockCondition',
     '--note': 'note', '--alert-number': 'alertNumber', '--staging-dir': 'stagingDir',
-    '--issue-number': 'issueNumber'
+    '--issue-number': 'issueNumber', '--override-ticket': 'overrideTicket',
+    '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
@@ -58,15 +60,64 @@ function taskLifecycle(args = []) {
         return;
     }
     values.agent = agent;
-    const resolved = resolveTaskRef(String(values.taskRef));
-    if (!resolved.ok) {
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
-        process.exitCode = 1;
+    const dryRunConflict = overrideDryRunConflict(values);
+    if (dryRunConflict) {
+        usageFailure(dryRunConflict.message);
         return;
     }
+    let repoRoot;
+    let taskId;
+    if (values.intent === 'restore') {
+        // restore's precondition is that the task does NOT exist locally yet (it only lives
+        // in a staging dir), so resolveTaskRef's existence check is inapplicable here; identity
+        // is guaranteed by applyTaskLifecycle's own full-TASK-id check plus staging validation.
+        try {
+            repoRoot = detectRepoRoot();
+        }
+        catch (error) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'REPO_ROOT_NOT_FOUND', message: error instanceof Error ? error.message : String(error) } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        taskId = String(values.taskRef);
+    }
+    else {
+        const resolved = resolveTaskRef(String(values.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;
+        }
+        repoRoot = resolved.repoRoot;
+        taskId = resolved.taskId;
+    }
     let result;
     try {
-        result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-lifecycle.${String(values.intent)}`, () => applyTaskLifecycle(values));
+        result = withTaskExecutionLock(repoRoot, taskId, `task-lifecycle.${String(values.intent)}`, () => {
+            const lifecycleResult = applyTaskLifecycle(values);
+            if (lifecycleResult.status !== 'failed' || !values.overrideTicket)
+                return lifecycleResult;
+            if (!values.overrideTarget || !values.overrideScope) {
+                return {
+                    ...lifecycleResult,
+                    error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires --override-target and --override-scope' }
+                };
+            }
+            const override = consumeHumanOverride({
+                taskRef: String(values.taskRef),
+                ticketId: String(values.overrideTicket),
+                failureId: failureId('lifecycle.apply', lifecycleResult.error?.code ?? 'LIFECYCLE_FAILED'),
+                target: String(values.overrideTarget),
+                scope: String(values.overrideScope),
+                intent: String(values.intent),
+                ...(values.alertNumber ? { alertNumber: Number(values.alertNumber) } : {}),
+                ...(values.issueNumber ? { issueNumber: Number(values.issueNumber) } : {}),
+                ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {})
+            });
+            if (override.status === 'failed')
+                return { ...lifecycleResult, humanOverride: override };
+            return { ...lifecycleResult, ...override, humanOverride: override, error: null };
+        });
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))