teapot-coding-agent 0.26.14 → 0.27.1

package/README.md

@@ -6,8 +6,6 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/akku1139/teapot)
 
-[日本語版はこちら](README.ja.md)
-
 ---
 
 ## 🚀 Quick start
@@ -167,7 +165,7 @@ Agents can run `bash` and rewrite files — including `rm` and `npm install`.
 
 - Designed to run under a **dedicated Linux user**
 - `git commit` before handing over a repo you care about
-- File operations outside the workspace are rejected (`safeJoin`)
+- File operations outside the workspace are rejected (`safeJoin`), but agents can use `bash` outside of the worktree
 - teapot listens on localhost only by default. If you expose it, set **both** `--host 0.0.0.0` and an API token (`TEAPOT_API_TOKEN` env or config `password`):
 
 ```sh

package/dist/agent/agent.js

@@ -1227,23 +1227,48 @@ export class Agent {
             }
             if (p.source === "user") {
                 const id = p.id ?? `u${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
-                this.deliveredPrompts.push(id);
-                // cap: UI only needs recent confirmations
-                if (this.deliveredPrompts.length > 64)
-                    this.deliveredPrompts.shift();
-                void this.log
-                    .append("system_note", this.currentSession, this.currentBranch, {
-                    event: "prompt-delivered",
-                    promptId: id,
-                    preview: p.text.slice(0, 80),
-                })
-                    .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
-                    .catch(() => { });
+                // #37: queued here, MARKED at the request boundary instead — see
+                // markDeliveredPrompts(). Text is kept so the marker can carry the same
+                // preview the UI shows.
+                this.undeliveredPrompts.push({ id, preview: p.text.slice(0, 80) });
             }
         }
     }
     /** ids of user prompts that have entered an LLM call payload (recent first-capped) */
     deliveredPrompts = [];
+    /**
+     * User prompts consumed from the queue but not yet MARKED as delivered (#37).
+     *
+     * They are drained at a turn boundary, but the `prompt-delivered` marker must
+     * wait until the request that carries them actually starts — which is later,
+     * and after `maybeCompact()`, which can itself call the LLM.
+     */
+    undeliveredPrompts = [];
+    /**
+     * Log `prompt-delivered` for every prompt whose outbound request is starting.
+     *
+     * #37: the marker's meaning is "the request carrying this prompt has begun".
+     * It used to fire in drainPendingPrompts, i.e. before the request, so the
+     * timeline reordered by a moment the API never saw.
+     */
+    async markDeliveredPrompts() {
+        if (this.undeliveredPrompts.length === 0)
+            return;
+        const pending = this.undeliveredPrompts;
+        this.undeliveredPrompts = [];
+        for (const { id, preview } of pending) {
+            this.deliveredPrompts.push(id);
+            // cap: the UI only needs recent confirmations
+            if (this.deliveredPrompts.length > 64)
+                this.deliveredPrompts.shift();
+            await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                event: "prompt-delivered",
+                promptId: id,
+                preview,
+            });
+        }
+        bus.emit("update", { kind: "agent-update", agentId: this.opts.id });
+    }
     /**
      * Background jobs that exited since the last LLM call. Their outcomes are
      * folded into ONE harness message at the turn boundary — the agent learns
@@ -1366,9 +1391,25 @@ export class Agent {
     stopSeq = 0;
     /** #95: set when this round already injected a harness progress request */
     progressRequestedThisRound = false;
+    /**
+     * CONTROL PLANE: fired on every status change, immediately, independent of the
+     * log.
+     *
+     * #126: `wait_children` wakeups used to ride `EventLog.onEvent`, so a status
+     * change reached the parent only AFTER the write completed. After the
+     * write-before-notify fix that meant a FAILED or slow write left a parked parent
+     * waiting forever — persistence latency became control flow. Measured with every
+     * write failing: `onEvent fired: 0`, so no wakeup at all.
+     *
+     * Control flow must not depend on durability, so this is separate from the
+     * event pipeline. The log's `onEvent` now means "persisted, tell the world";
+     * this means "my state changed, react now".
+     */
+    onControlStatusChange = null;
     setStatus(s, reason = "") {
-        // Update the field FIRST. log.append fires onEvent synchronously, and the
-        // master's child-event hook wakes parked wait_children callers — those
+        // Update the field FIRST. The control-plane hook fires synchronously below
+        // (see onControlStatusChange), and it is what wakes parked wait_children
+        // callers — those
         // re-check agent.status at that instant. Updating after the append made
         // every waiter observe the OLD status ("running"), conclude "someone is
         // still working", and stay parked until timeout even though the child had
@@ -1377,6 +1418,15 @@ export class Agent {
         this.status = s;
         this.statusReason = reason;
         if (prev !== s) {
+            // #126: control plane FIRST, and not via the log. A parent's wait_children
+            // must wake on the status change itself, not on the durability of the write
+            // that records it.
+            try {
+                this.onControlStatusChange?.(this.opts.id, s);
+            }
+            catch {
+                /* a control-plane listener must never break a status change */
+            }
             void this.log.append("state", this.currentSession, this.currentBranch, {
                 from: prev,
                 to: s,
@@ -1591,6 +1641,27 @@ export class Agent {
                     text: "",
                     reasoning: "",
                 });
+            // #37: `prompt-delivered` must mean "the outbound request CARRYING this
+            // prompt has started", not "the prompt moved from the queue into
+            // `this.messages`".
+            //
+            // It used to be logged in drainPendingPrompts, which runs BEFORE
+            // refreshSkills, maybeRequestProgress and — critically — maybeCompact. So
+            // the marker preceded the request, and `maybeCompact()` can itself make an
+            // LLM call, which meant the timeline claimed a delivery order the API never
+            // saw. Measured before the fix:
+            //
+            //     LLM CALL #1
+            //       seq=5  prompt-delivered("first prompt")
+            //       seq=6  llm turn start
+            //
+            // The UI reorders by this marker (resequenceToDelivery), so the semantics
+            // were the bug — not timeline-order.ts.
+            //
+            // Emitted ONCE per request, not per attempt: a retry sends the same payload,
+            // so re-emitting would move the marker after a later event on each try.
+            if (attempt === 1)
+                await this.markDeliveredPrompts();
             try {
                 return await this.callLlm(messages, tools, onDelta);
             }

package/dist/agent/tools.js

@@ -1192,8 +1192,18 @@ export const TOOLS = [
                 return stale;
             let oldText = str(args.old_text);
             const newText = str(args.new_text);
+            // #126: the single most common edit_file failure in the real logs (22
+            // occurrences) said only "old_text is required", while the tool's own
+            // schema already documents the better form. Name it and say what to do —
+            // the pattern master.ts uses for "not your sub-agent" (master.ts:979),
+            // which turned a confusing refusal into a re-addressable one.
             if (!oldText)
-                return { ok: false, result: "old_text is required" };
+                return {
+                    ok: false,
+                    result: "old_text is required — pass the exact text to replace, or read with " +
+                        '`read_file({line_ids:"hash"})` and pass that block VERBATIM as old_text. ' +
+                        "Do NOT copy read_file's `N| ` line-number prefixes.",
+                };
             const replaceAll = args.replace_all === true;
             // #7/#4: accept a block copied straight out of read_file's hashline
             // output. When the anchors do not verify we FAIL with the specific reason
@@ -1654,11 +1664,14 @@ export const TOOLS = [
     },
     {
         name: "message_agent",
-        description: "Send a message to a specific sub-agent (steer it mid-flight or answer its ask_user question).",
+        description: "Send a message to another agent. Use it to steer a sub-agent mid-flight, to answer its " +
+            "ask_user question, or to message your OWN PARENT (pass its id) — a sub-agent may ask its " +
+            "parent a question or hand back a partial result, which is how you report progress without " +
+            "ending your turn. You may NOT message a sibling or an unrelated agent.",
         parameters: {
             type: "object",
             properties: {
-                id: { type: "string", description: "sub-agent id" },
+                id: { type: "string", description: "sub-agent id, or your parent's id" },
                 text: { type: "string" },
             },
             required: ["id", "text"],

package/dist/log/events.js

@@ -89,12 +89,25 @@ export class EventLog {
             data,
         };
         this.lastByBranch.set(branch, evt.id);
-        try {
-            this.onEvent?.(evt);
-        }
-        catch {
-            /* observer must never break the log */
-        }
+        // #54: WRITE FIRST, then notify.
+        //
+        // The observer used to fire BEFORE the write. The frontend receives a
+        // `kind:"event"` frame and — by design — treats it as "something changed"
+        // and re-reads `/events`. So the reload could read the log BEFORE this
+        // event reached disk, and the reload would simply not contain it.
+        //
+        // Measured against a real EventLog, reloading on every notification:
+        //
+        //     appends: 30   WS-triggered reloads that MISSED the event: 30
+        //
+        // The 120ms debounce usually hides this, which is exactly why #54 felt
+        // random: a slow write misses, a fast one lands. Notifying after the write
+        // makes the event visible to any reader the observer triggers.
+        // `written` distinguishes a REAL write from the post-close drop path, which
+        // also resolves. #54: announcing a dropped event would tell the frontend to
+        // reload for something that will never appear — the row would flicker in and
+        // straight back out.
+        let written = false;
         const p = new Promise((resolve, reject) => {
             this.chain = this.chain.then(() => {
                 if (!this.stream) {
@@ -103,10 +116,31 @@ export class EventLog {
                     console.error(`[teapot] event dropped after log close (${this.agentId}): ${type}`);
                     return resolve(evt);
                 }
-                this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => err ? reject(err) : resolve(evt));
+                this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => {
+                    if (err)
+                        return reject(err);
+                    written = true;
+                    resolve(evt);
+                });
             }, () => resolve(evt));
         });
         this.chain = this.chain.then(() => { }, () => { });
+        // notify once the write is handed to the OS, so a reload the observer
+        // triggers can actually see this event
+        void p
+            .then(() => {
+            if (!written)
+                return; // dropped after close: nothing on disk to announce
+            try {
+                this.onEvent?.(evt);
+            }
+            catch {
+                /* observer must never break the log */
+            }
+        })
+            .catch(() => {
+            /* a failed write must not notify — the event is not on disk */
+        });
         return p;
     }
     lastEventId(branch) {

package/dist/master.js

@@ -16,6 +16,8 @@ import { bus } from "./bus.js";
 import { fetchModelList, contextLengthFor, isReasoningEffort, } from "./model-meta.js";
 /** how deep sub-agent spawning may nest (parent=0, its subs=1, …) */
 const MAX_SPAWN_DEPTH = 3;
+/** statuses that mean a child has finished working, for #130 */
+const SETTLED = new Set(["idle", "stopped", "waiting", "error"]);
 /**
  * Skills shipped with the package — resolved relative to this module so it
  * works from a global `npm install -g` install, an npx cache, or a repo
@@ -259,6 +261,14 @@ export class Master {
     replacementPid = null;
     tasks = [];
     childWaiters = new Map();
+    /**
+     * Children that have actually started, for #130.
+     *
+     * A child is `idle` between `addAgent` and `start()`, and that is its FIRST
+     * status transition — so without this the parent is told a brand-new sub-agent is
+     * idle before it has done anything.
+     */
+    reportedRunning = new Set();
     startedAt = Date.now();
     config;
     configPath;
@@ -524,6 +534,47 @@ export class Master {
             bus.emit("update", { kind: "event", agentId: e.agent, event: e });
             this.onChildEvent(ac, e);
         };
+        // #126: the CONTROL PLANE, separate from the event pipeline above.
+        //
+        // `onChildEvent` used to be what woke a parent's `wait_children`, and it runs
+        // after the event is persisted. So a failed or slow write left the parent
+        // parked forever — measured with every write failing, the wake never fired.
+        //
+        // A status change is CONTROL FLOW, not an observation, so it gets its own
+        // immediate path. `onChildEvent` keeps its other job (mirroring the child's
+        // activity into the parent's timeline, forwarding its final report), which
+        // legitimately belongs to the event stream.
+        agent.onControlStatusChange = (agentId, status) => {
+            if (!ac.parent)
+                return;
+            const parent = this.agents.get(ac.parent);
+            if (!parent)
+                return;
+            // the waiter re-checks whether ITS targets are all settled, so waking on
+            // every movement is correct and cheap
+            this.wakeParentWaiters(ac.parent);
+            // #130: only report a SETTLED child, never its birth.
+            //
+            // A freshly spawned child is `idle` for a moment before `start()` runs, and
+            // the FIRST status transition it ever makes is therefore idle->running via
+            // that idle. Reporting it told the parent "[harness] @kid is now idle" the
+            // instant the child existed — before it had done anything at all. Measured:
+            // transitions after a spawn are ["idle","running","idle"], so the first is
+            // always the spurious one.
+            //
+            // So the message waits for a child that has actually STARTED. A real
+            // completion still reports (it goes running -> idle), and the wake above is
+            // unconditional, so `wait_children` is unaffected either way.
+            // #130: a spawned child is `idle` until start() runs, and that lazy-load
+            // flip is its FIRST transition — so requiring a prior `running` is what stops
+            // the parent being told the child settled before it began.
+            if (this.reportedRunning.has(agentId) && SETTLED.has(status))
+                parent.enqueuePrompt(`[harness] @${agentId} is now ${status}. Continue your task, or finish() if the work is done.`, "harness");
+            if (status === "running")
+                this.reportedRunning.add(agentId);
+            else if (SETTLED.has(status))
+                this.reportedRunning.delete(agentId);
+        };
         // sub-agent management hooks — only when this agent can legally spawn
         if (myDepth < this.maxSpawnDepth()) {
             const self = agent;
@@ -788,8 +839,32 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
         const owned = this.sessionById(childId);
         if (owned)
             targetId = owned.agentId;
-        const cfg = this.config.agents.find((a) => a.id === targetId);
-        if (!cfg || cfg.parent !== parentId) {
+        // #132: a sub-agent must be able to message its OWN PARENT.
+        //
+        // The rule below only ever permitted parent -> child, so a child asking its
+        // parent a question was refused with the actively misleading
+        //
+        //     not your sub-agent: p1. no such sub-agent exists.
+        //
+        // — naming the parent as nonexistent, when it is the caller's own parent and
+        // plainly listed in config.agents. The parent link is the trust boundary: a
+        // child may address its parent, a parent may address its children, and
+        // NOTHING may address a sibling or an unrelated agent.
+        const caller = this.config.agents.find((a) => a.id === parentId);
+        const target = this.config.agents.find((a) => a.id === targetId);
+        const childToParent = target?.parent === parentId;
+        if (target && caller?.parent === targetId) {
+            const p = this.agents.get(targetId);
+            if (!p)
+                throw new Error(`sub-agent not running: ${targetId}`);
+            // mirrored wording, so the recipient knows who is writing
+            p.enqueuePrompt(`[harness] Message from sub-agent @${parentId}:\n\n${text}`, "harness");
+            if (p.status !== "running")
+                p.start(`message from sub-agent ${parentId}`);
+            return;
+        }
+        const cfg = target;
+        if (!cfg || (!childToParent && cfg.parent !== parentId)) {
             // Scoping is correct — only the DIRECT parent may message a child, so a
             // grandchild is rightly refused. But "not your sub-agent: <id>" reads
             // like a bug when the agent simply guessed the wrong level of the tree.
@@ -842,9 +917,18 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             // silently dropped exactly the details the operator spawned the sub
             // to gather. Context management is compaction's job, not the pipe's.
             `[harness] Sub-agent ${ac.id} finished. Final report:\n${report || "(no summary)"}`, "harness");
+            // #123: a parent's report is delivered INTO a live agent — queueing it is
+            // not enough. If the parent is idle (finished, or parked) the report sat in
+            // the queue until something else started the loop, so the operator saw a
+            // finished sub-agent and a parent that never reacted.
+            if (parent.status !== "running")
+                parent.start(`sub-agent ${ac.id} finished`);
         }
         else if (e.type === "error") {
             parent.enqueuePrompt(`[harness] Sub-agent ${ac.id} hit an error: ${String(e.data.message ?? "").slice(0, 500)}`, "harness");
+            // #123: same for an error report
+            if (parent.status !== "running")
+                parent.start(`sub-agent ${ac.id} error`);
         }
         // #63: a child's activity is NOT mirrored into the parent's log.
         //

package/dist/server/api.js

@@ -525,14 +525,18 @@ export function buildApp(master) {
     app.get("/api/agents/:id/tree", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const rel = c.req.query("path") || ".";
         let abs;
         try {
             abs = safeJoin(a.workspace, rel);
         }
         catch (err) {
-            return c.json({ error: err.message }, 400);
+            // #126: safeJoin's message embeds the RESOLVED absolute path
+            // ("path escapes workspace: /home/user/secret/project/…"), so returning it
+            // verbatim hands the caller the server's directory layout. The rejection is
+            // correct; the disclosure was not. Echo back the path AS GIVEN.
+            return c.json({ error: `path is outside the workspace: ${rel}` }, 400);
         }
         let dirents;
         try {
@@ -580,7 +584,7 @@ export function buildApp(master) {
     app.get("/api/agents/:id/file", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const rel = c.req.query("path") ?? "";
         if (!rel.trim())
             return c.json({ error: "path required" }, 400);
@@ -611,7 +615,7 @@ export function buildApp(master) {
     app.get("/api/agents/:id/raw", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const rel = c.req.query("path") ?? "";
         if (!rel.trim())
             return c.json({ error: "path required" }, 400);
@@ -649,7 +653,7 @@ export function buildApp(master) {
     app.put("/api/agents/:id/file", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const rel = c.req.query("path") ?? "";
         if (!rel.trim())
             return c.json({ error: "path required" }, 400);
@@ -755,20 +759,20 @@ export function buildApp(master) {
     });
     app.get("/api/agents/:id", (c) => {
         const a = master.agents.get(c.req.param("id"));
-        return a ? c.json(a.snapshot()) : c.json({ error: "not found" }, 404);
+        return a ? c.json(a.snapshot()) : notFound(c, "agent", c.req.param("id"));
     });
     // lazy session load: stopped (not restored) → idle, history rebuilt from the log
     app.post("/api/agents/:id/load", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         await a.load();
         return c.json({ ok: true, agent: a.snapshot() });
     });
     app.post("/api/agents/:id/prompt", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req
             .json()
             .catch(() => null); // #110
@@ -797,7 +801,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/prompt/cancel", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => null); // #110
         if (!body)
             return c.json({ error: "invalid JSON" }, 400);
@@ -811,7 +815,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/start", (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         a.start("api start");
         return c.json({ ok: true });
     });
@@ -874,14 +878,14 @@ export function buildApp(master) {
     app.post("/api/agents/:id/stop", (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         a.stop("stopped via api");
         return c.json({ ok: true });
     });
     app.post("/api/agents/:id/goal", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json()
             .catch(() => null); // #110
         if (!body)
@@ -911,7 +915,7 @@ export function buildApp(master) {
     app.get("/api/agents/:id/skills", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         try {
             const list = await currentSkills(a.toolCtx);
             return c.json({
@@ -926,7 +930,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/compact", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         try {
             return c.json({ ok: true, ...(await a.compactNow()) });
         }
@@ -954,7 +958,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/auto-continue", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => null);
         if (!body || typeof body.value !== "boolean")
             return c.json({ error: "boolean value required" }, 400);
@@ -970,7 +974,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/auto-compact", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => null);
         if (!body || typeof body.value !== "boolean")
             return c.json({ error: "boolean value required" }, 400);
@@ -990,7 +994,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/spawn", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req
             .json()
             .catch(() => null);
@@ -1013,7 +1017,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/stop-children", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => ({ ids: undefined }));
         try {
             const r = await master.stopChildrenFor(c.req.param("id"), body.ids);
@@ -1027,20 +1031,26 @@ export function buildApp(master) {
     app.post("/api/agents/:id/todo", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => null);
         if (!body)
             return c.json({ error: "invalid JSON" }, 400);
         await a.setTodo(body.text ?? "");
         if (body.notify !== false && body.text?.trim())
             a.enqueuePrompt(`[harness] The operator updated the task list:\n\n${body.text}\n\nWork through it (get_todo() always has the latest).`, "harness");
+        // #123: an idle agent must actually START on the queued prompt. The goal
+        // route above learned this (the queued prompt sat forever otherwise); the
+        // todo route did not, so saving a task list on an idle session looked like
+        // it had been ignored.
+        if (a.status !== "running")
+            a.start("todo set");
         return c.json({ ok: true });
     });
     // edit a previously-sent prompt: forks there, optionally summarizes the tail
     app.post("/api/agents/:id/edit-prompt", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req
             .json()
             .catch(() => null);
@@ -1066,7 +1076,7 @@ export function buildApp(master) {
     app.post("/api/agents/:id/fork", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         const body = await c.req.json().catch(() => ({ fromEvent: null }));
         const r = await a.fork(body.fromEvent ?? null);
         return c.json({ ok: true, ...r });
@@ -1096,7 +1106,7 @@ export function buildApp(master) {
     app.get("/api/agents/:id/events", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         // #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
@@ -1113,7 +1123,7 @@ export function buildApp(master) {
         if (sessionId) {
             const rec = master.sessionById(sessionId);
             if (!rec || rec.agentId !== c.req.param("id"))
-                return c.json({ error: "not found" }, 404);
+                return notFound(c, "session (or it belongs to another agent)", sessionId);
             filePath = path.join(rec.dir, "chat.jsonl");
         }
         // #59: the plain "latest N" request is what the UI polls every ~120 ms for
@@ -1152,13 +1162,13 @@ export function buildApp(master) {
         const known = master.agents.has(id) || master.config.agents.some((a) => a.id === id);
         const owned = master.sessionsOf(id);
         if (!known && owned.length === 0)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", id);
         return c.json({ sessions: owned });
     });
     app.get("/api/agents/:id/branches", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
-            return c.json({ error: "not found" }, 404);
+            return notFound(c, "agent", c.req.param("id"));
         // cached like /events — this used to bypass it and re-read the whole log
         const events = await readEventsCached(a.log.filePath);
         const branches = new Map();
@@ -1190,6 +1200,16 @@ export function buildApp(master) {
     // ---- metrics / SSE ----
     app.get("/api/metrics", (c) => c.json(master.metrics()));
     // current server version (for live-update polling)
+    /**
+     * A 404 that says WHICH thing was missing.
+     *
+     * #126: there were 24 hand-copied `c.json({ error: "not found" }, 404)` lines.
+     * From a client they are indistinguishable — a typo in an agent id, a deleted
+     * session, or a bad route all produce the same three words, and none carries
+     * the id that was looked up. The id is the first thing anyone debugging this
+     * needs, and it is already in hand.
+     */
+    const notFound = (c, what, id) => c.json({ error: `${what} not found: ${id || "(no id given)"}` }, 404);
     app.get("/api/version", (c) => c.json({ version: master.getVersion() }));
     // trigger a full server restart (agents stopped gracefully, new process spawned)
     app.post("/api/update/restart", async (c) => {

package/package.json

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