deepdebug-local-agent 1.5.0 → 1.7.0

package/test/la-protocol-v2/content-deny-list.test.js

@@ -0,0 +1,138 @@
+// F3-07c: the narrowed deny list (Edu, 2026-11-03): block the files that ARE credentials, serve the code that merely talks about them.
+// `credentials*` used to block credentials.service.ts; now a name that mentions credential/kubeconfig is served only when its last
+// extension is source code. The DLP (enforce, mandatory) stays the second layer for whatever is served.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { isSensitivePath, resolveInside, CODE_EXTENSIONS } from "../../src/la-protocol-v2/content-handlers/path-guard.js";
+import { ContentRefRegistry } from "../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { setup, write, tmpDir } from "./helpers/content-rig.js";
+
+// [path, sensitive?]  Every row is one name the guard must classify; "dir" rows are listing entries that are folders.
+const FILES = [
+    // ---- served: code and docs whose NAME mentions a credential (the reason for the change)
+    ["credentials.service.ts", false], ["src/auth/credentials.service.ts", false], ["CredentialsController.java", false],
+    ["src/main/java/io/x/CredentialsController.java", false], ["credentials_test.py", false], ["tests/test_credentials.py", false],
+    ["credentials.js", false], ["credentials.mjs", false], ["credentials.tsx", false], ["credentialsHelper.go", false],
+    ["credentials_store.rs", false], ["CredentialProvider.kt", false], ["credentials.rb", false], ["Credentials.cs", false],
+    ["credentials.php", false], ["credentials.vue", false], ["credentials.sql", false], ["credentials.md", false],
+    ["docs/credentials.md", false], ["credentials.spec.ts", false], ["credentials.d.ts", false], ["aws-credentials-loader.ts", false],
+    ["credential-store.js", false], ["CREDENTIALS.SERVICE.TS", false], ["credentials.service.ts.", false], ["credentials.html", false],
+    // ---- served: look-alikes that are not about secrets at all
+    ["env.ts", false], ["env.d.ts", false], ["env.mjs", false], ["env.config.js", false], ["src/env/index.js", false], ["environment.ts", false],
+    ["src/environment.js", false], ["kubeconfig.go", false], ["KubeconfigLoader.java", false], ["kubeconfig_loader.py", false],
+    ["secrets.service.ts", false], ["SecretsManager.java", false], ["README.md", false], ["package.json", false], ["src/keyboard.js", false],
+    ["docs/pem-format.md", false], ["tsconfig.json", false], ["src/secretary.js", false], [".gitignore", false], [".github/workflows/ci.yml", false],
+    ["src/credentials/index.ts", false], ["src/credentials/CredentialsService.java", false], ["env.ts.snap.ts", false], [".environment.ts", false],
+    // ---- blocked: files that ARE credentials (Edu's list)
+    ["credentials", true], [".credentials", true], ["credentials.json", true], ["credentials.yml", true], ["credentials.yaml", true],
+    ["credentials.xml", true], ["credentials.toml", true], ["credentials.ini", true], ["credentials.cfg", true], ["credentials.conf", true],
+    ["credentials.csv", true], ["credentials.txt", true], ["credentials.properties", true], ["credentials.db", true], ["credentials.sqlite", true],
+    ["credentials.enc", true], ["credentials.pem", true], ["credentials.p12", true], ["credentials.pfx", true], ["credentials.kdbx", true],
+    ["credentials.tfvars", true], ["credentials.env", true], ["application_default_credentials.json", true], ["x.credentials", true],
+    ["aws/credentials", true], [".aws/credentials", true], ["gcloud/credentials.db", true], [".config/gcloud/credentials.db", true],
+    ["CREDENTIALS.JSON", true], ["Credentials.Yml", true], ["deep/er/credentials.json", true], ["gcp-credentials.json", true],
+    ["credentials.prod.json", true], ["credentials.json.bak", true], ["credentials.bak", true], ["credentials~", true], ["credentials-prod", true],
+    ["credential.json", true], ["credentials.sh", true], ["credentials.service.json", true], ["credentials.json.", true],
+    ["credentials/prod.json", true], ["src/credentials/README", true], ["src/credentials/key.txt", true], [".credentials/token", true],
+    // ---- blocked: env files and their variants (the gaps the reviewer found)
+    [".env", true], [".env.local", true], [".env.production", true], [".env.production.local", true], [".envrc", true], [".envrc.local", true],
+    [".env_backup", true], [".env-prod", true], [".env.local~", true], [".env~", true], [".env#", true], ["env.production", true], ["env.local", true],
+    ["env_prod", true], ["env-staging", true], ["env", true], ["prod.env", true], ["app/.ENV", true], [".env2", true], [".envs/.production/.postgres", true],
+    // ---- blocked: kube, secrets, keys, npm/pip/net, docker, git, ssh
+    ["kubeconfig", true], ["kubeconfig-prod", true], ["kubeconfig_dev", true], ["kubeconfig.yaml", true], ["prod.kubeconfig", true], [".kube/config", true],
+    ["secrets/api.txt", true], ["config/secrets/prod.yml", true], ["secrets/manager.ts", true], [".secrets/x", true], ["secrets.json", true], ["secrets.yaml", true],
+    ["id_rsa", true], ["id_rsa.pub", true], ["id_rsa_github", true], ["id_ed25519", true], ["id_ed25519.pub", true], ["id_ed25519_work", true], ["id_ecdsa", true],
+    ["server.pem", true], ["private.key", true], ["release.keystore", true], ["debug.keystore", true], ["app.jks", true], ["cert.p12", true], ["vault.kdbx", true],
+    [".npmrc", true], ["pkg/.npmrc", true], [".pypirc", true], [".netrc", true], ["_netrc", true], [".pgpass", true], [".git-credentials", true],
+    [".docker/config.json", true], [".ssh/known_hosts", true], [".git/config", true], [".aws/config", true], [".gnupg/pubring.kbx", true],
+    ["terraform.tfstate", true], ["prod.tfvars", true], ["service-account-prod.json", true], [".htpasswd", true],
+    // ---- blocked: Windows aliases and streams of the above
+    ["CREDEN~1.JSO", true], ["CREDEN~1", true], ["ENV~1", true], ["KUBECO~1", true], [".env::$DATA", true], ["credentials.json:Zone.Identifier", true],
+    // ---- F3-07c review: credential files that no earlier rule named (blocked) and their look-alikes (served)
+    [".dockercfg", true], [".yarnrc", true], [".yarnrc.yml", true], [".pnpmrc", true], [".s3cfg", true], [".boto", true], [".terraformrc", true],
+    [".Renviron", true], ["auth.json", true], ["sub/auth.json", true], ["client_secret_123.json", true], ["firebase-adminsdk-abc.json", true],
+    ["gha-creds-1234.json", true], ["local.settings.json", true], ["wp-config.php", true], ["application-prod.properties", true],
+    ["application-prod.yml", true], ["application-prod.yaml", true], ["deploy_rsa", true], ["host_ed25519", true], ["ssh_host_rsa_key", true],
+    [".m2/settings.xml", true], [".m2/settings-security.xml", true], [".envrc/a.txt", true], [".env_backup/a.txt", true], [".env-prod/a.txt", true],
+    ["env.production/a.txt", true], ["kubeconfig-prod/a.txt", true], ["ENVRC~1", true], ["ENVS~1/x", true],
+    ["settings.xml", false], ["pom.xml", false], ["src/main/resources/application.yml", false], ["application-dev.yml", false],
+    ["application-test.properties", false], ["auth.ts", false], ["author.json", false], ["auth.service.ts", false], ["wp-config-sample.php", false],
+    ["rsa.ts", false], ["key_ed25519.ts", false], ["src/m2/settings.xml", false],
+];
+
+test("deny list table (F3-07c): >= 80 names, served and blocked, each one on its own", () => {
+    assert.ok(FILES.length >= 80, `${FILES.length} rows`);
+    assert.ok(FILES.filter(([, s]) => !s).length >= 30 && FILES.filter(([, s]) => s).length >= 50, "both sides are well covered");
+    const wrong = FILES.filter(([p, s]) => isSensitivePath(p) !== s).map(([p, s]) => `${p} expected ${s ? "blocked" : "served"}`);
+    assert.deepEqual(wrong, []);
+});
+
+test("deny list: a folder entry (dir) is judged as a folder: src/credentials is a folder of code, .credentials and secrets are not", () => {
+    for (const [p, sens] of [["credentials", false], ["src/credentials", false], ["Credentials", false], ["credential", false], ["kubeconfig", false], ["env", false],
+        [".credentials", true], ["secrets", true], [".secrets", true], [".git", true], [".ssh", true], [".aws", true], [".envs", true], [".env", true], ["x/.env", true],
+        ["node_modules", false], ["src", false], ["docs", false], ["environment", false]]) {
+        assert.equal(isSensitivePath(p, [], { dir: true }), sens, `dir ${p}`);
+    }
+    // the same name as a FILE stays blocked: the guard never serves a file called `credentials`
+    assert.equal(isSensitivePath("src/credentials"), true);
+});
+
+test("deny list: code extensions are an allow list; data formats, scripts and backups never are", () => {
+    for (const e of ["ts", "java", "py", "go", "js", "md", "sql", "kt", "rb", "cs", "rs", "php", "vue", "svelte"]) assert.ok(CODE_EXTENSIONS.has(e), e);
+    for (const e of ["json", "yml", "yaml", "xml", "toml", "ini", "cfg", "conf", "csv", "txt", "properties", "db", "sqlite", "enc", "pem", "p12", "pfx", "kdbx", "tfvars", "env",
+        "sh", "bash", "ps1", "bat", "gradle", "bak", "old", "orig", "tmp", "swp", "map", "snap", "j2", "log", ""]) assert.equal(CODE_EXTENSIONS.has(e), false, e);
+    for (const e of ["json", "yml", "toml", "txt", "sh", "bak"]) assert.equal(isSensitivePath(`credentials.${e}`), true, e);
+    for (const e of ["ts", "java", "py", "go", "md"]) assert.equal(isSensitivePath(`credentials.${e}`), false, e);
+});
+
+test("deny list: LOCAL_AGENT_CONTENT_DENY_GLOBS still adds to it (credentials.service.ts can be put back by an operator)", () => {
+    assert.equal(isSensitivePath("credentials.service.ts", ["credentials*"]), true);
+    assert.equal(isSensitivePath("credentials.service.ts", []), false);
+    assert.equal(isSensitivePath("src/x.ts", ["src/"]), true);
+});
+
+test("deny list: the registry never mints an id for a blocked name, and mints for credentials.service.ts; a folder id for src/credentials", () => {
+    const reg = new ContentRefRegistry({ tenantId: "t1" });
+    const q = { workspaceId: "w", root: "/r" };
+    assert.ok(reg.mint({ ...q, kind: "file", rel: "src/credentials.service.ts" }));
+    for (const rel of ["credentials.json", ".envrc", "env.production", "secrets/x.ts", "credentials"]) assert.equal(reg.mint({ ...q, kind: "file", rel }), null, rel);
+    assert.ok(reg.mint({ ...q, kind: "file.list", rel: "src/credentials" }), "a folder named credentials may be listed");
+    assert.equal(reg.mint({ ...q, kind: "file.list", rel: "secrets" }), null);
+    assert.equal(reg.mint({ ...q, kind: "file.list", rel: ".credentials" }), null);
+    assert.ok(reg.mint({ ...q, kind: "file.list", rel: null }), "the root");
+});
+
+test("deny list at read time: credentials.service.ts is served (masked by the DLP), credentials.json and a link to it are not", async () => {
+    const rig = await setup({ dlp: "enforce" });
+    try {
+        const secret = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+        write(rig.root(), "src/credentials.service.ts", `export const token = "${secret}";\nexport const ok = 1;\n`);
+        write(rig.root(), "credentials.json", `{"token":"${secret}"}`);
+        const good = rig.mint("file", "src/credentials.service.ts");
+        assert.ok(good, "an id exists for the code file");
+        const r = await rig.request({ ref: good });
+        assert.equal(r.status, "ok");
+        assert.equal(r.text.includes(secret), false, "the DLP is still the second layer");
+        assert.match(r.text, /export const ok = 1/);
+        assert.equal(rig.mint("file", "credentials.json"), null);
+        // swapped in after the id was minted: a harmless name that now links to credentials.json
+        write(rig.root(), "later.ts", "x");
+        const id = rig.mint("file", "later.ts");
+        fs.rmSync(path.join(rig.root(), "later.ts"));
+        fs.symlinkSync(path.join(rig.root(), "credentials.json"), path.join(rig.root(), "later.ts"));
+        assert.equal((await rig.request({ ref: id })).status, "forbidden");
+        assert.deepEqual(await resolveInside(rig.root(), "credentials.json"), { ok: false, status: "forbidden" });
+        assert.equal((await resolveInside(rig.root(), "src/credentials.service.ts")).ok, true);
+    } finally { await rig.stop(); }
+});
+
+test("deny list: nothing about the new rules is a regex over the whole path (no catastrophic backtracking on a long name)", () => {
+    const long = "credentials".repeat(5000) + ".json";
+    const t = Date.now();
+    assert.equal(isSensitivePath(long.slice(0, 1000)), true);
+    assert.equal(isSensitivePath("a/".repeat(500) + "x.ts"), false);
+    assert.ok(Date.now() - t < 500);
+    void tmpDir;
+});

package/test/la-protocol-v2/content-diff-symlink.test.js

@@ -0,0 +1,83 @@
+// F3-07c: `git diff` of a tracked symlink prints the TARGET of the link ("new file mode 120000", "+/abs/path"): an absolute path of this
+// machine. Entries whose mode is 120000 on either side no longer reach the diff. Real repositories, real links.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { setup, write, git, initRepo, tmpDir } from "./helpers/content-rig.js";
+import { rawPaths, dropSymlinkBlocks, worktreeDiff } from "../../src/la-protocol-v2/content-handlers/git-diff.js";
+
+async function withRig(opts, body) {
+    const rig = await setup(opts);
+    try { await body(rig); } finally { await rig.stop(); }
+}
+
+const OUTSIDE = "/very/private/absolute/target/of-the-link";
+
+test("diff: a tracked symlink that is retargeted, deleted, replaced by a file or created by replacing a file never prints its target; regular files still diff", async () => {
+    await withRig({}, async (rig) => {
+        const root = rig.root();
+        write(root, "regular.txt", "one\n");
+        write(root, "was-file.txt", "content\n");
+        write(root, "was-link-target.txt", "t\n");
+        fs.symlinkSync("/old/absolute/target-a", path.join(root, "link-retarget"));
+        fs.symlinkSync("/old/absolute/target-b", path.join(root, "link-deleted"));
+        fs.symlinkSync("/old/absolute/target-c", path.join(root, "link-becomes-file"));
+        initRepo(root);
+        // work tree changes
+        write(root, "regular.txt", "two\n");
+        fs.rmSync(path.join(root, "link-retarget")); fs.symlinkSync(OUTSIDE, path.join(root, "link-retarget"));
+        fs.rmSync(path.join(root, "link-deleted"));
+        fs.rmSync(path.join(root, "link-becomes-file")); write(root, "link-becomes-file", "now a file\n");
+        fs.rmSync(path.join(root, "was-file.txt")); fs.symlinkSync(OUTSIDE + "-2", path.join(root, "was-file.txt"));
+        // sanity: plain git DOES print the targets (this is what the guard hides)
+        const raw = git(root, "diff", "HEAD");
+        assert.match(raw, /new file mode 120000|deleted file mode 120000|120000/);
+        assert.ok(raw.includes(OUTSIDE) || raw.includes("/old/absolute/target"), "plain git shows the target");
+        const d = await rig.request({ kind: "diff", ref: "worktree" });
+        assert.equal(d.status, "ok");
+        assert.match(d.text, /regular\.txt/);
+        assert.match(d.text, /\+two/);
+        for (const leak of ["120000", OUTSIDE, "/old/absolute", "link-retarget", "link-deleted", "link-becomes-file", "was-file.txt"]) assert.equal(d.text.includes(leak), false, `leaked ${leak}`);
+        // an id for one path that is a link: empty diff, not the target
+        const one = rig.mint("diff", "link-retarget");
+        const o = await rig.request({ kind: "diff", ref: one });
+        assert.deepEqual([o.status, o.text], ["ok", ""]);
+    });
+});
+
+test("diff: a file turned into a link AFTER the file list was taken is still not printed (lstat net); the text net removes any block with mode 120000", async () => {
+    const root = tmpDir();
+    write(root, "a.txt", "1\n"); write(root, "b.txt", "1\n");
+    initRepo(root);
+    write(root, "a.txt", "2\n"); write(root, "b.txt", "2\n");
+    fs.rmSync(path.join(root, "b.txt")); fs.symlinkSync(OUTSIDE, path.join(root, "b.txt"));
+    const r = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 100, timeoutMs: 8000 });
+    assert.equal(r.ok, true);
+    assert.match(r.text, /a\.txt/);
+    assert.equal(r.text.includes("b.txt"), false);
+    assert.equal(r.text.includes(OUTSIDE), false);
+    fs.rmSync(root, { recursive: true, force: true });
+
+    const fake = [
+        "diff --git a/l b/l\nnew file mode 120000\nindex 0000000..e69de29\n--- /dev/null\n+++ b/l\n@@ -0,0 +1 @@\n+/etc/hostname\n\\n",
+        "diff --git a/m b/m\ndeleted file mode 120000\nindex e69de29..0000000\n--- a/m\n+++ /dev/null\n@@ -1 +0,0 @@\n-/etc/hosts\n",
+        "diff --git a/n b/n\nold mode 100644\nnew mode 120000\n",
+        "diff --git a/o b/o\nindex 1111111..2222222 120000\n--- a/o\n+++ b/o\n@@ -1 +1 @@\n-/a\n+/b\n",
+        "diff --git a/ok b/ok\nindex 1111111..2222222 100644\n--- a/ok\n+++ b/ok\n@@ -1 +1 @@\n-mode 120000 is just text here\n+new file mode 120000 neither\n",
+    ];
+    const out = dropSymlinkBlocks(fake.join(""));
+    assert.equal(out, fake[4], "only the regular file's block survives, including a body that talks about 120000");
+    assert.equal(dropSymlinkBlocks(fake[4]), fake[4]);
+    assert.equal(dropSymlinkBlocks(""), "");
+});
+
+test("diff: git diff --raw -z parsing: modes on either side, paths with spaces/newlines/unicode, and no path is ever split", () => {
+    const out = ":100644 100644 aaa bbb M\0src/a b.txt\0:100644 120000 aaa 000 T\0link\0:120000 000000 aaa 000 D\0gone\0:000000 100644 000 bbb A\0não\nsplit.txt\0:100755 100755 aaa bbb M\0x\0";
+    assert.deepEqual(rawPaths(out), [
+        { path: "src/a b.txt", symlink: false }, { path: "link", symlink: true }, { path: "gone", symlink: true },
+        { path: "não\nsplit.txt", symlink: false }, { path: "x", symlink: false },
+    ]);
+    assert.deepEqual(rawPaths(""), []);
+    assert.deepEqual(rawPaths(":100644 100644 a b M"), [], "a truncated entry gives nothing");
+});

package/test/la-protocol-v2/content-file-list.test.js

@@ -0,0 +1,385 @@
+// F3-07c: `file.list`, the producer of the opaque ids. Real V2Session, real handler, real folders on disk; the control plane is the
+// in-memory ReferenceCp. Against the REAL gateway: tools/interop/LaV2NodeContentRelayE2ETest.java (F3-07c section).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { ReferenceCp, TENANT, AGENT, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { setup, write, tmpDir } from "./helpers/content-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+import { listFolder } from "../../src/la-protocol-v2/content-handlers/file-list.js";
+import { ContentRefRegistry } from "../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { resolveContentHandlersConfig } from "../../src/la-protocol-v2/content-handlers/config.js";
+
+const ID43 = /^[A-Za-z0-9_-]{43}$/;
+const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+const contract = loadContract();
+
+async function withRig(opts, body) {
+    const rig = await setup(opts);
+    try { await body(rig); } finally { await rig.stop(); }
+}
+const list = (rig, ref = "root", extra = {}) => rig.request({ kind: "file.list", ref, ...extra });
+const body = (r) => JSON.parse(r.text);
+const names = (r) => body(r).entries.map((e) => e.name);
+
+/** A workspace with everything the listing must and must not show. */
+function seed(root) {
+    write(root, "README.md", `# readme\ntoken ${GH}\n`);
+    write(root, "a.txt", "aaa");
+    write(root, "credentials.service.ts", "export const x = 1;\n");
+    write(root, "src/main.ts", "export {};\n");
+    write(root, "src/credentials/index.ts", "export {};\n");
+    // never listed
+    write(root, ".env", "A=1");
+    write(root, "credentials.json", "{}");
+    write(root, ".envrc", "export A=1");
+    write(root, "secrets/api.txt", "x");
+    write(root, ".git/config", "[core]");
+    write(root, "id_rsa", "x");
+    write(root, "server.pem", "x");
+}
+
+test("file.list: the root lists what may be served, dirs first then names by bytes; credentials.service.ts is there, .env and credentials.json are not (not even their names)", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const r = await list(rig);
+        assert.deepEqual([r.status, r.contentType], ["ok", "application/json"]);
+        assert.deepEqual(names(r), ["src", "README.md", "a.txt", "credentials.service.ts"]);
+        for (const never of [".env", "credentials.json", ".envrc", "secrets", ".git", "id_rsa", "server.pem"]) assert.equal(r.text.includes(never), false, never);
+        const b = body(r);
+        assert.equal(contract.validateBody("file.list.body.schema.json", b), true, "the body is the contract's body");
+        assert.deepEqual(b.entries.map((e) => e.type), ["dir", "file", "file", "file"]);
+        assert.equal(b.nextRef, undefined);
+        for (const e of b.entries) assert.match(e.id, ID43);
+        assert.equal(new Set(b.entries.map((e) => e.id)).size, 4, "one id per entry");
+        const a = b.entries.find((e) => e.name === "a.txt");
+        assert.equal(a.size, 3);
+        assert.ok(Math.abs(Date.parse(a.mtime) - fs.statSync(path.join(rig.root(), "a.txt")).mtimeMs) < 2000);
+        assert.equal(b.entries[0].size, 0, "a folder has size 0");
+    });
+});
+
+test("file.list: an id of the listing opens the file (masked by the DLP) and the folder id lists the folder; nothing outside the listing can be asked for", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const b = body(await list(rig));
+        const readme = b.entries.find((e) => e.name === "README.md");
+        const f = await rig.request({ kind: "file", ref: readme.id });
+        assert.equal(f.status, "ok");
+        assert.match(f.text, /# readme/);
+        assert.equal(f.text.includes(GH), false, "DLP second layer on the content");
+        const src = b.entries.find((e) => e.name === "src");
+        const sub = await list(rig, src.id);
+        assert.deepEqual(names(sub), ["credentials", "main.ts"]);
+        const cred = body(sub).entries.find((e) => e.name === "credentials");
+        assert.deepEqual(names(await list(rig, cred.id)), ["index.ts"]);
+        // kinds do not mix
+        assert.equal((await list(rig, readme.id)).status, "not_found", "a file id is not a folder id");
+        assert.equal((await rig.request({ kind: "file", ref: src.id })).status, "not_found", "a folder id is not a file id");
+        assert.equal((await rig.request({ kind: "diff", ref: src.id })).status, "not_found");
+        // other workspace / unknown / path-like
+        assert.equal((await list(rig, src.id, { workspaceId: "ws-2" })).status, "not_found");
+        assert.equal((await list(rig, "root", { workspaceId: "ws-nope" })).status, "not_found");
+        for (const ref of ["src", "../x", "/etc", "A".repeat(43), "cr1_" + "A".repeat(22), "ROOT", "root/", "%2e%2e", ".", "worktree"]) {
+            assert.equal((await list(rig, ref)).status, "not_found", ref);
+        }
+        // the ids of a file the listing did not show cannot be had: there is none for .env
+        assert.equal(rig.registry.live().filter((e) => e.kind === "file").length, 5, "exactly the files shown so far: README.md, a.txt, credentials.service.ts, main.ts, index.ts");
+    });
+});
+
+test("file.list: dlp + blocked entries: a name with a secret is masked (the id still works), a blocked class withholds the entry and mints nothing", async () => {
+    await withRig({}, async (rig) => {
+        write(rig.root(), `${GH}.txt`, "named after a token");
+        write(rig.root(), "plain.txt", "p");
+        const r = await list(rig);
+        assert.equal(r.text.includes(GH), false);
+        const b = body(r);
+        const masked = b.entries.find((e) => e.name.includes("REDACTED"));
+        assert.ok(masked, "the name was masked: " + names(r));
+        assert.equal(contract.validateBody("file.list.body.schema.json", b), true, "a masked name keeps the body valid (the ids are not masked)");
+        assert.equal((await rig.request({ kind: "file", ref: masked.id })).text, "named after a token");
+    });
+    await withRig({ env: { LOCAL_AGENT_DLP_BLOCK_CLASSES: "vcs-token" } }, async (rig) => {
+        write(rig.root(), `${GH}.txt`, "x");
+        write(rig.root(), "plain.txt", "p");
+        const r = await list(rig);
+        assert.deepEqual(names(r), ["plain.txt"]);
+        assert.equal(rig.registry.size, 1, "no id was minted for the withheld entry");
+    });
+});
+
+test("file.list: only with DLP enforce (nothing is read, nothing minted otherwise); a range makes no sense; the flag-off path is the old one", async () => {
+    for (const dlp of ["off", "warn"]) {
+        await withRig({ dlp }, async (rig) => {
+            seed(rig.root());
+            const r = await list(rig);
+            assert.deepEqual([r.status, r.errorCode, r.body.length], ["error", "protocol_unsupported", 0], dlp);
+            assert.equal(rig.registry.size, 0);
+        });
+    }
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const r = await list(rig, "root", { range: { offset: 0, length: 10 } });
+        assert.deepEqual([r.status, r.errorCode], ["error", "protocol_unsupported"]);
+        assert.equal(rig.registry.size, 0);
+    });
+});
+
+test("file.list: paging by count: limit N gives N entries and a nextRef (a folder id that remembers the position); the pages add up to the folder, in order, once each", async () => {
+    await withRig({}, async (rig) => {
+        for (let i = 0; i < 25; i++) write(rig.root(), `f${String(i).padStart(2, "0")}.txt`, "x");
+        for (let i = 0; i < 3; i++) fs.mkdirSync(path.join(rig.root(), `d${i}`));
+        const all = [];
+        let ref = "root";
+        let pages = 0;
+        const refs = new Set();
+        for (; ref && pages < 10; pages++) {
+            const r = await list(rig, ref, { limit: 10 });
+            assert.equal(r.status, "ok");
+            const b = body(r);
+            assert.ok(b.entries.length <= 10);
+            all.push(...b.entries.map((e) => e.name));
+            if (b.nextRef) { assert.match(b.nextRef, ID43); assert.equal(refs.has(b.nextRef), false); refs.add(b.nextRef); }
+            else assert.equal(pages, 2, "the third page is the last");
+            ref = b.nextRef;
+        }
+        assert.equal(pages, 3);
+        assert.deepEqual(all, [...["d0", "d1", "d2"], ...Array.from({ length: 25 }, (_, i) => `f${String(i).padStart(2, "0")}.txt`)]);
+        // the nextRef belongs to the workspace and to the listing kind
+        const first = body(await list(rig, "root", { limit: 10 }));
+        assert.equal((await list(rig, first.nextRef, { workspaceId: "ws-2" })).status, "not_found");
+        assert.equal((await rig.request({ kind: "file", ref: first.nextRef })).status, "not_found");
+        // a continuation inside a sub folder stays in that folder
+        write(rig.root(), "sub/a.txt", "1"); write(rig.root(), "sub/b.txt", "1"); write(rig.root(), "sub/c.txt", "1");
+        const sub = body(await list(rig, "root", { limit: 1000 })).entries.find((e) => e.name === "sub");
+        const p1 = body(await list(rig, sub.id, { limit: 2 }));
+        assert.deepEqual(p1.entries.map((e) => e.name), ["a.txt", "b.txt"]);
+        assert.deepEqual(names(await list(rig, p1.nextRef, { limit: 2 })), ["c.txt"]);
+    });
+});
+
+test("file.list: paging by size: 255-character names do not fit 1000 to a page; every page is within the byte budget and the pages still add up", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_BYTES: "8192" } }, async (rig) => {
+        const N = 40;
+        const long = (i) => `${String(i).padStart(3, "0")}-${"n".repeat(240)}.txt`;
+        for (let i = 0; i < N; i++) write(rig.root(), long(i), "x");
+        const all = [];
+        let ref = "root";
+        let pages = 0;
+        while (ref && pages < 40) {
+            const r = await list(rig, ref, { limit: 1000 });
+            assert.equal(r.status, "ok", r.errorCode);
+            assert.ok(r.body.length <= 8192, `page ${pages}: ${r.body.length} bytes`);
+            assert.ok(body(r).entries.length >= 1);
+            all.push(...names(r));
+            ref = body(r).nextRef;
+            pages++;
+        }
+        assert.ok(pages >= 3, "several pages");
+        assert.deepEqual(all, Array.from({ length: N }, (_, i) => long(i)));
+        assert.equal(rig.registry.size, N + (pages - 1), "ids exist only for what was shown (+ one continuation per page but the last): an entry that did not fit left no id behind");
+    });
+});
+
+test("file.list: a folder with more than LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES entries is payload_too_large (never 'the first N the disk returned'); the limit itself is fine", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: "100" } }, async (rig) => {
+        for (let i = 0; i < 100; i++) write(rig.root(), `big/f${i}.txt`, "x");
+        const big = body(await list(rig)).entries.find((e) => e.name === "big");
+        assert.equal(body(await list(rig, big.id, { limit: 1000 })).entries.length, 100);
+        write(rig.root(), "big/one-more.txt", "x");
+        const r = await list(rig, big.id);
+        assert.deepEqual([r.status, r.errorCode, r.body.length], ["error", "payload_too_large", 0]);
+    });
+});
+
+test("file.list: links, hard links, devices and odd names: a link that leaves the root, a link to a secret, a hard link, a fifo and a name with a newline are simply not there", async () => {
+    await withRig({}, async (rig) => {
+        const root = rig.root();
+        const out = tmpDir("f307c-out-");
+        rig.dirs.push(out);
+        write(out, "outside.txt", "outside secret");
+        write(out, "dir/inner.txt", "x");
+        write(root, "ok.txt", "ok");
+        write(root, "real/inner.txt", "i");
+        write(root, ".env", "A=1");
+        write(root, "secrets/x.txt", "s");
+        fs.symlinkSync(path.join(out, "outside.txt"), path.join(root, "link-out.txt"));
+        fs.symlinkSync(path.join(out, "dir"), path.join(root, "link-outdir"));
+        fs.symlinkSync(path.join(root, ".env"), path.join(root, "innocent.txt"));
+        fs.symlinkSync(path.join(root, "secrets"), path.join(root, "innocent-dir"));
+        fs.symlinkSync(path.join(root, "ok.txt"), path.join(root, "link-in.txt"));
+        fs.symlinkSync(path.join(root, "real"), path.join(root, "link-indir"));
+        fs.symlinkSync(path.join(root, "missing"), path.join(root, "dangling"));
+        fs.symlinkSync("../outside.txt", path.join(root, "rel-out.txt"));
+        fs.symlinkSync(root, path.join(root, "loop"));                                  // a link to the root itself
+        try { fs.linkSync(path.join(root, "ok.txt"), path.join(root, "hard.txt")); } catch { /* no hard links here */ }
+        try { execFileSync("mkfifo", [path.join(root, "pipe")]); } catch { /* no mkfifo */ }
+        try { write(root, "bad\nname.txt", "x"); } catch { /* a file system that refuses it */ }
+        try { write(root, "repl\ufffdchar.txt", "x"); } catch { /* idem: a name with U+FFFD is what invalid UTF-8 looks like after decoding, so it is never listed */ }
+        const r = await list(rig);
+        assert.equal(r.status, "ok");
+        const n = names(r);
+        // ok.txt itself is hard-linked now (hard.txt is its second name): both are left out by the default hard link rule
+        const hard = fs.statSync(path.join(root, "ok.txt")).nlink > 1;
+        assert.deepEqual(n.filter((x) => !["ok.txt", "link-in.txt"].includes(x)), ["link-indir", "real"], n.join(","));
+        assert.equal(n.includes("ok.txt"), !hard);
+        assert.equal(n.includes("link-in.txt"), !hard, "a link to a hard-linked file is a name of it: same rule");
+        for (const never of ["link-out", "link-outdir", "innocent", "dangling", "rel-out", "pipe", "bad", "repl", "loop", ".env", "secrets", "hard.txt"]) assert.equal(r.text.includes(never), false, never);
+        // a link to a folder inside the root lists as a folder, and the ids it hands out are for the real folder
+        const li = body(r).entries.find((e) => e.name === "link-indir");
+        assert.equal(li.type, "dir");
+        assert.deepEqual(names(await list(rig, li.id)), ["inner.txt"]);
+        // a folder swapped for a link out of the root / to a secret after its id was minted is forbidden at list time
+        const real = body(r).entries.find((e) => e.name === "real");
+        fs.rmSync(path.join(root, "real"), { recursive: true });
+        fs.symlinkSync(path.join(out, "dir"), path.join(root, "real"));
+        assert.equal((await list(rig, real.id)).status, "forbidden");
+        fs.rmSync(path.join(root, "real"));
+        fs.symlinkSync(path.join(root, "secrets"), path.join(root, "real"));
+        assert.equal((await list(rig, real.id)).status, "forbidden");
+        assert.equal(r.text.includes(out), false);
+    });
+});
+
+test("file.list: the hard link rule can be lifted by LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS (as for file)", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS: "true" } }, async (rig) => {
+        write(rig.root(), "a.txt", "x");
+        try { fs.linkSync(path.join(rig.root(), "a.txt"), path.join(rig.root(), "b.txt")); } catch { return; }
+        assert.deepEqual(names(await list(rig)), ["a.txt", "b.txt"]);
+    });
+});
+
+test("file.list: unicode, spaces and a root reached through a link; an empty folder is an empty page; a folder that is not there is not_found", async () => {
+    await withRig({}, async (rig) => {
+        write(rig.root(), "ação final.txt", "x"); write(rig.root(), "日本語.md", "x"); write(rig.root(), "with space/a b.txt", "x"); fs.mkdirSync(path.join(rig.root(), "empty"));
+        const b = body(await list(rig));
+        assert.deepEqual(b.entries.map((e) => e.name), ["empty", "with space", "ação final.txt", "日本語.md"]);
+        const empty = b.entries.find((e) => e.name === "empty");
+        const e = await list(rig, empty.id);
+        assert.deepEqual([e.status, body(e)], ["ok", { entries: [] }]);
+        fs.rmdirSync(path.join(rig.root(), "empty"));
+        assert.equal((await list(rig, empty.id)).status, "not_found");
+    });
+    const base = tmpDir(); const real = path.join(base, "real"); const link = path.join(base, "link");
+    fs.mkdirSync(real); write(real, "x.txt", "x"); fs.symlinkSync(real, link);
+    await withRig({ workspaces: { "ws-1": { root: link } } }, async (rig) => {
+        assert.deepEqual(names(await list(rig)), ["x.txt"]);
+    });
+    fs.rmSync(base, { recursive: true, force: true });
+});
+
+test("file.list: nothing but codes in errors, audit and logs: no name, no path and no id of a listing is ever in them", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        write(rig.root(), "very-private-customer-name.txt", "x");
+        const r = await list(rig);
+        const ids = body(r).entries.map((e) => e.id);
+        await list(rig, "A".repeat(43)); await list(rig, ids[0]); await list(rig, "root", { workspaceId: "ws-nope" });
+        const noise = JSON.stringify([rig.handler.audit.tail(1000), rig.logs]);
+        for (const leak of ["very-private-customer-name", "README", "credentials", "main.ts", rig.root(), path.basename(rig.root()), ...ids, GH]) assert.equal(noise.includes(leak), false, `leaked ${leak}`);
+        const rec = rig.handler.audit.tail(1000).find((x) => x.kind === "file.list" && x.status === "ok");
+        assert.ok(rec && rec.bytes > 0 && rec.chunks >= 1);
+    });
+});
+
+test("file.list: a folder of 3000 entries gives a page of `limit`, and the slot and the memory reserved for the request come back", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: "20000" } }, async (rig) => {
+        for (let i = 0; i < 3000; i++) fs.writeFileSync(path.join(rig.root(), `f${i}.txt`), "x");
+        const r = await list(rig, "root", { limit: 1000 });
+        assert.equal(r.status, "ok");
+        assert.equal(body(r).entries.length, 1000);
+        assert.equal(rig.handler.inflight, 0);
+        assert.equal(rig.handler.reservedBytes, 0);
+    });
+});
+
+test("file.list: a cursor belongs to a folder id only (a file id with a cursor, or a bad cursor, is refused by the registry); listFolder stops when the request is aborted", async () => {
+    const reg = new ContentRefRegistry({ tenantId: TENANT });
+    const q = { workspaceId: "w", root: "/r" };
+    assert.equal(reg.mint({ ...q, kind: "file", rel: "a.txt", after: { dir: false, name: "a" } }), null);
+    assert.equal(reg.mint({ ...q, kind: "diff", rel: null, after: { dir: false, name: "a" } }), null);
+    for (const bad of ["x", 1, {}, { name: "" }, { name: "x".repeat(2000) }]) assert.equal(reg.mint({ ...q, kind: "file.list", rel: null, after: bad }), null, JSON.stringify(bad).slice(0, 20));
+    assert.ok(reg.mint({ ...q, kind: "file.list", rel: null, after: { dir: true, name: "d" } }));
+    const root = tmpDir();
+    write(root, ".env", "A=1");                      // nothing listable: only the loop that reads the folder can notice the abort
+    const o = { root, limit: 10, maxBytes: 1 << 20, maxDirEntries: 1000, mint: () => null, maskName: (n) => ({ name: n, blocked: false, denied: false, total: 0, redactions: {} }) };
+    assert.deepEqual(await listFolder({ ...o }), { ok: true, body: Buffer.from('{"entries":[]}'), entries: 0, dlp: { total: 0, redactions: {} } });
+    assert.deepEqual(await listFolder({ ...o, signal: AbortSignal.abort() }), { ok: false, status: "error", errorCode: "agent_offline" });
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("config (F3-07c): LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES is clamped to 100..200000, a bad value is the default (20000), never unlimited", () => {
+    const c = (v) => resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: v }, () => {}).maxDirEntries;
+    assert.deepEqual([c(undefined), c("abc"), c("99"), c("200001"), c("999999999999"), c("-5"), c("100"), c("200000"), c("5000")], [20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 100, 200_000, 5_000]);
+});
+
+// ------------------------------------------------------------------------------------------ the real wiring: content.index
+
+async function linkFor(cp, { env, root }) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => logs.push(m) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: TENANT }] };
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce"), wsManager,
+        getWorkspaceRoot: () => root, log, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce", ...env } });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    return { link, logs };
+}
+
+test("wiring: a listing mints through mintRef, so every id it hands out is announced with content.index ({kind, ref, size}: no names), and the register announces content.file.list", async () => {
+    const root = tmpDir(); seed(root); write(root, "very-private-customer-name.txt", "12345");
+    const cp = new ReferenceCp();
+    const { link, logs } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_INDEX_BATCH_MS: "0" } });
+    assert.ok(cp.registers[0].capabilities.includes("content.file.list"));
+    const requestId = (await import("./helpers/reference-cp.js")).uuid();
+    cp.sendData("content.request", { kind: "file.list", ref: "root", actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+    await waitFor(() => cp.contentRequests.get(requestId)?.done);
+    const b = JSON.parse(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString("utf8"));
+    assert.equal(b.entries.length, 5);
+    await waitFor(() => cp.received.filter((f) => f.type === "content.index").flatMap((f) => f.payload.entries).length === 5);
+    const idx = cp.received.filter((f) => f.type === "content.index").flatMap((f) => f.payload.entries);
+    const byRef = new Map(idx.map((e) => [e.ref, e]));
+    for (const e of b.entries) {
+        const i = byRef.get(e.id);
+        assert.ok(i, "announced: " + e.name.length);
+        assert.deepEqual(Object.keys(i).sort(), ["kind", "ref", "size"]);
+        assert.equal(i.kind, e.type === "dir" ? "file.list" : "file");
+        assert.equal(i.size, e.size);
+    }
+    const wire = JSON.stringify(cp.received.filter((f) => f.type === "content.index"));
+    for (const leak of ["very-private-customer-name", "README", "main.ts", root, path.basename(root)]) assert.equal(wire.includes(leak), false, `leaked ${leak}`);
+    assert.equal(logs.join("\n").includes("very-private"), false);
+    assert.deepEqual(cp.errorsSent, []);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("wiring: the nextRef of the real link works (the continuation is minted through mintRef with its cursor): page 2 continues where page 1 stopped", async () => {
+    const root = tmpDir();
+    for (const n of ["a", "b", "c", "d", "e"]) write(root, `${n}.txt`, n);
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root, env: {} });
+    const { uuid } = await import("./helpers/reference-cp.js");
+    const ask = async (ref, limit) => {
+        const requestId = uuid();
+        cp.sendData("content.request", { kind: "file.list", ref, limit, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+        await waitFor(() => cp.contentRequests.get(requestId)?.done);
+        return JSON.parse(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString("utf8"));
+    };
+    const p1 = await ask("root", 2);
+    assert.deepEqual(p1.entries.map((e) => e.name), ["a.txt", "b.txt"]);
+    assert.match(p1.nextRef, ID43);
+    const p2 = await ask(p1.nextRef, 2);
+    assert.deepEqual(p2.entries.map((e) => e.name), ["c.txt", "d.txt"]);
+    const p3 = await ask(p2.nextRef, 2);
+    assert.deepEqual([p3.entries.map((e) => e.name), p3.nextRef], [["e.txt"], undefined]);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});