@wipcomputer/wip-ldm-os 0.4.73-alpha.3 → 0.4.73-alpha.31

package/bin/ldm.js

@@ -20,7 +20,7 @@
  *   ldm --version         Show version
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync, lstatSync, symlinkSync } from 'node:fs';
 import { join, basename, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -350,7 +350,7 @@ function cleanStaleHooks() {
 
 function syncBootHook() {
   const srcBoot = join(__dirname, '..', 'src', 'boot', 'boot-hook.mjs');
-  const destBoot = join(LDM_ROOT, 'shared', 'boot', 'boot-hook.mjs');
+  const destBoot = join(LDM_ROOT, 'library', 'boot', 'boot-hook.mjs');
 
   if (!existsSync(srcBoot)) return false;
 
@@ -368,6 +368,176 @@ function syncBootHook() {
   return false;
 }
 
+// ── Inbox check hook sync ──
+//
+// Deploys src/hooks/inbox-check-hook.mjs to ~/.ldm/library/hooks/ and
+// wires it into ~/.claude/settings.json as a UserPromptSubmit hook so
+// that pending bridge messages in ~/.ldm/messages/ are surfaced as
+// additionalContext before CC responds to each user prompt.
+//
+// Closes the loop between lesa-bridge fire-and-forget sends and
+// CC-side message delivery. Without this hook, Claude Code only sees
+// bridge messages when it explicitly calls lesa_check_inbox, which
+// requires manual discipline and loses messages in practice.
+//
+// Idempotent: subsequent installs update the file only if its contents
+// changed, and only add the settings.json entry if it isn't already
+// wired to the exact same command path.
+//
+// See:
+//   ai/product/plans-prds/bridge/2026-04-06--cc-mini--bridge-master-product-plan.md
+//   ai/product/bugs/bridge/2026-04-06--cc-mini--bridge-async-inbox-plan.md
+//   ai/product/bugs/bridge/2026-04-10--cc-mini--bridge-reply-addressing-mismatch.md
+function syncInboxCheckHook() {
+  const srcHook = join(__dirname, '..', 'src', 'hooks', 'inbox-check-hook.mjs');
+  const destHook = join(LDM_ROOT, 'library', 'hooks', 'inbox-check-hook.mjs');
+  let changed = false;
+
+  if (!existsSync(srcHook)) return false;
+
+  // 1. File deploy: copy src/hooks/inbox-check-hook.mjs to ~/.ldm/library/hooks/
+  try {
+    const srcContent = readFileSync(srcHook, 'utf8');
+    let destContent = '';
+    try { destContent = readFileSync(destHook, 'utf8'); } catch {}
+
+    if (srcContent !== destContent) {
+      mkdirSync(dirname(destHook), { recursive: true });
+      writeFileSync(destHook, srcContent);
+      changed = true;
+    }
+  } catch {
+    return false;
+  }
+
+  // 2. Settings.json patch: wire the hook into hooks.UserPromptSubmit if absent.
+  const settingsPath = join(HOME, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return changed;
+
+  try {
+    const raw = readFileSync(settingsPath, 'utf8');
+    const settings = JSON.parse(raw);
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+    const hookCommand = `node ${destHook}`;
+    const alreadyWired = settings.hooks.UserPromptSubmit.some(group =>
+      Array.isArray(group.hooks) &&
+      group.hooks.some(h => h.type === 'command' && h.command === hookCommand)
+    );
+
+    if (!alreadyWired) {
+      settings.hooks.UserPromptSubmit.push({
+        hooks: [{
+          type: 'command',
+          command: hookCommand,
+          timeout: 5,
+        }],
+      });
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      changed = true;
+    }
+  } catch {
+    // Settings file malformed or unreadable. File deploy still succeeded
+    // if changed was true; leave settings.json untouched and let the user
+    // see the file deploy message without the wire-up.
+  }
+
+  return changed;
+}
+
+// ── Inbox rewake hook sync ──
+//
+// Deploys src/hooks/inbox-rewake-hook.mjs to ~/.ldm/library/hooks/ and
+// wires it into ~/.claude/settings.json as a Stop hook with
+// `asyncRewake: true`. This is the autonomous push layer that wakes
+// an idle Claude Code session when a bridge message arrives, without
+// the user having to type anything.
+//
+// Mechanics: the Stop hook fires after every CC turn. The rewake hook
+// acquires a per-session lock file (so concurrent Stop-event spawns do
+// not stack), then holds a long-lived fs.watch on ~/.ldm/messages/.
+// When a matching message file arrives, the hook writes the message to
+// stderr and exits with code 2. The CC harness wraps that stderr into
+// a system-reminder task-notification that wakes the idle model or
+// gets injected mid-query if the model is busy. See Claude Code's
+// `src/utils/hooks.ts` asyncRewake path for the exact mechanism.
+//
+// This closes the layer 1 gap from:
+//   ai/product/plans-prds/bridge/2026-04-11--cc-mini--autonomous-push-architecture.md
+//
+// Layers 2-4 (UserPromptSubmit inbox-check hook, SessionStart boot
+// hook, manual lesa_check_inbox) remain as independent fallbacks.
+//
+// Idempotent: subsequent installs update the file only if its contents
+// changed, and only add the settings.json entry if it isn't already
+// wired to the exact same command path.
+function syncInboxRewakeHook() {
+  const srcHook = join(__dirname, '..', 'src', 'hooks', 'inbox-rewake-hook.mjs');
+  const destHook = join(LDM_ROOT, 'library', 'hooks', 'inbox-rewake-hook.mjs');
+  let changed = false;
+
+  if (!existsSync(srcHook)) return false;
+
+  // 1. File deploy: copy src/hooks/inbox-rewake-hook.mjs to ~/.ldm/library/hooks/
+  try {
+    const srcContent = readFileSync(srcHook, 'utf8');
+    let destContent = '';
+    try { destContent = readFileSync(destHook, 'utf8'); } catch {}
+
+    if (srcContent !== destContent) {
+      mkdirSync(dirname(destHook), { recursive: true });
+      writeFileSync(destHook, srcContent);
+      changed = true;
+    }
+  } catch {
+    return false;
+  }
+
+  // 2. Settings.json patch: wire the hook into hooks.Stop as an
+  //    asyncRewake background hook if absent.
+  const settingsPath = join(HOME, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return changed;
+
+  try {
+    const raw = readFileSync(settingsPath, 'utf8');
+    const settings = JSON.parse(raw);
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.Stop) settings.hooks.Stop = [];
+
+    const hookCommand = `node ${destHook}`;
+    const alreadyWired = settings.hooks.Stop.some(group =>
+      Array.isArray(group.hooks) &&
+      group.hooks.some(h =>
+        h.type === 'command' &&
+        h.command === hookCommand &&
+        h.asyncRewake === true,
+      ),
+    );
+
+    if (!alreadyWired) {
+      settings.hooks.Stop.push({
+        hooks: [{
+          type: 'command',
+          command: hookCommand,
+          async: true,
+          asyncRewake: true,
+          // 6 hours: matches the rewake hook's internal hard timeout.
+          // The hook self-terminates well before this on parent death,
+          // hard cancel, or match, so this is just a runaway guard.
+          timeout: 21600,
+        }],
+      });
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      changed = true;
+    }
+  } catch {
+    // Settings file malformed or unreadable. Leave it alone.
+  }
+
+  return changed;
+}
+
 // ── Catalog helpers ──
 
 function loadCatalog() {
@@ -544,20 +714,14 @@ function deployDocs() {
     return count;
   }
 
-  // Deploy to settings/docs/ (agent reference)
-  const docsDest = join(workspacePath, 'settings', 'docs');
-  const docsCount = renderTemplates(docsDest);
-  if (docsCount > 0) {
-    console.log(`  + ${docsCount} personalized doc(s) deployed to ${docsDest.replace(HOME, '~')}/`);
-  }
-
-  // Deploy to library/documentation/ (human-readable library copy)
+  // Deploy to library/documentation/ (the canonical doc path since Mar 28 rename).
+  // Previously also deployed to settings/docs/ which Parker renamed to library/documentation/.
+  // That created a ghost folder on every install. Removed 2026-04-05 per INST-1.
   const libraryDest = join(workspacePath, 'library', 'documentation');
-  if (existsSync(join(workspacePath, 'library'))) {
-    const libCount = renderTemplates(libraryDest);
-    if (libCount > 0) {
-      console.log(`  + ${libCount} doc(s) deployed to ${libraryDest.replace(HOME, '~')}/`);
-    }
+  mkdirSync(libraryDest, { recursive: true });
+  const docsCount = renderTemplates(libraryDest);
+  if (docsCount > 0) {
+    console.log(`  + ${docsCount} personalized doc(s) deployed to ${libraryDest.replace(HOME, '~')}/`);
   }
 
   return docsCount;
@@ -632,17 +796,58 @@ function checkBackupHealth() {
 // After `npm install -g`, the updated files live at the npm package location but
 // never get copied to ~/.ldm/extensions/lesa-bridge/dist/. This function fixes that.
 
+function deployRules() {
+  const rulesSrc = join(__dirname, '..', 'shared', 'rules');
+  const rulesDest = join(LDM_ROOT, 'library', 'rules');
+  if (!existsSync(rulesSrc)) return;
+  mkdirSync(rulesDest, { recursive: true });
+  let rulesCount = 0;
+  for (const file of readdirSync(rulesSrc)) {
+    if (!file.endsWith('.md')) continue;
+    cpSync(join(rulesSrc, file), join(rulesDest, file));
+    rulesCount++;
+  }
+  if (rulesCount > 0) {
+    console.log(`  + ${rulesCount} shared rules deployed to ~/.ldm/library/rules/`);
+    // Deploy to Claude Code harness (~/.claude/rules/)
+    const claudeRules = join(HOME, '.claude', 'rules');
+    if (existsSync(join(HOME, '.claude'))) {
+      mkdirSync(claudeRules, { recursive: true });
+      for (const file of readdirSync(rulesDest)) {
+        if (!file.endsWith('.md')) continue;
+        cpSync(join(rulesDest, file), join(claudeRules, file));
+      }
+      console.log(`  + rules deployed to ~/.claude/rules/`);
+    }
+    // Deploy to OpenClaw harness (~/.openclaw/workspace/DEV-RULES.md)
+    const ocWorkspace = join(HOME, '.openclaw', 'workspace');
+    if (existsSync(ocWorkspace)) {
+      let combined = '# Dev Rules (deployed by ldm install)\n\n';
+      combined += '> Do not edit this file. It is regenerated by `ldm install`.\n';
+      combined += '> Source: ~/.ldm/library/rules/\n\n';
+      for (const file of readdirSync(rulesDest).sort()) {
+        if (!file.endsWith('.md')) continue;
+        combined += readFileSync(join(rulesDest, file), 'utf8') + '\n\n---\n\n';
+      }
+      writeFileSync(join(ocWorkspace, 'DEV-RULES.md'), combined);
+      console.log(`  + rules deployed to ~/.openclaw/workspace/DEV-RULES.md`);
+    }
+  }
+}
+
 function deployBridge() {
   const ldmBridgeDir = join(LDM_EXTENSIONS, 'lesa-bridge');
   const ocBridgeDir = join(HOME, '.openclaw', 'extensions', 'lesa-bridge');
 
   // Deploy targets: LDM path (canonical) and OpenClaw path (where the plugin loads)
+  // Create dirs if missing so first-time deploy works (don't skip with filter)
   const targets = [
     { dir: ldmBridgeDir, label: '~/.ldm/extensions/lesa-bridge/dist/' },
     { dir: ocBridgeDir, label: '~/.openclaw/extensions/lesa-bridge/dist/' },
-  ].filter(t => existsSync(t.dir)); // Only deploy if the extension dir exists
-
-  if (targets.length === 0) return 0;
+  ];
+  for (const t of targets) {
+    if (!existsSync(t.dir)) mkdirSync(t.dir, { recursive: true });
+  }
 
   // Find the npm package bridge files. Try require.resolve first, fall back to known path.
   let bridgeSrc = '';
@@ -773,10 +978,10 @@ async function cmdInit() {
     join(LDM_ROOT, 'state'),
     join(LDM_ROOT, 'sessions'),
     join(LDM_ROOT, 'messages'),
-    join(LDM_ROOT, 'shared', 'boot'),
-    join(LDM_ROOT, 'shared', 'cron'),
-    join(LDM_ROOT, 'shared', 'rules'),
-    join(LDM_ROOT, 'shared', 'prompts'),
+    join(LDM_ROOT, 'library', 'boot'),
+    join(LDM_ROOT, 'library', 'cron'),
+    join(LDM_ROOT, 'library', 'rules'),
+    join(LDM_ROOT, 'library', 'prompts'),
     join(LDM_ROOT, 'hooks'),
   ];
 
@@ -820,10 +1025,16 @@ async function cmdInit() {
     // Scaffold workspace output dirs if workspace is configured
     const workspace = config.workspace;
     if (workspace && existsSync(workspace)) {
-      // Per-agent workspace dirs
-      const agentNameMap = { 'cc-mini': 'cc-mini', 'cc-air': 'cc-air', 'oc-lesa-mini': 'Lēsa' };
+      // Per-agent workspace dirs.
+      // Resolve the team folder name from config.json agents[id].teamFolder
+      // so agents with unicode names or custom folder names don't get ghost
+      // folders created from their agent ID. Falls back to agent ID if no
+      // override is configured. Fixed 2026-04-05 per INST-1: previously
+      // hardcoded a map that only knew three agents and created ghost folders
+      // for any others.
       for (const agentId of agentList) {
-        const teamName = agentNameMap[agentId] || agentId;
+        const agentObj = typeof agentsObj[agentId] === 'object' ? agentsObj[agentId] : {};
+        const teamName = agentObj.teamFolder || agentObj.name || agentId;
         for (const sub of ['journals', 'automated/memory/summaries/daily', 'automated/memory/summaries/weekly', 'automated/memory/summaries/monthly', 'automated/memory/summaries/quarterly']) {
           dirs.push(join(workspace, 'team', teamName, sub));
         }
@@ -944,68 +1155,29 @@ async function cmdInit() {
   // Deploy all scripts from scripts/ to ~/.ldm/bin/ (#119)
   deployScripts();
 
-  // Deploy shared rules to ~/.ldm/shared/rules/ and to harnesses
-  const rulesSrc = join(__dirname, '..', 'shared', 'rules');
-  const rulesDest = join(LDM_ROOT, 'shared', 'rules');
-  if (existsSync(rulesSrc)) {
-    mkdirSync(rulesDest, { recursive: true });
-    let rulesCount = 0;
-    for (const file of readdirSync(rulesSrc)) {
-      if (!file.endsWith('.md')) continue;
-      cpSync(join(rulesSrc, file), join(rulesDest, file));
-      rulesCount++;
-    }
-    if (rulesCount > 0) {
-      console.log(`  + ${rulesCount} shared rules deployed to ~/.ldm/shared/rules/`);
-
-      // Deploy to Claude Code harness (~/.claude/rules/)
-      const claudeRules = join(HOME, '.claude', 'rules');
-      if (existsSync(join(HOME, '.claude'))) {
-        mkdirSync(claudeRules, { recursive: true });
-        for (const file of readdirSync(rulesDest)) {
-          if (!file.endsWith('.md')) continue;
-          cpSync(join(rulesDest, file), join(claudeRules, file));
-        }
-        console.log(`  + rules deployed to ~/.claude/rules/`);
-      }
-
-      // Deploy to OpenClaw harness (~/.openclaw/workspace/DEV-RULES.md)
-      const ocWorkspace = join(HOME, '.openclaw', 'workspace');
-      if (existsSync(ocWorkspace)) {
-        let combined = '# Dev Rules (deployed by ldm install)\n\n';
-        combined += '> Do not edit this file. It is regenerated by `ldm install`.\n';
-        combined += '> Source: ~/.ldm/shared/rules/\n\n';
-        for (const file of readdirSync(rulesDest).sort()) {
-          if (!file.endsWith('.md')) continue;
-          combined += readFileSync(join(rulesDest, file), 'utf8') + '\n\n---\n\n';
-        }
-        writeFileSync(join(ocWorkspace, 'DEV-RULES.md'), combined);
-        console.log(`  + rules deployed to ~/.openclaw/workspace/DEV-RULES.md`);
-      }
-    }
-  }
+  deployRules();
 
-  // Deploy boot-config.json to ~/.ldm/shared/boot/
+  // Deploy boot-config.json to ~/.ldm/library/boot/
   const bootSrc = join(__dirname, '..', 'shared', 'boot');
-  const bootDest = join(LDM_ROOT, 'shared', 'boot');
+  const bootDest = join(LDM_ROOT, 'library', 'boot');
   if (existsSync(bootSrc)) {
     mkdirSync(bootDest, { recursive: true });
     const bootConfig = join(bootSrc, 'boot-config.json');
     if (existsSync(bootConfig)) {
       cpSync(bootConfig, join(bootDest, 'boot-config.json'));
-      console.log(`  + boot-config.json deployed to ~/.ldm/shared/boot/`);
+      console.log(`  + boot-config.json deployed to ~/.ldm/library/boot/`);
     }
   }
 
-  // Deploy Level 1 CLAUDE.md template to ~/.claude/CLAUDE.md
-  const claudeMdTemplate = join(__dirname, '..', 'shared', 'templates', 'claude-md-level1.md');
-  const claudeMdDest = join(HOME, '.claude', 'CLAUDE.md');
-  if (existsSync(claudeMdTemplate) && existsSync(join(HOME, '.claude'))) {
-    cpSync(claudeMdTemplate, claudeMdDest);
-    console.log(`  + Level 1 CLAUDE.md deployed to ~/.claude/CLAUDE.md`);
-  }
+  // CLAUDE.md files are NEVER deployed by the installer.
+  // They are git-tracked files in their respective repos:
+  //   ~/.claude/CLAUDE.md           ... wipcomputer-ldmos-wipcomputerinc-dot-claude-private
+  //   ~/wipcomputerinc/CLAUDE.md    ... wipcomputerinc repo
+  //   ~/.openclaw/CLAUDE.md         ... openclaw repo
+  // Changes go through branches and PRs like any other file.
+  // See: 2026-03-27--cc-mini--single-source-of-truth-reversed.md
 
-  // Deploy shared templates to workspace settings/templates/
+  // Deploy shared templates to workspace library/templates/
   const templatesSrc = join(__dirname, '..', 'shared', 'templates');
   if (existsSync(templatesSrc)) {
     // Read workspace path from ~/.ldm/config.json
@@ -1015,7 +1187,7 @@ async function cmdInit() {
       workspacePath = (ldmConfig.workspace || '').replace('~', HOME);
     } catch {}
     if (workspacePath && existsSync(workspacePath)) {
-      const templatesDest = join(workspacePath, 'settings', 'templates');
+      const templatesDest = join(workspacePath, 'library', 'templates');
       mkdirSync(templatesDest, { recursive: true });
       let templatesCount = 0;
       for (const file of readdirSync(templatesSrc)) {
@@ -1029,9 +1201,9 @@ async function cmdInit() {
     }
   }
 
-  // Deploy shared prompts to ~/.ldm/shared/prompts/
+  // Deploy shared prompts to ~/.ldm/library/prompts/
   const promptsSrc = join(__dirname, '..', 'shared', 'prompts');
-  const promptsDest = join(LDM_ROOT, 'shared', 'prompts');
+  const promptsDest = join(LDM_ROOT, 'library', 'prompts');
   if (existsSync(promptsSrc)) {
     mkdirSync(promptsDest, { recursive: true });
     let promptsCount = 0;
@@ -1041,7 +1213,33 @@ async function cmdInit() {
       promptsCount++;
     }
     if (promptsCount > 0) {
-      console.log(`  + ${promptsCount} shared prompts deployed to ~/.ldm/shared/prompts/`);
+      console.log(`  + ${promptsCount} shared prompts deployed to ~/.ldm/library/prompts/`);
+    }
+  }
+
+  // Backward-compat symlink: ~/.ldm/shared -> ~/.ldm/library
+  // Anything still referencing shared/ will follow the symlink
+  {
+    const sharedPath = join(LDM_ROOT, 'shared');
+    const libraryPath = join(LDM_ROOT, 'library');
+    try {
+      const stat = lstatSync(sharedPath);
+      if (stat.isSymbolicLink()) {
+        // Already a symlink, update target if needed
+        const target = readlinkSync(sharedPath);
+        if (target !== libraryPath) {
+          unlinkSync(sharedPath);
+          symlinkSync(libraryPath, sharedPath);
+        }
+      } else if (stat.isDirectory()) {
+        // shared/ is a real directory (pre-rename state). Don't touch it.
+        // The migration will handle this in a dedicated session.
+      }
+    } catch {
+      // shared/ doesn't exist. Create symlink.
+      try {
+        symlinkSync(libraryPath, sharedPath);
+      } catch {}
     }
   }
 
@@ -1321,23 +1519,31 @@ async function cmdInstall() {
 
   // Check if target looks like an npm package (starts with @ or is a plain name without /)
   if (resolvedTarget.startsWith('@') || (!resolvedTarget.includes('/') && !existsSync(resolve(resolvedTarget)))) {
-    // Try npm install to temp dir
+    // Try npm pack + tar extract to temp dir
+    // npm install --prefix silently fails for scoped packages in temp directories...
+    // it creates the lock file but doesn't extract files. npm pack is reliable.
     const npmName = resolvedTarget;
     const tempDir = join(LDM_TMP, `npm-${Date.now()}`);
     console.log('');
     console.log(`  Installing ${npmName} from npm...`);
     try {
       mkdirSync(tempDir, { recursive: true });
-      execSync(`npm install ${npmName} --prefix "${tempDir}"`, { stdio: 'pipe' });
-      // Find the installed package in node_modules
-      const pkgName = npmName.startsWith('@') ? npmName : npmName;
-      const installed = join(tempDir, 'node_modules', pkgName);
-      if (existsSync(installed)) {
-        console.log(`  + Installed from npm`);
-        repoPath = installed;
+      // Use npm pack + tar instead of npm install --prefix
+      const tarball = execSync(`npm pack ${npmName} --pack-destination "${tempDir}" 2>/dev/null`, {
+        encoding: 'utf8', timeout: 60000, cwd: tempDir,
+      }).trim();
+      const tarPath = join(tempDir, tarball);
+      if (existsSync(tarPath)) {
+        execSync(`tar xzf "${tarPath}" -C "${tempDir}"`, { stdio: 'pipe' });
+        const extracted = join(tempDir, 'package');
+        if (existsSync(extracted)) {
+          console.log(`  + Installed from npm`);
+          repoPath = extracted;
+        } else {
+          console.error(`  x npm pack succeeded but extraction failed`);
+        }
       } else {
-        console.error(`  x Package installed but not found at expected path`);
-        process.exit(1);
+        console.error(`  x npm pack failed: tarball not found`);
       }
     } catch (e) {
       // npm failed, fall through to git clone or path resolution
@@ -1596,9 +1802,10 @@ async function cmdInstallCatalog() {
   // in the extension directories. This copies them to both LDM and OpenClaw targets.
   deployBridge();
 
-  // Deploy scripts and docs on every install so fixes land without re-init
+  // Deploy scripts, docs, and rules on every install so fixes land without re-init
   deployScripts();
   deployDocs();
+  deployRules();
 
   // Check backup configuration
   checkBackupHealth();
@@ -2206,13 +2413,56 @@ async function cmdInstallCatalog() {
       continue;
     }
 
-    if (!entry.catalogRepo) {
+    if (!entry.catalogRepo && !entry.catalogNpm) {
       console.log(`  Skipping ${entry.name}: no catalog repo (install manually with ldm install <org/repo>)`);
       continue;
     }
-    console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+
+    // Source resolution chain (#264):
+    // 1. npm (when --alpha/--beta or npm package available) - works online, any machine
+    // 2. Local private repo (offline, developer machine) - works without internet
+    // 3. GitHub clone (fallback) - works online, any machine
+    let installSource = null;
+    const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : null;
+
+    // Try npm first when using alpha/beta tracks or when npm is available
+    if (entry.catalogNpm && (npmTag || !entry.catalogRepo)) {
+      const ver = npmTag ? `${entry.catalogNpm}@${npmTag}` : `${entry.catalogNpm}@${entry.latestVersion}`;
+      installSource = ver;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from npm ${npmTag || 'latest'})...`);
+    }
+
+    // Try local private repo (for offline/developer installs)
+    if (!installSource && entry.catalogRepo) {
+      const repoName = basename(entry.catalogRepo);
+      const privateRepoName = repoName + '-private';
+      const WORKSPACE = join(HOME, 'wipcomputerinc');
+      // Search known repo locations
+      const searchDirs = ['repos/ldm-os/devops', 'repos/ldm-os/components', 'repos/ldm-os/utilities', 'repos/ldm-os/apps', 'repos/ldm-os/apis', 'repos/ldm-os/identity'];
+      for (const dir of searchDirs) {
+        const localPrivate = join(WORKSPACE, dir, privateRepoName);
+        const localPublic = join(WORKSPACE, dir, repoName);
+        if (existsSync(localPrivate)) {
+          installSource = localPrivate;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${privateRepoName})...`);
+          break;
+        }
+        if (existsSync(localPublic)) {
+          installSource = localPublic;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${repoName})...`);
+          break;
+        }
+      }
+    }
+
+    // Fallback: GitHub clone
+    if (!installSource) {
+      installSource = entry.catalogRepo;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+    }
+
     try {
-      execSync(`ldm install ${entry.catalogRepo}`, { stdio: 'inherit' });
+      execSync(`ldm install ${installSource}`, { stdio: 'inherit' });
       updated++;
 
       // For parent packages, update registry version for all sub-tools (#139, #262)
@@ -2326,7 +2576,32 @@ async function cmdInstallCatalog() {
 
   // Sync boot hook from npm package (#49)
   if (syncBootHook()) {
-    ok('Boot hook updated (sessions, messages, updates now active)');
+    console.log('  + Boot hook updated (sessions, messages, updates now active)');
+  }
+
+  // Sync inbox-check hook: UserPromptSubmit hook that surfaces pending
+  // bridge messages into CC context on every prompt. Closes the gap
+  // between lesa-bridge writes and CC delivery.
+  if (syncInboxCheckHook()) {
+    console.log('  + Inbox-check hook updated (bridge messages surface automatically)');
+  }
+
+  // Sync inbox-rewake hook: Stop hook with asyncRewake that watches
+  // ~/.ldm/messages/ in the background and wakes the model when a new
+  // bridge message arrives, without requiring user interaction. Layer 1
+  // of the April 11 autonomous-push-architecture plan.
+  if (syncInboxRewakeHook()) {
+    console.log('  + Inbox-rewake hook updated (autonomous push: wakes on new bridge message)');
+  }
+
+  // Deploy git pre-commit hook on every install (not just init)
+  const hooksDir = join(LDM_ROOT, 'hooks');
+  const preCommitDest = join(hooksDir, 'pre-commit');
+  const preCommitSrc = join(__dirname, '..', 'templates', 'hooks', 'pre-commit');
+  if (existsSync(preCommitSrc)) {
+    if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+    cpSync(preCommitSrc, preCommitDest);
+    chmodSync(preCommitDest, 0o755);
   }
 
   console.log('');
@@ -3814,6 +4089,145 @@ async function main() {
     process.exit(1);
   }
 
+  // ── ldm pair ────────────────────────────────────────────────────────
+  // Device pairing for Bridge Phase A.
+  // Links this machine to the user's Kaleidoscope account via passkey.
+  //
+  // Flow:
+  //   1. Generate a human-readable code (BLUE-FISH-4729)
+  //   2. POST the code to wip.computer/api/pair/request
+  //   3. User goes to wip.computer/pair on their phone, signs in with passkey, enters code
+  //   4. Poll GET /api/pair/status?code=X until approved or expired
+  //   5. Store the device token at ~/.ldm/auth/kaleidoscope.json
+  //
+  // The code is shown in the terminal. The user navigates to the pairing
+  // page themselves (CC does NOT open a URL, to prevent phishing).
+  // The code expires after 120 seconds.
+
+  async function cmdPair() {
+    const PAIR_API = process.env.LDM_PAIR_API || 'https://wip.computer';
+    const AUTH_DIR = join(LDM_ROOT, 'auth');
+    const TOKEN_PATH = join(AUTH_DIR, 'kaleidoscope.json');
+
+    // Check if already paired
+    if (existsSync(TOKEN_PATH)) {
+      try {
+        const existing = JSON.parse(readFileSync(TOKEN_PATH, 'utf8'));
+        if (existing.token) {
+          console.log('');
+          console.log(`  Already paired as ${existing.userName || 'unknown'}`);
+          console.log(`  Paired: ${existing.pairedAt || 'unknown'}`);
+          console.log(`  Token: ${existing.token.slice(0, 8)}...`);
+          console.log('');
+          console.log('  To re-pair, delete ~/.ldm/auth/kaleidoscope.json and run ldm pair again.');
+          console.log('');
+          return;
+        }
+      } catch {}
+    }
+
+    // Generate code
+    const words = [
+      'BLUE', 'RED', 'GREEN', 'GOLD', 'GRAY', 'PINK', 'DARK', 'WARM', 'COLD', 'WILD',
+      'FISH', 'BIRD', 'WOLF', 'BEAR', 'DEER', 'HAWK', 'FROG', 'LYNX', 'DOVE', 'CROW',
+    ];
+    const w1 = words[Math.floor(Math.random() * 10)];
+    const w2 = words[10 + Math.floor(Math.random() * 10)];
+    const num = String(Math.floor(1000 + Math.random() * 9000));
+    const code = `${w1}-${w2}-${num}`;
+
+    // Detect device name
+    const { hostname } = await import('node:os');
+    const deviceName = hostname() || 'unknown';
+
+    // Read agent ID from config
+    let agentId = 'cc-mini';
+    try {
+      const config = JSON.parse(readFileSync(join(LDM_ROOT, 'config.json'), 'utf8'));
+      const agents = config.agents || {};
+      for (const [id, agent] of Object.entries(agents)) {
+        if (agent.harness === 'claude-code') { agentId = id; break; }
+      }
+    } catch {}
+
+    console.log('');
+    console.log('  Pairing code:');
+    console.log('');
+    console.log(`    ${code}`);
+    console.log('');
+    console.log('  Go to wip.computer/pair on your phone.');
+    console.log('  Sign in with your passkey. Enter the code.');
+    console.log('');
+    console.log('  Waiting for approval...');
+
+    // Register the code with the server
+    try {
+      const registerRes = await fetch(`${PAIR_API}/api/pair/request`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code, deviceName, agentId }),
+      });
+      if (!registerRes.ok) {
+        const err = await registerRes.text();
+        console.error(`  x Failed to register pairing code: ${err}`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(`  x Cannot reach ${PAIR_API}: ${err.message}`);
+      console.error('  Make sure the server is running.');
+      process.exit(1);
+    }
+
+    // Poll for approval (every 2 seconds, up to 120 seconds)
+    const maxAttempts = 60;
+    for (let i = 0; i < maxAttempts; i++) {
+      await new Promise(r => setTimeout(r, 2000));
+
+      try {
+        const statusRes = await fetch(`${PAIR_API}/api/pair/status?code=${encodeURIComponent(code)}`);
+        const data = await statusRes.json();
+
+        if (data.status === 'approved' && data.token) {
+          // Store token
+          mkdirSync(AUTH_DIR, { recursive: true });
+          writeFileSync(TOKEN_PATH, JSON.stringify({
+            token: data.token,
+            userId: data.userId,
+            userName: data.userName,
+            deviceName,
+            agentId,
+            pairedAt: new Date().toISOString(),
+            server: PAIR_API,
+          }, null, 2) + '\n');
+
+          console.log('');
+          console.log(`  ✓ Paired as ${data.userName || 'User'} (${deviceName} / ${agentId})`);
+          console.log(`  Token stored at ~/.ldm/auth/kaleidoscope.json`);
+          console.log('');
+          return;
+        }
+
+        if (statusRes.status === 404 || statusRes.status === 410) {
+          console.error('');
+          console.error('  x Code expired. Run ldm pair again.');
+          console.error('');
+          process.exit(1);
+        }
+
+        // Still pending. Keep polling.
+        process.stdout.write('.');
+      } catch {
+        // Network error. Keep trying.
+        process.stdout.write('x');
+      }
+    }
+
+    console.error('');
+    console.error('  x Timed out waiting for approval. Run ldm pair again.');
+    console.error('');
+    process.exit(1);
+  }
+
   if (command === '--version' || command === '-v') {
     console.log(PKG_VERSION);
     process.exit(0);
@@ -3866,6 +4280,9 @@ async function main() {
     case 'backup':
       await cmdBackup();
       break;
+    case 'pair':
+      await cmdPair();
+      break;
     default:
       console.error(`  Unknown command: ${command}`);
       console.error(`  Run: ldm --help`);