deepdebug-local-agent 1.6.0 → 1.8.0

package/src/incident-detector/store.js

@@ -0,0 +1,119 @@
+/**
+ * store.js - the local detail store of detected errors (F3-11b). The TEXT of an error (message, stack trace) lives here and
+ * nowhere else: the control plane only ever gets metadata.
+ *
+ *   file        <storeDir>/incident-detail.jsonl, one JSON object per line, dir 0700 / file 0600, append only
+ *   rotation    at storeMaxBytes the file moves to incident-detail.jsonl.1 (one generation): disk use <= 2 x storeMaxBytes
+ *   record      {v, ts, errorHash, fingerprint, service, severity, windowStart, message, stack, stackBytes, truncated}
+ *               message/stack are masked by the DLP (when DLP is on) and cut to storeMessageChars/storeStackChars
+ *   sampling    samplesPerWindow records per errorHash and window (the count is in the candidate, not in this file)
+ *   queue       at most storeMaxQueue writes waiting; add() resolves when the record is queued OR dropped (never blocks the caller
+ *               for more than the queue allows: when full it waits for room, which slows the reading of the sources = backpressure)
+ *   getDetail   (errorHash, {limit}) reads the newest records back: this is the hook for `content.request` kind `incident.detail`
+ *               (F3-07 handler, NOT wired here: the contract/gateway kind and its ref scheme are not defined yet, see README.md)
+ *   never       logs a path, a message or a stack: counters only. A broken disk disables the store, not the detector.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { protectEgress } from "../dlp/index.js";
+
+const FILE = "incident-detail.jsonl";
+const cut = (s, n) => (typeof s === "string" && s.length > n ? s.slice(0, n) : s);
+
+export function createDetailStore({ dir, maxBytes, maxQueue, messageChars, stackChars, samplesPerWindow, env = process.env, now = Date.now }) {
+    const file = path.join(dir, FILE);
+    const stats = { written: 0, sampledOut: 0, dropped: 0, errors: 0, rotations: 0, redactions: 0, dlpDenied: 0 };
+    const samples = new Map();   // `${errorHash}|${windowStart}` -> records written
+    let queue = [];
+    let size = null;
+    let broken = false;
+    let writing = null;
+    let waiters = [];
+
+    async function ensure() {
+        if (size !== null) return;
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        size = await fs.promises.stat(file).then((s) => s.size, () => 0);
+    }
+
+    async function drain() {
+        try {
+            await ensure();
+            while (queue.length) {
+                const batch = queue;
+                queue = [];
+                const lines = batch.map((r) => JSON.stringify(r) + "\n");
+                const bytes = lines.reduce((n, l) => n + Buffer.byteLength(l), 0);
+                if (size > 0 && size + bytes > maxBytes) {
+                    await fs.promises.rename(file, `${file}.1`).catch(() => {});
+                    size = 0;
+                    stats.rotations++;
+                }
+                await fs.promises.appendFile(file, lines.join(""), { mode: 0o600 });
+                size += bytes;
+                stats.written += batch.length;
+                const w = waiters; waiters = []; for (const f of w) f();
+            }
+        } catch {
+            broken = true;      // disk full, permissions...: the detector keeps going without a store
+            stats.errors++;
+            stats.dropped += queue.length;
+            queue = [];
+        } finally {
+            writing = null;
+            const w = waiters; waiters = []; for (const f of w) f();
+        }
+    }
+
+    const mask = (text) => {
+        if (typeof text !== "string" || text === "") return text;
+        const r = protectEgress(text, { env, source: "incident-store" });
+        if (r.denied) { stats.dlpDenied++; return "[DLP_DENIED]"; }
+        if (r.total) stats.redactions += r.total;
+        return r.text;
+    };
+
+    return {
+        stats,
+        get broken() { return broken; },
+        get queued() { return queue.length; },
+        /** @returns {Promise<boolean>} true = queued. */
+        async add({ errorHash, fingerprint, service, severity, windowStart, message, stack }) {
+            if (broken) { stats.dropped++; return false; }
+            const key = `${errorHash}|${windowStart}`;
+            const n = samples.get(key) || 0;
+            if (n >= samplesPerWindow) { stats.sampledOut++; return false; }
+            if (samples.size > 50_000) samples.clear();   // bounded: a reset only lets a few extra samples through
+            samples.set(key, n + 1);
+            while (queue.length >= maxQueue && !broken) await new Promise((res) => { waiters.push(res); if (!writing) writing = drain(); });
+            if (broken) { stats.dropped++; return false; }
+            const m = typeof message === "string" ? message : "";
+            const st = typeof stack === "string" ? stack : "";
+            queue.push({
+                v: 1, ts: new Date(now()).toISOString(), errorHash, fingerprint, service, severity, windowStart,
+                message: mask(cut(m, messageChars)), stack: st ? mask(cut(st, stackChars)) : null,
+                stackBytes: Buffer.byteLength(st), truncated: m.length > messageChars || st.length > stackChars,
+            });
+            if (!writing) writing = drain();
+            return true;
+        },
+        /** Newest first. Reads both generations; a bad line is skipped. */
+        async getDetail(errorHash, { limit = 5 } = {}) {
+            if (writing) await writing;
+            const out = [];
+            for (const f of [file, `${file}.1`]) {
+                let text;
+                try { text = await fs.promises.readFile(f, "utf8"); } catch { continue; }
+                const lines = text.split("\n");
+                for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+                    if (!lines[i].includes(errorHash)) continue;
+                    try { const r = JSON.parse(lines[i]); if (r.errorHash === errorHash) out.push(r); } catch { /* skip */ }
+                }
+                if (out.length >= limit) break;
+            }
+            return out;
+        },
+        /** Waits until everything queued is on disk (tests, shutdown). */
+        async flush() { if (!writing && queue.length) writing = drain(); if (writing) await writing; },
+    };
+}

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; }
 }