teapot-coding-agent 0.24.0 → 0.24.2

package/dist/agent/agent.js

@@ -346,10 +346,23 @@ export class Agent {
         return this.manualCompactBudget;
     }
     /**
-     * Long-parking tools (wait_children) flip the visible status to idle so the
-     * operator isn't staring at a running spinner for minutes. The run chain is
-     * still parked inside the tool — but any prompt/stop wakes it immediately.
+     * Is this agent doing work that `stop()` would actually stop?
+     *
+     * `status` cannot answer this on its own. Three states count as live:
+     *   - `running`: the obvious one;
+     *   - a PARKED TOOL: `parkForTool()` flips the visible status to "idle" so a
+     *     multi-minute `wait_children` doesn't look like a running spinner, but
+     *     the loop is very much alive inside the tool;
+     *   - QUEUED PROMPTS: prompts handed to a stopped agent are accepted and held,
+     *     and a later `start()` will consume them.
+     *
+     * Anything keying "should this button stop or start?" off `status` alone
+     * therefore offers **start** on a working agent, and the user cannot stop it
+     * (#59) — the same trap #38 documented for editing history.
      */
+    isLive() {
+        return this.status === "running" || this.parkedByTool || this.pendingPrompts.length > 0;
+    }
     /**
      * A background shell (bash background=true) finished. Two channels:
      * 1. a system_note row in the timeline — the operator sees the outcome
@@ -614,6 +627,15 @@ export class Agent {
         if (msgs.length > 0) {
             this.messages = msgs;
             this.currentBranch = last.branch;
+            // #50: re-apply pruning to the restored history. `maybePrune` clips
+            // oversized tool output IN PLACE, so a live session keeps its clipped
+            // text while the log still holds the full result — a restart therefore
+            // handed the provider a strictly LARGER prompt than the one that had just
+            // succeeded, which is a size regression that only shows up after a
+            // reload. It is a size fix, not a semantic one: the model has already
+            // seen and acted on that output, and the pruned form keeps the head plus
+            // a marker, exactly as it did live.
+            this.maybePrune();
             await this.log.append("system_note", this.currentSession, this.currentBranch, {
                 event: "session-restored",
                 branch: last.branch,
@@ -876,6 +898,17 @@ export class Agent {
             id: this.opts.id,
             status: this.status,
             statusReason: this.statusReason,
+            /**
+             * Is there work in flight that `stop` would actually stop?
+             *
+             * `status` alone is not enough to answer that, and the UI needs it: a
+             * parked tool (`wait_children`) rewrites the status to "idle" while the
+             * loop is very much alive, so a client keying "stop vs start" off
+             * `status === "running"` offered **start** on a running agent and the
+             * user could not stop it (#59). This is the same "running is not the
+             * only live state" fact #38 had to be taught about editing.
+             */
+            live: this.isLive(),
             workspace: this.workspace,
             workspaceMissing: this.workspaceMissing,
             session: this.currentSession,
@@ -1864,18 +1897,37 @@ export class Agent {
                     const text = String(res.message.content ?? "");
                     const approved = /^APPROVED\b/i.test(text.trim());
                     const feedback = text.replace(/^(APPROVED|CHANGES-REQUIRED)\s*[:—-]?\s*/i, "").trim();
-                    await this.setGoalAudit(approved ? "approved" : "changes-required", feedback || "(no detail)");
+                    // #51: storing the literal "(no detail)" made the UI draw a card
+                    // whose whole content was the absence of a reason, and that same
+                    // string landed in goal.md for the right panel. An empty string is
+                    // the honest value: the auditor returned a verdict and no reason,
+                    // which every consumer can already render as "label only".
+                    await this.setGoalAudit(approved ? "approved" : "changes-required", feedback);
+                    // `operatorFacing: true` — the verdict is written for the TIMELINE
+                    // only. The audit ran in its own side conversation (a tools-less call
+                    // over buildMessages() + an audit prompt), so it was never in
+                    // `this.messages` and must not come back through a restore: doing so
+                    // injected an assistant turn that answers nothing into the model's
+                    // context, which providers answer with a 200 and no choices (#50).
+                    // The rejection feedback reaches the agent as a real prompt below.
                     await this.log.append("message", this.currentSession, this.currentBranch, {
                         role: "assistant",
+                        operatorFacing: true,
                         content: approved
                             ? `✅ completion audit: APPROVED — ${feedback}`
                             : `🔍 completion audit: CHANGES REQUIRED — ${feedback}`,
                     });
                     if (!approved) {
-                        // hand the gaps back to the worker as its next instruction
+                        // hand the gaps back to the worker as its next instruction.
+                        // #51: with the "(no detail)" placeholder gone, an empty verdict
+                        // would leave this prompt saying "address these gaps" and then
+                        // naming none — so restate the contract as the thing to re-check.
+                        const gaps = feedback.trim()
+                            ? feedback.slice(0, 2000)
+                            : `The auditor returned no specific gaps. Re-read the verification contract above and re-run it yourself, item by item, before finishing again:\n\n${this.goal.verify?.slice(0, 2000) || this.goal.text.slice(0, 2000)}`;
                         this.pendingPrompts.push({
                             source: "harness",
-                            text: `[harness] The completion audit REJECTED this finish. Address these gaps, then finish again with goalComplete=true:\n\n${feedback.slice(0, 2000)}`,
+                            text: `[harness] The completion audit REJECTED this finish. Address these gaps, then finish again with goalComplete=true:\n\n${gaps}`,
                         });
                     }
                 }
@@ -2152,6 +2204,20 @@ export class Agent {
             phase: "summarizing",
             summarized: oldCount,
         });
+        // #56: the START belongs on the timeline too. Only the right panel showed
+        // compaction, and it reports the *outcome*; a long summarize (hundreds of
+        // thousands of tokens) looks exactly like a hung agent on the timeline,
+        // because the first `context-compacted` event is only appended once the
+        // whole pass is over. Log the announcement as a visible system_note so
+        // the operator sees WHERE the conversation was rewritten, even if the
+        // pass later fails — `before`/`oldCount` are known at this point, and the
+        // completion divider still carries the authoritative after-figures.
+        await this.log.append("system_note", this.currentSession, this.currentBranch, {
+            event: "context-compaction-started",
+            tokensBefore: before,
+            messages: oldCount,
+            reason: force ? "manual" : "auto",
+        });
         this.compactPhase = "summarizing";
         try {
             summary = await this.summarize(old, (text) => {
@@ -2686,13 +2752,28 @@ function rebuildMessagesFrom(list) {
                 msgs.push(mk());
         }
         else if (e.type === "message") {
-            // final summaries are operator-facing only — the live loop never puts
-            // them in model history, so restores must skip them too
-            if (d.final === true)
+            // Operator-facing rows are TIMELINE content, not conversation: the live
+            // loop never put them in `messages`, so a restore must not either.
+            // `final` is the finish() summary; `operatorFacing` covers harness notes
+            // such as the completion audit verdict. Replaying either produced a
+            // history shape no live run emits, and a provider given that answers
+            // 200 with zero choices (#50).
+            if (d.final === true || d.operatorFacing === true)
                 continue;
             const role = d.role === "assistant" ? "assistant" : "user";
-            const m = { role, content: typeof d.content === "string" ? d.content : "" };
-            if (Array.isArray(d.toolCalls) && d.toolCalls.length > 0) {
+            const content = typeof d.content === "string" ? d.content : "";
+            const hasCalls = Array.isArray(d.toolCalls) && d.toolCalls.length > 0;
+            // A blank assistant turn that issued NO tool calls is an artefact of a
+            // kill mid-stream: the model streamed nothing, so the live run never had
+            // this turn, yet the restore replays it as a real utterance. sanitize()
+            // then rewrites blank assistant content to the literal "(no content)",
+            // so the agent is told it previously said a sentence it never said — a
+            // history shape no live run produces (#50). A blank turn that DID call
+            // tools is legitimate and must stay, or its results are orphaned.
+            if (role === "assistant" && !content && !hasCalls)
+                continue;
+            const m = { role, content };
+            if (hasCalls) {
                 m.tool_calls = d.toolCalls.map((c) => ({
                     id: c.id,
                     type: "function",

package/dist/agent/llm.js

@@ -128,6 +128,75 @@ function sanitize(messages) {
         return { ...m };
     });
 }
+/**
+ * Why did the response carry no usable message?
+ *
+ * #50 — this used to be a bare "LLM API returned no choices", which is what
+ * made the report undiagnosable: an empty `choices` array, a 200 carrying an
+ * `error` object, a `delta`-shaped body, and an SSE stream that the SDK
+ * handed back as a plain String all produce the identical line, and none of
+ * them is a useful thing to read in a log.
+ *
+ * The leading text is kept stable at "LLM API returned no choices" so any
+ * existing matching (and the retry notes operators have learned to read)
+ * still works; the diagnosis follows after a colon.
+ */
+function noChoicesDetail(res) {
+    const base = "LLM API returned no choices";
+    // a gateway that answers 200 with an error object instead of failing: the
+    // actionable message is right there and used to be thrown away
+    const err = res?.error;
+    if (err && typeof err === "object") {
+        const msg = typeof err.message === "string" ? err.message : JSON.stringify(err);
+        const code = err.code ?? err.type;
+        return `${base}: provider returned an error in a 200 response${code ? ` (${String(code)})` : ""} — ${String(msg).slice(0, 300)}`;
+    }
+    // the SDK returned raw text — e.g. an SSE body served to a non-streaming
+    // request. JSON.parse succeeds for a real object, so a failure here means we
+    // were handed something that is not a completion at all.
+    if (typeof res === "string") {
+        const head = res.slice(0, 160).replace(/\s+/g, " ").trim();
+        return `${base}: response was not a completion object (${res.length} bytes of ${res.trimStart().startsWith("data:") || res.trimStart().startsWith("event:") ? "SSE" : "text"})${head ? ` — ${head}` : ""}`;
+    }
+    const choices = res?.choices;
+    if (Array.isArray(choices)) {
+        const first = choices[0];
+        if (!first)
+            return `${base}: the provider returned an empty choices array (0 candidates)`;
+        if (first.delta && !first.message) {
+            return `${base}: the provider returned a streaming delta on a non-streaming request (finish_reason=${String(first.finish_reason)})`;
+        }
+        if (first.message === null) {
+            return `${base}: the provider returned a choice with a null message (finish_reason=${String(first.finish_reason)})`;
+        }
+        return `${base}: the provider returned a choice with no message field (finish_reason=${String(first.finish_reason)})`;
+    }
+    return `${base}: the response had no choices array (${safeShape(res)})`;
+}
+/** a short type summary of an unexpected response, for the log line */
+function safeShape(res) {
+    try {
+        const o = res;
+        if (!o || typeof o !== "object")
+            return `got ${typeof res}`;
+        return `keys: ${Object.keys(o).slice(0, 8).join(", ") || "(none)"}`;
+    }
+    catch {
+        return "unreadable response";
+    }
+}
+/**
+ * HTTP statuses that mean "this request shape is not supported here", so
+ * re-issuing it without `stream: true` is a genuinely different request.
+ *
+ * Deliberately an allow-list rather than the whole 4xx range. 408/425/429 are
+ * TRANSIENT: replaying them immediately against an already-saturated provider
+ * just doubles the request count without changing anything. 401/403 mean the
+ * credentials are wrong, which is not fixed by dropping `stream` either — they
+ * are excluded on purpose, since a fallback there would replace one honest
+ * auth error with the same one and a wasted round trip.
+ */
+const STREAM_REJECTED_STATUS = new Set([400, 404, 405, 406, 415, 422, 501]);
 export async function chat(cfg, messages, tools, signal, onDelta) {
     try {
         const res = await client(cfg).chat.completions.create({
@@ -136,10 +205,14 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
             ...(tools.length ? { tools } : {}),
             ...effortForRequest(cfg),
         }, { signal });
-        const raw = res.choices?.[0];
+        // #50: a gateway may answer with `null` (or any non-object) on some proxy
+        // error paths, so the guard is on `rm`, not on `res` being truthy —
+        // reading `res.choices` unguarded threw a bare TypeError that named neither
+        // the provider nor the shape.
+        const raw = res?.choices?.[0];
         const rm = raw?.message;
         if (!rm)
-            throw new Error("LLM API returned no choices");
+            throw new Error(noChoicesDetail(res));
         // normalize: providers attach extra fields (reasoning, refusal, ...) and
         // nullable content — keep only what our protocol understands
         const message = {
@@ -198,6 +271,13 @@ export async function chat(cfg, messages, tools, signal, onDelta) {
     }
     catch (err) {
         const e = err;
+        // #50: our own shape-diagnosis already reads as a full sentence and names
+        // the response it saw. It carries no HTTP status (the request SUCCEEDED —
+        // that is the whole problem), so the generic wrapper below would have
+        // relabelled it "LLM API error ?: …", hiding both the diagnosis and the
+        // fact that no status was ever involved.
+        if (String(err.message ?? "").startsWith("LLM API returned no choices"))
+            throw err;
         if (e.status === undefined && !String(err.message).includes("provider returned"))
             throw err; // not an API error (abort, bug, ...)
         const detail = e.error?.message ?? e.message ?? "unknown provider error";
@@ -284,14 +364,58 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
                         function: { name: c.name, arguments: c.args || "{}" },
                     }];
             });
-        if (!message.content && !message.tool_calls)
-            throw new Error("LLM API error: empty completion");
+        if (!message.content && !message.tool_calls) {
+            // #50: a stream that opened, produced NOTHING, and closed cleanly. The
+            // throw carries a marker so the handler below can tell this apart from a
+            // request the provider actively rejected: this one is a broken/flaky
+            // proxy, and re-issuing it without `stream` is a genuinely different
+            // request that usually succeeds. Throwing a bare Error would make the two
+            // indistinguishable and cost us that safety net.
+            const e = new Error("LLM API error: empty completion");
+            e.emptyStream = true;
+            throw e;
+        }
         return { message, reasoning: reasoning || undefined, usage };
     }
     catch (err) {
-        // provider may not support streaming at all — one clean fallback
-        if (!gotChunk && !signal?.aborted)
+        // #50 — a provider that doesn't support streaming at all still gets ONE
+        // clean fallback, but ONLY when the streaming attempt produced nothing for
+        // a reason that could plausibly be the stream itself.
+        //
+        // The old condition was `!gotChunk && !signal?.aborted`, which also matched
+        // a request that FAILED — a gateway answering 200 with an SSE `error`
+        // frame, or a context-length rejection. In those cases the fallback
+        // re-issued the same oversized request in a different shape, and the
+        // resulting "LLM API returned no choices" replaced the real diagnosis.
+        // That is why a restored 1500-message session reported "no choices" three
+        // times and then errored: the genuine "context length exceeded" was
+        // discarded on the first attempt and could never be recognised by
+        // isContextOverflow(), so the compact-and-retry recovery never ran.
+        //
+        // Two exclusions, and the second one matters as much as the first:
+        //
+        //  1. A status that means the REQUEST ITSELF was rejected. Only then is
+        //     re-issuing it without `stream` a different request rather than the
+        //     same failing one. `400`/`404`/`405`/`422` are the shapes a provider
+        //     uses to say "no streaming here" — deliberately NOT the whole 4xx
+        //     range, because 408/425/429 are transient: replaying those against an
+        //     already-saturated provider just doubles the request count.
+        //  2. A THROWN error, as opposed to a request that simply produced no
+        //     chunks. A 200 that streams zero chunks and closes cleanly is a
+        //     broken/flaky proxy, and that is precisely the case the non-streaming
+        //     retry rescues. Requiring a 4xx here would have deleted that safety
+        //     net — a regression this file's own tests caught.
+        //
+        // So the fallback runs when the request was rejected outright, OR when it
+        // completed without error and without a single chunk. Everything else —
+        // 5xx, an error frame, a mid-stream failure — is the ANSWER, rethrown
+        // untouched so overflow recovery can see it.
+        const status = err?.status;
+        const rejectedByProvider = typeof status === "number" && STREAM_REJECTED_STATUS.has(status);
+        const emptyStream = err?.emptyStream === true;
+        if (!gotChunk && !signal?.aborted && (rejectedByProvider || emptyStream)) {
             return chat(cfg, messages, tools, signal, onDelta);
+        }
         // user interrupt: hand back whatever streamed so far so the harness can
         // keep the partial output visible instead of losing it
         if (signal?.aborted && (text || reasoning)) {

package/dist/agent/tools.js

@@ -182,7 +182,13 @@ function startBackgroundShell(cmd, ctx) {
  *  Wording varies by provider (OpenRouter/OpenAI/Anthropic/local servers). */
 export function isContextOverflow(err) {
     const msg = String(err?.message ?? "").toLowerCase();
-    return (/context (length|window|limit)|too many tokens|prompt is too long|max.{0,12}tokens.{0,20}(exceed|surpass)|request too large|payload too large|exceeds.{0,20}limit/.test(msg) || /\b(400|413)\b.*token/.test(msg));
+    return (/context (length|window|limit)|too many tokens|prompt is too long|max.{0,12}tokens.{0,20}(exceed|surpass)|request too large|payload too large|exceeds.{0,20}limit/.test(msg) ||
+        /\b(400|413)\b.*token/.test(msg) ||
+        // #50: some gateways answer an over-long request with HTTP 200 and put the
+        // real diagnosis in the body, which llm.ts now surfaces after the "no
+        // choices" prefix. Without this the compact-and-retry recovery never
+        // recognised it and the turn simply failed.
+        /no choices:[\s\S]{0,300}context (length|window|limit)/.test(msg));
 }
 /** Any background shell still running for this workspace? The auto-continue
  *  loop consults this before nudging a finished round: an agent that parked
@@ -709,10 +715,43 @@ export function hashLine(content) {
 }
 /** `LINE:HASH| content` for each line, 1-indexed */
 export function renderHashlines(lines, startLine = 1) {
-    return lines
+    // same trailing-newline rule as renderGutter (#7): a file ending in "\n"
+    // splits into a final "" that is not a line, and an anchor for it is a lie
+    // the model can copy into an edit that then never verifies
+    const body = lines.length && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
+    return body
         .map((l, i) => `${startLine + i}:${hashLine(l)}| ${l}`)
         .join("\n");
 }
+/**
+ * Width of the `N| ` gutter for a page, so every line in it lines up.
+ *
+ * #7: the prefix had no padding, so the gutter silently widened at line 1000
+ * and the whole block jumped sideways mid-file — the exact "unfriendly line
+ * numbers" complaint. Padding to the widest number IN THE PAGE is enough: a
+ * page is a bounded window, and aligning to the file's total length would
+ * push every line of a 20-line read of a 500k-line file 6 characters right.
+ */
+export function gutterWidth(startLine, count) {
+    return String(Math.max(0, startLine - 1) + count).length;
+}
+/**
+ * The default `N| ` display, with a stable gutter width and no phantom line.
+ *
+ * #7, second half: the prefix was added AFTER `text.split("\n")`, so a file
+ * ending in a newline produced a final numbered row for a line that does not
+ * exist. A model that copies the tail verbatim then hands `edit_file` an
+ * old_text with a phantom line in it, and the edit fails for no visible reason.
+ * A trailing empty element is dropped, which is what the reader means.
+ */
+export function renderGutter(lines, startLine = 1) {
+    // a trailing newline splits into a final "" — not a line of the file
+    const body = lines.length && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
+    if (!body.length)
+        return "";
+    const w = gutterWidth(startLine, body.length);
+    return body.map((l, i) => `${String(startLine + i).padStart(w)}| ${l}`).join("\n");
+}
 /** parse a `LINE:HASH` anchor; returns null when the text is not an anchor */
 export function parseAnchor(anchor) {
     const m = /^\s*(\d+):([0-9a-z]{4,8}| {4})\s*$/.exec(anchor);
@@ -913,7 +952,7 @@ export const TOOLS = [
                 }
                 const parts = regions.map(([s, e]) => idMode === "hash"
                     ? renderHashlines(lines.slice(s, e + 1), s + 1)
-                    : lines.slice(s, e + 1).map((l, k) => `${s + k + 1}| ${l}`).join("\n"));
+                    : renderGutter(lines.slice(s, e + 1), s + 1));
                 let result = parts.join("\n--\n");
                 if (idxs.length > page.length || off > 0)
                     result += `\n(${off + 1}–${off + page.length} of ${idxs.length} matches)`;
@@ -924,8 +963,11 @@ export const TOOLS = [
             off = off < 0 ? Math.max(0, lines.length + off) : Math.max(0, off - 1);
             const lim = num(args.limit, 2000);
             const pageLines = lines.slice(off, off + lim);
-            const slice = idMode === "hash" ? renderHashlines(pageLines, off + 1) : pageLines.map((l, i) => `${off + i + 1}| ${l}`).join("\n");
-            const more = off + lim < lines.length ? `\n... (${lines.length - off - lim} more lines)` : "";
+            const slice = idMode === "hash" ? renderHashlines(pageLines, off + 1) : renderGutter(pageLines, off + 1);
+            // the phantom trailing line is dropped for the count too, or a file that
+            // ends in a newline always reports one line more than it has
+            const total = lines.length && lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
+            const more = off + lim < total ? `\n... (${total - off - lim} more lines)` : "";
             return { ok: true, result: slice + more };
         },
     },
@@ -1090,12 +1132,27 @@ export const TOOLS = [
             // already proved which lines it means, so a block whose content occurs
             // twice must still edit the anchored occurrence rather than fail the
             // uniqueness check (#4).
+            // The hashline path splits on "\n" to index by resolved line number, which
+            // leaves a trailing "\r" on every line of a CRLF file. Rejoining with
+            // "\n" then DROPS all of them, so a single edit silently rewrote a
+            // Windows file's line endings: the replaced line arrived with the model's
+            // "\n" while every untouched line kept its "\r\n". The file still parsed
+            // and the edit "succeeded", so nothing reported it — but the next
+            // checkout diff shows the whole file changed, and tools that normalise on
+            // EOL (git, prettier, formatters) now rewrite it.
+            //
+            // So the EOL is detected ONCE from the untouched text and re-applied to
+            // the replacement, which also keeps a CRLF file CRLF when the model sends
+            // LF-separated new_text (the overwhelmingly common case — models never
+            // emit \r).
+            const eol = text.includes("\r\n") ? "\r\n" : "\n";
             const out = hashSpan
                 ? text
                     .split("\n")
                     .slice(0, hashSpan.start)
-                    .concat(newText.split("\n"), text.split("\n").slice(hashSpan.end))
+                    .concat(newText.replace(/\r\n/g, "\n").split("\n"), text.split("\n").slice(hashSpan.end))
                     .join("\n")
+                    .replace(/(?<!\r)\n/g, eol)
                 : replaceAll
                     ? text.split(oldText).join(newText)
                     : text.replace(oldText, newText);

package/dist/log/events.js

@@ -156,3 +156,132 @@ export async function readEvents(filePath) {
         return [];
     }
 }
+/** Default floor for a tail read, so a small `limit` cannot cause a tiny read. */
+const TAIL_MIN_BYTES = 64 * 1024;
+/**
+ * Read only the LAST `limit` events from an append-only JSONL log.
+ *
+ * #59: the web UI polls this endpoint every ~120 ms for the selected agent, and
+ * the full re-parse cost 348 ms on a 57 MB / 200 000-event log. The mtime cache
+ * could not help — a RUNNING agent appends constantly, so `size` and `mtimeMs`
+ * change on every single request and the cache only ever helped stopped agents.
+ *
+ * The log is strictly append-only: `EventLog.append` is the only writer and
+ * always writes a whole `JSON.stringify(evt) + "\n"` under a serialized chain,
+ * so an append never rewrites earlier bytes. That makes a tail read safe, and
+ * makes byte-offset caching legitimate.
+ *
+ * Anchored to the tail deliberately. The read starts at a byte offset chosen for
+ * the file's current size, so the FIRST line it sees is usually a fragment —
+ * dropped. `bytesScanned` is reported so callers (and tests) can assert the read
+ * really was partial rather than trusting a wall-clock number.
+ */
+export async function readEventsTail(filePath, limit) {
+    const empty = { events: [], total: 0, bytesScanned: 0, truncated: false };
+    if (limit <= 0)
+        return empty;
+    let fh = null;
+    try {
+        const fsp = await import("node:fs/promises");
+        fh = await fsp.open(filePath, "r");
+        const st = await fh.stat();
+        if (st.size === 0)
+            return empty;
+        // grow the window until it holds `limit` whole lines. Start at a floor so a
+        // small limit still reads a sensible block, then double — bounded by the
+        // file size, because a pathological file must not make us read forever.
+        let want = Math.min(st.size, Math.max(TAIL_MIN_BYTES, limit * 512));
+        for (;;) {
+            const r = await readWindow(fh, st.size, want);
+            if (r.events.length >= limit || want >= st.size) {
+                return {
+                    events: r.events.slice(-limit),
+                    // `total` is an APPROXIMATE count: only the window was parsed, so this
+                    // is "at least this many". /events uses it for the "load older" hint,
+                    // where approximate is fine — an exact count would mean reading the
+                    // entire file, which is the cost this function exists to avoid.
+                    total: r.events.length,
+                    bytesScanned: r.bytes,
+                    truncated: r.bytes < st.size,
+                };
+            }
+            want = Math.min(st.size, want * 4);
+        }
+    }
+    catch {
+        return empty;
+    }
+    finally {
+        await fh?.close().catch(() => { });
+    }
+}
+/** read the last `bytes` of the file, dropping the leading partial line */
+async function readWindow(fh, size, bytes) {
+    const start = Math.max(0, size - bytes);
+    const buf = Buffer.alloc(size - start);
+    if (buf.length)
+        await fh.read(buf, 0, buf.length, start);
+    const text = buf.toString("utf8");
+    const nl = text.indexOf("\n");
+    // the first line is a fragment unless we started at 0
+    const body = start > 0 ? (nl === -1 ? "" : text.slice(nl + 1)) : text;
+    const events = [];
+    for (const line of body.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            /* torn or corrupt line: skip it, never return a fragment */
+        }
+    }
+    return { events, bytes: buf.length };
+}
+/**
+ * Keep one branch's rows out of a timeline, optionally including the history it
+ * inherited before it forked.
+ *
+ * #38. A fork is a new timeline, but the agent's CONTEXT on it still includes
+ * everything before the fork point — `rebuildMessagesFrom` walks the parent
+ * chain across branch boundaries precisely so a restarted fork keeps its
+ * history. Filtering the view by strict equality therefore showed *less* than
+ * the model actually reasons over, which is why a filtered fork looked like
+ * data loss even though nothing was missing from the log.
+ *
+ * `includeInherited` walks the parent links out of the branch's own events and
+ * keeps everything they reach, so the view matches the model's context. Strict
+ * remains the default: a caller that genuinely wants only a branch's own rows
+ * (counting, auditing) should not be handed inherited history silently.
+ *
+ * Pure and exported so the rule can be tested without an HTTP server.
+ */
+export function filterByBranch(events, branch, includeInherited = false) {
+    if (!includeInherited)
+        return events.filter((e) => e.branch === branch);
+    const byId = new Map(events.map((e) => [e.id, e]));
+    // every event belonging to the branch, plus everything reachable by `parent`
+    const wanted = new Set();
+    // A WORKLIST, not a loop over the growing set: iterating `wanted` while
+    // adding to it inside the same pass re-visits nodes and, on a parent cycle,
+    // never terminates.
+    const queue = [];
+    for (const e of events) {
+        if (e.branch !== branch)
+            continue;
+        if (wanted.has(e.id))
+            continue;
+        wanted.add(e.id);
+        queue.push(e.id);
+    }
+    while (queue.length) {
+        const cur = byId.get(queue.pop());
+        // walk up through the fork boundary — a fork's parent is the last event of
+        // the SOURCE branch, and that branch's history is inherited too
+        if (cur?.parent && !wanted.has(cur.parent)) {
+            wanted.add(cur.parent);
+            queue.push(cur.parent);
+        }
+    }
+    return events.filter((e) => wanted.has(e.id));
+}

package/dist/server/api.js

@@ -51,7 +51,7 @@ async function listModels(baseUrl, apiKey) {
 }
 import path from "node:path";
 import { bus } from "../bus.js";
-import { readEvents } from "../log/events.js";
+import { readEvents, readEventsTail, filterByBranch } from "../log/events.js";
 /** media categories the file tree can preview inline */
 const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif"]);
 const VIDEO_EXT = new Set(["mp4", "webm", "mov", "mkv", "avi", "m4v"]);
@@ -943,7 +943,14 @@ export function buildApp(master) {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
             return c.json({ error: "not found" }, 404);
-        const limit = Math.min(Number(c.req.query("limit") ?? 200), 5000);
+        // #54: the frontend pairs a tool_call with its tool_result by walking the
+        // events it holds, so a window that can contain a result WITHOUT its call
+        // strands the bash row at "waiting for output…" forever — the call scrolled
+        // out while the command was still running. 200 was small enough to hit this
+        // on any moderately long command. The default is now sized to hold a whole
+        // pair even when thousands of events land in between (a long stream logs one
+        // per delta); the server clamps hard, so a caller asking for more is cheap.
+        const limit = Math.min(Number(c.req.query("limit") ?? 2000), 20000);
         let filePath = a.log.filePath;
         // ?session=<internalId> reads ANY session owned by this agent (past
         // incarnations too) — the internal id, not the agent id, is the stable
@@ -955,12 +962,22 @@ export function buildApp(master) {
                 return c.json({ error: "not found" }, 404);
             filePath = path.join(rec.dir, "chat.jsonl");
         }
-        let events = await readEventsCached(filePath);
+        // #59: the plain "latest N" request is what the UI polls every ~120 ms for
+        // a RUNNING agent, and it is the one that does NOT need history — it serves
+        // it from a tail read that scans ~2% of the file. `?before` (older pages)
+        // and `?branch` genuinely need the whole log, so they keep the full parse.
+        // `total` is a lower bound on the tail path (see readEventsTail) and is
+        // only used for the "load older" affordance, where approximate is fine.
         const branch = c.req.query("branch");
+        const before = c.req.query("before");
+        if (!before && !branch) {
+            const tail = await readEventsTail(filePath, limit);
+            return c.json({ events: tail.events, total: tail.total, partial: tail.truncated });
+        }
+        let events = await readEventsCached(filePath);
         if (branch)
-            events = events.filter((e) => e.branch === branch);
+            events = filterByBranch(events, branch, c.req.query("lineage") === "true");
         // cursor pagination for older pages: everything strictly BEFORE this id
-        const before = c.req.query("before");
         if (before) {
             const idx = events.findIndex((e) => e.id === before);
             events = idx === -1 ? [] : events.slice(0, idx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teapot-coding-agent",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "A lightweight, always-on multi-agent harness for AI coding agents",
   "type": "module",
   "license": "AGPL-3.0-or-later",