@verax-ai/proxy 0.3.0 → 0.4.0

package/README.md

@@ -29,7 +29,12 @@ import { createProxy, loadPolicy, FileLedger, explain } from "@verax-ai/proxy";
 ```
 
 - `loadPolicy` reads a policy file. `policy/default.json` in this package is
-  the one the body starts from.
+  the one the body starts from. Two rules with the same `id`, or two rules for
+  the same `tool`, are refused at load and the error names both ids.
+- A `spend` rule may set `dayOffsetMinutes` (integer, −720..840, default 0).
+  The daily cap buckets `createdAtMs` shifted by that many minutes, so 0 is a
+  UTC day and 180 is the operator's day in UTC+3. Approval re-checks the same
+  bucket.
 - `createProxy` wraps tool functions: each call is decided and recorded, then
   run or refused.
 - `FileLedger` and `MemoryLedger` hold the records, one `FileLedger` per

package/dist/approvals.d.ts

@@ -22,6 +22,8 @@ export type ApprovalRow = {
     payee?: unknown;
     currency?: unknown;
     createdAtMs?: number;
+    /** Set when the row becomes approved. Missing on older files: those count toward today. */
+    approvedAtMs?: number;
     expiresAtMs: number;
     status: "pending" | "approved" | "expired";
     brain: string;
@@ -34,6 +36,7 @@ export type ApprovalsLog = {
     listAll(): Promise<ApprovalRow[]>;
     updateStatus(ref: string, status: "approved" | "expired", extra?: {
         allowRef?: string;
+        approvedAtMs?: number;
     }): Promise<void>;
 };
 export declare class MemoryApprovalsLog implements ApprovalsLog {
@@ -45,6 +48,7 @@ export declare class MemoryApprovalsLog implements ApprovalsLog {
     listAll(): Promise<ApprovalRow[]>;
     updateStatus(ref: string, status: "approved" | "expired", extra?: {
         allowRef?: string;
+        approvedAtMs?: number;
     }): Promise<void>;
 }
 export declare class FileApprovalsLog implements ApprovalsLog {
@@ -57,6 +61,7 @@ export declare class FileApprovalsLog implements ApprovalsLog {
     listAll(): Promise<ApprovalRow[]>;
     updateStatus(ref: string, status: "approved" | "expired", extra?: {
         allowRef?: string;
+        approvedAtMs?: number;
     }): Promise<void>;
     private read;
 }
@@ -74,18 +79,20 @@ export declare function spentTodayMinorOf(rows: Array<{
     subject: string;
     status: string;
     createdAtMs?: number;
+    approvedAtMs?: number;
     expiresAtMs: number;
     args: Record<string, unknown>;
-}>, nowMs: number, currency: string, approvalTtlMs: number): number;
+}>, nowMs: number, currency: string, approvalTtlMs: number, dayOffsetMinutes?: number): number;
 export declare function createApprovalBudgetGuard(opts: {
     policy: Policy;
     approvals: ApprovalsLog;
     now: () => number;
+    ledger: Ledger;
 }): (snap: ApprovalRow) => Promise<{
     ok: true;
 } | {
     ok: false;
-    reason: "budget-exceeded";
+    reason: "budget-exceeded" | "rule-missing";
 }>;
 export declare function approvePending(opts: {
     ledger: Ledger;
@@ -103,18 +110,20 @@ export declare function approvePending(opts: {
         ok: true;
     } | {
         ok: false;
-        reason: "budget-exceeded";
+        reason: "budget-exceeded" | "rule-missing";
     } | Promise<{
         ok: true;
     } | {
         ok: false;
-        reason: "budget-exceeded";
+        reason: "budget-exceeded" | "rule-missing";
     }>;
 }): Promise<ApproveResult>;
 export type ApprovalCommand = {
     ref: string;
     approverId: string;
     atMs: number;
+    /** Absent on a command written before this field existed; drain applies that as `cli-script`. */
+    via?: "cli" | "cli-script";
 };
 export declare function enqueueApprovalCommand(dir: string, cmd: ApprovalCommand): void;
 export declare function drainApprovalCommands(dir: string, apply: (cmd: ApprovalCommand) => Promise<void>): Promise<void>;

package/dist/approvals.js

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, } from "node:fs";
+import { appendFileSync, closeSync, constants, existsSync, fchownSync, fstatSync, lstatSync, openSync, readdirSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
 /** I/O seam so drain-busy tests can inject rename failures. */
 export const approvalFs = {
     renameSync,
@@ -10,6 +10,14 @@ import { appendDurable, lookupDecisionByRef, lookupResolvedBy, noteResolution }
 import { effectDescriptor, sha256Canonical } from "./hash.js";
 import { inputsLogFor } from "./inputs.js";
 import { SerialQueue } from "./serial-queue.js";
+function withStatus(cur, status, extra) {
+    return {
+        ...cur,
+        status,
+        ...(extra?.allowRef !== undefined ? { allowRef: extra.allowRef } : {}),
+        ...(typeof extra?.approvedAtMs === "number" ? { approvedAtMs: extra.approvedAtMs } : {}),
+    };
+}
 function lastByRef(rows) {
     const map = new Map();
     for (const row of rows)
@@ -45,7 +53,7 @@ export class MemoryApprovalsLog {
         const cur = this.byRef.get(ref);
         if (!cur)
             return;
-        await this.append({ ...cur, status, ...(extra?.allowRef !== undefined ? { allowRef: extra.allowRef } : {}) });
+        await this.append(withStatus(cur, status, extra));
     }
 }
 export class FileApprovalsLog {
@@ -73,7 +81,7 @@ export class FileApprovalsLog {
         const cur = this.byRef.get(ref);
         if (!cur)
             return;
-        await this.append({ ...cur, status, ...(extra?.allowRef !== undefined ? { allowRef: extra.allowRef } : {}) });
+        await this.append(withStatus(cur, status, extra));
     }
     read() {
         try {
@@ -113,19 +121,30 @@ function approvalLockFor(ledger) {
         bag[APPROVAL_LOCK] = new SerialQueue();
     return bag[APPROVAL_LOCK];
 }
-export function spentTodayMinorOf(rows, nowMs, currency, approvalTtlMs) {
-    const d = new Date(nowMs);
-    const start = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+export function spentTodayMinorOf(rows, nowMs, currency, approvalTtlMs, dayOffsetMinutes = 0) {
+    const shift = dayOffsetMinutes * 60_000;
+    const d = new Date(nowMs + shift);
+    const start = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) - shift;
     const end = start + 86_400_000;
     let sum = 0;
     for (const row of rows) {
         if (row.subject !== "spend")
             continue;
-        if (row.status !== "pending" && row.status !== "approved")
-            continue;
-        const created = row.createdAtMs ?? row.expiresAtMs - approvalTtlMs;
-        if (created < start || created >= end)
+        if (row.status === "approved") {
+            // Bucket by approval time. A row written before this field existed has
+            // no approvedAtMs and counts toward the day being checked.
+            if (typeof row.approvedAtMs === "number" && (row.approvedAtMs < start || row.approvedAtMs >= end)) {
+                continue;
+            }
+        }
+        else if (row.status === "pending") {
+            const created = row.createdAtMs ?? row.expiresAtMs - approvalTtlMs;
+            if (created < start || created >= end)
+                continue;
+        }
+        else {
             continue;
+        }
         if (row.args.currency !== currency)
             continue;
         const amt = row.args.amountMinor;
@@ -138,16 +157,44 @@ export function createApprovalBudgetGuard(opts) {
     return async (snap) => {
         if (snap.subject !== "spend")
             return { ok: true };
-        const dailyMax = opts.policy.rule(snap.ruleId)?.spend?.dailyMaxMinor;
+        const rule = opts.policy.rule(snap.ruleId);
+        // A missing rule is not an uncapped rule. A rule that exists and names no
+        // dailyMaxMinor is the policy's choice to leave that spend uncapped.
+        if (rule === null)
+            return { ok: false, reason: "rule-missing" };
+        const dailyMax = rule.spend?.dailyMaxMinor;
         if (dailyMax === undefined)
             return { ok: true };
         const currency = typeof snap.args.currency === "string" ? snap.args.currency : "";
         const amount = typeof snap.args.amountMinor === "number" ? snap.args.amountMinor : 0;
         // Sibling pending rows are not authorized yet. Counting them here would
-        // deadlock two 100-unit pendings against a later 150 cap; approved spend
-        // plus this amount is what the operator is about to commit.
-        const others = (await opts.approvals.listAll()).filter((row) => row.ref !== snap.ref && row.status === "approved");
-        const spent = spentTodayMinorOf(others, opts.now(), currency, opts.policy.approvalTtlMs);
+        // deadlock two 100-unit pendings against a later 150 cap. A pending row
+        // whose ref the ledger already resolved as allow was authorized; the
+        // approvals file may still say pending if the process stopped before
+        // updateStatus. That row counts. Other pendings do not.
+        const listed = await opts.approvals.listAll();
+        const others = [];
+        for (const row of listed) {
+            if (row.ref === snap.ref)
+                continue;
+            if (row.status === "approved") {
+                others.push(row);
+                continue;
+            }
+            if (row.status !== "pending" || row.subject !== "spend")
+                continue;
+            const hit = lookupResolvedBy(opts.ledger, row.ref);
+            if (hit?.kind !== "allow")
+                continue;
+            const allow = await lookupDecisionByRef(opts.ledger, hit.ref);
+            others.push({
+                ...row,
+                status: "approved",
+                ...(typeof allow?.timestampMs === "number" ? { approvedAtMs: allow.timestampMs } : {}),
+            });
+        }
+        const offset = opts.policy.rule(snap.ruleId)?.spend?.dayOffsetMinutes ?? opts.policy.dayOffsetMinutes ?? 0;
+        const spent = spentTodayMinorOf(others, opts.now(), currency, opts.policy.approvalTtlMs, offset);
         if (spent + amount > dailyMax)
             return { ok: false, reason: "budget-exceeded" };
         return { ok: true };
@@ -173,7 +220,19 @@ async function hasResolves(inputsLog, ledger, deferRef) {
 export async function approvePending(opts) {
     return approvalLockFor(opts.ledger).enqueue(() => approvePendingUnlocked(opts));
 }
+function ledgerStateDir(ledger) {
+    const dir = ledger.dir;
+    return typeof dir === "string" && dir !== "" ? dir : null;
+}
+function approvalsHalted(ledger) {
+    const dir = ledgerStateDir(ledger);
+    if (!dir)
+        return false;
+    return existsSync(join(dir, "halted"));
+}
 async function approvePendingUnlocked(opts) {
+    if (approvalsHalted(opts.ledger))
+        return { ok: false, reason: "halted" };
     const inputsLog = opts.inputsLog ?? inputsLogFor(opts.ledger);
     const defer = await lookupDecisionByRef(opts.ledger, opts.ref);
     if (!defer || defer.decision !== "defer")
@@ -187,7 +246,13 @@ async function approvePendingUnlocked(opts) {
     if (resolved || (await hasResolves(inputsLog, opts.ledger, opts.ref))) {
         const hit = resolved ?? lookupResolvedBy(opts.ledger, opts.ref);
         if (snap?.status === "pending" && hit) {
-            await opts.approvals.updateStatus(opts.ref, hit.kind === "allow" ? "approved" : "expired", hit.kind === "allow" ? { allowRef: hit.ref } : undefined);
+            if (hit.kind === "allow") {
+                const stamped = (await lookupDecisionByRef(opts.ledger, hit.ref))?.timestampMs ?? opts.now();
+                await opts.approvals.updateStatus(opts.ref, "approved", { allowRef: hit.ref, approvedAtMs: stamped });
+            }
+            else {
+                await opts.approvals.updateStatus(opts.ref, "expired");
+            }
         }
         return alreadyResolved(hit?.kind === "allow" ? hit.ref : snap?.allowRef);
     }
@@ -261,6 +326,9 @@ async function approvePendingUnlocked(opts) {
         prevRecordHash,
     }, opts.recordSigner.privateKeyPem, opts.recordSigner.publicKeyPem));
     noteResolution(opts.ledger, opts.ref, { ref: allowRef, kind: "allow" });
+    // The allow is on the ledger. Mark the snapshot approved before the effect
+    // row, so a stop during appendEffect still counts this spend.
+    await opts.approvals.updateStatus(opts.ref, "approved", { allowRef, approvedAtMs: opts.now() });
     if (snap.subject === "spend") {
         const resultHash = sha256Canonical({
             authorized: true,
@@ -278,14 +346,49 @@ async function approvePendingUnlocked(opts) {
             actor: opts.approverId,
         }, "self", resultHash);
     }
-    await opts.approvals.updateStatus(opts.ref, "approved", { allowRef });
     return { ok: true, allowRef };
 }
 export function enqueueApprovalCommand(dir, cmd) {
-    appendFileSync(join(dir, "approval-commands.jsonl"), `${JSON.stringify(cmd)}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-    });
+    const file = join(dir, "approval-commands.jsonl");
+    const payload = Buffer.from(`${JSON.stringify(cmd)}\n`, "utf8");
+    const dirStat = lstatSync(dir);
+    if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+        throw new Error(`refusing: ${dir} is a link`);
+    }
+    let existing;
+    try {
+        existing = lstatSync(file);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (existing?.isSymbolicLink()) {
+        throw new Error(`refusing: ${file} is a link`);
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    const chownToDir = process.platform !== "win32" && uid !== undefined && uid !== dirStat.uid;
+    if (process.platform === "win32") {
+        appendFileSync(file, payload, { mode: 0o600 });
+        return;
+    }
+    const nofollow = constants.O_NOFOLLOW ?? 0;
+    const flags = (existing
+        ? constants.O_WRONLY | constants.O_APPEND
+        : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL) | nofollow;
+    const fd = openSync(file, flags, 0o600);
+    try {
+        // A hard link would carry the chown to another file; only a single-link regular file is written.
+        const opened = fstatSync(fd);
+        if (!opened.isFile() || opened.nlink !== 1)
+            throw new Error(`refusing: ${file} is not a single-link file`);
+        if (chownToDir)
+            fchownSync(fd, dirStat.uid, dirStat.gid);
+        writeSync(fd, payload);
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 export async function drainApprovalCommands(dir, apply) {
     const live = join(dir, "approval-commands.jsonl");
@@ -320,8 +423,23 @@ export async function drainApprovalCommands(dir, apply) {
     const poisonPath = join(dir, "approval-commands.poison.jsonl");
     for (const name of names) {
         const file = join(dir, name);
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch (err) {
+            const kept = join(dir, `approval-commands.unreadable-${Date.now()}`);
+            try {
+                renameSync(file, kept);
+            }
+            catch {
+                // Leave the processing name in place. The bytes stay either way.
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`verax-drain: unreadable ${file}: ${message}\n`);
+            continue;
+        }
         try {
-            const text = readFileSync(file, "utf8");
             for (const line of text.split("\n")) {
                 if (line === "")
                     continue;

package/dist/checkpoints.d.ts

@@ -1,3 +1,12 @@
 import type { SignedCheckpoint } from "@cedulon/checkpoint";
 export declare function checkpointsPath(dir: string): string;
 export declare function loadCheckpoints(dir: string): SignedCheckpoint[];
+/**
+ * Every non-empty line is either a checkpoint row or a named problem.
+ * A missing file is an empty result with no problem. A line that does not
+ * parse, and a line that parses but is not a checkpoint, are both problems.
+ */
+export declare function readCheckpointFile(dir: string): {
+    rows: SignedCheckpoint[];
+    problems: string[];
+};

package/dist/checkpoints.js

@@ -29,3 +29,47 @@ export function loadCheckpoints(dir) {
     }
     return out;
 }
+function isCheckpointRow(row) {
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        return false;
+    const rec = row;
+    return Boolean(rec.claims) && typeof rec.coseHex === "string";
+}
+/**
+ * Every non-empty line is either a checkpoint row or a named problem.
+ * A missing file is an empty result with no problem. A line that does not
+ * parse, and a line that parses but is not a checkpoint, are both problems.
+ */
+export function readCheckpointFile(dir) {
+    let text;
+    try {
+        text = readFileSync(checkpointsPath(dir), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { rows: [], problems: [] };
+        return { rows: [], problems: ["checkpoint file could not be read"] };
+    }
+    const rows = [];
+    const problems = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            problems.push(`checkpoint line ${i + 1} is not a checkpoint`);
+            continue;
+        }
+        if (!isCheckpointRow(parsed)) {
+            problems.push(`checkpoint line ${i + 1} is not a checkpoint`);
+            continue;
+        }
+        rows.push(parsed);
+    }
+    return { rows, problems };
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { createProxy, LedgerDenyUnrecorded } from "./proxy.ts";
-export { loadPolicy } from "./policy.ts";
+export { loadPolicy, TERMINAL_CONTROL_CLASS } from "./policy.ts";
 export { FileLedger, MemoryLedger, readLedgerTail } from "./ledger.ts";
 export { indexCoverage, listPieceFiles } from "./ledger-manifest.ts";
 export { explain } from "./explain.ts";
 export { approvePending, approvalsLogFor, createApprovalBudgetGuard, enqueueApprovalCommand, loadApprovalsFromDir, } from "./approvals.ts";
-export { loadEffectsFromDir, parseCardCsv, parseChannelJsonl, reconcile } from "./reconcile.ts";
+export { loadDecisionRefsFromDir, loadEffectsFromDir, parseCardCsv, parseChannelJsonl, reconcile } from "./reconcile.ts";
 export { tenantKey } from "./tenant.ts";
 export { diskProbe } from "./disk.ts";
 export { checkpointsPath } from "./checkpoints.ts";

package/dist/index.js

@@ -1,10 +1,10 @@
 export { createProxy, LedgerDenyUnrecorded } from "./proxy.js";
-export { loadPolicy } from "./policy.js";
+export { loadPolicy, TERMINAL_CONTROL_CLASS } from "./policy.js";
 export { FileLedger, MemoryLedger, readLedgerTail } from "./ledger.js";
 export { indexCoverage, listPieceFiles } from "./ledger-manifest.js";
 export { explain } from "./explain.js";
 export { approvePending, approvalsLogFor, createApprovalBudgetGuard, enqueueApprovalCommand, loadApprovalsFromDir, } from "./approvals.js";
-export { loadEffectsFromDir, parseCardCsv, parseChannelJsonl, reconcile } from "./reconcile.js";
+export { loadDecisionRefsFromDir, loadEffectsFromDir, parseCardCsv, parseChannelJsonl, reconcile } from "./reconcile.js";
 export { tenantKey } from "./tenant.js";
 // The body writes checkpoints and signs its own effect attestations. Both were
 // reached through a relative path into this package, which only exists inside

package/dist/ledger-manifest.d.ts

@@ -61,6 +61,15 @@ export declare function nextPieceId(existingIds: string[], atMs: number): string
  */
 export declare function readLedgerManifest(dir: string): LedgerManifest | null;
 export declare function writeLedgerManifest(dir: string, manifest: LedgerManifest): void;
+/**
+ * A manifest piece path is usable only when it stays inside `dir` after
+ * normalization. Absolute paths, drive letters, UNC (`\\host\share`,
+ * `//host/share`) and `..` are refused here, before any filesystem call.
+ * Null means the path is confined; the string is the problem to report.
+ */
+export declare function ledgerPiecePathProblem(dir: string, rel: string): string | null;
+/** Confined absolute path, or a thrown error. Does not touch the filesystem. */
+export declare function requireLedgerPiecePath(dir: string, rel: string): string;
 export declare function listPieceFiles(dir: string): PieceFiles[];
 export declare function pieceOverlaps(piece: {
     firstMs: number | null;

package/dist/ledger-manifest.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, posix, relative, resolve, win32 } from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
 export const LEGACY_PIECE_ID = "legacy";
 export const DEFAULT_PIECE_MAX_ROWS = 50_000;
@@ -128,16 +128,59 @@ function asPieceRow(raw) {
 export function writeLedgerManifest(dir, manifest) {
     writeFileAtomic(manifestPath(dir), `${JSON.stringify(manifest)}\n`);
 }
+const PIECE_SEP = /[/\\]/;
+function piecePathRefusal(rel) {
+    return `manifest piece path leaves the ledger directory: ${rel}`;
+}
+function looksUnc(rel) {
+    return rel.startsWith("\\\\") || rel.startsWith("//") || rel.startsWith("\\/") || rel.startsWith("/\\");
+}
+function looksDrive(rel) {
+    return /^[A-Za-z]:/.test(rel);
+}
+function hasDotDot(rel) {
+    return rel.split(PIECE_SEP).some((part) => part === "..");
+}
+/**
+ * A manifest piece path is usable only when it stays inside `dir` after
+ * normalization. Absolute paths, drive letters, UNC (`\\host\share`,
+ * `//host/share`) and `..` are refused here, before any filesystem call.
+ * Null means the path is confined; the string is the problem to report.
+ */
+export function ledgerPiecePathProblem(dir, rel) {
+    if (typeof rel !== "string" || rel === "" || rel.includes("\0"))
+        return piecePathRefusal(String(rel));
+    if (looksUnc(rel) || looksDrive(rel) || hasDotDot(rel) || win32.isAbsolute(rel) || posix.isAbsolute(rel)) {
+        return piecePathRefusal(rel);
+    }
+    const root = resolve(dir);
+    const target = resolve(dir, rel);
+    const fromRoot = relative(root, target);
+    if (fromRoot === "" ||
+        win32.isAbsolute(fromRoot) ||
+        posix.isAbsolute(fromRoot) ||
+        fromRoot.split(PIECE_SEP).some((part) => part === "..")) {
+        return piecePathRefusal(rel);
+    }
+    return null;
+}
+/** Confined absolute path, or a thrown error. Does not touch the filesystem. */
+export function requireLedgerPiecePath(dir, rel) {
+    const problem = ledgerPiecePathProblem(dir, rel);
+    if (problem !== null)
+        throw new Error(problem);
+    return resolve(dir, rel);
+}
 export function listPieceFiles(dir) {
     const manifest = readLedgerManifest(dir);
     const pieces = manifest?.pieces ?? [legacyPieceRow()];
     return pieces.map((p) => ({
         id: p.id,
-        decisions: join(dir, p.decisions),
-        effects: join(dir, p.effects),
-        inputs: join(dir, p.inputs),
-        copyDecisions: join(dir, copyRel(p.id, "decisions.jsonl")),
-        copyEffects: join(dir, copyRel(p.id, "effects.jsonl")),
+        decisions: requireLedgerPiecePath(dir, p.decisions),
+        effects: requireLedgerPiecePath(dir, p.effects),
+        inputs: requireLedgerPiecePath(dir, p.inputs),
+        copyDecisions: requireLedgerPiecePath(dir, copyRel(p.id, "decisions.jsonl")),
+        copyEffects: requireLedgerPiecePath(dir, copyRel(p.id, "effects.jsonl")),
         closed: p.closed,
         firstMs: p.firstMs,
         lastMs: p.lastMs,

package/dist/ledger.d.ts

@@ -132,6 +132,8 @@ export declare class FileLedger implements Ledger {
     /** After lock handoff a new instance reloads; the lost owner cannot append. */
     private loadCaches;
     private applyActivePaths;
+    /** Manifest piece path, refused before any filesystem call when it leaves this directory. */
+    private pieceFile;
     private activePiece;
     private applyIndexLine;
     private pruneCounted;
@@ -148,6 +150,12 @@ export declare class FileLedger implements Ledger {
     private ownsLock;
     /** Lock file on disk, not a process counter. */
     lockStatus(): "held" | "free";
+    /**
+     * Record the port this process is listening on. Called once the socket is
+     * bound, so the number is the one the kernel gave us. An older lock has no
+     * port; this rewrite keeps the pid, the start time, and the token.
+     */
+    recordListenPort(port: number): void;
     private markLost;
     private assertOwned;
     private lockedError;