deepdebug-local-agent 1.4.0 → 1.6.0

package/test/la-protocol-v2/content-alignment.test.js

@@ -0,0 +1,608 @@
+// F3-07b: aligning the Local Agent content handlers with the gateway (F3-06b / F3-07b): 43-char ids + `worktree`, content.index
+// (inventory of ids, no names), produce() that throws, hard links, the wider deny list, git clean/smudge filters.
+// Real V2Session, real handlers, real files/repos on disk; the control plane is the in-memory ReferenceCp.
+// Against the REAL gateway (HTTP -> controller -> LaV2Session -> this agent): tools/interop/LaV2NodeContentRelayE2ETest.java.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import { ReferenceCp, TENANT, AGENT, uuid, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { setup, write, git, initRepo, tmpDir, ACTOR } from "./helpers/content-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { createContentIndexer } from "../../src/la-protocol-v2/content-handlers/content-index.js";
+import { ContentRefRegistry } from "../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { resolveContentHandlersConfig } from "../../src/la-protocol-v2/content-handlers/config.js";
+import { isSensitivePath, resolveInside, readRegular, normalizeRel } from "../../src/la-protocol-v2/content-handlers/path-guard.js";
+import { worktreeDiff, filterOverrides } from "../../src/la-protocol-v2/content-handlers/git-diff.js";
+import { ProtocolError } from "../../src/la-protocol-v2/errors.js";
+
+const ID43 = /^[A-Za-z0-9_-]{43}$/;
+const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+
+async function withRig(opts, body) {
+    const rig = await setup(opts);
+    try { await body(rig); } finally { await rig.stop(); }
+}
+
+/** The real runtime wiring (buildV2Link) over an in-memory CP, as content-wiring.test.js does. */
+async function linkFor(cp, { env, root, errors = [] }) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => errors.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, transport };
+}
+
+const indexFrames = (cp) => cp.received.filter((f) => f.type === "content.index");
+
+// ------------------------------------------------------------------------------------------ 2. ids of 43 chars, `worktree`
+
+test("ids: the agent mints 43-char base64url ids and serves them; worktree is the symbolic ref of kind diff only; the F3-07 form is not_found", async () => {
+    await withRig({}, async (rig) => {
+        write(rig.root(), "src/app.js", "const a = 1;\n");
+        initRepo(rig.root());
+        write(rig.root(), "src/app.js", `const a = 2; // ${GH}\n`);
+        const id = rig.mint("file", "src/app.js");
+        assert.match(id, ID43);
+        const f = await rig.request({ ref: id });
+        assert.deepEqual([f.status, f.text.includes("const a = 2"), f.text.includes(GH)], ["ok", true, false]);
+        const d = await rig.request({ kind: "diff", ref: "worktree" });
+        assert.equal(d.status, "ok");
+        assert.match(d.text, /src\/app\.js/);
+        assert.equal(d.text.includes(GH), false, "masked");
+        assert.equal((await rig.request({ kind: "file", ref: "worktree" })).status, "not_found", "worktree is not a file");
+        assert.equal((await rig.request({ ref: "cr1_" + "A".repeat(22) })).status, "not_found");
+        assert.equal((await rig.request({ ref: "A".repeat(43) })).status, "not_found", "well-formed but never minted");
+        assert.equal((await rig.request({ kind: "diff", ref: "worktree", workspaceId: "ws-nope" })).status, "not_found", "worktree of an unregistered workspace");
+        assert.equal((await rig.request({ kind: "diff", ref: id })).status, "not_found", "an id minted for a file is not a diff id");
+    });
+});
+
+test("ids: the F3-07 form (cr1_ + 22), 42/44 chars, padding, '.', '/', '+' are not ids for the registry or the pattern", async () => {
+    const { REF_PATTERN } = await import("../../src/la-protocol-v2/content-handlers/ref-registry.js");
+    const ok = "Zm9vYmFyYmF6cXV4MTIzNDU2Nzg5MGFiY2RlZmdoaWo";
+    assert.equal(ok.length, 43);
+    assert.equal(REF_PATTERN.test(ok), true);
+    for (const bad of ["cr1_" + "A".repeat(22), ok.slice(1), ok + "A", ok.slice(0, 42) + "=", ok.slice(0, 42) + ".", ok.slice(0, 42) + "/", ok.slice(0, 42) + "+", "worktree", ""]) {
+      assert.equal(REF_PATTERN.test(bad), false, bad);
+    }
+});
+
+// ------------------------------------------------------------------------------------------ 3. content.index
+
+test("content.index: a minted id is announced as {kind, ref, size} and nothing else; no name, no path, no directory anywhere in the frame", async () => {
+    const root = tmpDir(); write(root, "src/secret-name-xyz/app.txt", "hello world"); write(root, ".env", "X=1");
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root });
+    const m = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "src/secret-name-xyz/app.txt" });
+    assert.equal(link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: ".env" }), null, "sensitive: no id, no entry");
+    assert.equal(link.content.mintRef({ workspaceId: "ws-unknown", kind: "file", rel: "src/secret-name-xyz/app.txt" }), null);
+    await waitFor(() => indexFrames(cp).length === 1);
+    const [fr] = indexFrames(cp);
+    assert.deepEqual(fr.payload, { entries: [{ kind: "file", ref: m.id, size: 11 }] });
+    assert.equal(fr.workspaceId, "ws-1");
+    assert.equal(fr.chunk, undefined);
+    assert.equal(fr.sig, undefined, "unsigned, like log.stats");
+    const wire = JSON.stringify(cp.rawIn);
+    for (const leak of ["secret-name-xyz", "app.txt", root, path.basename(root), ".env"]) assert.equal(wire.includes(leak), false, `leaked ${leak}`);
+    assert.deepEqual(cp.errorsSent, []);
+    assert.equal(link.content.indexer.announcedCount, 1);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("content.index: size is informative and honest (a file outside the root by link, a missing file, a directory: 0); diff ids announce size 0", async () => {
+    const base = tmpDir(); const root = path.join(base, "ws"); fs.mkdirSync(root);
+    write(base, "outside.txt", "x".repeat(5000));
+    write(root, "in.txt", "x".repeat(123));
+    fs.symlinkSync(path.join(base, "outside.txt"), path.join(root, "link.txt"));
+    fs.mkdirSync(path.join(root, "adir"));
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root });
+    const sizes = {};
+    for (const rel of ["in.txt", "link.txt", "missing.txt", "adir"]) sizes[rel] = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel });
+    const diff = link.content.mintRef({ workspaceId: "ws-1", kind: "diff", rel: "in.txt" });
+    await link.content.indexer.flush();
+    const bySize = new Map(indexFrames(cp).flatMap((f) => f.payload.entries).map((e) => [e.ref, e]));
+    assert.equal(bySize.get(sizes["in.txt"].id).size, 123);
+    assert.equal(bySize.get(sizes["link.txt"].id).size, 0, "a link that leaves the root reveals nothing about its target");
+    assert.equal(bySize.get(sizes["missing.txt"].id).size, 0);
+    assert.equal(bySize.get(sizes["adir"].id).size, 0);
+    assert.deepEqual([bySize.get(diff.id).kind, bySize.get(diff.id).size], ["diff", 0]);
+    link.close();
+    fs.rmSync(base, { recursive: true, force: true });
+});
+
+test("content.index: ids are batched (one frame per workspace up to 256 entries, the contract limit), every id exactly once", async () => {
+    const root = tmpDir(); write(root, "a.txt", "a");
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_INDEX_BATCH_MS: "200" } });
+    const ids = [];
+    for (let i = 0; i < 300; i++) ids.push(link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" }).id);
+    await waitFor(() => indexFrames(cp).length === 2, 4000);
+    const frames = indexFrames(cp);
+    assert.deepEqual(frames.map((f) => f.payload.entries.length), [256, 44]);
+    const announced = frames.flatMap((f) => f.payload.entries.map((e) => e.ref));
+    assert.equal(new Set(announced).size, 300);
+    assert.deepEqual([...announced].sort(), [...ids].sort());
+    assert.deepEqual(cp.errorsSent, []);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("content.index: after a connection that is NOT a resume every live id is announced again; after a resume nothing is repeated", async () => {
+    const root = tmpDir(); write(root, "a.txt", "abc"); write(root, "b.txt", "defg");
+    const cp = new ReferenceCp();
+    const { link, transport } = await linkFor(cp, { root });
+    const a = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" }).id;
+    const b = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "b.txt" }).id;
+    await waitFor(() => indexFrames(cp).flatMap((f) => f.payload.entries).length === 2);
+    // resume: same CP, same session id -> nothing again
+    link.session.detach(transport);
+    const t2 = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, t2)), () => {});
+    link.session.attach(t2);
+    await waitFor(() => link.session.state === "ready");
+    await link.content.indexer.flush();
+    assert.equal(cp.hellos.length >= 2, true);
+    assert.equal(indexFrames(cp).flatMap((f) => f.payload.entries).length, 2, "a resumed session keeps its index at the gateway");
+    // a brand new gateway session (a CP that does not know the old one): ready with resumed=false -> announce again
+    link.session.detach(t2);
+    const cp2 = new ReferenceCp({ privateKey: cp.privateKey, publicKeyRaw: cp.publicKeyRaw, keyId: cp.keyId }); // another gateway session, the same signing key
+    const t3 = { send: (t) => cp2.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp2.attach((t) => queueMicrotask(() => link.session.handleText(t, t3)), () => {});
+    link.session.attach(t3);
+    await waitFor(() => link.session.state === "ready" && indexFrames(cp2).length > 0, 4000);
+    const again = indexFrames(cp2).flatMap((f) => f.payload.entries);
+    assert.deepEqual(again.map((e) => e.ref).sort(), [a, b].sort());
+    assert.deepEqual(again.map((e) => e.size).sort(), [3, 4]);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("content.index: the gateway's ack `rejected protocol_unsupported` stops the announcements, the session stays up and content is still served", async () => {
+    const root = tmpDir(); write(root, "a.txt", "hello");
+    const cp = new ReferenceCp();
+    cp.rejectData = ["protocol_unsupported"];
+    const { link, logs } = await linkFor(cp, { root });
+    const id = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" }).id;
+    await waitFor(() => cp.rejectedFrames.length === 1);
+    await link.content.indexer.flush();
+    assert.deepEqual(cp.rejectedFrames, [["content.index", "protocol_unsupported"]]);
+    assert.equal(link.session.state, "ready", "non-fatal");
+    const more = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" });
+    assert.ok(more);
+    await link.content.indexer.flush();
+    assert.equal(cp.rejectedFrames.length, 1, "nothing more is sent");
+    assert.equal(indexFrames(cp).length, 0);
+    assert.ok(logs.some((l) => l.includes("keeps no content index")));
+    const requestId = uuid();
+    cp.sendData("content.request", { kind: "file", ref: id, actor: ACTOR }, { workspaceId: "ws-1", requestId });
+    await waitFor(() => cp.contentRequests.get(requestId)?.done);
+    assert.equal(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString(), "hello");
+    assert.equal(logs.concat([]).some((l) => l.includes(root) || l.includes(id)), false);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+// content.index with a fake session and fake timers: the ack policy, bounds, no leaks
+function fakeSession() {
+    const s = new EventEmitter();
+    s.state = "ready";
+    s.sent = [];
+    s.script = [];                     // codes to fail the next sends with (null = accept)
+    s.send = async (type, payload, opts) => {
+        const code = s.script.length ? s.script.shift() : null;
+        s.sent.push({ type, payload, workspaceId: opts.workspaceId, code });
+        if (code) throw new ProtocolError(code, "rejected by the control plane");
+    };
+    return s;
+}
+function fakeTimers() {
+    const pending = [];
+    return { pending, setTimeout: (fn, ms) => { const t = { fn, ms, off: false }; pending.push(t); return t; }, clearTimeout: (t) => { if (t) t.off = true; },
+        async fire() { const due = pending.splice(0).filter((t) => !t.off); for (const t of due) await t.fn(); } };
+}
+function indexerRig({ maxIds = 2048, ttl = 900_000 } = {}) {
+    const session = fakeSession();
+    const timers = fakeTimers();
+    let t = 1_000_000;
+    const registry = new ContentRefRegistry({ tenantId: TENANT, ttlMs: ttl, now: () => t });
+    const logs = [];
+    const config = { indexMaxIds: maxIds, indexBatchMs: 100, refTtlMs: ttl };
+    const indexer = createContentIndexer({ session, registry, config, log: { warn: (m) => logs.push(m), log: (m) => logs.push(m) }, now: () => t, timers });
+    const mint = (rel = "f.txt", ws = "ws-1", size = 1) => {
+        const m = registry.mint({ workspaceId: ws, root: "/r", kind: "file", rel, size });
+        indexer.add({ workspaceId: ws, kind: "file", ref: m.id, size, expiresAt: m.expiresAt });
+        return m.id;
+    };
+    return { session, timers, registry, indexer, logs, mint, advance: (ms) => { t += ms; } };
+}
+
+test("indexer: rate_limited -> nothing stored, the ids come back after 30 s, then 60 s, doubling to 5 min; success resets it", async () => {
+    const r = indexerRig();
+    r.session.script = ["rate_limited", "rate_limited"];
+    const id = r.mint();
+    await r.indexer.flush();
+    assert.deepEqual(r.session.sent.map((s) => s.code), ["rate_limited"]);
+    assert.equal(r.indexer.announcedCount, 0);
+    assert.equal(r.timers.pending.at(-1).ms, 30_000);
+    await r.timers.fire();                       // announce() -> schedules the batch (0 ms)
+    await r.timers.fire();                       // the batch: rejected again
+    await r.indexer.flush();
+    assert.equal(r.timers.pending.at(-1).ms, 60_000);
+    await r.timers.fire(); await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.session.sent.at(-1).code, null, "accepted at last");
+    assert.deepEqual(r.session.sent.at(-1).payload.entries.map((e) => e.ref), [id]);
+    assert.equal(r.indexer.announcedCount, 1);
+    assert.ok(r.logs.every((l) => !l.includes(id)), "no id in a log line");
+    r.indexer.close();
+});
+
+test("indexer: protocol_unsupported stops for the connection (no timers, adds are dropped); the next non-resumed ready starts again", async () => {
+    const r = indexerRig();
+    r.session.script = ["protocol_unsupported"];
+    r.mint();
+    await r.indexer.flush();
+    assert.equal(r.timers.pending.filter((t) => !t.off).length, 0, "no retry timer");
+    const before = r.session.sent.length;
+    r.mint("g.txt");
+    await r.indexer.flush();
+    assert.equal(r.session.sent.length, before);
+    assert.equal(r.indexer.stats.dropped >= 1, true);
+    r.session.emit("ready", { resumed: false });
+    await r.indexer.flush(); await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.session.sent.at(-1).code, null);
+    assert.equal(r.session.sent.at(-1).payload.entries.length, 2, "both live ids come back: the one that was refused and the one dropped while stopped (it is in the registry)");
+    r.indexer.close();
+});
+
+test("indexer: internal and timeout are retried after 5 s; other failures wait for the next ready; nothing is thrown into the caller", async () => {
+    const r = indexerRig();
+    r.session.script = ["internal", "timeout", "agent_offline"];
+    r.mint();
+    await r.indexer.flush();
+    assert.equal(r.timers.pending.at(-1).ms, 5_000);
+    await r.timers.fire(); await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.timers.pending.at(-1).ms, 5_000);
+    await r.timers.fire(); await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.session.sent.at(-1).code, "agent_offline");
+    assert.equal(r.timers.pending.filter((t) => !t.off).length, 0, "agent_offline: no timer, the next ready announces again");
+    r.session.emit("ready", { resumed: false });
+    await r.indexer.flush(); await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.session.sent.at(-1).code, null);
+    r.indexer.close();
+});
+
+test("indexer: not ready -> nothing is sent; ready -> every live id goes out; expired ids are not announced", async () => {
+    const r = indexerRig({ ttl: 60_000 });
+    r.session.state = "await_ready";
+    const a = r.mint("a.txt"); const b = r.mint("b.txt");
+    await r.timers.fire(); await r.indexer.flush();
+    assert.equal(r.session.sent.length, 0);
+    r.advance(61_000);
+    const c = r.mint("c.txt");                   // a and b expired in the meantime
+    r.session.state = "ready";
+    r.session.emit("ready", { resumed: false });
+    await r.indexer.flush(); await r.timers.fire(); await r.indexer.flush();
+    const refs = r.session.sent.flatMap((s) => s.payload.entries.map((e) => e.ref));
+    assert.deepEqual(refs, [c]);
+    assert.equal(refs.includes(a) || refs.includes(b), false);
+    r.indexer.close();
+});
+
+test("indexer: at most LOCAL_AGENT_CONTENT_INDEX_MAX_IDS live ids are announced (the gateway keeps 2048 per session); the rest is only counted", async () => {
+    const r = indexerRig({ maxIds: 3 });
+    for (let i = 0; i < 5; i++) r.mint(`f${i}.txt`);
+    await r.indexer.flush();
+    assert.equal(r.session.sent.flatMap((s) => s.payload.entries).length, 3);
+    assert.equal(r.indexer.stats.dropped, 2);
+    r.indexer.close();
+    assert.equal(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_INDEX_MAX_IDS: "999999" }, () => {}).indexMaxIds, 2048, "never above the gateway's limit");
+});
+
+test("indexer: workspaces never share a frame; entries carry only kind, ref, size; close() leaves no timer", async () => {
+    const r = indexerRig();
+    r.mint("a", "ws-1"); r.mint("b", "ws-2"); r.mint("c", "ws-1");
+    await r.indexer.flush();
+    assert.deepEqual(r.session.sent.map((s) => [s.workspaceId, s.payload.entries.length]), [["ws-1", 2], ["ws-2", 1]]);
+    for (const s of r.session.sent) for (const e of s.payload.entries) assert.deepEqual(Object.keys(e).sort(), ["kind", "ref", "size"]);
+    r.mint("d", "ws-1");
+    r.indexer.close();
+    assert.equal(r.timers.pending.filter((t) => !t.off).length, 0);
+});
+
+// ------------------------------------------------------------------------------------------ 5. produce() that throws
+
+test("a throwing workspace lookup, registry or audit never leaves the gateway without an answer: internal, audited, no path or message anywhere", async () => {
+    const unhandled = [];
+    const onUnhandled = (e) => unhandled.push(e);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+        await withRig({}, async (rig) => {
+            const root = rig.root();
+            write(root, "a.txt", "hello");
+            const id = rig.mint("file", "a.txt");
+            const LEAK = "/Users/victim/very-secret-dir/passwords.txt";
+            const realGet = rig.wsMap.get.bind(rig.wsMap);
+            // 1. resolveWorkspace / the workspace list throws
+            rig.wsMap.get = () => { throw new TypeError(`cannot read ${LEAK}`); };
+            let r = await rig.request({ ref: id, waitMs: 2500 });
+            assert.deepEqual([r.status, r.errorCode, r.frames.length, r.body.length], ["error", "internal", 1, 0]);
+            let rec = rig.handler.audit.tail(1)[0];
+            assert.deepEqual([rec.kind, rec.status, rec.errorCode, rec.bytes], ["file", "error", "internal", 0]);
+            rig.wsMap.get = realGet;
+            // 2. the registry throws
+            const realResolve = rig.registry.resolve.bind(rig.registry);
+            rig.registry.resolve = () => { throw new Error(`boom ${LEAK}`); };
+            r = await rig.request({ ref: id, waitMs: 2500 });
+            assert.deepEqual([r.status, r.errorCode], ["error", "internal"]);
+            rig.registry.resolve = realResolve;
+            // 3. a diff whose producer throws deep inside (the repository is replaced by something that throws on realpath is not portable: use the registry again)
+            rig.registry.resolve = () => { throw new RangeError(LEAK); };
+            r = await rig.request({ kind: "diff", ref: "worktree", waitMs: 2500 });
+            assert.deepEqual([r.status, r.errorCode], ["error", "internal"]);
+            rig.registry.resolve = realResolve;
+            // 4. the audit throws: the content is still delivered
+            const realRecord = rig.handler.audit.record;
+            rig.handler.audit.record = () => { throw new Error(`audit ${LEAK}`); };
+            r = await rig.request({ ref: id, waitMs: 2500 });
+            assert.deepEqual([r.status, r.text], ["ok", "hello"]);
+            await waitFor(() => rig.handler.inflight === 0);
+            assert.equal(rig.logs.some((l) => l.includes("failed internally")), false, "an audit failure is absorbed where it happens, not escalated to the last-resort handler");
+            rig.handler.audit.record = realRecord;
+            // and the next request is normal: nothing is stuck (slot, memory)
+            assert.equal((await rig.request({ ref: id })).status, "ok");
+            await waitFor(() => rig.handler.inflight === 0 && rig.handler.reservedBytes === 0);
+            const everything = rig.everything();
+            assert.equal(everything.includes("victim"), false, "the message of an exception never reaches the wire, the audit or a log");
+            assert.equal(everything.includes("passwords.txt"), false);
+            assert.equal(everything.includes(root), false);
+            assert.deepEqual(rig.cp.errorsSent, []);
+        });
+    } finally { process.off("unhandledRejection", onUnhandled); }
+    assert.deepEqual(unhandled, [], "no TypeError swallowed into an unhandled rejection");
+});
+
+test("mintRef with a workspace manager that throws returns null (no exception with a path in it, no id)", async () => {
+    const root = tmpDir(); write(root, "a.txt", "x");
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root });
+    const { installContentHandlers } = await import("../../src/la-protocol-v2/content-handlers/install.js");
+    const bad = { session: link.session, close() {} };
+    const c = installContentHandlers({ link: bad, tenantId: TENANT, wsManager: { list: () => { throw new Error("/leaky/path"); } }, getWorkspaceRoot: () => root,
+        config: resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true" }, () => {}), env: { LOCAL_AGENT_DLP_MODE: "enforce" } });
+    assert.equal(c.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" }), null);
+    bad.close();
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+// ------------------------------------------------------------------------------------------ 6. hard links, deny list
+
+function hardLinkFixture() {
+    const base = tmpDir(); const root = path.join(base, "ws"); fs.mkdirSync(root);
+    write(base, "outside-secret.txt", "OUTSIDE-SECRET-CONTENT");
+    write(root, "plain.txt", "plain");
+    let linked = true;
+    try { fs.linkSync(path.join(base, "outside-secret.txt"), path.join(root, "hard.txt")); } catch { linked = false; }
+    return { base, root, linked };
+}
+
+test("hard link: a second name of a file outside the root is forbidden by default (nlink > 1); LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS lifts it; ordinary files are untouched", async (t) => {
+    const f = hardLinkFixture();
+    if (!f.linked) { t.skip("hard links not supported here"); return; }
+    try {
+        assert.equal((await resolveInside(f.root, "hard.txt")).status, "forbidden");
+        assert.equal((await resolveInside(f.root, "plain.txt")).ok, true);
+        const allowed = await resolveInside(f.root, "hard.txt", [], { allowHardlinks: true });
+        assert.equal(allowed.ok, true);
+        // through the handler, with an id minted before the link existed
+        await withRig({ workspaces: { "ws-1": { root: f.root } } }, async (rig) => {
+            const id = rig.mint("file", "hard.txt");
+            const r = await rig.request({ ref: id });
+            assert.deepEqual([r.status, r.body.length], ["forbidden", 0]);
+            assert.equal(rig.everything().includes("OUTSIDE-SECRET"), false);
+            assert.equal((await rig.request({ ref: rig.mint("file", "plain.txt") })).text, "plain");
+        });
+        await withRig({ workspaces: { "ws-1": { root: f.root } }, env: { LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS: "true" } }, async (rig) => {
+            assert.equal((await rig.request({ ref: rig.mint("file", "hard.txt") })).text, "OUTSIDE-SECRET-CONTENT");
+        });
+        assert.equal(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true" }, () => {}).allowHardlinks, false, "default off");
+        assert.equal(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS: "maybe" }, () => {}).allowHardlinks, false, "unknown stays off");
+    } finally { fs.rmSync(f.base, { recursive: true, force: true }); }
+});
+
+test("hard link created AFTER the path check is still caught on the open descriptor (fstat), not only on the path", async (t) => {
+    const base = tmpDir(); const root = path.join(base, "ws"); fs.mkdirSync(root);
+    write(root, "late.txt", "late");
+    try {
+        const resolved = await resolveInside(root, "late.txt");
+        assert.equal(resolved.ok, true);
+        try { fs.linkSync(path.join(root, "late.txt"), path.join(base, "alias.txt")); } catch { t.skip("hard links not supported here"); return; }
+        assert.deepEqual(await readRegular(resolved, 1024, undefined), { ok: false, status: "forbidden" });
+        const ok = await readRegular(resolved, 1024, undefined, { allowHardlinks: true });
+        assert.equal(ok.ok, true);
+    } finally { fs.rmSync(base, { recursive: true, force: true }); }
+});
+
+const SENSITIVE = [
+    ".env~", "app/.env~", ".ENV~", ".env.local~", ".env.production.bak", ".env#", ".#.env",
+    ".env::$DATA", "app/.env::$DATA", ".env:Zone.Identifier", ".env.::$DATA", "id_rsa::$DATA", "keys/server.pem::$DATA",
+    "kubeconfig", "deploy/kubeconfig", "kubeconfig.yaml", "prod.kubeconfig", ".kube/config", "KUBECONFIG",
+    "id_rsa", "id_rsa.pub", "id_ed25519", "id_ecdsa", "x/id_dsa", "vault.kdbx", "db/secrets.KDBX",
+    ".npmrc", "pkg/.npmrc", ".pypirc", "credentials", "credentials.json", "credentials.yml", "credentials.xml", "aws/credentials",
+    // Windows 8.3 aliases of sensitive names
+    "ENV~1", "env~1", "ENV~10", "NPMRC~1", "PYPIRC~1", "NETRC~1", "PGPASS~1", "HTPASS~1", "GIT-CR~1", "VAULT-~1", "KUBECO~1", "CREDEN~1.JSO", "CREDEN~1",
+    "ID_ED2~1", "ID_RSA~1", "SERVIC~1.JSO", "SECRET~1.JSO", "MY-LON~1.PEM", "SERVER~1.KEY", "STATE~1.TFS", "PROD~1.TFV", "VAULT~1.KDB", "API-KE~1.SEC", "dir/ENV~1",
+];
+const NOT_SENSITIVE = ["src/environment.js", "env.js", "src/env/index.js", "notes~1.txt", "enviro~1.txt", "a~1.txt", "credential-store.js", "kube.js", "src/kubeconfigs.md.txt".replace("kubeconfigs.md.txt", "kubectl.md"),
+    "README~1.md", "id_rsa_notes_dir/readme.md".replace("id_rsa_notes_dir/", "docs/id-rsa-")];
+
+test("deny list (F3-07b): .env~, NTFS streams (::$DATA), kubeconfig, id_*, *.kdbx, .npmrc, .pypirc, credentials*, 8.3 aliases; look-alikes stay readable", () => {
+    for (const p of SENSITIVE) assert.equal(isSensitivePath(p), true, p);
+    for (const p of NOT_SENSITIVE) assert.equal(isSensitivePath(p), false, p);
+    for (const p of [".env.", ".env ", ".ENV. .", "dir/.env..."]) assert.equal(isSensitivePath(p), true, "trailing dots/spaces: " + JSON.stringify(p));
+    assert.equal(isSensitivePath("a:b/c.txt"), false, "a colon alone is an ordinary character");
+    assert.equal(isSensitivePath("cert:v1.pem"), true, "an extension that is sensitive stays sensitive with a colon in the name");
+});
+
+test("deny list: nothing in it can be minted as an id and a swapped-in sensitive name is forbidden at read time", async () => {
+    await withRig({}, async (rig) => {
+        for (const rel of [".env~", ".env::$DATA", "kubeconfig", "CREDEN~1.JSO", "ENV~1", "credentials.json", ".npmrc"]) {
+            assert.equal(rig.mint("file", rel), null, rel);
+        }
+        write(rig.root(), "ok.txt", "fine");
+        const id = rig.mint("file", "ok.txt");
+        fs.rmSync(path.join(rig.root(), "ok.txt"));
+        write(rig.root(), "kubeconfig", "apiVersion: v1\ntoken: abc\n");
+        fs.symlinkSync(path.join(rig.root(), "kubeconfig"), path.join(rig.root(), "ok.txt"));
+        assert.equal((await rig.request({ ref: id })).status, "forbidden", "a harmless name that is a link to kubeconfig");
+    });
+});
+
+test("normalizeRel still refuses what it refused (regression of the wider list)", () => {
+    for (const bad of ["../a", "/a", "C:\\a", "a\u0000b", ""]) assert.equal(normalizeRel(bad), null);
+});
+
+// ------------------------------------------------------------------------------------------ 7. git filters
+
+/** A repo with a clean/smudge/process filter that would touch a marker file; returns where the marker would be. */
+function repoWithFilters(root, { required = true, names = ["evil"], withProcess = true } = {}) {
+    const marks = path.join(tmpDir("f307b-marks-"), "m");
+    fs.mkdirSync(marks);
+    write(root, ".gitattributes", "*.js filter=evil\n*.txt filter=we.ird.name\n");
+    write(root, "a.js", "one\n");
+    write(root, "b.txt", "one\n");
+    initRepo(root);
+    const sh = (n) => `touch '${path.join(marks, n)}'; cat`;
+    git(root, "config", "filter.evil.clean", sh("evil-clean"));
+    git(root, "config", "filter.evil.smudge", sh("evil-smudge"));
+    if (withProcess) git(root, "config", "filter.evil.process", `touch '${path.join(marks, "evil-process")}'`);
+    git(root, "config", "filter.we.ird.name.clean", sh("dotted-clean"));
+    if (required) { git(root, "config", "filter.evil.required", "true"); git(root, "config", "filter.we.ird.name.required", "true"); }
+    for (const n of names.slice(1)) git(root, "config", `filter.${n}.clean`, sh(`${n}-clean`));
+    write(root, "a.js", "two\n");
+    write(root, "b.txt", "two\n");
+    return marks;
+}
+const marksOf = (dir) => fs.readdirSync(dir);
+
+test("git filters (F3-07b): the clean filter of the repository config is NOT executed by the diff (control: plain `git diff` executes it); the diff is still right", async () => {
+    const root = tmpDir(); const marks = repoWithFilters(root, { required: false, withProcess: false });
+    // control: without the neutralisation git runs the repository's command (this is what the finding was about)
+    git(root, "-c", "core.fsmonitor=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "HEAD");
+    assert.ok(marksOf(marks).length > 0, "control: a plain git diff DID run a filter here; if this fails the test below proves nothing");
+    for (const f of marksOf(marks)) fs.rmSync(path.join(marks, f));
+    const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+    assert.equal(d.ok, true);
+    assert.match(d.text, /\+two/);
+    assert.match(d.text, /a\.js/);
+    assert.match(d.text, /b\.txt/);
+    assert.deepEqual(marksOf(marks), [], "no clean, smudge or process command ran");
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(marks, { recursive: true, force: true });
+});
+
+test("git filters: required=true filters, process filters and filter names with dots are neutralised too (a required filter with an empty command would abort git)", async () => {
+    const root = tmpDir(); const marks = repoWithFilters(root, { required: true });
+    const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+    assert.equal(d.ok, true, JSON.stringify(d));
+    assert.match(d.text, /\+two/);
+    assert.deepEqual(marksOf(marks), []);
+    fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(marks, { recursive: true, force: true });
+});
+
+test("git filters: a filter in the user's GLOBAL git config is neutralised as well", async () => {
+    const root = tmpDir(); write(root, ".gitattributes", "*.js filter=gl\n"); write(root, "a.js", "one\n"); initRepo(root);
+    write(root, "a.js", "two\n");
+    const home = tmpDir("f307b-home-"); const marks = tmpDir("f307b-gm-");
+    fs.writeFileSync(path.join(home, ".gitconfig"), `[filter "gl"]\n\tclean = touch '${path.join(marks, "global")}'; cat\n\trequired = true\n`);
+    const oldHome = process.env.HOME; const oldUp = process.env.USERPROFILE; const oldXdg = process.env.XDG_CONFIG_HOME;
+    process.env.HOME = home; process.env.USERPROFILE = home; process.env.XDG_CONFIG_HOME = path.join(home, ".config");
+    try {
+        const o = await filterOverrides({ cwd: root, timeoutMs: 5000 });
+        assert.equal(o.ok, true);
+        assert.ok(o.args.includes("filter.gl.clean="), "the global filter is listed");
+        const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+        assert.equal(d.ok, true);
+        assert.match(d.text, /\+two/);
+        assert.deepEqual(marksOf(marks), []);
+    } finally {
+        for (const [k, v] of [["HOME", oldHome], ["USERPROFILE", oldUp], ["XDG_CONFIG_HOME", oldXdg]]) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+        for (const d of [root, home, marks]) fs.rmSync(d, { recursive: true, force: true });
+    }
+});
+
+test("git filters: fail closed when the repository defines an absurd number of filters; none defined is a normal diff", async () => {
+    const root = tmpDir(); write(root, "a.txt", "one\n"); initRepo(root); write(root, "a.txt", "two\n");
+    const none = await filterOverrides({ cwd: root, timeoutMs: 5000 });
+    assert.equal(none.ok, true); // (a global/system git-lfs config, if any, is listed: it is neutralised too)
+    assert.equal(none.args.some((a) => a.startsWith("filter.f")), false);
+    for (let i = 0; i < 65; i++) git(root, "config", `filter.f${i}.clean`, "cat");
+    const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+    assert.deepEqual([d.ok, d.status, d.errorCode], [false, "error", "internal"]);
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("git filters: a repository config git cannot read (the filter list fails) means no diff, not a diff without the neutralisation", async () => {
+    const root = tmpDir(); write(root, "a.txt", "one\n"); initRepo(root); write(root, "a.txt", "two\n");
+    fs.appendFileSync(path.join(root, ".git", "config"), "\n[filter \"x\"\n  clean = ((( broken\n");
+    const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+    assert.deepEqual([d.ok, d.status, d.errorCode], [false, "error", "internal"]);
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("git filters through the handler: kind diff worktree and an id, in enforce, run no filter; the answer is masked", async () => {
+    await withRig({}, async (rig) => {
+        const marks = repoWithFilters(rig.root(), { required: true });
+        rig.dirs.push(marks);
+        write(rig.root(), "a.js", `two\nk=${GH}\n`);
+        const r = await rig.request({ kind: "diff", ref: "worktree" });
+        assert.equal(r.status, "ok");
+        assert.equal(r.text.includes(GH), false);
+        assert.match(r.text, /\[REDACTED:github_token\]/);
+        const one = await rig.request({ kind: "diff", ref: rig.mint("diff", "a.js") });
+        assert.equal(one.status, "ok");
+        assert.deepEqual(marksOf(marks), [], "no filter command ran, for either request");
+    });
+});
+
+test("git diff and hard links: a tracked file that is a hard link is left out of the diff by default (git would read the data of a file that may live outside the root); the flag lifts it", async (t) => {
+    const base = tmpDir(); const root = path.join(base, "ws"); fs.mkdirSync(root);
+    write(root, "plain.txt", "one\n"); write(root, "hard.txt", "one\n");
+    initRepo(root);
+    write(root, "plain.txt", "two\n"); write(root, "hard.txt", "two\n");
+    try { fs.linkSync(path.join(root, "hard.txt"), path.join(base, "alias.txt")); } catch { t.skip("hard links not supported here"); return; }
+    try {
+        const d = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000 });
+        assert.equal(d.ok, true);
+        assert.match(d.text, /plain\.txt/);
+        assert.equal(d.text.includes("hard.txt"), false);
+        const allowed = await worktreeDiff({ root, maxBytes: 1 << 20, maxFiles: 50, timeoutMs: 8000, allowHardlinks: true });
+        assert.match(allowed.text, /hard\.txt/);
+    } finally { fs.rmSync(base, { recursive: true, force: true }); }
+});
+
+test("git diff and hard links through the handler: LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS reaches the diff (default: left out)", async (t) => {
+    for (const [allow, expected] of [[undefined, false], ["true", true]]) {
+        const base = tmpDir(); const root = path.join(base, "ws"); fs.mkdirSync(root);
+        write(root, "plain.txt", "one\n"); write(root, "hard.txt", "one\n");
+        initRepo(root);
+        write(root, "plain.txt", "two\n"); write(root, "hard.txt", "two\n");
+        try { fs.linkSync(path.join(root, "hard.txt"), path.join(base, "alias.txt")); } catch { t.skip("hard links not supported here"); fs.rmSync(base, { recursive: true, force: true }); return; }
+        await withRig({ workspaces: { "ws-1": { root } }, env: allow ? { LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS: allow } : {} }, async (rig) => {
+            const r = await rig.request({ kind: "diff", ref: "worktree" });
+            assert.equal(r.status, "ok");
+            assert.match(r.text, /plain\.txt/);
+            assert.equal(r.text.includes("hard.txt"), expected, String(allow));
+        });
+        fs.rmSync(base, { recursive: true, force: true });
+    }
+});