pi-daddy 0.27.4 → 0.32.0

package/dist/governance/init.js

@@ -0,0 +1,360 @@
+/**
+ * `pi-daddy init` — scaffold a governed project from the skill packages already installed (B2, P3).
+ *
+ * Legacy unregistered npm packages can be scaffolded per skill: create a directory, copy the
+ * body and declaration copies plus a starting `PI_DADDY_GRANT`. Configured enabled Pi resources
+ * are referenced where installed instead (ADR-0074); no competing .pi/skills copy is created.
+ *
+ * **The line it does not cross, and the reason this module exists at all:** `init` writes files an operator
+ * then **reviews, edits and commits**. It never chooses a ceiling. A skill that declares `allowed-tools` is
+ * copied *verbatim* — the author's declaration is the ceiling, and re-deriving it here would put a second
+ * opinion between the file and the enforcer. A skill that declares none is copied with a **commented**
+ * placeholder and stays unspawnable until a human fills it in.
+ *
+ * **What it DOES choose is the starting grant, which is a stronger act** — ADR-0029, added after a reviewer
+ * pointed out that ADR-0028 drew its boundary around the wrong object. The handoff's reason a third party
+ * may safely author `allowed-tools` is that *"the operator's `PI_DADDY_GRANT` still bounds it"*; a
+ * generated union gives the bound and the bounded one author, and it is not the operator. So capabilities
+ * that can change a machine are emitted **commented** (`./grant-env.ts`).
+ *
+ * The placeholder is deliberately not a working example. Uncommenting it unedited yields capability ids
+ * like `tool:<list` which the catalog refuses as unknown — a loud failure, in the direction rule 8 asks
+ * for, rather than a grant nobody decided.
+ */
+import { lstat, mkdir, open, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { agentCapability, workspaceCapability } from "../kernel/capabilities.js";
+import { ceilingForDefinition } from "../kernel/definitions.js";
+import { runWithFinalizers } from "./finalization.js";
+import { ALWAYS_LIVE, assertGrantIsWritable, isLiveByDefault, renderProjectSettings, } from "../kernel/grant-env.js";
+import { PI_BUILTIN_TOOLS } from "../kernel/pi-tools.js";
+import { PI_PROJECT_DIR, PROJECT_FILES, PROJECT_GITIGNORE_CONTENT, PROJECT_STATE_DIRNAME, piProjectDir, projectGitignorePath, projectSettingsPath, projectStateDir, } from "../kernel/project-paths.js";
+import { spawnSync } from "node:child_process";
+/**
+ * Count declarations, not authorizations (R-73). Both pattern and needs-withheld mean the skill
+ * declared a ceiling; only undeclared means it did not. The CLI must report the same distinction.
+ */
+export function countDeclaring(skills, from) {
+    return skills.filter((s) => s.from === from && s.withheld !== "undeclared").length;
+}
+const PLACEHOLDER = [
+    "# pi-daddy: this skill declares no `allowed-tools`, so it CANNOT be spawned as a governed sub-agent —",
+    "# an undeclared capability set is treated as NONE, never as everything. Decide what it needs, then",
+    "# uncomment and complete the line below. pi-daddy does not choose this for you: the capability set is",
+    "# the thing you are meant to review and commit.",
+    "# pi 0.84.1's tools: " + PI_BUILTIN_TOOLS.join(", ") + ".",
+    "# allowed-tools: <list the tools this skill needs, e.g. Read, Grep>",
+];
+/**
+ * A copied file that is unspawnable for a reason an operator cannot see by reading it.
+ *
+ * The undeclared case got four explanatory lines from the start; a pattern-carrying one got nothing, so
+ * opening `.pi/skills/git-ops/SKILL.md` to find out why it will not spawn showed a perfectly ordinary file.
+ * Same argument, opposite treatment — now the same treatment.
+ */
+const patternNote = (patterns) => [
+    "# pi-daddy: this skill CANNOT be spawned as a governed sub-agent. Its `allowed-tools` restricts a tool",
+    `# with a pattern (${patterns.join(", ")}), and pi's --tools matches whole tool names only — granting the`,
+    "# bare tool would widen the declaration and dropping it would silently narrow, so neither is done.",
+    "# Replace the pattern with whole tool names to make it spawnable.",
+];
+/**
+ * The file to write for one skill: verbatim when it declares a usable ceiling, plus a commented note when
+ * it does not.
+ *
+ * Inserted at the END of the frontmatter block, so the rest of the file — including its own key order and
+ * its body — is byte-identical to the package's. A `#` line is a YAML comment and this package's
+ * frontmatter reader skips it, so an undeclared copy is still *undeclared*: not spawnable until a human
+ * edits it, which is the whole point.
+ */
+export function withPlaceholder(text, declared, note = PLACEHOLDER) {
+    if (declared)
+        return text;
+    const match = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(text);
+    // No frontmatter at all means `parseSkillDefinition` returned null and this skill was never discovered;
+    // inventing one here would invent a file shape. Left exactly as it is.
+    if (!match)
+        return text;
+    const [full, opening, body, close] = match;
+    const eol = close.startsWith("\r\n") ? "\r\n" : "\n";
+    return opening + body + eol + note.join(eol) + close + text.slice(full.length);
+}
+/** `tool:` ids pi 0.84.1 has no tool for. `delegate` is this package's own, hence the exemption. */
+function unknownToolIds(capabilities) {
+    const builtins = new Set(PI_BUILTIN_TOOLS);
+    return capabilities.filter((c) => c.startsWith("tool:") && c !== ALWAYS_LIVE && !builtins.has(c.slice("tool:".length)));
+}
+/**
+ * Decide what `init` would write. Pure: no filesystem, no npm, no decisions taken on the operator's behalf.
+ *
+ * The grant is **the read-only part** of what the copied skills declare, plus one `agent:` id per definition
+ * that can actually run within it, plus `tool:delegate` — without which the session registers no delegation
+ * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
+ * away (ADR-0029).
+ */
+export function planInit(packages, cwd, 
+/**
+ * Ids from the operator's workspace registry, when one is configured — read by the CALLER, because
+ * `planInit` is pure and stays that way.
+ *
+ * ADR-0035 made routing a capability and said `init` "scaffolds the registered ids so the common path is a
+ * one-line grant edit". It did not: `init` had never heard of the registry, so the ADR's own stated
+ * migration path for a breaking change did not exist. These are emitted **commented**, never live —
+ * offering the ids while refusing to choose among them is exactly ADR-0028's position.
+ */
+registeredWorkspaceIds = []) {
+    const skills = [];
+    const collisions = [];
+    const seen = new Set();
+    for (const pkg of packages) {
+        for (const skill of pkg.skills) {
+            const name = skill.definition.name;
+            if (seen.has(name)) {
+                collisions.push(`${name} (also in ${pkg.name}@${pkg.version}, not written)`);
+                continue;
+            }
+            seen.add(name);
+            const ceiling = ceilingForDefinition(skill.definition);
+            const notes = [];
+            let withheld = null;
+            let note = PLACEHOLDER;
+            if (ceiling.undeclared)
+                withheld = "undeclared";
+            else if (ceiling.patterns.length > 0) {
+                withheld = "pattern";
+                note = patternNote(ceiling.patterns);
+                notes.push(`declares ${ceiling.patterns.join(", ")} — pi's --tools matches whole tool names only, so a ` +
+                    `sub-tool pattern is refused rather than reinterpreted (granting the bare tool would widen it)`);
+            }
+            skills.push({
+                name,
+                from: `${pkg.name}@${pkg.version}`,
+                sourcePath: skill.path,
+                targetPath: skill.referenced ? skill.path : join(piProjectDir(cwd), "skills", name, "SKILL.md"),
+                referenced: skill.referenced,
+                content: withPlaceholder(skill.text, withheld === null, note),
+                ceiling: ceiling.capabilities,
+                withheld,
+                notes,
+            });
+        }
+    }
+    // ADR-0029: split what the declared ceilings ask for into what `init` grants live and what it comments.
+    const declared = skills.filter((s) => s.withheld === null);
+    const withheldCapabilities = new Map();
+    for (const skill of declared) {
+        for (const capability of skill.ceiling) {
+            if (isLiveByDefault(capability))
+                continue;
+            // A routing destination is withheld but does NOT belong in this map, and the difference is not
+            // cosmetic. This map drives two things: the "WITHHELD BY DEFAULT — these can change your machine"
+            // block, and `/grants init`'s dialog. Review found a `workspace:` id reaching both — described to the
+            // operator with `tool:bash`'s rationale (routing does not change your machine, and unlike `bash` it
+            // *is* gateable), and then granted **live and persisted** on one "Yes", off a third-party package's
+            // declaration. That is the rule `grant-env.ts` states — "does not become live because a package asked
+            // for it" — honoured by the rendered file and broken by the dialog beside it: two surfaces of one
+            // command disagreeing, which is R-28's shape inside the fix for R-28.
+            //
+            // Which worktree a child starts in is not derivable from a declaration (ADR-0028), so `init` lists
+            // routing and never grants it. `routableWorkspaces` below is where these go; the definition that
+            // declared one still loses its live `agent:` id via the `needs-withheld` pass, so nothing becomes
+            // spawnable behind the operator's back either.
+            if (capability.startsWith("workspace:"))
+                continue;
+            withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
+        }
+    }
+    // A definition needing a withheld capability does not get a live `agent:` id either: authorising it to run
+    // and then refusing it at spawn time is a worse answer than not authorising it, and it would put an
+    // `agent:` id in the grant whose definition cannot work — the shape ADR-0028 rule 3 already refuses.
+    for (const skill of declared) {
+        if (skill.ceiling.some((c) => !isLiveByDefault(c)))
+            skill.withheld = "needs-withheld";
+    }
+    const authorised = skills.filter((s) => s.withheld === null);
+    const written = new Set(authorised.map((s) => s.name));
+    // `agent:<other>` in a ceiling is legitimate — it is how a delegator learns which definitions IT may
+    // spawn — but a name `init` did not write here would authorise a file from another skill root that the
+    // operator is not reviewing, including `~/.pi/agent/skills`, which other tools install into. Reported,
+    // never granted: the same objection ADR-0028 rule 3 makes to authorising an undeclared skill.
+    const crossReferences = [];
+    const live = new Set([ALWAYS_LIVE]);
+    for (const skill of authorised) {
+        live.add(agentCapability(skill.name));
+        for (const capability of skill.ceiling) {
+            if (capability.startsWith("agent:") && !written.has(capability.slice("agent:".length))) {
+                crossReferences.push({ from: skill.name, capability });
+                continue;
+            }
+            live.add(capability);
+        }
+    }
+    const grant = [...live].sort();
+    const cautions = authorised.flatMap((s) => unknownToolIds(s.ceiling).map((c) => `${s.name} declares ${c}, which pi 0.84.1 has no tool for — unless an extension provides it, ` +
+        `spawning ${s.name} is refused as an unknown capability`));
+    // R-78's structural backstop. Throws rather than rendering something a shell could read as more than a
+    // value, so a gap in the per-entry whitelist costs a refusal instead of an injection.
+    assertGrantIsWritable(grant);
+    const describe = {
+        undeclared: (s) => "declares no `allowed-tools` — fill it in, then add `agent:" + s.name + "` below",
+        pattern: (s) => s.notes.join("; "),
+        "needs-withheld": (s) => `needs ${s.ceiling.filter((c) => !isLiveByDefault(c)).join(", ")}, withheld by default — see below`,
+    };
+    const grantEnvSkills = skills.map((s) => ({
+        name: s.name,
+        ceiling: s.ceiling,
+        ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
+    }));
+    // Registry ids the operator could route to, plus any a copied definition actually declares — a package
+    // naming `workspace:prod` is evidence that id matters here, and it must still be uncommented by hand.
+    const declaredWorkspaces = skills.flatMap((s) => s.ceiling.filter((c) => c.startsWith("workspace:")));
+    const routableWorkspaces = [
+        ...new Set([...registeredWorkspaceIds.map(workspaceCapability), ...declaredWorkspaces]),
+    ].sort();
+    return {
+        skills,
+        collisions,
+        grant,
+        withheldCapabilities,
+        routableWorkspaces,
+        stateDir: projectStateDir(cwd),
+        settingsPath: projectSettingsPath(cwd),
+        gitignorePath: projectGitignorePath(cwd),
+        settingsContent: renderProjectSettings({
+            skills: grantEnvSkills,
+            live: grant,
+            withheld: withheldCapabilities,
+            withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
+            crossReferences,
+            cautions,
+            routableWorkspaces,
+        }),
+        cautions,
+    };
+}
+/**
+ * Create a file only if nothing is there, and **never through a symlink**.
+ *
+ * Both properties come from `O_CREAT|O_EXCL` (`flag: "wx"`), and both were defects in the first version
+ * (R-79). It probed for existence with `readFile` and then called `writeFile`:
+ *
+ *  - `readFile` conflates *unreadable* with *absent*, so an operator's `SKILL.md` with restrictive
+ *    permissions was reported `wrote` and their narrowed `allowed-tools: Read` was replaced by the
+ *    package's wider one — **without `--force`**, falsifying this package's own documented "Kept" rule.
+ *    A FIFO at the target path hung the probe forever, with no timeout anywhere in the path.
+ *  - `writeFile` follows symlinks, so a dangling symlink at a target path created the file at the link's
+ *    destination, outside the project, while reporting an in-project path. That is **B-I6**, which
+ *    `approval-store.ts` already fixed for the approval store under ADR-0014 — a new writer in the same
+ *    package reintroducing a defect the package documents as closed, and whose comment says in so many
+ *    words *"never through a symlink"*.
+ *
+ * `wx` fails with `EEXIST` on anything at the path, including a dangling symlink, so there is no probe, no
+ * race between the probe and the write, and no way to write through a link.
+ */
+async function createUnlessPresent(path, content, outcome) {
+    try {
+        await mkdir(join(path, ".."), { recursive: true });
+        const handle = await open(path, "wx");
+        await runWithFinalizers(() => handle.writeFile(content, "utf8"), [{ label: "new-file handle cleanup failed", run: () => handle.close() }]);
+        outcome.written.push(path);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            outcome.kept.push(path);
+        else
+            outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/** Replace a file, unlinking first so a symlink is REPLACED rather than written through. */
+async function replace(path, content, outcome) {
+    try {
+        await mkdir(join(path, ".."), { recursive: true });
+        // `rm` unlinks the LINK, never its target — which is exactly the semantics `--force` should have.
+        await rm(path, { force: true });
+        await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+        outcome.written.push(path);
+    }
+    catch (error) {
+        outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/**
+ * Apply a plan.
+ *
+ * **Existing files are kept, not overwritten**, and that default is load-bearing rather than polite: the
+ * edit an operator makes to one of these files IS the capability decision, and the second run of a
+ * scaffolding command is exactly when it would be destroyed.
+ *
+ * **`--force` never regenerates `settings.json`** (R-79). It rewrites the definition copies, which is the
+ * documented re-sync path for R-74 — but the grant file is the *reviewed artifact*, and an operator who had
+ * deleted `agent:build` and added a ledger path would have had both silently restored to generated defaults
+ * by a command whose usage text mentions only `allowed-tools`. Deleting the file is how to regenerate it,
+ * and that is not something anyone does by accident.
+ */
+/**
+ * Whether git would ignore `settings.json` anyway — the common case, because most projects' root `.gitignore`
+ * lists `.pi/`, and git never descends into an ignored directory, so the nested `!settings.json` cannot
+ * re-include it (ADR-0076 PR 3c review finding). `true` = ignored, `false` = tracked-or-untracked, `null` =
+ * not a git checkout or git unavailable; the caller only warns on `true`.
+ */
+export async function settingsIgnoredByGit(settingsPath) {
+    try {
+        const { status } = spawnSync("git", ["-C", dirname(dirname(dirname(settingsPath))), "check-ignore", "-q", "--", settingsPath], {
+            stdio: "ignore",
+            timeout: 5000,
+        });
+        if (status === 0)
+            return true;
+        if (status === 1)
+            return false;
+        return null; // 128: not a repository, or git refused
+    }
+    catch {
+        return null;
+    }
+}
+/** The two lines an operator adds to the root `.gitignore` so the reviewable record is committable. */
+export const GITIGNORE_REINCLUDE_LINES = [
+    `!${PI_PROJECT_DIR}/`,
+    `!${PI_PROJECT_DIR}/${PROJECT_STATE_DIRNAME}/${PROJECT_FILES.settings}`,
+];
+export async function applyInit(plan, options = {}) {
+    const outcome = { written: [], kept: [], failed: [] };
+    // pi's `.pi` first, then our owner-only state directory inside it. Existing operator/Pi state is never
+    // chmodded, followed through a symlink, or reused if it is not a directory.
+    for (const dir of [dirname(plan.stateDir), plan.stateDir]) {
+        try {
+            await mkdir(dir, { mode: 0o700 });
+            const created = await lstat(dir);
+            if (!created.isDirectory() || created.isSymbolicLink())
+                throw Error("private state directory creation failed");
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                outcome.failed.push({ path: dir, error: error instanceof Error ? error.message : String(error) });
+                return outcome;
+            }
+            const existing = await lstat(dir);
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                outcome.failed.push({
+                    path: dir,
+                    error: "existing state path is not a directory; it was not followed or changed",
+                });
+                return outcome;
+            }
+        }
+    }
+    const force = options.force === true;
+    for (const skill of plan.skills) {
+        if (skill.referenced)
+            continue;
+        if (force)
+            await replace(skill.targetPath, skill.content, outcome);
+        else
+            await createUnlessPresent(skill.targetPath, skill.content, outcome);
+    }
+    await createUnlessPresent(plan.settingsPath, plan.settingsContent, outcome);
+    await createUnlessPresent(plan.gitignorePath, PROJECT_GITIGNORE_CONTENT, outcome);
+    return outcome;
+}
+//# sourceMappingURL=init.js.map

package/dist/governance/init.js.map

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

package/dist/governance/lease-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-helper.d.ts","sourceRoot":"","sources":["../../src/governance/lease-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,yBAAyB,CAAC;AAelD,eAAO,MAAM,aAAa,QAmCF,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,OAAO,KAAG,IAE7C,CAAC;AAEF;;;;;GAKG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,IAgBxG,CAAC"}

package/dist/governance/lease-helper.js

@@ -0,0 +1,121 @@
+/**
+ * **The lock helper: a separate program, and the parent's side of its pipes.**
+ *
+ * Split out of `workspace-lease.ts` because `test/file-size.test.ts` refused that file — at 405 lines on the
+ * ADR-0035 branch when PR #14 merged into it, and at 435 here once R-152's guards landed. Both branches take
+ * the same seam so they converge rather than diverge, and the cap has never been raised: `delegate.ts` was
+ * split at 413 the same way (rule: when a guard fails, obey it).
+ *
+ * The seam is not arbitrary. Everything here concerns the process that HOLDS the kernel lock — the source it
+ * runs, the readiness token it prints, and the parent-side handles that keep it referenced.
+ * `workspace-lease.ts` keeps the lease lifecycle that talks to it.
+ */
+export const LEASE_READY = "PI_DADDY_LEASE_READY";
+// The lock holder also owns crash cleanup for the governed child. If the parent dies, stdin closes;
+// the helper signals the attached process, or closes the herdr tab, before releasing flock. A raw
+// descendant deliberately detached by bash remains ADR-0012's OS-containment boundary, not a lease
+// guarantee. The process branch SIGTERMs, escalates to SIGKILL at +500ms, and releases at +750ms
+// WITHOUT confirming death (R-101). The herdr branch retries `tab close` a BOUNDED number of times
+// and then releases anyway, leaving a marker file: an unreleasable lock strands a worktree forever
+// with no in-product recovery, which is strictly worse than a recorded failure to close (R-102).
+//
+// **Each attempt is bounded in WALL CLOCK, not just in count (R-146).** `execFile` with no `timeout`
+// never calls back if `herdr` accepts the close and does not answer, so the retry counter never
+// decrements, `giveUp` never runs and no marker is written — the lock is held forever. That was masked
+// while the parent could not exit, because the operator saw a hung `pi` instead; measured with a `herdr`
+// that sleeps, the parent then exited in 82ms and left a silent strand, which is R-102's rejected outcome
+// reached quietly. A bound on retries is not a bound on time.
+export const HELPER_SOURCE = `
+import { execFile } from "node:child_process";
+import { writeFileSync } from "node:fs";
+let clean=false, target=null, buffered="";
+process.stdout.write(${JSON.stringify(`${LEASE_READY}:`)}+process.pid+"\\n");
+process.stdin.setEncoding("utf8");
+process.stdin.on("data",chunk=>{buffered+=chunk;
+for(;
+;
+){const i=buffered.indexOf("\\n");
+if(i<0)break;
+const line=buffered.slice(0,i);
+buffered=buffered.slice(i+1);
+try{const value=JSON.parse(line);
+if(value.release)clean=true;
+else if(value.process_pid)target={process_pid:value.process_pid};
+else if(value.herdr_tab)target={herdr_tab:value.herdr_tab};
+}catch{}}});
+process.stdin.on("end",()=>{if(clean||!target)return process.exit(0);
+if(target.process_pid){try{process.kill(target.process_pid,"SIGTERM")}catch{return process.exit(0)}setTimeout(()=>{try{process.kill(target.process_pid,"SIGKILL")}catch{}},500);
+return setTimeout(()=>process.exit(0),750);
+}let left=Number(process.env.PI_DADDY_LEASE_CLOSE_ATTEMPTS||10);
+const giveUp=last=>{
+try{
+if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,
+JSON.stringify({reason:last&&(last.killed||last.signal==="SIGKILL")?"herdr-close-timeout":"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")
+}catch{}
+process.exit(0)};
+const close=()=>execFile("herdr",["tab","close",target.herdr_tab],
+{timeout:Number(process.env.PI_DADDY_LEASE_CLOSE_TIMEOUT_MS||15000),killSignal:"SIGKILL"},
+error=>{if(!error)return process.exit(0);
+if(--left<=0)return giveUp(error);
+setTimeout(close,1000)});
+close();
+});
+process.stdin.resume();`;
+/**
+ * `unref` the parent's end of one of the helper's pipes.
+ *
+ * A spawned pipe is a `net.Socket`, which has `unref`; `ChildProcess.stdin` is typed `Writable`, which does
+ * not. Hence the narrow cast. The optional call is **defensive, not load-bearing** — the holder is spawned at
+ * exactly one site with three pipes, so none of these is ever `null`, and an earlier version of this comment
+ * claimed otherwise by citing a `stdio: "ignore"` caller that does not exist.
+ *
+ * Only `stdout` and `stderr` are unref'ed. `stdin` was too, until a line-by-line reversion showed the suite
+ * stayed green without it — an unforced line inside the fix that exists to be forced, which is exactly the
+ * shape R-122 was about.
+ */
+export const unrefStream = (stream) => {
+    stream?.unref?.();
+};
+/**
+ * The bounds on the helper's `herdr tab close` attempts live here, with the attempts they bound — moved out of
+ * `workspace-lease.ts` when the line ceiling refused it at 402 lines, once both this branch's ADR-0035 work and
+ * `main`'s R-152 guards had landed in it. Third time that guard has fired on this file and third time the
+ * answer was a seam rather than a bigger cap.
+ */
+/**
+ * **A bound that is not a bound throws, and it throws a `RangeError` (R-146, R-152).**
+ *
+ * Both ends fail, in opposite directions and both silently:
+ *
+ *  - `0` reads as "no limit" and Node agrees — `execFile` treats `timeout: 0` as *no* timeout (measured: the
+ *    callback for a 3s sleep arrives at 3004ms with no error), reinstating the unbounded hang the bound exists
+ *    to prevent. Negatives behave identically.
+ *  - anything above `2^31 - 1` truncates: `setTimeout` warns `TimeoutOverflowWarning … set to 1`, so
+ *    `Number.MAX_SAFE_INTEGER` — the plausible "effectively no limit" sentinel, given the argument about `0`
+ *    — SIGKILLs every `herdr tab close` after 1ms, before herdr can act. Measured: callback at 3ms.
+ *
+ * **Not a `GovernanceRefusal`.** It was one, carrying `WORKSPACE_LEASE_STALE`, which everywhere else in this
+ * package means *the lease went stale or was lost* — so an ADR-0034 controller switching on codes (the reason
+ * codes exist, R-103) would classify a permanent caller bug as transient and retry a call that can never
+ * succeed. A refusal is a governance outcome that gets ledgered; a bad argument is neither.
+ *
+ * Checked for read leases too, which the first version did not: it sat below the read-lease early return, so a
+ * controller smoke-testing its configuration against a read lease got a false all-clear.
+ */
+export const assertCloseBounds = (input) => {
+    const MAX_TIMER = 2_147_483_647;
+    for (const [name, value, ceiling] of [
+        ["herdrCloseTimeoutMs", input.herdrCloseTimeoutMs, MAX_TIMER],
+        ["herdrCloseAttempts", input.herdrCloseAttempts, Number.MAX_SAFE_INTEGER],
+    ]) {
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value < 1 || value > ceiling) {
+            throw new RangeError(`${name} must be a whole number between 1 and ${ceiling}, not ${String(value)}. Zero and negatives ` +
+                `are not "no limit" but no bound at all, a value past ${MAX_TIMER} truncates to 1ms, and a ` +
+                `fractional count is not a count — this bound exists so a hung herdr cannot hold the writer lock ` +
+                `forever (R-146).`);
+        }
+    }
+};
+//# sourceMappingURL=lease-helper.js.map

package/dist/governance/lease-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-helper.js","sourceRoot":"","sources":["../../src/governance/lease-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAClD,oGAAoG;AACpG,kGAAkG;AAClG,mGAAmG;AACnG,iGAAiG;AACjG,mGAAmG;AACnG,mGAAmG;AACnG,iGAAiG;AACjG,EAAE;AACF,qGAAqG;AACrG,gGAAgG;AAChG,uGAAuG;AACvG,yGAAyG;AACzG,0GAA0G;AAC1G,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG;;;;uBAIN,IAAI,CAAC,SAAS,CAAC,GAAG,WAAW,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+BhC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAe,EAAQ,EAAE;IAClD,MAAwC,EAAE,KAAK,EAAE,EAAE,CAAC;AACvD,CAAC,CAAC;AAEF;;;;;GAKG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAoE,EAAQ,EAAE;IAC9G,MAAM,SAAS,GAAG,aAAa,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI;QACnC,CAAC,qBAAqB,EAAE,KAAK,CAAC,mBAAmB,EAAE,SAAS,CAAC;QAC7D,CAAC,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,EAAE,MAAM,CAAC,gBAAgB,CAAC;KACjE,EAAE,CAAC;QACX,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;YAC7D,MAAM,IAAI,UAAU,CAClB,GAAG,IAAI,yCAAyC,OAAO,SAAS,MAAM,CAAC,KAAK,CAAC,uBAAuB;gBAClG,wDAAwD,SAAS,2BAA2B;gBAC5F,kGAAkG;gBAClG,kBAAkB,CACrB,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC,CAAC"}

package/dist/governance/lease-record.d.ts

@@ -0,0 +1,90 @@
+import type { ValidatedWorkspace, WorkspaceAccess } from "../kernel/workspace.ts";
+export interface LeaseMetadata {
+    version: 1;
+    state: "active" | "released";
+    token: string;
+    owner_id: string;
+    workspace_id: string;
+    root: string;
+    pid: number;
+    acquired_at: string;
+    released_at?: string;
+    release_reason?: string;
+}
+export interface WorkspaceLease {
+    workspace: ValidatedWorkspace;
+    access: WorkspaceAccess;
+    ownerId: string;
+    /**
+     * `true` only when the kernel lock was free but metadata said the prior owner never released.
+     * `"unknown"` when the prior owner's record could not be read at all — that is not evidence of a
+     * clean handover and must not be recorded as one (R-100).
+     */
+    recovered: boolean | "unknown";
+    /** Attach the governed resource so parent death cleans it before the kernel lock is released. */
+    attachProcess(pid: number): void;
+    attachHerdrTab(tabId: string): void;
+    /** Resolves only when the kernel-lock helper exits before explicit release. */
+    lost: Promise<Error>;
+    /**
+     * NEVER throws. A cleanup function that can throw destroys its caller's return value — a completed
+     * child's entire output was discarded this way (R-99) — so the outcome is a VALUE the caller records:
+     *   `"released"`            the kernel lock was handed back and the handover recorded;
+     *   `"released-unrecorded"` the lock was handed back but the record failed, so the NEXT owner will
+     *                           report a recovery that did not happen unless this is ledgered;
+     *   `"lost"`                the helper was already gone, so this owner never released anything.
+     */
+    release(reason?: string): Promise<LeaseReleaseOutcome>;
+    /**
+     * Record that this lease is being kept deliberately, WITHOUT releasing the kernel lock.
+     *
+     * Needed because a retained lease never calls `release()`, so the metadata stays `state: "active"` and
+     * whoever acquires next reports `recovered: true` — blaming a crash on a known-good path.
+     */
+    /**
+     * Record that the lease is being KEPT rather than handed back, and answer what actually happened — the
+     * caller ledgers this word (R-152). It is not always `retained`: a helper that has already died makes the
+     * fact `lost`, and a lease already settled by `release()` keeps the outcome it had.
+     */
+    markRetained(reason?: string): Promise<LeaseReleaseOutcome>;
+    /** Reads the give-up marker the helper leaves when it could not close a herdr writer tab. */
+    readCloseFailure(): Promise<{
+        reason: string;
+        herdr_tab?: string;
+    } | null>;
+}
+/**
+ * What a release actually did. Six members rather than three, because the first version conflated facts
+ * that call for different responses — and one of them is an alarm:
+ *   `released`             the lock went back and THIS owner wrote its own handover;
+ *   `released-unrecorded`  the lock went back and the record does not say so, so the next owner will report
+ *                          a recovery that never happened unless the caller ledgers this. **The alarm.**
+ *   `released-superseded`  the lock went back and a successor already owns the metadata, so we correctly
+ *                          declined to overwrite it. Healthy, and previously indistinguishable from the
+ *                          alarm above;
+ *   `not-held`             a read lease, which never took a kernel lock — recording it as `released`
+ *                          overstated how many handovers the kernel performed, which is R-105 on the
+ *                          release side of the same defect;
+ *   `lost`                 the helper was already gone; this owner released nothing.
+ */
+export type LeaseReleaseOutcome = "released" | "released-unrecorded" | "released-superseded" | "not-held" | "lost"
+/**
+ * The lease was RETAINED and is therefore already settled — `release()` after `markRetained()` answers
+ * this instead of running the clean handshake (R-146). It was previously expressible only as the
+ * `| "retained"` bolted onto two signatures, which is why `release()` could not say it and claimed
+ * `released` instead: a clean handover for a lease kept precisely because a pane would not close.
+ */
+ | "retained";
+export declare function leasePaths(leaseDir: string, root: string): {
+    lock: string;
+    metadata: string;
+    marker: string;
+};
+export declare function atomicMetadata(path: string, value: LeaseMetadata): Promise<void>;
+/**
+ * `null` means no prior owner was recorded. `"malformed"` means a record exists and cannot be read,
+ * which is strictly LESS evidence than a readable "active" one and must never read as a clean handover
+ * (R-100). Absent and unreadable are different facts; conflating them silently erases a real recovery.
+ */
+export declare function readMetadata(path: string): Promise<LeaseMetadata | null | "malformed">;
+//# sourceMappingURL=lease-record.d.ts.map

package/dist/governance/lease-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-record.d.ts","sourceRoot":"","sources":["../../src/governance/lease-record.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAElF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,iGAAiG;IACjG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD;;;;;OAKG;IACH;;;;OAIG;IACH,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5D,6FAA6F;IAC7F,gBAAgB,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5E;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,qBAAqB,GACrB,qBAAqB,GACrB,UAAU,GACV,MAAM;AACR;;;;;GAKG;GACD,UAAU,CAAC;AAEf,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;;;;EAQxD;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,GAAG,WAAW,CAAC,CAgB5F"}

package/dist/governance/lease-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-record.js","sourceRoot":"","sources":["../../src/governance/lease-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoFjC,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,IAAY;IACvD,2FAA2F;IAC3F,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACvC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,oBAAoB,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,KAAoB;IACrE,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC;IAC1D,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5G,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IAClF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QACxD,IAAI,KAAK,EAAE,OAAO,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC;QAC7C,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,OAAO,WAAW,CAAC;QAC/E,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,WAAW,CAAC;QACxE,OAAO,KAAsB,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC"}