@worca/app 1.2.0-rc.1 → 1.2.0-rc.3

package/src/core/config.mjs

@@ -15,8 +15,8 @@
 import { getDb, prepare, tx } from './db.mjs';
 import { projectKey } from './store.mjs';
 import { loadAgentRegistry, registryToSteps } from './agent-registry.mjs';
-import { EFFORTS, prepareModelEnv, isSubagentModelValue, subagentModelIssue } from './model-env.mjs';
-import { listGlobalModels, addGlobalModel, removeGlobalModel } from './settings.mjs';
+import { EFFORTS, prepareModelEnv, withTierModelEnv, isSubagentModelValue, subagentModelIssue } from './model-env.mjs';
+import { listGlobalModels, addGlobalModel, removeGlobalModel, hideBuiltinModels } from './settings.mjs';
 import { listPluginModels, allPluginModels, flattenPluginModelEnv } from './plugin-models.mjs';
 
 /**
@@ -184,6 +184,11 @@ function composeCatalog(projectCustom = []) {
   const seen = new Set();
   const unreliable = (lc) => (flagged.has(lc) ? { costUnreliable: true } : {});
   const routedOf = (env) => !!(env && 'ANTHROPIC_BASE_URL' in env);
+  // "Hide built-in models" (#422): a cosmetic flag on the UNSHADOWED built-ins,
+  // read by every picker. The entry stays in the catalog — hiding an id must
+  // never stop it resolving, or a stored run / plugin reference that names it
+  // would break — so pickers skip `hidden`, validators ignore it.
+  const hidden = hideBuiltinModels() ? { hidden: true } : {};
   const pluginShape = (id, m, lc) => ({
     id, label: m.label, efforts: [...m.efforts], custom: 'plugin', plugin: m.plugin,
     hasEnv: !!m.env, routed: routedOf(m.env), ...unreliable(lc),
@@ -196,7 +201,7 @@ function composeCatalog(projectCustom = []) {
       ? { id: m.id, label: shadow.label, efforts: [...shadow.efforts], custom: 'global', hasEnv: !!shadow.env, routed: routedOf(shadow.env), ...unreliable(lc) }
       : pshadow
         ? pluginShape(m.id, pshadow, lc)
-        : { ...m, custom: false, hasEnv: false, routed: false });
+        : { ...m, custom: false, hasEnv: false, routed: false, ...hidden });
     seen.add(lc);
   }
   for (const m of globals) {
@@ -486,10 +491,12 @@ export function resolveModelEnv(modelId) {
   const lc = id.toLowerCase();
   let rawEnv;
   let who;
+  let canonicalId = id;
   const entry = listGlobalModels().find((m) => m.id.toLowerCase() === lc);
   if (entry && entry.env) {
     rawEnv = entry.env;
     who = JSON.stringify(entry.id);
+    canonicalId = entry.id;
   } else if (!entry) {
     const pm = listPluginModels().find((m) => m.id.toLowerCase() === lc);
     if (pm && pm.env) {
@@ -499,6 +506,7 @@ export function resolveModelEnv(modelId) {
       }
       rawEnv = env;
       who = `${JSON.stringify(pm.id)} (plugin "${pm.plugin}")`;
+      canonicalId = pm.id;
     }
   }
   if (!rawEnv) return undefined;
@@ -506,7 +514,27 @@ export function resolveModelEnv(modelId) {
   for (const k of dropped) {
     console.warn(`[worca] model ${who}: dropping env key ${JSON.stringify(k)} (reserved or unresolvable \${VAR} ref)`);
   }
-  return Object.keys(env).length ? env : undefined;
+  if (!Object.keys(env).length) return undefined;
+  // Endpoint-routed entries also carry the CLI's internal tier keys, pointed at
+  // this entry's own wire id (#422, model-env.mjs#withTierModelEnv) — so the
+  // CLI's session-title / alias / probe calls never fall back to a first-party
+  // id the endpoint has never heard of. Keys the entry sets itself win.
+  return withTierModelEnv(env, canonicalId);
+}
+
+/**
+ * Whether `modelId` names a catalog member — built-in, global, or plugin —
+ * regardless of the hide-built-ins flag (hidden entries still resolve).
+ * Case-insensitive like every other id lookup here. Synchronous; never throws.
+ * @param {string} modelId
+ */
+export function catalogHasModel(modelId) {
+  const id = typeof modelId === 'string' ? modelId.trim() : '';
+  if (!id) return false;
+  const lc = id.toLowerCase();
+  return PREDEFINED_MODELS.some((m) => m.id.toLowerCase() === lc)
+    || listGlobalModels().some((m) => m.id.toLowerCase() === lc)
+    || listPluginModels().some((m) => m.id.toLowerCase() === lc);
 }
 
 /**
@@ -990,6 +1018,7 @@ export async function setActiveWorkflow(projectDir, workflowId) {
  * @returns {Promise<{nodes:Record<string,object>,feedbacks:Record<string,{maxCycles:number}>}>}
  */
 export async function resolveRunConfig(projectDir, workflowId) {
+  if (!projectDir) return { nodes: {}, wires: {}, feedbacks: {} };   // defaults-only (global export); avoids projectKey(null). v2 shape incl. wires.
   const wf = readWorkflowsMap(projectKey(projectDir))[workflowId] || {};
   return {
     nodes: wf.nodes && typeof wf.nodes === 'object' ? wf.nodes : {},

package/src/core/folder-dialog.mjs

@@ -20,7 +20,14 @@
 
 import { spawn } from 'node:child_process';
 
-const PROMPT = 'Select a project folder';
+// The dialog title, by PURPOSE. A closed set, never caller text: the string is
+// interpolated into an osascript / PowerShell command line.
+const PROMPTS = Object.freeze({
+  project: 'Select a project folder',
+  export: 'Select the project folder to export into',
+  plugin: 'Select the plugin folder',
+});
+const promptFor = (purpose) => PROMPTS[purpose] || PROMPTS.project;
 // A dialog waits on a human; give it a long leash, then kill the process so a
 // forgotten dialog cannot pin server resources forever.
 const DIALOG_TIMEOUT_MS = 5 * 60 * 1000;
@@ -75,20 +82,22 @@ export const _testing = {
 /**
  * Open the platform's native folder picker and wait for the user.
  * Serialized: while one dialog is open, further calls resolve { status:'busy' }.
+ * @param {{purpose?: 'project'|'export'|'plugin'}} [opts] picks the dialog title
  * @returns {Promise<{status:'picked', path:string} | {status:'canceled'}
  *   | {status:'unsupported'} | {status:'busy'}>}
  */
-export async function pickFolderNative() {
+export async function pickFolderNative({ purpose } = {}) {
   if (_inFlight) return { status: 'busy' };
   _inFlight = true;
   try {
     const platform = _ov.platform || process.platform;
     const env = _ov.env || process.env;
     const run = _ov.runner || defaultRun;
+    const prompt = promptFor(purpose);
     if ((env.WORCA_NO_NATIVE_DIALOG || '') === '1') return { status: 'unsupported' };
-    if (platform === 'darwin') return await pickMac(run);
-    if (platform === 'win32') return await pickWindows(run);
-    if (platform === 'linux') return await pickLinux(run, env);
+    if (platform === 'darwin') return await pickMac(run, prompt);
+    if (platform === 'win32') return await pickWindows(run, prompt);
+    if (platform === 'linux') return await pickLinux(run, env, prompt);
     return { status: 'unsupported' };
   } finally {
     _inFlight = false;
@@ -101,10 +110,10 @@ function pickedOrCanceled(stdoutRaw) {
   return path ? { status: 'picked', path } : { status: 'canceled' };
 }
 
-async function pickMac(run) {
+async function pickMac(run, prompt) {
   const r = await run('osascript', [
     '-e', 'tell application "System Events" to activate',
-    '-e', `POSIX path of (choose folder with prompt "${PROMPT}")`,
+    '-e', `POSIX path of (choose folder with prompt "${prompt}")`,
   ]);
   if (r.ok) return pickedOrCanceled(r.stdout);
   // `choose folder` cancel: exit 1 + "execution error: User canceled. (-128)"
@@ -112,11 +121,11 @@ async function pickMac(run) {
   return { status: 'unsupported' }; // no GUI session, automation denied, ...
 }
 
-async function pickWindows(run) {
+async function pickWindows(run, prompt) {
   const script =
     'Add-Type -AssemblyName System.Windows.Forms | Out-Null; ' +
     '$d = New-Object System.Windows.Forms.FolderBrowserDialog; ' +
-    `$d.Description = '${PROMPT}'; $d.ShowNewFolderButton = $true; ` +
+    `$d.Description = '${prompt}'; $d.ShowNewFolderButton = $true; ` +
     "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.WriteLine($d.SelectedPath) }";
   const r = await run('powershell.exe', ['-NoProfile', '-STA', '-Command', script]);
   if (!r.ok) return { status: 'unsupported' };
@@ -125,13 +134,13 @@ async function pickWindows(run) {
   return path ? { status: 'picked', path } : { status: 'canceled' };
 }
 
-async function pickLinux(run, env) {
+async function pickLinux(run, env, prompt) {
   if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return { status: 'unsupported' };
-  const zen = await run('zenity', ['--file-selection', '--directory', `--title=${PROMPT}`]);
+  const zen = await run('zenity', ['--file-selection', '--directory', `--title=${prompt}`]);
   if (zen.ok) return pickedOrCanceled(zen.stdout);
   if (zen.code === 1 && !zen.timedOut) return { status: 'canceled' }; // user closed it
   // zenity missing (spawn error -> code -1) or broken: try kdialog.
-  const kd = await run('kdialog', ['--title', PROMPT, '--getexistingdirectory', env.HOME || '/']);
+  const kd = await run('kdialog', ['--title', prompt, '--getexistingdirectory', env.HOME || '/']);
   if (kd.ok) return pickedOrCanceled(kd.stdout);
   if (kd.code === 1 && !kd.timedOut) return { status: 'canceled' };
   return { status: 'unsupported' };

package/src/core/marketplaces.mjs

@@ -122,6 +122,19 @@ async function syncEntry(entry, { exec } = {}) {
 export async function addMarketplace(url, { exec } = {}) {
   const norm = normalizeMarketplaceUrl(url);
   if (!norm) throw Object.assign(new Error('marketplace url is required'), { code: 'BAD_REQUEST' });
+  // A plain PLUGIN folder — a worca-cc-plugin.json, no marketplace manifest, and
+  // NOT a git repository (a git repo whose root is a plugin IS a marketplace:
+  // the fallback scan discovers it at depth 0) — is not a marketplace. It is the
+  // natural thing to paste after `worca workflow export --format plugin`. Say
+  // so, name the fix, and carry the dir so the server route can link it on the
+  // user's behalf (code PLUGIN_FOLDER).
+  if (!/^[a-z+]+:\/\//i.test(norm) && !/^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:/.test(norm)
+    && existsSync(join(norm, 'worca-cc-plugin.json')) && !existsSync(join(norm, 'worca-cc-marketplace.json'))
+    && !existsSync(join(norm, '.git'))) {
+    throw Object.assign(
+      new Error(`${norm} is a single plugin folder, not a marketplace — link it instead: worca plugin link ${norm}`),
+      { code: 'PLUGIN_FOLDER', dir: norm });
+  }
   const id = marketplaceId(norm);
   if (readMarketplaces().marketplaces[id]) { // cheap pre-check: fail before any git work
     throw Object.assign(new Error(`marketplace already added: ${norm}`), { code: 'EXISTS' });

package/src/core/model-env.mjs

@@ -17,6 +17,47 @@
  *  without importing the core graph. */
 export const EFFORTS = ['medium', 'high', 'xhigh', 'max'];
 
+// The effort worca's own auxiliary calls run at (title generation, the Models
+// view Test button). Deliberately BELOW the pipeline list: the CLI accepts
+// `--effort low` (claude --help, 2.1.259) and a one-line summary needs nothing
+// more, so the cheapest tier is the right one. EFFORTS omits it on purpose —
+// pipeline nodes are not offered `low` — which is why it lives here as its own
+// constant instead of being clamped into that list (#422).
+export const AUX_EFFORT = 'low';
+
+// Claude Code resolves its OWN internal calls — session titles, the alias tiers
+// a Task `model: haiku|sonnet|opus|fable` expands to, quota probes — through
+// these keys. A catalog entry that routes to a custom endpoint (ANTHROPIC_BASE_URL)
+// routinely sets ANTHROPIC_MODEL and nothing else, so the CLI falls back to
+// first-party ids against an endpoint that does not serve them (the
+// `unrecognized_model` noise in run logs). withTierModelEnv fills every one the
+// entry left unset with the entry's own wire id (#422). ANTHROPIC_SMALL_FAST_MODEL
+// is the pre-DEFAULT_HAIKU spelling older CLIs still read.
+export const TIER_MODEL_ENV_KEYS = Object.freeze([
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL',
+  'ANTHROPIC_SMALL_FAST_MODEL',
+]);
+
+/**
+ * The tier keys an endpoint-routed model env should carry, synthesized from
+ * the env's wire id. Pure: a non-routed env (no ANTHROPIC_BASE_URL) comes back
+ * untouched, an explicit key in the env is never overwritten, and with no wire
+ * id to point at (no ANTHROPIC_MODEL and no model id) nothing is added.
+ * @param {Record<string,string>|undefined} env  a PREPARED model env
+ * @param {string} [modelId]  the catalog id — the wire id when ANTHROPIC_MODEL is unset (#374)
+ * @returns {Record<string,string>|undefined}
+ */
+export function withTierModelEnv(env, modelId) {
+  if (!env || typeof env !== 'object' || !('ANTHROPIC_BASE_URL' in env)) return env;
+  const wire = (typeof env.ANTHROPIC_MODEL === 'string' && env.ANTHROPIC_MODEL.trim())
+    || (typeof modelId === 'string' ? modelId.trim() : '');
+  if (!wire) return env;
+  const out = { ...env };
+  for (const k of TIER_MODEL_ENV_KEYS) if (!(k in out)) out[k] = wire;
+  return out;
+}
+
 // Env keys a model entry may NOT set (§4.4): process fundamentals and worca's
 // own runtime knobs, any of which injection could otherwise subvert (mock
 // mode, the claude binary path, the effort flag name). Everything else —

package/src/core/model-test.mjs

@@ -7,6 +7,7 @@
 
 import { runClaude } from './claude-runner.mjs';
 import { resolveModelEnv } from './config.mjs';
+import { AUX_EFFORT } from './model-env.mjs';
 import { classifyError } from './recoverable-error.mjs';
 
 const TEST_TIMEOUT_MS = 60_000;
@@ -52,7 +53,7 @@ export async function testModel(id, { signal, bin, run = runClaude } = {}) {
       prompt: 'Reply with exactly OK.',
       model: id,
       modelEnv: resolveModelEnv(id),
-      effort: 'low',
+      effort: AUX_EFFORT,
       permissionMode: 'acceptEdits',
       allowedTools: [],          // empty → no --allowedTools flag; pure text gen
       signal: ctrl.signal,

package/src/core/plugin-manifest.mjs

@@ -5,6 +5,7 @@
 
 import { readFileSync, readdirSync, readlinkSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, sep, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { WORCA_PLUGIN_API, WORCA_PLUGIN_APIS } from './plugin-api.mjs';
 import { EFFORTS, isReservedModelEnvKey, assertModelCost } from './model-env.mjs';
 import { validateMetaV2, normalizeAgentMeta, indexByKey } from '../shared/graph/agent-meta.mjs';
@@ -19,7 +20,37 @@ const KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const SOURCE_ID_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const FIELD_TYPES = new Set(['text', 'select']);
 const INPUT_TYPES = new Set(['text', 'select', 'remote-select', 'task-browser']);
-const KNOWN_TOP = new Set(['name', 'version', 'description', 'author', 'homepage', 'license', 'engines', 'taskSources', 'chatChannels', 'setup', 'models', 'modelSecrets']);
+// `worca` is a free-form tool-metadata block (the workflow exporter records
+// `worca.exports` there — issue #421); the loader never reads it.
+const KNOWN_TOP = new Set(['name', 'version', 'description', 'author', 'homepage', 'license', 'engines', 'taskSources', 'chatChannels', 'setup', 'models', 'modelSecrets', 'worca']);
+
+/** The built-in agent layer (repo agents/). Same URL math as agent-registry's
+ *  DEFAULT_AGENTS_DIR, duplicated because agent-registry imports THIS module
+ *  (declaredApi) and a back-import would be a cycle. */
+const BUILTIN_AGENTS_DIR = fileURLToPath(new URL('../../agents/', import.meta.url));
+
+/**
+ * Normalized meta v2 sidecars of the built-in layer, for the plugin-template
+ * isolation rule (#421): a template may reference built-ins (immutable, always
+ * present on every host) plus the plugin's own agents — never the user layer
+ * or another plugin. A sidecar that fails the v2 gate is skipped: it ships no
+ * ports, so a template naming it gets the same V4 the runtime would raise.
+ * @param {string} [dir]
+ * @returns {object[]}
+ */
+export function builtinAgentMetas(dir = BUILTIN_AGENTS_DIR) {
+  const out = [];
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => f.endsWith('.meta.json')); } catch { return out; }
+  for (const f of files.sort()) {
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(dir, f), 'utf8')); } catch { continue; }
+    if (Number(meta?.metaVersion) !== 2 || !KEY_RE.test(String(meta.key || ''))) continue;
+    if (validateMetaV2(meta).errors.length) continue;
+    out.push(normalizeAgentMeta(meta).meta);
+  }
+  return out;
+}
 const KNOWN_SOURCE = new Set(['id', 'displayName', 'module', 'configSchema', 'inputs', 'multiProfile']);
 const KNOWN_CHANNEL = new Set(['id', 'displayName', 'platform', 'module', 'ingress', 'capabilities', 'configSchema']);
 const CHANNEL_INGRESS = new Set(['connect', 'webhook']);
@@ -497,7 +528,7 @@ export function findEscapingSymlinks(root) {
  * strict: unknown-field warnings become errors.
  * @returns {{ok:boolean, manifest:object|null, problems:Array<{level:'error'|'warn', message:string}>}}
  */
-export function validatePluginDir(absDir, { strict = false } = {}) {
+export function validatePluginDir(absDir, { strict = false, builtinMetas } = {}) {
   const problems = [];
   const push = (level, message) => problems.push({ level, message });
 
@@ -592,12 +623,18 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
 
   // workflows/*.json are v2 GRAPHS (API 3), validated by the SAME shared
   // validator the composer and POST /api/workflows use, over a ports function
-  // built from this plugin's OWN sidecars plus the engine's flow-card ports.
-  // The isolation rule stays: a template may reference only keys this plugin
-  // ships, so a host rename or a deleted user agent can never break it.
+  // built from the BUILT-IN sidecars plus this plugin's OWN, plus the engine's
+  // flow-card ports. The isolation rule (#421): a template may reference
+  // built-ins (immutable, present on every host) and keys this plugin ships —
+  // never the user layer or another plugin — so a host rename or a deleted
+  // user agent can never break it. The plugin's own sidecar wins the index on
+  // a key it shares with a built-in (the registry drops such a plugin agent at
+  // load; the template still validates against the ports it will run with).
   const wfDir = join(absDir, 'workflows');
   if (existsSync(wfDir)) {
-    const portsFn = portsFnFor(indexByKey(ownMetas));
+    const hostMetas = Array.isArray(builtinMetas) ? builtinMetas : builtinAgentMetas();
+    const hostKeys = new Set(hostMetas.map((m) => m.key));
+    const portsFn = portsFnFor(indexByKey([...hostMetas, ...ownMetas]));
     for (const f of readdirSync(wfDir).filter((x) => x.endsWith('.json'))) {
       let tpl = null;
       try { tpl = JSON.parse(readFileSync(join(wfDir, f), 'utf8')); }
@@ -607,14 +644,14 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
       const keys = nodes.filter((n) => n && n.kind === 'agent').map((n) => n.key).filter(Boolean);
       let unresolved = false;
       for (const k of new Set(keys)) {
-        if (agentKeys.has(k)) continue;
+        if (agentKeys.has(k) || hostKeys.has(k)) continue;
         if (ungatedKeys.has(k)) {
           // The sidecar is this plugin's, it just did not pass. Report at the
           // DATA level so an API-1 plugin keeps installing (spec §9) instead of
           // being refused for a template that is fine.
           push(dataLevel, `workflows/${f}: references agent key "${k}" whose sidecar is not a valid meta v2 sidecar`);
         } else {
-          push('error', `workflows/${f}: references agent key "${k}" which this plugin does not ship`);
+          push('error', `workflows/${f}: references agent key "${k}" which is neither a built-in nor shipped by this plugin`);
         }
         unresolved = true;
       }

package/src/core/run-harness.mjs

@@ -3641,6 +3641,13 @@ export class RunHarness extends EventEmitter {
       signal: this.abort.signal,
       bin: this.claude.bin,
       mock: this.claude.mock,
+      // The run's own model is the title default (#422, title.mjs#resolveTitleModel):
+      // an install with no first-party model titles its runs with no setup.
+      runModel: this.claude.model,
+      // A failed title used to vanish into a kept provisional title. Say so in
+      // the run log — once per run, there is only ever one title call.
+      onError: ({ model, error }) => this._log('orchestrator', 'warn',
+        `title generation failed (model ${model}): ${clipMiddle(error?.message || error, 300)} — keeping the provisional title`),
       // Same env policy as the pipeline nodes. Both undefined on an unconfigured
       // project ⇒ byte-identical spawn env (legacy parity).
       envScrub: this.guardrails?.envScrub || undefined,

package/src/core/settings.mjs

@@ -543,8 +543,69 @@ export const SETTINGS_POST_KEYS = Object.freeze([
   'pipelineCostLimitUsd', 'totalCostLimitUsd', 'costLimitResetPeriod',
   'askMaxTurns', 'askMaxBudgetUsd',
   'debugSpawnEnabled',
+  'titleModel', 'hideBuiltinModels',
 ]);
 
+// ── Title-generation model + hidden built-ins (#422) ─────────────────────────
+// `titleModel` is the catalog id every run/chat title is written with; absent
+// means "the model of the run or chat that asked for the title" (title.mjs owns
+// that precedence, and the catalog check — settings.mjs cannot import config.mjs).
+// `hideBuiltinModels` drops the first-party built-ins from every model picker
+// for an install with no first-party account; it is cosmetic + defaults only,
+// a hidden id still resolves (config.mjs#composeCatalog). Both are read at use
+// time like every other stored setting — a UI save reaches the next title call.
+export const DEFAULT_HIDE_BUILTIN_MODELS = false;
+const TITLE_MODEL_MAX_LEN = 200;
+
+const isTitleModelId = (v) => typeof v === 'string' && v.trim().length > 0 && v.length <= TITLE_MODEL_MAX_LEN;
+
+/** The STORED title model id (trimmed), or null when unset/invalid (loudly). */
+export function titleModel() {
+  const v = readSettings().titleModel;
+  if (v === undefined) return null;
+  if (isTitleModelId(v)) return v.trim();
+  console.warn(`[worca] invalid titleModel ${JSON.stringify(v)} — titles use the run's model`);
+  return null;
+}
+
+/** @throws {Error} unless `input` is a non-empty model id (or empty, which clears). */
+export function assertTitleModelInput(input) {
+  if (isClearInput(input)) return;
+  if (!isTitleModelId(input)) throw new Error(`titleModel must be a model id of at most ${TITLE_MODEL_MAX_LEN} characters, or empty to use the run's model`);
+}
+
+export async function setTitleModel(input) {
+  assertTitleModelInput(input);
+  const settings = readSettings();
+  if (isClearInput(input)) delete settings.titleModel;
+  else settings.titleModel = input.trim();
+  await persistSettings(settings);
+  return { titleModel: titleModel() };
+}
+
+/** Whether built-in (first-party) models are hidden from every picker. */
+export function hideBuiltinModels() {
+  const v = readSettings().hideBuiltinModels;
+  if (v === undefined) return DEFAULT_HIDE_BUILTIN_MODELS;
+  if (typeof v === 'boolean') return v;
+  console.warn(`[worca] invalid hideBuiltinModels ${JSON.stringify(v)} — using the default (${DEFAULT_HIDE_BUILTIN_MODELS})`);
+  return DEFAULT_HIDE_BUILTIN_MODELS;
+}
+
+/** @throws {Error} unless `input` is a boolean. */
+export function assertHideBuiltinModelsInput(input) {
+  if (typeof input !== 'boolean') throw new Error('hideBuiltinModels must be true or false');
+}
+
+export async function setHideBuiltinModels(input) {
+  assertHideBuiltinModelsInput(input);
+  const settings = readSettings();
+  if (input === DEFAULT_HIDE_BUILTIN_MODELS) delete settings.hideBuiltinModels;
+  else settings.hideBuiltinModels = input;
+  await persistSettings(settings);
+  return { hideBuiltinModels: hideBuiltinModels() };
+}
+
 // ── Spawn-debug diagnostics toggle (the stored side of WORCA_DEBUG_SPAWN) ────
 // Like every other stored setting (skillMount, the cost caps, the ask caps) this
 // is READ AT USE TIME: claude-runner.mjs#debugSpawnEnabled calls

package/src/core/title.mjs

@@ -1,12 +1,62 @@
 // src/core/title.mjs
 import { runClaude } from './claude-runner.mjs';
-import { resolveModelEnv } from './config.mjs';
+import { resolveModelEnv, catalogHasModel } from './config.mjs';
+import { titleModel as storedTitleModel } from './settings.mjs';
+import { AUX_EFFORT } from './model-env.mjs';
 
-// A fast, cheap model is enough for a one-line summary. Overridable for tests/cost tuning.
-const DEFAULT_TITLE_MODEL =
-  process.env.WORCA_TITLE_MODEL || 'claude-haiku-4-5-20251001';
+// The last-resort title model: the BUILT-IN Haiku id (config.mjs PREDEFINED_MODELS),
+// not the dated API id it used to be — a global entry that shadows the built-in
+// (to route it) must match, or its routing env would never reach a title call.
+export const DEFAULT_TITLE_MODEL = 'claude-haiku-4-5';
 const MAX_LEN = 70;
 
+/**
+ * Which model writes a title, decided PER CALL (#422) — nothing is captured at
+ * import, so a Settings save or an env change reaches the very next title:
+ *   1. `opts.model`            — an explicit caller choice
+ *   2. WORCA_TITLE_MODEL       — a non-empty env override (tests, cost tuning);
+ *                                verbatim, no catalog check: an operator escape hatch
+ *   3. the stored `titleModel` — only while it is still a catalog member; a stale
+ *                                id (plugin removed, entry deleted) is reported and skipped
+ *   4. `opts.runModel`         — the model of the run / chat that asked for the title,
+ *                                which is what makes an install with NO first-party
+ *                                model produce titles with zero configuration
+ *   5. DEFAULT_TITLE_MODEL     — the built-in Haiku
+ * Pure apart from the injectable readers. Exported for tests and for the
+ * settings API (describeTitleModel below).
+ * @param {{model?:string, runModel?:string}} [opts]
+ * @param {{env?:NodeJS.ProcessEnv, stored?:()=>string|null, inCatalog?:(id:string)=>boolean}} [deps]
+ * @returns {{model:string, source:'explicit'|'env'|'settings'|'run'|'builtin', stale:string|null}}
+ */
+export function resolveTitleModel(opts = {}, { env = process.env, stored = storedTitleModel, inCatalog = catalogHasModel } = {}) {
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
+  const explicit = str(opts.model);
+  if (explicit) return { model: explicit, source: 'explicit', stale: null };
+  const fromEnv = str(env.WORCA_TITLE_MODEL);
+  if (fromEnv) return { model: fromEnv, source: 'env', stale: null };
+  let stale = null;
+  const configured = str(stored());
+  if (configured) {
+    if (inCatalog(configured)) return { model: configured, source: 'settings', stale: null };
+    stale = configured;
+  }
+  const runModel = str(opts.runModel);
+  if (runModel) return { model: runModel, source: 'run', stale };
+  return { model: DEFAULT_TITLE_MODEL, source: 'builtin', stale };
+}
+
+/**
+ * What the Settings card shows: the stored id, whether the environment
+ * overrides it, and a stale stored id that no longer resolves. `model` is
+ * null when titles follow the run's model (the default).
+ * @returns {{model:string|null, source:'env'|'settings'|'run', stale:string|null}}
+ */
+export function describeTitleModel(deps) {
+  const r = resolveTitleModel({}, deps);
+  if (r.source === 'env' || r.source === 'settings') return { model: r.model, source: r.source, stale: null };
+  return { model: null, source: 'run', stale: r.stale };
+}
+
 const SYSTEM = [
   'You write a SHORT, human-readable title for a software task.',
   'Rules: 3–8 words, Title Case-ish, no trailing period, no quotes, no markdown,',
@@ -60,24 +110,34 @@ export function isRefusalTitle(t) {
  * failure/abort/empty input so the caller keeps the provisional title.
  * `permissionMode` (default 'acceptEdits') exists for Ask Worca: its title call
  * passes 'dontAsk' so the mock dispatcher can never reach a file-writing role.
+ * `runModel` is the model of the run/chat asking (resolveTitleModel step 4).
+ * `onError` fires ONCE when the call yields no usable title for any reason but
+ * an abort (a spawn failure, a refusal, an empty reply) — the caller logs it on
+ * its own channel; the return value stays '' so every existing caller is unchanged.
  * @param {string} prompt
- * @param {{cwd:string, signal?:AbortSignal, model?:string, bin?:string, mock?:boolean, envScrub?:boolean, envAllowlist?:string[], tools?:string[], strictMcpConfig?:boolean, settingSources?:string[], disableSlashCommands?:boolean, mcpConfigPath?:string, permissionMode?:string}} opts
+ * @param {{cwd:string, signal?:AbortSignal, model?:string, runModel?:string, onError?:(info:{model:string, error:Error})=>void, bin?:string, mock?:boolean, envScrub?:boolean, envAllowlist?:string[], tools?:string[], strictMcpConfig?:boolean, settingSources?:string[], disableSlashCommands?:boolean, mcpConfigPath?:string, permissionMode?:string}} opts
  * @returns {Promise<string>}
  */
 export async function generateTitle(prompt, opts = {}) {
   const text = String(prompt || '').trim();
   if (!text) return '';
+  const { model, stale } = resolveTitleModel(opts);
+  if (stale) console.warn(`[worca] titleModel ${JSON.stringify(stale)} is no longer in the catalog — titles use ${model}`);
+  const report = (error) => {
+    if (typeof opts.onError !== 'function') return;
+    try { opts.onError({ model, error }); } catch { /* a logging sink must never fail the caller */ }
+  };
   try {
     const { text: out } = await runClaude({
       cwd: opts.cwd || process.cwd(),
       systemPrompt: SYSTEM,
       prompt: `Write the title for this task:\n\n${text.slice(0, 4000)}`,
-      model: opts.model || DEFAULT_TITLE_MODEL,
+      model,
       // Aux calls keep their model choice but still route through the catalog's
       // env (design §4.8) — a global entry matching this id carries its routing
       // env everywhere the id is used.
-      modelEnv: resolveModelEnv(opts.model || DEFAULT_TITLE_MODEL),
-      effort: 'low',
+      modelEnv: resolveModelEnv(model),
+      effort: AUX_EFFORT,
       permissionMode: opts.permissionMode || 'acceptEdits',
       allowedTools: [],            // empty → no --allowedTools flag → claude defaults; pure text gen
       signal: opts.signal,
@@ -103,9 +163,12 @@ export async function generateTitle(prompt, opts = {}) {
       onEvent: () => {},
     });
     const title = sanitizeTitle(out);
-    return isRefusalTitle(title) ? '' : title;
+    if (!title) { report(new Error('the model returned an empty reply')); return ''; }
+    if (isRefusalTitle(title)) { report(new Error(`the model did not write a title: ${title.slice(0, 120)}`)); return ''; }
+    return title;
   } catch (err) {
     if (err && err.name === 'AbortError') return ''; // run was stopped — caller keeps provisional
+    report(err instanceof Error ? err : new Error(String(err)));
     return '';
   }
 }