@quickchatai/pi-quickreview 1.2.0 → 1.3.2

package/dist/src/scan/scanfs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanfs.js","sourceRoot":"","sources":["../../../src/scan/scanfs.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,kEAAkE;AAClE,sEAAsE;AACtE,uEAAuE;AACvE,uEAAuE;AACvE,0BAA0B;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,MAAM,EACN,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhE;6DAC6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1C,sEAAsE;AACtE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,MAAM;IACN,cAAc;IACd,OAAO;IACP,MAAM;IACN,aAAa;IACb,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH;;;sCAGsC;AACtC,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,GAAW;IACvC,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,CAAC,IAAc,EAAiB,EAAE;QAC5C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,kBAAkB,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;gBAChF,QAAQ,EAAE,MAAM;gBAChB,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;gBAC5B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;aACpC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,2EAA2E;IAC3E,mEAAmE;IACnE,wEAAwE;IACxE,4EAA4E;IAC5E,+CAA+C;IAC/C,MAAM,IAAI,GAAG,GAAoB,EAAE;QACjC,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,GAAW,EAAW,EAAE;YACrC,IAAI,KAAe,CAAC;YACpB,IAAI,CAAC;gBACH,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,SAAS;gBAClC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC7B,IAAI,EAAE,CAAC;gBACP,IAAI,CAAC;oBACH,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;oBAC1B,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;wBACpB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;4BAAE,OAAO,KAAK,CAAC;wBAC/B,SAAS;oBACX,CAAC;oBACD,EAAE,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC/C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;wBAAE,OAAO,KAAK,CAAC;oBACnE,SAAS,CAAC,gCAAgC;gBAC5C,CAAC;gBACD,IAAI,EAAE,CAAC,MAAM,EAAE;oBAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACvE,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QACF,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;gBAAE,OAAO,IAAI,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAClC,CAAC,CAAC;IACF,wEAAwE;IACxE,yCAAyC;IACzC,IAAI,QAAmC,CAAC;IACxC,MAAM,YAAY,GAAG,GAAkB,EAAE;QACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAiB,EAAE;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC/B,IAAI,CAAC;YACH,oEAAoE;YACpE,2DAA2D;YAC3D,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;YAC3B,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC5E,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,cAAc;gBAAE,OAAO,IAAI,CAAC;YAC1D,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC,CAAC,gCAAgC;YAC5E,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,GAAG,EAAE;YACd,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;YACvC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACvE,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE;YACb,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI;QACtD,YAAY,EAAE,GAAG,EAAE;YACjB,qEAAqE;YACrE,8DAA8D;YAC9D,MAAM,GAAG,GAAG,GAAG,CAAC;gBACd,KAAK;gBACL,kBAAkB;gBAClB,aAAa;gBACb,IAAI;gBACJ,MAAM,CAAC,kBAAkB,CAAC;gBAC1B,aAAa;gBACb,IAAI;gBACJ,WAAW;aACZ,CAAC,CAAC;YACH,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC9B,MAAM,MAAM,GAA2B,EAAE,CAAC;YAC1C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,EAAE;oBAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;8CAC8C;AAC9C,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;wBAEwB;AACxB,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY;IACxC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE;QACtC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QACrF,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE;YACZ,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,IAAI,CAAC;gBAClE,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACnB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,GAAG,GAAG,IAAI,CACd,OAAO,CAAC,IAAI,CAAC,EACb,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAClF,CAAC;YACF,IAAI,CAAC;gBACH,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACzB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC7B,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/scan/scanlease.d.ts

@@ -0,0 +1,50 @@
+export declare const DRIVER_DIR = "scan/driver";
+/** How often a driving runner renews its lease. */
+export declare const LEASE_RENEW_MS = 5000;
+/** A lease not renewed for this long has lapsed. */
+export declare const LEASE_TTL_MS = 30000;
+export interface LeaseRecord {
+    holder: string;
+    /** The run it drives; null while a start is still planning. */
+    run: string | null;
+    pid: number;
+    host: string;
+    at: string;
+}
+/** The lease port a ScanRunner drives. */
+export interface ScanLease {
+    /** This runner's holder id. */
+    readonly holder: string;
+    /** Take the lease for `run` — or renew it when this runner holds it
+     * already; false when another live holder has it, or another claim won. */
+    claim(run: string | null): boolean;
+    /** Renew the lease this runner holds; false when it holds none any more. */
+    renew(run: string | null): boolean;
+    /** Give the lease up — only when this runner still holds it. */
+    release(): void;
+    /** Why the last claim failed, when it was not another holder's live lease. */
+    readonly lastError: string | null;
+    /** The live lease of ANOTHER holder, or null. */
+    other(): LeaseRecord | null;
+}
+/** The current lease record under the state home `home`, live or not —
+ * null when there is none or it cannot be read. For a reader that holds
+ * none (the TUI), which judges it with `leaseIsLive`. */
+export declare function currentLease(home: string): LeaseRecord | null;
+export declare const leaseIsLive: (r: LeaseRecord, now?: Date) => boolean;
+/** The live lease under the state home `home`, or null. */
+export declare function liveLease(home: string, now?: Date): LeaseRecord | null;
+/** The lease as generation files under the state home `home`. Total: a
+ * failed write is a failed claim or renewal, never a throw. */
+export declare function fileLease(home: string, opts?: {
+    clock?: () => Date;
+    holder?: string;
+    /** Called between reading the lease and creating the next generation. */
+    beforeCreate?: () => void;
+    /** Called right after generation `gen` was created, before the check
+     * that no newer one appeared. */
+    afterCreate?: (gen: number) => void;
+    /** The hard link (`fs.linkSync`). */
+    link?: (existing: string, path: string) => void;
+}): ScanLease;
+//# sourceMappingURL=scanlease.d.ts.map

package/dist/src/scan/scanlease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanlease.d.ts","sourceRoot":"","sources":["../../../src/scan/scanlease.ts"],"names":[],"mappings":"AA8CA,eAAO,MAAM,UAAU,gBAAgB,CAAC;AACxC,mDAAmD;AACnD,eAAO,MAAM,cAAc,OAAQ,CAAC;AACpC,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;+EAC2E;IAC3E,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;IACnC,4EAA4E;IAC5E,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;IACnC,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iDAAiD;IACjD,KAAK,IAAI,WAAW,GAAG,IAAI,CAAC;CAC7B;AAmED;;yDAEyD;AACzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE7D;AAED,eAAO,MAAM,WAAW,GAAI,GAAG,WAAW,EAAE,MAAK,IAAiB,KAAG,OAAyB,CAAC;AAE/F,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,GAAG,IAAI,CAGlF;AAED;+DAC+D;AAC/D,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IACJ,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;qCACiC;IACjC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,qCAAqC;IACrC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C,GACL,SAAS,CA2HX"}

package/dist/src/scan/scanlease.js

@@ -0,0 +1,251 @@
+// The scan driver lease: which process drives the scan in flight, across
+// processes. A ScanRunner knows its OWN run (`active`); a run recorded as
+// `running` that this runner does not drive is either interrupted or driven
+// by another process sharing the state home — the companion, or a
+// `qcr scan start` driver. The lease tells them apart: the driving runner
+// holds it and renews it while it drives; a holder that stopped renewing
+// (killed, its machine asleep) has let it lapse, and its run reads as
+// interrupted again.
+//
+// The lease is a sequence of GENERATIONS, `scan/driver/<n>.json`, the highest
+// one current. A claim creates the next generation with an exclusive create
+// (the record is written aside and hard-linked into place, which fails when
+// the name exists — or, on a filesystem that refuses hard links, an O_EXCL
+// create), so of any number of processes claiming at once exactly one wins
+// each generation; the winner then checks no newer generation appeared before
+// it takes the lease. A holder renews only its own generation; once a newer
+// one exists (its lease lapsed and was taken over) it no longer holds the
+// lease, and renewal says so. An unreadable current generation (an O_EXCL
+// create not yet written, or a corrupt file) counts as live until its file is
+// as old as the lease's life, then as no lease. A claim prunes every
+// generation but the one before its own, and temp files older than the
+// lease's life.
+//
+// What the lease does NOT serialise: the records other processes may write
+// while a run is driven elsewhere. `qcr scan match` / `dismiss` and the
+// companion's triage rewrite `scan/findings.json`, and a driver's reconcile
+// does too, each as a fresh read, a change and a write — between one
+// process's read and its write another's write can be lost. The run record
+// `scan/run.json` is written only by the lease holder; a holder that lost the
+// lease stops its run and writes it no more (scanrun.ts).
+//
+// A leaf: node built-ins only, so the TUI's scan tab reads the lease too.
+import { randomUUID } from "node:crypto";
+import { linkSync, statSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+export const DRIVER_DIR = "scan/driver";
+/** How often a driving runner renews its lease. */
+export const LEASE_RENEW_MS = 5_000;
+/** A lease not renewed for this long has lapsed. */
+export const LEASE_TTL_MS = 30_000;
+function parse(text) {
+    try {
+        const r = JSON.parse(text);
+        if (typeof r.holder !== "string" || typeof r.at !== "string")
+            return null;
+        return {
+            holder: r.holder,
+            run: typeof r.run === "string" ? r.run : null,
+            pid: typeof r.pid === "number" ? r.pid : 0,
+            host: typeof r.host === "string" ? r.host : "",
+            at: r.at,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const GEN = /^(\d+)\.json$/;
+/** Has the file at `path` been written within the lease's life? Files carry
+ * the real clock's mtime, so this reads the real clock. */
+function fresh(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs < LEASE_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+const errText = (err) => err instanceof Error
+    ? `${err.code ?? "error"}: ${err.message}`
+    : String(err);
+/** Where a hard link is refused rather than the name taken. */
+const NO_LINK = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+/** The current generation and its record (null: unreadable), or null when
+ * there is no lease at all. */
+function current(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const gens = names.flatMap((n) => {
+        const m = GEN.exec(n);
+        return m ? [Number(m[1])] : [];
+    });
+    if (gens.length === 0)
+        return null;
+    const gen = Math.max(...gens);
+    let record = null;
+    try {
+        record = parse(readFileSync(join(dir, `${gen}.json`), "utf8"));
+    }
+    catch {
+        record = null;
+    }
+    return { gen, record };
+}
+const isLive = (r, now) => {
+    const at = Date.parse(r.at);
+    return Number.isFinite(at) && now.getTime() - at < LEASE_TTL_MS;
+};
+/** The current lease record under the state home `home`, live or not —
+ * null when there is none or it cannot be read. For a reader that holds
+ * none (the TUI), which judges it with `leaseIsLive`. */
+export function currentLease(home) {
+    return current(join(home, DRIVER_DIR))?.record ?? null;
+}
+export const leaseIsLive = (r, now = new Date()) => isLive(r, now);
+/** The live lease under the state home `home`, or null. */
+export function liveLease(home, now = new Date()) {
+    const r = currentLease(home);
+    return r && isLive(r, now) ? r : null;
+}
+/** The lease as generation files under the state home `home`. Total: a
+ * failed write is a failed claim or renewal, never a throw. */
+export function fileLease(home, opts = {}) {
+    const dir = join(home, DRIVER_DIR);
+    const clock = opts.clock ?? (() => new Date());
+    const holder = opts.holder ?? `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+    const link = opts.link ?? linkSync;
+    let mine = null;
+    let lastError = null;
+    const record = (run, at = clock()) => `${JSON.stringify({ holder, run, pid: process.pid, host: hostname(), at: at.toISOString() })}\n`;
+    // Only its holder rewrites a generation: tmp + rename.
+    const rewrite = (gen, text) => {
+        const tmp = join(dir, `.${gen}.${randomUUID()}.tmp`);
+        try {
+            writeFileSync(tmp, text);
+            renameSync(tmp, join(dir, `${gen}.json`));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const prune = (below) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const m = GEN.exec(name);
+            const stale = (m !== null && Number(m[1]) < below) ||
+                (name.startsWith(".") && name.endsWith(".tmp") && !fresh(join(dir, name)));
+            if (!stale)
+                continue;
+            try {
+                unlinkSync(join(dir, name));
+            }
+            catch {
+                // Another claimer pruned it first.
+            }
+        }
+    };
+    /** Create generation `gen` exclusively; null, or why not. */
+    const create = (gen, text) => {
+        const path = join(dir, `${gen}.json`);
+        const tmp = join(dir, `.claim.${randomUUID()}.tmp`);
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(tmp, text);
+            try {
+                link(tmp, path);
+                return null;
+            }
+            catch (err) {
+                if (!NO_LINK.has(err.code ?? ""))
+                    throw err;
+            }
+            writeFileSync(path, text, { flag: "wx" });
+            return null;
+        }
+        catch (err) {
+            return errText(err);
+        }
+        finally {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                // Never written.
+            }
+        }
+    };
+    const lease = {
+        holder,
+        get lastError() {
+            return lastError;
+        },
+        claim(run) {
+            lastError = null;
+            const cur = current(dir);
+            if (cur !== null && mine === cur.gen)
+                return lease.renew(run);
+            if (cur !== null && cur.record === null && fresh(join(dir, `${cur.gen}.json`))) {
+                lastError = `generation ${cur.gen} is unreadable and was written within the lease's life — it may still be being written`;
+                return false;
+            }
+            if (cur?.record && cur.record.holder !== holder && isLive(cur.record, clock()))
+                return false;
+            opts.beforeCreate?.();
+            const gen = (cur?.gen ?? 0) + 1;
+            const failed = create(gen, record(run));
+            if (failed !== null) {
+                lastError = `generation ${gen} could not be created (${failed})`;
+                return false;
+            }
+            opts.afterCreate?.(gen);
+            // Won the create; still the newest?
+            if (current(dir)?.gen !== gen) {
+                lastError = `a newer generation than ${gen} appeared as it was created`;
+                return false;
+            }
+            mine = gen;
+            prune(gen - 1);
+            return true;
+        },
+        renew(run) {
+            const cur = current(dir);
+            if (mine === null ||
+                cur === null ||
+                cur.gen !== mine ||
+                cur.record === null ||
+                !isLive(cur.record, clock())) {
+                mine = null;
+                return false;
+            }
+            return rewrite(mine, record(run));
+        },
+        release() {
+            const cur = current(dir);
+            if (mine !== null && cur !== null && cur.gen === mine)
+                rewrite(mine, record(null, new Date(0)));
+            mine = null;
+        },
+        other() {
+            const cur = current(dir);
+            if (cur === null || cur.record === null || cur.gen === mine)
+                return null;
+            return isLive(cur.record, clock()) ? cur.record : null;
+        },
+    };
+    return lease;
+}
+//# sourceMappingURL=scanlease.js.map

package/dist/src/scan/scanlease.js.map

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

package/dist/src/scan/scanleaves.d.ts

@@ -0,0 +1,55 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { CaseRunner } from "./scanports.js";
+import type { Runtime, SessionSpec } from "../engine/port.js";
+import type { SessionExtras } from "../engine/sdkruntime.js";
+/** A leaf turn's hard wall clock. The login's own case budget
+ * (`SCAN_CASE_AUTH_BUDGET_MS`) is the usual bound and aborts first; this one
+ * only backs it where no login budget applies, and is kept past it so the
+ * budget's last-resort step (it ends the process) never races the abort. */
+export declare const LEAF_TURN_TIMEOUT_MS: number;
+/** The per-session pieces the runner hands whoever builds the runtime: the
+ * `extras` of `sdkRuntime` (packages/pi-plugin/src/engine/sdkruntime.ts). */
+export type LeafExtras = (spec: SessionSpec) => SessionExtras;
+export interface SdkCaseRunnerOptions {
+    /** The scan agent build: `<agent>.md` files. */
+    agentsDir: string;
+    /** The leaf's working directory: first-party ground, never the reviewed
+     * checkout (whose own pi config must not load). Also what a relative read is
+     * resolved against. */
+    cwd: string;
+    /** Where each case's event stream is kept; absent, none is. */
+    transcriptDir?: string;
+    /** The env the leaf's env is filtered from. */
+    env: NodeJS.ProcessEnv;
+    /** The user's home: a read's `~` expands against it. */
+    home: string;
+    /** The model of an agent that names none. */
+    defaultModel?: string;
+    /** The runtime this case runs on, built with the case's `extras`. Called once
+     * per case: a route that must re-read its login per case builds its host
+     * here. */
+    runtime: (extras: LeafExtras) => Runtime | Promise<Runtime>;
+    /** The guard extension. Omitted: bash-guard over the leaf env. */
+    guard?: ExtensionFactory;
+    /** Wall clock for a case's turn. Omitted: `LEAF_TURN_TIMEOUT_MS`. */
+    timeoutMs?: number;
+}
+/** Where a case's session JSONL goes: `<run>/lens-sessions/<case>/` beside the
+ * transcript `rel` names (`<run>/<case>.jsonl`). */
+export declare function caseSessionDir(transcriptDir: string, rel: string): string;
+/**
+ * Runs a case as one SDK session, the way `piCaseRunner` runs it as one child:
+ * the agent's model (its `:thinking` suffix as the session's thinking level),
+ * its tools, its body appended to pi's system prompt, the task as the one
+ * message. The answer is the last assistant message's text; the cost is pi's
+ * own per-message accounting summed (null when it reported none); `reads` is the
+ * `read`/`grep` calls that finished without an error, resolved against `cwd`.
+ * With `transcriptDir` the session's whole event stream is kept at
+ * `transcriptFile(spec.id)` under it, the format `pi --mode json` prints, and
+ * its session JSONL beside it (`caseSessionDir`). An
+ * abort stops the session (abort, then dispose after the stop grace). Every
+ * outcome resolves — a runtime that cannot be built or a session that cannot
+ * start is a failed case, never a rejection.
+ */
+export declare function sdkCaseRunner(opts: SdkCaseRunnerOptions): CaseRunner;
+//# sourceMappingURL=scanleaves.d.ts.map

package/dist/src/scan/scanleaves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanleaves.d.ts","sourceRoot":"","sources":["../../../src/scan/scanleaves.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAexE,OAAO,KAAK,EAAe,UAAU,EAAY,MAAM,gBAAgB,CAAC;AAExE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;4EAG4E;AAC5E,eAAO,MAAM,oBAAoB,QAAyC,CAAC;AAqB3E;6EAC6E;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,aAAa,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;2BAEuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;eAEW;IACX,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,kEAAkE;IAClE,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoBD;oDACoD;AACpD,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,UAAU,CA6KpE"}

package/dist/src/scan/scanleaves.js

@@ -0,0 +1,258 @@
+// The scan's leaf runner on the SDK: the `CaseRunner` port
+// (scanports.ts) over the runtime port, the in-process twin of
+// `piCaseRunner` (caserunner.ts). One case is one session on the
+// runtime, with the same pieces the child process gets: the agent file's model,
+// tools and body (appended to pi's own system prompt), bash-guard the one
+// extension, no skill and no context file, a cwd that is first-party ground and
+// never the reviewed checkout, and the allowlisted env. The outcome, the reads
+// and the kept transcript are read off the same event stream by the same
+// reader (`caseReadout`), so a case answers identically whichever host ran it.
+//
+// It builds no host: the runtime a case runs on is the caller's (`runtime`),
+// so this module loads no SDK. Two hosts hand one in: the `qcr scan` driver,
+// a disposable one-scan process (src/engine/caserunner-sdk.ts
+// `scanSdkCases`), and the pi plugin's /qcr-scan, inside the person's own pi.
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { bashGuardConfigFromEnv, createBashGuard } from "../../extensions/bash-guard.js";
+import { CASE_STOP_GRACE_MS } from "../casebudget.js";
+import { splitModelSpec } from "../reviewconfig.js";
+import { AuthError, SCAN_CASE_AUTH_BUDGET_MS } from "../engine/auth.js";
+import { TRANSCRIPT_RUNS_KEPT, caseReadout, leafEnv, parseAgentFile, pruneTranscripts, stderrExcerpt, transcriptFile, } from "./caseread.js";
+import { LENS_SESSIONS_DIR } from "../engine/openable.js";
+/** A leaf turn's hard wall clock. The login's own case budget
+ * (`SCAN_CASE_AUTH_BUDGET_MS`) is the usual bound and aborts first; this one
+ * only backs it where no login budget applies, and is kept past it so the
+ * budget's last-resort step (it ends the process) never races the abort. */
+export const LEAF_TURN_TIMEOUT_MS = SCAN_CASE_AUTH_BUDGET_MS + 15 * 60_000;
+/** What the model's bash may draw from the leaf env, beyond pi's defaults:
+ * certificates, proxies, XDG dirs and the temp dirs. Never a provider key. */
+const LEAF_BASH_ENV_ALLOW = [
+    "TMP",
+    "TEMP",
+    "XDG_*",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "NODE_EXTRA_CA_CERTS",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "all_proxy",
+];
+/** A transcript's path under `dir`, relative and absolute, with its run
+ * directory made (and the old runs pruned when it is new); null when it cannot
+ * be made. A transcript is evidence, never a reason to fail a case. */
+function openTranscript(dir, id) {
+    try {
+        const rel = transcriptFile(id);
+        const at = join(dir, rel);
+        const runDir = rel.includes("/") ? rel.slice(0, rel.indexOf("/")) : null;
+        const fresh = runDir !== null && !existsSync(join(dir, runDir));
+        mkdirSync(dirname(at), { recursive: true });
+        if (fresh)
+            pruneTranscripts(dir, TRANSCRIPT_RUNS_KEPT, runDir);
+        writeFileSync(at, "", { mode: 0o600 });
+        return { rel, at };
+    }
+    catch {
+        return null;
+    }
+}
+/** Where a case's session JSONL goes: `<run>/lens-sessions/<case>/` beside the
+ * transcript `rel` names (`<run>/<case>.jsonl`). */
+export function caseSessionDir(transcriptDir, rel) {
+    return join(transcriptDir, dirname(rel), LENS_SESSIONS_DIR, basename(rel, ".jsonl"));
+}
+/**
+ * Runs a case as one SDK session, the way `piCaseRunner` runs it as one child:
+ * the agent's model (its `:thinking` suffix as the session's thinking level),
+ * its tools, its body appended to pi's system prompt, the task as the one
+ * message. The answer is the last assistant message's text; the cost is pi's
+ * own per-message accounting summed (null when it reported none); `reads` is the
+ * `read`/`grep` calls that finished without an error, resolved against `cwd`.
+ * With `transcriptDir` the session's whole event stream is kept at
+ * `transcriptFile(spec.id)` under it, the format `pi --mode json` prints, and
+ * its session JSONL beside it (`caseSessionDir`). An
+ * abort stops the session (abort, then dispose after the stop grace). Every
+ * outcome resolves — a runtime that cannot be built or a session that cannot
+ * start is a failed case, never a rejection.
+ */
+export function sdkCaseRunner(opts) {
+    return {
+        run: async (spec, signal, onCost) => {
+            if (!/^[a-z][a-z0-9-]*$/.test(spec.agent))
+                return {
+                    ok: false,
+                    reason: `not an agent name: ${JSON.stringify(spec.agent)}`,
+                    cost_usd: 0,
+                };
+            let agent;
+            try {
+                agent = parseAgentFile(readFileSync(join(opts.agentsDir, `${spec.agent}.md`), "utf8"));
+            }
+            catch {
+                return { ok: false, reason: `no agent ${spec.agent} in ${opts.agentsDir}`, cost_usd: 0 };
+            }
+            if (agent === null || agent.name !== spec.agent)
+                return { ok: false, reason: `${spec.agent}.md is not an agent file`, cost_usd: 0 };
+            const modelSpec = agent.model ?? opts.defaultModel;
+            if (!modelSpec)
+                return { ok: false, reason: `${spec.agent} names no model and none is set`, cost_usd: 0 };
+            if (signal.aborted)
+                return { ok: false, reason: "stopped before it started", cost_usd: 0 };
+            let tmp;
+            try {
+                tmp = mkdtempSync(join(tmpdir(), "qcr-case-"));
+            }
+            catch (err) {
+                return { ok: false, reason: `no temp directory for the case: ${String(err)}`, cost_usd: 0 };
+            }
+            let session;
+            try {
+                const env = leafEnv(opts.env);
+                const { model, thinking } = splitModelSpec(modelSpec);
+                const guard = opts.guard ?? createBashGuard(bashGuardConfigFromEnv(env, opts.cwd));
+                const extras = () => ({
+                    extensions: [guard],
+                    appendSystemPrompt: [agent.systemPrompt],
+                    bashEnv: { allow: LEAF_BASH_ENV_ALLOW },
+                    ...(thinking !== null
+                        ? { thinkingLevel: thinking }
+                        : {}),
+                });
+                // The transcript: opened before the session, appended event by event,
+                // abandoned (and its name dropped from the outcome) at the first write
+                // that fails.
+                const opened = opts.transcriptDir !== undefined ? openTranscript(opts.transcriptDir, spec.id) : null;
+                const sessionSpec = {
+                    cwd: opts.cwd,
+                    env,
+                    model,
+                    ...(agent.tools.length > 0 ? { tools: agent.tools } : {}),
+                    name: spec.id,
+                    // The case's session JSONL beside its transcript, so the case
+                    // opens in pi: `qcr open <run dir> --lens <case>`.
+                    ...(opts.transcriptDir !== undefined && opened !== null
+                        ? { sessionDir: caseSessionDir(opts.transcriptDir, opened.rel) }
+                        : {}),
+                    eventsFile: join(tmp, "events.jsonl"),
+                    stderrFile: join(tmp, "stderr.txt"),
+                    limits: { timeoutMs: opts.timeoutMs ?? LEAF_TURN_TIMEOUT_MS },
+                };
+                let transcript = opened?.rel;
+                let transcriptAt = opened?.at ?? null;
+                const keep = (event) => {
+                    if (transcriptAt === null)
+                        return;
+                    try {
+                        appendFileSync(transcriptAt, JSON.stringify(event) + "\n");
+                    }
+                    catch {
+                        transcriptAt = null;
+                        transcript = undefined;
+                    }
+                };
+                const readout = caseReadout(opts.cwd, opts.home, onCost);
+                const finish = (o) => transcript === undefined ? o : { ...o, transcript };
+                try {
+                    const runtime = await opts.runtime(extras);
+                    session = await runtime.create(sessionSpec);
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    // A refused login already says what to do; anything else is the host's.
+                    return {
+                        ok: false,
+                        reason: err instanceof AuthError ? reason : `could not start the session: ${reason}`,
+                        cost_usd: 0,
+                    };
+                }
+                session.subscribe((event) => {
+                    keep(event);
+                    readout.feed(event);
+                });
+                let stopped = false;
+                let hardStop;
+                const gone = new Promise((resolve) => {
+                    hardStop = resolve;
+                });
+                const onAbort = () => {
+                    stopped = true;
+                    const live = session;
+                    void live?.abort().catch(() => { });
+                    // The stop grace, then the session is released; a turn still not
+                    // settled a grace later is given up on, so the case resolves.
+                    setTimeout(() => void live?.dispose().catch(() => { }), CASE_STOP_GRACE_MS).unref();
+                    setTimeout(() => hardStop?.({ ok: false, reason: "stopped", cost_usd: readout.spent() }), 2 * CASE_STOP_GRACE_MS).unref();
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                if (signal.aborted) {
+                    onAbort();
+                    // Cancelled while the session was being created: no turn starts.
+                    return finish({ ok: false, reason: "stopped", cost_usd: 0 });
+                }
+                const turn = (async () => {
+                    let result;
+                    try {
+                        result = await session.prompt(`Task: ${spec.prompt}`);
+                    }
+                    catch (err) {
+                        return {
+                            ok: false,
+                            reason: `the session failed: ${err instanceof Error ? err.message : String(err)}`,
+                            cost_usd: readout.spent(),
+                        };
+                    }
+                    // What a case that ended without an answer had spent: a failure costs
+                    // money too, and a caller holding a budget must count it.
+                    const cost_usd = readout.spent();
+                    if (stopped)
+                        return { ok: false, reason: "stopped", cost_usd };
+                    if (result.timedOut)
+                        return { ok: false, reason: "the case ran past its wall clock", cost_usd };
+                    // The model's own reason leads: a provider error also ends the turn non-zero.
+                    if (readout.failure !== null)
+                        return { ok: false, reason: readout.failure, cost_usd };
+                    if (result.code !== 0) {
+                        let tail = "";
+                        try {
+                            tail = stderrExcerpt(readFileSync(sessionSpec.stderrFile, "utf8"));
+                        }
+                        catch {
+                            // No stderr to quote.
+                        }
+                        return {
+                            ok: false,
+                            reason: `the session ended without a result${tail ? `: ${tail}` : ""}`,
+                            cost_usd,
+                        };
+                    }
+                    if (readout.final.trim() === "")
+                        return { ok: false, reason: "the subagent gave no answer", cost_usd };
+                    return { ok: true, output: readout.final, cost_usd, reads: readout.reads };
+                })();
+                try {
+                    return finish(await Promise.race([turn, gone]));
+                }
+                finally {
+                    signal.removeEventListener("abort", onAbort);
+                }
+            }
+            finally {
+                try {
+                    await session?.dispose();
+                }
+                catch {
+                    // Already released.
+                }
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        },
+    };
+}
+//# sourceMappingURL=scanleaves.js.map