@contorium/mcp 0.8.1

package/dist/understanding.js

@@ -0,0 +1 @@
+export { readChangeArtifact, readHandoffArtifact, readImpactArtifact, readIntentArtifact, readProjectGraph, readProjectKnowledgeGraph, readKnowledgeSnapshot, readProjectTimeline, readUnderstandingGraph, readStateJson, readWorkspaceStatus, filterMappingsByConfidence, getProjectHandoff, } from '@contora/state-core';

package/dist/workspace.d.ts

@@ -0,0 +1,12 @@
+export interface WorkspaceSnapshot {
+    workspaceRoot: string;
+    currentTask: string;
+    notes: string;
+    sessionId?: string;
+    openFiles: string[];
+    recentFiles: string[];
+    gitStaged: string[];
+    gitWorking: string[];
+    lastUpdated: number;
+}
+export declare function loadWorkspaceSnapshot(workspaceRoot: string): Promise<WorkspaceSnapshot | null>;

package/dist/workspace.js

@@ -0,0 +1,40 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const CONTORA_DATA_DIR = '.contora';
+const LEGACY_DATA_DIR = '.context-recall';
+async function readStateFile(dir, relData) {
+    const fp = path.join(dir, relData, 'state.json');
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        if (!o || typeof o !== 'object') {
+            return undefined;
+        }
+        return {
+            workspaceRoot: dir,
+            sessionId: typeof o.sessionId === 'string' ? o.sessionId : undefined,
+            currentTask: typeof o.currentTask === 'string' ? o.currentTask : '',
+            notes: typeof o.notes === 'string' ? o.notes : '',
+            openFiles: Array.isArray(o.openFiles) ? o.openFiles.filter((x) => typeof x === 'string') : [],
+            recentFiles: Array.isArray(o.recentFiles)
+                ? o.recentFiles.filter((x) => typeof x === 'string')
+                : [],
+            gitStaged: Array.isArray(o.gitStaged) ? o.gitStaged.filter((x) => typeof x === 'string') : [],
+            gitWorking: Array.isArray(o.gitWorking)
+                ? o.gitWorking.filter((x) => typeof x === 'string')
+                : [],
+            lastUpdated: typeof o.lastUpdated === 'number' ? o.lastUpdated : 0,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function loadWorkspaceSnapshot(workspaceRoot) {
+    const primary = await readStateFile(workspaceRoot, CONTORA_DATA_DIR);
+    if (primary) {
+        return primary;
+    }
+    const legacy = await readStateFile(workspaceRoot, LEGACY_DATA_DIR);
+    return legacy ?? null;
+}

package/dist/workspaceConfig.d.ts

@@ -0,0 +1,14 @@
+export interface McpStartupConfig {
+    workspaceHint: string;
+    workspaceFromArgv: boolean;
+}
+/** Set once at process start from CLI --workspace (highest priority). */
+export declare function setStartupWorkspace(workspace: string | undefined): void;
+/**
+ * Workspace hint resolution (MCP v1 standard):
+ * 1. CLI --workspace
+ * 2. CONTORIUM_WORKSPACE (+ host env aliases)
+ * 3. .mcp.json / .cursor/mcp.json
+ * 4. process.cwd()
+ */
+export declare function resolveMcpStartupConfig(argv?: string[]): McpStartupConfig;

package/dist/workspaceConfig.js

@@ -0,0 +1,80 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+let startupWorkspaceOverride;
+/** Set once at process start from CLI --workspace (highest priority). */
+export function setStartupWorkspace(workspace) {
+    startupWorkspaceOverride = workspace?.trim() || undefined;
+}
+function parseWorkspaceArg(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--workspace' && argv[i + 1]) {
+            return argv[i + 1].trim();
+        }
+        if (arg.startsWith('--workspace=')) {
+            return arg.slice('--workspace='.length).trim();
+        }
+    }
+    return undefined;
+}
+function expandEnvPlaceholders(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name]?.trim() ?? '');
+}
+function readMcpJsonWorkspace(startDir) {
+    const candidates = [
+        path.join(startDir, '.mcp.json'),
+        path.join(startDir, '.cursor', 'mcp.json'),
+    ];
+    for (const file of candidates) {
+        try {
+            const raw = fs.readFileSync(file, 'utf8');
+            const parsed = JSON.parse(raw);
+            const servers = parsed.mcpServers;
+            const contoriumBlock = parsed.contorium;
+            const env = servers?.contorium?.env ??
+                servers?.['@contorium/mcp']?.env ??
+                contoriumBlock?.env;
+            const ws = env?.CONTORIUM_WORKSPACE?.trim();
+            if (ws) {
+                const expanded = expandEnvPlaceholders(ws);
+                if (expanded) {
+                    return path.resolve(expanded);
+                }
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+}
+/**
+ * Workspace hint resolution (MCP v1 standard):
+ * 1. CLI --workspace
+ * 2. CONTORIUM_WORKSPACE (+ host env aliases)
+ * 3. .mcp.json / .cursor/mcp.json
+ * 4. process.cwd()
+ */
+export function resolveMcpStartupConfig(argv = process.argv.slice(2)) {
+    const fromArgv = parseWorkspaceArg(argv);
+    if (fromArgv) {
+        setStartupWorkspace(fromArgv);
+        return { workspaceHint: path.resolve(fromArgv), workspaceFromArgv: true };
+    }
+    if (startupWorkspaceOverride) {
+        return { workspaceHint: path.resolve(startupWorkspaceOverride), workspaceFromArgv: true };
+    }
+    const fromEnv = process.env.CONTORIUM_WORKSPACE?.trim() ||
+        process.env.CODEX_PROJECT_DIR?.trim() ||
+        process.env.CLAUDE_PROJECT_DIR?.trim() ||
+        process.env.CLAUDE_PROJECT_ROOT?.trim() ||
+        process.env.MCP_WORKSPACE_ROOT?.trim();
+    if (fromEnv) {
+        return { workspaceHint: path.resolve(fromEnv), workspaceFromArgv: false };
+    }
+    const fromMcpJson = readMcpJsonWorkspace(process.cwd());
+    if (fromMcpJson) {
+        return { workspaceHint: fromMcpJson, workspaceFromArgv: false };
+    }
+    return { workspaceHint: process.cwd(), workspaceFromArgv: false };
+}

package/node_modules/@contora/state-core/dist/adapterSync.d.ts

@@ -0,0 +1,29 @@
+import type { AdapterKind, StateEngineMode, StateSourceMetadata } from './types.js';
+export interface AdapterSyncResult {
+    mode: StateEngineMode;
+    /** true when .contora/state.json did not exist before this call */
+    created: boolean;
+    /** true when state.json or artifacts were written */
+    updated: boolean;
+    source?: StateSourceMetadata;
+    eventCount: number;
+}
+/**
+ * Shared one-shot sync for MCP / CLI adapters (runtime adapter pattern).
+ * Scans workspace, merges into state.json, optionally rebuilds L4 when no events.
+ */
+export declare function syncWorkspaceState(workspaceRoot: string, writer: AdapterKind, options?: {
+    forceArtifacts?: boolean;
+}): Promise<AdapterSyncResult>;
+/** Read-only status for CLI `status` / IDE-less inspection. */
+export declare function readWorkspaceStatus(workspaceRoot: string): Promise<{
+    workspaceRoot: string;
+    hasState: boolean;
+    mode: StateEngineMode | 'unknown';
+    source?: StateSourceMetadata;
+    eventCount: number;
+    gitWorking: number;
+    gitStaged: number;
+    currentTask: string;
+}>;
+//# sourceMappingURL=adapterSync.d.ts.map

package/node_modules/@contora/state-core/dist/adapterSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapterSync.d.ts","sourceRoot":"","sources":["../src/adapterSync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA4BpF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA8D5B;AAED,+DAA+D;AAC/D,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAiBD"}

package/node_modules/@contora/state-core/dist/adapterSync.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncWorkspaceState = syncWorkspaceState;
+exports.readWorkspaceStatus = readWorkspaceStatus;
+const path = __importStar(require("node:path"));
+const bootstrapState_js_1 = require("./bootstrap/bootstrapState.js");
+const rebuildFromScan_js_1 = require("./state-builder/rebuildFromScan.js");
+const buildUnderstanding_js_1 = require("./understanding/buildUnderstanding.js");
+const dualMode_js_1 = require("./dualMode.js");
+const dashboardActivity_js_1 = require("./dashboardActivity.js");
+const workspaceScanner_js_1 = require("./scanner/workspaceScanner.js");
+async function countEventLines(workspaceRoot) {
+    const { readdir, readFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+    const { join } = await Promise.resolve().then(() => __importStar(require('node:path')));
+    const dir = join(workspaceRoot, '.contora', 'events');
+    let total = 0;
+    try {
+        const files = await readdir(dir);
+        for (const f of files) {
+            if (!f.endsWith('.jsonl')) {
+                continue;
+            }
+            const text = await readFile(join(dir, f), 'utf8');
+            total += text.split('\n').filter((l) => l.trim()).length;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return total;
+}
+/**
+ * Shared one-shot sync for MCP / CLI adapters (runtime adapter pattern).
+ * Scans workspace, merges into state.json, optionally rebuilds L4 when no events.
+ */
+async function syncWorkspaceState(workspaceRoot, writer, options) {
+    const resolved = path.resolve(workspaceRoot);
+    const scan = await (0, workspaceScanner_js_1.scanWorkspace)(resolved);
+    const eventCount = await countEventLines(resolved);
+    const existing = await (0, bootstrapState_js_1.readStateJson)(resolved);
+    const created = !existing;
+    if (!existing) {
+        const state = (0, bootstrapState_js_1.bootstrapStateFromScan)(scan);
+        await (0, bootstrapState_js_1.writeStateJson)(resolved, state, { mode: 'scan-driven', writer });
+        await (0, rebuildFromScan_js_1.rebuildArtifactsFromScan)(resolved, scan, state, writer);
+        const written = await (0, bootstrapState_js_1.readStateJson)(resolved);
+        return {
+            mode: 'scan-driven',
+            created: true,
+            updated: true,
+            source: written?.source,
+            eventCount,
+        };
+    }
+    const dual = (0, dualMode_js_1.buildDualModeInput)({ state: existing, eventCount, scan });
+    const gitChanged = JSON.stringify(existing.gitStaged) !== JSON.stringify(dual.state.gitStaged) ||
+        JSON.stringify(existing.gitWorking) !== JSON.stringify(dual.state.gitWorking);
+    const recentChanged = eventCount === 0 &&
+        JSON.stringify(existing.recentFiles) !== JSON.stringify(dual.state.recentFiles);
+    const shouldWrite = gitChanged || recentChanged || options?.forceArtifacts;
+    if (shouldWrite) {
+        await (0, bootstrapState_js_1.writeStateJson)(resolved, dual.state, { mode: dual.mode, writer });
+    }
+    if (eventCount === 0 && (shouldWrite || options?.forceArtifacts)) {
+        await (0, rebuildFromScan_js_1.rebuildArtifactsFromScan)(resolved, scan, dual.state, writer);
+    }
+    if (gitChanged || options?.forceArtifacts) {
+        await (0, buildUnderstanding_js_1.buildAndWriteUnderstandingArtifacts)({
+            workspaceRoot: resolved,
+            state: dual.state,
+            scan,
+        }).catch(() => undefined);
+    }
+    const written = await (0, bootstrapState_js_1.readStateJson)(resolved);
+    const updated = shouldWrite || (eventCount === 0 && !!options?.forceArtifacts);
+    if (updated || gitChanged) {
+        await (0, dashboardActivity_js_1.bumpWorkspaceActivity)(resolved, {
+            source: writer,
+            kind: gitChanged ? 'git_change' : 'sync',
+            detail: gitChanged ? 'workspace sync' : undefined,
+        }).catch(() => undefined);
+    }
+    return {
+        mode: dual.mode,
+        created: false,
+        updated,
+        source: written?.source,
+        eventCount,
+    };
+}
+/** Read-only status for CLI `status` / IDE-less inspection. */
+async function readWorkspaceStatus(workspaceRoot) {
+    const scan = await (0, workspaceScanner_js_1.scanWorkspace)(workspaceRoot);
+    const state = await (0, bootstrapState_js_1.readStateJson)(workspaceRoot);
+    const eventCount = await countEventLines(workspaceRoot);
+    const mode = state
+        ? (0, dualMode_js_1.buildDualModeInput)({ state, eventCount, scan }).mode
+        : 'unknown';
+    return {
+        workspaceRoot,
+        hasState: !!state,
+        mode,
+        source: state?.source,
+        eventCount,
+        gitWorking: state?.gitWorking.length ?? scan.gitWorking.length,
+        gitStaged: state?.gitStaged.length ?? scan.gitStaged.length,
+        currentTask: state?.currentTask ?? '',
+    };
+}

package/node_modules/@contora/state-core/dist/adapters.d.ts

@@ -0,0 +1,20 @@
+import type { AdapterKind } from './types.js';
+/** Tool adapter contract — adapters ingest; State Engine owns truth. */
+export interface ContoriumAdapter {
+    readonly kind: AdapterKind;
+    /** Human-readable status for logs / MCP debug. */
+    describe(): string;
+}
+export declare class IdeAdapter implements ContoriumAdapter {
+    readonly kind: "ide";
+    describe(): string;
+}
+export declare class McpAdapter implements ContoriumAdapter {
+    readonly kind: "mcp";
+    describe(): string;
+}
+export declare class CliAdapter implements ContoriumAdapter {
+    readonly kind: "cli";
+    describe(): string;
+}
+//# sourceMappingURL=adapters.d.ts.map

package/node_modules/@contora/state-core/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,IAAI,MAAM;CAGnB;AAED,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,IAAI,MAAM;CAGnB;AAED,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,IAAI,MAAM;CAGnB"}

package/node_modules/@contora/state-core/dist/adapters.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliAdapter = exports.McpAdapter = exports.IdeAdapter = void 0;
+class IdeAdapter {
+    kind = 'ide';
+    describe() {
+        return 'IDE event streaming (Mode A)';
+    }
+}
+exports.IdeAdapter = IdeAdapter;
+class McpAdapter {
+    kind = 'mcp';
+    describe() {
+        return 'MCP workspace scan + poll (Mode B)';
+    }
+}
+exports.McpAdapter = McpAdapter;
+class CliAdapter {
+    kind = 'cli';
+    describe() {
+        return 'CLI scan command (Mode B)';
+    }
+}
+exports.CliAdapter = CliAdapter;

package/node_modules/@contora/state-core/dist/bootstrap/bootstrapState.d.ts

@@ -0,0 +1,6 @@
+import type { BootstrapStateJson, WriteStateOptions, WorkspaceScanFacts } from '../types.js';
+export declare function bootstrapStateFromScan(scan: WorkspaceScanFacts): BootstrapStateJson;
+export declare function readStateJson(workspaceRoot: string): Promise<BootstrapStateJson | null>;
+export declare function writeStateJson(workspaceRoot: string, state: BootstrapStateJson, meta?: WriteStateOptions): Promise<void>;
+export declare function stateJsonExists(workspaceRoot: string): Promise<boolean>;
+//# sourceMappingURL=bootstrapState.d.ts.map

package/node_modules/@contora/state-core/dist/bootstrap/bootstrapState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapState.d.ts","sourceRoot":"","sources":["../../src/bootstrap/bootstrapState.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQ7F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAWnF;AAED,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA2C7F;AAED,wBAAsB,cAAc,CAClC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7E"}

package/node_modules/@contora/state-core/dist/bootstrap/bootstrapState.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrapStateFromScan = bootstrapStateFromScan;
+exports.readStateJson = readStateJson;
+exports.writeStateJson = writeStateJson;
+exports.stateJsonExists = stateJsonExists;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const sourceMetadata_js_1 = require("../sourceMetadata.js");
+const CONTORA_DIR = '.contora';
+function newSessionId() {
+    return `sess_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function bootstrapStateFromScan(scan) {
+    return {
+        sessionId: newSessionId(),
+        currentTask: '',
+        openFiles: scan.recentFiles.slice(0, 8),
+        recentFiles: scan.recentFiles.slice(0, 24),
+        gitStaged: scan.gitStaged,
+        gitWorking: scan.gitWorking,
+        notes: '',
+        lastUpdated: scan.scannedAt,
+    };
+}
+async function readStateJson(workspaceRoot) {
+    const fp = path.join(workspaceRoot, CONTORA_DIR, 'state.json');
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        const sourceRaw = o.source;
+        let source;
+        if (sourceRaw && typeof sourceRaw === 'object') {
+            const s = sourceRaw;
+            if ((s.mode === 'event-driven' || s.mode === 'scan-driven' || s.mode === 'merged') &&
+                (s.lastWriter === 'ide' || s.lastWriter === 'mcp' || s.lastWriter === 'cli') &&
+                typeof s.lastUpdated === 'string') {
+                source = {
+                    mode: s.mode,
+                    lastWriter: s.lastWriter,
+                    lastUpdated: s.lastUpdated,
+                };
+            }
+        }
+        return {
+            sessionId: typeof o.sessionId === 'string' ? o.sessionId : newSessionId(),
+            currentTask: typeof o.currentTask === 'string' ? o.currentTask : '',
+            openFiles: Array.isArray(o.openFiles)
+                ? o.openFiles.filter((x) => typeof x === 'string')
+                : [],
+            recentFiles: Array.isArray(o.recentFiles)
+                ? o.recentFiles.filter((x) => typeof x === 'string')
+                : [],
+            gitStaged: Array.isArray(o.gitStaged)
+                ? o.gitStaged.filter((x) => typeof x === 'string')
+                : [],
+            gitWorking: Array.isArray(o.gitWorking)
+                ? o.gitWorking.filter((x) => typeof x === 'string')
+                : [],
+            notes: typeof o.notes === 'string' ? o.notes : '',
+            lastUpdated: typeof o.lastUpdated === 'number' ? o.lastUpdated : 0,
+            source,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeStateJson(workspaceRoot, state, meta) {
+    const dir = path.join(workspaceRoot, CONTORA_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    const toWrite = meta ? (0, sourceMetadata_js_1.attachStateSource)(state, meta.mode, meta.writer) : state;
+    await fs.writeFile(path.join(dir, 'state.json'), JSON.stringify(toWrite, null, 2), 'utf8');
+}
+async function stateJsonExists(workspaceRoot) {
+    try {
+        await fs.access(path.join(workspaceRoot, CONTORA_DIR, 'state.json'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@contora/state-core/dist/bootstrapArtifacts.d.ts

@@ -0,0 +1,18 @@
+import type { BootstrapStateJson, WorkspaceScanFacts } from './types.js';
+export interface BootstrapProjectBuiltState {
+    version: 1;
+    engine_version: 2;
+    generatedAt: number;
+    task_anchor?: string;
+    project_goal: string;
+    current_stage: string;
+    active_modules: string[];
+    recent_decisions: string[];
+    open_problems: string[];
+    completed_milestones: string[];
+    next_actions: string[];
+    confidence: number;
+}
+export declare function buildBootstrapProjectState(scan: WorkspaceScanFacts, state?: BootstrapStateJson): BootstrapProjectBuiltState;
+export declare function writeBootstrapArtifacts(workspaceRoot: string, scan: WorkspaceScanFacts, state?: BootstrapStateJson): Promise<void>;
+//# sourceMappingURL=bootstrapArtifacts.d.ts.map

package/node_modules/@contora/state-core/dist/bootstrapArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapArtifacts.d.ts","sourceRoot":"","sources":["../src/bootstrapArtifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,EACxB,KAAK,CAAC,EAAE,kBAAkB,GACzB,0BAA0B,CA8B5B;AAED,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,kBAAkB,EACxB,KAAK,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/node_modules/@contora/state-core/dist/bootstrapArtifacts.js

@@ -0,0 +1,43 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { formatBootstrapSnapshotMarkdown } from './minimalSnapshot.js';
+const BUILDER_DIR = ['.contora', 'state-builder'];
+export function buildBootstrapProjectState(scan, state) {
+    const modules = [
+        ...scan.topLevelModules.slice(0, 6),
+        ...scan.recentFiles.slice(0, 4).map((f) => f.split('/').pop() ?? f),
+    ];
+    const active = [...new Set(modules)].slice(0, 8);
+    const goal = scan.readmeHint?.trim() ||
+        (active.length ? `develop ${active.slice(0, 2).join(' and ')} areas` : 'ongoing workspace development');
+    const gitCount = scan.gitStaged.length + scan.gitWorking.length;
+    return {
+        version: 1,
+        engine_version: 2,
+        generatedAt: scan.scannedAt,
+        task_anchor: state?.currentTask?.trim() || undefined,
+        project_goal: goal,
+        current_stage: scan.isGitRepo
+            ? 'repository scan (tool-agnostic bootstrap)'
+            : 'workspace scan (no git)',
+        active_modules: active,
+        recent_decisions: [],
+        open_problems: gitCount >= 6 ? ['uncommitted changes across workspace'] : ['(light or undirected activity)'],
+        completed_milestones: [],
+        next_actions: [
+            'review recent file activity',
+            ...(scan.isGitRepo ? ['review and commit pending changes'] : []),
+        ],
+        confidence: 0.35,
+    };
+}
+export async function writeBootstrapArtifacts(workspaceRoot, scan, state) {
+    const dir = path.join(workspaceRoot, ...BUILDER_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    const built = buildBootstrapProjectState(scan, state);
+    const md = formatBootstrapSnapshotMarkdown(scan, state?.currentTask ?? '');
+    await Promise.all([
+        fs.writeFile(path.join(dir, 'project-state.json'), JSON.stringify(built, null, 2), 'utf8'),
+        fs.writeFile(path.join(dir, 'project-snapshot.md'), md, 'utf8'),
+    ]);
+}

package/node_modules/@contora/state-core/dist/bootstrapState.d.ts

@@ -0,0 +1,6 @@
+import type { BootstrapStateJson, WorkspaceScanFacts } from './types.js';
+export declare function bootstrapStateFromScan(scan: WorkspaceScanFacts): BootstrapStateJson;
+export declare function readStateJson(workspaceRoot: string): Promise<BootstrapStateJson | null>;
+export declare function writeStateJson(workspaceRoot: string, state: BootstrapStateJson): Promise<void>;
+export declare function stateJsonExists(workspaceRoot: string): Promise<boolean>;
+//# sourceMappingURL=bootstrapState.d.ts.map

package/node_modules/@contora/state-core/dist/bootstrapState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapState.d.ts","sourceRoot":"","sources":["../src/bootstrapState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAQzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAWnF;AAED,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA0B7F;AAED,wBAAsB,cAAc,CAClC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7E"}

package/node_modules/@contora/state-core/dist/bootstrapState.js

@@ -0,0 +1,60 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const CONTORA_DIR = '.contora';
+function newSessionId() {
+    return `sess_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function bootstrapStateFromScan(scan) {
+    return {
+        sessionId: newSessionId(),
+        currentTask: '',
+        openFiles: scan.recentFiles.slice(0, 8),
+        recentFiles: scan.recentFiles.slice(0, 24),
+        gitStaged: scan.gitStaged,
+        gitWorking: scan.gitWorking,
+        notes: '',
+        lastUpdated: scan.scannedAt,
+    };
+}
+export async function readStateJson(workspaceRoot) {
+    const fp = path.join(workspaceRoot, CONTORA_DIR, 'state.json');
+    try {
+        const text = await fs.readFile(fp, 'utf8');
+        const o = JSON.parse(text);
+        return {
+            sessionId: typeof o.sessionId === 'string' ? o.sessionId : newSessionId(),
+            currentTask: typeof o.currentTask === 'string' ? o.currentTask : '',
+            openFiles: Array.isArray(o.openFiles)
+                ? o.openFiles.filter((x) => typeof x === 'string')
+                : [],
+            recentFiles: Array.isArray(o.recentFiles)
+                ? o.recentFiles.filter((x) => typeof x === 'string')
+                : [],
+            gitStaged: Array.isArray(o.gitStaged)
+                ? o.gitStaged.filter((x) => typeof x === 'string')
+                : [],
+            gitWorking: Array.isArray(o.gitWorking)
+                ? o.gitWorking.filter((x) => typeof x === 'string')
+                : [],
+            notes: typeof o.notes === 'string' ? o.notes : '',
+            lastUpdated: typeof o.lastUpdated === 'number' ? o.lastUpdated : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeStateJson(workspaceRoot, state) {
+    const dir = path.join(workspaceRoot, CONTORA_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'state.json'), JSON.stringify(state, null, 2), 'utf8');
+}
+export async function stateJsonExists(workspaceRoot) {
+    try {
+        await fs.access(path.join(workspaceRoot, CONTORA_DIR, 'state.json'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@contora/state-core/dist/dashboardActivity.d.ts

@@ -0,0 +1,12 @@
+import type { AdapterKind } from './types.js';
+export type WorkspaceActivityKind = 'file_change' | 'function_change' | 'git_change' | 'sync' | 'event';
+export interface WorkspaceActivityBump {
+    at: number;
+    source: AdapterKind;
+    kind: WorkspaceActivityKind;
+    detail?: string;
+}
+/** Record workspace activity — universal trigger for dashboard auto-attach (IDE / MCP / CLI). */
+export declare function bumpWorkspaceActivity(workspaceRoot: string, bump: Omit<WorkspaceActivityBump, 'at'>): Promise<void>;
+export declare function readWorkspaceActivity(workspaceRoot: string): Promise<WorkspaceActivityBump | undefined>;
+//# sourceMappingURL=dashboardActivity.d.ts.map