deepdebug-local-agent 1.5.0 → 1.7.0

package/docs/la-protocol-v2.md

@@ -50,34 +50,85 @@ 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#`, `.envrc`,
+  `.env_backup`, `.env-prod`, `env.production`), `*.pem`, `*.key`, `*.p12`, `*.kdbx`, `*.keystore`, `*.jks`, `id_rsa*`, `id_ed25519*`...,
+  `.npmrc`, `.pypirc`, `.netrc`, `kubeconfig*`, `secrets/`, `*.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`).
+  **Narrowed (F3-07c, Edu 2026-11-03): files that ARE credentials are blocked, code that merely mentions them is served.** A name with
+  `credential` (or `kubeconfig`) in it is served only when its LAST extension is source code or documentation (`ts`, `java`, `py`, `go`, `js`,
+  `kt`, `rb`, `cs`, `rs`, `php`, `sql`, `md`, `html`, `css`, ... `CODE_EXTENSIONS` in `path-guard.js`): `credentials.service.ts`,
+  `CredentialsController.java`, `credentials_test.py` are served; `credentials`, `.credentials`, `credentials.json|yml|xml|toml|ini|cfg|
+  conf|csv|txt|properties|db|sqlite|enc|pem|p12|pfx|kdbx|tfvars|env`, `application_default_credentials.json`, `*.credentials`, `aws/credentials`,
+  `gcloud/credentials.db` and anything unknown (`credentials.bak`, `credentials-prod`, `credentials.sh`) are not. A FOLDER named
+  `credentials` is fine (`src/credentials/`), but a file under it must be code too. The same rule tells `env.ts` / `env.d.ts` (served)
+  from `env.production` / `env_prod` / `env` (blocked). `secrets/` (any depth) is blocked whole, code included. The DLP (`enforce`, mandatory)
+  stays the second layer: whatever is served is masked. The table of >= 80 names is `test/la-protocol-v2/content-deny-list.test.js`.
+  `LOCAL_AGENT_CONTENT_DENY_GLOBS` adds to the list. No id is ever minted for them.
+- **`file.list` (F3-07c): the producer of the ids.** `content.request{kind:"file.list", ref}` lists ONE folder of a workspace (`ref` = `root` or a
+  folder id / `nextRef`; `limit` 1..1000, default 200; no range) and answers `application/json` `{entries:[{id, name, type, size, mtime}], nextRef?}`
+  (`file.list.body.schema.json` of the contract). The listing is the producer of the ids: each entry gets an id (43 chars, 15 min, bound to
+  tenant + workspace + root + kind; `file` for a file, `file.list` for a folder), minted through `mintRef`, so each id is announced in
+  `content.index` (`{kind, ref, size}`, no names). Left out, silently (not even a count): sensitive names, a link that leaves the root or
+  points to a secret, hard links, sockets/fifos/devices, names the contract cannot express, names the DLP withholds. Names are client
+  content: each name is masked by the DLP on its own (never the whole JSON, the ids would be masked by the high-entropy rule). `.gitignore` is
+  NOT consulted (a listing of the disk, not of git; the deny list is the control). One level per call, so no depth; a folder with more than
+  `LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES` (20000) entries is `payload_too_large` (never a partial listing); body <= min(`LOCAL_AGENT_CONTENT_MAX_BYTES`,
+  1 MiB), a page that does not fit ends with a `nextRef` (a folder id that remembers the position); order = dirs first, then names by UTF-8
+  bytes. Announced as capability `content.file.list` (the gateway sends `file.list` only to agents that announce it). Same flag
+  (`LOCAL_AGENT_CONTENT_HANDLERS`) and same mandatory DLP `enforce` as `file`/`diff`.
+- **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).
+  **Symlinks (F3-07c)**: the hunk of a tracked symlink prints the link TARGET (an absolute path of this machine), so entries with mode
+  `120000` on either side (`git diff --raw -z`) never reach the diff; names that are links on disk are skipped too, and as a last net
+  any block of the text whose header says `120000` is removed.
+  **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 +136,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
+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 176 frame vectors of F3-22, valid and invalid, the 54 `file.list` body vectors, 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), and for F3-07c `content-deny-list.test.js` (the narrowed deny list, >= 80 names), `content-file-list.test.js` (the listing, paging, links, DLP, index) and `content-diff-symlink.test.js`.
+Against the real gateway: `tools/interop` (`LaV2NodeContentInteropTest` straight into `LaV2Session`;
+`LaV2NodeContentRelayE2ETest`: HTTP -> `ContentRelayController` -> `LaV2Session` -> this agent, no patch on either side; `LaV2NodeFileListE2ETest` (F3-07c): the same chain starting from `file.list`, the agent mints no id by itself). 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,9 @@ 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/file.list 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)
+# LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES=20000  file.list: a folder with more entries is payload_too_large (100..200000)
+# LOCAL_AGENT_CONTENT_DENY_GLOBS=a/,*.x      extra deny globs (they add to the built-in list: .env*, keys, credentials files, secrets/ ...)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.5.0",
+  "version": "1.7.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

@@ -2,10 +2,11 @@
  * config.js - LOCAL_AGENT_CONTENT_HANDLERS flag and limits of the content.request handlers (F3-07).
  *
  *   false (default)  `content.request` keeps being acked `rejected protocol_unsupported`: nothing of this folder is loaded.
- *   true             handlers for `file` and `diff` are registered. Needs LOCAL_AGENT_PROTOCOL_V2=true as well
+ *   true             handlers for `file`, `diff` and `file.list` (F3-07c) 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";
@@ -40,9 +41,16 @@ export function resolveContentHandlersConfig(env = process.env, warn = console.w
         // the gateway gives a request 30 s in total (contract: contentTotalMs)
         totalMs: int(env.LOCAL_AGENT_CONTENT_TOTAL_MS, 25_000, 1_000, 30_000),
         gitTimeoutMs: int(env.LOCAL_AGENT_CONTENT_GIT_TIMEOUT_MS, 8_000, 500, 20_000),
+        // F3-07c: file.list reads at most this many entries of one folder; a bigger folder is payload_too_large (never a partial listing)
+        maxDirEntries: int(env.LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES, 20_000, 100, 200_000),
         maxDiffFiles: int(env.LOCAL_AGENT_CONTENT_MAX_DIFF_FILES, 500, 1, 5_000),
         // 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,196 @@
+/**
+ * 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. A frame that fails puts back ONLY ITS OWN entries (F3-07c: it used to wipe the queue, including
+ *             other workspaces' batches that had nothing to do with the failure); the rest of the queue is untouched.
+ *             rejected rate_limited = nothing of that frame was stored: back off (30 s, doubling to 5 min), then send the failed
+ *             batch again. rejected protocol_unsupported = this gateway keeps no index: the queue is useless, drop it and stop
+ *             until the next `ready`. rejected internal / timeout = send again after a short pause, at most MAX_ATTEMPTS times in
+ *             a row (then the batch is dropped and counted; the ids stay served, only not announced). Anything else (reset,
+ *             not_ready): the batch stays queued; the next `ready` announces again (a non-resumed one rebuilds the queue).
+ *   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;
+const MAX_ATTEMPTS = 5;
+
+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 queued = new Set();           // refs in `pending` (an id is queued once, whoever asks: add(), announce(), a retry)
+    let attempts = 0;                   // consecutive transient failures of the batch at the head
+    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 retryNotBefore = 0;   // no send before this time after a rate_limited answer, whoever asks (a listing mints up to 1000 ids)
+    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();
+        if (queued.has(e.ref)) return false;                      // already waiting to be sent
+        if (announced.size + queued.size >= 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);
+        queued.add(e.ref);
+        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;
+        // the failed batch is still in `pending`: sending again is a pump (announce() would also pick up what the gateway lost, but a
+        // retry after rate_limited/internal has nothing to rebuild)
+        retryTimer = unref(timers.setTimeout(() => { retryTimer = null; void pump(); }, 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
+        if (retryNotBefore > now()) {                                // rate limited: new ids wait inside the window, they do not restart it
+            scheduleRetry(retryNotBefore - now());
+            return Promise.resolve();
+        }
+        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;
+                if (list.length === 0) { pending.delete(workspaceId); continue; }
+                // the batch stays in `pending` until the gateway accepted it: a failure leaves it (and every other workspace) where it was
+                const batch = list.slice(0, MAX_PER_FRAME);
+                const entries = batch.map(({ kind, ref, size }) => ({ kind, ref, size }));
+                stats.frames++;
+                stats.entries += entries.length;
+                try {
+                    await session.send("content.index", { entries }, { workspaceId });
+                } catch (e) {
+                    const code = e instanceof ProtocolError ? e.code : "internal";
+                    stats.rejected += entries.length;
+                    stats.byCode[code] = (stats.byCode[code] || 0) + 1;
+                    if (code === "protocol_unsupported") {
+                        stopped = true;
+                        pending.clear(); queued.clear();         // this gateway keeps no index: nothing queued will ever be accepted
+                        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);
+                        retryNotBefore = now() + backoffMs;
+                        warn(`[la-content] content.index rate limited; announcing again in ${Math.round(backoffMs / 1000)} s`);
+                        scheduleRetry(backoffMs);
+                    } else if (code === "internal" || code === "timeout") {
+                        if (++attempts >= MAX_ATTEMPTS) {
+                            attempts = 0;
+                            discard(workspaceId, list, batch);
+                            stats.dropped += batch.length;
+                            warn(`[la-content] content.index not accepted (${code}); gave up on one batch after ${MAX_ATTEMPTS} attempts`);
+                            if (pending.size > 0) scheduleRetry(RETRY_MS);
+                        } else {
+                            warn(`[la-content] content.index not accepted (${code}); trying again shortly`);
+                            scheduleRetry(RETRY_MS);
+                        }
+                    }
+                    // other codes (not_ready, agent_offline, session reset): the batch stays queued; the next ready announces again
+                    return;
+                }
+                attempts = 0;
+                stats.accepted += entries.length;
+                for (const b of batch) announced.set(b.ref, b.expiresAt);
+                discard(workspaceId, list, batch);
+            }
+            backoffMs = 0;
+            retryNotBefore = 0;
+        } catch { /* nothing here may throw into the data path */ }
+    }
+
+    /** Takes a sent (or abandoned) batch out of the queue, unless a new `ready` already replaced the queue meanwhile. */
+    function discard(workspaceId, list, batch) {
+        if (pending.get(workspaceId) !== list) return;
+        for (const b of batch) queued.delete(b.ref);
+        list.splice(0, batch.length);
+        if (list.length === 0) pending.delete(workspaceId);
+    }
+
+    /** 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;
+        retryNotBefore = 0;
+        if (!info || !info.resumed) { announced.clear(); pending.clear(); queued.clear(); attempts = 0; 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() { return queued.size; },
+        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();
+            queued.clear();
+            session.off("ready", onReady);
+        },
+    };
+}

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

@@ -33,6 +33,28 @@ export function contentTypeOf(rel, isText) {
     return t === "application/zip" ? t : "application/octet-stream";
 }
 
+/**
+ * DLP of ONE file name (F3-07c, file.list): the same engine and configuration as for content, applied to each name on its own so a
+ * mask can never reach across the JSON of a listing. In enforce a hit is replaced by [REDACTED:<rule>]; a hit in
+ * LOCAL_AGENT_DLP_BLOCK_CLASSES withholds the entry (`blocked`); a DLP failure is `denied` (the whole listing fails closed).
+ * @returns {{name:string, blocked:boolean, denied:boolean, total:number, redactions:object}}
+ */
+export function maskName(name, { env = process.env, source = "content.file.list" } = {}) {
+    const cfg = dlpConfigFromEnv(env);
+    if (cfg.mode !== "enforce") return { name: "", blocked: false, denied: true, total: 0, redactions: {} }; // never list unmasked
+    if (name.length > cfg.maxBytes) return { name: "", blocked: true, denied: false, total: 0, redactions: {} };
+    const res = protectEgress(name, { env, source });
+    if (res.denied || res.text === DENIED || res.text === OVERSIZE) return { name: "", blocked: false, denied: true, total: 0, redactions: {} };
+    return { name: res.text, blocked: !!res.blocked, denied: false, total: res.total, redactions: res.redactions };
+}
+
+/** A listing body the agent built itself (ids, sizes, times are not client content; the names were masked one by one). */
+export function prepareList({ buffer, maxBytes, dlp }) {
+    const cfg = dlp || { mode: "enforce", total: 0, redactions: {} };
+    if (buffer.length > maxBytes) return { ok: false, status: "error", errorCode: "payload_too_large", dlp: cfg };
+    return { ok: true, buffer, contentType: "application/json", dlp: cfg };
+}
+
 /**
  * @param {{buffer:Buffer, contentType?:string, range?:{offset:number,length:number}, maxBytes:number, env?:object, source:string}} o
  * @returns {{ok:true, buffer:Buffer, contentType:string, dlp:{mode:string,total:number,redactions:object}} |

package/src/la-protocol-v2/content-handlers/file-list.js

@@ -0,0 +1,174 @@
+/**
+ * file-list.js - `file.list` kind: ONE folder of a workspace, one page at a time (F3-07c). This is the producer of the opaque ids:
+ * every entry it hands out carries an id minted here (43 chars, bound to tenant + workspace + root + kind, 15 min), which is how the
+ * front asks for the file (`file`) or the sub folder (`file.list`) later. Before this nothing in the agent minted a `file` id.
+ *
+ * What is listed (the same rules as for serving, applied before anything is minted or named):
+ *   - the folder: realpath inside the root, not sensitive under its logical OR its real name, a directory. `root` = the workspace root.
+ *   - an entry is left out, silently (its name never leaves, nor a count of them): sensitive name (deny list, `dir` rules for folders),
+ *     a name the schema cannot express (control chars, `/`, > 255, invalid UTF-8), anything that is not a regular file or a folder
+ *     (socket, fifo, device), a symlink whose real target is outside the root / sensitive / not a file or folder / unreadable,
+ *     a hard-linked file (unless LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS), and a name that the DLP withholds (blocked class).
+ *   - the DLP masks every name on its own (never the whole JSON: the ids are random 43-char strings and the high-entropy rule would
+ *     mask them). The ids, sizes and times are produced here, they are not client content.
+ *   - .gitignore is NOT consulted: this is a listing of what is on the disk, not of what git tracks; the deny list is the control, an
+ *     ignored file is served as any other one (build output, logs, local notes), `.git/` and the secret files stay denied. It also
+ *     avoids a process per request.
+ * Bounds: one level per call (no recursion, so no depth to run away), at most `maxDirEntries` entries read from the folder (more =
+ * `payload_too_large`, deterministic, never "the first N the disk happened to return"), `limit` entries per page (<= 1000), the body
+ * <= min(maxBytes, 1 MiB) (the gateway refuses a bigger listing), time = the request deadline (`signal`).
+ * Paging: order is dirs first, then names by UTF-8 bytes (= code point order). A page that ends before the folder does carries
+ * `nextRef`, a folder id that remembers where to continue (the position stays here; the id is the cursor).
+ * Nothing here logs, and no path or name is part of any error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isSensitivePath } from "./path-guard.js";
+
+export const ROOT_REF = "root";
+export const MAX_LIST_BYTES = 1024 * 1024; // the gateway refuses a listing body above this (too_large)
+const DEFAULT_LIMIT = 200;
+const NAME_BAD = /[\u0000-\u001f\u007f/\ufffd]/;
+
+const inside = (root, abs) => abs === root || abs.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+const toPosix = (p) => p.split(path.sep).join("/");
+const byteCmp = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+/** dirs first, then by name bytes */
+const order = (a, b) => (a.dir === b.dir ? byteCmp(a.name, b.name) : a.dir ? -1 : 1);
+
+export function clampLimit(limit) {
+    return Number.isSafeInteger(limit) && limit >= 1 && limit <= 1000 ? limit : DEFAULT_LIMIT;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.root           workspace root as registered
+ * @param {string|null} o.rel       folder relative to the root (null = the root); already normalized by the caller (normalizeRel)
+ * @param {{dir:boolean,name:string}|null} [o.after]  continue after this entry
+ * @param {number} o.limit
+ * @param {number} o.maxBytes       the body may not exceed min(this, 1 MiB)
+ * @param {number} o.maxDirEntries
+ * @param {string[]} [o.denyGlobs]
+ * @param {boolean} [o.allowHardlinks]
+ * @param {AbortSignal} [o.signal]
+ * @param {(o:{kind:"file"|"file.list", rel:string|null, size:number, after?:object}) => ({id:string}|null)} o.mint
+ * @param {(name:string) => ({name:string, blocked:boolean, denied:boolean, total:number, redactions:object})} o.maskName
+ * @returns {Promise<{ok:true, body:Buffer, entries:number, dlp:{total:number, redactions:object}} |
+ *                   {ok:false, status:"not_found"|"forbidden"|"error", errorCode?:string}>}
+ */
+export async function listFolder({ root, rel = null, after = null, limit, maxBytes, maxDirEntries, denyGlobs = [], allowHardlinks = false, signal, mint, maskName }) {
+    let rootReal;
+    try { rootReal = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
+
+    // 1. the folder
+    let dirReal = rootReal;
+    let dirRel = "";
+    if (rel) {
+        if (isSensitivePath(rel, denyGlobs, { dir: true })) return { ok: false, status: "forbidden" };
+        const abs = path.join(rootReal, ...rel.split("/"));
+        if (!inside(rootReal, abs)) return { ok: false, status: "forbidden" };
+        try { dirReal = await fs.promises.realpath(abs); } catch (e) { return { ok: false, status: e && (e.code === "EACCES" || e.code === "EPERM") ? "forbidden" : "not_found" }; }
+        if (!inside(rootReal, dirReal)) return { ok: false, status: "forbidden" };       // a folder link that leaves the workspace
+        dirRel = toPosix(path.relative(rootReal, dirReal));
+        if (dirRel && isSensitivePath(dirRel, denyGlobs, { dir: true })) return { ok: false, status: "forbidden" }; // a link to a sensitive folder
+    }
+    try { if (!(await fs.promises.stat(dirReal)).isDirectory()) return { ok: false, status: "not_found" }; } catch { return { ok: false, status: "not_found" }; }
+
+    // 2. read the folder (bounded) and keep what may be shown, by name alone: no further I/O yet
+    const cands = [];
+    let seen = 0;
+    try {
+        const d = await fs.promises.opendir(dirReal);
+        try {
+            for await (const ent of d) {
+                if (++seen > maxDirEntries) return { ok: false, status: "error", errorCode: "payload_too_large" };
+                if (signal && signal.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+                const name = ent.name;
+                if (typeof name !== "string" || name.length === 0 || name.length > 255 || NAME_BAD.test(name) || name === "." || name === "..") continue;
+                const childRel = dirRel ? `${dirRel}/${name}` : name;
+                cands.push({ name, childRel, dirent: ent });
+            }
+        } finally { await d.close().catch(() => {}); }
+    } catch (e) {
+        return { ok: false, status: e && (e.code === "EACCES" || e.code === "EPERM") ? "forbidden" : "not_found" };
+    }
+
+    // 3. classify (a symlink is judged by where it really leads), still without reading anything
+    const kept = [];
+    let n = 0;
+    for (const c of cands) {
+        if ((++n & 63) === 0 && signal && signal.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+        const e = c.dirent;
+        let dir;
+        let link = false;
+        if (e.isDirectory()) dir = true;
+        else if (e.isFile()) dir = false;
+        else if (e.isSymbolicLink()) { link = true; }
+        else if (e.isBlockDevice() || e.isCharacterDevice() || e.isFIFO() || e.isSocket()) continue;
+        else { // the file system did not say (DT_UNKNOWN)
+            try { const st = await fs.promises.lstat(path.join(dirReal, c.name)); dir = st.isDirectory(); if (!dir && !st.isFile()) { if (!st.isSymbolicLink()) continue; link = true; } } catch { continue; }
+        }
+        if (!link && isSensitivePath(c.childRel, denyGlobs, { dir })) continue;
+        if (link) {
+            try {
+                const real = await fs.promises.realpath(path.join(dirReal, c.name));
+                if (!inside(rootReal, real) || real === rootReal) continue;
+                const st = await fs.promises.stat(real);
+                dir = st.isDirectory();
+                if (!dir && !st.isFile()) continue;
+                const relReal = toPosix(path.relative(rootReal, real));
+                if (isSensitivePath(c.childRel, denyGlobs, { dir }) || isSensitivePath(relReal, denyGlobs, { dir })) continue; // a harmless name that is a link to a secret
+                c.real = real;
+                c.relReal = relReal;
+            } catch { continue; }
+        }
+        c.dir = dir;
+        kept.push(c);
+    }
+    kept.sort(order);
+
+    // 4. one page: skip what the previous page already showed, then take entries until the page is full
+    const budget = Math.max(1024, Math.min(maxBytes, MAX_LIST_BYTES) - 4096); // room for the envelope of the JSON and for `nextRef`
+    let i = 0;
+    if (after) while (i < kept.length && order(kept[i], { dir: after.dir, name: after.name }) <= 0) i++;
+    const entries = [];
+    let bytes = 2 + 11 + 3 + 52; // {"entries":[]} + room
+    const dlp = { total: 0, redactions: {} };
+    let last = null;
+    let more = false;
+    for (; i < kept.length; i++) {
+        if (entries.length >= limit) { more = true; break; }
+        if ((i & 31) === 0 && signal && signal.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+        const c = kept[i];
+        const target = c.real || path.join(dirReal, c.name);
+        let st;
+        try { st = await fs.promises.lstat(target); } catch { continue; }
+        if (c.dir ? !st.isDirectory() : !st.isFile()) continue;                           // changed under our feet
+        if (!c.dir && st.nlink > 1 && !allowHardlinks) continue;                          // may be a second name of a file outside the root
+        const masked = maskName(c.name);
+        if (masked.denied) return { ok: false, status: "error", errorCode: "internal" };
+        if (masked.blocked || !masked.name || masked.name.length > 255 || NAME_BAD.test(masked.name)) continue;
+        const size = c.dir ? 0 : Math.min(st.size, 2 ** 40);
+        const mtime = new Date(Number.isFinite(st.mtimeMs) ? Math.min(Math.max(st.mtimeMs, 0), 4_102_444_800_000) : 0).toISOString();
+        // measured BEFORE minting: an entry that does not fit must not leave an id behind
+        const len = Buffer.byteLength(JSON.stringify({ id: "A".repeat(43), name: masked.name, type: c.dir ? "dir" : "file", size, mtime })) + 1;
+        if (entries.length > 0 && bytes + len > budget) { more = true; break; }
+        const minted = mint({ kind: c.dir ? "file.list" : "file", rel: c.relReal || c.childRel, size });
+        if (!minted) continue;
+        const entry = { id: minted.id, name: masked.name, type: c.dir ? "dir" : "file", size, mtime };
+        bytes += len;
+        entries.push(entry);
+        last = { dir: c.dir, name: c.name };
+        dlp.total += masked.total;
+        for (const [k, v] of Object.entries(masked.redactions || {})) dlp.redactions[k] = (dlp.redactions[k] || 0) + v;
+    }
+
+    // 5. continuation: only when there is more to show after the last entry given
+    const body = { entries };
+    if (more && last) {
+        const next = mint({ kind: "file.list", rel: dirRel || null, size: 0, after: last });
+        if (!next) return { ok: false, status: "error", errorCode: "internal" };
+        body.nextRef = next.id;
+    }
+    return { ok: true, body: Buffer.from(JSON.stringify(body), "utf8"), entries: entries.length, dlp };
+}