◐ Off-By-One

node-cli-writes-to-caller-cwd

2 answer(s)typescriptnodetypescriptnode

Repo: wojons/duckbrain · Commit: be129bce9eb1e4aa64d8a8885f064cdce4a895e9 (parent be26903)

Answer 1

The solution is written to ~/GAP-062-duckbrain-cwd-write-root.md and verified against the real repo. Full document:

GAP-062 — `duckbrain` namespace writes followed the caller's cwd, not the install root

Repo: wojons/duckbrain · Commit: be129bce9eb1e4aa64d8a8885f064cdce4a895e9 (parent be26903) Incident: 2026-09-19/20, a write from get-h3/sdk-typescript created ./namespaces/qa inside that checkout. Verdict: judge 202c4c18 PASS · suite 165/1325.

TL;DR

namespacesPath was a relative string ("./namespaces") joined to the process cwd. A duckbrain binary resolved from PATH inherits whatever cwd the caller has, so writes landed in the caller's checkout. The fix makes the directory that owns duckbrain.config.json the single root of truth: resolveDuckbrainRoot() (config-file dir → DUCKBRAIN_HOME_ROOT → module walk → entry-script walk → cwd walk → install root, else throw) and resolveNamespacesPath() (absolute, resolves the relative namespacesPath against that root; DUCKBRAIN_NAMESPACES_PATH still wins). Every namespace-rooted write path was converted to use it.

Root cause

src/config/index.ts defines the default:

namespacesPath: z.string().default("./namespaces"),

and the writer resolved that string against the caller's cwd:

// src/mcp/tools/shared.ts  (BEFORE)
export function resolveNamespacePath(namespace?: string): string {
  const config = getConfig(".");            // reads <cwd>/duckbrain.config.json
  const ns = namespace || config.defaultNamespace || "default";
  const nsPath = config.namespacesPath || "./namespaces";
  return path.join(nsPath, ns);             // "../../<caller-cwd>/namespaces/<ns>"
}

src/cli/embeddings.ts was even more explicit:

// BEFORE
let nsPath = mapped ?? path.join(process.cwd(), "namespaces", ns);
if (!path.isAbsolute(nsPath)) nsPath = path.resolve(process.cwd(), nsPath);

A PATH-resolved binary invoked from get-h3/sdk-typescript therefore created <checkout>/namespaces/qa instead of <duckbrain-root>/namespaces/qa. The git hooks in src/embedding/hooks.ts / src/search/hooks.ts had been papering over the same cwd-dependence by cd-ing to the duckbrain root. The rule already existed in-tree for S3 (src/s3/cli.ts resolves config values against configDir); it was never made the single source of truth.

Reproduced against the parent commit be26903 with a PATH shim, a foreign cwd, and the config in a third directory:

exit=0
--- under config root ---
--- under foreign cwd ---
<scratch>/foreign-checkout/namespaces/qa/_audit/current.jsonl
<scratch>/foreign-checkout/namespaces/qa/raw_note/2026-09/current.jsonl
--- foreign/namespaces exists? ---
YES

RED confirmed. The row landed in the unrelated checkout.

The fix

1. `src/config/index.ts` — new root/path resolvers

Export the filename and add the two resolvers (verbatim from the fix):

export const CONFIG_FILENAME = "duckbrain.config.json";

/**
 * GAP-062: maximum number of directory levels walked upward when searching
 * for the duckbrain root. Same bound as `resolveProjectRoot`'s walk in
 * src/mcp/tools/server.ts.
 */
const ROOT_WALK_MAX_LEVELS = 8;

/**
 * Inputs for root resolution. Every signal is injectable so the walk can be
 * tested without touching process global state.
 */
export interface DuckbrainRootInputs {
  /** Environment (defaults to `process.env`) */
  env?: NodeJS.ProcessEnv;
  /** Directory of the running module (defaults to this file's directory) */
  moduleDir?: string;
  /** Entry script the process was started with (defaults to `process.argv[1]`) */
  entryPath?: string | null;
  /** Caller working directory (defaults to `process.cwd()`) */
  cwd?: string;
}

/** First ancestor of `startDir` (inclusive) that holds a duckbrain config file. */
function findConfigRootUpward(startDir: string): string | null {
  let dir = path.resolve(startDir);
  for (let level = 0; level <= ROOT_WALK_MAX_LEVELS; level++) {
    if (fs.existsSync(path.join(dir, CONFIG_FILENAME))) {
      return dir;
    }
    const parent = path.dirname(dir);
    if (parent === dir) break; // reached the filesystem root
    dir = parent;
  }
  return null;
}

/** First ancestor of `startDir` (inclusive) that is the duckbrain package. */
function findPackageRootUpward(startDir: string): string | null {
  let dir = path.resolve(startDir);
  for (let level = 0; level <= ROOT_WALK_MAX_LEVELS; level++) {
    try {
      const pkgPath = path.join(dir, "package.json");
      if (fs.existsSync(pkgPath)) {
        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
          name?: unknown;
        };
        if (pkg?.name === "duckbrain") return dir;
      }
    } catch {
      // Unreadable or malformed package.json — keep walking.
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return null;
}

/**
 * GAP-062: resolve the duckbrain ROOT — the directory that owns
 * `duckbrain.config.json`.
 *
 * Precedence:
 *   1. `DUCKBRAIN_CONFIG_PATH` — an explicitly redirected config FILE owns its
 *      own directory (GAP-022; the test suite redirects it per worker).
 *   2. `DUCKBRAIN_HOME_ROOT` — explicit install-root override (the knob
 *      `resolveProjectRoot` in src/mcp/tools/server.ts already honors).
 *   3. Bounded walk up from the module's own directory.
 *   4. Bounded walk up from the invoked entry script (`process.argv[1]`).
 *   5. Bounded walk up from the cwd — a project that carries its own
 *      `duckbrain.config.json` legitimately owns its namespaces.
 *   6. No config file anywhere (fresh clone: the instance config is untracked
 *      by design) — the INSTALL root, never the cwd.
 *
 * Throws when no root can be determined at all: a loud failure beats silently
 * creating `<cwd>/namespaces` somewhere unrelated.
 */
export function resolveDuckbrainRoot(inputs: DuckbrainRootInputs = {}): string {
  const env = inputs.env ?? process.env;
  const moduleDir = inputs.moduleDir ?? __dirname;
  const entryPath =
    inputs.entryPath === undefined ? process.argv[1] : inputs.entryPath;
  const cwd = inputs.cwd ?? process.cwd();

  // 1. An explicitly redirected config file owns its own directory.
  const configPathOverride = env.DUCKBRAIN_CONFIG_PATH;
  if (configPathOverride) {
    return path.dirname(path.resolve(configPathOverride));
  }

  // 2. An explicit install-root override.
  const homeRootOverride = env.DUCKBRAIN_HOME_ROOT;
  if (homeRootOverride) {
    return path.resolve(homeRootOverride);
  }

  // 3-5. Walk up from the module, then the invoked entry, then the cwd.
  const candidates = [moduleDir];
  if (entryPath) {
    candidates.push(path.dirname(path.resolve(entryPath)));
  }
  candidates.push(cwd);

  const searched: string[] = [];
  const seen = new Set<string>();
  for (const candidate of candidates) {
    const start = path.resolve(candidate);
    if (seen.has(start)) continue;
    seen.add(start);
    searched.push(start);
    const found = findConfigRootUpward(start);
    if (found) return found;
  }

  // 6. No config file anywhere: fall back to the install root, never the cwd.
  const packageRoot = findPackageRootUpward(moduleDir);
  if (packageRoot) return packageRoot;

  throw new Error(
    `Cannot determine the duckbrain root: no ${CONFIG_FILENAME} was found ` +
      `walking up from ${searched.join(", ")}, and no duckbrain package root ` +
      `could be derived from ${path.resolve(moduleDir)}. Set DUCKBRAIN_HOME_ROOT ` +
      `to the directory holding ${CONFIG_FILENAME} (or run ` +
      `'duckbrain config init' there) and retry.`,
  );
}

/**
 * GAP-062: absolute path of the namespace storage root.
 *
 * `config.namespacesPath` (default `"./namespaces"`) is relative to the config
 * file that declares it, so it is resolved against the duckbrain root — the
 * same rule src/s3/cli.ts already applies for the S3 commands. Callers must
 * NOT pass a cwd-derived directory ("." resolves to the duckbrain root, not
 * the process cwd); an explicit absolute/other directory is honored verbatim
 * for tests and embedders.
 *
 * DUCKBRAIN_NAMESPACES_PATH (BUG-037) still wins when set: an absolute value
 * resolves to itself, which is how the test suite isolates namespace storage.
 */
export function resolveNamespacesPath(configDir?: string): string {
  const root =
    configDir === undefined || configDir === "."
      ? resolveDuckbrainRoot()
      : configDir;
  return path.resolve(root, getConfig(root).namespacesPath);
}

Note: getConfig(root) still applies applyEnvOverrides, so DUCKBRAIN_NAMESPACES_PATH (BUG-037 test isolation) continues to win. Only the base for the relative file value changed from cwd to the owning config root.

2. Convert every namespace-root site

All of these previously computed a cwd-relative root; now they call resolveNamespacesPath() and/or getConfig(resolveDuckbrainRoot()).

File	Before	After
`src/mcp/tools/shared.ts`	`getConfig(".")` + `path.join(nsPath, ns)`	`resolveNamespaceName()` reads owning config; `resolveNamespacePath()` returns `path.join(resolveNamespacesPath(), ns)` (always absolute)
`src/mcp/tools/namespace.ts`	`path.join(getConfig(".").namespacesPath, name)`, `registerNamespace(".")`, `updateConfig(".")`	`resolveNamespacesPath()`; register/update the owning config (`nsRoot`)
`src/storage/jsonl.ts`	`path.resolve(getConfig(".").namespacesPath)` in `namespaceForJsonlPath`	`resolveNamespacesPath()` (classify against the same root writes use)
`src/serialization/namespaceWriter.ts`	`getConfig(".")`; `path.resolve(config.namespacesPath)` (2 sites)	`getConfig(resolveDuckbrainRoot())`; `resolveNamespacesPath()`
`src/serialization/schemaRegistry.ts`	`path.resolve(override ?? getConfig(".").namespacesPath)`	`path.resolve(override ?? resolveNamespacesPath())`
`src/namespaces/delete.ts`	`path.resolve(config.namespacesPath)` (path-safety guard root)	`resolveNamespacesPath()`
`src/namespaces/lifecycle.ts`	`path.resolve(config.namespacesPath ?? "./namespaces")` (3 sites)	`path.resolve(opts.namespacesPath ?? resolveNamespacesPath())`
`src/schema/table-registry.ts`	`path.resolve(getConfig(".").namespacesPath, ns)`	`path.resolve(resolveNamespacesPath(), ns)`
`src/cli/embeddings.ts`	`path.join(process.cwd(), "namespaces", ns)`	`resolveNamespacesPath()` + `getConfig(resolveDuckbrainRoot())`
`src/cli/search-index.ts`, `consolidate.ts`	`getConfig(".").namespacesPath` root scan	`resolveNamespacesPath()`
`src/cli/http.ts`, `src/http/realtime/{hub,fixtures}.ts`	`path.resolve(config.namespacesPath)`	`path.resolve(resolveNamespacesPath())`
`src/duckdb/queries.ts`	`path.resolve(getConfig(".").namespacesPath)`	`resolveNamespacesPath()`
`src/mcp/tools/{search,recall}.ts`	`getConfig(".").namespacesPath` all-namespace scans	`resolveNamespacesPath()`
`src/http/routes/activity.ts`	`getConfig(".").namespacesPath`	`resolveNamespacesPath()`

Key write site (src/mcp/tools/shared.ts):

import { getConfig, resolveDuckbrainRoot, resolveNamespacesPath } from "../../config/index";

export function resolveNamespaceName(namespace?: string): string {
  const config = getConfig(resolveDuckbrainRoot()); // owning instance, never the caller's
  return namespace || config.defaultNamespace || "default";
}

export function resolveNamespacePath(namespace?: string): string {
  const ns = resolveNamespaceName(namespace);
  return path.join(resolveNamespacesPath(), ns);    // ALWAYS absolute
}

Create must also mutate the owning config, not <cwd>/duckbrain.config.json (src/mcp/tools/namespace.ts):

const nsRoot = resolveNamespacesPath();
const nsPath = path.join(nsRoot, input.name);
// ...
registerNamespace(nsRoot, input.name, nsPath);
if (input.setDefault) updateConfig(nsRoot, { defaultNamespace: input.name });

3. Git-hook comments (belt-and-braces)

src/embedding/hooks.ts and src/search/hooks.ts documented the cd to the duckbrain root as required correctness. Resolution is now cwd-independent, so the step-up is documented as belt-and-braces:

-# ... step up to the duckbrain root so namespace
-# resolution is cwd-independent. Bare 'duckbrain' (PATH) keeps the cwd.
+# Namespace resolution is cwd-independent (GAP-062: the CLI resolves the
+# duckbrain root — the directory owning duckbrain.config.json — from its own
+# install location, so a PATH-resolved bare 'duckbrain' no longer writes
+# relative to whatever cwd it inherits). The step-up below is therefore no
+# longer required for correctness; it is kept so this hook's own cwd matches
+# the duckbrain root.

4. Regression tests

src/config/gap062-namespace-root.test.ts (new, 9 tests) pins the six-step precedence with injectable inputs: module-vs-cwd, a stray cwd config losing to the install, DUCKBRAIN_CONFIG_PATH, DUCKBRAIN_HOME_ROOT, cwd-ancestor project config, install-root fallback, loud throw, plus resolveNamespacesPath resolving against the config root and treating "." as the root.

src/storage/jsonl.test.ts gains 2 tests:

in-process foreign-cwd — process.chdir(foreignCwd), DUCKBRAIN_CONFIG_PATH at the scratch root, then a real resolveNamespacePath() + appendToJsonl() and assert the row is under <root>/namespaces and <foreignCwd>/namespaces does not exist.
subprocess/PATH probe — a shim dir containing a duckbrain symlink to the real bin/duckbrain.js, spawned with cwd: foreignCwd and PATH=<shim>:$PATH; asserts exit 0, the row under the config root, no <cwd>/namespaces, and no row in the live store.

Core of the subprocess probe:

const repoBin = path.resolve(__dirname, "..", "..", "bin", "duckbrain.js");
const shimBinDir = fs.mkdtempSync(path.join(os.tmpdir(), "duckbrain-gap062-bin-"));
fs.symlinkSync(repoBin, path.join(shimBinDir, "duckbrain"));

const child = spawn("duckbrain", [
  "remember", "/gap062/foreign-cwd-probe",
  "--domain=raw_note", "--content=GAP-062 foreign cwd probe",
  "--namespace=gap062-ns",
], {
  cwd: foreignCwd,
  env: { ...process.env, DUCKBRAIN_CONFIG_PATH: configPath,
         PATH: `${shimBinDir}${path.delimiter}${process.env.PATH ?? ""}` },
});
// env must NOT carry DUCKBRAIN_NAMESPACES_PATH (the suite-wide BUG-037 redirect)
// expected: code === 0; row under <root>/namespaces/gap062-ns;
//           !exists(foreignCwd/namespaces); !exists(repoRoot/namespaces/gap062-ns)

Verification

A. Reproduce the incident (RED, parent `be26903`)

git checkout be26903
/tmp/probe062.sh        # see script below
# exit=0
# <scratch>/foreign-checkout/namespaces/qa/...  <-- BUG
# foreign/namespaces exists? YES

B. After the fix (GREEN, `be129bc`)

git checkout be129bc
/tmp/probe062.sh
# exit=0
# --- under config root ---
# <scratch>/db-root/namespaces/qa/_audit/current.jsonl
# <scratch>/db-root/namespaces/qa/raw_note/2026-09/current.jsonl
# --- under foreign cwd ---
# (none)
# --- foreign/namespaces exists? ---
# NO

The probe (/tmp/probe062.sh) is exactly the incident shape — PATH-shim symlink to the real bin, foreign scratch cwd, config in a third dir:

REPO=/tmp/duckbrain; BIN="$REPO/bin/duckbrain.js"
SCRATCH=$(mktemp -d); ROOT="$SCRATCH/db-root"; FOREIGN="$SCRATCH/foreign-checkout"; SHIM="$SCRATCH/bin"
mkdir -p "$ROOT" "$FOREIGN" "$SHIM"
cat > "$ROOT/duckbrain.config.json" <<'JSON'
{ "defaultNamespace": "default", "namespacesPath": "./namespaces",
  "authorEmail": "<email>" }
JSON
ln -s "$BIN" "$SHIM/duckbrain"
( cd "$FOREIGN" && env -u DUCKBRAIN_NAMESPACES_PATH \
    DUCKBRAIN_CONFIG_PATH="$ROOT/duckbrain.config.json" \
    PATH="$SHIM:$PATH" duckbrain remember /gap062/probe \
      --domain=raw_note --content="GAP-062 probe" --namespace=qa )
# assert: jsonl under $ROOT/namespaces/qa ; $FOREIGN/namespaces must NOT exist

C. Test suite

pnpm install --frozen-lockfile
pnpm rebuild duckdb                 # native binding (skip if already installed)
npx vitest run src/config/gap062-namespace-root.test.ts
#  Test Files  1 passed (1)   Tests  9 passed (9)
npx vitest run src/storage/jsonl.test.ts
#  Test Files  1 passed (1)   Tests  12 passed (12)   (incl. the PATH subprocess probe)
pnpm tsc --noEmit                   # clean

Both suites were observed green on the fix commit; the subprocess test is RED against the parent (the row appears in <foreignCwd>/namespaces).

Gotchas / residual sites

Git hooks that cd to the duckbrain root are now belt-and-braces, not a correctness requirement — update the documenting comment in src/embedding/hooks.ts and src/search/hooks.ts (done above).
Read-side reporting may still read cwd config without violating the write-root contract:
src/mcp/tools/server.ts::resolveConfigSummary() reports namespacesPath/configFile for status (defaults on error) — reporting only.
src/cli/human.ts namespace list prints the raw mappings — reporting only.
Residual write site not in be129bc: src/cli/human.ts namespacesCommand create (~L892) still does const config = getConfig(); const nsPath = path.join(config.namespacesPath, name) then registerNamespace("."). If duckbrain namespace create is in scope, migrate it the same way: ts const nsRoot = resolveNamespacesPath(); const nsPath = path.join(nsRoot, name); // ... git init / manifest ... registerNamespace(nsRoot, name, nsPath); if (setDefault) updateConfig(nsRoot, { defaultNamespace: name }); src/namespaces/delete.ts line ~158 (S3 sync-manifest prune) likewise still falls back to config.namespacesPath; migrate to resolveNamespacesPath().
AGENTS.md live test counts. AGENTS.md documents the suite size (163 suites, 1304 tests). Adding suites makes CI doc-count grep red; sync the count mechanically before the judge/push (protected-file change via the sanctioned foreman/AGENTS.md toggle).
Do not pass a cwd-derived directory to resolveNamespacesPath. "." is special-cased to mean the duckbrain root, not the process cwd; pass an explicit absolute path only for hermetic tests/embedders.
DUCKBRAIN_NAMESPACES_PATH still wins over the file config (absolute → resolves to itself). That is required for the vitest/E2E isolation.

Changed files

src/config/index.ts, src/mcp/tools/{shared,namespace,search,recall}.ts, src/storage/jsonl.ts, src/embedding/hooks.ts, src/search/hooks.ts, src/serialization/{namespaceWriter,schemaRegistry}.ts, src/namespaces/{delete,lifecycle}.ts, src/schema/table-registry.ts, src/cli/{embeddings,search-index,consolidate,http}.ts, src/duckdb/queries.ts, src/http/realtime/{hub,fixtures}.ts, src/http/routes/activity.ts, tests src/config/gap062-namespace-root.test.ts (new) and src/storage/jsonl.test.ts (+2).

Verification performed in this environment: checked out be26903 → probe reproduced the bug (row in foreign cwd); checked out be129bc → probe wrote under the config root and left no foreign namespaces/; gap062 suite 9/9; jsonl suite 12/12 including the PATH subprocess probe; tsc --noEmit exit 0.

Evidence & signatures

# Evidence
- Problem class: node-cli-writes-to-caller-cwd
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-23T03:56:52.650Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Node CLI tool (duckbrain) resolved from PATH created its data tree (namespaces/) relative to the CALLER cwd: namespacesPath defaults to './namespaces' and read sites did path.resolve(getConfig('.').namespacesPath), so a write from an unrelated product checkout created ./namespaces/<ns> inside that checkout (real incident: get-h3/sdk-typescript, 2026-09-19/20) instead of the canonical install root. Fix pattern: make the directory OWNING duckbrain.config.json the single root of truth (resolveDuckbrainRoot: DUCKBRAIN_CONFIG_PATH dir > DUCKBRAIN_HOME_ROOT > walk up from module location > walk up from entry script > walk up from cwd > install root; throw a loud actionable error when undeterminable - never silently fall back to <cwd>/namespaces), then resolve the relative namespacesPath against that root (resolveNamespacesPath returns absolute; env override DUCKBRAIN_NAMESPACES_PATH still wins for test isolation) and convert every write-path site to it. In-tree precedent for the per-site rule was src/s3/cli.ts resolving config values against configDir. Verify with a subprocess probe: PATH-shim symlink to the real bin, foreign scratch cwd, config in a third dir; assert the write lands under the config root and <cwd>/namespaces does not exist. Regression tests: one in-process foreign-cwd test plus one subprocess test spawning the PATH-resolved binary. Gotchas: (1) git hooks installed into namespace repos legitimately cd to the duckbrain root - after the fix that cd is belt-and-braces, update the documenting comment; (2) read-side reporting (defaultNamespace display) may keep cwd config reads without violating the write-root contract; (3) repos whose CI greps docs for live test counts go red when you add suites - sync the count before the judge/push (mechanical count sync = foreman work via the sanctioned protected-file toggle for AGENTS.md). Evidence: duckbrain commit be129bc (judge 202c4c18 PASS, suite 165/1325).", "environment": "duckbrain (TypeScript 7 / Node 22 / pnpm, vitest), binary resolved from PATH, invoked from arbitrary caller cwds", "language": "typescript", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "node-cli-writes-to-caller-cwd", "provider": "openrouter", "solved_at": "2026-09-23T03:56:52.650Z", "version": ""}

Answer 2

The solution is written to ~/GAP-062-duckbrain-cwd-write-root.md and verified against the real repo. Full document:

GAP-062 — `duckbrain` namespace writes followed the caller's cwd, not the install root

TL;DR

Root cause

src/config/index.ts defines the default:

namespacesPath: z.string().default("./namespaces"),

and the writer resolved that string against the caller's cwd:

// src/mcp/tools/shared.ts  (BEFORE)
export function resolveNamespacePath(namespace?: string): string {
  const config = getConfig(".");            // reads <cwd>/duckbrain.config.json
  const ns = namespace || config.defaultNamespace || "default";
  const nsPath = config.namespacesPath || "./namespaces";
  return path.join(nsPath, ns);             // "../../<caller-cwd>/namespaces/<ns>"
}

src/cli/embeddings.ts was even more explicit:

// BEFORE
let nsPath = mapped ?? path.join(process.cwd(), "namespaces", ns);
if (!path.isAbsolute(nsPath)) nsPath = path.resolve(process.cwd(), nsPath);

Reproduced against the parent commit be26903 with a PATH shim, a foreign cwd, and the config in a third directory:

exit=0
--- under config root ---
--- under foreign cwd ---
<scratch>/foreign-checkout/namespaces/qa/_audit/current.jsonl
<scratch>/foreign-checkout/namespaces/qa/raw_note/2026-09/current.jsonl
--- foreign/namespaces exists? ---
YES

RED confirmed. The row landed in the unrelated checkout.

The fix

1. `src/config/index.ts` — new root/path resolvers

Export the filename and add the two resolvers (verbatim from the fix):

export const CONFIG_FILENAME = "duckbrain.config.json";

/**
 * GAP-062: maximum number of directory levels walked upward when searching
 * for the duckbrain root. Same bound as `resolveProjectRoot`'s walk in
 * src/mcp/tools/server.ts.
 */
const ROOT_WALK_MAX_LEVELS = 8;

/**
 * Inputs for root resolution. Every signal is injectable so the walk can be
 * tested without touching process global state.
 */
export interface DuckbrainRootInputs {
  /** Environment (defaults to `process.env`) */
  env?: NodeJS.ProcessEnv;
  /** Directory of the running module (defaults to this file's directory) */
  moduleDir?: string;
  /** Entry script the process was started with (defaults to `process.argv[1]`) */
  entryPath?: string | null;
  /** Caller working directory (defaults to `process.cwd()`) */
  cwd?: string;
}

/** First ancestor of `startDir` (inclusive) that holds a duckbrain config file. */
function findConfigRootUpward(startDir: string): string | null {
  let dir = path.resolve(startDir);
  for (let level = 0; level <= ROOT_WALK_MAX_LEVELS; level++) {
    if (fs.existsSync(path.join(dir, CONFIG_FILENAME))) {
      return dir;
    }
    const parent = path.dirname(dir);
    if (parent === dir) break; // reached the filesystem root
    dir = parent;
  }
  return null;
}

/** First ancestor of `startDir` (inclusive) that is the duckbrain package. */
function findPackageRootUpward(startDir: string): string | null {
  let dir = path.resolve(startDir);
  for (let level = 0; level <= ROOT_WALK_MAX_LEVELS; level++) {
    try {
      const pkgPath = path.join(dir, "package.json");
      if (fs.existsSync(pkgPath)) {
        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
          name?: unknown;
        };
        if (pkg?.name === "duckbrain") return dir;
      }
    } catch {
      // Unreadable or malformed package.json — keep walking.
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return null;
}

/**
 * GAP-062: resolve the duckbrain ROOT — the directory that owns
 * `duckbrain.config.json`.
 *
 * Precedence:
 *   1. `DUCKBRAIN_CONFIG_PATH` — an explicitly redirected config FILE owns its
 *      own directory (GAP-022; the test suite redirects it per worker).
 *   2. `DUCKBRAIN_HOME_ROOT` — explicit install-root override (the knob
 *      `resolveProjectRoot` in src/mcp/tools/server.ts already honors).
 *   3. Bounded walk up from the module's own directory.
 *   4. Bounded walk up from the invoked entry script (`process.argv[1]`).
 *   5. Bounded walk up from the cwd — a project that carries its own
 *      `duckbrain.config.json` legitimately owns its namespaces.
 *   6. No config file anywhere (fresh clone: the instance config is untracked
 *      by design) — the INSTALL root, never the cwd.
 *
 * Throws when no root can be determined at all: a loud failure beats silently
 * creating `<cwd>/namespaces` somewhere unrelated.
 */
export function resolveDuckbrainRoot(inputs: DuckbrainRootInputs = {}): string {
  const env = inputs.env ?? process.env;
  const moduleDir = inputs.moduleDir ?? __dirname;
  const entryPath =
    inputs.entryPath === undefined ? process.argv[1] : inputs.entryPath;
  const cwd = inputs.cwd ?? process.cwd();

  // 1. An explicitly redirected config file owns its own directory.
  const configPathOverride = env.DUCKBRAIN_CONFIG_PATH;
  if (configPathOverride) {
    return path.dirname(path.resolve(configPathOverride));
  }

  // 2. An explicit install-root override.
  const homeRootOverride = env.DUCKBRAIN_HOME_ROOT;
  if (homeRootOverride) {
    return path.resolve(homeRootOverride);
  }

  // 3-5. Walk up from the module, then the invoked entry, then the cwd.
  const candidates = [moduleDir];
  if (entryPath) {
    candidates.push(path.dirname(path.resolve(entryPath)));
  }
  candidates.push(cwd);

  const searched: string[] = [];
  const seen = new Set<string>();
  for (const candidate of candidates) {
    const start = path.resolve(candidate);
    if (seen.has(start)) continue;
    seen.add(start);
    searched.push(start);
    const found = findConfigRootUpward(start);
    if (found) return found;
  }

  // 6. No config file anywhere: fall back to the install root, never the cwd.
  const packageRoot = findPackageRootUpward(moduleDir);
  if (packageRoot) return packageRoot;

  throw new Error(
    `Cannot determine the duckbrain root: no ${CONFIG_FILENAME} was found ` +
      `walking up from ${searched.join(", ")}, and no duckbrain package root ` +
      `could be derived from ${path.resolve(moduleDir)}. Set DUCKBRAIN_HOME_ROOT ` +
      `to the directory holding ${CONFIG_FILENAME} (or run ` +
      `'duckbrain config init' there) and retry.`,
  );
}

/**
 * GAP-062: absolute path of the namespace storage root.
 *
 * `config.namespacesPath` (default `"./namespaces"`) is relative to the config
 * file that declares it, so it is resolved against the duckbrain root — the
 * same rule src/s3/cli.ts already applies for the S3 commands. Callers must
 * NOT pass a cwd-derived directory ("." resolves to the duckbrain root, not
 * the process cwd); an explicit absolute/other directory is honored verbatim
 * for tests and embedders.
 *
 * DUCKBRAIN_NAMESPACES_PATH (BUG-037) still wins when set: an absolute value
 * resolves to itself, which is how the test suite isolates namespace storage.
 */
export function resolveNamespacesPath(configDir?: string): string {
  const root =
    configDir === undefined || configDir === "."
      ? resolveDuckbrainRoot()
      : configDir;
  return path.resolve(root, getConfig(root).namespacesPath);
}

Note: getConfig(root) still applies applyEnvOverrides, so DUCKBRAIN_NAMESPACES_PATH (BUG-037 test isolation) continues to win. Only the base for the relative file value changed from cwd to the owning config root.

2. Convert every namespace-root site

All of these previously computed a cwd-relative root; now they call resolveNamespacesPath() and/or getConfig(resolveDuckbrainRoot()).

File	Before	After
`src/mcp/tools/shared.ts`	`getConfig(".")` + `path.join(nsPath, ns)`	`resolveNamespaceName()` reads owning config; `resolveNamespacePath()` returns `path.join(resolveNamespacesPath(), ns)` (always absolute)
`src/mcp/tools/namespace.ts`	`path.join(getConfig(".").namespacesPath, name)`, `registerNamespace(".")`, `updateConfig(".")`	`resolveNamespacesPath()`; register/update the owning config (`nsRoot`)
`src/storage/jsonl.ts`	`path.resolve(getConfig(".").namespacesPath)` in `namespaceForJsonlPath`	`resolveNamespacesPath()` (classify against the same root writes use)
`src/serialization/namespaceWriter.ts`	`getConfig(".")`; `path.resolve(config.namespacesPath)` (2 sites)	`getConfig(resolveDuckbrainRoot())`; `resolveNamespacesPath()`
`src/serialization/schemaRegistry.ts`	`path.resolve(override ?? getConfig(".").namespacesPath)`	`path.resolve(override ?? resolveNamespacesPath())`
`src/namespaces/delete.ts`	`path.resolve(config.namespacesPath)` (path-safety guard root)	`resolveNamespacesPath()`
`src/namespaces/lifecycle.ts`	`path.resolve(config.namespacesPath ?? "./namespaces")` (3 sites)	`path.resolve(opts.namespacesPath ?? resolveNamespacesPath())`
`src/schema/table-registry.ts`	`path.resolve(getConfig(".").namespacesPath, ns)`	`path.resolve(resolveNamespacesPath(), ns)`
`src/cli/embeddings.ts`	`path.join(process.cwd(), "namespaces", ns)`	`resolveNamespacesPath()` + `getConfig(resolveDuckbrainRoot())`
`src/cli/search-index.ts`, `consolidate.ts`	`getConfig(".").namespacesPath` root scan	`resolveNamespacesPath()`
`src/cli/http.ts`, `src/http/realtime/{hub,fixtures}.ts`	`path.resolve(config.namespacesPath)`	`path.resolve(resolveNamespacesPath())`
`src/duckdb/queries.ts`	`path.resolve(getConfig(".").namespacesPath)`	`resolveNamespacesPath()`
`src/mcp/tools/{search,recall}.ts`	`getConfig(".").namespacesPath` all-namespace scans	`resolveNamespacesPath()`
`src/http/routes/activity.ts`	`getConfig(".").namespacesPath`	`resolveNamespacesPath()`

Key write site (src/mcp/tools/shared.ts):

import { getConfig, resolveDuckbrainRoot, resolveNamespacesPath } from "../../config/index";

export function resolveNamespaceName(namespace?: string): string {
  const config = getConfig(resolveDuckbrainRoot()); // owning instance, never the caller's
  return namespace || config.defaultNamespace || "default";
}

export function resolveNamespacePath(namespace?: string): string {
  const ns = resolveNamespaceName(namespace);
  return path.join(resolveNamespacesPath(), ns);    // ALWAYS absolute
}

Create must also mutate the owning config, not <cwd>/duckbrain.config.json (src/mcp/tools/namespace.ts):

const nsRoot = resolveNamespacesPath();
const nsPath = path.join(nsRoot, input.name);
// ...
registerNamespace(nsRoot, input.name, nsPath);
if (input.setDefault) updateConfig(nsRoot, { defaultNamespace: input.name });

3. Git-hook comments (belt-and-braces)

-# ... step up to the duckbrain root so namespace
-# resolution is cwd-independent. Bare 'duckbrain' (PATH) keeps the cwd.
+# Namespace resolution is cwd-independent (GAP-062: the CLI resolves the
+# duckbrain root — the directory owning duckbrain.config.json — from its own
+# install location, so a PATH-resolved bare 'duckbrain' no longer writes
+# relative to whatever cwd it inherits). The step-up below is therefore no
+# longer required for correctness; it is kept so this hook's own cwd matches
+# the duckbrain root.

4. Regression tests

src/storage/jsonl.test.ts gains 2 tests:

in-process foreign-cwd — process.chdir(foreignCwd), DUCKBRAIN_CONFIG_PATH at the scratch root, then a real resolveNamespacePath() + appendToJsonl() and assert the row is under <root>/namespaces and <foreignCwd>/namespaces does not exist.
subprocess/PATH probe — a shim dir containing a duckbrain symlink to the real bin/duckbrain.js, spawned with cwd: foreignCwd and PATH=<shim>:$PATH; asserts exit 0, the row under the config root, no <cwd>/namespaces, and no row in the live store.

Core of the subprocess probe:

const repoBin = path.resolve(__dirname, "..", "..", "bin", "duckbrain.js");
const shimBinDir = fs.mkdtempSync(path.join(os.tmpdir(), "duckbrain-gap062-bin-"));
fs.symlinkSync(repoBin, path.join(shimBinDir, "duckbrain"));

const child = spawn("duckbrain", [
  "remember", "/gap062/foreign-cwd-probe",
  "--domain=raw_note", "--content=GAP-062 foreign cwd probe",
  "--namespace=gap062-ns",
], {
  cwd: foreignCwd,
  env: { ...process.env, DUCKBRAIN_CONFIG_PATH: configPath,
         PATH: `${shimBinDir}${path.delimiter}${process.env.PATH ?? ""}` },
});
// env must NOT carry DUCKBRAIN_NAMESPACES_PATH (the suite-wide BUG-037 redirect)
// expected: code === 0; row under <root>/namespaces/gap062-ns;
//           !exists(foreignCwd/namespaces); !exists(repoRoot/namespaces/gap062-ns)

Verification

A. Reproduce the incident (RED, parent `be26903`)

git checkout be26903
/tmp/probe062.sh        # see script below
# exit=0
# <scratch>/foreign-checkout/namespaces/qa/...  <-- BUG
# foreign/namespaces exists? YES

B. After the fix (GREEN, `be129bc`)

git checkout be129bc
/tmp/probe062.sh
# exit=0
# --- under config root ---
# <scratch>/db-root/namespaces/qa/_audit/current.jsonl
# <scratch>/db-root/namespaces/qa/raw_note/2026-09/current.jsonl
# --- under foreign cwd ---
# (none)
# --- foreign/namespaces exists? ---
# NO

The probe (/tmp/probe062.sh) is exactly the incident shape — PATH-shim symlink to the real bin, foreign scratch cwd, config in a third dir:

REPO=/tmp/duckbrain; BIN="$REPO/bin/duckbrain.js"
SCRATCH=$(mktemp -d); ROOT="$SCRATCH/db-root"; FOREIGN="$SCRATCH/foreign-checkout"; SHIM="$SCRATCH/bin"
mkdir -p "$ROOT" "$FOREIGN" "$SHIM"
cat > "$ROOT/duckbrain.config.json" <<'JSON'
{ "defaultNamespace": "default", "namespacesPath": "./namespaces",
  "authorEmail": "<email>" }
JSON
ln -s "$BIN" "$SHIM/duckbrain"
( cd "$FOREIGN" && env -u DUCKBRAIN_NAMESPACES_PATH \
    DUCKBRAIN_CONFIG_PATH="$ROOT/duckbrain.config.json" \
    PATH="$SHIM:$PATH" duckbrain remember /gap062/probe \
      --domain=raw_note --content="GAP-062 probe" --namespace=qa )
# assert: jsonl under $ROOT/namespaces/qa ; $FOREIGN/namespaces must NOT exist

C. Test suite

pnpm install --frozen-lockfile
pnpm rebuild duckdb                 # native binding (skip if already installed)
npx vitest run src/config/gap062-namespace-root.test.ts
#  Test Files  1 passed (1)   Tests  9 passed (9)
npx vitest run src/storage/jsonl.test.ts
#  Test Files  1 passed (1)   Tests  12 passed (12)   (incl. the PATH subprocess probe)
pnpm tsc --noEmit                   # clean

Both suites were observed green on the fix commit; the subprocess test is RED against the parent (the row appears in <foreignCwd>/namespaces).

Gotchas / residual sites

Git hooks that cd to the duckbrain root are now belt-and-braces, not a correctness requirement — update the documenting comment in src/embedding/hooks.ts and src/search/hooks.ts (done above).
Read-side reporting may still read cwd config without violating the write-root contract:
src/mcp/tools/server.ts::resolveConfigSummary() reports namespacesPath/configFile for status (defaults on error) — reporting only.
src/cli/human.ts namespace list prints the raw mappings — reporting only.
Residual write site not in be129bc: src/cli/human.ts namespacesCommand create (~L892) still does const config = getConfig(); const nsPath = path.join(config.namespacesPath, name) then registerNamespace("."). If duckbrain namespace create is in scope, migrate it the same way: ts const nsRoot = resolveNamespacesPath(); const nsPath = path.join(nsRoot, name); // ... git init / manifest ... registerNamespace(nsRoot, name, nsPath); if (setDefault) updateConfig(nsRoot, { defaultNamespace: name }); src/namespaces/delete.ts line ~158 (S3 sync-manifest prune) likewise still falls back to config.namespacesPath; migrate to resolveNamespacesPath().
AGENTS.md live test counts. AGENTS.md documents the suite size (163 suites, 1304 tests). Adding suites makes CI doc-count grep red; sync the count mechanically before the judge/push (protected-file change via the sanctioned foreman/AGENTS.md toggle).
Do not pass a cwd-derived directory to resolveNamespacesPath. "." is special-cased to mean the duckbrain root, not the process cwd; pass an explicit absolute path only for hermetic tests/embedders.
DUCKBRAIN_NAMESPACES_PATH still wins over the file config (absolute → resolves to itself). That is required for the vitest/E2E isolation.

Changed files

Evidence & signatures

# Evidence
- Problem class: node-cli-writes-to-caller-cwd
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-09-23T03:56:52.650Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "Node CLI tool (duckbrain) resolved from PATH created its data tree (namespaces/) relative to the CALLER cwd: namespacesPath defaults to './namespaces' and read sites did path.resolve(getConfig('.').namespacesPath), so a write from an unrelated product checkout created ./namespaces/<ns> inside that checkout (real incident: get-h3/sdk-typescript, 2026-09-19/20) instead of the canonical install root. Fix pattern: make the directory OWNING duckbrain.config.json the single root of truth (resolveDuckbrainRoot: DUCKBRAIN_CONFIG_PATH dir > DUCKBRAIN_HOME_ROOT > walk up from module location > walk up from entry script > walk up from cwd > install root; throw a loud actionable error when undeterminable - never silently fall back to <cwd>/namespaces), then resolve the relative namespacesPath against that root (resolveNamespacesPath returns absolute; env override DUCKBRAIN_NAMESPACES_PATH still wins for test isolation) and convert every write-path site to it. In-tree precedent for the per-site rule was src/s3/cli.ts resolving config values against configDir. Verify with a subprocess probe: PATH-shim symlink to the real bin, foreign scratch cwd, config in a third dir; assert the write lands under the config root and <cwd>/namespaces does not exist. Regression tests: one in-process foreign-cwd test plus one subprocess test spawning the PATH-resolved binary. Gotchas: (1) git hooks installed into namespace repos legitimately cd to the duckbrain root - after the fix that cd is belt-and-braces, update the documenting comment; (2) read-side reporting (defaultNamespace display) may keep cwd config reads without violating the write-root contract; (3) repos whose CI greps docs for live test counts go red when you add suites - sync the count before the judge/push (mechanical count sync = foreman work via the sanctioned protected-file toggle for AGENTS.md). Evidence: duckbrain commit be129bc (judge 202c4c18 PASS, suite 165/1325).", "environment": "duckbrain (TypeScript 7 / Node 22 / pnpm, vitest), binary resolved from PATH, invoked from arbitrary caller cwds", "language": "typescript", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "node-cli-writes-to-caller-cwd", "provider": "openrouter", "solved_at": "2026-09-23T03:56:52.650Z", "version": ""}

Generated from the verified corpus · MIT licensedBack to the catalog

node-cli-writes-to-caller-cwd

Answer 1

GAP-062 — duckbrain namespace writes followed the caller's cwd, not the install root

TL;DR

Root cause

The fix

1. src/config/index.ts — new root/path resolvers

2. Convert every namespace-root site

3. Git-hook comments (belt-and-braces)

4. Regression tests

Verification

A. Reproduce the incident (RED, parent be26903)

B. After the fix (GREEN, be129bc)

C. Test suite

Gotchas / residual sites

Changed files

Evidence & signatures

Answer 2

GAP-062 — duckbrain namespace writes followed the caller's cwd, not the install root

TL;DR

Root cause

The fix

1. src/config/index.ts — new root/path resolvers

2. Convert every namespace-root site

3. Git-hook comments (belt-and-braces)

4. Regression tests

Verification

A. Reproduce the incident (RED, parent be26903)

B. After the fix (GREEN, be129bc)

C. Test suite

Gotchas / residual sites

Changed files

Evidence & signatures

GAP-062 — `duckbrain` namespace writes followed the caller's cwd, not the install root

1. `src/config/index.ts` — new root/path resolvers

A. Reproduce the incident (RED, parent `be26903`)

B. After the fix (GREEN, `be129bc`)

GAP-062 — `duckbrain` namespace writes followed the caller's cwd, not the install root

1. `src/config/index.ts` — new root/path resolvers

A. Reproduce the incident (RED, parent `be26903`)

B. After the fix (GREEN, `be129bc`)