chapterhouse 0.3.2 → 0.3.3

package/README.md

@@ -182,6 +182,21 @@ Optional Entra settings:
 - `ENTRA_REQUIRED_ROLE` — if set, the signed-in user must have this app role in the token's `roles` claim. This replaced the older group-based check.
 - `ENTRA_TEAM_LEAD_ID` — optional for regular engineers, who can omit it entirely. Set it only for the one person who should be treated as `team-lead` for managerial functions such as `/api/team/report` and protected OKR/KPI/team wiki writes. Without it, the signed-in user is treated as `engineer`, which is the correct role for normal team members.
 
+### WorkIQ MCP server (Entra only)
+
+When `ENTRA_AUTH_ENABLED=true`, Chapterhouse automatically adds a `workiq` entry to `~/.copilot/mcp-config.json` at daemon startup. This gives the orchestrator access to Microsoft 365 tools (Teams, Outlook, Calendar, etc.) via the `@microsoft/workiq` MCP server without any manual configuration.
+
+The entry uses `npx -y @microsoft/workiq` so no global npm install is required — npx fetches the server on first use.
+
+| Behaviour | Detail |
+|-----------|--------|
+| **Trigger** | `ENTRA_AUTH_ENABLED=true` + `ENTRA_TENANT_ID` set |
+| **Idempotent** | Safe to restart; entry is only written if `workiq` key is absent |
+| **Opt-out** | Set `CHAPTERHOUSE_WORKIQ_AUTO_INSTALL=false` to disable |
+| **Failure-safe** | If the write fails (permissions, read-only FS), a structured warning is logged and the daemon continues |
+
+**`CHAPTERHOUSE_WORKIQ_AUTO_INSTALL`** — `true` (default) or `false`. Set to `false` to manage the workiq MCP entry manually.
+
 ## Docker (Personal)
 
 For a single-user local deployment, use the personal compose file. It binds port `7788`, runs the daemon as the non-root `node` user, and persists state in `CHAPTERHOUSE_HOME` (default: `$HOME/.chapterhouse` on macOS/Linux).
@@ -371,6 +386,7 @@ Busy sessions (processing a turn or with items queued) are never evicted by eith
 #### Daemon PATH
 
 The generated systemd unit and launchd plist compose a rich `PATH` that includes:
+
 - The installing shell's `$PATH` (captured at install time)
 - The binary's own directory
 - Linuxbrew (`/home/linuxbrew/.linuxbrew/bin`), Homebrew (`/opt/homebrew/bin`, `/usr/local/bin`)
@@ -392,7 +408,7 @@ The browser app at `http://localhost:7788` is split into a few views:
 
 ## How it Works
 
-```
+```text
 Browser ──HTTP / SSE──► Chapterhouse Daemon
                             │
                       Orchestrator Session (Copilot SDK)
@@ -506,6 +522,12 @@ npm run dev:web
 
 # Build everything
 npm run build
+
+# Run tests
+npm test
+
+# Lint user-facing markdown (README, CHANGELOG, docs/, .github/)
+npm run lint:md
 ```
 
 The web UI lives in `web/`. Production builds emit to `web/dist/`, which the Express server serves out of in `src/api/server.ts`.
@@ -531,5 +553,6 @@ git push origin main --follow-tags
 All commits on this repository follow **[Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)**. The format is `<type>(<scope>): <subject>` (e.g. `feat(api): add session export endpoint`). Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`, `revert`, `release`.
 
 This is automatically enforced:
+
 - **Locally:** `husky` installs a `commit-msg` git hook on `npm install` that runs `commitlint` against every commit message. Bad messages are rejected before the commit lands.
 - **On PRs:** A GitHub Action (`lint-pr-title.yml`) validates the PR title on every open/edit. This matters because squash-merges use the PR title as the commit message on `main`.

package/dist/api/server.js

@@ -5,7 +5,7 @@ import { existsSync, statSync, readdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
-import { sendToOrchestrator, getAgentInfo, cancelCurrentMessage, getLastRouteResult, getCurrentSessionKey } from "../copilot/orchestrator.js";
+import { sendToOrchestrator, getAgentInfo, cancelCurrentMessage, getLastRouteResult, getCurrentSessionKey, subscribeTaskEvents } from "../copilot/orchestrator.js";
 import { getAgentRegistry } from "../copilot/agents.js";
 import { config, persistModel } from "../config.js";
 import { getRouterConfig, updateRouterConfig } from "../copilot/router.js";
@@ -19,7 +19,7 @@ import { withWikiWrite } from "../wiki/lock.js";
 import { listSkills, removeSkill } from "../copilot/skills.js";
 import { restartDaemon } from "../daemon.js";
 import { API_TOKEN_PATH, resolveWikiRelativePath } from "../paths.js";
-import { getDb, getSessionMessages } from "../store/db.js";
+import { getDb, getSessionMessages, getTaskEvents } from "../store/db.js";
 import { getStatus, onStatusChange } from "../status.js";
 import { formatSseData, formatSseEvent } from "./sse.js";
 import { syncDecisionsFileToWiki } from "../squad/mirror.js";
@@ -279,6 +279,44 @@ app.get("/api/workers/:taskId", (req, res) => {
         completedAt: row.completed_at,
     });
 });
+// Historical event log for a task (catch-up on page load)
+app.get("/api/workers/:taskId/events", (req, res) => {
+    const taskId = req.params.taskId;
+    const afterSeqRaw = req.query.afterSeq;
+    const afterSeq = typeof afterSeqRaw === "string" && !isNaN(Number(afterSeqRaw)) ? Number(afterSeqRaw) : 0;
+    const taskRow = getDb()
+        .prepare(`SELECT task_id FROM agent_tasks WHERE task_id = ?`)
+        .get(taskId);
+    if (!taskRow) {
+        throw new NotFoundError("Task not found");
+    }
+    const events = getTaskEvents(taskId, afterSeq);
+    res.json({ taskId, events });
+});
+// SSE stream for per-task live tool-call activity
+app.get("/api/workers/:taskId/events/stream", (req, res) => {
+    const taskId = req.params.taskId;
+    const taskRow = getDb()
+        .prepare(`SELECT task_id FROM agent_tasks WHERE task_id = ?`)
+        .get(taskId);
+    if (!taskRow) {
+        throw new NotFoundError("Task not found");
+    }
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    res.write(formatSseData({ type: "connected", taskId }));
+    const heartbeat = setInterval(() => { res.write(`:ping\n\n`); }, 20_000);
+    const unsub = subscribeTaskEvents(taskId, (event) => {
+        res.write(formatSseData({ type: "task_event", taskId, ...event }));
+    });
+    req.on("close", () => {
+        clearInterval(heartbeat);
+        unsub();
+    });
+});
 // ---------------------------------------------------------------------------
 // SSE stream for real-time chat
 // ---------------------------------------------------------------------------

package/dist/config.js

@@ -46,6 +46,7 @@ const configSchema = z.object({
     API_RATE_LIMIT_AUTH_MAX: z.string().optional(),
     API_RATE_LIMIT_SSE_MAX_CONNECTIONS: z.string().optional(),
     ENABLE_SQUAD: z.string().optional(),
+    CHAPTERHOUSE_WORKIQ_AUTO_INSTALL: z.string().optional(),
 });
 export const DEFAULT_MODEL = "claude-sonnet-4.6";
 export const DEFAULT_TEAM_WIKI_CACHE_TTL_MINUTES = 60;
@@ -219,6 +220,7 @@ export function parseRuntimeConfig(env, options = {}) {
         apiRateLimitAuthMax,
         apiRateLimitSseMaxConnections,
         squadEnabled: raw.ENABLE_SQUAD === "1",
+        workiqAutoInstall: parseBooleanEnv("CHAPTERHOUSE_WORKIQ_AUTO_INSTALL", raw.CHAPTERHOUSE_WORKIQ_AUTO_INSTALL, true),
     };
 }
 const runtimeConfig = parseRuntimeConfig(process.env);
@@ -258,6 +260,7 @@ export const config = {
     apiRateLimitAuthMax: runtimeConfig.apiRateLimitAuthMax,
     apiRateLimitSseMaxConnections: runtimeConfig.apiRateLimitSseMaxConnections,
     squadEnabled: runtimeConfig.squadEnabled,
+    workiqAutoInstall: runtimeConfig.workiqAutoInstall,
     copilotAuthToken: runtimeConfig.copilotAuthToken,
     get copilotModel() {
         return _copilotModel;

package/dist/copilot/orchestrator.js

@@ -7,7 +7,7 @@ import { config, DEFAULT_MODEL } from "../config.js";
 import { loadMcpConfig } from "./mcp-config.js";
 import { getSkillDirectories } from "./skills.js";
 import { resetClient } from "./client.js";
-import { logConversation, getState, setState, deleteState, getCopilotSession, upsertCopilotSession, getTaskSessionKey, getDb, bumpProjectLastUsed } from "../store/db.js";
+import { logConversation, getState, setState, deleteState, getCopilotSession, upsertCopilotSession, getTaskSessionKey, getDb, bumpProjectLastUsed, appendTaskEvent } from "../store/db.js";
 import { maybeWriteEpisode } from "./episode-writer.js";
 import { getWikiSummary } from "../wiki/context.js";
 import { SESSIONS_DIR } from "../paths.js";
@@ -51,6 +51,32 @@ let lastRouteResult;
 export function getLastRouteResult() {
     return lastRouteResult;
 }
+const taskEventListeners = new Map();
+export function subscribeTaskEvents(taskId, listener) {
+    if (!taskEventListeners.has(taskId)) {
+        taskEventListeners.set(taskId, new Set());
+    }
+    taskEventListeners.get(taskId).add(listener);
+    return () => {
+        const set = taskEventListeners.get(taskId);
+        if (set) {
+            set.delete(listener);
+            if (set.size === 0)
+                taskEventListeners.delete(taskId);
+        }
+    };
+}
+function emitTaskEvent(taskId, event) {
+    const set = taskEventListeners.get(taskId);
+    if (set) {
+        for (const listener of set) {
+            try {
+                listener(event);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // SessionRegistry — the single owner of all per-session orchestrators
 // ---------------------------------------------------------------------------
@@ -333,6 +359,21 @@ async function executeOnSession(manager, item) {
         let accumulated = "";
         let toolCallExecuted = false;
         let toolCallCount = 0;
+        // Per-turn map: toolCallId → spawn args stashed from tool.execution_start when toolName === "task".
+        // Correlates the SDK's subagent.started event (which only carries agent_type fields) with the
+        // actual spawn parameters (name, description) passed to the task() tool call.
+        const spawnArgsMap = new Map();
+        // Unconditional capture — must fire even when onActivity is absent so the DB handler can resolve names.
+        const unsubSpawnCapture = session.on("tool.execution_start", (event) => {
+            const data = event.data;
+            if (data.toolName === "task" && data.toolCallId) {
+                const args = (data.arguments ?? {});
+                spawnArgsMap.set(data.toolCallId, {
+                    name: typeof args.name === "string" ? args.name : undefined,
+                    description: typeof args.description === "string" ? args.description : undefined,
+                });
+            }
+        });
         const unsubToolDone = session.on("tool.execution_complete", (event) => {
             toolCallExecuted = true;
             toolCallCount++;
@@ -378,12 +419,20 @@ async function executeOnSession(manager, item) {
         const unsubSubStart = item.onActivity
             ? session.on("subagent.started", (event) => {
                 const data = event.data;
+                const spawnArgs = spawnArgsMap.get(data.toolCallId);
+                const agentSlug = (typeof spawnArgs?.name === "string" ? spawnArgs.name : (data.agentName || "unknown"))
+                    .toLowerCase()
+                    .replace(/\s+/g, "-");
+                const resolvedDescription = (typeof spawnArgs?.description === "string"
+                    ? spawnArgs.description
+                    : data.agentDescription || data.agentDisplayName || `Squad dispatch: ${agentSlug}`).slice(0, 500);
                 item.onActivity({
                     kind: "subagent_started",
                     toolCallId: data.toolCallId,
                     agentName: data.agentName,
                     agentDisplayName: data.agentDisplayName,
-                    agentDescription: data.agentDescription,
+                    agentDescription: resolvedDescription,
+                    agentSlug,
                 });
             })
             : () => { };
@@ -413,17 +462,27 @@ async function executeOnSession(manager, item) {
             : () => { };
         // Always persist SDK subagent dispatches to agent_tasks so Workers tab shows them.
         const db = getDb();
+        // Set of task IDs for subagents spawned in THIS turn — used to filter nested tool events.
+        const activeSubagentTaskIds = new Set();
         const unsubSubStartDb = session.on("subagent.started", (event) => {
             try {
                 const data = event.data;
-                const agentSlug = (data.agentName || "unknown").toLowerCase().replace(/\s+/g, "-");
-                const description = (data.agentDescription || data.agentDisplayName || `Squad dispatch: ${agentSlug}`).slice(0, 500);
+                const spawnArgs = spawnArgsMap.get(data.toolCallId);
+                const agentSlug = (typeof spawnArgs?.name === "string" ? spawnArgs.name : (data.agentName || "unknown"))
+                    .toLowerCase()
+                    .replace(/\s+/g, "-");
+                const description = (typeof spawnArgs?.description === "string"
+                    ? spawnArgs.description
+                    : data.agentDescription || data.agentDisplayName || `Squad dispatch: ${agentSlug}`).slice(0, 500);
                 db.prepare(`INSERT OR IGNORE INTO agent_tasks (task_id, agent_slug, description, status, origin_channel, session_key, source) VALUES (?, ?, ?, 'running', ?, ?, 'squad')`).run(data.toolCallId, agentSlug, description, item.sourceChannel || null, sessionKey);
+                activeSubagentTaskIds.add(data.toolCallId);
             }
             catch { /* non-fatal */ }
         });
         const unsubSubDoneDb = session.on("subagent.completed", (event) => {
             try {
+                spawnArgsMap.delete(event.data.toolCallId);
+                activeSubagentTaskIds.delete(event.data.toolCallId);
                 db.prepare(`UPDATE agent_tasks SET status = 'completed', completed_at = CURRENT_TIMESTAMP WHERE task_id = ?`).run(event.data.toolCallId);
             }
             catch { /* non-fatal */ }
@@ -431,10 +490,57 @@ async function executeOnSession(manager, item) {
         const unsubSubFailDb = session.on("subagent.failed", (event) => {
             try {
                 const data = event.data;
+                spawnArgsMap.delete(data.toolCallId);
+                activeSubagentTaskIds.delete(data.toolCallId);
                 db.prepare(`UPDATE agent_tasks SET status = 'error', result = ?, completed_at = CURRENT_TIMESTAMP WHERE task_id = ?`).run(data.error || "Subagent failed", data.toolCallId);
             }
             catch { /* non-fatal */ }
         });
+        // ---------------------------------------------------------------------------
+        // Nested tool-call streaming — capture tool.execution_start / _complete events
+        // whose parentToolCallId matches a known subagent task id, persist them to
+        // agent_task_events, and broadcast to per-task SSE subscribers.
+        // ---------------------------------------------------------------------------
+        const unsubNestedToolStart = session.on("tool.execution_start", (event) => {
+            try {
+                const data = event.data;
+                const parentId = data.parentToolCallId;
+                if (!parentId || !activeSubagentTaskIds.has(parentId))
+                    return;
+                const toolName = data.toolName ?? null;
+                const args = data.arguments ?? {};
+                let summary = null;
+                if (typeof args.command === "string")
+                    summary = args.command.slice(0, 120);
+                else if (typeof args.path === "string")
+                    summary = args.path.slice(0, 120);
+                else if (typeof args.query === "string")
+                    summary = args.query.slice(0, 120);
+                else if (typeof args.prompt === "string")
+                    summary = args.prompt.slice(0, 120);
+                const ev = appendTaskEvent(parentId, "tool_start", toolName, summary);
+                if (ev)
+                    emitTaskEvent(parentId, ev);
+            }
+            catch { /* non-fatal */ }
+        });
+        const unsubNestedToolDone = session.on("tool.execution_complete", (event) => {
+            try {
+                const data = event.data;
+                const parentId = data.parentToolCallId;
+                if (!parentId || !activeSubagentTaskIds.has(parentId))
+                    return;
+                const success = data.success !== false;
+                const resultContent = data.result?.content ?? data.result?.detailedContent;
+                const summary = typeof resultContent === "string"
+                    ? (success ? resultContent.slice(0, 120) : `error: ${resultContent.slice(0, 100)}`)
+                    : (success ? "ok" : "error");
+                const ev = appendTaskEvent(parentId, "tool_complete", null, summary);
+                if (ev)
+                    emitTaskEvent(parentId, ev);
+            }
+            catch { /* non-fatal */ }
+        });
         const unsubDelta = session.on("assistant.message_delta", (event) => {
             if (toolCallExecuted && accumulated.length > 0 && !accumulated.endsWith("\n")) {
                 accumulated += "\n";
@@ -474,6 +580,7 @@ async function executeOnSession(manager, item) {
             unsubDelta();
             unsubToolDone();
             unsubToolStart();
+            unsubSpawnCapture();
             unsubReasoning();
             unsubSubStart();
             unsubSubDone();
@@ -481,6 +588,8 @@ async function executeOnSession(manager, item) {
             unsubSubStartDb();
             unsubSubDoneDb();
             unsubSubFailDb();
+            unsubNestedToolStart();
+            unsubNestedToolDone();
         }
     });
 }

package/dist/copilot/orchestrator.test.js

@@ -98,6 +98,7 @@ async function loadOrchestratorModule(t, overrides = {}) {
             { slug: "coder", name: "Kaylee", model: "claude-sonnet-4.6" },
         ],
         sendResult: "Finished successfully",
+        taskEvents: new Map(),
         ...overrides,
     };
     const client = createFakeClient(state);
@@ -181,8 +182,17 @@ async function loadOrchestratorModule(t, overrides = {}) {
                     get: () => undefined,
                     all: () => [],
                 }),
+                transaction: (fn) => fn,
             }),
             bumpProjectLastUsed: (_projectRoot) => { },
+            appendTaskEvent: (taskId, kind, toolName, summary) => {
+                const seq = (state.taskEvents.get(taskId)?.length ?? 0) + 1;
+                const ev = { id: seq, taskId, seq, ts: Date.now(), kind, toolName, summary };
+                if (!state.taskEvents.has(taskId))
+                    state.taskEvents.set(taskId, []);
+                state.taskEvents.get(taskId).push(ev);
+                return ev;
+            },
         },
     });
     t.mock.module("./episode-writer.js", {
@@ -665,4 +675,199 @@ test("regression #35: session A blocking does not delay session B (concurrent se
     state.pendingReject?.(new Error("test teardown"));
     await new Promise((resolve) => setTimeout(resolve, 10));
 });
+// ---------------------------------------------------------------------------
+// #81 — task spawn args (name/description) must win over SDK agent_type fields
+// Root cause: subagent.started only carries agent_type boilerplate. The actual
+// spawn params (name, description) arrive earlier via tool.execution_start for
+// toolName === "task". We stash them keyed by toolCallId and prefer them in the
+// INSERT so the worker tab shows "kaylee" instead of "general-purpose".
+// ---------------------------------------------------------------------------
+test("#81: tool.execution_start stash + subagent.started → agent_tasks uses spawn name/description", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("dispatch a worker", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    // Step 1: emit tool.execution_start for a "task" call with spawn parameters
+    state.lastSession.emit("tool.execution_start", {
+        toolName: "task",
+        toolCallId: "tc-spawn-1",
+        arguments: { name: "kaylee", description: "🔧 Kaylee: test spawn" },
+    });
+    // Step 2: emit subagent.started with the same toolCallId — SDK only knows agent_type details
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "tc-spawn-1",
+        agentName: "general-purpose",
+        agentDisplayName: "General Purpose Agent",
+        agentDescription: "Full-capability agent boilerplate",
+    });
+    const insertWrite = state.dbWrites.find((w) => w.sql.includes("INSERT") && w.sql.includes("agent_tasks"));
+    assert.ok(insertWrite, "subagent.started must INSERT a row into agent_tasks");
+    const argsJson = JSON.stringify(insertWrite.args);
+    assert.ok(argsJson.includes("kaylee"), `agent_slug must be "kaylee" but got: ${argsJson}`);
+    assert.ok(argsJson.includes("🔧 Kaylee: test spawn"), `description must be spawn description but got: ${argsJson}`);
+    assert.ok(!argsJson.includes("general-purpose"), `agent_slug must NOT fall back to "general-purpose" when spawn name is available`);
+    state.pendingReject?.(new Error("test teardown"));
+});
+test("#81 fallback: subagent.started with no prior tool.execution_start uses agentName/agentDescription", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("dispatch a worker", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    // No tool.execution_start emitted — subagent.started fires cold
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "tc-no-spawn",
+        agentName: "general-purpose",
+        agentDisplayName: "General Purpose Agent",
+        agentDescription: "Full-capability agent boilerplate",
+    });
+    const insertWrite = state.dbWrites.find((w) => w.sql.includes("INSERT") && w.sql.includes("agent_tasks"));
+    assert.ok(insertWrite, "subagent.started must still INSERT a row without spawn args");
+    const argsJson = JSON.stringify(insertWrite.args);
+    assert.ok(argsJson.includes("general-purpose"), `agent_slug must fall back to agentName ("general-purpose") when no spawn args: ${argsJson}`);
+    assert.ok(argsJson.includes("Full-capability agent boilerplate"), `description must fall back to agentDescription: ${argsJson}`);
+    state.pendingReject?.(new Error("test teardown"));
+});
+test("#81: activity callback receives resolved agentSlug from spawn args (SSE live path)", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    const activityEvents = [];
+    orchestrator.sendToOrchestrator("dispatch a worker", { type: "background" }, () => { }, undefined, // no attachments
+    (event) => { activityEvents.push(event); });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    // Stash spawn args via tool.execution_start
+    state.lastSession.emit("tool.execution_start", {
+        toolName: "task",
+        toolCallId: "tc-activity-1",
+        arguments: { name: "kaylee", description: "🔧 Kaylee: test spawn" },
+    });
+    // SDK fires subagent.started with boilerplate agent_type fields
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "tc-activity-1",
+        agentName: "general-purpose",
+        agentDisplayName: "General Purpose Agent",
+        agentDescription: "Full-capability agent boilerplate",
+    });
+    const startedEvent = activityEvents.find((e) => e.kind === "subagent_started");
+    assert.ok(startedEvent, "onActivity must have been called with a subagent_started event");
+    assert.equal(startedEvent.agentSlug, "kaylee", `agentSlug in activity event must be "kaylee" (spawn name), got: ${startedEvent.agentSlug}`);
+    assert.ok(String(startedEvent.agentDescription).includes("🔧 Kaylee"), `agentDescription in activity event must use spawn description, got: ${startedEvent.agentDescription}`);
+    state.pendingReject?.(new Error("test teardown"));
+});
+// ---------------------------------------------------------------------------
+// #86: Nested tool-call events streamed to /workers detail pane
+// ---------------------------------------------------------------------------
+test("#86: tool.execution_start with parentToolCallId matching active subagent calls appendTaskEvent", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("dispatch kaylee", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    // Register the subagent task via subagent.started so activeSubagentTaskIds is populated
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "subagent-task-001",
+        agentName: "kaylee",
+        agentDisplayName: "Kaylee — Backend Dev",
+        agentDescription: "Fix the streaming gap",
+    });
+    // Fire a nested tool.execution_start with parentToolCallId pointing to the subagent
+    state.lastSession.emit("tool.execution_start", {
+        toolCallId: "nested-call-001",
+        toolName: "bash",
+        parentToolCallId: "subagent-task-001",
+        arguments: { command: "npm run build" },
+    });
+    const events = state.taskEvents.get("subagent-task-001") ?? [];
+    assert.equal(events.length, 1, "appendTaskEvent must have been called once for the nested tool start");
+    assert.equal(events[0].kind, "tool_start");
+    assert.equal(events[0].toolName, "bash");
+    assert.equal(events[0].summary, "npm run build");
+    state.pendingReject?.(new Error("test teardown"));
+});
+test("#86: tool.execution_start with parentToolCallId NOT in active subagents is ignored", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("run something", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    // No subagent.started fired — activeSubagentTaskIds is empty
+    state.lastSession.emit("tool.execution_start", {
+        toolCallId: "nested-call-002",
+        toolName: "bash",
+        parentToolCallId: "unknown-parent",
+        arguments: { command: "echo hi" },
+    });
+    const events = state.taskEvents.get("unknown-parent") ?? [];
+    assert.equal(events.length, 0, "appendTaskEvent must NOT be called when parentToolCallId is not a known subagent");
+    state.pendingReject?.(new Error("test teardown"));
+});
+test("#86: tool.execution_complete with parentToolCallId calls appendTaskEvent with tool_complete", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("dispatch agent", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "subagent-task-002",
+        agentName: "zoe",
+        agentDisplayName: "Zoe — QA",
+        agentDescription: "Run tests",
+    });
+    state.lastSession.emit("tool.execution_complete", {
+        toolCallId: "nested-call-003",
+        parentToolCallId: "subagent-task-002",
+        success: true,
+        result: { content: "All tests passed" },
+    });
+    const events = state.taskEvents.get("subagent-task-002") ?? [];
+    assert.equal(events.length, 1, "appendTaskEvent must have been called for tool_complete");
+    assert.equal(events[0].kind, "tool_complete");
+    assert.ok(String(events[0].summary).includes("All tests passed"), `summary must include result content, got: ${events[0].summary}`);
+    state.pendingReject?.(new Error("test teardown"));
+});
+test("#86: subagent.completed removes task from activeSubagentTaskIds — subsequent nested events ignored", async (t) => {
+    const { orchestrator, state, client } = await loadOrchestratorModule(t, {
+        sendResult: "__PENDING__",
+    });
+    await orchestrator.initOrchestrator(client);
+    orchestrator.sendToOrchestrator("dispatch agent", { type: "background" }, () => { });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(state.lastSession, "FakeSession must have been created");
+    state.lastSession.emit("subagent.started", {
+        toolCallId: "subagent-task-003",
+        agentName: "wash",
+        agentDisplayName: "Wash",
+        agentDescription: "UI work",
+    });
+    // Complete the subagent — removes from activeSubagentTaskIds
+    state.lastSession.emit("subagent.completed", {
+        toolCallId: "subagent-task-003",
+        agentName: "wash",
+        agentDisplayName: "Wash",
+    });
+    // Nested event arriving after completion must be ignored
+    state.lastSession.emit("tool.execution_start", {
+        toolCallId: "late-tool-call",
+        toolName: "view",
+        parentToolCallId: "subagent-task-003",
+        arguments: { path: "/some/file" },
+    });
+    const events = state.taskEvents.get("subagent-task-003") ?? [];
+    assert.equal(events.length, 0, "No task events must be recorded after subagent completes");
+    state.pendingReject?.(new Error("test teardown"));
+});
 //# sourceMappingURL=orchestrator.test.js.map

package/dist/copilot/session-manager.js

@@ -53,6 +53,11 @@ export class SessionManager {
     _currentModel;
     _recentTiers = [];
     _lastActivityAt = Date.now();
+    /** Set by registry.close() when the session is busy at close time. The drain loop
+     * honors this after the queue fully empties — evicting without violating the
+     * never-evict-mid-turn invariant. */
+    _pendingClose = false;
+    _onPendingCloseEvict;
     constructor(sessionKey, worker, sessionFactory) {
         this.worker = worker;
         this.sessionFactory = sessionFactory;
@@ -72,6 +77,19 @@ export class SessionManager {
     get lastActivityAt() {
         return this._lastActivityAt;
     }
+    /** True when an explicit close was requested while the session was busy. */
+    get pendingClose() {
+        return this._pendingClose;
+    }
+    /**
+     * Mark this session for deferred eviction. Called by SessionRegistry.close()
+     * when the session is mid-turn or has queued messages. The drain loop calls
+     * `onEvict` after the queue fully empties.
+     */
+    setPendingClose(onEvict) {
+        this._pendingClose = true;
+        this._onPendingCloseEvict = onEvict;
+    }
     // ── Session and model state (for orchestrator.ts) ────────────────────────
     get session() {
         return this._session;
@@ -136,6 +154,11 @@ export class SessionManager {
             this._lastActivityAt = Date.now();
         }
         this._processing = false;
+        // Honor deferred explicit-close: evict now that the queue is empty.
+        if (this._pendingClose && this._queue.length === 0) {
+            log.info({ sessionKey: this.sessionKey }, "session.pendingClose.evicting");
+            this._onPendingCloseEvict?.();
+        }
     }
     // ── Session lifecycle ────────────────────────────────────────────────────
     /** Ensure the CopilotSession exists, creating/resuming if needed. Concurrency-safe. */
@@ -245,14 +268,21 @@ export class SessionRegistry {
     }
     /**
      * Explicitly close a session (e.g., browser tab closed).
-     * Deferred (with warning) if the session is currently busy.
+     * If busy (mid-turn or queued messages), sets _pendingClose on the manager so the
+     * drain loop evicts it as soon as the queue empties — honoring the explicit-close
+     * intent without violating the never-evict-mid-turn invariant.
      */
     close(sessionKey, reason) {
         const manager = this.managers.get(sessionKey);
         if (!manager)
             return;
         if (!manager.canEvict) {
-            log.warn({ sessionKey, reason }, "Eviction deferred — session is mid-turn or has queued messages");
+            log.info({ sessionKey, reason }, "session.close.deferred — session is busy; will evict when queue drains");
+            manager.setPendingClose(() => {
+                this.managers.delete(sessionKey);
+                void manager.evict(reason);
+                log.info({ sessionKey, reason }, "session.evicted (deferred)");
+            });
             return;
         }
         this.managers.delete(sessionKey);