@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/lib/agent-clients/config.ts

@@ -10,20 +10,13 @@ import type {
   OrchestrationModelPolicy
 } from './types.ts';
 
-type AgentClientConfigInput = Readonly<{
-  agentClients?: unknown;
-  tuis?: unknown;
-  sandbox?: unknown;
-  customTUIs?: unknown;
-}>;
+type AgentClientConfigInput = Readonly<Record<string, unknown>>;
 
 type AgentClientDiagnosticCode =
   | 'INVALID_AGENT_CLIENTS'
   | 'DUPLICATE_AGENT_CLIENT'
   | 'MISSING_AGENT_CLIENT'
-  | 'UNKNOWN_AGENT_CLIENT'
-  | 'LEGACY_CONFLICT'
-  | 'LEGACY_VALUE_IGNORED';
+  | 'UNKNOWN_AGENT_CLIENT';
 
 type AgentClientDiagnostic = Readonly<{
   code: AgentClientDiagnosticCode;
@@ -31,13 +24,8 @@ type AgentClientDiagnostic = Readonly<{
 }>;
 
 type NormalizeAgentClientsResult = Readonly<{
-  source: 'canonical' | 'legacy';
   state: AgentClientState;
   canonical: AgentClientsConfig;
-  remainingSandboxTools: readonly string[] | undefined;
-  removeLegacyTuis: boolean;
-  changed: boolean;
-  diagnostics: readonly AgentClientDiagnostic[];
 }>;
 
 class AgentClientConfigError extends Error {
@@ -166,147 +154,29 @@ function serializeAgentClients(state: AgentClientState): AgentClientsConfig {
   }));
 }
 
-function projectLegacyTuis(
-  value: unknown,
-  diagnostics: AgentClientDiagnostic[]
-): Readonly<Record<AgentClientId, boolean>> {
-  if (!Array.isArray(value)) {
-    return Object.fromEntries(
-      AGENT_CLIENT_IDS.map((id) => [id, true])
-    ) as Readonly<Record<AgentClientId, boolean>>;
-  }
-
-  const enabled = new Set<AgentClientId>();
-  for (const [index, candidate] of value.entries()) {
-    if (isAgentClientId(candidate)) {
-      enabled.add(candidate);
-    } else {
-      diagnostics.push({
-        code: 'LEGACY_VALUE_IGNORED',
-        path: `tuis[${index}]`
-      });
-    }
-  }
-  return Object.fromEntries(
-    AGENT_CLIENT_IDS.map((id) => [id, enabled.has(id)])
-  ) as Readonly<Record<AgentClientId, boolean>>;
-}
-
-type SandboxProjection = Readonly<{
-  installed: Readonly<Record<AgentClientId, boolean>>;
-  clientSignals: ReadonlySet<AgentClientId>;
-  remainingTools: readonly string[] | undefined;
-}>;
-
-function projectLegacySandbox(
-  value: unknown,
-  diagnostics: AgentClientDiagnostic[]
-): SandboxProjection {
-  if (!Array.isArray(value) || value.length === 0) {
-    return {
-      installed: Object.fromEntries(
-        AGENT_CLIENT_IDS.map((id) => [id, true])
-      ) as Readonly<Record<AgentClientId, boolean>>,
-      clientSignals: new Set<AgentClientId>(),
-      remainingTools: Array.isArray(value) ? [] : undefined
-    };
-  }
-
-  const installed = new Set<AgentClientId>();
-  const remainingTools: string[] = [];
-  for (const [index, candidate] of value.entries()) {
-    if (isAgentClientId(candidate)) {
-      installed.add(candidate);
-    } else if (typeof candidate === 'string') {
-      remainingTools.push(candidate);
-    } else {
-      diagnostics.push({
-        code: 'LEGACY_VALUE_IGNORED',
-        path: `sandbox.tools[${index}]`
-      });
-    }
-  }
-  return {
-    installed: Object.fromEntries(
-      AGENT_CLIENT_IDS.map((id) => [id, installed.has(id)])
-    ) as Readonly<Record<AgentClientId, boolean>>,
-    clientSignals: installed,
-    remainingTools
-  };
-}
-
-function stateFromLegacy(
-  enabled: Readonly<Record<AgentClientId, boolean>>,
-  installed: Readonly<Record<AgentClientId, boolean>>
-): AgentClientState {
-  return Object.fromEntries(
-    AGENT_CLIENT_IDS.map((id) => [
-      id,
-      {
-        enabled: enabled[id],
-        installInSandbox: installed[id]
-      }
-    ])
-  ) as AgentClientState;
-}
-
-function sameCanonicalOrder(value: unknown): boolean {
-  return Array.isArray(value)
-    && value.every((entry, index) => isRecord(entry) && entry.id === AGENT_CLIENT_IDS[index]);
-}
-
 function normalizeAgentClients(
   input: AgentClientConfigInput
 ): NormalizeAgentClientsResult {
-  const diagnostics: AgentClientDiagnostic[] = [];
-  const hasCanonical = hasOwn(input, 'agentClients');
-  const hasLegacyTuis = hasOwn(input, 'tuis');
-  const sandbox = isRecord(input.sandbox) ? input.sandbox : undefined;
-  const hasLegacySandboxTools = sandbox !== undefined && hasOwn(sandbox, 'tools');
-  const tuiProjection = projectLegacyTuis(input.tuis, diagnostics);
-  const sandboxProjection = projectLegacySandbox(sandbox?.tools, diagnostics);
-
-  if (!hasCanonical) {
-    const state = stateFromLegacy(tuiProjection, sandboxProjection.installed);
-    return {
-      source: 'legacy',
-      state,
-      canonical: serializeAgentClients(state),
-      remainingSandboxTools: sandboxProjection.remainingTools,
-      removeLegacyTuis: hasLegacyTuis,
-      changed: true,
-      diagnostics
-    };
-  }
-
+  if (!hasOwn(input, 'agentClients')) fail('MISSING_AGENT_CLIENT', 'agentClients');
   const state = parseCanonical(input.agentClients);
-  if (hasLegacyTuis) {
-    for (const id of AGENT_CLIENT_IDS) {
-      if (state[id].enabled !== tuiProjection[id]) {
-        fail('LEGACY_CONFLICT', 'tuis');
-      }
+  for (const [index, id] of AGENT_CLIENT_IDS.entries()) {
+    const entry = Array.isArray(input.agentClients) ? input.agentClients[index] : undefined;
+    if (!isRecord(entry) || entry.id !== id) {
+      fail('INVALID_AGENT_CLIENTS', `agentClients[${index}].id`);
     }
   }
-  if (hasLegacySandboxTools) {
-    for (const id of sandboxProjection.clientSignals) {
-      if (!state[id].installInSandbox) {
-        fail('LEGACY_CONFLICT', 'sandbox.tools');
+  if (hasOwn(input, 'tuis')) fail('INVALID_AGENT_CLIENTS', 'tuis');
+  const sandbox = isRecord(input.sandbox) ? input.sandbox : undefined;
+  if (Array.isArray(sandbox?.tools)) {
+    for (const [index, tool] of sandbox.tools.entries()) {
+      if (isAgentClientId(tool)) {
+        fail('INVALID_AGENT_CLIENTS', `sandbox.tools[${index}]`);
       }
     }
   }
-
   return {
-    source: 'canonical',
     state,
-    canonical: serializeAgentClients(state),
-    remainingSandboxTools: hasLegacySandboxTools
-      ? sandboxProjection.remainingTools
-      : undefined,
-    removeLegacyTuis: hasLegacyTuis,
-    changed: hasLegacyTuis
-      || sandboxProjection.clientSignals.size > 0
-      || !sameCanonicalOrder(input.agentClients),
-    diagnostics
+    canonical: serializeAgentClients(state)
   };
 }
 

package/lib/agent-clients/reconcile.ts

@@ -32,7 +32,6 @@ type AgentClientSeedOperation = Readonly<{
 type WorkflowDiagnostic = AgentClientDiagnostic | Readonly<{ code: string; path: string }>;
 
 type AgentClientWorkflowPlan = Readonly<{
-  source: 'canonical' | 'legacy';
   before: AgentClientState;
   desired: AgentClientState;
   nextConfig: Record<string, unknown>;
@@ -149,15 +148,6 @@ function planAgentClientReconciliation(input: Readonly<{
 
   const nextConfig = structuredClone(input.config);
   nextConfig.agentClients = serializeAgentClients(desired);
-  delete nextConfig.tuis;
-  if (normalized.remainingSandboxTools !== undefined) {
-    const sandbox = isRecord(nextConfig.sandbox) ? { ...nextConfig.sandbox } : {};
-    sandbox.tools = [
-      'agent-infra',
-      ...normalized.remainingSandboxTools.filter((tool) => tool !== 'agent-infra')
-    ];
-    nextConfig.sandbox = sandbox;
-  }
   const existingFiles = isRecord(nextConfig.files) ? nextConfig.files : {};
   const existingBaselines = isRecord(existingFiles.managedBaselines)
     ? existingFiles.managedBaselines
@@ -240,14 +230,13 @@ function planAgentClientReconciliation(input: Readonly<{
     || actionableSeed;
 
   return Object.freeze({
-    source: normalized.source,
     before: normalized.state,
     desired,
     nextConfig,
     projectAssets,
     seedOperations: Object.freeze(seedOperations),
     nextSteps,
-    diagnostics: Object.freeze([...normalized.diagnostics, ...custom.diagnostics]),
+    diagnostics: Object.freeze([...custom.diagnostics]),
     changed,
     projectRoot: input.projectRoot,
     configPath: path.join(input.projectRoot, '.agents', '.airc.json')

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,33 +1,20 @@
 // 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']);
+  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'
 };
 
 export const AGENT_USAGE_HINT =
-  "agent must be a short token (claude/codex/antigravity/opencode/cursor), " +
+  "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/agent-clients/types.ts

@@ -2,7 +2,8 @@ const AGENT_CLIENT_IDS = [
   'claude-code',
   'codex',
   'antigravity-cli',
-  'opencode'
+  'opencode',
+  'traecli'
 ] as const;
 
 type AgentClientId = (typeof AGENT_CLIENT_IDS)[number];

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

@@ -22,6 +22,11 @@
       "id": "opencode",
       "enabled": true,
       "installInSandbox": true
+    },
+    {
+      "id": "traecli",
+      "enabled": true,
+      "installInSandbox": true
     }
   ],
   "sandbox": {
@@ -85,6 +90,10 @@
     ],
     "ejected": [],
     "retiredManaged": [
+      {
+        "path": ".trae/skills/",
+        "templateHashes": []
+      },
       {
         "path": ".agents/workspace/README.md",
         "templateHashes": [

package/lib/init.ts

@@ -117,7 +117,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;
   }
@@ -294,7 +294,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/codex-lifecycle.ts

@@ -11,7 +11,7 @@ import {
 import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
 import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
 import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import { verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { hasSealableOrchestrationDelegation } from '../task/orchestration.ts';
@@ -101,7 +101,7 @@ function hookDefinitionHash(): string {
 function controllerBinding(taskId: string) {
   const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
   if (!contextPath) return undefined;
-  const context = verifyCodexSandboxControllerContext(contextPath, { repoRoot: process.cwd() });
+  const context = verifyCodexSandboxControllerContextWithWarnings(contextPath, { repoRoot: process.cwd() }).context;
   return {
     instanceDigest: context.controllerInstanceDigest,
     controlGeneration: context.controlGeneration

package/lib/internal/codex-sandbox-controller.ts

@@ -1,6 +1,6 @@
 import {
   runCodexSandboxController,
-  verifyCodexSandboxControllerContext
+  verifyCodexSandboxControllerContextWithWarnings
 } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 
 const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
@@ -58,7 +58,8 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
       const contextPath = parsed.values['--context']
         ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
       if (!contextPath) throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');
-      const context = verifyCodexSandboxControllerContext(contextPath);
+      const verified = verifyCodexSandboxControllerContextWithWarnings(contextPath);
+      const context = verified.context;
       process.stdout.write(`${JSON.stringify({
         status: 'ready',
         changed: false,
@@ -69,8 +70,8 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
           expiresAt: context.expiresAt,
           buildIdentity: context.buildIdentity,
           hookDefinitionHash: context.hookDefinitionHash,
-          lifecycleProfilesHash: context.lifecycleProfilesHash
         },
+        ...(verified.warnings.length > 0 ? { warnings: verified.warnings } : {}),
         error: null
       })}\n`);
       return;

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/sandbox-control.ts

@@ -9,7 +9,7 @@ import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
 import {
   controllerProofFromContext,
-  verifyCodexSandboxControllerContext
+  verifyCodexSandboxControllerContextWithWarnings
 } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 
 function isCanonicalCodexPrepare(args: readonly string[]): boolean {
@@ -118,7 +118,7 @@ async function sandboxControl(args: string[]): Promise<void> {
       if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
         const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
         const proof = contextPath
-          ? controllerProofFromContext(verifyCodexSandboxControllerContext(contextPath))
+          ? controllerProofFromContext(verifyCodexSandboxControllerContextWithWarnings(contextPath).context)
           : null;
         response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
       } else {

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