@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/run-manifest.mjs

@@ -108,7 +108,11 @@ export async function rmGuarded(runRoot, { worcaHome, pipelineId } = {}) {
     return { ok: false, removed: false, reason: `refusing to remove ${target}: basename !== pipelineId ${pipelineId}` };
   }
   try {
-    await rm(target, { recursive: true, force: true });
+    // maxRetries: the run root holds git worktree checkouts; on Windows a dir
+    // cannot be removed while git's index/packed-refs handle (or a virus scanner)
+    // is still open, so a single rm EBUSY/EPERMs under load. Node backs off across
+    // attempts (~cumulative seconds); POSIX takes the first try.
+    await rm(target, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
     return { ok: true, removed: true };
   } catch (err) {
     return { ok: false, removed: false, reason: err?.message || String(err) };

package/src/core/settings.mjs

@@ -11,6 +11,12 @@
 //   contextMaxBytesPerFile — §5.4 per-source-file inlining cap.
 //   contextMaxBytesTotal   — §5.4 total memory budget.
 //   skillMount             — §5.6 'copy' (default) | 'symlink' (opt-in).
+//   debugSpawnEnabled      — the stored spawn-diagnostics preference (a UI checkbox).
+//                            claude-runner.mjs reads it fresh on every spawn through
+//                            effectiveDebugSpawn(), so it applies to the UI server AND
+//                            to CLI runs with no restart. A NON-EMPTY WORCA_DEBUG_SPAWN
+//                            in the process environment overrides it (power-user
+//                            override); this module never writes process.env.
 //   pipelineCostLimitUsd   — per-pipeline lifetime USD spend cap; unset = no limit.
 //   totalCostLimitUsd      — windowed all-pipelines USD spend cap; unset = no limit.
 //   costLimitResetPeriod   — total-budget window, 'weekly' | 'monthly' (default).
@@ -42,7 +48,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
-import { EFFORTS, isReservedModelEnvKey } from './model-env.mjs';
+import { EFFORTS, isReservedModelEnvKey, assertModelCost, envFlag } from './model-env.mjs';
 
 /**
  * The real OS home base, honoring HOME/USERPROFILE so tests can sandbox it.
@@ -384,6 +390,74 @@ export function assertCostLimitInputs(inputs = {}) {
   if (has('costLimitResetPeriod')) assertResetPeriodInput(inputs.costLimitResetPeriod);
 }
 
+// ── Ask Worca per-turn limits (ask-worca-design.md §6.9, D12) ────────────────
+// Two keys, both read fresh on every chat turn. `askMaxTurns` is an integer cap
+// on claude's agentic turns (--max-turns); `askMaxBudgetUsd` is the per-turn
+// dollar cap (--max-budget-usd). For the budget key the literal `null` is a
+// STORED value meaning "no cap" (the flag is omitted), while '' / undefined clear
+// the key back to the default — the two semantics the design assigns to that key.
+export const DEFAULT_ASK_MAX_TURNS = 40;
+export const DEFAULT_ASK_MAX_BUDGET_USD = 2;
+
+const isAskMaxTurns = (v) => Number.isSafeInteger(v) && v >= 1 && v <= 500;
+const isAskMaxBudget = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0.1 && v <= 100;
+
+/** --max-turns for one chat turn: integer 1..500; absent/invalid ⇒ the default (loudly). */
+export function askMaxTurns() {
+  const v = readSettings().askMaxTurns;
+  if (v === undefined) return DEFAULT_ASK_MAX_TURNS;
+  if (isAskMaxTurns(v)) return v;
+  console.warn(`[worca] invalid askMaxTurns ${JSON.stringify(v)} — using the default (${DEFAULT_ASK_MAX_TURNS})`);
+  return DEFAULT_ASK_MAX_TURNS;
+}
+
+/** --max-budget-usd for one chat turn: number 0.1..100, or null = no cap; absent/invalid ⇒ the default (loudly). */
+export function askMaxBudgetUsd() {
+  const v = readSettings().askMaxBudgetUsd;
+  if (v === undefined) return DEFAULT_ASK_MAX_BUDGET_USD;
+  if (v === null) return null;
+  if (isAskMaxBudget(v)) return v;
+  console.warn(`[worca] invalid askMaxBudgetUsd ${JSON.stringify(v)} — using the default (${DEFAULT_ASK_MAX_BUDGET_USD})`);
+  return DEFAULT_ASK_MAX_BUDGET_USD;
+}
+
+function assertAskMaxTurnsInput(input) {
+  if (!isClearInput(input) && !isAskMaxTurns(input)) {
+    throw new Error('askMaxTurns must be an integer between 1 and 500');
+  }
+}
+function assertAskMaxBudgetInput(input) {
+  if (input === '' || input === undefined || input === null) return; // clear, or stored no-cap
+  if (!isAskMaxBudget(input)) {
+    throw new Error('askMaxBudgetUsd must be null (no cap) or a number between 0.1 and 100');
+  }
+}
+
+/** Validate the ask keys PRESENT in `inputs` as a set, before any write (assertCostLimitInputs pattern). */
+export function assertAskLimitInputs(inputs = {}) {
+  const has = (k) => Object.prototype.hasOwnProperty.call(inputs, k);
+  if (has('askMaxTurns')) assertAskMaxTurnsInput(inputs.askMaxTurns);
+  if (has('askMaxBudgetUsd')) assertAskMaxBudgetInput(inputs.askMaxBudgetUsd);
+}
+
+export async function setAskMaxTurns(input) {
+  assertAskMaxTurnsInput(input);
+  const settings = readSettings();
+  if (isClearInput(input)) delete settings.askMaxTurns;
+  else settings.askMaxTurns = input;
+  await persistSettings(settings);
+  return { askMaxTurns: askMaxTurns() };
+}
+
+export async function setAskMaxBudgetUsd(input) {
+  assertAskMaxBudgetInput(input);
+  const settings = readSettings();
+  if (input === '' || input === undefined) delete settings.askMaxBudgetUsd;
+  else settings.askMaxBudgetUsd = input;          // a number, or the literal null (no cap)
+  await persistSettings(settings);
+  return { askMaxBudgetUsd: askMaxBudgetUsd() };
+}
+
 /** Write (or clear) a USD cap key. @throws {Error} unless positive finite number (or empty). */
 async function setUsdCap(key, input) {
   assertUsdCapInput(key, input);
@@ -458,6 +532,75 @@ export async function setCostLimitResetPeriod(input) {
   return { costLimitResetPeriod: costLimitResetPeriod() };
 }
 
+// ── The keys POST /api/settings understands ──────────────────────────────────
+// The route keeps a legacy contract: a body naming NONE of these clears root
+// (test/settings-projects-root.test.mjs "a bodyless POST resets root"). Every
+// setter's key is listed HERE, beside the setters, so a new key cannot forget
+// to join a hand-maintained exclusion list in the route and wipe the root on
+// its first save.
+export const SETTINGS_POST_KEYS = Object.freeze([
+  'root', 'projectsRoot', 'chat',
+  'pipelineCostLimitUsd', 'totalCostLimitUsd', 'costLimitResetPeriod',
+  'askMaxTurns', 'askMaxBudgetUsd',
+  'debugSpawnEnabled',
+]);
+
+// ── 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
+// effectiveDebugSpawn() on every spawn, so a UI save reaches the very next spawn
+// in this process and in any CLI process with no restart, and nothing here ever
+// mutates process.env (a runtime env write would leak an explicit
+// WORCA_DEBUG_SPAWN=0 into every inherited child env and break the runner's
+// "OFF ⇒ byte-identical spawn env" invariant).
+export const DEFAULT_DEBUG_SPAWN_ENABLED = false;
+
+const isBool = (v) => typeof v === 'boolean';
+
+/** @throws {Error} unless `input` is a boolean (the route and the setter share this). */
+export function assertDebugSpawnInput(input) {
+  if (!isBool(input)) throw new Error('debugSpawnEnabled must be true or false');
+}
+
+/** STORED spawn-debug preference: boolean, default OFF. Invalid stored value ⇒ OFF (loudly). */
+export function debugSpawnEnabled() {
+  const v = readSettings().debugSpawnEnabled;
+  if (v === undefined) return DEFAULT_DEBUG_SPAWN_ENABLED;
+  if (isBool(v)) return v;
+  console.warn(`[worca] invalid debugSpawnEnabled ${JSON.stringify(v)} — using the default (${DEFAULT_DEBUG_SPAWN_ENABLED})`);
+  return DEFAULT_DEBUG_SPAWN_ENABLED;
+}
+
+/**
+ * What the runner will actually do on the next spawn, and why. ONE precedence
+ * rule, shared by the runner gate and the settings API: a NON-EMPTY
+ * WORCA_DEBUG_SPAWN in the environment wins (parsed with the envFlag rule, so an
+ * exported "0"/"false" is an explicit OFF override), otherwise the stored
+ * preference applies. An empty export (`export WORCA_DEBUG_SPAWN=` in a profile
+ * or a dotenv template) is NOT an override — the runner would read it as OFF
+ * while the UI showed the stored value checked, with nothing explaining why.
+ * @returns {{enabled: boolean, source: 'env'|'settings'}}
+ */
+export function effectiveDebugSpawn() {
+  const v = process.env.WORCA_DEBUG_SPAWN;
+  if (v !== undefined && v !== '') return { enabled: envFlag('WORCA_DEBUG_SPAWN'), source: 'env' };
+  return { enabled: debugSpawnEnabled(), source: 'settings' };
+}
+
+/**
+ * Persist the preference. Nothing else: the runner reads it back per spawn, so
+ * the change is live everywhere without touching this process's environment.
+ * @throws {Error} unless `input` is a boolean.
+ */
+export async function setDebugSpawnEnabled(input) {
+  assertDebugSpawnInput(input);
+  const settings = readSettings();
+  if (input === DEFAULT_DEBUG_SPAWN_ENABLED) delete settings.debugSpawnEnabled;
+  else settings.debugSpawnEnabled = input;
+  await persistSettings(settings);
+  return { debugSpawnEnabled: debugSpawnEnabled() };
+}
+
 // ---------------------------------------------------------------------------
 // Global model catalog (configurable-models-design.md §4.1). Stored entries are
 // MINIMAL — label only when it differs from id, efforts only when a proper
@@ -486,23 +629,42 @@ function sanitizeGlobalModel(raw) {
   const env = {};
   const rawEnv = raw.env && typeof raw.env === 'object' && !Array.isArray(raw.env) ? raw.env : {};
   for (const [k, v] of Object.entries(rawEnv)) {
-    if (isReservedModelEnvKey(k) || typeof v !== 'string' || !v) {
+    // Trim before storing: an ANTHROPIC_MODEL wire id (#374) reaches `--model`
+    // verbatim, so a pasted ' claude-opus-4-8' or whitespace-only value must not
+    // land on disk. Whitespace-only (truthy but empty after trim) is dropped.
+    const t = typeof v === 'string' ? v.trim() : '';
+    if (isReservedModelEnvKey(k) || typeof v !== 'string' || !t) {
       console.warn(`[worca] models entry ${JSON.stringify(id)}: dropping env key ${JSON.stringify(k)} (reserved or not a non-empty string)`);
       continue;
     }
-    env[k] = v;
+    env[k] = t;
   }
+  const cost = sanitizeModelCost(raw.cost, id);
   return {
     id,
     label,
     efforts: efforts.length ? efforts : [...EFFORTS],
     ...(Object.keys(env).length ? { env } : {}),
+    ...(cost ? { cost } : {}),
   };
 }
 
+/** Lenient read-side counterpart of assertModelCost (model-env.mjs): drops an
+ *  invalid `cost` loudly instead of throwing (a corrupt settings.json must never
+ *  break reads). */
+function sanitizeModelCost(raw, id) {
+  if (raw == null) return undefined;
+  try {
+    return assertModelCost(raw);
+  } catch (e) {
+    console.warn(`[worca] models entry ${JSON.stringify(id)}: dropping invalid cost — ${e.message}`);
+    return undefined;
+  }
+}
+
 /**
- * The sanitized global model catalog: [{id, label, efforts, env?}], effective
- * shape (label/efforts always present). Missing/corrupt -> []. Malformed and
+ * The sanitized global model catalog: [{id, label, efforts, env?, cost?}],
+ * effective shape (label/efforts always present). Missing/corrupt -> []. Malformed and
  * case-insensitively duplicate entries are dropped loudly (first wins). Never
  * throws.
  */
@@ -580,12 +742,13 @@ function assertTestSettingsAccess() {
 }
 
 /** The MINIMAL stored shape for validated parts (see section comment). */
-function storedModelShape(id, label, efforts, env) {
+function storedModelShape(id, label, efforts, env, cost) {
   return {
     id,
     ...(label && label !== id ? { label } : {}),
     ...(efforts.length && efforts.length !== EFFORTS.length ? { efforts } : {}),
     ...(Object.keys(env).length ? { env } : {}),
+    ...(cost ? { cost } : {}),
   };
 }
 
@@ -603,21 +766,23 @@ function rawModels(settings) {
 
 /**
  * Add a global catalog entry. `label` defaults to the id; `efforts` must be a
- * subset of EFFORTS (empty/absent = all); `env` keys must not be reserved.
- * @returns {Promise<{id:string,label:string,efforts:string[],env?:object}>} the effective entry
+ * subset of EFFORTS (empty/absent = all); `env` keys must not be reserved;
+ * `cost` is an optional per-model override ({free} | {perMtok}, see assertModelCost).
+ * @returns {Promise<{id:string,label:string,efforts:string[],env?:object,cost?:object}>} the effective entry
  * @throws {Error} on invalid input or a case-insensitively duplicate id
  */
-export async function addGlobalModel({ id, label, efforts, env } = {}) {
+export async function addGlobalModel({ id, label, efforts, env, cost } = {}) {
   assertTestSettingsAccess();
   const vid = assertModelId(id);
   if (!isClearInput(label) && typeof label !== 'string') throw new Error('label must be a string');
   const vefforts = assertEfforts(efforts);
   const venv = assertEnvPairs(env);
+  const vcost = assertModelCost(cost);
   const settings = readSettings();
   const models = rawModels(settings);
   if (findModelIndex(models, vid) !== -1) throw new Error(`a model with id ${JSON.stringify(vid)} already exists`);
   const vlabel = (typeof label === 'string' && label.trim()) || vid;
-  settings.models = [...models, storedModelShape(vid, vlabel, vefforts, venv)];
+  settings.models = [...models, storedModelShape(vid, vlabel, vefforts, venv, vcost)];
   await persistSettings(settings);
   return listGlobalModels().find((m) => m.id.toLowerCase() === vid.toLowerCase());
 }
@@ -626,11 +791,12 @@ export async function addGlobalModel({ id, label, efforts, env } = {}) {
  * Patch a global catalog entry. Omitted fields are kept. `label`: ''/null
  * resets to the id. `efforts`: []/null resets to all. `env`: null clears the
  * whole map; an object merges per key, where a null value DELETES that key and
- * a string sets it (write-only PATCH semantics, design §4.10).
+ * a string sets it (write-only PATCH semantics, design §4.10). `cost`: null/''
+ * removes the override; an object replaces it wholesale.
  * @returns {Promise<object>} the effective entry
  * @throws {Error} on an unknown id or invalid input
  */
-export async function updateGlobalModel(id, { label, efforts, env } = {}) {
+export async function updateGlobalModel(id, { label, efforts, env, cost } = {}) {
   assertTestSettingsAccess();
   const vid = assertModelId(id);
   const settings = readSettings();
@@ -658,8 +824,13 @@ export async function updateGlobalModel(id, { label, efforts, env } = {}) {
     }
   }
 
+  // cost: omitted keeps the current override; null/'' removes it; an object
+  // replaces it wholesale (not a per-key merge — the table is small).
+  let nextCost = current.cost;
+  if (cost !== undefined) nextCost = isClearInput(cost) ? undefined : assertModelCost(cost);
+
   settings.models = models.slice();
-  settings.models[idx] = storedModelShape(current.id, nextLabel, nextEfforts, nextEnv);
+  settings.models[idx] = storedModelShape(current.id, nextLabel, nextEfforts, nextEnv, nextCost);
   await persistSettings(settings);
   return listGlobalModels().find((m) => m.id.toLowerCase() === vid.toLowerCase());
 }

package/src/core/skills.mjs

@@ -105,12 +105,19 @@ export function resolveSkill(name, { repoRoot, projectDir, homeDir = homedir(),
  * `registry` is the plain object returned by loadAgentRegistry (keyed by agent
  * key); `plan.steps` is Array<Array<node>> and each node has `.key`.
  * @param {Record<string, {requiresSkills?: string[]}>} registry
- * @param {{steps?: Array<Array<{key:string}>>}} plan
+ * @param {{steps?: Array<Array<{key:string}>>}|Iterable<string>} planOrKeys  v1 plan, or agent keys
  * @returns {Array<{skill:string, requiredBy:string[]}>}
  */
-export function collectRequiredSkills(registry, plan) {
+export function collectRequiredSkills(registry, planOrKeys) {
+  // Two entry shapes: the v1 ExecutablePlan ({steps:[[{key}]]}) and a plain
+  // iterable of agent keys (what the engine-agnostic run harness has — it never
+  // sees a v1 plan). A plan object is not iterable, so the test is unambiguous.
   const nodeKeys = new Set();
-  for (const group of plan?.steps || []) for (const node of group) nodeKeys.add(node.key);
+  if (planOrKeys && typeof planOrKeys !== 'string' && typeof planOrKeys[Symbol.iterator] === 'function') {
+    for (const key of planOrKeys) nodeKeys.add(key);
+  } else {
+    for (const group of planOrKeys?.steps || []) for (const node of group) nodeKeys.add(node.key);
+  }
   /** @type {Map<string, Set<string>>} */
   const bySkill = new Map();
   for (const key of nodeKeys) {

package/src/core/source-bindings.mjs

@@ -0,0 +1,175 @@
+// src/core/source-bindings.mjs
+// Which PROFILE of a plugin task source a project (or workspace) pulls from.
+//
+// The problem this solves: one worca install drives several projects, and each
+// may belong to a different tracker instance — repo A files tickets in one Jira,
+// repo B in another. Making that a per-run dropdown is how you start a pipeline
+// against the wrong tracker: the mistake is silent (the wrong ticket text simply
+// lands in the prompt) and only visible once the run is underway. So the choice
+// is made ONCE per project and remembered here.
+//
+// Rows are (scope_type, scope_key, plugin, source_id) -> profile. A project that
+// pulls from two different sources binds each independently.
+//
+// Deliberately tolerant on read: an unbound scope, an uninstalled plugin and a
+// profile that was since deleted all collapse to the same answer (null), because
+// every caller's next move is identical — ask the user. But "never bound" and
+// "was bound, then the profile went away" are NOT the same for the single-
+// profile convenience fallback: a scope that once chose a tracker must be ASKED
+// again, never silently re-pointed at whichever profile happens to survive. So
+// deleting a profile TOMBSTONES its bindings (profile = '') instead of dropping
+// the rows; a tombstone reads as unbound everywhere except resolveProfile's
+// 'only' fallback, which it suppresses.
+
+import { getDb, prepare } from './db.mjs';
+
+/** Deleted-profile marker. Reads as "unbound" (getBinding -> null) but records
+ *  that this scope HAD chosen — resolveProfile must ask, not guess. */
+const TOMBSTONE = '';
+
+/** The two scopes a binding can hang off. */
+const SCOPES = new Set(['project', 'workspace']);
+
+function checkScope(scopeType) {
+  if (!SCOPES.has(scopeType)) throw new Error(`invalid binding scope "${scopeType}"`);
+  return scopeType;
+}
+
+const key = (o = {}) => ({
+  scopeType: checkScope(o.scopeType),
+  scopeKey: String(o.scopeKey || ''),
+  plugin: String(o.plugin || ''),
+  sourceId: String(o.sourceId || ''),
+});
+
+/** Raw row value: null (no row) | '' (tombstone) | profile id. Internal —
+ *  resolveProfile needs the three-way answer; everyone else wants getBinding. */
+function rawBinding(ref) {
+  const k = key(ref);
+  if (!k.scopeKey || !k.plugin || !k.sourceId) return null;
+  getDb();
+  const row = prepare(
+    'SELECT profile FROM source_bindings WHERE scope_type = ? AND scope_key = ? AND plugin = ? AND source_id = ?'
+  ).get(k.scopeType, k.scopeKey, k.plugin, k.sourceId);
+  return row ? String(row.profile) : null;
+}
+
+/**
+ * The profile explicitly bound to this scope, or null (a tombstoned binding
+ * reads as unbound). No fallback logic — use resolveProfile() for that.
+ * @returns {string|null}
+ */
+export function getBinding(ref) {
+  const p = rawBinding(ref);
+  return p === TOMBSTONE ? null : p;
+}
+
+/** Bind (or re-bind) a scope to a profile. Returns the stored profile. */
+export function setBinding(ref, profile) {
+  const k = key(ref);
+  const p = String(profile || '').trim();
+  if (!k.scopeKey || !k.plugin || !k.sourceId) throw new Error('binding needs scopeKey, plugin and sourceId');
+  if (!p) throw new Error('binding needs a profile');
+  getDb();
+  prepare(`
+    INSERT INTO source_bindings (scope_type, scope_key, plugin, source_id, profile, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT (scope_type, scope_key, plugin, source_id)
+    DO UPDATE SET profile = excluded.profile, updated_at = excluded.updated_at
+  `).run(k.scopeType, k.scopeKey, k.plugin, k.sourceId, p, new Date().toISOString());
+  return p;
+}
+
+/** Remove a binding. Silent when there was none. */
+export function clearBinding(ref) {
+  const k = key(ref);
+  getDb();
+  prepare(
+    'DELETE FROM source_bindings WHERE scope_type = ? AND scope_key = ? AND plugin = ? AND source_id = ?'
+  ).run(k.scopeType, k.scopeKey, k.plugin, k.sourceId);
+  return { ok: true };
+}
+
+/** Every LIVE binding for one scope: [{ plugin, sourceId, profile }].
+ *  Tombstones are bookkeeping for resolveProfile, not bindings — excluded. */
+export function listBindingsForScope(scopeType, scopeKey) {
+  getDb();
+  return prepare(
+    "SELECT plugin, source_id, profile FROM source_bindings WHERE scope_type = ? AND scope_key = ? AND profile != '' ORDER BY plugin, source_id"
+  ).all(checkScope(scopeType), String(scopeKey || ''))
+    .map((r) => ({ plugin: r.plugin, sourceId: r.source_id, profile: r.profile }));
+}
+
+/** Tombstone every binding naming a profile — called when that profile is
+ *  deleted, so a project never points at a profile that is gone, and never
+ *  silently re-points at a survivor either (the tombstone suppresses the
+ *  single-profile fallback until the user chooses again). Plugin-wide (no
+ *  sourceId): profiles and their buckets are per-PLUGIN, so deleting one
+ *  dangles every source's binding to it, not just the source the delete came
+ *  in through. Returns the row count. */
+export function clearBindingsForProfile(plugin, profile) {
+  getDb();
+  const p = String(profile || '');
+  if (!p) return 0; // '' is the tombstone itself, never a deletable profile
+  const r = prepare(
+    'UPDATE source_bindings SET profile = ?, updated_at = ? WHERE plugin = ? AND profile = ?'
+  ).run(TOMBSTONE, new Date().toISOString(), String(plugin || ''), p);
+  return Number(r?.changes ?? 0);
+}
+
+/** Drop every binding for a plugin — called on uninstall. */
+export function clearBindingsForPlugin(plugin) {
+  getDb();
+  prepare('DELETE FROM source_bindings WHERE plugin = ?').run(String(plugin || ''));
+  return { ok: true };
+}
+
+/**
+ * The profile a run should use, with the fallbacks that make the common case
+ * invisible:
+ *
+ *   1. an explicit binding on this scope wins;
+ *   2. for a WORKSPACE with no binding of its own, the member projects' bindings
+ *      decide — but only if they AGREE. Members split across two trackers is a
+ *      real ambiguity, and guessing one would be the silent-wrong-tracker bug
+ *      this module exists to prevent, so it stays unresolved;
+ *   3. a source with exactly one profile needs no ceremony — use it, UNLESS
+ *      this scope once chose a profile that has since gone away (a tombstoned
+ *      or stale binding): its next run against a tracker it never picked is
+ *      the exact silent-wrong-tracker bug again, so it degrades to "ask";
+ *   4. otherwise null: the caller must ask.
+ *
+ * `available` is the source's profile id list (plugin-config#listProfiles). A
+ * binding naming a profile that is no longer in it is treated as absent, so
+ * deleting a profile degrades to "ask" rather than to a broken run.
+ *
+ * @param {{scopeType:string, scopeKey:string, plugin:string, sourceId:string,
+ *          memberKeys?:string[], available?:string[]}} ref
+ * @returns {{profile:string|null, via:'binding'|'members'|'only'|'none'|'conflict',
+ *           candidates?:string[]}}
+ */
+export function resolveProfile(ref = {}) {
+  const available = Array.isArray(ref.available) ? ref.available.map(String) : null;
+  const known = (p) => !!p && (!available || available.includes(p));
+
+  const own = rawBinding(ref);
+  if (known(own)) return { profile: own, via: 'binding' };
+  // A row that no longer names a live profile — tombstoned by a delete, or
+  // stale (its profile left the roster while we weren't looking) — means this
+  // scope HAD chosen. It must choose again; no fallback may choose for it.
+  let hadBinding = own !== null;
+
+  if (ref.scopeType === 'workspace' && Array.isArray(ref.memberKeys) && ref.memberKeys.length) {
+    const found = new Set();
+    for (const k of ref.memberKeys) {
+      const p = rawBinding({ scopeType: 'project', scopeKey: k, plugin: ref.plugin, sourceId: ref.sourceId });
+      if (known(p)) found.add(p);
+      else if (p !== null) hadBinding = true; // a member's lapsed choice suppresses the fallback too
+    }
+    if (found.size === 1) return { profile: [...found][0], via: 'members' };
+    if (found.size > 1) return { profile: null, via: 'conflict', candidates: [...found] };
+  }
+
+  if (!hadBinding && available && available.length === 1) return { profile: available[0], via: 'only' };
+  return { profile: null, via: 'none' };
+}