@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/dist/lib/agent-clients/adapters/traecli.js

@@ -0,0 +1,65 @@
+import { defineAgentClientAdapter } from '../adapter.js';
+import { hostJoin } from '../../sandbox/engines/wsl2-paths.js';
+const traecliAdapter = defineAgentClientAdapter({
+    id: 'traecli',
+    displayName: 'TraeCode CLI',
+    invocation: '/${skillName}',
+    capabilities: {
+        instructions: { level: 'compatible' },
+        skills: { level: 'compatible' },
+        commands: { level: 'integrated' },
+        hooks: { level: 'compatible' },
+        subagents: { level: 'experimental' },
+        orchestration: { level: 'experimental' },
+        sandbox: { level: 'integrated' },
+        verification: { level: 'compatible' }
+    },
+    modelSelection: {
+        kind: 'interactive-only',
+        command: '/model',
+        guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
+    },
+    delegationEvidence: {
+        actualModel: 'unavailable',
+        actualReasoningEffort: 'unavailable'
+    },
+    project: {
+        ownedPathPrefixes: ['.traecli/'],
+        managed: ['.traecli/commands/'],
+        merged: [],
+        ejected: [],
+        seedCommands: [{
+                templates: {
+                    en: '.traecli/commands/update-agent-infra.en.md',
+                    'zh-CN': '.traecli/commands/update-agent-infra.zh-CN.md'
+                },
+                target: '.traecli/commands/update-agent-infra.md'
+            }],
+        customCommand: {
+            target: '.traecli/commands/${skillName}.md',
+            frontmatter: {},
+            argumentsToken: '$ARGUMENTS'
+        }
+    },
+    sandbox: {
+        createTool: ({ home }) => ({
+            id: 'traecli',
+            name: 'TraeCode CLI',
+            install: {
+                type: 'shell',
+                cmd: 'curl -fsSL https://trae.cn/trae-cli/install_v2.sh | bash'
+            },
+            sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'traecli'),
+            containerMount: '/home/devuser/.trae',
+            versionCmd: 'traecli --version',
+            setupHint: 'Run traecli login inside the container to authenticate.'
+        }),
+        aliases: [
+            { name: 'traecli-yolo', command: 'traecli --dangerously-bypass-approvals-and-sandbox; tput ed' },
+            { name: 'ty', command: 'traecli --dangerously-bypass-approvals-and-sandbox; tput ed' }
+        ],
+        hooks: []
+    }
+});
+export { traecliAdapter };
+//# sourceMappingURL=traecli.js.map

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

@@ -101,114 +101,29 @@ function serializeAgentClients(state) {
             : {})
     }));
 }
-function projectLegacyTuis(value, diagnostics) {
-    if (!Array.isArray(value)) {
-        return Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, true]));
-    }
-    const enabled = new Set();
-    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)]));
-}
-function projectLegacySandbox(value, diagnostics) {
-    if (!Array.isArray(value) || value.length === 0) {
-        return {
-            installed: Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, true])),
-            clientSignals: new Set(),
-            remainingTools: Array.isArray(value) ? [] : undefined
-        };
-    }
-    const installed = new Set();
-    const remainingTools = [];
-    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)])),
-        clientSignals: installed,
-        remainingTools
-    };
-}
-function stateFromLegacy(enabled, installed) {
-    return Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [
-        id,
-        {
-            enabled: enabled[id],
-            installInSandbox: installed[id]
-        }
-    ]));
-}
-function sameCanonicalOrder(value) {
-    return Array.isArray(value)
-        && value.every((entry, index) => isRecord(entry) && entry.id === AGENT_CLIENT_IDS[index]);
-}
 function normalizeAgentClients(input) {
-    const diagnostics = [];
-    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)
     };
 }
 export { AgentClientConfigError, normalizeAgentClients, serializeAgentClients };

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

@@ -71,15 +71,6 @@ function planAgentClientReconciliation(input) {
     });
     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
@@ -161,14 +152,13 @@ function planAgentClientReconciliation(input) {
     const changed = JSON.stringify(nextConfig) !== JSON.stringify(input.config)
         || 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/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.
-export const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'antigravity', 'opencode', 'cursor']);
-// 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.
+// 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: `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), " +
+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/agent-clients/types.js

@@ -2,7 +2,8 @@ const AGENT_CLIENT_IDS = [
     'claude-code',
     'codex',
     'antigravity-cli',
-    'opencode'
+    'opencode',
+    'traecli'
 ];
 const AGENT_CLIENT_CAPABILITY_IDS = [
     'instructions',

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

@@ -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/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;
     }
@@ -214,7 +214,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/codex-lifecycle.js

@@ -6,7 +6,7 @@ import { preflightCodexLifecycleEvidence, resolveCodexTerminal, resolveCodexThre
 import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.js';
 import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.js';
 import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
-import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+import { verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { hasSealableOrchestrationDelegation } from '../task/orchestration.js';
 import { activateCodexOrchestrationDelegation, activateCodexSpawnDelegation, reconcileCodexOrchestrationDelegation, sealCodexOrchestrationDelegation, sealCodexParentDelegation } from '../task/codex-orchestration.js';
@@ -81,7 +81,7 @@ function controllerBinding(taskId) {
     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/dist/lib/internal/codex-sandbox-controller.js

@@ -1,4 +1,4 @@
-import { runCodexSandboxController, verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+import { runCodexSandboxController, verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
 const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
 function fail(code, message, exitCode = 1) {
     process.stdout.write(`${JSON.stringify({
@@ -53,7 +53,8 @@ async function codexSandboxController(args = []) {
                 ?? 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,
@@ -64,8 +65,8 @@ async function codexSandboxController(args = []) {
                     expiresAt: context.expiresAt,
                     buildIdentity: context.buildIdentity,
                     hookDefinitionHash: context.hookDefinitionHash,
-                    lifecycleProfilesHash: context.lifecycleProfilesHash
                 },
+                ...(verified.warnings.length > 0 ? { warnings: verified.warnings } : {}),
                 error: null
             })}\n`);
             return;

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

@@ -2,7 +2,7 @@ import { requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTa
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { serveSandboxControl } from '../sandbox/control/server.js';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.js';
-import { controllerProofFromContext, verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+import { controllerProofFromContext, verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
 function isCanonicalCodexPrepare(args) {
     if (args[1] !== 'prepare')
         return false;
@@ -106,7 +106,7 @@ async function sandboxControl(args) {
             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 });
             }

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