teapot-coding-agent 0.11.0 → 0.12.0

package/dist/agent/llm.js

@@ -36,7 +36,7 @@ function sanitize(messages) {
         return m;
     });
 }
-export async function chat(cfg, messages, tools, signal) {
+export async function chat(cfg, messages, tools, signal, onDelta) {
     try {
         const res = await client(cfg).chat.completions.create({
             model: cfg.model,
@@ -72,6 +72,8 @@ export async function chat(cfg, messages, tools, signal) {
         if (!message.content && !message.tool_calls) {
             throw new Error("LLM API error: empty completion");
         }
+        // non-streaming fallback still feeds the UI one final snapshot
+        onDelta?.({ text: message.content ?? "", reasoning: reasoning ?? "" });
         return {
             message,
             reasoning,
@@ -165,7 +167,7 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
     catch (err) {
         // provider may not support streaming at all — one clean fallback
         if (!gotChunk && !signal?.aborted)
-            return chat(cfg, messages, tools, signal);
+            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

@@ -3,7 +3,7 @@
  * Tool specs are plain JSON-schema function definitions — provider-agnostic.
  */
 import { spawn } from "node:child_process";
-import { existsSync, promises as fs } from "node:fs";
+import { existsSync, promises as fs, realpathSync } from "node:fs";
 import path from "node:path";
 import { discoverSkills, isValidSkillName, readSkillFile, saveSkill, SKILL_FILE, } from "./skills.js";
 const str = (v, fallback = "") => (typeof v === "string" ? v : fallback);
@@ -23,6 +23,19 @@ function safeJoin(cwd, p) {
     if (rel.startsWith("..") || path.isAbsolute(rel)) {
         throw new Error(`path escapes workspace: ${p}`);
     }
+    // symlinks inside the workspace can point anywhere — resolve the real
+    // target and confine THAT too (path.resolve alone doesn't follow links)
+    let real = abs;
+    try {
+        real = realpathSync(abs);
+    }
+    catch {
+        /* target may not exist yet (write_file) — lexical check above still holds */
+    }
+    const relReal = path.relative(cwd, real);
+    if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+        throw new Error(`path escapes workspace via symlink: ${p}`);
+    }
     return abs;
 }
 /** Run a command in its own process group; kill the whole group on timeout. */
@@ -699,6 +712,110 @@ export const TOOLS = [
             return { ok: res.ok || text.length > 0, result: clipText(text, num(args.limit, 20_000)) };
         },
     },
+    {
+        name: "spawn_agent",
+        description: "Spawn a sub-agent to work a task in parallel (same workspace, own session). " +
+            'context "none" = fresh start with just the task; "fork" = inherit this conversation ' +
+            "byte-exactly (provider prefix cache stays warm) before the task is appended. " +
+            "Returns the sub-agent id immediately; its finish summary is delivered back to you.",
+        parameters: {
+            type: "object",
+            properties: {
+                task: { type: "string", description: "self-contained instructions for the sub-agent" },
+                context: { type: "string", enum: ["none", "fork"], description: "default none" },
+                name: { type: "string", description: "optional short name fragment for the id" },
+            },
+            required: ["task"],
+        },
+        async run(args, ctx) {
+            const sa = ctx.subAgents;
+            if (!sa)
+                return { ok: false, result: "sub-agents are not available here" };
+            const task = str(args.task).trim();
+            if (!task)
+                return { ok: false, result: "task required" };
+            const context = args.context === "fork" ? "fork" : "none";
+            try {
+                const r = await sa.spawn({
+                    task,
+                    context,
+                    name: str(args.name).trim() || undefined,
+                });
+                return { ok: true, result: `spawned sub-agent ${r.id} — it works in parallel; use list_children / message_agent to steer it, stop_children to halt` };
+            }
+            catch (e) {
+                return { ok: false, result: `spawn failed: ${e.message}` };
+            }
+        },
+    },
+    {
+        name: "list_children",
+        description: "List your live sub-agents: id, status, current goal.",
+        parameters: { type: "object", properties: {} },
+        async run(_args, ctx) {
+            const sa = ctx.subAgents;
+            if (!sa)
+                return { ok: false, result: "sub-agents are not available here" };
+            const kids = sa.list();
+            if (!kids.length)
+                return { ok: true, result: "(no sub-agents)" };
+            return {
+                ok: true,
+                result: kids
+                    .map((k) => `${k.id} · ${k.status} · ${clip(k.goal, 60)}`)
+                    .join("\n"),
+            };
+        },
+    },
+    {
+        name: "stop_children",
+        description: "Stop one or more of your sub-agents. Without ids: stops ALL of them (and their descendants).",
+        parameters: {
+            type: "object",
+            properties: {
+                ids: { type: "array", items: { type: "string" }, description: "sub-agent ids; omit for all" },
+            },
+        },
+        async run(args, ctx) {
+            const sa = ctx.subAgents;
+            if (!sa)
+                return { ok: false, result: "sub-agents are not available here" };
+            const ids = Array.isArray(args.ids) ? args.ids.map(String) : undefined;
+            const r = await sa.stop(ids);
+            return {
+                ok: true,
+                result: r.stopped.length ? `stopped: ${r.stopped.join(", ")}` : "(nothing running to stop)",
+            };
+        },
+    },
+    {
+        name: "message_agent",
+        description: "Send a message to a specific sub-agent (steer it mid-flight or answer its ask_user question).",
+        parameters: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "sub-agent id" },
+                text: { type: "string" },
+            },
+            required: ["id", "text"],
+        },
+        async run(args, ctx) {
+            const sa = ctx.subAgents;
+            if (!sa)
+                return { ok: false, result: "sub-agents are not available here" };
+            const id = str(args.id);
+            const text = str(args.text);
+            if (!text.trim())
+                return { ok: false, result: "text required" };
+            try {
+                await sa.message(id, text);
+                return { ok: true, result: `message delivered to ${id}` };
+            }
+            catch (e) {
+                return { ok: false, result: e.message };
+            }
+        },
+    },
     {
         name: "load_skill",
         description: "Load a skill's full instructions by name. Use when the system prompt's skill list " +
@@ -812,12 +929,17 @@ export function toolSpecs() {
         function: { name: t.name, description: t.description, parameters: t.parameters },
     }));
 }
+/** tools that mutate the workspace — blocked for read-only personas */
+const MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch", "bash"]);
 export async function executeTool(name, rawArgs, ctx) {
     const def = TOOLS.find((t) => t.name === name);
     if (!def)
         return { ok: false, result: `unknown tool: ${name}` };
     if (ctx.signal?.aborted)
         return { ok: false, result: "aborted (harness shutdown)" };
+    // read-only personas (researcher/reviewer) are enforced, not just asked
+    if (ctx.readOnly && MUTATING_TOOLS.has(name))
+        return { ok: false, result: `${name} is blocked: this agent runs with read-only tools` };
     let args;
     try {
         args = rawArgs ? JSON.parse(rawArgs) : {};

package/dist/config-schema.js

@@ -0,0 +1,51 @@
+/**
+ * Zod schema for teapot's config — the single source of truth for what a
+ * valid config looks like. Used to gate web-UI edits (PUT /api/config) and
+ * any programmatic writes, with human-readable error messages.
+ *
+ * NOTE: validation gates, it does not become the storage format — the master
+ * persists the raw user JSON so unknown fields survive round-trips.
+ */
+import { z } from "zod";
+export const ProviderSchema = z.object({
+    baseUrl: z.union([z.string().url("baseUrl must be a valid URL"), z.literal("")]).optional(),
+    apiKey: z.string().optional(),
+    model: z.string().optional(),
+});
+export const AgentEntrySchema = z.object({
+    id: z
+        .string()
+        .regex(/^[A-Za-z0-9._-]{1,64}$/, "id: letters/digits/dots/dashes only, max 64"),
+    workspace: z.string().min(1, "workspace required"),
+    provider: z.string().optional(),
+    model: z.string().optional(),
+    baseUrl: z.string().optional(),
+    apiKey: z.string().optional(),
+    contextWindowTokens: z.number().int().positive().optional(),
+    parent: z.string().optional(),
+});
+export const TaskSchema = z.object({
+    id: z.string().min(1, "task id required").max(64),
+    agent: z.string().min(1, "task agent required"),
+    schedule: z.string().min(3, "schedule required (cron or 'every Nm')"),
+    prompt: z.string().min(1, "prompt required"),
+    forked: z.boolean().optional(),
+});
+/** the patch shape accepted by PUT /api/config */
+export const ConfigPatchSchema = z.object({
+    providers: z.record(z.string().min(1, "provider name required"), ProviderSchema).optional(),
+    defaultProvider: z.string().optional(),
+    progressIntervalMs: z.number().int().min(10_000, "progress interval must be ≥ 10s").optional(),
+    progressMinChars: z.number().int().min(100).optional(),
+    contextTokenBudget: z.number().int().min(1_000).optional(),
+    contextWindowTokens: z.number().int().min(1_000).optional(),
+    maxSpawnDepth: z.number().int().min(0).max(8).optional(),
+    tasks: z.array(TaskSchema).optional(),
+});
+/** Format a ZodError into a compact operator-readable message. */
+export function formatZodError(error) {
+    return error.issues
+        .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join("; ")
+        .slice(0, 500);
+}

package/dist/index.js

@@ -1,21 +1,45 @@
 #!/usr/bin/env node
 /**
  * teapot master entry point.
- * Usage: teapot [config.json]
+ * Usage: teapot [--port N] [--config file.json] [config.json]
  * Config may also come from TEAPOT_* env vars (see src/master.ts).
+ * First run (no config file): boot anyway and finish setup in the web UI.
  */
+import { existsSync } from "node:fs";
 import { loadConfig, resolveConfigPath, Master } from "./master.js";
 import { buildApp, serveApp } from "./server/api.js";
 async function main() {
-    const configPath = resolveConfigPath(process.argv[2]);
+    // CLI: teapot [--port N] [-p N] [--config file] [-c file] [config.json]
+    let cfgArg;
+    let portOverride;
+    const args = process.argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--port" || a === "-p")
+            portOverride = Number(args[++i]);
+        else if (a === "--config" || a === "-c")
+            cfgArg = args[++i];
+        else if (!cfgArg && !a.startsWith("-"))
+            cfgArg = a;
+    }
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        console.log("teapot [--port N] [--config file.json] [config.json]");
+        console.log("  env: TEAPOT_PORT, TEAPOT_CONFIG_DIR, TEAPOT_DATA_DIR, TEAPOT_API_TOKEN");
+        return;
+    }
+    const configPath = resolveConfigPath(cfgArg);
+    const configExisted = existsSync(configPath);
     const config = loadConfig(configPath);
-    console.log(`[teapot] config: ${configPath}`);
+    if (portOverride !== undefined && !Number.isNaN(portOverride))
+        config.port = portOverride;
+    console.log(`[teapot] config: ${configPath}${configExisted ? "" : " (not found — first run)"}`);
     const hasProviders = Object.keys(config.providers ?? {}).length > 0;
     if (!config.llm.apiKey && !hasProviders)
-        console.warn("[teapot] warning: no API key configured");
+        console.warn("[teapot] warning: no API key configured — finish setup in the web UI");
     if (!config.llm.model && !hasProviders)
         console.warn("[teapot] warning: no model configured");
     const master = new Master(config, configPath);
+    master.configFileExists = configExisted;
     await master.start();
     const app = buildApp(master);
     serveApp(app, config.port);

package/dist/master.js

@@ -7,9 +7,46 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSy
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { Agent } from "./agent/agent.js";
 import { parseSchedule, matches, nextFireAt } from "./scheduler/cron.js";
 import { bus } from "./bus.js";
+/** how deep sub-agent spawning may nest (parent=0, its subs=1, …) */
+const MAX_SPAWN_DEPTH = 3;
+/**
+ * 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
+ * checkout alike. Lowest-priority skill root (workspace > global > bundled).
+ */
+const BUNDLED_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../skills");
+/** default sub-agent personas — mentionable from the composer (@name) and
+ *  usable by agents via spawn_agent({persona}) */
+export const SUB_PERSONAS = {
+    reviewer: {
+        label: "🔍 reviewer",
+        directive: "ROLE: code reviewer. Inspect the change set, judge correctness, style, tests; report concrete findings as a prioritized list.",
+        readOnly: true,
+    },
+    tester: {
+        label: "🧪 tester",
+        directive: "ROLE: test engineer. Write and run tests for the task at hand, hunt edge cases, report pass/fail with exact commands.",
+    },
+    researcher: {
+        label: "🔎 researcher",
+        directive: "ROLE: read-only explorer. Search the codebase/docs, map how things work, and report a compact briefing with file:line references.",
+        readOnly: true,
+    },
+    implementer: {
+        label: "🔨 implementer",
+        directive: "ROLE: hands-on implementer. Make the change end-to-end (code + tests), keep edits small and verified, then report what changed and why.",
+    },
+    "gyaru-reviewer": {
+        label: "💅 gyaru reviewer",
+        directive: "ROLE: pre-commit diff reviewer in a blunt gyaru voice. Read the whole diff and hunt: debug leftovers, unclear UI copy, silent data-loss risks, convention drift. Every finding must be concrete — suggested fix or an explicit shrug.",
+        readOnly: true,
+    },
+};
+;
 const CONFIG_DIR = process.env.TEAPOT_CONFIG_DIR ??
     path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "teapot-coding-agent");
 const DATA_DIR = process.env.TEAPOT_DATA_DIR ??
@@ -141,6 +178,8 @@ export class Master {
     startedAt = Date.now();
     config;
     configPath;
+    /** false on first boot with no config file → web UI shows the setup wizard */
+    configFileExists = true;
     constructor(config, configPath) {
         this.config = config;
         this.configPath = configPath;
@@ -176,13 +215,17 @@ export class Master {
                 a.opts.progressMinChars =
                     patch.progressMinChars;
         }
+        if (patch.contextTokenBudget !== undefined)
+            this.config.contextTokenBudget = patch.contextTokenBudget;
+        if (patch.maxSpawnDepth !== undefined)
+            this.config.maxSpawnDepth = patch.maxSpawnDepth;
         if (patch.tasks) {
             this.config.tasks = patch.tasks;
             // rebuild schedule table live
             this.tasks = patch.tasks.map((t) => ({
                 task: t,
                 schedule: parseSchedule(t.schedule),
-                lastRunMin: -1,
+                lastRunMin: t.lastRunMin ?? -1,
             }));
         }
         this.saveConfig();
@@ -203,12 +246,59 @@ export class Master {
             this.tasks.push({
                 task: t,
                 schedule: parseSchedule(t.schedule),
-                lastRunMin: -1,
+                lastRunMin: t.lastRunMin ?? -1,
             });
         }
         // single low-frequency tick for everything periodic (idle cost ≈ 0)
         setInterval(() => void this.tick(), 15_000).unref();
     }
+    /**
+     * First-run wizard bootstrap: write a minimal config file, apply it to the
+     * running master, and optionally create + start the first agent. Only
+     * available while no config file exists — after this, edits go through
+     * PUT /api/config behind whatever auth is configured.
+     */
+    async applySetup(body) {
+        if (this.configFileExists)
+            throw new Error("setup already completed — edit the config file instead");
+        const llm = {
+            baseUrl: body.baseUrl,
+            ...(body.apiKey ? { apiKey: body.apiKey } : {}),
+            model: body.model,
+        };
+        const raw = {
+            llm,
+            ...(body.password ? { password: body.password } : {}),
+            agents: [],
+        };
+        const dir = path.dirname(this.configPath);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(this.configPath, JSON.stringify(raw, null, 2) + "\n");
+        // hot-apply to the running master (no restart needed)
+        this.config.llm = { ...this.config.llm, ...llm };
+        if (body.password)
+            this.config.password = body.password;
+        this.configFileExists = true;
+        this.raw.llm = llm;
+        if (body.password)
+            this.raw.password = body.password;
+        let agentId;
+        if (body.workspace?.trim()) {
+            const ws = path.resolve(body.workspace.replace(/^~/, process.env.HOME ?? "~"));
+            await mkdirSync(ws, { recursive: true });
+            const name = (body.agentName?.trim() || path.basename(ws))
+                .replace(/[^\w.-]/g, "-")
+                .slice(0, 40) || "agent";
+            let id = name;
+            let n = 2;
+            while (this.agents.has(id))
+                id = `${name.slice(0, 38)}-${n++}`;
+            const agent = await this.addAgent({ id, workspace: ws }, { persist: true, fresh: true });
+            agentId = id;
+            agent.start("created by setup wizard");
+        }
+        return { ok: true, agentId };
+    }
     /**
      * Create an agent; optionally persist it to the config file.
      * Each incarnation gets its own session directory under
@@ -233,6 +323,9 @@ export class Master {
         };
         if (!llm.model)
             throw new Error(`agent ${ac.id}: no model configured (set model on the agent or on its provider)`);
+        // spawn-tree depth: computed from the config chain (ac may not be
+        // registered yet when this runs — spawnChildFor persists AFTER creation)
+        const myDepth = ac.parent ? this.depthOf(ac.parent) + 1 : 0;
         const sessionDir = this.resolveSessionDir(ac.id, opts.fresh === true);
         await mkdirSync(sessionDir, { recursive: true });
         const agent = new Agent({
@@ -248,7 +341,12 @@ export class Master {
                 ? { contextWindowTokens: (ac.contextWindowTokens ?? this.config.contextWindowTokens) }
                 : {}),
             globalSkillsDir: path.join(CONFIG_DIR, "skills"),
+            bundledSkillsDir: BUNDLED_SKILLS_DIR,
             provider: provName,
+            spawnDepth: myDepth,
+            ...(ac.readOnly ? { readOnlyTools: true } : {}),
+            ...(ac.parent ? { parent: ac.parent } : {}),
+            ...(ac.chatFn ? { chatFn: ac.chatFn } : {}),
         });
         // console line + broadcast: the web UI only refreshes on bus traffic, so
         // every appended event must reach it (otherwise messages sit invisible
@@ -256,7 +354,24 @@ export class Master {
         agent.log.onEvent = (e) => {
             printAgentEvent(e);
             bus.emit("update", { kind: "event", agentId: e.agent, event: e });
+            this.onChildEvent(ac, e);
         };
+        // sub-agent management hooks — only when this agent can legally spawn
+        if (myDepth < this.maxSpawnDepth()) {
+            const self = agent;
+            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,
+                })),
+                stop: (ids) => this.stopChildrenFor(ac.id, ids),
+                message: (id, text) => this.messageChild(ac.id, id, text),
+            };
+            agent.toolCtx.subAgents = hooks;
+        }
         await agent.init();
         this.agents.set(ac.id, agent);
         if (opts.persist) {
@@ -265,6 +380,156 @@ export class Master {
         }
         return agent;
     }
+    /** spawn-tree depth of an agent (0 = top level); unknown → 0 */
+    depthOf(id, seen = new Set()) {
+        const cap = this.maxSpawnDepth();
+        let depth = 0;
+        let cur = this.config.agents.find((a) => a.id === id);
+        while (cur?.parent && !seen.has(cur.id) && depth < cap + 2) {
+            seen.add(cur.id);
+            cur = this.config.agents.find((a) => a.id === cur.parent);
+            depth++;
+        }
+        return depth;
+    }
+    /** configured nesting limit (config.maxSpawnDepth, default 3) */
+    maxSpawnDepth() {
+        const v = this.config.maxSpawnDepth;
+        return typeof v === "number" && v >= 0 ? v : MAX_SPAWN_DEPTH;
+    }
+    /** direct children of an agent, with their Agent instances */
+    childrenOf(id) {
+        const kids = this.config.agents.filter((a) => a.parent === id);
+        const out = [];
+        for (const k of kids) {
+            const inst = this.agents.get(k.id);
+            if (inst)
+                out.push({ id: k.id, agent: inst });
+        }
+        return out;
+    }
+    /**
+     * 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
+     * tip — the parent's history is NEVER copied into the child's file; the
+     * child resolves it at restore time.
+     */
+    async spawnChildFor(parent, o) {
+        const parentId = parent.opts_id();
+        const persona = o.persona && Object.prototype.hasOwnProperty.call(SUB_PERSONAS, o.persona)
+            ? o.persona
+            : undefined;
+        const base = `${parentId}-sub${persona ? `-${persona}` : ""}${o.name ? `-${o.name.replace(/[^\w.-]/g, "-").slice(0, 24)}` : ""}`.slice(0, 60);
+        let id = base;
+        let n = 2;
+        while (this.agents.has(id) || this.config.agents.some((a) => a.id === id))
+            id = `${base.slice(0, 56)}-${n++}`;
+        // persona directives shape how the sub approaches the task
+        const directive = persona ? `${SUB_PERSONAS[persona].label}\n${SUB_PERSONAS[persona].directive}\n\n` : "";
+        const pcfg = this.config.agents.find((a) => a.id === parentId);
+        let forkTip;
+        let forkBranch;
+        if (o.context === "fork") {
+            // capture the fork tip BEFORE creating the child (parent keeps running)
+            forkTip = parent.log.lastEventId(parent.currentBranch);
+            forkBranch = parent.currentBranch;
+        }
+        const child = await this.addAgent({
+            id,
+            workspace: parent.workspace,
+            provider: pcfg?.provider,
+            model: pcfg?.model,
+            contextWindowTokens: pcfg?.contextWindowTokens,
+            parent: parentId,
+            ...(persona && SUB_PERSONAS[persona]?.readOnly ? { readOnly: true } : {}),
+        }, { persist: true, fresh: true });
+        if (o.context === "fork" && forkTip) {
+            await child.log.append("sub_fork", id, "br0", {
+                parentAgent: parentId,
+                parentSession: path.basename(parent.snapshot().sessionDir),
+                parentBranch: forkBranch,
+                upToEvent: forkTip,
+            });
+            // the inherited prefix becomes visible history for the child's loop
+            child.importMessages(parent.exportMessages());
+        }
+        await child.setGoal(`${directive}${o.task}`.slice(0, 2000));
+        await child.enqueuePrompt((o.context === "fork"
+            ? `[harness] You are sub-agent ${id}, spawned by @${parentId} with the conversation above. `
+            : `[harness] You are sub-agent ${id}, spawned by @${parentId}. `) +
+            `Work solely on this task:\n\n${directive}${o.task}`, "harness");
+        child.start(`spawned by ${parentId}`);
+        console.log(`[teapot] sub-agent ${id} spawned by ${parentId} (context: ${o.context ?? "none"}${persona ? `, persona: ${persona}` : ""})`);
+        return { id };
+    }
+    /** Stop direct children (and their descendants by default) of an agent. */
+    async stopChildrenFor(parentId, ids) {
+        const stopped = [];
+        const walk = (pid) => {
+            for (const { id, agent } of this.childrenOf(pid)) {
+                if (ids && !ids.includes(id)) {
+                    // still descend: stopping a parent implies stopping its subtree
+                    walk(id);
+                    continue;
+                }
+                agent.stop("stopped by parent agent");
+                stopped.push(id);
+                if (ids) {
+                    // explicit id → also take its subtree
+                    const sub = this.childrenOf(id);
+                    for (const { id: gid, agent: g } of sub) {
+                        g.stop("stopped with parent");
+                        stopped.push(gid);
+                    }
+                }
+                else {
+                    walk(id); // full-subtree default
+                }
+            }
+        };
+        walk(parentId);
+        return { stopped };
+    }
+    /** Deliver a parent's message into a child's mailbox (and wake it). */
+    async messageChild(parentId, childId, text) {
+        const cfg = this.config.agents.find((a) => a.id === childId);
+        if (!cfg || cfg.parent !== parentId)
+            throw new Error(`not your sub-agent: ${childId}`);
+        const child = this.agents.get(childId);
+        if (!child)
+            throw new Error(`sub-agent not running: ${childId}`);
+        child.enqueuePrompt(`[harness] Message from @${parentId}:\n\n${text}`, "harness");
+        if (child.status !== "running")
+            child.start(`message from ${parentId}`);
+    }
+    /**
+     * Mirror interesting child events into the parent's timeline (tagged with
+     * the acting sub id) and forward terminal outcomes to the parent's mailbox.
+     */
+    onChildEvent(ac, e) {
+        const parentId = ac.parent;
+        if (!parentId)
+            return;
+        const parent = this.agents.get(parentId);
+        if (!parent)
+            return;
+        // forward outcomes so the parent hears the result without polling
+        if (e.type === "message" && e.data.final) {
+            const summary = String(e.data.content ?? "").trim();
+            parent.enqueuePrompt(`[harness] Sub-agent ${ac.id} finished. Final report:\n${summary.slice(0, 2000) || "(no summary)"}`, "harness");
+        }
+        else if (e.type === "error") {
+            parent.enqueuePrompt(`[harness] Sub-agent ${ac.id} hit an error: ${String(e.data.message ?? "").slice(0, 500)}`, "harness");
+        }
+        // mirror feed-worthy activity; nested subs keep their original actor id
+        const MIRROR = new Set(["prompt", "message", "tool_call", "tool_result", "progress", "error", "question", "state"]);
+        if (!MIRROR.has(e.type))
+            return;
+        const inner = e.type === "sub" ? e.data : null;
+        const actor = inner?.sub ?? ac.id;
+        const payload = inner ? { sub: actor, type: inner.type, data: inner.data } : { sub: ac.id, type: e.type, data: e.data };
+        void parent.log.append("sub", parent.currentSession, parent.currentBranch, payload);
+    }
     /** sessions root + helpers */
     sessionsRoot() {
         return path.join(this.config.dataDir, "sessions");
@@ -390,6 +655,9 @@ export class Master {
                     continue; // dedupe within the same minute
                 t.lastRunMin = minuteKey;
                 t.lastRunAt = Date.now();
+                // persist so a master restart doesn't re-fire the same minute
+                t.task.lastRunMin = minuteKey;
+                this.saveConfig();
                 const agent = this.agents.get(t.task.agent);
                 if (!agent)
                     continue;