@fitlab-ai/agent-infra 0.6.1 → 0.6.2

package/README.md

@@ -777,7 +777,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.1",
+  "templateVersion": "v0.6.2",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -753,7 +753,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.1",
+  "templateVersion": "v0.6.2",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/dist/lib/defaults.json

@@ -5,7 +5,7 @@
   "sandbox": {
     "engine": null,
     "runtimes": [
-      "node20"
+      "node22"
     ],
     "tools": [
       "claude-code",

package/dist/lib/sandbox/commands/create.js

@@ -18,7 +18,7 @@ import { hostJoin, toEnginePath, volumeArg } from "../engines/wsl2-paths.js";
 import { validateSelinuxDisableEnv } from "../engines/selinux.js";
 import { resolveBuildUid } from "../engines/native.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
-import { assertClaudeCredentialsAvailable, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
+import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
 const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
 const SANDBOX_ALIAS_BLOCK_END = '# <<< agent-infra managed aliases <<<';
@@ -825,11 +825,13 @@ export async function create(args) {
     assertBranchAvailable(config.repoRoot, branch, { allowedWorktrees: worktreeCandidates });
     const tools = resolveTools(effectiveConfig);
     const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
-    // Fail fast before any filesystem/docker side effects so a missing
-    // Claude Code credential blob doesn't leave the user with a stale
-    // worktree, docker image, or temporary Dockerfile they need to manually
-    // clean up.
-    assertClaudeCredentialsAvailable(effectiveConfig.home, effectiveConfig.project, resolvedTools);
+    // Fatal credential states still fail before filesystem/docker side effects.
+    // A genuinely missing Claude Code credential only removes Claude Code's
+    // sandbox config and credential mounts for this create run.
+    const credentialOutcome = prepareClaudeCredentials(effectiveConfig.home, effectiveConfig.project, resolvedTools);
+    const effectiveResolvedTools = credentialOutcome.status === 'SKIPPED'
+        ? resolvedTools.filter(({ tool }) => tool.id !== 'claude-code')
+        : resolvedTools;
     const container = containerName(effectiveConfig, branch);
     const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
     const shareCommon = shareCommonDir(effectiveConfig);
@@ -840,6 +842,11 @@ export async function create(args) {
     const engine = detectEngine(effectiveConfig);
     p.intro(pc.cyan('AI Sandbox'));
     p.log.info(`Project: ${pc.bold(effectiveConfig.project)} | Branch: ${pc.bold(branch)} | Base: ${pc.bold(baseBranch || 'HEAD')}`);
+    if (credentialOutcome.status === 'SKIPPED') {
+        p.log.warn('Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
+            + '  Claude Code is still installed in the image but will not be authenticated.\n'
+            + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".');
+    }
     try {
         p.log.step('Checking container engine...');
         await ensureDocker(effectiveConfig, (detail) => {
@@ -913,7 +920,7 @@ export async function create(args) {
             {
                 title: 'Preparing tool state',
                 task: async () => {
-                    for (const { tool, dir } of resolvedTools) {
+                    for (const { tool, dir } of effectiveResolvedTools) {
                         fs.mkdirSync(dir, { recursive: true });
                         for (const { hostPath, sandboxName } of tool.hostPreSeedFiles ?? []) {
                             const destination = path.join(dir, sandboxName);
@@ -946,7 +953,7 @@ export async function create(args) {
                             fs.writeFileSync(filePath, content, 'utf8');
                         }
                     }
-                    return `${resolvedTools.length} tool config directories ready`;
+                    return `${effectiveResolvedTools.length} tool config directories ready`;
                 }
             },
             {
@@ -978,31 +985,32 @@ export async function create(args) {
                     const cachedGpg = needsGpg
                         ? readGpgCache(effectiveConfig.home, effectiveConfig.project, undefined, signingKey)
                         : null;
-                    const envFile = buildContainerEnvFile(resolvedTools, engine);
+                    const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
                     let hostShellConfig;
                     try {
-                        const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+                        const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
                         if (claudeCodeEntry) {
                             ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
                             ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
-                            // Credential availability is asserted up-front in create() so we
-                            // know the shared credentials file already exists at this point.
+                            // prepareClaudeCredentials wrote the shared credentials file
+                            // before this point. If credentials were missing, the
+                            // claude-code entry was removed from effectiveResolvedTools.
                         }
-                        const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
+                        const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
                         if (codexEntry) {
                             ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
                             ensureCodexWorkspaceTrust(codexEntry.dir);
                         }
-                        const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
+                        const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
                         if (geminiEntry) {
                             ensureGeminiWorkspaceTrust(geminiEntry.dir);
                         }
-                        const opencodeEntry = resolvedTools.find(({ tool }) => tool.id === 'opencode');
+                        const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
                         if (opencodeEntry) {
                             // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
                             ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
                         }
-                        const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => [
+                        const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => [
                             '-v',
                             volumeArg(engine, dir, tool.containerMount)
                         ]);
@@ -1017,7 +1025,7 @@ export async function create(args) {
                             '-v',
                             volumeArg(engine, hostPath, containerPath, ':ro')
                         ]);
-                        const liveMountVolumes = resolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
+                        const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
                             .filter(({ hostPath }) => fs.existsSync(hostPath))
                             .flatMap(({ hostPath, containerSubpath }) => [
                             '-v',
@@ -1105,7 +1113,7 @@ export async function create(args) {
                                 : 'Host GPG keys unavailable; using stripped git config fallback...');
                         }
                     }
-                    for (const { tool } of resolvedTools) {
+                    for (const { tool } of effectiveResolvedTools) {
                         for (const command of tool.postSetupCmds ?? []) {
                             runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
                         }
@@ -1143,7 +1151,7 @@ export async function create(args) {
         }
     }
     p.outro(pc.green('Sandbox ready'));
-    const toolHints = resolvedTools.map(({ tool, dir }) => {
+    const toolHints = effectiveResolvedTools.map(({ tool, dir }) => {
         const hasLiveMount = (tool.hostLiveMounts ?? []).some(({ hostPath }) => fs.existsSync(hostPath));
         const hint = hasLiveMount
             ? 'Live-mounted auth/config files stay in sync with the host.'

package/dist/lib/sandbox/config.js

@@ -2,11 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
+import pc from 'picocolors';
 import { validateSandboxEngine } from "./engine.js";
 import { hostJoin } from "./engines/wsl2-paths.js";
+import { findRuntimeEngineMismatches } from "./runtime-engines.js";
 const DEFAULTS = Object.freeze({
     engine: null,
-    runtimes: ['node20'],
+    runtimes: ['node22'],
     tools: ['claude-code', 'codex', 'gemini-cli', 'opencode'],
     dockerfile: null,
     vm: {
@@ -38,7 +40,7 @@ function cloneDefaults() {
         vm: { ...DEFAULTS.vm }
     };
 }
-export function loadConfig({ platformFn = platform } = {}) {
+export function loadConfig({ platformFn = platform, writeStderr = (chunk) => process.stderr.write(chunk) } = {}) {
     const repoRoot = detectRepoRoot();
     const home = homedir();
     if (!home) {
@@ -56,6 +58,24 @@ export function loadConfig({ platformFn = platform } = {}) {
     if (!project || typeof project !== 'string') {
         throw new Error('sandbox: .agents/.airc.json is missing a valid "project" field');
     }
+    const runtimes = Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
+        ? [...sandbox.runtimes]
+        : defaults.runtimes;
+    const dockerfile = typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null;
+    if (!dockerfile) {
+        let enginesNode;
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+            enginesNode = typeof pkg.engines?.node === 'string' ? pkg.engines.node : undefined;
+        }
+        catch {
+            enginesNode = undefined;
+        }
+        for (const { runtimes: invalidRuntimes, enginesNode: range } of findRuntimeEngineMismatches(runtimes, enginesNode)) {
+            writeStderr(pc.yellow(`Warning: sandbox runtimes ${invalidRuntimes.map((runtime) => `"${runtime}"`).join(', ')} do not satisfy this project's package.json "engines.node" ("${range}").\n` +
+                '  Update "sandbox.runtimes" in .agents/.airc.json (e.g. "node22"), or relax "engines.node".\n'));
+        }
+    }
     return {
         repoRoot,
         configPath,
@@ -68,13 +88,11 @@ export function loadConfig({ platformFn = platform } = {}) {
         shareBase: hostJoin(home, '.agent-infra', 'share', project),
         dotfilesDir: hostJoin(home, '.agent-infra', 'dotfiles'),
         engine,
-        runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
-            ? [...sandbox.runtimes]
-            : defaults.runtimes,
+        runtimes,
         tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
             ? [...sandbox.tools]
             : defaults.tools,
-        dockerfile: typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null,
+        dockerfile,
         vm: {
             cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,
             memory: asPositiveNumberOrNull(sandbox.vm?.memory) ?? defaults.vm.memory,

package/dist/lib/sandbox/credentials.js

@@ -395,43 +395,62 @@ export function formatRemaining(expiresAt) {
     const minutes = totalMinutes % 60;
     return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
 }
-export function assertClaudeCredentialsAvailable(home, project, resolvedTools, extractFn = extractClaudeCredentialsBlob, writeFn = writeClaudeCredentialsFile, inspectFn = inspectClaudeKeychainStatus) {
+export function prepareClaudeCredentials(home, project, resolvedTools, extractFn = extractClaudeCredentialsBlob, writeFn = writeClaudeCredentialsFile, inspectFn = inspectClaudeKeychainStatus) {
     const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
     if (!claudeCodeEntry) {
-        return;
+        return { status: 'NOT_APPLICABLE' };
     }
     let blob = null;
     const hasCustomInspectFn = inspectFn !== inspectClaudeKeychainStatus;
     const hasCustomExtractFn = extractFn !== extractClaudeCredentialsBlob;
     if (hasCustomInspectFn || !hasCustomExtractFn) {
         const inspection = inspectFn(home);
-        if (inspection.status === 'KEYCHAIN_LOCKED') {
-            throw new Error([
-                'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
-                '',
-                buildLockedGuidance()
-            ].join('\n'));
+        switch (inspection.status) {
+            case 'OK':
+                blob = inspection.blob;
+                break;
+            case 'MISSING':
+                return { status: 'SKIPPED' };
+            case 'KEYCHAIN_LOCKED':
+                throw new Error([
+                    'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
+                    '',
+                    buildLockedGuidance()
+                ].join('\n'));
+            case 'STALE_ACCESS':
+                throw new Error([
+                    'Claude Code credentials on host are invalid or expired.',
+                    '',
+                    'The sandbox needs valid Claude Code OAuth credentials so the container can use Claude Code.',
+                    '',
+                    'To fix:',
+                    '  1. On the host, run "claude" once and complete the OAuth login flow.',
+                    '  2. Verify with "claude /status" that you see your subscription.',
+                    '  3. Re-run "ai sandbox create".'
+                ].join('\n'));
+            case 'KEYCHAIN_ERROR':
+                throw new Error([
+                    'Claude Code credentials could not be read from the host keychain.',
+                    '',
+                    inspection.detail ? `Detail: ${inspection.detail}` : 'Detail: unknown keychain error',
+                    '',
+                    'To fix:',
+                    '  1. Unlock or repair the host keychain, then re-run "ai sandbox create".',
+                    '  2. For SSH / CI, set AGENT_INFRA_CLAUDE_CREDENTIALS_FILE to an absolute path containing a valid credentials blob.'
+                ].join('\n'));
+            default: {
+                const _exhaustive = inspection;
+                throw new Error(`Unhandled Claude Code credential inspection status: ${_exhaustive.status}`);
+            }
         }
-        blob = inspection.status === 'OK' ? inspection.blob : null;
     }
     else {
         blob = extractFn(home);
-    }
-    if (!blob) {
-        throw new Error([
-            'Claude Code credentials not found on host.',
-            '',
-            'The sandbox needs your Claude Code OAuth credentials so the container can use Claude Code.',
-            '',
-            'To fix:',
-            '  1. On the host, run "claude" once and complete the OAuth login flow.',
-            '  2. Verify with "claude /status" that you see your subscription.',
-            '  3. Re-run "ai sandbox create".',
-            '',
-            'Alternatively, if you do not need Claude Code in this sandbox,',
-            'remove "claude-code" from the "sandbox.tools" array in .agents/.airc.json.'
-        ].join('\n'));
+        if (!blob) {
+            return { status: 'SKIPPED' };
+        }
     }
     writeFn(home, project, blob);
+    return { status: 'OK' };
 }
 //# sourceMappingURL=credentials.js.map

package/dist/lib/sandbox/runtime-engines.js

@@ -0,0 +1,27 @@
+import semver from 'semver';
+function nodeMajor(runtime) {
+    const match = /^node(\d+)$/.exec(runtime);
+    return match ? Number(match[1]) : null;
+}
+export function findRuntimeEngineMismatches(runtimes, enginesNode) {
+    if (!enginesNode) {
+        return [];
+    }
+    const range = semver.validRange(enginesNode);
+    if (!range) {
+        return [];
+    }
+    const nodeRuntimes = [];
+    for (const runtime of runtimes) {
+        const major = nodeMajor(runtime);
+        if (major === null) {
+            continue;
+        }
+        nodeRuntimes.push(runtime);
+        if (semver.intersects(`${major}.x`, range)) {
+            return [];
+        }
+    }
+    return nodeRuntimes.length > 0 ? [{ runtimes: nodeRuntimes, enginesNode }] : [];
+}
+//# sourceMappingURL=runtime-engines.js.map

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module"
 }

package/lib/defaults.json

@@ -5,7 +5,7 @@
   "sandbox": {
     "engine": null,
     "runtimes": [
-      "node20"
+      "node22"
     ],
     "tools": [
       "claude-code",

package/lib/sandbox/commands/create.ts

@@ -43,7 +43,7 @@ import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import {
-  assertClaudeCredentialsAvailable,
+  prepareClaudeCredentials,
   redactCommandError,
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
@@ -1100,15 +1100,17 @@ export async function create(args: string[]): Promise<void> {
   assertBranchAvailable(config.repoRoot, branch, { allowedWorktrees: worktreeCandidates });
   const tools = resolveTools(effectiveConfig);
   const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
-  // Fail fast before any filesystem/docker side effects so a missing
-  // Claude Code credential blob doesn't leave the user with a stale
-  // worktree, docker image, or temporary Dockerfile they need to manually
-  // clean up.
-  assertClaudeCredentialsAvailable(
+  // Fatal credential states still fail before filesystem/docker side effects.
+  // A genuinely missing Claude Code credential only removes Claude Code's
+  // sandbox config and credential mounts for this create run.
+  const credentialOutcome = prepareClaudeCredentials(
     effectiveConfig.home,
     effectiveConfig.project,
     resolvedTools
   );
+  const effectiveResolvedTools = credentialOutcome.status === 'SKIPPED'
+    ? resolvedTools.filter(({ tool }) => tool.id !== 'claude-code')
+    : resolvedTools;
   const container = containerName(effectiveConfig, branch);
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
   const shareCommon = shareCommonDir(effectiveConfig);
@@ -1122,6 +1124,13 @@ export async function create(args: string[]): Promise<void> {
   p.log.info(
     `Project: ${pc.bold(effectiveConfig.project)} | Branch: ${pc.bold(branch)} | Base: ${pc.bold(baseBranch || 'HEAD')}`
   );
+  if (credentialOutcome.status === 'SKIPPED') {
+    p.log.warn(
+      'Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
+      + '  Claude Code is still installed in the image but will not be authenticated.\n'
+      + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".'
+    );
+  }
 
   try {
     p.log.step('Checking container engine...');
@@ -1206,7 +1215,7 @@ export async function create(args: string[]): Promise<void> {
       {
         title: 'Preparing tool state',
         task: async () => {
-          for (const { tool, dir } of resolvedTools) {
+          for (const { tool, dir } of effectiveResolvedTools) {
             fs.mkdirSync(dir, { recursive: true });
 
             for (const { hostPath, sandboxName } of tool.hostPreSeedFiles ?? []) {
@@ -1243,7 +1252,7 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
-          return `${resolvedTools.length} tool config directories ready`;
+          return `${effectiveResolvedTools.length} tool config directories ready`;
         }
       },
       {
@@ -1283,31 +1292,32 @@ export async function create(args: string[]): Promise<void> {
               signingKey
             )
             : null;
-          const envFile = buildContainerEnvFile(resolvedTools, engine);
+          const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
           let hostShellConfig: HostShellConfig;
           try {
-            const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+            const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
             if (claudeCodeEntry) {
               ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
               ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
-              // Credential availability is asserted up-front in create() so we
-              // know the shared credentials file already exists at this point.
+              // prepareClaudeCredentials wrote the shared credentials file
+              // before this point. If credentials were missing, the
+              // claude-code entry was removed from effectiveResolvedTools.
             }
-            const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
+            const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
             if (codexEntry) {
               ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
               ensureCodexWorkspaceTrust(codexEntry.dir);
             }
-            const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
+            const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
             if (geminiEntry) {
               ensureGeminiWorkspaceTrust(geminiEntry.dir);
             }
-            const opencodeEntry = resolvedTools.find(({ tool }) => tool.id === 'opencode');
+            const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
             if (opencodeEntry) {
               // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
               ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
             }
-            const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => [
+            const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => [
               '-v',
               volumeArg(engine, dir, tool.containerMount)
             ]);
@@ -1322,7 +1332,7 @@ export async function create(args: string[]): Promise<void> {
               '-v',
               volumeArg(engine, hostPath, containerPath, ':ro')
             ]);
-            const liveMountVolumes = resolvedTools.flatMap(({ tool }) =>
+            const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) =>
               (tool.hostLiveMounts ?? [])
                 .filter(({ hostPath }) => fs.existsSync(hostPath))
                 .flatMap(({ hostPath, containerSubpath }) => [
@@ -1435,7 +1445,7 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
-          for (const { tool } of resolvedTools) {
+          for (const { tool } of effectiveResolvedTools) {
             for (const command of tool.postSetupCmds ?? []) {
               runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
             }
@@ -1477,7 +1487,7 @@ export async function create(args: string[]): Promise<void> {
 
   p.outro(pc.green('Sandbox ready'));
 
-  const toolHints = resolvedTools.map(({ tool, dir }) => {
+  const toolHints = effectiveResolvedTools.map(({ tool, dir }) => {
     const hasLiveMount = (tool.hostLiveMounts ?? []).some(({ hostPath }) => fs.existsSync(hostPath));
     const hint = hasLiveMount
       ? 'Live-mounted auth/config files stay in sync with the host.'

package/lib/sandbox/config.ts

@@ -2,12 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
+import pc from 'picocolors';
 import { validateSandboxEngine } from './engine.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
+import { findRuntimeEngineMismatches } from './runtime-engines.ts';
 
 const DEFAULTS = Object.freeze({
   engine: null,
-  runtimes: ['node20'],
+  runtimes: ['node22'],
   tools: ['claude-code', 'codex', 'gemini-cli', 'opencode'],
   dockerfile: null,
   vm: {
@@ -18,6 +20,7 @@ const DEFAULTS = Object.freeze({
 });
 
 type PlatformFn = typeof platform;
+type WriteStderr = (chunk: string) => unknown;
 
 type SandboxConfigInput = {
   engine?: string | null;
@@ -82,7 +85,10 @@ function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes:
   };
 }
 
-export function loadConfig({ platformFn = platform }: { platformFn?: PlatformFn } = {}): SandboxConfig {
+export function loadConfig({
+  platformFn = platform,
+  writeStderr = (chunk) => process.stderr.write(chunk)
+}: { platformFn?: PlatformFn; writeStderr?: WriteStderr } = {}): SandboxConfig {
   const repoRoot = detectRepoRoot();
   const home = homedir();
 
@@ -105,6 +111,30 @@ export function loadConfig({ platformFn = platform }: { platformFn?: PlatformFn
     throw new Error('sandbox: .agents/.airc.json is missing a valid "project" field');
   }
 
+  const runtimes = Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
+    ? [...sandbox.runtimes]
+    : defaults.runtimes;
+  const dockerfile = typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null;
+
+  if (!dockerfile) {
+    let enginesNode: string | undefined;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
+        engines?: { node?: unknown };
+      };
+      enginesNode = typeof pkg.engines?.node === 'string' ? pkg.engines.node : undefined;
+    } catch {
+      enginesNode = undefined;
+    }
+
+    for (const { runtimes: invalidRuntimes, enginesNode: range } of findRuntimeEngineMismatches(runtimes, enginesNode)) {
+      writeStderr(pc.yellow(
+        `Warning: sandbox runtimes ${invalidRuntimes.map((runtime) => `"${runtime}"`).join(', ')} do not satisfy this project's package.json "engines.node" ("${range}").\n` +
+        '  Update "sandbox.runtimes" in .agents/.airc.json (e.g. "node22"), or relax "engines.node".\n'
+      ));
+    }
+  }
+
   return {
     repoRoot,
     configPath,
@@ -117,13 +147,11 @@ export function loadConfig({ platformFn = platform }: { platformFn?: PlatformFn
     shareBase: hostJoin(home, '.agent-infra', 'share', project),
     dotfilesDir: hostJoin(home, '.agent-infra', 'dotfiles'),
     engine,
-    runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
-      ? [...sandbox.runtimes]
-      : defaults.runtimes,
+    runtimes,
     tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
       ? [...sandbox.tools]
       : defaults.tools,
-    dockerfile: typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null,
+    dockerfile,
     vm: {
       cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,
       memory: asPositiveNumberOrNull(sandbox.vm?.memory) ?? defaults.vm.memory,

package/lib/sandbox/credentials.ts

@@ -92,6 +92,11 @@ type ResolvedTool = {
   };
 };
 
+export type ClaudeCredentialOutcome =
+  | { status: 'OK' }
+  | { status: 'SKIPPED' }
+  | { status: 'NOT_APPLICABLE' };
+
 type CredentialPayload = {
   claudeAiOauth?: CredentialPayload;
   scopes?: unknown;
@@ -584,17 +589,17 @@ export function formatRemaining(expiresAt: unknown): string {
   return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
 }
 
-export function assertClaudeCredentialsAvailable(
+export function prepareClaudeCredentials(
   home: string,
   project: string,
   resolvedTools: ResolvedTool[],
   extractFn: (home: string) => string | null = extractClaudeCredentialsBlob,
   writeFn: (home: string, project: string, blob: string) => void = writeClaudeCredentialsFile,
   inspectFn: (home: string) => CredentialInspection = inspectClaudeKeychainStatus
-): void {
+): ClaudeCredentialOutcome {
   const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
   if (!claudeCodeEntry) {
-    return;
+    return { status: 'NOT_APPLICABLE' };
   }
 
   let blob: string | null = null;
@@ -602,33 +607,51 @@ export function assertClaudeCredentialsAvailable(
   const hasCustomExtractFn = extractFn !== extractClaudeCredentialsBlob;
   if (hasCustomInspectFn || !hasCustomExtractFn) {
     const inspection = inspectFn(home);
-    if (inspection.status === 'KEYCHAIN_LOCKED') {
-      throw new Error([
-        'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
-        '',
-        buildLockedGuidance()
-      ].join('\n'));
+    switch (inspection.status) {
+      case 'OK':
+        blob = inspection.blob;
+        break;
+      case 'MISSING':
+        return { status: 'SKIPPED' };
+      case 'KEYCHAIN_LOCKED':
+        throw new Error([
+          'Claude Code credentials are stored in the macOS keychain, but the keychain is locked.',
+          '',
+          buildLockedGuidance()
+        ].join('\n'));
+      case 'STALE_ACCESS':
+        throw new Error([
+          'Claude Code credentials on host are invalid or expired.',
+          '',
+          'The sandbox needs valid Claude Code OAuth credentials so the container can use Claude Code.',
+          '',
+          'To fix:',
+          '  1. On the host, run "claude" once and complete the OAuth login flow.',
+          '  2. Verify with "claude /status" that you see your subscription.',
+          '  3. Re-run "ai sandbox create".'
+        ].join('\n'));
+      case 'KEYCHAIN_ERROR':
+        throw new Error([
+          'Claude Code credentials could not be read from the host keychain.',
+          '',
+          inspection.detail ? `Detail: ${inspection.detail}` : 'Detail: unknown keychain error',
+          '',
+          'To fix:',
+          '  1. Unlock or repair the host keychain, then re-run "ai sandbox create".',
+          '  2. For SSH / CI, set AGENT_INFRA_CLAUDE_CREDENTIALS_FILE to an absolute path containing a valid credentials blob.'
+        ].join('\n'));
+      default: {
+        const _exhaustive: never = inspection;
+        throw new Error(`Unhandled Claude Code credential inspection status: ${(_exhaustive as { status: string }).status}`);
+      }
     }
-    blob = inspection.status === 'OK' ? inspection.blob : null;
   } else {
     blob = extractFn(home);
-  }
-
-  if (!blob) {
-    throw new Error([
-      'Claude Code credentials not found on host.',
-      '',
-      'The sandbox needs your Claude Code OAuth credentials so the container can use Claude Code.',
-      '',
-      'To fix:',
-      '  1. On the host, run "claude" once and complete the OAuth login flow.',
-      '  2. Verify with "claude /status" that you see your subscription.',
-      '  3. Re-run "ai sandbox create".',
-      '',
-      'Alternatively, if you do not need Claude Code in this sandbox,',
-      'remove "claude-code" from the "sandbox.tools" array in .agents/.airc.json.'
-    ].join('\n'));
+    if (!blob) {
+      return { status: 'SKIPPED' };
+    }
   }
 
   writeFn(home, project, blob);
+  return { status: 'OK' };
 }

package/lib/sandbox/runtime-engines.ts

@@ -0,0 +1,39 @@
+import semver from 'semver';
+
+export type RuntimeEngineMismatch = {
+  runtimes: string[];
+  enginesNode: string;
+};
+
+function nodeMajor(runtime: string): number | null {
+  const match = /^node(\d+)$/.exec(runtime);
+  return match ? Number(match[1]) : null;
+}
+
+export function findRuntimeEngineMismatches(
+  runtimes: string[],
+  enginesNode: string | undefined
+): RuntimeEngineMismatch[] {
+  if (!enginesNode) {
+    return [];
+  }
+
+  const range = semver.validRange(enginesNode);
+  if (!range) {
+    return [];
+  }
+
+  const nodeRuntimes: string[] = [];
+  for (const runtime of runtimes) {
+    const major = nodeMajor(runtime);
+    if (major === null) {
+      continue;
+    }
+    nodeRuntimes.push(runtime);
+    if (semver.intersects(`${major}.x`, range)) {
+      return [];
+    }
+  }
+
+  return nodeRuntimes.length > 0 ? [{ runtimes: nodeRuntimes, enginesNode }] : [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
     "@clack/prompts": "1.4.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
+    "semver": "^7.8.1",
     "smol-toml": "^1.6.1"
   },
   "scripts": {
@@ -61,6 +62,7 @@
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^25.9.1",
+    "@types/semver": "^7.7.1",
     "typescript": "~6.0"
   }
 }

package/templates/.agents/rules/create-issue.github.en.md

@@ -149,13 +149,13 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 Failure is non-blocking.
 
-### 6.5 Set Issue Fields (Optional)
+### 7. Set Issue Fields (Optional)
 
 If `has_push=true`, read `.agents/rules/issue-fields.md` and follow Flow A to write any applicable non-empty `priority`, `effort`, `start_date`, and `target_date` values from `task.md`.
 
 Field write failures are non-blocking.
 
-### 7. Write Back task.md
+### 8. Write Back task.md
 
 Update task.md:
 
@@ -164,7 +164,7 @@ Update task.md:
 
 > Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Task Created`), written by the caller SKILL step 3.
 
-### 8. Return the Result
+### 9. Return the Result
 
 Hand the following back to the caller `create-task`:
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -149,13 +149,13 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 设置失败不阻断流程。
 
-### 6.5 设置 Issue 字段（可选）
+### 7. 设置 Issue 字段（可选）
 
 如果 `has_push=true`，读取 `.agents/rules/issue-fields.md`，按流程 A 写入 `task.md` 中适用且非空的 `priority`、`effort`、`start_date` 和 `target_date`。
 
 字段写入失败不阻断流程。
 
-### 7. 回写 task.md
+### 8. 回写 task.md
 
 更新 task.md：
 
@@ -164,7 +164,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 > 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Task Created`），由调用方 SKILL 步骤 3 写入。
 
-### 8. 返回结果
+### 9. 返回结果
 
 把以下信息回传给调用方 `create-task`：
 

package/templates/.agents/rules/release-commands.github.en.md

@@ -1,6 +1,6 @@
 # Release Platform Commands
 
-Read this file before loading release history, querying merged PRs, or creating a draft release.
+Read this file before loading release history, querying merged PRs, or publishing the Release notes.
 
 ## Query Releases
 
@@ -37,10 +37,16 @@ gh issue view {issue-number} --json number,title,labels,url,author
 
 Map GitHub no-reply emails with this rule: if `Name <email>` contains an email matching `(\d+\+)?(\S+?)@users\.noreply\.github\.com`, use the second capture group lowercased as the login. This covers both `{id}+{login}@users.noreply.github.com` and `{login}@users.noreply.github.com`.
 
-## Create a Draft Release
+## Publish the Release Notes
+
+The GitHub Release for `v{version}` is created and published automatically by the release workflow so Homebrew bottles have a stable upload target. This command writes the curated notes onto that existing Release, falling back to creating it if it does not exist yet.
 
 ```bash
-gh release create "v{version}" --draft --title "v{version}" --notes-file "{notes-file}"
+if gh release view "v{version}" >/dev/null 2>&1; then
+  gh release edit "v{version}" --notes-file "{notes-file}"
+else
+  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
+fi
 ```
 
 If commands fail, stop or escalate according to the calling skill.

package/templates/.agents/rules/release-commands.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Release 平台命令
 
-在读取历史 release、查询已合并 PR，或创建 draft release 前先读取本文件。
+在读取历史 release、查询已合并 PR，或发布 Release notes 前先读取本文件。
 
 ## Release 查询
 
@@ -37,10 +37,16 @@ gh issue view {issue-number} --json number,title,labels,url,author
 
 GitHub no-reply 邮箱映射规则：如果 `Name <email>` 中的 email 匹配 `(\d+\+)?(\S+?)@users\.noreply\.github\.com`，使用第二个捕获组的小写形式作为 login。该规则同时覆盖 `{id}+{login}@users.noreply.github.com` 和 `{login}@users.noreply.github.com`。
 
-## 创建 Draft Release
+## 发布 Release notes
+
+`v{version}` 的 GitHub Release 由 release 工作流自动创建并发布，为 Homebrew bottle 提供稳定的上传落点。本命令把精修后的 notes 写到这个已存在的 Release 上；若 Release 尚不存在则兜底创建。
 
 ```bash
-gh release create "v{version}" --draft --title "v{version}" --notes-file "{notes-file}"
+if gh release view "v{version}" >/dev/null 2>&1; then
+  gh release edit "v{version}" --notes-file "{notes-file}"
+else
+  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
+fi
 ```
 
 失败时按调用方规则停止或提示人工介入。

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -49,6 +49,8 @@ If `task.md` contains these source fields, also read the corresponding source in
 
 ### 4. Perform Requirements Analysis
 
+Before analysis begins: if `start_date` in the frontmatter is empty, write today's date immediately (command: `date +%F`, format `YYYY-MM-DD`); keep any existing value. Before writing, read `.agents/rules/version-stamp.md` and refresh `updated_at` / `agent_infra_version` at the same time.
+
 Follow the `analysis` step in `.agents/workflows/feature-development.yaml`:
 
 **Required tasks** (analysis only, no business code changes):
@@ -126,6 +128,7 @@ If task.md contains a valid `issue_number`, perform these sync actions (skip and
 - Set `status: pending-design-work` by following issue-sync.md
 - Create or update the task comment marker defined in `.agents/rules/issue-sync.md` (follow the task.md comment sync rule in issue-sync.md)
 - Publish the `{analysis-artifact}` comment
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 7. Verification Gate
 

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -49,6 +49,8 @@ description: "分析任务并输出需求分析文档"
 
 ### 4. 执行需求分析
 
+开始分析前：若 frontmatter 的 `start_date` 为空，立即写入当日日期（命令 `date +%F`，格式 `YYYY-MM-DD`）；已有值则保留。写入前先读取 `.agents/rules/version-stamp.md`，并同步刷新 `updated_at` / `agent_infra_version`。
+
 遵循 `.agents/workflows/feature-development.yaml` 中的 `analysis` 步骤：
 
 **必要任务**（仅分析，不编写业务代码）：
@@ -126,6 +128,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 按 issue-sync.md 设置 `status: pending-design-work`
 - 创建或更新 `.agents/rules/issue-sync.md` 中定义的 task 评论标记（按 issue-sync.md 的 task.md 评论同步规则）
 - 发布 `{analysis-artifact}` 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 7. 完成校验
 

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -98,6 +98,7 @@ If a valid `issue_number` exists:
 - Backfill checked `## Requirements` items to the Issue body by following the requirements-checkbox sync steps in issue-sync.md
 - Do not set any `status:` label — status labels are automatically cleared when the Issue is closed
 - Finally create or update the summary comment marked with the summary marker defined in `.agents/rules/issue-sync.md`
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 7. Verification Gate
 

package/templates/.agents/skills/complete-task/SKILL.zh-CN.md

@@ -98,6 +98,7 @@ ls .agents/workspace/completed/{task-id}/task.md
 - 按 issue-sync.md 的需求复选框同步步骤，兜底同步 `## 需求` 中已勾选的条目到 Issue body
 - 不要设置 `status:` label — Issue 关闭后 status label 会被自动清除
 - 最后创建或更新 `.agents/rules/issue-sync.md` 中定义的 summary 评论标记对应的 summary 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 7. 完成校验
 

package/templates/.agents/skills/create-pr/config/verify.json

@@ -24,6 +24,7 @@
       "verify_in_labels_match_pr": true,
       "verify_pr_type_label": true,
       "verify_pr_assignee": true,
+      "verify_issue_fields": true,
       "verify_milestone": true,
       "expected_pr_comment_marker_key": "prSummary"
     }

package/templates/.agents/skills/create-release-note/SKILL.en.md

@@ -156,31 +156,28 @@ Show the generated release notes to the user.
 
 Ask:
 1. Need any adjustments?
-2. Create a draft release?
+2. Write these notes onto the Release for this version?
 
-### 9. Create Draft Release (If Confirmed)
+### 9. Publish the Release Notes (If Confirmed)
 
-Create the draft release by following `.agents/rules/release-commands.md`.
+Write the notes by following the "Publish the Release Notes" command in `.agents/rules/release-commands.md` (it updates the Release already created and published by the release workflow, falling back to creating it if missing).
 
 Output:
 ```
-Draft Release created.
+Release notes updated.
 
-- URL: {draft-release-url}
+- URL: {release-url}
 - Version: v{version}
-- Status: Draft
+- Status: Published
 
-Please review and publish on the platform:
-1. Open the URL above
-2. Review the release notes
-3. Click "Publish release"
+The notes have been written to the Release. Edit further at the URL above if needed.
 ```
 
 ## Notes
 
 1. **Requires the platform CLI**: Must have the platform CLI installed and authenticated
 2. **Tags must exist**: Run the release skill first to create tags
-3. **Draft mode**: Creates a draft - won't auto-publish
+3. **Release auto-published**: the `v{version}` Release is created and published by the release workflow (the upload target for Homebrew bottles); this skill writes/refreshes the notes on that Release
 4. **Classification accuracy**: Auto-classification is based on title/scope/files; complex PRs may need manual adjustment
 
 ## Error Handling

package/templates/.agents/skills/create-release-note/SKILL.zh-CN.md

@@ -156,31 +156,28 @@ git log v<prev-version>..v<version> \
 
 询问：
 1. 需要调整吗？
-2. 是否创建 draft release？
+2. 是否把 notes 写入该版本的 Release？
 
-### 9. 创建 Draft Release（如确认）
+### 9. 发布 Release notes（如确认）
 
-按 `.agents/rules/release-commands.md` 的 Draft Release 创建命令执行。
+按 `.agents/rules/release-commands.md` 的「发布 Release notes」命令执行（写入已由 release 工作流自动创建/发布的 Release；不存在时兜底创建）。
 
 输出：
 ```
-Draft Release created.
+Release notes 已更新。
 
-- URL: {draft-release-url}
+- URL: {release-url}
 - Version: v{version}
-- Status: Draft
+- Status: Published
 
-Please review and publish on the platform:
-1. Open the URL above
-2. Review the release notes
-3. Click "Publish release"
+发布说明已写入该 Release。如需进一步调整，可在上面的 URL 直接编辑。
 ```
 
 ## 注意事项
 
 1. **需要 the platform CLI**：必须安装并认证 the platform CLI
 2. **标签必须存在**：先执行 release 技能创建标签
-3. **草稿模式**：创建草稿 —— 不会自动发布
+3. **Release 已自动发布**：`v{version}` 的 Release 由 release 工作流自动创建并发布（给 Homebrew bottle 提供上传落点）；本技能往该 Release 写入/刷新 notes
 4. **分类准确性**：自动分类基于标题/scope/文件；复杂的 PR 可能需要手动调整
 
 ## 错误处理

package/templates/.agents/skills/create-task/SKILL.en.md

@@ -78,8 +78,8 @@ created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
 created_by: human
-priority:                  # optional; Urgent | High | Medium | Low
-effort:                    # optional; High | Medium | Low
+priority:                  # required; inferred by the AI from the title/description; Urgent | High | Medium | Low
+effort:                    # required; inferred by the AI from the title/description; High | Medium | Low
 start_date:                # optional; YYYY-MM-DD
 target_date:               # optional; YYYY-MM-DD
 current_step: requirement-analysis
@@ -87,7 +87,7 @@ assigned_to: {current AI agent}
 ```
 
 Note: `created_by` is `human` because the task comes from the user's description.
-Optional Issue field metadata may be left empty at task creation; do not invent dates.
+priority / effort are required: the AI infers them from the task title and description (candidates in `.agents/rules/issue-fields.md`; normalize localized input). Leave start_date / target_date empty at creation - analyze-task / plan-task fill them later; do not invent dates.
 
 ### 3. Update Task Status
 

package/templates/.agents/skills/create-task/SKILL.zh-CN.md

@@ -78,8 +78,8 @@ created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
 created_by: human
-priority:                  # 可选；Urgent | High | Medium | Low
-effort:                    # 可选；High | Medium | Low
+priority:                  # 必填；由 AI 从标题/描述推断；Urgent | High | Medium | Low
+effort:                    # 必填；由 AI 从标题/描述推断；High | Medium | Low
 start_date:                # 可选；YYYY-MM-DD
 target_date:               # 可选；YYYY-MM-DD
 current_step: requirement-analysis
@@ -87,7 +87,7 @@ assigned_to: {当前 AI 代理}
 ```
 
 注意：`created_by` 为 `human`，因为任务来源于用户的描述。
-可选 Issue 字段元数据在创建任务时可留空；不要臆测日期。
+priority / effort 必填：由 AI 从任务标题与描述推断后填入（候选值见 `.agents/rules/issue-fields.md`；中文输入按本地化映射规范化）。start_date / target_date 创建时保持留空，由 analyze-task / plan-task 阶段填入；不要臆测日期。
 
 ### 3. 更新任务状态
 

package/templates/.agents/skills/plan-task/SKILL.en.md

@@ -91,6 +91,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `assigned_to`: {current AI agent}
 - `updated_at`: {current time}
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
+- If `target_date` is empty, write an estimated completion date based on the effort estimate (`YYYY-MM-DD`); leave it empty without blocking when no reasonable estimate exists; keep any existing value
 - Record the plan artifact for this round: `{plan-artifact}` (Round `{plan-round}`)
 - If the task template contains a `## Design` section, update it to link to `{plan-artifact}`
 - Mark technical-design as complete in workflow progress and include the actual round when the task template supports it
@@ -104,6 +105,7 @@ If task.md contains a valid `issue_number`, perform these sync actions (skip and
 - Set `status: pending-design-work` by following issue-sync.md
 - Create or update the task comment marker defined in `.agents/rules/issue-sync.md` (follow the task.md comment sync rule in issue-sync.md)
 - Publish the `{plan-artifact}` comment
+- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
 
 ### 8. Verification Gate
 

package/templates/.agents/skills/plan-task/SKILL.zh-CN.md

@@ -91,6 +91,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `assigned_to`：{当前 AI 代理}
 - `updated_at`：{当前时间}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
+- 若 `target_date` 为空，基于工作量评估写入预估完成日（`YYYY-MM-DD`）；无法合理预估时保持留空、不阻塞；已有值则保留
 - 记录本轮方案产物：`{plan-artifact}`（Round `{plan-round}`）
 - 如任务模板包含 `## 设计` 段落，更新为指向 `{plan-artifact}` 的链接
 - 在工作流进度中标记 technical-design 为已完成，并注明实际轮次（如果任务模板支持）
@@ -104,6 +105,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 按 issue-sync.md 设置 `status: pending-design-work`
 - 创建或更新 `.agents/rules/issue-sync.md` 中定义的 task 评论标记（按 issue-sync.md 的 task.md 评论同步规则）
 - 发布 `{plan-artifact}` 评论
+- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
 
 ### 8. 完成校验
 

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -26,7 +26,7 @@ const DEFAULTS = {
   "sandbox": {
     "engine": null,
     "runtimes": [
-      "node20"
+      "node22"
     ],
     "tools": [
       "claude-code",