@fitlab-ai/agent-infra 0.9.11 → 0.9.13

package/README.md

@@ -55,10 +55,10 @@ Once initialized, open the project in your AI TUI and install the latest skills:
 
 ```bash
 /import-issue 42           # AI reads the issue, creates a task, extracts requirements
-/analyze-task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
-/review-analysis <task-id> # An isolated reviewer checks the analysis
-/plan-task <task-id>       # AI proposes a fix plan
-/review-plan <task-id>     # A fresh isolated reviewer checks the plan
+/analyze-task --task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
+/review-analysis --task <task-id> # An isolated reviewer checks the analysis
+/plan-task --task <task-id>       # AI proposes a fix plan
+/review-plan --task <task-id>     # A fresh isolated reviewer checks the plan
 ```
 
 > **You review the plan and reply in natural language:**
@@ -71,12 +71,12 @@ Just fix it at the application layer in LoginService.
 > AI re-runs `/plan-task` to update the plan accordingly and confirms.
 
 ```bash
-/code-task <task-id>       # AI writes the fix, adds a test for user+tag@example.com — green
-/review-code <task-id>     # A fresh isolated reviewer reports one minor finding
-/code-task <task-id>       # AI fixes the minor issue and re-validates
-/commit
-/create-pr <task-id>       # PR opened, auto-linked to issue #42
-/complete-task <task-id>   # task archived
+/code-task --task <task-id>       # AI writes the fix, tests it, and creates a local checkpoint commit
+/review-code --task <task-id>     # A fresh isolated reviewer reports one minor finding
+/code-task --task <task-id>       # AI fixes the minor issue, re-validates, and creates a new checkpoint
+/review-code --task <task-id>     # The reviewer approves the current checkpoint
+/create-pr --task <task-id>       # The reviewed branch is published to its task-bound target; PR links issue #42
+/complete-task --task <task-id>   # task archived
 ```
 
 **11 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
@@ -189,10 +189,10 @@ The most-used lifecycle commands, in delivery order. The command prefix varies b
 | `run-task` | Resume the lifecycle with fresh isolated executors/reviewers when the selected client exposes verified actual model/effort evidence; Codex now has an experimental Hooks + App Server evidence channel, but orchestration remains disabled until that channel is connected to delegation receipts |
 | `analyze-task` → `review-analysis` | Capture scope and risks, then review the analysis |
 | `plan-task` → `review-plan` | Design the approach, then review the plan |
-| `code-task` → `review-code` | Implement and test, then run a structured code review |
-| `commit` → `create-pr` → `complete-task` | Commit, open a PR, and archive the task |
+| `code-task` → `review-code` | Implement and test; `code-task` creates a local checkpoint, then a structured review checks that checkpoint |
+| `create-pr` → `complete-task` | Publish the approved checkpoint to the task-bound target branch, then archive after merge and final gates |
 
-Start with one atomic role policy, for example: `$run-task 42 --executor-model <id> --executor-reasoning-effort <value> --reviewer-model <id> --reviewer-reasoning-effort <value>`. Both roles may use the same model. With no explicit policy, `run-task` reads the current Agent Client's optional `agentClients[].orchestration`; if neither source is complete, it shows the host model-selection guidance before creating any run. Re-entry uses the persisted run policy. Finish or clear active runs before upgrading agent-infra; unsupported disk state fails closed without rewriting.
+Start with one atomic role policy, for example: `$run-task --task 42 --executor-model <id> --executor-reasoning-effort <value> --reviewer-model <id> --reviewer-reasoning-effort <value>`. Both roles may use the same model. With no explicit policy, `run-task` reads the current Agent Client's optional `agentClients[].orchestration`; if neither source is complete, it shows the host model-selection guidance before creating any run. Re-entry uses the persisted run policy. Finish or clear active runs before upgrading agent-infra; unsupported disk state fails closed without rewriting.
 
 See the full catalog — task status, release, security, and project-maintenance skills — in [Built-in AI Skills](./docs/en/skills.md).
 

package/README.zh-CN.md

@@ -54,10 +54,10 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 ```bash
 /import-issue 42           # AI 读取 Issue，创建任务，提取需求
-/analyze-task <task-id>    # AI 扫描代码库，定位根因，输出 analysis.md
-/review-analysis <task-id> # 隔离 reviewer 审查分析产物
-/plan-task <task-id>       # AI 提出修复方案
-/review-plan <task-id>     # fresh 隔离 reviewer 审查方案
+/analyze-task --task <task-id>    # AI 扫描代码库，定位根因，输出 analysis.md
+/review-analysis --task <task-id> # 隔离 reviewer 审查分析产物
+/plan-task --task <task-id>       # AI 提出修复方案
+/review-plan --task <task-id>     # fresh 隔离 reviewer 审查方案
 ```
 
 > **你审查方案后用自然语言回复：**
@@ -70,12 +70,12 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 > AI 按你的要求重跑 `/plan-task` 更新方案并确认。
 
 ```bash
-/code-task <task-id>       # AI 编写修复代码，添加 user+tag@example.com 测试 —— 通过
-/review-code <task-id>     # fresh 隔离 reviewer 报告一个次要问题
-/code-task <task-id>       # AI 修复次要问题并重新验证
-/commit
-/create-pr <task-id>       # PR 已创建，自动关联 Issue #42
-/complete-task <task-id>   # 任务归档
+/code-task --task <task-id>       # AI 编写修复代码、测试，并创建本地 checkpoint commit
+/review-code --task <task-id>     # fresh 隔离 reviewer 报告一个次要问题
+/code-task --task <task-id>       # AI 修复次要问题、重新验证，并创建新的 checkpoint
+/review-code --task <task-id>     # reviewer 审查并通过当前 checkpoint
+/create-pr --task <task-id>       # 将已审查分支发布到任务绑定目标分支；PR 自动关联 Issue #42
+/complete-task --task <task-id>   # 任务归档
 ```
 
 **11 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
@@ -188,10 +188,10 @@ ai agent-client configure
 | `run-task` | 当所选客户端能提供已验证的 actual model/effort 证据时，用 fresh 隔离 executor/reviewer 续跑生命周期；Codex 现已具备实验性的 Hooks + App Server 证据通道，但在该通道接入 delegation receipt 前仍不会启用 orchestration |
 | `analyze-task` → `review-analysis` | 明确范围与风险，再审查分析 |
 | `plan-task` → `review-plan` | 设计实现路径，再审查方案 |
-| `code-task` → `review-code` | 实现并测试，再执行结构化代码审查 |
-| `commit` → `create-pr` → `complete-task` | 提交、创建 PR、归档任务 |
+| `code-task` → `review-code` | 实现并测试；`code-task` 创建本地 checkpoint，再由结构化审查检视该 checkpoint |
+| `create-pr` → `complete-task` | 将已通过审查的 checkpoint 发布到任务绑定目标分支，并在合并和最终门禁通过后归档 |
 
-启动时可提供原子角色策略，例如：`$run-task 42 --executor-model <id> --executor-reasoning-effort <值> --reviewer-model <id> --reviewer-reasoning-effort <值>`。两个角色可以使用同一模型。完全没有显式策略时，`run-task` 读取当前 Agent Client 可选的 `agentClients[].orchestration`；两个来源都不完整时，会在创建任何 run 前展示宿主模型选择指引。重入使用已持久化的 run 策略。升级 agent-infra 前必须完成或清空 active run；不受支持的磁盘状态会失败关闭且不改写。
+启动时可提供原子角色策略，例如：`$run-task --task 42 --executor-model <id> --executor-reasoning-effort <值> --reviewer-model <id> --reviewer-reasoning-effort <值>`。两个角色可以使用同一模型。完全没有显式策略时，`run-task` 读取当前 Agent Client 可选的 `agentClients[].orchestration`；两个来源都不完整时，会在创建任何 run 前展示宿主模型选择指引。重入使用已持久化的 run 策略。升级 agent-infra 前必须完成或清空 active run；不受支持的磁盘状态会失败关闭且不改写。
 
 完整清单（任务状态、发布、安全、项目维护等 skill）见 [内置 AI Skills](./docs/zh-CN/skills.md)。
 

package/dist/bin/internal-cli.js

@@ -45,12 +45,12 @@ if (taskControlCommand) {
             }
             case 'task-lifecycle': {
                 const { taskLifecycle } = await import('../lib/internal/task-lifecycle.js');
-                taskLifecycle(process.argv.slice(3));
+                await taskLifecycle(process.argv.slice(3));
                 break;
             }
             case 'task-finalization': {
                 const { taskFinalization } = await import('../lib/internal/task-finalization.js');
-                taskFinalization(process.argv.slice(3));
+                await taskFinalization(process.argv.slice(3));
                 break;
             }
         }
@@ -60,7 +60,7 @@ else
     switch (command) {
         case 'task-create': {
             const { taskCreate } = await import('../lib/internal/task-create.js');
-            taskCreate(process.argv.slice(3));
+            await taskCreate(process.argv.slice(3));
             break;
         }
         case 'sandbox-control': {
@@ -88,6 +88,11 @@ else
             gitWorkflow(process.argv.slice(3));
             break;
         }
+        case 'task-delivery': {
+            const { taskDelivery } = await import('../lib/internal/task-delivery.js');
+            taskDelivery(process.argv.slice(3));
+            break;
+        }
         case 'release-workflow': {
             const { releaseWorkflow } = await import('../lib/internal/release-workflow.js');
             await releaseWorkflow(process.argv.slice(3));
@@ -95,37 +100,37 @@ else
         }
         case 'platform-release-notes': {
             const { platformReleaseNotes } = await import('../lib/internal/platform-release-notes.js');
-            platformReleaseNotes(process.argv.slice(3));
+            await platformReleaseNotes(process.argv.slice(3));
             break;
         }
         case 'platform-context': {
             const { platformContext } = await import('../lib/internal/platform-context.js');
-            platformContext(process.argv.slice(3));
+            await platformContext(process.argv.slice(3));
             break;
         }
         case 'platform-comment': {
             const { platformComment } = await import('../lib/internal/platform-comment.js');
-            platformComment(process.argv.slice(3));
+            await platformComment(process.argv.slice(3));
             break;
         }
         case 'platform-issue': {
             const { platformIssue } = await import('../lib/internal/platform-issue.js');
-            platformIssue(process.argv.slice(3));
+            await platformIssue(process.argv.slice(3));
             break;
         }
         case 'platform-pr': {
             const { platformPr } = await import('../lib/internal/platform-pr.js');
-            platformPr(process.argv.slice(3));
+            await platformPr(process.argv.slice(3));
             break;
         }
         case 'platform-pr-review': {
             const { platformPrReview } = await import('../lib/internal/platform-pr-review.js');
-            platformPrReview(process.argv.slice(3));
+            await platformPrReview(process.argv.slice(3));
             break;
         }
         case 'pr-review-grade': {
             const { prReviewGrade } = await import('../lib/internal/pr-review-grade.js');
-            prReviewGrade(process.argv.slice(3));
+            await prReviewGrade(process.argv.slice(3));
             break;
         }
         case 'platform-checks': {
@@ -140,17 +145,17 @@ else
         }
         case 'task-ledger': {
             const { taskLedger } = await import('../lib/internal/task-ledger.js');
-            taskLedger(process.argv.slice(3));
+            await taskLedger(process.argv.slice(3));
             break;
         }
         case 'task-warning': {
             const { taskWarning } = await import('../lib/internal/task-warning.js');
-            taskWarning(process.argv.slice(3));
+            await taskWarning(process.argv.slice(3));
             break;
         }
         case 'task-activity': {
             const { taskActivity } = await import('../lib/internal/task-activity.js');
-            taskActivity(process.argv.slice(3));
+            await taskActivity(process.argv.slice(3));
             break;
         }
         case 'task-artifact': {
@@ -165,27 +170,32 @@ else
         }
         case 'task-review': {
             const { taskReview } = await import('../lib/internal/task-review.js');
-            taskReview(process.argv.slice(3));
+            await taskReview(process.argv.slice(3));
             break;
         }
         case 'task-event': {
             const { taskEvent } = await import('../lib/internal/task-event.js');
-            taskEvent(process.argv.slice(3));
+            await taskEvent(process.argv.slice(3));
+            break;
+        }
+        case 'task-invalidation': {
+            const { taskInvalidation } = await import('../lib/internal/task-invalidation.js');
+            taskInvalidation(process.argv.slice(3));
             break;
         }
         case 'task-lifecycle': {
             const { taskLifecycle } = await import('../lib/internal/task-lifecycle.js');
-            taskLifecycle(process.argv.slice(3));
+            await taskLifecycle(process.argv.slice(3));
             break;
         }
         case 'task-finalization': {
             const { taskFinalization } = await import('../lib/internal/task-finalization.js');
-            taskFinalization(process.argv.slice(3));
+            await taskFinalization(process.argv.slice(3));
             break;
         }
         case 'task-override': {
             const { taskOverride } = await import('../lib/internal/task-override.js');
-            taskOverride(process.argv.slice(3));
+            await taskOverride(process.argv.slice(3));
             break;
         }
         case 'task-short-id': {
@@ -200,7 +210,7 @@ else
         }
         case 'task-verify': {
             const { taskVerify } = await import('../lib/internal/task-verify.js');
-            taskVerify(process.argv.slice(3));
+            await taskVerify(process.argv.slice(3));
             break;
         }
         case 'task-validate': {

package/dist/lib/agent-clients/adapters/codex-lifecycle/build-identity.js

@@ -16,20 +16,63 @@ function isLifecycleProtocolVersion(value) {
 function normalizeRelativePath(value) {
     return value.replaceAll('\\', '/');
 }
+function isSafeLifecyclePath(value) {
+    return exactText(value)
+        && value === normalizeRelativePath(value)
+        && !path.isAbsolute(value)
+        && !/^[A-Za-z]:[\\/]/u.test(value)
+        && !value.split('/').includes('..');
+}
+function isLifecycleLauncherLine(value) {
+    return typeof value === 'string'
+        && value.length > 1
+        && value.slice(0, -1).trim() === value.slice(0, -1)
+        && value.startsWith('#!')
+        && value.endsWith('\n')
+        && value.indexOf('\n') === value.length - 1
+        && !value.includes('\r');
+}
+function readLifecycleLauncherShebang(value, executableFiles) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Lifecycle manifest launcher shebang policy is invalid');
+    }
+    const policy = value;
+    if (!isSafeLifecyclePath(policy.sourceFile)
+        || !isSafeLifecyclePath(policy.compiledFile)
+        || !isLifecycleLauncherLine(policy.canonicalLine)
+        || !Array.isArray(policy.acceptedLines)
+        || !policy.acceptedLines.every(isLifecycleLauncherLine)
+        || new Set(policy.acceptedLines).size !== policy.acceptedLines.length
+        || !policy.acceptedLines.includes(policy.canonicalLine)
+        || !executableFiles.includes(policy.sourceFile)
+        || policy.compiledFile !== normalizeRelativePath(path.join('dist', policy.sourceFile.endsWith('.ts')
+            ? policy.sourceFile.replace(/\.ts$/u, '.js')
+            : policy.sourceFile))) {
+        throw new Error('Lifecycle manifest launcher shebang policy is invalid');
+    }
+    return Object.freeze({
+        sourceFile: policy.sourceFile,
+        compiledFile: policy.compiledFile,
+        canonicalLine: policy.canonicalLine,
+        acceptedLines: Object.freeze([...policy.acceptedLines])
+    });
+}
 function readLifecycleManifestFiles(packageRoot) {
     const file = path.join(packageRoot, 'lib', 'agent-clients', 'adapters', 'codex-lifecycle', 'manifest-files.json');
     const value = JSON.parse(fs.readFileSync(file, 'utf8'));
     if (!Array.isArray(value.executableFiles)
         || !Array.isArray(value.contractFiles)
-        || !value.executableFiles.every(exactText)
-        || !value.contractFiles.every(exactText)
+        || !value.executableFiles.every(isSafeLifecyclePath)
+        || !value.contractFiles.every(isSafeLifecyclePath)
         || new Set(value.executableFiles).size !== value.executableFiles.length
         || new Set(value.contractFiles).size !== value.contractFiles.length) {
         throw new Error('Lifecycle manifest file list is invalid');
     }
+    const executableFiles = Object.freeze([...value.executableFiles]);
     return Object.freeze({
-        executableFiles: Object.freeze([...value.executableFiles]),
-        contractFiles: Object.freeze([...value.contractFiles])
+        executableFiles,
+        contractFiles: Object.freeze([...value.contractFiles]),
+        launcherShebang: readLifecycleLauncherShebang(value.launcherShebang, executableFiles)
     });
 }
 function executablePackageRoot() {
@@ -47,7 +90,22 @@ function executablePackageRoot() {
         current = parent;
     }
 }
-function hashFiles(root, files) {
+function normalizeLifecycleLauncherBytes(relative, content, policy) {
+    const normalized = normalizeRelativePath(relative);
+    if (normalized !== policy.sourceFile && normalized !== policy.compiledFile)
+        return content;
+    const lineEnd = content.indexOf(0x0a);
+    if (lineEnd < 0)
+        return content;
+    const firstLine = content.subarray(0, lineEnd + 1);
+    if (!policy.acceptedLines.some((line) => Buffer.from(line).equals(firstLine)))
+        return content;
+    return Buffer.concat([
+        Buffer.from(policy.canonicalLine),
+        content.subarray(lineEnd + 1)
+    ]);
+}
+function hashFiles(root, files, launcherShebang) {
     const hash = crypto.createHash('sha256');
     for (const relative of [...new Set(files.map(normalizeRelativePath))].sort()) {
         if (path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..')) {
@@ -60,7 +118,10 @@ function hashFiles(root, files) {
         }
         hash.update(relative);
         hash.update('\0');
-        hash.update(fs.readFileSync(file));
+        const content = fs.readFileSync(file);
+        hash.update(launcherShebang
+            ? normalizeLifecycleLauncherBytes(relative, content, launcherShebang)
+            : content);
         hash.update('\0');
     }
     return hash.digest('hex');
@@ -107,7 +168,7 @@ function computeLifecycleBuildIdentity(repoRoot, options = {}) {
         throw new Error('Lifecycle package version is invalid');
     let internalExecutableBuildHash;
     if (options.executableFiles) {
-        internalExecutableBuildHash = hashFiles(repoRoot, options.executableFiles);
+        internalExecutableBuildHash = hashFiles(repoRoot, options.executableFiles, defaults.launcherShebang);
     }
     else {
         const manifestFile = path.join(executableRoot, 'dist', 'lifecycle-build-manifest.json');
@@ -121,17 +182,17 @@ function computeLifecycleBuildIdentity(repoRoot, options = {}) {
             }
             if (fileURLToPath(import.meta.url).split(path.sep).includes('dist')) {
                 const compiledFiles = defaults.executableFiles.map((file) => file.endsWith('.ts') ? path.join('dist', file.replace(/\.ts$/u, '.js')) : file);
-                if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, compiledFiles)) !== manifest.internalExecutableBuildHash) {
+                if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, compiledFiles), defaults.launcherShebang) !== manifest.internalExecutableBuildHash) {
                     throw new Error('Lifecycle compiled executable build does not match its manifest');
                 }
             }
-            else if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles)) !== manifest.sourceInputHash) {
+            else if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles), defaults.launcherShebang) !== manifest.sourceInputHash) {
                 throw new Error('Lifecycle executable build manifest is stale or invalid');
             }
             internalExecutableBuildHash = manifest.internalExecutableBuildHash;
         }
         else
-            internalExecutableBuildHash = hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles));
+            internalExecutableBuildHash = hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles), defaults.launcherShebang);
     }
     return Object.freeze({
         protocolVersion: LIFECYCLE_PROTOCOL_VERSION,

package/dist/lib/agent-clients/next-steps.js

@@ -1,6 +1,7 @@
 import { listEnabledAgentClientAdapters } from './registry.js';
 import { renderAgentClientInvocation } from './invocation.js';
 import semver from 'semver';
+import { isTaskScopeSkill } from '../task/skill-scope.js';
 const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const SAFE_TASK_REF = /^(?:\d+|TASK-\d{8}-\d{6})$/;
 function requireSafeName(value, field) {
@@ -19,7 +20,11 @@ function renderNextStepCommands(input) {
         throw new Error('Invalid version');
     }
     const args = [
-        ...(input.taskRef === undefined ? [] : [input.taskRef]),
+        ...(input.taskRef === undefined
+            ? []
+            : isTaskScopeSkill(input.skillName)
+                ? ['--task', input.taskRef]
+                : [input.taskRef]),
         ...(input.version === undefined ? [] : [input.version])
     ];
     const builtins = listEnabledAgentClientAdapters(input.state).map((adapter) => Object.freeze({

package/dist/lib/decide.js

@@ -94,13 +94,13 @@ export async function decide(args, options = {}) {
             metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
         };
         let result;
-        const execute = () => {
+        const execute = async () => {
             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({
+            const consumed = await consumeHumanOverride({
                 taskRef: resolved.taskId,
                 ticketId: parsedDecision.overrideTicket,
                 failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
@@ -120,7 +120,7 @@ export async function decide(args, options = {}) {
                 throw new Error(consumed.error.message);
             return current;
         };
-        result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
+        result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
         if (result.error)
             throw new Error(result.error.message);
         return 0;

package/dist/lib/defaults.json

@@ -48,6 +48,10 @@
     "task": {
         "shortIdLength": 2
     },
+    "delivery": {
+        "remote": "origin",
+        "baseRef": "main"
+    },
     "labels": {
         "in": {}
     },

package/dist/lib/git/workflow.js

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

package/dist/lib/init.js

@@ -175,6 +175,7 @@ async function cmdInit() {
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         task: structuredClone(defaults.task),
+        delivery: structuredClone(defaults.delivery),
         labels: structuredClone(defaults.labels),
         files: { managed: [], merged: [], ejected: [] },
         agentClients: serializeAgentClients(defaultState)

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

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

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

@@ -76,7 +76,7 @@ async function platformChecks(args = []) {
         return;
     }
     if (operation === 'inspect') {
-        finish(inspectPullRequestReadiness(taskRef, { cwd }));
+        finish(await inspectPullRequestReadiness(taskRef, { cwd }));
         return;
     }
     if (operation === 'resolve-run') {
@@ -84,7 +84,7 @@ async function platformChecks(args = []) {
             fail('resolve-run requires --check-name');
             return;
         }
-        finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
+        finish(await resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
         return;
     }
     if (operation === 'logs') {
@@ -94,7 +94,7 @@ async function platformChecks(args = []) {
             fail('logs requires a positive --run and optional positive --job');
             return;
         }
-        finish(fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
+        finish(await fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
         return;
     }
     const intervalSeconds = positive(values.intervalSeconds);

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

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { checkPlatformCommentOwner, listPlatformComments, syncPlatformComment } from '../platform/issue-comments.js';
 import { backfillCompletionComments } from '../platform/completion-backfill.js';
-const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
@@ -47,7 +47,7 @@ function readBodyFile(value, cwd) {
         return fs.readFileSync(0, 'utf8');
     return fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
-function platformComment(args = []) {
+async function platformComment(args = []) {
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
@@ -70,9 +70,9 @@ function platformComment(args = []) {
     }
     const cwd = path.resolve(typeof parsed.values.cwd === 'string' ? parsed.values.cwd : process.cwd());
     if (operation === 'list') {
-        const issue = Number(parsed.values.issue);
-        if (!Number.isInteger(issue) || issue <= 0) {
-            fail('list requires a positive --issue');
+        const issue = parsed.values.issue;
+        if (typeof issue !== 'string' || !issue) {
+            fail('list requires --issue <token>');
             return;
         }
         const unexpected = Object.keys(parsed.values).find((key) => !['issue', 'cwd'].includes(key));
@@ -80,7 +80,7 @@ function platformComment(args = []) {
             fail(`list does not accept '--${unexpected}'`);
             return;
         }
-        finish(listPlatformComments(issue, cwd));
+        finish(await listPlatformComments(issue, cwd));
         return;
     }
     if (operation === 'owner') {
@@ -89,7 +89,7 @@ function platformComment(args = []) {
             fail(`owner does not accept '--${unexpected}'`);
             return;
         }
-        finish(checkPlatformCommentOwner(taskRef, { cwd }));
+        finish(await checkPlatformCommentOwner(taskRef, { cwd }));
         return;
     }
     if (operation === 'backfill') {
@@ -108,7 +108,7 @@ function platformComment(args = []) {
             fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`);
             return;
         }
-        finish(backfillCompletionComments(taskRef, { cwd, agent: normalizedAgent }));
+        finish(await backfillCompletionComments(taskRef, { cwd, agent: normalizedAgent }));
         return;
     }
     const kind = parsed.values.kind;
@@ -143,7 +143,7 @@ function platformComment(args = []) {
         fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
         return;
     }
-    finish(syncPlatformComment(taskRef, {
+    finish(await syncPlatformComment(taskRef, {
         kind: kind,
         agent: normalizedAgent,
         artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,

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

@@ -6,7 +6,7 @@ function fail(message) {
     process.stderr.write(USAGE);
     process.exitCode = 1;
 }
-function platformContext(args = []) {
+async function platformContext(args = []) {
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
@@ -35,7 +35,7 @@ function platformContext(args = []) {
         seen.add(flag);
         cwd = path.resolve(value);
     }
-    const result = resolvePlatformContext({ cwd });
+    const result = await resolvePlatformContext({ cwd });
     process.stdout.write(`${JSON.stringify(result)}\n`);
     if (result.status === 'failed')
         process.exitCode = 1;