@fitlab-ai/agent-infra 0.6.3 → 0.6.4

package/README.md

@@ -787,7 +787,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.3",
+  "templateVersion": "v0.6.4",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

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

package/dist/lib/sandbox/clipboard/bridge.js

@@ -90,13 +90,15 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
     const onSigterm = () => child.kill('SIGTERM');
     function handleCtrlV(match, target) {
         try {
-            if (!adapter.hasImage()) {
-                target.write(match.raw);
-                return;
-            }
+            // readImagePng returns null both for "no image on clipboard" and for
+            // unexpected read failures; both cases forward the original Ctrl+V so
+            // the container app handles it as a regular keystroke. The throw branch
+            // below only fires on truly unexpected exceptions (e.g. fs write
+            // errors writing to the host clipboard dir).
             const png = adapter.readImagePng();
             if (!png) {
-                throw new Error('clipboard image could not be read');
+                target.write(match.raw);
+                return;
             }
             const filename = pngClipboardFilename(png);
             writeClipboardPngAtomic(clipboardHostDir(home), filename, png);

package/dist/lib/sandbox/clipboard/darwin.js

@@ -2,32 +2,25 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-const HAS_IMAGE_TIMEOUT_MS = 500;
+// Quick "is osascript callable at all" probe used by available(). Not for
+// clipboard work — clipboard work shares READ_IMAGE_TIMEOUT_MS below.
+// Generous 2s budget: this is a once-per-session bridge enablement check;
+// failing it just disables the clipboard bridge for that session, so we'd
+// rather tolerate a cold osascript spawn than misreport "unavailable".
+const OSASCRIPT_PROBE_TIMEOUT_MS = 2_000;
 const READ_IMAGE_TIMEOUT_MS = 5_000;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 export function createDarwinClipboardAdapter({ execFn = execFileSync, mkdtempFn = fs.mkdtempSync, readFileFn = fs.readFileSync, rmFn = fs.rmSync } = {}) {
     return {
         available() {
             try {
-                execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: HAS_IMAGE_TIMEOUT_MS });
+                execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: OSASCRIPT_PROBE_TIMEOUT_MS });
                 return { ok: true };
             }
             catch {
                 return { ok: false, reason: 'macOS osascript is unavailable' };
             }
         },
-        hasImage() {
-            try {
-                const output = String(execFn('osascript', ['-e', 'clipboard info'], {
-                    encoding: 'utf8',
-                    timeout: HAS_IMAGE_TIMEOUT_MS
-                }));
-                return /\b(PNGf|TIFF|JPEG|GIFf)\b/.test(output);
-            }
-            catch {
-                return false;
-            }
-        },
         readImagePng() {
             const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
             const outputPath = path.join(tmpDir, 'clipboard.png');

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

@@ -20,6 +20,7 @@ import { validateSelinuxDisableEnv } from "../engines/selinux.js";
 import { resolveBuildUid } from "../engines/native.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
+import { detectHostTimezone } from "../host-timezone.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 <<<';
@@ -1046,6 +1047,8 @@ export async function create(args) {
                         const dotfilesMount = dotfilesSnapshot
                             ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
                             : [];
+                        const hostTz = detectHostTimezone();
+                        const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
                         runEngineTaskCommand(engine, 'docker', [
                             'run',
                             '-d',
@@ -1075,6 +1078,7 @@ export async function create(args) {
                             ...liveMountVolumes,
                             ...shellConfigVolumes,
                             ...envFile.dockerArgs,
+                            ...tzFlags,
                             '-w',
                             '/workspace',
                             effectiveConfig.imageName

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

@@ -6,6 +6,7 @@ import { runInteractiveEngine, runSafeEngine } from "../shell.js";
 import { resolveTaskBranch } from "../task-resolver.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
+import { detectHostTimezone } from "../host-timezone.js";
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
@@ -29,6 +30,10 @@ export function terminalEnvFlags(env = process.env) {
     }
     return flags;
 }
+export function hostTimezoneEnvFlags(detect = detectHostTimezone) {
+    const tz = detect();
+    return tz ? ['-e', `TZ=${tz}`] : [];
+}
 export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY) {
     if (result.status === 'STALE_ACCESS') {
         return 'Warning: Claude Code credentials on host appear stale. Run "ai sandbox refresh" or "claude /login" to renew.\n';
@@ -84,7 +89,7 @@ export async function enter(args) {
             process.stderr.write(`Warning: Failed to sync Claude Code credentials: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
         }
     }
-    const envFlags = terminalEnvFlags();
+    const envFlags = [...terminalEnvFlags(), ...hostTimezoneEnvFlags()];
     if (cmd.length === 0) {
         try {
             materializeDotfiles(config.dotfilesDir, dotfilesCacheDir(config.home, config.project));

package/dist/lib/sandbox/host-timezone.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import os from 'node:os';
+const ZONEINFO_MARK = '/zoneinfo/';
+const IANA_ZONE_RE = /^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/;
+function safeTimezone(value) {
+    if (!value || !IANA_ZONE_RE.test(value)) {
+        return null;
+    }
+    return value;
+}
+export function detectHostTimezone(options = {}) {
+    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;
+    }
+}
+//# sourceMappingURL=host-timezone.js.map

package/dist/lib/sandbox/runtimes/base.dockerfile

@@ -3,7 +3,6 @@ FROM ubuntu:22.04
 LABEL description="AI coding sandbox"
 
 ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Asia/Shanghai
 
 ARG HOST_UID=1000
 ARG HOST_GID=1000
@@ -22,7 +21,7 @@ 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) \
@@ -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' \
@@ -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/lib/sandbox/clipboard/bridge.ts

@@ -153,14 +153,15 @@ async function runBridge({
 
   function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
     try {
-      if (!adapter.hasImage()) {
-        target.write(match.raw);
-        return;
-      }
-
+      // readImagePng returns null both for "no image on clipboard" and for
+      // unexpected read failures; both cases forward the original Ctrl+V so
+      // the container app handles it as a regular keystroke. The throw branch
+      // below only fires on truly unexpected exceptions (e.g. fs write
+      // errors writing to the host clipboard dir).
       const png = adapter.readImagePng();
       if (!png) {
-        throw new Error('clipboard image could not be read');
+        target.write(match.raw);
+        return;
       }
       const filename = pngClipboardFilename(png);
       writeClipboardPngAtomic(clipboardHostDir(home), filename, png);

package/lib/sandbox/clipboard/darwin.ts

@@ -4,7 +4,12 @@ import os from 'node:os';
 import path from 'node:path';
 import type { ExecFileSyncOptions } from 'node:child_process';
 
-const HAS_IMAGE_TIMEOUT_MS = 500;
+// Quick "is osascript callable at all" probe used by available(). Not for
+// clipboard work — clipboard work shares READ_IMAGE_TIMEOUT_MS below.
+// Generous 2s budget: this is a once-per-session bridge enablement check;
+// failing it just disables the clipboard bridge for that session, so we'd
+// rather tolerate a cold osascript spawn than misreport "unavailable".
+const OSASCRIPT_PROBE_TIMEOUT_MS = 2_000;
 const READ_IMAGE_TIMEOUT_MS = 5_000;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
@@ -12,7 +17,14 @@ type ExecFn = (cmd: string, args: string[], options?: ExecFileSyncOptions) => Bu
 
 export type DarwinClipboardAdapter = {
   available(): { ok: true } | { ok: false; reason: string };
-  hasImage(): boolean;
+  // Returns PNG bytes when the clipboard holds (or can synthesize) an image,
+  // null otherwise. No separate hasImage(): a probing `clipboard info` call
+  // forces NSPasteboard to materialize TIFF/BMP/8BPS representations to
+  // report their sizes, which can take seconds when the clipboard holds a
+  // Retina screenshot. Letting AppleScript's `as «class PNGf»` either succeed
+  // (image present, possibly auto-converted from TIFF/JPEG/GIF) or error
+  // (nothing PNG-coercible) keeps the path O(PNG size) regardless of how
+  // many other representations the source declared.
   readImagePng(): Buffer | null;
 };
 
@@ -30,23 +42,12 @@ export function createDarwinClipboardAdapter({
   return {
     available() {
       try {
-        execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: HAS_IMAGE_TIMEOUT_MS });
+        execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: OSASCRIPT_PROBE_TIMEOUT_MS });
         return { ok: true };
       } catch {
         return { ok: false, reason: 'macOS osascript is unavailable' };
       }
     },
-    hasImage() {
-      try {
-        const output = String(execFn('osascript', ['-e', 'clipboard info'], {
-          encoding: 'utf8',
-          timeout: HAS_IMAGE_TIMEOUT_MS
-        }));
-        return /\b(PNGf|TIFF|JPEG|GIFf)\b/.test(output);
-      } catch {
-        return false;
-      }
-    },
     readImagePng() {
       const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
       const outputPath = path.join(tmpDir, 'clipboard.png');

package/lib/sandbox/commands/create.ts

@@ -48,6 +48,7 @@ import {
   redactCommandError,
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
+import { detectHostTimezone } from '../host-timezone.ts';
 
 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 >>>';
@@ -1364,6 +1365,8 @@ export async function create(args: string[]): Promise<void> {
             const dotfilesMount = dotfilesSnapshot
               ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
               : [];
+            const hostTz = detectHostTimezone();
+            const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
 
             runEngineTaskCommand(engine, 'docker', [
               'run',
@@ -1398,6 +1401,7 @@ export async function create(args: string[]): Promise<void> {
               ...liveMountVolumes,
               ...shellConfigVolumes,
               ...envFile.dockerArgs,
+              ...tzFlags,
               '-w',
               '/workspace',
               effectiveConfig.imageName

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,11 @@ 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 formatCredentialSyncStatus(
   result: ReturnType<typeof reconcileClaudeCredentials>,
   isTTY = process.stderr.isTTY
@@ -101,7 +107,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));

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/runtimes/base.dockerfile

@@ -3,7 +3,6 @@ FROM ubuntu:22.04
 LABEL description="AI coding sandbox"
 
 ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Asia/Shanghai
 
 ARG HOST_UID=1000
 ARG HOST_GID=1000
@@ -22,7 +21,7 @@ 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) \
@@ -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' \
@@ -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.4",
   "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 从版本线收窄到具体版本。

package/templates/.agents/rules/testing-discipline.en.md

@@ -38,3 +38,47 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 - **Over-mocking**: Stub only real boundaries such as network, filesystem, time, or randomness; do not mock the logic of the unit under test, or the test only proves that the mock followed the script.
 - **Testing implementation details**: Prefer assertions on public APIs, artifacts, state changes, or error results; avoid assertions on private functions, internal call order, or temporary data structures.
 - **Insufficient assertions**: Assertions must pin down concrete expected values; do not replace checks on key fields, counts, and boundaries with "does not throw" or "result exists".
+
+## Coverage positioning (informational layer)
+
+> CI emits coverage via `node --test --experimental-test-coverage` as a hint about "which files are weakly tested". It is **not a merge gate**.
+
+### Local run
+
+```bash
+npm run test:coverage
+```
+
+The tail of stdout prints per-file line / branch / function coverage and the uncovered line numbers.
+
+### CI display
+
+`.github/workflows/unit-tests.yml` writes the coverage block into the GitHub Actions step summary on the ubuntu-latest shard (visible on the PR Checks page). Windows / macOS shards do not duplicate this output.
+
+The Codecov badge at the top of the README is generated by Codecov after `.github/workflows/unit-tests.yml` uploads `coverage.lcov` from the ubuntu-latest shard.
+
+### Boundaries
+
+- **No percentage thresholds**: Threshold flags such as `--test-coverage-lines/branches/functions` are forbidden. Goodhart's law reminds us that once coverage becomes a metric, developers write "coverage-friendly but behavior-weak" tests.
+- **Third-party services for the badge only**: Codecov hosts the README coverage badge, but the root `codecov.yml` explicitly disables its project/patch status checks and PR comments — Codecov only displays a number here and does not participate in merge decisions. Do not integrate other services such as coveralls.
+- **No tier split**: Coverage is currently emitted only for the full `test` tier; smoke / core tier coverage has no independent value.
+- **Does not block PRs**: The CI step uses `continue-on-error: true`, so a failed coverage collection does not affect merges.
+
+### Where New Tests Go
+
+The test directory determines which npm script runs a test file:
+
+- `tests/unit/<module>/`: fast structural or pure-function tests; does not spawn the real CLI process or depend on external tools, suitable for `test:smoke`.
+- `tests/integration/<module>/`: combines multiple modules, runs CLI subprocesses, touches temporary filesystems, or verifies template sync flows while staying stable and reasonably fast, suitable for `test:core`.
+- `tests/e2e/<module>/`: slower contract, platform-sync, packaged-output, cross-process, or end-to-end workflow tests, run only by full `npm test`.
+
+Modules remain as second-level directories such as `cli`, `core`, `scripts`, and `templates`. Shared helpers and fixtures stay in `tests/helpers/`, `tests/helpers.ts`, and `tests/fixtures/`; do not place them under a tier.
+
+### Relation to "test tier coverage"
+
+Distinguish two concepts:
+
+- **Test tier coverage** (`tests/unit/core/test-tier-coverage.test.ts` checks test directory placement and npm script tier mapping): governs "which test files belong to which tier" and is orthogonal to source-line coverage.
+- **Source-line coverage** (this section): governs "which lines of production source are exercised by tests".
+
+The two serve different purposes and should not substitute for each other.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -38,3 +38,47 @@ assert.match(content, /^name: implement-task$/m);    // 正向断言已足够
 - **mock 过度**：只在网络、文件系统、时间、随机数等真实边界打桩；不要 mock 被测对象自身逻辑，否则测试只验证 mock 是否按预设运行。
 - **测试实现细节**：优先断言公开接口、产物、状态变化或错误结果；避免断言私有函数、内部调用顺序、临时数据结构。
 - **断言不充分**：断言必须锁定具体期望值；不要用"只要不抛异常""结果存在即可"替代对关键字段、数量和边界的验证。
+
+## 覆盖率定位（信息层）
+
+> CI 中通过 `node --test --experimental-test-coverage` 输出覆盖率，仅作为"哪些文件被测试薄弱"的提示，**不作为 merge gate**。
+
+### 本地运行
+
+```bash
+npm run test:coverage
+```
+
+stdout 末尾会打印按文件粒度的行 / 分支 / 函数覆盖率以及未覆盖行号。
+
+### CI 展示
+
+`.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上把覆盖率块写入 GitHub Actions 的 step summary（PR Checks 页可见）。Windows / macOS 分片不重复输出。
+
+README 顶部的 Codecov 徽章由 `.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上传 `coverage.lcov` 后由 Codecov 生成。
+
+### 边界
+
+- **不设置百分比阈值**：`--test-coverage-lines/branches/functions` 等阈值参数禁止加入；Goodhart's law 提醒我们一旦把覆盖率作为指标，开发者会写"覆盖率友好但行为弱"的测试。
+- **第三方服务仅用于徽章**：已接入 Codecov 托管 README 覆盖率徽章，但通过根 `codecov.yml` 显式关闭其 project/patch status check 与 PR 评论——Codecov 在本项目只展示数字，不参与 merge 决策。不接入 coveralls 等其他服务。
+- **不区分 tier**：当前只对 full `test` tier 输出覆盖率；smoke / core tier 的覆盖率没有独立价值。
+- **不阻塞 PR**：CI 步骤 `continue-on-error: true`，即便覆盖率采集失败也不影响 merge。
+
+### 新测试该放哪一层
+
+测试文件放入哪一层决定它会被哪些 npm script 自动执行：
+
+- `tests/unit/<module>/`：快速、结构性或纯函数类测试；不启动真实 CLI 子进程，不依赖外部工具，适合 `test:smoke`。
+- `tests/integration/<module>/`：会组合多个模块、运行 CLI 子进程、触达临时文件系统或验证模板同步流程，但仍应保持稳定和相对快速，适合 `test:core`。
+- `tests/e2e/<module>/`：较慢的契约、平台同步、打包产物、跨进程或端到端流程测试，只在完整 `npm test` 中运行。
+
+模块继续作为第二级目录（如 `cli`、`core`、`scripts`、`templates`）。共享 helper 和 fixtures 保持在 `tests/helpers/`、`tests/helpers.ts`、`tests/fixtures/`，不要放入任一 tier。
+
+### 与"测试 tier 覆盖"的关系
+
+注意区分两个概念：
+
+- **测试 tier 覆盖**（`tests/unit/core/test-tier-coverage.test.ts` 校验测试文件目录归属与 npm script tier 映射）：管的是"哪些测试文件被纳入哪一 tier"，与代码行覆盖率正交。
+- **代码行覆盖率**（本节）：管的是"业务源码哪些行被测试触达"。
+
+两者目的不同，不要相互替代。

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

@@ -116,6 +116,8 @@ The rule's content is determined by the configured code platform:
 - A platform that supports Issue creation: contains the full flow for auth detection, template detection, label/type/milestone inference, the create-Issue call, and writing back to `task.md`
 - Custom or empty platforms (no platform-specific variant provided): the rule body is a no-op notice, and this step is skipped entirely
 
+> **Hard constraint**: the milestone sub-step in `.agents/rules/create-issue.md` §4 is mandatory; missing it fails the step 5 gate (`verify_milestone: true`) and aborts create-task.
+
 Handle the result:
 - Rule successfully created the Issue: `issue_number` has been written back to task.md per the rule; continue by reading `.agents/rules/issue-sync.md`, completing upstream repository and permission detection, then sync the task comment and set `status: waiting-for-triage` by rule
 - Rule failed (auth / network / template parse / etc.): do not roll back task.md; do NOT append an extra Activity Log entry; follow "Scenario C: Issue creation failed" output to surface `error_code` and `error_message` to the user so they can decide whether to retry manually or write `issue_number` later

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

@@ -116,6 +116,8 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 支持 Issue 创建的平台：包含完整的认证检测、模板检测、label/Issue Type/milestone 推断、Issue 创建调用、`task.md` 回写流程
 - 自定义或空平台（未提供平台变体规则文件）：内容为 no-op 说明，本步骤直接跳过
 
+> **强约束**：`.agents/rules/create-issue.md` §4 中的 milestone 子步骤为必须执行项；漏设会被步骤 5 的 gate（`verify_milestone: true`）截停，导致 create-task 失败。
+
 处理结果：
 - 规则成功创建 Issue：`issue_number` 已按规则回写到 task.md；继续读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测，然后同步 task 评论并按规则设置 `status: waiting-for-triage`
 - 规则失败（认证 / 网络 / 模板解析等）：不回滚 task.md；不追加额外 Activity Log；按"场景 C：Issue 创建失败"输出向用户透出 `error_code` 与 `error_message`，让用户决定后续是否手动重试或写入 `issue_number`

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

@@ -25,6 +25,7 @@
       "when": "issue_number_exists",
       "issue_must_exist": true,
       "verify_task_comment_content": true,
+      "verify_milestone": true,
       "expected_status_label_key": "waitingForTriage"
     }
   }

package/templates/.agents/skills/import-issue/SKILL.en.md

@@ -114,7 +114,7 @@ If task.md contains a valid `issue_number`, use the Issue update command from `.
 
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
 - Read `.agents/rules/issue-sync.md` before syncing, and complete upstream repository detection plus permission detection
-- Check the Issue's current milestone; if it is unset, read `.agents/rules/milestone-inference.md` and infer plus set the milestone using "Phase 1: `create-task` (when the platform rule creates an Issue)". If `has_triage=false` or the inference is uncertain, skip and continue
+- Check the Issue's current milestone; if it is unset, read `.agents/rules/milestone-inference.md`, infer a release line using "Phase 1: `create-task` (when the platform rule creates an Issue)", and run its "Backfill when called from `import-issue`" subsection to write back to the remote Issue. If inference fails, permissions are insufficient, or write-back fails, skip and continue without blocking the import
 - After every scenario, task comment sync is mandatory: create or update the task comment marker defined in `.agents/rules/issue-sync.md` so the remote `:task` comment exists and matches the local `task.md` content (follow the task.md comment sync rule in issue-sync.md)
 
 ### 7. Verification Gate

package/templates/.agents/skills/import-issue/SKILL.zh-CN.md

@@ -114,7 +114,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测
-- 检查 Issue 当前 milestone；如果未设置，先读取 `.agents/rules/milestone-inference.md`，按其中的「阶段 1：`create-task`（平台规则创建 Issue 时）」规则推断并设置 milestone；如果 `has_triage=false` 或推断不确定，跳过并继续
+- 检查 Issue 当前 milestone；如果未设置，先读取 `.agents/rules/milestone-inference.md`，按其中的「阶段 1：`create-task`（平台规则创建 Issue 时）」推断版本线，并按其「`import-issue` 调用时的兜底」子节执行远端回写；推断失败、权限不足或回写失败均跳过并继续，不阻断导入
 - 所有场景结束后，必须执行一次 task 留言同步，创建或更新 `.agents/rules/issue-sync.md` 中定义的 task 评论标记，确保远端 `:task` 评论存在且内容与本地 `task.md` 一致（按 issue-sync.md 的 task.md 评论同步规则）
 
 ### 7. 完成校验