teapot-coding-agent 0.28.1 → 0.29.0

package/dist/agent/skills.js

@@ -46,26 +46,40 @@ export async function skillRootsFingerprint(roots) {
             continue;
         }
         parts.push(`${st.mtimeMs}:${st.size}`);
-        let entries;
+        // stamp every SKILL.md the discovery walk could adopt (same depth bound):
+        // the one-level stat missed a NESTED skill's add/edit entirely, so the
+        // stamp never changed, refreshSkills early-returned, and the skill stayed
+        // invisible/stale in list_skills and the system-prompt catalogue
+        await stampSkillFiles(root.dir, 0, parts);
+    }
+    return parts.join("|");
+}
+/** recursive fingerprint walk — mirrors walkSkills' bound and containment rules */
+async function stampSkillFiles(dir, depth, parts) {
+    if (depth > MAX_SKILL_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (e.name.startsWith("."))
+            continue;
+        const full = path.join(dir, e.name);
+        if (!e.isDirectory())
+            continue;
         try {
-            entries = await fs.readdir(root.dir, { withFileTypes: true });
+            const s = await fs.stat(path.join(full, SKILL_FILE));
+            parts.push(`${full}=${s.mtimeMs}:${s.size}`);
         }
         catch {
-            continue;
-        }
-        for (const e of entries) {
-            if (!e.isDirectory() || e.name.startsWith("."))
-                continue;
-            try {
-                const s = await fs.stat(path.join(root.dir, e.name, SKILL_FILE));
-                parts.push(`${e.name}=${s.mtimeMs}:${s.size}`);
-            }
-            catch {
-                parts.push(`${e.name}=none`);
-            }
+            // not a skill dir itself — still a container to descend into
         }
+        await stampSkillFiles(full, depth + 1, parts);
     }
-    return parts.join("|");
 }
 export function isValidSkillName(name) {
     return /^[a-z0-9][a-z0-9._-]{0,63}$/.test(name);

package/dist/agent/tools.js

@@ -1645,9 +1645,30 @@ export const TOOLS = [
                 return { ok: false, result: "sub-agents are not available here" };
             const ids = Array.isArray(args.ids) ? args.ids.map(String) : undefined;
             const ms = Math.min(Math.max(num(args.timeout_ms, 300_000), 1_000), 3_600_000);
+            // #140: a prompt ALREADY in the queue must be consumed FIRST. The
+            // enqueue-time wake only fires for prompts arriving DURING the park —
+            // one queued before the park is invisible to it, and parking over it
+            // strands the operator's message ("idle" display, nothing processed)
+            // until a child settles. Stand down and let the next turn boundary
+            // drain it; the model can call wait_children again afterwards.
+            if (ctx.hasPendingPrompts?.()) {
+                ctx.onProgressGateReset?.();
+                return {
+                    ok: true,
+                    result: "A prompt is already queued for you — handle it first, then call wait_children again if you still need to wait.",
+                };
+            }
             // park VISIBLY: the UI shows idle ("waiting on sub-agents") instead of a
             // running spinner, and any user prompt / stop wakes us instantly
-            ctx.onIdlePark?.(`waiting on sub-agent${ids?.length === 1 ? ` ${ids[0]}` : "s"}`);
+            const parked = ctx.onIdlePark?.(`waiting on sub-agent${ids?.length === 1 ? ` ${ids[0]}` : "s"}`);
+            if (parked === false) {
+                // the agent refused the park (a prompt raced in) — same answer as above
+                ctx.onProgressGateReset?.();
+                return {
+                    ok: true,
+                    result: "A prompt arrived while you were about to wait — handle it first, then call wait_children again if you still need to wait.",
+                };
+            }
             // the child's report is about to land in our mailbox — a progress report
             // right after it would be pure noise, so re-arm the gate here
             ctx.onProgressGateReset?.();

package/dist/config-schema.js

@@ -39,7 +39,8 @@ export const ConfigPatchSchema = z.object({
     progressMinChars: z.number().int().min(100).optional(),
     // null clears a previously pinned compact budget → back to per-model derivation
     contextTokenBudget: z.number().int().min(1_000).nullable().optional(),
-    contextWindowTokens: z.number().int().min(1_000).optional(),
+    // null clears a saved window pin → back to per-model inference (same contract as contextTokenBudget)
+    contextWindowTokens: z.number().int().min(1_000).nullable().optional(),
     maxSpawnDepth: z.number().int().min(0).max(8).optional(),
     // soft cap on LLM turns in one round; reaching it nudges the model to wrap
     // up (not an error) — 0 disables the cap

package/dist/master.js

@@ -3,7 +3,7 @@
  * Agents are in-process async loops (I/O bound only); all CPU-heavy work is
  * delegated to subprocesses managed by the bash tool with hard timeouts.
  */
-import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, renameSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, lstatSync, renameSync, unlinkSync, openSync, closeSync, fsyncSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import os from "node:os";
@@ -168,6 +168,30 @@ export function loadConfig(configPath) {
     };
 }
 /** Raw parsed user config (for lossless persistence of web edits). */
+/**
+ * Can this path be replaced by an atomic rename?
+ *
+ * #144: `/dev/null`, a fifo, or a directory are all legitimate values for
+ * `configPath`, and `rename` over them either fails outright (EACCES for a temp
+ * beside `/dev/null`) or is not what the caller wants. Only a regular file gets
+ * the write-temp-then-rename treatment.
+ */
+function isRegularFileTarget(p) {
+    try {
+        // lstat, not stat: a SYMLINK must take the plain-write path. statSync
+        // follows the link, so a symlink→regular-file passed this check and the
+        // atomic rename then REPLACED THE LINK with a real file — the link's
+        // target (a dotfile repo, stow/chezmoi) kept the old value and a restart
+        // resurrected it. Same reasoning covers hardlinks (rename splits the
+        // inode; the write must go through the existing directory entry).
+        const st = lstatSync(p);
+        return st.isFile() && !st.isSymbolicLink();
+    }
+    catch {
+        // does not exist yet — the parent decides; a real config path will be created
+        return true;
+    }
+}
 export function loadedRaw() {
     return masterRawConfig;
 }
@@ -289,8 +313,30 @@ export class Master {
         this.config = config;
         this.configPath = configPath;
     }
-    /** Persist current logical config back to disk (lossless via raw user config). */
+    /**
+     * Persist current logical config back to disk (lossless via raw user config).
+     *
+     * #144: this was a bare `writeFileSync`, which TRUNCATES the target before it
+     * writes. config.json holds every agent, provider and scheduled task, so any
+     * interruption during the write — SIGINT, a crash, a full disk — left a ZERO-LENGTH
+     * file, and the next boot read `{}` and came up empty.
+     *
+     * Boot made this far more likely than it sounds: every agent that mints a
+     * session calls `recordSession` → `saveConfig`, so a machine with 30 configured
+     * agents rewrites the whole file 30 times before the server listens. A user
+     * pressing Ctrl-C during that window lost the lot.
+     *
+     * Now: write a sibling temp file, fsync it, then `rename` over the target.
+     * `rename` is atomic within a filesystem, so the file is either the old content
+     * or the new — never empty. A crash mid-write leaves the temp file behind and
+     * the real config untouched.
+     */
     saveConfig() {
+        // #144: during boot, mark dirty instead of writing; flushed once at the end
+        if (this.deferConfigWrites) {
+            this.configDirty = true;
+            return;
+        }
         this.raw.agents = this.config.agents;
         this.raw.providers = this.config.providers;
         this.raw.defaultProvider = this.config.defaultProvider;
@@ -299,7 +345,75 @@ export class Master {
             this.raw.progressIntervalMs = this.config.progressIntervalMs;
         if (this.raw.progressMinChars === undefined && this.config.progressMinChars !== undefined)
             this.raw.progressMinChars = this.config.progressMinChars;
-        writeFileSync(this.configPath, JSON.stringify(this.raw, null, 2) + "\n");
+        this.writeConfigAtomic(JSON.stringify(this.raw, null, 2) + "\n");
+    }
+    /**
+     * Coalesce config writes. #144.
+     *
+     * Boot calls `addAgent` for every configured agent, and any agent whose recorded
+     * session is gone mints a new one — which calls `recordSession` → `saveConfig`.
+     * A machine with 30 agents therefore rewrote the whole file 30 times before the
+     * server listened, and each was a window in which the file could be truncated.
+     *
+     * With the write now atomic that is no longer dangerous, but it is still 30
+     * unnecessary writes of a 148KB file. During boot, saves are marked dirty and
+     * flushed ONCE at the end. Outside boot (an edit, a spawn, a rename) behaviour is
+     * unchanged: synchronous and immediate.
+     */
+    deferConfigWrites = false;
+    configDirty = false;
+    /** write once and clear the dirty flag — used at the end of a batched section */
+    flushConfig() {
+        this.configDirty = false;
+        this.saveConfig();
+    }
+    /** write-and-rename, so config.json is never observed empty or half-written */
+    writeConfigAtomic(body) {
+        // #144: `/dev/null` is a real, intentional value here — many callers (and
+        // every test that does not care about persistence) pass it as "no config
+        // file". The old `writeFileSync("/dev/null", …)` succeeded and discarded.
+        //
+        // Atomic writing cannot honour that: the temp file would be
+        // `/dev/.config.json.tmp-…`, which is EACCES for a normal user, so 22 tests
+        // failed with a bare 400 from POST /api/agents. Keep the old behaviour for a
+        // non-regular target, and only do write-rename where rename means something.
+        if (!isRegularFileTarget(this.configPath)) {
+            writeFileSync(this.configPath, body);
+            return;
+        }
+        const dir = path.dirname(this.configPath);
+        // same directory as the target, so rename() stays within one filesystem
+        const tmp = path.join(dir, `.config.json.tmp-${process.pid}-${Date.now()}`);
+        let fd;
+        try {
+            fd = openSync(tmp, "w");
+            writeFileSync(fd, body);
+            // fsync BEFORE the rename: without it the rename can land while the data is
+            // still in the page cache, which is the same data-loss window on a crash
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(tmp, this.configPath);
+        }
+        catch (err) {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* nothing to clean up */
+            }
+            // Losing the new state is survivable; losing the file is not, so rethrow
+            // rather than pretending the save succeeded
+            throw err;
+        }
     }
     raw = loadedRaw();
     /** Apply partial config edits from the web UI and persist them. */
@@ -334,6 +448,27 @@ export class Master {
             this.config.onError = patch.onError;
         if (patch.retryDelayMs !== undefined)
             this.config.retryDelayMs = patch.retryDelayMs;
+        // #PUT-config: an explicit null clears a saved window pin → back to
+        // per-model inference; a positive number pins it (same contract as
+        // contextTokenBudget above)
+        if (patch.contextWindowTokens !== undefined) {
+            this.config.contextWindowTokens =
+                (patch.contextWindowTokens ?? 0) > 0 ? patch.contextWindowTokens : undefined;
+        }
+        // persist the scalar edits: saveConfig only mirrors agents/providers/etc.
+        // into raw, so these would otherwise pass validation, live for one
+        // process, and silently vanish from the file (a restart resurrected the
+        // old values). undefined DELETES the key so a null-clear also persists.
+        for (const k of [
+            "contextTokenBudget", "contextWindowTokens", "maxSpawnDepth",
+            "maxTurnsPerRound", "onError", "retryDelayMs",
+        ]) {
+            const v = this.config[k];
+            if (v === undefined)
+                delete this.raw[k];
+            else
+                this.raw[k] = v;
+        }
         if (patch.tasks) {
             this.config.tasks = patch.tasks;
             // rebuild schedule table live
@@ -347,28 +482,48 @@ export class Master {
     }
     async start() {
         mkdirSync(this.config.dataDir, { recursive: true });
-        for (const ac of this.config.agents) {
-            try {
-                await this.addAgent(ac);
+        // #144: ONE config write for the whole boot instead of one per agent.
+        //
+        // Every agent whose recorded session is gone mints a new one, and minting
+        // calls recordSession → saveConfig. With ~30 configured agents the user's log
+        // showed ~30 "session … is gone" lines, and therefore ~30 full rewrites of a
+        // 148KB config.json — all before the server ever listened. That is the window
+        // in which Ctrl-C emptied the file.
+        //
+        // `finally` so a throw mid-boot still flushes what it already changed: a
+        // deferred write that never flushes would leave config.json describing the PREVIOUS
+        // boot, which is its own silent data loss.
+        this.deferConfigWrites = true;
+        this.configDirty = false;
+        try {
+            for (const ac of this.config.agents) {
+                try {
+                    await this.addAgent(ac);
+                }
+                catch (err) {
+                    // one bad entry (duplicate id, unknown provider, …) must not take the
+                    // whole master down — skip it loudly and keep serving the rest
+                    console.error(`[teapot] skipping agent "${ac.id}": ${err.message}`);
+                }
             }
-            catch (err) {
-                // one bad entry (duplicate id, unknown provider, …) must not take the
-                // whole master down — skip it loudly and keep serving the rest
-                console.error(`[teapot] skipping agent "${ac.id}": ${err.message}`);
+            for (const t of this.config.tasks ?? []) {
+                try {
+                    this.tasks.push({
+                        task: t,
+                        schedule: parseSchedule(t.schedule),
+                        lastRunMin: t.lastRunMin ?? -1,
+                    });
+                }
+                catch (err) {
+                    // a hand-edited schedule typo must not stop the server from listening
+                    console.error(`[teapot] skipping task "${t.id}": ${err.message}`);
+                }
             }
         }
-        for (const t of this.config.tasks ?? []) {
-            try {
-                this.tasks.push({
-                    task: t,
-                    schedule: parseSchedule(t.schedule),
-                    lastRunMin: t.lastRunMin ?? -1,
-                });
-            }
-            catch (err) {
-                // a hand-edited schedule typo must not stop the server from listening
-                console.error(`[teapot] skipping task "${t.id}": ${err.message}`);
-            }
+        finally {
+            this.deferConfigWrites = false;
+            if (this.configDirty)
+                this.flushConfig();
         }
         // single low-frequency tick for everything periodic (idle cost ≈ 0)
         setInterval(() => void this.tick(), 15_000).unref();
@@ -825,10 +980,13 @@ When this task is done (or truly blocked), call finish() with a summary for @${p
             : this.childrenOf(parentId).map((c) => c.id)).filter((id) => this.agents.has(id));
         if (targets.length === 0)
             return Promise.resolve({ note: "no live sub-agents to wait for" });
-        const active = () => targets.filter((id) => {
-            const s = this.agents.get(id)?.status;
-            return s === "running" || s === "waiting";
-        });
+        // isBusy(), not the raw status: parkForTool overwrites a parked child's
+        // status to "idle" (spinner suppression) while its loop is very much
+        // alive — the raw check counted that child as settled and let the parent
+        // resume over unfinished work. isBusy() sees parked tools, compactions
+        // and an open ask_user; queued prompts are DORMANT (isLive()'s "stop vs
+        // start" extra) and must not hold the wait. A stop request reads settled.
+        const active = () => targets.filter((id) => this.agents.get(id)?.isBusy());
         const first = active();
         if (first.length === 0)
             return Promise.resolve({ note: `all sub-agents already settled: ${targets.join(", ")}` });

package/dist/scheduler/cron.js

@@ -88,12 +88,14 @@ 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 ~31
- * days (e.g. a Feb-29-only cron in August).
+ * 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.
  */
 export function nextFireAt(schedule, from = new Date()) {
     const startMinute = Math.floor(from.getTime() / 60_000) + 1; // next whole minute
-    const horizon = 60 * 24 * 31;
+    const horizon = 60 * 24 * 366;
     for (let i = 0; i < horizon; i++) {
         const d = new Date((startMinute + i) * 60_000);
         if (matches(schedule, d))

package/dist/server/api.js

@@ -103,7 +103,14 @@ export function buildApp(master) {
     // Optional bearer auth for LAN exposure — TEAPOT_API_TOKEN env wins, else
     // the config's `password` field. Static files stay public; only /api/* is
     // gated.
-    const apiToken = process.env.TEAPOT_API_TOKEN || master.config.password || "";
+    // Optional bearer auth for LAN exposure — TEAPOT_API_TOKEN env wins, else
+    // the config's `password` field. Static files stay public; only /api/* is
+    // gated.
+    //
+    // Read DYNAMICALLY: the first-run wizard sets `config.password` through
+    // /api/setup AFTER buildApp ran — a const captured here once meant a
+    // freshly-set-up server stayed wide open until the next process restart.
+    const apiToken = () => process.env.TEAPOT_API_TOKEN || master.config.password || "";
     /**
      * Routes where `?token=` is accepted (#79).
      *
@@ -119,19 +126,21 @@ export function buildApp(master) {
      * also accept the query form.
      */
     const tokenInQueryOk = (path) => path === "/api/ws" || /^\/api\/agents\/[^/]+\/term$/.test(path);
-    if (apiToken)
-        app.use("/api/*", async (c, next) => {
-            const h = c.req.header("authorization");
-            const provided = h?.startsWith("Bearer ") ? h.slice(7) : undefined;
-            if (provided && provided === apiToken)
+    app.use("/api/*", async (c, next) => {
+        const want = apiToken();
+        if (!want)
+            return next(); // nothing configured yet — the API stays open
+        const h = c.req.header("authorization");
+        const provided = h?.startsWith("Bearer ") ? h.slice(7) : undefined;
+        if (provided && provided === want)
+            return next();
+        if (tokenInQueryOk(c.req.path)) {
+            const q = c.req.query("token");
+            if (q && q === want)
                 return next();
-            if (tokenInQueryOk(c.req.path)) {
-                const q = c.req.query("token");
-                if (q && q === apiToken)
-                    return next();
-            }
-            return c.json({ error: "unauthorized" }, 401);
-        });
+        }
+        return c.json({ error: "unauthorized" }, 401);
+    });
     // per-agent terminal spawn guard
     const termCounts = new Map();
     /**
@@ -748,6 +757,12 @@ export function buildApp(master) {
                 progressIntervalMs: patch.progressIntervalMs,
                 progressMinChars: patch.progressMinChars,
                 contextTokenBudget: patch.contextTokenBudget,
+                // these four were validated (200 ok) and then DROPPED — the settings
+                // modal's context window never reached the config at all
+                contextWindowTokens: patch.contextWindowTokens,
+                maxTurnsPerRound: patch.maxTurnsPerRound,
+                onError: patch.onError,
+                retryDelayMs: patch.retryDelayMs,
                 maxSpawnDepth: patch.maxSpawnDepth,
                 tasks: patch.tasks,
             });
@@ -1036,14 +1051,20 @@ export function buildApp(master) {
         if (!body)
             return c.json({ error: "invalid JSON" }, 400);
         await a.setTodo(body.text ?? "");
-        if (body.notify !== false && body.text?.trim())
+        // #123: a notification-bearing save must actually WAKE the idle agent (the
+        // queued prompt used to sit forever).
+        //
+        // #123 residual: but the START follows the NOTIFICATION, not the save. The
+        // original fix left `a.start(...)` outside the gate — a brace-less if only
+        // gates the enqueue — so `notify:false` (whose entire meaning is "save
+        // silently") booted a stopped agent, and so did an EMPTY list. A todo save
+        // is note-taking; booting an incarnation is a side effect.
+        const shouldNotify = body.notify !== false && !!body.text?.trim();
+        if (shouldNotify) {
             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");
+            if (a.status !== "running")
+                a.start("todo set");
+        }
         return c.json({ ok: true });
     });
     // edit a previously-sent prompt: forks there, optionally summarizes the tail

package/dist/server/term-size.js

@@ -20,7 +20,7 @@ export class TermSizeTracker {
         if (st.rows === rows && st.cols === cols)
             return;
         const wait = Math.max(0, st.busyUntil - Date.now());
-        st.timer = setTimeout(() => {
+        const apply = () => {
             st.timer = null;
             st.rows = rows;
             st.cols = cols;
@@ -30,6 +30,18 @@ export class TermSizeTracker {
             catch {
                 /* child exited mid-debounce */
             }
+        };
+        st.timer = setTimeout(() => {
+            // output may have CONTINUED past the deadline this timer was computed
+            // from (markBusy only extends busyUntil — it cannot reach an already
+            // pending timer). Writing now would type stty into a running program,
+            // so defer to whatever busy window remains.
+            const remain = st.busyUntil - Date.now();
+            if (remain > 0) {
+                st.timer = setTimeout(apply, remain);
+                return;
+            }
+            apply();
         }, wait > 0 ? wait : TERM_RESIZE_DEBOUNCE_MS);
     }
     /** a child produced output — defer resizes so we never type into it */

package/package.json

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