@codyswann/lisa 4.10.14 → 4.11.0

package/dist/cli/worktree-inventory.d.ts

@@ -0,0 +1,82 @@
+import type { WorktreeFacts } from "./worktree-prune-policy.js";
+/** One entry as git itself reports it. */
+export interface WorktreeEntry {
+    /** Absolute worktree path. */
+    readonly path: string;
+    /** Checked-out branch, or undefined when detached. */
+    readonly branch?: string;
+    /** Whether git reports the entry locked. */
+    readonly locked: boolean;
+    /** Whether git reports the entry's directory as gone. */
+    readonly prunable: boolean;
+    /** Whether this is the primary checkout (always the first entry). */
+    readonly isPrimary: boolean;
+}
+/**
+ * Parse `git worktree list --porcelain` output.
+ *
+ * The first record is always the primary checkout, which is how the primary is
+ * identified — not by comparing it against a path the caller supplied, which
+ * would be wrong the moment the caller ran from a worktree.
+ * @param stdout - Porcelain output
+ * @returns Parsed entries in git's order
+ */
+export declare function parseWorktreeList(stdout: string): readonly WorktreeEntry[];
+/**
+ * Run one bounded git command.
+ * @param args - Git arguments
+ * @param cwd - Directory to run git in
+ * @returns Trimmed stdout
+ */
+export declare function git(args: readonly string[], cwd: string): Promise<string>;
+/**
+ * List every worktree registered for a checkout.
+ * @param repoPath - Any path inside the repository
+ * @returns Registered entries
+ */
+export declare function listWorktrees(repoPath: string): Promise<readonly WorktreeEntry[]>;
+/** The half of the facts that only git and the filesystem can answer. */
+export interface WorktreeGitState {
+    /** Ownership verdict from the receipt check. */
+    readonly ownership: WorktreeFacts["ownership"];
+    /** Seconds since the worktree last showed activity. */
+    readonly idleSeconds: number;
+    /** Modified, staged, added, deleted, or renamed TRACKED files. */
+    readonly trackedChanges: number;
+    /** Untracked, non-ignored files. */
+    readonly untrackedFiles: number;
+    /** Commits present locally and on no remote. */
+    readonly unpushedCommits: number;
+}
+/** Inputs shared by every fact-gathering call in one run. */
+export interface GatherContext {
+    /** Live working directories, or undefined when the probe could not run. */
+    readonly liveWorkingDirectories: readonly string[] | undefined;
+    /** Owner id of the process running the cleaner. */
+    readonly callerOwnerId: string | undefined;
+    /** Absolute path the cleaner is running from. */
+    readonly currentPath: string;
+    /** Clock in epoch milliseconds. */
+    readonly nowMs: number;
+}
+/**
+ * Gather every fact the entitlement rule is allowed to consider.
+ *
+ * A worktree git cannot report on yields `readable: false` with zeroed counts.
+ * The zeros are never read as "holds nothing" because `readable: false` is
+ * itself a blocker — the same reason the doctor check returns undefined for an
+ * unreadable worktree instead of a zeroed exposure.
+ * @param entry - Registered worktree entry
+ * @param context - Shared run inputs
+ * @returns Facts for the entitlement rule
+ */
+export declare function gatherWorktreeFacts(entry: WorktreeEntry, context: GatherContext): Promise<WorktreeFacts>;
+/**
+ * Gather facts for many worktrees without spawning git for all of them at once.
+ * @param entries - Registered worktree entries
+ * @param context - Shared run inputs
+ * @param start - Batch start index
+ * @returns Facts in the original entry order
+ */
+export declare function gatherAllWorktreeFacts(entries: readonly WorktreeEntry[], context: GatherContext, start?: number): Promise<readonly WorktreeFacts[]>;
+//# sourceMappingURL=worktree-inventory.d.ts.map

package/dist/cli/worktree-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-inventory.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-inventory.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAOhE,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAM1E;AA+BD;;;;;GAKG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAInC;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC/C,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oCAAoC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC/D,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,aAAa,CAAC,CAgCxB;AAuFD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,EAAE,aAAa,EACtB,KAAK,SAAI,GACR,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAanC"}

package/dist/cli/worktree-inventory.js

@@ -0,0 +1,195 @@
+/**
+ * Enumeration and fact-gathering for registered git worktrees.
+ *
+ * Enumeration is `git worktree list --porcelain`, never a scan of the worktree
+ * roots, and that is load-bearing twice over. It is the git control plane's own
+ * record of which checkouts belong to this repository — ownership evidence
+ * rather than a path guess — and it reaches worktrees parked outside the tidy
+ * roots, which a root scan silently reports as absent.
+ * @module cli/worktree-inventory
+ */
+import { execFile } from "node:child_process";
+import { realpath, stat } from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { countLiveHolders } from "./worktree-liveness.js";
+import { judgeOwnership, readOwnerReceipt } from "./worktree-ownership.js";
+const run = promisify(execFile);
+const GIT_TIMEOUT_MS = 15_000;
+const GIT_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
+const INSPECTION_BATCH_SIZE = 8;
+/**
+ * Parse `git worktree list --porcelain` output.
+ *
+ * The first record is always the primary checkout, which is how the primary is
+ * identified — not by comparing it against a path the caller supplied, which
+ * would be wrong the moment the caller ran from a worktree.
+ * @param stdout - Porcelain output
+ * @returns Parsed entries in git's order
+ */
+export function parseWorktreeList(stdout) {
+    return stdout
+        .split(/\n{2,}/)
+        .map(block => block.split("\n").filter(line => line !== ""))
+        .filter(lines => lines.some(line => line.startsWith("worktree ")))
+        .map((lines, index) => parseWorktreeBlock(lines, index === 0));
+}
+/**
+ * Parse one porcelain record.
+ * @param lines - Non-empty lines of the record
+ * @param isPrimary - Whether this record is the primary checkout
+ * @returns Parsed entry
+ */
+function parseWorktreeBlock(lines, isPrimary) {
+    const worktreePath = (lines.find(line => line.startsWith("worktree ")) ?? "worktree ").slice("worktree ".length);
+    const branchLine = lines.find(line => line.startsWith("branch "));
+    const branch = branchLine === undefined
+        ? undefined
+        : branchLine.slice("branch ".length).replace(/^refs\/heads\//, "");
+    const base = {
+        path: worktreePath,
+        locked: lines.some(line => line === "locked" || line.startsWith("locked ")),
+        prunable: lines.some(line => line === "prunable" || line.startsWith("prunable ")),
+        isPrimary,
+    };
+    return branch === undefined ? base : { ...base, branch };
+}
+/**
+ * Run one bounded git command.
+ * @param args - Git arguments
+ * @param cwd - Directory to run git in
+ * @returns Trimmed stdout
+ */
+export async function git(args, cwd) {
+    const { stdout } = await run("git", [...args], {
+        cwd,
+        maxBuffer: GIT_MAX_BUFFER_BYTES,
+        timeout: GIT_TIMEOUT_MS,
+    });
+    return stdout;
+}
+/**
+ * List every worktree registered for a checkout.
+ * @param repoPath - Any path inside the repository
+ * @returns Registered entries
+ */
+export async function listWorktrees(repoPath) {
+    return parseWorktreeList(await git(["worktree", "list", "--porcelain"], repoPath));
+}
+/**
+ * Gather every fact the entitlement rule is allowed to consider.
+ *
+ * A worktree git cannot report on yields `readable: false` with zeroed counts.
+ * The zeros are never read as "holds nothing" because `readable: false` is
+ * itself a blocker — the same reason the doctor check returns undefined for an
+ * unreadable worktree instead of a zeroed exposure.
+ * @param entry - Registered worktree entry
+ * @param context - Shared run inputs
+ * @returns Facts for the entitlement rule
+ */
+export async function gatherWorktreeFacts(entry, context) {
+    // Compared against the PHYSICAL path. `lsof` reports resolved paths, and on
+    // macOS the scratch and temp roots agents park worktrees under are symlinks
+    // (`/tmp` is `/private/tmp`). Comparing the registered spelling against a
+    // resolved one finds no live holder for a worktree somebody is sitting in —
+    // a false "abandoned" verdict on exactly the busiest case.
+    const physical = await realpath(entry.path).catch(() => entry.path);
+    const shell = {
+        path: entry.path,
+        ...(entry.branch === undefined ? {} : { branch: entry.branch }),
+        isPrimary: entry.isPrimary,
+        isCurrent: isCurrentWorktree(physical, context.currentPath),
+        locked: entry.locked,
+        liveHolders: context.liveWorkingDirectories === undefined
+            ? undefined
+            : countLiveHolders(physical, context.liveWorkingDirectories),
+    };
+    const state = await readWorktreeState(entry.path, context).catch(() => undefined);
+    return state === undefined
+        ? {
+            ...shell,
+            readable: false,
+            ownership: "unclaimed",
+            idleSeconds: 0,
+            trackedChanges: 0,
+            untrackedFiles: 0,
+            unpushedCommits: 0,
+        }
+        : { ...shell, readable: true, ...state };
+}
+/**
+ * Read the git-derived half of one worktree's facts.
+ * @param worktree - Absolute worktree path
+ * @param context - Shared run inputs
+ * @returns Ownership, idleness, and work-at-risk facts
+ */
+async function readWorktreeState(worktree, context) {
+    const [status, adminDirectory, unpushed] = await Promise.all([
+        git(["status", "--porcelain"], worktree),
+        git(["rev-parse", "--absolute-git-dir"], worktree).then(out => out.trim()),
+        git(["rev-list", "--count", "HEAD", "--not", "--remotes"], worktree),
+    ]);
+    const lines = status.split("\n").filter(line => line !== "");
+    const untrackedFiles = lines.filter(line => line.startsWith("??")).length;
+    const receiptOwner = await readOwnerReceipt(adminDirectory);
+    return {
+        ownership: judgeOwnership(receiptOwner, context.callerOwnerId),
+        idleSeconds: await measureIdleSeconds(worktree, adminDirectory, context.nowMs),
+        trackedChanges: lines.length - untrackedFiles,
+        untrackedFiles,
+        unpushedCommits: Number.parseInt(unpushed.trim(), 10) || 0,
+    };
+}
+/**
+ * Report whether the cleaner is running inside a worktree.
+ * @param worktree - Absolute worktree path
+ * @param currentPath - Path the cleaner runs from
+ * @returns True when the cleaner is inside
+ */
+function isCurrentWorktree(worktree, currentPath) {
+    const relative = path.relative(path.resolve(worktree), path.resolve(currentPath));
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+/**
+ * Measure how long a worktree has shown no activity.
+ *
+ * The probes are the worktree root and the control-plane files git touches on
+ * every command run inside it. A working-tree edit that misses all of them
+ * still cannot slip through, because an edit shows up as a tracked or untracked
+ * change, which is a blocker in its own right.
+ * @param worktree - Absolute worktree path
+ * @param adminDirectory - Worktree's git admin directory
+ * @param nowMs - Clock in epoch milliseconds
+ * @returns Seconds since the most recent observed activity
+ */
+async function measureIdleSeconds(worktree, adminDirectory, nowMs) {
+    const probes = [
+        worktree,
+        path.join(adminDirectory, "HEAD"),
+        path.join(adminDirectory, "index"),
+        path.join(adminDirectory, "gitdir"),
+    ];
+    const times = await Promise.all(probes.map(probe => stat(probe).then(info => info.mtimeMs, () => 0)));
+    const newest = Math.max(0, ...times);
+    return newest === 0 ? 0 : Math.max(0, Math.floor((nowMs - newest) / 1000));
+}
+/**
+ * Gather facts for many worktrees without spawning git for all of them at once.
+ * @param entries - Registered worktree entries
+ * @param context - Shared run inputs
+ * @param start - Batch start index
+ * @returns Facts in the original entry order
+ */
+export async function gatherAllWorktreeFacts(entries, context, start = 0) {
+    if (start >= entries.length)
+        return [];
+    const batch = entries.slice(start, start + INSPECTION_BATCH_SIZE);
+    return [
+        ...(await Promise.all(batch.map(entry => gatherWorktreeFacts(entry, context)))),
+        ...(await gatherAllWorktreeFacts(entries, context, start + INSPECTION_BATCH_SIZE)),
+    ];
+}
+//# sourceMappingURL=worktree-inventory.js.map

package/dist/cli/worktree-inventory.js.map

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

package/dist/cli/worktree-liveness.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Fixed absolute `lsof` locations, tried in order.
+ *
+ * Fixed paths rather than a bare command name so a writeable directory early on
+ * `PATH` cannot decide which binary answers a question whose answer authorizes
+ * a deletion.
+ */
+export declare const LSOF_CANDIDATES: readonly string[];
+/**
+ * Machine-wide live working directories, or `undefined` when unknowable.
+ *
+ * `undefined` is not "none" — it is "not assessed", and every caller treats it
+ * as a refusal to proceed.
+ */
+export type LivenessProbe = () => Promise<readonly string[] | undefined>;
+/**
+ * Report whether one path is the same as, or inside, another.
+ * @param parent - Containing directory
+ * @param child - Path being tested
+ * @returns True when `child` is `parent` or lives beneath it
+ */
+export declare function isInside(parent: string, child: string): boolean;
+/**
+ * Count live processes whose working directory sits inside a worktree.
+ * @param worktree - Absolute worktree path
+ * @param workingDirectories - Live working directories from the probe
+ * @returns Number of processes holding the worktree open
+ */
+export declare function countLiveHolders(worktree: string, workingDirectories: readonly string[]): number;
+/**
+ * Parse `lsof -F n` output into the working directories it reports.
+ * @param stdout - Raw `lsof` field output
+ * @returns Absolute directory paths, deduplicated
+ */
+export declare function parseLsofWorkingDirectories(stdout: string): readonly string[];
+/**
+ * Probe the machine for every process working directory.
+ *
+ * `lsof` exits non-zero whenever any process could not be inspected, which is
+ * routine on a multi-user box, so the exit status is deliberately not the
+ * signal — the presence of parsed output is. That is the one place where
+ * reading a status would produce the wrong answer, and reading the content
+ * produces the right one.
+ *
+ * Candidates are tried one at a time rather than in parallel: a machine-wide
+ * `lsof` is a real cost, and four of them to answer one question is three too
+ * many on a box already under fleet load.
+ * @param index - Candidate to try, for the sequential fallback
+ * @returns Live working directories, or undefined when the probe could not run
+ */
+export declare function probeLiveWorkingDirectories(index?: number): Promise<readonly string[] | undefined>;
+//# sourceMappingURL=worktree-liveness.d.ts.map

package/dist/cli/worktree-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-liveness.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-liveness.ts"],"names":[],"mappings":"AA2BA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAK3C,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,SAAS,MAAM,EAAE,GACpC,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAS7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,SAAI,GACR,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAKxC"}

package/dist/cli/worktree-liveness.js

@@ -0,0 +1,124 @@
+/**
+ * Live-process probe used to decide whether a worktree is still in use.
+ *
+ * This is the module that makes ownership provable rather than guessed. A
+ * worktree's path says nothing about who is using it — every agent on this
+ * machine parks its checkout under the same handful of roots — so a prefix
+ * match would reap a sibling's live work. What DOES distinguish them is whether
+ * a running process is sitting inside the directory right now.
+ *
+ * The probe is deliberately all-or-nothing. When it cannot run — no `lsof`, a
+ * timeout, an empty read — it reports `undefined` rather than an empty list,
+ * and the caller refuses every candidate. An empty list would mean "nothing is
+ * live", which is the false all-clear that turns a cleaner into a shredder.
+ * @module cli/worktree-liveness
+ */
+import { execFile } from "node:child_process";
+import * as path from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** Probe wall-clock budget. A machine-wide `lsof` is not instant. */
+const PROBE_TIMEOUT_MS = 30_000;
+/** Output ceiling for the probe. */
+const PROBE_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+/**
+ * Fixed absolute `lsof` locations, tried in order.
+ *
+ * Fixed paths rather than a bare command name so a writeable directory early on
+ * `PATH` cannot decide which binary answers a question whose answer authorizes
+ * a deletion.
+ */
+export const LSOF_CANDIDATES = Object.freeze([
+    "/usr/sbin/lsof",
+    "/usr/bin/lsof",
+    "/bin/lsof",
+    "/opt/homebrew/bin/lsof",
+]);
+/**
+ * Report whether one path is the same as, or inside, another.
+ * @param parent - Containing directory
+ * @param child - Path being tested
+ * @returns True when `child` is `parent` or lives beneath it
+ */
+export function isInside(parent, child) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+/**
+ * Count live processes whose working directory sits inside a worktree.
+ * @param worktree - Absolute worktree path
+ * @param workingDirectories - Live working directories from the probe
+ * @returns Number of processes holding the worktree open
+ */
+export function countLiveHolders(worktree, workingDirectories) {
+    return workingDirectories.filter(directory => isInside(worktree, directory))
+        .length;
+}
+/**
+ * Parse `lsof -F n` output into the working directories it reports.
+ * @param stdout - Raw `lsof` field output
+ * @returns Absolute directory paths, deduplicated
+ */
+export function parseLsofWorkingDirectories(stdout) {
+    return [
+        ...new Set(stdout
+            .split("\n")
+            .filter(line => line.startsWith("n/"))
+            .map(line => line.slice(1))),
+    ];
+}
+/**
+ * Probe the machine for every process working directory.
+ *
+ * `lsof` exits non-zero whenever any process could not be inspected, which is
+ * routine on a multi-user box, so the exit status is deliberately not the
+ * signal — the presence of parsed output is. That is the one place where
+ * reading a status would produce the wrong answer, and reading the content
+ * produces the right one.
+ *
+ * Candidates are tried one at a time rather than in parallel: a machine-wide
+ * `lsof` is a real cost, and four of them to answer one question is three too
+ * many on a box already under fleet load.
+ * @param index - Candidate to try, for the sequential fallback
+ * @returns Live working directories, or undefined when the probe could not run
+ */
+export async function probeLiveWorkingDirectories(index = 0) {
+    const candidate = LSOF_CANDIDATES[index];
+    if (candidate === undefined)
+        return undefined;
+    const found = await runLsof(candidate);
+    return found ?? (await probeLiveWorkingDirectories(index + 1));
+}
+/**
+ * Run one `lsof` candidate and parse its output.
+ * @param executable - Absolute `lsof` path to try
+ * @returns Parsed working directories, or undefined when this candidate failed
+ */
+async function runLsof(executable) {
+    const stdout = await run(executable, ["-a", "-d", "cwd", "-F", "n", "-w"], {
+        maxBuffer: PROBE_MAX_BUFFER_BYTES,
+        timeout: PROBE_TIMEOUT_MS,
+    }).then(result => result.stdout, (error) => readPartialStdout(error));
+    const directories = parseLsofWorkingDirectories(stdout);
+    return directories.length === 0 ? undefined : directories;
+}
+/**
+ * Recover stdout from a failed `execFile` rejection.
+ *
+ * A timed-out child returns EMPTY streams, so this yields `""` and the caller
+ * treats the probe as unavailable rather than as a clean machine.
+ * @param error - Rejection from `execFile`
+ * @returns Whatever stdout the child produced before failing
+ */
+function readPartialStdout(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "stdout" in error &&
+        typeof error.stdout === "string"
+        ? error.stdout
+        : "";
+}
+//# sourceMappingURL=worktree-liveness.js.map

package/dist/cli/worktree-liveness.js.map

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

package/dist/cli/worktree-ownership.d.ts

@@ -0,0 +1,65 @@
+/** Receipt filename inside a worktree's git admin directory. */
+export declare const OWNER_RECEIPT_FILENAME = "lisa-worktree-owner.json";
+/**
+ * Environment variables consulted, in order, for the caller's owner id.
+ *
+ * All of them are supplied by the surrounding agent runtime. None is invented
+ * by Lisa, because an id Lisa minted per invocation would never match a receipt
+ * written by an earlier invocation and would make every claim useless.
+ */
+export declare const OWNER_ID_VARIABLES: readonly string[];
+/** What a receipt says about the caller's relationship to a worktree. */
+export type OwnershipVerdict = "mine" | "theirs" | "unclaimed";
+/** Persisted claim on one worktree. */
+export interface OwnerReceipt {
+    /** Opaque id of the agent that claimed the worktree. */
+    readonly ownerId: string;
+    /** ISO timestamp the claim was written. */
+    readonly claimedAt: string;
+}
+/**
+ * Resolve the owner id of the process running the cleaner.
+ *
+ * Returns undefined when no runtime supplied one. Undefined is a real answer
+ * and a restrictive one: a caller with no id can never match a receipt, so
+ * every claimed worktree is somebody else's as far as it is concerned.
+ * @param env - Environment to read
+ * @returns Owner id, or undefined when none is available
+ */
+export declare function resolveCallerOwnerId(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Judge a worktree's claim against the caller.
+ *
+ * A receipt naming somebody else is a hard "theirs" even when the caller has no
+ * id of its own — an unidentified caller proves nothing, and "I could not tell"
+ * must never resolve in favour of deletion.
+ * @param receiptOwner - Owner recorded in the receipt, if any
+ * @param callerOwner - Owner id of the running process, if any
+ * @returns Ownership verdict
+ */
+export declare function judgeOwnership(receiptOwner: string | undefined, callerOwner: string | undefined): OwnershipVerdict;
+/**
+ * Absolute path of the receipt for one worktree admin directory.
+ * @param adminDirectory - Worktree's git admin directory
+ * @returns Absolute receipt path
+ */
+export declare function ownerReceiptPath(adminDirectory: string): string;
+/**
+ * Read the owner recorded for one worktree.
+ *
+ * An unreadable or malformed receipt returns undefined rather than throwing:
+ * the caller then treats the worktree as unclaimed and falls back to the
+ * non-use gates, which are strictly more conservative than a claim.
+ * @param adminDirectory - Worktree's git admin directory
+ * @returns Recorded owner id, or undefined when there is no usable receipt
+ */
+export declare function readOwnerReceipt(adminDirectory: string): Promise<string | undefined>;
+/**
+ * Write an ownership claim for one worktree.
+ * @param adminDirectory - Worktree's git admin directory
+ * @param ownerId - Owner id to record
+ * @param now - Clock, injectable for tests
+ * @returns Absolute path of the receipt written
+ */
+export declare function writeOwnerReceipt(adminDirectory: string, ownerId: string, now?: () => Date): Promise<string>;
+//# sourceMappingURL=worktree-ownership.d.ts.map

package/dist/cli/worktree-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-ownership.d.ts","sourceRoot":"","sources":["../../src/cli/worktree-ownership.ts"],"names":[],"mappings":"AAkBA,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAI9C,CAAC;AAEH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE/D,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAqC,GAChD,MAAM,GAAG,SAAS,CAMpB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,gBAAgB,CAGlB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,MAAM,CAAC,CASjB"}