@ran-sh/dsh-crew 0.5.1 → 0.5.2

package/src/install/install-legacy.mjs

@@ -6,11 +6,14 @@ import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, readd
 import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { normalizeModelPriority } from '../model-routing.mjs';
+import { normalizeModelPriority } from '../model-routing.mjs';
+import { zcodeStatus } from './zcode.mjs';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const MARKETPLACE_NAME = 'dsh-crew';
-const PLUGIN_KEY = `dsh-crew@${MARKETPLACE_NAME}`;
+const PLUGIN_KEY = `dsh-crew@${MARKETPLACE_NAME}`;
+const POLICY_START = '<!-- DSH CREW MANAGED POLICY:START -->';
+const POLICY_END = '<!-- DSH CREW MANAGED POLICY:END -->';
 // dsh_worker_config is included so the session commands (/dsh-crew:config,
 // /dsh-config) and any orchestrator policy lookup run without an extra
 // authorization prompt.
@@ -33,6 +36,50 @@ function readText(file) {
   try { return readFileSync(file, 'utf8'); } catch { return null; }
 }
 
+function managedPolicyBlock(root) {
+  const policy = readText(join(root, 'codex', 'AGENTS.md'))?.trim();
+  if (!policy) return null;
+  return `${POLICY_START}\n${policy}\n${POLICY_END}`;
+}
+
+function installGlobalCodexPolicy({ home, root }) {
+  const file = join(home, '.codex', 'AGENTS.md');
+  const block = managedPolicyBlock(root);
+  if (!block) return { ok: false, action: 'global policy template missing' };
+  mkdirSync(dirname(file), { recursive: true });
+  const current = readText(file) ?? '';
+  const managed = new RegExp(`${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  const template = readText(join(root, 'codex', 'AGENTS.md'))?.trim() ?? '';
+  let next;
+  if (managed.test(current)) next = current.replace(managed, block);
+  else if (current.trim() === template) next = `${block}\n`;
+  else next = `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
+  if (next !== current) {
+    backup(file);
+    writeFileSync(file, next);
+  }
+  return { ok: true, action: `global policy: ${file}` };
+}
+
+function globalCodexPolicyReady({ home, root = ROOT }) {
+  const block = managedPolicyBlock(root);
+  const text = readText(join(home, '.codex', 'AGENTS.md'));
+  return !!block && typeof text === 'string' && text.includes(block);
+}
+
+function uninstallGlobalCodexPolicy({ home }) {
+  const file = join(home, '.codex', 'AGENTS.md');
+  const current = readText(file);
+  if (typeof current !== 'string') return null;
+  const managed = new RegExp(`(?:\\r?\\n){0,2}${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\r?\\n)?`, 'm');
+  if (!managed.test(current)) return null;
+  const next = current.replace(managed, '').trimEnd();
+  backup(file);
+  if (next.trim()) writeFileSync(file, `${next}\n`);
+  else rmSync(file);
+  return `codex global policy: removed managed block`;
+}
+
 function tomlSection(text, name) {
   if (typeof text !== 'string') return null;
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -256,7 +303,7 @@ export function writeGlobalConfig(patch) {
 }
 
 /** What is currently installed where — drives the settings-page buttons. */
-export function installStatus({ home = homedir() } = {}) {
+export function installStatus({ home = homedir(), root } = {}) {
   const settings = readJson(join(home, '.claude', 'settings.json'), {});
   const enabled = settings.enabledPlugins;
   const claudeInstalled = !!(enabled && !Array.isArray(enabled) && enabled[PLUGIN_KEY]);
@@ -282,6 +329,7 @@ export function installStatus({ home = homedir() } = {}) {
     status_prompt: !!readText(join(codexRoot, 'prompts', 'dsh-status.md'))?.trim(),
     mcp: !!mcpTarget,
     target_alignment: !!workerTarget && workerTarget === reviewerTarget && workerTarget === mcpTarget,
+    global_policy: globalCodexPolicyReady({ home }),
   };
   const codexInstalled = Object.values(components).some(Boolean)
     || existsSync(join(codexRoot, 'agents', 'ds-flash.toml'))
@@ -296,10 +344,11 @@ export function installStatus({ home = homedir() } = {}) {
       missing: claudeMissing,
     },
     codex: { installed: codexInstalled, ready: missing.length === 0, components, missing },
+    zcode: zcodeStatus({ home, ...(root ? { root } : {}) }),
   };
 }
 
-export function uninstallCodex({ home = homedir() } = {}) {
+export function uninstallCodex({ home = homedir() } = {}) {
   const actions = [];
   // Both the v0.2 roles (ds-worker / ds-reviewer) and the deprecated v0.1
   // aliases (ds-flash / ds-pro) are dsh-crew managed; uninstall removes only
@@ -308,10 +357,12 @@ export function uninstallCodex({ home = homedir() } = {}) {
     const p = join(home, '.codex', 'agents', f);
     if (existsSync(p)) { backup(p); rmSync(p); actions.push(`removed: ${p} (backup kept)`); }
   }
-  for (const f of ['dsh-config.md', 'dsh-status.md']) {
+  for (const f of ['dsh-config.md', 'dsh-status.md']) {
     const p = join(home, '.codex', 'prompts', f);
     if (existsSync(p)) { rmSync(p); actions.push(`removed: ${p}`); }
-  }
+  }
+  const policyAction = uninstallGlobalCodexPolicy({ home });
+  if (policyAction) actions.push(policyAction);
   // Remove only the dsh-crew entry from [mcp_servers], keeping any other
   // MCP servers the user configured.
   const configFile = join(home, '.codex', 'config.toml');
@@ -428,7 +479,7 @@ export async function installClaudeCode({ home = homedir(), statusline = false,
   return { ok: true, actions };
 }
 
-export function installCodex({ home = homedir(), scope, root = ROOT } = {}) {
+export function installCodex({ home = homedir(), scope, root = ROOT } = {}) {
   const actions = [];
   const agentsDir = scope === 'project' ? join(process.cwd(), '.codex', 'agents') : join(home, '.codex', 'agents');
   mkdirSync(agentsDir, { recursive: true });
@@ -455,10 +506,13 @@ export function installCodex({ home = homedir(), scope, root = ROOT } = {}) {
     writeFileSync(join(promptsDir, f), readFileSync(join(promptsSrc, f), 'utf8'));
     actions.push(`prompt: ${join(promptsDir, f)}`);
   }
-  if (scope !== 'project') {
-    const act = writeGlobalCodexMcpServer(home, renderedPath);
-    actions.push(...act);
-  }
+  if (scope !== 'project') {
+    const act = writeGlobalCodexMcpServer(home, renderedPath);
+    actions.push(...act);
+    const policy = installGlobalCodexPolicy({ home, root });
+    if (!policy.ok) return { ok: false, actions: [...actions, policy.action] };
+    actions.push(policy.action);
+  }
   return { ok: true, actions };
 }
 

package/src/install/install.mjs

@@ -4,7 +4,9 @@
 // This module keeps all installer exports while replacing only global config
 // read/write semantics with schema-v3 canonical authority.
 
-export * from './install-legacy.mjs';
+export * from './install-legacy.mjs';
+export * from './windows-startup.mjs';
+export * from './zcode.mjs';
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';

package/src/install/npx-lifecycle.mjs

@@ -549,14 +549,30 @@ async function activateRelease({ home, releaseDir, manifest, log, installer }) {
   }
   log(`✓ Harness plugin registered (dedicated dsh-crew profile → ${releaseDir})`);
 
-  const codex = installer.installCodex({ home, root: releaseDir });
+  const codex = installer.installCodex({ home, root: releaseDir });
   if (codex.ok === false) {
     log(`✗ Codex Desktop integration failed: ${(codex.actions ?? []).join('; ')}`);
     return false;
   }
-  log('✓ Codex Desktop integration');
-
-  const claude = await installer.installClaudeCode({ home, root: releaseDir });
+  log('✓ Codex Desktop integration');
+
+  if (installer.installZCode) {
+    const zcode = installer.installZCode({ home, root: releaseDir });
+    if (zcode.ok === false) {
+      log(`✗ ZCode integration failed (${zcode.code ?? 'unknown'})`);
+      return false;
+    }
+    log('✓ ZCode integration');
+  }
+
+  const startup = installer.installWindowsStartup?.({ home, root: releaseDir });
+  if (startup?.ok === false) {
+    log(`✗ Windows login startup failed (${startup.code ?? 'unknown'})`);
+    return false;
+  }
+  if (startup?.supported) log('✓ Windows login startup');
+
+  const claude = await installer.installClaudeCode({ home, root: releaseDir });
   if (claude.ok === false) {
     log(`✗ Claude Code integration failed`);
     return false;
@@ -944,11 +960,17 @@ export function npxStatus({
     } catch { dshPlugin = 'unknown'; }
   }
 
-  const st = installer.installStatus ? installer.installStatus({ home }) : realInstaller.installStatus({ home });
-  const codex = st?.codex?.installed ? 'installed' : 'not installed';
-  const claude = st?.claude?.installed ? 'installed' : 'not installed';
+  const st = installer.installStatus
+    ? installer.installStatus({ home, root: pointer?.path ?? runningPackageRoot() })
+    : realInstaller.installStatus({ home, root: pointer?.path ?? runningPackageRoot() });
+  const codex = st?.codex?.installed ? 'installed' : 'not installed';
+  const zcode = st?.zcode?.installed ? 'installed' : 'not installed';
+  const claude = st?.claude?.installed ? 'installed' : 'not installed';
   const official = officialWebIntegrationStatus({ home, releaseDir: pointer?.path });
-  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
+  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
+  const startupState = installer.windowsStartupStatus?.({ home });
+  const windowsStartup = !startupState?.supported ? 'not supported'
+    : startupState.ready ? 'installed' : startupState.installed ? 'needs repair' : 'not installed';
 
   log(`DSH Crew launcher/candidate: ${candidateVersion ?? 'unknown'}`);
   log(`Installed DSH Crew payload: ${installedLine}`);
@@ -964,8 +986,10 @@ export function npxStatus({
   }
   log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile on 3210)`);
   log(`Official 3080 UI bridge: ${officialWeb}`);
-  log(`Codex Desktop integration: ${codex}`);
-  log(`Claude Code integration: ${claude}`);
+  log(`Codex Desktop integration: ${codex}`);
+  log(`ZCode integration: ${zcode}`);
+  log(`Claude Code integration: ${claude}`);
+  log(`Windows login startup: ${windowsStartup}`);
 
   return {
     ok: true,
@@ -974,9 +998,11 @@ export function npxStatus({
     installedPath: pointer?.path ?? null,
     dshPlugin,
     officialWeb,
-    codex,
-    claude,
-  };
+    codex,
+    zcode,
+    claude,
+    windowsStartup,
+  };
 }
 
 export async function npxUninstall({
@@ -992,13 +1018,23 @@ export async function npxUninstall({
   const pointer = readCurrentPointer({ home });
   const name = pointer?.name ?? readManifest(runningPackageRoot())?.name;
 
-  const cx = installer.uninstallCodex({ home });
+  const cx = installer.uninstallCodex({ home });
   if (cx.ok !== false) log('✓ Codex Desktop integration removed');
-  else fail('Codex Desktop integration removal failed');
-
-  const cl = installer.uninstallClaudeCode ? await installer.uninstallClaudeCode({ home }) : realInstaller.uninstallClaudeCode({ home });
-  if (cl.ok !== false) log('✓ Claude Code integration removed');
-  else fail('Claude Code integration removal failed');
+  else fail('Codex Desktop integration removal failed');
+
+  if (installer.uninstallZCode) {
+    const zc = installer.uninstallZCode({ home });
+    if (zc.ok !== false) log('✓ ZCode integration removed');
+    else fail('ZCode integration removal failed');
+  }
+
+  const cl = installer.uninstallClaudeCode ? await installer.uninstallClaudeCode({ home }) : realInstaller.uninstallClaudeCode({ home });
+  if (cl.ok !== false) log('✓ Claude Code integration removed');
+  else fail('Claude Code integration removal failed');
+
+  const startup = installer.uninstallWindowsStartup?.({ home });
+  if (startup?.ok === false) fail('Windows login startup removal failed');
+  else if (startup?.supported) log('✓ Windows login startup removed');
 
   const official = removeOfficialWebIntegration({ home, preserveIntent: !purge, remember: !purge });
   if (!official.ok) fail(`official 3080 bridge removal failed (${official.code ?? 'unknown'})`);

package/src/install/windows-startup.mjs

@@ -0,0 +1,98 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const WINDOWS_STARTUP_FILENAME = 'DSH Crew.vbs';
+export const WINDOWS_LAUNCHER_FILENAME = 'start-dsh-crew.cmd';
+
+function defaultStartupDir({ home, env }) {
+  if (home === homedir() && env.APPDATA) {
+    return join(env.APPDATA, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+  }
+  return join(home, 'AppData', 'Roaming', 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+}
+
+function paths({ home, startupDir, env }) {
+  const launcherFile = join(home, '.config', 'dsh-crew', 'launchers', WINDOWS_LAUNCHER_FILENAME);
+  const resolvedStartupDir = startupDir ?? defaultStartupDir({ home, env });
+  return {
+    launcherFile,
+    startupFile: join(resolvedStartupDir, WINDOWS_STARTUP_FILENAME),
+  };
+}
+
+function renderVbs(template, launcherFile) {
+  const escaped = launcherFile.replace(/"/g, '""');
+  return template.replace('__LAUNCHER__', escaped);
+}
+
+export function windowsStartupStatus({
+  home = homedir(),
+  startupDir,
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform !== 'win32') return { supported: false, installed: false, ready: false };
+  const resolved = paths({ home, startupDir, env });
+  const installed = existsSync(resolved.startupFile) || existsSync(resolved.launcherFile);
+  let ready = existsSync(resolved.startupFile) && existsSync(resolved.launcherFile);
+  if (ready) {
+    try {
+      const text = readFileSync(resolved.startupFile, 'utf16le').replace(/^\uFEFF/, '');
+      ready = text.includes(resolved.launcherFile);
+    } catch { ready = false; }
+  }
+  return { supported: true, installed, ready, ...resolved };
+}
+
+export function installWindowsStartup({
+  home = homedir(),
+  root,
+  startupDir,
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform !== 'win32') return { ok: true, supported: false, changed: false };
+  if (!root) return { ok: false, supported: true, code: 'STARTUP_SOURCE_REQUIRED' };
+  const sourceLauncher = join(root, 'windows', WINDOWS_LAUNCHER_FILENAME);
+  const sourceVbs = join(root, 'windows', 'start-dsh-crew.vbs');
+  if (!existsSync(sourceLauncher) || !existsSync(sourceVbs)) {
+    return { ok: false, supported: true, code: 'STARTUP_ASSET_MISSING' };
+  }
+  const resolved = paths({ home, startupDir, env });
+  mkdirSync(dirname(resolved.launcherFile), { recursive: true });
+  mkdirSync(dirname(resolved.startupFile), { recursive: true });
+  const beforeLauncher = existsSync(resolved.launcherFile) ? readFileSync(resolved.launcherFile) : null;
+  const beforeStartup = existsSync(resolved.startupFile) ? readFileSync(resolved.startupFile) : null;
+  copyFileSync(sourceLauncher, resolved.launcherFile);
+  const rendered = renderVbs(readFileSync(sourceVbs, 'utf8'), resolved.launcherFile);
+  writeFileSync(resolved.startupFile, `\uFEFF${rendered}`, 'utf16le');
+  const changed = !beforeLauncher?.equals(readFileSync(resolved.launcherFile))
+    || !beforeStartup?.equals(readFileSync(resolved.startupFile));
+  return { ok: true, supported: true, changed, ...resolved };
+}
+
+export function uninstallWindowsStartup({
+  home = homedir(),
+  startupDir,
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform !== 'win32') return { ok: true, supported: false, removed: false };
+  const resolved = paths({ home, startupDir, env });
+  let removed = false;
+  for (const file of [resolved.startupFile, resolved.launcherFile]) {
+    if (existsSync(file)) {
+      rmSync(file, { force: true });
+      removed = true;
+    }
+  }
+  return { ok: true, supported: true, removed, ...resolved };
+}

package/src/install/zcode.mjs

@@ -0,0 +1,316 @@
+// ZCode host integration.  This module is deliberately file-only: it never
+// launches ZCode, mutates credentials, or overwrites an unowned MCP server.
+// The generated files make ZCode dispatch through the same dsh-crew MCP server
+// used by Codex and Claude while keeping ZCode's native config precedence.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const HOST = 'zcode';
+const SERVER = 'dsh-crew';
+const POLICY_START = '<!-- DSH CREW MANAGED ZCODE POLICY:START -->';
+const POLICY_END = '<!-- DSH CREW MANAGED ZCODE POLICY:END -->';
+const OWNERSHIP_FILE = ({ home = homedir() } = {}) => join(home, '.config', 'dsh-crew', 'integrations', 'zcode.json');
+
+// Keep the allowlist explicit. ZCode rejects wildcard tool permissions, and a
+// future server tool is not silently exposed until a template intentionally
+// opts into it.
+export const ZCODE_MCP_TOOLS = Object.freeze([
+  'dsh_run_worker',
+  'dsh_spawn_worker',
+  'dsh_worker_status',
+  'dsh_worker_result',
+  'dsh_worker_cancel',
+  'dsh_worker_config',
+]);
+
+function readText(file) {
+  try { return readFileSync(file, 'utf8'); } catch { return null; }
+}
+
+function readJson(file, fallback = null) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+function contentHash(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function writeJson(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function backup(file) {
+  if (!existsSync(file)) return null;
+  const path = `${file}.dsh-crew-backup-${Date.now()}`;
+  copyFileSync(file, path);
+  return path;
+}
+
+function normalizePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    const path = resolve(value);
+    return process.platform === 'win32' ? path.toLowerCase() : path;
+  } catch { return null; }
+}
+
+function serverTarget(server) {
+  if (!server || typeof server !== 'object') return null;
+  if (server.command !== 'node' || !Array.isArray(server.args) || typeof server.args[0] !== 'string') return null;
+  return normalizePath(server.args[0]);
+}
+
+function nativeServers(config) {
+  const servers = config?.mcp?.servers;
+  return servers && typeof servers === 'object' && !Array.isArray(servers) ? servers : {};
+}
+
+function sharedServers(config) {
+  const servers = config?.mcpServers;
+  return servers && typeof servers === 'object' && !Array.isArray(servers) ? servers : {};
+}
+
+function configSource({ home = homedir() } = {}) {
+  const nativeFile = join(home, '.zcode', 'cli', 'config.json');
+  const sharedFile = join(home, '.agents', 'mcp.json');
+  const native = readJson(nativeFile, {});
+  const shared = readJson(sharedFile, {});
+  const nativeMap = nativeServers(native);
+  const sharedMap = sharedServers(shared);
+  // ZCode shadows .agents/mcp.json whenever its native config has at least
+  // one server. If native is empty, the shared file is the least-surprising
+  // compatibility path for users who already manage MCP centrally.
+  if (Object.keys(nativeMap).length > 0 || Object.keys(sharedMap).length === 0) {
+    return { file: nativeFile, kind: 'native', config: native, servers: nativeMap };
+  }
+  return { file: sharedFile, kind: 'shared', config: shared, servers: sharedMap };
+}
+
+export function resolveZCodeMcpTarget({ home = homedir() } = {}) {
+  const source = configSource({ home });
+  return serverTarget(source.servers[SERVER]);
+}
+
+function expectedTarget({ root = ROOT } = {}) {
+  return resolve(join(root, 'src', 'server.mjs'));
+}
+
+function managedPolicyBlock(root) {
+  const template = readText(join(root, 'zcode', 'AGENTS.md'))?.trim();
+  return template ? `${POLICY_START}\n${template}\n${POLICY_END}` : null;
+}
+
+function installPolicy({ home, root }) {
+  const file = join(home, '.zcode', 'AGENTS.md');
+  const block = managedPolicyBlock(root);
+  if (!block) return { ok: false, code: 'ZCODE_POLICY_TEMPLATE_MISSING' };
+  mkdirSync(dirname(file), { recursive: true });
+  const current = readText(file) ?? '';
+  const escapedStart = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const escapedEnd = POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const managed = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, 'm');
+  const next = managed.test(current)
+    ? current.replace(managed, block)
+    : `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
+  if (next !== current) { backup(file); writeFileSync(file, next); }
+  return { ok: true, file };
+}
+
+function removePolicy({ home }) {
+  const file = join(home, '.zcode', 'AGENTS.md');
+  const current = readText(file);
+  if (typeof current !== 'string') return false;
+  const start = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const end = POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const managed = new RegExp(`(?:\\r?\\n){0,2}${start}[\\s\\S]*?${end}(?:\\r?\\n)?`, 'm');
+  if (!managed.test(current)) return false;
+  const next = current.replace(managed, '').trimEnd();
+  backup(file);
+  if (next.trim()) writeFileSync(file, `${next}\n`);
+  else rmSync(file, { force: true });
+  return true;
+}
+
+function ownership({ home = homedir() } = {}) {
+  const data = readJson(OWNERSHIP_FILE({ home }), null);
+  return data && typeof data === 'object' && data.host === HOST ? data : null;
+}
+
+function writeOwnership({ home, configFile, configKind, target, files = [] }) {
+  writeJson(OWNERSHIP_FILE({ home }), {
+    schema_version: 1,
+    host: HOST,
+    server: SERVER,
+    config_file: configFile,
+    config_kind: configKind,
+    target,
+    files,
+    managed_at: new Date().toISOString(),
+  });
+}
+
+function templateFiles({ home, root }) {
+  return [
+    ['agents', 'ds-worker.md'],
+    ['agents', 'ds-reviewer.md'],
+    ['commands', 'dsh-config.md'],
+    ['commands', 'dsh-status.md'],
+  ].map(([dir, file]) => ({ source: join(root, 'zcode', dir, file), dest: join(home, '.zcode', dir, file) }));
+}
+
+function installTemplates({ home, root, priorFiles = [] }) {
+  const actions = [];
+  const records = [];
+  for (const { source, dest } of templateFiles({ home, root })) {
+    if (!existsSync(source)) return { ok: false, code: 'ZCODE_TEMPLATE_MISSING', source };
+    mkdirSync(dirname(dest), { recursive: true });
+    const before = readText(dest);
+    const rendered = readFileSync(source, 'utf8');
+    const previous = priorFiles.find((entry) => entry?.path === dest);
+    let backupFile = previous?.backup ?? null;
+    if (before !== rendered) {
+      if (before !== null && !backupFile) backupFile = backup(dest);
+      writeFileSync(dest, rendered);
+    }
+    actions.push(dest);
+    records.push({
+      path: dest,
+      preexisting: previous?.preexisting === true || (previous === undefined && before !== null),
+      ...(backupFile ? { backup: backupFile } : {}),
+      managed_sha256: contentHash(rendered),
+    });
+  }
+  return { ok: true, actions, records };
+}
+
+function updateMcp({ home, root }) {
+  const source = configSource({ home });
+  const target = expectedTarget({ root });
+  const current = source.servers[SERVER];
+  const currentTarget = serverTarget(current);
+  const owned = ownership({ home });
+  if (current && currentTarget !== target) {
+    // Only an exact previously-owned entry may be repaired. Any foreign
+    // command, even if it is also named dsh-crew, is a hard collision.
+    if (!(owned && owned.config_file === source.file && normalizePath(owned.target) === currentTarget)) {
+      return { ok: false, code: 'ZCODE_MCP_COLLISION', config_file: source.file };
+    }
+  }
+
+  const next = { ...source.config };
+  if (source.kind === 'native') next.mcp = { ...(next.mcp ?? {}), servers: { ...source.servers, [SERVER]: { command: 'node', args: [target] } } };
+  else next.mcpServers = { ...source.servers, [SERVER]: { command: 'node', args: [target] } };
+  const changed = JSON.stringify(next) !== JSON.stringify(source.config);
+  if (changed) { backup(source.file); writeJson(source.file, next); }
+  return { ok: true, changed, config_file: source.file, config_kind: source.kind, target };
+}
+
+export function installZCode({ home = homedir(), root = ROOT } = {}) {
+  const templates = templateFiles({ home, root });
+  const missing = templates.find(({ source }) => !existsSync(source));
+  if (missing) return { ok: false, code: 'ZCODE_TEMPLATE_MISSING', source: missing.source };
+  const priorFiles = ownership({ home })?.files ?? [];
+  // Check for collisions before writing any other integration surface so a
+  // failed install is transaction-like and leaves user files untouched.
+  const mcp = updateMcp({ home, root });
+  if (!mcp.ok) return mcp;
+  const policy = installPolicy({ home, root });
+  if (!policy.ok) return policy;
+  const installed = installTemplates({ home, root, priorFiles });
+  if (!installed.ok) return installed;
+  writeOwnership({
+    home,
+    configFile: mcp.config_file,
+    configKind: mcp.config_kind,
+    target: mcp.target,
+    files: installed.records,
+  });
+  return { ok: true, ...mcp, policy_file: policy.file, files: installed.actions };
+}
+
+function zcodeComponents({ home = homedir(), root = ROOT } = {}) {
+  const expected = normalizePath(expectedTarget({ root }));
+  const source = configSource({ home });
+  const configured = serverTarget(source.servers[SERVER]);
+  const owned = ownership({ home });
+  const components = {
+    mcp: configured === expected,
+    policy: typeof readText(join(home, '.zcode', 'AGENTS.md')) === 'string' && readText(join(home, '.zcode', 'AGENTS.md')).includes(POLICY_START),
+    worker_agent: existsSync(join(home, '.zcode', 'agents', 'ds-worker.md')),
+    reviewer_agent: existsSync(join(home, '.zcode', 'agents', 'ds-reviewer.md')),
+    config_prompt: existsSync(join(home, '.zcode', 'commands', 'dsh-config.md')),
+    status_prompt: existsSync(join(home, '.zcode', 'commands', 'dsh-status.md')),
+    ownership: !!owned && owned.config_file === source.file && normalizePath(owned.target) === expected,
+  };
+  return { components, source, expected, configured, owned };
+}
+
+export function zcodeStatus({ home = homedir(), root = ROOT } = {}) {
+  const { components, source, expected, configured } = zcodeComponents({ home, root });
+  const missing = Object.entries(components).filter(([, value]) => !value).map(([key]) => key);
+  const installed = Object.values(components).some(Boolean);
+  return {
+    installed,
+    ready: missing.length === 0,
+    components,
+    missing,
+    config_file: source.file,
+    config_kind: source.kind,
+    target: configured ?? expected,
+  };
+}
+
+export function uninstallZCode({ home = homedir() } = {}) {
+  const actions = [];
+  const owned = ownership({ home });
+  if (owned) {
+    const file = owned.config_file;
+    const config = readJson(file, null);
+    if (config && typeof config === 'object') {
+      const kind = owned.config_kind === 'shared' ? 'shared' : 'native';
+      const servers = kind === 'shared' ? sharedServers(config) : nativeServers(config);
+      const current = servers[SERVER];
+      if (normalizePath(owned.target) === serverTarget(current)) {
+        const next = { ...config };
+        if (kind === 'shared') {
+          next.mcpServers = { ...servers }; delete next.mcpServers[SERVER];
+          if (Object.keys(next.mcpServers).length === 0) delete next.mcpServers;
+        } else {
+          next.mcp = { ...(next.mcp ?? {}), servers: { ...servers } }; delete next.mcp.servers[SERVER];
+          if (Object.keys(next.mcp.servers).length === 0) delete next.mcp.servers;
+          if (Object.keys(next.mcp).length === 0) delete next.mcp;
+        }
+        backup(file); writeJson(file, next); actions.push(`mcp: removed ${SERVER} from ${file}`);
+      }
+    }
+    rmSync(OWNERSHIP_FILE({ home }), { force: true });
+  }
+  if (removePolicy({ home })) actions.push('policy: removed managed ZCode block');
+  const managedFiles = Array.isArray(owned?.files) && owned.files.length
+    ? owned.files
+    : ['agents/ds-worker.md', 'agents/ds-reviewer.md', 'commands/dsh-config.md', 'commands/dsh-status.md']
+      .map((rel) => ({ path: join(home, '.zcode', rel) }));
+  for (const entry of managedFiles) {
+    const file = entry?.path;
+    if (!file || !existsSync(file)) continue;
+    const current = readText(file);
+    const unchanged = !entry.managed_sha256 || (current !== null && contentHash(current) === entry.managed_sha256);
+    if (!unchanged) continue;
+    if (entry.preexisting && entry.backup && existsSync(entry.backup)) {
+      copyFileSync(entry.backup, file);
+      actions.push(`restored: ${file}`);
+    } else {
+      rmSync(file, { force: true });
+      actions.push(`removed: ${file}`);
+    }
+  }
+  return { ok: true, actions };
+}
+
+export function zcodeOwnershipFile({ home = homedir() } = {}) { return OWNERSHIP_FILE({ home }); }