@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/cmos-agent-onboard.js

@@ -0,0 +1,1533 @@
+"use strict";
+// ABOUTME: Aggregates CMOS project state into the cold-start onboarding payload.
+// ABOUTME: Also surfaces sender-attribution ambiguity so agents can verify whoami early.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmosAgentOnboardToolDefinition = exports.cmosAgentOnboardSchema = void 0;
+exports.cmosAgentOnboard = cmosAgentOnboard;
+exports.getProjectType = getProjectType;
+exports.formatAgentOnboardForLLM = formatAgentOnboardForLLM;
+/**
+ * cmos_agent_onboard Tool
+ *
+ * MCP tool for agent onboarding/context initialization.
+ * Returns an aggregated payload optimized for agent context windows (<4KB).
+ * Combines data from contexts, missions, sessions, and decisions.
+ *
+ * @module tools/cmos/cmos-agent-onboard
+ */
+const zod_1 = require("zod");
+const path_1 = __importDefault(require("path"));
+const client_1 = require("./client");
+const client_2 = require("./client");
+const errors_1 = require("./errors");
+const agent_feedback_1 = require("./agent-feedback");
+const dashboard_client_1 = require("./dashboard-client");
+const context_freshness_1 = require("./context-freshness");
+const project_identity_1 = require("./project-identity");
+const project_registry_1 = require("../../intelligence/project-registry");
+const sender_context_1 = require("../../intelligence/sender-context");
+const owner_resolution_1 = require("./owner-resolution");
+const context_retention_1 = require("./context-retention");
+const staleness_detection_1 = require("./staleness-detection");
+const orphan_detection_1 = require("./orphan-detection");
+const server_health_1 = require("../../server-health");
+const auth_state_1 = require("../../auth/auth-state");
+const cmos_constraints_1 = require("./cmos-constraints");
+const tier_config_1 = require("./tier-config");
+/**
+ * Input parameters schema for cmos_agent_onboard tool.
+ */
+exports.cmosAgentOnboardSchema = zod_1.z.object({
+    /** Optional free-text UX feedback from the agent (Sprint 56 m03). */
+    agentFeedback: zod_1.z
+        .string()
+        .max(2000)
+        .optional()
+        .describe('Optional free-text UX feedback. Use this to report rough edges, improvement ideas, or surprising tool behavior you hit during the prior session. Reviewed periodically via cmos_feedback(action="list").'),
+    /** Optional: explicit project root to search from */
+    projectRoot: zod_1.z
+        .string()
+        .optional()
+        .describe('Project root directory to search for CMOS database (defaults to cwd)'),
+});
+/**
+ * MCP Tool Definition for cmos_agent_onboard.
+ */
+exports.cmosAgentOnboardToolDefinition = {
+    name: 'cmos_agent_onboard',
+    description: 'Get aggregated onboarding payload for agent cold-start. Returns project identity, active session, pending missions, recent decisions, and suggested actions. Optimized for context windows (<4KB).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentFeedback: {
+                type: 'string',
+                maxLength: 2000,
+                description: 'Optional free-text UX feedback. Use this to report rough edges, improvement ideas, or surprising tool behavior you hit during the prior session. Reviewed periodically via cmos_feedback(action="list").',
+            },
+            projectRoot: {
+                type: 'string',
+                description: 'Project root directory to search for CMOS database (defaults to cwd)',
+            },
+        },
+        additionalProperties: false,
+    },
+};
+/**
+ * Execute the cmos_agent_onboard tool.
+ *
+ * Aggregates data from multiple sources into a single optimized payload
+ * for agent context initialization.
+ *
+ * @param params - Tool parameters
+ * @returns CmosToolResult with onboarding data
+ */
+async function cmosAgentOnboard(params = {}) {
+    return (0, client_1.withClientAsync)(async (client) => {
+        const warnings = [];
+        // Sprint 52 m01: seed metadata.owner from dashboard identity if absent, then
+        // rewrite any legacy `cmos://unknown/*` address before project_identity is read.
+        // Best-effort — failure is silent; the identity row keeps an empty cmos_address
+        // until a later checkpoint resolves the owner.
+        try {
+            await (0, owner_resolution_1.resolveAndPersistOwner)(client);
+            (0, project_identity_1.backfillUnknownCmosAddress)(client);
+        }
+        catch {
+            // never block onboard on identity resolution
+        }
+        // Get project identity from master_context + metadata
+        const project = getProjectIdentity(client);
+        // Load tier config from cmos/tiers/{projectType}.md
+        const tierConfig = (0, tier_config_1.loadTierConfig)(project.projectType, params.projectRoot);
+        const hiddenFields = new Set(tierConfig?.onboardFieldsHide ?? []);
+        // Conditionally fetch sprint/mission data based on tier
+        const currentSprint = hiddenFields.has('currentSprint') ? null : getCurrentSprint(client);
+        // Get active session
+        const activeSession = getActiveSession(client);
+        // Get pending missions (suppressed for tiers that hide them)
+        const pendingMissions = hiddenFields.has('pendingMissions')
+            ? []
+            : getPendingMissions(client, currentSprint?.id ?? null);
+        // Get blocked missions (suppressed for tiers that hide them)
+        const blockedMissions = hiddenFields.has('blockedMissions') ? [] : getBlockedMissions(client);
+        // Get recent decisions
+        const recentDecisions = getRecentDecisions(client);
+        // Get next steps from project_context
+        const nextSteps = getNextSteps(client);
+        // Get session statistics
+        const sessionStats = getSessionStats(client);
+        // Get context size telemetry
+        const contextSizes = getContextSizes(client);
+        const masterSizeWarning = contextSizes.masterContext
+            ? (0, context_retention_1.buildContextSizeWarning)('master_context', contextSizes.masterContext)
+            : null;
+        const projectSizeWarning = contextSizes.projectContext
+            ? (0, context_retention_1.buildContextSizeWarning)('project_context', contextSizes.projectContext)
+            : null;
+        if (masterSizeWarning) {
+            warnings.push(masterSizeWarning);
+        }
+        if (projectSizeWarning) {
+            warnings.push(projectSizeWarning);
+        }
+        // Calculate context freshness
+        const freshnessResult = (0, context_freshness_1.calculateContextFreshness)(client, {
+            contextId: 'master_context',
+        });
+        warnings.push(...freshnessResult.warnings);
+        const staleWarning = (0, context_freshness_1.buildContextStalenessWarning)(freshnessResult.freshness);
+        if (staleWarning) {
+            warnings.push(staleWarning);
+        }
+        // Detect and flag stale decisions/learnings
+        const stalenessResult = (0, staleness_detection_1.detectAndFlagStaleness)(client);
+        if (stalenessResult.totalStaleDecisions > 0 || stalenessResult.totalStaleLearnings > 0) {
+            warnings.push(`${stalenessResult.totalStaleDecisions} stale decision(s) and ${stalenessResult.totalStaleLearnings} stale learning(s) detected (threshold: ${stalenessResult.threshold} sprints). ` +
+                `Run cmos_decisions(action="review") for per-decision triage with suggested actions.`);
+        }
+        // Detect orphaned entities (sprints with no missions, missions with no sprint, stale sessions)
+        const orphans = (0, orphan_detection_1.detectOrphans)(client);
+        const orphanWarnings = (0, orphan_detection_1.buildOrphanWarnings)(orphans);
+        warnings.push(...orphanWarnings);
+        // Layer 0: Full project identity from the project_identity contexts row
+        const fullProjectIdentity = getFullProjectIdentity(client);
+        // Layer 2: Tier-aware last session memory
+        const tier = project.projectType;
+        const lastSession = getLastSession(client, tier);
+        // Detect fresh project: zero active missions AND no PROJECT BRIEF in master_context
+        const freshProject = detectFreshProject(client);
+        const tierSelectionPrompt = freshProject
+            ? buildTierSelectionPrompt(project.projectType)
+            : undefined;
+        // Managed Sprint Zero trigger: fresh project + managed tier
+        const sprintZeroReady = freshProject && project.projectType === 'managed' ? true : undefined;
+        const sprintZeroContext = sprintZeroReady ? buildSprintZeroContext() : undefined;
+        // General tier first-session prompt: fresh project + general tier
+        const firstSessionPrompt = freshProject && project.projectType === 'general' ? buildFirstSessionPrompt() : undefined;
+        // Fetch messaging context and sync health (non-blocking — gracefully degrades)
+        // Skip syncHealth fetch if tier config hides it (avoids unnecessary network calls)
+        const [messaging, syncHealth] = await Promise.all([
+            fetchMessagingContext(warnings),
+            hiddenFields.has('syncHealth') ? Promise.resolve(null) : fetchSyncHealth(client, warnings),
+        ]);
+        // Get server health (build staleness detection)
+        const serverHealth = (0, server_health_1.getServerHealth)();
+        if (!serverHealth.codeIsCurrent && serverHealth.stalenessMessage) {
+            warnings.push(serverHealth.stalenessMessage);
+        }
+        // Detect stale next-steps (pending from >1 sprint ago)
+        const staleNextStepsCount = getStaleNextStepsCount(client, currentSprint?.id ?? null);
+        // Detect stale/expired constraints
+        const staleConstraintCount = getStaleConstraintCountForOnboard(client);
+        const senderAttributionAmbiguity = await detectSenderAttributionAmbiguity(params, params.projectRoot ?? process.cwd());
+        // Sprint 57 m04: pull authState so the agent sees it on first turn.
+        // Best-effort — never block onboard on credential-store I/O hiccups.
+        let authState;
+        try {
+            const authProjectRoot = params.projectRoot ?? undefined;
+            authState = await (0, auth_state_1.computeAuthState)(authProjectRoot ? { projectRoot: authProjectRoot } : {});
+        }
+        catch {
+            authState = undefined;
+        }
+        // Generate suggested actions based on current state (filtered by tier)
+        const suggestedActions = generateSuggestedActions({
+            activeSession,
+            pendingMissions,
+            blockedMissions,
+            currentSprint,
+            contextFreshness: freshnessResult.freshness,
+            messaging,
+            syncHealth,
+            orphans,
+            serverHealth,
+            staleCounts: {
+                decisions: stalenessResult.totalStaleDecisions,
+                learnings: stalenessResult.totalStaleLearnings,
+            },
+            staleNextStepsCount,
+            staleConstraintCount,
+            contextSizes,
+            senderAttributionAmbiguity,
+            toolsSkip: tierConfig?.toolsSkip ?? [],
+            freshProject,
+            authState,
+            projectRootSupplied: !!params.projectRoot,
+        });
+        const result = {
+            project,
+            currentSprint,
+            activeSession,
+            pendingMissions,
+            blockedMissions,
+            recentDecisions,
+            nextSteps,
+            suggestedActions,
+            sessionStats,
+            contextSizes,
+            contextFreshness: freshnessResult.freshness,
+            staleness: {
+                staleDecisions: stalenessResult.totalStaleDecisions,
+                staleLearnings: stalenessResult.totalStaleLearnings,
+                threshold: stalenessResult.threshold,
+            },
+            messaging,
+            syncHealth,
+            orphans,
+            serverHealth,
+            tierConfig,
+            freshProject,
+            ...(authState ? { authState } : {}),
+        };
+        if (tierSelectionPrompt !== undefined) {
+            result.tierSelectionPrompt = tierSelectionPrompt;
+        }
+        if (sprintZeroReady !== undefined) {
+            result.sprintZeroReady = sprintZeroReady;
+        }
+        if (sprintZeroContext !== undefined) {
+            result.sprintZeroContext = sprintZeroContext;
+        }
+        if (firstSessionPrompt !== undefined) {
+            result.firstSessionPrompt = firstSessionPrompt;
+        }
+        // Context v2 Sprint 50: Layer 0 + Layer 2
+        result.projectIdentity = fullProjectIdentity;
+        result.lastSession = lastSession;
+        // Sprint 56 m03: persist optional agent UX feedback if supplied.
+        const feedbackSanitized = [];
+        if (params.agentFeedback && params.agentFeedback.trim().length > 0) {
+            const fb = (0, agent_feedback_1.recordAgentFeedback)(client, params.agentFeedback, {
+                toolName: 'cmos_agent_onboard',
+                sessionId: activeSession?.id ?? null,
+                sprintId: currentSprint?.id ?? null,
+            });
+            if (fb.feedbackId !== null) {
+                result.feedbackId = fb.feedbackId;
+            }
+            feedbackSanitized.push(...fb.sanitizedFields);
+        }
+        return (0, errors_1.createSuccess)(result, warnings, feedbackSanitized);
+    }, { projectRoot: params.projectRoot });
+}
+/**
+ * Read project_type from metadata table. Defaults to 'build' for backward compatibility.
+ */
+function getProjectType(client) {
+    const result = client.getOne('SELECT value FROM metadata WHERE key = ?', [
+        'project_type',
+    ]);
+    if (result.success && result.data?.value) {
+        const normalized = result.data.value.trim();
+        if (normalized.length > 0)
+            return normalized;
+    }
+    return 'build';
+}
+/**
+ * Extract project identity from master_context + metadata.
+ */
+function getProjectIdentity(client) {
+    const projectType = getProjectType(client);
+    const result = client.getOne('SELECT content FROM contexts WHERE id = ?', [
+        'master_context',
+    ]);
+    if (!result.success || !result.data) {
+        return { name: 'CMOS Project', description: null, status: null, projectType };
+    }
+    try {
+        const content = JSON.parse(result.data.content);
+        const projectIdentity = content.project_identity || content.project || {};
+        return {
+            name: projectIdentity.name || content.project?.name || 'CMOS Project',
+            description: projectIdentity.description || content.project?.description || null,
+            status: projectIdentity.status || content.project?.status || null,
+            projectType,
+        };
+    }
+    catch {
+        return { name: 'CMOS Project', description: null, status: null, projectType };
+    }
+}
+/**
+ * Get the full project identity from the project_identity contexts row (Layer 0).
+ * Auto-seeds the row if absent. Returns null on failure.
+ */
+function getFullProjectIdentity(client) {
+    try {
+        return (0, project_identity_1.getProjectIdentity)(client);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build tier-aware last session memory (Layer 2).
+ *
+ * Depth by tier:
+ * - general: {title, summary, openItems}
+ * - managed: {title, summary, decisions, nextSteps}
+ * - build:   {title, summary, decisions, nextSteps, openItems}
+ */
+function getLastSession(client, tier) {
+    const result = client.getOne(`SELECT id, title, type, summary, captures, completed_at
+     FROM sessions
+     WHERE status = 'completed'
+     ORDER BY completed_at DESC
+     LIMIT 1`, []);
+    if (!result.success || !result.data)
+        return null;
+    const session = result.data;
+    const base = {
+        id: session.id,
+        title: session.title,
+        summary: session.summary,
+        completedAt: session.completed_at,
+    };
+    // Parse captures for decisions and next-steps
+    let decisions = [];
+    let nextSteps = [];
+    if (session.captures) {
+        try {
+            const captures = JSON.parse(session.captures);
+            if (Array.isArray(captures)) {
+                decisions = captures
+                    .filter((c) => c.category === 'decision' && typeof c.content === 'string')
+                    .map((c) => c.content);
+                nextSteps = captures
+                    .filter((c) => c.category === 'next-step' && typeof c.content === 'string')
+                    .map((c) => c.content);
+            }
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    // Fetch open items from next_steps table (table may not exist on older DBs)
+    const nextStepsTableExists = client.getOne(`SELECT name FROM sqlite_master WHERE type='table' AND name='next_steps'`, []);
+    const openItems = [];
+    if (nextStepsTableExists.success && nextStepsTableExists.data) {
+        const openItemsResult = client.getMany(`SELECT content FROM next_steps WHERE status = 'pending' ORDER BY id DESC LIMIT 10`, []);
+        if (openItemsResult.success && openItemsResult.data) {
+            openItems.push(...openItemsResult.data.map((r) => r.content));
+        }
+    }
+    // Apply tier-aware depth
+    if (tier === 'general') {
+        return { ...base, openItems };
+    }
+    else if (tier === 'managed') {
+        return { ...base, decisions, nextSteps };
+    }
+    else {
+        // build (default) — all fields
+        return { ...base, decisions, nextSteps, openItems };
+    }
+}
+/**
+ * Get current sprint context using mission-aware detection.
+ *
+ * Strategy:
+ * 1. Sprint with In Progress or Current missions (active work)
+ * 2. Explicit In Progress/Current/Active sprint that still has open work or no missions yet
+ * 3. Most recently active sprint when status fields drift behind reality
+ * 4. Earliest non-completed sprint with Queued missions (next work)
+ * 5. Fall back to status-based ordering
+ */
+function getCurrentSprint(client) {
+    // Sprint 55 m03: Archived sprints must never surface as currentSprint, even
+    // if an Archived sprint has recent mission/session activity. Each step below
+    // filters Archived explicitly (Step 2 is already scoped to open statuses).
+    // Step 1: Find sprint with active work (In Progress or Current missions) on
+    // a non-Archived sprint.
+    const activeWorkResult = client.getOne(`SELECT m.sprint_id FROM missions m
+       JOIN sprints s ON s.id = m.sprint_id
+      WHERE m.status IN ('In Progress', 'Current')
+        AND m.sprint_id IS NOT NULL
+        AND COALESCE(s.status, 'Planned') != 'Archived'
+      LIMIT 1`, []);
+    if (activeWorkResult.success && activeWorkResult.data?.sprint_id) {
+        return getSprintContextById(client, activeWorkResult.data.sprint_id);
+    }
+    // Step 2: Prefer an explicitly active sprint unless it already looks fully completed.
+    const explicitOpenSprintId = getExplicitOpenSprintId(client);
+    if (explicitOpenSprintId) {
+        return getSprintContextById(client, explicitOpenSprintId);
+    }
+    // Step 3: Most recently active sprint with mission/session activity, even if the
+    // sprint status was never advanced beyond Planned.
+    const recentActivitySprintId = getMostRecentlyActiveSprintId(client);
+    if (recentActivitySprintId) {
+        return getSprintContextById(client, recentActivitySprintId);
+    }
+    // Step 4: Earliest non-completed, non-archived sprint with Queued missions
+    const queuedWorkResult = client.getOne(`SELECT m.sprint_id FROM missions m
+     JOIN sprints s ON m.sprint_id = s.id
+     WHERE m.status = 'Queued' AND m.sprint_id IS NOT NULL
+       AND COALESCE(s.status, 'Planned') NOT IN ('Completed', 'Archived')
+     ORDER BY CASE COALESCE(s.status, 'Planned')
+        WHEN 'In Progress' THEN 0
+        WHEN 'Current' THEN 1
+        WHEN 'Active' THEN 2
+        WHEN 'Planned' THEN 3
+        ELSE 4
+      END, COALESCE(s.start_date, '9999-12-31') ASC, s.rowid ASC
+     LIMIT 1`, []);
+    if (queuedWorkResult.success && queuedWorkResult.data?.sprint_id) {
+        return getSprintContextById(client, queuedWorkResult.data.sprint_id);
+    }
+    // Step 5: Fall back to status-based ordering, with Archived sprints excluded
+    // entirely. When no Active/In Progress/Planned sprint exists, prefer the
+    // latest Completed sprint over silently returning an Archived record.
+    const result = client.getOne(`SELECT id, title, status, focus
+       FROM sprints
+      WHERE COALESCE(status, 'Planned') != 'Archived'
+      ORDER BY CASE status
+        WHEN 'In Progress' THEN 0
+        WHEN 'Current' THEN 1
+        WHEN 'Active' THEN 2
+        WHEN 'Planned' THEN 3
+        WHEN 'Completed' THEN 4
+        ELSE 5
+      END, COALESCE(end_date, start_date, '') DESC, rowid DESC
+      LIMIT 1`, []);
+    if (!result.success || !result.data) {
+        return null;
+    }
+    return {
+        id: result.data.id,
+        title: result.data.title,
+        status: result.data.status,
+        focus: result.data.focus,
+    };
+}
+function getExplicitOpenSprintId(client) {
+    const result = client.getOne(`SELECT s.id
+       FROM sprints s
+      WHERE COALESCE(s.status, 'Planned') IN ('In Progress', 'Current', 'Active')
+        AND (
+          NOT EXISTS (
+            SELECT 1
+              FROM missions m
+             WHERE m.sprint_id = s.id
+          )
+          OR EXISTS (
+            SELECT 1
+              FROM missions m
+             WHERE m.sprint_id = s.id
+               AND COALESCE(m.status, '') != 'Completed'
+          )
+        )
+      ORDER BY CASE COALESCE(s.status, 'Planned')
+        WHEN 'In Progress' THEN 0
+        WHEN 'Current' THEN 1
+        WHEN 'Active' THEN 2
+        ELSE 3
+      END, COALESCE(s.start_date, '') DESC, s.rowid DESC
+      LIMIT 1`, []);
+    return result.success ? (result.data?.id ?? null) : null;
+}
+function getMostRecentlyActiveSprintId(client) {
+    // Sprint 55 m03: Archived sprints had historically-recent mission/session
+    // timestamps on mature projects like OODS-Foundry-MCP (74 sprints, 458
+    // missions), so this step was returning the latest Archived sprint instead
+    // of falling through to the Completed sprint in Step 5. Exclude Archived
+    // alongside Completed so only genuinely-active parent sprints bubble up.
+    const result = client.getOne(`SELECT activity.sprint_id
+       FROM (
+         SELECT m.sprint_id, m.completed_at AS activity_at
+           FROM missions m
+           JOIN sprints s ON s.id = m.sprint_id
+          WHERE m.sprint_id IS NOT NULL
+            AND m.completed_at IS NOT NULL
+            AND COALESCE(s.status, 'Planned') NOT IN ('Completed', 'Archived')
+         UNION ALL
+         SELECT sess.sprint_id, COALESCE(sess.completed_at, sess.started_at) AS activity_at
+           FROM sessions sess
+           JOIN sprints s ON s.id = sess.sprint_id
+          WHERE sess.sprint_id IS NOT NULL
+            AND COALESCE(s.status, 'Planned') NOT IN ('Completed', 'Archived')
+       ) AS activity
+      WHERE activity.activity_at IS NOT NULL
+      GROUP BY activity.sprint_id
+      ORDER BY MAX(activity.activity_at) DESC, activity.sprint_id DESC
+      LIMIT 1`, []);
+    return result.success ? (result.data?.sprint_id ?? null) : null;
+}
+/**
+ * Get sprint context by ID.
+ */
+function getSprintContextById(client, sprintId) {
+    const result = client.getOne(`SELECT id, title, status, focus FROM sprints WHERE id = ?`, [sprintId]);
+    if (!result.success || !result.data) {
+        return null;
+    }
+    return {
+        id: result.data.id,
+        title: result.data.title,
+        status: result.data.status,
+        focus: result.data.focus,
+    };
+}
+/**
+ * Get active session if any.
+ */
+function getActiveSession(client) {
+    const result = client.getOne(`SELECT id, type, title, started_at, captures
+       FROM sessions
+      WHERE status = 'active'
+      ORDER BY started_at DESC
+      LIMIT 1`, []);
+    if (!result.success || !result.data) {
+        return null;
+    }
+    const session = result.data;
+    let captureCount = 0;
+    try {
+        const captures = JSON.parse(session.captures || '[]');
+        captureCount = Array.isArray(captures) ? captures.length : 0;
+    }
+    catch {
+        captureCount = 0;
+    }
+    return {
+        id: session.id,
+        type: session.type,
+        title: session.title,
+        startedAt: session.started_at,
+        captureCount,
+    };
+}
+/**
+ * Get pending missions (In Progress, Current, Queued).
+ * Queued missions are scoped to the active sprint when identified.
+ */
+function getPendingMissions(client, activeSprintId) {
+    // Show In Progress/Current from any sprint, but scope Queued to active sprint
+    const query = activeSprintId
+        ? `SELECT id, name, status, sprint_id
+         FROM missions
+        WHERE status IN ('In Progress', 'Current')
+           OR (status = 'Queued' AND sprint_id = ?)
+        ORDER BY CASE status
+          WHEN 'In Progress' THEN 0
+          WHEN 'Current' THEN 1
+          ELSE 2
+        END, rowid
+        LIMIT 5`
+        : `SELECT id, name, status, sprint_id
+         FROM missions
+        WHERE status IN ('In Progress', 'Current', 'Queued')
+        ORDER BY CASE status
+          WHEN 'In Progress' THEN 0
+          WHEN 'Current' THEN 1
+          ELSE 2
+        END, rowid
+        LIMIT 5`;
+    const params = activeSprintId ? [activeSprintId] : [];
+    const result = client.getMany(query, params);
+    if (!result.success || !result.data) {
+        return [];
+    }
+    return result.data.map((m) => ({
+        id: m.id,
+        name: m.name,
+        status: m.status,
+        sprintId: m.sprint_id,
+    }));
+}
+/**
+ * Get blocked missions.
+ */
+function getBlockedMissions(client) {
+    const result = client.getMany(`SELECT id, name, status, sprint_id
+       FROM missions
+      WHERE status = 'Blocked'
+      ORDER BY rowid
+      LIMIT 3`, []);
+    if (!result.success || !result.data) {
+        return [];
+    }
+    return result.data.map((m) => ({
+        id: m.id,
+        name: m.name,
+        status: m.status,
+        sprintId: m.sprint_id,
+    }));
+}
+/**
+ * Get recent strategic decisions.
+ */
+function getRecentDecisions(client) {
+    const result = client.getMany(`SELECT decision_text, project_domain, created_at
+       FROM strategic_decisions
+      ORDER BY created_at DESC
+      LIMIT 10`, []);
+    if (!result.success || !result.data) {
+        return [];
+    }
+    return result.data.map((d) => ({
+        decision: d.decision_text,
+        domain: d.project_domain,
+        createdAt: d.created_at,
+    }));
+}
+/**
+ * Count stale next-steps: pending next-steps from sprints older than the current one.
+ * Returns 0 if the next_steps table doesn't exist.
+ */
+function getStaleNextStepsCount(client, currentSprintId) {
+    // Check if next_steps table exists
+    const tableCheck = client.getOne(`SELECT name FROM sqlite_master WHERE type='table' AND name='next_steps'`);
+    if (!tableCheck.success || !tableCheck.data)
+        return 0;
+    if (!currentSprintId) {
+        // No active sprint — all pending next-steps are stale
+        const result = client.getOne(`SELECT COUNT(*) AS count FROM next_steps WHERE status = 'pending'`);
+        return result.success && result.data ? result.data.count : 0;
+    }
+    // Pending next-steps from sprints other than the current one
+    const result = client.getOne(`SELECT COUNT(*) AS count FROM next_steps
+     WHERE status = 'pending'
+       AND (sprint_id IS NOT NULL AND sprint_id != ?)`, [currentSprintId]);
+    return result.success && result.data ? result.data.count : 0;
+}
+/**
+ * Count stale/expired constraints using the constraints module.
+ */
+function getStaleConstraintCountForOnboard(client) {
+    return (0, cmos_constraints_1.getStaleConstraintCount)(client);
+}
+/**
+ * Get next steps from project_context.
+ */
+function getNextSteps(client) {
+    const result = client.getOne('SELECT content FROM contexts WHERE id = ?', [
+        'project_context',
+    ]);
+    if (!result.success || !result.data) {
+        return [];
+    }
+    try {
+        const content = JSON.parse(result.data.content);
+        const workingMemory = content.working_memory || {};
+        const nextSessionContext = content.next_session_context || {};
+        const candidateSteps = [
+            ...readOnboardSteps(workingMemory.next_steps),
+            ...readOnboardSteps(nextSessionContext.when_we_resume),
+            ...readOnboardSteps(content.next_steps),
+        ];
+        const completedMissionIds = loadCompletedMissionIds(client);
+        const completedSprintIds = loadCompletedSprintIds(client);
+        const sessionReferenceIndex = loadSessionReferenceIndex(client);
+        const nextSteps = [];
+        const seen = new Set();
+        for (const step of candidateSteps) {
+            if (referencesCompletedMission(step, completedMissionIds)) {
+                continue;
+            }
+            if (referencesCompletedSprint(step, completedSprintIds)) {
+                continue;
+            }
+            const sessionReference = extractValidSessionReference(step, sessionReferenceIndex.all);
+            if (sessionReference &&
+                sessionReferenceIndex.recent.size > 0 &&
+                !sessionReferenceIndex.recent.has(sessionReference)) {
+                continue;
+            }
+            const dedupeKey = stripSessionReference(step, sessionReferenceIndex.all).toLowerCase();
+            if (seen.has(dedupeKey)) {
+                continue;
+            }
+            seen.add(dedupeKey);
+            nextSteps.push(step);
+            if (nextSteps.length >= 5) {
+                break;
+            }
+        }
+        return nextSteps;
+    }
+    catch {
+        return [];
+    }
+}
+function readOnboardSteps(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function loadCompletedMissionIds(client) {
+    const result = client.getMany(`SELECT id
+       FROM missions
+      WHERE status = 'Completed'`, []);
+    return new Set(result.success && result.data ? result.data.map((row) => row.id) : []);
+}
+function loadCompletedSprintIds(client) {
+    const result = client.getMany(`SELECT id
+       FROM sprints
+      WHERE status = 'Completed'`, []);
+    return new Set(result.success && result.data ? result.data.map((row) => row.id) : []);
+}
+function loadSessionReferenceIndex(client) {
+    const result = client.getMany(`SELECT id
+       FROM sessions
+      ORDER BY COALESCE(completed_at, started_at) DESC, rowid DESC`, []);
+    if (!result.success || !result.data) {
+        return { all: new Set(), recent: new Set() };
+    }
+    const orderedIds = result.data.map((row) => row.id).filter(Boolean);
+    return {
+        all: new Set(orderedIds),
+        recent: new Set(orderedIds.slice(0, 2)),
+    };
+}
+function extractValidSessionReference(step, knownSessionIds) {
+    const separatorIndex = step.indexOf(':');
+    if (separatorIndex <= 0) {
+        return null;
+    }
+    const candidate = step.slice(0, separatorIndex).trim();
+    return knownSessionIds.has(candidate) ? candidate : null;
+}
+function stripSessionReference(step, knownSessionIds) {
+    const reference = extractValidSessionReference(step, knownSessionIds);
+    if (!reference) {
+        return step.trim();
+    }
+    return step.slice(step.indexOf(':') + 1).trim();
+}
+function referencesCompletedMission(step, completedMissionIds) {
+    const normalizedStep = step.toLowerCase();
+    for (const missionId of completedMissionIds) {
+        if (normalizedStep.includes(missionId.toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+function referencesCompletedSprint(step, completedSprintIds) {
+    const normalizedStep = step.toLowerCase();
+    for (const sprintId of completedSprintIds) {
+        const tokens = [sprintId.toLowerCase(), sprintId.toLowerCase().replace(/-/g, ' ')];
+        const numericMatch = sprintId.toLowerCase().match(/^sprint-(\d+)$/);
+        if (numericMatch) {
+            const normalizedNumber = String(Number.parseInt(numericMatch[1], 10));
+            tokens.push(`sprint ${normalizedNumber}`);
+            tokens.push(`sprint-${numericMatch[1]}`);
+        }
+        if (tokens.some((token) => normalizedStep.includes(token))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get session statistics.
+ */
+function getSessionStats(client) {
+    const result = client.getOne(`SELECT COUNT(*) AS total_sessions,
+            MAX(COALESCE(completed_at, started_at)) AS last_activity
+       FROM sessions`, []);
+    if (!result.success || !result.data) {
+        return { totalSessions: 0, lastActivity: null };
+    }
+    return {
+        totalSessions: result.data.total_sessions,
+        lastActivity: result.data.last_activity,
+    };
+}
+function getContextSizes(client) {
+    const contexts = client.getMany(`SELECT id, content
+       FROM contexts
+      WHERE id IN ('master_context', 'project_context')`, []);
+    if (!contexts.success || !contexts.data) {
+        return {
+            masterContext: null,
+            projectContext: null,
+            totalSizeKb: 0,
+            totalSizeBytes: 0,
+        };
+    }
+    let masterContext = null;
+    let projectContext = null;
+    for (const row of contexts.data) {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(row.content);
+        }
+        catch {
+            parsed = {};
+        }
+        const settings = (0, context_retention_1.resolveContextSizeSettings)(parsed);
+        const metrics = (0, context_retention_1.calculateContextSizeMetrics)(row.content, settings);
+        if (row.id === 'master_context') {
+            masterContext = metrics;
+        }
+        else if (row.id === 'project_context') {
+            projectContext = metrics;
+        }
+    }
+    return {
+        masterContext,
+        projectContext,
+        totalSizeKb: (masterContext?.sizeKb ?? 0) + (projectContext?.sizeKb ?? 0),
+        totalSizeBytes: (masterContext?.sizeBytes ?? 0) + (projectContext?.sizeBytes ?? 0),
+    };
+}
+/**
+ * Fetch messaging context from the dashboard.
+ * Non-blocking: if dashboard is unreachable or not configured,
+ * returns null and adds a warning.
+ */
+async function fetchMessagingContext(warnings) {
+    const clientResult = dashboard_client_1.DashboardClient.fromEnv();
+    if (!clientResult.success) {
+        // Dashboard not configured — this is normal, don't warn
+        return null;
+    }
+    try {
+        const client = clientResult.data;
+        const result = await client.listMessages({
+            tab: 'inbox',
+            status: 'pending',
+            limit: 5,
+        });
+        if (!result.success) {
+            warnings.push(`Dashboard messaging unavailable: ${result.error?.message ?? 'unknown error'}`);
+            return null;
+        }
+        return {
+            unreadCount: result.data.unreadCount,
+            recentMessages: result.data.messages.map((msg) => ({
+                id: msg.id,
+                type: msg.type,
+                summary: msg.summary,
+                from: msg.from ?? null,
+                status: msg.status,
+                createdAt: msg.createdAt,
+            })),
+        };
+    }
+    catch {
+        warnings.push('Dashboard messaging unavailable: unexpected error during fetch');
+        return null;
+    }
+}
+/** PG table → SQLite table name mapping for reconciliation (global fallback) */
+const PG_TO_SQLITE_TABLE = {
+    cmos_sprints: 'sprints',
+    cmos_missions: 'missions',
+    cmos_sessions: 'sessions',
+    cmos_decisions: 'strategic_decisions',
+    cmos_learnings: 'learnings',
+    cmos_mission_dependencies: 'mission_dependencies',
+};
+/** Project state entity field → SQLite table name mapping (project-scoped) */
+const PROJECT_STATE_TO_SQLITE = {
+    sprints: 'sprints',
+    missions: 'missions',
+    sessions: 'sessions',
+    decisions: 'strategic_decisions',
+    learnings: 'learnings',
+    dependencies: 'mission_dependencies',
+};
+/**
+ * Fetch sync health by comparing SQLite counts with PG mirror counts.
+ * Uses project-scoped endpoint for accurate per-project comparison.
+ * Falls back to global endpoint if project-scoped is unavailable.
+ * Non-blocking — returns null if dashboard is unreachable.
+ */
+async function fetchSyncHealth(db, warnings) {
+    const clientResult = dashboard_client_1.DashboardClient.fromEnv();
+    if (!clientResult.success) {
+        return null;
+    }
+    try {
+        const client = clientResult.data;
+        // Resolve project slug from metadata
+        const nameResult = db.getOne(`SELECT value FROM metadata WHERE key = 'project_name'`);
+        const projectName = nameResult.success && nameResult.data ? nameResult.data.value : null;
+        // Try project-scoped endpoint first
+        if (projectName) {
+            const slug = projectName.toLowerCase().replace(/\s+/g, '-');
+            const stateResult = await client.getSyncProjectState(slug);
+            if (stateResult.success && stateResult.data) {
+                return buildSyncHealthFromProjectState(db, stateResult.data, client);
+            }
+        }
+        // Fallback to global endpoint
+        return buildSyncHealthFromGlobalStatus(db, client, warnings);
+    }
+    catch {
+        warnings.push('Sync health unavailable: unexpected error during fetch');
+        return null;
+    }
+}
+/** Build sync health from project-scoped state (accurate per-project counts) */
+async function buildSyncHealthFromProjectState(db, projectState, client) {
+    const mismatches = [];
+    for (const [entityField, sqliteTable] of Object.entries(PROJECT_STATE_TO_SQLITE)) {
+        const pgEntities = projectState[entityField];
+        const pgCount = Array.isArray(pgEntities) ? pgEntities.length : 0;
+        const countResult = db.getOne(`SELECT COUNT(*) AS cnt FROM ${sqliteTable}`);
+        const sqliteCount = countResult.success && countResult.data ? countResult.data.cnt : 0;
+        if (sqliteCount !== pgCount) {
+            mismatches.push({
+                table: sqliteTable,
+                sqliteCount,
+                pgCount,
+                delta: sqliteCount - pgCount,
+            });
+        }
+    }
+    // Get sync log stats from global endpoint
+    let failedEntries = 0;
+    let lastSyncAt = null;
+    try {
+        const statusResult = await client.getSyncStatus();
+        if (statusResult.success && statusResult.data) {
+            failedEntries = statusResult.data.failedSyncLogEntries;
+            lastSyncAt = statusResult.data.lastSyncAt;
+        }
+    }
+    catch {
+        // Non-critical
+    }
+    return {
+        allMatch: mismatches.length === 0,
+        totalMismatches: mismatches.length,
+        mismatches,
+        failedEntries,
+        lastSyncAt,
+    };
+}
+/** Build sync health from global status endpoint (fallback) */
+async function buildSyncHealthFromGlobalStatus(db, client, warnings) {
+    const statusResult = await client.getSyncStatus();
+    if (!statusResult.success || !statusResult.data) {
+        warnings.push(`Sync health unavailable: ${statusResult.error?.message ?? 'unknown error'}`);
+        return null;
+    }
+    const pgStatus = statusResult.data;
+    const mismatches = [];
+    for (const pgTable of pgStatus.tables) {
+        const sqliteTable = PG_TO_SQLITE_TABLE[pgTable.table];
+        if (!sqliteTable)
+            continue;
+        const countResult = db.getOne(`SELECT COUNT(*) AS cnt FROM ${sqliteTable}`);
+        const sqliteCount = countResult.success && countResult.data ? countResult.data.cnt : 0;
+        if (sqliteCount !== pgTable.count) {
+            mismatches.push({
+                table: sqliteTable,
+                sqliteCount,
+                pgCount: pgTable.count,
+                delta: sqliteCount - pgTable.count,
+            });
+        }
+    }
+    return {
+        allMatch: mismatches.length === 0,
+        totalMismatches: mismatches.length,
+        mismatches,
+        failedEntries: pgStatus.failedSyncLogEntries,
+        lastSyncAt: pgStatus.lastSyncAt,
+    };
+}
+/**
+ * Detect whether this is a fresh project — one that has not accumulated any
+ * history yet.
+ *
+ * Sprint 55 m03: row counts across sprints, missions, and sessions are now the
+ * authoritative signal. Any persisted sprint / mission / session means the
+ * project is past the tabula-rasa state and must not be flagged fresh, even if
+ * every mission has since been completed and no "PROJECT BRIEF" marker was
+ * ever written to master_context. Previously this function only checked for
+ * active missions + the brief marker, which misreported mature projects
+ * (OODS-Foundry-MCP: 74 sprints / 458 missions / 127 sessions) as fresh and
+ * surfaced the new-project tierSelectionPrompt on every onboard.
+ *
+ * Falls back to the PROJECT BRIEF heuristic only when the database has zero
+ * rows in all three tables, so the first-session prompt still fires for
+ * genuinely-new projects that import context via master_context without ever
+ * persisting a sprint row.
+ */
+function detectFreshProject(client) {
+    const rowsResult = client.getOne(`SELECT
+       (SELECT COUNT(*) FROM sprints) AS sprint_count,
+       (SELECT COUNT(*) FROM missions) AS mission_count,
+       (SELECT COUNT(*) FROM sessions) AS session_count`, []);
+    if (rowsResult.success && rowsResult.data) {
+        const { sprint_count, mission_count, session_count } = rowsResult.data;
+        if (sprint_count > 0 || mission_count > 0 || session_count > 0) {
+            return false;
+        }
+    }
+    const contextResult = client.getOne('SELECT content FROM contexts WHERE id = ?', ['master_context']);
+    if (!contextResult.success || !contextResult.data)
+        return true; // No context → fresh
+    const content = contextResult.data.content.toLowerCase();
+    const hasBrief = content.includes('project brief') || content.includes('project_brief');
+    return !hasBrief;
+}
+/**
+ * Build a tier-appropriate first-session prompt for fresh projects.
+ * The agent uses this to kick off the opening conversation.
+ */
+function buildTierSelectionPrompt(tier) {
+    switch (tier) {
+        case 'general':
+            return ('New project detected. This is a fresh CMOS General workspace — a thinking partner ' +
+                'with memory. Start by introducing the project: what are you working on, and what ' +
+                'would be most useful to capture and remember across conversations?');
+        case 'managed':
+            return ('New project detected. This is a fresh CMOS Managed workspace. ' +
+                "Let's capture the project brief to get started: what's the goal, who are the " +
+                "stakeholders, and what's the target timeline?");
+        case 'build':
+        default:
+            return ('New project detected. This is a fresh CMOS Build workspace with no active missions. ' +
+                'Start with sprint planning to define the first sprint and its missions: ' +
+                'cmos_session(action="start", type="planning", title="Sprint 1 Planning").');
+    }
+}
+/**
+ * Build the Sprint Zero entry context for managed-tier fresh projects.
+ * Contains everything the agent needs to run the intake interview without
+ * reading the sprint-zero-managed.md snippet file.
+ */
+function buildSprintZeroContext() {
+    return {
+        description: 'Sprint Zero is a short intake interview that produces a populated project brief ' +
+            'and identifies the first milestone. It adapts to what the user arrives with and ' +
+            'may span more than one session.',
+        entryModes: [
+            {
+                situation: 'Has a client and a deadline',
+                entry: 'Stage 2 — stakeholders and context',
+                openingQuestion: "Great, let's get your project set up. Tell me about the client and what the deadline is.",
+            },
+            {
+                situation: 'Has a problem or goal but no strategy yet',
+                entry: 'Stage 1 — project identity',
+                openingQuestion: "What's the project in one sentence? And who is it for?",
+            },
+            {
+                situation: 'Has an idea but nothing concrete',
+                entry: 'Stage 0 — exploration',
+                openingQuestion: "What's on your mind? Tell me about it — even rough is fine.",
+            },
+        ],
+        routingQuestion: 'Before we dive in — do you already have a client or deadline in mind, ' +
+            'or are you still figuring out what this project is?',
+    };
+}
+/**
+ * Build the first-session conversation guide for general-tier fresh projects.
+ * Tells the agent what to ask, what to capture, and what the user should leave with.
+ */
+function buildFirstSessionPrompt() {
+    return ('First session — General tier. Memory and thinking partner; no missions, no tasks, no structured intake.\n\n' +
+        "Open: One warm question about what they're working on. Do not mention CMOS, tiers, or setup.\n" +
+        'Example: "What are you working on? I\'ll hold onto the things worth remembering as we go."\n\n' +
+        'During the session:\n' +
+        '- Start a session silently: cmos_session(action="start", type="custom", title="<topic>")\n' +
+        '- Capture decisions as they surface: cmos_decisions(action="capture", ...)\n' +
+        '- Write key context to master_context: cmos_context(action="write", contextType="master_context")\n' +
+        '- Do not interrupt to announce what you are saving\n\n' +
+        'End state: user has project context written, key decisions and open threads captured, ' +
+        'agent ready to resume naturally next session.');
+}
+async function detectSenderAttributionAmbiguity(params, resolvedProjectRoot) {
+    const reasons = [];
+    const advertisedRoots = (params.advertisedRoots ?? []).map((root) => path_1.default.resolve(root));
+    if ((process.env[client_2.CMOS_PROJECT_ROOT_ENV] ?? '').trim().length > 0) {
+        reasons.push(`${client_2.CMOS_PROJECT_ROOT_ENV} is set`);
+    }
+    if (advertisedRoots.length === 0) {
+        reasons.push('no MCP roots advertised');
+    }
+    if (!params.callerProvidedProjectRoot && advertisedRoots.length === 0) {
+        try {
+            const registry = await project_registry_1.ProjectRegistry.create();
+            const projects = await registry.list();
+            const cwd = path_1.default.resolve(process.cwd());
+            const currentRoot = path_1.default.resolve(resolvedProjectRoot);
+            if (projects.length > 1 && (cwd === sender_context_1.SERVER_INSTALL_ROOT || cwd !== currentRoot)) {
+                reasons.push('multiple registered projects with no clear current root');
+            }
+        }
+        catch {
+            // Registry ambiguity is best-effort; onboard should never fail because of it.
+        }
+    }
+    return {
+        ambiguous: reasons.length > 0,
+        reasons,
+    };
+}
+/**
+ * Generate suggested actions based on current state.
+ */
+function generateSuggestedActions(state) {
+    const skippedTools = new Set(state.toolsSkip);
+    const actions = [];
+    // If this is a fresh project, suggest starting the first-session flow immediately
+    if (state.freshProject) {
+        actions.push({
+            action: 'Fresh project detected — no active missions. Begin first-session setup.',
+            command: 'Follow the tierSelectionPrompt in this payload to start the opening conversation.',
+            priority: 0,
+        });
+    }
+    // If server is running stale code, top priority action
+    if (!state.serverHealth.codeIsCurrent) {
+        actions.push({
+            action: 'MCP server is running stale code — restart required to pick up latest build',
+            command: 'Restart MCP server process (e.g., reload Claude Desktop config or restart PM2)',
+            priority: 0,
+        });
+    }
+    if (state.senderAttributionAmbiguity.ambiguous && !skippedTools.has('cmos_message')) {
+        actions.push({
+            action: 'Run whoami to confirm sender attribution',
+            command: 'cmos_message(action="whoami")',
+            priority: 1,
+        });
+    }
+    // Sprint 57 m04 + Sprint 58 m02: surface auth-state issues so agents can self-heal credentials.
+    if (state.authState && !skippedTools.has('cmos_auth')) {
+        if (state.authState.identitySource === 'request-body') {
+            actions.push({
+                action: 'Sends are being attributed via the legacy user-scoped + body-level path — rotate to a project-scoped key.',
+                command: 'cmos_auth(action="reissue", projectRoot="<current project root>")',
+                priority: 1,
+            });
+        }
+        else if (state.projectRootSupplied &&
+            state.authState.identitySource !== 'none' &&
+            state.authState.projectKey === null &&
+            state.authState.userScopedKey !== null) {
+            actions.push({
+                action: 'No project-scoped key for this project root yet — register or reissue to mint one.',
+                command: 'cmos_auth(action="reissue", projectRoot="<current project root>") (after registration completes)',
+                priority: 2,
+            });
+        }
+        else if (state.authState.authTier === 'none') {
+            // Sprint 58 m02 — replaces the Sprint 57 m04 "identitySource === none"
+            // branch with a cmos_auth(action="login") command (now that m01 ships
+            // the reachable entrypoint). Same trigger condition because authTier
+            // is 'none' iff no user-scoped keys AND no legacy env vars.
+            actions.push({
+                action: 'No dashboard credentials configured — run login before any send/init.',
+                command: 'cmos_auth(action="login")',
+                priority: 1,
+            });
+        }
+        else if (state.authState.authTier === 'legacy-env' ||
+            state.authState.authTier === 'password-fallback') {
+            // Sprint 58 m02 — authTier is non-none but not device-code: the user
+            // has auth configured but via a deprecated arm. Nudge toward login
+            // without blocking work (priority 2, not 1).
+            actions.push({
+                action: `Authenticating via ${state.authState.authTier} — migrate to device-code credentials.`,
+                command: 'cmos_auth(action="login")',
+                priority: 2,
+            });
+        }
+    }
+    // Sprint closeout guardrail: all missions done but sprint still Active
+    if (state.currentSprint &&
+        state.currentSprint.status === 'Active' &&
+        state.pendingMissions.length === 0 &&
+        state.blockedMissions.length === 0 &&
+        !skippedTools.has('cmos_sprint')) {
+        actions.push({
+            action: `All missions complete — close out ${state.currentSprint.id} with sprint complete`,
+            command: `cmos_sprint(action="complete", sprintId="${state.currentSprint.id}", summary="Sprint summary here")`,
+            priority: 1,
+        });
+    }
+    // If stale decisions exist, suggest automated review
+    if (state.staleCounts.decisions > 0) {
+        actions.push({
+            action: `${state.staleCounts.decisions} stale decision(s) — run automated review for triage`,
+            command: 'cmos_decisions(action="review") for per-decision scores and batch archive suggestions',
+            priority: 2,
+        });
+    }
+    // If stale next-steps exist, suggest review
+    if (state.staleNextStepsCount > 0) {
+        actions.push({
+            action: `${state.staleNextStepsCount} stale next-step(s) from older sprints still pending — review and resolve`,
+            command: 'cmos_context(action="next_steps", nextStepAction="list") to review, then complete/carry/drop',
+            priority: 3,
+        });
+    }
+    // If stale/expired constraints exist, suggest review
+    if (state.staleConstraintCount > 0) {
+        actions.push({
+            action: `${state.staleConstraintCount} stale/expired constraint(s) — review and archive outdated ones`,
+            command: 'cmos_context(action="constraints", constraintAction="review") to see scores, then archive',
+            priority: 3,
+        });
+    }
+    // If context is near size limit, suggest proactive condensation
+    const masterUsage = state.contextSizes.masterContext?.usagePercent ?? 0;
+    const projectUsage = state.contextSizes.projectContext?.usagePercent ?? 0;
+    if (masterUsage >= 75 || projectUsage >= 75) {
+        const which = masterUsage >= 75 && projectUsage >= 75
+            ? 'both contexts'
+            : masterUsage >= 75
+                ? 'master_context'
+                : 'project_context';
+        const maxUsage = Math.max(masterUsage, projectUsage);
+        actions.push({
+            action: `Context at ${maxUsage.toFixed(0)}% capacity (${which}) — condense proactively to avoid hitting limits`,
+            command: 'cmos_context(action="condense", strategy="auto") or strategy="aggressive" for deeper reduction',
+            priority: 2,
+        });
+    }
+    // If sync health shows mismatches, warn (skip if cmos_db is hidden)
+    if (state.syncHealth && !state.syncHealth.allMatch && !skippedTools.has('cmos_db')) {
+        actions.push({
+            action: `Sync health: ${state.syncHealth.totalMismatches} table(s) have count mismatches between SQLite and PG mirror`,
+            command: 'cmos_db(action="reconcile") for details, cmos_db(action="backfill", force=true) to re-sync',
+            priority: 3,
+        });
+    }
+    // Surface each stale session as an individual high-priority action
+    for (const session of state.orphans.staleSessions) {
+        actions.push({
+            action: `Stale session ${session.id} ("${session.title}") active for ${Math.round(session.hoursActive)}h — complete or discard`,
+            command: `cmos_session(action="complete", sessionId="${session.id}", summary="Auto-closed: abandoned session")`,
+            priority: 1,
+        });
+    }
+    // Surface orphaned sprints/missions at lower priority
+    const nonSessionOrphans = state.orphans.orphanedSprints.length + state.orphans.orphanedMissions.length;
+    if (nonSessionOrphans > 0) {
+        actions.push({
+            action: `${nonSessionOrphans} orphaned entit${nonSessionOrphans === 1 ? 'y' : 'ies'} detected — review warnings for details`,
+            command: 'Review orphan warnings above. Archive unused sprints/missions.',
+            priority: 3,
+        });
+    }
+    // If strategic context is stale, recommend refresh immediately.
+    if (state.contextFreshness.isStale) {
+        actions.push({
+            action: `Refresh stale master context (lag ~${state.contextFreshness.lagDays?.toFixed(1) ?? 'unknown'} days)`,
+            command: 'cmos_context_update()',
+            priority: 1,
+        });
+    }
+    // If there are unread messages, suggest checking inbox
+    if (state.messaging && state.messaging.unreadCount > 0) {
+        actions.push({
+            action: `Review ${state.messaging.unreadCount} unread message(s) in inbox`,
+            command: 'cmos_message(action="list", status="pending")',
+            priority: 2,
+        });
+    }
+    // If there are blocked missions, suggest unblocking (skip if missions hidden)
+    if (state.blockedMissions.length > 0 && !skippedTools.has('cmos_mission')) {
+        const blocked = state.blockedMissions[0];
+        actions.push({
+            action: `Resolve blocked mission: ${blocked.id} (${blocked.name})`,
+            command: `cmos_mission_show(missionId="${blocked.id}")`,
+            priority: 3,
+        });
+    }
+    // If there's an In Progress mission, suggest continuing it (skip if missions hidden)
+    const inProgress = state.pendingMissions.find((m) => m.status === 'In Progress');
+    if (inProgress && !skippedTools.has('cmos_mission')) {
+        actions.push({
+            action: `Continue in-progress mission: ${inProgress.id} (${inProgress.name})`,
+            command: `cmos_mission_show(missionId="${inProgress.id}")`,
+            priority: 4,
+        });
+    }
+    // If there's a Current mission (not In Progress), suggest starting it (skip if missions hidden)
+    const current = state.pendingMissions.find((m) => m.status === 'Current');
+    if (current && !inProgress && !skippedTools.has('cmos_mission_transition')) {
+        actions.push({
+            action: `Start current mission: ${current.id} (${current.name})`,
+            command: `cmos_mission_start(missionId="${current.id}")`,
+            priority: 5,
+        });
+    }
+    // If no active session, suggest starting one
+    if (!state.activeSession) {
+        actions.push({
+            action: 'Start a planning or review session',
+            command: 'cmos_session_start(type="planning", title="Session title")',
+            priority: 6,
+        });
+    }
+    // If there's an active session, remind to complete it
+    if (state.activeSession) {
+        actions.push({
+            action: `Complete active session: ${state.activeSession.title}`,
+            command: `cmos_session_complete(summary="Session summary")`,
+            priority: 7,
+        });
+    }
+    // If there's a current sprint with completed sprints in history, suggest analytics (skip if sprints hidden)
+    if (state.currentSprint && !skippedTools.has('cmos_sprint')) {
+        actions.push({
+            action: 'View cross-sprint trend analytics (velocity, completion rate, decision volume)',
+            command: 'cmos_sprint(action="analytics")',
+            priority: 8,
+        });
+    }
+    // Suggest viewing mission status if no other actions (skip if missions hidden)
+    if (actions.length === 0 && !skippedTools.has('cmos_mission')) {
+        actions.push({
+            action: 'View mission queue',
+            command: 'cmos_mission_status()',
+            priority: 1,
+        });
+    }
+    return actions.sort((a, b) => a.priority - b.priority);
+}
+/**
+ * Format agent onboard result for LLM readability.
+ *
+ * @param result - Agent onboard result
+ * @returns Human-readable summary
+ */
+function formatAgentOnboardForLLM(result) {
+    if (!result.success || !result.data) {
+        const error = result.error;
+        return [
+            '❌ Failed to retrieve onboarding data',
+            '',
+            `Error: ${error?.message ?? 'Unknown error'}`,
+            error?.suggestion ? `Suggestion: ${error.suggestion}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    const data = result.data;
+    const lines = [];
+    // Header
+    lines.push('🚀 **Agent Onboarding**');
+    lines.push('');
+    // Project identity
+    lines.push(`**Project**: ${data.project.name}`);
+    if (data.project.description) {
+        lines.push(`  ${data.project.description}`);
+    }
+    if (data.project.status) {
+        lines.push(`  Status: ${data.project.status}`);
+    }
+    if (data.tierConfig) {
+        lines.push(`  Tier: ${data.tierConfig.label} (${data.tierConfig.tier})`);
+    }
+    // Sprint context
+    if (data.currentSprint) {
+        lines.push('');
+        lines.push(`**Sprint**: ${data.currentSprint.id} - ${data.currentSprint.title}`);
+        if (data.currentSprint.focus) {
+            lines.push(`  Focus: ${data.currentSprint.focus}`);
+        }
+    }
+    // Session stats
+    lines.push('');
+    lines.push(`**Sessions**: ${data.sessionStats.totalSessions} total${data.sessionStats.lastActivity ? `, last: ${data.sessionStats.lastActivity}` : ''}`);
+    lines.push('');
+    lines.push(`**Context Size**: ${data.contextSizes.totalSizeKb.toFixed(2)}KB (${data.contextSizes.totalSizeBytes} bytes total)`);
+    if (data.contextSizes.masterContext) {
+        lines.push(`  master_context: ${data.contextSizes.masterContext.sizeKb.toFixed(2)}KB (${data.contextSizes.masterContext.usagePercent.toFixed(1)}%)`);
+    }
+    if (data.contextSizes.projectContext) {
+        lines.push(`  project_context: ${data.contextSizes.projectContext.sizeKb.toFixed(2)}KB (${data.contextSizes.projectContext.usagePercent.toFixed(1)}%)`);
+    }
+    // Context freshness
+    lines.push('');
+    lines.push(`**Context Freshness**: ${data.contextFreshness.isStale ? 'stale' : 'fresh'}${data.contextFreshness.lagDays !== null
+        ? ` (${data.contextFreshness.lagDays.toFixed(1)} day lag)`
+        : ''}`);
+    lines.push(`  master_context.updated_at: ${data.contextFreshness.contextUpdatedAt ?? 'unknown'}`);
+    lines.push(`  latest completed activity: ${data.contextFreshness.latestActivityAt ?? 'none'}`);
+    // Sync health (reconciliation)
+    if (data.syncHealth) {
+        lines.push('');
+        if (data.syncHealth.allMatch) {
+            lines.push('**Sync Health**: all tables match');
+        }
+        else {
+            lines.push(`**Sync Health**: ${data.syncHealth.totalMismatches} table(s) mismatched`);
+            for (const m of data.syncHealth.mismatches) {
+                const sign = m.delta > 0 ? '+' : '';
+                lines.push(`  ${m.table}: SQLite=${m.sqliteCount} PG=${m.pgCount} (${sign}${m.delta})`);
+            }
+        }
+        if (data.syncHealth.failedEntries > 0) {
+            lines.push(`  Failed sync entries: ${data.syncHealth.failedEntries}`);
+        }
+    }
+    // Server health
+    if (data.serverHealth) {
+        lines.push('');
+        const sh = data.serverHealth;
+        const uptimeStr = sh.uptimeSeconds < 60
+            ? `${sh.uptimeSeconds}s`
+            : sh.uptimeSeconds < 3600
+                ? `${Math.floor(sh.uptimeSeconds / 60)}m`
+                : `${Math.floor(sh.uptimeSeconds / 3600)}h ${Math.floor((sh.uptimeSeconds % 3600) / 60)}m`;
+        const buildHash = sh.startupBuild?.buildHash.slice(0, 12) ?? 'unknown';
+        const staleTag = sh.codeIsCurrent ? 'current' : '⚠️ STALE';
+        lines.push(`**Server Health**: pid=${sh.pid} uptime=${uptimeStr} mem=${sh.memoryUsageMb}MB build=${buildHash}… (${staleTag})`);
+        if (sh.stalenessMessage) {
+            lines.push(`  ${sh.stalenessMessage}`);
+        }
+    }
+    // Orphan detection
+    if (data.orphans && data.orphans.totalOrphans > 0) {
+        lines.push('');
+        lines.push(`**Orphans**: ${data.orphans.totalOrphans} detected (${data.orphans.orphanedSprints.length} sprint(s), ${data.orphans.orphanedMissions.length} mission(s), ${data.orphans.staleSessions.length} stale session(s))`);
+    }
+    // Messaging
+    if (data.messaging) {
+        lines.push('');
+        lines.push(`**Messaging**: ${data.messaging.unreadCount} unread`);
+        if (data.messaging.recentMessages.length > 0) {
+            for (const msg of data.messaging.recentMessages) {
+                const from = msg.from ? ` from ${msg.from}` : '';
+                lines.push(`  • [${msg.type}] ${msg.summary}${from}`);
+            }
+        }
+    }
+    // Active session
+    if (data.activeSession) {
+        lines.push('');
+        lines.push('⚡ **Active Session**');
+        lines.push(`  ${data.activeSession.type}: ${data.activeSession.title}`);
+        lines.push(`  Captures: ${data.activeSession.captureCount}`);
+    }
+    // Pending missions
+    if (data.pendingMissions.length > 0) {
+        lines.push('');
+        lines.push('📋 **Pending Work**');
+        for (const m of data.pendingMissions) {
+            lines.push(`  • ${m.id} (${m.status}): ${m.name}`);
+        }
+    }
+    // Blocked missions
+    if (data.blockedMissions.length > 0) {
+        lines.push('');
+        lines.push('🚫 **Blocked**');
+        for (const m of data.blockedMissions) {
+            lines.push(`  • ${m.id}: ${m.name}`);
+        }
+    }
+    // Recent decisions
+    if (data.recentDecisions.length > 0) {
+        lines.push('');
+        lines.push('📝 **Recent Decisions**');
+        for (const d of data.recentDecisions.slice(0, 5)) {
+            const domain = d.domain ? ` [${d.domain}]` : '';
+            lines.push(`  • ${d.decision}${domain}`);
+        }
+    }
+    // Next steps
+    if (data.nextSteps.length > 0) {
+        lines.push('');
+        lines.push('➡️ **Next Steps**');
+        for (const step of data.nextSteps) {
+            lines.push(`  • ${step}`);
+        }
+    }
+    // Suggested actions
+    if (data.suggestedActions.length > 0) {
+        lines.push('');
+        lines.push('💡 **Suggested Actions**');
+        for (const action of data.suggestedActions.slice(0, 3)) {
+            lines.push(`  ${action.priority}. ${action.action}`);
+            lines.push(`     → ${action.command}`);
+        }
+    }
+    // Tier behavioral guide
+    if (data.tierConfig?.guide) {
+        lines.push('');
+        lines.push('📖 **Behavioral Guide**');
+        lines.push(data.tierConfig.guide);
+    }
+    if (result.warnings && result.warnings.length > 0) {
+        lines.push('');
+        lines.push('⚠️ **Warnings**');
+        for (const warning of result.warnings) {
+            lines.push(`  • ${warning}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=cmos-agent-onboard.js.map