pi-session-mcp 0.13.0 → 0.14.0

package/dist/setup-writers.js

@@ -1,5 +1,4 @@
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
@@ -8,310 +7,20 @@ import { ALIAS_PATTERN } from "./execution-profile.js";
 import { runDoctor } from "./doctor.js";
 import { MAX_WRITERS } from "./execution-modes.js";
 import { changeExecutionMode } from "./setup-modes.js";
-import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
-import { createCommandMcpStdioLauncher, createProcessRunner } from "./setup-process.js";
-import { DurableOwnershipStore } from "./setup-ownership.js";
-import { localHookNeededByOthers, ownsWakeHook, runWakeHook } from "./setup-hooks.js";
+import { createCommandMcpStdioLauncher } from "./setup-process.js";
 import { result } from "./setup-result.js";
-import { createWriterRegistrationAdapter, unregisterWriter } from "./client-adapters/writer-registration.js";
 import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
-import { sameWriterLimits, writerLimits } from "./writer-limits.js";
-import { IMAGE_PULL_TIMEOUT_MS, podmanCgroupControllers } from "./writer-boundary.js";
-import { acquireWriterLease, WriterLeaseError } from "./writer-lease.js";
-import { ensureWriterAbsent } from "./writer-fence.js";
-import * as lifecycle from "./writer-lifecycle.js";
+import { podmanCgroupControllers } from "./writer-boundary.js";
 import * as acceptance from "./writer-acceptance.js";
-import { skillOverrideDirectory } from "./skill-library.js";
-import { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
-import { readWriterState, writeWriterState, writerName, writerPaths, writerRegistrationName, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
-export const SETUP_LEASE_WAIT_MS = 10_000;
-const FENCE_CODES = ["writer_busy", "writer_fenced", "writer_lease_unavailable"];
-const safeAlias = (alias) => ALIAS_PATTERN.test(alias) ? alias : "invalid";
-const targetFor = (alias, name) => ({ client: "writer", scope: safeAlias(alias), alias: WRITER_NAME_PATTERN.test(name) || (alias === "host" && name === "control") ? name : "invalid" });
-const modesTarget = (alias) => ({ client: "modes", scope: "workspace", alias: safeAlias(alias) });
-const codeFor = (error) => error instanceof OverrideLockError || error instanceof WriterLeaseError ? error.code : error instanceof Error && /^[a-z][a-z0-9_]{0,63}$/.test(error.message) ? error.message : "writer_operation_failed";
-function services(deps) {
-    const home = deps.home ?? homedir();
-    const runner = deps.runner ?? createProcessRunner({ timeoutMs: IMAGE_PULL_TIMEOUT_MS, maxOutputBytes: 1_048_576, ...(deps.signal ? { signal: deps.signal } : {}) });
-    return { home, runner, life: deps.lifecycle ?? lifecycle, accept: deps.acceptance ?? acceptance,
-        ownership: deps.ownership ?? new DurableOwnershipStore(join(home, ".local", "state", "pi-session-mcp", "ownership.json"), { ...(deps.signal ? { signal: deps.signal } : {}) }),
-        adapter: deps.adapter ?? createWriterRegistrationAdapter(runner) };
-}
-async function context(alias, deps) {
-    const config = await loadConfig(deps.configPath);
-    const checkout = config.workspaces.get(alias);
-    if (!checkout)
-        throw new Error("alias_unknown");
-    const { home, runner } = services(deps);
-    return { home, runner, checkout, alias, releaseRoot: deps.releaseRoot, nodePath: process.execPath };
-}
-async function locked(deps, action) {
-    const directory = writersRoot(deps.home ?? homedir());
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    await chmod(directory, 0o700);
-    const lock = await (deps.lock ?? acquireOverrideLock)(directory, { ...(deps.signal ? { signal: deps.signal } : {}) });
-    try {
-        return await action();
-    }
-    finally {
-        await lock.release();
-    }
-}
-async function fenced(ctx, name, deps, action) {
-    let lease;
-    try {
-        lease = await (deps.lease ?? acquireWriterLease)(ctx.home, name, { waitMs: SETUP_LEASE_WAIT_MS, ...(deps.signal ? { signal: deps.signal } : {}) });
-    }
-    catch (error) {
-        throw new Error(error instanceof WriterLeaseError && error.code === "writer_busy" ? "writer_busy" : "writer_lease_unavailable");
-    }
-    try {
-        try {
-            await (deps.ensureAbsent ?? ensureWriterAbsent)(ctx.runner, writerPaths(ctx.home, name), name, { leaseFd: lease.fd });
-        }
-        catch {
-            throw new Error("writer_fenced");
-        }
-        return await action({ ...ctx, leaseFd: lease.fd });
-    }
-    finally {
-        await lease.release();
-    }
-}
-function intent(ctx, name, client) {
-    return { client, name: writerRegistrationName(name), wrapperPath: writerPaths(ctx.home, name).wrapper, projectDir: ctx.checkout };
-}
+import { writerName, writerPaths, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
+import { codeFor, context, DoctorGateError, doctorGate, FENCE_CODES, fenced, GLOBAL_ERRORS, locked, modesTarget, plan, preflight, remove, services, targetFor } from "./setup-writers-common.js";
+import { gateBeforeWrite, inferBase, plannedWriters } from "./setup-writers-plan.js";
+import { reconcileUnlocked } from "./setup-writers-reconcile.js";
 /**
- * The wake hook of a writer's Claude Code registration, in the local settings of the operator's
- * project. Claude Code only: a Codex writer has no hook. The writer's own configuration decides
- * whether delivery is wanted; the entry is shared per project, see `localHookNeededByOthers`.
- * Findings without news (`hook_not_enabled`, `hook_not_owned`) are not reported.
+ * Writer setup entry points: a repository's mode change with its writers (planning and base inference in
+ * `setup-writers-plan.ts`, reconciliation in `setup-writers-reconcile.ts`), single-writer operations and the isolation control.
  */
-async function writerHook(ctx, name, deps, operation, enabled) {
-    const { ownership } = services(deps);
-    const roots = { packageRoot: deps.releaseRoot, home: ctx.home, cwd: ctx.checkout, env: process.env, nodePath: ctx.nodePath };
-    // Nothing wanted and nothing owned: not even the project's settings are looked at.
-    if (!enabled && !await ownsWakeHook("local", roots, ownership))
-        return undefined;
-    const request = (access, op) => runWakeHook({
-        operation: op, scope: "local", enabled, ownership: access,
-        roots,
-        keep: () => localHookNeededByOthers({ ownership: access, home: ctx.home, cwd: ctx.checkout, configPath: deps.configPath, except: { writer: name } }),
-    });
-    const outcome = operation === "apply" || operation === "remove" ? await ownership.transaction((access) => request(access, operation)) : await request(ownership, operation);
-    return outcome.code === "hook_not_enabled" || outcome.code === "hook_not_owned" ? undefined : outcome;
-}
-class DoctorGateError extends Error {
-    findings;
-    constructor(findings) {
-        super("doctor_failed");
-        this.findings = findings;
-    }
-}
-async function doctorGate(ctx, deps) {
-    const doctor = await (deps.doctor ?? runDoctor)({ home: ctx.home, packageRoot: deps.releaseRoot, configPath: deps.configPath, loadConfig: () => loadConfig(deps.configPath) });
-    const ownSubjects = new Set([ctx.alias, ...Array.from({ length: 16 }, (_, index) => writerName(ctx.alias, index + 1))]);
-    // A refused profile of this repository is its own finding: collect, finish and the profile change that fixes it must stay possible (#141).
-    // Another repository's writer that is not ready is untouched by this step and expected after an upgrade; counting it would deadlock
-    // the repository steps of two container repositories (#148).
-    const own = (check) => ownSubjects.has(check.subject)
-        || (check.id === "container_profile_refused" && check.subject.startsWith(`${ctx.alias}:`))
-        || (check.id === "writer_not_ready" && WRITER_NAME_PATTERN.test(check.subject));
-    const blocking = doctor.checks.filter((check) => check.severity === "error" && !own(check));
-    if (blocking.length)
-        throw new DoctorGateError(blocking.map((check) => ({ status: "failed", code: check.id, target: { client: "doctor", scope: "check", alias: gateAlias(check.id, check.subject) } })));
-}
-/** The alias that leads a Doctor subject: `<profile>:<package>` and writer names report their alias part; global checks have none. */
-function gateAlias(id, subject) {
-    if (GLOBAL_ERRORS.has(id))
-        return "invalid";
-    const head = subject.split(":")[0] ?? "";
-    return safeAlias(WRITER_NAME_PATTERN.test(head) ? head.slice(0, head.lastIndexOf("-w")) : head);
-}
-async function preflight(ctx, names, discard, deps) {
-    if (discard)
-        return;
-    for (const name of names) {
-        const state = await readWriterState(ctx.home, name);
-        const work = await (deps.lifecycle ?? lifecycle).inspectWork(ctx, name);
-        if (!work.baseline && state?.collected?.digest !== work.digest)
-            throw new Error("writer_uncollected");
-    }
-}
-async function remove(ctx, name, discard, deps, extras = []) {
-    await preflight(ctx, [name], discard, deps);
-    const { adapter, ownership, life } = services(deps);
-    // Remove registrations before deleting the wrapper used to prove ownership.
-    for (const client of ["claude-code", "codex"]) {
-        const expected = intent(ctx, name, client);
-        const owned = await ownership.get({ client, scope: client === "codex" ? "user" : "local", alias: expected.name });
-        if (owned)
-            await unregisterWriter(ownership, adapter, expected);
-        else if (["equivalent", "divergent"].includes(await adapter.inspect(expected)))
-            throw new Error("ownership_unavailable");
-    }
-    // After the registration is gone. A hook that cannot be edited is reported, not a reason to keep the
-    // writer: the operator's settings are not the writer's to hold hostage, and the record keeps the entry owned.
-    const hook = await writerHook(ctx, name, deps, "remove", false).catch(() => ({ status: "failed", code: "hook_install_failed" }));
-    if (hook)
-        extras.push(hook);
-    return life.removeWriter(ctx, name, { discard });
-}
-const writerIndex = (name) => Number(name.slice(name.lastIndexOf("-w") + 2));
-async function plan(ctx, entry) {
-    const keep = [], missing = [], surplus = [];
-    for (let index = 1; index <= MAX_WRITERS; index++) {
-        const name = writerName(ctx.alias, index), state = await readWriterState(ctx.home, name);
-        if (entry.mode === "container" && index <= entry.container.writers) {
-            keep.push(name);
-            if (!state || state.phase === "provisioning")
-                missing.push(name);
-        }
-        else if (state)
-            surplus.push(name);
-    }
-    return { keep, missing, surplus };
-}
-async function reconcileUnlocked(configPath, alias, request, deps) {
-    const findings = [];
-    const ctx = await context(alias, { ...deps, configPath });
-    const config = await loadConfig(configPath), entry = config.workspaceModes.get(alias);
-    const planned = await plan(ctx, entry), { life, accept, ownership, adapter } = services(deps);
-    const add = (name, outcome) => { findings.push({ target: targetFor(alias, name), ...outcome }); };
-    await doctorGate(ctx, deps);
-    // A surplus writer that cannot be fenced is reported on its own target and left in place; the others proceed.
-    const unfenced = new Set();
-    for (const name of planned.surplus) {
-        try {
-            await fenced(ctx, name, deps, (leased) => preflight(leased, [name], request.discard, deps));
-        }
-        catch (error) {
-            if (!FENCE_CODES.includes(codeFor(error)))
-                throw error;
-            unfenced.add(name);
-            add(name, { status: "failed", code: codeFor(error) });
-        }
-    }
-    const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
-    // Each writer's reconciliation, including first provisioning and acceptance, owns one fence.
-    for (const name of planned.keep) {
-        try {
-            await fenced(ctx, name, deps, async (ctx) => {
-                if (planned.missing.includes(name)) {
-                    const outcome = await life.provisionWriter(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory, ...(request.baseRef ? { baseRef: request.baseRef } : {}) });
-                    add(name, outcome);
-                    if (outcome.status === "failed")
-                        return;
-                }
-                // Settings first: a drifted writer is left exactly as it is, neither migrated nor accepted again (#134).
-                if (!planned.missing.includes(name)) {
-                    const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory });
-                    if (drift) {
-                        add(name, drift);
-                        return;
-                    }
-                    const state = await readWriterState(ctx.home, name);
-                    if (!state)
-                        throw new Error("writer_state_invalid");
-                    const limits = writerLimits(entry.container);
-                    if (!sameWriterLimits(state.limits, limits)) {
-                        const { limits: _previous, ...rest } = state;
-                        await writeWriterState(ctx.home, name, { ...rest, ...(limits ? { limits } : {}) });
-                        add(name, { status: "ok", code: "writer_limits_updated" });
-                    }
-                }
-                // Decide for both clients before removing anything, so a divergent registration of one client never
-                // costs the writer its owned registration of the other. A client that is not installed has nothing to keep.
-                let divergent = false;
-                const owned = [];
-                for (const client of ["claude-code", "codex"]) {
-                    const expected = intent(ctx, name, client);
-                    const record = await ownership.get({ client, scope: client === "codex" ? "user" : "local", alias: expected.name });
-                    const current = await adapter.inspect(expected);
-                    if (record ? current === "divergent" : current === "equivalent" || current === "divergent")
-                        divergent = true;
-                    else if (record)
-                        owned.push(expected);
-                }
-                if (!divergent) {
-                    for (const expected of owned) {
-                        try {
-                            await unregisterWriter(ownership, adapter, expected);
-                        }
-                        catch (error) {
-                            if (codeFor(error) !== "ownership_diverged")
-                                throw error;
-                            divergent = true;
-                        }
-                    }
-                }
-                const hook = await writerHook(ctx, name, deps, "remove", false);
-                if (hook)
-                    findings.push({ target: targetFor(alias, name), ...hook });
-                const state = await readWriterState(ctx.home, name);
-                if (!state)
-                    throw new Error("writer_state_invalid");
-                if (divergent) {
-                    if (state.launch !== "legacy")
-                        await writeWriterState(ctx.home, name, { ...state, launch: "legacy" });
-                    add(name, { status: "failed", code: "registration_divergent" });
-                    return;
-                }
-                const paths = writerPaths(ctx.home, name), wrapper = renderWrapper(ctx.nodePath, ctx.releaseRoot, name);
-                if (!(await lstat(paths.wrapper)).isFile())
-                    throw new Error("writer_state_invalid");
-                const wrapperChanged = wrapperDigest(await readFile(paths.wrapper, "utf8")) !== wrapperDigest(wrapper);
-                if (wrapperChanged) {
-                    const temporary = join(paths.root, `.wrapper-${randomUUID()}.tmp`);
-                    try {
-                        await writeFile(temporary, wrapper, { flag: "wx", mode: 0o700 });
-                        await rename(temporary, paths.wrapper);
-                    }
-                    finally {
-                        await rm(temporary, { force: true });
-                    }
-                }
-                // A launch change also needs fresh provider-free acceptance, even when wrapper bytes match.
-                const migrated = state.launch !== "relay";
-                if (migrated || wrapperChanged) {
-                    const { acceptance: _oldAcceptance, ...unaccepted } = state;
-                    await writeWriterState(ctx.home, name, { ...unaccepted, launch: "relay", phase: "not_ready" });
-                }
-                // A ready phase with a stale binding (package upgrade, new image, Podman version) is accepted again (#130).
-                const current = await accept.acceptanceCurrent(ctx, name);
-                if (current === "stale") {
-                    const outcome = await accept.acceptWriter(ctx, name);
-                    add(name, outcome);
-                    if (outcome.status === "failed")
-                        return;
-                }
-                else if (current === "unknown") {
-                    add(name, { status: "failed", code: "podman_unavailable" });
-                    return;
-                }
-            });
-        }
-        catch (error) {
-            if (!FENCE_CODES.includes(codeFor(error)))
-                throw error;
-            add(name, { status: "failed", code: codeFor(error) });
-        }
-    }
-    for (const name of planned.surplus) {
-        if (unfenced.has(name))
-            continue;
-        const extras = [];
-        try {
-            add(name, await fenced(ctx, name, deps, (leased) => remove(leased, name, request.discard, deps, extras)));
-        }
-        catch (error) {
-            add(name, { status: "failed", code: codeFor(error) });
-        }
-        for (const extra of extras)
-            findings.push({ target: targetFor(alias, name), ...extra });
-    }
-    return result("apply", findings);
-}
+export { SETUP_LEASE_WAIT_MS } from "./setup-writers-common.js";
 /** Serializes planning, destructive-work refusal, mode commit and writer reconciliation. */
 export async function changeWriterMode(configPath, request, deps) {
     const operation = request.apply ? "apply" : "dry-run";
@@ -356,80 +65,18 @@ export async function changeWriterMode(configPath, request, deps) {
     }
     const action = async () => {
         let proposed;
-        // Record the base as provisioning resolves it, so a refused or remote-tracking form never reaches the modes file.
-        let recorded = request;
-        if (request.baseRef !== undefined) {
-            try {
-                recorded = { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps), request.baseRef) };
-            }
-            catch (error) {
-                return failed(codeFor(error));
-            }
-        }
-        else if (request.mode === "container" || request.mode === undefined && await containerRuntime()) {
-            const config = await loadConfig(configPath);
-            if (!config.workspaceModes.get(request.alias)?.container?.base) {
-                const bases = new Set();
-                for (let index = 1; index <= MAX_WRITERS; index++) {
-                    const state = await readWriterState(deps.home ?? homedir(), writerName(request.alias, index));
-                    if (state)
-                        bases.add(state.base.ref);
-                }
-                if (bases.size > 1)
-                    return result(operation, [{ target: modesTarget(request.alias), status: "failed", code: "workspace_base_ambiguous" }]);
-                if (bases.size === 1)
-                    recorded = { ...request, baseRef: [...bases][0].replace(/^refs\/heads\//, "") };
-                // First provisioning: record the base it will resolve (origin/HEAD, else main), so default starts find writers.
-                else if (request.mode === "container") {
-                    try {
-                        recorded = { ...request, baseRef: await services(deps).life.baseBranchName(await context(request.alias, deps)) };
-                    }
-                    catch (error) {
-                        return failed(codeFor(error));
-                    }
-                }
-            }
-        }
+        const recorded = await inferBase(configPath, request, deps, containerRuntime, failed);
+        if ("schemaVersion" in recorded)
+            return recorded;
         return changeExecutionMode(configPath, recorded, {
             ...modeDependencies,
             beforeWrite: async (entry) => {
                 proposed = entry;
                 const ctx = await context(request.alias, deps), planned = await plan(ctx, entry);
                 try {
-                    if (request.apply) {
-                        await doctorGate(ctx, deps);
-                        for (const name of planned.surplus) {
-                            try {
-                                await fenced(ctx, name, deps, (leased) => preflight(leased, [name], request.discard ?? false, deps));
-                            }
-                            catch (error) {
-                                // Refuse the mode change, but name the writer that could not be fenced.
-                                if (FENCE_CODES.includes(codeFor(error)))
-                                    return result(operation, [{ target: targetFor(request.alias, name), status: "failed", code: codeFor(error) }]);
-                                throw error;
-                            }
-                        }
-                        // Settings drift before the write, so a kept writer with changed settings refuses the mode
-                        // change itself and the modes file never records a mode no writer matches (#163). Read-only like
-                        // the dry run, which fences nothing; reconcile re-checks under its fence. Missing writers have
-                        // no settings yet.
-                        if (entry.mode === "container") {
-                            const { life } = services(deps);
-                            const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
-                            const drifted = [];
-                            for (const name of planned.keep) {
-                                if (planned.missing.includes(name))
-                                    continue;
-                                const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: entry.container, rawConfig, overrideDirectory });
-                                if (drift)
-                                    drifted.push({ target: targetFor(request.alias, name), ...drift });
-                            }
-                            if (drifted.length)
-                                return result(operation, drifted);
-                        }
-                    }
-                    else
-                        await preflight(ctx, planned.surplus, request.discard ?? false, deps);
+                    if (request.apply)
+                        return await gateBeforeWrite(configPath, ctx, entry, planned, request.discard ?? false, operation, deps);
+                    await preflight(ctx, planned.surplus, request.discard ?? false, deps);
                 }
                 catch (error) {
                     return error instanceof DoctorGateError ? result(operation, [...failed(error.message).findings, ...error.findings]) : failed(codeFor(error));
@@ -442,18 +89,8 @@ export async function changeWriterMode(configPath, request, deps) {
                     if (request.apply)
                         writers = await reconcileUnlocked(configPath, request.alias, { discard: request.discard ?? false, ...(request.baseRef ? { baseRef: request.baseRef } : {}) }, deps);
                     else {
-                        const ctx = await context(request.alias, deps), planned = await plan(ctx, proposed), { life } = services(deps);
-                        const kept = [];
-                        const rawConfig = JSON.parse(await readFile(configPath, "utf8")), overrideDirectory = skillOverrideDirectory(configPath);
-                        for (const name of planned.keep) {
-                            // The same settings check as apply, so a drifted writer shows before anything is applied (#134).
-                            const drift = await life.writerSettingsDrift(ctx, { index: writerIndex(name), settings: proposed.container, rawConfig, overrideDirectory });
-                            const state = await readWriterState(ctx.home, name);
-                            const updatingLimits = state && state.phase !== "provisioning" && !sameWriterLimits(state.limits, writerLimits(proposed.container));
-                            kept.push({ target: targetFor(request.alias, name), ...(drift ?? { status: "planned", code: updatingLimits ? "writer_limits_update_planned" : "writer_planned" }) });
-                        }
-                        const refused = kept.some((finding) => finding.status === "failed" || finding.status === "divergent");
-                        writers = result("dry-run", [...kept, ...planned.surplus.map((name) => ({ target: targetFor(request.alias, name), status: "planned", code: "writer_remove_planned" }))], refused ? "failed" : "planned");
+                        const ctx = await context(request.alias, deps);
+                        writers = await plannedWriters(configPath, ctx, proposed, await plan(ctx, proposed), deps);
                     }
                 }
                 catch (error) {
@@ -473,7 +110,6 @@ export async function changeWriterMode(configPath, request, deps) {
         return failed(codeFor(error));
     }
 }
-const GLOBAL_ERRORS = new Set(["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid"]);
 export async function runWriterOperation(name, operation, opts, deps) {
     const reportOperation = operation === "verify" ? "verify" : opts.apply ? operation === "remove" ? "remove" : "apply" : "dry-run";
     if (!WRITER_NAME_PATTERN.test(name))

package/dist/skill-library.js

@@ -13,7 +13,7 @@ export const SKILL_NAME_PATTERN = /^(?=.{1,64}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
 export const BUILTIN_SKILL_PREFIX = "builtin:";
 /** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
-export const CONTROLLER_SKILLS = Object.freeze(["pi-session-orchestration"]);
+export const CONTROLLER_SKILLS = Object.freeze(["pi-session-orchestration", "pi-session-profiles"]);
 export const MAX_SKILL_TREE_FILES = 32;
 export const MAX_SKILL_TREE_BYTES = 1024 * 1024;
 const MAX_SKILL_TREE_DEPTH = 8;

package/dist/wake-hook.d.ts

@@ -139,11 +139,22 @@ export interface WaiterLockOptions {
     readonly pid?: number;
     readonly isAlive?: (pid: number) => boolean;
     readonly maxAgeMs?: number;
+    /** Test seam: runs after a lock was judged stale and before its reclamation starts. */
+    readonly beforeReclaim?: () => void;
 }
 /**
  * At most one waiter per turn: `<claims>/wait-…` is created exclusively and holds the owner's pid. A lock whose owner
  * is alive (and younger than `maxAgeMs`, which guards against a reused pid) means another waiter already covers this
  * turn: returns `undefined`. A stale lock (dead pid, too old, unreadable content) is replaced. Returns the lock path.
+ *
+ * Reclaiming a stale lock is serialized by the exclusive guard `<lock>.reclaim`, and the lock is judged again while
+ * holding it: an earlier observation never deletes a lock that another waiter created after it. A guard that is already
+ * there means another waiter is reclaiming and will cover the turn. A guard left by a crash between two calls blocks
+ * reclamation for that one turn only, until `cleanupOldClaims` removes it. A guard that cannot be created (for example
+ * in a full runtime directory) fails like the lock itself, and the caller waits without a lock rather than dropping the
+ * wake. Remaining limit: the guard does not serialize a fresh create or a release, so a lock judged stale by age alone
+ * (its pid alive) that its owner releases between the inode check and the unlink, and that a new waiter recreates with
+ * the same inode number, can still be removed.
  */
 export declare function acquireWaiterLock(claims: string, namespace: WakeNamespace, sessionId: string, turnId: string, options?: WaiterLockOptions): string | undefined;
 /** Removes the lock only if it still names `pid`, so a replacement lock of another waiter is never deleted. */

package/dist/wake-hook.js

@@ -448,12 +448,12 @@ function readLockPid(path) {
         fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
         const stat = fstatSync(fd);
         if (!stat.isFile())
-            return { pid: undefined, ageMs: Number.POSITIVE_INFINITY };
+            return { pid: undefined, ageMs: Number.POSITIVE_INFINITY, ino: stat.ino };
         const buffer = Buffer.alloc(32);
         const length = readSync(fd, buffer, 0, buffer.length, null);
         const text = buffer.toString("utf8", 0, length).trim();
         const pid = /^[0-9]{1,10}$/.test(text) ? Number(text) : undefined;
-        return { pid: pid !== undefined && pid > 0 ? pid : undefined, ageMs: Date.now() - stat.mtimeMs };
+        return { pid: pid !== undefined && pid > 0 ? pid : undefined, ageMs: Date.now() - stat.mtimeMs, ino: stat.ino };
     }
     catch {
         return undefined;
@@ -470,11 +470,23 @@ function readLockPid(path) {
  * At most one waiter per turn: `<claims>/wait-…` is created exclusively and holds the owner's pid. A lock whose owner
  * is alive (and younger than `maxAgeMs`, which guards against a reused pid) means another waiter already covers this
  * turn: returns `undefined`. A stale lock (dead pid, too old, unreadable content) is replaced. Returns the lock path.
+ *
+ * Reclaiming a stale lock is serialized by the exclusive guard `<lock>.reclaim`, and the lock is judged again while
+ * holding it: an earlier observation never deletes a lock that another waiter created after it. A guard that is already
+ * there means another waiter is reclaiming and will cover the turn. A guard left by a crash between two calls blocks
+ * reclamation for that one turn only, until `cleanupOldClaims` removes it. A guard that cannot be created (for example
+ * in a full runtime directory) fails like the lock itself, and the caller waits without a lock rather than dropping the
+ * wake. Remaining limit: the guard does not serialize a fresh create or a release, so a lock judged stale by age alone
+ * (its pid alive) that its owner releases between the inode check and the unlink, and that a new waiter recreates with
+ * the same inode number, can still be removed.
  */
 export function acquireWaiterLock(claims, namespace, sessionId, turnId, options = {}) {
     const path = join(claims, waiterLockName(namespace, sessionId, turnId));
     const pid = options.pid ?? process.pid, isAlive = options.isAlive ?? processAlive, maxAgeMs = options.maxAgeMs ?? DEFAULT_BUDGET_MS + WAITER_LOCK_GRACE_MS;
-    for (let attempt = 0; attempt < 3; attempt += 1) {
+    const stale = (held) => 
+    // A lock that is still being written (no pid yet) is young; it is stale only once it has been unreadable for a while.
+    !(held.pid !== undefined ? isAlive(held.pid) && held.ageMs <= maxAgeMs : held.ageMs < 2000);
+    const create = () => {
         try {
             const fd = openSync(path, "wx", 0o600);
             try {
@@ -488,18 +500,49 @@ export function acquireWaiterLock(claims, namespace, sessionId, turnId, options
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
+            return undefined;
         }
+    };
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        if (create() !== undefined)
+            return path;
         const held = readLockPid(path);
         if (held === undefined)
             continue; // vanished meanwhile: try to create it again
-        // A lock that is still being written (no pid yet) is young; it is stale only once it has been unreadable for a while.
-        const live = held.pid !== undefined ? isAlive(held.pid) && held.ageMs <= maxAgeMs : held.ageMs < 2000;
-        if (live)
+        if (!stale(held))
             return undefined;
+        options.beforeReclaim?.();
+        const guard = `${path}.reclaim`;
         try {
-            unlinkSync(path);
+            closeSync(openSync(guard, "wx", 0o600));
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return undefined;
+            throw error;
+        }
+        try {
+            const current = readLockPid(path);
+            if (current !== undefined) {
+                if (!stale(current))
+                    return undefined;
+                // Only the file that was judged stale is removed; a different one at the path is decided by the create below.
+                try {
+                    if (lstatSync(path, { throwIfNoEntry: false })?.ino === current.ino)
+                        unlinkSync(path);
+                }
+                catch { /* gone or replaced */ }
+            }
+            // Created while holding the guard, so a reclamation on the last attempt still covers the turn.
+            if (create() !== undefined)
+                return path;
+        }
+        finally {
+            try {
+                unlinkSync(guard);
+            }
+            catch { /* already gone */ }
         }
-        catch { /* replaced by someone else: the next attempt decides */ }
     }
     return undefined;
 }