@aexol/spectral 0.9.245 → 0.9.247

package/dist/secrets/store.js

@@ -0,0 +1,415 @@
+/**
+ * Local encrypted secret store.
+ *
+ * Storage layout (both files under `getConfigDir()`, honoring
+ * `SPECTRAL_CONFIG_DIR` for tests):
+ *  - `<configDir>/secrets.key`      32 random bytes, mode 0600 — AES-256 key
+ *  - `<configDir>/secrets.json.enc` AES-256-GCM encrypted JSON, mode 0600
+ *
+ * Encrypted file layout:
+ *  - bytes 0-7:   magic `"SPSECRT1"` (format tag)
+ *  - bytes 8-19:  12-byte random IV
+ *  - bytes 20-35: 16-byte GCM auth tag
+ *  - bytes 36+:   ciphertext (UTF-8 JSON)
+ *
+ * Security rules enforced here and by this module's consumers:
+ *  - `listSecrets()` returns ONLY `{ name, createdAt, updatedAt }` — values are
+ *    never part of any listing.
+ *  - `getSecretValue()` is INTERNAL: it is consumed only by
+ *    `getSecretEnvVars()` (env-var injection into the agent's bash tool). It
+ *    is deliberately NOT re-exported from `./index.js`, so neither the relay
+ *    handlers nor the LLM-facing tool surface can reach it.
+ *  - No caller ever logs a value; error messages and listings carry names only.
+ *
+ * All I/O is synchronous by design: `getSecretEnvVars()` must be callable from
+ * the sync `getShellEnv()` in `src/sdk/coding-agent/utils/shell.ts`. The store
+ * is tiny (values are capped at 64 KiB each), so sync reads are negligible.
+ *
+ * Keep this module zero-side-effect on import: nothing touches the filesystem
+ * until one of the exported functions is called.
+ */
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { getConfigDir } from "../config.js";
+/** Secret names: start with a letter, then letters/digits/underscores, max 64 chars. */
+export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** Maximum UTF-8 byte size of a secret value (64 KiB). */
+export const MAX_SECRET_VALUE_BYTES = 64 * 1024;
+/** 8-byte format tag at the head of the encrypted store. */
+const MAGIC = Buffer.from("SPSECRT1", "utf8");
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+/** Thrown when a secret name is missing/invalid after normalization. */
+export class SecretNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecretNameError";
+    }
+}
+/** Thrown when a secret value exceeds `MAX_SECRET_VALUE_BYTES`. */
+export class SecretValueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecretValueError";
+    }
+}
+/** Thrown when the encrypted store is unreadable, corrupt, or key-mismatched. */
+export class SecretStoreCorruptError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecretStoreCorruptError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+/** Path to the AES-256 key file (32 random bytes). Lazily computed — see `getConfigDir`. */
+export function getSecretKeyPath() {
+    return join(getConfigDir(), "secrets.key");
+}
+/** Path to the AES-256-GCM encrypted store. Lazily computed — see `getConfigDir`. */
+export function getSecretDataPath() {
+    return join(getConfigDir(), "secrets.json.enc");
+}
+// ---------------------------------------------------------------------------
+// Validation / normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a secret name per the shared contract: trim surrounding
+ * whitespace, uppercase, then validate against `SECRET_NAME_PATTERN`.
+ * Throws `SecretNameError` with a generic message — the offending raw input
+ * is never echoed back, so it can't leak into logs.
+ */
+export function normalizeSecretName(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        throw new SecretNameError("Secret name is required");
+    }
+    const name = raw.trim().toUpperCase();
+    if (!SECRET_NAME_PATTERN.test(name)) {
+        throw new SecretNameError("Invalid secret name: must start with a letter, contain only letters, digits and underscores, max 64 characters (pattern ^[A-Z][A-Z0-9_]{0,63}$)");
+    }
+    return name;
+}
+function assertValueSize(value) {
+    if (typeof value !== "string") {
+        throw new SecretValueError("Secret value must be a string");
+    }
+    if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
+        throw new SecretValueError(`Secret value too large: max ${MAX_SECRET_VALUE_BYTES} bytes (64 KiB)`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Crypto + file I/O
+// ---------------------------------------------------------------------------
+function encrypt(data, key) {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ciphertext = Buffer.concat([cipher.update(data, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([MAGIC, iv, tag, ciphertext]);
+}
+function decrypt(buf, key) {
+    if (buf.length < MAGIC.length + IV_LENGTH + TAG_LENGTH ||
+        !buf.subarray(0, MAGIC.length).equals(MAGIC)) {
+        throw new SecretStoreCorruptError("Unrecognized secret store format");
+    }
+    const iv = buf.subarray(MAGIC.length, MAGIC.length + IV_LENGTH);
+    const tag = buf.subarray(MAGIC.length + IV_LENGTH, MAGIC.length + IV_LENGTH + TAG_LENGTH);
+    const ciphertext = buf.subarray(MAGIC.length + IV_LENGTH + TAG_LENGTH);
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    }
+    catch {
+        throw new SecretStoreCorruptError("Secret store is corrupt or was encrypted with a different key");
+    }
+}
+/**
+ * Read the EXISTING key file. Throws `SecretStoreCorruptError` when the key
+ * is missing or has the wrong size. Deliberately NEVER generates a key: key
+ * generation happens on write paths only (`ensureSecretKey`), so a read
+ * against encrypted data without a key surfaces the lost-key state instead of
+ * silently minting a fresh key that can never decrypt the store.
+ */
+function readSecretKey() {
+    const keyPath = getSecretKeyPath();
+    let key;
+    try {
+        key = readFileSync(keyPath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new SecretStoreCorruptError("Secrets key file is missing but encrypted data exists: restore secrets.key or delete the store and re-enter your secrets");
+        }
+        throw new SecretStoreCorruptError(`Cannot read secrets key: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (key.length !== KEY_LENGTH) {
+        throw new SecretStoreCorruptError(`Secrets key file is corrupt (expected ${KEY_LENGTH} bytes): delete it and re-enter your secrets`);
+    }
+    return key;
+}
+/**
+ * Return the AES-256 key, generating a new one ONLY when the key file does
+ * not exist yet (write paths). An existing key with loose permissions is
+ * tightened back to 0600 (defense-in-depth).
+ */
+function ensureSecretKey() {
+    const keyPath = getSecretKeyPath();
+    mkdirSync(dirname(keyPath), { recursive: true, mode: 0o700 });
+    if (existsSync(keyPath)) {
+        try {
+            chmodSync(keyPath, 0o600);
+        }
+        catch {
+            // Best-effort: some filesystems do not support chmod.
+        }
+        return readSecretKey();
+    }
+    const key = randomBytes(KEY_LENGTH);
+    writeFileSync(keyPath, key, { mode: 0o600 });
+    return key;
+}
+function emptyStoreData() {
+    return { version: 1, secrets: {} };
+}
+/** Read + decrypt the store. Returns an empty store when the file is missing. Throws on corruption. */
+function readStoreData() {
+    const dataPath = getSecretDataPath();
+    if (!existsSync(dataPath))
+        return emptyStoreData();
+    let raw;
+    try {
+        raw = readFileSync(dataPath);
+    }
+    catch (err) {
+        throw new SecretStoreCorruptError(`Cannot read secret store: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // The read path NEVER generates a key: encrypted data without a key is a
+    // lost-key state, and minting a fresh key here would mask it (and touch
+    // the filesystem as a side effect of a read). Keys are generated on write
+    // paths only (ensureSecretKey via writeStoreData).
+    const key = readSecretKey();
+    const json = decrypt(raw, key);
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed.version !== 1 || typeof parsed.secrets !== "object" || parsed.secrets === null) {
+            throw new SecretStoreCorruptError("Unrecognized secret store payload");
+        }
+        return { version: 1, secrets: parsed.secrets };
+    }
+    catch (err) {
+        if (err instanceof SecretStoreCorruptError)
+            throw err;
+        throw new SecretStoreCorruptError("Unrecognized secret store payload");
+    }
+}
+/** Orphaned `.tmp-*` files older than this are removed on the next write. */
+const STALE_TMP_MS = 60_000;
+/**
+ * Remove orphaned `secrets.json.enc.tmp-*` files left behind by crashed
+ * writers. Only files older than `STALE_TMP_MS` are removed so a concurrent
+ * process's in-flight write (tmp file created moments ago) is never deleted.
+ */
+function cleanupStaleTmpFiles(dataPath) {
+    let entries;
+    try {
+        entries = readdirSync(dirname(dataPath));
+    }
+    catch {
+        return;
+    }
+    const prefix = `${basename(dataPath)}.tmp-`;
+    const cutoff = Date.now() - STALE_TMP_MS;
+    for (const entry of entries) {
+        if (!entry.startsWith(prefix))
+            continue;
+        const full = join(dirname(dataPath), entry);
+        try {
+            if (statSync(full).mtimeMs < cutoff)
+                unlinkSync(full);
+        }
+        catch {
+            // Ignore: the file vanished (another writer renamed it away).
+        }
+    }
+}
+/** Encrypt + atomically write the store (tmp file + rename), mode 0600. */
+function writeStoreData(data) {
+    const dataPath = getSecretDataPath();
+    const key = ensureSecretKey();
+    const payload = encrypt(JSON.stringify(data), key);
+    // Unique per-request tmp name: pid alone is shared by every write this
+    // process makes, so a crashed write would make the next write silently
+    // reuse (and clobber) the orphan. A random hex suffix makes collisions
+    // between concurrent writers practically impossible.
+    const tmpPath = `${dataPath}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+    writeFileSync(tmpPath, payload, { mode: 0o600 });
+    try {
+        renameSync(tmpPath, dataPath);
+    }
+    catch (err) {
+        // Best-effort: remove this request's tmp file so failed writes cannot
+        // accumulate orphans.
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // Already gone.
+        }
+        throw err;
+    }
+    // Defense-in-depth: a pre-existing file with loose permissions gets tightened.
+    chmodSync(dataPath, 0o600);
+    cleanupStaleTmpFiles(dataPath);
+}
+// ---------------------------------------------------------------------------
+// mtime-cached env injection
+// ---------------------------------------------------------------------------
+/**
+ * Cache keyed on the data file's `mtimeMs:size` so external writes (other CLI
+ * processes, the relay API) invalidate it without a restart. Our own write
+ * path (`setSecret`/`deleteSecret`) refreshes the cache explicitly, covering
+ * same-millisecond writes where the mtime would not change.
+ */
+let envCache = null;
+function dataFileCacheKey() {
+    try {
+        const data = statSync(getSecretDataPath());
+        const key = statSync(getSecretKeyPath());
+        return `${data.mtimeMs}:${data.size}:${key.mtimeMs}:${key.size}`;
+    }
+    catch {
+        return null;
+    }
+}
+function refreshEnvCache() {
+    const cacheKey = dataFileCacheKey();
+    const data = readStoreData();
+    // PATH is reserved: a secret named PATH would override the shell PATH that
+    // getShellEnv() deliberately rebuilds (bin dir injection) and break the
+    // bash tool. Stored under that name, it is ignored for env injection only.
+    const env = {};
+    for (const [name, record] of Object.entries(data.secrets)) {
+        if (name.toLowerCase() === "path")
+            continue;
+        env[name] = record.value;
+    }
+    envCache = { key: cacheKey ?? "empty", env };
+}
+/**
+ * Return the secret env vars (name → value) for injection into the agent
+ * shell environment. Synchronous, mtime-cached: new/updated/deleted secrets
+ * are picked up on the next call without a CLI restart.
+ *
+ * Failure modes degrade gracefully — a corrupt store, missing key, or unreadable
+ * file returns `{}` instead of throwing, because `getShellEnv()` is sync and
+ * must never break bash spawning. No values are ever logged.
+ */
+export function getSecretEnvVars() {
+    try {
+        const cacheKey = dataFileCacheKey();
+        if (cacheKey === null) {
+            return {};
+        }
+        if (envCache && envCache.key === cacheKey) {
+            return envCache.env;
+        }
+        refreshEnvCache();
+        return envCache?.env ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create or update a secret. Returns the metadata-only view (never the value).
+ * Throws `SecretNameError` for invalid names, `SecretValueError` for oversized
+ * values, and `SecretStoreCorruptError` when the store cannot be read/written.
+ *
+ * Fully synchronous (no awaits): the read-modify-write below is atomic per
+ * event-loop turn, so concurrent relay POSTs in one process can never
+ * interleave — no mutex is needed. Cross-process writers are isolated by the
+ * unique per-request tmp name + rename in `writeStoreData`; the last rename
+ * wins and every writer re-reads the store on its next call.
+ */
+export function setSecret(rawName, value) {
+    const name = normalizeSecretName(rawName);
+    assertValueSize(value);
+    const data = readStoreData();
+    const now = new Date().toISOString();
+    const existing = data.secrets[name];
+    data.secrets[name] = {
+        value,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+    writeStoreData(data);
+    refreshEnvCache();
+    return { name, createdAt: data.secrets[name].createdAt, updatedAt: now };
+}
+/**
+ * Delete a secret. Returns true when a record was removed, false when the
+ * name was not stored. Throws `SecretNameError` for invalid names.
+ */
+export function deleteSecret(rawName) {
+    const name = normalizeSecretName(rawName);
+    const data = readStoreData();
+    if (!Object.prototype.hasOwnProperty.call(data.secrets, name)) {
+        return false;
+    }
+    delete data.secrets[name];
+    writeStoreData(data);
+    refreshEnvCache();
+    return true;
+}
+/**
+ * List secrets as metadata only — `{ name, createdAt, updatedAt }`. Values are
+ * never part of the returned shape (this is the source for the relay GET
+ * response and the `list_secrets` agent tool).
+ */
+export function listSecrets() {
+    const data = readStoreData();
+    return Object.entries(data.secrets)
+        .map(([name, record]) => ({
+        name,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * INTERNAL — read a single secret value. Used ONLY for env-var injection via
+ * `getSecretEnvVars()`. Deliberately not re-exported from `./index.js` so it
+ * cannot be reached from the relay handlers or the LLM-facing tool surface.
+ * Never log the return value.
+ */
+export function getSecretValue(rawName) {
+    const name = normalizeSecretName(rawName);
+    const data = readStoreData();
+    return data.secrets[name]?.value;
+}
+/**
+ * Remove the store + key (test helper and future "reset secrets" support).
+ * Returns true when either file was deleted.
+ */
+export function resetSecretStore() {
+    let removed = false;
+    for (const path of [getSecretDataPath(), getSecretKeyPath()]) {
+        try {
+            unlinkSync(path);
+            removed = true;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    envCache = null;
+    return removed;
+}

package/dist/server/agent-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/agent-bridge.js

@@ -63,9 +63,11 @@ import { BrowserService } from "../extensions/browser/browser-service.js";
 import subagentExt from "../agent/index.js";
 import designerExtension from "../designer/index.js";
 import logicTraceExtension from "../extensions/logic-trace.js";
+import listSecretsExtension from "../extensions/list-secrets.js";
 import observationalMemory from "../memory/index.js";
 import { OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, } from "../memory/types.js";
 import { fetchAllowedModels as defaultFetchAllowedModels, } from "../relay/models-fetch.js";
+import { annotatedUserMessageText } from "./attachments/persist.js";
 import { humanizeProviderError } from "./error-humanizer.js";
 import { readStudioBinding, getBindingFilePath } from "../studio-binding.js";
 // Facade imports: cohesive helpers extracted verbatim to `./agent-bridge/` modules.
@@ -368,6 +370,12 @@ export class AgentBridge {
             async (ext) => {
                 observationalMemory(ext);
             },
+            // list_secrets: metadata-only view of the local encrypted secret store
+            // (names + timestamps). Values are never returned to the LLM — they are
+            // injected as env vars into the bash tool via getShellEnv().
+            async (ext) => {
+                listSecretsExtension(ext);
+            },
         ];
         // Always register subagent tool — execute() checks settings from disk
         // on every invocation, so toggling takes effect immediately (no restart).
@@ -432,9 +440,19 @@ export class AgentBridge {
                     const imageBlocks = (msg.images ?? [])
                         .map(toImageContent)
                         .filter((block) => block !== null);
+                    // Attachment persistence (Option A): annotate rehydrated user
+                    // messages whose attachments are still on disk, so the LLM sees
+                    // the same saved-at hint the original prompt carried. Attachments
+                    // that were swept (or never persisted) leave the text untouched.
+                    const text = annotatedUserMessageText({
+                        cwd: this.opts.cwd,
+                        sessionId: this.opts.sessionId,
+                        content: msg.content,
+                        images: msg.images,
+                    });
                     const content = imageBlocks.length > 0
-                        ? [...imageBlocks, { type: "text", text: msg.content }]
-                        : msg.content;
+                        ? [...imageBlocks, { type: "text", text }]
+                        : text;
                     sessionManager.appendMessage({
                         role: "user",
                         content,

package/dist/server/attachments/cleanup.d.ts

@@ -0,0 +1,42 @@
+/**
+ * TTL GC for persisted chat attachments (`.spectral/attachments/<id>/`).
+ *
+ * Mirrors `src/server/offload-gc.ts`: the sweep removes per-session
+ * directories whose session no longer exists AND whose directory mtime is
+ * older than `SPECTRAL_ATTACHMENT_TTL_DAYS` (default 7). Sessions that still
+ * exist in the store are never swept, however old their attachments are.
+ *
+ * Best-effort and synchronous: callers fire-and-forget it (server startup,
+ * first prompt). Never throws.
+ *
+ * @module @spectral/server/attachments/cleanup
+ */
+/** Session dirs older than this (in days) are swept when their session is gone. */
+export declare const DEFAULT_ATTACHMENT_TTL_DAYS = 7;
+/** Effective TTL in ms (override via `SPECTRAL_ATTACHMENT_TTL_DAYS`). */
+export declare function getAttachmentTtlMs(): number;
+export interface AttachmentSweepResult {
+    removedSessions: number;
+    removedBytes: number;
+}
+export interface SweepAttachmentsOptions {
+    /** `.spectral/attachments` root to sweep (per project cwd). */
+    root: string;
+    /**
+     * Session ids that still exist — their directories are NEVER swept,
+     * however old. Omitted = treat every session as gone (TTL-only sweep).
+     */
+    activeSessionIds?: Iterable<string>;
+    /** Epoch ms "now" (tests). Defaults to `Date.now()`. */
+    now?: number;
+    /** TTL override in ms (tests). Defaults to `getAttachmentTtlMs()`. */
+    ttlMs?: number;
+}
+/**
+ * Remove stale attachment session directories. A directory is removed only
+ * when BOTH: its name matches no active session id AND its mtime is older
+ * than the TTL. Dotfiles (`.gitignore`) and stray non-directories are left
+ * alone. Never throws.
+ */
+export declare function sweepAttachments(options: SweepAttachmentsOptions): AttachmentSweepResult;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/server/attachments/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../../src/server/attachments/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,mFAAmF;AACnF,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,yEAAyE;AACzE,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAsBD,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,qBAAqB,CAuCxF"}

package/dist/server/attachments/cleanup.js

@@ -0,0 +1,100 @@
+/**
+ * TTL GC for persisted chat attachments (`.spectral/attachments/<id>/`).
+ *
+ * Mirrors `src/server/offload-gc.ts`: the sweep removes per-session
+ * directories whose session no longer exists AND whose directory mtime is
+ * older than `SPECTRAL_ATTACHMENT_TTL_DAYS` (default 7). Sessions that still
+ * exist in the store are never swept, however old their attachments are.
+ *
+ * Best-effort and synchronous: callers fire-and-forget it (server startup,
+ * first prompt). Never throws.
+ *
+ * @module @spectral/server/attachments/cleanup
+ */
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { envPositiveInt } from "../../sdk/coding-agent/core/tools/offload.js";
+/** Session dirs older than this (in days) are swept when their session is gone. */
+export const DEFAULT_ATTACHMENT_TTL_DAYS = 7;
+/** Effective TTL in ms (override via `SPECTRAL_ATTACHMENT_TTL_DAYS`). */
+export function getAttachmentTtlMs() {
+    return envPositiveInt("SPECTRAL_ATTACHMENT_TTL_DAYS", DEFAULT_ATTACHMENT_TTL_DAYS) *
+        24 * 60 * 60 * 1000;
+}
+function dirSizeBytes(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        try {
+            if (entry.isDirectory())
+                total += dirSizeBytes(full);
+            else if (entry.isFile())
+                total += statSync(full).size;
+        }
+        catch {
+            // Skip unreadable entries — GC is best-effort.
+        }
+    }
+    return total;
+}
+/**
+ * Remove stale attachment session directories. A directory is removed only
+ * when BOTH: its name matches no active session id AND its mtime is older
+ * than the TTL. Dotfiles (`.gitignore`) and stray non-directories are left
+ * alone. Never throws.
+ */
+export function sweepAttachments(options) {
+    const result = { removedSessions: 0, removedBytes: 0 };
+    const { root } = options;
+    if (!root || !existsSync(root))
+        return result;
+    const active = new Set(options.activeSessionIds ?? []);
+    const ttlMs = options.ttlMs ?? getAttachmentTtlMs();
+    const now = options.now ?? Date.now();
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        // Only sweep session directories; leave `.gitignore` and strays alone.
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (active.has(entry.name))
+            continue;
+        const dir = join(root, entry.name);
+        let mtimeMs;
+        try {
+            const stat = statSync(dir);
+            if (!stat.isDirectory())
+                continue;
+            mtimeMs = stat.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        // `stat.mtimeMs` carries sub-ms precision while `Date.now()` does not —
+        // floor it so a directory created in the same millisecond as `now`
+        // (ttlMs = 0) is deterministically "older".
+        if (now - Math.floor(mtimeMs) < ttlMs)
+            continue;
+        try {
+            result.removedBytes += dirSizeBytes(dir);
+            rmSync(dir, { recursive: true, force: true });
+            result.removedSessions += 1;
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    return result;
+}