@dzhechkov/harness-core 0.8.46 → 0.8.47

package/src/agentdb-index.ts

@@ -12,7 +12,7 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, copyFileSync, realpathSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, realpathSync, readFileSync, writeFileSync, renameSync, unlinkSync, lstatSync, rmSync, constants as fsConstants } from 'node:fs';
 import { join, dirname, resolve, relative, isAbsolute, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -1408,6 +1408,31 @@ export async function reindexAgentdbRows(
     if (rel.startsWith('..') || isAbsolute(rel)) {
       return { reembedded: 0, error: `opts.backupPath must stay inside ${dbDir}, got: ${opts.backupPath}` };
     }
+    // agentdb-backup-no-symlink-escape (backlog c2a85b540a293ea2): the check above resolves only the
+    // PARENT physically and re-joins the basename lexically, so a LAST component that is itself a
+    // symlink out of the store passed it and the snapshot was written through the link (MEASURED on
+    // HEAD: a dangling link got a snapshot created outside, a link to an empty outside file had it
+    // overwritten). The leaf is lstat'ed — never followed — and refused by name. The snapshot writer
+    // repeats this check and writes via a staging dir + rename, so a link planted after this point is
+    // replaced, not followed (agentdb-snapshot.ts, stageThenRename).
+    // Review r1 (MINOR): only ENOENT means "absent" — EACCES/EIO/ENOTDIR are a path whose kind cannot
+    // be determined, refused by name rather than read as free.
+    let leaf: ReturnType<typeof lstatSync> | undefined;
+    try {
+      leaf = lstatSync(candidate);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (code !== 'ENOENT') {
+        return { reembedded: 0, error: `opts.backupPath cannot be inspected (${code ?? 'unknown error'}): ${opts.backupPath}` };
+      }
+      leaf = undefined;
+    }
+    if (leaf?.isSymbolicLink()) {
+      return { reembedded: 0, error: `opts.backupPath is a symbolic link — refusing to follow it: ${opts.backupPath}` };
+    }
+    if (leaf !== undefined && !leaf.isFile()) {
+      return { reembedded: 0, error: `opts.backupPath exists and is not a regular file: ${opts.backupPath}` };
+    }
   }
 
   // FR-3: sqlite resolves BEFORE any snapshot is taken — an unavailable dependency must abort with
@@ -1474,7 +1499,11 @@ export async function reindexAgentdbRows(
         snapshotMethod = outcome.method;
         snapshotNote = outcome.note;
         if (existsSync(`${dbFile}.embed-manifest.json`)) {
-          copyFileSync(`${dbFile}.embed-manifest.json`, `${backupPath}.embed-manifest.json`);
+          // no-symlink-escape (FR-5): remove whatever sits at the sibling (rmSync removes a symlink
+          // itself, never its target), then copy with COPYFILE_EXCL — O_CREAT|O_EXCL refuses a link
+          // planted in between (EEXIST) instead of writing through it.
+          rmSync(`${backupPath}.embed-manifest.json`, { force: true });
+          copyFileSync(`${dbFile}.embed-manifest.json`, `${backupPath}.embed-manifest.json`, fsConstants.COPYFILE_EXCL);
         }
       }
       } catch (snapErr) {

package/src/agentdb-snapshot.ts

@@ -43,6 +43,18 @@
  * bug, a backup that looked complete but carried a wrong-generation `-wal`. It now refuses up front
  * (before `VACUUM INTO` or any copy) when `backupPath` already exists and is non-empty.
  *
+ * **agentdb-backup-no-symlink-escape (backlog c2a85b540a293ea2).** A `backupPath` that is itself a
+ * symbolic link used to be written THROUGH: `statSync` in AM-4 follows the link (so a link to a
+ * non-empty file was refused, by accident), but a dangling link got a fresh snapshot created at its
+ * target and a link to an EMPTY file had it overwritten — outside the store (MEASURED on HEAD, /var/tmp
+ * probe, features/agentdb-backup-no-symlink-escape/00_complexity_assessment.md). Two layers now:
+ * {@link assertBackupLeafWritable} refuses a symlink or non-regular leaf by name before anything is
+ * written, and {@link stageThenRename} writes the snapshot (main file and any `-wal`) into a fresh
+ * private `mkdtempSync` directory next to the target and moves it into place with `renameSync`.
+ * `rename(2)` replaces a directory ENTRY — a link planted at `backupPath` between the check and the
+ * write is replaced by the snapshot, never followed. `O_NOFOLLOW` was not an option: the main path
+ * writes through sqlite's `VACUUM INTO`, which takes no open flags.
+ *
  * {@link restoreSqliteSnapshot} (FR-4) is the paired rollback. MEASURED (same repro): copying the
  * old main file back over `dbFile` WITHOUT removing a `-wal` left over from the aborted operation
  * — reopening the "restored" db returned ZERO rows, not the restored one, because sqlite replayed
@@ -61,7 +73,8 @@
  * @packageDocumentation
  */
 
-import { copyFileSync, existsSync, rmSync, statSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 
 /** How a snapshot was actually taken — always reported by the caller, never assumed. */
 export type SnapshotMethod = 'vacuum-into' | 'copy+wal' | 'copy';
@@ -130,6 +143,77 @@ function clearBackupSidecars(backupPath: string): void {
   rmSync(`${backupPath}-shm`, { force: true });
 }
 
+/**
+ * no-symlink-escape (FR-1/FR-2/FR-4): refuse a `backupPath` whose LAST component is a symbolic link
+ * (whatever it points at) or an existing non-regular file (directory, FIFO, socket, device). `lstatSync`
+ * never follows the link; only a confirmed `ENOENT` means "free". Any other lstat error propagates —
+ * a target whose kind cannot be determined is not written to.
+ */
+function assertBackupLeafWritable(backupPath: string): void {
+  let st: ReturnType<typeof lstatSync>;
+  try {
+    st = lstatSync(backupPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return;
+    throw err;
+  }
+  if (st.isSymbolicLink()) {
+    throw new Error(`snapshot target is a symbolic link — refusing to follow it: ${backupPath}`);
+  }
+  if (!st.isFile()) {
+    throw new Error(`snapshot target exists and is not a regular file: ${backupPath}`);
+  }
+}
+
+/**
+ * no-symlink-escape (FR-3, the TOCTOU half): run `write` against a path inside a fresh private staging
+ * directory (`mkdtempSync` — atomic, unpredictable name, mode 0700) next to `backupPath`, then move the
+ * result into place with `renameSync`: the main file first, then its `-wal` only when the outcome says
+ * `'copy+wal'` (AM-1: decided by the explicit method, never by what happens to exist on disk). A symlink
+ * planted at the target after {@link assertBackupLeafWritable} is REPLACED by the rename, never
+ * followed. The staging directory is always removed; one left by a crashed process is named
+ * `.<basename>.staging-XXXXXX`, which the rotation pattern (`<db>.pre-reindex-<ms>.bak…`) never matches.
+ */
+function stageThenRename(backupPath: string, write: (staged: string) => SnapshotOutcome): SnapshotOutcome {
+  const staging = mkdtempSync(join(dirname(backupPath), `.${basename(backupPath)}.staging-`));
+  try {
+    const staged = join(staging, basename(backupPath));
+    const outcome = write(staged);
+    // Order main -> wal is deliberate: publishing the -wal FIRST would put a foreign WAL next to
+    // whatever main file sits at backupPath, which sqlite could apply to it.
+    const stagedId = lstatSync(staged); // identity of the file we are about to publish
+    renameSync(staged, backupPath);
+    if (outcome.method === 'copy+wal') {
+      try {
+        renameSync(`${staged}-wal`, `${backupPath}-wal`);
+      } catch (cause) {
+        // Review r1 (MAJOR): a published main file without its -wal is a half snapshot that reads
+        // as complete. Withdraw it — only if the entry is still the very file we just renamed
+        // (same dev+ino, regular file) — and fail loudly under a named reason.
+        let withdrawn = false;
+        try {
+          const now = lstatSync(backupPath);
+          if (now.isFile() && now.dev === stagedId.dev && now.ino === stagedId.ino) {
+            unlinkSync(backupPath);
+            withdrawn = true;
+          }
+        } catch { /* withdrawn stays false and is reported below */ }
+        const why = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(
+          `snapshot-wal-publish-failed: could not move the -wal sidecar to ${backupPath}-wal (${why}); ` +
+            (withdrawn
+              ? 'the just-published main file was withdrawn — no half snapshot left'
+              : `the main file at ${backupPath} could NOT be confirmed as ours and was left in place`),
+          { cause },
+        );
+      }
+    }
+    return outcome;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
 function copyWithWal(dbFile: string, backupPath: string, note: string): SnapshotOutcome {
   // AM-2: statSync directly; only a confirmed ENOENT means "no -wal to copy" — any other stat error
   // propagates out of this function (and out of snapshotSqliteDatabase) as a thrown exception.
@@ -158,7 +242,8 @@ function copyWithWal(dbFile: string, backupPath: string, note: string): Snapshot
  *
  * Throws (no snapshot taken, or an incomplete one left in a fully-cleared state) when: `backupPath`
  * already names an existing, non-empty file (AM-4); or a `-wal` stat probe hits a non-ENOENT error
- * (AM-2, inside the fallback path). Never silently overwrites, never mis-reports a lesser guarantee
+ * (AM-2, inside the fallback path); or `backupPath` is a symbolic link or an existing non-regular file
+ * (no-symlink-escape). Never silently overwrites, never mis-reports a lesser guarantee
  * as a stronger one.
  */
 export function snapshotSqliteDatabase(
@@ -167,8 +252,25 @@ export function snapshotSqliteDatabase(
   backupPath: string,
   opts: { strategy?: 'vacuum-into' | 'copy+wal' } = {},
 ): SnapshotOutcome {
+  assertBackupLeafWritable(backupPath); // no-symlink-escape — a link or non-file leaf is never written through
   assertBackupTargetFree(backupPath); // AM-4 — before any write, on either strategy
   clearBackupSidecars(backupPath); // AM-1 — clean slate before either strategy writes anything
+  const outcome = stageThenRename(backupPath, (staged) => writeSnapshot(Database, dbFile, staged, opts));
+  // AM-1 — VACUUM INTO's output never has a matching -wal of its own: clear again once it is in place.
+  if (outcome.method === 'vacuum-into') clearBackupSidecars(backupPath);
+  return outcome;
+}
+
+/**
+ * The two snapshot strategies, writing to `backupPath` — which {@link snapshotSqliteDatabase} always
+ * passes as the STAGED path inside its private staging directory, never the final target.
+ */
+function writeSnapshot(
+  Database: SnapshotDbCtor,
+  dbFile: string,
+  backupPath: string,
+  opts: { strategy?: 'vacuum-into' | 'copy+wal' },
+): SnapshotOutcome {
   if (opts.strategy === 'copy+wal') {
     return copyWithWal(dbFile, backupPath, 'snapshotStrategy=copy+wal forced by caller');
   }
@@ -179,8 +281,7 @@ export function snapshotSqliteDatabase(
     } finally {
       db.close();
     }
-    clearBackupSidecars(backupPath); // AM-1 — VACUUM INTO's output never has a matching -wal of its own
-    return { method: 'vacuum-into' };
+    return { method: 'vacuum-into' }; // AM-1 sidecar clear runs in snapshotSqliteDatabase, after the rename
   } catch (err) {
     return copyWithWal(dbFile, backupPath, `VACUUM INTO failed: ${err instanceof Error ? err.message : String(err)}`);
   }

package/src/apply-leg.ts

@@ -208,8 +208,16 @@ export function probeRecallEngine(socketPath: string, timeoutMs = 1000): Promise
  * skipped entirely in own-fallback mode. (c) `answerRecall`'s `embed(prompt)` call is now wrapped so
  * either failure mode degrades to the SAME honest `cosine-fallback` reply shape as every other
  * failure, never a bare protocol `{error}`.
+ *
+ * Bumped 12→13 (`retro-debt-sentinel-per-session`): the hook reads its admission-debt sentinel from
+ * `.dz/retro/<sessionId>/` (entry added retroactively for the record by the next bump).
+ *
+ * Bumped 13→14 (`daemon-install-root-from-self`, ADR-001, backlog 6dd464d5d6ee917f): the daemon's
+ * `INSTALL_ROOT` is two levels above its own directory (it was one short — `<root>/.claude` — so the
+ * install-root link never fired and the daemon served, and resolved its deps from, `cwd`); the hook's
+ * `reviveDaemon()` spawns it with `cwd: PROJECT` and `DZ_PROJECT_ROOT: PROJECT`.
  */
-export const APPLY_LEG_VERSION = 13;
+export const APPLY_LEG_VERSION = 14;
 
 /**
  * Parse the `dz-apply-leg-version` stamp from a deployed helper file. Unlike
@@ -595,7 +603,17 @@ function reviveDaemon() {
     const { spawn } = require('child_process');
     const daemon = path.join(PROJECT, '.claude', 'helpers', 'dz-embed-daemon.mjs');
     if (!fs.existsSync(daemon)) return;
-    const child = spawn(process.execPath, [daemon], { detached: true, stdio: 'ignore' });
+    // daemon-install-root-from-self (ADR-001 p.2): the daemon serves exactly the store this hook just
+    // checked. \`cwd\` so a self-healed daemon never inherits the caller's directory (the orphan with
+    // cwd=…/other from the 2026-09-15 field report); \`DZ_PROJECT_ROOT\` because the daemon ranks it
+    // ABOVE its own install root, so a stale value inherited by this hook would otherwise still
+    // re-route it (same class as AM-3 of apply-leg-install-root, for the SessionStart command).
+    const child = spawn(process.execPath, [daemon], {
+      cwd: PROJECT,
+      env: { ...process.env, DZ_PROJECT_ROOT: PROJECT },
+      detached: true,
+      stdio: 'ignore',
+    });
     child.unref();
   }, undefined);
 }
@@ -922,7 +940,7 @@ export function embedDaemonSource(coreDistDir: string | null = null): string {
 
 import { createServer } from 'node:net';
 import { existsSync, unlinkSync, readFileSync, mkdirSync, writeFileSync, renameSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { connect } from 'node:net';
 import { createHash } from 'node:crypto';
@@ -938,7 +956,11 @@ console.log = (...a) => console.error(...a);
 // recallHookSource's own PROJECT comment) — DZ_PROJECT_ROOT stays the TOP override for the daemon
 // (a caller that explicitly names a project root always wins), then INSTALL_ROOT (this file's own
 // location, when it owns a \`.dz/\`), then cwd.
-const INSTALL_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+// daemon-install-root-from-self (ADR-001 p.1): this file lives at <root>/.claude/helpers/, so the
+// install root is TWO levels above its directory — the hook's own rule (path.resolve(__dirname, '..',
+// '..')), written for ESM. The previous dirname(dirname(<file>)) stopped at <root>/.claude, so the
+// install-root link never fired and the daemon always served (and resolved its deps from) cwd.
+const INSTALL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const PROJECT = process.env['DZ_PROJECT_ROOT'] ?? (existsSync(join(INSTALL_ROOT, '.dz')) ? INSTALL_ROOT : process.cwd());
 
 // ADR-001 (hook-recall-hybrid-parity, D1): the SAME candidate-list resolution the hook uses for its

package/src/architecture.ts

@@ -9,7 +9,7 @@
  * helpers at the bottom do the disk I/O for the CLI and the feature-adr end-of-run auto-update.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 /** One curated subsystem — the top-layer intent node. */
@@ -192,13 +192,26 @@ export function renderDriftReport(report: DriftReport): string {
  * I/O helper (lazy `require`, never throws) shared by the CLI and the feature-adr end-of-run auto-update
  * (FR-3), so both build the map from the identical scan. Deterministic: output is sorted.
  */
+function isDirFollowingLinks(path: string): boolean {
+  try { return statSync(path).isDirectory(); } catch { return false; }
+}
+
 export function scanWorkspacePackages(repoRoot: string): ScannedPackage[] {
   try {
     const base = join(repoRoot, 'packages', '@dzhechkov');
     if (!existsSync(base)) return [];
     const out: ScannedPackage[] = [];
+    const seenReal = new Set<string>();
     for (const entry of readdirSync(base, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
+      // A symlink to a package directory is a package directory: `dz mutation-gate`'s shadow tree
+      // symlinks every sibling, and pnpm links workspace packages the same way. Dirent reports such
+      // an entry as a symlink, never as a directory, so follow it; a dangling link is skipped.
+      if (!entry.isDirectory() && !(entry.isSymbolicLink() && isDirFollowingLinks(join(base, entry.name)))) continue;
+      // An alias link to a directory already scanned is the SAME package — count it once.
+      let real: string;
+      try { real = realpathSync(join(base, entry.name)); } catch { continue; }
+      if (seenReal.has(real)) continue;
+      seenReal.add(real);
       const pj = join(base, entry.name, 'package.json');
       if (!existsSync(pj)) continue;
       let json: { name?: string; dependencies?: Record<string, string>; peerDependencies?: Record<string, string>; optionalDependencies?: Record<string, string> };