@fitlab-ai/agent-infra 0.9.6 → 0.9.8

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/codex-lifecycle.js

@@ -4,8 +4,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { preflightCodexLifecycleEvidence, resolveCodexTerminal, resolveCodexThread } from '../agent-clients/adapters/codex-lifecycle/app-server.js';
 import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.js';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.js';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
+import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
 import { activateCodexOrchestrationDelegation, activateCodexSpawnDelegation, reconcileCodexOrchestrationDelegation, sealCodexOrchestrationDelegation, sealCodexParentDelegation } from '../task/codex-orchestration.js';
-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)$/;
 function output(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
@@ -34,6 +38,7 @@ function parse(args) {
         return null;
     }
     const allowed = {
+        'capability-arm': ['--task-id'],
         'hook-event': ['--event', '--bridge'],
         'resolve-start': ['--child-id'],
         'resolve-stop': ['--child-id'],
@@ -71,6 +76,16 @@ function hookDefinitionHash() {
     const file = path.join(process.cwd(), '.codex', 'hooks.json');
     return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
+function controllerBinding(taskId) {
+    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() {
     let input = '';
     process.stdin.setEncoding('utf8');
@@ -156,6 +171,29 @@ async function codexLifecycle(args = []) {
                 output({ status: 'ready', changed: false, evidence: result, diagnostics: result.diagnostics, error: null });
             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'];
@@ -166,6 +204,36 @@ async function codexLifecycle(args = []) {
                 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/dist/lib/internal/codex-sandbox-controller.js

@@ -0,0 +1,106 @@
+import { runCodexSandboxController, verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
+function fail(code, message, exitCode = 1) {
+    process.stdout.write(`${JSON.stringify({
+        status: 'failed',
+        changed: false,
+        error: { code, message }
+    })}\n`);
+    process.exitCode = exitCode;
+}
+function parse(args) {
+    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 = {};
+    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 = []) {
+    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 };
+//# sourceMappingURL=codex-sandbox-controller.js.map

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))