@galda/cli 0.10.0

package/engine/lib.mjs

@@ -0,0 +1,2378 @@
+// Manager for AI — pure helpers (unit-tested in engine/test/)
+
+import { resolve, join, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createPublicKey, verify as verifyRsaSignature } from 'node:crypto';
+
+// Build the URL a headless-browser verifier should open for a goal's entry
+// point. Plain http(s) entries pass through unchanged. A relative path is
+// normally opened as a bare file:// page — but the Manager's own UI
+// (managerRoot/app/index.html) talks to itself via relative fetch() calls
+// (/api/tasks, /api/state, …), which resolve against the file:// origin and
+// fail outright when opened that way. So that one entry must be checked
+// against the live server URL instead.
+// `accessKey`, when given, is appended as `?key=` for the Manager's own
+// index.html — that page sits behind the server's ?key= auth gate (see
+// server.mjs), so a verifier opening it without the key gets a 403 page
+// instead of the real UI, and every window.state check on it fails.
+export function resolveEntryUrl({ entry, projectDir, managerRoot, port, accessKey }) {
+  if (!entry) return null;
+  if (/^https?:\/\//.test(entry)) {
+    // direct http URLs to this Manager's own UI also need the key
+    if (accessKey && entry.includes(`localhost:${port}`) && !entry.includes('key=')) {
+      return `${entry}${entry.includes('?') ? '&' : '?'}key=${accessKey}`;
+    }
+    return entry;
+  }
+  const abs = resolve(join(projectDir, entry));
+  if (abs === resolve(managerRoot, 'app', 'index.html')) {
+    const base = `http://localhost:${port}/`;
+    return accessKey ? `${base}?key=${accessKey}` : base;
+  }
+  return pathToFileURL(abs).href;
+}
+
+// Extract token/cost usage from a parsed `type:'result'` stream-json event
+// (the final event of a `claude -p --output-format stream-json` run).
+// Returns null for any other event type.
+export function parseResultUsage(ev) {
+  if (!ev || ev.type !== 'result') return null;
+  const u = ev.usage ?? {};
+  return {
+    input_tokens: u.input_tokens ?? null,
+    output_tokens: u.output_tokens ?? null,
+    cache_read_input_tokens: u.cache_read_input_tokens ?? null,
+    cache_creation_input_tokens: u.cache_creation_input_tokens ?? null,
+    cost_usd: ev.total_cost_usd ?? ev.cost_usd ?? null,
+    duration_ms: ev.duration_ms ?? null,
+  };
+}
+
+// Sum a list of per-attempt usage objects (as returned by parseResultUsage)
+// into one totals object; null entries are skipped. Returns null when there
+// is nothing to sum, so callers can store task.usage = sumUsage(...) as-is.
+export function sumUsage(usages) {
+  const list = (usages ?? []).filter(Boolean);
+  if (!list.length) return null;
+  const keys = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'cost_usd', 'duration_ms'];
+  const out = {};
+  for (const k of keys) out[k] = list.reduce((sum, u) => sum + (u[k] ?? 0), 0);
+  return out;
+}
+
+// Render a task's summed usage (as returned by sumUsage) into the one-line
+// "tokens in Xk / out Yk (flat-rate, no extra cost)" label shown on a
+// finished task card. No $ figure: Manager for AI runs on the flat-rate
+// Claude Code subscription, not metered API billing, so a per-task dollar
+// cost would be misleading (see docs/internal/strategy-vs-goal.md).
+// Mirrored manually in app/index.html's formatUsage() since that inline
+// script can't import this module — keep both in sync.
+// Returns null when there is no usage to show.
+export function formatUsage(usage) {
+  if (!usage) return null;
+  const fmtK = (n) => (n == null ? '0' : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+  return `tokens in ${fmtK(usage.input_tokens)} / out ${fmtK(usage.output_tokens)} (flat-rate, no extra cost)`;
+}
+
+// Compact total-token label for tight spaces (review-card badges, the
+// header's today's-total figure) — just "12.3k", no unit/wording; the
+// caller supplies those. Mirrored manually in app/index.html's
+// formatUsageCompact() since that inline script can't import this module —
+// keep both in sync. Returns null when there is no usage to show.
+export function formatUsageCompact(usage) {
+  if (!usage) return null;
+  const fmtK = (n) => (n == null ? '0' : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+  return fmtK((usage.input_tokens ?? 0) + (usage.output_tokens ?? 0));
+}
+
+// Sums usage across tasks that finished on the same local calendar day as
+// `nowMs` (compared via toDateString(), so it's just "today" in whatever
+// timezone the caller's clock is in) — powers the header's today's-total
+// figure. `nowMs` is a parameter rather than read internally so the result
+// stays deterministic/testable. Mirrored manually in app/index.html since
+// that inline script can't import this module — keep both in sync. Returns
+// null when nothing finished today or none of it carries usage.
+export function sumUsageForToday(tasks, nowMs) {
+  const todayKey = new Date(nowMs).toDateString();
+  const usages = (tasks ?? [])
+    .filter((t) => t?.finishedAt && new Date(t.finishedAt).toDateString() === todayKey)
+    .map((t) => t.usage);
+  return sumUsage(usages);
+}
+
+// Token-frugal execution planning -------------------------------------------------
+// A visible Project is the user's mental workspace. Internally, Manager can
+// route goals into smaller workstreams and session policies so unrelated work
+// does not inherit a huge session. These rules are examples, not a taxonomy:
+// unknown topics get a task-derived workstream label instead of being forced
+// into one of the named buckets.
+const WORKSTREAM_RULES = [
+  { id: 'design', label: 'Design', re: /design|ui|ux|figma|visual|見た目|デザイン|レイアウト|配色|ボタン|画面|モバイル/i },
+  { id: 'research', label: 'Research', re: /marketing|market|seo|landing|copy|ads|growth|競合|人気|ユーザー数|調査|リサーチ|市場|top\s*\d+/i },
+  { id: 'docs', label: 'Docs', re: /docs?|prd|readme|spec|仕様|要件|ドキュメント|レポート|まとめ/i },
+  { id: 'backend', label: 'Backend', re: /api|server|engine|backend|db|auth|test|テスト|検証|削除|追加|修正|実装/i },
+  { id: 'frontend', label: 'Frontend', re: /frontend|app\/|html|css|javascript|typescript|react|vue|svelte/i },
+];
+
+function derivedWorkstream(text = '') {
+  const cleaned = String(text ?? '')
+    .replace(/[^\p{L}\p{N}\s/_-]+/gu, ' ')
+    .trim();
+  const token = (cleaned.split(/\s+/).find((w) => w.length >= 3) ?? cleaned.slice(0, 18)) || 'task';
+  const id = token.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32) || 'task';
+  return { id: `task-${id}`, label: token.slice(0, 24) };
+}
+
+export function classifyWorkstream({ text = '', changedFiles = [] } = {}) {
+  const haystack = `${text}\n${(changedFiles ?? []).join('\n')}`;
+  return WORKSTREAM_RULES.find((r) => r.re.test(haystack)) ?? derivedWorkstream(text || (changedFiles ?? []).join(' '));
+}
+
+export function chooseSessionPolicy({ usage = null, runTokens = 0, runAttempts = 0, previousSession = false, text = '' } = {}) {
+  const fresh = (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0) + (usage?.cache_creation_input_tokens ?? 0);
+  const cacheRead = usage?.cache_read_input_tokens ?? 0;
+  const cacheDominated = cacheRead > 500_000 && cacheRead > fresh * 5;
+  const hugeContext = cacheRead > 1_500_000 || Number(runTokens ?? 0) > 1_500_000;
+  const broadAsk = /全部|全体|あらゆる|まとめて|top\s*\d+|調査|リサーチ|設計|PRD|計画/i.test(String(text ?? ''));
+  if (!previousSession) return { mode: 'cold', reason: 'new independent goal' };
+  if (cacheDominated || hugeContext) return { mode: 'cold-handoff', reason: 'large cached context would be expensive to resume' };
+  if (runAttempts >= 4 || broadAsk) return { mode: 'compact', reason: 'keep useful summary, drop long transcript' };
+  return { mode: 'resume', reason: 'small focused follow-up' };
+}
+
+export function chooseWorkerPolicy({ text = '', changedFiles = [], risk = null } = {}) {
+  const workstream = classifyWorkstream({ text, changedFiles });
+  const haystack = `${text}\n${(changedFiles ?? []).join('\n')}`;
+  const docsOnly = changedFiles.length > 0 && !hasTestRelevantChanges(changedFiles);
+  const highRisk = risk?.shouldPause || /auth|payment|billing|database|migration|deploy|secret|認証|支払|課金|DB|デプロイ/i.test(haystack);
+  const research = workstream.id === 'research' || /調査|リサーチ|market|top\s*\d+/i.test(haystack);
+  const design = workstream.id === 'design';
+  const policy = highRisk
+    ? { effort: 'high', reason: 'safety-sensitive change needs stronger verification' }
+    : docsOnly || research
+      ? { effort: 'low', reason: 'docs/research path should stay lightweight' }
+      : design
+        ? { effort: 'medium', reason: 'UI/design work needs proof but not broad exploration' }
+        : { effort: 'medium', reason: 'default implementation path' };
+  return {
+    workstreamId: workstream.id,
+    workstreamLabel: workstream.label,
+    effort: policy.effort,
+    reason: policy.reason,
+  };
+}
+
+export function buildExecutionPlan({ projectId = null, text = '', usage = null, runTokens = 0, runAttempts = 0, previousSession = false } = {}) {
+  const workstream = classifyWorkstream({ text });
+  const session = chooseSessionPolicy({ usage, runTokens, runAttempts, previousSession, text });
+  const workerPolicy = chooseWorkerPolicy({ text });
+  const optimizationTechniques = [
+    session.mode === 'compact' ? 'compact handoff' : null,
+    session.mode === 'cold-handoff' ? 'fresh handoff' : null,
+    session.mode === 'cold' ? '/clear equivalent' : null,
+    workerPolicy.reason ? 'worker policy' : null,
+  ].filter(Boolean);
+  return {
+    projectGroupId: projectId,
+    workstreamId: workstream.id,
+    workstreamLabel: workstream.label,
+    sessionMode: session.mode,
+    sessionReason: session.reason,
+    workerPolicy,
+    optimizationTechniques,
+  };
+}
+
+export function buildContextHandoffSummary({ goal = null, tasks = [] } = {}) {
+  const reqs = (tasks ?? []).filter((t) => !t.reply);
+  const done = reqs.filter((t) => ['done', 'skipped'].includes(t.status)).length;
+  const files = [...new Set(reqs.flatMap((t) => t.changedFiles ?? []))]
+    .filter(Boolean)
+    .slice(0, 20);
+  const reports = reqs
+    .filter((t) => t.result || t.title)
+    .slice(-4)
+    .map((t) => `- #${t.num ?? '?'} ${String(t.title ?? '').replace(/\s+/g, ' ').slice(0, 80)}: ${String(t.result ?? t.status ?? '').replace(/\s+/g, ' ').slice(0, 220)}`);
+  return [
+    'Manager handoff summary:',
+    `Goal: ${String(goal?.text ?? '').replace(/\s+/g, ' ').slice(0, 500) || '(unknown)'}`,
+    `Progress: ${done}/${reqs.length} requirements done`,
+    goal?.reviewSummary?.changed ? `What changed: ${String(goal.reviewSummary.changed).replace(/\s+/g, ' ').slice(0, 300)}` : null,
+    goal?.testResult ? `Tests: ${goal.testResult.ran ? `${goal.testResult.passed ?? 0} passed / ${goal.testResult.failed ?? 0} failed` : `not run (${goal.testResult.skippedReason ?? 'skipped'})`}` : null,
+    files.length ? `Changed files: ${files.join(', ')}` : null,
+    reports.length ? ['Recent worker reports:', ...reports].join('\n') : null,
+    'Continue from files on disk and this summary. Do not assume hidden chat history.',
+  ].filter(Boolean).join('\n').slice(0, 4000);
+}
+
+export function estimateTokenOptimization({ usage = null, weightedTokens = null, cacheReadWeight = 0.1, sessionMode = null, usedHandoff = false, usedCompact = false, usedClear = false, agentModel = null } = {}) {
+  const u = usage ?? {};
+  const raw = (u.input_tokens ?? 0) + (u.output_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+  const weighted = weightedTokens != null && Number.isFinite(Number(weightedTokens))
+    ? Number(weightedTokens)
+    : usageBudgetTokens(u, { cacheReadWeight });
+  const saved = Math.max(0, raw - weighted);
+  const percent = raw > 0 ? Math.round((saved / raw) * 100) : 0;
+  const techniques = [];
+  if ((u.cache_read_input_tokens ?? 0) > 0) techniques.push('cache-read weighting');
+  if (['compact', 'cold-handoff'].includes(sessionMode)) techniques.push(sessionMode === 'compact' ? 'compact handoff' : 'fresh handoff');
+  if (usedHandoff) techniques.push('AI handoff');
+  if (usedCompact) techniques.push('/compact');
+  if (usedClear) techniques.push('/clear');
+  if (agentModel) techniques.push(`model ${agentModel}`);
+  if (!percent && !techniques.length) return null;
+  return { rawTokens: raw, weightedTokens: weighted, savedTokens: saved, percent, techniques: [...new Set(techniques)] };
+}
+
+export function estimateFailureCauseMix({ usage = null, blockedKind = null, changedFiles = [], testResult = null, attentionHadDetail = true, taskCount = 1 } = {}) {
+  const causes = [
+    { id: 'session-cache', label: '巨大 session / cache read の肥大化', weight: 0 },
+    { id: 'verification-contract', label: '検証ゲートのケース分岐不足', weight: 0 },
+    { id: 'project-splitting', label: 'Project / タスク分割が粗い', weight: 0 },
+    { id: 'attention-explainability', label: 'Attention / Review の説明不足', weight: 0 },
+    { id: 'test-flake', label: 'テストフレーク・環境差分', weight: 0 },
+  ];
+  const add = (id, w) => { const c = causes.find((x) => x.id === id); if (c) c.weight += w; };
+  const fresh = (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0) + (usage?.cache_creation_input_tokens ?? 0);
+  const cacheRead = usage?.cache_read_input_tokens ?? 0;
+  if (cacheRead > 500_000 && cacheRead > fresh * 5) add('session-cache', 45);
+  if (blockedKind === 'budget') add('session-cache', 35);
+  if (blockedKind === 'test') add('verification-contract', hasTestRelevantChanges(changedFiles) ? 25 : 55);
+  if (testResult?.failed > 0 && !hasTestRelevantChanges(changedFiles)) add('verification-contract', 35);
+  if ((changedFiles ?? []).length > 8 || taskCount > 3) add('project-splitting', 25);
+  if (!attentionHadDetail) add('attention-explainability', 20);
+  if (/did not report ready in time|fetch failed|bad port/i.test(String(testResult?.detail ?? ''))) add('test-flake', 30);
+  if (!causes.some((c) => c.weight > 0)) {
+    add('session-cache', 35); add('verification-contract', 30); add('project-splitting', 20); add('attention-explainability', 10); add('test-flake', 5);
+  }
+  const total = causes.reduce((s, c) => s + c.weight, 0) || 1;
+  return causes
+    .map((c) => ({ id: c.id, label: c.label, percent: Math.round((c.weight / total) * 100) }))
+    .filter((c) => c.percent > 0)
+    .sort((a, b) => b.percent - a.percent);
+}
+
+function primaryFailureCause({ usage = null, blockedKind = null, changedFiles = [], testResult = null, attentionHadDetail = true, taskCount = 1 } = {}) {
+  return estimateFailureCauseMix({ usage, blockedKind, changedFiles, testResult, attentionHadDetail, taskCount })[0]
+    ?? { id: 'unknown', label: '原因未特定', percent: 0 };
+}
+
+function failurePhase(kind) {
+  if (kind === 'budget' || kind === 'rate-limit') return 'worker-run';
+  if (kind === 'test' || kind === 'proof' || kind === 'verify') return 'manager-verification';
+  return 'execution';
+}
+
+function failureSummaryFor({ kind, goalText, testResult, budgetReason, proofMissing, verifyFail }) {
+  const needed = String(goalText ?? '').replace(/\s+/g, ' ').trim().slice(0, 120) || '依頼内容の完了';
+  if (kind === 'budget') {
+    return {
+      whatHappened: `必要だった作業「${needed}」は worker 実行中に token budget guardrail で止まりました。`,
+      yourCall: '次回は cold-handoff と狭い検査範囲で再開し、広い探索や巨大セッション再開を避けます。',
+    };
+  }
+  if (kind === 'rate-limit') {
+    return {
+      whatHappened: `必要だった作業「${needed}」は Claude の利用制限で一時停止しました。`,
+      yourCall: '再開可能時刻まで待ってから自動再開し、即時リトライで同じ制限を踏まないようにします。',
+    };
+  }
+  if (kind === 'test') {
+    const failed = Number(testResult?.failed ?? 0);
+    return {
+      whatHappened: `必要だった作業「${needed}」は実装後の Manager 検証まで進みましたが、テスト ${failed} 件で止まりました。`,
+      yourCall: '失敗ログを読ませて回帰を直し、関連テストから再実行してから全体確認に戻します。',
+    };
+  }
+  if (kind === 'proof') {
+    return {
+      whatHappened: `必要だった作業「${needed}」は UI 変更後の proof 撮影で止まりました。`,
+      yourCall: '起動・撮影条件を確認し、ユーザーが判断できるスクショまたは動画を取得してから Review に戻します。',
+    };
+  }
+  if (kind === 'verify' || verifyFail) {
+    return {
+      whatHappened: `必要だった作業「${needed}」は検証条件を満たせず Review に進めませんでした。`,
+      yourCall: '不足している proof / 検証結果をそろえ、判断できる状態にしてから再提出します。',
+    };
+  }
+  return {
+    whatHappened: budgetReason ? String(budgetReason).slice(0, 180) : `必要だった作業「${needed}」が途中で止まりました。`,
+    yourCall: '停止地点のログを読んで、同じ失敗を避ける最小ステップで再開します。',
+  };
+}
+
+export function buildFailurePostmortem({
+  goal = null,
+  tasks = [],
+  kind = 'unknown',
+  reason = '',
+  usage = null,
+  changedFiles = [],
+  testResult = null,
+  attentionHadDetail = true,
+  previousEntries = [],
+} = {}) {
+  const taskList = (tasks ?? []).filter(Boolean);
+  const files = [...new Set([...(changedFiles ?? []), ...taskList.flatMap((t) => t.changedFiles ?? [])])]
+    .filter(Boolean);
+  const cause = primaryFailureCause({
+    usage,
+    blockedKind: kind,
+    changedFiles: files,
+    testResult,
+    attentionHadDetail,
+    taskCount: taskList.filter((t) => !t.reply).length || 1,
+  });
+  const recurrenceKey = `${kind}:${cause.id}:${hasTestRelevantChanges(files) ? 'code' : 'non-code'}`;
+  const recurrenceCount = (previousEntries ?? []).filter((e) => e?.recurrenceKey === recurrenceKey).length + 1;
+  const summary = failureSummaryFor({
+    kind,
+    goalText: goal?.text,
+    testResult,
+    budgetReason: reason,
+    proofMissing: kind === 'proof',
+    verifyFail: kind === 'verify',
+  });
+  const preventionByCause = {
+    'session-cache': ['cold-handoff', 'compact summary', 'narrow file reads', 'no broad repository scan before retry'],
+    'verification-contract': ['pass failing test output into auto-feedback', 'run narrow related tests first', 'skip unrelated full-suite block for docs/report-only work'],
+    'project-splitting': ['split into a narrower internal workstream', 'finish one small patch before expanding scope'],
+    'attention-explainability': ['show what was needed, where it stopped, and the next action in the first view'],
+    'test-flake': ['retry deterministic setup once', 'preserve environment logs', 'separate environment failure from product regression'],
+  };
+  const nextPolicyByCause = {
+    'session-cache': 'Start the next attempt from a fresh handoff instead of resuming the large session.',
+    'verification-contract': 'Give the worker the exact failing output and require a narrow fix plus rerun.',
+    'project-splitting': 'Route follow-up work into a smaller workstream before broad implementation.',
+    'attention-explainability': 'Summarize the failure in user language before asking for a decision.',
+    'test-flake': 'Retry the deterministic setup and keep raw logs for human review if it repeats.',
+  };
+  return {
+    id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    kind,
+    phase: failurePhase(kind),
+    recurrenceKey,
+    recurrenceCount,
+    rootCauseId: cause.id,
+    rootCause: cause.label,
+    confidence: cause.percent,
+    whatHappened: summary.whatHappened,
+    yourCall: summary.yourCall,
+    preventionAdded: preventionByCause[cause.id] ?? ['record failure details', 'retry with narrower scope'],
+    nextPolicy: nextPolicyByCause[cause.id] ?? 'Retry from the recorded failure details with narrower scope.',
+    evidence: {
+      reason: String(reason ?? '').slice(0, 1000),
+      failedTests: testResult?.failed ?? null,
+      changedFiles: files.slice(0, 20),
+      usage,
+    },
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function appendFailureMemory(goal, entry, limit = 12) {
+  const entries = [...(goal?.failureMemory ?? []), entry].filter(Boolean).slice(-limit);
+  return entries;
+}
+
+export function latestFailurePolicy(goalOrEntries) {
+  const entries = Array.isArray(goalOrEntries) ? goalOrEntries : (goalOrEntries?.failureMemory ?? []);
+  const last = entries?.[entries.length - 1];
+  if (!last) return null;
+  return {
+    recurrenceKey: last.recurrenceKey,
+    text: [
+      `Previous failure memory: ${last.whatHappened}`,
+      `Root cause: ${last.rootCause} (${last.confidence}% confidence).`,
+      `Prevention now required: ${(last.preventionAdded ?? []).join(', ')}.`,
+      `Next policy: ${last.nextPolicy}`,
+    ].join('\n'),
+  };
+}
+
+// Parse one line of `claude -p --output-format stream-json --verbose` output
+// into displayable events. Returns an array (a single assistant message can
+// carry several tool calls); empty array when the line has nothing to show.
+export function parseStreamEvents(line) {
+  let ev;
+  try { ev = JSON.parse(line); } catch { return []; }
+  if (ev.type === 'system' && ev.subtype === 'init' && ev.session_id) {
+    return [{ kind: 'session', id: String(ev.session_id) }];
+  }
+  if (ev.type === 'result') {
+    return [{ kind: 'result', text: String(ev.result ?? '').trim(), usage: parseResultUsage(ev) }];
+  }
+  if (ev.type !== 'assistant') return [];
+  const out = [];
+  for (const p of ev.message?.content ?? []) {
+    if (p.type === 'tool_use') {
+      const i = p.input ?? {};
+      // TodoWrite carries the worker's live to-do list; surface it as a
+      // dedicated event (the UI renders it as a checklist, not an activity line).
+      if (p.name === 'TodoWrite') {
+        out.push({ kind: 'todos', todos: Array.isArray(i.todos) ? i.todos : [] });
+        continue;
+      }
+      const arg = i.file_path ?? i.path ?? i.pattern ?? i.command ?? i.url ?? i.query ?? '';
+      out.push({ kind: 'activity', text: `${p.name} ${String(arg)}`.trim().slice(0, 140) });
+    } else if (p.type === 'text' && p.text?.trim()) {
+      out.push({ kind: 'activity', text: `✎ ${p.text.trim().replace(/\s+/g, ' ').slice(0, 110)}` });
+    }
+  }
+  return out;
+}
+
+// Parse the planner's reply into { entry, tasks }. Accepts either a JSON
+// object {entry, tasks:[...]} or a bare JSON array anywhere in the text;
+// falls back to a single task made from the raw request. Each task may carry
+// a passCondition (used for automatic proof verification).
+export function parsePlan(text, fallbackTitle) {
+  const str = String(text ?? '');
+  const normalize = (arr) => arr
+    .map((x) => typeof x === 'string'
+      ? { title: x, detail: '', passCondition: null }
+      : {
+          title: String(x?.title ?? x?.task ?? '').trim(),
+          detail: String(x?.detail ?? x?.description ?? '').trim(),
+          passCondition: x?.passCondition ? String(x.passCondition).trim() : null,
+        })
+    .filter((t) => t.title)
+    .slice(0, 6); // PRD §3: 1〜6 tasks (matches the planner prompt's cap)
+
+  const obj = str.match(/\{[\s\S]*\}/);
+  if (obj) {
+    try {
+      const o = JSON.parse(obj[0]);
+      if (Array.isArray(o?.tasks)) {
+        const tasks = normalize(o.tasks);
+        if (tasks.length) return { entry: o.entry ? String(o.entry).trim() : null, tasks };
+      }
+    } catch { /* fall through */ }
+  }
+  const arr = str.match(/\[[\s\S]*\]/);
+  if (arr) {
+    try {
+      const a = JSON.parse(arr[0]);
+      if (Array.isArray(a)) {
+        const tasks = normalize(a);
+        if (tasks.length) return { entry: null, tasks };
+      }
+    } catch { /* fall through */ }
+  }
+  const title = String(fallbackTitle ?? '').replace(/\s+/g, ' ').trim().slice(0, 120);
+  return { entry: null, tasks: [{ title, detail: '', passCondition: null }] };
+}
+
+// ---- planner decomposition = USER-TOPIC granularity ------------------------
+// Masa (dogfood): 「プログラム的なタスクに分解しすぎ。ユーザー体験としての
+// タスクを積んでるのに…『音声入力』と『ビジュアル作成』の2つに分けるのはいい。
+// でも『PRDを作って』みたいなブレイクダウンはいらない」。So the planner splits
+// ONLY on distinct user-facing deliverables, never on engineering PHASES.
+//
+// Titles that plainly name an engineering PHASE (a step in building something)
+// rather than a user-facing outcome. Deliberately NARROW — only unmistakable
+// build-step language — so a genuine deliverable is never mistaken for a phase.
+const ENGINEERING_PHASE_RE = /(^|[^A-Za-z])PRD([^A-Za-z]|$)|仕様書|要件定義|設計(書|する|を|の)|テスト(を|の|コード)?(書|追加|作成|実装)|(write|add|unit|integration|e2e)[\s-]*tests?|テストを書|リファクタ|refactor|パーサ[ー]?(を|の)?(追加|実装|書|作)|型定義|scaffold|ボイラープレート|boilerplate/i;
+
+export function isEngineeringPhaseTitle(title) {
+  return ENGINEERING_PHASE_RE.test(String(title ?? ''));
+}
+
+// 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:
+//   1) drop tasks whose titles are plainly engineering phases — but ONLY when at
+//      least one genuine user-facing task survives (never delete the whole plan).
+//   2) clamp to `maxTasks` (default 4): a single coherent request should be 1
+//      topic; only genuinely separate asks split (realistically 1–3).
+// When EVERY task looks like a phase, that's the signal the whole request is ONE
+// topic that got shredded into build steps: collapse to a single task carrying
+// the user's own goal text as the title, with the phase details merged so the
+// 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);
+  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);
+    const detail = list.map((t) => t.detail).filter(Boolean).join('\n');
+    const passCondition = list.find((t) => t.passCondition)?.passCondition ?? null;
+    return [{ title, detail, passCondition }];
+  }
+  return 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.
+//
+// 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();
+}
+
+// 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;
+}
+
+// ---- which goal states allow EDIT / DELETE from the board ------------------
+// Masa (dogfood): 「急に入ったやつ(ゴール)が編集したり削除したりできない。
+// できるようにして」。Expanded beyond the original stacked/pending.
+//
+// EDIT (text / PR toggle) is allowed while a goal has not meaningfully started
+// producing a reviewable result: stacked, pending, planning (being
+// decomposed), needsInput (awaiting an answer), and a 'running' goal that is
+// still QUEUED (decomposed but no task has actually picked up yet — startedAt
+// unset). A goal whose worker is in flight (running + startedAt) or that has
+// already produced a result (review / done / blocked / retesting …) is NOT
+// editable — rewriting its text underneath a live worker or a produced PR would
+// be dishonest; use reply/dismiss for those.
+export const EDITABLE_GOAL_STATUSES = ['stacked', 'sending', 'pending', 'planning', 'needsInput'];
+export function canEditGoal(status, startedAt) {
+  if (EDITABLE_GOAL_STATUSES.includes(status)) return true;
+  if (status === 'running' && !startedAt) return true; // queued: decomposed, not yet started
+  return false;
+}
+
+// DELETE (cancel) is allowed up to and including an actively-running goal:
+// stacked/pending/planning/needsInput/queued cancel with little/nothing to
+// stop, and a truly-running goal is cancelled by SIGTERMing its worker child
+// and dropping its queued tasks (server side). A goal already in review or
+// finished (done) is NOT deleted here — that's the Ledger's Archive/Revert
+// territory, and 'done' keeps its 409 as before.
+export const DELETABLE_GOAL_STATUSES = ['stacked', 'sending', 'pending', 'planning', 'needsInput', 'running', 'partial', 'failed', 'interrupted', 'blocked'];
+export function canDeleteGoal(status) {
+  return DELETABLE_GOAL_STATUSES.includes(status);
+}
+
+// Should the planner surface a clarifying question and park the goal in
+// needsInput? Only on the FIRST plan. Once the user has answered once
+// (goal.clarified, set by /answer), NEVER re-ask — otherwise a re-plan that
+// still returns a question loops the already-answered card back onto the board
+// (Masa: 「一度答えたのに再表示」). The answer is already folded into goal.text,
+// so a re-plan decomposes normally. Structural guarantee: even if the planner
+// LLM disobeys the prompt and returns a question again, this returns false.
+export function shouldAskClarification(clarify, goal) {
+  return !!clarify && !goal?.clarified;
+}
+
+// A human-readable reason for a worker that ended WITHOUT emitting any result
+// text — replaces the old bare "(no output)" that told the user nothing about
+// WHY a task stopped (Masa: 「failedの原因が分からない」). timedOut = the run-time
+// cap SIGTERMed it (a forced stop, not a code bug); exit 143/130 = SIGTERM/SIGINT
+// (timeout or a cancel); any other non-zero = the CLI crashed/exited early.
+export function workerExitReason(code, timedOut, timeoutMs = 10 * 60 * 1000) {
+  const mins = Math.max(1, Math.round(timeoutMs / 60000));
+  // No trailing sentence punctuation — the Attention card embeds this mid-sentence
+  // and appends its own terminator.
+  if (timedOut) return `作業が${mins}分の実行上限に達したため自動停止しました（変更は途中の可能性あり）/ Worker hit the ${mins}-minute run limit and was stopped before finishing (the change may be partial)`;
+  if (code === 143 || code === 130) return '作業が途中で中断されました（レポート未生成）/ The worker was interrupted before it finished, no report was produced';
+  if (code && code !== 0) return `作業ツールが途中で終了しました（exit ${code}、レポート未生成）/ The worker tool exited early (exit ${code}) and produced no report`;
+  return '(no output)';
+}
+
+// Compose the text saved as task.result from a worker run. When the worker
+// emitted a real report, use it. When it did NOT (killed mid-run / crashed),
+// fall back to a concrete reason AND — for a forced stop — append the LAST thing
+// it was doing when it was cut off, so the Attention card shows both WHY it
+// stopped and HOW FAR it got (Masa: 「どこまでやったか分かるように」).
+export function workerResultText({ result = '', err = '', code = 0, timedOut = false, lastAct = '', timeoutMs } = {}) {
+  if (result && result.trim()) return result;
+  const stderr = String(err || '').trim().slice(0, 1000);
+  if (stderr) return stderr;
+  const reason = workerExitReason(code, timedOut, timeoutMs);
+  const tail = String(lastAct || '').trim().slice(0, 300);
+  return tail && isForcedStop(code, timedOut) ? `${reason}\n最後の作業 / last step: ${tail}` : reason;
+}
+
+// Was the worker forcibly STOPPED (timeout or SIGTERM) rather than failing on
+// its own? Such a task is 'interrupted' (retryable, not a code failure) — never
+// a bare 'failed', which reads as "the worker's code was wrong". Mirrors the
+// budget-breach precedent (goal-guardrails: interrupted, human-visible).
+export function isForcedStop(code, timedOut) {
+  return Boolean(timedOut) || code === 143 || code === 130;
+}
+
+// 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 &&
+// proof.pass). A weak auto-snapshot (no .verified) never promotes an interrupted
+// goal, so genuinely-incomplete work still lands in Attention for a human.
+// (Proposal 3: a run-cap timeout that happened AFTER the change was proven good
+// should reach Review, not sit in 'partial' looking like a failure.)
+export function taskCountsAsComplete(task) {
+  if (['done', 'skipped'].includes(task?.status)) return true;
+  return task?.status === 'interrupted' && task?.proof?.verified === true && task?.proof?.pass === true;
+}
+
+// Should the chat stream auto-scroll to the bottom after a re-render?
+// Only true while the user is already at (or within `threshold`px of) the
+// bottom — otherwise a re-render triggered by an unrelated status update
+// (SSE, task progress, …) would yank them away from log they're reading.
+export function shouldAutoScroll(scrollTop, scrollHeight, clientHeight, threshold = 100) {
+  return scrollHeight - clientHeight - scrollTop <= threshold;
+}
+
+// Decide the scrollTop to apply *after* a re-render replaces #stream's HTML
+// (task 93). `pre` is the element's geometry captured BEFORE the innerHTML
+// swap; `newScrollHeight` is its height AFTER. If the user was near the bottom
+// we follow the new bottom; otherwise we pin the exact prior scrollTop so
+// reading old history is never yanked by an incoming SSE/refresh render.
+export function nextStreamScrollTop(pre, newScrollHeight, threshold = 100) {
+  return shouldAutoScroll(pre.scrollTop, pre.scrollHeight, pre.clientHeight, threshold)
+    ? newScrollHeight
+    : pre.scrollTop;
+}
+
+// GET /api/state payload for tasks (task 49): the browser's live activity
+// log (state.act) is otherwise only ever populated by streamed SSE 'act'
+// events, so a page refresh mid-run would blank a running task's log until
+// new lines arrive. Send the already-accumulated `activity` back for
+// running tasks so the client can seed state.act from it; every other
+// status never renders activity, so it's stripped to keep the payload
+// small (activity is capped at 200 lines/task but there can be many tasks).
+export function trimTaskActivityForState(tasks) {
+  // activity + todos are live-only: a running task keeps them so a UI reload
+  // restores the in-flight log/checklist; a finished task drops both.
+  return tasks.map((t) => t.status === 'running' ? t : (({ activity, todos, ...rest }) => rest)(t));
+}
+
+// PROOF.md for a goal PR: one section per verified task, GIF auto-plays.
+export function buildGoalProofMd({ goalText, items }) {
+  return [
+    `# Proof / 動作確認`,
+    ``,
+    `Goal / ゴール: ${String(goalText ?? '').replace(/\s+/g, ' ').slice(0, 300)}`,
+    ``,
+    `Each task below was verified independently by Manager for AI in a headless browser (deterministic check, no LLM at verification time).`,
+    `以下の各タスクは Manager for AI が headless ブラウザで独立検証しました（検証はdeterministic・検証時にLLMは使いません）。`,
+    ``,
+    ...items.flatMap((it) => [
+      `## ${it.num} ${it.title}`,
+      ``,
+      `Pass condition / 成功条件: ${it.passCondition}`,
+      ``,
+      it.beforeShotName ? `Before / 変更前:\n\n![before](./${it.beforeShotName})\n` : '',
+      it.beforeShotName ? `After / 変更後:\n` : '',
+      it.gifName ? `![demo](./${it.gifName})\n` : '',
+      it.shotName ? `![proof](./${it.shotName})\n` : '',
+      it.videoName ? `Full-quality video / 高画質mp4: [${it.videoName}](./${it.videoName})\n` : '',
+      `Result / 結果: ${it.detail}`,
+      ``,
+    ]),
+  ].filter((l) => l !== '').join('\n');
+}
+
+// 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);
+  if (!files.length) return true;
+  return files.some((f) => !DOC_ONLY_RE.test(f));
+}
+
+// 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);
+}
+
+// Task 56: a project's review definition can carry a free-text `description`
+// written in the Review settings panel (e.g. "GitHubにプルリクエストを出して
+// ください"). Before this, that text only showed up next to the Review
+// column and had no effect on the PR Manager for AI actually opens. Fold it
+// into the PR body as its own section so the rule is visibly reflected in
+// the goal's PR, not just displayed in the UI. Returns [] (nothing to
+// splice in) when there is no description to show.
+export function buildReviewRuleSection(description) {
+  const text = String(description ?? '').trim();
+  if (!text) return [];
+  return [
+    `## Review rule / レビュールール`,
+    ``,
+    text,
+    ``,
+  ];
+}
+
+// Stable reorder: items whose ids appear in `ids` follow that order (in the
+// positions they occupied); everything else keeps its place.
+export function orderByIds(arr, ids, getId = (x) => x.id) {
+  const want = ids.map(Number);
+  const targets = arr.filter((x) => want.includes(Number(getId(x))));
+  targets.sort((a, b) => want.indexOf(Number(getId(a))) - want.indexOf(Number(getId(b))));
+  let i = 0;
+  return arr.map((x) => (want.includes(Number(getId(x))) ? targets[i++] : x));
+}
+
+// Drag-reorder for the "To do" queue: only 'queued' tasks may change
+// position. A task that has already been picked up (status 'running') must
+// never be paused or reprioritized by a To-do reorder, so it's excluded from
+// the reorder entirely and kept exactly where it was.
+export function reorderQueue(waiting, ids) {
+  const queued = waiting.filter((t) => t.status === 'queued');
+  const rest = waiting.filter((t) => t.status !== 'queued');
+  return [...orderByIds(queued, ids), ...rest];
+}
+
+// Priority queue ordering: '高' runs before '中' before '低'. A task with no
+// priority (or an unrecognized value) is treated as '中', matching the
+// default new tasks are created with. Array.prototype.sort is a stable sort
+// (guaranteed by the spec), so this never disturbs the relative order tasks
+// already have within the same priority — that incoming order already
+// reflects creation order (queues.waiting is appended to in creation order)
+// and any drag reorder (reorderQueue above, which is itself order-preserving
+// for everything it doesn't touch). Callers should feed this the array
+// *after* applying a drag reorder, so a drag only ever re-ranks within a
+// priority band rather than fighting it.
+export const TASK_PRIORITIES = ['高', '中', '低'];
+const PRIORITY_WEIGHT = { 高: 0, 中: 1, 低: 2 };
+export function sortQueueByPriority(tasks) {
+  return tasks
+    .map((t, i) => ({ t, i }))
+    .sort((a, b) => (PRIORITY_WEIGHT[a.t.priority] ?? 1) - (PRIORITY_WEIGHT[b.t.priority] ?? 1) || a.i - b.i)
+    .map(({ t }) => t);
+}
+
+// ---- per-project bounded parallelism ---------------------------------------
+// Masa: "same project でも conflict しないものは並列で実装してほしい" — each
+// goal already runs in its own isolated git worktree (server.mjs goalWorkDir),
+// so different goals' tasks can safely execute at the same time; only a
+// SINGLE goal's OWN tasks must stay sequential (task 2 depends on task 1's
+// work being on disk already). These two pure helpers decide "how many more
+// tasks can I start right now" — server.mjs's pump() is the only caller that
+// touches real child processes / the running Set.
+
+// Clamp an env-provided concurrency limit to a sane range: at least 1 (a
+// misconfigured 0/negative/non-numeric value must never wedge the queue
+// entirely), at most `max` (a hard safety cap so a typo like "40" can't spawn
+// forty `claude` processes). Falls back to `def` when unset/unparsable.
+export function clampParallelLimit(value, { def = 2, min = 1, max = 4 } = {}) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 1) return def;
+  return Math.min(Math.max(Math.floor(n), min), max);
+}
+
+// Is there room to start another task, given how many are already running
+// and the current limit (project-level or global-level — same shape either
+// way)? A non-positive/NaN limit never permits starting anything.
+export function canStartMore(runningCount, limit) {
+  return Number.isFinite(limit) && limit > 0 && (runningCount ?? 0) < limit;
+}
+
+// Pick up to `limit` tasks from the front of `waiting` that are safe to start
+// RIGHT NOW, preserving same-goal ordering: a goal already represented in
+// `runningGoalIds` (has an in-flight task) contributes nothing this round,
+// and once this round has picked one task for a goal, no LATER task for that
+// same goal is picked alongside it (its siblings were pushed after it, in
+// plan order, so this is exactly "only the earliest not-yet-running task per
+// goal is runnable"). Different goals interleaved in `waiting` are otherwise
+// left in their existing order. Pure — callers own actually starting/tracking
+// the tasks and the worktree/child-process side effects.
+export function nextRunnableTasks(waiting, runningGoalIds, limit) {
+  if (!Number.isFinite(limit) || limit <= 0) return [];
+  const busy = new Set(runningGoalIds ?? []);
+  const claimedThisRound = new Set();
+  const picked = [];
+  for (const task of waiting ?? []) {
+    if (picked.length >= limit) break;
+    const gid = task?.goalId;
+    if (gid != null) {
+      if (busy.has(gid) || claimedThisRound.has(gid)) continue;
+      claimedThisRound.add(gid);
+    }
+    picked.push(task);
+  }
+  return picked;
+}
+
+// Drag-and-drop insertion point: given the hovered row's bounding rect
+// ({top, bottom}, as from Element.getBoundingClientRect()) and the pointer's
+// clientY, decide whether the drop belongs above that row (top half) or
+// below it (bottom half). Drives both the insertion-line indicator shown
+// while dragging and reorderByDrop below, so what the user sees lines up
+// with where the item actually lands.
+export function dndDropsAfter(rect, clientY) {
+  const mid = rect.top + (rect.bottom - rect.top) / 2;
+  return clientY >= mid;
+}
+
+// Recompute the ordered id list for a drag-drop, placing `draggedId` just
+// before/after `targetId` (rather than always immediately before it, as a
+// naive splice would) so the reordered list matches the half of `targetId`
+// the pointer was over when it dropped.
+export function reorderByDrop(ids, draggedId, targetId, after) {
+  if (draggedId === targetId) return ids.slice();
+  const arr = ids.filter((id) => id !== draggedId);
+  const idx = arr.indexOf(targetId);
+  if (idx === -1) return ids.slice();
+  arr.splice(idx + (after ? 1 : 0), 0, draggedId);
+  return arr;
+}
+
+// Bucket a goal's status into the four states shown on a Tasks-panel group
+// header: queued tasks haven't started (todo), planning/running is active
+// work (doing), an open PR awaits a human (review), everything else finished
+// (done/partial/failed/interrupted all read as "done" — the failure detail
+// is already visible on the task rows underneath).
+//
+// A goal moves to 'running' as soon as planning finishes, but its tasks all
+// start out 'queued' — nothing is actually executing yet. goal.startedAt only
+// gets set once the first non-reply task picks up (server.mjs), so a
+// 'running' goal without startedAt is still queued from the user's point of
+// view; only once startedAt is set has work actually begun (doing).
+export function goalGroupStatus(goalStatus, startedAt) {
+  if (goalStatus === 'stacked' || goalStatus === 'sending') return 'todo';
+  if (goalStatus === 'running' && !startedAt) return 'todo';
+  if (goalStatus === 'planning' || goalStatus === 'running') return 'doing';
+  if (goalStatus === 'review') return 'review';
+  if (goalStatus === 'retesting') return 'doing'; // Ledger Dismiss → engine re-testing ×3 (v45 §5.3)
+  if (goalStatus === 'blocked') return 'attn'; // §4E: blocked is Attention, not Done
+  if (goalStatus === 'needsInput') return 'todo'; // smart intake: awaiting an answer
+  return 'done'; // includes 'reverted' (terminal)
+}
+
+// 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.
+//
+// `columns` (task 44: a project's custom workflow column list, as saved by
+// validateWorkflowColumns) lets the chip text follow a renamed stage — e.g.
+// once a project renames its "review" column to "審査待ち", a goal sitting
+// in review shows that name here too, not just in the Tasks-panel section
+// header. Omitting `columns` (existing callers, and any project that never
+// customized) reproduces the original hardcoded English labels exactly, so
+// this is a pure additive refactor. A goal that failed/partially failed
+// always reads as FAIL regardless of how the "done" column got renamed —
+// that distinction lives on the task rows underneath and must stay visible,
+// not get relabeled into whatever "done" is called today.
+//
+// `startedAt` (goal.startedAt, set once the first non-reply task actually
+// starts running — see goalGroupStatus above) disambiguates 'running': a
+// goal that just finished planning has every task still 'queued', so it
+// reads as QUEUED until startedAt is set, then flips to DOING.
+export function goalChip(goalStatus, columns, startedAt) {
+  if (goalStatus === 'stacked' || goalStatus === 'sending') return [pickColumnLabel(columns, 'todo', 'QUEUED'), ''];
+  if (goalStatus === 'running' && !startedAt) return [pickColumnLabel(columns, 'todo', 'QUEUED'), ''];
+  if (goalStatus === 'planning' || goalStatus === 'running') return [pickColumnLabel(columns, 'doing', 'DOING'), 'doing'];
+  if (goalStatus === 'review') return [pickColumnLabel(columns, 'review', 'REVIEW'), 'review'];
+  if (goalStatus === 'done') return [pickColumnLabel(columns, 'done', 'DONE'), ''];
+  if (goalStatus === 'retesting') return ['RE-TESTING', 'doing']; // Ledger Dismiss → retest ×3 (v45 §5.3)
+  if (goalStatus === 'reverted') return ['REVERTED', '']; // Ledger Revert: terminal, distinct from archived
+  if (goalStatus === 'blocked') return ['BLOCKED', 'blocked']; // §4E: distinct state (reason + reverify), not FAIL/Done
+  if (goalStatus === 'needsInput') return ['確認待ち', 'blocked']; // smart intake: awaiting an answer
+  return ['FAIL', ''];
+}
+
+// Group a flat task list under their parent goal for the Tasks sidebar, so
+// a goal like "この体験を実現したい" shows as one collapsible unit instead of
+// its tasks scattered flat in the list. Each group carries a done/total
+// count (e.g. "2/5") and a status bucket derived from the goal itself, so
+// the caller doesn't need to re-derive goal state to build the header. Tasks
+// whose goal isn't in `goals` (deleted goal, or filtered out by the caller)
+// come back separately as orphanTasks rather than being dropped.
+export function groupTasksByGoal(tasks, goals) {
+  const groups = goals.map((g) => {
+    const gtasks = tasks.filter((t) => t.goalId === g.id);
+    return {
+      goal: g,
+      tasks: gtasks,
+      done: gtasks.filter((t) => t.status === 'done').length,
+      total: gtasks.length,
+      status: goalGroupStatus(g.status, g.startedAt),
+    };
+  });
+  const orphanTasks = tasks.filter((t) => !goals.some((g) => g.id === t.goalId));
+  return { groups, orphanTasks };
+}
+
+// Group an already-ordered task list under their goals, preserving the order
+// in which each goal first appears in `tasks` (so the section's own sort —
+// queue order for To do, num-desc for Done — is respected across groups and
+// within them). Tasks whose goal isn't in `goals` collect into a trailing
+// group with goal:null. Used to render per-goal headings in each Kanban
+// column. Returns [{ goal, tasks }] with no empty groups.
+export function groupTasksByGoalOrdered(tasks, goals) {
+  const byId = new Map(goals.map((g) => [g.id, g]));
+  const order = [];
+  const map = new Map();
+  for (const t of tasks) {
+    const key = byId.has(t.goalId) ? t.goalId : null;
+    if (!map.has(key)) { map.set(key, []); order.push(key); }
+    map.get(key).push(t);
+  }
+  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;
+}
+
+// Review digest (task 227): one row per review-pending goal, collapsed to a
+// single scannable line — check text, proof, test result, PR link — so a
+// reviewer can approve/reject without opening each goal individually. Goals
+// that share the same PR (a common goal-decomposed-into-several-tasks case)
+// collapse into one row instead of showing the same PR link twice; goals with
+// no PR never dedup against each other since there's nothing to key on.
+// Mirrored in app/index.html since the inline browser script can't import
+// this module.
+export function buildReviewDigest({ goals, tasks } = {}) {
+  const rows = [];
+  const byPr = new Map();
+  for (const g of goals ?? []) {
+    if (g?.status !== 'review') continue;
+    const goalTasks = (tasks ?? []).filter((t) => t.goalId === g.id);
+    const checkLine = (g.reviewSummary?.check || g.plan?.[0] || g.text || '').replace(/\s+/g, ' ').trim().slice(0, 66);
+    const plan = isPlanReview(g);
+    const row = {
+      goalIds: [g.id],
+      reviewNumber: goalReviewNumber({ goal: g, tasks }),
+      checkLine: plan ? `PLAN — approve to execute: ${checkLine}`.slice(0, 90) : checkLine,
+      pr: g.pr ?? null,
+      testResult: g.testResult ?? null,
+      proof: goalTasks.find((t) => t.proof)?.proof ?? null,
+      plan,
+      planText: plan ? (g.planText ?? '') : null,
+    };
+    if (row.pr && byPr.has(row.pr)) {
+      const existing = byPr.get(row.pr);
+      existing.goalIds.push(g.id);
+      if (row.reviewNumber != null && (existing.reviewNumber == null || row.reviewNumber < existing.reviewNumber)) {
+        existing.reviewNumber = row.reviewNumber;
+      }
+      if (existing.proof == null) existing.proof = row.proof;
+      if (existing.testResult == null) existing.testResult = row.testResult;
+      continue;
+    }
+    if (row.pr) byPr.set(row.pr, row);
+    rows.push(row);
+  }
+  return rows;
+}
+
+// Does this goal ask for a pull request?
+export function wantsPullRequest(text) {
+  return /プルリク|pull\s*request|(^|[^A-Za-z])PR([^A-Za-z]|$)/i.test(String(text ?? ''));
+}
+
+// Task 46: the "Deliverable" toggle (pr | none | auto) on task creation and
+// editing. An explicit 'pr'/'none' always wins over the text heuristic, so
+// a user's choice survives editing the goal's text afterwards. `projectDefault`
+// (task 45: a project's reviewDefinition.defaultWantsPR, edited from the same
+// settings panel as the review definition) is only consulted for 'auto' when
+// the text itself gives no signal either way — an explicit "PRを作って" in the
+// text still wins even if the project's default is off, matching the
+// pre-task-45 behavior that new callers who omit this argument keep exactly.
+export function resolveWantsPR(pr, text, projectDefault = false) {
+  return pr === 'pr' ? true : pr === 'none' ? false : (wantsPullRequest(text) || !!projectDefault);
+}
+
+// Task 90: which entry point created a goal (Web chat / MCP / future API),
+// shown as a small badge next to the goal. Only the known values are
+// trusted; anything else (or a missing field, e.g. goals created before this
+// field existed) falls back to 'web' since that's the original and still
+// most common path. `sourceRef` is a reserved slot for a future Notion/Linear
+// ticket id or URL — always null today, populated once that integration exists.
+export const GOAL_SOURCES = ['web', 'mcp', 'api'];
+export function resolveGoalSource(input) {
+  return GOAL_SOURCES.includes(input) ? input : 'web';
+}
+
+// A project's review definition (task 45): configurable conditions that
+// decide whether a finished goal needs a human's review (status 'review')
+// or ships straight to 'done'/'partial'. requirePR reproduces the original,
+// hardcoded behavior — a goal that wants a PR always needs review, even if
+// PR creation itself failed (goal.prError carries the reason). Toggling it
+// off lets a project skip review entirely for PR-less workflows.
+// requireVerifyPass additionally forces review unless every task in the
+// goal has an independent headless-browser verification that passed
+// (task.proof.pass === true) — a task with no passCondition at all (so
+// proof stays null) does not satisfy it either, since "verify結果必須" means
+// a verify result is mandatory, not merely allowed to be absent.
+// `description` is free text explaining, to a human looking at the board,
+// what this project's review step actually checks — it has no effect on
+// nextGoalStatus() below, it just gets displayed next to the Review column.
+// `defaultWantsPR` is the fallback used by resolveWantsPR() above when a new
+// or edited goal leaves the Deliverable toggle on 'auto' and its text gives
+// no explicit signal — it decides whether *this project* opens PRs by
+// default, separately from whether a PR-wanting goal must go through review.
+// `language` is the output language for the Manager's review-facing text
+// (e.g. summarizeForReview's plain-language headline) — 'ja' or 'en' only.
+// `prSections` toggles which sections createGoalPR includes in the PR body;
+// `reviewCard` toggles what the review checklist card shows for each task.
+export const DEFAULT_REVIEW_DEFINITION = {
+  requirePR: true,
+  requireVerifyPass: false,
+  description: '',
+  defaultWantsPR: false,
+  language: 'ja',
+  prSections: { summary: true, whatChanged: true, howToReview: true, tests: true, screenshots: true, risk: true },
+  reviewCard: { screenshots: true, beforeAfter: false },
+};
+
+// Normalize a nested boolean-flag object (prSections/reviewCard) key by key,
+// so a partial payload — or one missing the whole sub-object — can't
+// silently disable flags it never mentioned; each key falls back to its own
+// default independently rather than the sub-object being replaced wholesale.
+function normalizeBoolMap(input, defaults) {
+  const out = {};
+  for (const key of Object.keys(defaults)) {
+    out[key] = (input && typeof input === 'object' && !Array.isArray(input) && input[key] !== undefined)
+      ? !!input[key] : defaults[key];
+  }
+  return out;
+}
+
+// Validate + normalize a project's review definition (from the settings
+// panel's Save button). Missing fields fall back to the default rather than
+// `false`, so a partial payload can't silently disable an existing
+// requirement.
+export function validateReviewDefinition(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { ok: false, error: 'review definition object required' };
+  return {
+    ok: true,
+    definition: {
+      requirePR: input.requirePR !== undefined ? !!input.requirePR : DEFAULT_REVIEW_DEFINITION.requirePR,
+      requireVerifyPass: input.requireVerifyPass !== undefined ? !!input.requireVerifyPass : DEFAULT_REVIEW_DEFINITION.requireVerifyPass,
+      description: input.description !== undefined ? String(input.description).slice(0, 500) : DEFAULT_REVIEW_DEFINITION.description,
+      defaultWantsPR: input.defaultWantsPR !== undefined ? !!input.defaultWantsPR : DEFAULT_REVIEW_DEFINITION.defaultWantsPR,
+      language: (input.language === 'ja' || input.language === 'en') ? input.language : DEFAULT_REVIEW_DEFINITION.language,
+      prSections: normalizeBoolMap(input.prSections, DEFAULT_REVIEW_DEFINITION.prSections),
+      reviewCard: normalizeBoolMap(input.reviewCard, DEFAULT_REVIEW_DEFINITION.reviewCard),
+    },
+  };
+}
+
+// What should goal.status become once all its tasks have finished? Driven
+// by the project's review definition above — a completed-but-unreviewed
+// goal must never read as "done", or a required review step silently gets
+// skipped.
+// Every finished goal lands in Review for a human check first — nothing reaches
+// Done unchecked. (Bug: previously only PR-wanting goals or verify-failures were
+// gated, so with defaultWantsPR:false the common non-PR goal slipped straight to
+// Done without review. Masa: 本来すべての to do が review に来るべき.) A human
+// Approve in the Manager (advanceReviewGoal/approveGoal) is what moves it to Done;
+// reviewToDoneStatus still auto-closes from the PR side. Only a goal that didn't
+// finish all its work stays 'partial' (its failed tasks show in Attention).
+export function nextGoalStatus({ allDone, wantsPR, allVerified = true, reviewDefinition = DEFAULT_REVIEW_DEFINITION }) {
+  return allDone ? 'review' : 'partial';
+}
+
+// チェックリストUIで要件が全件Approveされたら goal を review→done へ進める。
+// 以前は「PRありgoalはマージが唯一の完了トリガー」として弾いていたが、それだと
+// 承認しても done が永続化されず次のrefreshで review に戻る不具合になっていた
+// (しかもPR作成はしばしば失敗する)。approveGoal と同じくPRの有無で門前払いしない。
+// review→done はGitHub側からも自動で閉じる(syncGoalMerges/isPrApproved)——これは
+// 人がアプリ側から閉じる経路。
+export function advanceReviewGoal(goal) {
+  if (goal.status !== 'review') return { ok: false, error: 'goal is not in review' };
+  return { ok: true, status: 'done' };
+}
+
+// advanceReviewGoal の逆操作（『元に戻す』ボタン）。対称に揃え、PRの有無で弾かない
+// ——どの done ゴールも review へ戻せる。
+export function revertReviewGoal(goal) {
+  if (goal.status !== 'done') return { ok: false, error: 'goal is not done' };
+  return { ok: true, status: 'review' };
+}
+
+// レビュー詳細パネル(task 70)のApprove/Dismissボタンの判定。advanceReviewGoal(task 62,
+// チェックリスト全件Approveの自動進行)とは別に、人間がレビュー画面から単発で下す判断
+// を扱う——PRの有無を問わず、レビュー中のgoalだけが対象。
+// Approveはそのままdoneへ。goalGroupStatus/goalChipのdone分岐(review以外は全部doneと
+// 読む)と揃えているので、doneに寄せて問題ない。
+export function approveGoal({ goalStatus }) {
+  if (goalStatus !== 'review') return { ok: false, error: 'goal is not in review' };
+  return { ok: true, status: 'done' };
+}
+
+// Dismiss(差し戻し)は 'running' に戻す——goalGroupStatus/goalChipは 'running' を
+// startedAt済みなら'doing'バケットに読むので、これでレビュー中断→作業中の表示に戻る。
+export function dismissGoal({ goalStatus }) {
+  if (goalStatus !== 'review') return { ok: false, error: 'goal is not in review' };
+  return { ok: true, status: 'running' };
+}
+
+// ---- MODE (Auto / Plan) ----------------------------------------------------
+// A goal runs in one of two modes. 'auto' = the default implement→verify→review
+// flow (worker edits files with acceptEdits). 'plan' = the worker runs under
+// Claude Code's `--permission-mode plan` and produces a PLAN only, making NO
+// file edits; the plan lands in Review as "PLAN — approve to execute".
+export const GOAL_MODES = ['auto', 'plan'];
+
+// Map a goal/task mode to the Claude Code CLI `--permission-mode` value.
+// Unknown / unset → 'acceptEdits' (unchanged default behavior). Only 'plan'
+// switches the worker into propose-a-plan-first mode.
+export function permissionModeFor(mode) {
+  return mode === 'plan' ? 'plan' : 'acceptEdits';
+}
+
+// A plan-review is a goal sitting in Review whose deliverable is a PLAN awaiting
+// human approval (no PR, no proof gate — there are no changes to prove). This
+// distinguishes it from a normal review so Approve re-queues to EXECUTE rather
+// than filing it to Done.
+export function isPlanReview(goal) {
+  return !!goal && goal.status === 'review' && goal.planPhase === 'awaiting-approval';
+}
+
+// Approving a plan-review does NOT file it to Done — it re-queues the SAME goal
+// to EXECUTE the approved plan: flip mode to 'auto' (acceptEdits), mark
+// planPhase 'executing', and run the normal implement→verify→review flow. The
+// caller re-queues the goal's tasks and injects goal.planText as context.
+export function nextAfterPlanApprove(goal) {
+  if (!isPlanReview(goal)) return { ok: false, error: 'goal is not a plan awaiting approval' };
+  return { ok: true, mode: 'auto', planPhase: 'executing', status: 'running' };
+}
+
+// Interpret a `gh pr view <url> --json state,mergedAt` result. GitHub's PR
+// state is MERGED once merged (mergedAt is also set), but a fork/rebase-merge
+// can in principle carry a stale state while mergedAt is already populated,
+// so check both.
+export function isPrMerged({ state, mergedAt } = {}) {
+  return state === 'MERGED' || !!mergedAt;
+}
+
+// Interpret the same `gh pr view` result's reviewDecision field
+// (APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED / null).
+export function isPrApproved({ reviewDecision } = {}) {
+  return reviewDecision === 'APPROVED';
+}
+
+// A 'review' goal whose PR merged OR was approved is done; every other goal
+// status (and a still-open, unapproved PR) passes through unchanged — this
+// never regresses a goal out of 'review' on its own.
+export function reviewToDoneStatus({ goalStatus, merged }) {
+  // Only an actual MERGE closes a review (= the change shipped). A GitHub PR
+  // *approval* must NOT auto-Done on reload — you review IN the Manager, so an
+  // external approval silently clearing your Review was the "勝手にdone" surprise.
+  return goalStatus === 'review' && merged ? 'done' : goalStatus;
+}
+
+// Build the proof PR body (EN + JA, no emoji) and the PROOF.md committed to
+// the branch. In private repos, raw.githubusercontent URLs 404 inside PR
+// bodies (GitHub's image proxy cannot authenticate), so images live in a
+// committed PROOF.md whose blob page renders them for any signed-in member.
+export function buildProofBody({ owner, branch, proofRel, shotName, videoName, gifName, passCondition, attempts, appRel }) {
+  const blob = (rel) => `https://github.com/${owner}/blob/${branch}/${rel.replace(/\\/g, '/')}`;
+  const proofPage = blob(`${proofRel}/PROOF.md`);
+  const tried = attempts.map((a) => `${a.attempt}:${a.pass ? 'pass' : 'fail'}`).join(', ');
+
+  const proofMd = [
+    `# Proof / 動作確認`,
+    ``,
+    `Pass condition / 成功条件: ${passCondition}`,
+    ``,
+    `Verified independently by Manager for AI in a headless browser. The worker's self-report is never trusted.`,
+    `Manager for AI が headless ブラウザで独立検証しました（workerの自己申告は信用しない設計）。`,
+    ``,
+    gifName ? `## Video / 動画（自動再生）\n\n![demo](./${gifName})\n` : '',
+    `## Screenshot / スクリーンショット`,
+    ``,
+    `![proof](./${shotName})`,
+    ``,
+    videoName ? `Full-quality video / 高画質mp4: [${videoName}](./${videoName})\n` : '',
+    `Attempts / 試行: ${tried}`,
+  ].filter((l) => l !== '').join('\n');
+
+  const body = [
+    `## Proof / 動作確認 — one tap, plays in place / 1タップでその場で動きます`,
+    ``,
+    `${proofPage}`,
+    ``,
+    `(GitHub cannot render images inside private-repo PR bodies, so the proof video (GIF) and screenshot auto-play on the page above.)`,
+    `(privateリポジトリのPR本文には画像を出せないGitHub仕様のため、上のページでproof動画(GIF)とスクショが自動再生されます。)`,
+    ``,
+    `## What this proves / このPRが証明すること`,
+    ``,
+    `Pass condition / 成功条件: ${passCondition}`,
+    ``,
+    `Manager for AI verified this change independently in a headless browser (video + screenshot recorded at verification time). The worker's self-report is never trusted.`,
+    `Manager for AI が headless ブラウザで独立検証しました（検証時に動画とスクショを記録。workerの自己申告は信用しない設計）。`,
+    ``,
+    videoName ? `Full-quality video / 高画質mp4: ${blob(`${proofRel}/${videoName}`)}` : '',
+    ``,
+    `Attempts / 試行: ${tried} — Target / 対象: \`${appRel}\``,
+  ].filter((l) => l !== '').join('\n');
+
+  return { body, proofMd };
+}
+
+// Parse `git log --pretty=format:%H%x1f%ad%x1f%an%x1f%s --date=iso-strict`
+// output (one commit per line, fields separated by \x1f) into
+// [{hash, date, author, subject}], newest-first (git's own order).
+export function parseGitLog(rawText) {
+  return String(rawText ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [hash, date, author, ...rest] = line.split('\x1f');
+      return { hash: hash ?? '', date: date ?? '', author: author ?? '', subject: rest.join('\x1f') };
+    });
+}
+
+// `git status --porcelain` is empty (only whitespace) exactly when the
+// working tree has nothing to commit. Used to skip a rework push when a
+// reply task changed nothing (e.g. a comment-only follow-up) instead of
+// letting `git commit` fail on an empty tree.
+export function hasGitChanges(porcelainStatus) {
+  return Boolean(String(porcelainStatus ?? '').trim());
+}
+
+// ---- merge-time conflict detection -----------------------------------------
+// Parallel goals never corrupt each other's WORKING files (each runs in its
+// own worktree) — but two goals that edited the same repo path will still
+// conflict when both branches try to land on main. Detection is deterministic
+// (plain path-set overlap, no LLM) and runs at goal-finish time (server.mjs
+// updateGoalConflicts), comparing the just-finished goal's changed files
+// against siblings that are still running or awaiting merge.
+
+// Do these two file lists share at least one path? Order-independent, and
+// an empty/missing list on either side can never "conflict" (nothing to
+// overlap with — most commonly a no-code goal, or a sibling whose worker
+// hasn't changed anything yet).
+export function goalsConflict(filesA, filesB) {
+  const a = filesA ?? [], b = filesB ?? [];
+  if (!a.length || !b.length) return false;
+  const setA = new Set(a);
+  return b.some((f) => setA.has(f));
+}
+
+// Which of `otherGoals` (each `{ id, changedFiles }`) touch at least one path
+// this goal (`{ id, changedFiles }`) also touched? Returns their ids, in the
+// order they appear in `otherGoals` — server.mjs stamps these onto
+// `goal.conflictsWith` (and, reciprocally, onto each flagged sibling) so
+// Review can surface "touches the same files as #N".
+export function detectConflicts(goal, otherGoals) {
+  const files = goal?.changedFiles ?? [];
+  if (!files.length) return [];
+  return (otherGoals ?? [])
+    .filter((g) => g && g.id !== goal.id && goalsConflict(files, g.changedFiles))
+    .map((g) => g.id);
+}
+
+// Which of `commits` (newest-first, as returned by parseGitLog) are new
+// since we last synced up to `lastSeenHash`? null means nothing has been
+// seen yet, so every commit is new. If lastSeenHash isn't found in the
+// list (e.g. history was rewritten), treat everything as new rather than
+// silently dropping commits.
+export function diffNewCommits(commits, lastSeenHash) {
+  if (lastSeenHash == null) return commits;
+  const idx = commits.findIndex((c) => c.hash === lastSeenHash);
+  if (idx === -1) return commits;
+  return commits.slice(0, idx);
+}
+
+// Task 45/46/62 verification: a freshly booted ephemeral instance of the
+// Manager app (see server.mjs's startEphemeralApp) starts with zero
+// history, but a verify check for completion-time behavior (e.g. "no PR
+// toggle -> no PR at completion", or "the Review section shows this
+// project's review description") needs real finished/settled examples to
+// inspect. Running an actual worker task there to produce one would spawn a
+// live Claude Code worker back onto this very project directory — and since
+// the ephemeral instance has no other goal running, a brand-new goal
+// created there does NOT queue harmlessly: it goes straight to 'planning'
+// and kicks off a REAL background `claude` process immediately, which takes
+// far longer than any UI wait is willing to sit through. So instead these
+// already-settled example goals are seeded directly into the ephemeral
+// instance's queue log before it boots — same JSONL shape replayQueueLog
+// reads on every real restart:
+//   1) finished with a PR (wantsPR: true, pr set)
+//   2) finished without a PR (wantsPR: false, no pr)
+//   3) already sitting in 'review' WITH a PR — app/index.html's
+//      renderTasks() only renders the Review section (and the project's
+//      review description next to it) when at least one goal has status
+//      'review', so without this fixture there is no way to see that text
+//      rendered short of waiting out a real worker run.
+//   4) already sitting in 'review' WITHOUT a PR, with 8 requirement tasks —
+//      this is the only way to exercise the PR-less review checklist
+//      (#reviewOverlay, task 62): that "Review checklist" button only
+//      renders for a review-status goal with g.pr unset (app/index.html),
+//      so a seeded goal that has a PR (like #3 above) can never open it.
+//      Each requirement task carries proof (server.mjs's seedEphemeralHistory
+//      writes matching proof-<id>/proof.gif files to disk) so the checklist's
+//      video/GIF slot has something real to render, not the "no video"
+//      placeholder.
+//   5) a failed/interrupted To Do row with Retry/View log/Archive nearby — so
+//      design proofs for Attention/failed-row work can capture the actual
+//      target UI instead of a generic empty page or the wrong lane.
+export function buildEphemeralSeedLines(at = '2026-01-01T00:00:00.000Z') {
+  const reqTitles = [
+    'ヘッダーにロゴを表示', 'ダークモード切り替え', '検索ボックスの実装', '一覧の無限スクロール',
+    '通知バッジのカウント', 'ログイン画面のバリデーション', 'エクスポートCSVボタン', 'モバイル幅でのレイアウト崩れ修正',
+  ];
+  const reqTasks = reqTitles.map((title, i) => ({
+    kind: 'task', id: 8 + i, num: i + 1, goalId: 7, projectId: 'default', title,
+    detail: `${title}について、要求どおりの見た目・挙動になっているかを確認する。`,
+    passCondition: `${title}が画面上で確認できること`, model: 'sonnet', status: 'done', createdAt: at,
+    result: 'ok', changedFiles: ['fixture.txt'], secs: 1,
+    proof: { pass: true, detail: 'ok', gif: 'proof.gif', png: null, mp4: null }, usage: null, finishedAt: at,
+  }));
+  return [
+    { kind: 'goal', id: 1, projectId: 'default', text: '[verify fixture] PRあり完了ゴール', status: 'done', wantsPR: true, model: 'sonnet', images: [], plan: ['fixture task'], pr: 'https://github.com/example/verify-fixture/pull/1', createdAt: at },
+    { kind: 'task', id: 2, num: 1, goalId: 1, projectId: 'default', title: 'fixture task', detail: '', passCondition: '', model: 'sonnet', status: 'done', createdAt: at, result: 'ok', changedFiles: ['fixture.txt'], secs: 1, proof: { pass: true, detail: 'ok', gif: null, png: null, mp4: null }, usage: null, finishedAt: at },
+    { kind: 'goal', id: 3, projectId: 'default', text: '[verify fixture] PRなし完了ゴール', status: 'done', wantsPR: false, model: 'sonnet', images: [], plan: ['fixture task'], pr: undefined, createdAt: at },
+    { kind: 'task', id: 4, num: 1, goalId: 3, projectId: 'default', title: 'fixture task', detail: '', passCondition: '', model: 'sonnet', status: 'done', createdAt: at, result: 'ok', changedFiles: ['fixture.txt'], secs: 1, proof: { pass: true, detail: 'ok', gif: null, png: null, mp4: null }, usage: null, finishedAt: at },
+    { kind: 'goal', id: 5, projectId: 'default', text: '[verify fixture] レビュー待ちゴール(PRあり)', status: 'review', wantsPR: true, model: 'sonnet', images: [], plan: ['fixture task'], pr: 'https://github.com/example/verify-fixture/pull/2', createdAt: at },
+    { kind: 'task', id: 6, num: 1, goalId: 5, projectId: 'default', title: 'fixture task', detail: '', passCondition: '', model: 'sonnet', status: 'done', createdAt: at, result: 'ok', changedFiles: ['fixture.txt'], secs: 1, proof: { pass: true, detail: 'ok', gif: null, png: null, mp4: null }, usage: null, finishedAt: at },
+    { kind: 'goal', id: 7, projectId: 'default', text: '[verify fixture] レビュー待ちゴール(PRなし・要件8件)', status: 'review', wantsPR: false, model: 'sonnet', images: [], plan: reqTitles, pr: undefined, createdAt: at },
+    ...reqTasks,
+    { kind: 'goal', id: 16, projectId: 'default', text: '[verify fixture] 失敗したTo Do行', status: 'partial', wantsPR: false, model: 'sonnet', images: [], plan: ['失敗行のアクション確認'], pr: undefined, createdAt: at },
+    { kind: 'task', id: 17, num: 9, goalId: 16, projectId: 'default', title: '失敗行のアクション確認', detail: '', passCondition: null, model: 'sonnet', status: 'failed', createdAt: at, result: 'テスト失敗 4 件', changedFiles: ['app/index.html'], secs: 1, proof: null, usage: null, finishedAt: at },
+  ];
+}
+
+export function buildEphemeralSeedLog(at) {
+  return buildEphemeralSeedLines(at).map((l) => JSON.stringify(l)).join('\n') + '\n';
+}
+
+// Task 57 verification: the project sidebar needs a second project to click
+// to prove switching works, but a fresh ephemeral instance (see server.mjs's
+// startEphemeralApp) has no projects.json of its own and would otherwise
+// auto-generate exactly one ('default', named after cwd) — never enough to
+// exercise a switch. Seed a second real entry alongside it; 'default' stays
+// first and keeps its id so it still matches the projectId the seeded goals/
+// tasks above (buildEphemeralSeedLines) reference.
+export function buildEphemeralSeedProjects(cwd) {
+  return [
+    { id: 'default', name: basename(cwd), dir: cwd },
+    { id: 'default-2', name: '[verify fixture] second project', dir: cwd },
+  ];
+}
+
+// Rebuild in-memory { goals, tasks } from the restart-safe queue's
+// append-only JSONL log (engine/chat-runs/tasks.jsonl — one line per
+// goal/task write). This is what a server restart replays from disk, so a
+// goal/task written once (e.g. a memo the user wants to survive a restart)
+// is never lost: later lines for the same id override earlier ones (last
+// write wins), and a goal write with `deleted:true` removes it. Mid-flight
+// work can't resume across a restart, so it's marked retryable rather than
+// silently dropped: a 'running' task becomes 'interrupted', a 'planning'
+// goal goes back to 'stacked', and a 'running' goal with no queued task left
+// settles via nextGoalStatus() — a wantsPR goal lands in 'review' just like
+// the normal completion path, even if the crash happened before the PR got
+// created (the caller re-attempts createGoalPR for those on restart).
+// `reviewDefinitions` (projectId -> definition, as saved by
+// validateReviewDefinition) lets that settling honor each project's own
+// review definition (task 45); a project with none configured falls back to
+// DEFAULT_REVIEW_DEFINITION.
+export function replayQueueLog(rawText, reviewDefinitions = {}) {
+  let goals = [];
+  let tasks = [];
+  for (const line of String(rawText ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.kind === 'goal') { goals = goals.filter((g) => g.id !== e.id); if (!e.deleted) goals.push(e); }
+      else { tasks = tasks.filter((t) => t.id !== e.id); tasks.push(e); }
+    } catch { /* skip a corrupt line rather than lose the whole log */ }
+  }
+  for (const t of tasks) {
+    if (t.status === 'running') t.status = 'interrupted';
+  }
+  for (const g of goals) {
+    if (g.status === 'planning') g.status = 'stacked';
+    else if (g.status === 'running' && !tasks.some((t) => t.goalId === g.id && t.status === 'queued')) {
+      const gt = tasks.filter((t) => t.goalId === g.id);
+      const allDone = gt.length > 0 && gt.every((t) => t.status === 'done');
+      const allVerified = gt.every((t) => t.proof?.pass === true);
+      const reviewDefinition = reviewDefinitions[g.projectId] ?? DEFAULT_REVIEW_DEFINITION;
+      g.status = nextGoalStatus({ allDone, wantsPR: g.wantsPR, allVerified, reviewDefinition });
+    }
+  }
+  const nextId = Math.max(0, ...goals.map((g) => g.id), ...tasks.map((t) => t.id)) + 1;
+  const prioCounter = Math.max(0, ...goals.map((g) => g.prio ?? 0));
+  return { goals, tasks, nextId, prioCounter };
+}
+
+// Boot-time safety net for goals a dead server left with no live worker
+// (Masa dogfood: the To Do pile-up from a goal that never actually resumes).
+// replayQueueLog() above already stops a 'running' goal with no 'queued'
+// sibling task from staying 'running' forever — it settles such a goal via
+// nextGoalStatus() into 'review' or 'partial'. So under the CURRENT
+// replayQueueLog contract, this function is defense in depth: it should never
+// find anything to do against a ledger replayQueueLog itself produced. It
+// exists as an explicit, independently-tested guarantee — scoped to exactly
+// what it says — so that a future change to replayQueueLog's settling logic
+// (or a hand-edited/legacy ledger line) can never leave a goal fake-'running'
+// with nothing that will ever pick it up again.
+//
+// Deliberately narrow: only 'running' goals with no 'queued' sibling task are
+// reaped. An earlier version of this function also reclassified 'partial'
+// goals that had an 'interrupted' sibling task (replayQueueLog's own
+// settling outcome for "some task didn't finish") — that's a real, separate
+// UX gap (such a goal reads as "Done" via goalGroupStatus, which can hide a
+// restart interruption), but it collided with a legitimate, unrelated case:
+// a goal deliberately left 'running' with an 'interrupted' REPLY task
+// awaiting a human's Retry/Skip (see goal-rework-updates-existing-pr.test.mjs)
+// is NOT an orphan — closing that task via /skip must still be able to
+// re-settle the goal through finishGoalIfComplete, which only proceeds from
+// 'running'/'partial'. Reclassifying the goal to 'interrupted' up front
+// permanently blocked that. Widening finishGoalIfComplete's own gate to also
+// accept 'interrupted' would be the correct follow-up for that separate gap,
+// but is out of scope here.
+//
+// Pure: takes/returns plain data, no I/O. The caller (server.mjs, right after
+// replayQueueLog at boot) applies { status, reason } to its own goal objects
+// and saves them.
+export function reconcileOrphanGoals(goals, tasks) {
+  const out = [];
+  for (const g of goals ?? []) {
+    if (g.status !== 'running') continue;
+    const hasQueued = (tasks ?? []).some((t) => t.goalId === g.id && t.status === 'queued');
+    if (hasQueued) continue; // a queued sibling auto-resumes at boot — genuinely resuming, leave alone
+    out.push({ id: g.id, status: 'interrupted', reason: 'サーバ再起動により作業が中断されました。再試行してください。' });
+  }
+  return out;
+}
+
+// The four states the engine actually tracks per goal/task (see
+// goalGroupStatus/goalChip above). A project's workflow columns are a
+// display-layer relabeling/reordering on top of these — every column must
+// still map to one of them so existing status logic keeps working.
+export const WORKFLOW_BUCKETS = ['todo', 'doing', 'review', 'done'];
+
+// Tools a `claude -p` worker may call (--allowedTools). TodoWrite must stay
+// in this list — it's how the UI's To-do section (sendTodos / SSE 'todos')
+// gets any data at all; without it workers can never emit {kind:'todos'}.
+export const WORKER_TOOLS = 'Edit,Write,Read,Glob,Grep,Skill,TodoWrite,Bash(node:*),Bash(npm:*),Bash(npx:*)';
+
+// ---- SKILL picker ----------------------------------------------------------
+// Parse the YAML frontmatter of a SKILL.md / command .md and pull out `name`
+// and `description`. Pure string→object; returns null when there's no name.
+// Handles single-line `key: value` (optionally quoted); long folded/multi-line
+// descriptions collapse to their first line (fine — the picker truncates).
+export function parseSkillFrontmatter(md) {
+  const text = String(md ?? '');
+  const m = text.match(/^?---[ \t]*\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const block = m[1];
+  const bLines = block.split('\n');
+  const grab = (key) => {
+    const re = new RegExp(`^${key}[ \\t]*:[ \\t]*(.*)$`);
+    const idx = bLines.findIndex((l) => re.test(l));
+    if (idx < 0) return null;
+    let v = bLines[idx].match(re)[1].trim();
+    // YAML block scalar (description: > or |): fold the following indented lines.
+    if (v === '>' || v === '|' || /^[>|][+-]?$/.test(v)) {
+      const folded = [];
+      for (let i = idx + 1; i < bLines.length; i++) {
+        if (!/^\s+\S/.test(bLines[i]) && bLines[i].trim() !== '') break;
+        folded.push(bLines[i].trim());
+      }
+      v = folded.join(' ').trim();
+    }
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    return v.trim();
+  };
+  const name = grab('name');
+  if (!name) return null;
+  return { name, description: grab('description') ?? '' };
+}
+
+function truncateSkillDesc(s, n = 140) {
+  const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t;
+}
+
+// Read a resolved list of skill/command source directories and return a
+// de-duplicated list of { name, description, source, kind }. Each source is
+// { dir, source:'user'|'project', kind:'skill'|'command' }:
+//   kind 'skill'   → dir has <name>/SKILL.md subfolders
+//   kind 'command' → dir has *.md files
+// Dedup is by kind:name, first occurrence wins (pass user sources before
+// project so a project override doesn't hide the user one silently — both are
+// the same name anyway). Missing dirs are skipped, not an error.
+export function collectSkills(sources = []) {
+  const out = [];
+  const seen = new Set();
+  const add = (name, description, source, kind) => {
+    const k = `${kind}:${name}`;
+    if (seen.has(k)) return;
+    seen.add(k);
+    out.push({ name, description: truncateSkillDesc(description), source, kind });
+  };
+  for (const src of sources) {
+    if (!src || !src.dir || !existsSync(src.dir)) continue;
+    if (src.kind === 'skill') {
+      let entries = [];
+      try { entries = readdirSync(src.dir, { withFileTypes: true }); } catch { continue; }
+      for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const md = join(src.dir, e.name, 'SKILL.md');
+        if (!existsSync(md)) continue;
+        let parsed = null;
+        try { parsed = parseSkillFrontmatter(readFileSync(md, 'utf8')); } catch { /* unreadable */ }
+        add(parsed?.name || e.name, parsed?.description, src.source, 'skill');
+      }
+    } else if (src.kind === 'command') {
+      let files = [];
+      try { files = readdirSync(src.dir); } catch { continue; }
+      for (const f of files.sort()) {
+        if (!f.endsWith('.md')) continue;
+        let parsed = null;
+        try { parsed = parseSkillFrontmatter(readFileSync(join(src.dir, f), 'utf8')); } catch { /* unreadable */ }
+        add(parsed?.name || f.replace(/\.md$/, ''), parsed?.description, src.source, 'command');
+      }
+    }
+  }
+  return out;
+}
+
+export const DEFAULT_WORKFLOW_COLUMNS = [
+  { key: 'todo', label: 'To do', bucket: 'todo' },
+  { key: 'doing', label: 'Doing', bucket: 'doing' },
+  { key: 'review', label: 'Review', bucket: 'review' },
+  { key: 'done', label: 'Done', bucket: 'done' },
+];
+
+function slugifyColumnKey(label, i) {
+  const s = String(label ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return s || `col${i + 1}`;
+}
+
+// Validate + normalize a project's custom workflow column list (from the
+// column editor's Save button). Every column must carry a non-empty label
+// and a bucket in WORKFLOW_BUCKETS. A bucket left with no column at all just
+// falls back to its English default label (see pickColumnLabel) — tasks/goals
+// in that bucket keep rendering under the fallback section, so dropping a
+// column (even the last one for a bucket) is safe and must stay allowed;
+// the task board itself is driven by real status, not by this column list.
+// Column keys default to a slug of the label and are de-duped, so the caller
+// doesn't have to invent one for a brand-new column.
+export function validateWorkflowColumns(input) {
+  if (!Array.isArray(input) || !input.length) return { ok: false, error: 'at least one column is required' };
+  if (input.length > 10) return { ok: false, error: 'at most 10 columns allowed' };
+  const labels = input.map((c) => String(c?.label ?? '').trim().slice(0, 40));
+  if (labels.some((l) => !l)) return { ok: false, error: 'every column needs a name' };
+  const buckets = input.map((c) => c?.bucket);
+  if (buckets.some((b) => !WORKFLOW_BUCKETS.includes(b))) {
+    return { ok: false, error: `bucket must be one of: ${WORKFLOW_BUCKETS.join(', ')}` };
+  }
+  const seen = new Set();
+  const columns = input.map((c, i) => {
+    let key = String(c?.key ?? '').trim().slice(0, 40) || slugifyColumnKey(labels[i], i);
+    while (seen.has(key)) key = `${key}-${i}`;
+    seen.add(key);
+    return { key, label: labels[i], bucket: c.bucket };
+  });
+  return { ok: true, columns };
+}
+
+// First column whose bucket matches (a project may rename "Review" to
+// "審査" etc.) — used to render the Tasks-panel section headers with the
+// project's own column names instead of hardcoded English labels. Falls
+// back to `fallback` when no column claims that bucket (shouldn't happen
+// for a validateWorkflowColumns-saved list, but keeps rendering safe).
+// Mirrored manually in app/index.html since that inline script can't import
+// this module — keep both in sync.
+export function pickColumnLabel(columns, bucket, fallback) {
+  return (columns ?? []).find((c) => c.bucket === bucket)?.label || fallback;
+}
+
+// Merge a project's goals with git commits made outside the Manager (e.g.
+// via the Claude Code CLI directly) into one chronological (oldest-first)
+// timeline for the UI's stream. Both inputs are filtered to `projectId`
+// first, then tagged with `kind` so the renderer knows which template to use.
+// Mirrored manually in app/index.html's renderStream() — browser script
+// isn't a module and can't import server-side code.
+export function mergeGoalTimeline(goals, externalActivity, projectId) {
+  const goalItems = (goals ?? [])
+    .filter((g) => g.projectId === projectId && g.status !== 'stacked')
+    .map((g) => ({ kind: 'goal', ts: Date.parse(g.createdAt) || 0, data: g }));
+  const commitItems = (externalActivity ?? [])
+    .filter((c) => c.projectId === projectId)
+    .map((c) => ({ kind: 'commit', ts: Date.parse(c.date) || 0, data: c }));
+  return [...goalItems, ...commitItems].sort((a, b) => a.ts - b.ts);
+}
+
+// To do list display cap (task 88): first `limit` rows unless expanded.
+export function visibleTodos(list, showAll, limit = 10) {
+  return showAll ? list : list.slice(0, limit);
+}
+
+// Goal-level conclusion summary (task 84): composed deterministically from
+// worker reports — no LLM call, no raw-result concatenation. Always 3-6
+// Japanese lines covering ①何をやったか ②変更点 ③確認方法, even when tasks
+// are mixed done/failed/interrupted or there is only a single task.
+export function buildGoalSummary({ goalText, tasks } = {}) {
+  const work = (tasks ?? []).filter((t) => !t.reply);
+  const done = work.filter((t) => ['done', 'skipped'].includes(t.status));
+  const failed = work.filter((t) => ['failed', 'interrupted'].includes(t.status));
+  const files = [...new Set(work.flatMap((t) => t.changedFiles ?? []))];
+  const proofs = work.filter((t) => t.proof?.pass).length;
+
+  const title = (goalText ?? '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  const lines = [];
+  lines.push(`${title || 'ゴール'}: ${done.length}/${work.length}件完了${failed.length ? `（${failed.length}件は未完了・要対応）` : ''}`);
+
+  const highlights = done.slice(0, 3).map((t) => {
+    const first = (t.result ?? t.detail ?? '')
+      .replace(/^検証(PASS|FAIL)[^\n]*\n+/, '')
+      .split('\n')[0]
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 70);
+    return first ? `${t.title}: ${first}` : t.title;
+  });
+  if (highlights.length) lines.push(`何をやったか: ${highlights.join(' / ')}`);
+
+  if (failed.length) {
+    const names = failed.slice(0, 3).map((t) => t.title).join(' / ');
+    lines.push(`未完了: ${names}${failed.length > 3 ? ` 他${failed.length - 3}件` : ''}`);
+  }
+
+  lines.push(files.length
+    ? `変更点: ${files.slice(0, 8).join(' · ')}${files.length > 8 ? ` +${files.length - 8}件` : ''}`
+    : '変更点: コード変更なし');
+
+  lines.push(proofs
+    ? `確認方法: proof付きで${proofs}件検証済み。レビュー欄で詳細を確認してください。`
+    : '確認方法: 各タスクの実行結果を個別に確認してください。');
+
+  return lines.join('\n');
+}
+
+// Plain-text snapshot of Review/Attention/Done fed to the /api/ask LLM pass —
+// same three buckets app/index.html's renderTasks() renders (goal.status
+// 'review'/'blocked' + task.status failed/interrupted + task.status
+// done/skipped), flattened into text since there's no UI to look at here.
+export function buildAskContext(goals = [], tasks = []) {
+  const label = (g) => (g.reviewSummary?.check || g.plan?.[0] || g.text || '').replace(/\s+/g, ' ').trim().slice(0, 100);
+
+  const reviewGoals = goals.filter((g) => g.status === 'review');
+  const reviewLines = reviewGoals.map((g) => {
+    const tr = g.testResult;
+    const tests = tr?.ran ? `tests ${tr.passed}✓${tr.failed ? `/${tr.failed}✗` : ''}` : 'no tests';
+    return `- [goal ${g.id}] ${label(g)} (${tests}${g.pr ? `, PR: ${g.pr}` : ''})`;
+  });
+
+  const blockedGoals = goals.filter((g) => g.status === 'blocked');
+  const attnTasks = tasks.filter((t) => ['failed', 'interrupted'].includes(t.status));
+  const attentionLines = [
+    ...blockedGoals.map((g) => `- [goal ${g.id}] ${label(g)} — blocked: ${(g.blocked?.reason ?? 'blocked').replace(/\s+/g, ' ').slice(0, 100)}`),
+    ...attnTasks.map((t) => `- [task ${t.id}] ${(t.title ?? t.text ?? '').replace(/\s+/g, ' ').slice(0, 80)} — ${t.status}: ${(t.result ?? '').replace(/\s+/g, ' ').slice(0, 100)}`),
+  ];
+
+  const doneTasks = tasks.filter((t) => ['done', 'skipped'].includes(t.status)).slice(-30);
+  const doneLines = doneTasks.map((t) => `- [task ${t.id}] ${(t.title ?? t.text ?? '').replace(/\s+/g, ' ').slice(0, 80)}`);
+
+  const section = (title, lines) => [`## ${title}`, lines.length ? lines.join('\n') : '(なし)'].join('\n');
+  return [
+    section('Review（レビュー待ち）', reviewLines),
+    section('Attention（要対応）', attentionLines),
+    section('Done（完了）', doneLines),
+  ].join('\n\n');
+}
+
+// Goal statuses that count as "finished" for showing the goal-level
+// conclusion summary in chat (task 86) — mirrored in app/index.html's
+// goalRow (GOAL_COMPLETE_STATUSES) since that inline script can't import
+// this module. A goal still 'planning'/'running'/'sending' has no settled
+// outcome yet even if a stale summary happens to linger on the object, and
+// 'failed'/'stacked' goals never got a summary built for them.
+export const GOAL_COMPLETE_STATUSES = ['review', 'done', 'partial'];
+export function shouldShowGoalSummary(goal) {
+  return !!goal?.summary && GOAL_COMPLETE_STATUSES.includes(goal?.status);
+}
+
+// Review checklist recap (task 96): a short, deterministic summary of what a
+// goal set out to do and how far its requirements got — shown at the top of
+// the review checklist AND in the chat thread's review导线, so a reviewer sees
+// 「何をやったか・何を確認すればいいのか」without reading every worker report.
+// Mirrored in app/index.html (buildReviewSummary) since the inline browser
+// script can't import this module. No LLM — composed from goal.plan / task
+// titles / task状態.
+export function buildReviewSummary({ goal, tasks, approvedN = 0 } = {}) {
+  const reqs = (tasks ?? []).filter((t) => !t.reply);
+  const total = reqs.length;
+  const done = reqs.filter((t) => ['done', 'skipped'].includes(t.status)).length;
+  const proofs = reqs.filter((t) => t.proof?.pass).length;
+  const plan = Array.isArray(goal?.plan) ? goal.plan.filter(Boolean) : [];
+  const source = plan.length ? plan : reqs.map((t) => t.title);
+  const what = source
+    .map((s) => String(s ?? '').replace(/\s+/g, ' ').trim())
+    .filter(Boolean)
+    .slice(0, 3)
+    .join(' / ');
+  const fallback = String(goal?.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 80);
+  return {
+    approvedN,
+    total,
+    headline: `${approvedN} / ${total} approved`,
+    what: what || fallback,
+    detail: `${done}/${total} done${proofs ? ` · proof ×${proofs}` : ''}`,
+    failureMemory: goal?.failureMemory?.length ? goal.failureMemory[goal.failureMemory.length - 1] : null,
+    tokenOptimization: estimateTokenOptimization({
+      usage: goal?.runUsage,
+      weightedTokens: goal?.runTokens,
+      cacheReadWeight: goal?.runTokenWeight,
+      sessionMode: goal?.executionPlan?.sessionMode,
+      usedHandoff: goal?.executionPlan?.sessionMode === 'cold-handoff' || Boolean(goal?.contextHandoff),
+      usedCompact: goal?.executionPlan?.sessionMode === 'compact',
+      usedClear: Boolean(goal?.sessionClosedAt),
+      agentModel: goal?.model,
+    }),
+  };
+}
+
+// Task 114: the persistent bottom-right Log box (formerly the running-task-only
+// #actpanel) defaults to collapsed (1 line) and expands on click. Plain boolean
+// flip, but pulled out as a pure function so the click handler has a unit test
+// instead of only being exercisable by clicking around in a browser.
+// Mirrored in app/index.html since that inline script can't import this module.
+export function toggleLogCollapsed(collapsed) {
+  return !collapsed;
+}
+
+// Task 120: dragging the handle between #tasklist (To Do) and #actpanel (Log)
+// sets the To Do list's explicit height directly off the mouse position; Log
+// always gets whatever height is left over. Clamped so neither side collapses
+// past readability — To Do keeps at least minTasks px, Log keeps at least
+// minLog px (its header row). Mirrored in app/index.html since that inline
+// script can't import this module.
+export function clampTasklistHeight(px, containerHeight, minTasks = 120, minLog = 44) {
+  const max = Math.max(minTasks, containerHeight - minLog);
+  return Math.min(max, Math.max(minTasks, px));
+}
+
+// Task 115: turn an incoming SSE 'goal' message into one Log-box line,
+// based on what changed since the previously-known copy of that goal
+// (`prevGoal` is undefined the first time the client ever sees this goal id).
+// Only the milestones the Log box cares about are covered here — decomposed
+// into To-do tasks, shelved to Pending, and the goal-level Approve/Dismiss —
+// everything else (still 'planning', 'stacked' behind another goal, etc.)
+// returns null so it's simply not logged. Mirrored in app/index.html since
+// that inline script can't import this module.
+export function goalLogLine(goal, prevGoal) {
+  const label = String(goal?.plan?.[0] ?? goal?.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  if (!prevGoal) return goal?.status === 'pending' ? `Goal shelved to Pending: "${label}"` : null;
+  if (prevGoal.status === 'review' && goal.status === 'done') return `Approved: "${label}"`;
+  if (prevGoal.status === 'review' && goal.status === 'running') return `Dismissed: "${label}" — back to work`;
+  if (prevGoal.status !== 'running' && goal.status === 'running' && Array.isArray(goal.plan) && goal.plan.length) {
+    return `Goal decomposed into ${goal.plan.length} task(s) → To do: "${label}"`;
+  }
+  return null;
+}
+
+// Task 115: same idea as goalLogLine but for SSE 'task' messages — a task's
+// own start/complete/fail, plus a reply task's very first appearance (a
+// reply task is created already 'queued', with no earlier "queued" event of
+// its own to diff against, so that's the one case logged on first sight
+// instead of on a status change). Mirrored in app/index.html.
+export function taskLogLine(task, prevTask) {
+  const title = String(task?.title ?? '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  const label = task?.reply ? `Reply "${title}"` : `Task ${task?.num} "${title}"`;
+  if (!prevTask) return task?.reply ? `${label} queued — processed as thread reply` : null;
+  if (prevTask.status !== 'running' && task.status === 'running') return `${label} started`;
+  if (!['done', 'skipped'].includes(prevTask.status) && ['done', 'skipped'].includes(task.status)) return `${label} completed`;
+  if (!['failed', 'interrupted'].includes(prevTask.status) && ['failed', 'interrupted'].includes(task.status)) return `${label} failed`;
+  return null;
+}
+
+// Ring buffer for the Log box (task 115): append one entry, keeping only the
+// most recent `limit` (default 50) — the oldest is dropped first once full.
+// Generic (not Log-box-specific) so any capped-history list can reuse it.
+export function pushCapped(list, item, limit = 50) {
+  return [...(list ?? []), item].slice(-limit);
+}
+
+// Task 116: the header's Working·n/Idle pill (#workstat) is retired in favor
+// of the same status living in the persistent Log box's own header. `runningAll`
+// is the count of tasks with status 'running' across every project (same
+// count the old pill used — not filtered to the active project). Mirrored in
+// app/index.html since that inline script can't import this module.
+export function workStatusLabel(runningAll) {
+  return runningAll > 0 ? `Working · ${runningAll}` : 'Idle';
+}
+
+// One-line recap of a single requirement (task 96): the worker's own first
+// line (detail preferred over its raw result), stripped of the 検証PASS/FAIL
+// prefix, for the per-requirement summary in both review surfaces.
+export function requirementSummaryLine(task) {
+  return String(task?.detail ?? task?.result ?? '')
+    .replace(/^検証(PASS|FAIL)[^\n]*\n+/, '')
+    .split('\n')[0]
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120);
+}
+
+// ============================================================================
+// See all Ledger — engine logic (HANDOFF-v45 §5 / PRD §5.1)
+// ============================================================================
+
+// Plain Dismiss from the Ledger = a "できていない" declaration WITHOUT feedback
+// text. Instead of spawning a rework worker immediately (the dismiss-with-text
+// path), the engine re-runs the goal's deterministic verification ×3 first —
+// this is the decision that a retest may start.
+export function retestGoal({ goalStatus }) {
+  if (goalStatus !== 'review') return { ok: false, error: 'goal is not in review' };
+  return { ok: true, status: 'retesting' };
+}
+
+// UNDO of a Ledger Dismiss: only an in-flight retest can be cancelled — once
+// the job settled, the goal is already back in 'review' or reworking.
+export function cancelRetestGoal({ goalStatus }) {
+  if (goalStatus !== 'retesting') return { ok: false, error: 'goal is not re-testing' };
+  return { ok: true, status: 'review' };
+}
+
+// Decide the retest outcome from the job's deterministic runs (npm test in
+// the goal's worktree — NO LLM). `total` is how many green runs are required.
+// - every run ran and stayed green, `total` times → back to 'review' with the
+//   "retested ×3 — no issues found" note (PRD §5.1: 人に知らせて再提出)
+// - any run reproduces a failure → back to To Do as reworking ('running'),
+//   with the failure evidence for the worker respawn
+// - the project has no test suite at all → back to 'review', honestly noting
+//   the retest was skipped (never fabricate a green ×3)
+export function computeRetestOutcome(results = [], total = 3) {
+  if (!results.length || results.some((r) => !r?.ran)) {
+    return { verdict: 'skipped', status: 'review', note: 'retest skipped — no test suite' };
+  }
+  const failIdx = results.findIndex((r) => (r.failed ?? 0) > 0);
+  if (failIdx >= 0) {
+    const r = results[failIdx];
+    return {
+      verdict: 'fail', status: 'running',
+      note: `retest ${failIdx + 1}/${total} — ${r.failed} test(s) failing`,
+      evidence: `自動再テスト ${failIdx + 1}/${total} 回目で ${r.failed} 件のテスト失敗が再現（pass ${r.passed ?? 0} / fail ${r.failed}）`,
+    };
+  }
+  if (results.length < total) {
+    // interrupted before reaching ×total with no failure seen — do not claim ×3
+    return { verdict: 'skipped', status: 'review', note: `retest incomplete (${results.length}/${total} runs)` };
+  }
+  return { verdict: 'pass', status: 'review', note: `retested ×${total} — no issues found` };
+}
+
+// Revert (ゴミ箱) = "make the change never have happened": close the PR,
+// delete its remote branch, drop the goal's worktree, and park the goal in a
+// terminal 'reverted' status (distinct from 'skipped'/archived). Decision only —
+// the destructive gh/git calls live behind the server's small wrapper.
+export function revertGoal({ goalStatus }) {
+  if (!['review', 'done', 'blocked', 'partial'].includes(goalStatus)) {
+    return { ok: false, error: 'only a finished (review/done/blocked/partial) goal can be reverted' };
+  }
+  return { ok: true, status: 'reverted' };
+}
+
+// Which destructive steps a revert needs, from the goal's shape. Pure and
+// ordered: PR first (gh pr close --delete-branch removes the remote branch
+// with it), a pushed branch without a PR is deleted directly, and the local
+// worktree is removed last. No PR, no branch, no worktree → nothing but the
+// status flip.
+export function planRevertActions({ pr, prBranch, hasWorktree } = {}) {
+  const actions = [];
+  if (pr) actions.push({ kind: 'close-pr', url: pr, deleteBranch: !!prBranch });
+  else if (prBranch) actions.push({ kind: 'delete-remote-branch', branch: prBranch });
+  if (hasWorktree) actions.push({ kind: 'remove-worktree' });
+  return actions;
+}
+
+// Archive from the Ledger = 判断保留の棚上げ (PRD §5.1): review goals join the
+// statuses the /archive endpoint accepts. archivedFrom is remembered so the
+// one-liner's UNDO can put the goal back exactly where it was.
+export const ARCHIVABLE_GOAL_STATUSES = ['partial', 'failed', 'interrupted', 'blocked', 'review'];
+export function archiveGoal({ goalStatus }) {
+  if (!ARCHIVABLE_GOAL_STATUSES.includes(goalStatus)) {
+    return { ok: false, error: 'only an unfinished (partial/failed/interrupted/blocked) or review goal can be archived' };
+  }
+  return { ok: true, status: 'skipped', archivedFrom: goalStatus };
+}
+
+// UNDO of a Ledger Archive. Restricted to goals archived FROM review — an
+// unfinished goal's archive also retired its child tasks, which this does not
+// resurrect, so pretending to undo those would be dishonest.
+export function unarchiveGoal({ goalStatus, archivedFrom }) {
+  if (goalStatus !== 'skipped' || archivedFrom !== 'review') {
+    return { ok: false, error: 'only a goal archived from review can be unarchived' };
+  }
+  return { ok: true, status: 'review' };
+}
+
+// UNDO of a Ledger chat send-back (dismiss-with-text): only honest while the
+// rework reply task is still QUEUED — once a worker picked it up, the session
+// has already consumed the feedback and there is nothing true to undo.
+export function undismissGoal({ goalStatus, replyTask }) {
+  if (goalStatus !== 'running') return { ok: false, error: 'goal is not reworking' };
+  if (!replyTask || replyTask.status !== 'queued') {
+    return { ok: false, error: 'the rework already started — cannot undo' };
+  }
+  return { ok: true, status: 'review' };
+}
+
+// `git diff --numstat` → per-file adds/dels + totals for the Ledger meta row
+// (`+a −d`) and Details file list. Binary files report "-" — counted as 0.
+export function parseNumstat(raw) {
+  const files = [];
+  for (const line of String(raw ?? '').split('\n')) {
+    const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+    if (!m) continue;
+    files.push({ path: m[3], add: m[1] === '-' ? 0 : Number(m[1]), del: m[2] === '-' ? 0 : Number(m[2]) });
+  }
+  return {
+    files,
+    add: files.reduce((s, f) => s + f.add, 0),
+    del: files.reduce((s, f) => s + f.del, 0),
+  };
+}
+
+// Cap the diff text shipped to the Ledger Details block — a runaway diff
+// must not swamp /api/state-sized responses. Truncation is explicit so the
+// UI can say "… truncated" instead of silently lying about the change size.
+export function truncateDiffText(raw, maxLines = 400) {
+  const text = String(raw ?? '');
+  const lines = text.split('\n');
+  if (lines.length <= maxLines) return { text, truncated: false, totalLines: lines.length };
+  return { text: lines.slice(0, maxLines).join('\n'), truncated: true, totalLines: lines.length };
+}
+
+// ---- Cloudflare Access (Google login) JWT verification --------------------
+// Stage 1 of "common URL → Google login": when the app sits behind Cloudflare
+// Access on its hostname, CF injects a signed RS256 JWT
+// (`Cf-Access-Jwt-Assertion` header) on every request *after* the visitor
+// logs in with Google. That header is attacker-controlled input on any box
+// that isn't actually behind CF Access, so it must be cryptographically
+// verified — signature, expiry, audience — never trusted at face value. All
+// I/O (fetching the JWKS, reading env vars) stays in server.mjs; these are
+// pure functions so the crypto logic itself is unit-testable without a
+// network call or a real Cloudflare team.
+
+function base64urlToBuffer(s) {
+  return Buffer.from(String(s ?? ''), 'base64url');
+}
+
+// Split a compact JWT into its decoded header/payload plus the raw pieces
+// needed to re-verify the signature. Returns null for anything malformed
+// (wrong shape, bad base64url, non-JSON parts) instead of throwing.
+export function decodeJwtParts(token) {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3 || parts.some((p) => !p)) return null;
+  try {
+    const header = JSON.parse(base64urlToBuffer(parts[0]).toString('utf8'));
+    const payload = JSON.parse(base64urlToBuffer(parts[1]).toString('utf8'));
+    if (!header || typeof header !== 'object' || !payload || typeof payload !== 'object') return null;
+    return { header, payload, signingInput: `${parts[0]}.${parts[1]}`, signature: parts[2] };
+  } catch {
+    return null;
+  }
+}
+
+// `exp` is required — a JWT with no expiry is treated as already-expired
+// rather than eternally valid.
+export function jwtIsExpired(payload, nowSec = Math.floor(Date.now() / 1000)) {
+  if (!payload || typeof payload.exp !== 'number') return true;
+  return payload.exp <= nowSec;
+}
+
+export function jwtAudMatches(payload, aud) {
+  if (!payload || !aud) return false;
+  const auds = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+  return auds.includes(aud);
+}
+
+export function pickJwk(jwks, kid) {
+  const keys = jwks?.keys ?? [];
+  if (!kid) return null;
+  return keys.find((k) => k?.kid === kid) ?? null;
+}
+
+// Full verification of a Cloudflare Access identity JWT: decode → find the
+// matching JWK by `kid` → verify the RS256 signature → check `exp` → check
+// `aud`. Returns `{ok:false}` on the first failure (never partially trusts a
+// token) and `{ok:true, email}` only once every check has passed.
+export function verifyCfAccessJwt({ token, jwks, aud, now = Math.floor(Date.now() / 1000) }) {
+  const decoded = decodeJwtParts(token);
+  if (!decoded) return { ok: false, email: null, reason: 'malformed' };
+  const { header, payload, signingInput, signature } = decoded;
+  const jwk = pickJwk(jwks, header.kid);
+  if (!jwk) return { ok: false, email: null, reason: 'unknown-kid' };
+  let signatureValid = false;
+  try {
+    const keyObject = createPublicKey({ key: jwk, format: 'jwk' });
+    signatureValid = verifyRsaSignature('RSA-SHA256', Buffer.from(signingInput), keyObject, base64urlToBuffer(signature));
+  } catch {
+    signatureValid = false;
+  }
+  if (!signatureValid) return { ok: false, email: null, reason: 'bad-signature' };
+  if (jwtIsExpired(payload, now)) return { ok: false, email: null, reason: 'expired' };
+  if (!jwtAudMatches(payload, aud)) return { ok: false, email: null, reason: 'aud-mismatch' };
+  if (!payload.email) return { ok: false, email: null, reason: 'no-email' };
+  return { ok: true, email: payload.email };
+}
+
+// ---- multi-user goal ownership (stage 2: "common URL → branch by user") --
+// Stage 1 (verifyCfAccessJwt above) gets us a per-request verified Google
+// identity (req.authEmail). Stage 2 partitions GOALS by that identity so
+// each allow-listed Google user sees only their own goals, while the OWNER
+// (Masa / key-auth) keeps seeing every goal, including the ones that predate
+// this feature and carry no `owner` field at all. Projects/skills/columns
+// stay shared for everyone — only goal (and by extension task) visibility
+// is partitioned.
+
+// Resolve the *acting identity* for a request: 'owner' for key-auth (no
+// authEmail — the only path that existed before stage 1) and for
+// MANAGER_OWNER_EMAIL itself (so Masa logging in via Google still sees his
+// own pre-existing data), else the authed email verbatim. This is what gets
+// stamped onto a goal's `owner` field at creation time.
+export function resolveIdentity({ authEmail, ownerEmail } = {}) {
+  if (!authEmail) return 'owner'; // key-auth
+  if (ownerEmail && authEmail === ownerEmail) return 'owner';
+  return authEmail;
+}
+
+// Can `identity` see (act on) this goal? `identity` may already be resolved
+// via resolveIdentity ('owner' or an email) or be a raw authEmail — either
+// way, an identity equal to ownerEmail is treated as the owner. The owner
+// sees everything. A normal user sees only goals whose `owner` matches their
+// own identity. Backward compat is load-bearing here: a goal with no `owner`
+// field (every goal created before this feature) defaults to 'owner' —
+// visible to the owner, invisible to any other user — so nothing existing is
+// ever lost or hidden from Masa, and nothing existing ever leaks to a
+// different logged-in user.
+export function goalVisibleTo(goal, identity, ownerEmail) {
+  const who = ownerEmail && identity === ownerEmail ? 'owner' : identity;
+  if (who === 'owner') return true;
+  return (goal?.owner ?? 'owner') === who;
+}
+
+
+// A `high` category means "never auto-approve"; `low` is surfaced but does not
+// force a pause. Matching is deliberately broad — over-flagging a sensitive
+// area (an extra human glance) is the safe failure mode here.
+export const CHANGE_RISK_RULES = [
+  {
+    id: 'secrets', label: 'Secrets / credentials', level: 'high',
+    filePattern: /(^|\/)\.env(\.|$)|secret|credential|\.pem$|\.key$|id_rsa|api[_-]?key|\.pfx$|\.keystore$/i,
+    // Added line that assigns a long literal to a secret-shaped name.
+    diffPattern: /(?:^|\n)\+.*(?:api[_-]?key|secret|password|token|access[_-]?key)\s*[:=]\s*['"][^'"\s]{8,}/i,
+    reason: 'Touches credentials or hardcodes a secret — never auto-approve.',
+  },
+  {
+    id: 'auth', label: 'Auth / access control', level: 'high',
+    filePattern: /(^|\/)(auth|login|logout|session|oauth|jwt|permission|rbac|acl|middleware)(\/|\.|$)|password|passport/i,
+    reason: 'Changes authentication or access control.',
+  },
+  {
+    id: 'payment', label: 'Payment / billing', level: 'high',
+    filePattern: /payment|billing|stripe|checkout|charge|invoice|subscription|paypal|braintree/i,
+    reason: 'Changes payment or billing logic.',
+  },
+  {
+    id: 'db-migration', label: 'Database migration / schema', level: 'high',
+    filePattern: /(^|\/)migrations?(\/|$)|migrat|schema\.(sql|prisma|rb)$|\.sql$|alembic|knexfile|prisma\/schema/i,
+    diffPattern: /\b(DROP\s+(TABLE|DATABASE|COLUMN)|TRUNCATE\s+TABLE|ALTER\s+TABLE\s+\w+\s+DROP|DELETE\s+FROM)\b/i,
+    reason: 'Alters DB schema or migrations — can be irreversible.',
+  },
+  {
+    id: 'destructive', label: 'Destructive command', level: 'high',
+    filePattern: null,
+    // Only an ADDED destructive line counts (removing one is safe).
+    diffPattern: /(?:^|\n)\+.*(rm\s+-rf|git\s+push\s+[^\n]*--force|--force\b|DROP\s+DATABASE|mkfs|dd\s+if=|>\s*\/dev\/sd)/i,
+    reason: 'Adds a destructive or force command.',
+  },
+  {
+    id: 'ci-deploy', label: 'CI / deploy config', level: 'low',
+    filePattern: /(^|\/)\.github\/workflows\/|Dockerfile|docker-compose|vercel\.json|wrangler\.(toml|jsonc?)|(^|\/)\.circleci\/|Procfile|fly\.toml|netlify\.toml|(^|\/)deploy/i,
+    reason: 'Changes CI/CD or deployment config.',
+  },
+];
+
+// → { level:'none'|'low'|'high', shouldPause, categories:[{id,label,level,reason,files,viaDiff}], sensitiveFiles }
+export function classifyChangeRisk(changedFiles, diffText = '', { rules = CHANGE_RISK_RULES } = {}) {
+  const files = (Array.isArray(changedFiles) ? changedFiles : [changedFiles])
+    .filter((f) => typeof f === 'string' && f.trim())
+    .map((f) => f.trim());
+  const diff = typeof diffText === 'string' ? diffText : '';
+  const categories = [];
+  for (const rule of rules) {
+    const matchedFiles = rule.filePattern ? files.filter((f) => rule.filePattern.test(f)) : [];
+    const viaDiff = !!(rule.diffPattern && diff && rule.diffPattern.test(diff));
+    if (matchedFiles.length === 0 && !viaDiff) continue;
+    categories.push({ id: rule.id, label: rule.label, level: rule.level, reason: rule.reason, files: matchedFiles, viaDiff });
+  }
+  const hasHigh = categories.some((c) => c.level === 'high');
+  const level = hasHigh ? 'high' : categories.length ? 'low' : 'none';
+  const sensitiveFiles = [...new Set(categories.flatMap((c) => c.files))];
+  return { level, shouldPause: hasHigh, categories, sensitiveFiles };
+}
+
+// ---------------------------------------------------------------------------
+// goal 427: token/quota-frugal guardrails (PRD §4/§6 — "wake up to evidence,
+// not a burned weekly quota"). Three pure decision helpers; the stateful
+// wiring (accumulating elapsed/tokens/attempts per goal, detecting the
+// worker's actual stdout/stderr, pacing the queue) lives in server.mjs.
+// ---------------------------------------------------------------------------
+
+// Sum the four token-count fields of a runClaude() usage object (the same
+// shape sumUsage() produces) into one raw number. cost_usd/duration_ms are not
+// "tokens" and excluded.
+export function usageTotalTokens(usage) {
+  if (!usage) return 0;
+  const u = usage;
+  return (u.input_tokens ?? 0) + (u.output_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+}
+
+// Budget pressure is deliberately cache-aware: cache reads can be enormous
+// when a long Claude Code session is resumed, but they are not the same signal
+// as fresh input/output or cache creation. Count cache reads with a small
+// configurable weight so the guardrail catches real runaway work without
+// blocking every large-session continuation as if it spent that whole context
+// from scratch.
+export function usageBudgetTokens(usage, { cacheReadWeight = 0.1 } = {}) {
+  if (!usage) return 0;
+  const u = usage;
+  const weight = Number.isFinite(Number(cacheReadWeight)) ? Math.max(0, Number(cacheReadWeight)) : 0.1;
+  return Math.round(
+    (u.input_tokens ?? 0)
+    + (u.output_tokens ?? 0)
+    + (u.cache_creation_input_tokens ?? 0)
+    + ((u.cache_read_input_tokens ?? 0) * weight),
+  );
+}
+
+// Per-goal run budget (task 427 §1): once ANY of runtime / tokens / attempts
+// exceeds its limit, the goal must stop cleanly rather than keep retrying —
+// that's the actual quota burn. `limits` values of null/undefined disable
+// that particular check (so a caller can budget only what it wants to).
+// Checked in a fixed order (runtime, then tokens, then attempts) so a single
+// call always reports exactly one `which` even if several are already over.
+export function checkRunBudget({ elapsedMs = 0, tokens = 0, attempts = 0 } = {}, limits = {}) {
+  const { maxRuntimeMs, maxTokens, maxAttempts } = limits;
+  if (maxRuntimeMs != null && elapsedMs > maxRuntimeMs) {
+    return { exceeded: true, which: 'runtime', reason: `run budget exceeded: runtime (${Math.round(elapsedMs / 60000)}min > ${Math.round(maxRuntimeMs / 60000)}min limit)` };
+  }
+  if (maxTokens != null && tokens > maxTokens) {
+    return { exceeded: true, which: 'tokens', reason: `run budget exceeded: tokens (${tokens.toLocaleString('en-US')} > ${maxTokens.toLocaleString('en-US')} limit)` };
+  }
+  if (maxAttempts != null && attempts > maxAttempts) {
+    return { exceeded: true, which: 'attempts', reason: `run budget exceeded: attempts (${attempts} > ${maxAttempts} limit)` };
+  }
+  return { exceeded: false, which: null, reason: null };
+}
+
+// Rate-limit-aware pause/resume (task 427 §2): detect the `claude` worker
+// telling us it hit Claude's own usage/rate limit, from whatever text ended
+// up in the runClaude() result (the stream-json "result" event's text, or —
+// on a hard non-zero exit with no result — the captured stderr tail that
+// runClaude() already falls back to). Deliberately broad / best-effort: the
+// CLI's exact wording isn't a committed API and may drift, so this errs
+// toward over-matching (treating an ambiguous message as a rate limit and
+// pausing costs a little latency; missing one and hammering the limit costs
+// quota — the asymmetric-safe choice is over-matching).
+const RATE_LIMIT_RE = /(rate[\s-]?limit|usage limit|quota\s*(exceeded|reached)|resets?\s+(at|in)\b|try again (in|later)|5[\s-]hour limit|weekly limit|claude ai usage limit)/i;
+export function isRateLimited(resultText) {
+  return RATE_LIMIT_RE.test(String(resultText ?? ''));
+}
+
+// Backoff before an automatic resume, keyed by how many times THIS goal has
+// already been rate-limited (not the task's normal verify-retry `attempt` —
+// callers pass their own rate-limit-hit counter). Exponential, capped, so a
+// goal stuck against a still-active limit doesn't hot-loop retries into the
+// same wall (defeats the whole point) but also doesn't wait needlessly long
+// once the limit has plausibly cleared.
+export function nextResumeDelay(attempt, { baseMs = 5 * 60 * 1000, maxMs = 60 * 60 * 1000 } = {}) {
+  const n = Math.max(1, Number(attempt) || 1);
+  return Math.min(maxMs, baseMs * 2 ** (n - 1));
+}
+
+// ---- billing entitlement gate (public self-serve launch, docs/BILLING-LAUNCH-PLAN.md) --
+// Mirrors workers/billing-api/src/entitlement.mjs's FREE_TIER_LIMITS/
+// checkFreeTierLimit/resolveEntitlement exactly (Masa decision 2026-07-12:
+// 5 pending goals, 19 lifetime goals, 1 project, $16/mo unlocks all three).
+// Deliberately duplicated rather than imported: engine/ and workers/billing-api/
+// are independently deployed (a user's Mac vs Cloudflare) and independently
+// tested — sharing a module across that boundary would couple two things
+// that fail and deploy on different schedules. Keep the two copies in sync by
+// hand; both have their own test coverage against the same free-tier numbers.
+export const FREE_TIER_LIMITS = Object.freeze({
+  maxPendingGoals: 5,
+  maxCumulativeGoals: 19,
+  maxProjects: 1,
+});
+
+export function checkFreeTierLimit(usage) {
+  const pendingCount = Number(usage?.pendingCount) || 0;
+  const cumulativeCount = Number(usage?.cumulativeCount) || 0;
+  const projectCount = Number(usage?.projectCount) || 0;
+  if (pendingCount > FREE_TIER_LIMITS.maxPendingGoals) {
+    return { blocked: true, reason: 'pending-goal-limit', limit: FREE_TIER_LIMITS.maxPendingGoals, value: pendingCount };
+  }
+  if (cumulativeCount > FREE_TIER_LIMITS.maxCumulativeGoals) {
+    return { blocked: true, reason: 'cumulative-goal-limit', limit: FREE_TIER_LIMITS.maxCumulativeGoals, value: cumulativeCount };
+  }
+  if (projectCount > FREE_TIER_LIMITS.maxProjects) {
+    return { blocked: true, reason: 'project-limit', limit: FREE_TIER_LIMITS.maxProjects, value: projectCount };
+  }
+  return { blocked: false, reason: null, limit: null, value: null };
+}
+
+export function resolveEntitlement({ isOwner, isPaying, usage }) {
+  if (isOwner) return { allowed: true, blocked: null };
+  if (isPaying) return { allowed: true, blocked: null };
+  const limit = checkFreeTierLimit(usage);
+  return { allowed: !limit.blocked, blocked: limit.blocked ? limit : null };
+}
+
+// Design principle (BILLING-LAUNCH-PLAN.md §2): billing-api being briefly
+// unreachable must not lock out a previously-confirmed paying user. `cached`
+// is `{isPaying, checkedAt}` or null (never checked). Within `freshMs` the
+// cache is used with no network call at all (avoids a round trip on every
+// over-the-free-tier request); within `graceMs` a stale cache is still
+// trusted (covers a transient billing-api outage) but a refresh is signaled;
+// beyond `graceMs`, or with no cache at all, there is nothing safe to trust
+// so it resolves to not-paying (fail closed — never invent a "yes" for an
+// identity we have no evidence paid).
+export function resolveCachedEntitlement({ cached = null, now = Date.now(), freshMs = 10 * 60 * 1000, graceMs = 24 * 60 * 60 * 1000 } = {}) {
+  if (!cached) return { status: 'unknown', isPaying: false, needsRefresh: true };
+  const age = now - (Number(cached.checkedAt) || 0);
+  if (age <= freshMs) return { status: 'fresh', isPaying: Boolean(cached.isPaying), needsRefresh: false };
+  if (age <= graceMs) return { status: 'stale-grace', isPaying: Boolean(cached.isPaying), needsRefresh: true };
+  return { status: 'expired', isPaying: false, needsRefresh: true };
+}
+
+// ---- license token (local-first identity, docs/BILLING-LAUNCH-PLAN.md) --
+// Verifies the Ed25519-signed license token billing-api issues after a real
+// Stripe payment (workers/billing-api/src/license.mjs signs it; this is the
+// verify-only half, since the local app never signs). Offline: no network
+// call, works even if billing-api is unreachable — the token proves WHO the
+// user is (their paid email), independent of whether isPaying is still true
+// right now (that freshness check is resolveCachedEntitlement's job, backed
+// by a live GET /entitlement). Uses only Web Crypto (crypto.subtle) +
+// btoa/atob, available in both Node 20+ and the Workers runtime, so this is
+// byte-for-byte the same algorithm as the signer.
+//
+// LICENSE_PUBLIC_JWK is the public half of the keypair minted 2026-07-12
+// (workers/billing-api/scripts/gen-license-key.mjs) and deployed as billing-api's
+// LICENSE_PUBLIC_JWK var — public, safe to commit; rotate both sides together.
+export const LICENSE_PUBLIC_JWK = { key_ops: ['verify'], ext: true, alg: 'Ed25519', crv: 'Ed25519', x: 'Pfhl9xhWpyo0Lc3TgZMxF2P8P145B8zRyIAKFKFflaM', kty: 'OKP' };
+
+const licenseEnc = new TextEncoder();
+const licenseDec = new TextDecoder();
+function licenseB64urlToBytes(str) {
+  const b64 = str.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((str.length + 3) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+const licenseB64urlToString = (s) => licenseDec.decode(licenseB64urlToBytes(s));
+
+// Returns { valid, reason, payload }. `payload` ({email, isPaying, plan, iat,
+// exp}) is returned even when expired so the caller can show the stale
+// email/expiry; it is null when the token can't be decoded or the signature
+// is bad.
+export async function verifyLicenseToken({ token, publicJwk = LICENSE_PUBLIC_JWK, now = Date.now() } = {}) {
+  if (!token || typeof token !== 'string') return { valid: false, reason: 'missing token', payload: null };
+  const parts = token.split('.');
+  if (parts.length !== 3) return { valid: false, reason: 'malformed token', payload: null };
+  const [h, p, s] = parts;
+  let header, payload;
+  try { header = JSON.parse(licenseB64urlToString(h)); payload = JSON.parse(licenseB64urlToString(p)); }
+  catch { return { valid: false, reason: 'undecodable token', payload: null }; }
+  if (header?.typ !== 'AGLD-LIC') return { valid: false, reason: 'wrong token type', payload: null };
+  let ok;
+  try {
+    // Strip `alg` — some Web Crypto runtimes reject an OKP JWK with alg:"Ed25519"
+    // (they expect the JWA name "EdDSA"/none). Node is lenient; do it anyway so
+    // the same token verifies identically in every runtime. See license.mjs.
+    const { alg: _drop, ...pub } = publicJwk;
+    const key = await crypto.subtle.importKey('jwk', pub, { name: 'Ed25519' }, false, ['verify']);
+    ok = await crypto.subtle.verify({ name: 'Ed25519' }, key, licenseB64urlToBytes(s), licenseEnc.encode(`${h}.${p}`));
+  } catch { return { valid: false, reason: 'verify error', payload: null }; }
+  if (!ok) return { valid: false, reason: 'bad signature', payload: null };
+  if (typeof payload?.exp === 'number' && Math.floor(now / 1000) > payload.exp) {
+    return { valid: false, reason: 'expired', payload };
+  }
+  return { valid: true, reason: null, payload };
+}