@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/agent-clients/schema.ts

@@ -15,14 +15,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'
@@ -40,7 +41,7 @@ const AGENT_CLIENTS_SCHEMA = {
             }
           }
         }
-      }
+      }))
     },
     customTUIs: {
       type: 'array',

package/lib/agent-clients/tokens.ts

@@ -1,13 +1,11 @@
 // 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: ReadonlySet<string> =
   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: Readonly<Record<string, string>> = {
   'claude-code': 'claude',
   'antigravity-cli': 'antigravity'
@@ -17,17 +15,6 @@ 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: ReadonlySet<string> =
-  new Set([...KNOWN_AI_AGENTS, 'gemini']);
-
-const READ_AGENT_LONG_NAMES: Readonly<Record<string, string>> = {
-  ...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.
@@ -47,7 +34,7 @@ export function classifyAgent(raw: string):
   const token = raw.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
   if (token === '') return { status: 'unknown', display: 'human' };
   if (token === 'human') return { status: 'human', display: 'human' };
-  if (READ_KNOWN_AI_AGENTS.has(token)) return { status: 'ai', display: token };
-  const short = READ_AGENT_LONG_NAMES[token];
+  if (KNOWN_AI_AGENTS.has(token)) return { status: 'ai', display: token };
+  const short = AGENT_LONG_NAMES[token];
   return short ? { status: 'ai', display: short } : { status: 'unknown', display: 'human' };
 }

package/lib/decide.ts

@@ -3,7 +3,7 @@ import { parseTaskScope } from './task/command-options.ts';
 import { applyHumanDecision } from './task/decision-intents.ts';
 import { canonicalTimestamp } from './task/write.ts';
 import { consumeHumanOverride, failureId } from './task/human-override.ts';
-import { resolveTaskRef } from './task/resolve-ref.ts';
+import { resolveTaskContext } from './task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.ts';
 
 type DecideOptions = {
@@ -55,44 +55,36 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
       item = scope.positionals[++index];
       if (!item) { process.stderr.write(`Error: ${arg} requires a value\n`); return 1; }
     } 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: string[];
-  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);
       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 ?? ''),
+        taskRef: resolved.taskId,
         ticketId: parsedDecision.overrideTicket,
         failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
         target: parsedDecision.overrideTarget,
@@ -110,9 +102,7 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
       if (consumed.status === 'failed') 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;
   } catch (error) {

package/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/lib/git/workflow.ts

@@ -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';
 
 type CommandResult = { status: number | null; stdout: string; stderr: string };
@@ -105,6 +106,42 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
   return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };
 }
 
+function previewCommitTree(input: { cwd: string; paths: readonly string[]; expectedHead: string }) {
+  const invalid = validatePaths(input.paths);
+  if (invalid) return { status: 'failed' as const, tree: null, error: { code: 'GIT_COMMIT_INPUT_INVALID', message: invalid } };
+  const before = inspectGitWorkflow(input.cwd);
+  if (!before.snapshot) return { status: 'failed' as const, tree: null, error: { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' } };
+  if (before.snapshot.head !== input.expectedHead) {
+    return { status: 'failed' as const, 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' as const, 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: GitRunner = (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' as const, 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' as const, 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' as const, tree: null, error: { code: 'GIT_PREVIEW_FAILED', message: 'Unable to write the temporary Git tree' } };
+    return { status: 'planned' as const, tree, error: null };
+  } finally {
+    fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
 function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[]; expectedSha?: string }, runner: GitRunner = defaultRunner) {
   if (!input.remote || input.refs.length === 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_PUSH_INPUT_INVALID', message: 'Remote and refs are required' } };
   const operations: GitOperation[] = [];
@@ -192,5 +229,5 @@ function pushRebasedBranch(input: PushRebasedInput, runner: GitRunner = defaultR
   return { status: 'applied' as const, changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'applied' as const, ref: input.branch }], error: null };
 }
 
-export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch };
+export { commitExplicitPaths, inspectGitWorkflow, previewCommitTree, pushGitRefs, pushRebasedBranch };
 export type { CommandResult, GitRunner, PushRebasedInput };

package/lib/init.ts

@@ -32,6 +32,7 @@ type Defaults = {
   files: FileRegistry;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
+  delivery: { remote: string; baseRef: string };
   labels: Record<string, unknown>;
 };
 
@@ -43,6 +44,7 @@ type AgentConfig = {
   templateVersion: string;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
+  delivery: { remote: string; baseRef: string };
   labels: Record<string, unknown>;
   files: FileRegistry;
   agentClients: ReturnType<typeof serializeAgentClients>;
@@ -117,7 +119,7 @@ async function cmdInit(): Promise<void> {
   // 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;
   }
@@ -244,6 +246,7 @@ async function cmdInit(): Promise<void> {
     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)
@@ -294,7 +297,7 @@ async function cmdInit(): Promise<void> {
   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/lib/internal/git-workflow.ts

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { inspectGitWorkflow, pushRebasedBranch } from '../git/workflow.ts';
+import { inspectGitWorkflow, previewCommitTree, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
 import { executeCommitOperation } from '../task/commit-operation.ts';
@@ -26,6 +26,12 @@ function gitWorkflow(args: string[] = []): void {
     const inputIndex = rest.indexOf('--input');
     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/lib/internal/platform-pr.ts

@@ -7,6 +7,7 @@ import {
   createPlatformPullRequest,
   inspectPlatformPullRequest,
   resolveExternalPullRequest,
+  skipPlatformPullRequestFact,
   syncPlatformPullRequest
 } from '../platform/pull-requests.ts';
 import type { PullRequestResult } from '../platform/pull-requests.ts';
@@ -17,6 +18,7 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        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>]
@@ -64,7 +66,7 @@ function readFile(value: string, cwd: string): string {
 function platformPr(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
   const taskRef = args[1];
   if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
   const parsed = parse(args, 2);
@@ -76,6 +78,7 @@ function platformPr(args: string[] = []): void {
     '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']
@@ -88,6 +91,10 @@ function platformPr(args: string[] = []): void {
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); 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 as string)) {
     fail('--result must be pr_created, pr_reused, or no_op');

package/lib/internal/release-workflow.ts

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

package/lib/internal/task-delivery.ts

@@ -0,0 +1,53 @@
+import path from 'node:path';
+
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
+import { deliverTaskBranch } from '../task/delivery.ts';
+
+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: string[] = []): void {
+  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: string | undefined;
+  let baseRef: string | undefined;
+  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 };

package/lib/internal/task-finalization.ts

@@ -1,7 +1,10 @@
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
+import {
+  createDirectHostExecutionContext,
+  dispatchTaskControlOperation,
+  parseTaskControlOperation
+} from '../task/control-authority.ts';
 import { applyTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
-import { verifyTaskEvent } from '../task/verification.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
 
@@ -28,17 +31,26 @@ function fail(message: string): void {
   process.exitCode = 1;
 }
 
+function parseFailure(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
+}
+
 function taskFinalization(args: string[] = []): void {
   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: string;
   try {
     repoRoot = detectRepoRoot();
@@ -48,18 +60,20 @@ function taskFinalization(args: string[] = []): void {
     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/lib/internal/task-ledger.ts

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import { applyLedgerIntent } from '../task/ledger-intents.ts';
 import type { LedgerIntent } from '../task/ledger-intents.ts';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
-import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, isReviewStage, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
@@ -81,7 +81,13 @@ function taskLedger(args: string[] = []): void {
       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/lib/internal/task-lifecycle.ts

@@ -1,17 +1,14 @@
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
-import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
-import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
-import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
+import {
+  createDirectHostExecutionContext,
+  dispatchTaskControlOperation,
+  parseTaskControlOperation,
+  type TaskLifecycleControlRequest
+} from '../task/control-authority.ts';
+import { lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
-import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import type { TaskLifecycleResult } from '../task/lifecycle.ts';
 
 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: Record<string, string> = {
-  '--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: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
@@ -19,36 +16,29 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
+function parseFailure(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
+}
+
 function taskLifecycle(args: string[] = []): void {
   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: Record<string, unknown> = { taskRef: args[0], intent: args[1], agent: '' };
-  const seen = new Set<string>();
-  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);
+  } catch (error) {
+    usageFailure(parseFailure(error));
+    return;
   }
-  const agent = normalizeAgentToken(String(values.agent ?? ''));
-  if (!agent) { usageFailure(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
-  values.agent = agent;
-  const dryRunConflict = overrideDryRunConflict(values);
-  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  if (operation.family !== 'task-lifecycle') {
+    usageFailure('lifecycle operation is invalid');
+    return;
+  }
+
+  const request = operation.request as TaskLifecycleControlRequest;
   let repoRoot: string;
-  let taskId: string;
-  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();
     } catch (error) {
@@ -56,53 +46,20 @@ function taskLifecycle(args: string[] = []): void {
       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: ReturnType<typeof applyTaskLifecycle> & { humanOverride?: unknown };
-  try {
-    result = withTaskExecutionLock(
-      repoRoot,
-      taskId,
-      `task-lifecycle.${String(values.intent)}`,
-      () => {
-        const lifecycleResult = applyTaskLifecycle(values as TaskLifecycleRequest);
-        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) as TaskLifecycleRequest['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
+  ) as TaskLifecycleResult & { humanOverride?: unknown };
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
 }