@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/dist/lib/agent-clients/schema.js

@@ -10,14 +10,15 @@ const AGENT_CLIENTS_SCHEMA = {
             maxItems: AGENT_CLIENT_IDS.length,
             uniqueItems: true,
             description: 'Canonical Agent Client configuration. Object ID completeness and uniqueness are enforced by the runtime normalizer.',
-            items: {
+            additionalItems: false,
+            items: AGENT_CLIENT_IDS.map((id) => ({
                 type: 'object',
                 additionalProperties: false,
                 required: ['id', 'enabled', 'installInSandbox'],
                 properties: {
                     id: {
-                        type: 'string',
-                        enum: [...AGENT_CLIENT_IDS]
+                        const: id,
+                        type: 'string'
                     },
                     enabled: {
                         type: 'boolean'
@@ -35,7 +36,7 @@ const AGENT_CLIENTS_SCHEMA = {
                         }
                     }
                 }
-            }
+            }))
         },
         customTUIs: {
             type: 'array',

package/dist/lib/agent-clients/tokens.js

@@ -1,25 +1,15 @@
 // Active AI collaborator short tokens — the write-side whitelist for the
 // activity log. Migrated from lib/task/commands/log.ts so that the write-side
-// internal commands and the rendering side share one definition. Historical
-// Gemini tokens remain read-only and are handled by classifyAgent below.
+// internal commands and the rendering side share one definition.
 export const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'traecli']);
-// Long name -> short name mapping (HD-4, decision A): `claude-code` reuses the
-// existing orchestration precedent, and `antigravity-cli` is the active
-// client. `gemini-cli` is intentionally not writable.
+// Long name -> short name mapping: `claude-code` reuses the existing
+// orchestration precedent, and `antigravity-cli` is the active client.
 export const AGENT_LONG_NAMES = {
     'claude-code': 'claude',
     'antigravity-cli': 'antigravity'
 };
 export const AGENT_USAGE_HINT = "agent must be a short token (claude/codex/antigravity/opencode/cursor/traecli), " +
     "a long name (claude-code -> claude, antigravity-cli -> antigravity), or 'human'";
-// Read-side historical compatibility for activity-log rendering: `gemini` and
-// `gemini-cli` stay recognizable when displaying old logs, but are never
-// accepted by normalizeAgentToken (write side).
-const READ_KNOWN_AI_AGENTS = new Set([...KNOWN_AI_AGENTS, 'gemini']);
-const READ_AGENT_LONG_NAMES = {
-    ...AGENT_LONG_NAMES,
-    'gemini-cli': 'gemini'
-};
 // Strict write-side validation: the value must be exactly a short token, a
 // long name, or 'human'; returns the normalized short token, or null when
 // the value is not a recognized agent.
@@ -41,9 +31,9 @@ export function classifyAgent(raw) {
         return { status: 'unknown', display: 'human' };
     if (token === 'human')
         return { status: 'human', display: 'human' };
-    if (READ_KNOWN_AI_AGENTS.has(token))
+    if (KNOWN_AI_AGENTS.has(token))
         return { status: 'ai', display: token };
-    const short = READ_AGENT_LONG_NAMES[token];
+    const short = AGENT_LONG_NAMES[token];
     return short ? { status: 'ai', display: short } : { status: 'unknown', display: 'human' };
 }
 //# sourceMappingURL=tokens.js.map

package/dist/lib/decide.js

@@ -3,7 +3,7 @@ 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 { resolveTaskContext } from './task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.js';
 function parseDecisionParts(parts) {
     const decision = [];
@@ -66,47 +66,33 @@ export async function decide(args, options = {}) {
             }
         }
         else if (arg.startsWith('--item=')) {
-            if (item !== undefined) {
-                process.stderr.write("Error: duplicate option '--item'\n");
-                return 1;
-            }
-            item = arg.slice('--item='.length);
-            if (item === '') {
-                process.stderr.write('Error: --item requires a value\n');
-                return 1;
-            }
+            process.stderr.write('Error: --item=... is not supported; use --item <selector> or -i <selector>\n');
+            return 1;
         }
         else
             operands.push(arg);
     }
-    let taskRef = scope.taskRef;
-    let selector = item;
-    let decisionParts;
-    if (item !== undefined) {
-        decisionParts = operands;
-    }
-    else if (!scope.explicit) {
-        [taskRef, selector, ...decisionParts] = operands;
-    }
-    else {
-        decisionParts = [];
-    }
+    const taskRef = scope.taskRef;
+    const selector = item;
+    const decisionParts = operands;
     if (!selector || decisionParts.length === 0) {
-        process.stderr.write('Usage: ai decide [--task <ref>] --item <ordinal|ledger-id> [--needs-implementation true|false] <decision>\n       ai decide <task-ref> <ordinal|ledger-id> [--needs-implementation true|false] <decision>\n');
+        process.stderr.write('Usage: ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) [--needs-implementation true|false] <decision>\n');
         return 1;
     }
     try {
         const parsedDecision = parseDecisionParts(decisionParts);
         const now = (options.now ?? canonicalTimestamp)();
+        const resolved = resolveTaskContext(taskRef, { repoRoot: options.repoRoot });
+        if (!resolved.ok)
+            throw new Error(resolved.message);
         const request = {
-            taskRef, selector, decision: parsedDecision.decision,
+            taskRef: resolved.taskId, selector, decision: parsedDecision.decision,
             needsImplementation: parsedDecision.needsImplementation
         };
         const writeOptions = {
-            repoRoot: options.repoRoot,
+            repoRoot: resolved.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);
@@ -115,7 +101,7 @@ export async function decide(args, options = {}) {
             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 ?? ''),
+                taskRef: resolved.taskId,
                 ticketId: parsedDecision.overrideTicket,
                 failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
                 target: parsedDecision.overrideTarget,
@@ -134,9 +120,7 @@ export async function decide(args, options = {}) {
                 throw new Error(consumed.error.message);
             return current;
         };
-        result = resolved?.ok
-            ? withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute)
-            : execute();
+        result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
         if (result.error)
             throw new Error(result.error.message);
         return 0;

package/dist/lib/defaults.json

@@ -48,6 +48,10 @@
     "task": {
         "shortIdLength": 2
     },
+    "delivery": {
+        "remote": "origin",
+        "baseRef": "main"
+    },
     "labels": {
         "in": {}
     },
@@ -90,6 +94,10 @@
         ],
         "ejected": [],
         "retiredManaged": [
+            {
+                "path": ".trae/skills/",
+                "templateHashes": []
+            },
             {
                 "path": ".agents/workspace/README.md",
                 "templateHashes": [

package/dist/lib/git/workflow.js

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 const defaultRunner = (args, cwd) => {
     const result = spawnSync('git', [...args], { cwd, encoding: 'utf8' });
@@ -108,6 +109,47 @@ function commitExplicitPaths(input, runner = defaultRunner) {
         return { status: 'failed', changed: false, snapshot: after.snapshot, operations: [{ name: 'commit', status: 'failed', message: commit.stderr.trim() }], error: { code: 'GIT_COMMIT_FAILED', message: commit.stderr.trim() } };
     return { status: 'applied', changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' }, { name: 'commit', status: 'applied' }], error: null };
 }
+function previewCommitTree(input) {
+    const invalid = validatePaths(input.paths);
+    if (invalid)
+        return { status: 'failed', tree: null, error: { code: 'GIT_COMMIT_INPUT_INVALID', message: invalid } };
+    const before = inspectGitWorkflow(input.cwd);
+    if (!before.snapshot)
+        return { status: 'failed', tree: null, error: { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' } };
+    if (before.snapshot.head !== input.expectedHead) {
+        return { status: 'failed', tree: null, error: { code: 'GIT_HEAD_MISMATCH', message: `Expected HEAD ${input.expectedHead}, received ${before.snapshot.head}` } };
+    }
+    const selected = new Set(input.paths);
+    const unrelatedStaged = before.snapshot.staged.filter((candidate) => !selected.has(candidate));
+    if (unrelatedStaged.length > 0) {
+        return { status: 'failed', tree: null, error: { code: 'GIT_STAGED_SCOPE_MISMATCH', message: `Unrelated staged paths: ${unrelatedStaged.join(', ')}` } };
+    }
+    const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-preview-index-'));
+    const indexFile = path.join(temporaryDirectory, 'index');
+    const temporaryRunner = (args, cwd) => {
+        const result = spawnSync('git', [...args], {
+            cwd,
+            env: { ...process.env, GIT_INDEX_FILE: indexFile },
+            encoding: 'utf8'
+        });
+        return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    };
+    try {
+        const read = run(temporaryRunner, input.cwd, ['read-tree', input.expectedHead]);
+        if (read.status !== 0)
+            return { status: 'failed', tree: null, error: { code: 'GIT_PREVIEW_FAILED', message: read.stderr.trim() || 'Unable to prepare a temporary Git index' } };
+        const stage = run(temporaryRunner, input.cwd, ['add', '-A', '--', ...input.paths]);
+        if (stage.status !== 0)
+            return { status: 'failed', tree: null, error: { code: 'GIT_PREVIEW_FAILED', message: stage.stderr.trim() || 'Unable to stage the requested paths in a temporary index' } };
+        const tree = value(temporaryRunner, input.cwd, ['write-tree']);
+        if (!tree)
+            return { status: 'failed', tree: null, error: { code: 'GIT_PREVIEW_FAILED', message: 'Unable to write the temporary Git tree' } };
+        return { status: 'planned', tree, error: null };
+    }
+    finally {
+        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+}
 function pushGitRefs(input, runner = defaultRunner) {
     if (!input.remote || input.refs.length === 0)
         return { status: 'failed', changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_PUSH_INPUT_INVALID', message: 'Remote and refs are required' } };
@@ -185,5 +227,5 @@ function pushRebasedBranch(input, runner = defaultRunner) {
     }
     return { status: 'applied', changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'applied', ref: input.branch }], error: null };
 }
-export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch };
+export { commitExplicitPaths, inspectGitWorkflow, previewCommitTree, pushGitRefs, pushRebasedBranch };
 //# sourceMappingURL=workflow.js.map

package/dist/lib/init.js

@@ -71,7 +71,7 @@ async function cmdInit() {
     // check existing config
     if (fs.existsSync(configPath)) {
         err('This project already has agent-infra configuration.');
-        err('Use /update-agent-infra in your AI TUI to update.');
+        err('Use /update-agent-infra in your AI TUI to sync project files.');
         process.exitCode = 1;
         return;
     }
@@ -175,6 +175,7 @@ async function cmdInit() {
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         task: structuredClone(defaults.task),
+        delivery: structuredClone(defaults.delivery),
         labels: structuredClone(defaults.labels),
         files: { managed: [], merged: [], ejected: [] },
         agentClients: serializeAgentClients(defaultState)
@@ -214,7 +215,7 @@ async function cmdInit() {
     console.log('');
     ok('Project initialized successfully!');
     console.log('');
-    console.log('  If this init used npx, install agent-infra persistently before update or validation:');
+    console.log('  If this init used npx, install agent-infra persistently before ai update or validation:');
     console.log('    npm install -g @fitlab-ai/agent-infra');
     console.log('');
     if (workflowPlan.nextSteps.length === 0) {

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

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { inspectGitWorkflow, pushRebasedBranch } from '../git/workflow.js';
+import { inspectGitWorkflow, previewCommitTree, pushRebasedBranch } from '../git/workflow.js';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.js';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.js';
 import { executeCommitOperation } from '../task/commit-operation.js';
@@ -26,6 +26,13 @@ function gitWorkflow(args = []) {
         const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1], 'utf8')) : null;
         result = input ? pushRebasedBranch({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
     }
+    else if (action === 'preview-tree') {
+        const inputIndex = rest.indexOf('--input');
+        const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1], 'utf8')) : null;
+        result = input
+            ? previewCommitTree({ cwd: cwd ?? process.cwd(), paths: input.paths, expectedHead: input.expectedHead })
+            : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+    }
     else if (action === 'snapshot' || action === 'compare-trees') {
         const inputIndex = rest.indexOf('--input');
         const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1], 'utf8')) : null;

package/dist/lib/internal/platform-pr.js

@@ -1,12 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
-import { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, resolveExternalPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.js';
+import { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, resolveExternalPullRequest, skipPlatformPullRequestFact, syncPlatformPullRequest } from '../platform/pull-requests.js';
 import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.js';
 const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr skip <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
@@ -58,7 +59,7 @@ function platformPr(args = []) {
         return;
     }
     const operation = args[0];
-    if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) {
+    if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'summary-context', 'summary-sync'].includes(operation)) {
         fail('a valid operation is required');
         return;
     }
@@ -79,6 +80,7 @@ function platformPr(args = []) {
         'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
         create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
         bind: ['cwd', 'agent', 'pr', 'dryRun'],
+        skip: ['cwd', 'agent', 'dryRun'],
         sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'result', 'dryRun'],
         'summary-context': ['cwd'],
         'summary-sync': ['cwd', 'agent', 'bodyFile', 'result', 'dryRun']
@@ -106,6 +108,10 @@ function platformPr(args = []) {
         return;
     }
     values.agent = agent;
+    if (operation === 'skip') {
+        finish(skipPlatformPullRequestFact(taskRef, { cwd, agent, dryRun: values.dryRun === true }));
+        return;
+    }
     const primaryResult = values.result === undefined ? undefined : values.result;
     if (primaryResult !== undefined && !['pr_created', 'pr_reused', 'no_op'].includes(primaryResult)) {
         fail('--result must be pr_created, pr_reused, or no_op');

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

@@ -21,7 +21,6 @@ const DEMO_INPUT_PATHS = [
     'lib/prompt.ts',
     'lib/paths.ts',
     'lib/render.ts',
-    'lib/builtin-tuis.ts',
     'lib/sandbox/engines/'
 ];
 const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';

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

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { deliverTaskBranch } from '../task/delivery.js';
+const USAGE = `Usage: agent-infra-internal task-delivery <task-ref> deliver --agent <agent> [--remote <name>] [--base <branch>] [--dry-run] [--cwd <path>]\n`;
+function taskDelivery(args = []) {
+    const taskRef = args[0];
+    const operation = args[1];
+    if (!taskRef || operation !== 'deliver') {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'DELIVERY_PAYLOAD_INVALID', message: 'task ref and deliver operation are required' } })}\n`);
+        process.stderr.write(USAGE);
+        process.exitCode = 1;
+        return;
+    }
+    let agent = '';
+    let remote;
+    let baseRef;
+    let cwd = process.cwd();
+    let dryRun = false;
+    for (let index = 2; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--')) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'DELIVERY_PAYLOAD_INVALID', message: `${flag} requires a value` } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (flag === '--agent')
+            agent = value;
+        else if (flag === '--remote')
+            remote = value;
+        else if (flag === '--base')
+            baseRef = value;
+        else if (flag === '--cwd')
+            cwd = path.resolve(value);
+        else {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'DELIVERY_PAYLOAD_INVALID', message: `unknown option '${flag}'` } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const normalized = normalizeAgentToken(agent);
+    if (!normalized) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'DELIVERY_PAYLOAD_INVALID', message: `invalid --agent '${agent}': ${AGENT_USAGE_HINT}` } })}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = deliverTaskBranch(taskRef, { repoRoot: cwd, agent: normalized, remote, baseRef, dryRun });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
+        process.exitCode = 1;
+    if (result.status === 'blocked')
+        process.exitCode = 2;
+}
+export { taskDelivery };
+//# sourceMappingURL=task-delivery.js.map

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

@@ -1,7 +1,6 @@
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../task/control-authority.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`;
@@ -15,18 +14,25 @@ function fail(message) {
     process.stderr.write(USAGE);
     process.exitCode = 1;
 }
+function parseFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
+}
 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');
+    let operation;
+    try {
+        operation = parseTaskControlOperation('task-finalization', args);
+    }
+    catch (error) {
+        fail(parseFailure(error));
         return;
     }
-    const agent = normalizeAgentToken(args[3]);
-    if (!agent) {
-        fail(`invalid --agent: ${AGENT_USAGE_HINT}`);
+    if (operation.family !== 'task-finalization') {
+        fail('finalization operation is invalid');
         return;
     }
     let repoRoot;
@@ -39,14 +45,18 @@ function taskFinalization(args = []) {
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskRef(args[0], { repoRoot });
+    const resolved = resolveTaskRef(operation.request.taskRef, { 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) });
+    const boundOperation = {
+        ...operation,
+        request: { ...operation.request, taskRef: resolved.taskId }
+    };
+    const result = dispatchTaskControlOperation(createDirectHostExecutionContext({ repoRoot }), boundOperation);
     process.stdout.write(envelope(result.status, result.changed, true, result, result.error));
     process.exitCode = exitCode(result.status);
 }

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

@@ -1,7 +1,7 @@
 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 { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, isReviewStage, parseLedgerDocument, 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`;
@@ -110,7 +110,13 @@ function taskLedger(args = []) {
             return;
         }
         try {
-            const rows = parseLedger(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+            const ledger = parseLedgerDocument(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+            if (!ledger.present) {
+                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: { code: LEDGER_SECTION_MISSING_CODE, message: LEDGER_SECTION_MISSING_MESSAGE } })}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const rows = ledger.rows;
             const invalid = validateLedgerRows(rows);
             if (invalid) {
                 process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: invalid })}\n`);

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

@@ -1,76 +1,36 @@
-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 { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../task/control-authority.js';
+import { lifecycleIntentCatalog } from '../task/lifecycle.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(', ')}\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', '--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`);
     process.stderr.write(USAGE);
     process.exitCode = 1;
 }
+function parseFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
+}
 function taskLifecycle(args = []) {
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
     }
-    if (args.length < 2) {
-        usageFailure('task ref and intent are required');
-        return;
-    }
-    const values = { taskRef: args[0], intent: args[1], agent: '' };
-    const seen = new Set();
-    for (let index = 2; index < args.length; index += 1) {
-        const flag = args[index];
-        if (flag === '--dry-run') {
-            if (seen.has(flag)) {
-                usageFailure(`duplicate option '${flag}'`);
-                return;
-            }
-            seen.add(flag);
-            values.dryRun = true;
-            continue;
-        }
-        const key = FLAGS[flag];
-        if (!key) {
-            usageFailure(`unknown option '${flag}'`);
-            return;
-        }
-        if (seen.has(flag)) {
-            usageFailure(`duplicate option '${flag}'`);
-            return;
-        }
-        const value = args[++index];
-        if (value === undefined || value.startsWith('--')) {
-            usageFailure(`option '${flag}' requires a value`);
-            return;
-        }
-        seen.add(flag);
-        values[key] = key === 'alertNumber' || key === 'issueNumber' ? Number(value) : value;
+    let operation;
+    try {
+        operation = parseTaskControlOperation('task-lifecycle', args);
     }
-    const agent = normalizeAgentToken(String(values.agent ?? ''));
-    if (!agent) {
-        usageFailure(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`);
+    catch (error) {
+        usageFailure(parseFailure(error));
         return;
     }
-    values.agent = agent;
-    const dryRunConflict = overrideDryRunConflict(values);
-    if (dryRunConflict) {
-        usageFailure(dryRunConflict.message);
+    if (operation.family !== 'task-lifecycle') {
+        usageFailure('lifecycle operation is invalid');
         return;
     }
+    const request = operation.request;
     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.
+    if (request.intent === 'restore') {
         try {
             repoRoot = detectRepoRoot();
         }
@@ -79,53 +39,17 @@ function taskLifecycle(args = []) {
             process.exitCode = 1;
             return;
         }
-        taskId = String(values.taskRef);
     }
     else {
-        const resolved = resolveTaskRef(String(values.taskRef));
+        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;
         }
         repoRoot = resolved.repoRoot;
-        taskId = resolved.taskId;
-    }
-    let result;
-    try {
-        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))
-            throw error;
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
-        process.exitCode = 1;
-        return;
     }
+    const result = dispatchTaskControlOperation(createDirectHostExecutionContext({ repoRoot }), operation);
     process.stdout.write(`${JSON.stringify(result)}\n`);
     if (result.status === 'failed')
         process.exitCode = 1;