deepdebug-local-agent 1.6.0 → 1.7.0

package/docs/la-protocol-v2.md

@@ -78,11 +78,32 @@ start-up. The mode is also read at each request: leaving `enforce` at run time s
   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*` (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.
+  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`
@@ -97,6 +118,9 @@ start-up. The mode is also read at each request: leaving `enforce` at run time s
   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
@@ -112,20 +136,20 @@ start-up. The mode is also read at each request: leaving `enforce` at run time s
 ## What it does NOT do
 
 No handler for the other kinds (`incident.*`, `log.*`, `chat.session`, `wiki.page`, `job.*`, `approval.detail`, `report`),
-nothing in the agent calls `mintRef` yet (the producer of the file/diff inventory is a later increment), 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 168 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 26
+`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`), and for F3-07b
-`content-alignment.test.js` (43-char ids and `worktree`, `content.index`, throwing producers, hard links, deny list, git filters).
+`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). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
+`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,7 +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 over protocol v2 (needs LOCAL_AGENT_PROTOCOL_V2=true AND
+# 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.6.0",
+  "version": "1.7.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

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

@@ -2,7 +2,7 @@
  * 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).
  *
  * Even when true, the handlers are registered only with LOCAL_AGENT_DLP_MODE=enforce (F3-07b, runtime.js): there is no
@@ -41,6 +41,8 @@ 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),

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

@@ -10,10 +10,13 @@
  *   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.
+ *   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";
@@ -22,15 +25,19 @@ 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: {} };
 
@@ -45,12 +52,12 @@ export function createContentIndexer({ session, registry, config, log = console,
     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; }
+        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;
     }
@@ -62,13 +69,19 @@ export function createContentIndexer({ session, registry, config, log = console,
 
     function scheduleRetry(ms) {
         if (closed || retryTimer) return;
-        retryTimer = unref(timers.setTimeout(() => { retryTimer = null; announce(); }, ms));
+        // 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;
     }
@@ -79,40 +92,60 @@ export function createContentIndexer({ session, registry, config, log = console,
                 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;
+                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 });
-                    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;
+                        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") {
-                        warn(`[la-content] content.index not accepted (${code}); trying again shortly`);
-                        scheduleRetry(RETRY_MS);
+                        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 next ready announces again
+                    // 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;
@@ -131,7 +164,8 @@ export function createContentIndexer({ session, registry, config, log = console,
     const onReady = (info) => {
         stopped = false;
         backoffMs = 0;
-        if (!info || !info.resumed) { announced.clear(); pending.clear(); announce(); }
+        retryNotBefore = 0;
+        if (!info || !info.resumed) { announced.clear(); pending.clear(); queued.clear(); attempts = 0; announce(); }
         else void pump();
     };
     session.on("ready", onReady);
@@ -145,7 +179,7 @@ export function createContentIndexer({ session, registry, config, log = console,
             return ok;
         },
         announce,
-        get pending() { let n = 0; for (const l of pending.values()) n += l.length; return n; },
+        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; },
@@ -155,6 +189,7 @@ export function createContentIndexer({ session, registry, config, log = console,
             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 };
+}

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

@@ -16,6 +16,11 @@
  * 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.
+ *
+ * Symlinks (F3-07c). The hunk of a tracked symlink ("new file mode 120000", "+/abs/target") prints the TARGET of the link, i.e. an
+ * absolute path on this machine. Entries whose mode is 120000 on either side (git diff --raw: a link added, changed, removed, or a file
+ * replaced by a link and the other way round) never reach the second call; the names are also lstat-ed (a file turned into a link in
+ * between) and, as a last net, `dropSymlinkBlocks()` removes from the text any per-file block whose header says 120000.
  */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
@@ -107,7 +112,7 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     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 listArgs = [...safe, "diff", "--raw", "-z", "--no-abbrev", "--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" };
@@ -115,10 +120,11 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     if (listed.code !== 0) return { ok: false, status: "not_found" }; // not a repository, no HEAD yet, unsafe directory...
     const names = [];
     let argBytes = 0;
-    for (const n of listed.out.toString("utf8").split("\0")) {
-        const norm = n ? normalizeRel(n) : null;
+    for (const n of rawPaths(listed.out.toString("utf8"))) {
+        if (n.symlink) continue;                                           // the hunk would print the target of the link
+        const norm = n.path ? normalizeRel(n.path) : 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
+        if (await isLinkOnDisk(cwd, norm, allowHardlinks)) continue;       // a link (or a hard link) now, whatever git remembers
         argBytes += Buffer.byteLength(norm) + 1;
         if (names.length >= maxFiles || argBytes > 128 * 1024) break;
         names.push(norm);
@@ -130,13 +136,42 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     if (diff.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
     if (diff.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
     if (diff.code !== 0) return { ok: false, status: "error", errorCode: "internal" };
-    return { ok: true, text: diff.out.toString("utf8") };
+    return { ok: true, text: dropSymlinkBlocks(diff.out.toString("utf8")) };
+}
+
+/**
+ * `git diff --raw -z` -> [{path, symlink}]: ":<oldmode> <newmode> <oldsha> <newsha> <status>\0<path>\0" per entry (no renames: one path).
+ * @returns {{path:string, symlink:boolean}[]}
+ */
+export function rawPaths(out) {
+    const parts = out.split("\0");
+    const res = [];
+    for (let i = 0; i < parts.length; i++) {
+        const meta = parts[i];
+        if (!meta.startsWith(":")) continue;
+        const f = meta.slice(1).split(" ");
+        const p = parts[i + 1];
+        i++;
+        if (typeof p !== "string") break;
+        res.push({ path: p, symlink: f[0] === "120000" || f[1] === "120000" });
+    }
+    return res;
+}
+
+/** Removes the per-file blocks of a diff whose header (up to the first hunk) names mode 120000 (a symlink): they print the link target. */
+export function dropSymlinkBlocks(text) {
+    if (!text.includes("120000")) return text;
+    const blocks = text.split(/^(?=diff --git )/m);
+    return blocks.filter((b) => {
+        const head = b.split(/^@@/m, 1)[0];
+        return !/^(?:(?:new file|deleted file|old|new) mode 120000|index [0-9a-f]+\.\.[0-9a-f]+ 120000)\s*$/m.test(head);
+    }).join("");
 }
 
-/** 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) {
+/** True for a symlink, or (unless allowed) a regular file with more than one link. A name that no longer exists (a deletion) is neither. */
+async function isLinkOnDisk(cwd, rel, allowHardlinks) {
     try {
         const st = await fs.promises.lstat(path.join(cwd, ...rel.split("/")));
-        return st.isFile() && st.nlink > 1;
+        return st.isSymbolicLink() || (!allowHardlinks && st.isFile() && st.nlink > 1);
     } catch { return false; }
 }