@jitsusama/agentic-harness.core 0.6.1 → 0.6.3

package/dist/internal/file-lock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An advisory lock around one file's read-modify-write, for async
+ * callers.
+ *
+ * A read-modify-write that two writers run at once loses one of them:
+ * both read the same document and the second write lays its version
+ * over the first. Two layers stop that. Within a process, writers of
+ * one path queue behind each other, so parallel tool calls in one
+ * session never contend. Across processes, a lock file created with
+ * `wx` holds the holder's pid, and the next writer waits for it.
+ *
+ * The synchronous counterpart for quest READMEs is in
+ * `quest/io.ts`; its callers cannot await, so it spins instead.
+ *
+ * A lock is taken over when its holder has gone or it is older than
+ * any real write takes, since a crashed session must not wedge the
+ * file for good and a pid can be reused. Taking over renames the lock
+ * aside rather than deleting it, and checks the file it moved is the
+ * one it judged stale: between that judgement and the move, another
+ * writer may have taken over first and made a fresh one, and deleting
+ * by name would delete theirs. Release checks the same way, so a
+ * holder that was taken over from does not delete its successor's.
+ */
+/**
+ * Run `fn` while holding the lock for `path`, queued behind any other
+ * writer of the same path in this process and locked against every
+ * other process. The lock file is `${path}.lock`, so its directory has
+ * to exist.
+ */
+export declare function withFileLock<T>(path: string, fn: () => Promise<T>): Promise<T>;

package/dist/internal/file-lock.js

@@ -0,0 +1,183 @@
+/**
+ * An advisory lock around one file's read-modify-write, for async
+ * callers.
+ *
+ * A read-modify-write that two writers run at once loses one of them:
+ * both read the same document and the second write lays its version
+ * over the first. Two layers stop that. Within a process, writers of
+ * one path queue behind each other, so parallel tool calls in one
+ * session never contend. Across processes, a lock file created with
+ * `wx` holds the holder's pid, and the next writer waits for it.
+ *
+ * The synchronous counterpart for quest READMEs is in
+ * `quest/io.ts`; its callers cannot await, so it spins instead.
+ *
+ * A lock is taken over when its holder has gone or it is older than
+ * any real write takes, since a crashed session must not wedge the
+ * file for good and a pid can be reused. Taking over renames the lock
+ * aside rather than deleting it, and checks the file it moved is the
+ * one it judged stale: between that judgement and the move, another
+ * writer may have taken over first and made a fresh one, and deleting
+ * by name would delete theirs. Release checks the same way, so a
+ * holder that was taken over from does not delete its successor's.
+ */
+import { randomUUID } from "node:crypto";
+import { link, open, readFile, rename, stat, unlink } from "node:fs/promises";
+/** How long a writer waits for a live holder before saying so. */
+const WAIT_MS = 10_000;
+/** Pause between attempts at the lock. */
+const RETRY_MS = 20;
+/**
+ * A lock older than this is taken over whoever holds it. A write under
+ * it is a read and a rename of a small file, milliseconds, so anything
+ * this old is a holder that stopped rather than one still writing.
+ */
+const STALE_MS = 30_000;
+const queues = new Map();
+/**
+ * Run `fn` while holding the lock for `path`, queued behind any other
+ * writer of the same path in this process and locked against every
+ * other process. The lock file is `${path}.lock`, so its directory has
+ * to exist.
+ */
+export async function withFileLock(path, fn) {
+    const before = queues.get(path) ?? Promise.resolve();
+    const turn = before.then(() => locked(path, fn), () => locked(path, fn));
+    // The queue only orders writers; it never carries a failure from one
+    // to the next, so the entry it holds settles either way.
+    const settled = turn.then(() => undefined, () => undefined);
+    queues.set(path, settled);
+    try {
+        return await turn;
+    }
+    finally {
+        if (queues.get(path) === settled)
+            queues.delete(path);
+    }
+}
+async function locked(path, fn) {
+    const lockPath = `${path}.lock`;
+    const held = await acquire(lockPath);
+    try {
+        return await fn();
+    }
+    finally {
+        await release(lockPath, held);
+    }
+}
+async function acquire(lockPath) {
+    const deadline = Date.now() + WAIT_MS;
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx");
+            try {
+                await handle.writeFile(String(process.pid), "utf8");
+                return (await handle.stat()).ino;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        }
+        if (await takeOverIfStale(lockPath))
+            continue;
+        if (Date.now() >= deadline) {
+            const holder = await holderOf(lockPath);
+            throw new Error(`${lockPath} has been held for over ${WAIT_MS / 1000}s by ${holder === undefined ? "a process that did not say which" : `pid ${holder}`}, which is still running. Nothing was written. If that process is not writing, delete the lock file and try again.`);
+        }
+        await new Promise((done) => setTimeout(done, RETRY_MS));
+    }
+}
+async function takeOverIfStale(lockPath) {
+    let judged;
+    try {
+        judged = await stat(lockPath);
+    }
+    catch (error) {
+        // Released between the failed create and here: try again.
+        if (hasCode(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    const holder = await holderOf(lockPath);
+    const old = Date.now() - judged.mtimeMs > STALE_MS;
+    // A holder that has not written its pid yet is one mid-create, not
+    // one that has gone, so only age can make its lock stale.
+    const gone = holder !== undefined && !isAlive(holder);
+    if (!old && !gone)
+        return false;
+    const aside = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+    try {
+        await rename(lockPath, aside);
+    }
+    catch (error) {
+        // Somebody else took it over first.
+        if (hasCode(error, "ENOENT"))
+            return true;
+        throw error;
+    }
+    const moved = await stat(aside);
+    if (moved.ino !== judged.ino) {
+        // Between the judgement and the move another writer took over and
+        // made a fresh lock, and this moved theirs. Put it back, unless a
+        // third has already made one, in which case theirs stands and the
+        // one moved is left for its holder's release to find missing.
+        try {
+            await link(aside, lockPath);
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        }
+    }
+    await unlink(aside);
+    return true;
+}
+async function release(lockPath, ino) {
+    try {
+        if ((await stat(lockPath)).ino === ino)
+            await unlink(lockPath);
+    }
+    catch (error) {
+        // Taken over and released by somebody else already: nothing of
+        // this holder's is left to remove.
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function holderOf(lockPath) {
+    try {
+        const pid = Number.parseInt(await readFile(lockPath, "utf8"), 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+    }
+    catch (error) {
+        // Gone since the create failed, which the next attempt handles.
+        if (hasCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+function isAlive(pid) {
+    // This process never waits on its own lock, since its writers queue
+    // first, so a lock naming it is one a previous process with the same
+    // pid left behind.
+    if (pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM is a process that exists and belongs to somebody else.
+        return hasCode(error, "EPERM");
+    }
+}
+function hasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}

package/dist/internal/quest/io.js

@@ -26,7 +26,7 @@
  * that bypasses it can still write through. We rely on
  * every README write going through `withQuestLock`.
  */
-import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { closeSync, existsSync, fstatSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
 import { dirname, join } from "node:path";
 /** Lock-acquire retry budget per call. */
 const LOCK_TIMEOUT_MS = 5000;
@@ -102,30 +102,52 @@ function isProcessAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/**
+ * Take the lock over if its holder has gone or it is too old to be a
+ * write in progress.
+ *
+ * A lock with no readable record is judged by its file's age alone: a
+ * holder creates the lock and then writes its record, so for a moment
+ * every live lock is empty, and treating that as abandoned took locks
+ * from their holders. Taking over moves the lock aside and checks the
+ * move took the one judged stale; deleting by name could delete a lock
+ * another writer made after taking over first.
+ */
 function tryStealStaleLock(lockPath, now) {
-    const record = readLockRecord(lockPath);
-    if (!record) {
-        // Malformed lock file; remove and retry.
-        try {
-            unlinkSync(lockPath);
-        }
-        catch {
-            // Another process beat us to the cleanup; that's fine.
-        }
+    let judged;
+    try {
+        judged = statSync(lockPath);
+    }
+    catch {
+        // Released since the failed create; the next attempt takes it.
         return true;
     }
-    const age = now - record.startedAt;
-    if (age < STALE_LOCK_MS && isProcessAlive(record.pid))
+    const record = readLockRecord(lockPath);
+    const stale = record
+        ? now - record.startedAt >= STALE_LOCK_MS || !isProcessAlive(record.pid)
+        : now - judged.mtimeMs >= STALE_LOCK_MS;
+    if (!stale)
         return false;
+    const aside = `${lockPath}.stale-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
     try {
-        unlinkSync(lockPath);
-        return true;
+        renameSync(lockPath, aside);
     }
     catch {
-        // Another process beat us to the cleanup; let the
-        // next loop iteration retry the acquire.
+        // Somebody else took it over first; the next attempt sees theirs.
         return false;
     }
+    if (statSync(aside).ino !== judged.ino) {
+        // Moved a fresh lock another writer made after taking over first.
+        // Put it back, unless a third already made one, which then stands.
+        try {
+            linkSync(aside, lockPath);
+        }
+        catch {
+            // EEXIST: the newer lock stands, as above.
+        }
+    }
+    unlinkSync(aside);
+    return true;
 }
 function acquireLock(lockPath) {
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
@@ -139,7 +161,7 @@ function acquireLock(lockPath) {
             };
             writeSync(fd, JSON.stringify(payload));
             fsyncSync(fd);
-            return fd;
+            return { fd, ino: fstatSync(fd).ino };
         }
         catch (err) {
             const code = err.code;
@@ -165,15 +187,18 @@ function acquireLock(lockPath) {
         }
     }
 }
-function releaseLock(lockPath, fd) {
+function releaseLock(lockPath, held) {
     try {
-        closeSync(fd);
+        closeSync(held.fd);
     }
     catch {
         // Already closed; cleanup of the path below still runs.
     }
     try {
-        unlinkSync(lockPath);
+        // Only this holder's own lock: one taken over from it belongs to
+        // whoever made the new one.
+        if (statSync(lockPath).ino === held.ino)
+            unlinkSync(lockPath);
     }
     catch {
         // Lock file was stolen out from under us or never
@@ -203,12 +228,12 @@ export function withQuestLock(questDir, fn) {
             // Stat failed; the acquire loop handles it.
         }
     }
-    const fd = acquireLock(lockPath);
+    const held = acquireLock(lockPath);
     try {
         return fn();
     }
     finally {
-        releaseLock(lockPath, fd);
+        releaseLock(lockPath, held);
     }
 }
 /**

package/dist/lsp/standalone/backend.d.ts

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -30,6 +36,8 @@ export interface StandaloneBackendOptions {
     readonly servers?: Readonly<Record<string, ServerConfig>>;
     /** Environment used for PATH resolution. Defaults to process.env. */
     readonly env?: NodeJS.ProcessEnv;
+    /** How long a server may sit unused before it is stopped. */
+    readonly idleMs?: number;
 }
 /** A standalone backend with visibility into its live pool. */
 export interface StandaloneBackend extends LspBackend {

package/dist/lsp/standalone/backend.js

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -28,20 +34,56 @@ export class MissingServerError extends Error {
         this.name = "MissingServerError";
     }
 }
+/**
+ * Default idle window. Long enough that a burst of work on one
+ * project keeps its server warm, short enough that a project left
+ * behind gives its memory back within the hour.
+ */
+const DEFAULT_IDLE_MS = 10 * 60_000;
 /** Construct a standalone backend over the given (or default) server map. */
 export function createStandaloneBackend(options = {}) {
     const servers = options.servers ?? DEFAULT_SERVERS;
     const env = options.env ?? process.env;
+    const idleMs = options.idleMs ?? DEFAULT_IDLE_MS;
     const pool = new Map();
+    // Calls in flight per pool key, and the stop timer armed when a
+    // key's last call finishes.
+    const inFlight = new Map();
+    const idleTimers = new Map();
     const poolKey = (name, root) => `${name}|${root}`;
+    const claim = (key) => {
+        inFlight.set(key, (inFlight.get(key) ?? 0) + 1);
+        clearTimeout(idleTimers.get(key));
+        idleTimers.delete(key);
+    };
+    const release = (key) => {
+        const left = (inFlight.get(key) ?? 1) - 1;
+        if (left > 0) {
+            inFlight.set(key, left);
+            return;
+        }
+        inFlight.delete(key);
+        const timer = setTimeout(() => stopIdle(key), idleMs);
+        // An idle server must never be what keeps the process alive.
+        timer.unref();
+        idleTimers.set(key, timer);
+    };
+    const stopIdle = (key) => {
+        idleTimers.delete(key);
+        if (inFlight.has(key))
+            return;
+        const started = pool.get(key);
+        pool.delete(key);
+        void started?.then((server) => server.dispose(), () => { });
+    };
     const instanceFor = (server, root, binary) => {
         const key = poolKey(server.name, root);
         const existing = pool.get(key);
         if (existing)
-            return existing;
+            return { key, started: existing };
         const started = StandaloneServer.start(server, root, binary);
         pool.set(key, started);
-        return started;
+        return { key, started };
     };
     // Resolve a server's effective command and args for a root. A
     // server with a `resolve` hook picks its binary per project (the
@@ -65,7 +107,22 @@ export function createStandaloneBackend(options = {}) {
             binary,
         };
     };
-    const resolveInstances = async (filePath, typeOnly) => {
+    /**
+     * Run fn against the servers for a file, holding each one's pool
+     * key claimed from before it resolves until fn settles, so no
+     * server is stopped under a call that is using it.
+     */
+    const withInstances = async (filePath, typeOnly, fn) => {
+        const claimed = [];
+        try {
+            return await fn(await resolveInstances(filePath, typeOnly, claimed));
+        }
+        finally {
+            for (const key of claimed)
+                release(key);
+        }
+    };
+    const resolveInstances = async (filePath, typeOnly, claimed) => {
         const candidates = serversForFile(filePath, servers).filter((server) => !typeOnly || !server.isLinter);
         const instances = [];
         const reasons = [];
@@ -80,7 +137,10 @@ export function createStandaloneBackend(options = {}) {
                 reasons.push(eff.reason);
                 continue;
             }
-            instances.push(await instanceFor(eff.config, root, eff.binary));
+            const { key, started } = instanceFor(eff.config, root, eff.binary);
+            claim(key);
+            claimed.push(key);
+            instances.push(await started);
             if (typeOnly)
                 break;
         }
@@ -95,40 +155,46 @@ export function createStandaloneBackend(options = {}) {
     return {
         name: "standalone",
         async diagnostics(path) {
-            const instances = await resolveInstances(path, false);
-            const results = await Promise.all(instances.map((s) => s.diagnose(path)));
-            return results.flat();
+            return withInstances(path, false, async (instances) => {
+                const results = await Promise.all(instances.map((s) => s.diagnose(path)));
+                return results.flat();
+            });
         },
         async definition(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.definition(target);
+            return withInstances(target.path, true, ([server]) => server.definition(target));
         },
         async references(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.references(target);
+            return withInstances(target.path, true, ([server]) => server.references(target));
         },
         async hover(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.hover(target);
+            return withInstances(target.path, true, ([server]) => server.hover(target));
         },
         async documentSymbols(path) {
-            const [server] = await resolveInstances(path, true);
-            return server.documentSymbols(path);
+            return withInstances(path, true, ([server]) => server.documentSymbols(path));
         },
         async workspaceSymbols(query) {
             // Workspace symbols carry no file, so they search every
-            // server already running; nothing is spawned on demand.
-            const live = await Promise.all([...pool.values()]);
-            const results = await Promise.all(live.map((server) => server.workspaceSymbols(query)));
-            return results.flat();
+            // server already running; nothing is spawned on demand, and
+            // a server stopped for idleness is not searched until
+            // something file-bound starts it again.
+            const keys = [...pool.keys()];
+            for (const key of keys)
+                claim(key);
+            try {
+                const live = await Promise.all(keys.map((key) => pool.get(key)));
+                const results = await Promise.all(live.map((server) => server?.workspaceSymbols(query) ?? []));
+                return results.flat();
+            }
+            finally {
+                for (const key of keys)
+                    release(key);
+            }
         },
         async rename(target, newName) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.rename(target, newName);
+            return withInstances(target.path, true, ([server]) => server.rename(target, newName));
         },
         async codeActions(path, range) {
-            const [server] = await resolveInstances(path, true);
-            return server.codeActions(path, range);
+            return withInstances(path, true, ([server]) => server.codeActions(path, range));
         },
         syncDocument(path, text) {
             for (const started of pool.values()) {
@@ -142,6 +208,9 @@ export function createStandaloneBackend(options = {}) {
             return pool.size;
         },
         async dispose() {
+            for (const timer of idleTimers.values())
+                clearTimeout(timer);
+            idleTimers.clear();
             const started = [...pool.values()];
             pool.clear();
             await Promise.all(started.map((s) => s.then((server) => server.dispose())));

package/dist/review/ask/store.js

@@ -11,8 +11,10 @@
  * council needs that council still to be there, or nothing can say
  * what it consolidated.
  */
+import { randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { withFileLock } from "../../internal/file-lock.js";
 import { changeKey } from "../keys.js";
 /** Runs on disk, one file per change. */
 export function createRunStore(root) {
@@ -71,15 +73,29 @@ export function createRunStore(root) {
         // whose whole premise is that the session may not survive it,
         // so the window stopped being theoretical. A rename within one
         // directory is atomic: a reader sees the old ledger or the new
-        // one.
-        const pending = `${path}.${process.pid}.tmp`;
+        // one. Named per write, not per process: two writes in one
+        // process sharing a name tore the file, the shorter write landing
+        // over the start of the longer.
+        const pending = `${path}.${process.pid}.${randomUUID()}.tmp`;
         await writeFile(pending, JSON.stringify(ledger, null, 2), "utf8");
         await rename(pending, path);
     }
+    /**
+     * Read, change and write one change's ledger as a single step. Every
+     * write is a whole ledger built from the one read before it, so two
+     * of these at once, from parallel tool calls or two sessions on one
+     * change, would each lay its version over the other's and drop a
+     * round without an error.
+     */
+    async function mutate(change, next) {
+        await mkdir(root, { recursive: true });
+        await withFileLock(join(root, fileFor(change)), async () => {
+            await write(change, next(await read(change)));
+        });
+    }
     return {
         async record(change, run) {
-            const ledger = await read(change);
-            await write(change, { runs: [...ledger.runs, run] });
+            await mutate(change, (ledger) => ({ runs: [...ledger.runs, run] }));
         },
         async list(change) {
             return (await read(change)).runs;
@@ -176,24 +192,26 @@ export function createRunStore(root) {
             return (await read(change)).runs.find((r) => r.id === runId);
         },
         async keep(change, run) {
-            const ledger = await read(change);
-            const at = ledger.runs.findIndex((held) => held.id === run.id);
-            await write(change, {
-                runs: at === -1
-                    ? [...ledger.runs, run]
-                    : ledger.runs.map((held, index) => (index === at ? run : held)),
+            await mutate(change, (ledger) => {
+                const at = ledger.runs.findIndex((held) => held.id === run.id);
+                return {
+                    runs: at === -1
+                        ? [...ledger.runs, run]
+                        : ledger.runs.map((held, index) => (index === at ? run : held)),
+                };
             });
         },
         async replace(change, run) {
-            const ledger = await read(change);
-            const at = ledger.runs.findIndex((held) => held.id === run.id);
-            if (at === -1) {
-                // Adding it silently would make a retry look like it
-                // patched something when it invented a round instead.
-                throw new Error(`No run "${run.id}" is held against this change, so there is nothing to replace. Record it first, or check the id.`);
-            }
-            await write(change, {
-                runs: ledger.runs.map((held, index) => (index === at ? run : held)),
+            await mutate(change, (ledger) => {
+                const at = ledger.runs.findIndex((held) => held.id === run.id);
+                if (at === -1) {
+                    // Adding it silently would make a retry look like it
+                    // patched something when it invented a round instead.
+                    throw new Error(`No run "${run.id}" is held against this change, so there is nothing to replace. Record it first, or check the id.`);
+                }
+                return {
+                    runs: ledger.runs.map((held, index) => (index === at ? run : held)),
+                };
             });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jitsusama/agentic-harness.core",
-	"version": "0.6.1",
+	"version": "0.6.3",
 	"description": "Pi-agnostic business logic for agentic-harness: state machines, guardian decisions, quest/TDD domain model.",
 	"license": "MIT",
 	"type": "module",