deepdebug-local-agent 1.5.0 → 1.6.0

package/docs/la-protocol-v2.md

@@ -50,34 +50,61 @@ It also needs `TENANT_ID` to be a UUID and the agent id (`authorizationId` of `~
   answers in the v1 shape. **The gateway (F3-05a) still refuses to send v1 commands to a v2 agent
   (`protocol_mismatch`)**: this is ready on the LA side, but it will only be exercised once the gateway sends them.
 
-## Content handlers (F3-07, `LOCAL_AGENT_CONTENT_HANDLERS`, default false)
+## Content handlers (F3-07 / F3-07b, `LOCAL_AGENT_CONTENT_HANDLERS`, default false)
 
-Needs `LOCAL_AGENT_PROTOCOL_V2=true` too. Off (unset, empty, `false` or any unknown value): `content.request` is acked
-`rejected protocol_unsupported` exactly as before and the register announces no `content.*` capability. On: kinds
-`file` and `diff` are served (capabilities `content.file`, `content.diff`); any other kind of the allowlist answers
-`content.response` `status:"error"` + `errorCode:"protocol_unsupported"`.
+Needs `LOCAL_AGENT_PROTOCOL_V2=true` too, **and `LOCAL_AGENT_DLP_MODE=enforce` (F3-07b, no opt-out)**. Off (unset, empty,
+`false` or any unknown value): `content.request` is acked `rejected protocol_unsupported` exactly as before and the register
+announces no `content.*` capability. On with DLP `enforce`: kinds `file` and `diff` are served (capabilities `content.file`,
+`content.diff`); any other kind of the allowlist answers `content.response` `status:"error"` + `errorCode:"protocol_unsupported"`.
+On with DLP anything else (`off`, `warn`, unset, an unknown value): the handlers are **not registered**, no `content.*`
+capability is announced, `content.request` is acked `rejected protocol_unsupported`, and the agent logs an explicit ERROR at
+start-up. The mode is also read at each request: leaving `enforce` at run time stops serving at once.
 
-- **Opaque ids.** The `ref` is an id (`cr1_` + 128 random bits, base64url) minted by the agent, never derived from a path.
+- **Opaque ids.** The `ref` is an id of **43 base64url characters, no prefix** (32 random bytes = 256 bits, the shape the
+  gateway and the contract require; the F3-07 form `cr1_` + 22 is gone) minted by the agent, never derived from a path.
   It maps in memory to (tenant, workspace, root, kind, relative path), lives `LOCAL_AGENT_CONTENT_REF_TTL_MS` (15 min) and
   is forgotten when the agent restarts. Anything that is not a live id for this tenant+workspace+root+kind (unknown,
   expired, another workspace, a path, `../x`) is `not_found` and is never echoed. The only other ref is the symbolic
-  `worktree` for kind `diff` (the work tree of the envelope's workspace). Whoever reports metadata to the control plane
-  gets an id with `link.content.mintRef({workspaceId, kind, rel})` (no caller yet: see the F3-07 note).
+  `worktree` for kind `diff` (the whole work tree of the envelope's workspace; the gateway requires a workspaceId with it).
+  Whoever reports metadata to the control plane gets an id with `link.content.mintRef({workspaceId, kind, rel, size?})`
+  (no caller yet: see the F3-07 note); the id is announced in `content.index` (below).
+- **`content.index` (LA -> CP, F3-07b).** An unsigned, unsolicited frame with the inventory of ids: `payload.entries[]`
+  (1..256) of `{kind, ref, size}`, for ONE workspace (the envelope's). It cannot carry a name or a path (the schema has no
+  such field). Sent only when the handlers are on (so DLP is `enforce`) and the session is `ready`: a batch after each
+  `mintRef` (`LOCAL_AGENT_CONTENT_INDEX_BATCH_MS`, 100 ms), and every live id again after a `ready` that is not a resume
+  (`announce()` does it on request). At most `LOCAL_AGENT_CONTENT_INDEX_MAX_IDS` (2048, the gateway's per-session limit) live
+  announced ids; one frame in flight. The ack is the answer: `rejected rate_limited` = nothing stored, back off 30 s doubling
+  to 5 min; `rejected protocol_unsupported` = the gateway keeps no index, stop until the next connection; `rejected internal`
+  or a timeout = retry in 5 s. The index is NOT an access list: the agent stays the authority.
 - **The agent is the authority on paths.** Workspace must be registered here and belong to this tenant; the real path
   must stay inside the real root (a link that leaves it is `forbidden`), must not be sensitive under its real name,
-  must be a regular file opened without following links. Sensitive by default: `.env*`, `*.pem`, `*.key`, `*.p12`,
-  `id_rsa*`..., `.npmrc`, `.netrc`, `*.tfstate`, `.git/`, `.ssh/`, `.aws/`, `.docker/`... (`LOCAL_AGENT_CONTENT_DENY_GLOBS`
-  adds to the list). No id is ever minted for them.
+  must be a regular file opened without following links. Sensitive by default: `.env*` (also `.env~`, `.env#`), `*.pem`,
+  `*.key`, `*.p12`, `*.kdbx`, `id_rsa*`..., `.npmrc`, `.pypirc`, `.netrc`, `credentials*` (so `credentials.service.ts` is
+  refused too: add nothing, rename or read it another way), `kubeconfig`, `*.tfstate`, `.git/`, `.ssh/`, `.aws/`, `.kube/`,
+  `.docker/`... plus the NTFS stream form of any of them (`.env::$DATA`) and the Windows 8.3 aliases (`ENV~1`, `CREDEN~1.JSO`,
+  `ID_ED2~1`). `LOCAL_AGENT_CONTENT_DENY_GLOBS` adds to the list. No id is ever minted for them.
+- **Hard links (F3-07b).** A file with more than one hard link (`st.nlink > 1`) is `forbidden` by default: a hard link
+  cannot be told from the file itself and may be a second name of a file OUTSIDE the root, which the realpath check cannot
+  see. Checked on the path and again on the open descriptor; the diff leaves such files out. `LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS=true`
+  lifts it (pnpm stores and some build trees hard-link every file).
 - **DLP before anything leaves** (`LOCAL_AGENT_DLP_MODE`, the module `src/dlp`): `enforce` masks the whole text before it is
   chunked (a secret cannot straddle chunks), withholds a file with a hit in `LOCAL_AGENT_DLP_BLOCK_CLASSES`, and fails
-  closed for binary files, inputs above `LOCAL_AGENT_DLP_MAX_BYTES` and DLP errors. `warn` and `off` send the content as
-  read (warn only counts). The agent warns at start-up when handlers are on and the mode is not `enforce`.
+  closed for binary files, inputs above `LOCAL_AGENT_DLP_MAX_BYTES` and DLP errors. `warn` and `off` serve NOTHING (see
+  above).
 - **Limits.** `LOCAL_AGENT_CONTENT_MAX_BYTES` per response (default 1 MiB, ceiling 2 MiB = 64 chunks; a file above it is
   `payload_too_large` without being read), `LOCAL_AGENT_CONTENT_MAX_CONCURRENT` (4) and `..._MAX_INFLIGHT_BYTES`
   (`rate_limited` above), `LOCAL_AGENT_CONTENT_TOTAL_MS` (25 s), the session window (8 chunks in flight, backpressure).
   Cancellation: `handler.cancel(requestId)`, the deadline, closing the link, or loss of the session.
 - **Diff.** `git diff HEAD` of the work tree, no shell, without external diff/textconv/fsmonitor, without any `GIT_*` of
   the agent's env, only for files that pass the same deny list, at most `LOCAL_AGENT_CONTENT_MAX_DIFF_FILES` (500).
+  **Clean/smudge/process filters are neutralised (F3-07b)**: `--no-ext-diff`/`--no-textconv` do not stop `git diff` from
+  running the `filter.<name>.clean` command of the repository (or global) config, a command line chosen by whoever wrote the
+  repository. Before the diff the agent lists `filter.*` names (`git config --get-regexp '^filter\.'`, runs nothing) and
+  overrides each with an empty clean/smudge/process and `required=false`; if the list cannot be read, or has more than 64
+  names, there is no diff (fail closed). A tree that depends on a filter (git-lfs, keyword expansion) is diffed as stored.
+- **When `produce()` fails (F3-07b).** A workspace lookup, registry or filesystem call that throws never leaves the gateway
+  waiting: it gets `content.response` `status:"error"` + `errorCode:"internal"` (a code, never the exception message, which
+  may hold a path) and the request is audited like any other; an audit failure does not stop the answer.
 - **Audit.** One local record per request (kind, status, code, sizes, DLP mode and per-rule counts, a short hash of the
   ref): in memory and optionally `LOCAL_AGENT_CONTENT_AUDIT_FILE` (JSONL, 0600, rotates at 5 MiB). Never content,
   paths or the ref.
@@ -85,17 +112,20 @@ Needs `LOCAL_AGENT_PROTOCOL_V2=true` too. Off (unset, empty, `false` or any unkn
 ## What it does NOT do
 
 No handler for the other kinds (`incident.*`, `log.*`, `chat.session`, `wiki.page`, `job.*`, `approval.detail`, `report`),
-no inventory frame that tells the control plane which ids exist (the contract has none), no log/incident detector
+nothing in the agent calls `mintRef` yet (the producer of the file/diff inventory is a later increment), no log/incident detector
 (F3-11b), no `job.assign` runtime (F3-08). Those frames are acked `rejected protocol_unsupported`. `sha256` of
 `content.response` is not sent (the contract does not say what it covers).
 
 ## Tests
 
 `npm test` (node:test), all in `test/la-protocol-v2/`:
-`contract.test.js` (all 134 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 24
+`contract.test.js` (all 168 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 26
 traces), `session-inbound.test.js`, `session-outbound.test.js`, `link.test.js`, `tunnel-e2e.test.js` (the real
 `src/server.js` against a reference CP; flag off = v1 frames), and for F3-07 `content-path-guard.test.js`,
-`content-handlers.test.js`, `content-wiring.test.js` (flag, runtime wiring, real `src/server.js`). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
+`content-handlers.test.js`, `content-wiring.test.js` (flag, runtime wiring, real `src/server.js`), and for F3-07b
+`content-alignment.test.js` (43-char ids and `worktree`, `content.index`, throwing producers, hard links, deny list, git filters).
+Against the real gateway: `tools/interop` (`LaV2NodeContentInteropTest` straight into `LaV2Session`;
+`LaV2NodeContentRelayE2ETest`: HTTP -> `ContentRelayController` -> `LaV2Session` -> this agent, no patch on either side). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
 is a Node model of the gateway rules, not the gateway.
 
 **Interoperability with the real gateway session** (`LaV2Session`, Java, real Reactor Netty socket on loopback, real

package/env.example

@@ -80,3 +80,7 @@ LOG_LEVEL=info
 # DLP (T4-09): mask secrets/PII before content leaves the agent. Default off.
 # LOCAL_AGENT_DLP_MODE=off|warn|enforce   (warn = count only, enforce = redact)
 # LOCAL_AGENT_DLP_BLOCK_CLASSES=private-key,cloud-credential   (enforce: withhold whole text)
+# LOCAL_AGENT_CONTENT_HANDLERS=true   serves content.request kinds file/diff over protocol v2 (needs LOCAL_AGENT_PROTOCOL_V2=true AND
+#                                      LOCAL_AGENT_DLP_MODE=enforce: without enforce the handlers are NOT registered, no opt-out)
+# LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS=true   serve files with more than one hard link (refused by default)
+# LOCAL_AGENT_CONTENT_INDEX_MAX_IDS=2048     live ids announced to the gateway in content.index (max 2048)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/scripts/sync-la-protocol-v2-contract.mjs

@@ -2,7 +2,7 @@
 // scripts/sync-la-protocol-v2-contract.mjs - copies the CP <-> LA protocol v2 contract (F3-22) from a
 // vh-api-gateway checkout into this repo and records where it came from.
 //
-//   node scripts/sync-la-protocol-v2-contract.mjs <gateway-contract-dir> --commit <sha> [--tip <sha>]
+//   node scripts/sync-la-protocol-v2-contract.mjs <gateway-contract-dir> --commit <sha> [--tip <sha>] [--branch <name>]
 //
 // <gateway-contract-dir> is docs/contracts/la-protocol-v2 of vh-api-gateway (a worktree of release/qa, or
 // the output of `git archive`). The gateway folder stays the only source of truth: never edit the copies.
@@ -20,7 +20,7 @@ const src = args.find((a) => !a.startsWith("--"));
 const opt = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
 const commit = opt("commit");
 if (!src || !commit || !/^[0-9a-f]{40}$/.test(commit)) {
-    console.error("usage: sync-la-protocol-v2-contract.mjs <gateway docs/contracts/la-protocol-v2> --commit <40-hex sha> [--tip <sha>]");
+    console.error("usage: sync-la-protocol-v2-contract.mjs <gateway docs/contracts/la-protocol-v2> --commit <40-hex sha> [--tip <sha>] [--branch <name>]");
     process.exit(2);
 }
 const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
@@ -49,7 +49,7 @@ copyTree(path.join(src, "vectors"), path.join(vectorsDir, "vectors"), "vectors")
 fs.writeFileSync(path.join(runtimeDir, "CONTRACT_SOURCE.json"), JSON.stringify({
     repo: "VISIONHAMMER/vh-api-gateway",
     path: "docs/contracts/la-protocol-v2",
-    branch: "release/qa",
+    branch: opt("branch") || "release/qa", // default release/qa; a stacked gateway PR passes its own branch until it is merged
     commit,
     ...(opt("tip") ? { branchTip: opt("tip") } : {}),
     note: "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",

package/src/la-protocol-v2/content-handlers/config.js

@@ -5,7 +5,8 @@
  *   true             handlers for `file` and `diff` are registered. Needs LOCAL_AGENT_PROTOCOL_V2=true as well
  *                    (without it there is no v2 session and the flag does nothing).
  *
- * Unset/empty/unrecognised = false (an unknown value must never open the door to client content).
+ * Even when true, the handlers are registered only with LOCAL_AGENT_DLP_MODE=enforce (F3-07b, runtime.js): there is no
+ * opt-out. Unset/empty/unrecognised = false (an unknown value must never open the door to client content).
  * Every number is clamped: a bad value falls back to the default, never to "unlimited".
  */
 export const CONTENT_HANDLERS_FLAG = "LOCAL_AGENT_CONTENT_HANDLERS";
@@ -44,5 +45,10 @@ export function resolveContentHandlersConfig(env = process.env, warn = console.w
         // additive to the built-in list (path-guard.js); comma separated globs
         extraDenyGlobs: String(env.LOCAL_AGENT_CONTENT_DENY_GLOBS ?? "").split(",").map((s) => s.trim()).filter(Boolean).slice(0, 200),
         auditFile: String(env.LOCAL_AGENT_CONTENT_AUDIT_FILE ?? "").trim() || null,
+        // F3-07b: a file with more than one hard link is refused by default (it may be a second name of a file outside the root)
+        allowHardlinks: TRUE.has(String(env.LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS ?? "").trim().toLowerCase()),
+        // F3-07b: content.index (inventory of the ids this agent minted). The gateway keeps at most 2048 live ids per session.
+        indexMaxIds: int(env.LOCAL_AGENT_CONTENT_INDEX_MAX_IDS, 2048, 1, 2048),
+        indexBatchMs: int(env.LOCAL_AGENT_CONTENT_INDEX_BATCH_MS, 100, 0, 5_000),
     };
 }

package/src/la-protocol-v2/content-handlers/content-index.js

@@ -0,0 +1,161 @@
+/**
+ * content-index.js - announces the opaque ids this agent minted to the control plane: `content.index` (F3-07b, contract
+ * F3-22). The frame carries `{kind, ref, size}` per id and nothing else: no name, no path, no free text (the schema has no
+ * field for one). The control plane keeps it in memory with a TTL so a client can know which ids exist; it is NOT an access
+ * list: this agent stays the authority and answers `not_found` / `forbidden` for whatever it does not serve.
+ *
+ *   when      every id minted by link.content.mintRef is queued and sent after `batchMs` (grouped by workspace, at most 256 per
+ *             frame, the contract limit); after every `ready` that is not a resume, every live id is announced again (a new
+ *             gateway session knows nothing); `announce()` does the same on request.
+ *   only if   v2 session `ready`. install.js exists only with the content handlers on, and those only with DLP `enforce`.
+ *   bounds    at most `maxIds` (<= 2048, the gateway's per-session limit) live announced ids; the rest is still served, only
+ *             not announced. One frame in flight at a time (the ack is the answer).
+ *   the ack   accepted = stored. rejected rate_limited = nothing of that frame was stored: back off (30 s, doubling to 5 min)
+ *             and announce again. rejected protocol_unsupported = this gateway keeps no index: stop until the next `ready`.
+ *             rejected internal / timeout = try again after a short pause. Anything else (reset, not_ready): the next `ready`
+ *             announces again.
+ *   never     logs an id, a size or a path: counters and codes only.
+ */
+import { ProtocolError } from "../errors.js";
+
+const MAX_PER_FRAME = 256;
+const BACKOFF_MIN_MS = 30_000;
+const BACKOFF_MAX_MS = 300_000;
+const RETRY_MS = 5_000;
+
+export function createContentIndexer({ session, registry, config, log = console, now = Date.now, timers = { setTimeout, clearTimeout } }) {
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const pending = new Map();          // workspaceId -> [{kind, ref, size}]
+    const announced = new Map();        // id -> expiresAt (local clock), ids the gateway accepted in this session
+    let batchTimer = null;
+    let retryTimer = null;
+    let stopped = false;                // protocol_unsupported: stay quiet until the next ready
+    let backoffMs = 0;
+    let closed = false;
+    const stats = { queued: 0, frames: 0, entries: 0, accepted: 0, rejected: 0, dropped: 0, byCode: {} };
+
+    const ready = () => session.state === "ready";
+    const unref = (t) => { if (t && typeof t.unref === "function") t.unref(); return t; };
+
+    function pruneAnnounced() {
+        const t = now();
+        for (const [id, exp] of announced) if (exp <= t) announced.delete(id);
+    }
+
+    function enqueue(e) {
+        if (closed || stopped) { stats.dropped++; return false; }
+        pruneAnnounced();
+        let queued = 0;
+        for (const list of pending.values()) queued += list.length;
+        if (announced.size + queued >= config.indexMaxIds) { stats.dropped++; return false; }
+        const list = pending.get(e.workspaceId) || [];
+        list.push({ kind: e.kind, ref: e.ref, size: e.size, expiresAt: e.expiresAt });
+        pending.set(e.workspaceId, list);
+        stats.queued++;
+        return true;
+    }
+
+    function schedule(ms = config.indexBatchMs) {
+        if (closed || batchTimer) return;
+        batchTimer = unref(timers.setTimeout(() => { batchTimer = null; void pump(); }, ms));
+    }
+
+    function scheduleRetry(ms) {
+        if (closed || retryTimer) return;
+        retryTimer = unref(timers.setTimeout(() => { retryTimer = null; announce(); }, ms));
+    }
+
+    let running = null;
+    function pump() {
+        if (running) return running;
+        if (closed || stopped || !ready()) return Promise.resolve(); // not ready: the next `ready` announces everything still live
+        running = drain().finally(() => { running = null; });
+        return running;
+    }
+
+    async function drain() {
+        try {
+            for (;;) {
+                const next = pending.entries().next();
+                if (next.done) break;
+                const [workspaceId, list] = next.value;
+                const batch = list.splice(0, MAX_PER_FRAME);
+                if (list.length === 0) pending.delete(workspaceId);
+                if (batch.length === 0) continue;
+                const entries = batch.map(({ kind, ref, size }) => ({ kind, ref, size }));
+                stats.frames++;
+                stats.entries += entries.length;
+                try {
+                    await session.send("content.index", { entries }, { workspaceId });
+                    stats.accepted += entries.length;
+                    for (const b of batch) announced.set(b.ref, b.expiresAt);
+                } catch (e) {
+                    const code = e instanceof ProtocolError ? e.code : "internal";
+                    stats.rejected += entries.length;
+                    stats.byCode[code] = (stats.byCode[code] || 0) + 1;
+                    pending.clear(); // the rest comes back with the next announce(); nothing is kept half-sent
+                    if (code === "protocol_unsupported") {
+                        stopped = true;
+                        warn("[la-content] the gateway keeps no content index (protocol_unsupported); not announcing ids until the next connection");
+                    } else if (code === "rate_limited") {
+                        backoffMs = Math.min(BACKOFF_MAX_MS, backoffMs ? backoffMs * 2 : BACKOFF_MIN_MS);
+                        warn(`[la-content] content.index rate limited; announcing again in ${Math.round(backoffMs / 1000)} s`);
+                        scheduleRetry(backoffMs);
+                    } else if (code === "internal" || code === "timeout") {
+                        warn(`[la-content] content.index not accepted (${code}); trying again shortly`);
+                        scheduleRetry(RETRY_MS);
+                    }
+                    // other codes (not_ready, agent_offline, session reset): the next ready announces again
+                    return;
+                }
+            }
+            backoffMs = 0;
+        } catch { /* nothing here may throw into the data path */ }
+    }
+
+    /** Queues every live id (of one workspace, or of all) that the gateway does not know yet, and sends. */
+    function announce({ workspaceId } = {}) {
+        if (closed || stopped) return 0;
+        pruneAnnounced();
+        let n = 0;
+        const live = registry.live().filter((e) => (workspaceId === undefined || e.workspaceId === workspaceId) && !announced.has(e.id));
+        // when there are more than the gateway keeps, the newest ones are the ones a client can still use
+        const room = Math.max(0, config.indexMaxIds - announced.size);
+        for (const e of room === 0 ? [] : live.slice(-room)) {
+            if (enqueue({ workspaceId: e.workspaceId, kind: e.kind, ref: e.id, size: e.size, expiresAt: e.expiresAt })) n++;
+        }
+        if (n > 0) schedule(0);
+        return n;
+    }
+
+    const onReady = (info) => {
+        stopped = false;
+        backoffMs = 0;
+        if (!info || !info.resumed) { announced.clear(); pending.clear(); announce(); }
+        else void pump();
+    };
+    session.on("ready", onReady);
+
+    return {
+        stats,
+        /** A freshly minted id: queued, sent after the batch delay. */
+        add({ workspaceId, kind, ref, size = 0, expiresAt }) {
+            const ok = enqueue({ workspaceId, kind, ref, size, expiresAt: expiresAt ?? now() + config.refTtlMs });
+            if (ok) schedule();
+            return ok;
+        },
+        announce,
+        get pending() { let n = 0; for (const l of pending.values()) n += l.length; return n; },
+        get announcedCount() { pruneAnnounced(); return announced.size; },
+        /** Waits until nothing is queued or in flight (tests, shutdown). */
+        async flush() { if (batchTimer) { timers.clearTimeout(batchTimer); batchTimer = null; } await pump(); await running; },
+        close() {
+            closed = true;
+            if (batchTimer) timers.clearTimeout(batchTimer);
+            if (retryTimer) timers.clearTimeout(retryTimer);
+            batchTimer = retryTimer = null;
+            pending.clear();
+            session.off("ready", onReady);
+        },
+    };
+}

package/src/la-protocol-v2/content-handlers/git-diff.js

@@ -2,16 +2,29 @@
  * git-diff.js - `diff` kind: the work tree against HEAD, for the files that may be shown (F3-07).
  *
  * No shell. git runs with the agent's env minus secret-looking variables and minus every GIT_* variable (a stray
- * GIT_DIR must not point it at another repository), without external diff drivers, textconv filters or fsmonitor
- * hooks (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
- * first and filtered (sensitive and out-of-root names never reach the second call), then diffed with that explicit list
- * (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the process is killed above the cap).
+ * GIT_DIR must not point it at another repository), without external diff drivers, textconv or fsmonitor hooks
+ * (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
+ * first and filtered (sensitive names, and hard-linked files unless allowed, never reach the second call), then diffed
+ * with that explicit list (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the
+ * process is killed above the cap).
+ *
+ * Clean/smudge filters (F3-07b). `--no-ext-diff` and `--no-textconv` do NOT stop `git diff` from running the
+ * `filter.<name>.clean` command (and `process`, the long-running filter) of the repository config: to compare a work tree file with
+ * the index git first converts it with the clean filter its .gitattributes names, and that is a command line chosen
+ * by whoever wrote the repository. Before the two diff calls the filters the config defines are listed (`git config
+ * --get-regexp '^filter\.'`, which runs nothing) and every one of them is overridden on the command line with an empty
+ * clean, smudge and process and `required=false` (git treats an empty command as "no filter"; a still-required one
+ * would abort). Fail closed: if the list cannot be read, or has more than MAX_FILTERS names, there is no diff.
+ * Consequence: a work tree that depends on a filter (git-lfs, keyword expansion) is diffed as stored, unfiltered.
  */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import { sanitizedChildEnv } from "../../utils/child-env.js";
+import path from "node:path";
 import { isSensitivePath, normalizeRel } from "./path-guard.js";
 
+const MAX_FILTERS = 64;
+
 const GIT_SAFE = ["--literal-pathspecs", "-c", "core.quotepath=off", "-c", "core.fsmonitor=false", "-c", "core.pager=cat", "-c", "diff.external="];
 
 function gitEnv() {
@@ -53,11 +66,36 @@ function runGit(args, { cwd, input, maxBytes, timeoutMs, signal }) {
     });
 }
 
+/**
+ * `-c` overrides that switch off every filter the repository (or the user's global config) defines.
+ * @returns {Promise<{ok:true, args:string[]} | {ok:false, status:"error", errorCode:string}>}
+ */
+export async function filterOverrides({ cwd, timeoutMs, signal }) {
+    const r = await runGit([...GIT_SAFE, "config", "--null", "--get-regexp", "^filter\\."], { cwd, maxBytes: 1024 * 1024, timeoutMs, signal });
+    if (r.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (r.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (r.code === 1 && !r.overflow) return { ok: true, args: [] };   // exit 1 = no such key: no filter is defined
+    if (r.code !== 0 || r.overflow) return { ok: false, status: "error", errorCode: "internal" };
+    const names = new Set();
+    for (const entry of r.out.toString("utf8").split("\0")) {
+        const key = entry.split("\n", 1)[0];                          // "filter.<name>.<variable>" (name may contain dots)
+        if (!key.toLowerCase().startsWith("filter.")) continue;
+        const last = key.lastIndexOf(".");
+        if (last <= "filter.".length) continue;                        // "filter.x": a variable without a name, nothing to run
+        names.add(key.slice("filter.".length, last));
+    }
+    if (names.size > MAX_FILTERS) return { ok: false, status: "error", errorCode: "internal" };
+    const args = [];
+    for (const n of names) for (const v of ["clean", "smudge", "process"]) args.push("-c", `filter.${n}.${v}=`);
+    for (const n of names) args.push("-c", `filter.${n}.required=false`);
+    return { ok: true, args };
+}
+
 /**
  * @param {{root:string, rel?:string|null, maxBytes:number, maxFiles:number, timeoutMs:number, denyGlobs?:string[], signal?:AbortSignal}} o
  * @returns {Promise<{ok:true, text:string} | {ok:false, status:"not_found"|"forbidden"|"error", errorCode?:string}>}
  */
-export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], signal }) {
+export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], allowHardlinks = false, signal }) {
     let cwd;
     try { cwd = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
     let only = null;
@@ -66,7 +104,10 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
         if (!only) return { ok: false, status: "not_found" };
         if (isSensitivePath(only, denyGlobs)) return { ok: false, status: "forbidden" };
     }
-    const listArgs = [...GIT_SAFE, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
+    const filters = await filterOverrides({ cwd, timeoutMs, signal });
+    if (!filters.ok) return filters;
+    const safe = [...GIT_SAFE, ...filters.args];
+    const listArgs = [...safe, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
     const listed = await runGit(listArgs, { cwd, maxBytes: 4 * 1024 * 1024, timeoutMs, signal });
     if (listed.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
     if (listed.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
@@ -77,12 +118,13 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     for (const n of listed.out.toString("utf8").split("\0")) {
         const norm = n ? normalizeRel(n) : null;
         if (!norm || isSensitivePath(norm, denyGlobs)) continue;
+        if (!allowHardlinks && await isHardLinked(cwd, norm)) continue;   // git would read the data of a file that may live outside the root
         argBytes += Buffer.byteLength(norm) + 1;
         if (names.length >= maxFiles || argBytes > 128 * 1024) break;
         names.push(norm);
     }
     if (names.length === 0) return { ok: true, text: "" };
-    const diffArgs = [...GIT_SAFE, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
+    const diffArgs = [...safe, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
     const diff = await runGit(diffArgs, { cwd, maxBytes: maxBytes + 1, timeoutMs, signal });
     if (diff.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
     if (diff.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
@@ -90,3 +132,11 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     if (diff.code !== 0) return { ok: false, status: "error", errorCode: "internal" };
     return { ok: true, text: diff.out.toString("utf8") };
 }
+
+/** True for a regular file with more than one link. A name that no longer exists (a deletion) is not one. */
+async function isHardLinked(cwd, rel) {
+    try {
+        const st = await fs.promises.lstat(path.join(cwd, ...rel.split("/")));
+        return st.isFile() && st.nlink > 1;
+    } catch { return false; }
+}

package/src/la-protocol-v2/content-handlers/handler.js

@@ -25,6 +25,7 @@ import { normalizeRel, resolveInside, readRegular } from "./path-guard.js";
 import { worktreeDiff } from "./git-diff.js";
 import { prepareOutgoing, contentTypeOf, decodeText } from "./egress.js";
 import { createAudit, short } from "./audit.js";
+import { dlpConfigFromEnv } from "../../dlp/index.js";
 
 export const SERVED_KINDS = Object.freeze(["file", "diff"]);
 /** Symbolic ref of kind `diff`: the whole work tree of the envelope's workspace (carries no client data). */
@@ -43,6 +44,9 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
     /** @returns {Promise<{status:string, errorCode?:string, buffer?:Buffer, contentType?:string, dlp?:object}>} */
     async function produce(ctx, p, signal) {
         if (!SERVED_KINDS.includes(p.kind)) return { status: "error", errorCode: "protocol_unsupported" };
+        // F3-07b: content never leaves unmasked. runtime.js does not even register this handler without DLP enforce; this is the
+        // same rule at the moment of the request (the env is read per request), so a changed mode can not open the door.
+        if (dlpConfigFromEnv(env).mode !== "enforce") return { status: "error", errorCode: "protocol_unsupported" };
         const ws = await resolveWorkspace(ctx.workspaceId);
         if (!ws || !ws.root) return { status: "not_found" };
         const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: p.kind });
@@ -55,10 +59,10 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
     async function produceFile(p, ws, rel, signal) {
         const norm = rel && normalizeRel(rel);
         if (!norm) return { status: "not_found" };
-        const resolved = await resolveInside(ws.root, norm, config.extraDenyGlobs);
+        const resolved = await resolveInside(ws.root, norm, config.extraDenyGlobs, { allowHardlinks: config.allowHardlinks });
         if (!resolved.ok) return { status: resolved.status };
         if (signal.aborted) return { status: "error", errorCode: "agent_offline" };
-        const read = await readRegular(resolved, config.maxBytes, signal);
+        const read = await readRegular(resolved, config.maxBytes, signal, { allowHardlinks: config.allowHardlinks });
         if (!read.ok) return read.status === "too_large" ? { status: "error", errorCode: "payload_too_large" } : { status: read.status };
         const isText = decodeText(read.buffer) !== null;
         return finish(p, read.buffer, contentTypeOf(norm, isText), "content.file");
@@ -66,7 +70,7 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
 
     async function produceDiff(p, ws, rel, signal) {
         const d = await worktreeDiff({ root: ws.root, rel, maxBytes: config.maxBytes, maxFiles: config.maxDiffFiles,
-            timeoutMs: config.gitTimeoutMs, denyGlobs: config.extraDenyGlobs, signal });
+            timeoutMs: config.gitTimeoutMs, denyGlobs: config.extraDenyGlobs, allowHardlinks: config.allowHardlinks, signal });
         if (!d.ok) return d;
         return finish(p, Buffer.from(d.text, "utf8"), "text/x-diff", "content.diff");
     }
@@ -79,7 +83,9 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
 
     async function run(ctx, p, entry) {
         const t0 = now();
-        let result;
+        // F3-07b: always defined. If produce() throws, the gateway still gets an answer (a code, never the message of the
+        // exception: it may carry a path) and the request is audited like any other.
+        let result = { status: "error", errorCode: "internal" };
         let sent = null;
         let errorCode;
         try {
@@ -88,7 +94,11 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
             } else {
                 reservedBytes += reserveEach;
                 entry.reserved = true;
-                result = await produce(ctx, p, entry.ac.signal);
+                try {
+                    result = await produce(ctx, p, entry.ac.signal);
+                } catch {
+                    result = { status: "error", errorCode: "internal" };
+                }
             }
             if (entry.ac.signal.aborted) {
                 errorCode = "cancelled";
@@ -122,12 +132,14 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
         else if (status === "cancelled" || status === "timeout") stats.cancelled++;
         else stats.error++;
         bump(errorCode || result.errorCode || status);
-        auditor.record({
-            requestId: ctx.requestId, workspaceId: ctx.workspaceId, kind: p.kind, status, errorCode: errorCode || result.errorCode || null,
-            bytes: sent ? sent.bytes : 0, chunks: sent ? sent.chunks : 0, ms: now() - t0,
-            dlpMode: result.dlp ? result.dlp.mode : null, dlpHits: result.dlp ? result.dlp.total : 0, dlpRules: result.dlp ? result.dlp.redactions : {},
-            refSha: short(p.ref), actorRole: p.actor && p.actor.role, actorSha: short(p.actor && p.actor.userId),
-        });
+        try {
+            auditor.record({
+                requestId: ctx.requestId, workspaceId: ctx.workspaceId, kind: p.kind, status, errorCode: errorCode || result.errorCode || null,
+                bytes: sent ? sent.bytes : 0, chunks: sent ? sent.chunks : 0, ms: now() - t0,
+                dlpMode: result.dlp ? result.dlp.mode : null, dlpHits: result.dlp ? result.dlp.total : 0, dlpRules: result.dlp ? result.dlp.redactions : {},
+                refSha: short(p.ref), actorRole: p.actor && p.actor.role, actorSha: short(p.actor && p.actor.userId),
+            });
+        } catch { /* the audit must never take the data path down (nor leave a request without its answer) */ }
         if (status === "send_failed") warn(`[la-content] ${p.kind} not delivered: ${errorCode}`);
     }
 
@@ -147,7 +159,7 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
             entry.timer = setTimeout(() => { entry.reason = "deadline"; entry.ac.abort(); }, config.totalMs);
             inflight.set(ctx.requestId, entry);
             // background: ack first, answer later
-            queueMicrotask(() => { run(ctx, p, entry).catch(() => {}); });
+            queueMicrotask(() => { run(ctx, p, entry).catch(() => warn("[la-content] request failed internally")); });
             return { accept: true };
         },
 

package/src/la-protocol-v2/content-handlers/install.js

@@ -1,19 +1,24 @@
 /**
- * install.js - puts the content handlers on a v2 link (F3-07). Called by runtime.js only when
- * LOCAL_AGENT_CONTENT_HANDLERS=true (and v2 is on). Returns what the rest of the agent needs:
+ * install.js - puts the content handlers on a v2 link (F3-07, F3-07b). Called by runtime.js only when
+ * LOCAL_AGENT_CONTENT_HANDLERS=true, v2 is on AND LOCAL_AGENT_DLP_MODE=enforce. Returns what the rest of the agent needs:
  *
- *   mintRef({workspaceId, kind, rel})  the HOOK for whoever reports metadata to the control plane (file lists,
- *                                      diff summaries): returns an opaque id for that item, or null (sensitive
- *                                      path, unknown workspace). Nothing calls it yet: the contract has no
- *                                      LA->CP frame that carries an inventory (see the F3-07 note, open questions).
+ *   mintRef({workspaceId, kind, rel, size?})  the HOOK for whoever reports metadata to the control plane (file lists, diff
+ *                                      summaries): returns {id, expiresAt} for that item (id = 43 base64url chars), or null
+ *                                      (sensitive path, unknown workspace). The id is also announced to the control plane in a
+ *                                      `content.index` frame ({kind, ref, size}: no name, no path). Nothing in the agent calls
+ *                                      it yet (the inventory producer is a later increment); `announce()` re-sends what is live.
  */
 import { dlpConfigFromEnv } from "../../dlp/index.js";
 import { ContentRefRegistry } from "./ref-registry.js";
 import { createContentHandler, SERVED_KINDS } from "./handler.js";
+import { createContentIndexer } from "./content-index.js";
+import { sizeInsideSync } from "./path-guard.js";
 
 export const CONTENT_CAPABILITIES = Object.freeze(SERVED_KINDS.map((k) => `content.${k}`));
 
 export function installContentHandlers({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console }) {
+    // F3-07b, defence in depth: runtime.js already refuses; nobody can install the handlers without DLP enforce
+    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("content handlers need LOCAL_AGENT_DLP_MODE=enforce");
     const tenant = String(tenantId).toLowerCase();
     const registry = new ContentRefRegistry({ tenantId: tenant, ttlMs: config.refTtlMs, maxEntries: config.maxRefs, denyGlobs: config.extraDenyGlobs });
 
@@ -31,20 +36,30 @@ export function installContentHandlers({ link, tenantId, wsManager, getWorkspace
 
     const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log });
     link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
+    const indexer = createContentIndexer({ session: link.session, registry, config, log });
 
     const closeLink = link.close.bind(link);
-    link.close = () => { handler.cancelAll(); registry.clear(); closeLink(); };
+    link.close = () => { handler.cancelAll(); indexer.close(); registry.clear(); closeLink(); };
 
-    if (dlpConfigFromEnv(env).mode !== "enforce") {
-        (log.warn || log.log).call(log, "[la-content] content handlers are on but LOCAL_AGENT_DLP_MODE is not enforce: file content leaves this machine unmasked");
-    }
     link.content = {
         registry,
         handler,
-        mintRef: ({ workspaceId, kind, rel }) => {
-            const ws = resolveWorkspace(workspaceId);
-            return ws ? registry.mint({ workspaceId, root: ws.root, kind, rel }) : null;
+        indexer,
+        mintRef: ({ workspaceId, kind, rel, size }) => {
+            try {
+                const ws = resolveWorkspace(workspaceId);
+                if (!ws) return null;
+                const bytes = Number.isSafeInteger(size) ? size
+                    : kind === "file" && typeof rel === "string" ? sizeInsideSync(ws.root, rel.replace(/\\/g, "/"), { allowHardlinks: config.allowHardlinks }) : 0;
+                const minted = registry.mint({ workspaceId, root: ws.root, kind, rel, size: bytes });
+                if (minted) indexer.add({ workspaceId, kind, ref: minted.id, size: bytes, expiresAt: minted.expiresAt });
+                return minted;
+            } catch {
+                return null; // a failing workspace manager means "no id", never an exception with a path in it
+            }
         },
+        /** Announces again the live ids (of one workspace or all) that the gateway does not know yet. */
+        announce: (opts) => indexer.announce(opts),
     };
     return link.content;
 }