@seanyao/roll 3.614.1 → 3.614.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## v3.614.3 — 2026-06-14
+
+### 改进
+
+- **设计技能更严**:`roll-design` 现在把"详细设计"做成一道硬步骤——拆任务之前,必须先拿出能照着写的方案(数据结构、**至少一个完整样例**、接口、映射规则、边界情况)并经确认。规矩一句话:拿不出一个完整样例,就还没设计完。(US-SKILL-029)
+
+### 修复
+
+- 失败/空转的一轮循环现在也记下用了哪个模型:之前那条记录里模型是空的(只补过另一处、这条漏了),导致实时窗和循环账本看不到是哪个 AI 在跑;现在哪个都记上。(FIX-294)
+
+## v3.614.2 — 2026-06-14
+
+### 修复
+
+- `roll loop go` 启动时会给清楚的反馈了:告诉你起的是哪个会话、在做哪些卡、第一轮起没起、怎么只读地看——之前只甩一句模糊的 "started" 就退出,你根本不知道开没开。会话复用时也会补上观察窗,attach 进去能直接看到实时流、而不是落在干活的窗口里。还能 `--attach` 直接在前台跟住实时流(此时 Ctrl-C 只停看、不停循环)。(FIX-289)
+- 失败/空转的一轮循环现在也记下用了哪个模型、烧了多少 token、花了多少钱:之前账本那行只剩时间、其余全是 —;读不到用量时如实标"未知",不再假装成 0。而且每一轮结束(不管成没成)都会刷新项目网页,失败的循环不再在循环页里隐身。(FIX-290)
+- 网页截图取证不再因为"本地没装 Chromium"就悄悄降级成纯文本:有图形界面时直接用系统截屏(打开浏览器截真窗口、真像素),没界面才用无头浏览器,都不行才如实记"没截成"——绝不拿文本冒充截图。(FIX-291)
+
 ## v3.614.1 — 2026-06-14
 
 ### 新功能

package/dist/roll.mjs

@@ -2324,6 +2324,7 @@ function buildTerminalEvent(input) {
     cycleId: input.cycleId,
     storyId: input.storyId,
     agent: input.agent,
+    model: input.model ?? "",
     startedAt: input.startedAt,
     endedAt: input.endedAt,
     outcome: input.outcome,
@@ -2412,6 +2413,10 @@ var init_truth_registry = __esm({
       { field: "cycleId", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
       { field: "storyId", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
       { field: "agent", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
+      // FIX-294: routed model is a dispatch-time fact (like agent) — authoritative,
+      // ALWAYS present even when usage couldn't be parsed; the `usage` fact below
+      // still owns the present-or-reasoned token/cost truth.
+      { field: "model", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
       { field: "startedAt", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
       { field: "endedAt", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
       { field: "outcome", surface: "event:cycle:terminal", anchor: "cycle_outcome", writer: "buildTerminalEvent", kind: "authoritative" },
@@ -9452,6 +9457,10 @@ function terminalBoundsScript(title) {
     "end tell"
   ].join("\n");
 }
+async function hasGuiSession(run) {
+  const gui = await run("launchctl", ["managername"]);
+  return gui.code === 0 && gui.stdout.includes("Aqua");
+}
 async function resolveWindowRect(title, run) {
   const r = await run("osascript", ["-e", terminalBoundsScript(title)]);
   if (r.code !== 0)
@@ -9464,6 +9473,89 @@ async function resolveWindowRect(title, run) {
     return null;
   return { x: x1, y: y1, w: x2 - x1, h: y2 - y1 };
 }
+function browserOpenScript(target, browserApp, r) {
+  const app = appleScriptString(browserApp);
+  const url = appleScriptString(target);
+  return [
+    `tell application "${app}"`,
+    "  activate",
+    "  make new window",
+    "  try",
+    `    set URL of active tab of front window to "${url}"`,
+    "  on error",
+    "    try",
+    `      set URL of front document to "${url}"`,
+    "    end try",
+    "  end try",
+    `  delay ${BROWSER_RENDER_DELAY_S}`,
+    "  try",
+    `    set bounds of front window to {${r.x}, ${r.y}, ${r.x + r.w}, ${r.y + r.h}}`,
+    "  end try",
+    "end tell"
+  ].join("\n");
+}
+function browserBoundsScript(browserApp) {
+  const app = appleScriptString(browserApp);
+  return [
+    `tell application "${app}"`,
+    "  try",
+    "    activate",
+    "    set index of front window to 1",
+    "    delay 0.3",
+    "    return bounds of front window",
+    "  on error",
+    '    return ""',
+    "  end try",
+    "end tell"
+  ].join("\n");
+}
+function browserCloseScript(browserApp) {
+  const app = appleScriptString(browserApp);
+  return [
+    `tell application "${app}"`,
+    "  try",
+    "    close front window",
+    "  end try",
+    "end tell"
+  ].join("\n");
+}
+async function resolveBrowserRect(browserApp, run) {
+  const r = await run("osascript", ["-e", browserBoundsScript(browserApp)]);
+  if (r.code !== 0)
+    return null;
+  const parts = r.stdout.trim().split(",").map((part) => Number(part.trim()));
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n)))
+    return null;
+  const [x1, y1, x2, y2] = parts;
+  if (x2 <= x1 || y2 <= y1)
+    return null;
+  return { x: x1, y: y1, w: x2 - x1, h: y2 - y1 };
+}
+async function captureWebViaBrowser(req, run) {
+  const browserApp = req.browser ?? DEFAULT_BROWSER;
+  const rect = parseRegion(req.region ?? DEFAULT_REGION);
+  if (rect === null)
+    return "bad region";
+  const target = req.url;
+  const opened = await run("osascript", ["-e", browserOpenScript(target, browserApp, rect)]);
+  if (opened.code !== 0)
+    return `osascript ${browserApp} open failed`;
+  const liveRect = await resolveBrowserRect(browserApp, run);
+  if (liveRect === null) {
+    await run("osascript", ["-e", browserCloseScript(browserApp)]);
+    return "browser window not found \u2014 refusing a blind-region shot";
+  }
+  const front = await run("sh", ["-c", "lsappinfo info -only name $(lsappinfo front)"]);
+  if (front.code !== 0 || !front.stdout.includes(browserApp)) {
+    await run("osascript", ["-e", browserCloseScript(browserApp)]);
+    return `${browserApp} not frontmost \u2014 refusing to shoot another app's pixels`;
+  }
+  const shot = await run("screencapture", ["-x", "-R", `${liveRect.x},${liveRect.y},${liveRect.w},${liveRect.h}`, req.out]);
+  await run("osascript", ["-e", browserCloseScript(browserApp)]);
+  if (shot.code !== 0)
+    return "screencapture failed (screen-recording permission?)";
+  return null;
+}
 function terminalExitTabScript(title) {
   const esc8 = appleScriptString(title);
   return [
@@ -9550,9 +9642,17 @@ async function captureScreenshot(req, deps = {}) {
         return skip("ROLL_ATTEST_NO_BROWSER=1");
       if (req.url === void 0 || req.url === "")
         return skip("no url");
-      const r = await run("npx", ["-y", "playwright@latest", "screenshot", req.url, req.out]);
-      if (r.code !== 0)
-        return skip("playwright unavailable or capture failed");
+      if (platform3 === "darwin" && await hasGuiSession(run)) {
+        const reason = await captureWebViaBrowser(req, run);
+        if (reason !== null)
+          return skip(`GUI browser capture: ${reason}`);
+      } else {
+        const r = await run("npx", ["-y", "playwright@latest", "screenshot", req.url, req.out]);
+        if (r.code !== 0) {
+          const why = platform3 === "darwin" ? "no GUI session" : "non-macOS host";
+          return skip(`headless Chromium unavailable or capture failed (${why}; screencapture fallback not applicable)`);
+        }
+      }
     } else if (req.kind === "mobile-ios") {
       if (platform3 !== "darwin")
         return skip("not macOS");
@@ -9578,8 +9678,7 @@ async function captureScreenshot(req, deps = {}) {
       const rawLine = req.tmux !== void 0 && req.tmux !== "" ? `tmux attach -t ${req.tmux}` : req.command ?? "";
       if (containsSecret(rawLine))
         return skip("secret in capture command \u2014 redact & reshoot");
-      const gui = await run("launchctl", ["managername"]);
-      if (gui.code !== 0 || !gui.stdout.includes("Aqua"))
+      if (!await hasGuiSession(run))
         return skip("no GUI session");
       const rect = parseRegion(req.region ?? DEFAULT_REGION);
       if (rect === null)
@@ -9638,7 +9737,7 @@ async function captureAll(reqs, deps = {}) {
     out3.push(await captureScreenshot(r, deps));
   return out3;
 }
-var execFileAsync7, defaultRun2, SAFE_STEM, DEFAULT_REGION, TERMINAL_DONE_TIMEOUT_MS, TERMINAL_DONE_POLL_MS;
+var execFileAsync7, defaultRun2, SAFE_STEM, DEFAULT_REGION, TERMINAL_DONE_TIMEOUT_MS, TERMINAL_DONE_POLL_MS, DEFAULT_BROWSER, BROWSER_RENDER_DELAY_S;
 var init_screenshot = __esm({
   "packages/infra/dist/screenshot.js"() {
     "use strict";
@@ -9661,6 +9760,8 @@ var init_screenshot = __esm({
     DEFAULT_REGION = "0,0,1280,800";
     TERMINAL_DONE_TIMEOUT_MS = 12e4;
     TERMINAL_DONE_POLL_MS = 100;
+    DEFAULT_BROWSER = "Google Chrome";
+    BROWSER_RENDER_DELAY_S = 2;
   }
 });
 
@@ -9684,6 +9785,9 @@ __export(dist_exports, {
   attachArgv: () => attachArgv,
   branchCreate: () => branchCreate,
   branchDelete: () => branchDelete,
+  browserBoundsScript: () => browserBoundsScript,
+  browserCloseScript: () => browserCloseScript,
+  browserOpenScript: () => browserOpenScript,
   canonicalProjectPath: () => canonicalProjectPath,
   captureAll: () => captureAll,
   captureFromMarker: () => captureFromMarker,
@@ -17137,7 +17241,9 @@ function ledgerVerdict(status2, outcome) {
 function ledgerFailedCount(rows) {
   return rows.filter((r) => r.verdict === "failed" || r.verdict === "reverted" || r.verdict === "blocked").length;
 }
-function fmtTokens2(tin, tout) {
+function fmtTokens2(tin, tout, usageUnknown) {
+  if (usageUnknown)
+    return "?";
   const a = typeof tin === "number" ? tin : 0;
   const b = typeof tout === "number" ? tout : 0;
   if (a + b === 0)
@@ -17241,6 +17347,7 @@ function collectCycleLedger(projectPath3) {
     const rawTs = row2["ts"];
     const ts = typeof rawTs === "string" ? Date.parse(rawTs) : typeof rawTs === "number" ? rawTs > 1e10 ? rawTs : rawTs * 1e3 : Number.NaN;
     const cost = typeof row2["cost_effective_usd"] === "number" ? row2["cost_effective_usd"] : typeof row2["cost_usd"] === "number" ? row2["cost_usd"] : void 0;
+    const usageUnknown = row2["usage_unknown"] === true;
     const ev = byCycle.get(cycleId);
     const prNumber = storyId !== "" ? prMergedBy.get(storyId) : void 0;
     const prOpen = storyId !== "" ? prOpenBy.get(storyId) : void 0;
@@ -17254,8 +17361,8 @@ function collectCycleLedger(projectPath3) {
       storyId,
       agent: String(row2["agent"] ?? ""),
       model: typeof row2["model"] === "string" && row2["model"] !== "" ? row2["model"] : String(row2["agent"] ?? "\u2014") || "\u2014",
-      tokens: fmtTokens2(row2["tokens_in"], row2["tokens_out"]),
-      cost: cost !== void 0 ? `$${cost.toFixed(2)}` : "\u2014",
+      tokens: fmtTokens2(row2["tokens_in"], row2["tokens_out"], usageUnknown),
+      cost: cost !== void 0 ? `$${cost.toFixed(2)}` : usageUnknown ? "?" : "\u2014",
       duration: fmtDuration(row2["duration_sec"]),
       tape: rowTape(row2, verdict, ev, prNumber, prOpen),
       evidence
@@ -23605,6 +23712,8 @@ function pad3(s, w) {
 function tokensTotal(tokens) {
   if (tokens === "\u2014")
     return "\u2014";
+  if (tokens === "?")
+    return "?";
   const parts = tokens.split("/");
   const num4 = (p) => p.endsWith("k") ? Number(p.slice(0, -1)) * 1e3 : Number(p);
   const total = parts.reduce((a, p) => a + (Number.isFinite(num4(p)) ? num4(p) : 0), 0);
@@ -24728,6 +24837,7 @@ function realDeps4() {
       }
     },
     startTmux: startGoTmux,
+    followFeed: followGoLiveFeed,
     runOnce: realRunOnce,
     readUsageLimits: readAnthropicUsageLimits,
     sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms)),
@@ -24781,6 +24891,7 @@ function parseOptions2(args) {
   let worker = false;
   let noTmux = false;
   let noWait = false;
+  let attach = false;
   let scopeSpecified = false;
   let reviewMode = "auto";
   let reviewModeSpecified = false;
@@ -24798,6 +24909,10 @@ function parseOptions2(args) {
       noWait = true;
       continue;
     }
+    if (arg === "--attach" || arg === "--follow") {
+      attach = true;
+      continue;
+    }
     if (arg === "--epic") {
       const epic = args[i + 1]?.trim() ?? "";
       if (epic !== "") {
@@ -24882,6 +24997,7 @@ function parseOptions2(args) {
     worker,
     noTmux,
     noWait,
+    attach,
     scope,
     scopeSpecified,
     reviewMode,
@@ -24897,7 +25013,7 @@ function hasHelpArg2(args) {
 }
 function loopGoHelp() {
   return [
-    "Usage: roll loop go [--epic <name>|--cards <ids>] [--budget <usd>] [--for <duration>] [--max-cycles <n>] [--review <auto|hetero|self|off>] [--no-wait] [--no-tmux]",
+    "Usage: roll loop go [--epic <name>|--cards <ids>] [--budget <usd>] [--for <duration>] [--max-cycles <n>] [--review <auto|hetero|self|off>] [--no-wait] [--attach] [--no-tmux]",
     "  Chain goal-mode cycles until the scoped backlog is complete, paused, budget-limited, or capped.",
     "  \u6309 goal \u8303\u56F4\u8FDE\u7EED\u6267\u884C cycle\uFF0C\u76F4\u5230\u5B8C\u6210\u3001\u6682\u505C\u3001\u9884\u7B97\u53D7\u9650\u6216\u8FBE\u5230\u4E0A\u9650\u3002",
     "",
@@ -24910,6 +25026,7 @@ function loopGoHelp() {
     "  --usage-threshold <ratio>  Pause when account usage reaches this ratio; default 0.85.",
     "  --no-wait           Do not wait for usage windows to recover after a usage-limit pause.",
     "  --review <mode>     Final review policy before completion: auto, hetero, self, or off.",
+    "  --attach, --follow  Start the session, then follow the read-only live feed in the foreground (Ctrl-C stops the view, not the loop).",
     "  --no-tmux           Run in the current process instead of starting a tmux session.",
     "",
     "Limits are explicit per run (FIX-279):",
@@ -25000,21 +25117,76 @@ function shellQuote3(value) {
 function rollBin() {
   return (process.env["ROLL_BIN"] ?? "").trim() || process.argv[1] || "roll";
 }
+function goSessionName(slug) {
+  return `roll-loop-${slug}`;
+}
+function watchCommand(projectPath3, slug, rollBin3) {
+  const live = shellQuote3(join44(runtimeDir2(projectPath3), "live.log"));
+  return `printf 'roll goal \xB7 ${slug}\\n'; tail -n +1 -F ${live} | ${shellQuote3(rollBin3)} loop fmt`;
+}
+function planGoTmuxCommands(input, state) {
+  const session = goSessionName(input.slug);
+  const watch = watchCommand(input.projectPath, input.slug, input.rollBin);
+  const workerArgs = input.args.filter((arg) => arg !== "--worker" && arg !== "--no-tmux" && arg !== "--attach" && arg !== "--follow").concat("--worker").map(shellQuote3).join(" ");
+  const command = `cd ${shellQuote3(input.projectPath)} && ROLL_LOOP_GO_WORKER=1 ROLL_LOOP_NO_TMUX=1 ROLL_BIN=${shellQuote3(input.rollBin)} ${shellQuote3(input.rollBin)} loop go ${workerArgs}`;
+  const plan = [];
+  if (!state.sessionExists) {
+    plan.push(["new-session", "-d", "-s", session, "-x", "200", "-y", "50", "-n", "watch", watch]);
+  } else if (!state.watchWindowExists) {
+    plan.push(["new-window", "-d", "-t", session, "-n", "watch", watch]);
+  }
+  plan.push(["new-window", "-d", "-t", session, "-n", "go", command]);
+  return plan;
+}
+function probeGoTmuxState(slug) {
+  const session = goSessionName(slug);
+  const sessionExists = spawnSync4("tmux", ["has-session", "-t", session], { stdio: "ignore" }).status === 0;
+  if (!sessionExists)
+    return { sessionExists: false, watchWindowExists: false };
+  const listed = spawnSync4("tmux", ["list-windows", "-t", session, "-F", "#{window_name}"], { encoding: "utf8" });
+  const windows = listed.status === 0 ? String(listed.stdout ?? "").split("\n").map((w) => w.trim()) : [];
+  return { sessionExists: true, watchWindowExists: windows.includes("watch") };
+}
 function startGoTmux(input) {
-  const session = `roll-loop-${input.slug}`;
-  const rt = runtimeDir2(input.projectPath);
-  const workerArgs = input.args.filter((arg) => arg !== "--worker" && arg !== "--no-tmux").concat("--worker").map(shellQuote3).join(" ");
-  const watch = `printf 'roll goal \xB7 ${input.slug}\\n'; tail -n +1 -F ${shellQuote3(join44(rt, "live.log"))} | ${shellQuote3(input.rollBin)} loop fmt`;
+  const session = goSessionName(input.slug);
   try {
-    if (spawnSync4("tmux", ["has-session", "-t", session], { stdio: "ignore" }).status !== 0) {
-      spawnSync4("tmux", ["new-session", "-d", "-s", session, "-x", "200", "-y", "50", "-n", "watch", watch], { stdio: "ignore" });
+    const plan = planGoTmuxCommands(input, probeGoTmuxState(input.slug));
+    let goStarted = false;
+    for (const argv of plan) {
+      const ok8 = spawnSync4("tmux", argv, { stdio: "ignore" }).status === 0;
+      if (argv[0] === "new-window" && argv.includes("go") && argv[argv.length - 1]?.startsWith("cd "))
+        goStarted = ok8;
     }
-    const command = `cd ${shellQuote3(input.projectPath)} && ROLL_LOOP_GO_WORKER=1 ROLL_LOOP_NO_TMUX=1 ROLL_BIN=${shellQuote3(input.rollBin)} ${shellQuote3(input.rollBin)} loop go ${workerArgs}`;
-    return spawnSync4("tmux", ["new-window", "-d", "-t", session, "-n", "go", command], { stdio: "ignore" }).status === 0;
+    return goStarted;
   } catch {
     return false;
   }
 }
+function followGoLiveFeed(projectPath3, rollBin3) {
+  return new Promise((resolve5) => {
+    const live = join44(runtimeDir2(projectPath3), "live.log");
+    const tail3 = spawn3("tail", ["-n", "+1", "-F", live], { stdio: ["ignore", "pipe", "inherit"] });
+    const fmt = spawn3(rollBin3.endsWith(".js") || rollBin3.endsWith(".mjs") ? process.execPath : rollBin3, rollBin3.endsWith(".js") || rollBin3.endsWith(".mjs") ? [rollBin3, "loop", "fmt"] : ["loop", "fmt"], { stdio: ["pipe", "inherit", "inherit"] });
+    if (tail3.stdout !== null && fmt.stdin !== null)
+      tail3.stdout.pipe(fmt.stdin);
+    const finish = () => {
+      try {
+        tail3.kill("SIGTERM");
+      } catch {
+      }
+      try {
+        fmt.kill("SIGTERM");
+      } catch {
+      }
+      process.removeListener("SIGINT", finish);
+      resolve5();
+    };
+    process.on("SIGINT", finish);
+    fmt.on("exit", finish);
+    tail3.on("exit", finish);
+    tail3.on("error", finish);
+  });
+}
 function realRunOnce(input) {
   const bin = rollBin();
   const cmd = bin.endsWith(".js") || bin.endsWith(".mjs") ? process.execPath : bin;
@@ -25756,6 +25928,28 @@ function installStopHandlers(onStop) {
       process.off(signal2, handler);
   };
 }
+function describeScope(scope) {
+  if (scope.kind === "cards")
+    return `cards ${scope.cards.join(", ")}`;
+  if (scope.kind === "epic")
+    return `epic ${scope.epic}`;
+  return "all Todo backlog cards";
+}
+function goStartupFeedback(slug, scope) {
+  const session = goSessionName(slug);
+  return [
+    `Goal go session started: ${session}`,
+    `  scope:   ${describeScope(scope)}`,
+    "  cycles:  first cycle is running now; cycles chain until the scope is complete, paused, or capped.",
+    `  observe: tmux attach -t ${session}  (read-only watch window; the 'go' window is the worker \u2014 do not Ctrl-C it)`,
+    `           or follow inline:  roll loop go --attach`,
+    "",
+    `goal \u8FDE\u8DD1\u4F1A\u8BDD\u5DF2\u542F\u52A8: ${session}`,
+    "  \u7B2C\u4E00\u4E2A cycle \u6B63\u5728\u8FD0\u884C\uFF1B\u4F1A\u6301\u7EED\u8FDE\u8DD1\u76F4\u5230\u8303\u56F4\u5B8C\u6210\u3001\u6682\u505C\u6216\u8FBE\u4E0A\u9650\u3002",
+    `  \u89C2\u5BDF (\u53EA\u8BFB): tmux attach -t ${session}  \u6216  roll loop go --attach`,
+    ""
+  ].join("\n");
+}
 async function loopGoCommand(args, deps = realDeps4()) {
   if (hasHelpArg2(args)) {
     process.stdout.write(loopGoHelp());
@@ -25766,9 +25960,11 @@ async function loopGoCommand(args, deps = realDeps4()) {
   if (!opts.worker && !opts.noTmux && deps.hasTmux()) {
     const started = deps.startTmux({ projectPath: id.path, slug: id.slug, args, rollBin: rollBin() });
     if (started) {
-      process.stdout.write(`Goal go session started in tmux \u2014 attach anytime: tmux attach -t roll-loop-${id.slug}
-goal \u8FDE\u8DD1\u4F1A\u8BDD\u5DF2\u5728 tmux \u542F\u52A8 \u2014 \u53EF\u968F\u65F6\u89C2\u5BDF: tmux attach -t roll-loop-${id.slug}
-`);
+      process.stdout.write(goStartupFeedback(id.slug, opts.scope));
+      if (opts.attach && deps.followFeed !== void 0) {
+        process.stdout.write("Following live feed (Ctrl-C stops the view, not the loop) \u2026\n\u6B63\u5728\u8DDF\u968F\u5B9E\u65F6\u8F93\u51FA (Ctrl-C \u53EA\u505C\u6B62\u67E5\u770B\uFF0C\u4E0D\u4F1A\u505C\u6B62 loop) \u2026\n");
+        await deps.followFeed(id.path, rollBin());
+      }
       return 0;
     }
   }
@@ -30414,6 +30610,7 @@ ${diffStat}`;
       } else if (cmd.status === "idle" && (ctx.storyId ?? "") !== "") {
         ports.backlog.markStatus?.(ports.repoCwd, ctx.storyId ?? "", STATUS_MARKER.todo);
       }
+      refreshAggregates(ports.repoCwd);
       return {};
     }
     // _worktree_alert.
@@ -30456,16 +30653,22 @@ function buildRunRow(cmd, ctx, nowSec2) {
         row2["duration_sec"] = dur;
     }
   }
+  const routedModel = (ctx.model ?? "").trim() !== "" ? ctx.model : ctx.agent ?? "";
+  if (routedModel !== "")
+    row2["model"] = routedModel;
   if (ctx.cost !== void 0) {
     row2["cost_usd"] = ctx.cost.estimatedCost;
     row2["cost_effective_usd"] = ctx.cost.effectiveCost;
-    row2["model"] = ctx.cost.model;
+    if (ctx.cost.model !== "")
+      row2["model"] = ctx.cost.model;
     row2["tokens_in"] = ctx.cost.tokensIn;
     row2["tokens_out"] = ctx.cost.tokensOut;
     if (ctx.cost.cacheRead !== void 0)
       row2["tokens_cache_read"] = ctx.cost.cacheRead;
     if (ctx.cost.cacheWrite !== void 0)
       row2["tokens_cache_write"] = ctx.cost.cacheWrite;
+  } else {
+    row2["usage_unknown"] = true;
   }
   return row2;
 }
@@ -30505,10 +30708,13 @@ function buildTerminalRecord(cmd, ctx, worktreePath, nowSec2) {
   } else {
     usage2 = absent("no_parseable_usage");
   }
+  const routedModel = (ctx.model ?? "").trim() !== "" ? ctx.model : ctx.agent ?? "";
+  const model = ctx.cost !== void 0 && ctx.cost.model !== "" ? ctx.cost.model : routedModel;
   return buildTerminalEvent({
     cycleId: cmd.cycleId,
     storyId,
     agent: ctx.agent ?? "",
+    model,
     startedAt: ctx.startSec ?? nowSec2,
     endedAt: nowSec2,
     outcome: OUTCOME[cmd.status] ?? "unknown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.614.1",
+  "version": "3.614.3",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/roll-design/SKILL.md

@@ -27,20 +27,23 @@ Load when the user wants to discuss approaches, design a solution, model domains
 
 1. Clarify only when intent or boundaries are unclear.
 2. Model domain depth proportional to risk and novelty.
-3. Split into INVEST stories with acceptance criteria and dependencies.
-4. Write specs through roll story new and update backlog.
-5. Self-score the design quality.
+3. Detailed design before decomposition — for any non-trivial work, produce a concrete, implementable design artifact and get owner sign-off: (a) data/contract schema, (b) AT LEAST ONE complete worked sample of the intended output/behavior, (c) key interface signatures, (d) mapping/normalization rules, (e) edge cases & failure modes. Depth scales with risk/novelty; trivial work may be light.
+4. Split into INVEST stories — each a slice of the agreed detailed design.
+5. Write specs through roll story new and update backlog.
+6. Self-score the design quality.
 
 ## Hard Gates
 
 - Do not start implementation from this skill.
 - Backlog rows and spec files must stay consistent.
 - Peer review gates apply only when explicitly available/requested.
+- No story decomposition until a detailed design exists and the owner has signed off (proportional to risk). Decomposition slices an agreed design — it is NOT a substitute for designing. If you cannot show at least one complete worked sample of the intended output/behavior, the design is NOT done.
 
 ## Gotchas
 
 - Design writes backlog/spec artifacts; it must not quietly start code implementation.
 - Use roll story new for story directories; do not hand-create backlog rows without matching dossier structure.
+- Jumping from idea straight to INVEST stories (skipping detailed design) produces shallow specs and improvised, inconsistent implementation. Decomposition must slice a concrete, owner-agreed detailed design — schema + at least one complete worked sample + interfaces + mapping rules + edge cases.
 
 ## Maintenance
 

package/skills/roll-design/references/engineering-checklist.md

@@ -200,12 +200,28 @@ it('should handle concurrent writes', async () => {
 
 ---
 
+## 9. Detailed Design Completeness 📐
+
+**Definition:** Before decomposing work into stories, the detailed design must be concrete and implementable — not a sketch.
+
+**Must include (proportional to risk/novelty):**
+- [ ] Data/contract **schema**
+- [ ] **At least one complete worked sample** of the intended output/behavior
+- [ ] Key **interface signatures**
+- [ ] **Mapping/normalization rules**
+- [ ] **Edge cases & failure modes**
+
+**Rule:** If you cannot show at least one complete worked sample, the design is NOT done. Decomposition slices an agreed design — it is not a substitute for designing.
+
+---
+
 ## Mandatory Check Process
 
 During the **Test Design Review** phase of each Story, the following must be answered:
 
 ```markdown
 ### Engineering Common Sense Checklist
+- [ ] **Detailed design completeness**: Does the detailed design include at least one complete worked sample plus schema, interface signatures, mapping rules, and edge cases?
 - [ ] **Idempotency**: Can it be run repeatedly? Are there tests?
 - [ ] **Cross-module contract**: Are IDs/formats/algorithms consistent?
 - [ ] **Data flow**: Is the producer → consumer pipeline complete?

package/skills/roll-design/references/full-contract.md

@@ -176,7 +176,7 @@ Expected AC:
 Input: IDEA-NNN identifier from .roll/backlog.md
 
 Execution path:
-  [Read .roll/backlog.md IDEA-NNN row] → [Analyze] → [DDD Slice] → [Split Stories]
+  [Read .roll/backlog.md IDEA-NNN row] → [Analyze] → [DDD Slice] → [Solution Design] → [Split Stories]
       → [Write BACKLOG 📋 Todo] → [Annotate IDEA row: → US-XXX] → Done
 
 IDEA annotation: append `→ US-XXX` to the IDEA row's Description column.
@@ -289,10 +289,22 @@ User Input
                                          │
                                          ▼
               ┌─────────────────────────────────────────┐
-              │ 3. Solution Design                       │
-              │    - Architecture design                 │
-              │    - Module decomposition                │
+              │ 3. Detailed (Solution) Design  ★MANDATORY│
+              │    Before ANY decomposition, for         │
+              │    non-trivial work produce a concrete,  │
+              │    implementable artifact (depth scales  │
+              │    with risk/novelty):                   │
+              │    - Architecture / module decomposition │
               │    - Dependency analysis                 │
+              │    Required artifacts (all of):          │
+              │      (a) data/contract schema            │
+              │      (b) ≥1 COMPLETE worked sample of    │
+              │          the intended output/behavior    │
+              │      (c) key interface signatures        │
+              │      (d) mapping/normalization rules     │
+              │      (e) edge cases & failure modes      │
+              │    Rule: if you cannot show a complete   │
+              │    worked sample, the design is NOT done.│
               │    [Greenfield] Tactical Model per Context:
               │      - Aggregate Root + Entities + VOs  │
               │      - Invariants (业务不变式)           │
@@ -312,6 +324,15 @@ User Input
                                  │ AGREE / skipped
                                  ▼
               ┌─────────────────────────────────────────┐
+              │ [gate] Owner Sign-off on Detailed Design │  ← REQUIRED before decomposition
+              │    Decomposition slices an AGREED design;│
+              │    it does NOT replace designing. Get    │
+              │    owner sign-off (proportional to risk) │
+              │    before splitting into stories.        │
+              └──────────────────┬──────────────────────┘
+                                 │ Signed off
+                                 ▼
+              ┌─────────────────────────────────────────┐
               │ 4. Split into Stories                    │
               │    - INVEST principles                   │
               │    - Bounded Context → US domain prefix  │