@fitlab-ai/agent-infra 0.8.5 → 0.9.0

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

@@ -0,0 +1,217 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import semver from 'semver';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.js';
+import { inspectPlatformRelease, reconcileReleaseMilestones } from '../platform/releases.js';
+import { inspectHomebrewChannel, inspectNpmChannel } from '../release/channels.js';
+import { releaseSnapshot } from '../release/workflow.js';
+function command(cwd, executable, args) {
+    return spawnSync(executable, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+function runOptionalDemo(cwd, run = command) {
+    const vhs = run(cwd, 'vhs', ['--version']);
+    if (vhs.status !== 0)
+        return { status: 'skipped', reasonCode: 'VHS_MISSING', message: null, outputPath: null };
+    const ffmpeg = run(cwd, 'ffmpeg', ['-version']);
+    if (ffmpeg.status !== 0)
+        return { status: 'skipped', reasonCode: 'FFMPEG_MISSING', message: null, outputPath: null };
+    const demo = run(cwd, 'npm', ['run', 'demo:regen']);
+    if (demo.status !== 0) {
+        return {
+            status: 'failed',
+            reasonCode: 'DEMO_COMMAND_FAILED',
+            message: String(demo.stderr || demo.stdout),
+            outputPath: null
+        };
+    }
+    const outputPath = 'assets/demo-init.gif';
+    if (!fs.existsSync(path.join(cwd, outputPath))) {
+        return {
+            status: 'failed',
+            reasonCode: 'DEMO_OUTPUT_MISSING',
+            message: `${outputPath} was not generated`,
+            outputPath: null
+        };
+    }
+    return { status: 'recorded', reasonCode: null, message: null, outputPath };
+}
+function git(cwd, args) {
+    const result = command(cwd, 'git', args);
+    return result.status === 0 ? String(result.stdout).trim() : null;
+}
+async function inspectFacts(cwd, version) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    const config = JSON.parse(fs.readFileSync(path.join(cwd, '.agents', '.airc.json'), 'utf8'));
+    const tag = `v${version}`;
+    const branch = git(cwd, ['branch', '--show-current']) || '';
+    const head = git(cwd, ['rev-parse', 'HEAD']);
+    const localTagTarget = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`]);
+    const remoteBranch = branch ? git(cwd, ['ls-remote', '--heads', 'origin', branch]) : null;
+    const remoteTag = git(cwd, ['ls-remote', '--tags', 'origin', `refs/tags/${tag}`]);
+    const platform = inspectPlatformRelease(tag, { cwd });
+    const npm = await inspectNpmChannel(pkg.name, version);
+    const formulaUrl = `https://raw.githubusercontent.com/${config.org}/homebrew-tap/main/Formula/${config.project}.rb`;
+    const homebrew = await inspectHomebrewChannel(formulaUrl, version);
+    const workflows = platform.workflows;
+    const smokeRun = workflows.find((run) => String(run.name).toLowerCase().includes('post-release-smoke') && String(run.headBranch) === tag);
+    const smoke = smokeRun ? String(smokeRun.conclusion) === 'success' ? 'success' : String(smokeRun.status) === 'completed' ? 'failed' : 'pending' : null;
+    const postMessage = git(cwd, ['log', '-1', '--pretty=%s']) || '';
+    return {
+        localTag: Boolean(localTagTarget && localTagTarget === head),
+        localTagConflict: Boolean(localTagTarget && localTagTarget !== head),
+        remoteBranch: Boolean(remoteBranch && remoteBranch.split(/\s+/)[0] === head), remoteTag: Boolean(remoteTag),
+        githubRelease: platform.platform.type !== 'github'
+            ? true
+            : platform.status === 'blocked' ? null : Boolean(platform.release?.published),
+        npm: npm.published, homebrew: homebrew.published, smoke,
+        postCommit: postMessage.includes(`after v${version}`)
+    };
+}
+function changedPaths(cwd) {
+    const output = git(cwd, ['status', '--porcelain=v1']) || '';
+    return output.split('\n').filter(Boolean).map((line) => line.slice(3)).filter((value, index, all) => all.indexOf(value) === index);
+}
+function updateReleaseMetadata(cwd, version) {
+    const [major = '0', minor = '0'] = version.split('.');
+    const aircPath = path.join(cwd, '.agents', '.airc.json');
+    const airc = JSON.parse(fs.readFileSync(aircPath, 'utf8'));
+    fs.writeFileSync(aircPath, `${JSON.stringify({ ...airc, templateVersion: `v${version}` }, null, 2)}\n`);
+    for (const [fileName, supported, unsupported] of [
+        ['SECURITY.md', `| v${major}.${minor}.x   | Supported             |`, `| < v${major}.${minor}.0 | Not Supported         |`],
+        ['SECURITY.zh-CN.md', `| v${major}.${minor}.x   | 支持中                |`, `| < v${major}.${minor}.0 | 不再支持              |`]
+    ]) {
+        const filePath = path.join(cwd, fileName);
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, 'utf8')
+            .replace(/^\| v\d+\.\d+\.x\s+\| (?:Supported|支持中)\s+\|$/m, supported)
+            .replace(/^\| < v\d+\.\d+\.0\s+\| (?:Not Supported|不再支持)\s+\|$/m, unsupported);
+        fs.writeFileSync(filePath, content);
+    }
+}
+async function releaseWorkflow(args = []) {
+    const [action, rawVersion, ...rest] = args;
+    const version = String(rawVersion || '').replace(/^v/, '');
+    const cwdIndex = rest.indexOf('--cwd');
+    const cwd = path.resolve(cwdIndex >= 0 && rest[cwdIndex + 1] ? rest[cwdIndex + 1] : process.cwd());
+    if (!['inspect', 'prepare', 'publish', 'post'].includes(action || '') || !semver.valid(version)) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'RELEASE_INPUT_INVALID', message: 'Usage: release-workflow inspect|prepare|publish|post <version>' } })}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const before = releaseSnapshot(version, await inspectFacts(cwd, version));
+    if (action === 'inspect') {
+        process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`);
+        return;
+    }
+    if (action === 'prepare') {
+        if (before.facts.localTagConflict) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} does not point to HEAD` } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (before.phase !== 'unprepared') {
+            const milestones = reconcileReleaseMilestones(version, { cwd });
+            process.stdout.write(`${JSON.stringify({ ...milestones, snapshot: before })}\n`);
+            process.exitCode = milestones.status === 'failed' ? 1 : milestones.status === 'blocked' ? 2 : 0;
+            return;
+        }
+        const entropyIndex = rest.indexOf('--entropy-report');
+        const entropy = entropyIndex >= 0 ? rest[entropyIndex + 1] : null;
+        if (!entropy || !fs.existsSync(path.resolve(cwd, entropy))) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'ENTROPY_REPORT_REQUIRED', message: '--entropy-report must reference an existing report' } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const entropyContent = fs.readFileSync(path.resolve(cwd, entropy), 'utf8');
+        const blockingCount = Number(/^\|\s*release-blocking\s*\|\s*(\d+)\s*\|/m.exec(entropyContent)?.[1] ?? NaN);
+        if (!Number.isFinite(blockingCount) || blockingCount > 0) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'ENTROPY_REPORT_BLOCKING', message: 'Entropy report is invalid or contains release-blocking findings' } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const inspected = inspectGitWorkflow(cwd);
+        if (!inspected.snapshot || inspected.snapshot.worktree.length || inspected.snapshot.staged.length) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'WORKTREE_DIRTY', message: 'Release prepare requires a clean worktree' } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        for (const [exe, commandArgs] of [['npm', ['test']], ['npm', ['version', version, '--no-git-tag-version']], ['npm', ['install', '--package-lock-only']], [process.execPath, ['scripts/build-inline.js']]]) {
+            if (exe === process.execPath)
+                updateReleaseMetadata(cwd, version);
+            const result = command(cwd, exe, commandArgs);
+            if (result.status !== 0) {
+                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_PREPARE_COMMAND_FAILED', message: String(result.stderr || result.stdout) } })}\n`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const committed = commitExplicitPaths({ cwd, paths: changedPaths(cwd), message: `chore: release v${version}` });
+        if (committed.status === 'failed') {
+            process.stdout.write(`${JSON.stringify(committed)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const tagged = command(cwd, 'git', ['tag', '-a', `v${version}`, '-m', `Release v${version}`]);
+        const milestones = tagged.status === 0 ? reconcileReleaseMilestones(version, { cwd }) : null;
+        const snapshot = releaseSnapshot(version, await inspectFacts(cwd, version));
+        const failed = tagged.status !== 0 || milestones?.status === 'failed';
+        const blocked = milestones?.status === 'blocked';
+        const status = failed ? 'failed' : blocked ? 'blocked' : 'applied';
+        process.stdout.write(`${JSON.stringify({ status, changed: true, snapshot, operations: milestones?.operations ?? [], error: tagged.status !== 0 ? { code: 'GIT_TAG_FAILED', message: String(tagged.stderr) } : milestones?.error ?? null })}\n`);
+        process.exitCode = failed ? 1 : blocked ? 2 : 0;
+        return;
+    }
+    if (action === 'publish') {
+        if (!['prepared', 'partially-published'].includes(before.phase)) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const branch = git(cwd, ['branch', '--show-current']) || '';
+        const refs = [...(!before.facts.remoteBranch ? [branch] : []), ...(!before.facts.remoteTag ? [`refs/tags/v${version}`] : [])];
+        const result = pushGitRefs({ cwd, remote: 'origin', refs });
+        process.stdout.write(`${JSON.stringify({ ...result, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`);
+        process.exitCode = result.status === 'failed' ? 1 : result.status === 'degraded' ? 2 : 0;
+        return;
+    }
+    const channelsComplete = before.facts.githubRelease === true && before.facts.npm === true && before.facts.homebrew === true;
+    if (!['published', 'post-pending'].includes(before.phase) || !channelsComplete || before.facts.smoke !== 'success') {
+        process.stdout.write(`${JSON.stringify({ status: before.facts.smoke === 'failed' ? 'failed' : 'blocked', changed: false, snapshot: before, error: { code: 'RELEASE_CHANNELS_PENDING', message: 'Release channels or smoke workflow are not complete' } })}\n`);
+        process.exitCode = before.facts.smoke === 'failed' ? 1 : 2;
+        return;
+    }
+    const built = command(cwd, 'npm', ['run', 'build']);
+    if (built.status !== 0) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(built.stderr || built.stdout) } })}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const demo = runOptionalDemo(cwd);
+    if (demo.status === 'failed') {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, demo, error: { code: 'RELEASE_POST_DEMO_FAILED', message: demo.message } })}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    for (const [exe, commandArgs] of [['npm', ['version', 'prerelease', '--preid=alpha', '--no-git-tag-version']], ['npm', ['install', '--package-lock-only']], [process.execPath, ['scripts/build-inline.js']]]) {
+        const result = command(cwd, exe, commandArgs);
+        if (result.status !== 0) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(result.stderr || result.stdout) } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const committed = commitExplicitPaths({ cwd, paths: changedPaths(cwd), message: `chore: prepare next dev iteration after v${version}` });
+    if (committed.status === 'failed') {
+        process.stdout.write(`${JSON.stringify(committed)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const branch = git(cwd, ['branch', '--show-current']) || '';
+    const pushed = pushGitRefs({ cwd, remote: 'origin', refs: [branch] });
+    process.stdout.write(`${JSON.stringify({ ...pushed, demo, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`);
+    process.exitCode = pushed.status === 'failed' ? 1 : pushed.status === 'degraded' ? 2 : 0;
+}
+export { inspectFacts, releaseWorkflow, runOptionalDemo };
+//# sourceMappingURL=release-workflow.js.map

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

@@ -0,0 +1,67 @@
+import { resolveArtifactContext } from '../task/artifact-lifecycle.js';
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n\nInspect one workflow artifact family and print a read-only JSON context.\n`;
+function failUsage(message) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_PAYLOAD_INVALID', message } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 2;
+}
+function taskArtifact(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.length < 2) {
+        failUsage('task ref and operation are required');
+        return;
+    }
+    if (args[1] !== 'inspect') {
+        failUsage(`unknown operation '${args[1]}'`);
+        return;
+    }
+    let family = '';
+    const seen = new Set();
+    for (let index = 2; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag !== '--family') {
+            failUsage(`unknown option '${flag}'`);
+            return;
+        }
+        if (seen.has(flag)) {
+            failUsage(`duplicate option '${flag}'`);
+            return;
+        }
+        const value = args[++index];
+        if (!value || value.startsWith('--')) {
+            failUsage(`option '${flag}' requires a value`);
+            return;
+        }
+        seen.add(flag);
+        family = value;
+    }
+    if (!family) {
+        failUsage("option '--family' is required");
+        return;
+    }
+    const result = resolveArtifactContext(args[0], family);
+    const output = family === 'code' && result.codeMode ? {
+        ...result,
+        mode: result.codeMode.mode,
+        code_max: result.codeMode.codeMax,
+        rev_max: result.codeMode.reviewMax,
+        verdict: result.codeMode.verdict,
+        next_round: result.next?.round ?? null,
+        next_artifact: result.next?.name ?? null,
+        review_artifact: result.codeMode.reviewArtifact,
+        implementation_input: result.codeMode.implementationInput,
+        decision_id: result.codeMode.decisionId,
+        decision_evidence: result.codeMode.decisionEvidence,
+        message: result.codeMode.message
+    } : result;
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    if (result.status === 'refused')
+        process.exitCode = 1;
+    else if (result.status === 'failed')
+        process.exitCode = 2;
+}
+export { taskArtifact };
+//# sourceMappingURL=task-artifact.js.map

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

@@ -0,0 +1,43 @@
+import { parseTaskScope } from '../task/command-options.js';
+import { resolveTaskContext } from '../task/resolve-ref.js';
+const USAGE = `Usage: agent-infra-internal task-context resolve [<task-ref> | --task <task-ref> | -t <task-ref>]\n`;
+function fail(code, message, usage = false) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code, message } })}\n`);
+    if (usage)
+        process.stderr.write(USAGE);
+    process.exitCode = 1;
+}
+function taskContext(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args[0] !== 'resolve') {
+        fail('TASK_CONTEXT_PAYLOAD_INVALID', "operation 'resolve' is required", true);
+        return;
+    }
+    let scope;
+    try {
+        scope = parseTaskScope(args.slice(1));
+    }
+    catch (error) {
+        fail('TASK_CONTEXT_PAYLOAD_INVALID', error instanceof Error ? error.message : String(error), true);
+        return;
+    }
+    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
+        fail('TASK_CONTEXT_PAYLOAD_INVALID', 'task ref must be provided once', true);
+        return;
+    }
+    const taskRef = scope.taskRef ?? scope.positionals[0];
+    const result = resolveTaskContext(taskRef);
+    if (!result.ok) {
+        fail(result.code, result.message);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify({
+        status: 'resolved', changed: false, taskId: result.taskId, taskDir: result.taskDir,
+        taskMdPath: result.taskMdPath, taskState: result.state, error: null
+    })}\n`);
+}
+export { taskContext };
+//# sourceMappingURL=task-context.js.map

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

@@ -0,0 +1,70 @@
+import { applyTaskEvent, eventCatalog } from '../task/events.js';
+const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--dry-run]
+
+Apply one closed-set task lifecycle event and print a structured JSON result.
+Events: ${eventCatalog.join(', ')}
+`;
+const FLAGS = {
+    '--agent': 'agent', '--round': 'round', '--question': 'question', '--artifact': 'artifact',
+    '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
+    '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
+    '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
+    '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult'
+};
+const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
+function usageFailure(message) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'EVENT_PAYLOAD_INVALID', message } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+}
+function taskEvent(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (args.length < 2) {
+        usageFailure('task ref and event are required');
+        return;
+    }
+    const request = { taskRef: args[0], event: 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);
+            request.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);
+        if (NUMERIC.has(key))
+            request[key] = Number(value);
+        else if (key === 'verdict')
+            request.verdict = value;
+        else
+            request[key] = value;
+    }
+    const result = applyTaskEvent(request);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
+        process.exitCode = 1;
+}
+export { taskEvent };
+//# sourceMappingURL=task-event.js.map

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

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import { applyLedgerIntent } from '../task/ledger-intents.js';
+import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, stage-status\n`;
+const FLAGS = {
+    '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
+    '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
+    '--status': 'status', '--artifact': 'artifact'
+};
+const NUMERIC = new Set(['ordinal', 'round']);
+function usageFailure(message) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+}
+function taskLedger(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const [taskRef, kind] = args;
+    if (!taskRef || !kind) {
+        usageFailure('task ref and intent are required');
+        return;
+    }
+    if (!['finding-upsert', 'finding-respond', 'finding-review', 'decision-next-id', 'decision-upsert', 'stage-status'].includes(kind)) {
+        usageFailure(`unknown ledger intent '${kind}'`);
+        return;
+    }
+    const values = { kind, taskRef };
+    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] = NUMERIC.has(key) ? Number(value) : value;
+    }
+    const required = {
+        'finding-upsert': ['stage', 'reviewArtifact', 'ordinal', 'severity', 'evidence'],
+        'finding-respond': ['id', 'round', 'status', 'evidence'],
+        'finding-review': ['id', 'status', 'evidence'],
+        'decision-next-id': [],
+        'decision-upsert': ['id', 'stage', 'artifact'],
+        'stage-status': ['stage']
+    };
+    const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]]);
+    const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+    const missing = required[kind].find((key) => values[key] === undefined);
+    if (unexpected) {
+        usageFailure(`${kind} does not accept '${unexpected}'`);
+        return;
+    }
+    if (missing) {
+        usageFailure(`${kind} requires '${missing}'`);
+        return;
+    }
+    if (kind === 'stage-status') {
+        if (!isReviewStage(String(values.stage))) {
+            usageFailure(`stage-status requires a valid review stage`);
+            return;
+        }
+        const resolved = resolveTaskRef(taskRef);
+        if (!resolved.ok || resolved.state !== 'active') {
+            const message = resolved.ok ? `task ${resolved.taskId} is ${resolved.state}, expected active` : resolved.message;
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.ok ? 'TASK_STATE_MISMATCH' : resolved.code, message } })}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const rows = parseLedger(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+            const invalid = validateLedgerRows(rows);
+            if (invalid) {
+                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: invalid })}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            process.stdout.write(`${JSON.stringify({ status: 'ready', changed: false, taskId: resolved.taskId, stageStatus: summarizeLedgerStage(rows, values.stage), error: null })}\n`);
+        }
+        catch (error) {
+            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: { code: 'LEDGER_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const result = applyLedgerIntent(values);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
+        process.exitCode = 1;
+}
+export { taskLedger };
+//# sourceMappingURL=task-ledger.js.map

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

@@ -0,0 +1,58 @@
+import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.js';
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
+const FLAGS = {
+    '--agent': 'agent', '--reason': 'reason', '--unblock-condition': 'unblockCondition',
+    '--note': 'note', '--alert-number': 'alertNumber', '--staging-dir': 'stagingDir',
+    '--issue-number': 'issueNumber'
+};
+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 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;
+    }
+    const result = applyTaskLifecycle(values);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
+        process.exitCode = 1;
+}
+export { taskLifecycle };
+//# sourceMappingURL=task-lifecycle.js.map

package/dist/lib/internal/task-short-id.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { detectRepoRoot } from '../task/resolve-ref.js';
+import { configuredShortIdLength, executeShortIdCommand } from '../task/short-id.js';
+const USAGE = `Usage: agent-infra-internal task-short-id <alloc|release|resolve|list> [argument] [--active-dir <path>] [--short-id-length <N>] [--verify]\n`;
+function failure(message) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, output: '', error: { code: 'SHORT_ID_PAYLOAD_INVALID', message } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+}
+function taskShortId(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const operation = args[0];
+    if (!operation || !['alloc', 'release', 'resolve', 'list'].includes(operation)) {
+        failure('a valid short-id operation is required');
+        return;
+    }
+    const positional = [];
+    let activeDir = null;
+    let shortIdLength = null;
+    let verify = false;
+    const seen = new Set();
+    for (let index = 1; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === '--verify') {
+            if (seen.has(value)) {
+                failure(`duplicate option '${value}'`);
+                return;
+            }
+            seen.add(value);
+            verify = true;
+            continue;
+        }
+        if (value === '--active-dir' || value === '--short-id-length') {
+            if (seen.has(value)) {
+                failure(`duplicate option '${value}'`);
+                return;
+            }
+            const optionValue = args[++index];
+            if (optionValue === undefined || optionValue.startsWith('--')) {
+                failure(`option '${value}' requires a value`);
+                return;
+            }
+            seen.add(value);
+            if (value === '--active-dir')
+                activeDir = path.resolve(optionValue);
+            else
+                shortIdLength = Number(optionValue);
+            continue;
+        }
+        if (value.startsWith('--')) {
+            failure(`unknown option '${value}'`);
+            return;
+        }
+        positional.push(value);
+    }
+    if (positional.length > (operation === 'list' ? 0 : 1)) {
+        failure('too many positional arguments');
+        return;
+    }
+    let repoRoot = null;
+    try {
+        repoRoot = detectRepoRoot();
+    }
+    catch { /* custom active-dir mode */ }
+    const resolvedActiveDir = activeDir ?? (repoRoot ? path.join(repoRoot, '.agents', 'workspace', 'active') : null);
+    if (!resolvedActiveDir) {
+        failure('cannot determine active task directory');
+        return;
+    }
+    const width = shortIdLength ?? (repoRoot ? configuredShortIdLength(repoRoot) : 2);
+    const result = executeShortIdCommand({
+        operation: operation,
+        argument: positional[0], activeDir: resolvedActiveDir, shortIdLength: width, verify
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
+        process.exitCode = 1;
+}
+export { taskShortId };
+//# sourceMappingURL=task-short-id.js.map