@teammates/cli 0.5.2 → 0.6.0

package/README.md

@@ -7,18 +7,17 @@ Agent-agnostic CLI orchestrator for teammates. Routes tasks to teammates, manage
 ## Quick Start
 
 ```bash
-cd cli
+cd packages/cli
 npm install
 npm run build
 ```
 
-Then launch a session with your preferred agent:
+Then launch a session:
 
 ```bash
-teammates claude       # Claude Code
-teammates codex        # OpenAI Codex
-teammates aider        # Aider
-teammates echo         # Test adapter (no external agent)
+teammates               # Uses default adapter (claude)
+teammates --model sonnet # Override the agent model
+teammates echo           # Use the test adapter (no external agent)
 ```
 
 The CLI auto-discovers your `.teammates/` directory by walking up from the current working directory.
@@ -26,7 +25,7 @@ The CLI auto-discovers your `.teammates/` directory by walking up from the curre
 ## Usage
 
 ```
-teammates <agent> [options] [-- agent-flags...]
+teammates [options] [-- agent-flags...]
 ```
 
 ### Options
@@ -37,7 +36,7 @@ teammates <agent> [options] [-- agent-flags...]
 | `--dir <path>` | Override `.teammates/` directory location |
 | `--help` | Show usage information |
 
-Any arguments after the agent name are passed through to the underlying agent CLI.
+Any arguments after `--` are passed through to the underlying agent CLI.
 
 ## In-Session Commands
 
@@ -55,16 +54,18 @@ Once inside the REPL, you can interact with teammates using `@mentions`, `/comma
 
 | Command | Aliases | Description |
 |---|---|---|
-| `/status` | `/s`, `/queue`, `/qu` | Show teammates, active tasks, and queue |
-| `/log [teammate]` | `/l` | Show the last task result (optionally for a specific teammate) |
-| `/debug [teammate]` | `/raw` | Show raw agent output from the last task |
-| `/cancel <n>` | | Cancel a queued task by number |
-| `/init` | `/onboard`, `/setup` | Run onboarding to set up teammates for this project |
-| `/install <service>` | | Install a teammates service (e.g. `recall`) |
+| `/status` | `/s`, `/queue` | Show teammates, active tasks, and queue |
+| `/debug [teammate] [focus]` | | Analyze the last agent task with optional focus text |
+| `/cancel [n]` | | Cancel a queued task by number |
+| `/init` | `/onboard`, `/setup` | Run onboarding to set up teammates |
+| `/init pick` | | Pick teammates from persona templates (in-TUI) |
 | `/compact [teammate]` | | Compact daily logs into weekly/monthly summaries |
 | `/retro [teammate]` | | Run a structured self-retrospective for a teammate |
+| `/user [change]` | | View or update USER.md |
+| `/btw [question]` | | Ask a quick side question without interrupting |
 | `/copy` | `/cp` | Copy the last response to clipboard |
 | `/theme` | | Show current theme colors |
+| `/configure [service]` | `/config` | Configure external services (e.g. GitHub) |
 | `/clear` | `/cls`, `/reset` | Clear history and reset the session |
 | `/help` | `/h`, `/?` | Show available commands |
 | `/exit` | `/q`, `/quit` | Exit the session |
@@ -121,21 +122,24 @@ The CLI uses a generic adapter interface to support any coding agent. Each adapt
 
 | Preset | Command | Notes |
 |---|---|---|
-| `claude` | `claude -p --verbose` | Requires `claude` on PATH |
+| `claude` | `claude -p --verbose` | Default adapter. Requires `claude` on PATH |
 | `codex` | `codex exec` | Requires `codex` on PATH |
 | `aider` | `aider --message-file` | Requires `aider` on PATH |
+| `copilot` | GitHub Copilot SDK | Requires `@anthropic-ai/copilot-sdk` |
 | `echo` | (in-process) | Test adapter — echoes prompts, no external agent |
 
 ### How Adapters Work
 
-1. The adapter queries the recall index for relevant memories (automatic, in-process)
-2. The orchestrator builds a full prompt within a 32k token budget (SOUL → WISDOM → recall results → daily logs (budget-trimmed) → session state → roster → task)
-3. The prompt is written to a temp file
-4. The agent CLI is spawned with the prompt
-5. stdout/stderr are captured for result parsing
-6. The output is parsed for embedded handoff blocks
-7. The recall index is synced to pick up any files the agent created/modified
-8. Temp files are cleaned up
+1. **Auto-compaction** — If daily logs exceed the 24k token budget, oldest weeks are compacted into weekly summaries
+2. **Two-pass recall** — Pass 1: keyword extraction → query variation generation → frontmatter catalog matching → multi-query fusion with dedup. Pass 2: agents can search mid-task via `teammates-recall search`
+3. The orchestrator builds a full prompt with token-budgeted sections (identity → wisdom → recall → daily logs → roster → services → date/time/environment → user profile → task → output protocol → session/memory instructions)
+4. The prompt is written to a temp file
+5. The agent CLI is spawned with the prompt
+6. stdout/stderr are captured for result parsing
+7. **Empty response defense** — If the agent returns no text: retry with raw mode (no prompt wrapping), then minimal prompt, then synthetic fallback from metadata
+8. The output is parsed for embedded handoff blocks (with natural-language fallback)
+9. The recall index is synced to pick up any files the agent created/modified
+10. Temp files are cleaned up
 
 ### Writing a Custom Adapter
 
@@ -169,13 +173,15 @@ Or add a preset to `cli-proxy.ts` for any CLI agent that accepts a prompt and ru
 The CLI startup runs in two phases:
 
 **Phase 1 — Pre-TUI (console I/O)**
-1. **User profile setup** — Prompts for alias (required), name, role, experience, preferences, context. Creates `USER.md` and a user avatar folder at `.teammates/<alias>/` with `SOUL.md` (`**Type:** human`).
-2. **Team onboarding** (if no `.teammates/` exists) — Offers New team / Import / Solo / Exit. Onboarding agents run non-interactively to completion.
+1. **User profile setup** — If `USER.md` is missing, offers three paths: **GitHub** (imports name/alias via `gh api user`), **Manual** (prompts for alias, name, role, experience, preferences), or **Skip**. Creates `USER.md` and a user avatar folder at `.teammates/<alias>/` with `SOUL.md` (`**Type:** human`). Auto-detects the user's timezone.
+2. **Team onboarding** (if `.teammates/` was just created) — Offers **Pick teammates** (persona templates), **Auto-generate** (agent-driven), **Import** (from another project), **Solo mode**, or **Exit**.
 3. **Orchestrator init** — Loads existing teammates from `.teammates/`, registers user avatar with `type: "human"` and `presence: "online"`.
+4. **Startup maintenance** — Runs auto-compaction and recall sync for all teammates (silent — progress bar only, no feed output unless actual work was done).
 
 **Phase 2 — TUI (Consolonia)**
-4. Animated startup banner with roster
-5. REPL starts — routing, slash commands, handoff approval
+5. Animated startup banner with presence-colored roster
+6. REPL starts — routing, slash commands, handoff approval
+7. System tasks (compaction, summarization, wisdom distillation) run in the background without blocking user tasks
 
 All user interaction during Phase 1 uses plain console I/O (readline + ora spinners), avoiding mouse tracking issues that would occur inside the TUI.
 
@@ -191,7 +197,7 @@ The CLI ships with 15 built-in persona templates that serve as starting points w
 | **2 — Specialist** | Security (`shield`), Designer (`canvas`), Tech Writer (`quill`), Data Engineer (`forge`), SRE (`watchtower`), Architect (`blueprint`) |
 | **3 — Niche** | Frontend (`pixel`), Backend (`engine`), Mobile (`orbit`), ML/AI (`neuron`), Performance (`tempo`) |
 
-During onboarding, the CLI uses these personas to scaffold teammates. The user picks roles, optionally renames them, and the persona's SOUL.md body becomes the starting template — project-specific sections (commands, file patterns, technologies) are filled in by the onboarding agent.
+During onboarding, the CLI uses these personas to scaffold teammates. Use **Pick teammates** during initial onboarding or `/init pick` in-session to choose from the list. The user picks roles, optionally renames them, and the persona's SOUL.md body becomes the starting template — project-specific sections (commands, file patterns, technologies) are filled in by the onboarding agent.
 
 ## Architecture
 
@@ -201,12 +207,18 @@ cli/src/
   orchestrator.ts   # Task routing, session management, presence tracking
   adapter.ts        # AgentAdapter interface, prompt builder, handoff formatting
   registry.ts       # Discovers teammates from .teammates/, loads SOUL.md + memory, type detection
+  compact.ts        # Episodic memory compaction (daily→weekly→monthly) + auto-compaction
+  banner.ts         # Animated startup banner with presence roster and segmented footer
   personas.ts       # Persona loader — reads and parses bundled persona templates
+  theme.ts          # Theme configuration, color palette, styled text shortcuts
+  cli-args.ts       # CLI argument parsing, .teammates/ directory discovery
+  cli-utils.ts      # Pure utility functions (relativeTime, wrapLine, findAtMention, etc.)
   types.ts          # Core types (TeammateConfig, TaskResult, HandoffEnvelope, TeammateType, PresenceState)
   onboard.ts        # Template copying, team import, onboarding/adaptation prompts
   dropdown.ts       # Terminal dropdown/wordwheel widget
   adapters/
-    cli-proxy.ts    # Generic subprocess adapter with agent presets
+    cli-proxy.ts    # Generic subprocess adapter with agent presets (claude, codex, aider)
+    copilot.ts      # GitHub Copilot adapter
     echo.ts         # Test adapter (no-op)
 cli/personas/       # 15 persona template files (pm.md, swe.md, devops.md, etc.)
 ```
@@ -246,6 +258,11 @@ Tests use [Vitest](https://vitest.dev/) and cover the core modules:
 | `src/adapter.test.ts` | `buildTeammatePrompt`, `formatHandoffContext` |
 | `src/orchestrator.test.ts` | Task routing, assignment, reset |
 | `src/registry.test.ts` | Teammate discovery, SOUL.md parsing (role, ownership), daily logs |
+| `src/compact.test.ts` | Daily→weekly compaction, auto-compaction, partial merge |
+| `src/personas.test.ts` | Persona loading and scaffolding |
+| `src/theme.test.ts` | Theme configuration |
+| `src/cli-args.test.ts` | Argument parsing, directory discovery |
+| `src/cli-utils.test.ts` | Utility functions |
 | `src/adapters/echo.test.ts` | Echo adapter session and task execution |
 
 ## Dependencies

package/dist/adapter.d.ts

@@ -29,6 +29,12 @@ export interface AgentAdapter {
     resumeSession?(teammate: TeammateConfig, sessionId: string): Promise<string>;
     /** Get the session file path for a teammate (if session is active). */
     getSessionFile?(teammateName: string): string | undefined;
+    /**
+     * Kill a running agent and return its partial output.
+     * Used by the interrupt-and-resume system to capture in-progress work.
+     * Returns null if no agent is running for this teammate.
+     */
+    killAgent?(teammate: string): Promise<import("./adapters/cli-proxy.js").SpawnResult | null>;
     /** Clean up a session. */
     destroySession?(sessionId: string): Promise<void>;
     /**
@@ -82,7 +88,7 @@ export declare function syncRecallIndex(teammatesDir: string, teammate?: string)
  * - Last recall entry can push total up to budget + RECALL_OVERFLOW (4k grace)
  * - Weekly summaries are excluded (already indexed by recall)
  */
-export declare const DAILY_LOG_BUDGET_TOKENS = 24000;
+export declare const DAILY_LOG_BUDGET_TOKENS = 12000;
 /**
  * Build the full prompt for a teammate session.
  * Includes identity, memory, roster, output protocol, and the task.

package/dist/adapter.js

@@ -67,7 +67,7 @@ const CHARS_PER_TOKEN = 4;
  * - Last recall entry can push total up to budget + RECALL_OVERFLOW (4k grace)
  * - Weekly summaries are excluded (already indexed by recall)
  */
-export const DAILY_LOG_BUDGET_TOKENS = 24_000;
+export const DAILY_LOG_BUDGET_TOKENS = 12_000;
 const RECALL_MIN_BUDGET_TOKENS = 8_000;
 const RECALL_OVERFLOW_TOKENS = 4_000;
 /** Estimate tokens from character count. */
@@ -171,7 +171,14 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     // ── Task-adjacent context (close to task for maximum relevance) ───
     // <RECALL_RESULTS> — budget-allocated, adjacent to task
     const recallBudget = Math.max(RECALL_MIN_BUDGET_TOKENS, RECALL_MIN_BUDGET_TOKENS + dailyBudget);
-    const recallResults = options?.recallResults ?? [];
+    // Filter recall results that duplicate daily log content already in the prompt
+    const dailyLogDates = new Set(teammate.dailyLogs.slice(0, 7).map((log) => log.date));
+    const recallResults = (options?.recallResults ?? []).filter((r) => {
+        const dailyMatch = r.uri.match(/memory\/(\d{4}-\d{2}-\d{2})\.md/);
+        if (dailyMatch && dailyLogDates.has(dailyMatch[1]))
+            return false;
+        return true;
+    });
     if (recallResults.length > 0) {
         const lines = [
             "<RECALL_RESULTS>",
@@ -207,6 +214,8 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     const instrLines = [
         "<INSTRUCTIONS>",
         "",
+        "**Your FIRST priority is answering the user's request in `<TASK>`. Session updates, memory writes, and continuity housekeeping are SECONDARY — do them AFTER producing your text response, not before.**",
+        "",
         "### Output Protocol (CRITICAL)",
         "",
         "**Your #1 job is to produce a visible text response.** Session updates and memory writes are secondary — they support continuity but are not the deliverable. The user sees ONLY your text output. If you update files but return no text, the user sees an empty message and your work is invisible.",
@@ -246,6 +255,10 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     if (options?.sessionFile) {
         instrLines.push("", "### Session State", "", `Your session file is at: \`${options.sessionFile}\``, "", "**After completing the task**, append a brief entry to this file with:", "- What you did", "- Key decisions made", "- Files changed", "- Anything the next task should know", "", "This is how you maintain continuity across tasks. Always read it, always update it.");
     }
+    // Cross-folder write boundary (AI teammates only)
+    if (teammate.type === "ai") {
+        instrLines.push("", "### Folder Boundaries (ENFORCED)", "", `**You MUST NOT create, edit, or delete files inside another teammate's folder (\`.teammates/<other>/\`).** Your folder is \`.teammates/${teammate.name}/\` — you may only write inside it. Shared folders (\`.teammates/_*/\`) and ephemeral folders (\`.teammates/.*/\`) are also writable.`, "", "If your task requires changes to another teammate's files, you MUST hand off that work using the handoff block format above. Violation of this rule will cause your changes to be flagged and potentially reverted.");
+    }
     // Memory updates
     instrLines.push("", "### Memory Updates", "", "**After completing the task**, update your memory files:", "", `1. **Daily log** — Read \`.teammates/${teammate.name}/memory/${today}.md\` first (it may have entries from earlier tasks today), then write it back with your entry added. Create the file if it doesn't exist.`, "   - What you did", "   - Key decisions made", "   - Files changed", "   - Anything the next task should know", "", `2. **Typed memories** — If you learned something durable (a decision, pattern, feedback, or reference), create a typed memory file at \`.teammates/${teammate.name}/memory/<type>_<topic>.md\` with frontmatter (\`name\`, \`description\`, \`type\`). Update existing memory files if the topic already has one.`, "", "3. **WISDOM.md** — Do not edit directly. Wisdom entries are distilled from typed memories during compaction.", "", "These files are your persistent memory. Without them, your next session starts from scratch.");
     // Section Reinforcement — back-references from high-attention bottom edge to each section tag
@@ -273,7 +286,19 @@ export function buildTeammatePrompt(teammate, taskPrompt, options) {
     if (options?.handoffContext) {
         instrLines.push("- When `<HANDOFF_CONTEXT>` is present, address its requirements and open questions directly.");
     }
-    instrLines.push("- Your response must answer `<TASK>` — everything else is supporting context.", "", "**REMINDER: You MUST end your turn with visible text output. A turn with only file edits and no text is a failed turn.**");
+    instrLines.push("- Your response must answer `<TASK>` — everything else is supporting context.");
+    // Echo the user's actual request at the bottom edge for maximum attention.
+    // The orchestrator prepends conversation history before a "---" separator,
+    // so the user's raw message is the last segment after splitting on "---".
+    const segments = taskPrompt.split(/\n\n---\n\n/);
+    const userRequest = segments[segments.length - 1].trim();
+    if (userRequest.length > 0 && userRequest.length < 500) {
+        instrLines.push("", `**THE USER'S REQUEST:** ${userRequest}`);
+    }
+    else if (userRequest.length >= 500) {
+        instrLines.push("", "**IMPORTANT: The user's actual request is at the end of `<TASK>`. Read and address it before doing anything else.**");
+    }
+    instrLines.push("", "**REMINDER: You MUST end your turn with visible text output. A turn with only file edits and no text is a failed turn.**");
     parts.push(instrLines.join("\n"));
     return parts.join("\n");
 }

package/dist/adapter.test.js

@@ -101,27 +101,24 @@ describe("buildTeammatePrompt", () => {
         expect(prompt).toContain("### Session State");
         expect(prompt).toContain("/tmp/beacon-session.md");
     });
-    it("drops daily logs that exceed the 24k daily budget", () => {
-        // Each log is ~50k chars = ~12.5k tokens. Only 1 fits in 24k daily budget.
+    it("drops daily logs that exceed the 12k daily budget", () => {
+        // Each log is ~50k chars = ~12.5k tokens. First one exceeds 12k budget, dropped.
         const bigContent = "D".repeat(50_000);
         const config = makeConfig({
             dailyLogs: [
                 { date: "2026-03-18", content: "Today's log — never trimmed" },
-                { date: "2026-03-17", content: bigContent }, // day 2 — fits in 24k
-                { date: "2026-03-16", content: bigContent }, // day 3 — exceeds 24k, dropped
+                { date: "2026-03-17", content: bigContent }, // day 2 — exceeds 12k, dropped
             ],
         });
         const prompt = buildTeammatePrompt(config, "task");
         // Today's log is always fully present (never trimmed)
         expect(prompt).toContain("Today's log — never trimmed");
-        // Day 2 fits within 24k
-        expect(prompt).toContain("2026-03-17");
-        // Day 3 doesn't fit (12.5k + 12.5k > 24k)
-        expect(prompt).not.toContain("2026-03-16");
+        // Day 2 doesn't fit (12.5k > 12k)
+        expect(prompt).not.toContain("2026-03-17");
     });
-    it("recall gets at least 8k tokens even when daily logs use full 24k", () => {
-        // Daily logs fill their 24k budget. Recall still gets its guaranteed 8k minimum.
-        const dailyContent = "D".repeat(90_000); // ~22.5k tokens — fits in 24k
+    it("recall gets at least 8k tokens even when daily logs use full 12k", () => {
+        // Daily logs fill their 12k budget. Recall still gets its guaranteed 8k minimum.
+        const dailyContent = "D".repeat(40_000); // ~10k tokens — fits in 12k
         const config = makeConfig({
             dailyLogs: [
                 { date: "2026-03-18", content: "today" },
@@ -144,7 +141,7 @@ describe("buildTeammatePrompt", () => {
         expect(prompt).toContain("<RECALL_RESULTS>");
     });
     it("recall gets unused daily log budget", () => {
-        // Small daily logs leave most of 24k unused — recall gets the surplus.
+        // Small daily logs leave most of 12k unused — recall gets the surplus.
         const config = makeConfig({
             dailyLogs: [
                 { date: "2026-03-18", content: "today" },
@@ -152,7 +149,7 @@ describe("buildTeammatePrompt", () => {
             ],
         });
         // Large recall result — should fit because daily logs barely used any budget
-        const recallText = "R".repeat(80_000); // ~20k tokens — fits in (8k + ~24k unused)
+        const recallText = "R".repeat(80_000); // ~20k tokens — fits in (8k + ~12k unused)
         const prompt = buildTeammatePrompt(config, "task", {
             recallResults: [
                 {

package/dist/adapters/cli-proxy.d.ts

@@ -86,6 +86,8 @@ export declare class CliProxyAdapter implements AgentAdapter {
     private sessionsDir;
     /** Temp prompt files that need cleanup — guards against crashes before finally. */
     private pendingTempFiles;
+    /** Active child processes per teammate — used by killAgent() for interruption. */
+    private activeProcesses;
     constructor(options: CliProxyOptions);
     startSession(teammate: TeammateConfig): Promise<string>;
     executeTask(_sessionId: string, teammate: TeammateConfig, prompt: string, options?: {
@@ -93,6 +95,7 @@ export declare class CliProxyAdapter implements AgentAdapter {
     }): Promise<TaskResult>;
     routeTask(task: string, roster: RosterEntry[]): Promise<string | null>;
     getSessionFile(teammateName: string): string | undefined;
+    killAgent(teammate: string): Promise<SpawnResult | null>;
     destroySession(_sessionId: string): Promise<void>;
     /**
      * Spawn the agent, stream its output live, and capture it.

package/dist/adapters/cli-proxy.js

@@ -20,7 +20,7 @@ import { mkdirSync } from "node:fs";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { DAILY_LOG_BUDGET_TOKENS, buildTeammatePrompt, queryRecallContext, } from "../adapter.js";
+import { buildTeammatePrompt, DAILY_LOG_BUDGET_TOKENS, queryRecallContext, } from "../adapter.js";
 import { autoCompactForBudget } from "../compact.js";
 export const PRESETS = {
     claude: {
@@ -103,6 +103,8 @@ export class CliProxyAdapter {
     sessionsDir = "";
     /** Temp prompt files that need cleanup — guards against crashes before finally. */
     pendingTempFiles = new Set();
+    /** Active child processes per teammate — used by killAgent() for interruption. */
+    activeProcesses = new Map();
     constructor(options) {
         this.options = options;
         this.preset =
@@ -321,6 +323,20 @@ export class CliProxyAdapter {
     getSessionFile(teammateName) {
         return this.sessionFiles.get(teammateName);
     }
+    async killAgent(teammate) {
+        const entry = this.activeProcesses.get(teammate);
+        if (!entry || entry.child.killed)
+            return null;
+        // Kill with SIGTERM → 5s → SIGKILL
+        entry.child.kill("SIGTERM");
+        setTimeout(() => {
+            if (!entry.child.killed) {
+                entry.child.kill("SIGKILL");
+            }
+        }, 5_000);
+        // Wait for the process to exit — the spawnAndProxy close handler resolves this
+        return entry.done;
+    }
     async destroySession(_sessionId) {
         // Clean up any leaked temp prompt files
         for (const file of this.pendingTempFiles) {
@@ -337,119 +353,128 @@ export class CliProxyAdapter {
      * Spawn the agent, stream its output live, and capture it.
      */
     spawnAndProxy(teammate, promptFile, fullPrompt) {
-        return new Promise((resolve, reject) => {
-            // Always generate a debug log file for presets that support it (e.g. Claude's --debug-file).
-            // Written to .teammates/.tmp/debug/ so startup maintenance can clean old logs.
-            let debugFile;
-            if (this.preset.supportsDebugFile) {
-                const debugDir = join(teammate.cwd ?? process.cwd(), ".teammates", ".tmp", "debug");
-                try {
-                    mkdirSync(debugDir, { recursive: true });
-                }
-                catch {
-                    /* best effort */
-                }
-                debugFile = join(debugDir, `agent-${teammate.name}-${Date.now()}.log`);
-            }
-            const args = [
-                ...this.preset.buildArgs({ promptFile, prompt: fullPrompt, debugFile }, teammate, this.options),
-                ...(this.options.extraFlags ?? []),
-            ];
-            const command = this.options.commandPath ?? this.preset.command;
-            const env = { ...process.env, ...this.preset.env };
-            const timeout = this.options.timeout ?? 600_000;
-            const interactive = this.preset.interactive ?? false;
-            const useStdin = this.preset.stdinPrompt ?? false;
-            // Suppress Node.js ExperimentalWarning (e.g. SQLite) in agent
-            // subprocesses so it doesn't leak into the terminal UI.
-            const existingNodeOpts = env.NODE_OPTIONS ?? "";
-            if (!existingNodeOpts.includes("--disable-warning=ExperimentalWarning")) {
-                env.NODE_OPTIONS = existingNodeOpts
-                    ? `${existingNodeOpts} --disable-warning=ExperimentalWarning`
-                    : "--disable-warning=ExperimentalWarning";
+        // Create a deferred promise so killAgent() can await the same result
+        let resolveOuter;
+        let rejectOuter;
+        const done = new Promise((res, rej) => {
+            resolveOuter = res;
+            rejectOuter = rej;
+        });
+        // Always generate a debug log file for presets that support it (e.g. Claude's --debug-file).
+        // Written to .teammates/.tmp/debug/ so startup maintenance can clean old logs.
+        let debugFile;
+        if (this.preset.supportsDebugFile) {
+            const debugDir = join(teammate.cwd ?? process.cwd(), ".teammates", ".tmp", "debug");
+            try {
+                mkdirSync(debugDir, { recursive: true });
             }
-            // On Windows, npm-installed CLIs are .cmd wrappers that require shell.
-            // When using shell mode, pass command+args as a single string to avoid
-            // Node DEP0190 deprecation warning about unescaped args with shell: true.
-            const needsShell = this.preset.shell ?? process.platform === "win32";
-            const spawnCmd = needsShell ? [command, ...args].join(" ") : command;
-            const spawnArgs = needsShell ? [] : args;
-            const child = spawn(spawnCmd, spawnArgs, {
-                cwd: teammate.cwd ?? process.cwd(),
-                env,
-                stdio: [interactive || useStdin ? "pipe" : "ignore", "pipe", "pipe"],
-                shell: needsShell,
-            });
-            // Pipe prompt via stdin if the preset requires it
-            if (useStdin && child.stdin) {
-                child.stdin.write(fullPrompt);
-                child.stdin.end();
+            catch {
+                /* best effort */
             }
-            // ── Timeout with SIGTERM → SIGKILL escalation ──────────────
-            let killed = false;
-            let killTimer = null;
-            const timeoutTimer = setTimeout(() => {
-                if (!child.killed) {
-                    killed = true;
-                    child.kill("SIGTERM");
-                    // If SIGTERM doesn't work after 5s, force-kill
-                    killTimer = setTimeout(() => {
-                        if (!child.killed) {
-                            child.kill("SIGKILL");
-                        }
-                    }, 5_000);
-                }
-            }, timeout);
-            // Connect user's stdin → child only if agent may ask questions
-            let onUserInput = null;
-            if (interactive && !useStdin && child.stdin) {
-                onUserInput = (chunk) => {
-                    child.stdin?.write(chunk);
-                };
-                if (process.stdin.isTTY) {
-                    process.stdin.setRawMode(false);
-                }
-                process.stdin.resume();
-                process.stdin.on("data", onUserInput);
+            debugFile = join(debugDir, `agent-${teammate.name}-${Date.now()}.log`);
+        }
+        const args = [
+            ...this.preset.buildArgs({ promptFile, prompt: fullPrompt, debugFile }, teammate, this.options),
+            ...(this.options.extraFlags ?? []),
+        ];
+        const command = this.options.commandPath ?? this.preset.command;
+        const env = { ...process.env, ...this.preset.env };
+        const timeout = this.options.timeout ?? 600_000;
+        const interactive = this.preset.interactive ?? false;
+        const useStdin = this.preset.stdinPrompt ?? false;
+        // Suppress Node.js ExperimentalWarning (e.g. SQLite) in agent
+        // subprocesses so it doesn't leak into the terminal UI.
+        const existingNodeOpts = env.NODE_OPTIONS ?? "";
+        if (!existingNodeOpts.includes("--disable-warning=ExperimentalWarning")) {
+            env.NODE_OPTIONS = existingNodeOpts
+                ? `${existingNodeOpts} --disable-warning=ExperimentalWarning`
+                : "--disable-warning=ExperimentalWarning";
+        }
+        // On Windows, npm-installed CLIs are .cmd wrappers that require shell.
+        // When using shell mode, pass command+args as a single string to avoid
+        // Node DEP0190 deprecation warning about unescaped args with shell: true.
+        const needsShell = this.preset.shell ?? process.platform === "win32";
+        const spawnCmd = needsShell ? [command, ...args].join(" ") : command;
+        const spawnArgs = needsShell ? [] : args;
+        const child = spawn(spawnCmd, spawnArgs, {
+            cwd: teammate.cwd ?? process.cwd(),
+            env,
+            stdio: [interactive || useStdin ? "pipe" : "ignore", "pipe", "pipe"],
+            shell: needsShell,
+        });
+        // Register the active process for killAgent() access
+        this.activeProcesses.set(teammate.name, { child, done, debugFile });
+        // Pipe prompt via stdin if the preset requires it
+        if (useStdin && child.stdin) {
+            child.stdin.write(fullPrompt);
+            child.stdin.end();
+        }
+        // ── Timeout with SIGTERM → SIGKILL escalation ──────────────
+        let killed = false;
+        let killTimer = null;
+        const timeoutTimer = setTimeout(() => {
+            if (!child.killed) {
+                killed = true;
+                child.kill("SIGTERM");
+                // If SIGTERM doesn't work after 5s, force-kill
+                killTimer = setTimeout(() => {
+                    if (!child.killed) {
+                        child.kill("SIGKILL");
+                    }
+                }, 5_000);
             }
-            const stdoutBufs = [];
-            const stderrBufs = [];
-            child.stdout?.on("data", (chunk) => {
-                stdoutBufs.push(chunk);
-            });
-            child.stderr?.on("data", (chunk) => {
-                stderrBufs.push(chunk);
-            });
-            const cleanup = () => {
-                clearTimeout(timeoutTimer);
-                if (killTimer)
-                    clearTimeout(killTimer);
-                if (onUserInput) {
-                    process.stdin.removeListener("data", onUserInput);
-                }
+        }, timeout);
+        // Connect user's stdin → child only if agent may ask questions
+        let onUserInput = null;
+        if (interactive && !useStdin && child.stdin) {
+            onUserInput = (chunk) => {
+                child.stdin?.write(chunk);
             };
-            child.on("close", (code, signal) => {
-                cleanup();
-                const stdout = Buffer.concat(stdoutBufs).toString("utf-8");
-                const stderr = Buffer.concat(stderrBufs).toString("utf-8");
-                const output = stdout + (stderr ? `\n${stderr}` : "");
-                resolve({
-                    output: killed
-                        ? `${output}\n\n[TIMEOUT] Agent process killed after ${timeout}ms`
-                        : output,
-                    stdout,
-                    stderr,
-                    exitCode: code,
-                    signal: signal ?? null,
-                    timedOut: killed,
-                    debugFile,
-                });
-            });
-            child.on("error", (err) => {
-                cleanup();
-                reject(new Error(`Failed to spawn ${command}: ${err.message}`));
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode(false);
+            }
+            process.stdin.resume();
+            process.stdin.on("data", onUserInput);
+        }
+        const stdoutBufs = [];
+        const stderrBufs = [];
+        child.stdout?.on("data", (chunk) => {
+            stdoutBufs.push(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrBufs.push(chunk);
+        });
+        const cleanup = () => {
+            clearTimeout(timeoutTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (onUserInput) {
+                process.stdin.removeListener("data", onUserInput);
+            }
+            this.activeProcesses.delete(teammate.name);
+        };
+        child.on("close", (code, signal) => {
+            cleanup();
+            const stdout = Buffer.concat(stdoutBufs).toString("utf-8");
+            const stderr = Buffer.concat(stderrBufs).toString("utf-8");
+            const output = stdout + (stderr ? `\n${stderr}` : "");
+            resolveOuter({
+                output: killed
+                    ? `${output}\n\n[TIMEOUT] Agent process killed after ${timeout}ms`
+                    : output,
+                stdout,
+                stderr,
+                exitCode: code,
+                signal: signal ?? null,
+                timedOut: killed,
+                debugFile,
             });
         });
+        child.on("error", (err) => {
+            cleanup();
+            rejectOuter(new Error(`Failed to spawn ${command}: ${err.message}`));
+        });
+        return done;
     }
 }
 // ─── Output parsing (shared across all agents) ─────────────────────

package/dist/cli-utils.d.ts

@@ -17,5 +17,34 @@ export declare function findAtMention(line: string, cursor: number): {
 } | null;
 /** Set of recognized image file extensions. */
 export declare const IMAGE_EXTS: Set<string>;
+/** A single entry in the conversation history. */
+export interface ConversationEntry {
+    role: string;
+    text: string;
+}
+/**
+ * Strip protocol artifacts (TO: header, handoff blocks, trailing JSON) from
+ * an agent's raw output, returning just the message body.
+ */
+export declare function cleanResponseBody(rawOutput: string): string;
+/**
+ * Format a conversation entry for inclusion in a prompt.
+ * Single-line text stays inline; multi-line text gets the body on the next line.
+ */
+export declare function formatConversationEntry(role: string, text: string): string;
+/**
+ * Build the conversation context section for a teammate prompt.
+ * Works backwards from newest entries, including whole entries up to the budget.
+ */
+export declare function buildConversationContext(history: ConversationEntry[], summary: string, budget: number): string;
+/**
+ * Find the split index where older conversation entries should be summarized.
+ * Returns 0 if everything fits within the budget (nothing to summarize).
+ */
+export declare function findSummarizationSplit(history: ConversationEntry[], budget: number): number;
+/**
+ * Build the summarization prompt text from entries being pushed out of the budget.
+ */
+export declare function buildSummarizationPrompt(entries: ConversationEntry[], existingSummary: string): string;
 /** Check if a string looks like an image file path. */
 export declare function isImagePath(text: string): boolean;