@mafdet/cli 0.4.0 → 0.4.2

package/dist/commands/sessions.js

@@ -0,0 +1,379 @@
+// CLI-024 · `mafdet sessions` - list, show and delete what is on this machine.
+//
+// Read-only against the model: none of these commands sends a request, so
+// browsing history is free (plan §20.2). Deleting removes local files and
+// nothing else - the server's ledger is untouched, and the confirmation says
+// so, because "delete" is a word people reasonably expect to mean "and stop
+// charging me".
+import { existsSync } from "node:fs";
+import { fetchUsageEvents } from "../api/account.js";
+import { sessionsDir } from "../config/paths.js";
+import { formatUsd } from "../output/money.js";
+import { ExitCode } from "../output/exit-codes.js";
+import { parseFormatFlags, renderJson, renderRecord, renderTable, } from "../output/format.js";
+import { keyDigest } from "../security/redact.js";
+import { loadIndex, removeIndexEntry } from "../sessions/index-file.js";
+import { acquireSessionLock, SessionLockedError } from "../sessions/lock.js";
+import { daysToCover, matchSettlements, planReconciliation, } from "../sessions/reconcile.js";
+import { deleteSession, readSession, SessionWriter, } from "../sessions/store.js";
+import { settledCaveat, summariseUsage } from "../sessions/usage.js";
+import { buildRuntime, reportError, requireApiKey, } from "./runtime.js";
+import { join } from "node:path";
+const USAGE = `Usage:
+  mafdet sessions list [--json|--plain]
+  mafdet sessions show <session-id> [--json]
+  mafdet sessions usage <session-id> [--refresh] [--json]
+  mafdet sessions delete <session-id> [--yes]
+
+Conversations are stored on this computer only. Browsing them never
+calls a model and is never charged.
+
+--refresh asks the billing ledger what this key's requests actually
+cost. It sends request IDs and nothing else - no messages, no titles.
+`;
+export async function sessionsCommand(argv, io) {
+    const [sub, ...rest] = argv;
+    const root = sessionsDir(io.env ?? process.env);
+    if (sub === undefined || sub === "help" || sub === "--help") {
+        io.stdout(USAGE);
+        return sub === undefined ? ExitCode.Usage : ExitCode.Ok;
+    }
+    if (sub === "list")
+        return list(rest, io, root);
+    if (sub === "show")
+        return show(rest, io, root);
+    if (sub === "usage")
+        return usage(rest, io, root);
+    if (sub === "delete")
+        return remove(rest, io, root);
+    io.stderr(`mafdet sessions: unknown subcommand '${sub}'\n${USAGE}`);
+    return ExitCode.Usage;
+}
+function list(argv, io, root) {
+    const { format } = parseFormatFlags(argv);
+    const { sessions } = loadIndex(root);
+    if (format === "json") {
+        io.stdout(renderJson({
+            sessions_path: root,
+            count: sessions.length,
+            sessions,
+        }));
+        return ExitCode.Ok;
+    }
+    if (sessions.length === 0) {
+        // Not an error: a fresh machine has none, and saying where they would go
+        // is more use than an empty table.
+        io.stderr(`no saved conversations yet (they would be in ${root})\n`);
+        return ExitCode.Ok;
+    }
+    io.stdout(renderTable(sessions, [
+        { header: "SESSION", value: (s) => s.session_id },
+        { header: "TITLE", value: (s) => s.title },
+        { header: "MODEL", value: (s) => s.model_id },
+        { header: "REQUESTS", value: (s) => `${s.model_requests}` },
+        {
+            header: "EST. COST",
+            value: (s) => formatUsd(s.estimated_charge_micro_usd),
+        },
+        { header: "UPDATED", value: (s) => s.updated_at },
+    ]));
+    return ExitCode.Ok;
+}
+function show(argv, io, root) {
+    const { format } = parseFormatFlags(argv);
+    const id = argv.find((arg) => !arg.startsWith("-"));
+    if (id === undefined) {
+        io.stderr(`mafdet sessions show: no session id\n${USAGE}`);
+        return ExitCode.Usage;
+    }
+    const directory = join(root, id);
+    if (!existsSync(directory)) {
+        io.stderr(`mafdet sessions: no session '${id}' on this computer\n`);
+        return ExitCode.General;
+    }
+    let session;
+    try {
+        session = readSession(directory);
+    }
+    catch (error) {
+        io.stderr(`mafdet sessions: ${error instanceof Error ? error.message : String(error)}\n`);
+        return ExitCode.General;
+    }
+    if (format === "json") {
+        io.stdout(renderJson({
+            metadata: session.metadata,
+            events: session.events,
+            truncated_tail: session.truncatedTail,
+        }));
+        return ExitCode.Ok;
+    }
+    const m = session.metadata;
+    io.stdout(renderRecord([
+        ["session", m.session_id],
+        ["title", m.title],
+        ["model", m.model_id],
+        ["workspace", m.workspace],
+        ["mode", m.mode],
+        ["created", m.created_at],
+        ["updated", m.updated_at],
+        ["messages", `${m.message_count}`],
+        ["model requests", `${m.model_requests}`],
+        ["tokens", `${m.prompt_tokens} in / ${m.completion_tokens} out`],
+        ["estimated cost", formatUsd(m.estimated_charge_micro_usd)],
+    ]));
+    if (session.truncatedTail) {
+        // Worth saying plainly: the user should know a crash cost them the tail.
+        io.stderr("\nnote: the last event was incomplete, most likely an interrupted run.\n");
+    }
+    return ExitCode.Ok;
+}
+function remove(argv, io, root) {
+    const id = argv.find((arg) => !arg.startsWith("-"));
+    const confirmed = argv.includes("--yes");
+    if (id === undefined) {
+        io.stderr(`mafdet sessions delete: no session id\n${USAGE}`);
+        return ExitCode.Usage;
+    }
+    const directory = join(root, id);
+    if (!existsSync(directory)) {
+        io.stderr(`mafdet sessions: no session '${id}' on this computer\n`);
+        return ExitCode.General;
+    }
+    if (!confirmed) {
+        // No prompt here: this is the command surface, where a script must not be
+        // able to hang waiting for an answer. Say exactly what would happen and
+        // require the flag.
+        io.stderr(DELETION_NOTICE(id));
+        return ExitCode.Usage;
+    }
+    deleteSession(directory);
+    removeIndexEntry(root, id);
+    io.stdout(`deleted ${id}\n`);
+    return ExitCode.Ok;
+}
+export const DELETION_NOTICE = (id) => `Deleting ${id} removes local messages and its per-session usage mapping\n` +
+    `from this computer.\n\n` +
+    `It does not remove API usage, billing records, or charges.\n\n` +
+    // Plan §20.12 requires this said out loud. "Delete" reads as "gone", and on
+    // a modern filesystem it is not: an SSD may keep the blocks, and a Time
+    // Machine or restic snapshot certainly keeps the file. Promising an erase we
+    // cannot perform would be the more comfortable sentence and the false one.
+    `It is an ordinary file delete, not a secure erase: backups, snapshots\n` +
+    `and the filesystem itself may still hold copies.\n\n` +
+    `Re-run with --yes to delete.\n`;
+/**
+ * What this conversation used.
+ *
+ * Estimated and settled are shown as separate lines, never added together and
+ * never collapsed: §20.7 is explicit that an estimate must not be displayed as
+ * the final charge, and a settled figure that covers only some of the requests
+ * would be a smaller number than the truth.
+ */
+async function usage(argv, io, root) {
+    const { format } = parseFormatFlags(argv);
+    const id = argv.find((arg) => !arg.startsWith("-"));
+    if (id === undefined) {
+        io.stderr(`mafdet sessions usage: no session id\n${USAGE}`);
+        return ExitCode.Usage;
+    }
+    const directory = join(root, id);
+    if (!existsSync(directory)) {
+        io.stderr(`mafdet sessions: no session '${id}' on this computer\n`);
+        return ExitCode.General;
+    }
+    let session;
+    try {
+        session = readSession(directory);
+    }
+    catch (error) {
+        io.stderr(`mafdet sessions: ${error instanceof Error ? error.message : String(error)}\n`);
+        return ExitCode.General;
+    }
+    let refreshed;
+    if (argv.includes("--refresh")) {
+        refreshed = await refresh(directory, session, io);
+        // Re-read rather than patch the in-memory copy: the file is the record,
+        // and reading it back is the only way to know the settlements landed.
+        if (refreshed.appended > 0)
+            session = readSession(directory);
+    }
+    const totals = summariseUsage(session.events);
+    if (format === "json") {
+        io.stdout(renderJson({
+            session_id: id,
+            user_messages: totals.userMessages,
+            model_requests: totals.modelRequests,
+            tool_runs: totals.toolRuns,
+            tool_runs_refused: totals.toolRunsRefused,
+            rate_limit_hits: totals.rateLimitHits,
+            rate_limit_wait_ms: totals.rateLimitWaitMs,
+            prompt_tokens: totals.promptTokens,
+            completion_tokens: totals.completionTokens,
+            // Strings, so no parser turns a charge into a float.
+            estimated_charge_micro_usd: totals.estimatedMicroUsd.toString(),
+            settled_charge_micro_usd: totals.settledMicroUsd.toString(),
+            by_settlement: totals.bySettlement,
+            by_model: totals.byModel.map((m) => ({
+                model_id: m.modelId,
+                model_requests: m.modelRequests,
+                prompt_tokens: m.promptTokens,
+                completion_tokens: m.completionTokens,
+                estimated_charge_micro_usd: m.estimatedMicroUsd.toString(),
+            })),
+            by_api_key: totals.byKey.map((k) => ({
+                api_key_ref: k.apiKeyRef,
+                model_requests: k.modelRequests,
+                estimated_charge_micro_usd: k.estimatedMicroUsd.toString(),
+            })),
+            ...(refreshed === undefined ? {} : { refresh: jsonRefresh(refreshed) }),
+        }));
+        return refreshed?.exitCode ?? ExitCode.Ok;
+    }
+    const rows = [
+        ["user messages", `${totals.userMessages}`],
+        ["model requests", `${totals.modelRequests}`],
+        [
+            "tool runs",
+            `${totals.toolRuns}${totals.toolRunsRefused > 0 ? ` (${totals.toolRunsRefused} refused)` : ""}`,
+        ],
+        ["tokens", `${totals.promptTokens} in / ${totals.completionTokens} out`],
+        ["local estimate", formatUsd(totals.estimatedMicroUsd.toString())],
+    ];
+    if (totals.bySettlement.settled > 0) {
+        rows.push([
+            "server settled",
+            `${formatUsd(totals.settledMicroUsd.toString())} (${totals.bySettlement.settled} of ${totals.modelRequests})`,
+        ]);
+    }
+    if (totals.rateLimitHits > 0) {
+        rows.push([
+            "rate limited",
+            `${totals.rateLimitHits} time(s), ${Math.round(totals.rateLimitWaitMs / 1000)}s waiting`,
+        ]);
+    }
+    io.stdout(renderRecord(rows));
+    if (totals.byModel.length > 1) {
+        io.stdout("\nBy model\n");
+        io.stdout(renderTable(totals.byModel, [
+            { header: "MODEL", value: (m) => m.modelId },
+            { header: "REQUESTS", value: (m) => `${m.modelRequests}` },
+            {
+                header: "ESTIMATE",
+                value: (m) => formatUsd(m.estimatedMicroUsd.toString()),
+            },
+        ]));
+    }
+    if (totals.byKey.length > 1) {
+        // Split per key so two accounts' spending is never presented as one.
+        io.stdout("\nBy API key\n");
+        io.stdout(renderTable(totals.byKey, [
+            { header: "KEY", value: (k) => k.apiKeyRef },
+            { header: "REQUESTS", value: (k) => `${k.modelRequests}` },
+            {
+                header: "ESTIMATE",
+                value: (k) => formatUsd(k.estimatedMicroUsd.toString()),
+            },
+        ]));
+    }
+    const caveat = settledCaveat(totals);
+    if (caveat !== undefined)
+        io.stderr(`\nnote: ${caveat}.\n`);
+    if (refreshed !== undefined) {
+        for (const line of describeRefresh(refreshed))
+            io.stderr(`${line}\n`);
+    }
+    return refreshed?.exitCode ?? ExitCode.Ok;
+}
+async function refresh(directory, session, io) {
+    const nothing = { appended: 0, missing: 0, exhausted: true };
+    try {
+        const runtime = buildRuntime(io);
+        requireApiKey(runtime.config);
+        const plan = planReconciliation(session.events, keyDigest(runtime.config.apiKey ?? ""));
+        // Nothing to ask about is a complete answer, and a network call that could
+        // only return rows we would throw away is not worth making.
+        if (plan.wanted.size === 0) {
+            return { ...nothing, plan, exitCode: ExitCode.Ok };
+        }
+        const { events, exhausted } = await fetchUsageEvents(runtime.accountPlane, {
+            days: daysToCover(session.metadata.created_at),
+            wanted: plan.wanted,
+        });
+        const matched = matchSettlements(plan, events, new Date().toISOString());
+        let appended = 0;
+        if (matched.settlements.length > 0) {
+            // Under the lock: a session open in another window is appending to the
+            // same file, and `reopen` reads the sequence number before writing.
+            const lock = acquireSessionLock(directory);
+            try {
+                const writer = SessionWriter.reopen(directory);
+                for (const settlement of matched.settlements) {
+                    writer.append(settlement);
+                    appended += 1;
+                }
+                writer.close();
+            }
+            finally {
+                lock.release();
+            }
+        }
+        return {
+            plan,
+            appended,
+            missing: matched.missing.length,
+            exhausted,
+            exitCode: ExitCode.Ok,
+        };
+    }
+    catch (error) {
+        if (error instanceof SessionLockedError) {
+            io.stderr(`mafdet sessions: ${error.message}\n`);
+            return { ...nothing, error: error.message, exitCode: ExitCode.General };
+        }
+        // The local figures below are still correct - they were never in doubt -
+        // so they are printed anyway, and the exit code carries the failure.
+        return {
+            ...nothing,
+            error: error instanceof Error ? error.message : String(error),
+            exitCode: reportError(error, io),
+        };
+    }
+}
+function jsonRefresh(refreshed) {
+    return {
+        settled_now: refreshed.appended,
+        not_in_ledger: refreshed.missing,
+        complete_walk: refreshed.exhausted,
+        already_settled: refreshed.plan?.alreadySettled ?? 0,
+        other_api_key: refreshed.plan?.otherKey ?? 0,
+        no_request_id: refreshed.plan?.unanswerable ?? 0,
+        ...(refreshed.error === undefined ? {} : { error: refreshed.error }),
+    };
+}
+/** One line per thing the user might otherwise misread as something else. */
+function describeRefresh(refreshed) {
+    if (refreshed.error !== undefined)
+        return [];
+    const lines = [];
+    const plan = refreshed.plan;
+    if (refreshed.appended > 0) {
+        lines.push(`\nrefreshed: ${refreshed.appended} request(s) settled.`);
+    }
+    if (refreshed.missing > 0) {
+        // The distinction matters: one of these is "wait", the other is "look".
+        lines.push(refreshed.exhausted
+            ? `note: ${refreshed.missing} request(s) are not in the ledger yet; try again shortly.`
+            : `note: ${refreshed.missing} request(s) were not found in the pages read; try a narrower window.`);
+    }
+    if (plan !== undefined && plan.otherKey > 0) {
+        lines.push(`note: ${plan.otherKey} request(s) were paid for by a different API key. ` +
+            `Run this again with that key configured to settle them.`);
+    }
+    if (plan !== undefined &&
+        refreshed.appended === 0 &&
+        refreshed.missing === 0 &&
+        plan.otherKey === 0) {
+        lines.push("\nrefreshed: nothing left to settle.");
+    }
+    return lines;
+}

package/dist/config/paths.d.ts

@@ -8,4 +8,11 @@ export declare const PROJECT_CONFIG_FILE = ".mafdet.json";
  */
 export declare function userConfigDir(env?: NodeJS.ProcessEnv, os?: string, home?: string): string;
 export declare function userConfigPath(env?: NodeJS.ProcessEnv, os?: string, home?: string): string;
+/**
+ * Per-platform state directory (plan §20.5). Separate from the config
+ * directory on purpose: sessions are machine-local and must not follow a
+ * roaming profile between machines, whereas settings reasonably do.
+ */
+export declare function userStateDir(env?: NodeJS.ProcessEnv, os?: string, home?: string): string;
+export declare function sessionsDir(env?: NodeJS.ProcessEnv, os?: string, home?: string): string;
 //# sourceMappingURL=paths.d.ts.map

package/dist/config/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/config/paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAeR;AAED,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAER"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/config/paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAeR;AAED,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAoBR;AAED,wBAAgB,WAAW,CACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,MAAM,CAER"}

package/dist/config/paths.js

@@ -24,3 +24,27 @@ export function userConfigDir(env = process.env, os = platform(), home = homedir
 export function userConfigPath(env = process.env, os = platform(), home = homedir()) {
     return join(userConfigDir(env, os, home), CONFIG_FILE);
 }
+/**
+ * Per-platform state directory (plan §20.5). Separate from the config
+ * directory on purpose: sessions are machine-local and must not follow a
+ * roaming profile between machines, whereas settings reasonably do.
+ */
+export function userStateDir(env = process.env, os = platform(), home = homedir()) {
+    if (os === "win32") {
+        const localAppData = env.LOCALAPPDATA?.trim();
+        return join(localAppData && localAppData.length > 0
+            ? localAppData
+            : join(home, "AppData", "Local"), 
+        // Lowercase, matching userConfigDir: one machine should not end up with
+        // both `Mafdet\` and `mafdet\`.
+        "mafdet");
+    }
+    if (os === "darwin") {
+        return join(home, "Library", "Application Support", "mafdet");
+    }
+    const xdg = env.XDG_STATE_HOME?.trim();
+    return join(xdg && xdg.length > 0 ? xdg : join(home, ".local", "state"), "mafdet");
+}
+export function sessionsDir(env = process.env, os = platform(), home = homedir()) {
+    return join(userStateDir(env, os, home), "sessions");
+}

package/dist/filesystem/protected-dirs.d.ts

@@ -0,0 +1,26 @@
+export interface ProtectedDirectory {
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * Every directory the CLI owns, resolved as far as it exists.
+ *
+ * Resolved eagerly so the comparison later is real-path against real-path: a
+ * symlinked home, or a state directory reached through one, must not slip past.
+ *
+ * `os` and `home` are injectable for the same reason they are in `paths.ts`:
+ * §20.12b requires all three platform layouts to be covered, and a function
+ * that can only ever describe the machine running it cannot be shown to.
+ * On macOS the two directories coincide, which is why the list is deduplicated
+ * rather than assumed to hold two entries.
+ */
+export declare function protectedDirectories(env?: NodeJS.ProcessEnv, os?: string, home?: string): readonly ProtectedDirectory[];
+/**
+ * Is this path inside one of the CLI's own directories?
+ *
+ * `relative()` rather than a prefix test: a sibling named `mafdet-notes` must
+ * not be caught by a `mafdet` prefix, and on win32 `relative` compares
+ * case-insensitively, which is the behaviour we want there.
+ */
+export declare function protectedBy(absolutePath: string, directories: readonly ProtectedDirectory[]): ProtectedDirectory | undefined;
+//# sourceMappingURL=protected-dirs.d.ts.map

package/dist/filesystem/protected-dirs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-dirs.d.ts","sourceRoot":"","sources":["../../src/filesystem/protected-dirs.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAmB,EACvB,IAAI,GAAE,MAAkB,GACvB,SAAS,kBAAkB,EAAE,CAqB/B;AAYD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,kBAAkB,GAAG,SAAS,CAUhC"}

package/dist/filesystem/protected-dirs.js

@@ -0,0 +1,78 @@
+// CLI-023 · The CLI's own directories are off limits to the agent.
+//
+// Plan §20.12b. Sessions are stored under the user's state directory, and a
+// user may well run `mafdet` from $HOME - the 2026-08-07 screenshot shows
+// exactly that. Without this, the store lands inside the workspace and an
+// agent working in one project can read another project's transcript in full,
+// which would make "plaintext, but disclosed" a false description of the deal.
+//
+// Matched on the real resolved path rather than on a path shape: XDG_STATE_HOME
+// and LOCALAPPDATA can point anywhere, so a pattern like `.local/state/mafdet`
+// would miss a relocated directory - and matching a bare `mafdet` segment
+// would wrongly refuse a project that happens to contain one.
+import { realpathSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { relative, resolve, sep } from "node:path";
+import { userConfigDir, userStateDir } from "../config/paths.js";
+/**
+ * Every directory the CLI owns, resolved as far as it exists.
+ *
+ * Resolved eagerly so the comparison later is real-path against real-path: a
+ * symlinked home, or a state directory reached through one, must not slip past.
+ *
+ * `os` and `home` are injectable for the same reason they are in `paths.ts`:
+ * §20.12b requires all three platform layouts to be covered, and a function
+ * that can only ever describe the machine running it cannot be shown to.
+ * On macOS the two directories coincide, which is why the list is deduplicated
+ * rather than assumed to hold two entries.
+ */
+export function protectedDirectories(env = process.env, os = platform(), home = homedir()) {
+    const candidates = [
+        {
+            path: userStateDir(env, os, home),
+            reason: "it holds saved conversations from your other sessions",
+        },
+        {
+            path: userConfigDir(env, os, home),
+            reason: "it holds this CLI's own settings",
+        },
+    ];
+    const seen = new Set();
+    const directories = [];
+    for (const entry of candidates) {
+        const path = realOrSelf(entry.path);
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        directories.push({ ...entry, path });
+    }
+    return directories;
+}
+function realOrSelf(path) {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        // Not created yet. The lexical form is still worth refusing, so that the
+        // rule holds before the first session is ever written.
+        return resolve(path);
+    }
+}
+/**
+ * Is this path inside one of the CLI's own directories?
+ *
+ * `relative()` rather than a prefix test: a sibling named `mafdet-notes` must
+ * not be caught by a `mafdet` prefix, and on win32 `relative` compares
+ * case-insensitively, which is the behaviour we want there.
+ */
+export function protectedBy(absolutePath, directories) {
+    const target = resolve(absolutePath);
+    for (const directory of directories) {
+        const rel = relative(directory.path, target);
+        const inside = rel === "" ||
+            (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith("/"));
+        if (inside)
+            return directory;
+    }
+    return undefined;
+}

package/dist/filesystem/workspace.d.ts

@@ -1,3 +1,4 @@
+import { type ProtectedDirectory } from "./protected-dirs.js";
 /** Plan §7.4. */
 export declare const MAX_FILE_BYTES: number;
 export declare const MAX_TOOL_OUTPUT_BYTES: number;
@@ -36,13 +37,23 @@ export interface FileRead {
  */
 export declare class Workspace {
     readonly root: string;
+    /** The CLI's own directories, which the agent may never read. */
+    private readonly protectedDirs;
     private constructor();
-    static open(root: string): Workspace;
+    static open(root: string, protectedDirs?: readonly ProtectedDirectory[]): Workspace;
     /**
      * Validate a model-supplied path. Throws unless it lands inside the
      * workspace and is not on the sensitive list.
      */
     resolvePath(input: string): ResolvedPath;
+    /**
+     * Is this absolute path one of the CLI's own directories?
+     *
+     * Exposed so the directory walk can skip them, rather than relying on them
+     * happening to start with a dot - which is true on Linux and Windows and
+     * false on macOS.
+     */
+    isOwnedByCli(absolutePath: string): boolean;
     /** Read a text file, refusing binaries and anything oversized. */
     readTextFile(input: string): FileRead;
     /** True when the path is inside and allowed; never throws. */

package/dist/filesystem/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/filesystem/workspace.ts"],"names":[],"mappings":"AAkBA,iBAAiB;AACjB,eAAO,MAAM,cAAc,QAAa,CAAC;AACzC,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,IAAwB;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACA,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAzC,OAAO;IAEP,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAapC;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAmCxC,kEAAkE;IAClE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IA8BrC,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAS9B,OAAO,CAAC,YAAY;IAYpB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;CAuBlC;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEvD;AAMD,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,WAAW,CA0Db;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC,WAAW,CAsBb"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/filesystem/workspace.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,iBAAiB;AACjB,eAAO,MAAM,cAAc,QAAa,CAAC;AACzC,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,IAAwB;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IAElB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa;IAHhC,OAAO;IAMP,MAAM,CAAC,IAAI,CACT,IAAI,EAAE,MAAM,EACZ,aAAa,GAAE,SAAS,kBAAkB,EAA2B,GACpE,SAAS;IAaZ;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IA+CxC;;;;;;OAMG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI3C,kEAAkE;IAClE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IA8BrC,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAS9B,OAAO,CAAC,YAAY;IAYpB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;CAuBlC;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEvD;AAMD,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IACL,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,WAAW,CA0Db;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC,WAAW,CAsBb"}

package/dist/filesystem/workspace.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { unifiedDiff } from "./diff.js";
 import { ExitCode } from "../output/exit-codes.js";
+import { protectedBy, protectedDirectories, } from "./protected-dirs.js";
 import { classifySensitivePath } from "./sensitive-files.js";
 /** Plan §7.4. */
 export const MAX_FILE_BYTES = 512 * 1024;
@@ -32,10 +33,14 @@ export class WorkspaceError extends Error {
  */
 export class Workspace {
     root;
-    constructor(root) {
+    protectedDirs;
+    constructor(root, 
+    /** The CLI's own directories, which the agent may never read. */
+    protectedDirs) {
         this.root = root;
+        this.protectedDirs = protectedDirs;
     }
-    static open(root) {
+    static open(root, protectedDirs = protectedDirectories()) {
         let real;
         try {
             real = realpathSync(resolve(root));
@@ -46,7 +51,7 @@ export class Workspace {
         if (!statSync(real).isDirectory()) {
             throw new WorkspaceError(`workspace root is not a directory: ${root}`);
         }
-        return new Workspace(real);
+        return new Workspace(real, protectedDirs);
     }
     /**
      * Validate a model-supplied path. Throws unless it lands inside the
@@ -69,6 +74,12 @@ export class Workspace {
         const real = this.realpathOfNearestExisting(candidate);
         this.assertInside(real.path, input);
         const rel = toPosix(relative(this.root, real.exists ? real.path : candidate));
+        // Checked on the resolved absolute path, before the name-based rules: a
+        // session transcript is not recognisable by its filename.
+        const owned = protectedBy(real.exists ? real.path : candidate, this.protectedDirs);
+        if (owned !== undefined) {
+            throw new WorkspaceError(`refusing to touch ${rel}: that is the Mafdet CLI's own directory and ${owned.reason}.`);
+        }
         const verdict = classifySensitivePath(rel);
         if (verdict.denied) {
             throw new WorkspaceError(`refusing to touch ${rel}: ${verdict.reason}. Authorise that exact path if you really need it.`);
@@ -79,6 +90,16 @@ export class Workspace {
             exists: real.exists,
         };
     }
+    /**
+     * Is this absolute path one of the CLI's own directories?
+     *
+     * Exposed so the directory walk can skip them, rather than relying on them
+     * happening to start with a dot - which is true on Linux and Windows and
+     * false on macOS.
+     */
+    isOwnedByCli(absolutePath) {
+        return protectedBy(absolutePath, this.protectedDirs) !== undefined;
+    }
     /** Read a text file, refusing binaries and anything oversized. */
     readTextFile(input) {
         const target = this.resolvePath(input);

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAgDlD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsGpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAmDlD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyGpE"}