teapot-coding-agent 0.29.6 → 0.29.8

package/dist/index.js

@@ -37,15 +37,6 @@ async function waitForPortFree(port, host, timeoutMs) {
     return false;
 }
 /* ---------- live-update handover: keeping the operator's terminal (#35) ---------- */
-/**
- * The pid of the process that replaced US, or null if we are the server.
- *
- * `Master.restartServer()` spawns the replacement and records its pid here, so
- * the outgoing process can supervise its own successor instead of exiting and
- * handing the shell a prompt. A field on the master rather than an env var: both
- * processes are separate, but this value is written and read in the SAME
- * process, so there is no environment for the two of them to disagree over.
- */
 /** is `pid` still running? (EPERM means alive but not ours to signal) */
 function pidAlive(pid) {
     try {
@@ -60,16 +51,13 @@ function pidAlive(pid) {
  * Watch the replacement on the operator's behalf.
  *
  * The terminal is still wired to THIS process, so their Ctrl-C arrives here
- * first. Two things must happen, and the old one-shot shutdown() could do
- * neither:
- *
- *  1. forward the signal, so the replacement actually stops; and
- *  2. when the replacement does exit, leave too — otherwise the shell waits on
- *     a supervisor with nothing left to supervise and Ctrl-C looks broken.
+ * first: forward the signal so the replacement actually stops, and leave once
+ * it exits — otherwise the shell waits on a supervisor with nothing left to
+ * supervise and Ctrl-C looks broken.
  *
- * The original shutdown() cannot be reused for this: its `shuttingDown` latch
- * is already set by the SIGTERM that started the handover, so a later Ctrl-C
- * would be swallowed and this process would never exit.
+ * shutdown() cannot be reused for this: its `shuttingDown` latch is already set
+ * by the SIGTERM that started the handover, so a later Ctrl-C would be swallowed
+ * and this process would never exit.
  */
 function supervise(pid) {
     let signalled = false;
@@ -94,11 +82,9 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Parse `teapot [--port N] [-p N] [--host addr] [--config file] [config.json]`.
  *
- * Extracted from main() and exported so it can be tested. It was inline before,
- * which left `index.ts` at 48% branch coverage with NO test importing it at all —
- * the parser decides which config file is read and which port is bound, so a
- * regression here starts the wrong server on the wrong port with no error anyone
- * would read.
+ * Exported so it can be tested: the parser decides which config file is read and
+ * which port is bound, so a regression here starts the wrong server on the wrong
+ * port with no error anyone would read.
  *
  * The bare-word rule keeps the FIRST positional as the config path: a later bare
  * word is a stray argument, not an override, and silently replacing the config
@@ -160,18 +146,13 @@ async function main() {
     if (!Number.isNaN(fromPid) && fromPid !== process.pid) {
         console.log(`[teapot] restart: releasing port from old process ${fromPid}...`);
         try {
-            // Flush the old process's agents and let it release the socket. It does
-            // NOT wait for us (that would deadlock against our bind below) — it
-            // lingers only long enough for its own HTTP response to flush, then exits.
+            // Flush the old process's agents and let it release the socket. It must
+            // NOT wait for us — that would deadlock against our bind below.
             process.kill(fromPid, "SIGTERM");
         }
         catch {
             /* already gone */
         }
-        // Wait until the socket is genuinely free. Binding while the old process
-        // still holds it fails with EADDRINUSE, and because index.ts swallows
-        // uncaught exceptions that left two processes running while neither served
-        // anything (#35).
         if (!(await waitForPortFree(config.port, config.host, 30_000)))
             console.warn(`[teapot] warning: could not confirm ${config.host}:${config.port} is free — binding anyway`);
     }
@@ -209,32 +190,22 @@ async function main() {
         if (shuttingDown)
             return;
         shuttingDown = true;
-        // SUPERVISOR MODE. When a live update replaced us, we are no longer the
-        // server — but we are still the process the SHELL is waiting on, and it
-        // is still this process group that owns the terminal. Exiting here ended
-        // the shell's foreground job, so the operator was dumped back to the
-        // prompt mid-session while the new server kept running in the background
-        // ("teapot live restart returns to the shell", #35).
-        //
-        // So instead of exiting we hand over: keep the job slot, forward signals
-        // to the replacement, and only leave once it is gone. The operator's
-        // terminal — and their Ctrl-C — follow the server across the restart.
-        //
-        // The replacement is the child we spawned ourselves, so we hold it directly:
-        // no pid passed through the environment, and no way for the two processes
-        // to disagree about who supervises whom.
+        // SUPERVISOR MODE. When a live update replaced us we are no longer the
+        // server, but we are still the process the SHELL waits on and the one that
+        // owns the terminal; exiting here dumped the operator back to the prompt
+        // mid-session while the new server kept running in the background (#35). So
+        // we keep the job slot, forward signals to the replacement, and leave only
+        // once it is gone. The replacement is the child we spawned ourselves, so we
+        // hold it directly — no pid through the environment for the two processes to
+        // disagree over.
         if (master.replacementPid !== null) {
             const replacement = master.replacementPid;
             console.log(`[teapot] handing the terminal to the new server (pid ${replacement})...`);
-            // Release the port FIRST. The replacement is blocked in waitForPortFree
-            // waiting for exactly this, and it will SIGTERM us again if we do not go
-            // — but the difference now is that we stop SERVING rather than exiting,
-            // so the shell's foreground job survives the handover.
+            // Release the port FIRST: the replacement is blocked in waitForPortFree
+            // waiting for exactly this, and it will SIGTERM us again if we do not go.
             await server.close();
             console.log("[teapot] port released; supervising the new server");
             supervise(replacement);
-            // Stay attached until the replacement exits. The shell is still waiting
-            // on US, so leaving early is exactly the bug.
             while (pidAlive(replacement))
                 await sleep(500);
             console.log("[teapot] new server exited; releasing the terminal");
@@ -255,35 +226,27 @@ async function main() {
     process.on("SIGINT", () => void shutdown("SIGINT"));
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
-// Only when RUN, not when imported. `void main()` at module scope meant importing
-// this file for `parseArgs` started a whole server — which is why index.ts had no
-// test importing it and sat at 48% branch coverage. The check is the standard
-// ESM "am I the entry point" test, and `node --experimental-strip-types src/index.ts`
-// and `node dist/index.js` both still take this branch.
+// Only when RUN, not when imported: `void main()` at module scope meant importing
+// this file for `parseArgs` started a whole server. `node
+// --experimental-strip-types src/index.ts` and `node dist/index.js` both take
+// this branch.
 function isEntryPoint() {
     const arg = process.argv[1];
     if (!arg)
         return false;
-    // `npm i -g teapot-coding-agent` puts a SYMLINK at node_modules/.bin/teapot, and
-    // npm invokes the target THROUGH it. So `process.argv[1]` is the symlink path
-    // (…/node_modules/.bin/teapot), NOT the file it points at — which matched none
-    // of the checks below, `main()` never ran, and the installed command exited 0
-    // in silence. Reporting `teapot` did nothing and needing `node dist/index.js`
-    // was the only symptom. `realpathSync` is what resolves it.
+    // `npm i -g teapot-coding-agent` puts a SYMLINK at node_modules/.bin/teapot and
+    // npm invokes the target THROUGH it, so `process.argv[1]` is the symlink path,
+    // NOT the file it points at: the installed command then exited 0 in silence.
+    // `realpathSync` is what resolves it.
     try {
         const self = realpathSync(fileURLToPath(import.meta.url));
         const entry = realpathSync(arg);
         if (self === entry)
             return true;
         // `self === entry` is the ONLY correct test: it is the definition of being the
-        // entry point. The suffix checks that used to follow were a fallback for the
-        // symlink case, and they were far too loose — `endsWith("/index.ts")` is true
-        // for EVERY test file that imports this module, so importing it booted a real
+        // entry point. A suffix check such as `endsWith("/index.ts")` is true for
+        // EVERY test file that imports this module, so importing it booted a real
         // server on port 7788 and `cli-args.test.ts` failed with EADDRINUSE.
-        //
-        // Keep a basename check as a safety net for a bundler that rewrites paths, but
-        // require BOTH that we are the module AND that nothing else is: an argv[1] that
-        // resolves to a DIFFERENT file is by definition not this module's entry.
         return false;
     }
     catch {

package/dist/master.js

@@ -15,6 +15,40 @@ import { parseSchedule, matches, nextFireAt } from "./scheduler/cron.js";
 import { bus } from "./bus.js";
 import { fetchModelList, peekModelList, contextLengthFor, isReasoningEffort, } from "./model-meta.js";
 /** how deep sub-agent spawning may nest (parent=0, its subs=1, …) */
+/**
+ * Did the effective data dir come from an ENV OVERRIDE that disagrees with the
+ * config file's own `dataDir`? (#143)
+ *
+ * When it does, the config's session pointers are meaningless: they name
+ * directories under the OLD root, and this process is looking at a different
+ * one. Every agent therefore mints a fresh session — and `recordSession` writes
+ * those new pointers back into the config, destroying the real mapping. The
+ * caller then throws the new root away (a test's temp dir), leaving a config that
+ * points at sessions that never existed.
+ *
+ * That is not hypothetical: `test/cli-boot-and-host.test.ts` spawns the built CLI
+ * with `TEAPOT_DATA_DIR=<temp>` but NO config override, so `pnpm test` on a
+ * developer machine rewrote their real config and orphaned 493 sessions' pointers
+ * — twice, before this guard. On CI it is invisible, because CI has no config
+ * file to damage.
+ *
+ * So: a mismatched root makes session resolution READ-ONLY. The boot still works
+ * (agents get working sessions in the new root) — it just does not rewrite a
+ * config that is describing somebody else's data dir.
+ */
+function dataDirOverrideMismatch(configFilePath, effective) {
+    if (!process.env.TEAPOT_DATA_DIR)
+        return false; // not an override: the file is the truth
+    try {
+        const raw = JSON.parse(readFileSync(configFilePath, "utf8"));
+        if (typeof raw.dataDir !== "string" || !raw.dataDir)
+            return false;
+        return path.resolve(raw.dataDir) !== path.resolve(effective);
+    }
+    catch {
+        return false; // unreadable/new config — nothing to protect
+    }
+}
 const MAX_SPAWN_DEPTH = 3;
 /**
  * How long boot waits for an endpoint's model catalogue (#143).
@@ -322,6 +356,16 @@ export class Master {
     constructor(config, configPath) {
         this.config = config;
         this.configPath = configPath;
+        // #143: an env data-dir override that disagrees with the config file means
+        // this config describes a DIFFERENT data dir — its session pointers cannot be
+        // valid here, so rewriting them would destroy the real mapping. See
+        // dataDirOverrideMismatch().
+        this.sessionsReadOnly = dataDirOverrideMismatch(configPath, config.dataDir);
+        if (this.sessionsReadOnly) {
+            console.warn(`[teapot] TEAPOT_DATA_DIR (${config.dataDir}) disagrees with the config's own dataDir; ` +
+                `sessions will be resolved in the override but NOT written back to ${configPath}. ` +
+                `Set TEAPOT_CONFIG to an isolated config to silence this.`);
+        }
     }
     /**
      * Persist current logical config back to disk (lossless via raw user config).
@@ -382,6 +426,11 @@ export class Master {
      * idle, for a single request.
      */
     metaWaited = new Set();
+    /**
+     * #143: `TEAPOT_DATA_DIR` points somewhere other than the config's own dataDir,
+     * so session pointers must not be written back (see dataDirOverrideMismatch).
+     */
+    sessionsReadOnly = false;
     /** write once and clear the dirty flag — used at the end of a batched section */
     flushConfig() {
         this.configDirty = false;
@@ -786,40 +835,19 @@ export class Master {
             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.
-            // #135: reworded, because the old line was wrong in two ways.
+            // every movement is correct and cheap. ANCESTORS too: a waiter's targets
+            // now span the whole subtree, so a grandchild's movement must reach it.
+            this.wakeAncestorWaiters(ac.parent);
+            // #130: report only a SETTLED child, never its birth. A freshly spawned
+            // child is `idle` before `start()` runs, so that first idle->running flip
+            // would tell the parent "@kid is now idle" the instant it existed.
+            // Requiring a prior `running` is what filters it out; the wake above is
+            // unconditional, so `wait_children` is unaffected.
             //
-            // "Continue your task, or finish() if the work is done" was addressed to the
-            // PARENT — but the parent did not spawn this child for its own sake, and
-            // when the child DID call finish() the parent already receives a proper
-            // "Sub-agent X finished. Final report: …" (the `finished. Final report:`
-            // prompt below). So the nudge
-            // restated as an instruction what the report already stated as fact, and
-            // invited the parent to `finish()` ITS OWN goal over a child's status.
-            //
-            // The new wording says what happened and what to do about it, and points at
-            // the report when there is one:
-            //
-            //   child gave a summary  -> "…returned without calling finish(); its final
-            //                             message follows." (the report arrives separately)
-            //   child said nothing     -> "…went idle without reporting. If that is
-            //                             unexpected, message it or re-spawn it."
+            // #135: the wording addresses the CHILD's outcome, not the parent's goal.
+            // "Continue your task, or finish()..." invited the parent to finish its own
+            // goal over a child's status; the child's report already states what
+            // happened, so this points at it instead.
             if (this.reportedRunning.has(agentId) && SETTLED.has(status))
                 parent.enqueuePrompt(`[harness] Sub-agent @${agentId} is now ${status} without having called finish(), so it has not reported a result.` +
                     (status === "error"
@@ -838,11 +866,28 @@ export class Master {
             const hooks = {
                 depth: myDepth,
                 spawn: (o) => this.spawnChildFor(self, o),
-                list: () => this.childrenOf(ac.id).map((c) => ({
-                    id: c.id,
-                    status: c.agent.status,
-                    goal: c.agent.goal.text,
-                })),
+                list: () => 
+                // DIRECT children are the ones this agent can address (stop/message are
+                // refused for anything deeper), but a descendant still working is
+                // invisible to the parent unless it is LISTED — and the parent then
+                // resumes over it. So the whole subtree is listed, each row naming its
+                // own `parent` and flagged `nested`, which is what tells the model who
+                // to address instead of guessing a level (the error `message_agent`
+                // raises names the owner for the same reason).
+                this.subtreeOf(ac.id).flatMap(({ id, depth, parent }) => {
+                    const inst = this.agents.get(id);
+                    if (!inst)
+                        return []; // suspended: not addressable, so not listed
+                    return [
+                        {
+                            id,
+                            status: inst.status,
+                            goal: inst.goal.text,
+                            parent,
+                            nested: depth > 1,
+                        },
+                    ];
+                }),
                 stop: (ids) => this.stopChildrenFor(ac.id, ids),
                 message: (id, text) => this.messageChild(ac.id, id, text),
                 wait: (ids, ms) => 
@@ -875,6 +920,11 @@ export class Master {
         if (!entry)
             return; // not a configured agent — nothing to persist yet
         entry.session = sessionId;
+        // #143: never write session pointers into a config that is describing another
+        // data dir — every one of them would be wrong, and the correct mapping is
+        // destroyed. The in-memory session above still works for this process.
+        if (this.sessionsReadOnly)
+            return;
         this.saveConfig();
     }
     /** spawn-tree depth of an agent (0 = top level); unknown → 0 */
@@ -905,6 +955,35 @@ export class Master {
         }
         return out;
     }
+    /**
+     * Every configured descendant of `id`, at any depth, with its depth (1 = direct
+     * child) and its own parent id.
+     *
+     * A parent's work is not finished while anything it caused is still running,
+     * and that includes a sub-agent's sub-agent: C can delegate to G and return its
+     * own turn, leaving C idle while G works. Deciding from DIRECT children alone
+     * therefore let an ancestor report "all settled" over a live grandchild — the
+     * reported "it delegates further and the parent never knows".
+     *
+     * Returns configured ids (not instances) so a suspended descendant still counts
+     * as part of the subtree. `seen` guards a cycle in `parent`.
+     */
+    subtreeOf(id, depth = 1, seen = new Set()) {
+        const out = [];
+        for (const a of this.config.agents) {
+            if (a.parent !== id)
+                continue;
+            if (seen.has(a.id))
+                continue;
+            seen.add(a.id);
+            out.push({ id: a.id, depth, parent: id }, ...this.subtreeOf(a.id, depth + 1, seen));
+        }
+        return out;
+    }
+    /** the ids of every descendant of `id`, at any depth */
+    descendantsOf(id, seen = new Set()) {
+        return this.subtreeOf(id, 1, seen).map((x) => x.id);
+    }
     /**
      * Create a sub-agent on behalf of `parent`. context "fork" writes a
      * sub_fork header into the child log pointing at the parent's current
@@ -1044,9 +1123,12 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
      * while parked. Falls back to a timeout so waits can never hang forever.
      */
     waitChildren(parentId, ids, timeoutMs, signal) {
-        const targets = (ids && ids.length
-            ? ids
-            : this.childrenOf(parentId).map((c) => c.id)).filter((id) => this.agents.has(id));
+        // The whole DESCENDANT subtree, not just direct children: C can delegate to G
+        // and return its own turn, so C reads idle while G works. Waiting on C must
+        // therefore mean "C and everything C caused" — otherwise an ancestor resumes
+        // over live work it cannot see (see descendantsOf).
+        const named = ids && ids.length ? ids : this.descendantsOf(parentId);
+        const targets = [...new Set(named.flatMap((id) => [id, ...this.descendantsOf(id)]))].filter((id) => this.agents.has(id));
         if (targets.length === 0)
             return Promise.resolve({ note: "no live sub-agents to wait for" });
         // isBusy(), not the raw status: parkForTool overwrites a parked child's
@@ -1104,6 +1186,28 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             catch { /* ignore */ }
         }
     }
+    /**
+     * Wake the waiters of EVERY ancestor of an agent, not just its direct parent.
+     *
+     * A parked `wait_children` is woken by lifecycle events, and its targets now
+     * span the whole subtree — so a grandchild settling has to reach the
+     * grandparent, or the wake never arrives and the ancestor sits until its
+     * timeout even though the work finished.
+     *
+     * `parentId` is passed in rather than looked up: the caller already has it, and
+     * a spawned child that is not PERSISTED (a test, or a transient spawn) is absent
+     * from `config.agents`, so a lookup would find no parent at all and the wake
+     * would be silently skipped.
+     */
+    wakeAncestorWaiters(parentId) {
+        const seen = new Set();
+        let cur = parentId;
+        while (cur && !seen.has(cur)) {
+            seen.add(cur);
+            this.wakeParentWaiters(cur);
+            cur = this.config.agents.find((a) => a.id === cur)?.parent;
+        }
+    }
     async messageChild(parentId, childId, text) {
         // childId is normally the live agent id — but an internal session id
         // (sessions/<id>, the stable timeline handle) also resolves, so callers
@@ -1165,9 +1269,9 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
         if (!parentId)
             return;
         // any child lifecycle movement wakes a parked wait_children (the waiter
-        // re-checks whether its targets are all settled)
-        if (parentId)
-            this.wakeParentWaiters(parentId);
+        // re-checks whether its targets are all settled) — ancestors included, since
+        // a waiter's targets span its whole subtree
+        this.wakeAncestorWaiters(parentId);
         const parent = this.agents.get(parentId);
         if (!parent)
             return;
@@ -1203,29 +1307,12 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             if (parent.status !== "running")
                 parent.start(`sub-agent ${ac.id} error`);
         }
-        // #63: a child's activity is NOT mirrored into the parent's log.
-        //
-        // This used to write a `sub` row per child prompt/message/tool_call/…, so
-        // the parent's timeline filled with the child's entire transcript. Two
-        // problems, in order of discovery:
-        //
-        //  1. The rows were invisible, because `"sub"` was never in the web UI's
-        //     FEED_TYPES — so the filter dropped them and the feature did nothing
-        //     for as long as it existed (#40).
-        //  2. Once it was made to work (#40), the parent's timeline was flooded:
-        //     the operator reads a delegation as "what is this chat doing", not as
-        //     a firehose of a child's work.
-        //
-        // The mirroring bought nothing. `sub` rows are display-only:
-        // `rebuildMessagesFrom` never reads them, so the model never saw them and
-        // the child's own history was never duplicated into the parent's context.
-        // What the parent actually needs — the child's report — already arrives as
-        // a harness prompt above, which is the channel the model reads.
-        //
-        // So the right fix is to stop writing them. A chat's timeline is its own.
-        // If per-child detail is wanted in the UI later, it belongs behind an
-        // explicit filter ("show sub-agent activity"), reading each child's own log
-        // rather than interleaving a copy into the parent's.
+        // #63: a child's activity is NOT mirrored into the parent's log. Mirroring
+        // bought nothing — `sub` rows are display-only (`rebuildMessagesFrom` never
+        // read them, so the model never saw them) and once they DID render (#40) the
+        // parent's timeline was flooded with a child's transcript. What the parent
+        // needs is the child's report, which already arrives as a harness prompt
+        // above. A chat's timeline is its own.
     }
     /** sessions root + helpers */
     sessionsRoot() {

package/dist/scheduler/cron.js

@@ -13,8 +13,8 @@ const BOUNDS = [
 function parseField(part, min, max) {
     const out = new Set();
     const clampOrThrow = (v) => {
-        // out-of-range values used to slip through silently and produce a set
-        // that NEVER matched (e.g. "99 * * * *" ran never) — reject loudly
+        // accepting an out-of-range value produces a set that never matches, i.e. a
+        // cron that silently never fires ("99 * * * *")
         if (!Number.isInteger(v) || v < min || v > max)
             throw new Error(`bad cron field: ${part} (${min}-${max} expected)`);
         return v;
@@ -88,10 +88,9 @@ export function matches(schedule, d) {
 }
 /**
  * Next fire time after `from`, scanning minute by minute (cheap: a handful of
- * integer compares per minute). Returns null when nothing fires within a year
- * — annual crons (a December date seen in August) used to fall outside the old
- * 31-day horizon and showed `next: null` in the UI even though they fire.
- * A Feb-29-only cron can still legitimately report null most of the year.
+ * integer compares per minute). The horizon is a year so an annual cron (a
+ * December date seen in August) still resolves; a Feb-29-only cron can
+ * legitimately report null most of the year.
  */
 export function nextFireAt(schedule, from = new Date()) {
     const startMinute = Math.floor(from.getTime() / 60_000) + 1; // next whole minute

package/dist/server/term-size.js

@@ -5,9 +5,8 @@ export const TERM_BUSY_MS = 400;
 export class TermSizeTracker {
     states = new Map();
     /**
-     * Request a resize. Returns the number of `stty` lines that will actually
-     * be written for this call (0 while a burst is still collapsing) — exposed
-     * for tests and diagnostics.
+     * Request a resize; the sink write happens on the trailing edge of the
+     * debounce.
      */
     request(child, rows, cols, write) {
         const st = this.states.get(child) ?? { rows: 0, cols: 0, timer: null, busyUntil: 0 };

package/package.json

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