@galda/cli 0.10.16 → 0.10.19

package/engine/lib.mjs

@@ -5,6 +5,62 @@ import { pathToFileURL } from 'node:url';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { createPublicKey, verify as verifyRsaSignature } from 'node:crypto';
 
+// Worker agents Galda can drive. Galda is NOT tied to Claude Code — it runs on
+// whichever agent CLI you have. Neither is auto-installed and codex is never even
+// executed to detect it (running the codex binary can trip macOS XProtect — a
+// false-positive that looks like Galda shipped malware); its presence is detected
+// by a plain PATH lookup (isCommandOnPath). An agent is offered iff its CLI is
+// installed, so a Codex-only machine (no claude) still gets a working board.
+export const SUPPORTED_WORKER_AGENTS = ['claude-code', 'codex'];
+
+// Canonical order, filtered to what's actually installed on this machine.
+export function resolveConnectedAgents({ claude = false, codex = false } = {}) {
+  const agents = [];
+  if (claude) agents.push('claude-code');
+  if (codex) agents.push('codex');
+  return agents;
+}
+
+// Clamp a requested agent to one that's actually available — so a stale UI
+// default (e.g. 'claude-code' on a Codex-only machine) still runs on the agent
+// the user has, instead of spawning a `claude` that isn't there.
+export function pickAvailableAgent(requested, available = []) {
+  const list = Array.isArray(available) ? available.filter(Boolean) : [];
+  if (requested && list.includes(requested)) return requested;
+  return list[0] ?? 'claude-code';
+}
+
+// Is `cmd` an executable on PATH? Detected WITHOUT running it (pure fs lookup) —
+// this is how codex is detected so Galda never executes the binary. On Windows a
+// bare `codex` resolves via PATHEXT (.cmd/.exe/…); pass pathExt + sep=';' there.
+export function isCommandOnPath(cmd, { pathEnv = '', sep = ':', pathExt = '', existsFn } = {}) {
+  if (!cmd) return false;
+  const exists = existsFn || existsSync;
+  const dirs = String(pathEnv).split(sep).filter(Boolean);
+  const exts = ['', ...String(pathExt).split(';').map((e) => e.trim()).filter(Boolean)];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      try { if (exists(join(dir, cmd + ext))) return true; } catch { /* unreadable dir — skip */ }
+    }
+  }
+  return false;
+}
+
+// Galda makes small internal LLM calls (composer-intent classification, proof-card
+// summaries, board Q&A). These prefer Claude Code + haiku (cheap + fast), but must
+// still work on a Codex-only machine — so they run on whatever agent is available,
+// NOT a hardcoded `claude` that isn't installed. Pure so the routing is testable.
+export function pickUtilityAgent(available = []) {
+  const list = Array.isArray(available) ? available.filter(Boolean) : [];
+  if (list.includes('claude-code')) return 'claude-code';
+  return list[0] ?? 'claude-code';
+}
+// The cheapest/fastest model for each agent's small utility calls. (runCodex
+// re-validates against the real Codex model list, so an unknown value is safe.)
+export function utilityModel(agent) {
+  return agent === 'codex' ? 'gpt-5.4-mini' : 'haiku';
+}
+
 // 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
@@ -206,23 +262,71 @@ export function buildContextHandoffSummary({ goal = null, tasks = [] } = {}) {
   ].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 } = {}) {
+// task 6 (2026-07-16): "saved X%" used to be a proxy for cache-hit ratio —
+// this goal's own cache-read tokens discounted 0.1x, compared against this
+// same goal's raw total. That's real math, but it has nothing to do with
+// "cheaper than usual": a goal with heavy caching always scores high even if
+// it was worse than the norm, and a goal with no caching always scores 0
+// even if it finished in a third of the tokens via a tight plan. Below,
+// `tokenBaselinePerRequirement` turns a list of past finished goals into a
+// moving average of tokens-per-requirement, so `estimateTokenOptimization`
+// can compare THIS goal against that real baseline when enough history
+// exists (`basis: 'baseline'`) — and only falls back to the old cache-ratio
+// proxy (`basis: 'cache-weight'`) when there isn't enough history yet.
+const TOKEN_BASELINE_MIN_HISTORY = 3;
+const TOKEN_BASELINE_MAX_HISTORY = 20;
+
+export function tokenBaselinePerRequirement(history = []) {
+  const samples = (history ?? [])
+    .map((h) => {
+      if (typeof h === 'number') return h;
+      const tokens = Number(h?.weightedTokens);
+      const reqN = Math.max(1, Number(h?.requirementCount) || 1);
+      return Number.isFinite(tokens) ? tokens / reqN : null;
+    })
+    .filter((n) => Number.isFinite(n) && n > 0)
+    .slice(-TOKEN_BASELINE_MAX_HISTORY);
+  if (samples.length < TOKEN_BASELINE_MIN_HISTORY) return null;
+  return samples.reduce((a, b) => a + b, 0) / samples.length;
+}
+
+export function estimateTokenOptimization({ usage = null, weightedTokens = null, cacheReadWeight = 0.1, sessionMode = null, usedHandoff = false, usedCompact = false, usedClear = false, agentModel = null, requirementCount = 1, history = [] } = {}) {
   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);
+  if (raw <= 0) return null;
   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 reqN = Math.max(1, Number(requirementCount) || 1);
+  const perReq = weighted / reqN;
+  const baseline = tokenBaselinePerRequirement(history);
+
+  let percent, basis, savedTokens;
+  if (baseline != null) {
+    percent = Math.max(-100, Math.min(100, Math.round(((baseline - perReq) / baseline) * 100)));
+    basis = 'baseline';
+    savedTokens = Math.max(0, Math.round((baseline - perReq) * reqN));
+  } else {
+    savedTokens = Math.max(0, raw - weighted);
+    percent = Math.round((savedTokens / raw) * 100);
+    basis = 'cache-weight';
+  }
+
+  // "why": always at least one concrete, data-derived sentence — never a
+  // generic "session planning" filler with nothing behind it.
   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)] };
+  const cacheRatio = Math.round(((u.cache_read_input_tokens ?? 0) / raw) * 100);
+  if (cacheRatio > 0) techniques.push(`${cacheRatio}% of tokens served from cache`);
+  if (usedHandoff || sessionMode === 'cold-handoff') techniques.push('fresh handoff instead of a bloated session');
+  if (usedCompact || sessionMode === 'compact') techniques.push('/compact before continuing');
+  if (usedClear) techniques.push('/clear between unrelated goals');
+  if (agentModel) techniques.push(`${agentModel} for this run`);
+  if (basis === 'baseline' && percent > 0) {
+    techniques.push(`${Math.round(perReq / 1000)}k tokens/requirement vs your ${Math.round(baseline / 1000)}k average`);
+  }
+  if (!techniques.length) techniques.push(`${Math.round(raw / 1000)}k tokens this run (no cache reuse yet)`);
+
+  return { rawTokens: raw, weightedTokens: weighted, savedTokens, percent, basis, techniques: [...new Set(techniques)] };
 }
 
 export function estimateFailureCauseMix({ usage = null, blockedKind = null, changedFiles = [], testResult = null, attentionHadDetail = true, taskCount = 1 } = {}) {
@@ -1170,6 +1274,72 @@ export function detectRequestLanguage(text) {
   return /[぀-ヿ㐀-鿿]/.test(text || '') ? 'ja' : 'en';
 }
 
+// SLICE 2 intent routing (docs/HANDOFF-ONBOARDING-conversational.md): the single
+// composer is conversation-first — a chat/help/settings message ("what can you
+// do?", "reply in English", a greeting) must get a conversational reply, NOT a
+// To-Do; only implementation requests become goals. These are the pure,
+// testable pieces; the server wires them into POST /api/tasks.
+//
+// A dependency-free heuristic that short-circuits only the OBVIOUS cases so most
+// sends skip the LLM classifier:
+//   'task'   — a clear implementation request (imperative verb / code token) and
+//              no chat signal → skip the LLM, go straight to goal creation.
+//   'chat'   — a clear help/settings/greeting message and no task signal.
+//   'unsure' — ambiguous (both signals, or neither) → defer to the LLM.
+// It is deliberately conservative about declaring 'task' (the only branch that
+// skips the LLM): a message carrying BOTH a task verb and a help/settings signal
+// is 'unsure', not 'task', so a help question phrased with "add"/"fix" isn't
+// silently turned into a goal.
+const INTENT_TASK_RE = /\b(fix|add|implement|create|build|refactor|remove|delete|rename|migrate|debug|integrate|revert|deploy)\b|実装|直し|直す|なおして|修正|作って|作成|追加|変更|削除|対応して|リファクタ|置き換え|バグ|不具合/i;
+const INTENT_CODE_RE = /\.(?:js|mjs|cjs|ts|tsx|jsx|css|scss|html|py|go|rs|java|rb|php|json|md|yml|yaml|sh|sql)\b|`[^`]+`|\b(?:function|const|class|import)\b|#\d+/;
+const INTENT_CHAT_META_RE = /何ができ|なにができ|何が出来|使い方|どう使|どうやって使|使える\?|説明して|教えて(?:ください|くれ|ほしい)?\s*[?？]?$|about this (?:tool|app)|what (?:can|do|are|is|does) (?:you|it|this|i)|what'?s this|what can this|how (?:do|does|can) (?:i|this|you|it)|how to use|who are you|^\s*help\s*[?？]?$|そもそも|初めて/i;
+const INTENT_CHAT_SETTINGS_RE = /英語で|日本語で|(?:reply|respond|answer|talk|speak|write)\s+(?:back\s+)?in\s+\w|語で(?:返|答|話|書)|言語/i;
+const INTENT_GREETING_RE = /^\s*(?:hi|hey|hello|yo|sup|thanks|thank you|thx|good (?:morning|evening|afternoon))\b[\s.!?]*$|^\s*(?:こんにち(?:は|わ)|こんばん(?:は|わ)|おはよう|はじめまして|やあ|ありがと(?:う)?|よろしく)[\s。!?！？]*$/i;
+
+export function classifyComposerIntentHeuristic(text) {
+  const t = (text || '').trim();
+  if (!t) return 'chat';
+  const hasTask = INTENT_TASK_RE.test(t) || INTENT_CODE_RE.test(t);
+  const hasChat = INTENT_CHAT_META_RE.test(t) || INTENT_CHAT_SETTINGS_RE.test(t) || INTENT_GREETING_RE.test(t);
+  if (hasTask && !hasChat) return 'task';   // pure implementation request → skip LLM
+  if (hasChat && !hasTask) return 'chat';   // pure help/settings/greeting
+  return 'unsure';                          // both or neither → let the LLM decide
+}
+
+// The one prompt that BOTH classifies and (for chat) writes the reply in the
+// requester's language — one Haiku round-trip, not two. The model returns a
+// single line of JSON: {"intent":"chat|task","reply":"…"}.
+export function buildIntentPrompt(text, lang) {
+  const language = lang === 'ja' ? '日本語' : 'English';
+  return [
+    'You are the intent router for Agent Manager: a tool where a user delegates a coding task in plain language, an AI implements it, and it comes back as a reviewed pull request with proof.',
+    'Classify the user message below into exactly one intent:',
+    '- "task": a request to implement, change, fix, build, or remove something in code (even if vague, e.g. "add dark mode").',
+    '- "chat": anything that is NOT an implementation request — questions about what this tool can do or how to use it, greetings, thanks, small talk, or a settings/preference request (e.g. "reply in English").',
+    'When in doubt between the two, prefer "task".',
+    `If intent is "chat", also write "reply": a short, warm, helpful answer in ${language} (at most 4 sentences). If the user asks what this can do or how to start, briefly explain: describe the change you want in plain language, and it will ask which folder/repo to work in, implement it, and return a PR with proof. If intent is "task", set "reply" to "".`,
+    'Output ONLY one line of raw JSON with keys "intent" and "reply". No markdown, no code fence, no extra text.',
+    '',
+    'User message:',
+    String(text || '').slice(0, 4000),
+  ].join('\n');
+}
+
+// Tolerant parser for the router's reply — never throws. Extracts the first JSON
+// object; on any failure it fails safe to 'task' (so a garbled classification
+// can never silently swallow a real implementation request). Reply is clamped.
+export function parseIntentResponse(raw) {
+  const fallback = { intent: 'task', reply: '' };
+  if (!raw || typeof raw !== 'string') return fallback;
+  const m = raw.match(/\{[\s\S]*\}/);
+  if (!m) return fallback;
+  let obj;
+  try { obj = JSON.parse(m[0]); } catch { return fallback; }
+  const intent = obj && obj.intent === 'chat' ? 'chat' : 'task';
+  const reply = intent === 'chat' && typeof obj.reply === 'string' ? obj.reply.trim().slice(0, 2000) : '';
+  return { intent, reply };
+}
+
 // 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
@@ -1600,6 +1770,94 @@ export function reconcileOrphanGoals(goals, tasks) {
   return out;
 }
 
+// ---- cross-device board sync (P3, docs/design/CROSS-DEVICE-SYNC-PLAN.md) ----
+// The "board" is the portable snapshot of one install's local-first state that
+// the sync Worker (P2, PUT/GET /sync/board) stores per account, so a second
+// device signed into the same account inherits the work on boot. These are the
+// pure, unit-tested decision helpers; engine/server.mjs owns the actual disk +
+// network I/O and calls into these.
+export const BOARD_SNAPSHOT_VERSION = 1;
+
+// Assemble the snapshot server.mjs pushes. tasksLog is the raw text of
+// chat-runs/tasks.jsonl (the append-only heart of the board — goals + tasks);
+// the other three are the small JSON state files. Defensive about missing
+// pieces so a partial local state still produces a valid, replayable board.
+export function buildBoardSnapshot({ projects, tasksLog, workflowColumns, reviewDefinitions } = {}) {
+  return {
+    v: BOARD_SNAPSHOT_VERSION,
+    projects: Array.isArray(projects) ? projects : [],
+    tasksLog: typeof tasksLog === 'string' ? tasksLog : '',
+    workflowColumns: workflowColumns && typeof workflowColumns === 'object' ? workflowColumns : {},
+    reviewDefinitions: reviewDefinitions && typeof reviewDefinitions === 'object' ? reviewDefinitions : {},
+  };
+}
+
+// Validate/normalize a board pulled from the store before we let it overwrite
+// local state. Returns the normalized pieces, or null if it's malformed or a
+// version we don't understand (caller must then leave local state untouched).
+export function validateBoardSnapshot(board) {
+  if (!board || typeof board !== 'object') return null;
+  if (board.v !== BOARD_SNAPSHOT_VERSION) return null;
+  if (!Array.isArray(board.projects)) return null;
+  if (typeof board.tasksLog !== 'string') return null;
+  return {
+    projects: board.projects,
+    tasksLog: board.tasksLog,
+    workflowColumns: board.workflowColumns && typeof board.workflowColumns === 'object' ? board.workflowColumns : {},
+    reviewDefinitions: board.reviewDefinitions && typeof board.reviewDefinitions === 'object' ? board.reviewDefinitions : {},
+  };
+}
+
+// A board carries real work only if its task log has content — projects.json
+// always has at least the 'default' project, so it can't be the emptiness
+// signal. Used to decide whether a pull would discard un-synced local work.
+export function boardIsEmpty(snapshot) {
+  if (!snapshot) return true;
+  return !snapshot.tasksLog || !snapshot.tasksLog.trim();
+}
+
+// Monotonic optimistic-lock rev: pull only when the store is strictly ahead of
+// what this device last saw. Equal/older → nothing to adopt (we're current or
+// we're the writer). Missing/garbage revs coerce to 0.
+export function shouldPull({ localRev, remoteRev }) {
+  const l = Number(localRev) || 0;
+  const r = Number(remoteRev) || 0;
+  return r > l;
+}
+
+// Boot-time decision: should we hydrate from the remote board, and does doing
+// so throw away un-synced local work? clobbersLocal is the danger case — a
+// device that has never synced (localRev 0) but already has local goals, while
+// another device has pushed a board. Cross-device is takeover, not concurrent
+// offline editing (a non-goal per the plan): last-writer wins, but the caller
+// logs a warning when clobbersLocal so it's never silent.
+export function decideBoardPull({ localRev, remoteRev, localHasWork, remoteHasWork }) {
+  const pull = shouldPull({ localRev, remoteRev });
+  const clobbersLocal = pull && Boolean(localHasWork) && Boolean(remoteHasWork) && (Number(localRev) || 0) === 0;
+  return { pull, clobbersLocal };
+}
+
+// Live (mid-session) takeover decision (P4). A boot pull runs before any queue
+// or worker exists, so it can always hydrate; a *live* pull runs on an
+// already-serving instance, where hydrateFromBoard rewrites the append-only log
+// wholesale and reassigns goals/tasks. That is only safe when this device has
+// no in-flight work — a running/planning goal owns live worker children whose
+// completion would then write against goals that no longer exist. So this gate
+// refuses when `busy`, and otherwise reuses decideBoardPull for the "is the
+// store actually newer?" question. Returns a single `action`:
+//   'disabled' — sync off (no billing/token, or store un-provisioned)
+//   'busy'     — this device has active work; refuse (caller returns 409)
+//   'invalid'  — remote board missing/unparseable; nothing safe to adopt
+//   'current'  — remote is not ahead; already up to date
+//   'pull'     — adopt the remote board (clobbersLocal flags a last-writer wipe)
+export function liveTakeoverDecision({ syncEnabled, busy, remoteValid, localRev, remoteRev, localHasWork, remoteHasWork }) {
+  if (!syncEnabled) return { action: 'disabled' };
+  if (busy) return { action: 'busy' };
+  if (!remoteValid) return { action: 'invalid' };
+  const { pull, clobbersLocal } = decideBoardPull({ localRev, remoteRev, localHasWork, remoteHasWork });
+  return pull ? { action: 'pull', clobbersLocal } : { action: 'current' };
+}
+
 // 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
@@ -1857,7 +2115,7 @@ export function shouldShowGoalSummary(goal) {
 // 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 } = {}) {
+export function buildReviewSummary({ goal, tasks, approvedN = 0, tokenHistory = [] } = {}) {
   const reqs = (tasks ?? []).filter((t) => !t.reply);
   const total = reqs.length;
   const done = reqs.filter((t) => ['done', 'skipped'].includes(t.status)).length;
@@ -1886,10 +2144,26 @@ export function buildReviewSummary({ goal, tasks, approvedN = 0 } = {}) {
       usedCompact: goal?.executionPlan?.sessionMode === 'compact',
       usedClear: Boolean(goal?.sessionClosedAt),
       agentModel: goal?.model,
+      requirementCount: total,
+      history: tokenHistory,
     }),
   };
 }
 
+// task 6 (2026-07-16): turns a project's finished goals into the `history`
+// list `estimateTokenOptimization` needs for its baseline comparison — one
+// {weightedTokens, requirementCount} sample per finished goal, oldest-first,
+// excluding the goal currently being summarized. Mirrored in app/index.html
+// (goalTokenHistory) since the inline script can't import this module.
+export function goalTokenHistory({ goals = [], tasks = [], excludeGoalId = null } = {}) {
+  return (goals ?? [])
+    .filter((g) => g && g.id !== excludeGoalId && GOAL_COMPLETE_STATUSES.includes(g.status) && g.runTokens != null)
+    .map((g) => ({
+      weightedTokens: g.runTokens,
+      requirementCount: (tasks ?? []).filter((t) => t.goalId === g.id && !t.reply).length,
+    }));
+}
+
 // 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
@@ -2575,6 +2849,188 @@ export function isFolderInitConfirmed(answer, question = {}) {
   return /^(yes|y|はい|ok|する|始める)$/i.test(a);
 }
 
+// Onboarding funnel (task 5, PR運用ヒアリング): before a project's very first
+// runnable goal actually starts work, ask once whether this project wants
+// PRs (Masa: PR使う人/使わない人で欲しい挙動が違うのに今はサイレントに
+// defaultWantsPR:false が適用され、設定パネルを開かないと気づけない). Reuses
+// the same needsInput clarifying-card mechanism as the folder question
+// (kind:'reviewPref' instead of 'folder') so no new UI surface is needed.
+// `askedBefore` is a per-project flag (project.reviewPrefAsked) set the
+// moment the question is asked — so a project is asked at most once ever,
+// even if the user ignores the card and later goals get created for the
+// same project while it's still pending.
+export function needsReviewPreference({ askedBefore } = {}) {
+  return !askedBefore;
+}
+
+// Builds the "PR使いますか？" clarifying question. options[0] = wants PR,
+// options[1] = no PR (direct). Order matters — resolveReviewPreferenceAnswer
+// below keys off these exact indices/labels.
+export function buildReviewPreferenceQuestion({ lang = 'ja' } = {}) {
+  const text = lang === 'en'
+    ? 'Before the first task: do you want changes shipped as a PR to review, or applied directly?'
+    : '最初のタスクの前に：実装はPRでレビューしますか、それとも直接反映しますか？';
+  const options = lang === 'en'
+    ? ['PR — open a pull request to review', 'No PR — apply directly (still lands in Review to check)']
+    : ['PRを作ってレビューする', 'PRなしで直接反映する（Reviewでの確認はある）'];
+  return { text, options, kind: 'reviewPref', lang };
+}
+
+// Resolve a review-preference answer into a partial review-definition patch
+// (merged into the project's stored definition by the caller). Matches by
+// exact option label; an unrecognized/typed answer defaults to wanting a PR
+// — the original pre-task-5 default — rather than silently turning PRs off.
+export function resolveReviewPreferenceAnswer(answer, question) {
+  const noPrOption = question?.options?.[1];
+  const wantsPR = String(answer ?? '').trim() !== String(noPrOption ?? '');
+  return { defaultWantsPR: wantsPR };
+}
+
+// --- Intent router: no free-text field is a dead-end ----------------------
+// Every needsInput card has a free-text box. A reply typed there may be the
+// answer the card expects — OR a meta-instruction ("日本語で教えて", "別のを提案して").
+// The old code coerced anything unrecognized into a literal (`dir = resolved
+// ?.dir || answer`), so a Japanese instruction became a folder NAMED "日本語で
+// 教えて". The router below decides, WITHOUT coercion, which of three paths a
+// reply takes; the server fulfils each (rebuild card / relocalize / ask model).
+// All pure + tested; the server supplies filesystem/LLM I/O.
+
+// Does this string look like a filesystem path (vs prose)? Mirrors the accept
+// rule resolveFolderAnswer already used (absolute / home-relative), plus
+// explicit-relative and any embedded slash. Prose like "日本語で教えて" has no
+// slash → not a path → never silently turned into a folder.
+export function looksLikePath(s) {
+  const a = String(s ?? '').trim();
+  if (!a) return false;
+  return a.startsWith('/') || a.startsWith('~') || a.startsWith('./') || a.startsWith('../') || a.includes('/');
+}
+
+// Detect a reply whose PRIMARY intent is to switch the conversation language,
+// e.g. "日本語で教えて" / "in English please". Returns 'ja' | 'en' | null.
+// Deliberately narrow: only fires on short, language-focused messages, so a
+// real task that merely mentions "英語のドキュメント" isn't misread as a switch.
+// The cards render in ja/en; any other target language returns null here and is
+// left for the model (which can restate in any language).
+export function detectLanguageRequest(text) {
+  const a = String(text ?? '').trim();
+  if (!a || a.length > 40) return null;
+  const lo = a.toLowerCase();
+  const wantsJa = /(日本語|にほんご|ニホンゴ|japanese|nihongo)/.test(lo);
+  const wantsEn = /(英語|えいご|エイゴ|english|eigo)/.test(lo);
+  if (wantsJa && !wantsEn) return 'ja';
+  if (wantsEn && !wantsJa) return 'en';
+  return null;
+}
+
+// Decide how a free-text answer to a needsInput card should be handled, WITHOUT
+// coercing prose into a literal. `question` is goal.question ({kind, options,
+// lang, folders, yes, no, …}). Returns one of:
+//   { route: 'accept' }            — a clean answer; caller runs the card's resolver
+//   { route: 'relocalize', lang }  — a language switch; caller re-renders the SAME
+//                                    question in `lang` (never loses the user's place)
+//   { route: 'escalate' }          — free-form intent that isn't a clean answer;
+//                                    caller hands it to the model / re-asks safely
+export function routeQuestionAnswer(answer, question = {}) {
+  const a = String(answer ?? '').trim();
+  if (!a) return { route: 'escalate' };
+
+  // Picking an offered option verbatim is always a clean answer (any kind).
+  const options = Array.isArray(question.options) ? question.options : [];
+  if (options.some((o) => o === a)) return { route: 'accept' };
+
+  // A language-switch request → relocalize. Suppress only when the card is
+  // KNOWN to already be in that language (question.lang set and equal); a card
+  // without a declared lang (general planner clarify) always relocalizes since
+  // we can't prove it's already there — the model restating is harmless.
+  const lang = detectLanguageRequest(a);
+  if (lang && lang !== question.lang) return { route: 'relocalize', lang };
+
+  switch (question.kind) {
+    case 'folder': {
+      // A picked label, an exact known dir, or a path-like reply is a real answer.
+      // Bare prose is NOT — escalate instead of naming a folder after it.
+      if ((question.folders || []).some((f) => f.label === a || f.dir === a)) return { route: 'accept' };
+      return looksLikePath(a) ? { route: 'accept' } : { route: 'escalate' };
+    }
+    case 'folder-init': {
+      // Yes / an explicit decline are both clean answers; ambiguous prose escalates.
+      if (isFolderInitConfirmed(a, question)) return { route: 'accept' };
+      if (question.no && a === question.no) return { route: 'accept' };
+      if (/^(no|n|いいえ|やめる|キャンセル|cancel)$/i.test(a)) return { route: 'accept' };
+      return { route: 'escalate' };
+    }
+    default:
+      // General planner clarify card: any prose is a legitimate clarification —
+      // the existing path folds it into goal.text and re-plans (the model sees
+      // it). Keep that; only language switches diverted above.
+      return { route: 'accept' };
+  }
+}
+
+// A short localized note prepended to a re-asked card when the reply couldn't be
+// understood as an answer — so the user learns what the box expects instead of
+// silently looping. Folded into the card's existing `text` (no new UI field).
+export function notUnderstoodNote(lang = 'ja') {
+  return lang === 'en'
+    ? 'I couldn’t read that as a folder — type a path (e.g. /Users/you/proj) or pick one above. '
+    : 'それはフォルダとして解釈できませんでした。パス（例: /Users/you/proj）を入力するか、上から選んでください。';
+}
+
+// Parse the model's answer when we ask it to restate a pending clarify question
+// in another language (general cards have no builder to rebuild from). Expects
+// JSON {"text": "...", "options": ["..."]}. Returns {text, options} shaped like
+// a clarify card, or null when the model didn't return usable JSON (caller keeps
+// the original card). Options are capped to the same bounds as planGoal.
+export function parseRelocalizedQuestion(raw) {
+  try {
+    const m = String(raw ?? '').match(/\{[\s\S]*\}/);
+    if (!m) return null;
+    const o = JSON.parse(m[0]);
+    const text = String(o?.text ?? o?.question ?? '').trim().slice(0, 300);
+    if (!text) return null;
+    const options = Array.isArray(o?.options) ? o.options.slice(0, 4).map((x) => String(x).slice(0, 60)) : [];
+    return { text, options };
+  } catch {
+    return null;
+  }
+}
+
+// --- Worker auth preflight -------------------------------------------------
+// The manager runs every worker by spawning a standalone `claude` (server.mjs
+// runClaude), which inherits the LAUNCHING SHELL's login. If that shell has no
+// usable `claude` credentials, every task fails late with "Not logged in ·
+// Please run /login" (root cause of Masa's all-tasks-failed report). A boot
+// preflight probes once so the server can raise a banner and hold the queue
+// instead of failing task after task. Pure so we can test the classification
+// without spawning a process. NOTE: `claude -p` exits 0 even when logged out,
+// so we classify on the TEXT, not the exit code.
+export function classifyAuthProbe({ result = '', code = 0 } = {}) {
+  const text = String(result ?? '');
+  if (/not logged in|please run\s*\/login|\brun \/login\b/i.test(text)) return { ok: false, reason: 'logged-out' };
+  if (/invalid api key|authentication_error|\bunauthorized\b|not authenticated|401\b/i.test(text)) return { ok: false, reason: 'bad-credentials' };
+  if (code !== 0) return { ok: false, reason: 'probe-failed' };
+  return { ok: true, reason: null };
+}
+
+// One-line, actionable banner text for an auth-preflight failure. Tells the user
+// exactly how to fix it: sign the standalone CLI in, then RELAUNCH the manager
+// from that shell (the worker inherits that shell's login). Localized; the app
+// chrome is English (DESIGN-RULES) so the client mirrors the 'en' strings.
+export function authBannerText(reason, lang = 'ja') {
+  const en = {
+    'bad-credentials': 'Worker sign-in failed. Check ANTHROPIC_API_KEY, or run `claude` and /login, then relaunch the manager from that terminal.',
+    'probe-failed': 'Couldn’t verify `claude` sign-in. Make sure the `claude` CLI is installed and signed in, then relaunch the manager.',
+    'logged-out': 'Not signed in to `claude`. Run `claude` in a terminal and /login, then relaunch the manager from that same terminal. Tasks are paused until then.',
+  };
+  const ja = {
+    'bad-credentials': 'worker のサインインに失敗しました。ANTHROPIC_API_KEY を確認するか、ターミナルで `claude` を起動して /login し、そのターミナルから manager を再起動してください。',
+    'probe-failed': '`claude` のサインインを確認できませんでした。`claude` CLI がインストール済みでログイン済みか確認し、manager を再起動してください。',
+    'logged-out': 'ターミナルで `claude` にログインしてから起動してください（`claude` → /login 後、同じターミナルで manager を再起動）。ログインするまでタスクは実行しません。',
+  };
+  const table = lang === 'en' ? en : ja;
+  return table[reason] || table['logged-out'];
+}
+
 // Analytics identity (A+): a signed-in install scopes usage events to the
 // ACCOUNT (its email, which the billing Worker hashes into the same account_id
 // the accounts table carries) so per-user app activity joins WITHOUT a cookie;
@@ -2588,3 +3044,71 @@ export function pickAnalyticsUid(accountEmail, installId) {
 export function shouldEmitFreeExhausted(alreadyEmitted, blocked) {
   return !alreadyEmitted && Boolean(blocked);
 }
+
+// --- relay stand-down: kill the two-device mutual-kick loop --------------------
+// The relay binds ONE agent socket per account (idForEmail(email)); a newer
+// connection evicts the older one with close code 4000. License tokens are
+// SHORT-LIVED (7d) and the app re-fetches a fresh one while online, so the SAME
+// email's license.token string CHANGES over time. Without care, that re-mint is
+// indistinguishable from a sign-in and makes the evicted (stood-down) instance
+// re-dial → it evicts the other device → which later re-mints and re-dials →
+// forever. The user sees app.galda.app reload-looping (the "無限ループ").
+//
+// Fix: once we're evicted (4000) we go stoodDown and remember WHICH identity we
+// were bound to. A token change for the SAME identity (a re-mint of the account
+// already live on the other device) must NOT re-dial. Only a genuinely DIFFERENT
+// identity (the user switched accounts on this device) or an explicit takeover
+// (the "switch to this device" button, P4) re-dials. Newest instance wins, and
+// the loser stays down through any number of re-mints.
+
+// Pull the account identity out of a compact license token WITHOUT verifying the
+// signature — we only need a stable local key to compare "same account?". Format
+// is b64url(header).b64url(payload).b64url(sig) with payload.email (see
+// workers/billing-api/src/license.mjs). Returns '' when it can't be decoded.
+export function licenseTokenIdentity(token) {
+  if (!token || typeof token !== 'string') return '';
+  const parts = token.split('.');
+  if (parts.length !== 3) return '';
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    const email = payload?.email;
+    return typeof email === 'string' ? email.trim().toLowerCase() : '';
+  } catch { return ''; }
+}
+
+// Pure reducer for the relay-client's reconnect decision. Returns the next state
+// and whether to dial the relay now. State: { stoodDown, standingIdentity }.
+// Events:
+//   { type: 'evicted', identity }     — relay closed us with 4000 (superseded)
+//   { type: 'dropped' }               — a normal connection drop (network etc.)
+//   { type: 'tokenChanged', identity }— license.token appeared/changed on disk
+//   { type: 'takeover' }              — user explicitly claimed this device (P4)
+export function relayReconnectDecision(state, event) {
+  const s = { stoodDown: Boolean(state?.stoodDown), standingIdentity: state?.standingIdentity ?? null };
+  switch (event?.type) {
+    case 'evicted':
+      // A newer instance of THIS account took the slot — stand down and record
+      // whose slot we lost, so a later re-mint of the same account won't re-dial.
+      return { state: { stoodDown: true, standingIdentity: event.identity ?? s.standingIdentity }, dial: false, reason: 'superseded' };
+    case 'dropped':
+      // Ordinary drop: reconnect, UNLESS we already stood down (never re-enter
+      // the ring while another device holds the slot).
+      return { state: s, dial: !s.stoodDown, reason: s.stoodDown ? 'stood-down' : 'reconnect' };
+    case 'tokenChanged': {
+      const id = event.identity || '';
+      if (s.stoodDown && id && id === s.standingIdentity) {
+        // Same account re-minted its token — the other device is still it. Stay
+        // down; this is the exact re-dial that caused the infinite loop.
+        return { state: s, dial: false, reason: 'same-account-remint' };
+      }
+      // A different account (real account switch) or first sign-in → clear the
+      // stand-down and dial with the new identity.
+      return { state: { stoodDown: false, standingIdentity: null }, dial: true, reason: 'identity-changed' };
+    }
+    case 'takeover':
+      // User pressed "switch to this device" — reclaim the slot on purpose.
+      return { state: { stoodDown: false, standingIdentity: null }, dial: true, reason: 'takeover' };
+    default:
+      return { state: s, dial: false, reason: 'noop' };
+  }
+}