@lifeaitools/clauth 2.1.1 → 2.10.0

package/cli/mcp/tool-schemas.test.js

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { MCP_TOOLS, MCP_WRITE_TOOL_NAMES, filterMcpToolsForWriteMode } from "./tool-schemas.js";
+import { MCP_TOOLS as reExported } from "../commands/serve.js";
+
+test("MCP_TOOLS is a non-empty array of schema objects with unique names", () => {
+  assert.ok(Array.isArray(MCP_TOOLS));
+  assert.ok(MCP_TOOLS.length > 50, "the real tool catalog is much larger than 50 — a near-empty array means the extraction lost data");
+  const names = MCP_TOOLS.map((t) => t.name);
+  assert.equal(new Set(names).size, names.length, "duplicate tool names would mean two schemas collided during the move");
+  for (const tool of MCP_TOOLS) {
+    assert.equal(typeof tool.name, "string");
+    assert.equal(typeof tool.description, "string");
+    assert.equal(typeof tool.inputSchema, "object");
+  }
+});
+
+test("MCP_WRITE_TOOL_NAMES names only tools that actually exist in MCP_TOOLS", () => {
+  const names = new Set(MCP_TOOLS.map((t) => t.name));
+  for (const writeName of MCP_WRITE_TOOL_NAMES) {
+    assert.ok(names.has(writeName), `${writeName} is in MCP_WRITE_TOOL_NAMES but not in MCP_TOOLS — a stale/renamed entry`);
+  }
+});
+
+test("filterMcpToolsForWriteMode hides write tools by default and reveals them under CLAUTH_MCP_WRITE=1", () => {
+  const old = process.env.CLAUTH_MCP_WRITE;
+  try {
+    delete process.env.CLAUTH_MCP_WRITE;
+    const hidden = filterMcpToolsForWriteMode(MCP_TOOLS);
+    assert.equal(hidden.length, MCP_TOOLS.length - MCP_WRITE_TOOL_NAMES.size);
+    assert.ok(hidden.every((t) => !MCP_WRITE_TOOL_NAMES.has(t.name)));
+
+    process.env.CLAUTH_MCP_WRITE = "1";
+    const revealed = filterMcpToolsForWriteMode(MCP_TOOLS);
+    assert.equal(revealed.length, MCP_TOOLS.length);
+  } finally {
+    if (old === undefined) delete process.env.CLAUTH_MCP_WRITE;
+    else process.env.CLAUTH_MCP_WRITE = old;
+  }
+});
+
+// Regression: cli/index.js does `import { MCP_TOOLS } from "./commands/serve.js"`.
+// serve.js no longer DEFINES MCP_TOOLS — it re-exports the moved module's copy.
+// If that re-export line were ever dropped, this is the test that catches it,
+// not a runtime failure discovered by whoever next runs `clauth mcp list`.
+test("serve.js re-exports the SAME MCP_TOOLS array the tool-schemas module defines", () => {
+  assert.equal(reExported, MCP_TOOLS, "serve.js's re-export must be the identical array reference, not a copy");
+});

package/cli/ops/pm2-preflight.js

@@ -0,0 +1,54 @@
+// cli/ops/pm2-preflight.js
+// PM2 is clauth's deployment fabric -- the ops server (cli/http/servers/
+// ops-server.js) and `clauth ops install` cannot exist without it. Both used
+// to do `import pm2 from "pm2"` as a static top-level import: a missing or
+// corrupted node_modules/pm2 install made that import throw at module-load
+// time, which -- because serve.js imports ops-server.js unconditionally --
+// crashed the ENTIRE clauth daemon (vault included), not just the ops
+// feature, with no recovery attempt. pm2 is a real declared dependency in
+// package.json, so a plain `npm install` in clauth's own repo root restores
+// it; this is the shared repair path both call sites use instead of a bare
+// static import.
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export async function ensurePm2() {
+  try {
+    const mod = await import("pm2");
+    return mod.default ?? mod;
+  } catch (firstError) {
+    try {
+      execSync("npm install", { cwd: ROOT_DIR, stdio: "pipe" });
+    } catch (installError) {
+      throw new Error(
+        `pm2 is missing and \`npm install\` failed to restore it (${installError.message}). ` +
+        `clauth's ops/deployment fabric cannot start without pm2. Original error: ${firstError.message}`
+      );
+    }
+    try {
+      const mod = await import("pm2");
+      return mod.default ?? mod;
+    } catch (secondError) {
+      throw new Error(
+        `pm2 is still unavailable after \`npm install\` (${secondError.message}). ` +
+        `clauth's ops/deployment fabric cannot start without pm2.`
+      );
+    }
+  }
+}
+
+// A cheap presence-only check (no repair) for callers that just want to know
+// before deciding whether to run the repair themselves -- e.g. `clauth
+// install`'s prerequisite check, which reports the finding rather than
+// silently repairing mid-install.
+export async function pm2Available() {
+  try {
+    await import("pm2");
+    return true;
+  } catch {
+    return false;
+  }
+}

package/cli/recovery.js

@@ -9,6 +9,12 @@ import * as api from "./api.js";
 const RECOVERY_VERSION = 1;
 
 function getRecoveryDir() {
+  // Test isolation escape hatch, same pattern as supervisor-registry.js's
+  // CLAUTH_SUPERVISOR_DIR: getConfOptions() has no override and always resolves
+  // to the real user's AppData, so without this a test calling
+  // snapshotCredentialBeforeWrite() would write into Dave's actual recovery
+  // folder rather than a throwaway temp dir.
+  if (process.env.CLAUTH_RECOVERY_DIR) return process.env.CLAUTH_RECOVERY_DIR;
   const opts = getConfOptions();
   if (opts.cwd) return path.join(opts.cwd, "recovery");
   return path.join(os.homedir(), ".config", "clauth", "recovery");

package/cli/recovery.test.js

@@ -0,0 +1,179 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  normalizeCredentialValue,
+  snapshotCredentialBeforeWrite,
+  writeCredentialWithRecovery,
+} from "./recovery.js";
+
+// `fn` is always async — MUST be awaited inside try, or this finally fires
+// (and rmSync deletes the dir) before fn's body has even made its first fetch
+// call, and every assertion inside fn then races a directory that is already
+// gone.
+async function withTempRecoveryDir(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-recovery-test-"));
+  const old = process.env.CLAUTH_RECOVERY_DIR;
+  process.env.CLAUTH_RECOVERY_DIR = dir;
+  const machineIdOld = process.env.CLAUTH_MACHINE_ID;
+  process.env.CLAUTH_MACHINE_ID = "recovery-test-machine";
+  try {
+    return await fn(dir);
+  } finally {
+    if (old === undefined) delete process.env.CLAUTH_RECOVERY_DIR;
+    else process.env.CLAUTH_RECOVERY_DIR = old;
+    if (machineIdOld === undefined) delete process.env.CLAUTH_MACHINE_ID;
+    else process.env.CLAUTH_MACHINE_ID = machineIdOld;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// api.js's post() calls the global fetch — mocking it here needs no ESM
+// module-mock trickery, since fetch is a global rather than a named export.
+function withMockFetch(handler, fn) {
+  const old = globalThis.fetch;
+  globalThis.fetch = handler;
+  return (async () => {
+    try { return await fn(); } finally { globalThis.fetch = old; }
+  })();
+}
+
+function jsonResponse(status, body) {
+  return { ok: status >= 200 && status < 300, status, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+// ── normalizeCredentialValue: pure, no mocking needed ────────────────────────
+
+test("normalizeCredentialValue passes ordinary values through untouched", () => {
+  assert.equal(normalizeCredentialValue("hello", { service: "npm-token" }), "hello");
+  assert.equal(normalizeCredentialValue(42, {}), 42);
+  assert.equal(normalizeCredentialValue(null, {}), null);
+});
+
+test("normalizeCredentialValue normalizes line endings and trailing newline on a PEM key", () => {
+  const pem = "-----BEGIN RSA PRIVATE KEY-----\r\nabc\r\ndef\r\n-----END RSA PRIVATE KEY-----";
+  const out = normalizeCredentialValue(pem, { service: "some-key" });
+  assert.ok(!out.includes("\r"), "CRLF must be normalized to LF for a PEM value");
+  assert.ok(out.endsWith("-----END RSA PRIVATE KEY-----\n"), "must end with exactly one trailing newline");
+});
+
+test("normalizeCredentialValue treats an ssh-typed or ssh-named service as key material even without PEM headers", () => {
+  const raw = "ssh-ed25519 AAAAC3...\r\n";
+  const bySuffix = normalizeCredentialValue(raw, { service: "vultr-dev-ssh" });
+  assert.ok(!bySuffix.includes("\r"));
+  const byKeyType = normalizeCredentialValue(raw, { keyType: "ssh", service: "anything" });
+  assert.ok(!byKeyType.includes("\r"));
+});
+
+test("normalizeCredentialValue leaves a plain token's newlines alone — it is not key material", () => {
+  const value = "npm_abc123\r\nsome-trailing-junk";
+  assert.equal(normalizeCredentialValue(value, { service: "npm-token" }), value);
+});
+
+// ── snapshotCredentialBeforeWrite: needs a fetch mock + isolated dir ────────
+
+test("snapshotCredentialBeforeWrite refuses without password, machineHash, or service", async () => {
+  const result = await snapshotCredentialBeforeWrite({ password: "", machineHash: "h", service: "s" });
+  assert.equal(result.ok, false);
+  assert.equal(result.skipped, "missing_context");
+});
+
+test("snapshotCredentialBeforeWrite writes an encrypted, recoverable snapshot for an existing credential", async () =>
+  await withTempRecoveryDir(async (dir) => {
+    await withMockFetch(
+      async () => jsonResponse(200, { value: "super-secret-value", key_type: "token" }),
+      async () => {
+        const result = await snapshotCredentialBeforeWrite({
+          password: "hunter2", machineHash: "abc123", service: "demo-service",
+        });
+        assert.equal(result.ok, true, JSON.stringify(result));
+        assert.ok(fs.existsSync(result.filePath), "the snapshot file must actually exist on disk");
+        const payload = JSON.parse(fs.readFileSync(result.filePath, "utf8"));
+        assert.equal(payload.service, "demo-service");
+        assert.equal(payload.cipher, "aes-256-gcm");
+        // The ciphertext must not contain the plaintext — the whole point of
+        // encrypting the snapshot rather than writing the raw value to disk.
+        const raw = fs.readFileSync(result.filePath, "utf8");
+        assert.ok(!raw.includes("super-secret-value"), "the plaintext secret leaked into the snapshot file");
+      },
+    );
+  }));
+
+test("snapshotCredentialBeforeWrite is a safe no-op when there is no existing value to protect", async () =>
+  await withTempRecoveryDir(async (dir) => {
+    await withMockFetch(
+      async () => jsonResponse(200, { value: null }),
+      async () => {
+        const result = await snapshotCredentialBeforeWrite({
+          password: "hunter2", machineHash: "abc123", service: "brand-new-service",
+        });
+        assert.equal(result.ok, false);
+        assert.equal(result.skipped, "no_existing_value");
+        assert.equal(fs.readdirSync(dir).length, 0, "nothing should be written when there is nothing to snapshot");
+      },
+    );
+  }));
+
+test("snapshotCredentialBeforeWrite reports retrieve_failed without throwing when the vault is unreachable", async () =>
+  await withTempRecoveryDir(async () => {
+    await withMockFetch(
+      async () => { throw new Error("fetch failed"); },
+      async () => {
+        const result = await snapshotCredentialBeforeWrite({
+          password: "hunter2", machineHash: "abc123", service: "demo-service",
+        });
+        assert.equal(result.ok, false);
+        assert.equal(result.skipped, "retrieve_failed");
+      },
+    );
+  }));
+
+// ── writeCredentialWithRecovery: snapshot-then-write orchestration ─────────
+
+test("writeCredentialWithRecovery snapshots the OLD value before writing the new one", async () =>
+  await withTempRecoveryDir(async (dir) => {
+    const calls = [];
+    await withMockFetch(
+      async (url, opts) => {
+        const body = JSON.parse(opts.body);
+        calls.push(body.action || url);
+        if (String(url).includes("/status")) return jsonResponse(200, { services: [{ name: "demo-service", key_type: "token" }] });
+        if (String(url).includes("/retrieve")) return jsonResponse(200, { value: "old-value" });
+        if (String(url).includes("/write")) return jsonResponse(200, { ok: true });
+        return jsonResponse(404, { error: "unknown route" });
+      },
+      async () => {
+        const { result, snapshot } = await writeCredentialWithRecovery({
+          password: "hunter2", machineHash: "abc123", service: "demo-service", value: "new-value",
+        });
+        assert.equal(result.ok, true);
+        assert.equal(snapshot.ok, true, "the pre-write snapshot must succeed so 'old-value' is recoverable");
+        const payload = JSON.parse(fs.readFileSync(snapshot.filePath, "utf8"));
+        assert.equal(payload.service, "demo-service");
+      },
+    );
+    assert.ok(fs.readdirSync(dir).length >= 1, "a snapshot file must exist after the write");
+  }));
+
+test("writeCredentialWithRecovery still writes the new value even when there was nothing to snapshot", async () =>
+  await withTempRecoveryDir(async () => {
+    await withMockFetch(
+      async (url) => {
+        if (String(url).includes("/status")) return jsonResponse(200, { services: [] });
+        if (String(url).includes("/retrieve")) return jsonResponse(200, { value: null });
+        if (String(url).includes("/write")) return jsonResponse(200, { ok: true });
+        return jsonResponse(404, { error: "unknown route" });
+      },
+      async () => {
+        const { result, snapshot } = await writeCredentialWithRecovery({
+          password: "hunter2", machineHash: "abc123", service: "brand-new-service", value: "new-value",
+        });
+        assert.equal(result.ok, true, "the write itself must not be blocked by a failed/skipped snapshot");
+        assert.equal(snapshot.ok, false);
+        assert.equal(snapshot.skipped, "no_existing_value");
+      },
+    );
+  }));

package/cli/services/agent-pool-instance.js

@@ -0,0 +1,38 @@
+// cli/services/agent-pool-instance.js
+// The lazily-instantiated singleton behind call_agent's interactive warm pool
+// (call_agent MCP tool + POST /call-agent). Split out of
+// agent-pool-singleton.js -- the SOLID scorer flagged that file's original
+// shape (74.1 total) as mixing this concern with the separate DelegationLane
+// singleton, which shares no worker/slot/queue with this pool.
+//
+// AgentPool itself is defined in ../commands/agent-pool.js; this module only
+// owns the module-level singleton state and lazy construction.
+
+import { AgentPool } from "../commands/agent-pool.js";
+
+let _agentPool = null;
+export function getAgentPool() {
+  if (_agentPool) return _agentPool;
+  const poolSize = parseInt(process.env.CLAUTH_AGENT_POOL_SIZE || "2", 10);
+  const warmSize = parseInt(process.env.CLAUTH_AGENT_WARM_SIZE || String(Number.isFinite(poolSize) ? poolSize : 2), 10);
+  _agentPool = new AgentPool({
+    poolSize: Number.isFinite(poolSize) ? poolSize : 2,
+    warmSize: Number.isFinite(warmSize) ? warmSize : 2,
+    defaultModel: process.env.CLAUTH_AGENT_MODEL || "claude-haiku-4-5",
+  });
+  _agentPool.startReaper();
+  console.log(`[agent-pool] init: binary=${_agentPool.binary ? 'found' : 'MISSING'} warmEnabled=${_agentPool.warmEnabled} available=${_agentPool.available()} poolSize=${_agentPool.poolSize} warmSize=${_agentPool.warmSize}`);
+  // WP-P2: boot persistent re-targetable warm workers in the background so the
+  // first real call_agent dispatch hits a hot worker (sub-boot latency). Never
+  // blocks daemon startup; if warm isn't ready yet, dispatch falls back to cold.
+  if (_agentPool.warmEnabled && _agentPool.available()) {
+    _agentPool.prime().then((r) => {
+      console.log(`[agent-pool] prime complete: mode=${r.mode} warmed=${r.warmed} workers=${r.workers ?? 'n/a'}`);
+    }).catch((e) => {
+      console.error(`[agent-pool] prime failed: ${e.message}`);
+    });
+  } else {
+    console.log(`[agent-pool] prime skipped: warmEnabled=${_agentPool.warmEnabled} available=${_agentPool.available()}`);
+  }
+  return _agentPool;
+}

package/cli/services/claude-binary.js

@@ -0,0 +1,29 @@
+// cli/services/claude-binary.js
+// Locates the `claude` CLI binary, and the default working directory, for
+// spawning terminal/chitchat sessions. Shared by the terminal session manager
+// and the chitchat collab sessions — neither owns these exclusively, so they
+// get their own small module rather than living inside either.
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+
+export const CHITCHAT_CWD = "C:/Dev/regen-root";
+export const CHITCHAT_FALLBACK_CWD = CHITCHAT_CWD;
+
+export function findClaudeBinary() {
+  const candidates = [
+    process.env.CLAUDE_BIN,
+    path.join(os.homedir(), '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude'),
+    path.join(process.env.APPDATA || '', 'npm', 'claude.cmd'),
+    path.join(process.env.APPDATA || '', 'npm', 'claude'),
+    'claude', // PATH fallback
+  ].filter(Boolean);
+
+  for (const c of candidates) {
+    try {
+      execSync(`"${c}" --version`, { stdio: 'ignore', timeout: 3000 });
+      return c;
+    } catch {}
+  }
+  return null;
+}

package/cli/services/delegation-lane-instance.js

@@ -0,0 +1,35 @@
+// cli/services/delegation-lane-instance.js
+// The lazily-instantiated singleton hop-limited DelegationLane for sub-agent
+// call_agent calls. Split out of agent-pool-singleton.js -- the SOLID scorer
+// flagged that file's original shape as mixing this concern with the
+// separate interactive AgentPool singleton.
+//
+// A SEPARATE, cold-spawn-only lane for DELEGATED (sub-agent) call_agent calls.
+// It shares NO worker, slot, or queue with the interactive AgentPool, so a
+// parent worker delegating to a sub-agent can never starve or hold an
+// interactive pool slot (anti-deadlock -- see DelegationLane in agent-pool.js).
+//
+// The ENTIRE delegation capability is gated behind CLAUTH_AGENT_DELEGATION
+// (default OFF). When off, delegationEnabled() is false, getDelegationLane()
+// returns null and is never constructed, and runCallAgent ignores
+// agent_context.delegation entirely -- call_agent is byte-identical to today.
+
+import { DelegationLane } from "../commands/agent-pool.js";
+
+export function delegationEnabled() {
+  return String(process.env.CLAUTH_AGENT_DELEGATION ?? "0") === "1";
+}
+
+let _delegationLane = null;
+export function getDelegationLane() {
+  if (!delegationEnabled()) return null; // gate OFF → lane never exists
+  if (_delegationLane) return _delegationLane;
+  const maxInFlight = parseInt(process.env.CLAUTH_AGENT_DELEGATION_MAX_INFLIGHT || "4", 10);
+  const maxHops = parseInt(process.env.CLAUTH_AGENT_DELEGATION_MAX_HOPS || "2", 10);
+  _delegationLane = new DelegationLane({
+    maxInFlight: Number.isFinite(maxInFlight) ? maxInFlight : 4,
+    maxHops: Number.isFinite(maxHops) ? maxHops : 2,
+    defaultModel: process.env.CLAUTH_AGENT_MODEL || "claude-haiku-4-5",
+  });
+  return _delegationLane;
+}

package/cli/services/delegation-lane-instance.test.js

@@ -0,0 +1,37 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { delegationEnabled, getDelegationLane } from "./delegation-lane-instance.js";
+
+test("delegationEnabled is off by default — call_agent is byte-identical without it", () => {
+  const old = process.env.CLAUTH_AGENT_DELEGATION;
+  try {
+    delete process.env.CLAUTH_AGENT_DELEGATION;
+    assert.equal(delegationEnabled(), false);
+  } finally {
+    if (old === undefined) delete process.env.CLAUTH_AGENT_DELEGATION;
+    else process.env.CLAUTH_AGENT_DELEGATION = old;
+  }
+});
+
+test("getDelegationLane never constructs a lane while the gate is off", () => {
+  const old = process.env.CLAUTH_AGENT_DELEGATION;
+  try {
+    delete process.env.CLAUTH_AGENT_DELEGATION;
+    assert.equal(getDelegationLane(), null);
+  } finally {
+    if (old === undefined) delete process.env.CLAUTH_AGENT_DELEGATION;
+    else process.env.CLAUTH_AGENT_DELEGATION = old;
+  }
+});
+
+test("delegationEnabled reads CLAUTH_AGENT_DELEGATION=1 as on", () => {
+  const old = process.env.CLAUTH_AGENT_DELEGATION;
+  try {
+    process.env.CLAUTH_AGENT_DELEGATION = "1";
+    assert.equal(delegationEnabled(), true);
+  } finally {
+    if (old === undefined) delete process.env.CLAUTH_AGENT_DELEGATION;
+    else process.env.CLAUTH_AGENT_DELEGATION = old;
+  }
+});

package/cli/services/file-io.js

@@ -0,0 +1,38 @@
+// cli/services/file-io.js
+// Small file primitives shared by the fs_* MCP tools: hashing, atomic writes,
+// and stat+hash metadata. Split out of fs-mount.js for the same SRP reason as
+// git-exec.js/fs-upload-sessions.js — these are file-content concerns, not
+// mount-resolution concerns.
+
+import path from "node:path";
+import crypto from "node:crypto";
+import { mkdir, writeFile, rename, stat, readFile } from "node:fs/promises";
+
+export function sha256Hex(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export async function atomicWriteText(filePath, content) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`
+  );
+  await writeFile(tempPath, content, "utf8");
+  await rename(tempPath, filePath);
+}
+
+export async function fileInfo(filePath, requestedPath) {
+  const s = await stat(filePath);
+  const info = {
+    path: requestedPath,
+    type: s.isDirectory() ? "dir" : "file",
+    size: s.size,
+    modified: s.mtime.toISOString(),
+  };
+  if (s.isFile()) {
+    const content = await readFile(filePath);
+    info.sha256 = sha256Hex(content);
+  }
+  return info;
+}

package/cli/services/file-io.test.js

@@ -0,0 +1,10 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { sha256Hex } from "./file-io.js";
+
+test("sha256Hex hashes deterministically", () => {
+  assert.equal(sha256Hex("hello"), sha256Hex("hello"));
+  assert.notEqual(sha256Hex("hello"), sha256Hex("world"));
+  assert.match(sha256Hex("hello"), /^[0-9a-f]{64}$/);
+});

package/cli/services/fs-mount.js

@@ -0,0 +1,66 @@
+// cli/services/fs-mount.js
+// Fileserver-mount resolution: loads mount config from the vault (cached),
+// resolves a requested path safely within a mount, and checks the mount's
+// access-flag string. Everything else that used to live in this file (upload
+// sessions, git-exec wrappers, file-io, vault-read, git-import-path guards)
+// moved to its own single-purpose module — see the sibling files in this
+// directory — after the SOLID scorer flagged this file's original 12-export
+// shape as low-SRP ("10 connected component(s) across 12 members").
+
+import path from "node:path";
+import { deriveToken } from "../fingerprint.js";
+import * as api from "../api.js";
+
+let _fsMountsCache = null;
+let _fsMountsCacheTime = 0;
+const FS_CACHE_TTL = 60000; // 1 minute
+
+export async function getFileserverMounts(vault) {
+  if (!vault.password) return { error: "Vault is locked — unlock first" };
+  const now = Date.now();
+  if (_fsMountsCache && now - _fsMountsCacheTime < FS_CACHE_TTL) return { mounts: _fsMountsCache };
+
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.status(vault.password, vault.machineHash, token, timestamp);
+    if (result.error) return { error: result.error };
+    const mounts = [];
+    for (const s of (result.services || [])) {
+      if (s.key_type === "fileserver" && s.enabled) {
+        try {
+          const { token: t2, timestamp: ts2 } = deriveToken(vault.password, vault.machineHash);
+          const secret = await api.retrieve(vault.password, vault.machineHash, t2, ts2, s.name);
+          if (secret.value) {
+            const config = JSON.parse(secret.value);
+            mounts.push({ name: s.name, path: config.path, access: config.access || "r" });
+          }
+        } catch {}
+      }
+    }
+    _fsMountsCache = mounts;
+    _fsMountsCacheTime = now;
+    return { mounts };
+  } catch (err) {
+    return { error: `Mount lookup failed: ${err.message}` };
+  }
+}
+
+export async function resolveInMount(requestedPath, mountName, vault) {
+  const { mounts, error } = await getFileserverMounts(vault);
+  if (error) return { error };
+  if (!mounts || mounts.length === 0) return { error: "No fileserver services configured. Add one with key_type='fileserver' and value: {\"path\": \"C:/Dev/regen-root\", \"access\": \"rwdg\"}  (access flags: r=read w=write d=delete g=git)" };
+  const mount = mountName ? mounts.find(m => m.name === mountName) : mounts[0];
+  if (!mount) return { error: `Mount '${mountName}' not found. Available: ${mounts.map(m => m.name).join(", ")}` };
+  if (!mount.path) return { error: `Fileserver '${mount.name}' has no path configured` };
+  const resolved = path.resolve(mount.path, requestedPath);
+  const normalized = path.normalize(resolved);
+  const relative = path.relative(path.normalize(mount.path), normalized);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return { error: `Path escapes mount: ${requestedPath}` };
+  }
+  return { resolved: normalized, mount };
+}
+
+export function checkAccess(mount, flag) {
+  return mount.access.includes(flag);
+}

package/cli/services/fs-mount.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { resolveInMount, checkAccess } from "./fs-mount.js";
+
+test("getFileserverMounts is refused without a vault password", async () => {
+  const result = await resolveInMount("a.txt", null, { password: null });
+  assert.equal(result.error, "Vault is locked — unlock first");
+});
+
+test("checkAccess reads the mount's access-flag string directly", () => {
+  assert.equal(checkAccess({ access: "rwdg" }, "w"), true);
+  assert.equal(checkAccess({ access: "r" }, "w"), false);
+});

package/cli/services/fs-upload-sessions.js

@@ -0,0 +1,20 @@
+// cli/services/fs-upload-sessions.js
+// Chunked fs_write_chunk upload session registry: size/count limits + TTL
+// eviction. Split out of fs-mount.js (was one of 12 loosely-related exports
+// in a single file, which the SOLID scorer flagged as low-SRP — "10 connected
+// component(s) across 12 members," i.e. mostly-independent siblings crammed
+// together). This file has exactly one reason to change: upload-session
+// bookkeeping.
+
+export const FS_UPLOAD_SESSIONS = new Map();
+export const FS_UPLOAD_TTL_MS = 30 * 60 * 1000;
+export const FS_MAX_CHUNKS = 500;
+export const FS_MAX_CHUNK_BYTES = 128 * 1024;
+export const FS_MAX_INGEST_BYTES = 25 * 1024 * 1024;
+
+export function cleanupFsUploadSessions() {
+  const cutoff = Date.now() - FS_UPLOAD_TTL_MS;
+  for (const [id, session] of FS_UPLOAD_SESSIONS) {
+    if (session.updatedAt < cutoff) FS_UPLOAD_SESSIONS.delete(id);
+  }
+}

package/cli/services/fs-upload-sessions.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { FS_UPLOAD_SESSIONS, cleanupFsUploadSessions } from "./fs-upload-sessions.js";
+
+test("cleanupFsUploadSessions evicts sessions past the TTL and keeps fresh ones", () => {
+  FS_UPLOAD_SESSIONS.clear();
+  FS_UPLOAD_SESSIONS.set("stale", { updatedAt: 0 });
+  FS_UPLOAD_SESSIONS.set("fresh", { updatedAt: Date.now() });
+  cleanupFsUploadSessions();
+  assert.equal(FS_UPLOAD_SESSIONS.has("stale"), false);
+  assert.equal(FS_UPLOAD_SESSIONS.has("fresh"), true);
+  FS_UPLOAD_SESSIONS.delete("fresh");
+});

package/cli/services/git-exec.js

@@ -0,0 +1,37 @@
+// cli/services/git-exec.js
+// Simple synchronous git spawn wrappers used by fs_exec and the git-import
+// path specifically. Distinct from ../lib/fs-git.js, which holds the pure,
+// independently-testable git plumbing (commit/diff/branch/status) — these
+// two do NOT duplicate that; they exist because fs_exec needs a raw,
+// unopinionated "run git, give me stdout or throw" primitive in both text
+// and buffer form.
+
+import { spawnSync } from "node:child_process";
+
+export function runGit(cwd, args, opts = {}) {
+  const res = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    windowsHide: true,
+    maxBuffer: opts.maxBuffer || 10 * 1024 * 1024,
+  });
+  if (res.status !== 0) {
+    const detail = (res.stderr || res.stdout || "").trim();
+    throw new Error(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return (res.stdout || "").trim();
+}
+
+export function runGitRaw(cwd, args, opts = {}) {
+  const res = spawnSync("git", args, {
+    cwd,
+    encoding: "buffer",
+    windowsHide: true,
+    maxBuffer: opts.maxBuffer || 10 * 1024 * 1024,
+  });
+  if (res.status !== 0) {
+    const detail = Buffer.concat([res.stderr || Buffer.alloc(0), res.stdout || Buffer.alloc(0)]).toString("utf8").trim();
+    throw new Error(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return res.stdout || Buffer.alloc(0);
+}