@ran-sh/dsh-crew 0.3.7 → 0.4.0

package/src/dsh-cli-runtime.mjs

@@ -5,27 +5,27 @@
 // compatibility fallbacks. Status and uninstall callers can resolve without
 // allowing a download.
 
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'node:module';
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  realpathSync,
-  symlinkSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { crewDshHome, crewProfileDir } from './install/install.mjs';
 
-export const DSH_CLI_PACKAGE = '@deepseek-ai/dsh';
-export const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
-const CREW_PROFILE_DEFAULT_BUNDLES = ['@deepseek-ai/dsh-base'];
-const PROFILE_PATCH_TEMPLATE = '[]\n';
-const PROFILE_PNPM_WORKSPACE = 'packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n';
+export const DSH_CLI_PACKAGE = '@deepseek-ai/dsh';
+export 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';
 
 function defaultFindCommand(name) {
   const probe = process.platform === 'win32' ? 'where.exe' : 'which';
@@ -236,170 +236,181 @@ export function ensureCrewDshRuntime({
   return { ok: true, cli, reused: false, version: cli.version, runtimeRoot };
 }
 
-export function describeDshCli(cli) {
+export function describeDshCli(cli) {
   if (!cli) return 'unavailable';
   const version = cli.version ? `@${cli.version}` : '';
   return `${cli.kind}${version}`;
-}
-
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function isSafePackageName(name) {
-  return typeof name === 'string'
-    && /^(?:@[^/\s]+\/)?[^/\s]+$/u.test(name)
-    && !name.split('/').some((part) => part === '.' || part === '..');
-}
-
-function isWithin(root, candidate) {
-  const rel = relative(root, candidate);
-  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
-}
-
-function fileSpec(target) {
-  return `link:${target.replace(/\\/g, '/')}`;
-}
-
-function profileLinkPath(profileRoot, name) {
-  return join(profileRoot, 'node_modules', ...name.split('/'));
-}
-
-function readPluginRoot(root, expectedName) {
-  if (typeof root !== 'string' || !isAbsolute(root)) return { ok: false, code: 'INVALID_CREW_PLUGIN_ROOT' };
-  let targetRoot;
-  try { targetRoot = realpathSync(root); } catch { return { ok: false, code: 'CREW_PLUGIN_ROOT_NOT_FOUND' }; }
-  const packageFile = join(targetRoot, 'package.json');
-  let pkg;
-  try { pkg = JSON.parse(readFileSync(packageFile, 'utf8')); } catch { return { ok: false, code: 'CREW_PLUGIN_MANIFEST_INVALID' }; }
-  if (!isObject(pkg) || !isSafePackageName(pkg.name) || (expectedName !== undefined && pkg.name !== expectedName)) {
-    return { ok: false, code: 'CREW_PLUGIN_MANIFEST_INVALID' };
-  }
-  const patchSpec = pkg.dsh?.bundle?.patch;
-  if (typeof patchSpec !== 'string' || !patchSpec.trim()) return { ok: false, code: 'CREW_PLUGIN_BUNDLE_INVALID' };
-  const patchPath = resolve(targetRoot, patchSpec);
-  if (!isWithin(targetRoot, patchPath) || !existsSync(patchPath)) return { ok: false, code: 'CREW_PLUGIN_BUNDLE_INVALID' };
-  return { ok: true, targetRoot, packageFile, packageName: pkg.name, packageVersion: pkg.version ?? null, patchPath, pkg };
-}
-
-function readProfileManifestForRegistration(profileRoot) {
-  const profileManifest = join(profileRoot, 'package.json');
-  if (!existsSync(profileManifest)) {
-    return {
-      profileManifest,
-      manifest: {
-        name: `dsh-profile-${profileRoot.split(/[\\/]/u).at(-1)}`,
-        private: true,
-        dependencies: {},
-        dsh: { profile: { bundles: [...CREW_PROFILE_DEFAULT_BUNDLES] } },
-      },
-      created: true,
-    };
-  }
-  let manifest;
-  try { manifest = JSON.parse(readFileSync(profileManifest, 'utf8')); } catch { return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' }; }
-  if (!isObject(manifest)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  if (manifest.dependencies !== undefined && !isObject(manifest.dependencies)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  if (manifest.dependencies && Object.values(manifest.dependencies).some((value) => typeof value !== 'string')) {
-    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  }
-  if (manifest.dsh !== undefined && !isObject(manifest.dsh)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  if (manifest.dsh?.profile !== undefined && !isObject(manifest.dsh.profile)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  const bundles = manifest.dsh?.profile?.bundles;
-  if (bundles !== undefined && (!Array.isArray(bundles) || bundles.some((name) => !isSafePackageName(name)))) {
-    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  }
-  return { profileManifest, manifest, created: false };
-}
-
-function ensureProfileScaffold(profileRoot) {
-  mkdirSync(profileRoot, { recursive: true });
-  let changed = false;
-  const patchFile = join(profileRoot, 'cordis.patch.yml');
-  if (!existsSync(patchFile)) { writeFileSync(patchFile, PROFILE_PATCH_TEMPLATE); changed = true; }
-  const workspaceFile = join(profileRoot, 'pnpm-workspace.yaml');
-  if (!existsSync(workspaceFile)) { writeFileSync(workspaceFile, PROFILE_PNPM_WORKSPACE); changed = true; }
-  return changed;
-}
-
-function ensureDirectoryLink(linkPath, targetRoot) {
-  let stat;
-  try { stat = lstatSync(linkPath); } catch { stat = null; }
-  if (stat && !stat.isSymbolicLink()) return { ok: false, code: 'CREW_PLUGIN_LINK_CONFLICT' };
-  if (stat) {
-    try {
-      if (realpathSync(linkPath) === targetRoot) return { ok: true, changed: false };
-    } catch {}
-    unlinkSync(linkPath);
-  }
-  mkdirSync(dirname(linkPath), { recursive: true });
-  symlinkSync(targetRoot, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
-  return { ok: true, changed: true };
-}
-
-/**
- * Register a local Crew plugin without invoking DSH's pnpm-forwarding plugin
- * 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 ensureCrewPluginRegistration({ home = homedir(), root, name } = {}) {
-  const plugin = readPluginRoot(root, name);
-  if (!plugin.ok) return plugin;
-  const profileRoot = crewProfileDir({ home });
-  const profile = readProfileManifestForRegistration(profileRoot);
-  if (profile.ok === false) return profile;
-  const scaffoldChanged = ensureProfileScaffold(profileRoot);
-  const current = profile.manifest;
-  const dependencies = { ...(current.dependencies ?? {}) };
-  const currentBundles = current.dsh?.profile?.bundles ?? [...CREW_PROFILE_DEFAULT_BUNDLES];
-  const nextBundles = [];
-  let seen = false;
-  for (const bundle of currentBundles) {
-    if (bundle === plugin.packageName) {
-      if (!seen) { nextBundles.push(bundle); seen = true; }
-    } else nextBundles.push(bundle);
-  }
-  if (!seen) nextBundles.push(plugin.packageName);
-  dependencies[plugin.packageName] = fileSpec(plugin.targetRoot);
-  const next = {
-    ...current,
-    dependencies,
-    dsh: {
-      ...(current.dsh ?? {}),
-      profile: { ...(current.dsh?.profile ?? {}), bundles: nextBundles },
-    },
-  };
-  const manifestChanged = JSON.stringify(current) !== JSON.stringify(next) || profile.created;
-  const linkPath = profileLinkPath(profileRoot, plugin.packageName);
-  let link;
-  try { link = ensureDirectoryLink(linkPath, plugin.targetRoot); } catch { return { ok: false, code: 'CREW_PLUGIN_LINK_FAILED' }; }
-  if (!link.ok) return link;
-  try {
-    if (manifestChanged) writeFileSync(profile.profileManifest, JSON.stringify(next, null, 2) + '\n');
-    // Resolve the intended package entry from the validated checkout. Node's
-    // package-name resolution cache can retain the old target after a stale
-    // junction is replaced in the same process, so loader visibility is proven
-    // by the link target plus a normal package entry resolution from that
-    // target rather than by trusting a cached package-name lookup.
-    const resolvedEntry = createRequire(join(plugin.targetRoot, 'package.json')).resolve('.');
-    const resolvedRoot = realpathSync(linkPath);
-    if (resolvedRoot !== plugin.targetRoot || !isWithin(plugin.targetRoot, realpathSync(resolvedEntry))) {
-      return { ok: false, code: 'CREW_PLUGIN_NOT_LOADABLE' };
-    }
-    return {
-      ok: true,
-      changed: scaffoldChanged || manifestChanged || link.changed,
-      profileRoot,
-      profileManifest: profile.profileManifest,
-      linkPath,
-      targetRoot: plugin.targetRoot,
-      packageName: plugin.packageName,
-      packageVersion: plugin.packageVersion,
-      patchPath: plugin.patchPath,
-      resolvedEntry,
-    };
-  } catch { return { ok: false, code: 'CREW_PLUGIN_NOT_LOADABLE' }; }
-}
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isSafePackageName(name) {
+  return typeof name === 'string'
+    && /^(?:@[^/\s]+\/)?[^/\s]+$/u.test(name)
+    && !name.split('/').some((part) => part === '.' || part === '..');
+}
+
+function isWithin(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function fileSpec(target) {
+  return `link:${target.replace(/\\/g, '/')}`;
+}
+
+function profileLinkPath(profileRoot, name) {
+  return join(profileRoot, 'node_modules', ...name.split('/'));
+}
+
+function readPluginRoot(root, expectedName) {
+  if (typeof root !== 'string' || !isAbsolute(root)) return { ok: false, code: 'INVALID_CREW_PLUGIN_ROOT' };
+  let targetRoot;
+  try { targetRoot = realpathSync(root); } catch { return { ok: false, code: 'CREW_PLUGIN_ROOT_NOT_FOUND' }; }
+  const packageFile = join(targetRoot, 'package.json');
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(packageFile, 'utf8')); } catch { return { ok: false, code: 'CREW_PLUGIN_MANIFEST_INVALID' }; }
+  if (!isObject(pkg) || !isSafePackageName(pkg.name) || (expectedName !== undefined && pkg.name !== expectedName)) {
+    return { ok: false, code: 'CREW_PLUGIN_MANIFEST_INVALID' };
+  }
+  const patchSpec = pkg.dsh?.bundle?.patch;
+  if (typeof patchSpec !== 'string' || !patchSpec.trim()) return { ok: false, code: 'CREW_PLUGIN_BUNDLE_INVALID' };
+  const patchPath = resolve(targetRoot, patchSpec);
+  if (!isWithin(targetRoot, patchPath) || !existsSync(patchPath)) return { ok: false, code: 'CREW_PLUGIN_BUNDLE_INVALID' };
+  return { ok: true, targetRoot, packageFile, packageName: pkg.name, packageVersion: pkg.version ?? null, patchPath, pkg };
+}
+
+function readProfileManifestForRegistration(profileRoot, { create = true, defaultBundles = CREW_PROFILE_DEFAULT_BUNDLES } = {}) {
+  const profileManifest = join(profileRoot, 'package.json');
+  if (!existsSync(profileManifest)) {
+    if (!create) return { ok: false, code: 'PROFILE_NOT_FOUND', profileManifest };
+    return {
+      profileManifest,
+      manifest: {
+        name: `dsh-profile-${profileRoot.split(/[\\/]/u).at(-1)}`,
+        private: true,
+        dependencies: {},
+        dsh: { profile: { bundles: [...defaultBundles] } },
+      },
+      created: true,
+    };
+  }
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(profileManifest, 'utf8')); } catch { return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' }; }
+  if (!isObject(manifest)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  if (manifest.dependencies !== undefined && !isObject(manifest.dependencies)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  if (manifest.dependencies && Object.values(manifest.dependencies).some((value) => typeof value !== 'string')) {
+    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  }
+  if (manifest.dsh !== undefined && !isObject(manifest.dsh)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  if (manifest.dsh?.profile !== undefined && !isObject(manifest.dsh.profile)) return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  const bundles = manifest.dsh?.profile?.bundles;
+  if (bundles !== undefined && (!Array.isArray(bundles) || bundles.some((name) => !isSafePackageName(name)))) {
+    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  }
+  return { profileManifest, manifest, created: false };
+}
+
+function ensureProfileScaffold(profileRoot) {
+  mkdirSync(profileRoot, { recursive: true });
+  let changed = false;
+  const patchFile = join(profileRoot, 'cordis.patch.yml');
+  if (!existsSync(patchFile)) { writeFileSync(patchFile, PROFILE_PATCH_TEMPLATE); changed = true; }
+  const workspaceFile = join(profileRoot, 'pnpm-workspace.yaml');
+  if (!existsSync(workspaceFile)) { writeFileSync(workspaceFile, PROFILE_PNPM_WORKSPACE); changed = true; }
+  return changed;
+}
+
+function ensureDirectoryLink(linkPath, targetRoot) {
+  let stat;
+  try { stat = lstatSync(linkPath); } catch { stat = null; }
+  if (stat && !stat.isSymbolicLink()) return { ok: false, code: 'CREW_PLUGIN_LINK_CONFLICT' };
+  if (stat) {
+    try {
+      if (realpathSync(linkPath) === targetRoot) return { ok: true, changed: false };
+    } catch {}
+    unlinkSync(linkPath);
+  }
+  mkdirSync(dirname(linkPath), { recursive: true });
+  symlinkSync(targetRoot, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+  return { ok: true, changed: true };
+}
+
+/**
+ * Register a local Crew plugin without invoking DSH's pnpm-forwarding plugin
+ * 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({
+  profileRoot,
+  root,
+  name,
+  createProfile = true,
+  defaultBundles = CREW_PROFILE_DEFAULT_BUNDLES,
+} = {}) {
+  const plugin = readPluginRoot(root, name);
+  if (!plugin.ok) return plugin;
+  if (typeof profileRoot !== 'string' || !isAbsolute(profileRoot)) return { ok: false, code: 'INVALID_PROFILE_ROOT' };
+  const profile = readProfileManifestForRegistration(profileRoot, { create: createProfile, defaultBundles });
+  if (profile.ok === false) return profile;
+  const scaffoldChanged = createProfile ? ensureProfileScaffold(profileRoot) : false;
+  const current = profile.manifest;
+  const dependencies = { ...(current.dependencies ?? {}) };
+  const currentBundles = current.dsh?.profile?.bundles ?? [...CREW_PROFILE_DEFAULT_BUNDLES];
+  const nextBundles = [];
+  let seen = false;
+  for (const bundle of currentBundles) {
+    if (bundle === plugin.packageName) {
+      if (!seen) { nextBundles.push(bundle); seen = true; }
+    } else nextBundles.push(bundle);
+  }
+  if (!seen) nextBundles.push(plugin.packageName);
+  dependencies[plugin.packageName] = fileSpec(plugin.targetRoot);
+  const next = {
+    ...current,
+    dependencies,
+    dsh: {
+      ...(current.dsh ?? {}),
+      profile: { ...(current.dsh?.profile ?? {}), bundles: nextBundles },
+    },
+  };
+  const manifestChanged = JSON.stringify(current) !== JSON.stringify(next) || profile.created;
+  const linkPath = profileLinkPath(profileRoot, plugin.packageName);
+  let link;
+  try { link = ensureDirectoryLink(linkPath, plugin.targetRoot); } catch { return { ok: false, code: 'CREW_PLUGIN_LINK_FAILED' }; }
+  if (!link.ok) return link;
+  try {
+    if (manifestChanged) writeFileSync(profile.profileManifest, JSON.stringify(next, null, 2) + '\n');
+    // Resolve the intended package entry from the validated checkout. Node's
+    // package-name resolution cache can retain the old target after a stale
+    // junction is replaced in the same process, so loader visibility is proven
+    // by the link target plus a normal package entry resolution from that
+    // target rather than by trusting a cached package-name lookup.
+    const resolvedEntry = createRequire(join(plugin.targetRoot, 'package.json')).resolve('.');
+    const resolvedRoot = realpathSync(linkPath);
+    if (resolvedRoot !== plugin.targetRoot || !isWithin(plugin.targetRoot, realpathSync(resolvedEntry))) {
+      return { ok: false, code: 'CREW_PLUGIN_NOT_LOADABLE' };
+    }
+    return {
+      ok: true,
+      changed: scaffoldChanged || manifestChanged || link.changed,
+      profileRoot,
+      profileManifest: profile.profileManifest,
+      linkPath,
+      targetRoot: plugin.targetRoot,
+      packageName: plugin.packageName,
+      packageVersion: plugin.packageVersion,
+      patchPath: plugin.patchPath,
+      resolvedEntry,
+    };
+  } catch { return { ok: false, code: 'CREW_PLUGIN_NOT_LOADABLE' }; }
+}
+
+export function ensureCrewPluginRegistration({ home = homedir(), root, name } = {}) {
+  return ensurePluginRegistration({ profileRoot: crewProfileDir({ home }), root, name });
+}
 
 /**
  * Remove one Crew plugin registration without invoking a package manager.
@@ -407,41 +418,41 @@ export function ensureCrewPluginRegistration({ home = homedir(), root, name } =
  * status/uninstall probe cannot touch the official web profile or download
  * anything merely to remove a stale registration.
  */
-export function removeCrewPluginRegistration({ home = homedir(), name, profileRoot = crewProfileDir({ home }) } = {}) {
-  if (!isSafePackageName(name)) {
-    return { ok: false, code: 'INVALID_CREW_PLUGIN_NAME' };
-  }
+export function removeCrewPluginRegistration({ home = homedir(), name, profileRoot = crewProfileDir({ home }) } = {}) {
+  if (!isSafePackageName(name)) {
+    return { ok: false, code: 'INVALID_CREW_PLUGIN_NAME' };
+  }
   const packageFile = join(profileRoot, 'package.json');
   if (!existsSync(packageFile)) return { ok: true, removed: false };
-  let pkg;
-  try { pkg = JSON.parse(readFileSync(packageFile, 'utf8')); } catch { return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' }; }
-  if (!isObject(pkg)
-    || (pkg.dependencies !== undefined && !isObject(pkg.dependencies))
-    || (pkg.dsh !== undefined && !isObject(pkg.dsh))
-    || (pkg.dsh?.profile !== undefined && !isObject(pkg.dsh.profile))
-    || (pkg.dsh?.profile?.bundles !== undefined
-      && (!Array.isArray(pkg.dsh.profile.bundles)
-        || pkg.dsh.profile.bundles.some((item) => !isSafePackageName(item))))) {
-    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
-  }
-  const hadDependency = Boolean(pkg.dependencies?.[name]);
-  const bundles = Array.isArray(pkg.dsh?.profile?.bundles) ? pkg.dsh.profile.bundles : [];
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(packageFile, 'utf8')); } catch { return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' }; }
+  if (!isObject(pkg)
+    || (pkg.dependencies !== undefined && !isObject(pkg.dependencies))
+    || (pkg.dsh !== undefined && !isObject(pkg.dsh))
+    || (pkg.dsh?.profile !== undefined && !isObject(pkg.dsh.profile))
+    || (pkg.dsh?.profile?.bundles !== undefined
+      && (!Array.isArray(pkg.dsh.profile.bundles)
+        || pkg.dsh.profile.bundles.some((item) => !isSafePackageName(item))))) {
+    return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' };
+  }
+  const hadDependency = Boolean(pkg.dependencies?.[name]);
+  const bundles = Array.isArray(pkg.dsh?.profile?.bundles) ? pkg.dsh.profile.bundles : [];
   const hadBundle = bundles.includes(name);
   if (!hadDependency && !hadBundle) return { ok: true, removed: false };
-  const linkPath = profileLinkPath(profileRoot, name);
-  let linkStat;
-  try { linkStat = lstatSync(linkPath); } catch { linkStat = null; }
-  if (linkStat && !linkStat.isSymbolicLink()) return { ok: false, code: 'CREW_PLUGIN_LINK_CONFLICT' };
-  const next = { ...pkg };
+  const linkPath = profileLinkPath(profileRoot, name);
+  let linkStat;
+  try { linkStat = lstatSync(linkPath); } catch { linkStat = null; }
+  if (linkStat && !linkStat.isSymbolicLink()) return { ok: false, code: 'CREW_PLUGIN_LINK_CONFLICT' };
+  const next = { ...pkg };
   if (hadDependency) {
     next.dependencies = { ...pkg.dependencies };
     delete next.dependencies[name];
     if (Object.keys(next.dependencies).length === 0) delete next.dependencies;
   }
-  if (hadBundle) {
-    next.dsh = { ...pkg.dsh, profile: { ...pkg.dsh.profile, bundles: bundles.filter((item) => item !== name) } };
-  }
-  writeFileSync(packageFile, JSON.stringify(next, null, 2) + '\n');
-  if (linkStat) unlinkSync(linkPath);
-  return { ok: true, removed: true };
-}
+  if (hadBundle) {
+    next.dsh = { ...pkg.dsh, profile: { ...pkg.dsh.profile, bundles: bundles.filter((item) => item !== name) } };
+  }
+  writeFileSync(packageFile, JSON.stringify(next, null, 2) + '\n');
+  if (linkStat) unlinkSync(linkPath);
+  return { ok: true, removed: true };
+}

package/src/extension-contract.mjs

@@ -0,0 +1,78 @@
+// Stable extension-capability projection for GPT-first orchestrators. It
+// describes only DSH Crew and deliberately never advertises itself as a top-
+// level Executor or control plane.
+
+export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+
+function row(matrix, id) {
+  return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;
+}
+
+function component(status, reasonCode, evidence = null) {
+  return { status, reason_code: reasonCode, ...(evidence ? { evidence } : {}) };
+}
+
+function workspaceComponent(workspace) {
+  if (workspace?.status === 'CONFLICT' || workspace?.status === 'READ_ONLY') {
+    return { ...component('DEGRADED', workspace.reason_code ?? `WORKSPACE_${workspace.status}`), state: workspace.status };
+  }
+  if (workspace?.status === 'UNAVAILABLE') {
+    return { ...component('UNAVAILABLE', workspace.reason_code ?? 'WORKSPACE_UNAVAILABLE'), state: 'UNAVAILABLE' };
+  }
+  if (workspace?.status === 'READY') {
+    return { ...component('READY', workspace.reason_code ?? 'WORKSPACE_READY'), state: 'READY' };
+  }
+  return workspace?.ok === true
+    ? { ...component('READY', workspace.context ? 'WORKSPACE_CONTEXT_RESOLVED' : 'WORKSPACE_CONTEXT_NOT_REQUESTED'), state: 'READY' }
+    : { ...component('UNAVAILABLE', workspace?.code ?? 'WORKSPACE_NOT_CHECKED'), state: 'UNAVAILABLE' };
+}
+
+function readinessFromRow(entry, { pass = 'READY', notRun = 'DEGRADED' } = {}) {
+  if (!entry) return component('UNAVAILABLE', 'NO_EVIDENCE');
+  if (entry.status === 'PASS') return component(pass, entry.reason_code ?? 'CHECK_PASSED');
+  if (entry.status === 'NOT_RUN' || entry.status === 'SKIP') return component(notRun, entry.reason_code ?? 'CHECK_NOT_RUN');
+  return component('UNAVAILABLE', entry.reason_code ?? 'CHECK_FAILED');
+}
+
+export function buildExtensionContract({ config = {}, readinessMatrix = {}, workspace = null, profiles = null, runtime = null } = {}) {
+  const workerEnabled = config.subagents_enabled !== false && config.worker_state !== 'disabled';
+  const reviewerEnabled = config.subagents_enabled !== false && config.review_state !== 'disabled';
+  const realModelEvidence = ['model_execution', 'deepseek_flash', 'deepseek_pro', 'opencode_go_mimo_qwen']
+    .map((id) => row(readinessMatrix, id))
+    .find((entry) => entry?.status === 'PASS');
+  const catalogEvidence = row(readinessMatrix, 'provider_catalog');
+  const modelReadiness = realModelEvidence
+    ? component('READY', realModelEvidence.reason_code ?? 'MODEL_EXECUTION_PASSED')
+    : catalogEvidence?.status === 'PASS' || catalogEvidence?.status === 'SKIP'
+      ? component('DEGRADED', 'MODEL_CATALOG_ONLY')
+      : component('UNAVAILABLE', catalogEvidence?.reason_code ?? 'NO_EVIDENCE');
+  const components = {
+    harness: readinessFromRow(row(readinessMatrix, 'hub_compatibility')),
+    model: modelReadiness,
+    workspace: workspaceComponent(workspace),
+    reviewer: reviewerEnabled
+      ? readinessFromRow(row(readinessMatrix, 'reviewer_pipeline'))
+      : component('DEGRADED', 'REVIEWER_DISABLED'),
+  };
+  const states = Object.values(components).map((entry) => entry.status);
+  const readiness = states.includes('UNAVAILABLE') ? 'UNAVAILABLE' : states.includes('DEGRADED') ? 'DEGRADED' : 'READY';
+  return {
+    schema_version: EXTENSION_CONTRACT_SCHEMA_VERSION,
+    kind: 'dsh-crew-extension',
+    runtime: runtime ?? null,
+    capabilities: {
+      'deepseek.worker': workerEnabled,
+      'deepseek.reviewer': reviewerEnabled,
+      'worktree.isolation': true,
+      'model.fallback': config.escalate_on_failure === true,
+      'job.cancel': true,
+      'job.watch': true,
+      'job.resume': false,
+      'result.evidence': true,
+      'events.canonical': true,
+      'profiles.roles': profiles?.ok === true,
+      'workspace.context': true,
+    },
+    readiness: { status: readiness, components },
+  };
+}

package/src/failure-classification.mjs

@@ -69,6 +69,11 @@ const RUNTIME_CODES = new Set([
   'GIT_ERROR',
   'WORKTREE_LOCKED',
   'WORKTREE_CREATE_FAILED',
+  'PROFILE_NOT_FOUND',
+  'PROFILE_ROLE_MISMATCH',
+  'WORKSPACE_CONTEXT_NOT_FOUND',
+  'WORKSPACE_ROOT_MISMATCH',
+  'WORKSPACE_CONTEXT_REFS_INVALID',
   'CANDIDATE_CAPTURE_FAILED',
   'ATTEMPT_INFRA_FAILURE',
   'HUB_REQUEST_FAILED',
@@ -78,13 +83,37 @@ function normalizedCode(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+function failureFamily(category, reasonCode, sourceCode) {
+  const code = sourceCode ?? reasonCode ?? '';
+  if (category === 'none') return 'NONE';
+  if (category === 'compatibility' || code.startsWith('HUB_')) return 'HARNESS';
+  if (category === 'provider' || code.startsWith('MODEL_') || code.startsWith('PROVIDER_')) return 'MODEL';
+  if (/^(WORK|GIT_|ISOLATION_|CANDIDATE_|PROFILE_)/.test(code)) return 'WORKSPACE';
+  if (String(reasonCode).startsWith('REVIEW_')) return 'REVIEW';
+  if (category === 'policy') return 'POLICY';
+  return 'JOB';
+}
+
+function failureDisposition(category, family) {
+  if (category === 'none') return 'none';
+  if (category === 'cancelled') return 'terminal';
+  if (category === 'compatibility') return 'retry';
+  if (category === 'provider') return 'fallback';
+  if (category === 'policy' || family === 'WORKSPACE' || family === 'REVIEW') return 'human';
+  if (category === 'runtime') return 'retry';
+  return 'terminal';
+}
+
 function result(category, reasonCode, { sourceCode = null, terminalReason = null } = {}) {
+  const family = failureFamily(category, reasonCode, sourceCode);
   return {
     schema_version: 1,
     category,
     reason_code: reasonCode,
     ...(sourceCode ? { source_code: sourceCode } : {}),
     ...(terminalReason ? { terminal_reason: terminalReason } : {}),
+    family,
+    disposition: failureDisposition(category, family),
   };
 }