@sapiom/harness 0.0.0 → 0.1.1

package/dist/core/workflow-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Workflow registry (workstream W2's backend slice).
+ *
+ * Discovers orchestration projects by scanning a directory tree (bounded
+ * depth) for `sapiom.json` marker files, tracks manually-connected paths,
+ * and persists the combined list to HARNESS_PATHS.workflows. Exposes an
+ * Express router implementing the /api/workflows surface from
+ * src/shared/types.ts; the integrator mounts it (and express.json()) on the
+ * shared app.
+ */
+import { type Router as ExpressRouter } from "express";
+import { type WorkflowInfo } from "../shared/types.js";
+export declare class WorkflowRegistry {
+    private readonly registryPath;
+    private workflows;
+    private loaded;
+    constructor(registryPath?: string);
+    private ensureLoaded;
+    private persist;
+    list(): Promise<WorkflowInfo[]>;
+    /**
+     * Drops entries whose `path` no longer exists on disk and persists the
+     * result — users delete projects, and a crashed run can leave a temp
+     * directory registered. Deliberately narrow: only a confirmed-missing
+     * path (ENOENT/ENOTDIR) is pruned. A directory that exists but is
+     * merely unbuilt, unreadable (permissions), or temporarily unstattable
+     * stays registered. Returns what was pruned so the caller can log it.
+     */
+    prune(): Promise<WorkflowInfo[]>;
+    /** Scans `root` and merges discovered projects into the persisted registry. */
+    scan(root: string): Promise<WorkflowInfo[]>;
+    /** Registers an arbitrary path (the "+ Connect" flow); marker is optional at connect time. */
+    connectPath(inputPath: string): Promise<WorkflowInfo>;
+}
+export declare function createWorkflowsRouter(registry: WorkflowRegistry): ExpressRouter;
+//# sourceMappingURL=workflow-registry.d.ts.map

package/dist/core/workflow-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-registry.d.ts","sourceRoot":"","sources":["../../src/core/workflow-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAU,KAAK,MAAM,IAAI,aAAa,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAmFtE,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,YAAY;IAHzC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,MAAM,CAAS;gBAEM,YAAY,GAAE,MAA4C;YAEzE,YAAY;YAWZ,OAAO;IAKf,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAKrC;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAqBtC,+EAA+E;IACzE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBjD,8FAA8F;IACxF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAgB5D;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAkC/E"}

package/dist/core/workflow-registry.js

@@ -0,0 +1,220 @@
+/**
+ * Workflow registry (workstream W2's backend slice).
+ *
+ * Discovers orchestration projects by scanning a directory tree (bounded
+ * depth) for `sapiom.json` marker files, tracks manually-connected paths,
+ * and persists the combined list to HARNESS_PATHS.workflows. Exposes an
+ * Express router implementing the /api/workflows surface from
+ * src/shared/types.ts; the integrator mounts it (and express.json()) on the
+ * shared app.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Router } from "express";
+import { HARNESS_PATHS } from "../shared/types.js";
+import { hasTraversalSegment, resolveWithinRoot } from "./path-safety.js";
+const MAX_SCAN_DEPTH = 3;
+const SKIP_DIR_NAMES = new Set(["node_modules", ".git"]);
+function expandHome(inputPath) {
+    if (inputPath === "~")
+        return os.homedir();
+    if (inputPath.startsWith("~/"))
+        return path.join(os.homedir(), inputPath.slice(2));
+    return inputPath;
+}
+// `dir` reaching these sinks is always a resolved absolute path (from
+// path.resolve in scan/connectPath, or a confined descent in scanDir), so a
+// `..` segment can never survive. Asserting it anyway keeps the no-traversal
+// guarantee explicit and local to each fs read, and covers the arbitrary
+// path connectPath accepts (which has no scan root to confine it to).
+async function readMarker(dir) {
+    if (hasTraversalSegment(dir))
+        return null;
+    try {
+        const raw = await fs.readFile(path.join(dir, "sapiom.json"), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function nameFor(dir) {
+    if (hasTraversalSegment(dir))
+        return path.basename(dir);
+    try {
+        const raw = await fs.readFile(path.join(dir, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg.name)
+            return pkg.name;
+    }
+    catch {
+        // No package.json (or it doesn't parse) — fall back to the directory name.
+    }
+    return path.basename(dir);
+}
+/**
+ * Depth-first scan; a directory carrying a marker is registered and not
+ * descended into. Every directory touched is confined to `root` (the tree the
+ * caller asked to scan): the initial call is `root` itself, and recursion only
+ * ever descends into a direct child, so no crafted entry name can walk the
+ * scan outside `root`. Symlinked entries report `isDirectory() === false`
+ * (withFileTypes uses raw dirent info, not a followed stat) and so are never
+ * descended into either.
+ */
+async function scanDir(root, dir, depth, found) {
+    if (depth > MAX_SCAN_DEPTH)
+        return;
+    const safeDir = resolveWithinRoot(root, dir);
+    if (!safeDir)
+        return;
+    const marker = await readMarker(safeDir);
+    if (marker) {
+        found.push({
+            name: await nameFor(safeDir),
+            path: safeDir,
+            definitionId: marker.definitionId ?? null,
+            source: "scan",
+        });
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(safeDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || SKIP_DIR_NAMES.has(entry.name))
+            continue;
+        await scanDir(root, path.join(safeDir, entry.name), depth + 1, found);
+    }
+}
+export class WorkflowRegistry {
+    constructor(registryPath = expandHome(HARNESS_PATHS.workflows)) {
+        this.registryPath = registryPath;
+        this.workflows = [];
+        this.loaded = false;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        try {
+            const raw = await fs.readFile(this.registryPath, "utf8");
+            this.workflows = JSON.parse(raw);
+        }
+        catch {
+            this.workflows = [];
+        }
+        this.loaded = true;
+    }
+    async persist() {
+        await fs.mkdir(path.dirname(this.registryPath), { recursive: true });
+        await fs.writeFile(this.registryPath, JSON.stringify(this.workflows, null, 2));
+    }
+    async list() {
+        await this.ensureLoaded();
+        return this.workflows;
+    }
+    /**
+     * Drops entries whose `path` no longer exists on disk and persists the
+     * result — users delete projects, and a crashed run can leave a temp
+     * directory registered. Deliberately narrow: only a confirmed-missing
+     * path (ENOENT/ENOTDIR) is pruned. A directory that exists but is
+     * merely unbuilt, unreadable (permissions), or temporarily unstattable
+     * stays registered. Returns what was pruned so the caller can log it.
+     */
+    async prune() {
+        await this.ensureLoaded();
+        const kept = [];
+        const pruned = [];
+        for (const workflow of this.workflows) {
+            try {
+                await fs.stat(workflow.path);
+                kept.push(workflow);
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === "ENOENT" || code === "ENOTDIR")
+                    pruned.push(workflow);
+                else
+                    kept.push(workflow);
+            }
+        }
+        if (pruned.length > 0) {
+            this.workflows = kept;
+            await this.persist();
+        }
+        return pruned;
+    }
+    /** Scans `root` and merges discovered projects into the persisted registry. */
+    async scan(root) {
+        await this.ensureLoaded();
+        const absoluteRoot = path.resolve(expandHome(root));
+        const found = [];
+        await scanDir(absoluteRoot, absoluteRoot, 0, found);
+        const byPath = new Map(this.workflows.map((workflow) => [workflow.path, workflow]));
+        for (const workflow of found) {
+            const existing = byPath.get(workflow.path);
+            // A manually-connected entry keeps its `source`; a scan only refreshes name/definitionId.
+            byPath.set(workflow.path, existing ? { ...existing, ...workflow, source: existing.source } : workflow);
+        }
+        this.workflows = Array.from(byPath.values());
+        await this.persist();
+        return found;
+    }
+    /** Registers an arbitrary path (the "+ Connect" flow); marker is optional at connect time. */
+    async connectPath(inputPath) {
+        await this.ensureLoaded();
+        const absolutePath = path.resolve(expandHome(inputPath));
+        const marker = await readMarker(absolutePath);
+        const info = {
+            name: await nameFor(absolutePath),
+            path: absolutePath,
+            definitionId: marker?.definitionId ?? null,
+            source: "connect",
+        };
+        const idx = this.workflows.findIndex((workflow) => workflow.path === absolutePath);
+        if (idx >= 0)
+            this.workflows[idx] = info;
+        else
+            this.workflows.push(info);
+        await this.persist();
+        return info;
+    }
+}
+export function createWorkflowsRouter(registry) {
+    const router = Router();
+    router.get("/api/workflows", async (_req, res) => {
+        res.json(await registry.list());
+    });
+    router.post("/api/workflows/connect", async (req, res) => {
+        const inputPath = req.body?.path;
+        if (typeof inputPath !== "string" || !inputPath.trim()) {
+            res.status(400).json({ error: "path is required" });
+            return;
+        }
+        try {
+            res.json(await registry.connectPath(inputPath));
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post("/api/workflows/scan", async (req, res) => {
+        const root = req.body?.root;
+        if (typeof root !== "string" || !root.trim()) {
+            res.status(400).json({ error: "root is required" });
+            return;
+        }
+        try {
+            res.json(await registry.scan(root));
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=workflow-registry.js.map

package/dist/core/workflow-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-registry.js","sourceRoot":"","sources":["../../src/core/workflow-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/workspace-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Writes HARNESS_CONTEXT_FILE (`.sapiom/harness-context.json`) in a
+ * session's cwd — the agent-legible mirror of this workspace's UI state:
+ * which workflow (if any) the session is bound to, every workflow the
+ * registry currently knows about, and the session's own identity. Called
+ * unconditionally from `SessionManager.create()` so the file exists for
+ * every session regardless of entry point (REST, `autoCreateSession`), as a
+ * backfill from `SessionManager.resume()` when it's missing entirely, on
+ * every `PATCH /api/sessions/:id/workflow`, and whenever the workflow
+ * registry changes (scan/connect) — see server/index.ts's
+ * `writeSessionContext`/`scanWorkflowsAndBroadcast` for how those call
+ * sites are wired, and both of which can legitimately fire concurrent
+ * writes to the *same* destination (a scan's rewrite-all-open-sessions step
+ * racing a user's live bind click, for instance) — see `withPerPathQueue`.
+ * Unbinding writes `boundWorkflow: null` rather than deleting the file, so a
+ * concurrent read from the agent never races a momentary ENOENT.
+ */
+import { type HarnessKind, type WorkflowInfo } from "../shared/types.js";
+export interface WorkspaceContextSession {
+    id: string;
+    cwd: string;
+    harness: HarnessKind;
+}
+/**
+ * Atomically writes `<session.cwd>/.sapiom/harness-context.json`.
+ * Best-effort: a session's cwd could in principle be unwritable
+ * (permissions, deleted out from under the session) — that must never fail
+ * the caller that triggered it, so errors are logged, not thrown.
+ *
+ * `workflows` is sorted by path before writing (deterministic, independent
+ * of registry scan/insertion order) so an agent re-reading the file across
+ * turns can diff it cheaply instead of re-parsing a reordered blob every
+ * time.
+ */
+export declare function writeHarnessContext(session: WorkspaceContextSession, boundWorkflow: WorkflowInfo | null, workflows: WorkflowInfo[]): Promise<void>;
+/**
+ * True if `<cwd>/.sapiom/harness-context.json` already exists. Used by
+ * `SessionManager.resume()` to decide whether a backfill write is needed —
+ * resume must never clobber a file that could already reflect a real
+ * binding.
+ */
+export declare function harnessContextFileExists(cwd: string): Promise<boolean>;
+//# sourceMappingURL=workspace-context.d.ts.map

package/dist/core/workspace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-context.d.ts","sourceRoot":"","sources":["../../src/core/workspace-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EAEL,KAAK,WAAW,EAGhB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAM5B,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;CACtB;AAiCD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,uBAAuB,EAChC,aAAa,EAAE,YAAY,GAAG,IAAI,EAClC,SAAS,EAAE,YAAY,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO5E"}

package/dist/core/workspace-context.js

@@ -0,0 +1,108 @@
+/**
+ * Writes HARNESS_CONTEXT_FILE (`.sapiom/harness-context.json`) in a
+ * session's cwd — the agent-legible mirror of this workspace's UI state:
+ * which workflow (if any) the session is bound to, every workflow the
+ * registry currently knows about, and the session's own identity. Called
+ * unconditionally from `SessionManager.create()` so the file exists for
+ * every session regardless of entry point (REST, `autoCreateSession`), as a
+ * backfill from `SessionManager.resume()` when it's missing entirely, on
+ * every `PATCH /api/sessions/:id/workflow`, and whenever the workflow
+ * registry changes (scan/connect) — see server/index.ts's
+ * `writeSessionContext`/`scanWorkflowsAndBroadcast` for how those call
+ * sites are wired, and both of which can legitimately fire concurrent
+ * writes to the *same* destination (a scan's rewrite-all-open-sessions step
+ * racing a user's live bind click, for instance) — see `withPerPathQueue`.
+ * Unbinding writes `boundWorkflow: null` rather than deleting the file, so a
+ * concurrent read from the agent never races a momentary ENOENT.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { HARNESS_CONTEXT_FILE, } from "../shared/types.js";
+function toContextWorkflowEntry(workflow) {
+    return { name: workflow.name, path: workflow.path, definitionId: workflow.definitionId };
+}
+/**
+ * Serializes writes per destination path. Two independent triggers can
+ * legitimately race on the same `harness-context.json` (a workflow scan's
+ * rewrite-all-open-sessions step, a bind/unbind, a fresh session's initial
+ * write) — without this, concurrent writers could both compute the same
+ * `Date.now()`-based tmp filename (confirmed via repro: a tight burst of
+ * concurrent writes to one destination reliably collides within the same
+ * millisecond) and steal each other's tmp file out from under a pending
+ * `rename`, which fails with ENOENT. Serializing per path also fixes a
+ * subtler issue beyond the crash: without it, whichever concurrent write's
+ * disk I/O happens to finish first wins, which can silently apply writes
+ * out of the order they were actually triggered in. Keyed by absolute
+ * path; an entry is removed once nothing else has chained onto it, so this
+ * never grows unbounded over a long-running server's lifetime.
+ */
+const writeQueues = new Map();
+async function withPerPathQueue(filePath, task) {
+    const previous = writeQueues.get(filePath) ?? Promise.resolve();
+    // `task` never throws (its own try/catch logs and swallows) — chaining
+    // onto both branches of `previous` is defense in depth, so one write's
+    // failure can never wedge the queue for the next one to this same path.
+    const current = previous.then(task, task);
+    writeQueues.set(filePath, current);
+    try {
+        await current;
+    }
+    finally {
+        if (writeQueues.get(filePath) === current)
+            writeQueues.delete(filePath);
+    }
+}
+/**
+ * Atomically writes `<session.cwd>/.sapiom/harness-context.json`.
+ * Best-effort: a session's cwd could in principle be unwritable
+ * (permissions, deleted out from under the session) — that must never fail
+ * the caller that triggered it, so errors are logged, not thrown.
+ *
+ * `workflows` is sorted by path before writing (deterministic, independent
+ * of registry scan/insertion order) so an agent re-reading the file across
+ * turns can diff it cheaply instead of re-parsing a reordered blob every
+ * time.
+ */
+export async function writeHarnessContext(session, boundWorkflow, workflows) {
+    const filePath = path.join(session.cwd, HARNESS_CONTEXT_FILE);
+    const sortedWorkflows = [...workflows].sort((a, b) => a.path.localeCompare(b.path)).map(toContextWorkflowEntry);
+    const context = {
+        boundWorkflow: boundWorkflow ? toContextWorkflowEntry(boundWorkflow) : null,
+        workflows: sortedWorkflows,
+        session: { id: session.id, cwd: session.cwd, harness: session.harness },
+        updatedAt: new Date().toISOString(),
+    };
+    await withPerPathQueue(filePath, async () => {
+        try {
+            const dir = path.dirname(filePath);
+            await fs.mkdir(dir, { recursive: true });
+            // A random suffix, not just pid+Date.now(): millisecond resolution is
+            // not fine enough to stay unique across a burst of concurrent writes
+            // to the same destination (confirmed via repro). Collision-proof
+            // regardless of timing, independent of the queue above.
+            const tmpPath = path.join(dir, `.harness-context.json.tmp-${process.pid}-${crypto.randomUUID()}`);
+            await fs.writeFile(tmpPath, JSON.stringify(context, null, 2) + "\n", "utf8");
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (err) {
+            console.error(`[harness] failed to write ${filePath}:`, err);
+        }
+    });
+}
+/**
+ * True if `<cwd>/.sapiom/harness-context.json` already exists. Used by
+ * `SessionManager.resume()` to decide whether a backfill write is needed —
+ * resume must never clobber a file that could already reflect a real
+ * binding.
+ */
+export async function harnessContextFileExists(cwd) {
+    try {
+        await fs.access(path.join(cwd, HARNESS_CONTEXT_FILE));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=workspace-context.js.map

package/dist/core/workspace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-context.js","sourceRoot":"","sources":["../../src/core/workspace-context.ts"],"names":[],"mappings":"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"}

package/dist/core/workspace-watcher.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fingerprint of the set of workflow-marker directories under `root` (sorted,
+ * bounded depth, ignored subtrees skipped). Changes exactly when a workflow is
+ * added, removed, or renamed — not when unrelated files are edited. Exported
+ * for the polling fallback and for direct testing.
+ */
+export declare function snapshotWorkspaceWorkflows(root: string): string;
+export interface WorkspaceWatcherManagerDeps {
+    /** Debounced per-session notification that the workspace's workflow set may
+     *  have changed — the integrator re-scans that session's cwd and broadcasts
+     *  `workflows.changed` if the list actually changed. */
+    onChange(harnessSessionId: string): void;
+}
+/** Registry of one SessionWorkspaceWatcher per active harness session. */
+export declare class WorkspaceWatcherManager {
+    private readonly deps;
+    private readonly watchers;
+    constructor(deps: WorkspaceWatcherManagerDeps);
+    /** Idempotent: replaces any existing watcher for this session. */
+    start(harnessSessionId: string, cwd: string): void;
+    stop(harnessSessionId: string): void;
+    stopAll(): void;
+    /** Test/debug helper — how many sessions currently have an active watcher. */
+    get size(): number;
+}
+//# sourceMappingURL=workspace-watcher.d.ts.map

package/dist/core/workspace-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-watcher.d.ts","sourceRoot":"","sources":["../../src/core/workspace-watcher.ts"],"names":[],"mappings":"AAkDA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAyB/D;AAsED,MAAM,WAAW,2BAA2B;IAC1C;;4DAEwD;IACxD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,0EAA0E;AAC1E,qBAAa,uBAAuB;IAGtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;gBAE1C,IAAI,EAAE,2BAA2B;IAE9D,kEAAkE;IAClE,KAAK,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAQlD,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAKpC,OAAO,IAAI,IAAI;IAIf,8EAA8E;IAC9E,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/core/workspace-watcher.js

@@ -0,0 +1,174 @@
+/**
+ * Workspace watcher: notices when workflows are added to / removed from a
+ * session's workspace directory DURING a session, so the rail can be re-scanned
+ * and re-broadcast instead of staying frozen at whatever the boot/session-create
+ * scan found. Users scaffold new workflows (and delete old ones) mid-session and
+ * expect the rail to keep up.
+ *
+ * Modeled on core/canvas-watcher.ts (same recursive-fs.watch-with-polling-
+ * fallback shape, same per-session lifecycle), but tuned to STRUCTURAL change
+ * rather than content change. It fires only when the SET of workflow-marker
+ * directories under the workspace actually changes (a workflow appearing,
+ * disappearing, or being renamed) — never for ordinary file edits:
+ *
+ *   - A raw watch event only *arms* a check; the debounced check recomputes
+ *     the workflow-marker fingerprint and fires `onChange` iff it differs from
+ *     the last one. This is deliberately NOT keyed off the `fs.watch` event
+ *     type: recursive `fs.watch` on macOS reports `rename` for plain content
+ *     writes too, so an event-type filter would spam rescans on every save.
+ *     The fingerprint diff is the reliable, cross-platform signal.
+ *   - High-churn / irrelevant subtrees (`node_modules`, `.git`, `.sapiom`,
+ *     build output) are skipped when arming AND when fingerprinting: a
+ *     workflow marker never lives there, and `.sapiom/canvas/renders` in
+ *     particular is rewritten on every render.
+ *
+ * The polling fallback (Linux, or a watcher runtime error) diffs the same
+ * fingerprint on an interval, so both paths share one notion of "changed".
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const DEBOUNCE_MS = 250;
+const POLL_INTERVAL_MS = 1000;
+/** Kept in sync with core/workflow-registry.ts's scan: the marker file that
+ *  makes a directory a workflow, and how deep the scan looks for it. */
+const WORKFLOW_MARKER = "sapiom.json";
+const MAX_SCAN_DEPTH = 3;
+/** Directories a workflow marker never lives in — skipped both when
+ *  fingerprinting and when deciding whether a watch event is relevant.
+ *  `.sapiom` covers the canvas renders that are rewritten on every render. */
+const IGNORED_DIR_NAMES = new Set(["node_modules", ".git", ".sapiom", "dist", "build", ".next"]);
+function firstSegmentIgnored(relPath) {
+    for (const segment of relPath.split(path.sep)) {
+        if (segment && IGNORED_DIR_NAMES.has(segment))
+            return true;
+    }
+    return false;
+}
+/**
+ * Fingerprint of the set of workflow-marker directories under `root` (sorted,
+ * bounded depth, ignored subtrees skipped). Changes exactly when a workflow is
+ * added, removed, or renamed — not when unrelated files are edited. Exported
+ * for the polling fallback and for direct testing.
+ */
+export function snapshotWorkspaceWorkflows(root) {
+    const markerDirs = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_SCAN_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // A directory carrying the marker is itself a workflow — record it and
+        // don't descend (matches the registry's scan semantics).
+        if (entries.some((entry) => entry.isFile() && entry.name === WORKFLOW_MARKER)) {
+            markerDirs.push(dir);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || IGNORED_DIR_NAMES.has(entry.name))
+                continue;
+            walk(path.join(dir, entry.name), depth + 1);
+        }
+    };
+    walk(root, 0);
+    return markerDirs.sort().join("|");
+}
+/** One session's workspace watcher. */
+class SessionWorkspaceWatcher {
+    constructor(cwd, harnessSessionId, onChange) {
+        this.cwd = cwd;
+        this.harnessSessionId = harnessSessionId;
+        this.onChange = onChange;
+        this.watcher = null;
+        this.pollTimer = null;
+        this.debounceTimer = null;
+        this.closed = false;
+        this.lastSnapshot = "";
+        this.lastSnapshot = snapshotWorkspaceWorkflows(this.cwd);
+        this.arm();
+    }
+    /** Debounced check: recompute the fingerprint and fire only on a real change. */
+    scheduleCheck() {
+        if (this.closed)
+            return;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => this.checkNow(), DEBOUNCE_MS);
+    }
+    checkNow() {
+        if (this.closed)
+            return;
+        const snapshot = snapshotWorkspaceWorkflows(this.cwd);
+        if (snapshot === this.lastSnapshot)
+            return;
+        this.lastSnapshot = snapshot;
+        this.onChange(this.harnessSessionId);
+    }
+    isRelevantPath(filename) {
+        // A `null` filename means the platform couldn't say what changed — check
+        // to be safe rather than miss a new/removed workflow.
+        if (!filename)
+            return true;
+        return !firstSegmentIgnored(filename);
+    }
+    arm() {
+        if (this.closed)
+            return;
+        try {
+            this.watcher = fs.watch(this.cwd, { recursive: true }, (_event, filename) => {
+                if (this.isRelevantPath(filename))
+                    this.scheduleCheck();
+            });
+            this.watcher.on("error", () => this.fallBackToPolling());
+        }
+        catch {
+            // `recursive` isn't supported on this platform (notably Linux).
+            this.fallBackToPolling();
+        }
+    }
+    fallBackToPolling() {
+        if (this.closed || this.pollTimer)
+            return;
+        this.watcher?.close();
+        this.watcher = null;
+        this.pollTimer = setInterval(() => this.checkNow(), POLL_INTERVAL_MS);
+    }
+    close() {
+        this.closed = true;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.watcher?.close();
+        this.watcher = null;
+    }
+}
+/** Registry of one SessionWorkspaceWatcher per active harness session. */
+export class WorkspaceWatcherManager {
+    constructor(deps) {
+        this.deps = deps;
+        this.watchers = new Map();
+    }
+    /** Idempotent: replaces any existing watcher for this session. */
+    start(harnessSessionId, cwd) {
+        this.stop(harnessSessionId);
+        this.watchers.set(harnessSessionId, new SessionWorkspaceWatcher(cwd, harnessSessionId, (id) => this.deps.onChange(id)));
+    }
+    stop(harnessSessionId) {
+        this.watchers.get(harnessSessionId)?.close();
+        this.watchers.delete(harnessSessionId);
+    }
+    stopAll() {
+        for (const harnessSessionId of [...this.watchers.keys()])
+            this.stop(harnessSessionId);
+    }
+    /** Test/debug helper — how many sessions currently have an active watcher. */
+    get size() {
+        return this.watchers.size;
+    }
+}
+//# sourceMappingURL=workspace-watcher.js.map

package/dist/core/workspace-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-watcher.js","sourceRoot":"","sources":["../../src/core/workspace-watcher.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @sapiom/harness — library entry. The CLI (`sapiom-harness`) is the primary
+ * interface; this export exists so other packages can reuse the contract.
+ */
+export * from "./shared/types.js";
+//# sourceMappingURL=index.d.ts.map