@wipcomputer/wip-ldm-os 0.4.86 → 0.4.87-alpha.2

package/scripts/test-doctor-commit-deployed.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// Regression test: `ldm doctor --commit-deployed`.
+//
+// Covers:
+//   wip-tracking-private-only/bugs/installer/open-tickets/2026-07-06--cc-mini--ldm-doctor-commit-deployed.md
+//
+// The command records installer-deployed config drift in a tracked home tree so
+// the tree stops blocking `git pull`, gitignores runtime/transient junk, and
+// leaves personal choices. settings.json is split at JSON-key granularity:
+// installer-owned keys (hooks) commit, personal keys (model, permissions) stay.
+//
+// Follows the test-doctor-hook-dedupe.mjs harness: real bin/ldm.js against a
+// temp HOME with a real, disposable local git repo for the home tree. gh / npm
+// / crontab are shimmed on PATH and LDM_SELF_UPDATED=1 so no network, no PR, no
+// operator state is touched. No push, no merge: the command records locally.
+
+import { chmodSync, cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, existsSync } 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');
+
+let failed = 0;
+function assert(cond, label, output = '') {
+  if (cond) {
+    console.log(`  [PASS] ${label}`);
+  } else {
+    console.log(`  [FAIL] ${label}`);
+    if (output) console.log(`         ${String(output).trim().split('\n').slice(-20).join('\n         ')}`);
+    failed++;
+  }
+}
+
+const OLD_HOOKS = { SessionStart: [{ matcher: '*', hooks: [{ type: 'command', command: 'node /old/boot-hook.mjs', timeout: 15 }] }] };
+const NEW_HOOKS = { SessionStart: [{ matcher: '*', hooks: [{ type: 'command', command: 'node /new/boot-hook.mjs', timeout: 15 }] }] };
+
+function git(dir, ...a) {
+  return execFileSync('git', ['-C', dir, ...a], { encoding: 'utf8' });
+}
+function writeJSON(p, obj) {
+  writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+
+// Build a fixture HOME with a real local git repo at HOME/.claude. `driftFn`
+// receives the repo dir and mutates it into the post-install dirty state.
+function setupHome(driftFn) {
+  const home = mkdtempSync(join(tmpdir(), 'ldm-commitdep-'));
+  const claude = join(home, '.claude');
+  const fakeBin = join(home, 'fakebin');
+  mkdirSync(join(claude, 'rules'), { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+
+  // Baseline committed state.
+  writeJSON(join(claude, 'settings.json'), { model: 'sonnet', permissions: { defaultMode: 'default' }, hooks: OLD_HOOKS });
+  writeFileSync(join(claude, 'rules', 'base.md'), 'old rule\n');
+  // projects/ and cache/ already ignored; plans/ deliberately NOT, so the
+  // command has a new transient path to gitignore.
+  writeFileSync(join(claude, '.gitignore'), 'projects/\ncache/\n');
+
+  git(claude, 'init', '-q');
+  git(claude, 'config', 'user.email', 'test@example.com');
+  git(claude, 'config', 'user.name', 'Test');
+  git(claude, 'config', 'commit.gpgsign', 'false');
+  // Isolate the fixture from any global core.hooksPath (the real machine sets a
+  // pre-commit hook there that blocks commits on main). Kept OUTSIDE the repo so
+  // an added hook file never pollutes the repo's status. Tests that want a hook
+  // drop one into this dir explicitly.
+  const hooksDir = join(home, 'githooks');
+  mkdirSync(hooksDir, { recursive: true });
+  git(claude, 'config', 'core.hooksPath', hooksDir);
+  git(claude, 'add', '-A');
+  git(claude, 'commit', '-q', '-m', 'baseline');
+
+  driftFn(claude);
+
+  // Shims: never touched by this command, present for parity with doctor tests.
+  for (const b of ['gh', 'npm', 'crontab']) {
+    writeFileSync(join(fakeBin, b), '#!/bin/sh\nexit 0\n');
+    chmodSync(join(fakeBin, b), 0o755);
+  }
+  return { home, claude, fakeBin, hooksDir };
+}
+
+function run({ home, claude, fakeBin }, extra = []) {
+  const args = ['doctor', '--commit-deployed', '--home', claude, ...extra];
+  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 || '');
+  }
+}
+
+function headJSON(claude, path) {
+  return JSON.parse(git(claude, 'show', `HEAD:${path}`));
+}
+function statusPorcelain(claude) {
+  return git(claude, 'status', '--porcelain').trim();
+}
+
+console.log('Test 1: deployed + transient drift, no personal drift -> clean tree');
+{
+  const w = setupHome((c) => {
+    const s = { model: 'sonnet', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS };
+    writeJSON(join(c, 'settings.json'), s);            // deployed key (hooks) changed
+    writeFileSync(join(c, 'rules', 'base.md'), 'new rule\n'); // deployed file changed
+    mkdirSync(join(c, 'plans'), { recursive: true });
+    writeFileSync(join(c, 'plans', 'session.json'), '{}\n');  // transient, NOT yet ignored
+    mkdirSync(join(c, 'projects'), { recursive: true });
+    writeFileSync(join(c, 'projects', 'x.json'), '{}\n');     // transient, already ignored
+  });
+  const out = run(w);
+  assert(/record installer-deployed config drift/.test(git(w.claude, 'log', '-1', '--format=%s')), 'recorded a chore(deploy) commit', out);
+  assert(headJSON(w.claude, 'settings.json').hooks.SessionStart[0].hooks[0].command === 'node /new/boot-hook.mjs', 'committed settings.json has the new hooks', out);
+  assert(headJSON(w.claude, 'settings.json').model === 'sonnet', 'committed settings.json keeps model (personal untouched)');
+  assert(git(w.claude, 'show', 'HEAD:rules/base.md') === 'new rule\n', 'committed the deployed rules/ change');
+  assert(readFileSync(join(w.claude, '.gitignore'), 'utf8').includes('plans/'), 'gitignored the new transient path (plans/)', out);
+  assert(statusPorcelain(w.claude) === '', 'tree is CLEAN after recording', statusPorcelain(w.claude));
+  const backups = existsSync(join(w.home, '.ldm', 'backups')) ? readdirSync(join(w.home, '.ldm', 'backups')) : [];
+  assert(backups.length === 1 && existsSync(join(w.home, '.ldm', 'backups', backups[0], 'MANIFEST.txt')), 'timestamped backup with manifest taken before mutation', backups.join(','));
+
+  // Idempotent second run.
+  const headBefore = git(w.claude, 'rev-parse', 'HEAD').trim();
+  const out2 = run(w);
+  assert(/already clean, nothing to record/.test(out2), 'second run is a no-op (tree already clean)', out2);
+  assert(git(w.claude, 'rev-parse', 'HEAD').trim() === headBefore, 'no extra commit on the clean second run');
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 2: mixed settings.json (hooks + model) -> key granularity, personal left');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'opus', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS });
+    writeFileSync(join(c, 'rules', 'base.md'), 'new rule\n');
+  });
+  const out = run(w);
+  assert(headJSON(w.claude, 'settings.json').hooks.SessionStart[0].hooks[0].command === 'node /new/boot-hook.mjs', 'committed the hooks key', out);
+  assert(headJSON(w.claude, 'settings.json').model === 'sonnet', 'did NOT commit the personal model key (still old on HEAD)', out);
+  assert(JSON.parse(readFileSync(join(w.claude, 'settings.json'), 'utf8')).model === 'opus', 'working settings.json keeps the new personal model');
+  const dirty = statusPorcelain(w.claude).split('\n').filter(Boolean);
+  assert(dirty.length === 1 && /settings\.json$/.test(dirty[0]), 'only settings.json remains dirty (the personal delta)', statusPorcelain(w.claude));
+  assert(/Left uncommitted/.test(out) && /settings\.json \(model\)/.test(out), 'reports model left as personal', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 3: --include-personal folds personal keys in -> clean tree');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'opus', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS });
+  });
+  const out = run(w, ['--include-personal']);
+  assert(headJSON(w.claude, 'settings.json').model === 'opus', 'committed the personal model under --include-personal', out);
+  assert(headJSON(w.claude, 'settings.json').hooks.SessionStart[0].hooks[0].command === 'node /new/boot-hook.mjs', 'committed the hooks too');
+  assert(statusPorcelain(w.claude) === '', 'tree clean with --include-personal', statusPorcelain(w.claude));
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 4: personal-only drift -> nothing committed, left for the user');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'opus', permissions: { defaultMode: 'default' }, hooks: OLD_HOOKS });
+  });
+  const headBefore = git(w.claude, 'rev-parse', 'HEAD').trim();
+  const out = run(w);
+  assert(/No deployed drift or new runtime paths to record/.test(out), 'reports nothing deployed to record', out);
+  assert(git(w.claude, 'rev-parse', 'HEAD').trim() === headBefore, 'no commit created for personal-only drift');
+  assert(JSON.parse(readFileSync(join(w.claude, 'settings.json'), 'utf8')).model === 'opus', 'personal model left in the working tree');
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 5: dry run records nothing');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'sonnet', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS });
+  });
+  const headBefore = git(w.claude, 'rev-parse', 'HEAD').trim();
+  const out = run(w, ['--dry-run']);
+  assert(/\[DRY RUN\] Would record/.test(out), 'dry run reports intent', out);
+  assert(git(w.claude, 'rev-parse', 'HEAD').trim() === headBefore, 'dry run creates no commit');
+  assert(/ M settings\.json|settings\.json/.test(statusPorcelain(w.claude)), 'dry run leaves the tree unchanged (still dirty)');
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 6: non-git home is reported, not crashed');
+{
+  const home = mkdtempSync(join(tmpdir(), 'ldm-commitdep-nogit-'));
+  const notRepo = join(home, 'plain');
+  mkdirSync(notRepo, { recursive: true });
+  const fakeBin = join(home, 'fakebin');
+  mkdirSync(fakeBin, { recursive: true });
+  for (const b of ['gh', 'npm', 'crontab']) { writeFileSync(join(fakeBin, b), '#!/bin/sh\nexit 0\n'); chmodSync(join(fakeBin, b), 0o755); }
+  let out = '';
+  try {
+    out = execFileSync('node', [cli, 'doctor', '--commit-deployed', '--home', notRepo], {
+      env: { ...process.env, HOME: home, PATH: `${fakeBin}:${process.env.PATH}`, LDM_SELF_UPDATED: '1' },
+      encoding: 'utf-8', timeout: 30000,
+    });
+  } catch (err) { out = (err.stdout || '') + (err.stderr || ''); }
+  assert(/Not a git work tree/.test(out), 'reports a non-git home cleanly', out);
+  rmSync(home, { recursive: true, force: true });
+}
+
+console.log('Test 7: pre-existing personal .gitignore edit is NOT swept into the deploy commit');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'sonnet', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS });
+    // User has an uncommitted personal .gitignore edit...
+    writeFileSync(join(c, '.gitignore'), 'projects/\ncache/\npersonal-local/\n');
+    // ...and there is a new transient path that forces a gitignore addition.
+    mkdirSync(join(c, 'plans'), { recursive: true });
+    writeFileSync(join(c, 'plans', 'session.json'), '{}\n');
+  });
+  const out = run(w);
+  const committedGitignore = git(w.claude, 'show', 'HEAD:.gitignore');
+  assert(committedGitignore.includes('plans/'), 'the new transient pattern was committed', out);
+  assert(!committedGitignore.includes('personal-local/'), 'the pre-existing personal .gitignore edit was NOT committed', committedGitignore);
+  assert(readFileSync(join(w.claude, '.gitignore'), 'utf8').includes('personal-local/'), 'personal .gitignore edit still present in working tree');
+  const dirty = statusPorcelain(w.claude).split('\n').filter(Boolean);
+  assert(dirty.length === 1 && /\.gitignore$/.test(dirty[0]), 'only .gitignore (the personal edit) remains dirty', statusPorcelain(w.claude));
+  assert(/\.gitignore \(your existing edits/.test(out), 'reports .gitignore personal edits left', out);
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 8: malformed settings.json is skipped, never deletes committed hooks');
+{
+  const w = setupHome((c) => {
+    writeFileSync(join(c, 'settings.json'), '{ this is not valid json\n'); // corrupt working file
+    writeFileSync(join(c, 'rules', 'base.md'), 'new rule\n');              // a legit deployed change
+  });
+  const headBefore = git(w.claude, 'rev-parse', 'HEAD').trim();
+  const out = run(w);
+  assert(/settings\.json skipped/.test(out) && /not valid JSON/.test(out), 'warns and skips malformed settings.json', out);
+  // The committed settings.json must still carry the original hooks (not deleted).
+  const committed = headJSON(w.claude, 'settings.json');
+  assert(committed.hooks && committed.hooks.SessionStart, 'committed settings.json still has its hooks (not clobbered)', JSON.stringify(committed));
+  assert(committed.hooks.SessionStart[0].hooks[0].command === 'node /old/boot-hook.mjs', 'hooks unchanged at HEAD (no deletion commit)');
+  // The legit deployed rules/ change still got recorded (skip is scoped to settings.json).
+  assert(git(w.claude, 'rev-parse', 'HEAD').trim() !== headBefore, 'a commit was still made for the deployed rules/ change');
+  assert(git(w.claude, 'show', 'HEAD:rules/base.md') === 'new rule\n', 'rules/ change committed despite settings.json skip');
+  assert(/settings\.json/.test(statusPorcelain(w.claude)), 'malformed settings.json left dirty for manual repair');
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 9: a tracked file under a transient prefix is left, not falsely claimed clean');
+{
+  const w = setupHome((c) => {
+    // Commit a tracked file under a transient prefix in the baseline drift...
+    mkdirSync(join(c, 'plans'), { recursive: true });
+    writeFileSync(join(c, 'plans', 'tracked.md'), 'v1\n');
+    git(c, 'add', '--', 'plans/tracked.md');
+    git(c, 'commit', '-q', '-m', 'add tracked transient');
+    // ...then modify it (tracked-transient drift) plus a real deployed change.
+    writeFileSync(join(c, 'plans', 'tracked.md'), 'v2\n');
+    writeFileSync(join(c, 'rules', 'base.md'), 'new rule\n');
+  });
+  const out = run(w);
+  assert(git(w.claude, 'show', 'HEAD:rules/base.md') === 'new rule\n', 'deployed rules/ change committed', out);
+  assert(git(w.claude, 'show', 'HEAD:plans/tracked.md') === 'v1\n', 'tracked-transient file was NOT committed (still v1 at HEAD)');
+  assert(/tracked transient/.test(out), 'reports the tracked-transient file as left', out);
+  const dirty = statusPorcelain(w.claude).split('\n').filter(Boolean);
+  assert(dirty.length === 1 && /plans\/tracked\.md$/.test(dirty[0]), 'tracked-transient file remains dirty (honestly not claimed clean)', statusPorcelain(w.claude));
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+console.log('Test 10: records even when a pre-commit hook blocks commits on main');
+{
+  const w = setupHome((c) => {
+    writeJSON(join(c, 'settings.json'), { model: 'sonnet', permissions: { defaultMode: 'default' }, hooks: NEW_HOOKS });
+    writeFileSync(join(c, 'rules', 'base.md'), 'new rule\n');
+  });
+  // Simulate the real machine: a pre-commit hook that hard-blocks `git commit`
+  // on main. The command lands its commit via plumbing, so it must still work.
+  const hook = join(w.hooksDir, 'pre-commit');
+  writeFileSync(hook, '#!/bin/sh\nif [ "$(git symbolic-ref --short HEAD)" = "main" ]; then echo "BLOCKED: no commits on main"; exit 1; fi\n');
+  chmodSync(hook, 0o755);
+  // Ensure the fixture is actually on main and the hook really blocks a plain commit.
+  execFileSync('git', ['-C', w.claude, 'branch', '-M', 'main'], { encoding: 'utf8' });
+  let blocked = false;
+  try { execFileSync('git', ['-C', w.claude, 'commit', '-q', '--allow-empty', '-m', 'probe'], { encoding: 'utf8' }); }
+  catch { blocked = true; }
+  assert(blocked, 'sanity: a plain git commit on main is blocked by the hook');
+
+  const out = run(w);
+  assert(git(w.claude, 'log', '-1', '--format=%s').includes('record installer-deployed config drift'), 'command still recorded the commit on main via plumbing', out);
+  assert(git(w.claude, 'show', 'HEAD:rules/base.md') === 'new rule\n', 'deployed change landed despite the blocking hook');
+  assert(statusPorcelain(w.claude) === '', 'tree clean after recording past the hook', statusPorcelain(w.claude));
+  rmSync(w.home, { recursive: true, force: true });
+}
+
+if (failed > 0) {
+  console.log(`\n${failed} assertion(s) failed`);
+  process.exit(1);
+}
+console.log('\nAll doctor commit-deployed tests passed');

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

@@ -102,6 +102,11 @@ exit 0
   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);
+  assert((existsSync(join(binDir, 'ldm-backup-engine.py'))), 'backup engine deploys into ~/.ldm/bin', output);
+  assert((existsSync(join(binDir, 'ldm-backup-policy.json'))), 'backup policy deploys into ~/.ldm/bin', output);
+  assert((statSync(join(binDir, 'ldm-backup-engine.py')).mode & 0o111) !== 0, 'backup engine is executable', output);
+  assert((statSync(join(binDir, 'ldm-backup-policy.json')).mode & 0o111) === 0, 'backup policy is not executable', output);
+  assert(readFileSync(join(binDir, 'ldm-backup-policy.json'), 'utf8') === readFileSync(join(repo, 'scripts', 'ldm-backup-policy.json'), 'utf8'), 'backup policy content matches package source', output);
 
   const restored = readFileSync(shimPath);
   assert(restored.length === Buffer.byteLength(shimContent), 'foreign shim size is unchanged', output);

package/shared/docs/README.md.tmpl

@@ -16,7 +16,7 @@ If something is wrong, update `~/.ldm/config.json` or run `ldm install`. The doc
 | `what-is-dotldm.md` | The `~/.ldm/` runtime directory explained |
 | `directory-map.md` | What lives where and why |
 | `how-worktrees-work.md` | Git worktrees, the _worktrees/ convention |
-| `how-backup-works.md` | Daily backup, iCloud offsite, restore |
+| `how-backup-works.md` | Safe dry run, verified internal snapshots, and later-tier gates |
 | `how-releases-work.md` | The full release pipeline |
 | `how-install-works.md` | ldm install, the install prompt, dogfooding |
 | `how-agents-work.md` | Agents, harnesses, bridge, memory |

package/shared/docs/directory-map.md.tmpl

@@ -43,7 +43,7 @@
   hooks/                    <- Claude Code hooks
   state/                    <- runtime state
   tmp/                      <- install staging
-  backups/                  <- daily backups (ldm-backup.sh) + iCloud offsite tars
+  backups/v1/internal/      <- verified internal snapshots and in-progress staging
 ```
 
 ## Harness Directories (deployment targets)

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

@@ -1,111 +1,78 @@
 # How Backup Works
 
-## One Script, One Place
+## Safe planning first
 
-`~/.ldm/bin/ldm-backup.sh` runs daily at 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`. It backs up everything to `~/.ldm/backups/`, then tars it to iCloud for offsite.
+The backup engine has a strictly read-only dry run:
 
-## What Gets Backed Up
+```bash
+~/.ldm/bin/ldm-backup.sh --dry-run
+```
 
-| Source | Method | What's in it |
-|--------|--------|-------------|
-| `~/.ldm/memory/crystal.db` | sqlite3 .backup | Irreplaceable memory (all agents) |
-| `~/.ldm/agents/` | cp -a | Identity files, journals, daily logs |
-| `~/.ldm/state/` | cp -a | Config, version, registry |
-| `~/.ldm/config.json` | cp | Workspace pointer, org |
-| `~/.openclaw/memory/main.sqlite` | sqlite3 .backup | OC conversations |
-| `~/.openclaw/memory/context-embeddings.sqlite` | sqlite3 .backup | Embeddings |
-| `~/.openclaw/workspace/` | tar | Shared context, daily logs |
-| `~/.openclaw/agents/main/sessions/` | tar | OC session JSONL |
-| `~/.openclaw/openclaw.json` | cp | OC config |
-| `~/.claude/CLAUDE.md` | cp | CC instructions |
-| `~/.claude/settings.json` | cp | CC settings |
-| `~/.claude/projects/` | tar | CC auto-memory + transcripts |
-| `~/wipcomputerinc/` | tar (excludes node_modules, .git/objects, old backups, _trash) | Entire workspace |
+It shows every policy source, classification, exclusion reason, per-source estimate, total estimated new bytes, available disk capacity, required reserve, planned staging path, planned internal destination, blocked requirements, and the final preflight verdict.
 
-**NOT backed up:** node_modules/, .git/objects/ (reconstructable), extensions (reinstallable), ~/.claude/cache.
+Dry run does not create files or directories. It does not acquire the persistent lock, write state, copy data, create a manifest, create a completion marker, rotate snapshots, write to Vault or iCloud, change the schedule, enable the LaunchAgent, or modify containment state. Sensitive filenames and contents are not printed.
 
-## Backup Structure
+Exit zero means the proposed run passes the same policy and preflight used by the real engine. Exit nonzero means a required source, encryption gate, destination, or disk reserve blocks the run.
 
-```
-~/.ldm/backups/2026-03-24--09-50-22/
-  ldm/
-    memory/crystal.db
-    agents/
-    state/
-    config.json
-  openclaw/
-    memory/main.sqlite
-    memory/context-embeddings.sqlite
-    workspace.tar
-    sessions.tar
-    openclaw.json
-  claude/
-    CLAUDE.md
-    settings.json
-    projects.tar
-  wipcomputerinc.tar
-```
+## Canonical source policy
 
-## iCloud Offsite
+`~/.ldm/bin/ldm-backup-policy.json` defines required, rebuildable, sensitive, blocked, manifest-only, and excluded sources. Estimation, capture, manifest generation, and exclusion records all use this one policy.
 
-After local backup, the entire dated folder is compressed and copied to iCloud. The iCloud path is read from `~/.ldm/config.json` at `paths.icloudBackup`.
+Sources that require encryption remain visibly blocked until that later gate ships. The engine never turns a blocked or missing required source into a partial success.
 
-```
-~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/
-  wipcomputerinc-lesa-2026-03-24--09-50-22.tar.gz
-```
+The policy has one explicit ID for every approved source-inventory row. The test suite compares the exact ID list so a future omission cannot silently pass.
 
-One file per backup. iCloud syncs it across devices. Rotates to {{backup.keep}} days.
+## Runtime and changing files
 
-## How to Run
+The engine uses Python 3 standard library only. No third-party Python packages are required. If `python3` is unavailable, the runner exits with `Backup failed [python3-missing]`. Owner acceptance of Python 3 as a release prerequisite must be recorded separately at the release gate.
 
-```bash
-~/.ldm/bin/ldm-backup.sh                    # run backup now
-~/.ldm/bin/ldm-backup.sh --dry-run          # preview what would be backed up
-~/.ldm/bin/ldm-backup.sh --keep 14          # keep 14 days instead of 7
-~/.ldm/bin/ldm-backup.sh --include-secrets   # include ~/.ldm/secrets/
-```
+A real run observes each source again immediately before capture. Changes since dry-run or initial planning are recorded and captured from the newer observation. Files and trees must then remain stable while that source is copied. Same-size changes are detected by checksum, and any during-capture mutation fails the run. SQLite uses the SQLite backup API for a transactionally consistent snapshot.
 
-## How to Restore
+The engine recalculates the reserve before copying a changed source. It includes staged bytes, stat-only refreshed remaining sources, a full checksum observation of the source about to be copied, projected metadata, and the required 10 percent reserve. Growth that crosses the floor fails before that source is copied.
 
-```bash
-~/.ldm/bin/ldm-restore.sh                           # list available backups
-~/.ldm/bin/ldm-restore.sh 2026-03-24--09-50-22      # restore everything
-~/.ldm/bin/ldm-restore.sh --only ldm <backup>       # restore only crystal.db + agents
-~/.ldm/bin/ldm-restore.sh --only openclaw <backup>  # restore only OC data
-~/.ldm/bin/ldm-restore.sh --from-icloud <file>      # restore from iCloud tar
-~/.ldm/bin/ldm-restore.sh --dry-run <backup>        # preview
+Manifest-only requirements must produce validated machine-readable evidence. An entry without an implemented generator is marked blocked before its source path is walked. When a required evidence generator is not implemented, including repo-aware Git/worktree and system inventories, the source stays blocked instead of being treated as fulfilled.
+
+## Successful snapshot
+
+A completed internal snapshot lives under:
+
+```text
+~/.ldm/backups/v1/internal/<snapshot-id>/
 ```
 
-After restore: `openclaw gateway restart` then `crystal status` to verify.
+It is built first as `.in-progress-<snapshot-id>`. Promotion happens only after every required capture succeeds, SQLite copies pass `PRAGMA quick_check`, checksums validate, the manifest validates, and `completion.json` is written last.
+
+Any required failure exits nonzero, writes no completion marker, and never prints `Backup complete`.
+
+## Retention
+
+The engine retains {{backup.keep}} unpinned verified snapshots plus every pinned snapshot. Pinned snapshots do not consume an unpinned retention slot. In-progress and unverified directories are never rotated.
+
+## Structured state
+
+Diagnostic state lives under `~/.ldm/state/backup/v1/`:
+
+- `schedule.json`
+- `attempt.json`
+- `result.json`
+- `success-local.json`
 
-## Schedule
+State records are atomic, but they are not completion proof. A snapshot requires a valid manifest and completion marker.
 
-| What | When | How |
-|------|------|-----|
-| Backup | 3:00 AM | LaunchAgent `ai.openclaw.ldm-backup` runs `~/.ldm/bin/ldm-backup.sh` |
+Snapshot identifiers use UTC and end in `Z`. If no valid containment marker is present, schedule state records evidence status as `unknown`.
 
-One LaunchAgent. One script. No Full Disk Access currently (target: midnight via LDMDevTools.app once PID error is fixed). Verify is built into the script (exit code + log).
+## Current boundaries
 
-## Config
+This engine correctness slice covers the internal tier. Vault, iCloud, monitoring, isolated restore, migration, and schedule resumption remain separately gated. Do not run a real backup until those gates are approved.
 
-All backup settings live in `~/.ldm/config.json`:
-- `paths.workspace` ... workspace path
-- `paths.icloudBackup` ... iCloud offsite destination
-- `backup.keep` ... retention days (default: 7)
-- `backup.includeSecrets` ... whether to include `~/.ldm/secrets/`
-- `org` ... used for tar filename prefix
+## Your system
 
-## Logs
+**Internal destination:** `~/.ldm/backups/v1/internal/`
 
-`~/.ldm/logs/backup.log` (LaunchAgent stdout/stderr)
+**Configured iCloud path:** `~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/` (not written by this engine slice)
 
----
+**Schedule label:** `ai.openclaw.ldm-backup`
 
-## Your System
+**Retention:** {{backup.keep}} unpinned verified snapshots
 
-**Local backups:** `~/.ldm/backups/`
-**iCloud offsite:** `~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/`
-**Schedule:** 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`
-**Retention:** {{backup.keep}} days local, {{backup.keep}} days iCloud
-**Script:** `~/.ldm/bin/ldm-backup.sh` (deployed by `ldm install`)
+**Runner:** `~/.ldm/bin/ldm-backup.sh`

package/shared/docs/system-directories.md.tmpl

@@ -33,7 +33,7 @@ Where LDM OS runs. Rules, commands, and skills are authored here and deployed to
 | `~/.ldm/hooks/` | Claude Code hooks | ldm install |
 | `~/.ldm/state/` | Runtime state | Tools (watermarks, markers) |
 | `~/.ldm/tmp/` | Install staging | ldm install (cleaned after) |
-| `~/.ldm/backups/` | Local backups + iCloud offsite tars | ldm-backup.sh |
+| `~/.ldm/backups/v1/internal/` | Verified internal snapshots and in-progress staging | ldm-backup.sh |
 
 ## Harness Directories (deployment targets)
 

package/shared/docs/what-is-dotldm.md.tmpl

@@ -41,7 +41,7 @@ The LDM OS runtime directory. Everything the system needs to run lives here. You
   hooks/               Claude Code hooks
   state/               runtime state (last release marker, watermarks)
   tmp/                 install staging (cleaned after install)
-  backups/             daily backup output (local + iCloud offsite)
+  backups/v1/internal/ verified internal snapshots and in-progress staging
 ```
 
 ## What Gets Backed Up