chapterhouse 0.5.1 → 0.6.0

package/.pr-types.json

@@ -0,0 +1,14 @@
+[
+  "feat",
+  "fix",
+  "docs",
+  "style",
+  "refactor",
+  "perf",
+  "test",
+  "chore",
+  "build",
+  "ci",
+  "revert",
+  "release"
+]

package/README.md

@@ -91,6 +91,12 @@ cd ~/.chapterhouse/src
 npm install && npm run build && npm link
 ```
 
+If you're opening a sprint PR from the repo, validate the title first:
+
+```bash
+npm run pr:title:check -- "chore: add PR title preflight validation"
+```
+
 ## Upgrading
 
 ```bash

package/dist/api/server.js

@@ -9,6 +9,7 @@ import { sendToOrchestrator, interruptCurrentTurn, enqueueForSse, getAgentInfo,
 import { agentEventBus } from "../copilot/agent-event-bus.js";
 import { ensureDefaultAgents, getAgentRegistry, loadAgents } from "../copilot/agents.js";
 import { config, persistModel } from "../config.js";
+import { ModeContext } from "../mode-context.js";
 import { getRouterConfig, updateRouterConfig } from "../copilot/router.js";
 import { searchIndex, parseIndex } from "../wiki/index-manager.js";
 import { createAuthMiddleware, getBootstrapAuthResponse } from "./auth.js";
@@ -34,6 +35,7 @@ import { childLogger } from "../util/logger.js";
 import { getActiveScope } from "../memory/active-scope.js";
 import { createScope, getScope } from "../memory/scopes.js";
 const log = childLogger("server");
+const modeContext = new ModeContext(config);
 void searchIndex; // re-exported by index-manager; reference here documents the dep
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Built SPA bundle (web/dist/), shipped alongside dist/
@@ -148,7 +150,7 @@ catch (err) {
     log.error({ err: err instanceof Error ? err.message : String(err) }, "Auth token error");
     process.exit(1);
 }
-if (config.standaloneMode) {
+if (modeContext.isPersonal() && config.standaloneMode) {
     log.warn("Running without authentication — team features disabled");
 }
 function isLoopbackHostname(hostname) {
@@ -262,7 +264,7 @@ function assertValidPagePath(path) {
     }
 }
 function getWikiPageScope(path) {
-    return teamWikiSync.isTeamPath(path) ? "team" : "personal";
+    return modeContext.canSyncTeamWiki() && teamWikiSync.isTeamPath(path) ? "team" : "personal";
 }
 function getEmptyWikiWelcomeContent(today = new Date()) {
     return `---
@@ -1027,7 +1029,7 @@ app.put("/api/projects/:slug/rules/soft", async (req, res) => {
 app.get("/api/wiki/pages", async (req, res) => {
     ensureWikiStructure();
     // Sync team wiki pages if connected, using the caller's auth token
-    if (teamWikiSync.isEnabled()) {
+    if (modeContext.canSyncTeamWiki() && teamWikiSync.isEnabled()) {
         const authorizationHeader = typeof req.headers.authorization === "string"
             ? req.headers.authorization
             : undefined;

package/dist/cli.js

@@ -61,9 +61,11 @@ switch (command) {
         await import("./daemon.js");
         break;
     }
-    case "setup":
-        await import("./setup.js");
+    case "setup": {
+        const { runSetup } = await import("./setup.js");
+        await runSetup();
         break;
+    }
     case "update": {
         const updateFlags = args.slice(1);
         const checkOnly = updateFlags.includes("--check-only");

package/dist/config.js

@@ -2,6 +2,7 @@ import { config as loadEnv } from "dotenv";
 import { z } from "zod";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { API_TOKEN_PATH, ENV_PATH, ensureChapterhouseHome } from "./paths.js";
+export { ModeContext } from "./mode-context.js";
 export const DISABLE_DOTENV_ENV_VAR = "CHAPTERHOUSE_DISABLE_DOTENV";
 const DEFAULT_WORKER_TIMEOUT_MS = 900_000;
 const BOOLEAN_ENV_PATTERN = /^(true|false)$/;
@@ -176,6 +177,43 @@ function parseEntityCategories(rawValue) {
         .filter(Boolean);
     return cats.length > 0 ? [...new Set(cats)] : [...DEFAULT_ENTITY_CATEGORIES];
 }
+function configuredKeys(entries) {
+    return entries
+        .filter(([, value]) => typeof value === "boolean" ? value : value.trim().length > 0)
+        .map(([key]) => key);
+}
+function buildModeCompatibilityWarnings(raw, mode) {
+    if (mode !== "personal") {
+        return [];
+    }
+    const warnings = [];
+    const adoKeys = configuredKeys([
+        ["ADO_ORG", raw.ADO_ORG?.trim() || ""],
+        ["ADO_PROJECT", raw.ADO_PROJECT?.trim() || ""],
+        ["ADO_PAT", raw.ADO_PAT?.trim() || ""],
+    ]);
+    if (adoKeys.length > 0 && adoKeys.length < 3) {
+        warnings.push(`Personal mode detected incomplete Azure DevOps settings (${adoKeys.join(", ")}); those team-only settings may be ignored.`);
+    }
+    const entraKeys = configuredKeys([
+        ["ENTRA_AUTH_ENABLED", raw.ENTRA_AUTH_ENABLED?.trim() === "true"],
+        ["ENTRA_TENANT_ID", raw.ENTRA_TENANT_ID?.trim() || ""],
+        ["ENTRA_CLIENT_ID", raw.ENTRA_CLIENT_ID?.trim() || ""],
+        ["ENTRA_REQUIRED_ROLE", raw.ENTRA_REQUIRED_ROLE?.trim() || ""],
+        ["ENTRA_TEAM_LEAD_ID", raw.ENTRA_TEAM_LEAD_ID?.trim() || ""],
+    ]);
+    if (entraKeys.length > 0) {
+        warnings.push(`Personal mode ignores Entra auth settings (${entraKeys.join(", ")}).`);
+    }
+    const teamsKeys = configuredKeys([
+        ["TEAMS_NOTIFICATIONS_ENABLED", raw.TEAMS_NOTIFICATIONS_ENABLED?.trim() === "true"],
+        ["TEAMS_WEBHOOK_URL", raw.TEAMS_WEBHOOK_URL?.trim() || ""],
+    ]);
+    if (teamsKeys.length > 0) {
+        warnings.push(`Personal mode ignores Teams notification settings (${teamsKeys.join(", ")}).`);
+    }
+    return warnings;
+}
 function resolveConfiguredApiToken(envToken, { apiTokenPath = API_TOKEN_PATH, exists = existsSync, readFile = readFileSync, } = {}) {
     const trimmedEnvToken = envToken?.trim();
     if (trimmedEnvToken) {
@@ -220,11 +258,33 @@ export function parseRuntimeConfig(env, options = {}) {
     const entraClientId = raw.ENTRA_CLIENT_ID?.trim() || "";
     const entraRequiredRole = raw.ENTRA_REQUIRED_ROLE?.trim() || "";
     const entraTeamLeadId = raw.ENTRA_TEAM_LEAD_ID?.trim() || "";
-    const entraAuthEnabled = parseBooleanEnv("ENTRA_AUTH_ENABLED", raw.ENTRA_AUTH_ENABLED, false);
+    const rawEntraAuthEnabled = parseBooleanEnv("ENTRA_AUTH_ENABLED", raw.ENTRA_AUTH_ENABLED, false);
+    if (parsedMode === "personal" && rawEntraAuthEnabled) {
+        throw new Error("Personal mode cannot be used with ENTRA_AUTH_ENABLED=true. Set CHAPTERHOUSE_MODE=team to use Entra auth, or unset ENTRA_AUTH_ENABLED to run in unauthenticated personal mode.");
+    }
+    const parsedTeamsWebhookUrl = parseOptionalUrl("TEAMS_WEBHOOK_URL", raw.TEAMS_WEBHOOK_URL);
+    const rawTeamsNotificationsEnabled = parseBooleanEnv("TEAMS_NOTIFICATIONS_ENABLED", raw.TEAMS_NOTIFICATIONS_ENABLED, false);
+    const modeCompatibilityWarnings = buildModeCompatibilityWarnings(raw, parsedMode);
+    const personalModeIgnoresEntra = parsedMode === "personal" && configuredKeys([
+        ["ENTRA_AUTH_ENABLED", rawEntraAuthEnabled],
+        ["ENTRA_TENANT_ID", entraTenantId],
+        ["ENTRA_CLIENT_ID", entraClientId],
+        ["ENTRA_REQUIRED_ROLE", entraRequiredRole],
+        ["ENTRA_TEAM_LEAD_ID", entraTeamLeadId],
+    ]).length > 0;
+    const personalModeIgnoresTeams = parsedMode === "personal" && configuredKeys([
+        ["TEAMS_NOTIFICATIONS_ENABLED", rawTeamsNotificationsEnabled],
+        ["TEAMS_WEBHOOK_URL", parsedTeamsWebhookUrl],
+    ]).length > 0;
+    const effectiveEntraAuthEnabled = personalModeIgnoresEntra ? false : rawEntraAuthEnabled;
+    const effectiveEntraTenantId = personalModeIgnoresEntra ? "" : entraTenantId;
+    const effectiveEntraClientId = personalModeIgnoresEntra ? "" : entraClientId;
+    const effectiveEntraRequiredRole = personalModeIgnoresEntra ? "" : entraRequiredRole;
+    const effectiveEntraTeamLeadId = personalModeIgnoresEntra ? "" : entraTeamLeadId;
+    const effectiveTeamsWebhookUrl = personalModeIgnoresTeams ? "" : parsedTeamsWebhookUrl;
+    const effectiveTeamsNotificationsEnabled = personalModeIgnoresTeams ? false : rawTeamsNotificationsEnabled;
     const apiToken = resolveConfiguredApiToken(raw.API_TOKEN, options);
-    const standaloneMode = !entraAuthEnabled && !apiToken;
-    const teamsWebhookUrl = parseOptionalUrl("TEAMS_WEBHOOK_URL", raw.TEAMS_WEBHOOK_URL);
-    const teamsNotificationsEnabled = parseBooleanEnv("TEAMS_NOTIFICATIONS_ENABLED", raw.TEAMS_NOTIFICATIONS_ENABLED, false);
+    const standaloneMode = !effectiveEntraAuthEnabled && !apiToken;
     const apiRateLimitWindowMs = parsePositiveIntegerEnv("API_RATE_LIMIT_WINDOW_MS", raw.API_RATE_LIMIT_WINDOW_MS, DEFAULT_API_RATE_LIMIT_WINDOW_MS);
     const apiRateLimitGeneralMax = parsePositiveIntegerEnv("API_RATE_LIMIT_GENERAL_MAX", raw.API_RATE_LIMIT_GENERAL_MAX, DEFAULT_API_RATE_LIMIT_GENERAL_MAX);
     const apiRateLimitAuthMax = parsePositiveIntegerEnv("API_RATE_LIMIT_AUTH_MAX", raw.API_RATE_LIMIT_AUTH_MAX, DEFAULT_API_RATE_LIMIT_AUTH_MAX);
@@ -238,10 +298,10 @@ export function parseRuntimeConfig(env, options = {}) {
     const memoryInboxRetentionDays = parsePositiveIntegerEnv("CHAPTERHOUSE_MEMORY_INBOX_RETENTION_DAYS", raw.CHAPTERHOUSE_MEMORY_INBOX_RETENTION_DAYS, 7);
     const memoryHotRecallBoost = parsePositiveNumberEnv("CHAPTERHOUSE_MEMORY_HOT_RECALL_BOOST", raw.CHAPTERHOUSE_MEMORY_HOT_RECALL_BOOST, 1.5);
     const memoryHotAgeDays = parsePositiveIntegerEnv("CHAPTERHOUSE_MEMORY_HOT_AGE_DAYS", raw.CHAPTERHOUSE_MEMORY_HOT_AGE_DAYS, 30);
-    if (entraAuthEnabled && (!entraTenantId || !entraClientId)) {
+    if (effectiveEntraAuthEnabled && (!effectiveEntraTenantId || !effectiveEntraClientId)) {
         throw new Error("ENTRA_AUTH_ENABLED=true requires ENTRA_TENANT_ID and ENTRA_CLIENT_ID");
     }
-    if (teamsNotificationsEnabled && !teamsWebhookUrl) {
+    if (effectiveTeamsNotificationsEnabled && !effectiveTeamsWebhookUrl) {
         throw new Error("TEAMS_NOTIFICATIONS_ENABLED=true requires TEAMS_WEBHOOK_URL");
     }
     return {
@@ -256,11 +316,11 @@ export function parseRuntimeConfig(env, options = {}) {
         adoProject: raw.ADO_PROJECT?.trim() || DEFAULT_ADO_PROJECT,
         adoPat: raw.ADO_PAT?.trim() || "",
         workerTimeoutMs: parsedWorkerTimeout,
-        entraTenantId,
-        entraClientId,
-        entraRequiredRole,
-        entraTeamLeadId,
-        entraAuthEnabled,
+        entraTenantId: effectiveEntraTenantId,
+        entraClientId: effectiveEntraClientId,
+        entraRequiredRole: effectiveEntraRequiredRole,
+        entraTeamLeadId: effectiveEntraTeamLeadId,
+        entraAuthEnabled: effectiveEntraAuthEnabled,
         standaloneMode,
         corsAllowedOrigins: parseCorsAllowedOrigins(raw.CORS_ALLOWED_ORIGINS),
         copilotModel: raw.COPILOT_MODEL || DEFAULT_MODEL,
@@ -271,8 +331,8 @@ export function parseRuntimeConfig(env, options = {}) {
         teamWikiCacheTtlMinutes: parsedTeamWikiCacheTtlMinutes,
         teamWikiPaths: parseTeamWikiPaths(raw.TEAM_WIKI_PATHS),
         wikiEntityCategories: parseEntityCategories(raw.WIKI_ENTITY_CATEGORIES),
-        teamsWebhookUrl,
-        teamsNotificationsEnabled,
+        teamsWebhookUrl: effectiveTeamsWebhookUrl,
+        teamsNotificationsEnabled: effectiveTeamsNotificationsEnabled,
         apiRateLimitWindowMs,
         apiRateLimitGeneralMax,
         apiRateLimitAuthMax,
@@ -295,6 +355,7 @@ export function parseRuntimeConfig(env, options = {}) {
         memoryTieringEnabled: parseZeroOneEnv("CHAPTERHOUSE_MEMORY_TIERING_ENABLED", raw.CHAPTERHOUSE_MEMORY_TIERING_ENABLED, true),
         memoryHotRecallBoost,
         memoryHotAgeDays,
+        modeCompatibilityWarnings,
     };
 }
 const runtimeConfig = parseRuntimeConfig(process.env);
@@ -352,6 +413,7 @@ export const config = {
     memoryTieringEnabled: runtimeConfig.memoryTieringEnabled,
     memoryHotRecallBoost: runtimeConfig.memoryHotRecallBoost,
     memoryHotAgeDays: runtimeConfig.memoryHotAgeDays,
+    modeCompatibilityWarnings: runtimeConfig.modeCompatibilityWarnings,
     copilotAuthToken: runtimeConfig.copilotAuthToken,
     get copilotModel() {
         return _copilotModel;

package/dist/config.test.js

@@ -14,6 +14,7 @@ test("parses Teams webhook settings", async () => {
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "team",
         TEAMS_WEBHOOK_URL: "https://teams.example.test/webhook",
         TEAMS_NOTIFICATIONS_ENABLED: "true",
     });
@@ -24,6 +25,7 @@ test("rejects Teams notifications without a webhook", async () => {
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     assert.throws(() => configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "team",
         TEAMS_NOTIFICATIONS_ENABLED: "true",
     }), /TEAMS_NOTIFICATIONS_ENABLED=true requires TEAMS_WEBHOOK_URL/);
 });
@@ -60,6 +62,7 @@ test("requires Entra tenant and client when auth is enabled", async () => {
     const configModule = await import("./config.js");
     assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
     assert.throws(() => configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "team",
         ENTRA_AUTH_ENABLED: "true",
         ENTRA_TENANT_ID: "tenant-id",
     }), /ENTRA_AUTH_ENABLED=true requires ENTRA_TENANT_ID and ENTRA_CLIENT_ID/);
@@ -268,4 +271,74 @@ test("rejects invalid SSE replay settings", async () => {
         CHAPTERHOUSE_SSE_BUFFER_CAPACITY: "0",
     }), /CHAPTERHOUSE_SSE_BUFFER_CAPACITY must be a positive integer/);
 });
+test("personal mode starts cleanly without Entra env vars", async () => {
+    // Security: personal mode should boot in its intended unauthenticated configuration instead of requiring enterprise auth by accident.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+    });
+    assert.equal(parsed.chapterhouseMode, "personal");
+    assert.equal(parsed.entraAuthEnabled, false);
+    assert.doesNotMatch(parsed.modeCompatibilityWarnings.join("\n"), /Entra/i);
+});
+test("personal mode rejects explicit Entra auth enablement with a clear fix suggestion", async () => {
+    // Security: personal deployments must fail fast instead of starting in a broken auth state that looks protected but is not.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    assert.throws(() => configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+        ENTRA_AUTH_ENABLED: "true",
+        ENTRA_TENANT_ID: "tenant-id",
+        ENTRA_CLIENT_ID: "client-id",
+    }), /Personal mode cannot be used with ENTRA_AUTH_ENABLED=true[\s\S]*CHAPTERHOUSE_MODE=team[\s\S]*unset ENTRA_AUTH_ENABLED/);
+});
+test("team mode accepts Entra auth when required settings are present", async () => {
+    // Security: team mode is the only safe place for Entra auth, so valid enterprise settings must remain supported there.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "team",
+        ENTRA_AUTH_ENABLED: "true",
+        ENTRA_TENANT_ID: "tenant-id",
+        ENTRA_CLIENT_ID: "client-id",
+    });
+    assert.equal(parsed.chapterhouseMode, "team");
+    assert.equal(parsed.entraAuthEnabled, true);
+    assert.equal(parsed.entraTenantId, "tenant-id");
+    assert.equal(parsed.entraClientId, "client-id");
+});
+test("personal mode still warns about leftover Entra settings when auth is not explicitly enabled", async () => {
+    // Security: leftover enterprise env vars should be called out so personal-mode operators know those settings are being ignored.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+        ENTRA_TENANT_ID: "tenant-only",
+    });
+    assert.equal(parsed.chapterhouseMode, "personal");
+    assert.equal(parsed.entraAuthEnabled, false);
+    assert.match(parsed.modeCompatibilityWarnings.join("\n"), /Entra/i);
+});
+test("personal mode warns and disables incomplete Teams notification settings instead of throwing", async () => {
+    // Security: personal mode should ignore team-only integrations without partially enabling cross-tenant notification flows.
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+        TEAMS_NOTIFICATIONS_ENABLED: "true",
+    });
+    assert.equal(parsed.teamsNotificationsEnabled, false);
+    assert.match(parsed.modeCompatibilityWarnings.join("\n"), /Teams/i);
+});
+test("personal mode warns when Azure DevOps settings are only partially configured", async () => {
+    const configModule = await import("./config.js");
+    assert.equal(typeof configModule.parseRuntimeConfig, "function", "parseRuntimeConfig should be exported");
+    const parsed = configModule.parseRuntimeConfig({
+        CHAPTERHOUSE_MODE: "personal",
+        ADO_PAT: "test-pat",
+    });
+    assert.equal(parsed.adoPat, "test-pat");
+    assert.match(parsed.modeCompatibilityWarnings.join("\n"), /Azure DevOps/i);
+});
 //# sourceMappingURL=config.test.js.map

package/dist/copilot/memory-coordinator.js

@@ -0,0 +1,234 @@
+import { getActiveScope } from "../memory/active-scope.js";
+import { CheckpointTracker, isCheckpointInFlight, runCheckpointExtraction } from "../memory/checkpoint.js";
+import { runEndOfTaskMemoryHook } from "../memory/eot.js";
+import { getHotTierEntries, renderHotTierForActiveScope, renderHotTierXML } from "../memory/hot-tier.js";
+import { isHousekeepingInFlight, runHousekeeping } from "../memory/housekeeping.js";
+import { getScope } from "../memory/scopes.js";
+import { config as defaultConfig } from "../config.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("memory-coordinator");
+const MAX_CHECKPOINT_CHARS_PER_SIDE = 4_000;
+export class MemoryCoordinator {
+    checkpointTrackers = new Map();
+    checkpointTurnsBySession = new Map();
+    housekeepingTurnsBySession = new Map();
+    completedTaskIds = new Set();
+    getCopilotClient;
+    resolveScopeForSession;
+    config;
+    constructor(options) {
+        this.getCopilotClient = options.getCopilotClient;
+        this.resolveScopeForSession = options.resolveScopeForSession ?? (() => getActiveScope());
+        this.config = options.config ?? defaultConfig;
+    }
+    async onTurnComplete(sessionKey, prompt, response, source) {
+        const sourceType = this.normalizeSource(source);
+        if (sourceType === "background") {
+            return;
+        }
+        this.scheduleCheckpointExtraction(sessionKey, prompt, response);
+        this.scheduleHousekeeping(sessionKey);
+    }
+    async onScopeChange(sessionKey, prev, next) {
+        if (!prev) {
+            return;
+        }
+        const previousScope = getScope(prev) ?? null;
+        if (!previousScope) {
+            return;
+        }
+        if (!this.config.memoryCheckpointOnScopeChange) {
+            log.info({ sessionKey, scope: previousScope.slug }, "memory.checkpoint.scope_change_disabled");
+            return;
+        }
+        const tracker = this.getCheckpointTracker(sessionKey);
+        const turnsSinceLast = tracker.turnsSinceLastFire();
+        if (turnsSinceLast < this.config.memoryCheckpointMinTurnsForScopeFire) {
+            log.info({
+                sessionKey,
+                scope: previousScope.slug,
+                turns_since_last: turnsSinceLast,
+                min_required: this.config.memoryCheckpointMinTurnsForScopeFire,
+            }, "memory.checkpoint.scope_change_skip");
+            return;
+        }
+        if (isCheckpointInFlight(sessionKey)) {
+            log.info({ sessionKey, trigger: "scope_change" }, "memory.checkpoint.in_flight_skip");
+            return;
+        }
+        const copilotClient = this.getCopilotClient();
+        if (!copilotClient) {
+            log.error({ sessionKey }, "memory.checkpoint.error");
+            return;
+        }
+        const turns = this.checkpointTurnsBySession.get(sessionKey) ?? [];
+        if (turns.length === 0) {
+            log.info({
+                sessionKey,
+                scope: previousScope.slug,
+                turns_since_last: turnsSinceLast,
+                min_required: this.config.memoryCheckpointMinTurnsForScopeFire,
+            }, "memory.checkpoint.scope_change_skip");
+            return;
+        }
+        tracker.markScopeChangeFire();
+        const nextScope = next ? (getScope(next) ?? null) : null;
+        void runCheckpointExtraction({
+            sessionKey,
+            turns: turns.slice(-this.config.memoryCheckpointTurns),
+            activeScope: previousScope,
+            copilotClient,
+            trigger: "scope_change",
+            scopeChangeContext: {
+                from: previousScope.slug,
+                to: nextScope?.slug ?? "no active scope",
+            },
+        }).catch((error) => {
+            log.error({ err: error, sessionKey }, "memory.checkpoint.error");
+        });
+    }
+    async buildHotTierContext(sessionKey) {
+        if (!this.config.memoryInjectEnabled) {
+            return "";
+        }
+        const scope = this.resolveScopeForSession(sessionKey);
+        if (!scope) {
+            return "";
+        }
+        const activeScope = getActiveScope();
+        const hotTierXml = activeScope?.id === scope.id
+            ? renderHotTierForActiveScope()
+            : renderHotTierXML(getHotTierEntries(scope.id));
+        return hotTierXml ? hotTierXml.trimEnd() : "";
+    }
+    buildPerTurnHooks(sessionKey) {
+        if (!this.config.memoryInjectEnabled) {
+            return undefined;
+        }
+        const hooks = {
+            onUserPromptSubmitted: async () => {
+                const hotTierXml = await this.buildHotTierContext(sessionKey);
+                return hotTierXml ? { additionalContext: hotTierXml } : undefined;
+            },
+        };
+        return hooks;
+    }
+    async onAgentTaskComplete(taskId, result) {
+        if (this.completedTaskIds.has(taskId)) {
+            log.info({ taskId }, "memory.eot.duplicate_skip");
+            return;
+        }
+        this.completedTaskIds.add(taskId);
+        const copilotClient = this.getCopilotClient();
+        if (!copilotClient) {
+            return;
+        }
+        const finalResult = typeof result === "string" ? result : result == null ? "" : String(result);
+        await runEndOfTaskMemoryHook({
+            taskId,
+            finalResult,
+            copilotClient,
+        });
+    }
+    reset(sessionKey) {
+        this.getCheckpointTracker(sessionKey).reset();
+        this.checkpointTurnsBySession.delete(sessionKey);
+        this.housekeepingTurnsBySession.delete(sessionKey);
+        this.completedTaskIds.clear();
+    }
+    shutdown() {
+        this.checkpointTrackers.clear();
+        this.checkpointTurnsBySession.clear();
+        this.housekeepingTurnsBySession.clear();
+        this.completedTaskIds.clear();
+    }
+    normalizeSource(source) {
+        return source === "background" ? "background" : source === "sse-web" ? "sse-web" : "web";
+    }
+    truncateCheckpointText(value) {
+        const trimmed = value.trim();
+        if (trimmed.length <= MAX_CHECKPOINT_CHARS_PER_SIDE) {
+            return trimmed;
+        }
+        return `${trimmed.slice(0, MAX_CHECKPOINT_CHARS_PER_SIDE)}…`;
+    }
+    getCheckpointTracker(sessionKey) {
+        let tracker = this.checkpointTrackers.get(sessionKey);
+        if (!tracker) {
+            tracker = new CheckpointTracker();
+            this.checkpointTrackers.set(sessionKey, tracker);
+        }
+        return tracker;
+    }
+    appendCheckpointTurn(sessionKey, turn) {
+        const turns = this.checkpointTurnsBySession.get(sessionKey) ?? [];
+        turns.push(turn);
+        const overflow = turns.length - this.config.memoryCheckpointTurns;
+        if (overflow > 0) {
+            turns.splice(0, overflow);
+        }
+        this.checkpointTurnsBySession.set(sessionKey, turns);
+        return turns;
+    }
+    scheduleCheckpointExtraction(sessionKey, prompt, response) {
+        const tracker = this.getCheckpointTracker(sessionKey);
+        const turns = this.appendCheckpointTurn(sessionKey, {
+            user: this.truncateCheckpointText(prompt),
+            assistant: this.truncateCheckpointText(response),
+        });
+        if (!this.config.memoryCheckpointEnabled) {
+            log.info({ sessionKey }, "memory.checkpoint.disabled");
+            return;
+        }
+        tracker.tickOrchestratorTurn();
+        if (!tracker.shouldFire()) {
+            return;
+        }
+        tracker.markFired();
+        if (isCheckpointInFlight(sessionKey)) {
+            log.info({ sessionKey }, "memory.checkpoint.in_flight_skip");
+            return;
+        }
+        const copilotClient = this.getCopilotClient();
+        if (!copilotClient) {
+            log.error({ sessionKey }, "memory.checkpoint.error");
+            return;
+        }
+        const activeScope = this.resolveScopeForSession(sessionKey);
+        void runCheckpointExtraction({
+            sessionKey,
+            turns: turns.slice(-this.config.memoryCheckpointTurns),
+            activeScope,
+            copilotClient,
+            trigger: "cadence",
+        }).catch((error) => {
+            log.error({ err: error, sessionKey }, "memory.checkpoint.error");
+        });
+    }
+    scheduleHousekeeping(sessionKey) {
+        if (!this.config.memoryHousekeepingEnabled) {
+            log.info({ sessionKey }, "memory.housekeeping.disabled");
+            return;
+        }
+        const turns = (this.housekeepingTurnsBySession.get(sessionKey) ?? 0) + 1;
+        if (turns < this.config.memoryHousekeepingTurns) {
+            this.housekeepingTurnsBySession.set(sessionKey, turns);
+            return;
+        }
+        this.housekeepingTurnsBySession.set(sessionKey, 0);
+        const activeScope = this.resolveScopeForSession(sessionKey);
+        if (!activeScope) {
+            log.info({ sessionKey }, "memory.housekeeping.no_active_scope");
+            return;
+        }
+        const scopeIds = [activeScope.id];
+        if (isHousekeepingInFlight(scopeIds)) {
+            log.info({ sessionKey, scope_ids: scopeIds }, "memory.housekeeping.in_flight_skip");
+            return;
+        }
+        void runHousekeeping({ scopeIds }).catch((error) => {
+            log.error({ err: error, sessionKey, scope_ids: scopeIds }, "memory.housekeeping.error");
+        });
+    }
+}
+//# sourceMappingURL=memory-coordinator.js.map