@bolt-foundry/gambit 0.8.6-rc.3 → 0.8.6-rc.4

package/script/src/server_workspace_decks.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.resolveGraderDeckFromState = exports.resolveScenarioDeckFromState = exports.buildRootScenarioFallback = exports.buildWorkspaceDeckStateFromLoadedDeck = exports.summarizeDeckState = exports.toAvailableGraderDeck = exports.toAvailableTestDeck = exports.toDeckLabel = void 0;
+const path = __importStar(require("../deps/jsr.io/@std/path/1.1.4/mod.js"));
+const slugify = (label) => {
+    return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)+/g, "");
+};
+const parseDeckMaxTurns = (value) => {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    const rounded = Math.round(value);
+    if (rounded < 1)
+        return 1;
+    if (rounded > 200)
+        return 200;
+    return rounded;
+};
+const toDeckLabel = (filePath) => {
+    const base = path.basename(filePath);
+    return base
+        .replace(/\.deck\.(md|ts)$/i, "")
+        .replace(/[-_]+/g, " ")
+        .trim() || base;
+};
+exports.toDeckLabel = toDeckLabel;
+const toAvailableTestDeck = (deck, index) => {
+    const label = deck.label && typeof deck.label === "string"
+        ? deck.label
+        : (0, exports.toDeckLabel)(deck.path);
+    const id = deck.id && typeof deck.id === "string"
+        ? deck.id
+        : slugify(`${label || "test-deck"}-${index}`);
+    const maxTurns = parseDeckMaxTurns(deck.maxTurns);
+    return {
+        id,
+        label: label || id,
+        description: typeof deck.description === "string"
+            ? deck.description
+            : undefined,
+        path: deck.path,
+        ...(maxTurns !== undefined ? { maxTurns } : {}),
+    };
+};
+exports.toAvailableTestDeck = toAvailableTestDeck;
+const toAvailableGraderDeck = (deck, index) => {
+    const label = deck.label && typeof deck.label === "string"
+        ? deck.label
+        : (0, exports.toDeckLabel)(deck.path);
+    const id = deck.id && typeof deck.id === "string"
+        ? deck.id
+        : slugify(`${label || "grader-deck"}-${index}`);
+    return {
+        id,
+        label: label || id,
+        description: typeof deck.description === "string"
+            ? deck.description
+            : undefined,
+        path: deck.path,
+    };
+};
+exports.toAvailableGraderDeck = toAvailableGraderDeck;
+const summarizeDeckState = (deckState) => ({
+    scenarioDeckCount: deckState?.scenarioDecks.length ?? 0,
+    scenarioDeckPaths: (deckState?.scenarioDecks ?? []).slice(0, 12).map((deck) => deck.path),
+    graderDeckCount: deckState?.graderDecks.length ?? 0,
+});
+exports.summarizeDeckState = summarizeDeckState;
+const buildWorkspaceDeckStateFromLoadedDeck = async (args) => {
+    const scenarioDecks = await Promise.all((args.deck.testDecks ?? []).map(async (scenarioDeck, index) => {
+        const availableDeck = (0, exports.toAvailableTestDeck)(scenarioDeck, index);
+        const desc = await args.describeDeckInputSchemaFromPath(availableDeck.path);
+        return {
+            ...availableDeck,
+            inputSchema: desc.schema,
+            defaults: desc.defaults,
+            inputSchemaError: desc.error,
+        };
+    }));
+    return {
+        workspaceId: args.workspaceId,
+        rootDeckPath: args.deck.path,
+        assistantDeck: args.buildPersistedAssistantDeck(args.deck),
+        scenarioDecks,
+        graderDecks: (args.deck.graderDecks ?? []).map(exports.toAvailableGraderDeck),
+        updatedAt: new Date().toISOString(),
+    };
+};
+exports.buildWorkspaceDeckStateFromLoadedDeck = buildWorkspaceDeckStateFromLoadedDeck;
+const buildRootScenarioFallback = (deckState) => ({
+    id: "root",
+    label: (0, exports.toDeckLabel)(deckState.assistantDeck.deck),
+    description: "Root simulator deck",
+    path: deckState.assistantDeck.deck,
+});
+exports.buildRootScenarioFallback = buildRootScenarioFallback;
+const resolveScenarioDeckFromState = (deckState, identifier) => {
+    if (!identifier)
+        return undefined;
+    const normalizedIdentifier = path.resolve(identifier);
+    return deckState.scenarioDecks.find((deck) => deck.id === identifier || path.resolve(deck.path) === normalizedIdentifier);
+};
+exports.resolveScenarioDeckFromState = resolveScenarioDeckFromState;
+const resolveGraderDeckFromState = (deckState, identifier) => {
+    if (!identifier)
+        return undefined;
+    const normalizedIdentifier = path.resolve(identifier);
+    return deckState.graderDecks.find((deck) => deck.id === identifier || path.resolve(deck.path) === normalizedIdentifier);
+};
+exports.resolveGraderDeckFromState = resolveGraderDeckFromState;

package/script/src/server_workspace_graphql.d.ts

@@ -0,0 +1,17 @@
+import type { SimulatorGraphqlOperations } from "./server_isograph_environment.js";
+import type { WorkspaceDeckState } from "./server_types.js";
+type WorkspaceDeckGraphqlOperations = Pick<SimulatorGraphqlOperations, "listWorkspaceGraderDecks" | "listWorkspaceScenarioDecks" | "readWorkspaceAssistantDeck">;
+type WorkspaceDeckGraphqlDeps = {
+    activateWorkspaceDeck: (workspaceId?: string | null, options?: {
+        forceReload?: boolean;
+        source?: string;
+        reloadAttemptId?: string;
+    }) => Promise<void>;
+    readWorkspaceDeckStateStrict: (workspaceId: string) => WorkspaceDeckState;
+    getResolvedDeckPath: () => string;
+    summarizeWorkspaceDeckState: (workspaceId?: string | null) => Record<string, unknown>;
+    logWorkspaceRefreshDebug: (event: string, payload: Record<string, unknown>) => void;
+};
+export declare const createWorkspaceDeckGraphqlOperations: (deps: WorkspaceDeckGraphqlDeps) => WorkspaceDeckGraphqlOperations;
+export {};
+//# sourceMappingURL=server_workspace_graphql.d.ts.map

package/script/src/server_workspace_graphql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_workspace_graphql.d.ts","sourceRoot":"","sources":["../../src/src/server_workspace_graphql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,KAAK,8BAA8B,GAAG,IAAI,CACxC,0BAA0B,EACxB,0BAA0B,GAC1B,4BAA4B,GAC5B,4BAA4B,CAC/B,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,qBAAqB,EAAE,CACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,KACE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,4BAA4B,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC1E,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAClC,2BAA2B,EAAE,CAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,KACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,wBAAwB,EAAE,CACxB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,IAAI,CAAC;CACX,CAAC;AAEF,eAAO,MAAM,oCAAoC,GAC/C,MAAM,wBAAwB,KAC7B,8BAmDD,CAAC"}

package/script/src/server_workspace_graphql.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkspaceDeckGraphqlOperations = void 0;
+const createWorkspaceDeckGraphqlOperations = (deps) => ({
+    listWorkspaceGraderDecks: async (workspaceId) => {
+        await deps.activateWorkspaceDeck(workspaceId, {
+            source: "graphql:listWorkspaceGraderDecks",
+        });
+        const deckState = deps.readWorkspaceDeckStateStrict(workspaceId);
+        return deckState.graderDecks.map((deck) => ({
+            id: deck.id,
+            label: deck.label,
+            description: deck.description,
+            path: deck.path,
+        }));
+    },
+    listWorkspaceScenarioDecks: async (workspaceId) => {
+        deps.logWorkspaceRefreshDebug("graphql.scenarioDecks.list.begin", {
+            workspaceId,
+            resolvedDeckPath: deps.getResolvedDeckPath(),
+            ...deps.summarizeWorkspaceDeckState(workspaceId),
+        });
+        await deps.activateWorkspaceDeck(workspaceId, {
+            source: "graphql:listWorkspaceScenarioDecks",
+        });
+        deps.logWorkspaceRefreshDebug("graphql.scenarioDecks.list.afterActivate", {
+            workspaceId,
+            resolvedDeckPath: deps.getResolvedDeckPath(),
+            ...deps.summarizeWorkspaceDeckState(workspaceId),
+        });
+        const deckState = deps.readWorkspaceDeckStateStrict(workspaceId);
+        const result = deckState.scenarioDecks.map((deck) => ({
+            id: deck.id,
+            label: deck.label,
+            description: deck.description,
+            path: deck.path,
+            maxTurns: deck.maxTurns,
+            inputSchema: deck.inputSchema,
+            defaults: deck.defaults,
+            inputSchemaError: deck.inputSchemaError,
+        }));
+        deps.logWorkspaceRefreshDebug("graphql.scenarioDecks.list.return", {
+            workspaceId,
+            returnedDeckCount: result.length,
+            returnedDeckPaths: result.slice(0, 12).map((deck) => deck.path),
+        });
+        return result;
+    },
+    readWorkspaceAssistantDeck: async (workspaceId) => {
+        await deps.activateWorkspaceDeck(workspaceId, {
+            source: "graphql:readWorkspaceAssistantDeck",
+        });
+        return deps.readWorkspaceDeckStateStrict(workspaceId).assistantDeck;
+    },
+});
+exports.createWorkspaceDeckGraphqlOperations = createWorkspaceDeckGraphqlOperations;

package/script/src/server_workspace_runtime.d.ts

@@ -0,0 +1,55 @@
+import type { LoadedDeck, SavedState } from "@bolt-foundry/gambit-core";
+import type { WorkspaceDeckState } from "./server_types.js";
+export type WorkspaceRecord = {
+    id: string;
+    rootDir: string;
+    rootDeckPath: string;
+    createdAt: string;
+};
+type WorkspaceRuntimeDeps = {
+    verbose: boolean;
+    logger: {
+        info?: (...args: Array<unknown>) => void;
+        warn: (...args: Array<unknown>) => void;
+    };
+    randomId: (prefix: string) => string;
+    resolveDeckPath: (deckPath: string) => string;
+    readSessionState: (workspaceId: string) => SavedState | undefined;
+    readWorkspaceDeckState: (workspaceId: string) => WorkspaceDeckState | null;
+    writeWorkspaceDeckState: (state: WorkspaceDeckState) => Promise<WorkspaceDeckState>;
+    buildWorkspaceDeckStateFromLoadedDeck: (args: {
+        workspaceId: string;
+        deck: LoadedDeck;
+    }) => Promise<WorkspaceDeckState>;
+    reloadPrimaryDeck: () => void;
+    getDeckLoadPromise: () => Promise<LoadedDeck | null>;
+    getResolvedDeckPath: () => string;
+    setResolvedDeckPath: (deckPath: string) => void;
+    clearDefaultBuildBotRoot: () => void;
+    logWorkspaceRefreshDebug: (event: string, payload: Record<string, unknown>) => void;
+    extractMissingReadfilePath: (message: string) => string | null;
+    emitWorkspaceGraphRefresh: (args: {
+        workspaceId: string;
+        reason: "fs-change";
+        paths: Array<string>;
+        kinds: Array<string>;
+    }) => void;
+};
+export declare const createWorkspaceRuntime: (deps: WorkspaceRuntimeDeps) => {
+    activateWorkspaceDeck: (workspaceId?: string | null, options?: {
+        forceReload?: boolean;
+        source?: string;
+        reloadAttemptId?: string;
+    }) => Promise<void>;
+    registerWorkspace: (record: WorkspaceRecord) => WorkspaceRecord;
+    removeWorkspace: (workspaceId: string) => void;
+    resolveWorkspaceRecord: (workspaceId?: string | null) => WorkspaceRecord | null;
+    stopAllWorkspaceFsWatchers: () => void;
+    summarizeWorkspaceDeckState: (workspaceId?: string | null) => {
+        scenarioDeckCount: number;
+        scenarioDeckPaths: string[];
+        graderDeckCount: number;
+    };
+};
+export {};
+//# sourceMappingURL=server_workspace_runtime.d.ts.map

package/script/src/server_workspace_runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_workspace_runtime.d.ts","sourceRoot":"","sources":["../../src/src/server_workspace_runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAExE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAUF,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;QACzC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;KACzC,CAAC;IACF,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAClE,sBAAsB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,CAAC;IAC3E,uBAAuB,EAAE,CACvB,KAAK,EAAE,kBAAkB,KACtB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC,qCAAqC,EAAE,CAAC,IAAI,EAAE;QAC5C,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,UAAU,CAAC;KAClB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,kBAAkB,EAAE,MAAM,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACrD,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAClC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,wBAAwB,EAAE,MAAM,IAAI,CAAC;IACrC,wBAAwB,EAAE,CACxB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,IAAI,CAAC;IACV,0BAA0B,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC/D,yBAAyB,EAAE,CAAC,IAAI,EAAE;QAChC,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,WAAW,CAAC;QACpB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;KACtB,KAAK,IAAI,CAAC;CACZ,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAM,oBAAoB;0CAyS/C,MAAM,GAAG,IAAI,YACjB;QACR,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;gCAjDgC,eAAe,KAAG,eAAe;mCAsH9B,MAAM;2CA/G5B,MAAM,GAAG,IAAI,KAC1B,eAAe,GAAG,IAAI;;gDArO0B,MAAM,GAAG,IAAI;;;;;CAsWjE,CAAC"}

package/script/src/server_workspace_runtime.js

@@ -0,0 +1,395 @@
+"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.createWorkspaceRuntime = void 0;
+const dntShim = __importStar(require("../_dnt.shims.js"));
+const path = __importStar(require("../deps/jsr.io/@std/path/1.1.4/mod.js"));
+const server_workspace_decks_js_1 = require("./server_workspace_decks.js");
+const createWorkspaceRuntime = (deps) => {
+    const workspaceById = new Map();
+    const workspaceFsWatchers = new Map();
+    const normalizeWorkspaceFsPath = (value) => value.split(/\\|\//g).filter(Boolean).join("/");
+    const isInternalWorkspacePath = (value) => {
+        const normalized = normalizeWorkspaceFsPath(value);
+        return normalized === ".gambit" || normalized.startsWith(".gambit/");
+    };
+    const isWorkspaceGraphRelevantPath = (value) => {
+        const normalized = normalizeWorkspaceFsPath(value);
+        if (normalized.length === 0)
+            return false;
+        if (isInternalWorkspacePath(normalized))
+            return false;
+        return true;
+    };
+    const toWorkspaceRelativePath = (rootDir, absoluteOrRelativePath) => {
+        const resolvedRoot = path.resolve(rootDir);
+        const resolvedCandidate = path.resolve(absoluteOrRelativePath);
+        const relative = normalizeWorkspaceFsPath(path.relative(resolvedRoot, resolvedCandidate));
+        if (!relative || relative.startsWith(".."))
+            return null;
+        return relative;
+    };
+    const summarizeWorkspaceDeckState = (workspaceId) => (0, server_workspace_decks_js_1.summarizeDeckState)(workspaceId ? deps.readWorkspaceDeckState(workspaceId) : null);
+    const buildDeckSourcePaths = (deckState) => {
+        const candidates = [
+            deckState.rootDeckPath,
+            deckState.assistantDeck.deck,
+            ...deckState.scenarioDecks.map((deck) => deck.path),
+            ...deckState.graderDecks.map((deck) => deck.path),
+        ];
+        const resolved = new Set();
+        for (const candidate of candidates) {
+            const trimmed = candidate.trim();
+            if (!trimmed)
+                continue;
+            resolved.add(path.resolve(trimmed));
+        }
+        return [...resolved];
+    };
+    const isWorkspaceDeckStateStale = async (args) => {
+        const expectedRootDeckPath = path.resolve(args.nextPath);
+        const persistedRootDeckPath = path.resolve(args.deckState.rootDeckPath);
+        if (persistedRootDeckPath !== expectedRootDeckPath) {
+            return { stale: true, reason: "root-deck-path-changed" };
+        }
+        const updatedAtMs = Date.parse(args.deckState.updatedAt);
+        if (!Number.isFinite(updatedAtMs)) {
+            return { stale: true, reason: "invalid-updated-at" };
+        }
+        for (const sourcePath of buildDeckSourcePaths(args.deckState)) {
+            try {
+                const info = await dntShim.Deno.stat(sourcePath);
+                if (!info.isFile) {
+                    return { stale: true, reason: "deck-source-not-file" };
+                }
+                const mtimeMs = info.mtime?.getTime();
+                if (typeof mtimeMs === "number" && mtimeMs > updatedAtMs) {
+                    return { stale: true, reason: "deck-source-newer-than-state" };
+                }
+            }
+            catch (error) {
+                if (error instanceof dntShim.Deno.errors.NotFound) {
+                    return { stale: true, reason: "deck-source-missing" };
+                }
+                return { stale: true, reason: "deck-source-stat-failed" };
+            }
+        }
+        return { stale: false, reason: null };
+    };
+    const flushWorkspaceFsWatcher = (workspaceId) => {
+        const watcher = workspaceFsWatchers.get(workspaceId);
+        if (!watcher || watcher.pendingPaths.size === 0)
+            return;
+        const changedPaths = [...watcher.pendingPaths].sort();
+        const kinds = [...watcher.pendingKinds].sort();
+        deps.logWorkspaceRefreshDebug("fs.flush", {
+            workspaceId,
+            kinds,
+            paths: changedPaths,
+            pathCount: changedPaths.length,
+        });
+        watcher.pendingPaths.clear();
+        watcher.pendingKinds.clear();
+        watcher.debounceTimer = null;
+        if (deps.verbose) {
+            deps.logger.info?.(`[sim] workspace fs change detected workspaceId=${workspaceId} kinds=${kinds.join(",")} paths=${changedPaths.join(",")}`);
+        }
+        const reloadAttemptId = deps.randomId("wsrefresh");
+        deps.logWorkspaceRefreshDebug("fs.reload.start", {
+            workspaceId,
+            reloadAttemptId,
+            changedPaths,
+            kinds,
+            resolvedDeckPath: deps.getResolvedDeckPath(),
+            ...summarizeWorkspaceDeckState(workspaceId),
+        });
+        void activateWorkspaceDeck(workspaceId, {
+            forceReload: true,
+            source: "fs-watcher",
+            reloadAttemptId,
+        })
+            .then(() => {
+            deps.logWorkspaceRefreshDebug("fs.reload.success", {
+                workspaceId,
+                reloadAttemptId,
+                changedPaths,
+                kinds,
+                resolvedDeckPath: deps.getResolvedDeckPath(),
+                ...summarizeWorkspaceDeckState(workspaceId),
+            });
+            deps.emitWorkspaceGraphRefresh({
+                workspaceId,
+                reason: "fs-change",
+                paths: changedPaths,
+                kinds,
+            });
+            deps.logWorkspaceRefreshDebug("fs.graphRefresh.emit", {
+                workspaceId,
+                reloadAttemptId,
+                reason: "fs-change",
+                pathCount: changedPaths.length,
+                kindCount: kinds.length,
+            });
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.logWorkspaceRefreshDebug("fs.reload.fail", {
+                workspaceId,
+                reloadAttemptId,
+                resolvedDeckPath: deps.getResolvedDeckPath(),
+                error: message,
+                missingPath: deps.extractMissingReadfilePath(message),
+                ...summarizeWorkspaceDeckState(workspaceId),
+            });
+            deps.logger.warn(`[sim] workspace deck reload failed after fs change workspaceId=${workspaceId} error=${message}`);
+        });
+    };
+    const stopWorkspaceFsWatcher = (workspaceId) => {
+        const watcher = workspaceFsWatchers.get(workspaceId);
+        if (!watcher)
+            return;
+        deps.logWorkspaceRefreshDebug("fs.stop", { workspaceId });
+        if (watcher.debounceTimer !== null) {
+            clearTimeout(watcher.debounceTimer);
+            watcher.debounceTimer = null;
+        }
+        watcher.abortController.abort();
+        workspaceFsWatchers.delete(workspaceId);
+    };
+    const startWorkspaceFsWatcher = (record) => {
+        if (workspaceFsWatchers.has(record.id))
+            return;
+        deps.logWorkspaceRefreshDebug("fs.start", {
+            workspaceId: record.id,
+            rootDir: record.rootDir,
+        });
+        const abortController = new AbortController();
+        const pendingPaths = new Set();
+        const pendingKinds = new Set();
+        let debounceTimer = null;
+        const watcher = dntShim.Deno.watchFs(record.rootDir, { recursive: true });
+        abortController.signal.addEventListener("abort", () => {
+            try {
+                watcher.close();
+            }
+            catch {
+                // ignore close errors while shutting down
+            }
+        });
+        const task = (async () => {
+            try {
+                for await (const event of watcher) {
+                    if (abortController.signal.aborted)
+                        break;
+                    const kind = typeof event.kind === "string" ? event.kind : "unknown";
+                    let sawRelevantPath = false;
+                    for (const candidatePath of event.paths) {
+                        const relativePath = toWorkspaceRelativePath(record.rootDir, candidatePath);
+                        if (!relativePath || !isWorkspaceGraphRelevantPath(relativePath)) {
+                            continue;
+                        }
+                        pendingPaths.add(relativePath);
+                        sawRelevantPath = true;
+                    }
+                    if (!sawRelevantPath)
+                        continue;
+                    pendingKinds.add(kind);
+                    if (debounceTimer !== null)
+                        continue;
+                    debounceTimer = setTimeout(() => {
+                        const existing = workspaceFsWatchers.get(record.id);
+                        if (!existing)
+                            return;
+                        existing.debounceTimer = null;
+                        flushWorkspaceFsWatcher(record.id);
+                    }, 120);
+                    const existing = workspaceFsWatchers.get(record.id);
+                    if (existing) {
+                        existing.debounceTimer = debounceTimer;
+                    }
+                }
+            }
+            catch (error) {
+                if (!abortController.signal.aborted) {
+                    deps.logger.warn(`[sim] workspace fs watcher stopped for ${record.id}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            finally {
+                if (abortController.signal.aborted) {
+                    const existing = workspaceFsWatchers.get(record.id);
+                    if (existing && existing.debounceTimer !== null) {
+                        clearTimeout(existing.debounceTimer);
+                        existing.debounceTimer = null;
+                    }
+                }
+            }
+        })();
+        workspaceFsWatchers.set(record.id, {
+            abortController,
+            pendingPaths,
+            pendingKinds,
+            debounceTimer,
+            task,
+        });
+    };
+    const registerWorkspace = (record) => {
+        workspaceById.set(record.id, record);
+        startWorkspaceFsWatcher(record);
+        return record;
+    };
+    const resolveWorkspaceRecord = (workspaceId) => {
+        if (!workspaceId)
+            return null;
+        const cached = workspaceById.get(workspaceId);
+        if (cached)
+            return cached;
+        const state = deps.readSessionState(workspaceId);
+        const meta = state?.meta ?? {};
+        const deckPath = typeof meta
+            .workspaceRootDeckPath === "string"
+            ? meta.workspaceRootDeckPath
+            : typeof meta.deck === "string"
+                ? meta.deck
+                : undefined;
+        const rootDir = typeof meta.workspaceRootDir ===
+            "string"
+            ? meta.workspaceRootDir
+            : deckPath
+                ? path.dirname(deckPath)
+                : undefined;
+        if (!deckPath || !rootDir)
+            return null;
+        const createdAt = typeof meta.workspaceCreatedAt ===
+            "string"
+            ? meta.workspaceCreatedAt
+            : typeof meta.sessionCreatedAt === "string"
+                ? meta.sessionCreatedAt
+                : new Date().toISOString();
+        return registerWorkspace({
+            id: workspaceId,
+            rootDir,
+            rootDeckPath: deckPath,
+            createdAt,
+        });
+    };
+    const activateWorkspaceDeck = async (workspaceId, options) => {
+        if (!workspaceId)
+            return;
+        const record = resolveWorkspaceRecord(workspaceId);
+        if (!record)
+            return;
+        const existingDeckState = deps.readWorkspaceDeckState(workspaceId);
+        const source = options?.source ?? "unspecified";
+        const reloadAttemptId = options?.reloadAttemptId ?? null;
+        const nextPath = deps.resolveDeckPath(record.rootDeckPath);
+        const resolvedDeckPath = deps.getResolvedDeckPath();
+        const shouldSwitch = nextPath !== resolvedDeckPath;
+        deps.logWorkspaceRefreshDebug("deck.activate.begin", {
+            workspaceId,
+            source,
+            reloadAttemptId,
+            forceReload: Boolean(options?.forceReload),
+            nextPath,
+            resolvedDeckPath,
+            ...(0, server_workspace_decks_js_1.summarizeDeckState)(existingDeckState),
+        });
+        if (shouldSwitch) {
+            deps.setResolvedDeckPath(nextPath);
+            deps.clearDefaultBuildBotRoot();
+        }
+        else if (!options?.forceReload && existingDeckState) {
+            const freshness = await isWorkspaceDeckStateStale({
+                deckState: existingDeckState,
+                nextPath,
+            });
+            if (!freshness.stale) {
+                deps.logWorkspaceRefreshDebug("deck.activate.skip", {
+                    workspaceId,
+                    source,
+                    reloadAttemptId,
+                    reason: "already-active-and-fresh",
+                    resolvedDeckPath,
+                    ...(0, server_workspace_decks_js_1.summarizeDeckState)(existingDeckState),
+                });
+                return;
+            }
+            deps.logWorkspaceRefreshDebug("deck.activate.reload", {
+                workspaceId,
+                source,
+                reloadAttemptId,
+                reason: freshness.reason ?? "deck-state-stale",
+                resolvedDeckPath,
+                ...(0, server_workspace_decks_js_1.summarizeDeckState)(existingDeckState),
+            });
+        }
+        deps.reloadPrimaryDeck();
+        const loadedDeck = await deps.getDeckLoadPromise().catch(() => null);
+        let nextDeckState = existingDeckState;
+        if (loadedDeck) {
+            nextDeckState = await deps.buildWorkspaceDeckStateFromLoadedDeck({
+                workspaceId,
+                deck: loadedDeck,
+            });
+            await deps.writeWorkspaceDeckState(nextDeckState);
+        }
+        deps.logWorkspaceRefreshDebug("deck.activate.done", {
+            workspaceId,
+            source,
+            reloadAttemptId,
+            loaded: Boolean(loadedDeck),
+            loadedDeckPath: loadedDeck?.path ?? null,
+            resolvedDeckPath: deps.getResolvedDeckPath(),
+            ...(0, server_workspace_decks_js_1.summarizeDeckState)(nextDeckState),
+        });
+    };
+    const removeWorkspace = (workspaceId) => {
+        stopWorkspaceFsWatcher(workspaceId);
+        workspaceById.delete(workspaceId);
+    };
+    const stopAllWorkspaceFsWatchers = () => {
+        for (const workspaceId of workspaceFsWatchers.keys()) {
+            stopWorkspaceFsWatcher(workspaceId);
+        }
+    };
+    return {
+        activateWorkspaceDeck,
+        registerWorkspace,
+        removeWorkspace,
+        resolveWorkspaceRecord,
+        stopAllWorkspaceFsWatchers,
+        summarizeWorkspaceDeckState,
+    };
+};
+exports.createWorkspaceRuntime = createWorkspaceRuntime;