@ran-sh/dsh-crew 2.0.9 → 2.0.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/install/install-legacy.mjs

@@ -4,6 +4,7 @@
 
 import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, readdirSync, rmSync, statSync, lstatSync } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -23,6 +24,11 @@ const PLUGIN_KEY = `dsh-crew@${MARKETPLACE_NAME}`;
 const CLAUDE_PLUGIN_TIMEOUT_MS = 300_000;
 const CLAUDE_SNAPSHOT_SETTLE_MS = 180_000;
 const CLAUDE_SNAPSHOT_POLL_MS = 5_000;
+// The one scope this installer writes, and therefore the only scope whose record
+// means "the integration is installed". Accepting any scope let a project-scope
+// record stand in for a missing user-scope snapshot, so a failed install read as
+// a current one.
+const CLAUDE_PLUGIN_SCOPE = 'user';
 const POLICY_START = '<!-- DSH CREW MANAGED POLICY:START -->';
 const POLICY_END = '<!-- DSH CREW MANAGED POLICY:END -->';
 
@@ -173,26 +179,31 @@ function claudePluginRootReady(root) {
     && mcp.args[0] === '${CLAUDE_PLUGIN_ROOT}/src/server.mjs';
 }
 
-function managedClaudeFileManifest(root, { maxFiles = 512, maxBytes = 8 * 1024 * 1024 } = {}) {
+export function managedClaudeFileManifest(root, { maxFiles = 512, maxBytes = 8 * 1024 * 1024, maxDirectories = 256, maxDepth = 12 } = {}) {
   const files = [];
   let bytes = 0;
+  let directories = 0;
   const add = (file, relativePath) => {
     const info = lstatSync(file);
     if (info.isSymbolicLink() || !info.isFile()) throw new Error('unsupported snapshot entry');
+    // Bound before reading, not after: reading first and rejecting afterwards
+    // loads a whole oversized file on the strength of its name.
+    if (files.length >= maxFiles || bytes + info.size > maxBytes) throw new Error('snapshot manifest bound exceeded');
     const content = readFileSync(file);
     bytes += content.length;
-    if (bytes > maxBytes || files.length >= maxFiles) throw new Error('snapshot manifest bound exceeded');
     files.push([relativePath.replace(/\\/g, '/'), createHash('sha256').update(content).digest('hex')]);
   };
-  const walk = (directory, relativeDirectory) => {
+  const walk = (directory, relativeDirectory, depth = 0) => {
+    if (depth > maxDepth) throw new Error('snapshot directory depth exceeded');
     if (!existsSync(directory)) return;
+    if (++directories > maxDirectories) throw new Error('snapshot directory count exceeded');
     const info = lstatSync(directory);
     if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('unsupported snapshot directory');
     for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       const file = join(directory, entry.name);
       const relativePath = join(relativeDirectory, entry.name);
       if (entry.isSymbolicLink()) throw new Error('snapshot symlink not allowed');
-      if (entry.isDirectory()) walk(file, relativePath);
+      if (entry.isDirectory()) walk(file, relativePath, depth + 1);
       else if (entry.isFile()) add(file, relativePath);
       else throw new Error('unsupported snapshot entry');
     }
@@ -200,7 +211,14 @@ function managedClaudeFileManifest(root, { maxFiles = 512, maxBytes = 8 * 1024 *
   try {
     add(join(root, '.claude-plugin', 'plugin.json'), join('.claude-plugin', 'plugin.json'));
     if (isFile(join(root, 'package.json'))) add(join(root, 'package.json'), 'package.json');
-    for (const directory of ['agents', 'commands', 'src']) walk(join(root, directory), directory);
+    // What the plugin loads, not just what names it. `worker.cordis.yml` is
+    // required before any dispatch (`src/jobs.mjs` throws without it) and the
+    // statusline scripts are named by the settings this installer writes, so a
+    // snapshot missing either is not this release even when the manifest it came
+    // from is byte-identical — which is exactly how a stale snapshot used to read
+    // as current.
+    if (isFile(join(root, 'worker.cordis.yml'))) add(join(root, 'worker.cordis.yml'), 'worker.cordis.yml');
+    for (const directory of ['agents', 'commands', 'skills', 'src', 'statusline']) walk(join(root, directory), directory);
     return files;
   } catch { return null; }
 }
@@ -212,11 +230,13 @@ function sameManagedClaudeFiles(expectedRoot, snapshotRoot) {
   return expected !== null && snapshot !== null && JSON.stringify(snapshot) === JSON.stringify(expected);
 }
 
-function claudeSnapshotReady(home, root) {
+function claudeSnapshotReady(home, root, { scope = null } = {}) {
   const installed = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'), {});
   const record = installed?.plugins?.[PLUGIN_KEY];
   const entries = Array.isArray(record) ? record : [record];
-  return entries.some((entry) => sameManagedClaudeFiles(root, entry?.installPath));
+  return entries.some((entry) => (scope === null || entry?.scope === scope)
+    && sameManagedClaudeFiles(root, entry?.installPath)
+    && claudeSnapshotResolvable(entry?.installPath));
 }
 
 function claudePermissionsReady(settings) {
@@ -399,7 +419,10 @@ export function installStatus({ home = homedir(), root = ROOT, env = process.env
   const claudeComponents = {
     enabled: claudeInstalled,
     marketplace: normalizedPath(marketplaceRoot) === normalizedPath(effectiveRoot) && claudePluginRootReady(effectiveRoot),
-    snapshot: claudeSnapshotReady(home, effectiveRoot),
+    // User scope only: this installer writes that scope, so it is the one whose
+    // record means the integration is installed. Accepting any scope let a
+    // project-scope record make a missing user-scope snapshot read as present.
+    snapshot: claudeSnapshotReady(home, effectiveRoot, { scope: CLAUDE_PLUGIN_SCOPE }),
     permissions: claudePermissionsReady(settings),
   };
   const claudeMissing = Object.entries(claudeComponents).filter(([, present]) => !present).map(([key]) => key);
@@ -512,6 +535,9 @@ export function uninstallCodex({ home = homedir(), env = process.env } = {}) {
  */
 export function claudeIntegrationLine(result) {
   if (result?.ok === false) return '✗ Claude Code integration failed';
+  if (result?.detected === false) {
+    return '- Claude Code not detected; settings registered, CLI step skipped';
+  }
   if (result?.degraded === true) {
     return `- Claude Code integration registered, but not loaded: ${result.reason ?? 'plugin snapshot not refreshed'}`;
   }
@@ -530,8 +556,126 @@ export function claudeIntegrationLine(result) {
  * without Claude Code, to learn nothing it did not already know.
  */
 export function claudeSnapshotSettleMs(err) {
-  const timedOut = err?.code === 'ETIMEDOUT' || err?.signal === 'SIGTERM';
-  return timedOut ? CLAUDE_SNAPSHOT_SETTLE_MS : 0;
+  // Only the shell's own timeout can leave a copy running. Matching on the signal
+  // as well spent the whole window on an `ENOBUFS` (output over maxBuffer) child
+  // that had already stopped and could never make the snapshot current.
+  return err?.code === 'ETIMEDOUT' ? CLAUDE_SNAPSHOT_SETTLE_MS : 0;
+}
+
+/**
+ * Whether the snapshot can actually run, not merely whether its files match.
+ *
+ * `src/server.mjs` is the MCP server Claude Code launches, and it imports its
+ * runtime dependencies by bare specifier — so a copy interrupted between `src/`
+ * and `node_modules/` leaves a snapshot whose compared files are all present and
+ * whose server cannot start. Resolution is asked from the snapshot's own
+ * `package.json` against the dependencies it declares, so this stays bounded by
+ * what the package says it needs rather than by walking installed packages. A
+ * snapshot carrying no `package.json` declares nothing, and fails the file
+ * comparison instead.
+ */
+function claudeSnapshotResolvable(snapshotRoot) {
+  if (typeof snapshotRoot !== 'string' || !snapshotRoot.trim()) return false;
+  const manifest = readJson(join(snapshotRoot, 'package.json'), null);
+  const declared = manifest && manifest.dependencies && typeof manifest.dependencies === 'object'
+    ? Object.keys(manifest.dependencies)
+    : [];
+  if (!declared.length) return true;
+  let fromSnapshot;
+  try { fromSnapshot = createRequire(join(snapshotRoot, 'package.json')); } catch { return false; }
+  return declared.every((dependency) => {
+    try { fromSnapshot.resolve(dependency); return true; } catch { /* try the manifest path below */ }
+    try { fromSnapshot.resolve(`${dependency}/package.json`); return true; } catch { return false; }
+  });
+}
+
+/**
+ * How to run the `claude` CLI, as an executable plus an argument array.
+ *
+ * Paths go in as arguments and never into a shell string: `JSON.stringify` quotes
+ * for JSON, not for a command processor, so a path containing `%NAME%` was
+ * expanded before the CLI ever saw it. Windows has to reach the CLI through a
+ * command processor because a `.cmd` shim cannot be executed directly, so an
+ * argument the processor would act on is refused rather than escaped — a refused
+ * install is recoverable, a silently relocated path is not.
+ */
+export function claudeCliInvocation(args, { platform = process.platform, environment = process.env } = {}) {
+  const argv = args.map((arg) => String(arg));
+  if (platform !== 'win32') return { command: 'claude', args: argv };
+  const unsafe = argv.find((arg) => /[\0\r\n"%!^&|<>]/.test(arg));
+  if (unsafe !== undefined) throw new Error(`unsafe claude CLI argument: ${unsafe}`);
+  return {
+    command: environment.ComSpec || environment.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', ['claude.cmd', ...argv.map((arg) => `"${arg}"`)].join(' ')],
+    windowsVerbatimArguments: true,
+  };
+}
+
+/**
+ * Kill a process and everything it started.
+ *
+ * The killed shell is not the process doing the work: `claude` is a grandchild
+ * that Windows does not reach when only its parent is terminated. An `uninstall`
+ * left running that way finishes *after* the install that followed it and deletes
+ * the plugin the install just registered, so the tree has to go, and the caller
+ * must not return until it has.
+ */
+async function killClaudeProcessTree(pid, { platform = process.platform } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  const { spawn } = await import('node:child_process');
+  if (platform === 'win32') {
+    await new Promise((done) => {
+      let settled = false;
+      const finish = () => { if (!settled) { settled = true; done(); } };
+      const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      killer.on('error', finish);
+      killer.on('close', finish);
+    });
+    return;
+  }
+  try { process.kill(-pid, 'SIGKILL'); } catch { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
+}
+
+/**
+ * Run one CLI step to completion, or end it and its descendants on timeout.
+ *
+ * Resolves only once nothing from this step can still be running, so the next
+ * step cannot be raced by the previous one. A timeout is reported in the shape
+ * `execSync` uses, so the settle rule reads it the same way.
+ */
+async function runClaudeStep(args, { timeoutMs = CLAUDE_PLUGIN_TIMEOUT_MS } = {}) {
+  let invocation;
+  try { invocation = claudeCliInvocation(args); }
+  catch (error) { return { ok: false, timedOut: false, status: null, error }; }
+  const { spawn } = await import('node:child_process');
+  return await new Promise((resolve) => {
+    const child = spawn(invocation.command, invocation.args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments === true,
+      detached: process.platform !== 'win32',
+    });
+    let timedOut = false;
+    let kill = null;
+    let stderr = '';
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const detail = stderr.slice(-400);
+      // Never report a step finished while its tree may still be writing.
+      const done = () => resolve(timedOut
+        ? { ok: false, timedOut: true, status: null, detail, error: Object.assign(new Error('claude CLI step timed out'), { code: 'ETIMEDOUT', signal: 'SIGTERM', status: null }) }
+        : { ok: code === 0, timedOut: false, status: code, detail, error: null });
+      if (kill) kill.then(done, done); else done();
+    };
+    let code = null;
+    const timer = setTimeout(() => { timedOut = true; kill = killClaudeProcessTree(child.pid); }, timeoutMs);
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', (error) => { stderr += String(error?.message ?? error); code = null; finish(); });
+    child.on('close', (value) => { code = value; finish(); });
+  });
 }
 
 export async function installClaudeCode({ home = homedir(), statusline = false, root = ROOT } = {}) {
@@ -548,58 +692,80 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
 
   // 2. settings.json: marketplace + enabledPlugins + permissions allowlist.
   const settingsFile = join(home, '.claude', 'settings.json');
-  mkdirSync(dirname(settingsFile), { recursive: true });
-  const bak = backup(settingsFile);
-  if (bak) actions.push(`backup: ${bak}`);
-  const settings = readJson(settingsFile, {});
-
-  // Both fields are records (see json.schemastore.org/claude-code-settings.json).
-  // Older versions of this installer wrote arrays, which Claude Code ignores
-  // with a warning — migrate those in place.
-  const markets = (settings.extraKnownMarketplaces && !Array.isArray(settings.extraKnownMarketplaces)
-    && typeof settings.extraKnownMarketplaces === 'object') ? settings.extraKnownMarketplaces : {};
-  if (Array.isArray(settings.extraKnownMarketplaces)) actions.push('migrated legacy extraKnownMarketplaces array');
-  markets[MARKETPLACE_NAME] = { source: { source: 'directory', path: mpDir } };
-  if (markets['dsh-workers']) {
-    delete markets['dsh-workers'];
-    actions.push('removed pre-rename dsh-workers marketplace entry');
-  }
-  settings.extraKnownMarketplaces = markets;
+  try {
+    mkdirSync(dirname(settingsFile), { recursive: true });
+    const bak = backup(settingsFile);
+    if (bak) actions.push(`backup: ${bak}`);
+    const settingsPresent = existsSync(settingsFile);
+    const parsed = readJson(settingsFile, null);
+    if (parsed === null && settingsPresent) {
+      // Present but unparseable is not "no settings yet". Rebuilding it as an
+      // empty configuration is exactly how an operator's settings disappear, with
+      // a backup left for them to restore by hand — the file is theirs, and an
+      // unreadable one is not permission to replace it.
+      return {
+        ok: false,
+        code: 'CLAUDE_SETTINGS_UNREADABLE',
+        error: `${settingsFile} is present but not valid JSON`,
+        actions,
+      };
+    }
+    const settings = parsed ?? {};
+
+    // Both fields are records (see json.schemastore.org/claude-code-settings.json).
+    // Older versions of this installer wrote arrays, which Claude Code ignores
+    // with a warning — migrate those in place.
+    const markets = (settings.extraKnownMarketplaces && !Array.isArray(settings.extraKnownMarketplaces)
+      && typeof settings.extraKnownMarketplaces === 'object') ? settings.extraKnownMarketplaces : {};
+    if (Array.isArray(settings.extraKnownMarketplaces)) actions.push('migrated legacy extraKnownMarketplaces array');
+    markets[MARKETPLACE_NAME] = { source: { source: 'directory', path: mpDir } };
+    if (markets['dsh-workers']) {
+      delete markets['dsh-workers'];
+      actions.push('removed pre-rename dsh-workers marketplace entry');
+    }
+    settings.extraKnownMarketplaces = markets;
 
-  const enabled = (settings.enabledPlugins && !Array.isArray(settings.enabledPlugins)
-    && typeof settings.enabledPlugins === 'object') ? settings.enabledPlugins : {};
-  if (Array.isArray(settings.enabledPlugins)) {
-    for (const key of settings.enabledPlugins) if (typeof key === 'string') enabled[key] = true;
-    actions.push('migrated legacy enabledPlugins array');
-  }
-  enabled[PLUGIN_KEY] = true;
-  if (enabled['dsh-workers@dsh-workers']) {
-    delete enabled['dsh-workers@dsh-workers'];
-    actions.push('removed pre-rename dsh-workers plugin entry');
-  }
-  settings.enabledPlugins = enabled;
-
-  settings.permissions = settings.permissions ?? {};
-  let allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
-  const preRename = allow.filter((r) => typeof r === 'string' && r.startsWith('mcp__plugin_dsh-workers_'));
-  if (preRename.length) {
-    allow = allow.filter((r) => !preRename.includes(r));
-    actions.push(`removed ${preRename.length} pre-rename permission rules`);
-  }
-  for (const tool of MCP_TOOLS) {
-    const rule = `mcp__plugin_dsh-crew_dsh-crew__${tool}`;
-    if (!allow.includes(rule)) allow.push(rule);
-  }
-  settings.permissions.allow = allow;
+    const enabled = (settings.enabledPlugins && !Array.isArray(settings.enabledPlugins)
+      && typeof settings.enabledPlugins === 'object') ? settings.enabledPlugins : {};
+    if (Array.isArray(settings.enabledPlugins)) {
+      for (const key of settings.enabledPlugins) if (typeof key === 'string') enabled[key] = true;
+      actions.push('migrated legacy enabledPlugins array');
+    }
+    enabled[PLUGIN_KEY] = true;
+    if (enabled['dsh-workers@dsh-workers']) {
+      delete enabled['dsh-workers@dsh-workers'];
+      actions.push('removed pre-rename dsh-workers plugin entry');
+    }
+    settings.enabledPlugins = enabled;
+
+    settings.permissions = settings.permissions ?? {};
+    let allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
+    const preRename = allow.filter((r) => typeof r === 'string' && r.startsWith('mcp__plugin_dsh-workers_'));
+    if (preRename.length) {
+      allow = allow.filter((r) => !preRename.includes(r));
+      actions.push(`removed ${preRename.length} pre-rename permission rules`);
+    }
+    for (const tool of MCP_TOOLS) {
+      const rule = `mcp__plugin_dsh-crew_dsh-crew__${tool}`;
+      if (!allow.includes(rule)) allow.push(rule);
+    }
+    settings.permissions.allow = allow;
 
-  if (statusline && !settings.statusLine) {
-    settings.statusLine = { type: 'command', command: `bash ${join(root, 'statusline', 'statusline.sh')}` };
-    actions.push('statusline: installed');
-  } else if (statusline) {
-    actions.push('statusline: skipped (one already configured)');
-  }
+    if (statusline && !settings.statusLine) {
+      settings.statusLine = { type: 'command', command: `bash ${join(root, 'statusline', 'statusline.sh')}` };
+      actions.push('statusline: installed');
+    } else if (statusline) {
+      actions.push('statusline: skipped (one already configured)');
+    }
 
-  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  } catch (error) {
+    // Both install entries branch on `ok === false` for this integration and
+    // neither could ever see it: a settings path that could not be backed up or
+    // written threw straight out of both of them. Failing to register is the
+    // integration failing, so it gets the shape its callers already handle.
+    return { ok: false, code: 'CLAUDE_SETTINGS_UNWRITABLE', error: String(error?.message ?? error), actions };
+  }
   actions.push(`settings: registered ${PLUGIN_KEY} + ${MCP_TOOLS.length} permission rules`);
 
   // Materialize the install through the claude CLI: registers the marketplace
@@ -612,7 +778,7 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
   const marketplaceCurrent = registered?.source?.source === 'directory'
     && normalizedPath(registered.source.path) === normalizedPath(root)
     && normalizedPath(registered.installLocation) === normalizedPath(root);
-  if (marketplaceCurrent && installedEntries.some((entry) => entry?.scope === 'user'
+  if (marketplaceCurrent && installedEntries.some((entry) => entry?.scope === CLAUDE_PLUGIN_SCOPE
     && sameManagedClaudeFiles(root, entry.installPath))) {
     actions.push('cli: skipped (registered marketplace and snapshot already current)');
     return { ok: true, actions };
@@ -621,43 +787,59 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
     actions.push('cli: skipped (non-default home; test mode)');
     return { ok: true, actions };
   }
-  // Set only when the CLI attempt threw, and only a timeout then justifies
-  // waiting for the snapshot: see claudeSnapshotSettleMs.
-  let installError = null;
-  try {
-    const { execSync } = await import('node:child_process');
-    // 300s, not 120: the install below runs after the uninstall, so it does a real
-    // copy of the plugin tree rather than the no-op an already-installed plugin
-    // gets. Measured on this machine: `marketplace add` 3s, `uninstall` 3s,
-    // `install` 163s (no-op install: 6s). The old ceiling killed the copy partway
-    // and left Claude Code without the plugin the same run had just removed.
-    const run = (cmd) => execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
-    try { run(`claude plugin marketplace add ${JSON.stringify(mpDir)}`); actions.push('cli: marketplace registered'); }
-    catch { actions.push('cli: marketplace add skipped (already registered)'); }
-    // `plugin install` on an already-installed plugin is a no-op and leaves a
-    // stale snapshot in ~/.claude/plugins/cache — uninstall first so an update
-    // always re-copies the current code.
-    try { run(`claude plugin uninstall ${PLUGIN_KEY}`); } catch {}
-    // Newer Claude Code (>= 2.1.x) dropped the -y flag; older builds accepted
-    // it. Try without it first, fall back to the legacy flag.
-    try {
-      run(`claude plugin install ${PLUGIN_KEY} --scope user`);
-    } catch (errNoFlag) {
-      if (!String(errNoFlag?.message ?? '').includes('unknown option')) throw errNoFlag;
-      run(`claude plugin install ${PLUGIN_KEY} --scope user -y`);
-    }
-    actions.push(`cli: plugin snapshot refreshed (${PLUGIN_KEY})`);
-  } catch (err) {
-    installError = err;
-    actions.push(`cli: plugin install failed — run manually: claude plugin install ${PLUGIN_KEY} (${String(err?.message ?? err).slice(0, 120)})`);
-  }
+  // The CLI is best-effort, but a host that does not have it must not be told to
+  // run it. The checkout entry already gates on this; doing it here too keeps the
+  // two entries describing the same machine the same way.
+  const { spawnSync } = await import('node:child_process');
+  const claudePresent = spawnSync(/^win/.test(process.platform) ? 'where' : 'which', ['claude'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  }).status === 0;
+  if (!claudePresent) {
+    actions.push('cli: skipped (claude not found)');
+    return { ok: true, detected: false, actions };
+  }
+  // Each step runs to completion — including ending the whole process tree on a
+  // timeout — before the next one starts, and the settle window is the widest any
+  // step asks for. Two things this replaces: an `uninstall` left running past its
+  // timeout finished *after* the install that followed and deleted the plugin the
+  // install had just registered, and a later step's ordinary failure used to erase
+  // an earlier step's timeout from the evidence.
+  // 300s, not 120: the install runs after the uninstall, so it does a real copy of
+  // the plugin tree rather than the no-op an already-installed plugin gets.
+  // Measured on this machine: `marketplace add` 3s, `uninstall` 3s, `install` 163s
+  // (no-op install: 6s). The old ceiling killed the copy partway and left Claude
+  // Code without the plugin the same run had just removed.
+  let settleMs = 0;
+  const noteStep = (step) => { settleMs = Math.max(settleMs, claudeSnapshotSettleMs(step?.error)); };
+
+  const marketplace = await runClaudeStep(['plugin', 'marketplace', 'add', mpDir]);
+  noteStep(marketplace);
+  actions.push(marketplace.ok
+    ? 'cli: marketplace registered'
+    : `cli: marketplace add failed${marketplace.timedOut ? ' (timed out)' : ''}`);
+
+  // `plugin install` on an already-installed plugin is a no-op and leaves a
+  // stale snapshot in ~/.claude/plugins/cache — uninstall first so an update
+  // always re-copies the current code.
+  noteStep(await runClaudeStep(['plugin', 'uninstall', PLUGIN_KEY]));
+
+  // Newer Claude Code (>= 2.1.x) dropped the -y flag; older builds accepted it.
+  // Try without it first, fall back to the legacy flag.
+  let install = await runClaudeStep(['plugin', 'install', PLUGIN_KEY, '--scope', CLAUDE_PLUGIN_SCOPE]);
+  if (!install.ok && !install.timedOut && /unknown option/i.test(String(install.detail ?? ''))) {
+    install = await runClaudeStep(['plugin', 'install', PLUGIN_KEY, '--scope', CLAUDE_PLUGIN_SCOPE, '-y']);
+  }
+  noteStep(install);
+  actions.push(install.ok
+    ? `cli: plugin snapshot refreshed (${PLUGIN_KEY})`
+    : `cli: plugin install failed — run manually: claude plugin install ${PLUGIN_KEY}${install.timedOut ? ' (timed out)' : ''}`);
   // Report the state that resulted, not the step that was attempted. The CLI is
   // best-effort — a machine without `claude` is a supported install, and its
   // settings alone are correct — but a CLI that is present and slow, timed out,
   // or failed leaves the snapshot exactly as stale as it was, and it is the
   // snapshot that `installStatus` reads. Saying so here is what lets the caller
   // stop printing a checkmark for a state it never verified.
-  if (claudeSnapshotReady(home, root)) return { ok: true, actions };
+  if (claudeSnapshotReady(home, root, { scope: CLAUDE_PLUGIN_SCOPE })) return { ok: true, actions };
   // The CLI can outlive the ceiling above. The install is a real copy of the
   // plugin tree — 163s measured on an idle machine, and ~6 minutes measured
   // during an activation, where the record landed well after any ceiling — and a
@@ -665,11 +847,11 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
   // is still running keeps writing while this function has already given up on
   // it. Wait for the snapshot to settle before reporting it missing, or the
   // update says "not loaded" about a plugin that is loading.
-  const settleDeadline = Date.now() + claudeSnapshotSettleMs(installError);
+  const settleDeadline = Date.now() + settleMs;
   const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   while (Date.now() < settleDeadline) {
     await wait(CLAUDE_SNAPSHOT_POLL_MS);
-    if (claudeSnapshotReady(home, root)) {
+    if (claudeSnapshotReady(home, root, { scope: CLAUDE_PLUGIN_SCOPE })) {
       return { ok: true, actions: [...actions, 'cli: snapshot confirmed current after the ceiling'] };
     }
   }

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '2.0.9';
+export const RUNTIME_VERSION = '2.0.11';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/windows/start-dsh-crew.ps1

@@ -437,8 +437,16 @@ function Get-HealthState {
         $diskReadable = $true
       }
       $cohortMatches = $diskReadable -and $runtime.dsh_version -eq $expectedDshVersion
+      # Read through PSObject: StrictMode is on, so a response that simply omits the
+      # property would throw and be swallowed as "not ready" rather than being
+      # reported absent.
+      $runtimeId = $null
+      if ($null -ne $runtime) {
+        $runtimeIdProperty = $runtime.PSObject.Properties['runtime_id']
+        if ($null -ne $runtimeIdProperty -and $null -ne $runtimeIdProperty.Value) { $runtimeId = [string] $runtimeIdProperty.Value }
+      }
       if ($response.ok -eq $true -and $version -and $cohortMatches) {
-        return [pscustomobject]@{ Ready = $true; Version = [string] $version; Error = $null }
+        return [pscustomobject]@{ Ready = $true; Version = [string] $version; RuntimeId = $runtimeId; Error = $null }
       }
       if (-not $diskReadable) {
         return [pscustomobject]@{ Ready = $false; Version = $null; Error = 'disk runtime manifest unreadable; cannot prove cohort identity' }
@@ -551,6 +559,92 @@ function Get-FreshSupervisorHeartbeat {
   return $null
 }
 
+# ---- Persisted ownership of the live Hub -----------------------------------
+# A watcher can exit while the Hub it started keeps serving. Nothing else on the
+# machine can tell a later watcher that such a listener is Crew's: port health
+# says a process answers, not whose it is, and adopting on health alone would put
+# a stranger's listener within reach of Stop-OwnedListener. So the identity is
+# written down when it is established, and re-proven field by field — PID, start
+# time, port, profile, Crew home and live runtime_id — before any later watcher
+# adopts it. A record that merely exists is not authority; it may name a Hub from
+# a previous cohort, another profile, or a PID the system has since recycled.
+
+$crewOwnedServiceFile = Join-Path $crewSupervisorRoot 'owned-service.json'
+
+function Write-OwnedServiceRecord {
+  param([pscustomobject] $Service, [string] $RuntimeId = $null)
+  if (-not $Service.CrewOwned -or -not $Service.RootPid -or -not $Service.RootStartedAtUtcTicks) { return }
+  $record = @{
+    schema_version = 1
+    profile = [string] $Service.Profile
+    home = [string] $Service.Home
+    port = [int] $Service.Port
+    root_pid = [int] $Service.RootPid
+    root_started_at_utc_ticks = [long] $Service.RootStartedAtUtcTicks
+    listener_pid = if ($Service.ListenerPid) { [int] $Service.ListenerPid } else { $null }
+    listener_started_at_utc_ticks = if ($Service.ListenerStartedAtUtcTicks) { [long] $Service.ListenerStartedAtUtcTicks } else { $null }
+    runtime_id = $RuntimeId
+    recorded_at = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+  } | ConvertTo-Json -Compress
+  try {
+    if (-not (Test-Path -LiteralPath $crewSupervisorRoot -PathType Container)) { New-Item -ItemType Directory -Path $crewSupervisorRoot -Force | Out-Null }
+    $temp = Join-Path $crewSupervisorRoot ("owned-service.{0}.tmp" -f $PID)
+    Write-Utf8NoBom -Path $temp -Content $record
+    Move-Item -LiteralPath $temp -Destination $crewOwnedServiceFile -Force
+  } catch { /* ownership record is best-effort, like the heartbeat */ }
+}
+
+function Clear-OwnedServiceRecord {
+  try {
+    if (Test-Path -LiteralPath $crewOwnedServiceFile -PathType Leaf) { Remove-Item -LiteralPath $crewOwnedServiceFile -Force }
+  } catch { }
+}
+
+function Get-OwnedServiceRecord {
+  try {
+    if (-not (Test-Path -LiteralPath $crewOwnedServiceFile -PathType Leaf)) { return $null }
+    $record = Get-Content -LiteralPath $crewOwnedServiceFile -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
+    if ($record.schema_version -ne 1) { return $null }
+    return $record
+  } catch {
+    return $null
+  }
+}
+
+function Restore-OwnedServiceRecord {
+  param([pscustomobject] $Service, [pscustomobject] $Health = $null)
+  if (-not $Service.CrewOwned) { return $false }
+  $record = Get-OwnedServiceRecord
+  if (-not $record) { return $false }
+  if ([string] $record.profile -ne [string] $Service.Profile) { return $false }
+  if ([string] $record.home -ne [string] $Service.Home) { return $false }
+  if ([int] $record.port -ne [int] $Service.Port) { return $false }
+  if (-not $record.root_pid -or -not $record.root_started_at_utc_ticks) { return $false }
+  if (-not $record.listener_pid -or -not $record.listener_started_at_utc_ticks) { return $false }
+  # Without this, an interrupted write could leave a record whose listener half is
+  # simply absent, and "absent" must never read as "the Hub this record names".
+  if ([string]::IsNullOrWhiteSpace([string] $record.runtime_id)) { return $false }
+  try {
+    $processes = @(Get-CimInstance Win32_Process -ErrorAction Stop)
+  } catch {
+    return $false
+  }
+  # Start times come from Get-Process, since Win32_Process carries none: the table
+  # only has to establish that the PID exists before the ticks are compared.
+  if (-not (Test-TrackedProcessIdentity -ProcessId ([int] $record.root_pid) -ExpectedStartTicks ([long] $record.root_started_at_utc_ticks) -ProcessTable $processes)) { return $false }
+  if (-not (Test-TrackedProcessIdentity -ProcessId ([int] $record.listener_pid) -ExpectedStartTicks ([long] $record.listener_started_at_utc_ticks) -ProcessTable $processes)) { return $false }
+  $port = Get-PortState $Service.Port
+  if ($port.State -ne 'occupied' -or -not $port.Pid -or [int] $port.Pid -ne [int] $record.listener_pid) { return $false }
+  $live = if ($Health) { $Health } else { Get-HealthState $Service }
+  if (-not $live.Ready) { return $false }
+  if ([string] $live.RuntimeId -ne [string] $record.runtime_id) { return $false }
+  $Service.RootPid = [int] $record.root_pid
+  $Service.RootStartedAtUtcTicks = [long] $record.root_started_at_utc_ticks
+  $Service.ListenerPid = [int] $record.listener_pid
+  $Service.ListenerStartedAtUtcTicks = [long] $record.listener_started_at_utc_ticks
+  return $true
+}
+
 function Ensure-CrewSupervisorRunning {
   param([int] $TimeoutSeconds = 90)
   $watcher = $null
@@ -967,7 +1061,7 @@ function Get-TrackedProcessTree {
 }
 
 function Set-TrackedListenerIdentity {
-  param([pscustomobject] $Service)
+  param([pscustomobject] $Service, [string] $RuntimeId = $null)
   $port = Get-PortState $Service.Port
   if ($port.State -ne 'occupied' -or -not $port.Pid) { return $false }
   $tree = @(Get-TrackedProcessTree -Service $Service)
@@ -976,6 +1070,7 @@ function Set-TrackedListenerIdentity {
     $listener = Get-Process -Id $port.Pid -ErrorAction Stop
     $Service.ListenerPid = [int] $port.Pid
     $Service.ListenerStartedAtUtcTicks = $listener.StartTime.ToUniversalTime().Ticks
+    Write-OwnedServiceRecord -Service $Service -RuntimeId $RuntimeId
     return $true
   } catch {
     return $false
@@ -1057,6 +1152,10 @@ function Start-CrewService {
     $Service.ListenerStartedAtUtcTicks = $null
     $Service.ConsecutiveFailures = 0
     $Service.State = 'starting'
+    # Recorded before the Hub is healthy on purpose: the record is written again
+    # with the listener identity once it is, and only that later write is
+    # adoptable, because this one carries no runtime_id to prove itself against.
+    Write-OwnedServiceRecord -Service $Service
     Write-LaunchLog ('Started {0} on port {1}; PID={2}; stdout={3}; stderr={4}' -f $Service.Profile, $Service.Port, $process.Id, $stdout, $stderr)
   } finally {
     $env:DSH_HOME = $previousHome
@@ -1070,7 +1169,7 @@ function Wait-CrewServices {
       $health = Get-HealthState $service
       $service.LastError = $health.Error
       if ($health.Ready) {
-        if ($service.CrewOwned -and -not $service.ListenerPid -and -not (Set-TrackedListenerIdentity -Service $service)) {
+        if ($service.CrewOwned -and -not $service.ListenerPid -and -not (Set-TrackedListenerIdentity -Service $service -RuntimeId $health.RuntimeId)) {
           throw ('{0} is healthy on {1}, but this supervisor cannot prove process ownership.' -f $service.Name, $service.Port)
         }
         if ($service.CrewOwned -and -not (Test-CrewServiceOwnership -Service $service)) {
@@ -1118,7 +1217,16 @@ function Ensure-CrewServices {
     $health = Get-HealthState $service
     if ($health.Ready) {
       $wasReady = $service.State -eq 'ready'
-      if ($service.CrewOwned -and -not $service.ListenerPid -and -not (Set-TrackedListenerIdentity -Service $service)) {
+      if ($service.CrewOwned -and -not $service.ListenerPid) {
+        # A watcher that exited leaves its Hub serving with nothing in memory to
+        # say whose it is. Re-prove the persisted identity before touching it;
+        # this is the only path by which a later watcher may adopt a live Hub,
+        # and it never adopts on port health alone.
+        if (Restore-OwnedServiceRecord -Service $service -Health $health) {
+          Write-LaunchLog ('{0} on {1} recovered from the persisted ownership record; listener PID={2}.' -f $service.Name, $service.Port, $service.ListenerPid)
+        }
+      }
+      if ($service.CrewOwned -and -not $service.ListenerPid -and -not (Set-TrackedListenerIdentity -Service $service -RuntimeId $health.RuntimeId)) {
         throw ('{0} is healthy on {1}, but this supervisor cannot prove process ownership.' -f $service.Name, $service.Port)
       }
       if ($service.CrewOwned -and -not (Test-CrewServiceOwnership -Service $service)) {
@@ -1157,6 +1265,7 @@ function Ensure-CrewServices {
         $service.ListenerPid = $null
         $service.ListenerStartedAtUtcTicks = $null
         $service.ConsecutiveFailures = 0
+        Clear-OwnedServiceRecord
         $port = Get-PortState $service.Port
       }
     }