@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/dist/lib/internal/sandbox-control.js

@@ -1,6 +1,70 @@
-import { requestSandboxControl, SandboxControlClientError } from '../sandbox/control/client.js';
+import { requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTaskControl, SandboxControlClientError } from '../sandbox/control/client.js';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { serveSandboxControl } from '../sandbox/control/server.js';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.js';
+import { controllerProofFromContext, verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+function isCanonicalCodexPrepare(args) {
+    if (args[1] !== 'prepare')
+        return false;
+    const clients = [];
+    for (let index = 2; index < args.length; index += 1) {
+        if (args[index] === '--client')
+            clients.push(args[index + 1] ?? '');
+        else if (args[index]?.startsWith('--client='))
+            clients.push(args[index].slice('--client='.length));
+    }
+    return clients.length === 1 && clients[0] === 'codex';
+}
+function writeFinalizationEnvelope(status, accepted, error, changed = false, result = null) {
+    process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
+}
+function finalizationErrorStatus(error) {
+    if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN')
+        return 'unknown';
+    return error.retryable ? 'blocked' : 'failed';
+}
+function sandboxFinalizationClient(args) {
+    if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
+        const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
+        writeFinalizationEnvelope('failed', false, error);
+        process.stderr.write('Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n');
+        process.exitCode = 1;
+        return;
+    }
+    const agent = normalizeAgentToken(args[3]);
+    if (!agent) {
+        const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: `invalid --agent: ${AGENT_USAGE_HINT}`, retryable: false };
+        writeFinalizationEnvelope('failed', false, error);
+        process.exitCode = 1;
+        return;
+    }
+    let response;
+    try {
+        response = requestSandboxTaskFinalization({ agent });
+    }
+    catch (error) {
+        if (!(error instanceof SandboxControlClientError))
+            throw error;
+        writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
+        process.stderr.write(`${error.detail.message}\n`);
+        process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
+        return;
+    }
+    if (response.phase === 'rejected') {
+        const error = response.error ?? {
+            code: 'SANDBOX_CONTROL_REJECTED',
+            message: 'sandbox control rejected the finalization request',
+            retryable: false
+        };
+        writeFinalizationEnvelope(finalizationErrorStatus(error), error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error);
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
+        return;
+    }
+    process.stdout.write(response.stdout);
+    process.stderr.write(response.stderr);
+    process.exitCode = response.exitCode ?? 1;
+}
 async function sandboxControl(args) {
     const [operation, ...rest] = args;
     if (operation === 'serve') {
@@ -33,9 +97,22 @@ async function sandboxControl(args) {
     }
     if (operation === 'client') {
         const [family = '', ...commandArgs] = rest;
+        if (family === 'task-finalization') {
+            sandboxFinalizationClient(commandArgs);
+            return;
+        }
         let response;
         try {
-            response = requestSandboxControl({ family, args: commandArgs });
+            if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
+                const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+                const proof = contextPath
+                    ? controllerProofFromContext(verifyCodexSandboxControllerContext(contextPath))
+                    : null;
+                response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
+            }
+            else {
+                response = requestSandboxControl({ family, args: commandArgs });
+            }
         }
         catch (error) {
             if (!(error instanceof SandboxControlClientError))

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-finalization.js

@@ -0,0 +1,54 @@
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { applyTaskFinalization } from '../task/finalization.js';
+import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
+import { verifyTaskEvent } from '../task/verification.js';
+const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
+function envelope(status, changed, accepted, result, error) {
+    return `${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`;
+}
+function exitCode(status) {
+    return status === 'completed' ? 0 : status === 'blocked' ? 2 : 1;
+}
+function fail(message) {
+    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message, retryable: false };
+    process.stdout.write(envelope('failed', false, false, null, error));
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+}
+function taskFinalization(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
+        fail('task ref, complete intent, and --agent are required');
+        return;
+    }
+    const agent = normalizeAgentToken(args[3]);
+    if (!agent) {
+        fail(`invalid --agent: ${AGENT_USAGE_HINT}`);
+        return;
+    }
+    let repoRoot;
+    try {
+        repoRoot = detectRepoRoot();
+    }
+    catch (error) {
+        const detail = { code: 'REPO_ROOT_NOT_FOUND', message: error instanceof Error ? error.message : String(error), retryable: false };
+        process.stdout.write(envelope('failed', false, true, null, detail));
+        process.exitCode = 1;
+        return;
+    }
+    const resolved = resolveTaskRef(args[0], { repoRoot });
+    if (!resolved.ok) {
+        const detail = { code: resolved.code, message: resolved.message, retryable: false };
+        process.stdout.write(envelope('failed', false, true, null, detail));
+        process.exitCode = 1;
+        return;
+    }
+    const result = applyTaskFinalization({ taskRef: resolved.taskId, intent: 'complete', agent }, { repoRoot, preflight: (request, options) => verifyTaskEvent({ ...request, event: 'complete-task.hard-preflight' }, options) });
+    process.stdout.write(envelope(result.status, result.changed, true, result, result.error));
+    process.exitCode = exitCode(result.status);
+}
+export { taskFinalization };
+//# sourceMappingURL=task-finalization.js.map

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