@galda/cli 0.10.37 → 0.10.39

package/engine/lib.mjs

@@ -590,6 +590,40 @@ export function isEngineeringPhaseTitle(title) {
   return ENGINEERING_PHASE_RE.test(String(title ?? ''));
 }
 
+// ---- title = the user's REQUEST, not a completion report -------------------
+// Masa (goal #474): the planner echoed a worker's finished-work sentence as the
+// title —「アニメーションが終わってから歯車の位置を計算するように直した」— instead of
+// naming what the user asked for. A title should read like the ask ("…のバグ修正"),
+// never like a past-tense report of HOW it was implemented. Detect that shape so
+// we can fall back to the user's own words. NARROW on purpose: only past-tense
+// completion phrasing (…した/…ました, "…ように直/修/変") — a genuine request title
+// never ends that way.
+const IMPL_REPORT_RE = /(直し|修正し|変更し|追加し|対応し|実装し|計算する|するように|完了し)(た|ました)?/;
+const PAST_DONE_RE = /(直した|修正した|変更した|追加した|対応した|実装した|しました|ました|するように直|するように修正|するように変更)/;
+export function isImplementationReportTitle(title) {
+  const s = String(title ?? '').trim();
+  if (!s) return false;
+  // Report shape = past-tense completion OR "…するように<動詞>" (describes the how).
+  return PAST_DONE_RE.test(s) || (/するように/.test(s) && IMPL_REPORT_RE.test(s));
+}
+
+// Derive a short, user-worded title from the raw request text. Strips the polite
+// request tail (…して/してください/直して/お願いします 等) so the title reads as the
+// thing itself (「…バグ修正して」→「…バグ修正」) — the user's words, not a rephrase.
+export function titleFromRequest(goalText, max = 60) {
+  let s = String(goalText ?? '').replace(/\s+/g, ' ').trim();
+  if (!s) return '';
+  // Drop a trailing polite/imperative request tail so the noun-phrase remains.
+  // Order matters: strip the courtesy suffix first, then the verb 直す ("…を直して"
+  // is a verb — drop the whole thing), then the する light verb ("…修正して" keeps
+  // the noun 修正, drops only して).
+  s = s.replace(/[\s、。，．,.!！?？]*(?:お願いします|おねがいします|お願い|please)[。.!！]*$/iu, '')
+       .replace(/[\s、。，．,.!！?？]*(?:を)?直して(?:ください|下さい|くれ|ほしい|欲しい)?[。.!！]*$/u, '')
+       .replace(/[\s、。，．,.!！?？]*して(?:ください|下さい|くれ|ほしい|欲しい)?[。.!！]*$/u, '')
+       .trim();
+  return s.slice(0, max);
+}
+
 // Reduce a planner's task list to USER-TOPIC granularity — the deterministic
 // backstop for when the LLM over-decomposes despite the prompt. Two moves, both
 // conservative so a distinct ask is never silently dropped:
@@ -603,7 +637,13 @@ export function isEngineeringPhaseTitle(title) {
 // worker still owns the full engineering breakdown internally.
 export function refinePlanTasks(tasks, { goalText, maxTasks = 4 } = {}) {
   const list = (tasks ?? []).filter((t) => t && String(t.title ?? '').trim());
-  if (list.length <= 1) return list.slice(0, maxTasks);
+  // A title that reads as a completion report ("…するように直した") is replaced with
+  // the user's own request wording. Only safe when there's a single topic — with
+  // multiple distinct deliverables the goal text can't stand in for any one title.
+  const userTitled = (arr) => arr.length === 1 && isImplementationReportTitle(arr[0].title) && titleFromRequest(goalText)
+    ? [{ ...arr[0], title: titleFromRequest(goalText) }]
+    : arr;
+  if (list.length <= 1) return userTitled(list.slice(0, maxTasks));
   const real = list.filter((t) => !isEngineeringPhaseTitle(t.title));
   if (!real.length) {
     const title = String(goalText ?? list[0].title).replace(/\s+/g, ' ').trim().slice(0, 120);
@@ -611,7 +651,7 @@ export function refinePlanTasks(tasks, { goalText, maxTasks = 4 } = {}) {
     const passCondition = list.find((t) => t.passCondition)?.passCondition ?? null;
     return [{ title, detail, passCondition }];
   }
-  return real.slice(0, maxTasks);
+  return userTitled(real.slice(0, maxTasks));
 }
 
 // ---- dedupe / merge overlapping goals --------------------------------------
@@ -870,8 +910,30 @@ export function buildGoalPrBody({ lang, goal, goalTasks, files, owner, branch, p
     L(`Implemented by Manager for AI: the goal was decomposed into ${goalTasks.length} task(s), each executed by a Claude Code worker (flat-rate, no extra API), tests written and run per task.${proofItemsCount ? ' Tasks with a pass condition were verified independently in a headless browser.' : ''}`,
       `Manager for AI が実装: ゴールを${goalTasks.length}個のタスクに分解し、Claude Code worker が順に実行（既存サブスク・追加API無し・タスク毎にテストを作成し実行）。${proofItemsCount ? '成功条件つきタスクは headless ブラウザで独立検証済み。' : ''}`),
     '',
+    // How the reviewer sees the thing for themselves, in the worker's own
+    // words. Above the reports because "run it and look" beats reading about
+    // it — and because for a request with nothing to run this section is simply
+    // absent rather than filled with a staged screenshot.
+    ...(() => {
+      const runs = goalTasks.filter((t) => t.run && (t.run.cmd || t.run.url));
+      if (!runs.length) return [];
+      return [
+        '',
+        L('## See it running', '## 動かして見る'),
+        '',
+        ...runs.flatMap((t) => [
+          t.run.note ? `${t.run.note}` : '',
+          t.run.cmd ? '```\n' + t.run.cmd + '\n```' : '',
+          t.run.url ? `→ ${t.run.url}` : '',
+        ].filter(Boolean)),
+      ];
+    })(),
+    '',
     L('## Tasks and worker reports', '## タスクとworker報告'),
-    ...goalTasks.map((t) => `\n### ${t.num} ${t.title} — ${t.status} (${t.secs}s)\n${(t.result ?? '').slice(0, 800)}`),
+    // 800 chars used to cut the worker's report mid-sentence. For a request
+    // that produces no runnable thing (research, a summary, an answer) that
+    // report IS the deliverable, so truncating it threw away the result.
+    ...goalTasks.map((t) => `\n### ${t.num} ${t.title} — ${t.status} (${t.secs}s)\n${(t.result ?? '').slice(0, 8000)}`),
     '',
     L(`Changed files: ${files.map((f) => `\`${f}\``).join(' ')}`, `変更ファイル: ${files.map((f) => `\`${f}\``).join(' ')}`),
   ].join('\n');
@@ -913,28 +975,6 @@ export function parseReviewSummary(raw, fallback = {}) {
   };
 }
 
-// A finished task's changed files look like a UI edit: app/ (the Manager's
-// own UI dir, or an equivalent frontend root) plus common frontend source
-// extensions. Pure/deterministic — no LLM — so it can gate proof capture
-// for EVERY UI-touching goal, not just ones that happened to get a
-// passCondition (Masa dogfood: "見た目の調整" goals had no capture at all).
-const UI_TOUCH_RE = /^app\/|\.(?:html|css|tsx|jsx|vue|svelte)$/i;
-export function isUiChange(changedFiles) {
-  return (changedFiles ?? []).some((f) => UI_TOUCH_RE.test(String(f ?? '')));
-}
-
-// Whether a finished UI-touching task/goal needs a zero-LLM proof capture
-// (screenshot + short clip of the ephemeral branch instance): only when the
-// project can actually be booted & screenshotted (canCapture), nothing has
-// captured proof yet (hasProof), and the change really looks like UI
-// (isUiChange). This is the ADDED path for goals with no explicit
-// passCondition — the existing passCondition-based verify loop (runVerification
-// in verify.mjs) still runs and still asserts pass/fail; this only decides
-// whether to ALSO take a capture-only snapshot when that loop didn't run.
-export function shouldCaptureProof({ changedFiles, hasProof, canCapture }) {
-  return Boolean(canCapture) && !hasProof && isUiChange(changedFiles);
-}
-
 const DOC_ONLY_RE = /(^|\/)(README|START-HERE|CHANGELOG|LICENSE)(\.[\w.-]+)?$|(^|\/)docs\/.*\.(md|mdx|txt)$|\.mdx?$|\.txt$/i;
 export function hasTestRelevantChanges(changedFiles) {
   const files = (changedFiles ?? []).map((f) => String(f ?? '').trim()).filter(Boolean);
@@ -1009,17 +1049,25 @@ export function classifyVerifyGate({
   return { blocked, kind, proofAdvisory };
 }
 
-// Whether to ALSO capture a BASELINE ("before") shot for a before/after
-// comparison. Only worth attempting when the baseline is a genuinely
-// different checkout of the code than the one just captured as "after" — a
-// goal whose worktree fell back to the shared project dir (no isolated
-// worktree available) would otherwise "capture" the SAME already-changed
-// code twice and label it before/after, which is not a comparison, it's a
-// fabrication. Best-effort beyond that: gated separately by whether the
-// baseline dir can itself be snapshotted (canCaptureBaseline).
-export function shouldCaptureBaseline({ baselineDir, afterDir, canCaptureBaseline }) {
-  if (!baselineDir || !afterDir || baselineDir === afterDir) return false;
-  return Boolean(canCaptureBaseline);
+// Serializes async work so at most one item runs at a time. The goal-verify
+// pipeline uses this to stop two goals' `npm test` runs (each spins up real
+// headless Chrome + real servers) from ever overlapping — running two full
+// suites at once was the actual cause of goal #552/#487 each blocking on a
+// DIFFERENT flaky test on every retry (2026-07-21 postmortem): the requested
+// feature was already correct, but the shared machine's CPU/ports/tmp-dirs
+// couldn't support two concurrent suites, so the baseline-diff gate never
+// saw the same failure twice in a row and never converged to "no new
+// failures". Queued work still runs even if an earlier item throws/rejects —
+// one bad run must not wedge every goal behind it forever.
+export function createSerialQueue() {
+  let tail = Promise.resolve();
+  return {
+    run(fn) {
+      const started = tail.then(fn, fn);
+      tail = started.then(() => undefined, () => undefined);
+      return started;
+    },
+  };
 }
 
 // Task 56: a project's review definition can carry a free-text `description`
@@ -1179,6 +1227,20 @@ export function goalGroupStatus(goalStatus, startedAt) {
   return 'done'; // includes 'reverted' (terminal)
 }
 
+// PRD §6.5 → Masa 2026-07-21: a folded goal no longer takes its own row in the Review
+// column. The standalone "→ #12 にまとめました" rows read as clutter ("まとめましたは
+// review欄にいらない"); the merge belongs inside the carrier review's detail, as a log of
+// what was folded into it. This selects the folded goals for a given carrier review (a
+// review can group several goalIds under one PR, so match against the whole set). Pure
+// so the browser mirror in app/index.html (non-module, can't import this) and the test
+// agree on exactly which goals a carrier review logs.
+export function foldedIntoReview(goals, targetGoalIds) {
+  const ids = new Set((targetGoalIds ?? []).map(Number));
+  return (goals ?? []).filter(
+    (g) => g && g.status === 'folded' && g.foldedInto != null && ids.has(Number(g.foldedInto)),
+  );
+}
+
 // Label + CSS class for the small status chip shown next to a goal in the
 // goal list and goal detail thread — mirrored in app/index.html's GOAL_CHIP
 // since that inline script can't import this module.
@@ -2083,7 +2145,252 @@ const WORKER_BASH = [
   'cat', 'ls', 'head', 'tail', 'wc', 'find', 'grep', 'rg',
   'sed', 'awk', 'sort', 'uniq', 'diff', 'echo', 'which', 'env', 'pwd', 'date',
 ].map((c) => `Bash(${c}:*)`).join(',');
-export const WORKER_TOOLS = `Edit,Write,Read,Glob,Grep,Skill,TodoWrite,${WORKER_BASH}`;
+// WebFetch/WebSearch: a plain Claude Code session has both, and a worker that
+// cannot open a page or look anything up fails a whole class of requests that
+// work locally ("この記事のとおりに直して", "現行の仕様を確認して"). They are
+// read-only, so they widen what the worker can SEE, not what it can change.
+export const WORKER_TOOLS = `Edit,Write,Read,Glob,Grep,Skill,TodoWrite,WebFetch,WebSearch,${WORKER_BASH}`;
+
+// ---- goal → single task (demoted planner) ----------------------------------
+// P0b (Masa 2026-07-21): the planner no longer decomposes the request into
+// tasks. The request reaches the worker verbatim as ONE task; the worker
+// (Claude Code / Codex) decides its own breakdown and emits it as its own
+// TodoWrite, which the board surfaces. One card = one request.
+
+// A short, single-line display label for the task, derived from the request
+// itself (no LLM rewrite). First non-empty line, trimmed and truncated.
+export function goalTaskTitle(text, max = 80) {
+  const firstLine = String(text ?? '').split('\n').map((s) => s.trim()).find(Boolean) ?? '';
+  return firstLine.length > max ? firstLine.slice(0, max - 1).trimEnd() + '…' : firstLine;
+}
+
+// Build the single task that carries a goal's request verbatim to the worker.
+// `id`, `num`, `createdAt` are supplied by the caller (stateful/impure bits);
+// everything else is derived from the goal so this stays pure & testable.
+// `passCondition` rides along only when the user wrote an explicit one.
+export function buildGoalTask(goal, { id, num, passCondition = null, createdAt }) {
+  return {
+    id, num, goalId: goal.id, projectId: goal.projectId,
+    title: goalTaskTitle(goal.text), detail: goal.text, passCondition,
+    model: goal.model, effort: goal.effort, agent: goal.agent,
+    mode: goal.mode ?? 'auto', skill: goal.skill ?? null,
+    status: 'queued', createdAt, priority: '中',
+    result: null, changedFiles: [], secs: null, activity: [], proof: null, usage: null,
+  };
+}
+
+// ---- worker prompt ---------------------------------------------------------
+// The instruction the worker (Claude Code / Codex) actually reads. Pure:
+// (task, goal, lastFailure, agentName) -> string, so it is unit-testable.
+// `agentName` is the resolved worker agent id ('codex' | 'claude-code'); the
+// caller resolves it (server keeps the WORKER_AGENTS table).
+//
+// P0a "un-lobotomy" (Masa 2026-07-21, goal #496): the harness used to (a) trim
+// the user's real request to 500 chars and bury it as "part of the overall
+// goal", and (b) inject suppressive RULES ("keep changes minimal", "make the
+// smallest safe change instead of expanding scope", "検証しすぎない…すぐ終える").
+// Together they turned "design 3 patterns as an artifact" into one minimal
+// tweak. North star: we never re-judge the request — the user's verbatim words
+// are the source of truth and the worker delivers exactly what they ask for.
+export function workerPrompt(task, goal, lastFailure, agentName = 'claude-code') {
+  // Optional skill the user attached to this goal. Empirically (scratch worker,
+  // haiku, custom fixture skill) the reliably-firing form is an explicit Skill-tool
+  // instruction as the FIRST line; a bare "/name" first line did not consistently
+  // trigger the skill in `claude -p`. See commit body for the run evidence.
+  const skill = task?.skill ?? goal?.skill;
+  const displayName = agentName === 'codex' ? 'Codex' : 'Claude Code';
+  // Report back to the human in the SAME language they wrote the goal in (Masa
+  // 2026-07-15: "撃った言語で返す"). JP characters → Japanese, otherwise English.
+  const replyLang = detectRequestLanguage(goal?.text || task?.title || '') === 'ja' ? '日本語' : 'English';
+  return [
+    skill ? `FIRST, use the /${skill} skill via the Skill tool (invoke Skill with the "${skill}" skill) before doing anything else. Then carry out the task below.` : '',
+    `You are a ${displayName} worker managed by "Manager for AI". Do the request below inside this project directory.`,
+    goal?.priorFailureMemory?.length ? `\nMANAGER FAILURE MEMORY:\n${latestFailurePolicy(goal.priorFailureMemory)?.text}\nApply this prevention before starting.` : '',
+    '',
+    // The user's own words, verbatim and in full, are the source of truth.
+    // TASK/DETAIL below is a paraphrase from the planner — when they differ,
+    // follow the user's words.
+    goal?.text ? `USER'S REQUEST (verbatim — the source of truth; deliver exactly this):\n${goal.text}` : '',
+    '',
+    `TASK ${task.num}: ${task.title}`,
+    task.detail ? `DETAIL: ${task.detail}` : '',
+    goal?.images?.length ? `ATTACHED IMAGES (absolute paths, use the Read tool to view them): ${goal.images.join(' ')}` : '',
+    task.passCondition ? `\nEXPLICIT PASS CONDITION (verified externally by a headless browser after you finish — NOT by you): ${task.passCondition}` : '',
+    lastFailure ? `\nPREVIOUS ATTEMPT FAILED EXTERNAL VERIFICATION: ${lastFailure}\nYour previous changes are on disk. Diagnose and fix.` : '',
+    '',
+    'RULES:',
+    '- Edit only files inside this directory and this project. Stay on this request; do not wander into unrelated work.',
+    // Deliverable fidelity (replaces the old "make the smallest safe change
+    // instead of expanding scope"): the request, not our fear of scope, sets
+    // the size of the work.
+    '- Deliver what the request actually asks for. If it asks for multiple options, N variations, a visual, an artifact, or a full exploration, produce ALL of them — do not reduce it to one, and do not cut it short to finish faster.',
+    '- Keep the work bounded to the request: inspect only files needed; avoid broad repository scans unless they are necessary.',
+    "- You may use the user's installed skills (Skill tool, e.g. /galda-doc) when one clearly fits the request.",
+    // Token-frugality + the 10-min run cap: the worker used to run the WHOLE suite
+    // (npm test) repeatedly, which the Manager ALSO runs at close-out — double work
+    // that regularly overran the cap (→ a SIGTERM 'interrupted'). Write the test,
+    // run only the RELEVANT file once, and leave the full-suite + verification to
+    // the Manager. (Masa: worker が自前でテスト全回し→止まる、が最大の無駄。)
+    '- 変更に対応するテストを書く。確認は該当テストファイル1つだけを1回実行する（例: node --test path/to/only-this.test.mjs）。プロジェクト全体の npm test を繰り返し回さない — 全体テストと最終検証は Manager 側が実行する。テストが適用できない変更は理由と手動確認手順を書く。',
+    // Anti-wasteful-re-verify only — NOT a licence to do less. Once it works,
+    // stop re-checking; but the deliverables above must still be produced in full.
+    '- 動くと確認できたら十分（無駄な再検証でログを漁り続けない）。ただし依頼された成果物は削らず出し切ること。',
+    '- Do not commit (git is handled by the Manager).',
+    // How the human actually looks at the result. We never guess the run
+    // command ourselves — guessing means branching on project type (Next.js vs
+    // Python vs …), and that is the "smart PM" behaviour this layer must not
+    // have. The only AI in the pipeline is the one that just did the work, so
+    // 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 はこれを使って人に「動かして見る」と「何を見ればいいか」を出す。動かして見せるものが無い依頼（調査・要約・質問への回答など）では書かなくてよい。`,
+    // 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や「詳しくはここ」のような飾りのリンクは、そのままリンクとして人に表示される）。`,
+    // The camera. We say it exists and where the pictures go; we never say when
+    // to use it — that is the worker's call, like the run declaration above.
+    // Telling it "screenshot UI changes" would be this layer deciding what kind
+    // of request it is, which is the behaviour that produced off-target proof.
+    `- 画面・見た目のあるものを作ったなら、自分でスクリーンショットを撮って見せてよい: \`node ${SHOT_CLI} <URL または HTMLファイル> ${SHOT_DIR}/<名前>.png [--full] [--wait-for <CSSセレクタ>]\`（headless Chrome・前面に出ない）。${SHOT_DIR}/ に置いた画像は Manager が回収して人に見せる（diff には入らない）。撮ったものは Read で自分でも見返せる。`,
+    `- 最後に${replyLang}で2〜4行：何を変えたか・どのファイルか・テスト結果・人間が確認すべき点。`,
+  ].filter(Boolean).join('\n');
+}
+
+// ---- RUN DECLARATION -------------------------------------------------------
+// The worker tells us how a human can run and look at what it built, by writing
+// RUN_DECL_FILE. This is the whole of P1's "動かして見られる状態": the evidence
+// is the real thing running, not a screenshot we staged.
+//
+// Why a file and not a line in the worker's report: writing a file is a tool
+// call the agent makes deliberately, where a report format is a wording habit
+// that drifts. And why the worker at all — the layer below (this one) must not
+// classify the request or the project to decide how to start it.
+//
+// Anything we cannot validate is dropped: no "run it" button is honest, a
+// button that opens the wrong thing is the fabricated-proof bug all over again.
+export const RUN_DECL_FILE = '.manager-run.json';
+
+export function parseRunDeclaration(text) {
+  let raw;
+  try { raw = JSON.parse(String(text ?? '')); } catch { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  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;
+  // 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) };
+}
+
+// ---- SHOTS: the worker's own camera ----------------------------------------
+// The worker could build a screen and had no way to show it: WORKER_TOOLS has
+// no browser, so "見せて" could only ever come back as prose. That is one half
+// of the off-target-evidence problem (#496) — the other half was us staging the
+// picture ourselves, which is exactly what must not come back.
+//
+// So: hand the worker a camera and nothing else. `engine/shot.mjs` takes a URL
+// or a local file and writes a PNG in headless Chrome. This layer never decides
+// WHEN to shoot or WHAT to shoot — the worker that just did the work does, the
+// same way it already decides the run declaration above. No request-type
+// branching lives here.
+//
+// Shots land in SHOT_DIR inside the worktree and the Manager moves them out
+// before the diff is computed: they are a message to the Manager, not part of
+// the deliverable, so they must never reach the PR (same rule as RUN_DECL_FILE).
+export const SHOT_DIR = '.manager-shots';
+
+// Absolute path to the camera, resolved from this file so it is correct in a
+// repo checkout and in an installed package alike (the worker runs in the
+// customer's worktree, which knows nothing about where the Manager lives).
+export const SHOT_CLI = (() => {
+  const p = decodeURIComponent(new URL('shot.mjs', import.meta.url).pathname);
+  return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+})();
+
+// Where Chrome might be. Env first so a customer with a non-standard install
+// (or a Linux box) can point at it; the rest are the default locations per
+// platform. Pure — the caller supplies `exists`, so this is testable.
+export function chromeCandidates(env = {}) {
+  return [
+    env.CHROME_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/chromium',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  ].filter(Boolean);
+}
+export function pickChromePath(env = {}, exists = () => false) {
+  return chromeCandidates(env).find((c) => exists(c)) ?? null;
+}
+
+// `node <manager>/engine/shot.mjs <url|file> <out.png> [--width N] [--height N]
+//  [--full] [--wait MS] [--wait-for SELECTOR]`
+// 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 num = (v, lo, hi) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n >= lo && n <= hi ? Math.round(n) : null;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    if (a === '--full') { opt.full = true; continue; }
+    if (a === '--width' || a === '--height') {
+      const n = num(argv[++i], 100, 4000);
+      if (n == null) return { error: `${a} needs a number between 100 and 4000` };
+      opt[a.slice(2)] = n; continue;
+    }
+    if (a === '--wait') {
+      const n = num(argv[++i], 0, 30000);
+      if (n == null) return { error: '--wait needs milliseconds between 0 and 30000' };
+      opt.wait = n; continue;
+    }
+    if (a === '--wait-for') {
+      const sel = String(argv[++i] ?? '').trim();
+      if (!sel) return { error: '--wait-for needs a CSS selector' };
+      opt.waitFor = sel; 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 (!/\.png$/i.test(out)) return { error: 'output must end in .png' };
+  return { target, out, ...opt };
+}
+
+// http(s) passes through; anything else is a local path → file:// URL.
+// `resolvePath` is injected so this stays pure and testable.
+export function shotTargetUrl(target, resolvePath = (p) => p) {
+  const t = String(target ?? '').trim();
+  if (!t) return null;
+  if (/^(https?|file):\/\//i.test(t)) return t;
+  const abs = String(resolvePath(t)).replace(/\\/g, '/');
+  const withSlash = abs.startsWith('/') ? abs : `/${abs}`;
+  return `file://${withSlash.split('/').map((seg, i) => (i === 0 ? seg : encodeURIComponent(seg))).join('/')}`;
+}
+
+// What the Manager takes out of SHOT_DIR: images only, no subpaths or dotfiles
+// (they become filenames in the Manager's own store), capped so a runaway loop
+// cannot bloat the record.
+export const SHOT_MAX = 20;
+export function collectShotNames(names = []) {
+  return names
+    .filter((n) => typeof n === 'string' && /\.(png|jpe?g|gif|webp)$/i.test(n))
+    .filter((n) => !n.includes('/') && !n.includes('\\') && !n.startsWith('.'))
+    .sort()
+    .slice(0, SHOT_MAX);
+}
 
 // ---- SKILL picker ----------------------------------------------------------
 // Parse the YAML frontmatter of a SKILL.md / command .md and pull out `name`