@ran-sh/dsh-crew 2.2.0 → 2.2.2

package/src/dsh-cli-runtime.mjs

@@ -35,7 +35,7 @@ import {
 // Re-exported so existing importers keep working while the cohort value now
 // lives in exactly one place (src/dsh-cohort.mjs).
 export { DSH_CLI_PACKAGE, TARGET_DSH_VERSION, TARGET_DSH_SPEC };
-export const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
+const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
 const CREW_PROFILE_DEFAULT_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'];
 const PROFILE_PATCH_TEMPLATE = '[]\n';
 const PROFILE_PNPM_WORKSPACE = 'packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n';
@@ -73,11 +73,6 @@ export function crewDshRuntimeVersionDir({ home = homedir(), version = TARGET_DS
   return join(crewDshHome({ home }), `runtime-${version}`);
 }
 
-export function crewDshRuntimeEntry({ home = homedir(), platform = process.platform } = {}) {
-  const suffix = platform === 'win32' ? '.cmd' : '';
-  return join(crewDshRuntimeRoot({ home }), 'node_modules', '.bin', `dsh${suffix}`);
-}
-
 export function crewDshRuntimeModule({ home = homedir() } = {}) {
   return join(crewDshRuntimeRoot({ home }), 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
 }
@@ -225,14 +220,29 @@ export function ensureCrewDshRuntime({
   platform = process.platform,
   comspec = process.env.ComSpec ?? 'cmd.exe',
   env = process.env,
+  read = readFileSync,
+  write = writeFileSync,
+  log = () => {},
 } = {}) {
-  const existing = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false });
+  const existing = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false, read });
   // Reuse only when the installed runtime already matches the requested
   // cohort. A stale cohort (e.g. an online 0.1.1-rc.2 runtime) must never be
   // mistaken for the target, and it must never be upgraded in place under a
   // live hub.
   if (existing?.kind === 'crew-runtime' && existing?.version === version) {
-    return { ok: true, cli: existing, reused: true };
+    // The core matching is not enough: a tree whose family drifted boots that
+    // core against siblings from another cohort and dies on the first import
+    // the newer ones dropped. Report it as the cohort mismatch it is so the
+    // caller runs the staged (re)install instead of handing it to the launcher.
+    const cohort = verifyCrewRuntimeCohort({ root: crewDshRuntimeRoot({ home }), version, read });
+    if (cohort.ok) return { ok: true, cli: existing, reused: true };
+    return {
+      ok: false,
+      code: 'DSH_RUNTIME_COHORT_MISMATCH',
+      error: `Crew runtime family drifted from ${version}: ${describeCohortDrift(cohort.drift)}`,
+      installed: existing.version ?? null,
+      target: version,
+    };
   }
   if (existing?.kind === 'crew-runtime') {
     return {
@@ -256,13 +266,14 @@ export function ensureCrewDshRuntime({
     ? ['add', '--dir', runtimeRoot, '--ignore-scripts', packageSpec]
     : ['install', '--prefix', runtimeRoot, '--no-package-lock', '--ignore-scripts', '--omit=dev', packageSpec];
   const invocation = buildDshInvocation(packageManager, packageArgs, { platform, comspec });
-  const result = runner(invocation.command, invocation.args, {
+  const runInstall = () => runner(invocation.command, invocation.args, {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     shell: invocation.shell,
     env: { ...env },
   });
-  const cli = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false });
+  const result = runInstall();
+  const cli = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false, read });
   if (result.status !== 0 || !cli || cli.kind !== 'crew-runtime') {
     return {
       ok: false,
@@ -283,7 +294,30 @@ export function ensureCrewDshRuntime({
       target: version,
     };
   }
-  return { ok: true, cli, reused: false, version: cli.version, runtimeRoot };
+  // The core is pinned by the install spec, but npm resolves its siblings from
+  // the core's caret ranges: a registry that published a newer prerelease of the
+  // family produces a mixed tree here, so lock and re-verify the family before
+  // this runtime can be reported reusable.
+  const locked = enforceCohortLock({ root: runtimeRoot, version, runInstall, read, write, log });
+  if (locked.failed) {
+    return {
+      ok: false,
+      code: 'DSH_RUNTIME_INSTALL_FAILED',
+      error: 'Crew-owned DSH runtime install failed',
+      status: locked.failed.status ?? -1,
+      stderrTail: String(locked.failed.stderr || locked.failed.stdout || '').trim().split(/\r?\n/).slice(-3).join(' | ').slice(0, 300),
+    };
+  }
+  if (!locked.ok) {
+    return {
+      ok: false,
+      code: 'DSH_RUNTIME_COHORT_INCONSISTENT',
+      error: `installed Crew runtime family does not match ${version}: ${describeCohortDrift(locked.drift)}`,
+      cohort: { drift: locked.drift },
+      target: version,
+    };
+  }
+  return { ok: true, cli, reused: false, version: cli.version, runtimeRoot, ...(locked.repairs ? { cohortRepaired: true } : {}) };
 }
 
 export function describeDshCli(cli) {
@@ -292,6 +326,104 @@ export function describeDshCli(cli) {
   return `${cli.kind}${version}`;
 }
 
+// ---- installed cohort identity ---------------------------------------------
+// The runtime tree is a COHORT, not a single package: @deepseek-ai/dsh plus the
+// @deepseek-ai/dsh-* family it loads. The install pins the core exactly, but npm
+// still resolves the family from the core's own caret ranges, so a registry that
+// has published a newer prerelease of the family yields a MIXED tree — core
+// alpha.1 with alpha.2 siblings — that installs cleanly and then dies at boot:
+// the alpha.1 core imports exports the alpha.2 siblings no longer provide. Both
+// the reuse gate and the install therefore judge every family member, and a tree
+// that drifted is locked with overrides and reinstalled once before anything is
+// reported reusable.
+
+// A family package may carry its own nested copy of a sibling, and node
+// resolves that copy FIRST for its parent — so a nested copy at the wrong
+// version breaks the parent exactly like a top-level one. npm does produce
+// these (a reconcile against a mixed tree nested whole subtrees), so the walk
+// follows family packages down through their own node_modules and stops before
+// it can descend into unrelated trees.
+const COHORT_NESTED_DEPTH = 3;
+
+function installedCohortEntries(root, read = readFileSync) {
+  const entries = [];
+  const visit = (scope, prefix, depth) => {
+    let names;
+    try { names = readdirSync(scope); } catch { return; }
+    for (const name of names) {
+      if (name !== 'dsh' && !name.startsWith('dsh-')) continue;
+      const dir = join(scope, name);
+      entries.push({ name: `@deepseek-ai/${name}`, version: readPackageVersionAt(dir, read), scope: prefix || 'node_modules' });
+      if (depth >= COHORT_NESTED_DEPTH) continue;
+      const nested = join(dir, 'node_modules', '@deepseek-ai');
+      if (existsSync(nested)) visit(nested, `${prefix ? `${prefix}/` : ''}${name}/node_modules`, depth + 1);
+    }
+  };
+  visit(join(root, 'node_modules', '@deepseek-ai'), '', 0);
+  return entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+}
+
+/**
+ * Judge every installed copy of the family against the pinned cohort version.
+ * `drift` names each copy whose on-disk version differs (an unreadable manifest
+ * reads as null), so callers can report the exact packages instead of a bare
+ * mismatch.
+ */
+export function verifyCrewRuntimeCohort({ root, version, read = readFileSync } = {}) {
+  const entries = installedCohortEntries(root, read);
+  const drift = entries.filter((entry) => entry.version !== version);
+  return { ok: entries.length > 0 && drift.length === 0, entries, drift };
+}
+
+function describeCohortDrift(drift) {
+  return drift
+    .map((entry) => (entry.scope && entry.scope !== 'node_modules'
+      ? `${entry.name}@${entry.version ?? 'missing'} (nested in ${entry.scope})`
+      : `${entry.name}@${entry.version ?? 'missing'}`))
+    .join(', ');
+}
+
+// Lock the whole family to the cohort version. npm v11 rejects an override that
+// shares a name with a direct dependency unless the spec repeats it verbatim, so
+// the core keeps its own exact dependency entry and is left out of `overrides`;
+// pnpm reads overrides from its own field, so both are written.
+function writeCohortOverrides({ root, version, names, read = readFileSync, write = writeFileSync }) {
+  const overrides = {};
+  for (const name of names) {
+    if (name === DSH_CLI_PACKAGE) continue;
+    overrides[name] = version;
+  }
+  if (Object.keys(overrides).length === 0) return false;
+  const manifestFile = join(root, 'package.json');
+  let manifest = null;
+  try { manifest = JSON.parse(read(manifestFile, 'utf8')); } catch { manifest = null; }
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) manifest = {};
+  const next = {
+    ...manifest,
+    dependencies: { ...(manifest.dependencies ?? {}), [DSH_CLI_PACKAGE]: version },
+    overrides,
+    pnpm: { ...(manifest.pnpm ?? {}), overrides },
+  };
+  write(manifestFile, `${JSON.stringify(next, null, 2)}\n`);
+  return true;
+}
+
+// Prove the freshly installed tree is a coherent cohort. A drifting family is
+// locked with overrides and reinstalled exactly ONCE; a tree that still drifts is
+// reported to the caller, never handed to the launcher as reusable.
+function enforceCohortLock({ root, version, runInstall, read = readFileSync, write = writeFileSync, log = () => {} }) {
+  const observed = verifyCrewRuntimeCohort({ root, version, read });
+  if (observed.ok) return { ok: true, repairs: 0 };
+  if (!writeCohortOverrides({ root, version, names: observed.entries.map((entry) => entry.name), read, write })) {
+    return { ok: false, drift: observed.drift };
+  }
+  log(`  DSH cohort drifted (${describeCohortDrift(observed.drift)}); locking the family with overrides`);
+  const result = runInstall();
+  if (result?.status !== 0) return { ok: false, failed: result };
+  const after = verifyCrewRuntimeCohort({ root, version, read });
+  return after.ok ? { ok: true, repairs: 1 } : { ok: false, drift: after.drift };
+}
+
 // Shared pnpm/npm install of the pinned DSH cohort into a specific root
 // directory. pnpm materializes ABSOLUTE-path .cmd shims and junctions that
 // point at the install root's own .pnpm store, so the tree must be installed
@@ -310,6 +442,9 @@ export function installDshInto({
   platform = process.platform,
   comspec = process.env.ComSpec ?? 'cmd.exe',
   env = process.env,
+  read = readFileSync,
+  write = writeFileSync,
+  log = () => {},
 }) {
   const pnpm = pnpmCommand ?? findCommand('pnpm');
   const npm = npmCommand ?? findCommand('npm');
@@ -322,12 +457,13 @@ export function installDshInto({
     ? ['add', '--dir', root, '--ignore-scripts', packageSpec]
     : ['install', '--prefix', root, '--no-package-lock', '--ignore-scripts', '--omit=dev', packageSpec];
   const invocation = buildDshInvocation(packageManager, packageArgs, { platform, comspec });
-  const result = runner(invocation.command, invocation.args, {
+  const runInstall = () => runner(invocation.command, invocation.args, {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     shell: invocation.shell,
     env: { ...env },
   });
+  const result = runInstall();
   if (result.status !== 0) {
     return {
       ok: false,
@@ -341,7 +477,7 @@ export function installDshInto({
   if (!exists(moduleEntry)) {
     return { ok: false, code: 'DSH_RUNTIME_INSTALL_INCOMPLETE', error: 'runtime entry missing after install' };
   }
-  const installedVersion = packageVersion(moduleEntry);
+  const installedVersion = packageVersion(moduleEntry, read);
   if (installedVersion !== version) {
     return {
       ok: false,
@@ -351,7 +487,26 @@ export function installDshInto({
       target: version,
     };
   }
-  return { ok: true, root, version: installedVersion };
+  const locked = enforceCohortLock({ root, version, runInstall, read, write, log });
+  if (locked.failed) {
+    return {
+      ok: false,
+      code: 'DSH_RUNTIME_INSTALL_FAILED',
+      error: 'Crew runtime install failed',
+      status: locked.failed.status ?? -1,
+      stderrTail: String(locked.failed.stderr || locked.failed.stdout || '').trim().split(/\r?\n/).slice(-3).join(' | ').slice(0, 300),
+    };
+  }
+  if (!locked.ok) {
+    return {
+      ok: false,
+      code: 'DSH_RUNTIME_COHORT_INCONSISTENT',
+      error: `installed Crew runtime family does not match ${version}: ${describeCohortDrift(locked.drift)}`,
+      cohort: { drift: locked.drift },
+      target: version,
+    };
+  }
+  return { ok: true, root, version: installedVersion, ...(locked.repairs ? { cohortRepaired: true } : {}) };
 }
 
 // Staged cohort migration: install the target cohort into a versioned
@@ -736,35 +891,36 @@ export async function restoreRetainedRuntime({
 }
 
 // GC retained runtimes that no release pins. A retained cohort is needed only
-// while some managed release (current or retained) declares it as its exact
-// @deepseek-ai/dsh dependency. Best-effort; never throws.
-export function gcRetainedRuntimes({ home = homedir(), releases = [], log = () => {} } = {}) {
+// while some managed release resolves to it, so the caller passes the resolved
+// cohort versions (see resolveReleaseCohort: manifest pin, then the
+// release-cohort.json sidecar). Best-effort; never throws — a root that is
+// missing, unreadable or not a directory prunes nothing rather than failing
+// the update that just committed.
+export function gcRetainedRuntimes({ home = homedir(), cohorts = [], log = () => {} } = {}) {
   const root = retainedRuntimesRoot({ home });
-  if (!existsSync(root)) return [];
-  const needed = new Set();
-  for (const release of releases) {
-    const spec = payloadDshSpec(release);
-    if (spec && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(spec)) needed.add(spec);
-  }
+  const needed = new Set(cohorts.filter((spec) => typeof spec === 'string' && EXACT_COHORT_RE.test(spec)));
+  let names;
+  try { names = readdirSync(root); } catch { return []; }
   const removed = [];
-  for (const name of readdirSync(root)) {
+  for (const name of names) {
+    if (needed.has(name)) continue;
     const dir = join(root, name);
-    if (!needed.has(name)) {
-      try { rmSync(dir, { recursive: true, force: true }); removed.push(name); } catch { /* best effort */ }
-    }
+    try { rmSync(dir, { recursive: true, force: true }); removed.push(name); } catch { /* best effort */ }
   }
   return removed;
 }
 
+const EXACT_COHORT_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
 // Read the exact @deepseek-ai/dsh pin from a payload manifest (dependencies
 // first, then peerDependencies). Exact pins only: a range or absence yields
 // null so callers fail closed instead of guessing a cohort.
 function payloadDshSpec(manifest) {
   if (!manifest || typeof manifest !== 'object') return null;
   const direct = manifest.dependencies?.['@deepseek-ai/dsh'];
-  if (typeof direct === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(direct)) return direct;
+  if (typeof direct === 'string' && EXACT_COHORT_RE.test(direct)) return direct;
   const peer = manifest.peerDependencies?.['@deepseek-ai/dsh'];
-  if (typeof peer === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(peer)) return peer;
+  if (typeof peer === 'string' && EXACT_COHORT_RE.test(peer)) return peer;
   return null;
 }
 
@@ -964,7 +1120,7 @@ function ensureDirectoryLink(linkPath, targetRoot) {
  * command. The profile manifest and one loader-visible directory link are the
  * only state changed; no dependency resolution or policy bypass is attempted.
  */
-export function ensurePluginRegistration({
+function ensurePluginRegistration({
   profileRoot,
   root,
   name,
@@ -1088,3 +1244,44 @@ export function removeCrewPluginRegistration({ home = homedir(), name, profileRo
   if (linkStat) unlinkSync(linkPath);
   return { ok: true, removed: true };
 }
+
+/**
+ * Idempotently materialize the Crew-owned Harness `web` profile scaffold.
+ *
+ * `ensureCrewDshRuntime` supplies the CLI but nothing else a managed 3210/3080
+ * boot needs: the Windows launcher preflight and the supervisor both require
+ * `<crew DSH_HOME>/profiles/web/package.json`, and a fresh install that never
+ * created it deadlocked (supervisor heartbeat timeout -> pending handoff ->
+ * every later update refused). The scaffold is the same shape the plugin
+ * registration writes for the dsh-crew profile: an existing valid manifest is
+ * left untouched, a missing one is created from CREW_PROFILE_DEFAULT_BUNDLES,
+ * and a corrupt one fails closed instead of being overwritten.
+ */
+export function ensureCrewWebProfile({
+  home = homedir(),
+  profileName = 'web',
+  defaultBundles = CREW_PROFILE_DEFAULT_BUNDLES,
+} = {}) {
+  if (typeof profileName !== 'string' || !/^[A-Za-z0-9._-]+$/u.test(profileName)) {
+    return { ok: false, code: 'INVALID_PROFILE_NAME' };
+  }
+  const profileRoot = join(crewDshHome({ home }), 'profiles', profileName);
+  const profile = readProfileManifestForRegistration(profileRoot, { create: true, defaultBundles });
+  if (profile.ok === false) return { ok: false, code: profile.code, profileRoot };
+  let scaffoldChanged = false;
+  try {
+    scaffoldChanged = ensureProfileScaffold(profileRoot);
+    if (profile.created) {
+      writeFileSync(profile.profileManifest, JSON.stringify(profile.manifest, null, 2) + '\n');
+    }
+  } catch (error) {
+    return { ok: false, code: 'CREW_WEB_PROFILE_SCAFFOLD_FAILED', error: String(error?.message ?? error), profileRoot };
+  }
+  return {
+    ok: true,
+    profileRoot,
+    profileManifest: profile.profileManifest,
+    created: profile.created === true,
+    changed: profile.created === true || scaffoldChanged,
+  };
+}

package/src/extension-contract.mjs

@@ -4,7 +4,7 @@
 
 import { validateModelCallabilityV2 } from './model-callability-contract.mjs';
 
-export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
 
 function row(matrix, id) {
   return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;

package/src/failure-classification.mjs

@@ -3,16 +3,6 @@
 // Classification consumes structured status/codes/outcomes only. It never
 // parses raw exception text, provider responses, credentials, quotas or logs.
 
-export const FAILURE_CATEGORIES = Object.freeze([
-  'none',
-  'policy',
-  'compatibility',
-  'provider',
-  'runtime',
-  'verification',
-  'cancelled',
-]);
-
 export const FAILURE_REASON_CODES = Object.freeze({
   NONE: 'NONE',
   CANCELLED: 'CANCELLED',

package/src/hub/entry.mjs

@@ -68,7 +68,7 @@ export function recordAdaptiveJobOutcome(job, store = getProcessAdaptiveHealthSt
  * a chained promise preserves all legacy completion/waiter behavior and runs
  * this observer only after the Hub's own finalizer populated endedAt/status.
  */
-export function installAdaptiveHealthObserver() {
+function installAdaptiveHealthObserver() {
   if (WorkerRegistry.prototype[ADAPTIVE_OBSERVER_INSTALLED] === true) return false;
   const originalSpawn = WorkerRegistry.prototype.spawn;
   Object.defineProperty(WorkerRegistry.prototype, ADAPTIVE_OBSERVER_INSTALLED, {

package/src/hub/index.mjs

@@ -40,7 +40,7 @@ import { raceWaiters } from '../removable-waiter.mjs';
 import { buildProviderInventory } from '../provider-inventory.mjs';
 import { buildProviderLayerMigrationPlan, executeProviderLayerMigration } from '../provider-layer-migration.mjs';
 import { inspectProviderProfile, readProviderDeclarations, readProviderMaterialization } from '../provider-profile-store.mjs';
-import { inspectProviderSettings, readHarnessDefault, readProviderSettingsDeclarations, readProviderSettingsMaterialization } from '../provider-settings-store.mjs';
+import { hasHarnessDefaultBlock, inspectProviderSettings, readHarnessDefault, readProviderSettingsDeclarations, readProviderSettingsMaterialization } from '../provider-settings-store.mjs';
 import { normalizeProviderLifecycleState } from '../provider-lifecycle-state.mjs';
 import { createProviderHealthStore } from '../provider-health.mjs';
 import { planProviderDelete } from '../provider-lifecycle.mjs';
@@ -119,7 +119,6 @@ export const QUICK_CONFIG_KEYS = Object.freeze([
 const LEGACY_TIER_MODELS = { flash: 'deepseek-v4-flash', pro: 'deepseek-v4-pro' };
 // Local copy (the hub must not import jobs.mjs, which pulls the DSH SDK into
 // the profile realm): a valid dispatch role set.
-const ROLES = { worker: true, reviewer: true };
 const CONFIG_DIR = join(homedir(), '.config', 'dsh-crew');
 const CREDENTIAL_PURGE_STATE_FILE = join(CONFIG_DIR, 'credential-purge-lifecycle.json');
 const RECOVERY_ACTION_PATTERN = /^[a-f0-9]{32}$/u;
@@ -252,6 +251,26 @@ export function hasCompleteProviderDeclarationEvidence(evidence) {
     && Object.values(evidence.sources ?? {}).every((source) => source?.present !== true || !source.code);
 }
 
+/**
+ * Decide what the Harness default authority evidence means. A persisted
+ * `agent-default-model` that disagrees with the live default is a real
+ * inconsistency and fails closed; a live default with nothing persisted is the
+ * normal state of a home whose model comes from configuration (the profile and
+ * base layers) — and the state every settings mutation materializes FROM, so
+ * demanding a persisted copy first deadlocked the very migration that writes one.
+ */
+export function projectHarnessDefaultEvidence({ liveDefault = null, persistedDefault = null, persistedDefaultDeclared = false } = {}) {
+  if (!liveDefault && !persistedDefault) return { ok: true, source: 'none' };
+  if (liveDefault && persistedDefault) {
+    return liveDefault.provider === persistedDefault.provider && liveDefault.model === persistedDefault.model
+      ? { ok: true, source: 'harness-settings' }
+      : { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_MISMATCH' };
+  }
+  return persistedDefaultDeclared
+    ? { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_MISMATCH' }
+    : { ok: true, source: 'harness-config' };
+}
+
 export function hasAvailableProviderLifecycleEvidence(evidence) {
   return evidence?.ok === true;
 }
@@ -341,6 +360,7 @@ async function readProviderInventorySnapshot(hub, ctx, config) {
   } catch { declarationEvidence.ok = false; declarationEvidence.sources.profile = { present: true, code: 'PROVIDER_SOURCE_UNAVAILABLE' }; }
   const settingsFile = join(CONFIG_DIR, 'harness', 'settings.yaml');
   let settingsDefault = null;
+  let persistedDefaultDeclared = false;
   let defaultEvidence = { ok: true, source: 'none' };
   try {
     declarationEvidence.sources.settings = { present: existsSync(settingsFile) };
@@ -353,8 +373,15 @@ async function readProviderInventorySnapshot(hub, ctx, config) {
       }
       else { declarationEvidence.ok = false; declarationEvidence.sources.settings.code = parsed.code; }
       const parsedDefault = readHarnessDefault(source);
-      if (parsedDefault.ok) settingsDefault = parsedDefault;
-      else defaultEvidence = { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_UNAVAILABLE' };
+      if (parsedDefault.ok) {
+        settingsDefault = parsedDefault;
+        persistedDefaultDeclared = true;
+      } else if (hasHarnessDefaultBlock(source)) {
+        // The block exists but cannot be read: fail closed on the mutation
+        // authority rather than treating the layer as absent.
+        defaultEvidence = { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_UNAVAILABLE' };
+        persistedDefaultDeclared = true;
+      }
     }
   } catch {
     declarationEvidence.ok = false;
@@ -364,9 +391,8 @@ async function readProviderInventorySnapshot(hub, ctx, config) {
   const liveDefault = catalog.harness_default && typeof catalog.harness_default.provider === 'string' && typeof catalog.harness_default.model === 'string'
     ? { provider: catalog.harness_default.provider, model: catalog.harness_default.model } : null;
   const persistedDefault = settingsDefault ? { provider: settingsDefault.provider, model: settingsDefault.model } : null;
-  if (liveDefault || persistedDefault) {
-    if (!liveDefault || !persistedDefault) defaultEvidence = { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_MISMATCH' };
-    else if (liveDefault.provider !== persistedDefault.provider || liveDefault.model !== persistedDefault.model) defaultEvidence = { ok: false, code: 'PROVIDER_DEFAULT_AUTHORITY_MISMATCH' };
+  if (defaultEvidence.ok) {
+    defaultEvidence = projectHarnessDefaultEvidence({ liveDefault, persistedDefault, persistedDefaultDeclared });
   }
   // The persisted agent-default-model is the mutation authority. Keep it in
   // the inventory even when the live selection is stale; the evidence gate
@@ -1439,6 +1465,30 @@ export async function apply(ctx) {
       handler: (req, res) => sendJson(res, 200, { ok: true, service: 'dsh-crew-hub' }),
     }));
 
+    // Operator entry into the full control plane. Its session token is minted per
+    // process, and every surface that links here (the desktop app's panel, the
+    // 3080 panel) runs in a different harness process whose connection service
+    // cannot mint one for this port — linking the bare port landed the operator on
+    // "dsh web authentication required". Only the hub itself can sign its own
+    // session, so it redirects; no token is written to a page, a file or a log.
+    // Loopback-only, because the Location carries a session credential.
+    disposers.push(webServer.register({
+      kind: 'exact', path: `${ROUTE_BASE}/control-plane`,
+      handler: (req, res) => {
+        if (!isLoopbackRequest(req)) return sendJson(res, 403, { ok: false, error: 'loopback only' });
+        const runtime = getHubRuntimeIdentity();
+        const base = `http://127.0.0.1:${Number(runtime?.listen_port) > 0 ? runtime.listen_port : 3210}/`;
+        let target = base;
+        try {
+          const connection = webCtx.get?.('connection');
+          const authenticated = connection?.authenticatedUrl?.(base);
+          if (typeof authenticated === 'string' && authenticated.startsWith('http://')) target = authenticated;
+        } catch { /* the bare control plane stays the honest fallback */ }
+        res.writeHead(302, { location: target, 'cache-control': 'no-store' });
+        res.end();
+      },
+    }));
+
     disposers.push(webServer.register({
       kind: 'prefix', path: `${ROUTE_BASE}/jobs`,
       handler: async (req, res) => {

package/src/i18n.mjs

@@ -13,7 +13,5 @@ export function setLang(lang) {
   return LANG;
 }
 
-export function getLang() { return LANG; }
-
 /** Pick the string for the active locale. Both branches are cheap literals. */
 export function tr(zh, en) { return LANG === 'zh' ? zh : en; }

package/src/install/crew-paths.mjs

@@ -9,7 +9,7 @@
 // the check disagreed about what "the installed server" is, and only the
 // installer was right.
 
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
@@ -60,21 +60,26 @@ export function loaderLinkPath({ home = homedir(), name } = {}) {
   return join(crewProfileDir({ home }), 'node_modules', ...name.split('/'));
 }
 
-function sameDirectory(left, right) {
-  try { return realpathSync(left) === realpathSync(right); } catch { return false; }
-}
-
 /**
  * The root the host integrations were installed from.
  *
- * Readiness must judge the integrations against the path they were actually
- * written with. That path is the loader link when it resolves to this release,
- * and the release directory itself otherwise — a machine whose link is missing
- * or points somewhere else is reported against the release, which is exactly
- * the mismatch the operator needs to see.
+ * The integrations embed the loader link path itself, and the link is what the
+ * host loads through: whichever payload it currently resolves to IS the live
+ * one, and an upgrade re-points the link so the same embedded path keeps
+ * resolving to the new release. Readiness therefore judges the integrations
+ * against the link whenever it resolves to a readable payload of this package,
+ * and falls back to the caller's root only when the link is broken or carries
+ * a different package. Gating on whether the link happens to realpath to the
+ * caller's root made the writer (link-rooted) and the validator
+ * (release-rooted) disagree about the same machine, and every clean install
+ * read back as "needs repair".
  */
 export function integrationRoot({ home = homedir(), root, name } = {}) {
   const link = loaderLinkPath({ home, name });
   if (!link || !root || !existsSync(link)) return root;
-  return sameDirectory(link, root) ? link : root;
+  try {
+    const payload = JSON.parse(readFileSync(join(link, 'package.json'), 'utf8'));
+    if (payload?.name === name) return link;
+  } catch { /* broken or foreign link payload */ }
+  return root;
 }

package/src/install/crew-skill.mjs

@@ -42,7 +42,7 @@ export function crewSkillFiles({ home = homedir(), env = process.env } = {}) {
 }
 
 /** The skill template shipped in the payload. */
-export function crewSkillSource({ root }) {
+function crewSkillSource({ root }) {
   return join(root, 'skills', CREW_SKILL_NAME, 'SKILL.md');
 }