amicus 4.4.0 → 4.5.0

package/src/sidecar/session-utils.js

@@ -229,13 +229,14 @@ async function executeMode(options) {
  *   has no single default `config.model`, so this registers ALL of them in provider.models
  *   instead. Additive alongside the single-model `options.model` path used by owned-server
  *   callers (start/continue); see opencode-client.js's buildServerOptions.
+ * @param {number} [options.retryDelayMs] - Test seam: collapse the lock-race backoff.
  * @returns {Promise<{client: object, server: object}>}
  * @throws {Error} If server fails to start or health check fails
  */
 async function startOpenCodeServer(mcpConfig, options = {}) {
   const { checkHealth, startServer } = require('../opencode-client');
   const { ensureNodeModulesBinInPath } = require('../utils/path-setup');
-  const { ensurePortAvailable } = require('../utils/server-setup');
+  const { ensurePortAvailable, retryOnLockRace } = require('../utils/server-setup');
   const { waitForServer } = require('../headless');
 
   ensureNodeModulesBinInPath();
@@ -253,20 +254,28 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
 
-  const { client, server } = await startServer(serverOptions);
-  logger.debug('OpenCode server started', { url: server.url });
-
-  const ready = await waitForServer(client, checkHealth);
-  if (!ready) {
-    // Fire-and-forget: today close() is sync (Promise.resolve wraps a
-    // non-promise harmlessly); once close() becomes async (bounded
-    // kill-escalation poll) this guard prevents an unhandled rejection
-    // from racing the throw below.
-    Promise.resolve(server.close()).catch(() => {});
-    throw new Error('OpenCode server failed to become ready');
-  }
+  // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
+  // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).
+  // The per-run shared server removes the races a single amicus process creates;
+  // this covers the ones it cannot — two amicus processes, or a CLI run beside a
+  // live MCP server, sharing one OpenCode SQLite database. Nothing else retries:
+  // see isLockClassStartFailure in ../utils/server-setup.
+  return retryOnLockRace(async () => {
+    const { client, server } = await startServer(serverOptions);
+    logger.debug('OpenCode server started', { url: server.url });
+
+    const ready = await waitForServer(client, checkHealth);
+    if (!ready) {
+      // Fire-and-forget: today close() is sync (Promise.resolve wraps a
+      // non-promise harmlessly); once close() becomes async (bounded
+      // kill-escalation poll) this guard prevents an unhandled rejection
+      // from racing the throw below.
+      Promise.resolve(server.close()).catch(() => {});
+      throw new Error('OpenCode server failed to become ready');
+    }
 
-  return { client, server };
+    return { client, server };
+  }, { retryDelayMs: options.retryDelayMs });
 }
 
 module.exports = {

package/src/sidecar/start.js

@@ -35,7 +35,7 @@ function generateTaskId() {
 
 /** Create session directory and save metadata */
 function createSessionMetadata(taskId, project, options) {
-  const { model, prompt, briefing, noUi, headless, agent, thinking } = options;
+  const { model, prompt, briefing, noUi, headless, agent, thinking, pack } = options;
 
   const sessionDir = SessionPaths.sessionDir(project, taskId);
   fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
@@ -65,7 +65,8 @@ function createSessionMetadata(taskId, project, options) {
     thinking: thinking || 'medium',
     status: 'running',
     pid: existing.pid || process.pid,
-    createdAt: existing.createdAt || new Date().toISOString()
+    createdAt: existing.createdAt || new Date().toISOString(),
+    ...(pack ? { pack } : {}), // v4.5 Task 13: absent-not-null; ...existing above preserves a prior write when this call omits pack.
   };
 
   writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
@@ -153,7 +154,7 @@ async function startSidecar(options) {
     contextMaxTokens = 80000, noUi, headless = false, timeout = 15,
     agent, mcp, mcpConfig, summaryLength = 'normal', thinking,
     client, sessionDir, noMcp, excludeMcp, opencodePort, coworkProcess, includeContext = true,
-    position = 'right', json = false, modelInput = null
+    position = 'right', json = false, modelInput = null, pack = null
   } = options;
 
   const effectivePrompt = prompt || briefing;
@@ -182,7 +183,7 @@ async function startSidecar(options) {
   );
 
   const sessDir = createSessionMetadata(taskId, effectiveProject, {
-    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking
+    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking, pack
   });
   saveInitialContext(sessDir, systemPrompt, userMessage);
   acquireLock(sessDir, effectiveHeadless ? 'headless' : 'interactive');

package/src/sidecar/workspace-auto-open.js

@@ -0,0 +1,69 @@
+/**
+ * Workspace Auto-Open Decision Helper
+ *
+ * Pure helper to determine whether the Council Workspace should auto-open
+ * on MCP council runs from Claude Code (local). Returns the decision and reason.
+ *
+ * Decision order (spec §6 guard 4):
+ * 1. uiParam === false → 'param-suppressed' (explicit user request beats everything, checked first)
+ * 2. Hard guards (always checked, beat even explicit true):
+ *    - !electronUsable → 'electron-absent'
+ *    - platform === 'linux' && !env.DISPLAY → 'no-display'
+ * 3. uiParam === true → 'ok' (explicit request overrides config and client gate, never hard guards)
+ * 4. autoOpenConfig === false → 'config-disabled'
+ * 5. client !== 'code-local' → 'client-not-code-local'
+ * 6. else → 'ok'
+ *
+ * @param {object} options
+ * @param {string} options.client - The client type (e.g., 'code-local', 'cowork', 'code-web')
+ * @param {boolean} options.electronUsable - Whether Electron is available
+ * @param {string} options.platform - The platform (e.g., 'win32', 'darwin', 'linux')
+ * @param {object} options.env - Environment variables object
+ * @param {boolean} options.autoOpenConfig - The config.workspace.autoOpen setting
+ * @param {boolean|undefined} options.uiParam - Explicit UI parameter (true, false, or undefined)
+ * @returns {{open: boolean, reason: string}}
+ */
+function shouldAutoOpenWorkspace({
+  client,
+  electronUsable,
+  platform,
+  env,
+  autoOpenConfig,
+  uiParam,
+}) {
+  // Step 1: uiParam === false beats everything (checked first)
+  if (uiParam === false) {
+    return { open: false, reason: 'param-suppressed' };
+  }
+
+  // Step 2: Hard guards (always checked, beat even explicit uiParam === true)
+  if (!electronUsable) {
+    return { open: false, reason: 'electron-absent' };
+  }
+
+  if (platform === 'linux' && !env.DISPLAY) {
+    return { open: false, reason: 'no-display' };
+  }
+
+  // Step 3: uiParam === true overrides config and client gate (but not hard guards)
+  if (uiParam === true) {
+    return { open: true, reason: 'ok' };
+  }
+
+  // Step 4: autoOpenConfig === false
+  if (autoOpenConfig === false) {
+    return { open: false, reason: 'config-disabled' };
+  }
+
+  // Step 5: client !== 'code-local'
+  if (client !== 'code-local') {
+    return { open: false, reason: 'client-not-code-local' };
+  }
+
+  // Step 6: else
+  return { open: true, reason: 'ok' };
+}
+
+module.exports = {
+  shouldAutoOpenWorkspace,
+};

package/src/sidecar/workspace-window.js

@@ -59,4 +59,49 @@ async function launchWorkspaceWindow({ project, runId = '' }, deps = {}) {
   });
 }
 
-module.exports = { launchWorkspaceWindow };
+/**
+ * v4.5 auto-open: fire-and-forget Workspace launch for the MCP path.
+ * DELIBERATELY different from launchWorkspaceWindow above:
+ * - never provisions (isElectronUsable check only — ensureElectron can
+ *   DOWNLOAD Electron, which auto-open guard 3 forbids);
+ * - no stdout relay (the caller may be an MCP stdio server whose stdout IS
+ *   the JSON-RPC channel — relaying would corrupt the protocol);
+ * - detached + unref, returns immediately (the sibling's promise resolves
+ *   only when the window CLOSES, which no request path may wait on).
+ * @param {{project: string, runId?: string}} opts
+ * @param {{isElectronUsable?: Function, resolveElectronBinary?: Function, spawn?: Function}} [deps]
+ * @returns {{launched: boolean, reason?: string}}
+ */
+function launchWorkspaceWindowDetached({ project, runId = '' }, deps = {}) {
+  const usable = deps.isElectronUsable || require('./electron-install').isElectronUsable;
+  const resolveExe = deps.resolveElectronBinary || require('./electron-install').resolveElectronBinary;
+  const spawnFn = deps.spawn || spawn;
+  if (!usable()) { return { launched: false, reason: 'electron-absent' }; }
+  const electronPath = resolveExe() || getElectronPath();
+  const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
+  const env = {
+    ...process.env,
+    AMICUS_MODE: 'council-workspace',
+    AMICUS_PROJECT: project,
+    AMICUS_RUN_ID: runId || '',
+    AMICUS_FOLD_NONCE: generateFoldNonce(),
+  };
+  try {
+    const proc = spawnFn(electronPath, [mainPath], { env, detached: true, stdio: 'ignore' });
+    // Node emits spawn failures (ENOENT/EACCES/corrupt binary) as an async
+    // 'error' event on the child; an unlistened ChildProcess 'error' is an
+    // uncaught exception. The MCP server (`amicus mcp`) installs no
+    // uncaughtException handler (bin/amicus.js only does that for
+    // start/continue), so that would kill the JSON-RPC channel. Best-effort:
+    // just log it, matching the fire-and-forget contract of this function.
+    proc.on('error', (err) => logger.debug('Workspace auto-open child failed (best-effort)', { error: err.message }));
+    proc.unref();
+    logger.info('Auto-opened council workspace (detached)', { runId: runId || '(run list)' });
+    return { launched: true };
+  } catch (err) {
+    logger.debug('Workspace auto-open spawn failed (best-effort)', { error: err.message });
+    return { launched: false, reason: `spawn-failed: ${err.message}` };
+  }
+}
+
+module.exports = { launchWorkspaceWindow, launchWorkspaceWindowDetached };

package/src/spend-query.js

@@ -60,25 +60,32 @@ function rowKey(row, dimension) {
 }
 
 /**
- * Group rows into {key, amount, tokens, runs, unpricedRows, sourceMix},
- * most-expensive first.
+ * Group rows into {key, amount, tokens, runs, unpricedRows,
+ * unattributedSubtreeRows, sourceMix}, most-expensive first.
  *
  * v4.4: `amount` deliberately stays a plain number — the published
  * spend.schema.json pins `groups[].amount` to `type: "number"` — so
  * `unpricedRows` is how a group says "this figure omits N rows we cannot
  * price". Without it, a group of entirely unpriced rows was indistinguishable
  * from a group that genuinely cost $0 (diagnosis §8).
+ *
+ * v4.4.1 CA-2: `unattributedSubtreeRows` is the SECOND way a figure can be a
+ * floor, and `unpricedRows` structurally cannot see it — such a row IS priced,
+ * lands in the `r` source bucket, and contributes its own cost to `amount`; what
+ * is missing is the child session it spawned. The two counters are incremented
+ * BESIDE each other, never instead of: a row can be both.
  */
 function groupRows(rows, dimension) {
   const map = new Map();
   for (const r of rows) {
     const key = rowKey(r, dimension);
-    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
+    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
     const b = map.get(key);
     b.runs += 1;
     addTokens(b.tokens, r.tokens);
     const cost = r.cost || {};
     if (typeof cost.amount === 'number') { b.amount += cost.amount; } else { b.unpricedRows += 1; }
+    if (r.subtreeUnknown) { b.unattributedSubtreeRows += 1; }
     const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
     b.sourceMix[src] += 1;
   }
@@ -96,7 +103,7 @@ function groupRows(rows, dimension) {
  * a row); computeWasted intentionally drops it instead.
  */
 function computeWasted(rows) {
-  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, byStatus: {} };
+  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, byStatus: {} };
   for (const r of rows) {
     if (r.status === 'complete' || !r.status) { continue; }
     out.runs += 1;
@@ -104,14 +111,19 @@ function computeWasted(rows) {
     // v4.4: null→0 here is arithmetic, not a claim. `unpricedRows` records how
     // many failed rows we could not price so "wasted $X" is never mistaken for
     // the whole loss (see groupRows for why `amount` stays a number).
+    // v4.4.1 CA-2: `unattributedSubtreeRows` is the other half of the same
+    // understatement — a failed leg that DID resolve its own cost but left a
+    // child session unpriced. Counted beside `unpricedRows`, never instead of.
     const priced = r.cost && typeof r.cost.amount === 'number';
     const amt = priced ? r.cost.amount : 0;
     if (!priced) { out.unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.unattributedSubtreeRows += 1; }
     out.amount += amt;
-    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0 }; }
+    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0 }; }
     out.byStatus[r.status].amount += amt;
     out.byStatus[r.status].runs += 1;
     if (!priced) { out.byStatus[r.status].unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.byStatus[r.status].unattributedSubtreeRows += 1; }
   }
   return out;
 }

package/src/template/apply.js

@@ -0,0 +1,88 @@
+// src/template/apply.js
+'use strict';
+
+/**
+ * @module template/apply
+ * F9 (v4.5): the one seam that turns (--template, --prompt, --artifact, --var)
+ * into a rendered briefing + template-sourced promptMeta. Used by the three CLI
+ * run commands and by pack-resolve for a pack's briefing.template (which is how
+ * templates reach MCP callers — MCP has no template params of its own).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ERROR_CODES } = require('../utils/error-doc');
+const { resolveTemplate } = require('./store');
+const { renderTemplate } = require('./render');
+
+const ARTIFACT_CAP_BYTES = 256 * 1024;
+
+/**
+ * @param {{templateRef: string, prompt?: string, artifactFile?: string,
+ *          varList?: string[], project: string}} opts
+ * @returns {{prompt, promptMeta, notices} | {error: {code, message, hint}}}
+ */
+function applyTemplate({ templateRef, prompt, artifactFile, varList, project }) {
+  const tpl = resolveTemplate(templateRef);
+  if (tpl.error) {
+    return { error: { code: ERROR_CODES.TEMPLATE_NOT_FOUND, message: tpl.error, hint: 'amicus template list' } };
+  }
+
+  const vars = {};
+  // F4 (Task-5 review): parseArgs' inline `--var=k=v` form takes the single-value
+  // branch, not the array-accumulation one, so varList arrives as a bare string
+  // instead of a one-element array — wrap it rather than let `for..of` iterate
+  // its characters. parseArgs itself is unchanged (plan-mandated, shared with
+  // --exclude-mcp); this coercion is the seam that absorbs both shapes.
+  const varArr = Array.isArray(varList)
+    ? varList
+    : (varList !== undefined && varList !== null) ? [varList] : [];
+  for (const entry of varArr) {
+    const eq = String(entry).indexOf('=');
+    if (eq < 1) {
+      return { error: { code: ERROR_CODES.BAD_ARGS, message: `Error: --var expects key=value, got '${entry}'`, hint: null } };
+    }
+    vars[String(entry).slice(0, eq)] = String(entry).slice(eq + 1);
+  }
+
+  let artifact; let artifactPath;
+  if (artifactFile !== undefined) {
+    artifactPath = path.resolve(String(artifactFile));
+    let raw;
+    try {
+      raw = fs.readFileSync(artifactPath);
+    } catch (err) {
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: cannot read --artifact ${artifactFile}: ${err.message}`, hint: null } };
+    }
+    if (raw.length > ARTIFACT_CAP_BYTES) {
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: --artifact ${artifactFile} is ${raw.length} bytes; the cap is 256 KB`, hint: null } };
+    }
+    artifact = raw.toString('utf-8');
+    if (artifact.charCodeAt(0) === 0xFEFF) { artifact = artifact.slice(1); }
+  }
+
+  const res = renderTemplate(tpl.text, {
+    prompt,
+    artifact,
+    artifactPath,
+    date: new Date().toISOString().slice(0, 10),
+    project: String(project),
+    vars,
+  });
+  if (res.error) {
+    return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: res.error, hint: null } };
+  }
+
+  return {
+    prompt: res.text,
+    promptMeta: {
+      source: 'template',
+      file: tpl.path,
+      chars: res.text.length,
+      template: { name: tpl.name, hash: tpl.hash },
+    },
+    notices: res.notices,
+  };
+}
+
+module.exports = { applyTemplate, ARTIFACT_CAP_BYTES };

package/src/template/render.js

@@ -0,0 +1,86 @@
+// src/template/render.js
+'use strict';
+
+/**
+ * @module template/render
+ * F9 (v4.5): strict {{variable}} rendering for briefing templates. Expansion
+ * happens ONLY in template files (spec carried decision 7) — --prompt text is
+ * always literal, so this module never sees non-template input.
+ *
+ * v4.5 variable set. {{input}} is deliberately ABSENT — it ships with v4.6's
+ * --input-from; on v4.5 it fails as an unknown variable, which is accurate.
+ * No {{model}}: prompts are built once per wave, model-independent.
+ */
+
+const VAR_RE = /\{\{\s*([A-Za-z_][\w.]*)\s*\}\}/g;
+const KNOWN_VARIABLES = ['prompt', 'artifact', 'artifact_path', 'date', 'project', 'var.<key>'];
+
+function knownList() {
+  return KNOWN_VARIABLES.map((v) => `{{${v}}}`).join(', ');
+}
+
+/**
+ * Render a template with strict typo-safety rules:
+ * unknown variable -> error; slot present without its data -> error; data
+ * passed without its slot -> error ("silently dropped"); unused --var -> notice.
+ *
+ * @param {string} text - raw template text
+ * @param {{prompt?: string, artifact?: string, artifactPath?: string,
+ *          date: string, project: string, vars?: Object<string,string>}} data
+ * @returns {{text: string, notices: string[]} | {error: string}}
+ */
+function renderTemplate(text, data) {
+  const vars = data.vars || {};
+  const used = new Set();
+  for (const m of String(text).matchAll(VAR_RE)) { used.add(m[1]); }
+
+  for (const name of used) {
+    if (name.startsWith('var.')) {
+      const key = name.slice(4);
+      if (!(key in vars)) {
+        return { error: `Error: template uses {{var.${key}}} but no --var ${key}=<value> was given` };
+      }
+      continue;
+    }
+    if (!['prompt', 'artifact', 'artifact_path', 'date', 'project'].includes(name)) {
+      return { error: `Error: Unknown template variable {{${name}}}. Known: ${knownList()}` };
+    }
+  }
+
+  if (used.has('prompt') && data.prompt === undefined) {
+    return { error: 'Error: template has {{prompt}} but no --prompt/--prompt-file was given' };
+  }
+  if (!used.has('prompt') && data.prompt !== undefined) {
+    return { error: 'Error: --prompt/--prompt-file was given but the template has no {{prompt}} slot — the text would be silently dropped' };
+  }
+  const usesArtifact = used.has('artifact') || used.has('artifact_path');
+  if (used.has('artifact') && data.artifact === undefined) {
+    return { error: 'Error: template has {{artifact}} but no --artifact <file> was given' };
+  }
+  if (used.has('artifact_path') && data.artifactPath === undefined) {
+    return { error: 'Error: template has {{artifact_path}} but no --artifact <file> was given' };
+  }
+  if (!usesArtifact && (data.artifact !== undefined || data.artifactPath !== undefined)) {
+    return { error: 'Error: --artifact was given but the template has no {{artifact}}/{{artifact_path}} slot — the file would be silently dropped' };
+  }
+
+  const notices = [];
+  for (const key of Object.keys(vars)) {
+    if (!used.has(`var.${key}`)) {
+      notices.push(`Notice: --var ${key}=… is not used by this template`);
+    }
+  }
+
+  const rendered = String(text).replace(VAR_RE, (_, name) => {
+    if (name === 'prompt') { return data.prompt; }
+    if (name === 'artifact') { return data.artifact; }
+    if (name === 'artifact_path') { return data.artifactPath; }
+    if (name === 'date') { return data.date; }
+    if (name === 'project') { return data.project; }
+    return vars[name.slice(4)];
+  });
+
+  return { text: rendered, notices };
+}
+
+module.exports = { renderTemplate, KNOWN_VARIABLES };

package/src/template/store.js

@@ -0,0 +1,106 @@
+// src/template/store.js
+'use strict';
+
+/**
+ * @module template/store
+ * F9 (v4.5): briefing templates are Markdown files in <configDir>/templates/
+ * (peer of packs/). Name = basename sans .md. Built-ins are embedded strings,
+ * shadowed by a same-named user file — exactly the built-in-bench precedent
+ * (config.js getCouncilWithSource). No save/rm: your editor is the manager.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Lazy so jest.doMock / AMICUS_CONFIG_DIR re-pointing works per-test.
+function _getConfigDir() { return require('../utils/config').getConfigDir(); }
+
+/**
+ * v4.5 ships `review` only. `critique`/`refine` are {{input}}-centric and
+ * arrive with v4.6's chaining (--input-from).
+ */
+const BUILTIN_TEMPLATES = Object.freeze({
+  review: [
+    '# Review briefing',
+    '',
+    'You are reviewing the artifact below against the caller\'s focus.',
+    '',
+    '## Focus',
+    '',
+    '{{prompt}}',
+    '',
+    '## Artifact ({{artifact_path}})',
+    '',
+    '{{artifact}}',
+    '',
+    '## Instructions',
+    '',
+    '- Ground every finding in the artifact text and cite its location.',
+    '- Give each finding a severity: critical / major / minor / nit.',
+    '- If you find nothing at a severity, say so explicitly.',
+    '- End with a one-paragraph overall verdict.',
+    '',
+  ].join('\n'),
+});
+
+/** @returns {string} the user templates directory (peer of packs/) */
+function templatesDir() {
+  return path.join(_getConfigDir(), 'templates');
+}
+
+function hashText(text) {
+  return crypto.createHash('sha256').update(text, 'utf-8').digest('hex').slice(0, 12);
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+}
+
+/**
+ * @param {string} nameOrPath - a path when it contains a path separator or
+ *   ends in `.md`; otherwise a template name.
+ * @returns {{name, path: string|null, text, hash, builtin: boolean} | {error: string}}
+ */
+function resolveTemplate(nameOrPath) {
+  const v = String(nameOrPath);
+  const isPath = v.endsWith('.md') || v.includes('/') || v.includes(path.sep);
+  if (isPath) {
+    const abs = path.resolve(v);
+    let text;
+    try {
+      text = stripBom(fs.readFileSync(abs, 'utf-8'));
+    } catch (err) {
+      return { error: `Error: cannot read template ${v}: ${err.message}` };
+    }
+    return { name: path.basename(abs, '.md'), path: abs, text, hash: hashText(text), builtin: false };
+  }
+  const userFile = path.join(templatesDir(), `${v}.md`);
+  try {
+    const text = stripBom(fs.readFileSync(userFile, 'utf-8'));
+    return { name: v, path: userFile, text, hash: hashText(text), builtin: false };
+  } catch { /* fall through to built-ins */ }
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_TEMPLATES, v)) {
+    const text = BUILTIN_TEMPLATES[v];
+    return { name: v, path: null, text, hash: hashText(text), builtin: true };
+  }
+  return { error: `Error: Template '${v}' not found (looked in ${templatesDir()} and built-ins)` };
+}
+
+/** @returns {Array<{name, builtin: boolean, shadowed: boolean}>} name-sorted */
+function listTemplates() {
+  const out = new Map();
+  for (const name of Object.keys(BUILTIN_TEMPLATES)) {
+    out.set(name, { name, builtin: true, shadowed: false });
+  }
+  let entries = [];
+  try { entries = fs.readdirSync(templatesDir()); } catch { /* no user dir yet */ }
+  for (const f of entries) {
+    if (!f.endsWith('.md')) { continue; }
+    const name = path.basename(f, '.md');
+    out.set(name, { name, builtin: false, shadowed: Object.prototype.hasOwnProperty.call(BUILTIN_TEMPLATES, name) });
+  }
+  return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+module.exports = { templatesDir, resolveTemplate, listTemplates, BUILTIN_TEMPLATES };