@ran-sh/dsh-crew 0.5.6 → 1.0.0

package/src/official-web-bridge.mjs

@@ -1,9 +1,12 @@
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { crewDshHome } from './install/install.mjs';
 import { crewDshRuntimeModule } from './dsh-cli-runtime.mjs';
+import { isLocalHostname, isLoopbackAddress, localRequestCore, originAuthorityMatches } from './local-request-guard.mjs';
+
+export { isLoopbackAddress };
 
 export const CREW_BRIDGE_PREFIX = '/_dsh/dsh-crew';
 export const CREW_BRIDGE_TARGET = 'http://127.0.0.1:3210';
@@ -13,43 +16,19 @@ const HOP_BY_HOP = new Set([
   'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length',
 ]);
 
-export function isLoopbackAddress(address) {
-  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
-}
-
-function isLocalHostname(hostname) {
-  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
-}
-
-export function resolveCrewBridgeTarget(env = process.env) {
-  const raw = env?.DSH_CREW_BRIDGE_TARGET;
-  if (!raw) return CREW_BRIDGE_TARGET;
-  try {
-    const target = new URL(raw);
-    if (target.protocol !== 'http:' || !isLocalHostname(target.hostname.toLowerCase()) || target.pathname !== '/' || target.search || target.hash) return CREW_BRIDGE_TARGET;
-    const port = Number(target.port);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) return CREW_BRIDGE_TARGET;
-    return target.origin;
-  } catch { return CREW_BRIDGE_TARGET; }
-}
+export function resolveCrewBridgeTarget() {
+  // Production bridge routing is an invariant, not an environment setting.
+  // Tests can inject dependencies directly into createCrewSidecarSupervisor.
+  return CREW_BRIDGE_TARGET;
+}
 
 export function isTrustedLocalRequest(req) {
-  if (!isLoopbackAddress(req?.socket?.remoteAddress)) return false;
+  if (!localRequestCore(req)) return false;
   const host = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
   if (!host) return false;
-  let authority;
-  try { authority = new URL(`http://${host}`); } catch { return false; }
-  if (!isLocalHostname(authority.hostname.toLowerCase())) return false;
-  const fetchSite = String(req?.headers?.['sec-fetch-site'] ?? '').toLowerCase();
-  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false;
   const origin = req?.headers?.origin;
-  if (origin !== undefined) {
-    if (typeof origin !== 'string') return false;
-    let parsedOrigin;
-    try { parsedOrigin = new URL(origin); } catch { return false; }
-    if (!isLocalHostname(parsedOrigin.hostname.toLowerCase()) || parsedOrigin.host.toLowerCase() !== host) return false;
-  }
-  return true;
+  if (origin === undefined) return true;
+  return originAuthorityMatches(origin, host);
 }
 
 function safeHeaders(source) {
@@ -86,39 +65,132 @@ async function readBoundedBody(req, limit = MAX_BODY_BYTES) {
   return Buffer.concat(chunks);
 }
 
-async function defaultHealthCheck(fetchImpl = globalThis.fetch, bridgeTarget = CREW_BRIDGE_TARGET) {
-  try {
-    const response = await fetchImpl(`${bridgeTarget}${CREW_BRIDGE_PREFIX}/ping`, {
-      signal: AbortSignal.timeout(1_500),
-      headers: { accept: 'application/json' },
-    });
-    return response.ok;
-  } catch { return false; }
-}
+export async function defaultRuntimeIdentity(fetchImpl = globalThis.fetch, bridgeTarget = CREW_BRIDGE_TARGET) {
+  try {
+    const response = await fetchImpl(`${bridgeTarget}${CREW_BRIDGE_PREFIX}/runtime`, {
+      signal: AbortSignal.timeout(1_500),
+      headers: { accept: 'application/json' },
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    if (!(body?.ok === true
+      && body.execution_plane === 'hub-3210'
+      && body.profile === 'dsh-crew'
+      && Number(body.listen_port) === 3210
+      && typeof body.runtime_id === 'string'
+      && body.runtime_id.trim().length > 0)) return null;
+    return { execution_plane: body.execution_plane, profile: body.profile, listen_port: Number(body.listen_port), runtime_id: body.runtime_id.trim() };
+  } catch { return null; }
+}
+
+export async function defaultHealthCheck(fetchImpl = globalThis.fetch, bridgeTarget = CREW_BRIDGE_TARGET) {
+  return (await defaultRuntimeIdentity(fetchImpl, bridgeTarget)) !== null;
+}
 
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-export function createCrewSidecarSupervisor({
-  home = homedir(),
-  exists = existsSync,
-  bridgeTarget = resolveCrewBridgeTarget(),
-  healthCheck = () => defaultHealthCheck(globalThis.fetch, bridgeTarget),
-  spawnImpl = spawn,
-  wait = delay,
-  maxAttempts = 120,
-  pollInterval = 250,
-} = {}) {
-  let starting = null;
-  let runningChild = null;
+export function createCrewSidecarSupervisor({
+  home = homedir(),
+  exists = existsSync,
+  bridgeTarget = resolveCrewBridgeTarget(),
+  healthCheck = () => defaultHealthCheck(globalThis.fetch, bridgeTarget),
+  spawnImpl = spawn,
+  killImpl = (pid) => process.kill(pid),
+  runtimeIdentity = () => defaultRuntimeIdentity(globalThis.fetch, bridgeTarget),
+  wait = delay,
+  maxAttempts = 120,
+  pollInterval = 250,
+  ownershipFile = join(crewDshHome({ home }), 'supervisor-ownership.json'),
+} = {}) {
+  if (bridgeTarget !== CREW_BRIDGE_TARGET) throw new Error('Crew supervisor is fixed to the isolated 3210 Crew Hub');
+  let starting = null;
+  let restarting = null;
+  let runningChild = null;
   const runtime = crewDshRuntimeModule({ home });
-  const dshHome = crewDshHome({ home });
-  const bridgePort = new URL(bridgeTarget).port;
-
-  async function start() {
-    if (await healthCheck()) return { ok: true, started: false };
-    if (!exists(runtime)) return { ok: false, code: 'CREW_RUNTIME_NOT_INSTALLED' };
-    const childAlive = runningChild && runningChild.killed !== true && runningChild.exitCode == null;
-    if (!childAlive) {
+  const dshHome = crewDshHome({ home });
+  const bridgePort = new URL(bridgeTarget).port;
+
+  function readOwnership() {
+    try {
+      const record = JSON.parse(readFileSync(ownershipFile, 'utf8'));
+      if (record?.schema_version !== 1
+        || !Number.isInteger(record.pid) || record.pid < 1
+        || record.profile !== 'dsh-crew'
+        || record.execution_plane !== 'hub-3210'
+        || Number(record.port) !== Number(bridgePort)) return null;
+      return record;
+    } catch { return null; }
+  }
+
+  function clearOwnership(expectedPid) {
+    try {
+      const current = readOwnership();
+      if (expectedPid !== undefined && current?.pid !== expectedPid) return;
+      rmSync(ownershipFile, { force: true });
+    } catch {}
+  }
+
+  function persistOwnership(pid, identity = null) {
+    if (!Number.isInteger(pid) || pid < 1) return false;
+    try {
+      mkdirSync(dshHome, { recursive: true });
+      const temp = `${ownershipFile}.${process.pid}.${Date.now()}.tmp`;
+      writeFileSync(temp, JSON.stringify({
+        schema_version: 1,
+        pid,
+        profile: 'dsh-crew',
+        execution_plane: 'hub-3210',
+        port: Number(bridgePort),
+        runtime_id: typeof identity?.runtime_id === 'string' ? identity.runtime_id : null,
+      }) + '\n');
+      renameSync(temp, ownershipFile);
+      return true;
+    } catch { return false; }
+  }
+
+  function adoptedChild(pid) {
+    return {
+      pid,
+      killed: false,
+      exitCode: null,
+      kill() {
+        try {
+          killImpl(pid);
+          this.killed = true;
+          this.exitCode = 0;
+          clearOwnership(pid);
+          return true;
+        } catch { return false; }
+      },
+      unref() {},
+    };
+  }
+
+  async function adoptPersistedChild() {
+    if (runningChild && runningChild.killed !== true && runningChild.exitCode == null) return true;
+    const record = readOwnership();
+    if (!record || !(await healthCheck())) {
+      if (record) clearOwnership(record.pid);
+      return false;
+    }
+    const identity = await runtimeIdentity();
+    if (!identity || (record.runtime_id && identity.runtime_id !== record.runtime_id)) {
+      clearOwnership(record.pid);
+      return false;
+    }
+    runningChild = adoptedChild(record.pid);
+    return true;
+  }
+
+  async function start() {
+    const childAlive = runningChild && runningChild.killed !== true && runningChild.exitCode == null;
+    if (await healthCheck()) {
+      if (childAlive) return { ok: true, started: false, owned: true };
+      if (await adoptPersistedChild()) return { ok: true, started: false, adopted: true, owned: true };
+      return { ok: false, code: 'PORT_OWNERSHIP_CONFLICT' };
+    }
+    if (!exists(runtime)) return { ok: false, code: 'CREW_RUNTIME_NOT_INSTALLED' };
+    if (!childAlive) {
       runningChild = spawnImpl(process.execPath, [
         runtime, '--profile', 'dsh-crew', '--host', '127.0.0.1', '--port', bridgePort,
       ], {
@@ -128,24 +200,78 @@ export function createCrewSidecarSupervisor({
         stdio: 'ignore',
         windowsHide: true,
       });
-      const ownedChild = runningChild;
-      ownedChild.once?.('exit', () => { if (runningChild === ownedChild) runningChild = null; });
+      const ownedChild = runningChild;
+      if (Number.isInteger(ownedChild?.pid) && !persistOwnership(ownedChild.pid)) {
+        try { ownedChild.kill?.(); } catch {}
+        runningChild = null;
+        return { ok: false, code: 'SUPERVISOR_OWNERSHIP_PERSIST_FAILED' };
+      }
+      ownedChild.once?.('exit', () => { if (runningChild === ownedChild) runningChild = null; });
       ownedChild.unref?.();
     }
     for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-      if (await healthCheck()) return { ok: true, started: true };
-      await wait(pollInterval);
+      if (await healthCheck()) {
+        if (Number.isInteger(runningChild?.pid)) {
+          const identity = await runtimeIdentity();
+          if (!identity) {
+            try { runningChild?.kill?.(); } catch {}
+            runningChild = null;
+            return { ok: false, code: 'SUPERVISOR_RUNTIME_IDENTITY_UNAVAILABLE' };
+          }
+          if (!persistOwnership(runningChild.pid, identity)) {
+            try { runningChild.kill?.(); } catch {}
+            runningChild = null;
+            return { ok: false, code: 'SUPERVISOR_OWNERSHIP_PERSIST_FAILED' };
+          }
+        }
+        return { ok: true, started: true, owned: true };
+      }
+      await wait(pollInterval);
     }
     return { ok: false, code: 'CREW_BACKEND_START_TIMEOUT' };
-  }
-
-  return {
-    ensure() {
-      if (!starting) starting = start().finally(() => { starting = null; });
-      return starting;
-    },
-  };
-}
+  }
+
+  async function restartOwnedBackend() {
+    let owned = runningChild;
+    let childAlive = owned && owned.killed !== true && owned.exitCode == null;
+    if (!childAlive && await healthCheck()) {
+      if (await adoptPersistedChild()) {
+        owned = runningChild;
+        childAlive = true;
+      } else {
+        return { ok: false, code: 'PORT_OWNERSHIP_CONFLICT' };
+      }
+    }
+    if (!childAlive) {
+      const started = await start();
+      return started.ok ? { ...started, restarted: started.started === true } : started;
+    }
+    if (typeof owned.kill !== 'function' || owned.kill() !== true) {
+      return { ok: false, code: 'CREW_BACKEND_RESTART_UNAVAILABLE' };
+    }
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (!await healthCheck()) break;
+      await wait(pollInterval);
+    }
+    if (await healthCheck()) return { ok: false, code: 'CREW_BACKEND_STOP_TIMEOUT' };
+    const started = await start();
+    return started.ok ? { ...started, restarted: true } : started;
+  }
+
+  return {
+    execution_plane: 'hub-3210',
+    profile: 'dsh-crew',
+    listen_port: Number(bridgePort),
+    ensure() {
+      if (!starting) starting = start().finally(() => { starting = null; });
+      return starting;
+    },
+    restartOwnedBackend() {
+      if (!restarting) restarting = restartOwnedBackend().finally(() => { restarting = null; });
+      return restarting;
+    },
+  };
+}
 
 const processSupervisor = createCrewSidecarSupervisor();
 
@@ -167,18 +293,29 @@ export async function proxyCrewRequest(req, res, {
   try {
     const backend = await ensureBackend();
     if (backend?.ok === false) throw new Error('backend unavailable');
-    const method = String(req.method ?? 'GET').toUpperCase();
-    const bodyBuffer = method === 'GET' || method === 'HEAD' ? null : await readBoundedBody(req);
-    const response = await fetchImpl(`${bridgeTarget}${req.url}`, {
-      method,
-      headers: safeHeaders(req.headers),
+    const method = String(req.method ?? 'GET').toUpperCase();
+    const bodyBuffer = method === 'GET' || method === 'HEAD' ? null : await readBoundedBody(req);
+    const requestHeaders = safeHeaders(req.headers);
+    for (const name of Object.keys(requestHeaders)) {
+      if (name.startsWith('x-dsh-crew-')) delete requestHeaders[name];
+    }
+    requestHeaders['x-dsh-crew-bridge'] = '3080-to-3210';
+    requestHeaders['x-dsh-crew-execution-plane'] = 'hub-3210';
+    requestHeaders['x-dsh-crew-ingress'] = 'official-3080';
+    const response = await fetchImpl(`${bridgeTarget}${req.url}`, {
+      method,
+      headers: requestHeaders,
       body: bodyBuffer === null ? undefined : new Blob([bodyBuffer]),
       signal: AbortSignal.timeout(120_000),
     });
-    const responseBody = Buffer.from(await response.arrayBuffer());
-    const headers = safeHeaders(Object.fromEntries(response.headers.entries()));
-    headers['content-length'] = String(responseBody.length);
-    headers['x-dsh-crew-bridge'] = '3080-to-3210';
+    const responseBody = Buffer.from(await response.arrayBuffer());
+    const headers = safeHeaders(Object.fromEntries(response.headers.entries()));
+    for (const name of Object.keys(headers)) {
+      if (name.startsWith('x-dsh-crew-')) delete headers[name];
+    }
+    headers['content-length'] = String(responseBody.length);
+    headers['x-dsh-crew-bridge'] = '3080-to-3210';
+    headers['x-dsh-crew-ingress'] = 'official-3080';
     res.writeHead(response.status, headers);
     res.end(responseBody);
   } catch (error) {
@@ -187,29 +324,45 @@ export async function proxyCrewRequest(req, res, {
   }
 }
 
-export function registerOfficialWebBridge(ctx, options = {}) {
-  return ctx.inject(['webServer'], (webCtx) => {
-    const disposeStatus = webCtx.webServer.register({
+export function registerOfficialWebBridge(ctx, options = {}) {
+  return ctx.inject(['webServer'], (webCtx) => {
+    const supervisor = options.supervisor ?? processSupervisor;
+    const disposeStatus = webCtx.webServer.register({
       kind: 'exact',
       path: `${CREW_BRIDGE_PREFIX}/bridge-status`,
       handler: (req, res) => {
         if (!isTrustedLocalRequest(req)) return sendJson(res, 403, { ok: false, code: 'LOCAL_SAME_ORIGIN_ONLY' });
-        return sendJson(res, 200, {
-          ok: true,
+        return sendJson(res, 200, {
+          ok: true,
           mode: 'official-3080-isolated-3210',
           surface: 'official-bridge',
           ui_role: 'control-plane',
+          execution_plane: 'hub-3210',
+          listen_port: 3210,
         });
       },
-    });
-    const disposeProxy = webCtx.webServer.register({
+    });
+    const disposeRestart = webCtx.webServer.register({
+      kind: 'exact',
+      path: `${CREW_BRIDGE_PREFIX}/supervisor/restart`,
+      handler: async (req, res) => {
+        if (!isTrustedLocalRequest(req)) return sendJson(res, 403, { ok: false, code: 'LOCAL_SAME_ORIGIN_ONLY' });
+        if (String(req.method ?? 'GET').toUpperCase() !== 'POST') return sendJson(res, 405, { ok: false, code: 'POST_ONLY' });
+        let body;
+        try { body = JSON.parse((await readBoundedBody(req, 8 * 1024)).toString('utf8') || '{}'); } catch { return sendJson(res, 400, { ok: false, code: 'SUPERVISOR_REQUEST_INVALID' }); }
+        if (body?.confirm !== true) return sendJson(res, 400, { ok: false, code: 'SUPERVISOR_RESTART_CONFIRM_REQUIRED' });
+        const result = await supervisor.restartOwnedBackend();
+        return sendJson(res, result?.ok === true ? 200 : 409, { ...result });
+      },
+    });
+    const disposeProxy = webCtx.webServer.register({
       kind: 'prefix',
       path: CREW_BRIDGE_PREFIX,
       handler: (req, res) => proxyCrewRequest(req, res, options),
     });
-    return () => { disposeProxy?.(); disposeStatus?.(); };
-  });
-}
+    return () => { disposeProxy?.(); disposeRestart?.(); disposeStatus?.(); };
+  });
+}
 
 export async function apply(ctx) {
   registerOfficialWebBridge(ctx);

package/src/policy.mjs

@@ -10,15 +10,22 @@ export * from './policy-legacy.mjs';
 import * as legacy from './policy-legacy.mjs';
 import { normalizeAdaptiveRouting } from './adaptive-routing.mjs';
 
-export { normalizeAdaptiveRouting };
-export const CONFIG_SCHEMA_VERSION = 3;
-
-function validObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function hasCanonicalAuthority(raw) {
-  return Number(raw?.config_schema_version) >= CONFIG_SCHEMA_VERSION
+export { normalizeAdaptiveRouting };
+export const CONFIG_SCHEMA_VERSION = 4;
+const MIN_CANONICAL_SCHEMA_VERSION = 3;
+
+function validObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+const EXECUTION_TRANSPORTS = new Set(['hub-3210', 'standalone-legacy']);
+
+function normalizeExecutionTransport(value) {
+  return EXECUTION_TRANSPORTS.has(value) ? value : 'hub-3210';
+}
+
+function hasCanonicalAuthority(raw) {
+  return Number(raw?.config_schema_version) >= MIN_CANONICAL_SCHEMA_VERSION
     && validObject(raw?.worker)
     && validObject(raw?.review)
     && validObject(raw?.execution);
@@ -64,31 +71,39 @@ function normalizeLegacySnapshot(raw, canonical) {
   };
 }
 
-function modelPolicyWithAdaptive(basePolicy, rawPolicy) {
-  return {
-    ...basePolicy,
-    adaptive: normalizeAdaptiveRouting(rawPolicy?.adaptive),
-  };
-}
+function modelPolicyWithAdaptive(basePolicy, rawPolicy) {
+  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive);
+  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
+    ? rawPolicy.ordering
+    : adaptive.enabled ? 'health-aware' : 'manual';
+  return {
+    ...basePolicy,
+    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
+    ordering,
+    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
+  };
+}
 
 function normalizeCanonical(raw) {
   const base = legacy.getCanonical(raw);
   const providerMode = legacy.normalizeWorkerProviderMode(base.worker?.provider_mode);
   const canonical = {
     ...base,
-    execution: {
-      ...base.execution,
+    execution: {
+      ...base.execution,
       // There is one global dispatch permission. `execution.enabled` is a
       // canonical mirror of the top-level switch, never a second authority.
-      enabled: base.subagents_enabled,
-    },
+      enabled: base.subagents_enabled,
+      transport: normalizeExecutionTransport(raw?.execution?.transport ?? base.execution?.transport),
+    },
     worker: {
       ...base.worker,
       provider_mode: providerMode,
       model_policy: modelPolicyWithAdaptive(base.worker.model_policy, raw?.worker?.model_policy),
     },
-    review: {
-      ...base.review,
+    review: {
+      ...base.review,
+      gate: ['required', 'optional', 'off'].includes(raw?.review?.gate) ? raw.review.gate : 'required',
       // v0.3 still exposes one Worker Provider selector. Until per-role
       // provider modes become first-class, keep both roles aligned.
       provider_mode: providerMode,
@@ -176,16 +191,32 @@ export function normalizeGlobalConfig(raw = {}) {
  * adaptive sub-domain, so direct canonical-ish v0.2 callers retain the exact
  * priority/escalation semantics they had before schema-v3 existed.
  */
-export function resolveModelPolicy(config = {}, role = 'worker', context = {}) {
-  const base = legacy.resolveModelPolicy(config, role, context);
-  const rawPolicy = role === 'reviewer'
-    ? config?.review?.model_policy
-    : config?.worker?.model_policy;
-  return {
-    ...base,
-    adaptive: normalizeAdaptiveRouting(rawPolicy?.adaptive ?? base.adaptive),
-  };
-}
+export function resolveModelPolicy(config = {}, role = 'worker', context = {}) {
+  const base = legacy.resolveModelPolicy(config, role, context);
+  const rawPolicy = role === 'reviewer'
+    ? config?.review?.model_policy
+    : config?.worker?.model_policy;
+  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive ?? base.adaptive);
+  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
+    ? rawPolicy.ordering
+    : adaptive.enabled ? 'health-aware' : 'manual';
+  return {
+    ...base,
+    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
+    ordering,
+    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
+  };
+}
+
+/** Automatic review respects the v4 reviewer gate; session opt-out remains authoritative. */
+export function shouldAutoReview(config = {}, session = {}) {
+  const normalized = normalizeGlobalConfig(config);
+  const gate = ['required', 'optional', 'off'].includes(config?.review?.gate)
+    ? config.review.gate
+    : normalized.review?.gate;
+  if (gate === 'off') return false;
+  return legacy.shouldAutoReview(normalized, session);
+}
 
 /** Explicit legacy-import normalizer for the persistence layer. */
 export function normalizeLegacyGlobalConfig(raw = {}) {

package/src/provider-config-scrub.mjs

@@ -0,0 +1,71 @@
+// Pure policy-reference scrub used by provider deletion transactions.
+// It removes only provider/model references, never credentials or unrelated
+// settings, and keeps explicit `priorityConfigured` semantics intact.
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+function cloneConfig(value) {
+  if (typeof structuredClone === 'function') return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+}
+
+function validId(value) {
+  return typeof value === 'string' && ID_PATTERN.test(value);
+}
+
+function ensureProviderIds(providerIds) {
+  if (!Array.isArray(providerIds)) throw new TypeError('provider ids must be an array');
+  const result = [];
+  const seen = new Set();
+  for (const id of providerIds) {
+    if (!validId(id)) throw new TypeError('provider id must be a bounded identifier');
+    if (seen.has(id)) continue;
+    seen.add(id);
+    result.push(id);
+  }
+  if (result.length === 0) throw new TypeError('provider ids must not be empty');
+  return result;
+}
+
+function scrubList(list, blocked, removed) {
+  if (!Array.isArray(list)) return list;
+  return list.filter((entry) => {
+    const provider = entry && typeof entry === 'object' ? entry.provider : null;
+    if (!blocked.has(provider)) return true;
+    if (!removed.includes(provider)) removed.push(provider);
+    return false;
+  });
+}
+
+function scrubPolicy(policy, blocked, removed) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) return;
+  for (const key of ['priority', 'escalation_priority']) {
+    if (Array.isArray(policy[key])) policy[key] = scrubList(policy[key], blocked, removed);
+  }
+}
+
+function scrubDefault(config, key, blocked, removed) {
+  const value = config[key];
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+  if (!blocked.has(value.provider)) return;
+  if (!removed.includes(value.provider)) removed.push(value.provider);
+  config[key] = null;
+}
+
+/** Remove references to provider ids from all known canonical/legacy policy mirrors. */
+export function scrubProviderReferences(config, providerIds) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new TypeError('config must be an object');
+  const ids = ensureProviderIds(providerIds);
+  const blocked = new Set(ids);
+  const next = cloneConfig(config);
+  const removed = [];
+
+  for (const key of ['flash_model_priority', 'pro_model_priority']) {
+    if (Array.isArray(next[key])) next[key] = scrubList(next[key], blocked, removed);
+  }
+  scrubPolicy(next.worker?.model_policy, blocked, removed);
+  scrubPolicy(next.review?.model_policy, blocked, removed);
+  for (const key of ['harness_default', 'agent_default_model', 'agentDefaultModel']) scrubDefault(next, key, blocked, removed);
+
+  return { config: next, removed };
+}