@fitlab-ai/agent-infra 0.6.3 → 0.6.5

package/lib/sandbox/commands/enter.ts

@@ -12,6 +12,7 @@ import { runInteractiveEngine, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.ts';
+import { detectHostTimezone } from '../host-timezone.ts';
 
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
@@ -39,6 +40,42 @@ export function terminalEnvFlags(env: NodeJS.ProcessEnv = process.env): string[]
   return flags;
 }
 
+export function hostTimezoneEnvFlags(detect = detectHostTimezone): string[] {
+  const tz = detect();
+  return tz ? ['-e', `TZ=${tz}`] : [];
+}
+
+export function clipboardBridgeDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = (env.AI_SANDBOX_NO_CLIPBOARD_BRIDGE ?? '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+export function runSandboxInteractive(params: {
+  engine: string;
+  dockerArgs: string[];
+  container: string;
+  home: string;
+  env?: NodeJS.ProcessEnv;
+  runBridge?: typeof runInteractiveWithClipboardBridge;
+  runInteractive?: typeof runInteractiveEngine;
+}): number | Promise<number> {
+  const {
+    engine,
+    dockerArgs,
+    container,
+    home,
+    env = process.env,
+    runBridge = runInteractiveWithClipboardBridge,
+    runInteractive = runInteractiveEngine
+  } = params;
+
+  if (clipboardBridgeDisabled(env)) {
+    return runInteractive(engine, 'docker', dockerArgs);
+  }
+
+  return runBridge({ engine, dockerArgs, container, home });
+}
+
 export function formatCredentialSyncStatus(
   result: ReturnType<typeof reconcileClaudeCredentials>,
   isTTY = process.stderr.isTTY
@@ -101,7 +138,7 @@ export async function enter(args: string[]): Promise<number> {
     }
   }
 
-  const envFlags = terminalEnvFlags();
+  const envFlags = [...terminalEnvFlags(), ...hostTimezoneEnvFlags()];
   if (cmd.length === 0) {
     try {
       materializeDotfiles(config.dotfilesDir, dotfilesCacheDir(config.home, config.project));
@@ -109,9 +146,10 @@ export async function enter(args: string[]): Promise<number> {
       process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
     }
 
-    return runInteractiveWithClipboardBridge({
+    const dockerArgs = ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH];
+    return runSandboxInteractive({
       engine,
-      dockerArgs: ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH],
+      dockerArgs,
       container,
       home: config.home
     });

package/lib/sandbox/commands/rebuild.ts

@@ -13,7 +13,7 @@ import type { SandboxTool } from '../tools.ts';
 import { toEnginePath } from '../engines/wsl2-paths.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 
-const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
+const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
 
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
@@ -38,12 +38,14 @@ export function buildArgs(
     engine,
     runFn = runEngine,
     runSafeFn = runSafeEngine,
-    env = process.env
+    env = process.env,
+    refresh = false
   }: {
     engine?: string;
     runFn?: EngineRunFn;
     runSafeFn?: EngineRunSafeFn;
     env?: NodeJS.ProcessEnv;
+    refresh?: boolean;
   } = {}
 ): string[] {
   const selectedEngine = engine ?? detectEngine(config);
@@ -54,7 +56,7 @@ export function buildArgs(
     env
   });
 
-  return [
+  const args = [
     'build',
     '-t',
     config.imageName,
@@ -72,6 +74,12 @@ export function buildArgs(
     toEnginePath(selectedEngine, dockerfilePath),
     toEnginePath(selectedEngine, config.repoRoot)
   ];
+
+  if (refresh) {
+    args.splice(1, 0, '--no-cache', '--pull');
+  }
+
+  return args;
 }
 
 function removeImageIfPresent(imageName: string, engine: string): void {
@@ -86,6 +94,7 @@ export async function rebuild(args: string[]): Promise<void> {
     allowPositionals: true,
     strict: true,
     options: {
+      refresh: { type: 'boolean' },
       quiet: { type: 'boolean', short: 'q' },
       help: { type: 'boolean', short: 'h' }
     }
@@ -101,6 +110,7 @@ export async function rebuild(args: string[]): Promise<void> {
   const preparedDockerfile = prepareDockerfile(config);
   const imageSignature = buildSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
+  const refresh = values.refresh ?? false;
   const engine = detectEngine(config);
 
   await ensureDocker(config, undefined);
@@ -113,7 +123,7 @@ export async function rebuild(args: string[]): Promise<void> {
       removeImageIfPresent(config.imageName, engine);
       spinner.stop('Old image removed');
       spinner.start('Building image...');
-      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }), {
+      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
@@ -124,7 +134,7 @@ export async function rebuild(args: string[]): Promise<void> {
       runVerboseEngine(
         engine,
         'docker',
-        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }),
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }),
         { cwd: config.repoRoot }
       );
       p.log.success(pc.green('Sandbox image rebuilt'));

package/lib/sandbox/host-timezone.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import os from 'node:os';
+
+export type DetectHostTimezoneOptions = {
+  platform?: NodeJS.Platform;
+  readlink?: (targetPath: string) => string;
+  env?: NodeJS.ProcessEnv;
+};
+
+const ZONEINFO_MARK = '/zoneinfo/';
+const IANA_ZONE_RE = /^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/;
+
+function safeTimezone(value: string | undefined): string | null {
+  if (!value || !IANA_ZONE_RE.test(value)) {
+    return null;
+  }
+  return value;
+}
+
+export function detectHostTimezone(options: DetectHostTimezoneOptions = {}): string | null {
+  const platform = options.platform ?? os.platform();
+  const env = options.env ?? process.env;
+  if (env.TZ) {
+    return safeTimezone(env.TZ);
+  }
+
+  if (platform !== 'darwin' && platform !== 'linux') {
+    return null;
+  }
+
+  const readlink = options.readlink ?? fs.readlinkSync;
+  try {
+    const target = readlink('/etc/localtime');
+    const idx = target.indexOf(ZONEINFO_MARK);
+    if (idx < 0) {
+      return null;
+    }
+    return safeTimezone(target.slice(idx + ZONEINFO_MARK.length));
+  } catch {
+    return null;
+  }
+}

package/lib/sandbox/index.ts

@@ -3,12 +3,13 @@ const USAGE = `Usage: ai sandbox <command> [options]
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
   exec <branch> [cmd...]       Enter sandbox or run a command
-  refresh                      Sync host Claude Code credentials to all sandbox copies
   ls                           List sandboxes for the current project
-  rm <branch> [--all]          Remove a sandbox or all sandboxes
   prune [--dry-run]            Remove orphaned per-branch state dirs
+  rebuild [--quiet] [--refresh]
+                               Rebuild the sandbox image (--refresh pulls base + tools)
+  refresh                      Sync host Claude Code credentials to all sandbox copies
+  rm <branch> [--all]          Remove a sandbox or all sandboxes
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
-  rebuild [--quiet]            Rebuild the sandbox image
 
 Run 'ai sandbox <command> --help' for details.`;
 

package/lib/sandbox/readme-scaffold.ts

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { shareBranchDir, shareCommonDir } from './constants.ts';
+
+type ScaffoldResult = { created: boolean; path: string };
+type WriteStderr = (chunk: string) => void;
+type ScaffoldFs = Pick<typeof fs, 'mkdirSync' | 'writeFileSync'>;
+type ScaffoldOptions = {
+  writeStderr?: WriteStderr;
+  fsModule?: ScaffoldFs;
+};
+
+const DOTFILES_README = `# User-level dotfiles channel
+
+This directory is mounted **read-only** into every sandbox container at
+\`/dotfiles\`. On entry, \`sandbox-dotfiles-link\` mirrors every file here as a
+symlink under \`$HOME\` (e.g. \`.tmux.conf\` -> \`/home/devuser/.tmux.conf\`),
+overriding image defaults so your editor, shell, and tool preferences follow
+you across \`ai sandbox destroy + create\`.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#user-level-dotfiles-channel
+
+Common usage - drop files or symlinks here:
+
+\`\`\`sh
+# Real files
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# Symlinks to live host paths
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> Do **not** put secrets here. Use the dedicated SSH / credential mounts.
+
+If you delete this file, the next \`ai sandbox create\` will re-create it
+verbatim. To stop seeing it, edit or empty the file in place - the scaffold
+only writes \`README.md\` when it is missing, never when it already exists.
+
+---
+
+# 用户级 dotfiles 通道
+
+该目录被以**只读**方式挂载到每个 sandbox 容器的 \`/dotfiles\`。容器启动时，
+\`sandbox-dotfiles-link\` 会把这里的每个文件 \`ln -sfn\` 到 \`$HOME\` 对应路径
+（例如 \`.tmux.conf -> /home/devuser/.tmux.conf\`），覆盖镜像默认值，让你的编辑器、
+shell、工具偏好跨 \`ai sandbox destroy + create\` 持久存在。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#用户级-dotfiles-通道
+
+常见用法：把文件或符号链接放进来：
+
+\`\`\`sh
+# 直接放文件
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# 用符号链接指向 host 实际文件
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> **不要**在此放任何凭证。SSH / 凭证请使用专用挂载通道。
+
+如果你删除该文件，下一次 \`ai sandbox create\` 会原样重新生成。如果你不想再
+看到它，**就地编辑或清空内容**即可：scaffold 仅在 \`README.md\` **缺失**时
+写入，文件存在（哪怕被清空）就不会被重写。
+`;
+
+const SHARE_COMMON_README = `# /share/common - host <-> sandbox shared scratch (cross-branch)
+
+This directory is mounted **read-write** into every sandbox container of this
+project at \`/share/common\`, regardless of branch. Drop files here to share
+between host and any sandbox without polluting the git worktree.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/common - 宿主 <-> sandbox 共享暂存（跨分支）
+
+该目录被以**读写**方式挂载到本项目所有 sandbox 容器的 \`/share/common\`，
+跨分支可见。可用来在宿主和任意 sandbox 之间传文件，无需弄脏 git worktree。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+
+const SHARE_BRANCH_README = `# /share/branch - host <-> sandbox shared scratch (branch-exclusive)
+
+This directory is mounted **read-write** into the sandbox container of this
+project's current branch at \`/share/branch\`. Files here are exclusive to this
+branch's sandbox and do not leak across branches.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/branch - 宿主 <-> sandbox 共享暂存（分支独占）
+
+该目录被以**读写**方式挂载到本项目当前分支 sandbox 容器的 \`/share/branch\`，
+仅当前分支可见，不会跨分支泄漏。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error';
+}
+
+function errorCode(error: unknown): string {
+  return typeof error === 'object' && error !== null && 'code' in error
+    ? String(error.code)
+    : '';
+}
+
+function ensureFile(target: string, content: string, options: ScaffoldOptions): ScaffoldResult {
+  const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+  const fsModule = options.fsModule ?? fs;
+  const result: ScaffoldResult = { created: false, path: target };
+
+  try {
+    fsModule.mkdirSync(path.dirname(target), { recursive: true });
+  } catch (error) {
+    writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+    return result;
+  }
+
+  try {
+    fsModule.writeFileSync(target, content, { encoding: 'utf8', flag: 'wx' });
+    result.created = true;
+  } catch (error) {
+    if (errorCode(error) === 'EEXIST') {
+      return result;
+    }
+    writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+  }
+
+  return result;
+}
+
+export function ensureDotfilesReadme(dotfilesDir: string, options: ScaffoldOptions = {}): ScaffoldResult {
+  return ensureFile(path.join(dotfilesDir, 'README.md'), DOTFILES_README, options);
+}
+
+export function ensureShareCommonReadme(
+  config: { shareBase: string },
+  options: ScaffoldOptions = {}
+): ScaffoldResult {
+  return ensureFile(path.join(shareCommonDir(config), 'README.md'), SHARE_COMMON_README, options);
+}
+
+export function ensureShareBranchReadme(
+  config: { shareBase: string },
+  branch: string,
+  options: ScaffoldOptions = {}
+): ScaffoldResult {
+  return ensureFile(path.join(shareBranchDir(config, branch), 'README.md'), SHARE_BRANCH_README, options);
+}
+
+export function ensureSandboxDiscoveryReadmes(
+  config: { shareBase: string; dotfilesDir: string },
+  branch: string,
+  options: ScaffoldOptions = {}
+): ScaffoldResult[] {
+  return [
+    ensureDotfilesReadme(config.dotfilesDir, options),
+    ensureShareCommonReadme(config, options),
+    ensureShareBranchReadme(config, branch, options)
+  ];
+}

package/lib/sandbox/runtimes/ai-tools.dockerfile

@@ -1,4 +1,6 @@
 USER devuser
+ENV DISABLE_UPDATES=1
+ENV OPENCODE_DISABLE_AUTOUPDATE=1
 ENV NPM_CONFIG_PREFIX=/home/devuser/.npm-global
 ENV PATH="/home/devuser/.npm-global/bin:${PATH}"
 

package/lib/sandbox/runtimes/base.dockerfile

@@ -1,9 +1,8 @@
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 LABEL description="AI coding sandbox"
 
 ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Asia/Shanghai
 
 ARG HOST_UID=1000
 ARG HOST_GID=1000
@@ -22,14 +21,14 @@ RUN apt-get update && apt-get install -y \
     build-essential ca-certificates gnupg lsb-release \
     libevent-core-2.1-7 libncursesw6 libtinfo6 \
     pkg-config bison libevent-dev libncurses-dev \
-    locales \
+    locales tzdata \
     && locale-gen en_US.UTF-8 \
     && (curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
         | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg) \
     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
         > /etc/apt/sources.list.d/github-cli.list \
     && apt-get update && apt-get install -y gh \
-    && TMUX_VERSION=3.6a \
+    && TMUX_VERSION=3.6b \
     && wget -qO /tmp/tmux.tar.gz \
         "https://github.com/tmux/tmux/releases/download/${TMUX_VERSION}/tmux-${TMUX_VERSION}.tar.gz" \
     && tar xzf /tmp/tmux.tar.gz -C /tmp \
@@ -45,13 +44,13 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # Enable extended keys in CSI u format so Shift+Enter and other modified
-# keys are forwarded through tmux. Preserve terminal-detection variables
+# keys are forwarded through tmux. Preserve terminal/timezone variables
 # injected at `docker exec` time when new tmux sessions are created.
 RUN printf '%s\n' \
       'set -g extended-keys always' \
       'set -g extended-keys-format csi-u' \
       "set -as terminal-features 'xterm*:extkeys'" \
-      "set -ga update-environment 'TERM_PROGRAM TERM_PROGRAM_VERSION LC_TERMINAL LC_TERMINAL_VERSION'" \
+      "set -ga update-environment 'TERM_PROGRAM TERM_PROGRAM_VERSION LC_TERMINAL LC_TERMINAL_VERSION TZ'" \
       'set -g mouse on' \
       'set -g status-interval 1' \
       'set -g status-right-length 80' \
@@ -127,7 +126,7 @@ find . -type f -print | while IFS= read -r rel; do
     .config/opencode|.config/opencode/*|\
     .local/share/opencode|.local/share/opencode/*|\
     .host-shell-config|.host-shell-config/*|\
-    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases)
+    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases|README.md)
       continue ;;
   esac
 
@@ -146,7 +145,7 @@ RUN cat > /usr/local/bin/sandbox-tmux-entry <<'SCRIPT' && chmod +x /usr/local/bi
 #!/bin/sh
 set -eu
 
-sandbox-dotfiles-link >/dev/null || true
+sandbox-dotfiles-link >/dev/null 2>&1 || true
 
 SESSION=work
 
@@ -154,20 +153,26 @@ if ! command -v tmux >/dev/null 2>&1; then
   exec bash
 fi
 
-if ! tmux has-session -t "$SESSION" 2>/dev/null; then
-  exec tmux new-session -s "$SESSION"
-fi
-
-tmux list-sessions -F '#{session_name} #{session_attached}' 2>/dev/null | \
-  while read -r name attached; do
-    [ "$name" = "$SESSION" ] && continue
+# Drop stale grouped sessions left by older entry-script versions (the windows
+# live on $SESSION, so killing the group members only removes view entries).
+tmux list-sessions -F '#{session_name}' 2>/dev/null | while IFS= read -r name; do
     case "$name" in
-      ''|*[!0-9]*) continue ;;
+      "$SESSION"-*) tmux kill-session -t "$name" 2>/dev/null || true ;;
     esac
-    [ "$attached" = "0" ] && tmux kill-session -t "$name" 2>/dev/null || true
-  done
+done
+
+# Reuse the single $SESSION; -d detaches any pre-existing client so the new
+# one becomes the sole owner of window-size, eliminating size races.
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  # Push the per-exec TZ into the running session's env so new
+  # windows/panes pick up the host timezone without a session kill.
+  if [ -n "${TZ:-}" ]; then
+    tmux set-environment -t "$SESSION" TZ "$TZ" 2>/dev/null || true
+  fi
+  exec tmux attach -d -t "$SESSION"
+fi
 
-exec tmux new-session -t "$SESSION"
+exec tmux new-session -s "$SESSION"
 SCRIPT
 
 ENV LANG=en_US.UTF-8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.4.0",
+    "@clack/prompts": "1.5.1",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
@@ -54,11 +54,11 @@
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
-    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts",
-    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts tests/cli/cli.test.ts tests/cli/merge.test.ts tests/cli/sandbox.test.ts tests/core/custom-skills.test.ts tests/core/custom-tuis.test.ts tests/core/demo-regen.test.ts tests/scripts/find-existing-task.test.ts tests/scripts/platform-adapter-defaults.test.ts",
-    "test": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts",
-    "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage --test-coverage-exclude='tests/**' --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts",
-    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts"
+    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
+    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
+    "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
+    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",

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

@@ -115,7 +115,25 @@ When applying the Issue Type, follow the "Set Issue Type" command in `.agents/ru
 
 #### milestone
 
-Infer per `.agents/rules/milestone-inference.md` § "Stage 1: `create-task` (when the platform rule creates the Issue)". When the inference is empty or the repo lacks a matching milestone, omit the milestone.
+**Mandatory; do not skip.** This section expands `.agents/rules/milestone-inference.md` Phase 1 in place and keeps the same semantics; do not treat it as optional inference.
+
+Select the milestone using these numbered steps, with priority strictly aligned to Phase 1:
+
+1. If `has_triage=false`: omit `--milestone` immediately and skip this section.
+2. List all open milestones in the repository:
+   ```bash
+   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
+     --jq '.[].title'
+   ```
+3. If task.md frontmatter explicitly provides a `milestone` field and that value appears in the step 2 list: use that value directly as `{milestone-arg}` and skip steps 4 / 5.
+4. Filter the step 2 result with `^[0-9]+\.[0-9]+\.x$`.
+   - Non-empty: sort by major and minor numerically, then choose the smallest release line as `{milestone-arg}`.
+5. If step 4 has no candidates: fall back to `General Backlog`.
+   - `General Backlog` exists in the step 2 result: use that milestone.
+   - `General Backlog` does not exist: omit `--milestone` only in this case.
+6. If the step 2 `gh api` call fails (network / authentication error): handle it as "no candidates" and continue to step 5.
+
+When a milestone is selected, pass the release line (or `General Backlog` or the explicit task.md value) as `{milestone-arg}` to the `gh issue create` command in step 5; keep the expansion rule at the end of §5 unchanged.
 
 ### 5. Call the GitHub CLI to Create the Issue
 

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

@@ -115,7 +115,25 @@ Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板
 
 #### milestone
 
-按 `.agents/rules/milestone-inference.md` 的 "阶段 1：`create-task`（平台规则创建 Issue 时）" 规则推断；推断结果为空或仓库无对应 milestone 时省略。
+**必须执行，不得跳过**。本节是 `.agents/rules/milestone-inference.md` 阶段 1 的就地展开，语义与之对齐；不要把它当成"可选推断"。
+
+按以下编号步骤选取 milestone（优先级与阶段 1 严格一致）：
+
+1. 如果 `has_triage=false`：直接省略 `--milestone`，跳过本节。
+2. 列出仓库 open 状态的全部 milestone：
+   ```bash
+   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
+     --jq '.[].title'
+   ```
+3. 如果 `task.md` frontmatter 显式给出 `milestone` 字段，且该值出现在步骤 2 列表中：直接使用该值作为 `{milestone-arg}`，跳过步骤 4 / 5。
+4. 用正则 `^[0-9]+\.[0-9]+\.x$` 过滤步骤 2 结果。
+   - 非空：按 major、minor 数值升序排序，取最小的版本线作为 `{milestone-arg}`。
+5. 步骤 4 候选为空：尝试回退到 `General Backlog`。
+   - 步骤 2 结果中存在 `General Backlog`：使用该 milestone。
+   - 不存在 `General Backlog`：仅在此情况下省略 `--milestone`。
+6. 步骤 2 的 `gh api` 调用失败（网络 / 认证错误）：按"无候选"处理，落到步骤 5。
+
+设置成功时把版本线（或 `General Backlog` 或 task.md 显式值）作为 `{milestone-arg}` 带入步骤 5 的 `gh issue create` 命令；§5 末尾的展开规则保持不变。
 
 ### 5. 调用 GitHub CLI 创建 Issue
 

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -44,6 +44,18 @@ Only match titles in `X.Y.x` format and choose the smallest major/minor pair num
 
 Direct milestone writes are triage-gated. When the caller detected `has_triage=false`, omit `--milestone` and continue.
 
+### Backfill when called from `import-issue`
+
+When `import-issue` imports an existing Issue whose current milestone is empty, infer a release line using the priority above, including the `General Backlog` fallback. When a non-empty release line is found, write it back to the remote Issue:
+
+```bash
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}" 2>/dev/null || true
+fi
+```
+
+If `has_triage=false`, inference returns empty, or `gh issue edit` fails, skip and continue without blocking the `import-issue` workflow.
+
 ## Phase 2: `implement-task`
 
 Goal: narrow the Issue milestone from a release line to a concrete version when implementation starts.

package/templates/.agents/rules/milestone-inference.github.zh-CN.md

@@ -44,6 +44,18 @@ gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
 
 Milestone 设置属于 `has_triage` 权限范围；如果调用方检测到 `has_triage=false`，则省略 `--milestone` 并继续。
 
+### `import-issue` 调用时的兜底
+
+`import-issue` 导入既有 Issue 时，若 Issue 当前 milestone 为空，按上述优先级推断版本线（含 `General Backlog` 回退）。命中非空版本线后，回写到远端 Issue：
+
+```bash
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}" 2>/dev/null || true
+fi
+```
+
+如果 `has_triage=false`、推断结果为空、或 `gh issue edit` 失败，跳过并继续，不阻断 `import-issue` 工作流。
+
 ## 阶段 2：`implement-task`
 
 目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。