@worca/app 1.3.0 → 1.4.0

package/src/core/policy/effective.mjs

@@ -0,0 +1,175 @@
+// src/core/policy/effective.mjs
+// What applies where (team-policy design §6): fold a policy document and the developer's
+// own settings into the value a run (or a page) will use, field by field. Pure — the
+// snapshot of local settings comes from policy/local.mjs, the document from policy/sync.mjs.
+
+import { FIELDS, effectiveKind, tierRank, semverAtLeast } from './registry.mjs';
+
+/**
+ * The team entries that apply to ONE run kind: `workspaceRuns` replaces `fields` for
+ * workspace runs, key by key, and `hard` reads as soft (registry.effectiveKind).
+ * @returns {Record<string, {kind:string, declaredKind:string, value:*, fromWorkspaceRuns:boolean, onBreach?:string, requireReason?:boolean, window?:string}>}
+ */
+export function fieldsForRun(doc, { workspaceRun = false } = {}) {
+  const out = {};
+  if (!doc) return out;
+  for (const f of FIELDS) {
+    const ws = workspaceRun ? doc.workspaceRuns?.[f.key] : null;
+    const e = ws || doc.fields?.[f.key] || null;
+    if (!e) continue;
+    out[f.key] = { ...e, kind: effectiveKind(f, e.kind), declaredKind: e.kind, fromWorkspaceRuns: !!ws };
+  }
+  return out;
+}
+
+/**
+ * The cap a gate enforces. `local` is the developer's stored cap (null = none); `team` the
+ * entry from fieldsForRun (null = the policy says nothing).
+ *   default: local wins when set, else the team value starts the developer off
+ *   soft:    the tighter of the two; ties go to local (no "team" pause for an equal number)
+ * @returns {{cap:number|null, binding:'local'|'team'|'team-default'|null, team:object|null}}
+ */
+export function effectiveCap({ local = null, team = null } = {}) {
+  if (!team) return { cap: local ?? null, binding: local == null ? null : 'local', team: null };
+  if (team.kind === 'default') {
+    return local != null ? { cap: local, binding: 'local', team } : { cap: team.value, binding: 'team-default', team };
+  }
+  if (local == null || team.value < local) return { cap: team.value, binding: 'team', team };
+  return { cap: local, binding: 'local', team };
+}
+
+/** A default-kind scalar: the developer's stored value wins when SET, else the team's. */
+export function effectiveDefault({ local = null, team = null } = {}) {
+  if (local && local.set) return { value: local.value, source: 'local' };
+  if (team) return { value: team.value, source: 'team-default' };
+  return { value: local ? local.value : null, source: local ? 'default' : 'none' };
+}
+
+const fmtUsd = (n) => `$${Number(n).toFixed(2)}`;
+// Built-in guardrail ids render as their display names everywhere (`secure` shows as "Strict",
+// the guardrail-store.mjs BUILTIN_META rule); a policy set reads "gp:<id>".
+const GUARDRAIL_NAMES = { permissive: 'Permissive', normal: 'Normal', secure: 'Strict' };
+/** A field value as the page shows it ("$25.00", "Strict", "on", "a, b"). */
+export function fmtValue(meta, v) {
+  if (v == null) return '—';
+  if (meta.key === 'guardrails.default' || meta.key === 'guardrails.minimum') return GUARDRAIL_NAMES[v] || String(v);
+  switch (meta.type) {
+    case 'usd': case 'usd-or-null': return fmtUsd(v);
+    case 'bool': return v ? 'on' : 'off';
+    case 'string[]': return v.length ? v.join(', ') : '(none)';
+    case 'plugins': return v.length ? v.map((p) => `${p.name}${p.minVersion ? ` ≥ ${p.minVersion}` : ''}`).join(', ') : '(none)';
+    case 'steps': return Object.entries(v).map(([r, s]) => `${r} ${s.model || '·'}${s.effort ? ` / ${s.effort}` : ''}`).join(' · ') || '(none)';
+    default: return String(v);
+  }
+}
+
+/**
+ * Rows for the effective-policy table (design board 4) and the CLI `policy show`.
+ * `local` is the policy/local.mjs snapshot: { [key]: { value, set } }.
+ * @returns {Array<{key,group,label,help,team:object|null,local:object|null,effective:{value,display,source},note:string|null,shown:boolean}>}
+ */
+export function effectiveRows({ doc = null, workspaceRun = false, local = {} } = {}) {
+  const team = fieldsForRun(doc, { workspaceRun });
+  const rows = [];
+  for (const meta of FIELDS) {
+    const t = team[meta.key] || null;
+    const l = local[meta.key] || null;
+    let effective; let note = null;
+    if (meta.cap) {
+      const r = effectiveCap({ local: l?.set ? l.value : null, team: t });
+      effective = { value: r.cap, display: fmtValue(meta, r.cap), source: r.binding || 'none' };
+      if (r.binding === 'team' && l?.set && l.value > t.value) note = `yours (${fmtUsd(l.value)}) is looser; the team cap applies`;
+      if (r.binding === 'local' && t?.kind === 'soft' && l?.set && l.value <= t.value) note = 'yours is tighter';
+    } else if (meta.advisory) {
+      effective = t ? { value: t.value, display: `${fmtUsd(t.value)} / ${t.window || 'monthly'}`, source: 'advisory' } : { value: null, display: '—', source: 'none' };
+    } else if (t && t.kind === 'soft') {
+      // An expectation: the run proceeds either way, deviations warn and are recorded.
+      effective = { value: t.value, display: fmtValue(meta, t.value), source: 'team' };
+      if (meta.key === 'metrics.record' && l && l.set && l.value === false && t.value === true) note = 'your "Include my runs" is off; the team expects recording';
+    } else {
+      const r = effectiveDefault({ local: l, team: t });
+      effective = { value: r.value, display: fmtValue(meta, r.value), source: r.source };
+    }
+    rows.push({
+      key: meta.key, group: meta.group, label: meta.label, help: meta.help, type: meta.type,
+      team: t ? { ...t, display: fmtValue(meta, t.value) } : null,
+      local: l ? { ...l, display: l.set ? fmtValue(meta, l.value) : '—' } : null,
+      effective, note, shown: !!t,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Off-policy findings for a run (design §8, §10). Codes are what the metrics record stores;
+ * `text` is the run-log / New pipeline line. Nothing here blocks anything.
+ * @param {object} fields  fieldsForRun() result
+ * @param {object} ctx     { guardrailsId, guardrailSet, stepModels:[{role,model}], installed:{name:{version,enabled}},
+ *                           worcaVersion, metricsRecord:boolean|null }
+ * @returns {Array<{code:string, text:string, level:'warn'|'info'}>}
+ */
+export function deviationsFor(fields, ctx = {}) {
+  const out = [];
+  const min = fields['guardrails.minimum'];
+  if (min && ctx.guardrailsId) {
+    const have = ctx.guardrailSet ? tierRank(ctx.guardrailSet) : tierRank(ctx.guardrailsId);
+    const want = tierRank(min.value);
+    if (have != null && want != null && have < want) {
+      const name = (id) => GUARDRAIL_NAMES[id] || id;
+      out.push({ code: `guardrails:${ctx.guardrailsId}<${min.value}`, level: 'warn', text: `Guardrails ${name(ctx.guardrailsId)} rank below the team minimum (${name(min.value)}). The run proceeds and is recorded as off-policy.` });
+    }
+  }
+  const allowed = fields['models.allowed'];
+  if (allowed && Array.isArray(ctx.stepModels)) {
+    const ok = new Set(allowed.value.map((m) => m.toLowerCase()));
+    const seen = new Set();
+    for (const s of ctx.stepModels) {
+      const id = typeof s?.model === 'string' ? s.model.trim() : '';
+      if (!id || seen.has(id.toLowerCase()) || ok.has(id.toLowerCase())) continue;
+      seen.add(id.toLowerCase());
+      out.push({ code: `model:${id}`, level: 'warn', text: `${s.role ? `The ${s.role}'s model ` : 'Model '}${id} is not in the allowed list (${allowed.value.join(', ')}). The run proceeds and is recorded as off-policy.` });
+    }
+  }
+  const required = fields['plugins.required'];
+  if (required && ctx.installed) {
+    for (const p of required.value) {
+      const have = ctx.installed[p.name];
+      if (!have) out.push({ code: `plugin-missing:${p.name}`, level: 'warn', text: `Required plugin ${p.name} is not installed.` });
+      else if (have.enabled === false) out.push({ code: `plugin-disabled:${p.name}`, level: 'warn', text: `Required plugin ${p.name} is disabled.` });
+      else if (p.minVersion && have.version && !semverAtLeast(have.version, p.minVersion)) out.push({ code: `plugin-outdated:${p.name}`, level: 'warn', text: `Required plugin ${p.name} is ${have.version}; the team expects at least ${p.minVersion}.` });
+    }
+  }
+  const blocked = fields['plugins.blocked'];
+  if (blocked && ctx.installed) {
+    for (const name of blocked.value) {
+      const have = ctx.installed[name];
+      if (have && have.enabled !== false) out.push({ code: `plugin-blocked:${name}`, level: 'warn', text: `Plugin ${name} is enabled but blocked by the team policy.` });
+    }
+  }
+  const minVer = fields['worca.minVersion'];
+  if (minVer && ctx.worcaVersion && !semverAtLeast(ctx.worcaVersion, minVer.value)) {
+    out.push({ code: `worca-version:${ctx.worcaVersion}<${minVer.value}`, level: 'warn', text: `Your Worca is ${ctx.worcaVersion}; this policy expects at least ${minVer.value}. Some fields may not apply.` });
+  }
+  const rec = fields['metrics.record'];
+  if (rec && rec.value === true && ctx.metricsRecord === false) {
+    out.push({ code: 'metrics-off', level: 'info', text: 'Your "Include my runs" is off; the team expects runs to be recorded.' });
+  }
+  return out;
+}
+
+/** The three-number summary the Projects cell, the Settings readout and the CLI print. */
+export function capSummary(doc, { workspaceRun = false } = {}) {
+  const f = fieldsForRun(doc, { workspaceRun });
+  const pick = (k) => (f[k] ? { kind: f[k].kind, value: f[k].value, onBreach: f[k].onBreach || 'pause', requireReason: !!f[k].requireReason } : null);
+  return {
+    pipeline: pick('cost.pipelineLimitUsd'),
+    total: pick('cost.totalLimitUsd'),
+    resetPeriod: f['cost.resetPeriod'] ? f['cost.resetPeriod'].value : null,
+    pooled: f['cost.pooledBudgetUsd'] ? { value: f['cost.pooledBudgetUsd'].value, window: f['cost.pooledBudgetUsd'].window || 'monthly' } : null,
+  };
+}
+
+/** How many entries a document sets, for "14 fields" copy. */
+export function fieldCount(doc) {
+  return doc ? Object.keys(doc.fields || {}).length + Object.keys(doc.workspaceRuns || {}).length : 0;
+}

package/src/core/policy/gate.mjs

@@ -0,0 +1,91 @@
+// src/core/policy/gate.mjs
+// The team-cap gates the run ENTRY points share (POST /api/run, POST /api/resume, the CLI):
+// the same fold the harness applies at every step boundary (run-harness._checkCostLimits),
+// evaluated once before a run or resume is created so the caller can answer with a dialog
+// instead of a pause. Soft only (team-policy design §7): a breach is never a refusal when
+// the developer says `pastTeamCap`, when the cap says `onBreach: warn`, or when nobody is
+// there to click (an unattended run).
+
+import { pipelineCostLimitUsd, totalCostLimitUsd, costLimitResetPeriod, readSettings } from '../settings.mjs';
+import { totalWindowSpendUsd, costWindowStart } from '../cost-budget.mjs';
+import { projectKey } from '../store.mjs';
+import { resolveProjectPolicy, resolveWorkspacePolicy } from './sync.mjs';
+import { fieldsForRun, effectiveCap } from './effective.mjs';
+import { readTotalAck, setTotalAck, hasPipelineOverride, writePolicyState, cleanReason } from './state.mjs';
+
+/**
+ * Resolve the policy for a run target and fold its two caps. Never throws; a target with no
+ * policy answers { policy: null }.
+ * @param {{projectDir?:string, workspaceId?:string}} target
+ */
+export async function teamCapsForTarget({ projectDir = null, workspaceId = null } = {}, { discover = 'if-missing' } = {}) {
+  let r = null;
+  try {
+    r = workspaceId ? await resolveWorkspacePolicy(workspaceId, { discover }) : projectDir ? await resolveProjectPolicy(projectDir, { discover }) : null;
+  } catch { r = null; }
+  if (!r || !r.ok) return { policy: null, fields: {}, pipeline: effectiveCap({ local: pipelineCostLimitUsd() }), total: effectiveCap({ local: totalCostLimitUsd() }), period: costLimitResetPeriod() };
+  const fields = fieldsForRun(r.doc, { workspaceRun: !!workspaceId });
+  const stored = readSettings().costLimitResetPeriod;
+  const teamPeriod = fields['cost.resetPeriod']?.value;
+  const period = stored === 'weekly' || stored === 'monthly' ? stored : (teamPeriod === 'weekly' || teamPeriod === 'monthly' ? teamPeriod : costLimitResetPeriod());
+  return {
+    policy: { home: r.home, homeDir: r.homeDir, sha: r.sha, delegated: r.delegated, from: r.from },
+    fields,
+    pipeline: effectiveCap({ local: pipelineCostLimitUsd(), team: fields['cost.pipelineLimitUsd'] || null }),
+    total: effectiveCap({ local: totalCostLimitUsd(), team: fields['cost.totalLimitUsd'] || null }),
+    period,
+  };
+}
+
+const usd = (n) => Number(n).toFixed(2);
+
+/**
+ * The team TOTAL cap at a run entry. `pastTeamCap` records the once-per-window acknowledgement
+ * (design §7) and lets the run through; a cap with `requireReason` refuses an empty reason.
+ * @returns {Promise<{blocked:false, caps:object, ack?:object} | {blocked:true, caps:object, error:string, code:'team_total'|'reason_required', policy:object}>}
+ */
+export async function checkTeamTotalGate(target, { pastTeamCap = false, reason = null, unattended = false, now = new Date() } = {}) {
+  const caps = await teamCapsForTarget(target);
+  const { total, policy, period } = caps;
+  if (!policy || total.binding !== 'team' || total.cap == null) return { blocked: false, caps };
+  const windowStartMs = costWindowStart(now, period).getTime();
+  const spent = totalWindowSpendUsd(windowStartMs);
+  if (spent < total.cap) return { blocked: false, caps };
+  const team = total.team;
+  const ackKey = projectKey(policy.homeDir);
+  const w = period === 'weekly' ? 'week' : 'month';
+  const detail = { home: policy.home, cap: total.cap, spent, period, window: w, windowStartMs, requireReason: !!team.requireReason, onBreach: team.onBreach || 'pause' };
+  if (readTotalAck(ackKey, policy.home, windowStartMs)) return { blocked: false, caps, acked: true };
+  if ((team.onBreach || 'pause') === 'warn' || unattended) return { blocked: false, caps, warned: true };
+  if (pastTeamCap) {
+    const clean = cleanReason(reason);
+    if (team.requireReason && !clean) return { blocked: true, caps, code: 'reason_required', error: `the team policy on ${policy.home} requires a reason to continue past its total cap`, policy: detail };
+    const ack = setTotalAck(ackKey, policy.home, windowStartMs, { reason: clean });
+    return { blocked: false, caps, ack };
+  }
+  return { blocked: true, caps, code: 'team_total', error: `team total cap reached ($${usd(spent)} >= $${usd(total.cap)} this ${w}, ${policy.home})`, policy: detail };
+}
+
+/**
+ * The team PIPELINE cap at a resume. `pastTeamCap` arms the per-pipeline override (persisted on
+ * the run, design §7) and lets the resume through.
+ * @returns {{blocked:false} | {blocked:true, error:string, code:'team_pipeline'|'reason_required', policy:object}}
+ */
+export function checkTeamPipelineGate(caps, { pipelineId, spentSoFar = 0, pastTeamCap = false, reason = null, unattended = false } = {}) {
+  const { pipeline, policy } = caps;
+  // The team SOFT cap is checked whether or not it is the tighter number (the local override
+  // never bypasses it — run-harness._checkCostLimits applies the same rule at every boundary).
+  const team = pipeline?.team && pipeline.team.kind === 'soft' ? pipeline.team : null;
+  if (!policy || !team) return { blocked: false };
+  if (spentSoFar < team.value) return { blocked: false };
+  if (hasPipelineOverride(pipelineId)) return { blocked: false, overridden: true };
+  const detail = { home: policy.home, cap: team.value, spent: spentSoFar, requireReason: !!team.requireReason, onBreach: team.onBreach || 'pause' };
+  if ((team.onBreach || 'pause') === 'warn' || unattended) return { blocked: false, warned: true };
+  if (pastTeamCap) {
+    const clean = cleanReason(reason);
+    if (team.requireReason && !clean) return { blocked: true, code: 'reason_required', error: `the team policy on ${policy.home} requires a reason to continue past its cost cap`, policy: detail };
+    writePolicyState(pipelineId, { home: policy.home, sha: policy.sha, overrides: ['pipeline'], ...(clean ? { reason: clean } : {}) });
+    return { blocked: false, overridden: true };
+  }
+  return { blocked: true, code: 'team_pipeline', error: `team cost cap reached ($${usd(spentSoFar)} >= $${usd(team.value)}, ${policy.home})`, policy: detail };
+}

package/src/core/policy/local.mjs

@@ -0,0 +1,145 @@
+// src/core/policy/local.mjs
+// The developer's side of the fold (team-policy design §6): a snapshot of the local settings
+// a policy can govern, the installed-plugin map the deviations need, and the plugin / marketplace
+// requirements the Plugins page and the setup checklist show. Core-only (reads settings.json,
+// project_config, plugins.lock.json, marketplaces.json); nothing here touches git.
+
+import { createRequire } from 'node:module';
+import {
+  readSettings, pipelineCostLimitUsd, totalCostLimitUsd, costLimitResetPeriod, humanRateUsdPerHour, askMaxTurns, askMaxBudgetUsd, hideBuiltinModels,
+} from '../settings.mjs';
+import { readConfigRow, readTeamMetricsPrefs } from '../config.mjs';
+import { projectKey } from '../store.mjs';
+import { readPluginsLock } from '../plugins-lock.mjs';
+import { readMarketplaces, writeMarketplaces, normalizeMarketplaceUrl, marketplaceId, addMarketplace } from '../marketplaces.mjs';
+import { fieldsForRun } from './effective.mjs';
+import { semverAtLeast } from './registry.mjs';
+
+export const WORCA_VERSION = createRequire(import.meta.url)('../../../package.json').version;
+
+const parseJson = (s, fallback) => { try { const v = JSON.parse(s); return v ?? fallback; } catch { return fallback; } };
+
+/**
+ * { [policyKey]: { value, set } } — `set` is whether the DEVELOPER stored a value (the
+ * default-kind rule keys off it), `value` is what Worca applies today (defaults included).
+ * @param {string|null} projectDir  project-level keys are null without one
+ */
+export function localSnapshot(projectDir = null) {
+  const raw = readSettings();
+  const has = (k) => raw[k] !== undefined && raw[k] !== null && raw[k] !== '';
+  const out = {
+    'cost.pipelineLimitUsd': { value: pipelineCostLimitUsd(), set: pipelineCostLimitUsd() != null },
+    'cost.totalLimitUsd': { value: totalCostLimitUsd(), set: totalCostLimitUsd() != null },
+    'cost.resetPeriod': { value: costLimitResetPeriod(), set: has('costLimitResetPeriod') },
+    'cost.humanRateUsd': { value: humanRateUsdPerHour(), set: humanRateUsdPerHour() != null },
+    'ask.maxTurns': { value: askMaxTurns(), set: has('askMaxTurns') },
+    'ask.maxBudgetUsd': { value: askMaxBudgetUsd(), set: raw.askMaxBudgetUsd !== undefined },   // literal null = "no cap", a choice
+    'models.hideBuiltins': { value: hideBuiltinModels(), set: has('hideBuiltinModels') || raw.hideBuiltinModelsChosen === true },
+    'plugins.marketplaces': { value: Object.values(readMarketplaces().marketplaces).map((m) => m.url), set: true },
+    'plugins.required': { value: Object.entries(readPluginsLock()).map(([name, e]) => ({ name, version: e?.version ?? null, enabled: e?.enabled !== false })), set: true },
+  };
+  if (projectDir) {
+    const key = projectKey(projectDir);
+    const row = readConfigRow(key);
+    const active = row && typeof row.active_workflow_id === 'string' ? row.active_workflow_id.trim() : '';
+    out['workflows.default'] = { value: active || null, set: !!active };
+    out['run.humanInLoop'] = { value: !(row && row.human_in_loop === 0), set: !!row && row.human_in_loop === 0 };
+    const steps = row ? parseJson(row.steps, {}) : {};
+    out['models.steps'] = { value: steps && typeof steps === 'object' ? steps : {}, set: !!steps && Object.keys(steps).length > 0 };
+    const tm = readTeamMetricsPrefs(key);
+    out['metrics.record'] = { value: tm ? tm.record !== false : null, set: !!tm && tm.record === false };
+  }
+  return out;
+}
+
+/** { name: { version, enabled } } from plugins.lock.json. */
+export function installedPluginsMap() {
+  const out = {};
+  for (const [name, e] of Object.entries(readPluginsLock())) out[name] = { version: e?.version ?? null, enabled: e?.enabled !== false, via: e?.via ?? null };
+  return out;
+}
+
+/**
+ * The union of `plugins.required` across policy homes, each with its installed state
+ * (Plugins page strip, setup checklist, `worca policy setup`). Two homes → the higher floor.
+ * @param {Array<{slug:string, doc:object}>} homes
+ */
+export function pluginRequirements(homes) {
+  const installed = installedPluginsMap();
+  const byName = new Map();
+  for (const h of homes || []) {
+    const f = fieldsForRun(h.doc);
+    for (const p of f['plugins.required']?.value || []) {
+      const cur = byName.get(p.name) || { name: p.name, marketplace: p.marketplace ?? null, minVersion: null, config: null, homes: [] };
+      if (p.minVersion && (!cur.minVersion || semverAtLeast(p.minVersion, cur.minVersion))) cur.minVersion = p.minVersion;
+      if (p.config && !cur.config) cur.config = p.config;
+      if (!cur.marketplace && p.marketplace) cur.marketplace = p.marketplace;
+      if (!cur.homes.includes(h.slug)) cur.homes.push(h.slug);
+      byName.set(p.name, cur);
+    }
+  }
+  const out = [];
+  for (const req of byName.values()) {
+    const have = installed[req.name] || null;
+    let state = 'ok';
+    if (!have) state = 'missing';
+    else if (have.enabled === false) state = 'disabled';
+    else if (req.minVersion && have.version && !semverAtLeast(have.version, req.minVersion)) state = 'outdated';
+    out.push({ ...req, installed: have, state });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Blocked plugins that are enabled here, per home. */
+export function blockedPluginFindings(homes) {
+  const installed = installedPluginsMap();
+  const out = [];
+  for (const h of homes || []) {
+    for (const name of fieldsForRun(h.doc)['plugins.blocked']?.value || []) {
+      const have = installed[name];
+      if (have && have.enabled !== false) out.push({ name, home: h.slug });
+    }
+  }
+  return out;
+}
+
+/**
+ * Marketplace URLs a policy asks for that this machine has neither added nor deliberately
+ * removed (marketplaces.json `policySeeded` remembers what policy added, design §6).
+ */
+export function marketplaceSeedCandidates(homes) {
+  const state = readMarketplaces();
+  const seeded = new Set(Array.isArray(state.policySeeded) ? state.policySeeded : []);
+  const present = new Set(Object.values(state.marketplaces).map((m) => m.url));
+  const out = new Map();
+  for (const h of homes || []) {
+    for (const raw of fieldsForRun(h.doc)['plugins.marketplaces']?.value || []) {
+      const url = normalizeMarketplaceUrl(raw);
+      if (!url || present.has(url) || seeded.has(url)) continue;
+      const cur = out.get(url) || { url, homes: [] };
+      if (!cur.homes.includes(h.slug)) cur.homes.push(h.slug);
+      out.set(url, cur);
+    }
+  }
+  return [...out.values()];
+}
+
+/**
+ * Add the candidate marketplaces (metadata only: a git archive, no code runs) and remember
+ * each in `policySeeded`, added or not, so a later local removal is never undone. Best-effort:
+ * one unreachable marketplace never blocks the others. `add` is injectable for tests.
+ */
+export async function seedPolicyMarketplaces(homes, { add = addMarketplace } = {}) {
+  const results = [];
+  for (const c of marketplaceSeedCandidates(homes)) {
+    let entry = null; let error = null;
+    try { entry = await add(c.url); }
+    catch (err) { if (err?.code === 'EXISTS') entry = readMarketplaces().marketplaces[marketplaceId(c.url)] || null; else error = String(err?.message || err); }
+    const state = readMarketplaces();
+    const seeded = new Set(Array.isArray(state.policySeeded) ? state.policySeeded : []);
+    seeded.add(c.url);
+    writeMarketplaces({ ...state, policySeeded: [...seeded] });
+    results.push({ url: c.url, homes: c.homes, added: !!entry && !error, error });
+  }
+  return results;
+}