@galda/cli 0.10.40 → 0.10.41

package/engine/lib.mjs

@@ -227,7 +227,13 @@ export function buildExecutionPlan({ projectId = null, text = '', usage = null,
     session.mode === 'compact' ? 'compact handoff' : null,
     session.mode === 'cold-handoff' ? 'fresh handoff' : null,
     session.mode === 'cold' ? '/clear equivalent' : null,
-    workerPolicy.reason ? 'worker policy' : null,
+    // 'worker policy' used to be listed here and it never was one: the effort
+    // chooseWorkerPolicy picks is not applied to the worker (it only reaches the
+    // handoff prompt as a sentence), and Masa ruled on 2026-07-22 that it must
+    // NOT start being applied — guessing effort from keywords in the request is
+    // the request-classification this layer is not allowed to do. A technique
+    // list that names something we did not do is what makes the saved figure
+    // untrustworthy, so it is gone rather than kept as a label.
   ].filter(Boolean);
   return {
     projectGroupId: projectId,
@@ -301,15 +307,20 @@ export function estimateTokenOptimization({ usage = null, weightedTokens = null,
   const perReq = weighted / reqN;
   const baseline = tokenBaselinePerRequirement(history);
 
-  let percent, basis, savedTokens;
+  // A percentage is only claimed against this user's own recent runs. The old
+  // fallback — with no history, score the run against its own cache-weighting —
+  // produced the number the PRD itself called out as a perverse incentive: the
+  // MORE context a run dragged along, the bigger its cache read, and the better
+  // the "saving" looked. That made the first runs of every new install, the
+  // ones with no history, the ones that bragged most (Masa 2026-07-22). Now
+  // there is simply no percentage until there is something real to compare to;
+  // the tokens and the techniques below still ship, so the card shows facts
+  // instead of a flattering ratio.
+  let percent = null, basis = 'no-baseline', savedTokens = null;
   if (baseline != null) {
     percent = Math.max(-100, Math.min(100, Math.round(((baseline - perReq) / baseline) * 100)));
     basis = 'baseline';
     savedTokens = Math.max(0, Math.round((baseline - perReq) * reqN));
-  } else {
-    savedTokens = Math.max(0, raw - weighted);
-    percent = Math.round((savedTokens / raw) * 100);
-    basis = 'cache-weight';
   }
 
   // "why": always at least one concrete, data-derived sentence — never a
@@ -320,7 +331,10 @@ export function estimateTokenOptimization({ usage = null, weightedTokens = null,
   if (usedHandoff || sessionMode === 'cold-handoff') techniques.push('fresh handoff instead of a bloated session');
   if (usedCompact || sessionMode === 'compact') techniques.push('/compact before continuing');
   if (usedClear) techniques.push('/clear between unrelated goals');
-  if (agentModel) techniques.push(`${agentModel} for this run`);
+  // The model is NOT listed any more. Naming it here read as something this
+  // layer did to save tokens, and it is the opposite: the model is the user's
+  // own pick from the composer, and we deliberately never override it
+  // (Masa 2026-07-22). Every remaining line is an action this layer took.
   if (basis === 'baseline' && percent > 0) {
     techniques.push(`${Math.round(perReq / 1000)}k tokens/requirement vs your ${Math.round(baseline / 1000)}k average`);
   }
@@ -744,65 +758,51 @@ export function refinePlanTasks(tasks, { goalText, maxTasks = 4 } = {}) {
   return userTitled(real.slice(0, maxTasks));
 }
 
-// ---- dedupe / merge overlapping goals --------------------------------------
-// Masa (dogfood): 「被ったやつも自分でちゃんと理解してまとめてほしい」。When a
-// new goal near-duplicates an existing active one, fold it in as a follow-up
-// instead of piling up a redundant parallel goal.
+// ---- dedupe / merge overlapping goals — REMOVED 2026-07-22 ----------------
+// normalizeGoalText / goalTextSimilarity / findOverlappingGoal lived here: a
+// word-overlap score that folded a new request into an in-flight goal whenever
+// the two texts scored >= 0.72 alike. Deleted with its call site
+// (docs/design/ONE-CONVERSATION.md §1.2) — it was our layer deciding "this is
+// probably the same thing" on the user's behalf. See parseGoalAddress below:
+// the person names the ticket, or the request becomes its own.
+
+// ---- the conversation on a goal (docs/design/ONE-CONVERSATION.md §1.1) -----
+// 「1本の会話・複数の入口」の入れ物。今日までの連続性は Claude Code 側の
+// sessionId だけに預けてあり、上書きされたり resume に失敗すると我々の側には
+// 何も残らなかった。ゴール自身がやりとりを持てば、セッションが飛んでも人には
+// 見える。
 //
-// Normalize goal text for overlap comparison: lowercase, collapse whitespace
-// (incl. full-width space), strip punctuation — so "PRDを作って！" and
-// "prd を 作って" compare alike.
-export function normalizeGoalText(text) {
-  return String(text ?? '')
-    .toLowerCase()
-    .replace(/[\s　]+/g, ' ')
-    .replace(/[、。，．,.!！?？「」『』（）()\[\]{}"'`~・…—\-_/\\:;]/g, '')
-    .replace(/\s+/g, ' ')
-    .trim();
+// 原則（Masa確定 2026-07-22）:
+//   - 要約しない・分類しない・間引かない。言われた言葉をそのまま全件。
+//   - 1発言の長さにだけ上限（極端な貼り付けで記録が壊れないように）。
+//   - /api/state には載せない。開いた時だけ取りに行く（実装ログ #234/#238 と同じ形）。
+export const MESSAGE_TEXT_LIMIT = 8000;
+export const MESSAGE_FROM = ['you', 'ai', 'manager'];
+export const MESSAGE_VIA = ['composer', 'review', 'thread'];
+
+// 1発言を正規化する。text が空なら null（空の発言は記録しない＝無いものを
+// 残さない）。from/via が未知なら記録側の都合で捨てず、既定に寄せる。
+export function buildGoalMessage({ from, via, text, at } = {}) {
+  const body = String(text ?? '').trim();
+  if (!body) return null;
+  return {
+    at: at || new Date().toISOString(),
+    from: MESSAGE_FROM.includes(from) ? from : 'manager',
+    via: MESSAGE_VIA.includes(via) ? via : 'composer',
+    text: body.slice(0, MESSAGE_TEXT_LIMIT),
+  };
 }
 
-// Similarity 0..1 between two goal texts. Combines word tokens with CJK
-// bigrams (Japanese has no spaces, so word-splitting alone can't compare
-// 日本語同士) into a Jaccard overlap; identical normalized text short-circuits
-// to 1. Pure and symmetric.
-export function goalTextSimilarity(a, b) {
-  const na = normalizeGoalText(a), nb = normalizeGoalText(b);
-  if (!na || !nb) return 0;
-  if (na === nb) return 1;
-  const toks = (s) => {
-    // Latin/alphanumeric WORDS (≥2 chars) + CJK BIGRAMS. Bigrams matter because
-    // Japanese has no spaces — splitting on ' ' alone would make the whole
-    // spaceless string one giant token and never compare 日本語同士.
-    const set = new Set((s.match(/[a-z0-9]{2,}/g) ?? []));
-    const cjk = s.replace(/[^぀-ヿ一-鿿]/g, '');
-    for (let i = 0; i < cjk.length - 1; i++) set.add(cjk.slice(i, i + 2));
-    return set;
-  };
-  const sa = toks(na), sb = toks(nb);
-  if (!sa.size || !sb.size) return 0;
-  let inter = 0;
-  for (const t of sa) if (sb.has(t)) inter++;
-  return inter / (sa.size + sb.size - inter);
-}
-
-// Find an existing goal a new goal's text substantially overlaps (near
-// duplicate), so the caller can fold it in as a thread follow-up rather than
-// create a redundant parallel goal. `existingGoals` is expected to be already
-// filtered by the caller to real merge candidates (same project, active,
-// session-bearing). Returns { goal, score } only on HIGH confidence
-// (threshold 0.72); when unsure, null → the caller creates the goal, so a
-// genuinely distinct ask is never silently swallowed. Very short texts
-// (< 6 normalized chars) never match — too little signal to be sure.
-export const GOAL_OVERLAP_THRESHOLD = 0.72;
-export function findOverlappingGoal(text, existingGoals, { threshold = GOAL_OVERLAP_THRESHOLD } = {}) {
-  if (normalizeGoalText(text).length < 6) return null;
-  let best = null, bestScore = 0;
-  for (const g of existingGoals ?? []) {
-    if (normalizeGoalText(g?.text).length < 6) continue;
-    const score = goalTextSimilarity(text, g?.text);
-    if (score > bestScore) { bestScore = score; best = g; }
-  }
-  return best && bestScore >= threshold ? { goal: best, score: bestScore } : null;
+// JSONL 1行 ⇄ 発言。壊れた行は黙って捨てる（1行の破損で会話全部を失わない）。
+export function serializeGoalMessage(msg) { return JSON.stringify(msg); }
+export function parseGoalMessages(raw) {
+  return String(raw ?? '').split('\n').map((line) => {
+    if (!line.trim()) return null;
+    try {
+      const m = JSON.parse(line);
+      return (m && typeof m.text === 'string') ? m : null;
+    } catch { return null; }
+  }).filter(Boolean);
 }
 
 // ---- which goal states allow EDIT / DELETE from the board ------------------
@@ -883,6 +883,24 @@ export function isForcedStop(code, timedOut) {
   return Boolean(timedOut) || code === 143 || code === 130;
 }
 
+// What a task's status is once the worker has stopped and any check has run.
+//
+// The one thing that changed (Masa 2026-07-22): a check that RAN AND FAILED no
+// longer scores the task 'failed', and (at the call site) no longer sends the
+// worker back for another attempt. Both were how a wrong check turned into real
+// damage — a run measured on 2026-07-22 failed a check that was looking at a
+// file the worker never made, and the rework it triggered spent >100k tokens
+// pushing the work toward that wrong target. A check we authored can be wrong
+// about the work; the work cannot be wrong about itself. So a failing check is
+// now what an inconclusive one already was: a note for the human in review,
+// never a verdict that manufactures a failure. A PASS still wins outright — it
+// is evidence, and evidence beats an exit code.
+export function taskStatusAfterVerify({ verdict, code, timedOut }) {
+  if (verdict?.pass) return 'done';
+  if (isForcedStop(code, timedOut)) return 'interrupted';
+  return code === 0 ? 'done' : 'failed';
+}
+
 // A task counts as complete for GOAL status when it cleanly finished
 // (done/skipped) OR it was force-stopped (interrupted) but its change is STRONGLY
 // verified — an independent passCondition verification PASSED (proof.verified &&
@@ -1404,18 +1422,18 @@ export function groupTasksByGoalOrdered(tasks, goals) {
   return order.map((key) => ({ goal: key == null ? null : byId.get(key), tasks: map.get(key) }));
 }
 
-// A goal's review number must stay stable while sibling reviews get
-// Approved and drop out of the list — an index-based "R1/R2/R3" reflows
-// every time one is removed (task 118: "R2をApproveした後にまた別のがR2に
-// なる"). Use the goal's own original TODO number instead: the lowest
-// task.num among the tasks that belong to it (its first-decomposed task).
-export function goalReviewNumber({ goal, tasks } = {}) {
-  if (goal == null) return null;
-  const nums = (tasks ?? [])
-    .filter((t) => t.goalId === goal.id)
-    .map((t) => t.num)
-    .filter((n) => typeof n === 'number' && Number.isFinite(n));
-  return nums.length ? Math.min(...nums) : null;
+// A goal's number must stay stable while sibling reviews get Approved and drop out of
+// the list — an index-based "R1/R2/R3" reflows every time one is removed (task 118:
+// "R2をApproveした後にまた別のがR2になる"). It is the goal's OWN id: unique, permanent,
+// and the number every screen already prints (app/index.html's own goalReviewNumber has
+// returned goal.id since the CDO review 2026-07-08 §1).
+//
+// This one used to return the goal's lowest task.num instead — so the same ticket was
+// called #4 by the engine's own digests and #5 by every screen. Measured on the resident
+// instance 2026-07-22: of 214 goals the two numbers agreed exactly ONCE and differed 184
+// times. One card, one request, one number (galda-one-card-one-request).
+export function goalReviewNumber({ goal } = {}) {
+  return goal == null ? null : goal.id;
 }
 
 // Review digest (task 227): one row per review-pending goal, collapsed to a
@@ -1710,11 +1728,114 @@ export function approveGoal({ goalStatus, hasPr = false }) {
   return { ok: true, status: 'done' };
 }
 
-// Dismiss(差し戻し)は 'running' に戻す——チャット(/reply や /dismiss にテキスト)での
-// 「作り直し」依頼の受け皿。goalGroupStatus は startedAt 済みなら 'doing' に読む。
-export function dismissGoal({ goalStatus }) {
+// 返事の行き先（docs/design/ONE-CONVERSATION.md §1.3）
+//
+// Dismiss は長いあいだ一本道だった——何を言っても必ず 'running'（＝すぐ作り直し）。
+// だが人が返す言葉は3種類ある: 「このまま直して」「いったん止めて考え直す」「それは別件」。
+// 一本道だと後ろ2つが表現できず、考え直したいだけの時にもワーカーが走り出す。
+//
+//   continue … 今までと同じ。Doing に戻して同じ会話を resume する（既定）
+//   rescope  … 止めて考え直す。To Do の下（pending）へ park し、ワーカーは起こさない。
+//              呼び出し側がゴールの文章そのものを新しい言葉に差し替える
+//              ——チケットの文章が書き換わるのはここだけ
+//   split    … 別件。このゴールには触らず、呼び出し側が新しいゴールを作る
+//   answer   … 聞いてるだけ。何も動かさない。Review のまま、コードも触らせず、
+//              作業した AI 本人が読み取り専用で答えるだけ（会話に1発言積む）
+//
+// なぜ rescope が 'pending' か: 「走らせずに一覧に戻す」意味を持つ状態はこれだけ。
+// 'stacked' は空きが出ると自動で走り出す（server の pump）ので「考え直す」にならない。
+//
+// なぜ answer が要るか (PRD §5.6・Masa確定 2026-07-22): 返事は中身に関わらず全部
+// 「直して」に落ちていた——「なんでこうしたの？」と聞いただけでゴールが Doing に
+// 戻り、ワーカーが起き、コードが変わり始める。聞いただけで作り直しが始まるのは
+// 壊れている。answer は goalStatus をそのまま返す＝1ビットも動かさない。
+export const REPLY_OUTCOMES = ['continue', 'rescope', 'split', 'answer'];
+export function dismissGoal({ goalStatus, outcome = 'continue' } = {}) {
   if (goalStatus !== 'review') return { ok: false, error: 'goal is not in review' };
-  return { ok: true, status: 'running' };
+  const which = REPLY_OUTCOMES.includes(outcome) ? outcome : 'continue';
+  if (which === 'rescope') return { ok: true, outcome: which, status: 'pending', spawnsWorker: false, rewritesText: true };
+  if (which === 'split') return { ok: true, outcome: which, status: goalStatus, spawnsWorker: false, splits: true };
+  if (which === 'answer') return { ok: true, outcome: which, status: goalStatus, spawnsWorker: false, answers: true };
+  return { ok: true, outcome: 'continue', status: 'running', spawnsWorker: true };
+}
+
+// 誰が決めるか＝**AI本人** (docs/design/ONE-CONVERSATION.md §1.4)
+//
+// 返事が来た時、それが「このまま直して」なのか「考え直したい」なのか「別件」なのか
+// 「ただ聞いただけ」なのかを、**我々の層で当てない**。キーワードでも類似度でもなく、
+// 人の言葉を1回だけ AI に渡して、返ってきた答えのとおりに配線する。0.72 の自動合流を
+// 消したのと同じ理由——この層が人の意図を推測し始めると、外れた時に黙って別のことを
+// する（今日そこを1つずつ潰してきた）。
+//
+// 迷った時だけ人に聞く: AI が unsure と答えたら**ゴールに触らず**選択肢を返す。人は
+// モードを普段選ばない。迷った時だけ選ぶ。
+export const REPLY_INTENTS = [...REPLY_OUTCOMES, 'unsure'];
+export function buildReplyIntentPrompt({ goalText, reply } = {}) {
+  return [
+    'You route replies in Agent Manager: a person delegated a coding task, an AI did it, and it came back for review. The person has now replied.',
+    'Decide what the reply ASKS FOR — exactly one of:',
+    '- "continue": fix or change the work that was just done (the usual case).',
+    '- "rescope": stop and rethink; the request itself should now say something different.',
+    '- "split": a separate piece of work that should not touch this one.',
+    '- "answer": a question about the work. Nothing should be built or changed — they want to know something.',
+    '- "unsure": you genuinely cannot tell. Prefer this over guessing: the person will be shown the choices.',
+    'Judge the reply on its own words. Do not treat a question mark as proof of "answer", or an imperative as proof of "continue" — "why is this red? make it blue" asks for a change.',
+    'Output ONLY one line of raw JSON: {"outcome":"continue|rescope|split|answer|unsure"}. No markdown, no code fence, no other text.',
+    '',
+    'The request that was worked on:',
+    String(goalText ?? '').slice(0, 2000),
+    '',
+    'Their reply:',
+    String(reply ?? '').slice(0, 4000),
+  ].join('\n');
+}
+
+// Tolerant parser — never throws. It returns TWO things, and the difference
+// between them is the whole point:
+//
+//   read: true  … the AI answered, and we understood it. 'unsure' here means the
+//                 AI genuinely could not tell → ask the person (§1.4).
+//   read: false … we could not get an answer at all (no agent installed, offline,
+//                 rate-limited, garbled output). The AI never said anything, so
+//                 there is nobody to have been unsure.
+//
+// Treating those two the same is a real bug, found by an existing test on
+// 2026-07-22: on a machine with no agent, a reply stopped doing ANYTHING — it put
+// the four choices on screen and waited. But if the agent cannot be reached, no
+// answer can be written either; the only useful thing a reply can still do is
+// what it always did — go back as rework, and run when the agent returns.
+// So the caller falls back to 'continue' when read is false. That is not a guess
+// about what the person meant: it is the documented default this endpoint has
+// always had when no outcome is given.
+export function parseReplyIntent(raw) {
+  const unread = { outcome: 'unsure', read: false };
+  if (!raw || typeof raw !== 'string') return unread;
+  const m = raw.match(/\{[\s\S]*\}/);
+  if (!m) return unread;
+  let obj;
+  try { obj = JSON.parse(m[0]); } catch { return unread; }
+  if (!REPLY_INTENTS.includes(obj?.outcome)) return unread;   // answered, but not in our words
+  return { outcome: obj.outcome, read: true };
+}
+
+// 宛先（docs/design/ONE-CONVERSATION.md §1.2）
+//
+// チャットで「#12 の件だけど」と書けたら、そのチケット宛て。**決定論で、我々の推測は
+// ゼロ**。これが要るのは、今まで「同じ話かどうか」を我々の層が文字列の似かた（0.72）で
+// 当てずっぽうに決めていたから——当たれば黙って合流し、外れれば別のカードが生えた。
+// 人が番号を書けるなら、推測する理由が無い。
+//
+// 最初の `#N` だけを見る。番号が実在しなければ宛先なしとして扱う（＝ふつうに新しい
+// チケットになる）ので、`#` を含むだけの文章がどこかへ黙って吸い込まれることはない。
+// 本文は削らない: 言われた言葉をそのまま作業AIへ渡す（P0 の「原文100%」と同じ約束）。
+export function parseGoalAddress(text) {
+  // `(?![\w-])` ＝「番号の直後に英数字やハイフンが続くなら、それは番号ではない」:
+  // `#1f6f4a`(色) や `#12-3` を宛先と読み違えない。日本語は \w に入らないので
+  // 「#12の件だけど」はちゃんと宛先になる。
+  const m = /(?:^|[\s（(「【])#(\d+)(?![\w-])/.exec(String(text ?? ''));
+  if (!m) return null;
+  const goalId = Number(m[1]);
+  return Number.isSafeInteger(goalId) && goalId > 0 ? { goalId } : null;
 }
 
 // Reject（07-20c・Dismiss とは別物）は自動再作業をせず、Rejected 欄に溜める 'rejected'
@@ -2342,7 +2463,7 @@ export function workerPrompt(task, goal, lastFailure, agentName = 'claude-code')
     // it is the one that says how to run it. Requests with nothing to run
     // (research, summaries, answers) simply skip this — the worker decides,
     // never us.
-    `- 人が実際に動かして結果を見られる依頼なら、最後にプロジェクト直下へ ${RUN_DECL_FILE} を書く: {"cmd": "<起動コマンド>", "url": "<開くURL>", "note": "<何が見えるか1行>", "check": "<人に何を見て判断してほしいか1行>"}。Manager はこれを使って人に「動かして見る」と「何を見ればいいか」を出す。動かして見せるものが無い依頼（調査・要約・質問への回答など）では書かなくてよい。`,
+    `- 人が実際に動かして結果を見られる依頼なら、最後にプロジェクト直下へ ${RUN_DECL_FILE} を書く: {"cmd": "<起動コマンド>", "url": "<開くURL>", "note": "<何が見えるか1行>", "check": "<人に何を見て判断してほしいか1行>", "title": "<この作業のチケット名。対象が分かる程度に説明的で動作を含む短い名前。例「看板モードの追加」「ヘッダのズレの修正」。依頼文をそのまま写さない>"}。Manager はこれを使って人に「動かして見る」と「何を見ればいいか」を出す。動かして見せるものが無い依頼（調査・要約・質問への回答など）では書かなくてよい。`,
     // Links are rendered as links. The product cannot tell a real one from a
     // decorative one, so the only place this can be held is here.
     `- 自分が作っていない場所へのリンクを報告に書かない（存在しないURLや「詳しくはここ」のような飾りのリンクは、そのままリンクとして人に表示される）。`,
@@ -2357,7 +2478,11 @@ export function workerPrompt(task, goal, lastFailure, agentName = 'claude-code')
     // anyway is not a harmless extra line: the Codex worker tried four times,
     // then reported the failure instead of the work. Do not ask an agent for
     // something this machine has proven it cannot do (Masa 2026-07-22).
-    agentName === 'codex' ? '' : `- 画面・見た目のあるものを作ったなら、自分でスクリーンショットを撮って見せてよい: \`node ${SHOT_CLI} <URL または HTMLファイル> ${SHOT_DIR}/<名前>.png [--full] [--wait-for <CSSセレクタ>]\`（headless Chrome・前面に出ない）。${SHOT_DIR}/ に置いた画像は Manager が回収して人に見せる（diff には入らない）。撮ったものは Read で自分でも見返せる。`,
+    agentName === 'codex' ? '' : `- 画面・見た目のあるものを作ったなら、自分でスクリーンショットを撮って見せてよい: \`node ${SHOT_CLI} <URL または HTMLファイル> ${SHOT_DIR}/<名前>.png [--full] [--wait-for <CSSセレクタ>] [--element <CSSセレクタ>] [--clip x,y,幅,高さ]\`（headless Chrome・前面に出ない）。変えた場所が小さいなら --element / --clip でそこだけ撮ってよい（ページ全体を撮って「どこが違うか探して」にしない）。${SHOT_DIR}/ に置いた画像は Manager が回収して人に見せる（diff には入らない）。撮ったものは Read で自分でも見返せる。`,
+    // The pair, declared by the only party that can know it. Deliberately not
+    // "take a before shot before you start": that would be this layer deciding
+    // the request is a change-something request, and most requests are not.
+    agentName === 'codex' ? '' : `- 同じ画面の「変える前」と「変えた後」を撮ったなら、${RUN_DECL_FILE} に \`"compare": ["<前の画像>.png", "<後の画像>.png"]\` と書いてよい（その2枚が同じ場所の前後だと分かるのは撮った本人だけ）。人には並べて、違う部分に印を付けて見せる。3案を並べた等、前後の関係が無い画像には書かない。`,
     `- 最後に${replyLang}で2〜4行：何を変えたか・どのファイルか・テスト結果・人間が確認すべき点。`,
   ].filter(Boolean).join('\n');
 }
@@ -2383,15 +2508,42 @@ export function parseRunDeclaration(text) {
   const str = (v, max) => (typeof v === 'string' && v.trim() ? v.trim().slice(0, max) : null);
   const cmd = str(raw.cmd, 500);
   const url = str(raw.url, 500);
-  // Nothing to start and nothing to open = nothing to look at.
-  if (!cmd && !url) return null;
+  // `compare` (Masa 2026-07-22): which TWO of the worker's own screenshots are
+  // the same view before and after. Only the agent that did the work knows that
+  // two images relate — a request for three design options has no "after" at
+  // all — so this layer must never infer it. (The app briefly guessed the pair
+  // from file names containing "before"/"after": the same mistake as the intake
+  // AI writing a pass condition, and it is not repeated here.)
+  const compare = parseComparePair(raw.compare);
+  const title = str(raw.title, 60);
+  // Nothing to start, nothing to open, nothing named, and no pair to show = nothing to look at.
+  if (!cmd && !url && !compare && !title) return null;
   // Only http(s): the button opens this in the user's browser.
   if (url && !/^https?:\/\//i.test(url)) return null;
   // `check` (Masa 2026-07-22): what to look at, in the working AI's own words. It used
   // to come from the intake AI's plan — this layer inventing a pass condition for a
   // request it only read. The AI that did the work states it here instead, in the same
   // file it already writes, and the review card shows that sentence verbatim.
-  return { cmd, url, note: str(raw.note, 300), check: str(raw.check, 300) };
+  // `title` (Masa 2026-07-22): the ticket name, from the AI that did the work.
+  // Until now the name came from a summarizer LLM down here, and when that call
+  // returned nothing the card fell back to the raw request — so the "title" was
+  // the user's own sentence, repeated back at them in the one place that is
+  // supposed to say what the work WAS. The agent that just did it can name it in
+  // one line, and it is the only party that knows what actually got done.
+  return { cmd, url, note: str(raw.note, 300), check: str(raw.check, 300), compare, title };
+}
+
+// Exactly two shot file names, in [before, after] order. Anything else is
+// dropped rather than half-accepted: the card draws a red box over the region
+// that differs between the two, and a box drawn over the wrong pair is the
+// fabricated-evidence bug again. Names only — a path would let a declaration
+// point outside the shots the Manager collected.
+export function parseComparePair(value) {
+  if (!Array.isArray(value) || value.length !== 2) return null;
+  const names = value.map((v) => (typeof v === 'string' ? v.trim() : '')).map((n) => n.replace(/^.*[/\\]/, ''));
+  if (names.some((n) => !n || n.length > 120)) return null;
+  if (names[0] === names[1]) return null; // a picture compared with itself shows nothing
+  return names;
 }
 
 // ---- SHOTS: the worker's own camera ----------------------------------------
@@ -2439,11 +2591,11 @@ export function pickChromePath(env = {}, exists = () => false) {
 }
 
 // `node <manager>/engine/shot.mjs <url|file> <out.png> [--width N] [--height N]
-//  [--full] [--wait MS] [--wait-for SELECTOR]`
+//  [--full] [--wait MS] [--wait-for SELECTOR] [--element SELECTOR] [--clip x,y,w,h]`
 // Returns { error } instead of throwing, so the CLI can print one clear line.
 export function parseShotArgs(argv = []) {
   const rest = [];
-  const opt = { width: 1440, height: 900, full: false, wait: 0, waitFor: null };
+  const opt = { width: 1440, height: 900, full: false, wait: 0, waitFor: null, element: null, clip: null };
   const num = (v, lo, hi) => {
     const n = Number(v);
     return Number.isFinite(n) && n >= lo && n <= hi ? Math.round(n) : null;
@@ -2466,12 +2618,33 @@ export function parseShotArgs(argv = []) {
       if (!sel) return { error: '--wait-for needs a CSS selector' };
       opt.waitFor = sel; continue;
     }
+    // Region (Masa 2026-07-22). A full-page picture of a one-component change
+    // hands the reviewer a page and asks them to find the difference — and the
+    // agent that made the change is the only one who knows where to point. Two
+    // ways in: a selector when the worker has one, coordinates when it doesn't.
+    if (a === '--element') {
+      const sel = String(argv[++i] ?? '').trim();
+      if (!sel) return { error: '--element needs a CSS selector' };
+      opt.element = sel; continue;
+    }
+    if (a === '--clip') {
+      const parts = String(argv[++i] ?? '').split(',').map((s) => s.trim());
+      if (parts.length !== 4) return { error: '--clip needs x,y,width,height (e.g. --clip 0,0,800,400)' };
+      const [x, y, width, height] = parts.map((v, idx) => num(v, idx < 2 ? 0 : 1, 20000));
+      if ([x, y, width, height].some((n) => n == null)) return { error: '--clip needs four numbers: x,y,width,height' };
+      opt.clip = { x, y, width, height }; continue;
+    }
     if (a.startsWith('--')) return { error: `unknown option ${a}` };
     rest.push(a);
   }
   const [target, out] = rest;
-  if (!target || !out) return { error: 'usage: node engine/shot.mjs <url|file> <out.png> [--width N] [--height N] [--full] [--wait MS] [--wait-for SELECTOR]' };
+  if (!target || !out) return { error: 'usage: node engine/shot.mjs <url|file> <out.png> [--width N] [--height N] [--full] [--wait MS] [--wait-for SELECTOR] [--element SELECTOR] [--clip x,y,w,h]' };
   if (!/\.png$/i.test(out)) return { error: 'output must end in .png' };
+  // One region, not two — a selector and a rectangle disagree the moment the
+  // page reflows, and silently preferring one would make the picture a guess.
+  if (opt.element && opt.clip) return { error: 'use --element or --clip, not both' };
+  // A region IS the framing, so --full has nothing left to mean.
+  if (opt.full && (opt.element || opt.clip)) return { error: '--full cannot be combined with --element/--clip' };
   return { target, out, ...opt };
 }
 
@@ -3517,6 +3690,15 @@ export function needsProjectFolder({ dir, homeDir, isRepo } = {}) {
   return !isRepo;
 }
 
+// The repo's own name: the last segment of its path. The composer chip prints this and
+// the folder menu prints it again on every row, so it lives here as one function — two
+// copies of "take the last segment" is how a chip and its own menu start disagreeing
+// (CDO handoff 2026-07-23 §A2). Trailing slashes are the caller's typo, not a segment.
+export function folderName(dir) {
+  const d = String(dir ?? '').replace(/\/+$/, '');
+  return d ? d.split('/').pop() : '';
+}
+
 // A short, ≤60-char display label for a repo dir, shown home-relative (~/…) so
 // the folder-choice options read cleanly on the board card.
 export function folderLabel(dir, homeDir = '') {