@manyoars/oars 0.5.2 → 0.5.4

package/dist/sessions/pool-send-lock.d.ts

@@ -5,6 +5,8 @@ export interface LockTimes {
     /** How long a run waits for the lock before it gives up. */
     waitMs: number;
     pollMs: number;
+    /** How long a run waits behind a live holder before it tells the person it is waiting. */
+    noticeMs: number;
 }
 /** What a test replaces: `stat` to read a lock as stale at the moment a waiter looks, `open` to make the create fail the way Windows does, `platform` to pick the platform's rules. */
 export interface LockFs {
@@ -13,8 +15,77 @@ export interface LockFs {
     }>;
     open?: (path: string, flags: 'wx') => Promise<FileHandle>;
     platform?: NodeJS.Platform;
+    /** Whether a process with this id is running on this machine. A test answers for a pid it made up. */
+    running?: (pid: number) => boolean;
+    /** This run's pid and host, recorded in the lock; a test names the holder it plays. */
+    self?: {
+        pid: number;
+        host: string;
+    };
+    /** The clock and the pause between polls; a test drives both instead of sleeping. */
+    clock?: {
+        now: () => number;
+        sleep: (ms: number) => Promise<void>;
+    };
+}
+export declare const DEFAULT_TIMES: LockTimes;
+/** Who holds the lock, as the holder wrote it into the file: its run, pid, host, and when it took the lock (epoch ms). */
+export interface Holder {
+    run: string;
+    pid: number;
+    host: string;
+    since: number;
+}
+/** What a run that waits tells its caller once, when the wait has lasted `noticeMs`: the holder when the file names one (an empty or older-format file names none), how old the lock is, and how long this run will wait. */
+export interface Waiting {
+    holder: Holder | undefined;
+    ageMs: number;
+    waitMs: number;
+}
+/** What a run that gave up knows: the holder, the lock's age now, the time already waited, and the constants the takeover rules use. */
+export interface BusyDetail {
+    holder: Holder | undefined;
+    /** Time since the holder took the lock, else since the lock file was last touched. */
+    ageMs: number;
+    /** Time since the lock file was last touched: a live holder touches it every `staleMs / 4`. */
+    untouchedMs: number;
+    waitedMs: number;
+    staleMs: number;
+    /** Whether the holder is a process on this host: its heartbeat then keeps the lock fresh while it lives, so only its end (not the clock) frees the lock. */
+    local: boolean;
+}
+export interface LockWait {
+    /** Called once if the lock is still held after `noticeMs`. */
+    onWait?: (waiting: Waiting) => void;
+    /** Ends the wait: the run throws the signal's reason. An interrupted `--send` leaves nothing waiting. */
+    signal?: AbortSignal;
 }
 export declare class SendLockBusy extends Error {
-    constructor();
+    readonly detail: BusyDetail;
+    constructor(detail?: BusyDetail);
+}
+export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs, wait?: LockWait) => Promise<T>;
+/** Why an interactive send ended before it finished: a signal reached it, or the process that launched it is gone. */
+export declare class SendInterrupted extends Error {
+    readonly kind: 'signal' | 'launcher';
+    readonly signal?: NodeJS.Signals | undefined;
+    constructor(kind: 'signal' | 'launcher', message: string, signal?: NodeJS.Signals | undefined);
+}
+/** What a test replaces: the process's signal hooks, its launcher, and how that launcher's liveness is read. */
+export interface InterruptHost {
+    on: (event: NodeJS.Signals, listener: () => void) => unknown;
+    off: (event: NodeJS.Signals, listener: () => void) => unknown;
+    /** The pid of the process that started this one; checked every `checkMs`. */
+    parent: number;
+    running: (pid: number) => boolean;
+    checkMs: number;
 }
-export declare const withSendLock: <T>(outbox: string, run: () => Promise<T>, times?: Partial<LockTimes>, fs?: LockFs) => Promise<T>;
+/**
+ * The signal an interactive `oars pool deposit --send` waits and sends under. Ctrl-C, a closed terminal, and a kill all end it. A launcher that is killed without a signal reaching its child (Windows `taskkill` of the
+ * shell or the `oars.cmd` shim, a `timeout` wrapper) leaves the child running, so the launcher's pid is read every second and a run whose launcher is gone ends too. The detached nightly sender is not watched:
+ * it is meant to outlive its starter.
+ */
+export declare const watchInterrupt: (host?: InterruptHost) => {
+    signal: AbortSignal;
+    stop: () => void;
+};

package/dist/sessions/pool-send-lock.js

@@ -1,15 +1,46 @@
 // One sender at a time per outbox: the detached sender (hook-bin.js nightly) and `deposit --send` both take this lock, so a batch is never posted twice by two runs that overlap. The lock is a file created
-// with `wx` beside `sent.log`, so it holds across processes as well as inside one. A run that finds it held waits; a lock older than `staleMs` belongs to a run that died, and is taken over by one waiter only, under a guard file. The holder touches the file while it runs, so a long send (a first night of raw parts) is never mistaken for a dead run, and it removes the file only if the file still names its own run.
+// with `wx` beside `sent.log`, so it holds across processes as well as inside one. A run that finds it held waits; a holder on this host whose pid is not running is taken over at once, and a lock untouched for `staleMs` belongs to a run that died (the rule for a holder whose liveness cannot be read: an empty or older-format file, another host's pid). Either takeover is by one waiter only, under a guard file. The holder touches the file while it runs, so a long send (a first night of raw parts) is never mistaken for a dead run, and it removes the file only if the file still names its own run.
 import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
+import { hostname } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-const DEFAULT_TIMES = { staleMs: 10 * 60 * 1000, waitMs: 2 * 60 * 1000, pollMs: 50 };
+export const DEFAULT_TIMES = { staleMs: 10 * 60 * 1000, waitMs: 2 * 60 * 1000, pollMs: 50, noticeMs: 500 };
 export class SendLockBusy extends Error {
-    constructor() {
+    detail;
+    constructor(detail = { holder: undefined, ageMs: 0, untouchedMs: 0, waitedMs: 0, staleMs: DEFAULT_TIMES.staleMs, local: false }) {
         super('Another oars run is sending from this outbox.');
+        this.detail = detail;
     }
 }
+const running = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error instanceof Error && Reflect.get(error, 'code') === 'EPERM';
+    }
+};
+/** The holder a lock file names, or `undefined` for a file that is empty, half written, or not in this format: such a lock is judged by the clock alone. */
+const holderOf = async (file) => {
+    const text = await readFile(file, 'utf8').catch(() => '');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const run = Reflect.get(parsed, 'run');
+    const pid = Reflect.get(parsed, 'pid');
+    const host = Reflect.get(parsed, 'host');
+    const since = Reflect.get(parsed, 'since');
+    return typeof run === 'string' && typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && typeof host === 'string' && typeof since === 'number' ? { run, pid, host, since } : undefined;
+};
 // EEXIST means another run holds the file. On Windows an open of a file whose delete is still pending (the holder just released it) answers EPERM or EACCES instead: the same contention, so retry within waitMs.
 const contended = (error, platform) => {
     if (!(error instanceof Error))
@@ -18,24 +49,37 @@ const contended = (error, platform) => {
     return code === 'EEXIST' || (platform === 'win32' && (code === 'EPERM' || code === 'EACCES'));
 };
 /**
- * A stale lock is removed under a takeover guard (`send.lock.takeover`, created with `wx`), so one waiter at a time reads the lock again and removes it only if it is still stale. A live lock is never moved
- * or removed: a waiter that read a lock as stale, but meets a lock another run took over and refreshed in the meantime, finds it fresh under the guard and leaves it. A guard left by a taker that died is
+ * Whether a lock can be removed now: its holder is a process on this machine that is not running (taken over at once, whatever the clock says), or the file has not been touched for `staleMs` (the holder's heartbeat stopped).
+ * A holder whose liveness cannot be read (an empty file, another host's pid) is judged by the clock alone, which is the only reason `staleMs` stays at ten minutes. A pid the system has handed to another process since reads as
+ * running, so pid reuse can only make a waiter wait for the clock, never take a live holder's lock; the lock's age is not taken from the pid for that reason.
+ */
+const reclaimable = async (file, staleMs, fs, now) => {
+    const held = await fs.stat(file).catch(() => undefined);
+    if (held === undefined)
+        return false;
+    if (now() - held.mtimeMs > staleMs)
+        return true;
+    const holder = await holderOf(file);
+    return holder !== undefined && holder.host === (fs.self?.host ?? hostname()) && !(fs.running ?? running)(holder.pid);
+};
+/**
+ * A reclaimable lock is removed under a takeover guard (`send.lock.takeover`, created with `wx`), so one waiter at a time reads the lock again and removes it only if it is still reclaimable. A live lock is never moved
+ * or removed: a waiter that read a lock as reclaimable, but meets a lock another run took over and refreshed in the meantime, finds it live under the guard and leaves it. A guard left by a taker that died is
  * removed once it is older than `staleMs`.
  */
-const takeOver = async (file, staleMs, fs) => {
+const takeOver = async (file, staleMs, fs, now) => {
     const guard = `${file}.takeover`;
     try {
         await (await open(guard, 'wx')).close();
     }
     catch {
         const left = await stat(guard).catch(() => undefined);
-        if (left !== undefined && Date.now() - left.mtimeMs > staleMs)
+        if (left !== undefined && now() - left.mtimeMs > staleMs)
             await rm(guard, { force: true });
         return false;
     }
     try {
-        const held = await fs.stat(file).catch(() => undefined);
-        if (held === undefined || Date.now() - held.mtimeMs <= staleMs)
+        if (!(await reclaimable(file, staleMs, fs, now)))
             return false;
         await rm(file, { force: true });
         return true;
@@ -44,18 +88,25 @@ const takeOver = async (file, staleMs, fs) => {
         await rm(guard, { force: true });
     }
 };
-export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
-    const { staleMs, waitMs, pollMs } = { ...DEFAULT_TIMES, ...times };
+export const withSendLock = async (outbox, run, times = {}, fs = { stat }, wait = {}) => {
+    const { staleMs, waitMs, pollMs, noticeMs } = { ...DEFAULT_TIMES, ...times };
     const file = join(outbox, 'send.lock');
     const runId = randomUUID();
     const create = fs.open ?? open;
     const platform = fs.platform ?? process.platform;
+    const clock = fs.clock ?? { now: () => Date.now(), sleep: (ms) => sleep(ms) };
+    const self = fs.self ?? { pid: process.pid, host: hostname() };
     await mkdir(outbox, { recursive: true });
-    const giveUp = Date.now() + waitMs;
+    const began = clock.now();
+    const giveUp = began + waitMs;
+    let noticed = false;
     for (;;) {
+        if (wait.signal?.aborted === true)
+            throw wait.signal.reason;
         try {
             const handle = await create(file, 'wx');
-            await handle.writeFile(runId);
+            const holder = { run: runId, pid: self.pid, host: self.host, since: clock.now() };
+            await handle.writeFile(JSON.stringify(holder));
             await handle.close();
             break;
         }
@@ -65,11 +116,19 @@ export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
         }
         const held = await fs.stat(file).catch(() => undefined);
         // A takeover that cleared the lock goes straight back to taking it; any other outcome waits, and gives up once waitMs has passed.
-        if (held !== undefined && Date.now() - held.mtimeMs > staleMs && (await takeOver(file, staleMs, fs)))
+        if (held !== undefined && (await reclaimable(file, staleMs, fs, clock.now)) && (await takeOver(file, staleMs, fs, clock.now)))
             continue;
-        if (Date.now() >= giveUp)
-            throw new SendLockBusy();
-        await sleep(pollMs);
+        const at = clock.now();
+        const holder = await holderOf(file);
+        const untouchedMs = held === undefined ? 0 : Math.max(0, at - held.mtimeMs);
+        const ageMs = holder === undefined ? untouchedMs : Math.max(0, at - holder.since);
+        if (!noticed && at - began >= noticeMs) {
+            noticed = true;
+            wait.onWait?.({ holder, ageMs, waitMs });
+        }
+        if (at >= giveUp)
+            throw new SendLockBusy({ holder, ageMs, untouchedMs, waitedMs: at - began, staleMs, local: holder?.host === self.host });
+        await clock.sleep(pollMs);
     }
     const beat = setInterval(() => {
         const now = new Date();
@@ -81,7 +140,48 @@ export const withSendLock = async (outbox, run, times = {}, fs = { stat }) => {
     finally {
         clearInterval(beat);
         // The file is ours only while it still names this run; a lock another run took over is theirs.
-        if ((await readFile(file, 'utf8').catch(() => undefined)) === runId)
+        if ((await holderOf(file))?.run === runId)
             await rm(file, { force: true });
     }
 };
+/** Why an interactive send ended before it finished: a signal reached it, or the process that launched it is gone. */
+export class SendInterrupted extends Error {
+    kind;
+    signal;
+    constructor(kind, message, signal) {
+        super(message);
+        this.kind = kind;
+        this.signal = signal;
+        this.name = 'SendInterrupted';
+    }
+}
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * The signal an interactive `oars pool deposit --send` waits and sends under. Ctrl-C, a closed terminal, and a kill all end it. A launcher that is killed without a signal reaching its child (Windows `taskkill` of the
+ * shell or the `oars.cmd` shim, a `timeout` wrapper) leaves the child running, so the launcher's pid is read every second and a run whose launcher is gone ends too. The detached nightly sender is not watched:
+ * it is meant to outlive its starter.
+ */
+export const watchInterrupt = (host = { on: (event, listener) => process.on(event, listener), off: (event, listener) => process.off(event, listener), parent: process.ppid, running, checkMs: 1000 }) => {
+    const controller = new AbortController();
+    const listeners = SIGNALS.map((name) => [
+        name,
+        () => {
+            controller.abort(new SendInterrupted('signal', `Interrupted by ${name}.`, name));
+        },
+    ]);
+    for (const [name, listener] of listeners)
+        host.on(name, listener);
+    const timer = setInterval(() => {
+        if (!host.running(host.parent))
+            controller.abort(new SendInterrupted('launcher', 'The program that started this send is gone.'));
+    }, host.checkMs);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        stop: () => {
+            clearInterval(timer);
+            for (const [name, listener] of listeners)
+                host.off(name, listener);
+        },
+    };
+};

package/dist/sessions/vocab-load.d.ts

@@ -17,10 +17,13 @@ export interface Vocabulary {
     models: ReadonlySet<string>;
     harnessVersions: ReadonlyMap<string, ReadonlySet<string>>;
 }
-/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
-export declare const VOCAB_DIR: import("url").URL;
+/**
+ * packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. A function, not a constant: a bundle imported from a
+ * `data:` URL (the pool's sample-pack command) has no file location, and building this URL at load time would throw before that caller could pass its own folder.
+ */
+export declare const vocabDir: () => URL;
 export declare const PACKAGE_FILES: readonly ["npm.json", "pypi.json", "crates.json", "rubygems.json", "homebrew.json", "go.json", "maven.json"];
 /** Reads and checks every snapshot under `dir` (default: the shipped folder). */
 export declare const readVocabulary: (dir?: URL) => Vocabulary;
-/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
-export declare const vocabulary: () => Vocabulary;
+/** The vocabulary of a folder (the shipped one by default), read once per folder on first use: reading 6 MB of JSON is not free, and most commands never project. `dir` is for a caller that cannot locate the folder itself. */
+export declare const vocabulary: (dir?: URL) => Vocabulary;

package/dist/sessions/vocab-load.js

@@ -3,8 +3,11 @@
 // A snapshot that does not parse is an error and never an empty list: an empty list would quietly project every name as `private`.
 import { readFileSync } from 'node:fs';
 import { VOCAB_SNAPSHOT_DATE, VOCAB_VERSION } from './public-vocabulary.js';
-/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
-export const VOCAB_DIR = new URL('../../vocab/', import.meta.url);
+/**
+ * packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. A function, not a constant: a bundle imported from a
+ * `data:` URL (the pool's sample-pack command) has no file location, and building this URL at load time would throw before that caller could pass its own folder.
+ */
+export const vocabDir = () => new URL('../../vocab/', import.meta.url);
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const recordAt = (value, where) => {
     if (!isRecord(value))
@@ -35,7 +38,7 @@ const packageSnapshot = (dir, file) => {
 };
 export const PACKAGE_FILES = ['npm.json', 'pypi.json', 'crates.json', 'rubygems.json', 'homebrew.json', 'go.json', 'maven.json'];
 /** Reads and checks every snapshot under `dir` (default: the shipped folder). */
-export const readVocabulary = (dir = VOCAB_DIR) => {
+export const readVocabulary = (dir = vocabDir()) => {
     const manifest = readJson(dir, 'manifest.json');
     const snapshotDate = manifest['snapshotDate'];
     if (snapshotDate !== VOCAB_SNAPSHOT_DATE) {
@@ -56,6 +59,13 @@ export const readVocabulary = (dir = VOCAB_DIR) => {
         harnessVersions: new Map(Object.entries(harnesses).map(([harness, versions]) => [harness, new Set(stringsAt(versions, `harness.${harness}`))])),
     };
 };
-let loaded;
-/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
-export const vocabulary = () => (loaded ??= readVocabulary());
+const loaded = new Map();
+/** The vocabulary of a folder (the shipped one by default), read once per folder on first use: reading 6 MB of JSON is not free, and most commands never project. `dir` is for a caller that cannot locate the folder itself. */
+export const vocabulary = (dir = vocabDir()) => {
+    const held = loaded.get(dir.href);
+    if (held !== undefined)
+        return held;
+    const read = readVocabulary(dir);
+    loaded.set(dir.href, read);
+    return read;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "mcpName": "io.github.manyoars/oars",
   "description": "A local, searchable record of your coding agent sessions. Reads Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, and more, and keeps the record on your machine.",
   "homepage": "https://manyoars.com/",
@@ -49,7 +49,7 @@
     "test:live": "vitest run --config vitest.live.config.ts"
   },
   "dependencies": {
-    "@manyoars/oars-client": "^0.1.2",
+    "@manyoars/oars-client": "^0.1.3",
     "commander": "^15.0.0",
     "openid-client": "^6.8.8"
   },