external-subagent 0.6.0 → 0.6.2

package/cli/commands/plugin.mjs

@@ -1,8 +1,9 @@
 import { CliError } from '../errors.mjs';
 import { installMcp, installPlugin, uninstallPlugin } from '../install/codex.mjs';
 import { installZcodePlugin, uninstallZcodePlugin } from '../install/zcode.mjs';
-import { installDshPlugin, uninstallDshPlugin } from '../install/dsh.mjs';
+import { installDshPlugin, uninstallDshPlugin, dshHomeFor } from '../install/dsh.mjs';
 import { registerCodexHome, unregisterCodexHome } from '../install/reconcile.mjs';
+import { registerDshBinding, unregisterDshBinding } from '../install/dsh-registry.mjs';
 import { verifyPayload } from '../install/payload.mjs';
 
 // Command surface for the managed host bindings.  `install-plugin` takes an
@@ -68,7 +69,23 @@ export function pluginCommand(paths, args) {
     // error at the CLI parsing boundary with the other flag-combination
     // errors instead of deep inside the installer.
     if (!options.profile) throw new CliError('INVALID_ARGUMENT', 'the dsh host requires --profile <name>', 2);
-    return options.uninstall ? uninstallDshPlugin(paths, installerOptions) : installDshPlugin(paths, installerOptions);
+    const result = options.uninstall ? uninstallDshPlugin(paths, installerOptions) : installDshPlugin(paths, installerOptions);
+    // Registry bookkeeping survives a dsh-desktop rewrite that drops the
+    // managed block: a registered profile is RESTORED by reconcile, an
+    // unregistered one is forgotten.  Dry-runs never touch the registry.
+    if (!options.dry_run) {
+      const dshHome = dshHomeFor(installerOptions, paths);
+      if (options.uninstall) {
+        if (result.uninstalled) {
+          const claim = unregisterDshBinding(paths, dshHome, options.profile);
+          result.claim_released = claim.unregistered;
+        }
+      } else if (result.installed) {
+        const claim = registerDshBinding(paths, dshHome, options.profile, { status: 'claimed' });
+        result.claim = { registered: claim.registered, deduplicated: claim.deduplicated, bindings: claim.bindings };
+      }
+    }
+    return result;
   }
   if (options.profile) throw new CliError('INVALID_ARGUMENT', '--profile applies to the dsh host only', 2);
   if (options.dshHome) throw new CliError('INVALID_ARGUMENT', '--dsh-home applies to the dsh host only', 2);

package/cli/constants.mjs

@@ -12,7 +12,7 @@ const IS_DEBUG_VARIANT = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
 
 export const PRODUCT_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug' : 'external-subagent';
 export const PRODUCT_ID = IS_DEBUG_VARIANT ? 'external_subagent_debug' : 'external_subagent';
-export const VERSION = '0.6.0';
+export const VERSION = '0.6.2';
 export const LAUNCH_AGENT_LABEL = IS_DEBUG_VARIANT ? 'com.external-subagent-debug.daemon' : 'com.external-subagent.daemon';
 export const DAEMON_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debugd' : 'external-subagentd';
 export const MCP_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';

package/cli/install/dsh-registry.mjs

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../errors.mjs';
+import { atomicWrite, jsonBytes, readOptional } from '../fs-atomic.mjs';
+
+// D28: the persistent registry of bound DSH profiles.  The dsh binding is
+// derivable from the patch sentinel in daily operation, but the sentinel
+// itself lives inside a file the dsh desktop rewrites wholesale on upgrade
+// (OBSERVED 2026-10-28, dsh 0.2.1-rc.3: both bound profiles lost the
+// managed block AND the staged skill, while the product's sentinel-only
+// reconcile reported bound:false and silently forgot the machines ever
+// bound).  This registry remembers what the user explicitly bound so
+// reconcile can RESTORE a dropped binding instead of merely refreshing
+// surviving ones.  It follows the codex-homes D08 model: atomic writes,
+// per-entry status bookkeeping, and corruption recovery that preserves the
+// bad bytes as evidence and continues with an empty table rather than
+// aborting the caller.
+
+const REGISTRY_SCHEMA_VERSION = 1;
+
+export function dshBindingsRegistryPath(paths) {
+  return path.join(paths.data, 'dsh-bindings.json');
+}
+
+function emptyRegistry() {
+  return { schema_version: REGISTRY_SCHEMA_VERSION, product: 'external-subagent', bindings: [] };
+}
+
+// Resolve a home to its canonical registry key.  A plain realpath fails on
+// a not-yet-created directory (a dsh home registered before its first
+// boot), and on macOS the /var -> /private/var symlink then yields the
+// UNRESOLVED prefix — so the same home would register and reconcile under
+// two different strings depending on whether it existed at the time.
+// Resolve the deepest EXISTING ancestor and append the remainder instead:
+// the key is stable across creation, removal, and symlinked tmpdirs.
+export function canonicalHome(home) {
+  if (typeof home !== 'string' || home.length === 0) throw new CliError('INVALID_ARGUMENT', 'dsh home must be a non-empty string', 2);
+  const absolute = path.resolve(home);
+  try { return fs.realpathSync(absolute); } catch { /* fall through to ancestor resolution */ }
+  const parent = path.dirname(absolute);
+  if (parent === absolute) return absolute;
+  return path.join(canonicalHome(parent), path.basename(absolute));
+}
+
+function resolveHome(home) {
+  return canonicalHome(home);
+}
+
+function normalizeEntry(entry) {
+  if (!entry || typeof entry.home !== 'string' || typeof entry.profile !== 'string') {
+    throw new CliError('DSH_BINDINGS_REGISTRY_INVALID', 'registry entry is missing its home or profile path');
+  }
+  if (/[\\/]/u.test(entry.profile)) {
+    throw new CliError('DSH_BINDINGS_REGISTRY_INVALID', 'registry entry profile must not contain path separators');
+  }
+  return {
+    home: entry.home,
+    profile: entry.profile,
+    claimed_at_ms: Number.isInteger(entry.claimed_at_ms) ? entry.claimed_at_ms : null,
+    last_sync_ms: Number.isInteger(entry.last_sync_ms) ? entry.last_sync_ms : null,
+    last_status: typeof entry.last_status === 'string' ? entry.last_status : null,
+  };
+}
+
+function parseRegistry(bytes, file) {
+  const doc = JSON.parse(bytes.toString('utf8'));
+  if (doc?.schema_version !== REGISTRY_SCHEMA_VERSION || doc?.product !== 'external-subagent' || !Array.isArray(doc.bindings)) {
+    throw new CliError('DSH_BINDINGS_REGISTRY_INVALID', 'registry identity or bindings table is invalid');
+  }
+  const registry = emptyRegistry();
+  registry.bindings = doc.bindings.map(normalizeEntry);
+  return registry;
+}
+
+// Corrupted registry: preserve the bytes for inspection, atomically stage a
+// fresh registry, and report a recoverable error — never abort the caller.
+export function loadDshBindings(paths) {
+  const file = dshBindingsRegistryPath(paths);
+  const bytes = readOptional(file);
+  if (bytes === null) return { registry: emptyRegistry(), recovery: null };
+  try {
+    return { registry: parseRegistry(bytes, file), recovery: null };
+  } catch (error) {
+    const backup = `${file}.corrupt-${Date.now()}`;
+    try { fs.renameSync(file, backup); } catch (renameError) {
+      throw new CliError('DSH_BINDINGS_REGISTRY_CORRUPT', `registry is corrupted and could not be preserved: ${renameError.message}`);
+    }
+    atomicWrite(file, jsonBytes(emptyRegistry()));
+    return {
+      registry: emptyRegistry(),
+      recovery: { status: 'recovered', code: 'DSH_BINDINGS_REGISTRY_CORRUPT', backup, error: error.message },
+    };
+  }
+}
+
+export function persistRegistry(paths, registry) {
+  atomicWrite(dshBindingsRegistryPath(paths), jsonBytes(registry));
+}
+
+export function registerDshBinding(paths, dshHome, profile, meta = {}) {
+  const { registry, recovery } = loadDshBindings(paths);
+  const home = resolveHome(dshHome);
+  const existing = registry.bindings.find((entry) => entry.home === home && entry.profile === profile);
+  let entry;
+  if (existing) {
+    entry = existing;
+    if (typeof meta.status === 'string') entry.last_status = meta.status;
+  } else {
+    entry = {
+      home,
+      profile,
+      claimed_at_ms: Date.now(),
+      last_sync_ms: null,
+      last_status: typeof meta.status === 'string' ? meta.status : 'claimed',
+    };
+    registry.bindings.push(entry);
+  }
+  persistRegistry(paths, registry);
+  return { registered: true, home, profile, deduplicated: Boolean(existing), bindings: registry.bindings.length, recovery };
+}
+
+export function unregisterDshBinding(paths, dshHome, profile) {
+  const { registry } = loadDshBindings(paths);
+  const home = resolveHome(dshHome);
+  const remaining = registry.bindings.filter((entry) => !(entry.home === home && entry.profile === profile));
+  const unregistered = remaining.length !== registry.bindings.length;
+  registry.bindings = remaining;
+  if (unregistered) persistRegistry(paths, registry);
+  return { unregistered, home, profile, bindings: registry.bindings.length };
+}
+
+// Product uninstall: no profile remains claimed.  The registry file itself
+// stays inside retained product data, matching the codex-homes posture.
+export function unregisterAllDshBindings(paths) {
+  const { registry } = loadDshBindings(paths);
+  const released = registry.bindings.map((entry) => ({ home: entry.home, profile: entry.profile }));
+  const file = dshBindingsRegistryPath(paths);
+  if (released.length > 0 || fs.existsSync(file)) {
+    registry.bindings = [];
+    persistRegistry(paths, registry);
+  }
+  return { unregistered: released.length, bindings: released };
+}

package/cli/install/dsh.mjs

@@ -7,6 +7,7 @@ import { atomicWrite, readOptional, restoreOptional } from '../fs-atomic.mjs';
 import { MCP_BIN_NAME } from '../constants.mjs';
 import { nativeBinary, pluginSourceRoot, PLUGIN_NAME } from './layout.mjs';
 import { guardedRestores } from './plugin-stage.mjs';
+import { loadDshBindings, persistRegistry as persistDshRegistry, dshBindingsRegistryPath, canonicalHome } from './dsh-registry.mjs';
 
 // Managed DSH host binding.  DSH boots profiles as an ordered stack of
 // plugin-bundle patch layers under the user's own overrides; the user layer
@@ -17,9 +18,11 @@ import { guardedRestores } from './plugin-stage.mjs';
 // into the user skill root (<dshHome>/skills), which dsh-skill-filesystem
 // scans by default (rank 400; OBSERVED against dsh 0.2.0-rc.2).  It never
 // touches the profile's package.json, bundles, node_modules, or any dsh
-// market/plugin-install state.  There is no registry file: the binding is
-// fully derivable from the patch sentinel plus the staged skill, so
-// reconcile and uninstall detect rather than remember it (the zcode model).
+// market/plugin-install state.  Claims also live in the persistent
+// dsh-bindings.json registry (dsh-registry.mjs): the dsh desktop rewrites
+// cordis.patch.yml wholesale on upgrade and DROPS the managed block
+// (OBSERVED 2026-10-28), so reconcile pairs the sentinel scan with the
+// registry to RESTORE a dropped binding instead of forgetting it.
 
 // The MCP client plugin is resolved by the dsh loader from the CLI's own
 // install tree when the bare package name is used (OBSERVED: a fresh
@@ -546,61 +549,135 @@ export function uninstallDshPlugin(paths, options = {}) {
   };
 }
 
-// Stateless reconcile for update flows (the zcode model): every profile
-// directory whose patch file carries the sentinel is rebound; the skill is
-// refreshed alongside.  Unknown/corrupt states are reported, never fatal to
-// the caller's broader reconcile.
+// Reconcile for update flows: the persistent registry (dsh-bindings.json)
+// UNION the sentinel scan.  The scan alone follows the zcode model — detect
+// rather than remember — but the dsh desktop rewrites cordis.patch.yml
+// wholesale on upgrade and DROPS the managed block (OBSERVED 2026-10-28),
+// after which a sentinel-only reconcile silently forgets the profile was
+// ever bound.  Registry entries therefore drive a RESTORE: a registered
+// profile whose patch lost the sentinel is re-bound (status `rebound`),
+// and one whose profile directory itself vanished is reported
+// (`missing_profile_dir`) without failing the reconcile.  Profiles bearing
+// the sentinel but absent from the registry (bound by an older build, or
+// by hand) are adopted into the registry so future drops restore too.
 export function reconcileDshBindings(paths, options = {}) {
   const dshHome = dshHomeFor(options, paths);
+  // Registry entries store realpath-resolved homes (registerDshBinding
+  // resolves); compare and dedupe against the SAME resolved form, or a
+  // symlinked dshHome (/var -> /private/var on macOS tmpdirs) would never
+  // match its own registry claims.
+  const resolvedHome = canonicalHome(dshHome);
   const profilesRoot = path.join(dshHome, 'profiles');
-  let entries;
+  const { registry, recovery } = loadDshBindings(paths);
+  const results = [];
+  const visited = new Set();
+  let directories = [];
+  let profilesRootAbsent = false;
   try {
-    entries = fs.readdirSync(profilesRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+    directories = fs.readdirSync(profilesRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
   } catch (error) {
-    if (error?.code === 'ENOENT') return { bound: false, profiles: [], note: 'no dsh profiles directory' };
-    return { bound: false, profiles: [], error: { code: 'DSH_PROFILES_UNREADABLE', message: error.message } };
+    if (error?.code === 'ENOENT') profilesRootAbsent = true;
+    else {
+      return { bound: false, profiles: [], error: { code: 'DSH_PROFILES_UNREADABLE', message: error.message }, ...(recovery ? { recovery } : {}) };
+    }
   }
-  const results = [];
-  for (const entry of entries) {
-    if (DSH_FORBIDDEN_PROFILES.includes(entry.name)) continue;
-    const patchFile = path.join(profilesRoot, entry.name, 'cordis.patch.yml');
+  const directorySet = new Set(directories);
+  // Sentinel scan: refresh every surviving binding and adopt unregistered ones.
+  for (const name of directories) {
+    if (DSH_FORBIDDEN_PROFILES.includes(name)) continue;
+    const patchFile = path.join(profilesRoot, name, 'cordis.patch.yml');
     const bytes = readOptional(patchFile);
     if (bytes === null || !bytes.toString('utf8').includes(SENTINEL)) continue;
+    visited.add(`${resolvedHome}\u0000${name}`);
+    try {
+      installDshPlugin(paths, { ...options, profile: name });
+      upsertRegistryEntry(registry, resolvedHome, name, 'updated');
+      results.push({ profile: name, status: 'updated', idempotent: true });
+    } catch (error) {
+      results.push({ profile: name, status: 'failed', error: { code: error.code || 'DSH_BINDING_FAILED', message: error.message } });
+    }
+  }
+  // Registry pass: restore registered profiles whose sentinel was dropped.
+  for (const entry of registry.bindings) {
+    if (entry.home !== resolvedHome) continue;
+    if (visited.has(`${entry.home}\u0000${entry.profile}`)) continue;
+    if (DSH_FORBIDDEN_PROFILES.includes(entry.profile)) continue;
+    if (!directorySet.has(entry.profile)) {
+      entry.last_status = 'missing_profile_dir';
+      results.push({ profile: entry.profile, status: 'missing_profile_dir' });
+      continue;
+    }
     try {
-      const install = installDshPlugin(paths, { ...options, profile: entry.name });
-      results.push({ profile: entry.name, status: 'updated', idempotent: Boolean(install.idempotent) });
+      installDshPlugin(paths, { ...options, dshHome: entry.home, profile: entry.profile });
+      entry.last_status = 'rebound';
+      entry.last_sync_ms = Date.now();
+      results.push({ profile: entry.profile, status: 'rebound' });
     } catch (error) {
-      results.push({ profile: entry.name, status: 'failed', error: { code: error.code || 'DSH_BINDING_FAILED', message: error.message } });
+      entry.last_status = 'failed';
+      results.push({ profile: entry.profile, status: 'failed', error: { code: error.code || 'DSH_BINDING_FAILED', message: error.message } });
     }
   }
-  return { bound: results.length > 0, profiles: results };
+  if (results.length > 0 || fs.existsSync(dshBindingsRegistryPath(paths))) {
+    persistDshRegistry(paths, registry);
+  }
+  return {
+    bound: results.length > 0,
+    profiles: results,
+    ...(profilesRootAbsent ? { note: 'no dsh profiles directory' } : {}),
+    ...(recovery ? { recovery } : {}),
+  };
+}
+
+// Insert or refresh a registry entry in place (the loaded registry object is
+// the caller's working copy; persisting happens once at the end).
+function upsertRegistryEntry(registry, dshHome, profile, status) {
+  const home = canonicalHome(dshHome);
+  const existing = registry.bindings.find((entry) => entry.home === home && entry.profile === profile);
+  if (existing) {
+    existing.last_status = status;
+    existing.last_sync_ms = Date.now();
+  } else {
+    registry.bindings.push({
+      home,
+      profile,
+      claimed_at_ms: Date.now(),
+      last_sync_ms: Date.now(),
+      last_status: status,
+    });
+  }
 }
 
 // Product uninstall: release every detected binding at once.  Detection is
-// the same sentinel scan as reconcile; each profile is uninstalled
-// independently (a failure on one never skips the rest, matching the
-// per-home codex release posture), and the shared staged skill is removed
-// when no bound profile remains.
+// the same sentinel scan plus the registry, so a desktop-rewritten patch
+// (sentinel dropped) is still unregistered even though its block is gone.
+// Each profile is uninstalled independently (a failure on one never skips
+// the rest, matching the per-home codex release posture), and the shared
+// staged skill is removed when no bound profile remains.
 export function uninstallAllDshBindings(paths, options = {}) {
   const dshHome = dshHomeFor(options, paths);
   const profilesRoot = path.join(dshHome, 'profiles');
-  let entries;
+  let entries = [];
   try {
-    entries = fs.readdirSync(profilesRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory());
-  } catch {
-    return { released: 0, profiles: [] };
+    entries = fs.readdirSync(profilesRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch { /* registry pass below still releases claims */ }
+  const names = new Set(entries);
+  const resolvedHome = canonicalHome(dshHome);
+  const { registry } = loadDshBindings(paths);
+  for (const entry of registry.bindings) {
+    if (entry.home === resolvedHome) names.add(entry.profile);
   }
   const results = [];
-  for (const entry of entries) {
-    if (DSH_FORBIDDEN_PROFILES.includes(entry.name)) continue;
-    const patchFile = path.join(profilesRoot, entry.name, 'cordis.patch.yml');
-    const bytes = readOptional(patchFile);
-    if (bytes === null || !bytes.toString('utf8').includes(SENTINEL)) continue;
+  for (const name of names) {
+    if (DSH_FORBIDDEN_PROFILES.includes(name)) continue;
     try {
-      const removed = uninstallDshPlugin(paths, { ...options, profile: entry.name });
-      results.push({ profile: entry.name, status: removed.uninstalled ? 'released' : 'absent' });
+      const removed = uninstallDshPlugin(paths, { ...options, profile: name });
+      results.push({ profile: name, status: removed.uninstalled ? 'released' : 'absent' });
     } catch (error) {
-      results.push({ profile: entry.name, status: 'failed', error: { code: error.code || 'DSH_BINDING_RELEASE_FAILED', message: error.message } });
+      results.push({ profile: name, status: 'failed', error: { code: error.code || 'DSH_BINDING_RELEASE_FAILED', message: error.message } });
     }
   }
   // The skill is shared across profiles; remove it once no binding remains.
@@ -609,5 +686,10 @@ export function uninstallAllDshBindings(paths, options = {}) {
       unstageSkill(dshHome, options.source || pluginSourceRoot());
     } catch { /* reported per-profile above; a stuck skill never fails the release */ }
   }
-  return { released: results.filter((result) => result.status === 'released').length, profiles: results };
+  // Release every registry claim for THIS dsh home (other homes keep theirs).
+  const before = registry.bindings.length;
+  registry.bindings = registry.bindings.filter((entry) => entry.home !== resolvedHome);
+  const registry_cleared = before !== registry.bindings.length || fs.existsSync(dshBindingsRegistryPath(paths));
+  if (registry_cleared) persistDshRegistry(paths, registry);
+  return { released: results.filter((result) => result.status === 'released').length, profiles: results, registry_cleared };
 }

package/npm/native/darwin-arm64/payload.json

@@ -1,20 +1,20 @@
 {
   "schema_version": 1,
   "product": "external-subagent",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "platform": "darwin-arm64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 10454384,
+      "bytes": 10436400,
       "mode": "755",
-      "sha256": "3c3363a340d30718a7cb50801467eab8be7e70856b3c6f8925f6c7e87243b3ce"
+      "sha256": "1a954915bde8dc5bafd1d73f9a767a55068a54c7707cafe1508a8ddebd35128d"
     },
     {
       "name": "external-subagent-mcp",
       "bytes": 935776,
       "mode": "755",
-      "sha256": "037d6041c379290284dadba0631b4f1e706a49e3315ef476952168f0ed3477ef"
+      "sha256": "e0f51f5b901bdb5c01bff16fa8dc136df9583b73aea07c687c24f6949a8dd066"
     }
   ]
 }

package/npm/native/linux-x64/payload.json

@@ -1,20 +1,20 @@
 {
   "schema_version": 1,
   "product": "external-subagent",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "platform": "linux-x64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 12008336,
+      "bytes": 12031728,
       "mode": "755",
-      "sha256": "d2f9599c6982ff3900cdc9516ed9bc7ab3b8d7c23012b1ac44f63a79a4f5878e"
+      "sha256": "ef39528c0c033016f06a6af0bbf727d15ecbaca3f697ee3d5ca321abb4ca75cd"
     },
     {
       "name": "external-subagent-mcp",
-      "bytes": 1025520,
+      "bytes": 1025480,
       "mode": "755",
-      "sha256": "5a84607f0e2abe6afc679b7ea39207d50c06084fbcc4f54444f8f55168bc2492"
+      "sha256": "fac84526602dca1cd82574f82afe28e5b6700532297670e33b8fb092c1fad7cb"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Manage bounded ZCode, DeepSeek Harness (DSH), Codex, and Google Antigravity (agy) subagent tasks through a local MCP service for any local host (Codex, ZCode, or a custom MCP client)",
   "type": "module",
   "license": "MIT",