pi-session-mcp 0.8.3 → 0.12.0

package/dist/setup-hooks.js

@@ -0,0 +1,657 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { readWriterState, writerEventDeliveryEnabled, writerPaths, writerRegistrationName, writersRoot, WRITER_NAME_PATTERN } from "./writer-state.js";
+/**
+ * The wake hook of ADR 0011 in Claude Code settings.
+ *
+ * Contract, not version (ADR 0004): Claude Code has no command for hooks, so there is no client
+ * version gate and no command to inspect. The entry follows Claude Code's settings schema
+ * (`hooks.PostToolUse[]` with `matcher`, and `hooks[]` of `type: "command"` with `command`,
+ * `timeout` in seconds and `asyncRewake`). Setup writes that entry and verify checks the file
+ * content only; whether the running client honours it is the acceptance check of the release.
+ *
+ * Settings files by Claude Code scope (documented client behaviour):
+ * - user: `${CLAUDE_CONFIG_DIR ?? ~/.claude}/settings.json`
+ * - project: `<project>/.claude/settings.json`
+ * - local: `<project>/.claude/settings.local.json`
+ * A project is the canonical (realpath) working directory, like the project skill slot. An
+ * entry written while a session is running may need a session restart (or the client's own
+ * settings reload) before it fires; setup cannot observe that.
+ *
+ * Ownership is the same pending-before-write transaction as skills: the pending record names the
+ * entry about to be written (and, for an update, the owned entry it replaces) by fingerprint, so
+ * an interrupted run is settled from the file alone. Records hold fingerprints only, never paths
+ * or command strings.
+ */
+export const WAKE_HOOK_ALIAS = "hook:pi-session-mcp-wake";
+/** Default wake budget; the hook timeout must cover it (ADR 0011, item 4). */
+export const WAKE_BUDGET_MS = 1_800_000;
+/** Seconds added to the budget so the hook timeout never fires before the program's own budget. */
+export const WAKE_TIMEOUT_MARGIN_SECONDS = 60;
+export const WAKE_MATCHER = [
+    "mcp__pi-session-mcp__pi_session_prompt",
+    "mcp__pi-session-mcp__pi_turn_get",
+].join("|");
+/** A command referencing this program path marks an entry as pi-session-mcp's. */
+const WAKE_PROGRAM = /\/dist\/wake-main\.js(?=$|[\s"'])/;
+/** Paths are embedded unquoted in a shell command: only characters that never need quoting. */
+const SAFE_COMMAND_PATH = /^\/[A-Za-z0-9_@%+=:,./-]*$/;
+const MAX_SETTINGS_BYTES = 4 * 1024 * 1024;
+class HookError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+/** The settings file changed between read and rename. */
+class SwapMismatch extends Error {
+}
+/** The canonical, deterministic entry. Throws `hook_path_unsafe` for a path that would need shell quoting. */
+export function buildWakeEntry(roots) {
+    const nodePath = roots.nodePath ?? process.execPath;
+    const program = `${roots.packageRoot}/dist/wake-main.js`;
+    const budgetMs = roots.budgetMs ?? WAKE_BUDGET_MS;
+    if (!Number.isInteger(budgetMs) || budgetMs < 1)
+        throw new HookError("hook_budget_invalid");
+    if (!isAbsolute(roots.packageRoot) || !SAFE_COMMAND_PATH.test(nodePath) || !SAFE_COMMAND_PATH.test(program))
+        throw new HookError("hook_path_unsafe");
+    return {
+        matcher: WAKE_MATCHER,
+        hooks: [{ type: "command", command: `${nodePath} ${program} --budget-ms ${budgetMs}`, timeout: Math.ceil(budgetMs / 1000) + WAKE_TIMEOUT_MARGIN_SECONDS, asyncRewake: true }],
+    };
+}
+/** The settings file of a scope. `projectRoot` must already be canonical. Pure. */
+export function wakeSettingsPath(scope, input) {
+    if (scope === "user") {
+        const configured = input.env.CLAUDE_CONFIG_DIR;
+        const directory = configured !== undefined && configured !== "" ? configured : join(input.home, ".claude");
+        if (!isAbsolute(directory))
+            throw new HookError("settings_location_invalid");
+        return join(directory, "settings.json");
+    }
+    if (input.projectRoot === undefined || !isAbsolute(input.projectRoot))
+        throw new HookError("settings_location_invalid");
+    return join(input.projectRoot, ".claude", scope === "project" ? "settings.json" : "settings.local.json");
+}
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+/** The fingerprint of an entry: sha256 of its JSON text, which is also what setup wrote. */
+export const wakeEntryFingerprint = (entry) => sha256(JSON.stringify(entry));
+/**
+ * Where the scope's settings live and how its ownership is keyed. A project may be untrusted: a
+ * link at `.claude` or at the settings file there makes the slot invalid, so setup never writes
+ * outside the project. In the operator's own configuration directory a linked settings file (for
+ * example into a dotfiles checkout) is followed and written through. Project and local records
+ * are bound to an opaque identity of the project, so another project never shares them.
+ */
+/** The ownership key of a scope's hook. It looks at no settings file: only the project's canonical directory. */
+async function recordTargetOf(scope, roots) {
+    if (scope === "user")
+        return { client: "claude-code", scope, alias: WAKE_HOOK_ALIAS };
+    return { client: "claude-code", scope, alias: `${WAKE_HOOK_ALIAS}@${sha256(await realpath(roots.cwd)).slice(0, 16)}` };
+}
+async function locate(scope, roots) {
+    if (scope === "user") {
+        const file = wakeSettingsPath("user", roots);
+        const resolved = await followUserLink(file);
+        return { file: resolved, recordTarget: { client: "claude-code", scope, alias: WAKE_HOOK_ALIAS }, guard: await guardOf(dirname(resolved), false) };
+    }
+    let projectRoot;
+    try {
+        projectRoot = await realpath(roots.cwd);
+    }
+    catch {
+        throw new HookError("settings_location_invalid");
+    }
+    const file = wakeSettingsPath(scope, { ...roots, projectRoot });
+    for (const [path, directory] of [[dirname(file), true], [file, false]]) {
+        let entry;
+        try {
+            entry = await lstat(path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw new HookError("settings_location_invalid");
+        }
+        if (entry.isSymbolicLink() || (directory ? !entry.isDirectory() : !entry.isFile()))
+            throw new HookError("settings_location_invalid");
+    }
+    const identity = sha256(projectRoot).slice(0, 16);
+    return { file, recordTarget: { client: "claude-code", scope, alias: `${WAKE_HOOK_ALIAS}@${identity}` }, guard: await guardOf(dirname(file), true) };
+}
+async function directoryIdentity(path, strict) {
+    let entry;
+    try {
+        entry = strict ? await lstat(path) : await stat(path);
+    }
+    catch {
+        throw new HookError("settings_location_invalid");
+    }
+    if (entry.isSymbolicLink() || !entry.isDirectory())
+        throw new HookError("settings_location_invalid");
+    return { dev: entry.dev, ino: entry.ino };
+}
+async function guardOf(path, strict) {
+    try {
+        return { path, strict, identity: await directoryIdentity(path, strict) };
+    }
+    catch (error) {
+        // A directory that does not exist yet is created, and then recorded, by the commit.
+        try {
+            await lstat(path);
+        }
+        catch (inner) {
+            if (inner.code === "ENOENT")
+                return { path, strict };
+        }
+        throw error;
+    }
+}
+/**
+ * Re-checks the location right before it is written: the directory is still the one that was
+ * seen (and, for a project, not a link), and a project's settings file is not a link. A mismatch
+ * writes nothing.
+ */
+async function assertLocation(guard, file) {
+    const now = await directoryIdentity(guard.path, guard.strict);
+    if (guard.identity && (now.dev !== guard.identity.dev || now.ino !== guard.identity.ino))
+        throw new HookError("settings_changed");
+    if (!guard.strict)
+        return;
+    try {
+        const entry = await lstat(file);
+        if (entry.isSymbolicLink() || !entry.isFile())
+            throw new HookError("settings_location_invalid");
+    }
+    catch (error) {
+        if (error instanceof HookError)
+            throw error;
+        if (error.code !== "ENOENT")
+            throw new HookError("settings_location_invalid");
+    }
+}
+async function followUserLink(file) {
+    let entry;
+    try {
+        entry = await lstat(file);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            // An absent file is fine; the directory, if it exists, must be one.
+            try {
+                if (!(await stat(dirname(file))).isDirectory())
+                    throw new HookError("settings_location_invalid");
+            }
+            catch (inner) {
+                if (inner instanceof HookError)
+                    throw inner;
+                if (inner.code !== "ENOENT")
+                    throw new HookError("settings_location_invalid");
+            }
+            return file;
+        }
+        throw new HookError("settings_location_invalid");
+    }
+    if (entry.isFile())
+        return file;
+    if (!entry.isSymbolicLink())
+        throw new HookError("settings_location_invalid");
+    try {
+        const real = await realpath(file);
+        if (!(await lstat(real)).isFile())
+            throw new Error("not a file");
+        return real;
+    }
+    catch {
+        throw new HookError("settings_location_invalid");
+    }
+}
+async function readSnapshot(file) {
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { exists: false, token: "absent", mode: 0o600, document: {} };
+        throw new HookError(code === "ELOOP" || code === "ENOTDIR" ? "settings_location_invalid" : "settings_unreadable");
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new HookError("settings_location_invalid");
+        if (info.size > MAX_SETTINGS_BYTES)
+            throw new HookError("settings_unparseable");
+        const bytes = await handle.readFile();
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            throw new HookError("settings_unparseable");
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new HookError("settings_unparseable");
+        return { exists: true, token: sha256(bytes), mode: info.mode & 0o7777, document: parsed };
+    }
+    catch (error) {
+        throw error instanceof HookError ? error : new HookError("settings_unreadable");
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function currentToken(file) {
+    try {
+        return sha256(await readFile(file));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw new HookError("settings_unreadable");
+    }
+}
+/**
+ * Writes the document next to the file and swaps it in only while the file still has the bytes
+ * that were read. The final compare happens right before the rename; a creation uses a hard link
+ * so it can never replace a file that appeared meanwhile. The location is re-checked at the same
+ * point (`assertLocation`): the directory is the one that was seen and not a link, and a project's
+ * settings file is not a link.
+ *
+ * Residual race, by design: a write by the same user that lands between the final compare and the
+ * rename is lost, because a rename-based swap cannot be made atomic against it and Claude Code
+ * does not honor setup's ownership lock. The compare keeps the window to a few system calls; a
+ * mismatch before it retries the whole read-modify-write.
+ */
+async function commit(file, before, document, dependencies, seen) {
+    const directory = dirname(file);
+    // A directory swapped for a link after locate() must not be created through or written into.
+    if (seen.identity)
+        await assertLocation(seen, file);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const guard = seen.identity ? seen : { ...seen, identity: await directoryIdentity(directory, seen.strict) };
+    const temporary = join(directory, `.${randomUUID()}.pi-session-mcp.tmp`);
+    const mode = before.exists ? before.mode : 0o600;
+    let installed = false;
+    try {
+        const handle = await open(temporary, "wx", mode);
+        try {
+            await handle.chmod(mode);
+            await handle.writeFile(`${JSON.stringify(document, null, 2)}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await dependencies.beforeCommit?.();
+        await assertLocation(guard, file);
+        if (await currentToken(file) !== before.token)
+            throw new SwapMismatch();
+        if (before.exists)
+            await rename(temporary, file);
+        else {
+            try {
+                await link(temporary, file);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new SwapMismatch();
+                throw error;
+            }
+        }
+        installed = true;
+        await syncDirectory(directory);
+    }
+    finally {
+        if (!installed || !before.exists)
+            await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function postToolUse(document) {
+    const hooks = document.hooks;
+    if (hooks === undefined)
+        return { document, entries: undefined };
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        throw new HookError("settings_shape_invalid");
+    const entries = hooks.PostToolUse;
+    if (entries === undefined)
+        return { document, entries: undefined };
+    if (!Array.isArray(entries))
+        throw new HookError("settings_shape_invalid");
+    return { document, entries };
+}
+const referencesWake = (entry) => {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const hooks = entry.hooks;
+    return Array.isArray(hooks) && hooks.some((hook) => !!hook && typeof hook === "object" && typeof hook.command === "string" && WAKE_PROGRAM.test(hook.command));
+};
+/** Indexes of pi-session-mcp's entries, and of those that setup's record names exactly. */
+function classify(entries, record) {
+    const all = [];
+    const named = [];
+    (entries ?? []).forEach((entry, index) => {
+        if (!referencesWake(entry))
+            return;
+        all.push(index);
+        if (record && wakeEntryFingerprint(entry) === record.fingerprint)
+            named.push(index);
+    });
+    return { all, named };
+}
+/**
+ * Settles a record from the file alone. A pending record whose entry is present becomes owned;
+ * one that still shows the entry it replaces returns to owning that entry; otherwise nothing of
+ * the transaction reached the file and the record is dropped.
+ */
+function settle(record, entries) {
+    if (!record || record.phase === "owned")
+        return record;
+    const present = (fingerprint) => (entries ?? []).some((entry) => referencesWake(entry) && wakeEntryFingerprint(entry) === fingerprint);
+    if (present(record.fingerprint))
+        return { target: record.target, fingerprint: record.fingerprint, previous: "absent", phase: "owned", transactionId: record.transactionId };
+    if (record.replaces !== undefined && present(record.replaces))
+        return { target: record.target, fingerprint: record.replaces, previous: "absent", phase: "owned", transactionId: record.transactionId };
+    return undefined;
+}
+const healthy = (ownership) => { ownership.assertHealthy?.(); };
+function edited(document, change, cleanup) {
+    const next = JSON.parse(JSON.stringify(document));
+    const hooks = (next.hooks ??= {});
+    const entries = (hooks.PostToolUse ??= []);
+    change(entries);
+    // Only structures that setup's entry left empty and nothing else uses are removed; any other
+    // content keeps its (possibly empty) array.
+    if (cleanup && entries.length === 0 && Object.keys(hooks).length === 1 && Object.keys(next).length === 1)
+        delete next.hooks;
+    return next;
+}
+/** Install, update, verify or remove the wake hook of one Claude Code scope. Never throws. */
+export async function runWakeHook(request) {
+    try {
+        return await reconcile(request);
+    }
+    catch (error) {
+        // A ledger failure keeps its own stable code (`ownership_unreadable`, `operation_aborted`, ...).
+        const message = error instanceof Error ? error.message : "";
+        return { status: "failed", code: error instanceof HookError ? error.code : /^(ownership_[a-z_]+|operation_aborted)$/.test(message) ? message : "hook_install_failed" };
+    }
+}
+async function reconcile(request) {
+    // Delivery off and no record of ours: nothing to maintain, so the client's settings are not even looked at
+    // (an unparseable or linked file there is not setup's business). Removal follows the record and checks it itself.
+    if (!request.enabled && request.operation !== "remove" && request.operation !== "rollback" && !await ownsWakeHook(request.scope, request.roots, request.ownership)) {
+        return { status: "unchanged", code: "hook_not_enabled" };
+    }
+    const location = await locate(request.scope, request.roots);
+    const dependencies = request.dependencies ?? {};
+    // A changed file is re-read once from the start; the second change fails.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            return await step(request, location, dependencies);
+        }
+        catch (error) {
+            if (!(error instanceof SwapMismatch))
+                throw error;
+        }
+    }
+    throw new HookError("settings_changed");
+}
+async function step(request, location, dependencies) {
+    const { operation, ownership, roots, enabled } = request;
+    const { recordTarget, file } = location;
+    const apply = operation === "apply";
+    const removing = operation === "remove" || operation === "rollback";
+    const mutating = apply || removing;
+    // The ledger first: when it cannot be read, nothing of the settings matters.
+    healthy(ownership);
+    const stored = await ownership.get(recordTarget);
+    const snapshot = await readSnapshot(file);
+    const { entries } = postToolUse(snapshot.document);
+    const record = settle(stored, entries);
+    // `recovered` is true when settling changed what the ledger says.
+    const recovered = stored !== undefined && (record === undefined || record.fingerprint !== stored.fingerprint || record.phase !== stored.phase);
+    const persistSettled = async () => {
+        if (!mutating || !recovered)
+            return;
+        healthy(ownership);
+        if (record)
+            await ownership.put(record);
+        else
+            await ownership.delete(recordTarget);
+        healthy(ownership);
+    };
+    // Settling comes first, so that a refusal below never leaves a transaction pending that the file already decided.
+    await persistSettled();
+    const { all, named } = classify(entries, record);
+    if (removing || (!enabled && operation !== "verify")) {
+        // Removal needs no configuration: it follows the record, and only an exactly owned entry goes.
+        if (!record)
+            return { status: "unchanged", code: removing ? "hook_not_owned" : "hook_not_enabled" };
+        if (named.length > 1 || (named.length === 0 && all.length > 0))
+            return { status: "divergent", code: "hook_divergent" };
+        if (named.length === 0) {
+            if (mutating) {
+                healthy(ownership);
+                await ownership.delete(recordTarget);
+                healthy(ownership);
+            }
+            return { status: mutating ? "ok" : "unchanged", code: mutating ? "hook_absent" : "hook_not_enabled" };
+        }
+        if (request.keep && await request.keep())
+            return { status: "unchanged", code: "hook_kept_shared" };
+        if (!mutating)
+            return { status: "planned", code: "hook_remove_planned" };
+        await commit(file, snapshot, edited(snapshot.document, (list) => { list.splice(named[0], 1); }, true), dependencies, location.guard);
+        await dependencies.checkpoint?.("written");
+        healthy(ownership);
+        await ownership.delete(recordTarget);
+        healthy(ownership);
+        return { status: "ok", code: "hook_removed" };
+    }
+    if (operation === "verify") {
+        if (!enabled)
+            return record && named.length > 0 ? { status: "failed", code: "hook_delivery_off" } : { status: "unchanged", code: "hook_not_enabled" };
+        const canonical = buildWakeEntry(roots);
+        const fingerprint = wakeEntryFingerprint(canonical);
+        const present = all.filter((index) => wakeEntryFingerprint(entries[index]) === fingerprint);
+        if (all.length === 0)
+            return { status: "failed", code: "hook_missing" };
+        if (all.length !== 1 || present.length !== 1)
+            return { status: "failed", code: "hook_not_equivalent" };
+        if (stored?.phase === "pending")
+            return { status: "failed", code: "hook_ownership_pending" };
+        if (!record || record.fingerprint !== fingerprint)
+            return { status: "failed", code: "hook_not_owned" };
+        try {
+            if (!(await lstat(`${roots.packageRoot}/dist/wake-main.js`)).isFile())
+                throw new Error("not a file");
+        }
+        catch {
+            return { status: "failed", code: "hook_program_missing" };
+        }
+        return { status: "ok", code: "hook_verified" };
+    }
+    const canonical = buildWakeEntry(roots);
+    const fingerprint = wakeEntryFingerprint(canonical);
+    let replaces;
+    let place;
+    let verb;
+    if (all.length === 0) {
+        verb = "add";
+        place = (list) => { list.push(canonical); };
+    }
+    else if (all.length === 1) {
+        const index = all[0];
+        const current = wakeEntryFingerprint(entries[index]);
+        if (current === fingerprint) {
+            return { status: apply && recovered ? "ok" : "unchanged", code: apply && recovered ? "hook_recovered" : "hook_already_equivalent" };
+        }
+        // Only an entry that setup's own record names exactly may be replaced; anything else is the operator's.
+        if (!record || record.fingerprint !== current)
+            return { status: "divergent", code: "hook_divergent" };
+        verb = "update";
+        replaces = current;
+        place = (list) => { list[index] = canonical; };
+    }
+    else
+        return { status: "divergent", code: "hook_divergent" };
+    if (!apply)
+        return { status: "planned", code: `hook_${verb}_planned` };
+    const pending = {
+        target: recordTarget, fingerprint, previous: "absent", phase: "pending", transactionId: randomUUID(),
+        ...(replaces === undefined ? {} : { replaces }),
+    };
+    healthy(ownership);
+    await ownership.put(pending);
+    healthy(ownership);
+    await dependencies.checkpoint?.("pending-recorded");
+    await commit(file, snapshot, edited(snapshot.document, place, false), dependencies, location.guard);
+    await dependencies.checkpoint?.("written");
+    healthy(ownership);
+    await ownership.put({ target: recordTarget, fingerprint, previous: "absent", phase: "owned", transactionId: pending.transactionId });
+    healthy(ownership);
+    return { status: "ok", code: verb === "add" ? "hook_added" : "hook_updated" };
+}
+/** Reconcile the hook of one scope, for example a writer's local scope. Call under the ownership transaction. */
+export async function installWakeHook(options) {
+    const outcome = await runWakeHook({
+        operation: options.apply ? "apply" : "dry-run", scope: options.scope, enabled: options.delivery, ownership: options.ownership,
+        roots: { packageRoot: options.packageRoot, home: options.home, cwd: options.cwd, env: options.env, ...(options.nodePath === undefined ? {} : { nodePath: options.nodePath }), ...(options.budgetMs === undefined ? {} : { budgetMs: options.budgetMs }) },
+        ...(options.dependencies === undefined ? {} : { dependencies: options.dependencies }),
+    });
+    return { target: { client: "claude-code", scope: options.scope, alias: WAKE_HOOK_ALIAS }, ...outcome };
+}
+/**
+ * Whether setup holds a record for the hook of this scope (and, for project and local, this
+ * project). Fails closed: a ledger that cannot be read answers `true`, so callers take the full
+ * path and fail with the ledger's own code instead of skipping an owned entry. A project that
+ * does not exist cannot have a record and answers `false`.
+ */
+export async function ownsWakeHook(scope, roots, ownership) {
+    let target;
+    try {
+        target = await recordTargetOf(scope, roots);
+    }
+    catch {
+        return false;
+    }
+    try {
+        return (await ownership.get(target)) !== undefined;
+    }
+    catch {
+        return true;
+    }
+}
+/** Unchanged outcomes that say nothing happened because nothing was wanted or owned; never part of a setup report. (Verify's failed `hook_not_owned` is news.) */
+const NO_NEWS = new Set(["hook_not_enabled", "hook_not_owned"]);
+export class FileSetupHookInstaller {
+    roots;
+    dependencies;
+    constructor(roots, dependencies = {}) {
+        this.roots = roots;
+        this.dependencies = dependencies;
+    }
+    async run(operation, target, ownership) {
+        const reported = { ...target, alias: WAKE_HOOK_ALIAS };
+        // Not applicable (a Codex target) is no news and is not reported, so a report without hooks keeps its 0.10 shape.
+        if (target.client !== "claude-code" || !["user", "project", "local"].includes(target.scope))
+            return [];
+        let enabled = false;
+        // Removal follows the record; only the other operations depend on the configuration.
+        if (operation !== "remove" && operation !== "rollback") {
+            try {
+                enabled = await this.roots.delivery();
+            }
+            catch {
+                return [{ target: reported, status: "failed", code: "hook_config_unreadable" }];
+            }
+        }
+        const { delivery: _delivery, configPath, ...roots } = this.roots;
+        const keep = configPath !== undefined && target.scope === "local"
+            ? () => localHookNeededByOthers({ ownership, home: roots.home, cwd: roots.cwd, configPath, except: "host" })
+            : undefined;
+        const outcome = await runWakeHook({ operation, scope: target.scope, roots, enabled, ownership, dependencies: this.dependencies, ...(keep ? { keep } : {}) });
+        // No hook wanted and none owned is no news either: omitted, like the writer path does.
+        return outcome.status === "unchanged" && NO_NEWS.has(outcome.code) ? [] : [{ target: reported, ...outcome }];
+    }
+    async owns(target, ownership) {
+        if (target.client !== "claude-code" || !["user", "project", "local"].includes(target.scope))
+            return false;
+        return ownsWakeHook(target.scope, this.roots, ownership);
+    }
+}
+/**
+ * The sharing rule of the local-scope entry. Claude Code's local settings file of a project holds
+ * one wake entry, and one ownership record stands for it, however many registrations need it.
+ * It is removed only when none of the others needs it any more. Another registration needs it
+ * when it is still owned in local scope and its server enables spool delivery:
+ *
+ * - a writer (`claude-code:local:pi-coding-<name>` owned) whose configured workspace resolves to
+ *   this project and whose own configuration enables delivery; a writer whose project cannot be
+ *   determined counts as needing it (the safe side: an entry too many, never one too few);
+ * - the host registration (`claude-code:local:pi-session-mcp` owned) while the host configuration
+ *   enables delivery. Its project is not recorded, so it counts for every project.
+ *
+ * `except` names the registration that is going away: a writer by its name, or the host.
+ * Any error answers `true`, so a doubt never removes a shared entry.
+ */
+export async function localHookNeededByOthers(options) {
+    try {
+        const project = await realpath(options.cwd);
+        const { loadConfig } = await import("./config.js");
+        const config = await loadConfig(options.configPath);
+        if (options.except !== "host") {
+            const host = await options.ownership.get({ client: "claude-code", scope: "local", alias: "pi-session-mcp" });
+            if (host?.phase === "owned" && config.eventDelivery === "spool")
+                return true;
+        }
+        let names;
+        try {
+            names = await readdir(writersRoot(options.home));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        for (const name of names.filter((candidate) => WRITER_NAME_PATTERN.test(candidate)).sort()) {
+            if (options.except !== "host" && options.except.writer === name)
+                continue;
+            const record = await options.ownership.get({ client: "claude-code", scope: "local", alias: writerRegistrationName(name) });
+            if (record?.phase !== "owned")
+                continue;
+            if (!await writerEventDeliveryEnabled(writerPaths(options.home, name).config))
+                continue;
+            const state = await readWriterState(options.home, name);
+            const workspace = state ? config.workspaces.get(state.alias) : undefined;
+            if (workspace === undefined)
+                return true;
+            try {
+                if (await realpath(workspace) === project)
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/setup-main.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createProductionSetup } from "./setup.js";
-/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias` or `[--apply] --customize-skill <name>`. */
+/** Executable entry point for client registrations, skill customization and `--repo <alias>` execution modes. */
 export interface SetupMainDependencies {
     readonly createSetup?: typeof createProductionSetup;
     readonly packageRoot?: string;