mindweave 0.0.1 → 2.1.2

package/dist/tools/editTarget.js

@@ -0,0 +1,131 @@
+/**
+ * editTarget.ts — the shared pre-edit gauntlet for the edit tool.
+ *
+ * Both tools must clear the exact same gates before touching a file: path guards
+ * (protected + forbidden-with-lift), the file must exist and be a file, and it
+ * must have been READ this session (the anti-confabulation rule). Factoring it
+ * here keeps that policy in one place so the two tools can never drift apart on
+ * safety. Returns the file's content + detected EOL on success, or a ready-made
+ * failure ToolResult to hand straight back.
+ */
+import { promises as fs } from "node:fs";
+import { foreignAgentReason, protectedPathReason } from "./guard.js";
+import { forbiddenPathReason } from "../governor/forbidden.js";
+import { requestAgentDataAccess, requestForbiddenLift, requestOutsideWorkspaceWrite } from "./approval.js";
+import { resolvePath } from "./paths.js";
+import { detectEol } from "./eol.js";
+import { fail, failQuietly } from "./results.js";
+// Re-exported because the edit tools reach for these alongside the gauntlet itself.
+export { fail, failQuietly } from "./results.js";
+/** Run the shared pre-edit checks for `rawPath`. `verb` names the action in
+ *  messages (e.g. "editing"). */
+export async function prepareEditTarget(ctx, rawPath, verb) {
+    const filePath = resolvePath(ctx, rawPath);
+    const blocked = protectedPathReason(filePath);
+    if (blocked)
+        return { ok: false, error: fail(`Refusing to edit ${rawPath}: it is ${blocked}.`) };
+    // Another tool's data. Writing to it is worse than reading it — we'd be editing
+    // a history we were never part of — so it goes through the same ask-first gate.
+    const otherTool = foreignAgentReason(filePath);
+    if (otherTool) {
+        const denied = await requestAgentDataAccess(ctx, otherTool, `${verb} ${rawPath}`);
+        if (denied)
+            return { ok: false, error: denied };
+    }
+    const forbidden = forbiddenPathReason(ctx.governance?.forbidden, filePath, ctx.roots ?? []);
+    if (forbidden) {
+        const lift = await requestForbiddenLift(ctx, forbidden, `${verb} ${rawPath}`, `the user has forbidden touching '${forbidden}'.`);
+        if (lift)
+            return { ok: false, error: lift }; // refused/deferred; an allow returns null → falls through
+    }
+    // The workspace boundary. Everything above is about WHICH file; this is about whether
+    // the agent should be writing there at all.
+    const outside = await requestOutsideWorkspaceWrite(ctx, filePath, `${verb} ${rawPath}`);
+    if (outside)
+        return { ok: false, error: outside };
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        return { ok: false, error: fail(`file ${rawPath} not found. Use write_file to create a new file.`) };
+    }
+    if (stat.isDirectory())
+        return { ok: false, error: fail(`${rawPath} is a directory, not a file.`) };
+    // Read-before-edit: the anti-confabulation gate.
+    //
+    // It used to refuse here, outright, for any file not in the ledger. That cost far more
+    // than it protected. Measured on a real session: the model batched one identical
+    // navigation edit across five pages, four were refused, and it then read four whole
+    // files (~9,000 tokens each) and re-issued the same four edits — which all applied
+    // cleanly, first try. Twelve calls where five would have done, and every byte of those
+    // reads was spent proving something the edit was about to prove anyway.
+    //
+    // Because that is what an edit already does: `old_string` is matched against the
+    // file's CURRENT bytes (see the freshness note below, which says as much). A unique
+    // match IS evidence the model knows what is there — you cannot quote a line you have
+    // not seen. So an unread file is no longer refused; it is made to earn the edit by
+    // matching exactly. If it cannot, the caller returns the same "read it first" message
+    // it always did, and the read happens then — when it is actually needed.
+    // A search-sourced entry does not count as having seen the file: grep shows matching
+    // lines, never the file, so the edit still has to earn itself by matching exactly.
+    const record = ctx.reads.get(filePath);
+    const seen = record && !record.viaSearch ? record : undefined;
+    let content;
+    try {
+        content = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        return { ok: false, error: fail(`could not read ${rawPath}: ${errText(error)}`) };
+    }
+    // Freshness: has the file moved since it was read?
+    //
+    // Without this the situation is still SAFE — the edit is matched against the file's
+    // current bytes, so a stale `old_string` simply fails to match — but it is diagnosed
+    // WRONGLY. The model is told "old_string not found, re-read and copy the target text
+    // precisely", which reads as "you mistyped", so it retries the same doomed string
+    // instead of re-reading. The cause has to be named for the recovery to be the right one.
+    //
+    // And the quieter case is worse: if the change landed somewhere the model is not
+    // editing, its edit applies cleanly against content nobody has looked at. That is the
+    // only path here where a confident edit is made on stale understanding, so it is worth
+    // one comparison of two numbers we already hold.
+    if (seen && changedSinceRead(seen, stat)) {
+        return {
+            ok: false,
+            error: failQuietly(`${rawPath} changed on disk since you read it (a command, a formatter, or the user). ` +
+                `Your view of this file is out of date, so an edit based on it could be wrong even where it matches. ` +
+                `Read it again, then redo the edit against what it says now.`),
+        };
+    }
+    return { ok: true, filePath, content, eol: detectEol(content), unread: seen === undefined };
+}
+/** The refusal an unread file earns only when its edits do NOT match exactly. Same
+ *  message the gate always gave; it is just paid for when it is actually true. */
+export function unreadError(rawPath) {
+    return fail(`${rawPath} has not been read this session, and your edit did not match it exactly. ` +
+        `Read it first so your edit matches the real content.`);
+}
+/**
+ * Did the file change between the read that put it in the ledger and now (pure)?
+ *
+ * Both signals are checked because either alone misses real cases: mtime resolution is
+ * coarse enough on some filesystems that a fast rewrite keeps the same stamp, and a size
+ * comparison alone misses any edit that happens to preserve length — a renamed symbol, a
+ * flipped boolean, a changed constant. Neither is exotic in a codebase.
+ *
+ * A file the ledger has no size for (an older record, or one seeded rather than read) is
+ * treated as unchanged: refusing on missing bookkeeping would block edits over our own
+ * gap rather than over anything the user did.
+ */
+export function changedSinceRead(seen, now) {
+    if (typeof seen.size === "number" && seen.size !== now.size)
+        return true;
+    if (typeof seen.mtimeMs === "number" && seen.mtimeMs > 0 && Math.abs(seen.mtimeMs - now.mtimeMs) > 1)
+        return true;
+    return false;
+}
+export function errText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=editTarget.js.map

package/dist/tools/editTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editTarget.js","sourceRoot":"","sources":["../../src/tools/editTarget.ts"],"names":[],"mappings":"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"}

package/dist/tools/editWindow.js

@@ -0,0 +1,49 @@
+/**
+ * editWindow.ts — showing the model what its edit actually produced.
+ *
+ * After a change lands, the tool hands back the changed region with line numbers
+ * rather than making the model re-read the whole file to see the result. That one
+ * habit is the difference between an edit costing one call and costing two, and
+ * re-reads were measured as a large share of wasted context.
+ *
+ * These live apart from the edit tool itself because `replace_symbol_body` needs
+ * the same rendering and has nothing else in common with it. Pure functions over
+ * normalized (LF) text: no filesystem, no EOL concerns, trivially testable.
+ */
+/**
+ * Render the lines spanning [startChar, endChar] in `text`, plus `pad` lines of
+ * context on each side, with 1-based right-aligned line numbers. Pure and indexed
+ * on the normalized (LF) text, so it's independent of the file's real EOL. Bounded
+ * by `maxLines` so a sweeping replace can't flood the result.
+ */
+export function numberedWindow(text, startChar, endChar, pad = 4, maxLines = 30) {
+    const lines = text.split("\n");
+    const startLine = charToLine(text, startChar);
+    const endLine = charToLine(text, endChar);
+    const from = Math.max(0, startLine - pad);
+    let to = Math.min(lines.length - 1, endLine + pad);
+    let truncated = false;
+    if (to - from + 1 > maxLines) {
+        to = from + maxLines - 1;
+        truncated = true;
+    }
+    const width = String(to + 1).length;
+    const out = [];
+    for (let i = from; i <= to; i++) {
+        out.push(`${String(i + 1).padStart(width)}  ${lines[i] ?? ""}`);
+    }
+    if (truncated)
+        out.push("    … (region continues; re-read the file if you need the rest)");
+    return out.join("\n");
+}
+/** The 0-based line a character offset falls on (count of newlines before it). */
+export function charToLine(text, charIndex) {
+    let line = 0;
+    const limit = Math.min(charIndex, text.length);
+    for (let i = 0; i < limit; i++) {
+        if (text[i] === "\n")
+            line++;
+    }
+    return line;
+}
+//# sourceMappingURL=editWindow.js.map

package/dist/tools/editWindow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editWindow.js","sourceRoot":"","sources":["../../src/tools/editWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,SAAiB,EACjB,OAAe,EACf,GAAG,GAAG,CAAC,EACP,QAAQ,GAAG,EAAE;IAEb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,GAAG,CAAC,CAAC;IAC1C,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,CAAC,CAAC;IACnD,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC;QAC7B,EAAE,GAAG,IAAI,GAAG,QAAQ,GAAG,CAAC,CAAC;QACzB,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;IACpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,SAAS;QAAE,GAAG,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;IAC3F,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,SAAiB;IACxD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/eol.js

@@ -0,0 +1,56 @@
+/**
+ * eol.ts — line-ending helpers so Mindweave's write tools respect a file's (or a
+ * project's) existing style instead of imposing LF.
+ *
+ * The model always emits LF in tool arguments (it can't see a CR). Left alone,
+ * write_file would turn a Windows (CRLF) project into a mix of CRLF and LF files,
+ * and a multi-line `old_string` would fail to match raw CRLF bytes. These
+ * helpers keep the bytes on disk consistent with what's already there.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+/** The dominant line ending of a text blob: CRLF if any CRLF is present, else LF. */
+export function detectEol(sample) {
+    return sample.includes("\r\n") ? "\r\n" : "\n";
+}
+/** Re-encode content to `eol` (normalize to LF first so it's idempotent). */
+export function applyEol(content, eol) {
+    const lf = content.replace(/\r\n/g, "\n");
+    return eol === "\r\n" ? lf.replace(/\n/g, "\r\n") : lf;
+}
+/** The line ending an EXISTING file uses (reads it; LF if unreadable/unknown). */
+export async function fileEol(path) {
+    try {
+        return detectEol(await fs.readFile(path, "utf8"));
+    }
+    catch {
+        return "\n";
+    }
+}
+/**
+ * Best-effort line ending for a NEW file: match a sibling text file in the same
+ * directory, else LF. Bounded and fail-safe so it never blocks or slows a write.
+ */
+export async function dirEol(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const e of entries.slice(0, 20)) {
+            if (!e.isFile())
+                continue;
+            try {
+                const buf = await fs.readFile(join(dir, e.name));
+                const head = buf.subarray(0, 8192).toString("utf8");
+                if (head.includes("\n"))
+                    return detectEol(head);
+            }
+            catch {
+                // Unreadable sibling — try the next one.
+            }
+        }
+    }
+    catch {
+        // No directory yet (or unreadable) — fall through to the default.
+    }
+    return "\n";
+}
+//# sourceMappingURL=eol.js.map

package/dist/tools/eol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eol.js","sourceRoot":"","sources":["../../src/tools/eol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,GAAQ;IAChD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE;gBAAE,SAAS;YAC1B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACpD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;oBAAE,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,yCAAyC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;IACpE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/exitPlan.js

@@ -0,0 +1,175 @@
+import { savePlanArtifact } from "../dynamo/planArtifact.js";
+import { fail, failQuietly } from "./results.js";
+import { readFreeText } from "./approval.js";
+/**
+ * What the user chose at the approval prompt. Order is the display order.
+ *
+ * The "fresh context" pair is the one worth explaining. Planning spends a lot of the
+ * window on exploration — files opened to understand the shape of the problem, searches
+ * that led nowhere — and none of that is needed to CARRY OUT the plan. Choosing fresh
+ * starts the work with the plan as the instruction and nothing else, which is both
+ * cheaper and cleaner than implementing underneath a transcript of the investigation.
+ * Nothing is lost: the session file is still on disk and the model is told where.
+ */
+export const PLAN_CHOICES = [
+    "Approve — Lightning (auto-accept)",
+    "Approve — Lightning, fresh context",
+    "Approve — Sentinel (ask each action)",
+    "Approve — Sentinel, fresh context",
+    "Reject",
+];
+/** The typed answer offered alongside them, for saying what to change. */
+export const PLAN_FEEDBACK = { label: "Change something", placeholder: "say what to change" };
+/**
+ * Read a verdict out of the chosen option (pure).
+ *
+ * Matched by POSITION-INDEPENDENT content rather than exact string equality: the
+ * approval channel can hand back a trimmed or re-cased answer, and an unrecognised
+ * reply must never be read as approval. Anything unknown is a refusal, because the
+ * failure that matters here is acting when nobody said yes.
+ */
+export function readVerdict(choice) {
+    return readDecision(choice).verdict;
+}
+/**
+ * The full decision behind an answer (pure).
+ *
+ * A TYPED answer is always a revision request carrying its text — the user telling the
+ * agent what to change is the one thing the old four-option prompt could not express,
+ * so "Change something" meant "stop and wait for them to say it in a new message",
+ * which cost a whole round trip to learn one sentence.
+ */
+export function readDecision(choice) {
+    const typed = readFreeText(choice);
+    if (typed !== null)
+        return { verdict: "revise", fresh: false, feedback: typed.trim() };
+    const c = choice.trim().toLowerCase();
+    if (c.startsWith("approve")) {
+        return { verdict: c.includes("sentinel") ? "sentinel" : "lightning", fresh: c.includes("fresh") };
+    }
+    if (c.startsWith("change"))
+        return { verdict: "revise", fresh: false };
+    return { verdict: "reject", fresh: false };
+}
+export const exitPlan = {
+    name: "exit_plan",
+    // It writes nothing, but it is not offered outside planning: there is nothing to
+    // exit from in an ordinary turn.
+    readOnly: true,
+    planOnly: true,
+    description: "Present your finished plan to the user and ask them to approve it. Call this when " +
+        "you have researched enough to say exactly what you would change and why — it is how " +
+        "planning ends. " +
+        "Put the WHOLE plan in `plan`: the user reads it here and nowhere else, so it must " +
+        "stand on its own, in the order you would carry it out, naming the files you would " +
+        "touch. Do not summarise it in your reply as well. " +
+        "If the user approves, you begin immediately in the same turn, so write the plan as " +
+        "the instruction you are about to follow. If they decline, stop and wait.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["plan"],
+        properties: {
+            plan: {
+                type: "string",
+                description: "The complete plan, in markdown. Steps in the order you would do them, the " +
+                    "files each one touches, and anything you would need the user to decide.",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const plan = typeof args.plan === "string" ? args.plan.trim() : "";
+        if (!plan)
+            return failQuietly("`plan` is required — put the whole plan in it.");
+        if (!ctx.requestApproval) {
+            return fail("Cannot ask for approval from here, so the plan cannot be started. Present the " +
+                "plan in your reply instead and let the user decide.");
+        }
+        // The plan travels as DETAIL, not as the question. It is the longest thing any
+        // tool asks about, and putting it in the prompt made the frame taller than the
+        // terminal — the screen tore and the app looked hung with no way to answer. As
+        // detail it prints into the transcript, which scrolls, and the prompt stays one
+        // line. Nothing is summarised: the user still reads the whole plan.
+        const choice = await ctx.requestApproval(PLAN_QUESTION, [...PLAN_CHOICES], plan, undefined, PLAN_FEEDBACK);
+        const { verdict, fresh, feedback } = readDecision(choice);
+        if (verdict === "reject") {
+            return {
+                output: "The user rejected the plan. Stop here and do not start any of it. Do not " +
+                    "propose a new plan until they say what they want changed.",
+                summary: "plan rejected",
+            };
+        }
+        if (verdict === "revise") {
+            // With their words, this is a working instruction and the model can revise now.
+            // Without them it is still a full stop, because guessing at what someone meant by
+            // "change something" is how an agent produces a second plan nobody asked for.
+            return feedback
+                ? {
+                    output: `The user did not approve the plan. They want this changed:
+
+${feedback}
+
+` +
+                        "Revise the plan accordingly and present it again with exit_plan. Do not " +
+                        "start any of the work yet.",
+                    summary: "plan sent back with notes",
+                }
+                : {
+                    output: "The user wants the plan changed but has not said how yet. Stop and wait for " +
+                        "them to tell you. Do not guess at a revision or start any part of the plan.",
+                    summary: "plan sent back",
+                };
+        }
+        // Approved. The plan is now the agreed scope of the work, so it becomes a
+        // durable artifact: written to .mindweave/plan.md (user-visible, user-editable,
+        // survives compaction BY CONSTRUCTION because the engine re-renders it from
+        // here every request instead of trusting the transcript) and carried on the
+        // context for this session. A failure to write must not un-approve the plan —
+        // the in-memory copy still governs this session; only persistence is lost.
+        ctx.activePlan = plan;
+        ctx.activePlanApprovedAt = new Date().toISOString();
+        try {
+            await savePlanArtifact(ctx.roots?.[0] ?? ctx.cwd, plan, verdict === "sentinel" ? "sentinel" : "lightning");
+        }
+        catch {
+            // Read-only filesystem or similar: session-local plan still applies.
+        }
+        // Approving ENDS the planning session, and the mode the user picked at the prompt
+        // is the mode they are now in. It used to be lifted for one turn and then forced
+        // back to planning, which had two costs: work that did not finish in a single turn
+        // came back with the editing tools withheld AND the plan no longer in context, so
+        // it needed approving again; and a user who had been in Sentinel before planning
+        // was silently returned to a different mode from the one they chose here.
+        ctx.planMode = false;
+        // Asked for, not done here. Replacing the conversation from inside a tool would
+        // strand the call that is still running: the provider requires every tool_call to
+        // be answered, so the engine performs it once this result has been recorded, and
+        // drops the call and its answer together.
+        if (fresh)
+            ctx.planFreshStart = plan;
+        ctx.guarded = verdict === "sentinel";
+        // A fresh Sentinel pass starts vigilant: an "allow all" from some earlier point in
+        // the session must not silently cover work the user has only just agreed to.
+        if (ctx.guarded)
+            ctx.guardAllowed = undefined;
+        ctx.onModeChange?.();
+        return {
+            output: `The user approved the plan${verdict === "sentinel" ? " and asked to confirm each action" : ""}. ` +
+                `Start now, in this turn, and follow the plan you just presented. ` +
+                `Begin by putting its steps on your task list if there is more than one. ` +
+                (fresh
+                    ? "The conversation from planning has been cleared, so work from the plan itself. " +
+                        "It is repeated in full above. "
+                    : "") +
+                (verdict === "sentinel"
+                    ? "Each change is confirmed with them before it happens, so work in small clear steps. "
+                    : "") +
+                `Do not restate the plan — they have read it.`,
+            summary: verdict === "sentinel" ? "plan approved (Sentinel)" : "plan approved (Lightning)",
+        };
+    },
+};
+/** The prompt itself — one line, because it renders in the height-bounded footer.
+ *  The plan is passed alongside it as detail and printed into the transcript. */
+export const PLAN_QUESTION = "Start on this?";
+//# sourceMappingURL=exitPlan.js.map

package/dist/tools/exitPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exitPlan.js","sourceRoot":"","sources":["../../src/tools/exitPlan.ts"],"names":[],"mappings":"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"}

package/dist/tools/focus.js

@@ -0,0 +1,42 @@
+/**
+ * focus.ts — pure helpers for a file's "focus spans": the line ranges the model has
+ * recently read or edited. When a file is too big to keep whole in the working set,
+ * these spans are what we show (its focused regions) instead of the entire file.
+ *
+ * Kept dependency-free so both the path/ledger layer (paths.ts) and the working-set
+ * renderer (workingSet.ts) can share it without an import cycle.
+ */
+/**
+ * Add a span to a file's focus list, merging overlapping/adjacent ranges and keeping
+ * at most `max` (the most recent). Returns a new array (or undefined when nothing to
+ * track). Pure.
+ */
+export function addFocus(existing, span, max = 4) {
+    if (!span)
+        return existing;
+    const all = [...(existing ?? []), { start: Math.max(1, span.start), end: Math.max(span.start, span.end) }].sort((a, b) => a.start - b.start);
+    const merged = [];
+    for (const s of all) {
+        const last = merged[merged.length - 1];
+        if (last && s.start <= last.end + 1)
+            last.end = Math.max(last.end, s.end);
+        else
+            merged.push({ ...s });
+    }
+    // Keep the most recent (highest-line) spans when over the cap.
+    return merged.slice(-max);
+}
+/**
+ * Is [start..end] wholly inside a span the model is already being shown?
+ *
+ * NOTE: the working set that used to render a large file's focus regions every turn is
+ * gone, so nothing populates the span map any more and this answers "no" in the engine's
+ * own path. Kept because the reasoning is still correct wherever a caller genuinely knows
+ * what is on screen: checked against the focus recorded BEFORE this read, and only ever
+ * used together with an unchanged-file check — a stale region is worse than a duplicated
+ * one. A span map with no producer must never be allowed to suppress content.
+ */
+export function coversSpan(focus, start, end) {
+    return (focus ?? []).some((f) => f.start <= start && f.end >= end);
+}
+//# sourceMappingURL=focus.js.map

package/dist/tools/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../../src/tools/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,QAAiC,EACjC,IAA2B,EAC3B,GAAG,GAAG,CAAC;IAEP,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAC7G,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAC5B,CAAC;IACF,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC;YAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;;YACrE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,+DAA+D;IAC/D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAA8B,EAAE,KAAa,EAAE,GAAW;IACnF,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;AACrE,CAAC"}

package/dist/tools/gitignore.js

@@ -0,0 +1,148 @@
+/**
+ * gitignore.ts — honour .gitignore in the pure-Node walk.
+ *
+ * WHY THIS EXISTS: search has two engines. ripgrep walks the tree itself and is
+ * .gitignore-aware; the Node fallback in walk.ts was not. So the same query
+ * returned different results depending on whether `rg` happened to be installed,
+ * and both tool descriptions stated the gitignore behaviour as universal — true on
+ * one engine, false on the other. Two engines that disagree about what exists is
+ * worse than either behaviour on its own, because nothing in the answer says which
+ * one you got.
+ *
+ * WHAT IS SUPPORTED (the common subset, which is what real .gitignore files use):
+ *   - comments (`#`), blank lines, trailing-space trimming
+ *   - negation (`!pattern`), last match wins, deeper files override shallower ones
+ *   - directory-only rules (`build/`)
+ *   - anchoring: a `/` anywhere but the end anchors to the .gitignore's own
+ *     directory; otherwise the rule matches a basename at any depth
+ *   - `*`, `?`, `**`, and backslash escapes
+ *
+ * NOT supported, deliberately: character classes (`[a-z]`). They are rare in real
+ * ignore files, and a half-right implementation of them would silently hide files,
+ * which is the one failure mode worth avoiding here — an unsupported rule is
+ * treated as matching nothing, so the walk errs toward SHOWING a file rather than
+ * hiding it. Over-showing is visible and correctable; over-hiding looks like the
+ * file does not exist.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+/** Parse .gitignore text into rules. Exported for testing. */
+export function parseGitignore(text) {
+    const rules = [];
+    for (const raw of text.split(/\r?\n/)) {
+        let line = raw;
+        // A comment only counts at the start; `foo#bar` is a real pattern.
+        if (line.startsWith("#"))
+            continue;
+        // Trailing whitespace is stripped unless escaped with a backslash.
+        line = line.replace(/(?<!\\)\s+$/, "");
+        if (line === "")
+            continue;
+        let negated = false;
+        if (line.startsWith("!")) {
+            negated = true;
+            line = line.slice(1);
+        }
+        else if (line.startsWith("\\!")) {
+            line = line.slice(1); // an escaped literal "!"
+        }
+        if (line === "")
+            continue;
+        let dirOnly = false;
+        if (line.endsWith("/")) {
+            dirOnly = true;
+            line = line.slice(0, -1);
+        }
+        if (line === "")
+            continue;
+        // A slash anywhere except the very end anchors the rule to this .gitignore's
+        // directory. Otherwise it matches a basename at any depth.
+        const anchored = line.includes("/");
+        if (line.startsWith("/"))
+            line = line.slice(1);
+        const body = globBody(line);
+        if (body === null)
+            continue; // unsupported syntax — match nothing (see header)
+        const prefix = anchored ? "" : "(?:.*/)?";
+        rules.push({ re: new RegExp(`^${prefix}${body}$`), negated, dirOnly });
+    }
+    return rules;
+}
+/** Translate one gitignore pattern into a regex body, or null if unsupported. */
+function globBody(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "\\") {
+            const next = pattern[i + 1];
+            if (next === undefined)
+                return null; // dangling escape
+            out += escapeRe(next);
+            i++;
+        }
+        else if (c === "[") {
+            return null; // character class — deliberately unsupported, see header
+        }
+        else if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                // `**/` spans zero or more whole segments; a trailing `**` matches the rest.
+                if (pattern[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else {
+            out += escapeRe(c);
+        }
+    }
+    return out;
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Read a directory's .gitignore into a layer, or null when it has none. */
+export async function loadIgnoreLayer(dir) {
+    let text;
+    try {
+        text = await fs.readFile(join(dir, ".gitignore"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const rules = parseGitignore(text);
+    return rules.length ? { base: dir, rules } : null;
+}
+/**
+ * Is `relPath` (posix, relative to the layer's base) ignored by these layers?
+ *
+ * Git's precedence: a deeper .gitignore overrides a shallower one, and within one
+ * file the LAST matching rule wins. So we walk layers deepest-first and return the
+ * first layer that has an opinion.
+ */
+export function isIgnored(layers, isDir) {
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const { layer, rel } = layers[i];
+        let decision = null;
+        for (const rule of layer.rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.re.test(rel))
+                decision = !rule.negated;
+        }
+        if (decision !== null)
+            return decision;
+    }
+    return false;
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/tools/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../src/tools/gitignore.ts"],"names":[],"mappings":"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"}