@wipcomputer/wip-ldm-os 0.4.81 → 0.4.83

package/scripts/test-bin-manifest.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// Regression test: bin ownership manifest aggregator + heal + integration.
+//
+// Unit: aggregateBinManifest, healBinManifest, validateDeclarations.
+// Integration: real `node bin/ldm.js install` against a temp HOME with a
+// fake extension declaring binFiles. Verifies install-time self-heal
+// restores a missing file from the declared source. Verifies that on
+// conflict the install aborts BEFORE any writes (per the design's
+// strict pre-write conflict rule).
+
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, readdirSync, copyFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import {
+  aggregateBinManifest,
+  healBinManifest,
+  validateDeclarations,
+  validateDeclaration,
+} from '../lib/bin-manifest.mjs';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = join(repo, 'bin', 'ldm.js');
+const pkg = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8'));
+
+let failed = 0;
+function assert(cond, label, output = '') {
+  if (cond) {
+    console.log(`  [PASS] ${label}`);
+  } else {
+    console.log(`  [FAIL] ${label}`);
+    if (output) console.log(`         --- ldm output (last lines) ---\n         ${output.trim().split('\n').slice(-30).join('\n         ')}`);
+    failed++;
+  }
+}
+
+// ── Unit: validateDeclaration ──
+console.log('Unit: validateDeclaration shape checks');
+{
+  assert(validateDeclaration({ name: 'a.sh', source: 'x/a.sh' }).length === 0, 'valid declaration passes');
+  assert(validateDeclaration(null).length > 0, 'null declaration fails');
+  assert(validateDeclaration({ source: 'x' }).length > 0, 'missing name fails');
+  assert(validateDeclaration({ name: 'a.sh' }).length > 0, 'missing source fails');
+  assert(validateDeclaration({ name: '../../etc/passwd', source: 'x' }).length > 0, 'name with .. fails');
+  assert(validateDeclaration({ name: 'sub/a.sh', source: 'x' }).length > 0, 'name with / fails');
+  assert(validateDeclaration({ name: 'a.sh', source: '../escape/a.sh' }).length > 0, 'source with .. fails');
+  assert(validateDeclaration({ name: 'a.sh', source: 'x', executable: 'yes' }).length > 0, 'non-boolean executable fails');
+}
+
+// ── Unit: validateDeclarations (multi-decl) ──
+console.log('Unit: validateDeclarations against on-disk source');
+{
+  const tmp = mkdtempSync(join(tmpdir(), 'mc-validate-'));
+  mkdirSync(join(tmp, 'src'), { recursive: true });
+  writeFileSync(join(tmp, 'src', 'good.sh'), '#!/bin/sh\n');
+  const res1 = validateDeclarations('test', tmp, [{ name: 'good.sh', source: 'src/good.sh' }]);
+  assert(res1.valid, 'declaration with existing source passes');
+
+  const res2 = validateDeclarations('test', tmp, [{ name: 'missing.sh', source: 'src/missing.sh' }]);
+  assert(!res2.valid && res2.errors.some(e => /source not found/.test(e)), 'declaration with missing source fails');
+
+  const res3 = validateDeclarations('test', tmp, [
+    { name: 'good.sh', source: 'src/good.sh' },
+    { name: 'good.sh', source: 'src/good.sh' },
+  ]);
+  assert(!res3.valid && res3.errors.some(e => /duplicate name/.test(e)), 'internal duplicate names fail');
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Unit: aggregateBinManifest produces entries from both declarers ──
+console.log('Unit: aggregateBinManifest combines LDM CLI + extensions');
+{
+  const tmp = mkdtempSync(join(tmpdir(), 'mc-agg-'));
+  const ldmCliRoot = join(tmp, 'cli');
+  const extensionsRoot = join(tmp, 'extensions');
+  const binDir = join(tmp, 'bin');
+  mkdirSync(ldmCliRoot, { recursive: true });
+  mkdirSync(join(extensionsRoot, 'mc'), { recursive: true });
+  mkdirSync(binDir, { recursive: true });
+  writeFileSync(join(ldmCliRoot, 'package.json'), JSON.stringify({
+    wipLdmOs: { binFiles: [{ name: 'cli-tool.sh', source: 'cli-tool.sh' }] },
+  }));
+  writeFileSync(join(ldmCliRoot, 'cli-tool.sh'), '#!/bin/sh\n');
+  writeFileSync(join(extensionsRoot, 'mc', 'openclaw.plugin.json'), JSON.stringify({
+    binFiles: [{ name: 'ext-shim.sh', source: 'dist/ext-shim.sh' }],
+  }));
+  mkdirSync(join(extensionsRoot, 'mc', 'dist'), { recursive: true });
+  writeFileSync(join(extensionsRoot, 'mc', 'dist', 'ext-shim.sh'), '#!/bin/sh\n');
+
+  const m = aggregateBinManifest({
+    ldmCliRoot, extensionsRoot, binDir,
+    registry: { extensions: { mc: {} } },
+  });
+  assert(m.entries.length === 2, 'two entries aggregated');
+  assert(m.entries.some(e => e.declarer === 'wip-ldm-os' && e.name === 'cli-tool.sh'), 'LDM CLI entry present');
+  assert(m.entries.some(e => e.declarer === 'mc' && e.name === 'ext-shim.sh'), 'extension entry present');
+  assert(m.conflicts.length === 0, 'no conflicts when names are distinct');
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Unit: aggregateBinManifest detects conflicts ──
+console.log('Unit: aggregateBinManifest detects same-name conflicts');
+{
+  const tmp = mkdtempSync(join(tmpdir(), 'mc-conflict-'));
+  const ldmCliRoot = join(tmp, 'cli');
+  const extensionsRoot = join(tmp, 'extensions');
+  mkdirSync(ldmCliRoot, { recursive: true });
+  mkdirSync(join(extensionsRoot, 'mc'), { recursive: true });
+  writeFileSync(join(ldmCliRoot, 'package.json'), JSON.stringify({
+    wipLdmOs: { binFiles: [{ name: 'shared.sh', source: 'a.sh' }] },
+  }));
+  writeFileSync(join(ldmCliRoot, 'a.sh'), '');
+  writeFileSync(join(extensionsRoot, 'mc', 'openclaw.plugin.json'), JSON.stringify({
+    binFiles: [{ name: 'shared.sh', source: 'b.sh' }],
+  }));
+  writeFileSync(join(extensionsRoot, 'mc', 'b.sh'), '');
+
+  const m = aggregateBinManifest({
+    ldmCliRoot, extensionsRoot, binDir: join(tmp, 'bin'),
+    registry: { extensions: { mc: {} } },
+  });
+  assert(m.conflicts.length === 1, 'one conflict detected');
+  assert(m.conflicts[0].name === 'shared.sh', 'conflict names the disputed file');
+  assert(m.conflicts[0].declarers.length === 2, 'both declarers listed');
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Unit: healBinManifest read-only and heal modes ──
+console.log('Unit: healBinManifest classifies and restores');
+{
+  const tmp = mkdtempSync(join(tmpdir(), 'mc-heal-'));
+  const binDir = join(tmp, 'bin');
+  mkdirSync(binDir, { recursive: true });
+  const sourceDir = join(tmp, 'src');
+  mkdirSync(sourceDir, { recursive: true });
+  writeFileSync(join(sourceDir, 'a.sh'), '#!/bin/sh\necho a\n');
+
+  const entryMissing = {
+    name: 'a.sh', destPath: join(binDir, 'a.sh'), sourcePath: join(sourceDir, 'a.sh'),
+    executable: true, declarer: 'test',
+  };
+
+  const ro = healBinManifest([entryMissing]);
+  assert(ro.missing.length === 1, 'read-only reports missing');
+  assert(ro.healed.length === 0, 'read-only does not restore');
+  assert(!existsSync(entryMissing.destPath), 'no write happened in read-only mode');
+
+  const wr = healBinManifest([entryMissing], { heal: true });
+  assert(wr.healed.length === 1, 'heal restores missing file');
+  assert(existsSync(entryMissing.destPath), 'file present after heal');
+  assert((statSync(entryMissing.destPath).mode & 0o111) !== 0, 'restored file is executable');
+
+  // Now make it non-executable and heal again.
+  chmodSync(entryMissing.destPath, 0o644);
+  const wr2 = healBinManifest([entryMissing], { heal: true });
+  assert(wr2.healed.length === 1, 'heal restores executable bit');
+  assert((statSync(entryMissing.destPath).mode & 0o111) !== 0, 'file is executable after second heal');
+
+  // Source missing case.
+  rmSync(join(sourceDir, 'a.sh'));
+  rmSync(entryMissing.destPath);
+  const noSrc = healBinManifest([entryMissing], { heal: true });
+  assert(noSrc.sourceMissing.length === 1, 'reports source missing');
+  assert(noSrc.failed.length === 1, 'failed records the entry');
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+// ── Integration: real `ldm install` heals a declared extension shim ──
+console.log('Integration: ldm install restores missing extension-declared shim');
+function makeIntegrationHome({ extDecls = null, extraExtension = null } = {}) {
+  const home = mkdtempSync(join(tmpdir(), 'ldm-bin-manifest-'));
+  const ldmRoot = join(home, '.ldm');
+  const binDir = join(ldmRoot, 'bin');
+  const extDir = join(ldmRoot, 'extensions');
+  const stateDir = join(ldmRoot, 'state');
+  const fakeBin = join(home, 'fakebin');
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(extDir, { recursive: true });
+  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+  writeFileSync(join(ldmRoot, 'version.json'), JSON.stringify({ version: pkg.version }, null, 2) + '\n');
+
+  // Optional fake plugin with binFiles.
+  const registryEntries = {};
+  if (extDecls) {
+    const pluginDir = join(extDir, 'fake-plugin');
+    const pluginDist = join(pluginDir, 'dist');
+    mkdirSync(pluginDist, { recursive: true });
+    writeFileSync(join(pluginDir, 'openclaw.plugin.json'), JSON.stringify({
+      id: 'fake-plugin', name: 'Fake Plugin', binFiles: extDecls,
+    }));
+    writeFileSync(join(pluginDist, 'fake-shim.sh'), '#!/bin/sh\necho fake\n');
+    chmodSync(join(pluginDist, 'fake-shim.sh'), 0o755);
+    registryEntries['fake-plugin'] = {};
+  }
+  if (extraExtension) {
+    const pluginDir = join(extDir, extraExtension.name);
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, 'openclaw.plugin.json'), JSON.stringify({
+      id: extraExtension.name, name: extraExtension.name, binFiles: extraExtension.binFiles,
+    }));
+    if (extraExtension.sourceFiles) {
+      for (const [rel, content] of Object.entries(extraExtension.sourceFiles)) {
+        const fp = join(pluginDir, rel);
+        mkdirSync(dirname(fp), { recursive: true });
+        writeFileSync(fp, content);
+        chmodSync(fp, 0o755);
+      }
+    }
+    registryEntries[extraExtension.name] = {};
+  }
+  writeFileSync(join(extDir, 'registry.json'), JSON.stringify({
+    _format: 'v2', extensions: registryEntries,
+  }, null, 2) + '\n');
+
+  // npm + crontab shims.
+  writeFileSync(join(fakeBin, 'npm'), '#!/bin/sh\nexit 0\n');
+  chmodSync(join(fakeBin, 'npm'), 0o755);
+  writeFileSync(join(fakeBin, 'crontab'), '#!/bin/sh\nif [ "$1" = "-l" ]; then exit 1; fi\nexit 0\n');
+  chmodSync(join(fakeBin, 'crontab'), 0o755);
+
+  return { home, binDir, extDir, fakeBin };
+}
+
+function runInstall({ home, fakeBin }) {
+  try {
+    return execFileSync('node', [cli, 'install'], {
+      env: { ...process.env, HOME: home, PATH: `${fakeBin}:${process.env.PATH}`, LDM_SELF_UPDATED: '1' },
+      encoding: 'utf-8',
+      timeout: 30000,
+    });
+  } catch (err) {
+    return { error: true, output: (err.stdout || '') + (err.stderr || ''), code: err.status };
+  }
+}
+
+// Test A: extension declares fake-shim.sh; install heal-restores it because dest is absent.
+{
+  const w = makeIntegrationHome({
+    extDecls: [{ name: 'fake-shim.sh', source: 'dist/fake-shim.sh' }],
+  });
+  const out = runInstall(w);
+  const text = typeof out === 'string' ? out : out.output;
+  const restored = join(w.binDir, 'fake-shim.sh');
+  assert(/Restored fake-shim\.sh/.test(text), 'install logs restore', text);
+  assert(existsSync(restored), 'fake-shim.sh present in ~/.ldm/bin/ after install', text);
+  assert((statSync(restored).mode & 0o111) !== 0, 'restored shim is executable', text);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// Test B: conflict between LDM CLI and a fake plugin BOTH claiming the same name.
+//         Install must abort BEFORE writing fake-shim.sh.
+console.log('Integration: ldm install aborts on conflict before writing');
+{
+  // The LDM CLI's wipLdmOs.binFiles already declares ldm-backup.sh.
+  // We add a fake plugin claiming the same name.
+  const w = makeIntegrationHome({
+    extDecls: [{ name: 'ldm-backup.sh', source: 'dist/fake-shim.sh' }],
+  });
+  const out = runInstall(w);
+  const text = typeof out === 'string' ? out : out.output;
+  assert(out.error === true, 'install exits non-zero on conflict', text);
+  assert(/bin manifest conflict/.test(text), 'output names the conflict', text);
+  assert(/aborting before seedLocalCatalog\/deployBridge\/deployScripts run/.test(text), 'output declares pre-write abort', text);
+  // Pre-write invariant: install bailed before any of seedLocalCatalog,
+  // deployBridge, or deployScripts ran. Verify each.
+  const backupShim = join(w.binDir, 'ldm-backup.sh');
+  assert(!existsSync(backupShim), 'no partial state: ldm-backup.sh was NOT written', text);
+  const catalogFile = join(w.home, '.ldm', 'catalog.json');
+  assert(!existsSync(catalogFile), 'no partial state: ~/.ldm/catalog.json was NOT seeded', text);
+  const bridgeDist = join(w.extDir, 'lesa-bridge', 'dist');
+  assert(!existsSync(bridgeDist), 'no partial state: bridge files were NOT deployed', text);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('');
+if (failed > 0) {
+  console.log(`${failed} test(s) failed.`);
+  process.exit(1);
+}
+console.log('All bin manifest tests passed.');

package/scripts/test-doctor-cron-target.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// Regression test: `ldm doctor` cron-target health check.
+//
+// Walks the crontab, verifies each ~/.ldm/bin/<file> referenced by a
+// cron entry exists and is executable, classifies failures, and offers
+// restore-from-extension-dist for known shims (--fix). This is the
+// LDM-side parallel to crystal doctor's checkCaptureShim.
+//
+// Each case sets a fake `crontab` shim on PATH so the operator's real
+// crontab is never read. Real bin/ldm.js doctor runs against a temp
+// HOME with version.json + registry.json seeded so the rest of the
+// doctor flow doesn't crash.
+
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = join(repo, 'bin', 'ldm.js');
+const pkg = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8'));
+
+let failed = 0;
+function assert(cond, label, output = '') {
+  if (cond) {
+    console.log(`  [PASS] ${label}`);
+  } else {
+    console.log(`  [FAIL] ${label}`);
+    if (output) console.log(`         --- ldm output (last lines) ---\n         ${output.trim().split('\n').slice(-30).join('\n         ')}`);
+    failed++;
+  }
+}
+
+function setupHome(crontabContent, { withCanonicalShim = true, shimMode = 0o755, shimContent = '#!/bin/sh\necho hi\n' } = {}) {
+  const home = mkdtempSync(join(tmpdir(), 'ldm-doctor-cron-'));
+  const ldmRoot = join(home, '.ldm');
+  const binDir = join(ldmRoot, 'bin');
+  const extDir = join(ldmRoot, 'extensions');
+  const stateDir = join(ldmRoot, 'state');
+  const fakeBin = join(home, 'fakebin');
+
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(extDir, { recursive: true });
+  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+
+  writeFileSync(join(ldmRoot, 'version.json'), JSON.stringify({ version: pkg.version }, null, 2) + '\n');
+
+  // Canonical extension dist for crystal-capture.sh (so "Run: ldm doctor --fix" hint fires).
+  // Also register memory-crystal in the registry and declare binFiles so the
+  // manifest-driven knownSources lookup can find it. Mirrors the post-merge
+  // state once memory-crystal-private declares its binFiles.
+  const registryExtensions = {};
+  if (withCanonicalShim) {
+    const mcDir = join(extDir, 'memory-crystal');
+    const mcDist = join(mcDir, 'dist');
+    mkdirSync(mcDist, { recursive: true });
+    writeFileSync(join(mcDist, 'crystal-capture.sh'), shimContent);
+    chmodSync(join(mcDist, 'crystal-capture.sh'), 0o755);
+    writeFileSync(join(mcDir, 'openclaw.plugin.json'), JSON.stringify({
+      id: 'memory-crystal',
+      name: 'Memory Crystal',
+      binFiles: [{ name: 'crystal-capture.sh', source: 'dist/crystal-capture.sh' }],
+    }));
+    registryExtensions['memory-crystal'] = {};
+  }
+  writeFileSync(join(extDir, 'registry.json'), JSON.stringify({ _format: 'v2', extensions: registryExtensions }, null, 2) + '\n');
+
+  // Fake crontab on PATH. -l prints the supplied content; anything else is a no-op.
+  const crontabScript = join(fakeBin, 'crontab');
+  const escaped = crontabContent.replace(/'/g, `'\\''`);
+  writeFileSync(crontabScript, `#!/bin/sh\nif [ "$1" = "-l" ]; then\n  printf '%s' '${escaped}'\nfi\n`);
+  chmodSync(crontabScript, 0o755);
+
+  // npm shim (avoid network).
+  const npmShim = join(fakeBin, 'npm');
+  writeFileSync(npmShim, `#!/bin/sh\nexit 0\n`);
+  chmodSync(npmShim, 0o755);
+
+  return { home, ldmRoot, binDir, extDir, fakeBin, shimMode };
+}
+
+function runDoctor({ home, fakeBin, fix = false }) {
+  const args = ['doctor'];
+  if (fix) args.push('--fix');
+  try {
+    return execFileSync('node', [cli, ...args], {
+      env: { ...process.env, HOME: home, PATH: `${fakeBin}:${process.env.PATH}`, LDM_SELF_UPDATED: '1' },
+      encoding: 'utf-8',
+      timeout: 30000,
+    });
+  } catch (err) {
+    return (err.stdout || '') + (err.stderr || '');
+  }
+}
+
+const CRON_CRYSTAL = '* * * * * ~/.ldm/bin/crystal-capture.sh >> ~/.ldm/logs/crystal-capture.log 2>&1\n';
+const CRON_FOREIGN = '*/5 * * * * ~/.ldm/bin/foreign-tool.sh\n';
+
+// ── Test 1: cron present, target exists and executable ──
+console.log('Test 1: cron present, target healthy');
+{
+  const w = setupHome(CRON_CRYSTAL);
+  // Seed a working shim at the cron target.
+  const target = join(w.binDir, 'crystal-capture.sh');
+  writeFileSync(target, '#!/bin/sh\necho ok\n');
+  chmodSync(target, 0o755);
+  const out = runDoctor(w);
+  assert(/Cron targets under ~\/\.ldm\/bin\/: 1 entry, all exist and executable/.test(out), 'reports healthy summary', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// ── Test 2: cron references missing target (known shim) ──
+console.log('Test 2: cron target missing, known shim');
+{
+  const w = setupHome(CRON_CRYSTAL);
+  const out = runDoctor(w);
+  assert(/cron target missing: .*crystal-capture\.sh/.test(out), 'reports "cron target missing"', out);
+  assert(/Run: ldm doctor --fix to restore from/.test(out), 'suggests --fix because canonical source exists', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// ── Test 3: --fix restores from extension dist ──
+console.log('Test 3: --fix restores from canonical source');
+{
+  const w = setupHome(CRON_CRYSTAL);
+  const target = join(w.binDir, 'crystal-capture.sh');
+  const out = runDoctor({ ...w, fix: true });
+  assert(/Restored crystal-capture\.sh from/.test(out), 'announces restore', out);
+  assert(existsSync(target), 'shim now exists at cron target', out);
+  assert((statSync(target).mode & 0o111) !== 0, 'restored shim is executable', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// ── Test 4: cron target exists but not executable ──
+console.log('Test 4: cron target not executable');
+{
+  const w = setupHome(CRON_CRYSTAL);
+  const target = join(w.binDir, 'crystal-capture.sh');
+  writeFileSync(target, '#!/bin/sh\necho ok\n');
+  chmodSync(target, 0o644);
+  const out = runDoctor(w);
+  assert(/cron target not executable: .*crystal-capture\.sh/.test(out), 'reports "cron target not executable"', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// ── Test 5: cron references unknown target with no canonical source ──
+console.log('Test 5: cron target missing, owner unknown');
+{
+  const w = setupHome(CRON_FOREIGN, { withCanonicalShim: false });
+  const out = runDoctor(w);
+  assert(/cron target missing: .*foreign-tool\.sh/.test(out), 'reports "cron target missing"', out);
+  assert(/Owner unknown/.test(out), 'admits owner is unknown when no canonical source exists', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+// ── Test 6: empty crontab ──
+console.log('Test 6: empty crontab');
+{
+  const w = setupHome('');
+  const out = runDoctor(w);
+  assert(!/cron target/.test(out), 'no cron target diagnostic when crontab is empty', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('');
+if (failed > 0) {
+  console.log(`${failed} test(s) failed.`);
+  process.exit(1);
+}
+console.log('All ldm doctor cron-target tests passed.');

package/scripts/test-installer-update-tracks.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const cli = readFileSync(join(root, 'bin', 'ldm.js'), 'utf8');
+
+const marker = '// Check parent packages for toolbox-style repos (#132)';
+const idx = cli.indexOf(marker);
+if (idx === -1) {
+  throw new Error('Could not find toolbox parent update block');
+}
+
+const parentBlock = cli.slice(idx, cli.indexOf('const totalUpdates = npmUpdates.length;', idx));
+if (!parentBlock.includes("const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';")) {
+  throw new Error('Toolbox parent update block does not select the requested release track');
+}
+
+if (!parentBlock.includes('dist-tags.${npmTag}')) {
+  throw new Error('Toolbox parent update block does not query alpha/beta dist-tags');
+}
+
+if (/const latest = execSync\(`npm view \$\{comp\.npm\} version 2>\/dev\/null`/.test(parentBlock)) {
+  throw new Error('Toolbox parent update block still hardcodes the stable npm version query');
+}
+
+const installMarker = '// For parent packages, installFromPath already refreshes each sub-tool';
+const installIdx = cli.indexOf(installMarker);
+if (installIdx === -1) {
+  throw new Error('Could not find parent registry refresh block');
+}
+
+const installBlock = cli.slice(installIdx, cli.indexOf('} catch (e) {', installIdx));
+if (installBlock.includes('= entry.latestVersion')) {
+  throw new Error('Parent update block must not stamp parent versions onto sub-tool registry entries');
+}
+
+console.log('installer update-track regression checks passed');

package/scripts/test-ldm-install-preserves-foreign-bin.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Regression test: `ldm install` must not remove or clobber foreign shims in
+// ~/.ldm/bin. Memory Crystal owns crystal-capture.sh, but the LDM installer
+// deploys its own scripts into the same directory on every install.
+//
+// This uses the real bin/ldm.js install path against a temp HOME. External
+// commands that would hit the network or operator crontab are shimmed through
+// PATH so the test is deterministic in CI and local sandboxes.
+
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cli = join(repo, 'bin', 'ldm.js');
+const pkg = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8'));
+
+function fail(message, output = '') {
+  console.error(`FAIL: ${message}`);
+  if (output) {
+    console.error('\n--- ldm output ---');
+    console.error(output.trim());
+  }
+  process.exit(1);
+}
+
+function assert(condition, message, output = '') {
+  if (!condition) fail(message, output);
+  console.log(`PASS: ${message}`);
+}
+
+const home = mkdtempSync(join(tmpdir(), 'ldm-install-bin-shim-'));
+
+try {
+  const ldmRoot = join(home, '.ldm');
+  const binDir = join(ldmRoot, 'bin');
+  const extDir = join(ldmRoot, 'extensions');
+  const stateDir = join(ldmRoot, 'state');
+  const fakeBin = join(home, 'fakebin');
+
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(extDir, { recursive: true });
+  mkdirSync(stateDir, { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+
+  writeFileSync(join(ldmRoot, 'version.json'), JSON.stringify({ version: pkg.version }, null, 2) + '\n');
+  writeFileSync(join(extDir, 'registry.json'), JSON.stringify({ extensions: {} }, null, 2) + '\n');
+
+  const shimPath = join(binDir, 'crystal-capture.sh');
+  const shimContent = '#!/bin/sh\nprintf "memory-crystal sentinel\\n"\n';
+  writeFileSync(shimPath, shimContent);
+  chmodSync(shimPath, 0o755);
+
+  // Avoid network-dependent version checks while still exercising real install.
+  const npmShim = join(fakeBin, 'npm');
+  writeFileSync(
+    npmShim,
+    `#!/bin/sh
+if [ "$1" = "view" ]; then
+  case "$3" in
+    version|dist-tags.alpha|dist-tags.beta) printf '%s\\n' '${pkg.version}' ;;
+    *) printf '%s\\n' '${pkg.version}' ;;
+  esac
+  exit 0
+fi
+if [ "$1" = "list" ]; then
+  printf '{}\\n'
+  exit 0
+fi
+exit 0
+`,
+  );
+  chmodSync(npmShim, 0o755);
+
+  // Avoid touching the operator's real crontab in any health path.
+  const crontabShim = join(fakeBin, 'crontab');
+  writeFileSync(crontabShim, '#!/bin/sh\nif [ "$1" = "-l" ]; then exit 1; fi\nexit 0\n');
+  chmodSync(crontabShim, 0o755);
+
+  let output = '';
+  try {
+    output = execFileSync('node', [cli, 'install'], {
+      env: {
+        ...process.env,
+        HOME: home,
+        PATH: `${fakeBin}:${process.env.PATH}`,
+        LDM_SELF_UPDATED: '1',
+      },
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  } catch (err) {
+    output = `${err.stdout || ''}${err.stderr || ''}`;
+    fail('real ldm install command should complete in temp HOME', output);
+  }
+
+  assert(existsSync(shimPath), 'foreign Memory Crystal shim still exists after ldm install', output);
+  assert(readFileSync(shimPath, 'utf8') === shimContent, 'foreign Memory Crystal shim content was not clobbered', output);
+  assert((readFileSync(shimPath, 'utf8').includes('memory-crystal sentinel')), 'foreign shim sentinel is intact', output);
+  assert((readFileSync(shimPath).length > 0), 'foreign shim remains non-empty', output);
+  assert((statSync(shimPath).mode & 0o111) !== 0, 'foreign shim remains executable', output);
+  assert((existsSync(join(binDir, 'ldm-backup.sh'))), 'ldm-owned scripts still deploy into ~/.ldm/bin', output);
+
+  const restored = readFileSync(shimPath);
+  assert(restored.length === Buffer.byteLength(shimContent), 'foreign shim size is unchanged', output);
+
+  console.log('\nldm install foreign-bin preservation regression passed.');
+} finally {
+  rmSync(home, { recursive: true, force: true });
+}

package/scripts/validate-bin-manifest.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// scripts/validate-bin-manifest.mjs — prepublish gate for wipLdmOs.binFiles.
+//
+// Layer 1 of the release-blocker design (see
+// ai/product/plans-prds/current/2026-04-28--cc-mini--ldm-bin-ownership-manifest-design.md).
+// Runs before every publish to assert each declared bin file is real and
+// internally consistent. A broken declaration cannot reach npm because
+// `wip-release` calls `prepublishOnly` which calls this.
+//
+// Checks:
+//   - Each declaration has a valid shape (name + source).
+//   - `name` is a basename (no /, no \, no ..).
+//   - `source` resolves to a real file under the package root.
+//   - No two declarations within this package share the same `name`.
+//
+// This does NOT check for cross-package conflicts. That is layer 2 in
+// the design and lands as a follow-up workflow once a known-extensions
+// registry exists.
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateDeclarations } from '../lib/bin-manifest.mjs';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8'));
+const decls = pkg?.wipLdmOs?.binFiles;
+
+if (!Array.isArray(decls)) {
+  console.log('No wipLdmOs.binFiles declared. Skipping validation.');
+  process.exit(0);
+}
+
+const result = validateDeclarations('wip-ldm-os', repo, decls);
+if (!result.valid) {
+  console.error('FAIL: wipLdmOs.binFiles validation failed:');
+  for (const e of result.errors) console.error(`  - ${e}`);
+  process.exit(1);
+}
+
+console.log(`OK: wipLdmOs.binFiles validated (${decls.length} entr${decls.length === 1 ? 'y' : 'ies'}).`);

package/shared/docs/dev-guide-wipcomputerinc.md.tmpl

@@ -28,7 +28,9 @@ These are three distinct actions. Never combine them. Never skip the dogfooding
 | **Deploy** | Ship to public | `wip-release` (version bump, npm publish, GitHub release) + `deploy-public.sh` (sync to public repo). Package is available to the world. **Still not on our machine.** |
 | **Install** | Put it on our system | `crystal init` or equivalent. Extensions updated. Hooks configured. Only when Parker says "install." |
 
-**After Deploy, STOP.** Do not copy files to `~/.ldm/extensions/` or `~/.openclaw/extensions/`. Do not run `npm install -g`. Do not run `npm link`. Do not touch the installed system. Tell Parker: "v0.X.Y is published. Run the install prompt when you're ready to update."
+**Prerelease exception:** agents install alpha and beta tracks for validation. Use `ldm install --alpha` after an alpha release and `ldm install --beta` after a beta release. That is test work.
+
+**After stable Deploy, STOP.** Do not copy files to `~/.ldm/extensions/` or `~/.openclaw/extensions/`. Do not run `npm install -g`. Do not run `npm link`. Do not run `ldm install` unless Parker explicitly asks. Tell Parker: "v0.X.Y is published. Run the install prompt when you're ready to update."
 
 **We always dogfood our own software.** The install prompt exists so Parker can see what's new, review the dry run, and decide to install. If agents deploy directly to extensions, the install prompt says "already up to date" and the dogfooding loop is broken.
 

package/shared/docs/how-install-works.md.tmpl

@@ -31,6 +31,8 @@ ldm install --beta       # beta track (npm @beta)
 
 Each track overwrites whatever is installed. Alpha, beta, and stable all use the same install path. The flag only changes which npm dist-tag is checked for updates.
 
+Agents may run alpha and beta installs for prerelease validation. Stable installs are different: Parker dogfoods stable/latest releases through the install prompt unless he explicitly asks an agent to install.
+
 ## Source Resolution
 
 When updating, the installer finds the package in priority order: