chapterhouse 0.3.1 → 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).
@@ -239,9 +254,47 @@ The deployment assets for the shared instance set Entra auth and `CHAPTERHOUSE_M
 | `chapterhouse update --check-only` | Print current/latest version without updating                    |
 | `chapterhouse update --ref <ver>`  | Install a specific version                                       |
 | `chapterhouse daemon <sub>`    | Manage the persistent background service          |
+| `chapterhouse squad init`      | Initialize a new Squad team for this project (guided dialog)     |
 | `chapterhouse squad worktree <sub>` | Manage per-agent git worktrees for concurrent squad work |
 | `chapterhouse help`            | Show available commands                           |
 
+### Squad Init Command
+
+Bootstrap a Squad team for a project that has no `.squad/` directory yet. The command runs an interactive dialog and writes the full `.squad/` scaffold:
+
+```sh
+chapterhouse squad init
+    # Runs the guided dialog: project name, stack, goal, team size, universe.
+    # Proposes a named roster, then writes .squad/ on confirmation.
+
+chapterhouse squad init --force
+    # Re-scaffolds even if .squad/ already exists (overwrites existing files).
+
+chapterhouse squad init --yes
+    # Skip the confirmation prompt (non-interactive / CI mode).
+
+chapterhouse squad init --universe Firefly
+    # Use a specific naming universe instead of the default (Dune).
+    # Available: Dune (default), Firefly, Star Wars, The Matrix, Breaking Bad
+```
+
+**What gets written:**
+
+| Path | Purpose |
+|------|---------|
+| `.squad/team.md` | Roster with `## Members` table (required by GitHub workflows) |
+| `.squad/routing.md` | Task routing rules by role |
+| `.squad/ceremonies.md` | Sprint rhythm and review gates |
+| `.squad/decisions.md` | Append-only decision log |
+| `.squad/agents/{name}/charter.md` | Per-agent charter with project context |
+| `.squad/agents/{name}/history.md` | Per-agent day-1 seed history |
+| `.squad/casting/policy.json` | Universe allowlist and capacity |
+| `.squad/casting/registry.json` | Persistent name registry (cast names survive re-runs) |
+| `.squad/casting/history.json` | Universe assignment audit trail |
+| `.gitattributes` | Union merge rules for append-only Squad files |
+
+**Naming universes:** By default, Squad uses the **Dune** universe (Leto, Jessica, Stilgar, Chani, Gurney, Duncan, …). This is configurable with `--universe` or via the dialog. Scribe and Ralph are always exempt from casting — they keep their names regardless of universe.
+
 ### Squad Worktree Commands
 
 Squad agents that work on GitHub issues each get a dedicated git worktree so they never step on each other. The `chapterhouse squad worktree` subcommands manage these worktrees:
@@ -319,9 +372,21 @@ Chapterhouse enforces a **3-layer timing contract** so in-flight LLM streams can
 
 **Rule:** each layer must exceed the one above it. Do not tighten `CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS` below `CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS`, and do not reduce `TimeoutStopSec` below `CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS`.
 
+#### Session lifecycle
+
+Each conversation window (browser tab, terminal session, squad worktree) maps to a separate `SessionManager` with its own queue and SDK session. Two env vars control how long sessions live:
+
+| Config | What it controls | Default |
+|--------|-----------------|---------|
+| `CHAPTERHOUSE_SESSION_IDLE_TTL_MS` | How long an idle session (no in-flight turn, empty queue) is kept before being disconnected | `1800000` (30 min) |
+| `CHAPTERHOUSE_SESSION_MAX_ACTIVE` | Maximum number of simultaneously active sessions; when reached, the least-recently-used *idle* session is evicted to make room | `20` |
+
+Busy sessions (processing a turn or with items queued) are never evicted by either mechanism.
+
 #### 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`)
@@ -343,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)
@@ -457,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`.
@@ -482,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/auth.js

@@ -1,5 +1,7 @@
 import jwt from "jsonwebtoken";
 import jwksClient from "jwks-rsa";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("auth");
 function getIssuer(tenantId) {
     return `https://login.microsoftonline.com/${tenantId}/v2.0`;
 }
@@ -137,8 +139,7 @@ export function createAuthMiddleware(options) {
         try {
             const claims = await verifyBearerToken(token, options.config);
             if (options.config.entraRequiredRole && !hasRequiredRole(claims, options.config.entraRequiredRole)) {
-                console.warn(`[auth] Token for ${claims.preferred_username || claims.oid} rejected: ` +
-                    `required role "${options.config.entraRequiredRole}" not found in roles=${JSON.stringify(claims.roles ?? [])}`);
+                log.warn({ username: claims.preferred_username || claims.oid, requiredRole: options.config.entraRequiredRole, roles: claims.roles ?? [] }, "token rejected: required app role not found");
                 unauthorized(res, "Unauthorized: user does not have the required app role");
                 return;
             }
@@ -151,7 +152,7 @@ export function createAuthMiddleware(options) {
             next();
         }
         catch (err) {
-            console.error("[auth] JWT verification failed:", err);
+            log.error({ err }, "JWT verification failed");
             unauthorized(res, "Unauthorized: invalid or expired token");
         }
     };

package/dist/api/auth.test.js

@@ -323,46 +323,34 @@ test("returns a generic message when JWT verification fails", async () => {
     const auth = await loadAuthModule();
     assert.ok(auth, "auth module should exist");
     assert.equal(typeof auth.createAuthMiddleware, "function", "createAuthMiddleware should be exported");
-    const originalConsoleError = console.error;
-    const logged = [];
-    console.error = (...args) => {
-        logged.push(args);
+    const middleware = auth.createAuthMiddleware({
+        apiToken: "legacy-token",
+        config: {
+            entraAuthEnabled: true,
+            standaloneMode: false,
+            entraClientId: "client-id",
+            entraTenantId: "tenant-id",
+            entraRequiredRole: "",
+            entraTeamLeadId: "",
+        },
+        verifyBearerToken: async () => {
+            throw new Error("jwt malformed");
+        },
+    });
+    const req = {
+        path: "/api/message",
+        headers: { authorization: "Bearer bad-token" },
+        query: {},
+        socket: { remoteAddress: "127.0.0.1" },
     };
-    try {
-        const middleware = auth.createAuthMiddleware({
-            apiToken: "legacy-token",
-            config: {
-                entraAuthEnabled: true,
-                standaloneMode: false,
-                entraClientId: "client-id",
-                entraTenantId: "tenant-id",
-                entraRequiredRole: "",
-                entraTeamLeadId: "",
-            },
-            verifyBearerToken: async () => {
-                throw new Error("jwt malformed");
-            },
-        });
-        const req = {
-            path: "/api/message",
-            headers: { authorization: "Bearer bad-token" },
-            query: {},
-            socket: { remoteAddress: "127.0.0.1" },
-        };
-        const res = createMockResponse();
-        let nextCalled = false;
-        await middleware(req, res, () => {
-            nextCalled = true;
-        });
-        assert.equal(nextCalled, false);
-        assert.equal(res.statusCode, 401);
-        assert.deepEqual(res.body, { error: "Unauthorized: invalid or expired token" });
-        assert.equal(logged.length, 1);
-        assert.equal(logged[0]?.[0], "[auth] JWT verification failed:");
-    }
-    finally {
-        console.error = originalConsoleError;
-    }
+    const res = createMockResponse();
+    let nextCalled = false;
+    await middleware(req, res, () => {
+        nextCalled = true;
+    });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+    assert.deepEqual(res.body, { error: "Unauthorized: invalid or expired token" });
 });
 // ---------------------------------------------------------------------------
 // Auth edge cases: JWKS cache + Entra error paths

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";
@@ -266,9 +266,12 @@ app.get("/api/workers/:taskId", (req, res) => {
     if (!row) {
         throw new NotFoundError("Task not found");
     }
+    const registry = getAgentRegistry();
+    const agent = registry.find((a) => a.slug === row.agent_slug);
     res.json({
         taskId: row.task_id,
         agentSlug: row.agent_slug,
+        name: agent?.name || row.agent_slug,
         description: row.description,
         status: row.status,
         result: row.result,
@@ -276,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/api/team.js

@@ -9,6 +9,7 @@ import { BadRequestError, ForbiddenError, InternalServerError, asBadRequest, par
 import { assertPagePath, ensureWikiStructure, getWikiDir, listPages, readPage, writePage, } from "../wiki/fs.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { TeamsNotifier, TEAMS_MILESTONE_THRESHOLDS } from "../integrations/teams-notify.js";
+import { childLogger } from "../util/logger.js";
 const wikiPageRoute = /^\/wiki\/(.+)$/;
 const updateSchema = z.object({
     engineerId: z.string().min(1),
@@ -111,10 +112,11 @@ function getCrossedMilestone(kr, delta) {
 }
 export function createTeamRouter(options) {
     const router = express.Router();
+    const log = childLogger("team");
     const now = options.now ?? (() => new Date());
     const teamsNotifier = options.teamsNotifier ?? new TeamsNotifier();
     const adoClient = options.adoClient ?? (config.adoPat ? new AdoClient() : undefined);
-    const warn = options.warn ?? ((message) => console.warn(message));
+    const warn = options.warn ?? ((message) => log.warn(message));
     router.use(options.authMiddleware);
     router.post("/update", async (req, res) => {
         const input = parseRequest(updateSchema, req.body);
@@ -187,7 +189,7 @@ export function createTeamRouter(options) {
             res.json({ ok: true, report });
         }
         catch (error) {
-            console.error("[team] Failed to generate report:", error);
+            log.error({ err: error instanceof Error ? error.message : error }, "failed to generate report");
             throw new InternalServerError();
         }
     });

package/dist/cli.js

@@ -25,7 +25,7 @@ Commands:
   setup            Pick a default model and write ~/.chapterhouse/.env
   update           Check for updates and install the latest version
   daemon <sub>     Manage the persistent background service (install/uninstall/start/stop/restart/status/logs)
-  squad <sub>      Squad agent tools (worktree management)
+  squad <sub>      Squad agent tools (init, worktree management)
   help             Show this help message
 
 Flags (start):
@@ -182,9 +182,13 @@ switch (command) {
     case "squad": {
         const squadSub = args[1];
         if (squadSub === 'worktree') {
-            const { runWorktreeCli, printWorktreeHelp } = await import("./squad/worktree.js");
+            const { runWorktreeCli } = await import("./squad/worktree.js");
             await runWorktreeCli(args.slice(2));
         }
+        else if (squadSub === 'init') {
+            const { runInitCli } = await import("./squad/init-cli.js");
+            await runInitCli(args.slice(2));
+        }
         else {
             if (squadSub) {
                 console.error(`Unknown squad subcommand: ${squadSub}\n`);
@@ -193,8 +197,10 @@ switch (command) {
 chapterhouse squad — Squad agent tools
 
 Subcommands:
+  init       Initialize a new Squad team for this project (guided dialog)
   worktree   Manage per-agent git worktrees (create / list / remove / prune)
 
+Run \`chapterhouse squad init\` to scaffold a .squad/ directory with a named team.
 Run \`chapterhouse squad worktree\` for worktree subcommand help.
 `.trim());
             if (squadSub)

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/episode-writer.js

@@ -12,6 +12,8 @@ import { addToIndex } from "../wiki/index-manager.js";
 import { appendLog } from "../wiki/log-manager.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { setBusy, setIdle } from "../status.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("episode-writer");
 const EPISODE_MODEL = "gpt-4.1";
 const EPISODE_TIMEOUT_MS = 30_000;
 const MIN_TURNS_FOR_SUMMARY = 10;
@@ -193,10 +195,10 @@ async function runEpisode(client) {
             setState(LAST_SUMMARY_TIME_KEY, String(now));
             setState(IN_PROGRESS_KEY, "");
         });
-        console.log(`[chapterhouse] Episode writer: summarized ${rows.length} turns (ids ${startId}-${endId}) → pages/conversations/${new Date().toISOString().slice(0, 10)}.md`);
+        log.info({ rows: rows.length, startId, endId }, "summarized turns");
     }
     catch (err) {
-        console.log(`[chapterhouse] Episode writer error (non-fatal): ${err instanceof Error ? err.message : err}`);
+        log.warn({ err: err instanceof Error ? err.message : err }, "episode writer error (non-fatal)");
         if (episodeSession) {
             episodeSession.destroy().catch(() => { });
             episodeSession = undefined;