pi-session-mcp 0.8.3 → 0.12.0

package/dist/doctor.d.ts

@@ -3,7 +3,7 @@ import { type ExtensionSpec } from "./extension-spec.js";
 import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "extension_missing" | "extension_version_mismatch" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated";
+export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "workspace_gitfile" | "workspace_mode_unset" | "workspace_base_unset" | "workspace_host_writes_accepted" | "container_runtime_unavailable" | "container_profile_refused" | "writer_lease_directory" | "writer_not_ready" | "writer_not_migrated" | "writer_off_default_base" | "writer_dirty" | "writer_git_identity_missing" | "writer_uncollected_bundle" | "extension_missing" | "extension_version_mismatch" | "extension_unpinned" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated" | "event_spool_root";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -36,17 +36,51 @@ export interface DoctorFileSystem {
     readonly access: (path: string, mode: number) => Promise<void>;
     /** Canonical path; defaults to the real file system when an injected fake omits it. */
     readonly realpath?: (path: string) => Promise<string>;
+    /** Metadata without following a final symbolic link; defaults to the real file system when omitted. */
+    readonly lstat?: (path: string) => Promise<{
+        readonly isFile: () => boolean;
+        readonly isSymbolicLink: () => boolean;
+        readonly size?: number;
+    }>;
+    /** At most `maxBytes` of a regular file's start, never following a symbolic link; defaults to the real file system when omitted. */
+    readonly readPrefix?: (path: string, maxBytes: number) => Promise<string>;
 }
 export interface DoctorDependencies {
+    readonly home?: string;
+    /** Pi's agent directory; defaults to the SDK's `getAgentDir()`. */
+    readonly agentDir?: string;
+    readonly writerRuntime?: () => Promise<{
+        podmanVersion?: string;
+        imageExists: (id: string) => Promise<boolean>;
+    }>;
     readonly packageRoot?: string;
     readonly nodeVersion?: string;
     readonly fileSystem?: DoctorFileSystem;
-    readonly loadConfig?: () => Promise<AppConfig>;
+    /** Explicit configuration path, otherwise captured once from PI_SESSION_MCP_CONFIG. */
+    readonly configPath?: string;
+    readonly loadConfig?: (path?: string) => Promise<AppConfig>;
+    /** Original configuration, before skill resolution; read only for selected container profiles. */
+    readonly loadRawConfig?: () => Promise<unknown>;
     readonly packageMetadata?: () => Promise<DoctorPackageMetadata>;
+    /** Offline rootless Podman probe; called only when a workspace uses container mode. */
+    readonly containerRuntime?: () => Promise<boolean>;
     /** Reads the installed manifest of a pinned extension; never imports extension code. */
     readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
     /** Reference trees that resolve legacy skill bases; defaults to the released shipped skills. */
     readonly releasedSkillTrees?: readonly ReleasedSkillTree[];
+    /** Environment for the event spool check; defaults to the process environment. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Metadata of the spool root without following a final symbolic link, `undefined` when absent; used only when event delivery is enabled. */
+    readonly eventSpoolRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
+    /** Metadata of the writer lease directory without following a final symbolic link, `undefined` when absent. */
+    readonly writerLeaseRoot?: (path: string) => Promise<EventSpoolRootInfo | undefined>;
+    /** Effective user id of the current process; defaults to the real one. */
+    readonly uid?: number;
+}
+export interface EventSpoolRootInfo {
+    readonly isDirectory: boolean;
+    readonly uid: number;
+    readonly mode: number;
 }
 export declare function runDoctor(dependencies?: DoctorDependencies): Promise<DoctorResult>;
 export declare function renderDoctorJson(result: DoctorResult): string;

package/dist/doctor.js

@@ -1,14 +1,38 @@
-import { access, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { access, lstat, open, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { createProcessRunner } from "./setup-process.js";
+import { podmanInfo, isSafeRefName } from "./writer-boundary.js";
+import { containedBuiltinSkills, containedProfileRefused } from "./writer-lifecycle.js";
+import { readWriterState, writerAcceptanceCurrent, writerName, writerPaths } from "./writer-state.js";
+import { LEASE_DIRECTORY } from "./writer-lease.js";
 import { loadConfig } from "./config.js";
+import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
+import { claimsRoot, eventsRoot } from "./turn-events.js";
 import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
 import { readSkillBases, SkillBasesError } from "./skill-customize.js";
 import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory } from "./skill-library.js";
+/** Largest `.git` file Doctor inspects; a real gitfile is one short line. */
+const MAX_GITFILE_BYTES = 4096;
+/** Reads at most `maxBytes` from a regular file; a final symbolic link or a non-regular file is rejected. */
+async function readPrefix(path, maxBytes) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error("not a regular file");
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_base_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_lease_directory", "writer_not_ready", "writer_not_migrated", "writer_off_default_base", "writer_dirty", "writer_git_identity_missing", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -103,9 +127,223 @@ async function skillOverrideChecks(overrideDirectory, shippedDirectory, released
     }
     return checks;
 }
+/**
+ * True when `<workspace>/.git` is a regular file whose content starts with a `gitdir:` pointer.
+ * A gitfile does not prove a linked worktree: submodules and `git init --separate-git-dir` use
+ * one too, and telling them apart would need the pointer target, which is never followed.
+ * A symbolic link, an absent or unreadable entry, an oversized file, or any other content is not
+ * a match, so no error here can fail Doctor.
+ */
+async function hasGitfilePointer(fs, workspace) {
+    const entry = join(workspace, ".git");
+    try {
+        const info = await (fs.lstat ?? lstat)(entry);
+        if (info.isSymbolicLink() || !info.isFile() || (info.size ?? 0) > MAX_GITFILE_BYTES)
+            return false;
+        // One byte more than the cap proves the file grew after the size check.
+        const content = await (fs.readPrefix ?? readPrefix)(entry, MAX_GITFILE_BYTES + 1);
+        return Buffer.byteLength(content, "utf8") <= MAX_GITFILE_BYTES && /^gitdir:[ \t]*\S/.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultRootInfo(path) {
+    try {
+        const info = await lstat(path);
+        return { isDirectory: info.isDirectory(), uid: info.uid, mode: info.mode };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Offline check of the host-only writer lease directory. A missing directory is fine because the
+ * first lease creates it. An existing entry must be a real directory of the current user with mode
+ * 0700: the rule `acquireWriterLease` applies before it opens a lease file. Nothing is created,
+ * repaired or read, and no path or lease file name appears in the report.
+ */
+async function writerLeaseCheck(home, probe, uid) {
+    let info;
+    try {
+        info = await probe(join(home, ...LEASE_DIRECTORY));
+    }
+    catch {
+        return failure("writer_lease_directory", "writer lease", "grant access to the writer lease directory");
+    }
+    if (info === undefined)
+        return undefined;
+    // Lease files must keep their inodes: a moved or recreated directory would let a second holder in.
+    if (!info.isDirectory)
+        return failure("writer_lease_directory", "writer lease", "close every writer session and setup run, then replace the entry with a private directory owned by the current user");
+    if ((uid !== undefined && info.uid !== uid) || (info.mode & 0o7777) !== 0o700) {
+        return failure("writer_lease_directory", "writer lease", "repair the lease directory in place (owner and chmod 700); never move or delete it or its lock files");
+    }
+    return ok("writer_lease_directory", "writer lease");
+}
+/**
+ * Offline check of the event spool's runtime directories, run only when event delivery is enabled.
+ * Nothing is created or repaired, and no path appears in the report. A missing runtime directory
+ * variable is a warning because Doctor may run in a different environment than the server.
+ * The `pi-session-mcp` entry, its `events` root and its `claims` directory, when present, must be
+ * real directories of the current user without group or other access: the rule that
+ * `TurnEventSpool.open` applies to the events root and the wake hook to the claims directory.
+ * An absent entry is fine because the server creates it, so Doctor cannot be green where startup
+ * fails with `event_spool_unavailable` for these directories.
+ */
+async function eventSpoolCheck(env, probe, uid) {
+    const events = eventsRoot(env);
+    if (events === undefined)
+        return warning("event_spool_root", "event spool", "without an absolute XDG_RUNTIME_DIR in the server environment, delivery stays inactive: set it, or disable events.delivery");
+    const runtime = dirname(events);
+    const entries = [[runtime, "pi-session-mcp runtime"], [events, "events"], [claimsRoot(env) ?? join(runtime, "claims"), "claims"]];
+    for (const [path, label] of entries) {
+        let info;
+        try {
+            info = await probe(path);
+        }
+        catch {
+            return failure("event_spool_root", "event spool", `grant access to the ${label} directory`);
+        }
+        if (info === undefined) {
+            if (path === runtime)
+                break;
+            continue;
+        }
+        if (!info.isDirectory)
+            return failure("event_spool_root", "event spool", `replace the ${label} entry with a private directory owned by the current user`);
+        if (uid !== undefined && info.uid !== uid)
+            return failure("event_spool_root", "event spool", `the ${label} directory must be owned by the current user`);
+        if ((info.mode & 0o077) !== 0)
+            return failure("event_spool_root", "event spool", `remove group and other permissions from the ${label} directory (chmod 700)`);
+    }
+    return ok("event_spool_root", "event spool");
+}
+async function defaultWriterRuntime() {
+    const runner = createProcessRunner();
+    const info = await podmanInfo(runner);
+    return { ...(info.version ? { podmanVersion: info.version } : {}), imageExists: async (id) => {
+            try {
+                return (await runner.run("podman", ["image", "exists", id], AbortSignal.timeout(10_000))).exitCode === 0;
+            }
+            catch {
+                return false;
+            }
+        } };
+}
+async function writerGitIdentity(clone) {
+    try {
+        const handle = await open(join(clone, ".git", "config"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65_536)
+                return false;
+            const buffer = Buffer.alloc(65_536);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if ((await handle.stat()).size > 65_536)
+                return false;
+            let user = false, name = false, email = false;
+            for (const line of buffer.subarray(0, bytesRead).toString("utf8").split("\n")) {
+                const section = /^\s*\[([^\]]+)\]/.exec(line);
+                if (section) {
+                    user = section[1].trim().toLowerCase() === "user";
+                    continue;
+                }
+                if (!user)
+                    continue;
+                const key = /^\s*(name|email)\s*=\s*(.*?)\s*$/i.exec(line);
+                if (!key || !key[2] || /^(?:""|[#;])/.test(key[2]))
+                    continue;
+                if (key[1].toLowerCase() === "name")
+                    name = true;
+                else
+                    email = true;
+            }
+            return name && email;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+async function writerDirty(clone, state) {
+    try {
+        const git = join(clone, ".git");
+        if (!(await lstat(clone)).isDirectory() || !(await lstat(git)).isDirectory())
+            return true;
+        const bounded = async (path) => {
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const info = await handle.stat();
+                if (!info.isFile() || info.size > 65_536)
+                    throw new Error("unsafe metadata");
+                const buffer = Buffer.alloc(65_536);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if ((await handle.stat()).size > 65_536)
+                    throw new Error("oversized metadata");
+                return buffer.subarray(0, bytesRead).toString("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+        };
+        if (!isSafeRefName(state.base.ref) || !state.base.ref.startsWith("refs/heads/"))
+            return true;
+        if ((await bounded(join(git, "HEAD"))).trim() !== `ref: ${state.base.ref}`)
+            return true;
+        const refs = new Map();
+        try {
+            for (const line of (await bounded(join(git, "packed-refs"))).split("\n")) {
+                if (!line || line.startsWith("#") || line.startsWith("^"))
+                    continue;
+                const match = /^([0-9a-f]{40}|[0-9a-f]{64}) (refs\/\S+)$/.exec(line);
+                if (!match)
+                    return true;
+                if (match[2].startsWith("refs/heads/"))
+                    refs.set(match[2], match[1]);
+            }
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const walk = async (path, ref, depth = 0) => {
+            if (depth > 64 || !(await lstat(path)).isDirectory())
+                throw new Error("unsafe refs");
+            for (const entry of await readdir(path, { withFileTypes: true })) {
+                const child = join(path, entry.name), name = `${ref}/${entry.name}`;
+                if (entry.isDirectory())
+                    await walk(child, name, depth + 1);
+                else if (entry.isFile())
+                    refs.set(name, (await bounded(child)).trim());
+                else
+                    throw new Error("unsafe ref");
+            }
+        };
+        if (!(await lstat(join(git, "refs"))).isDirectory())
+            return true;
+        try {
+            await walk(join(git, "refs/heads"), "refs/heads");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        return refs.size !== 1 || refs.get(state.base.ref) !== state.base.commit;
+    }
+    catch {
+        return true;
+    }
+}
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
+    const home = dependencies.home ?? homedir();
     const checks = [];
     let metadata;
     try {
@@ -172,8 +410,9 @@ export async function runDoctor(dependencies = {}) {
             checks.push(ok("version_mismatch", "package version"));
     }
     let config;
+    const configPath = dependencies.configPath ?? process.env.PI_SESSION_MCP_CONFIG;
     try {
-        config = await (dependencies.loadConfig ?? (() => loadConfig()))();
+        config = await (dependencies.loadConfig ?? loadConfig)(configPath);
         checks.push(ok("config_invalid", "configuration"));
     }
     catch (error) {
@@ -209,6 +448,12 @@ export async function runDoctor(dependencies = {}) {
                             checks.push(failure("workspace_not_writable", alias, "grant coding workspace write access"));
                         }
                     }
+                    if (canWrite) {
+                        if (await hasGitfilePointer(fs, path))
+                            checks.push(warning("workspace_gitfile", alias, "the workspace has a gitfile pointer (possible linked worktree or Git metadata stored outside the workspace); hooks and config may be shared with another repository, so give coding workers a separate full clone"));
+                        else
+                            checks.push(ok("workspace_gitfile", alias));
+                    }
                 }
             }
             catch (error) {
@@ -217,11 +462,127 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config) {
+        const canWrite = [...config.executionProfiles.values()].some((profile) => profile.permissionProfile === "coding");
+        let runtimeUsable;
+        for (const alias of [...config.workspaces.keys()].sort((a, b) => a.localeCompare(b))) {
+            const mode = config.workspaceModes.get(alias)?.mode ?? "unset";
+            if (mode === "unset" && canWrite)
+                checks.push(warning("workspace_mode_unset", alias, "choose an explicit execution mode for the workspace"));
+            else if (mode === "host")
+                checks.push(ok("workspace_host_writes_accepted", alias));
+            else if (mode === "container") {
+                runtimeUsable ??= await (dependencies.containerRuntime ?? containerRuntimeUsable)();
+                checks.push(runtimeUsable
+                    ? ok("container_runtime_unavailable", alias)
+                    : failure("container_runtime_unavailable", alias, "make rootless Podman available or choose a different execution mode"));
+            }
+        }
+    }
+    if (config) {
+        let runtime;
+        let rawConfig, rawConfigLoaded = false, rawConfigReadable = false;
+        let availableBuiltinSkills = new Set();
+        const offDefaultBase = new Map();
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container)
+                continue;
+            checks.push(entry.container.base === undefined
+                ? warning("workspace_base_unset", alias, `record the workspace default base with pi-session-mcp-setup --repo ${alias} --base <branch> --apply`)
+                : ok("workspace_base_unset", alias));
+            if (!rawConfigLoaded) {
+                rawConfigLoaded = true;
+                try {
+                    rawConfig = await (dependencies.loadRawConfig ?? (async () => {
+                        if (!configPath)
+                            throw new Error("configuration path unavailable");
+                        return JSON.parse(await fs.readFile(configPath, "utf8"));
+                    }))();
+                    availableBuiltinSkills = containedBuiltinSkills(rawConfig, config.skillOverrideDirectory);
+                    rawConfigReadable = true;
+                }
+                catch { /* An unavailable raw configuration cannot establish profile acceptance. */ }
+            }
+            if (!rawConfigReadable) {
+                checks.push(failure("container_profile_refused", alias, "selected profiles could not be checked; restore configuration read access and rerun Doctor"));
+            }
+            else {
+                const refused = entry.container.profiles.filter((profile) => containedProfileRefused(rawConfig, profile, availableBuiltinSkills));
+                for (const profile of refused)
+                    checks.push(failure("container_profile_refused", `${alias}:${profile}`, "use a non-default coding profile without extensions or MCP grants and with only shipped, non-overridden builtin skills, or drop it from the repository's profiles"));
+                if (refused.length === 0)
+                    checks.push(ok("container_profile_refused", alias));
+            }
+            for (let index = 1; index <= entry.container.writers; index++) {
+                const name = writerName(alias, index), paths = writerPaths(home, name);
+                const remediation = `run pi-session-mcp-setup --repo ${alias} --apply, or --writer ${name} --recreate --apply`;
+                let state, ready = false;
+                try {
+                    state = await readWriterState(home, name);
+                    if (state?.phase === "ready" && state.acceptance) {
+                        runtime ??= await (dependencies.writerRuntime ?? defaultWriterRuntime)();
+                        ready = await writerAcceptanceCurrent(paths.wrapper, state, runtime);
+                    }
+                }
+                catch { /* Unreadable state or runtime is not ready. */ }
+                checks.push(ready ? ok("writer_not_ready", name) : failure("writer_not_ready", name, remediation));
+                if (!state)
+                    continue;
+                checks.push(state.launch === "relay" ? ok("writer_not_migrated", name)
+                    : warning("writer_not_migrated", name, `run pi-session-mcp-setup --repo ${alias} --apply to migrate the writer to the relay`));
+                if (entry.container.base !== undefined && ready && state.base.ref !== `refs/heads/${entry.container.base}`) {
+                    offDefaultBase.set(alias, (offDefaultBase.get(alias) ?? 0) + 1);
+                }
+                checks.push(await writerDirty(paths.clone, state)
+                    ? warning("writer_dirty", name, "collect writer work before resetting or recreating the writer") : ok("writer_dirty", name));
+                let bundles = false;
+                try {
+                    if (!(await lstat(paths.bundles)).isDirectory())
+                        bundles = true;
+                    else
+                        bundles = (await readdir(paths.bundles)).some((file) => file !== "base.bundle");
+                }
+                catch (error) {
+                    bundles = !isMissing(error);
+                }
+                checks.push(await writerGitIdentity(paths.clone) ? ok("writer_git_identity_missing", name)
+                    : warning("writer_git_identity_missing", name, "set user.name and user.email in the operator checkout, then reset the writer"));
+                checks.push(bundles ? warning("writer_uncollected_bundle", name, "collect or review outstanding writer bundles") : ok("writer_uncollected_bundle", name));
+            }
+        }
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container || entry.container.base === undefined)
+                continue;
+            const count = offDefaultBase.get(alias) ?? 0;
+            checks.push(count === 0 ? ok("writer_off_default_base", alias)
+                : warning("writer_off_default_base", alias, `${count} ${count === 1 ? "writer is" : "writers are"} off the workspace default base; finish each with pi-session-mcp-setup --writer <name> --finish --apply once its work is collected`));
+        }
+    }
+    if (config) {
+        // This advisory check needs positive evidence, like the gitfile check: unreadable or
+        // malformed optional settings are ignored, while installed-manifest checks still run.
+        const unpinned = new Set();
+        if ([...config.executionProfiles.values()].some((profile) => profile.extensions?.length)) {
+            try {
+                // Load the SDK only here, like the extension resolver, so a broken install cannot stop Doctor from loading.
+                const agentDir = dependencies.agentDir ?? (await import("@earendil-works/pi-coding-agent")).getAgentDir();
+                const settings = JSON.parse((await fs.readFile(join(agentDir, "settings.json"), "utf8")).replace(/^\uFEFF/, ""));
+                if (typeof settings === "object" && settings !== null && "packages" in settings && Array.isArray(settings.packages)) {
+                    for (const entry of settings.packages) {
+                        const source = typeof entry === "object" && entry !== null && "source" in entry ? entry.source : entry;
+                        if (typeof source === "string")
+                            unpinned.add(source);
+                    }
+                }
+            }
+            catch { /* Optional settings cannot establish an unpinned entry. */ }
+        }
         const resolveExtension = dependencies.resolveExtension
             ?? (async (extension) => (await import("./pi-extensions.js")).resolvePiExtension(extension));
         for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
             for (const extension of profile.extensions ?? []) {
                 const subject = `${alias}:${extension.name}`;
+                if (unpinned.has(`npm:${extension.name}`))
+                    checks.push(warning("extension_unpinned", subject, `pin it with pi install npm:${extension.name}@${extension.version}`));
                 try {
                     await resolveExtension(extension);
                     checks.push(ok("extension_missing", subject), ok("extension_version_mismatch", subject));
@@ -266,6 +627,11 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config?.eventDelivery === "spool")
+        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.()));
+    const lease = await writerLeaseCheck(home, dependencies.writerLeaseRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.());
+    if (lease)
+        checks.push(lease);
     if (config)
         checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));

package/dist/event-spool.d.ts

@@ -0,0 +1,70 @@
+import { type TurnEvent } from "./turn-events.js";
+/**
+ * The server's side of the turn-event spool: one instance directory per server process under a
+ * private spool root, one atomic, content-free file per event. The wake hook program reads these
+ * files; the contract lives in `turn-events.ts`. Writing never throws into the registry or the
+ * shutdown path, because a lost wake is cheaper than a broken session.
+ */
+export type EventSpoolErrorCode = "event_spool_unavailable";
+/** The spool root is unusable. The message carries no path. */
+export declare class EventSpoolError extends Error {
+    readonly code: EventSpoolErrorCode;
+    constructor();
+}
+export interface EventSpoolDiagnostic {
+    readonly level: "warn";
+    readonly event: "event_spool_write_failed";
+    readonly stage: "event_spool";
+    readonly code: string;
+}
+export interface EventSpoolOptions {
+    /** Receives at most one diagnostic per spool. Must not throw; if it does, the error is ignored. */
+    readonly diagnostic?: (diagnostic: EventSpoolDiagnostic) => void;
+    /** The owner the root must have; defaults to the current process uid. */
+    readonly uid?: number | undefined;
+    /** Removes the instance directory at close; a seam for tests, defaults to a recursive `rmSync`. */
+    readonly removeInstance?: (path: string) => void;
+}
+type Distribute<T> = T extends unknown ? Omit<T, "v" | "seq" | "at" | "instance"> : never;
+/** What a caller supplies; the spool adds version, sequence number, time and instance. */
+export type TurnEventFields = Distribute<TurnEvent>;
+/** How many of its newest event files an instance keeps; the wake hook scans a bounded number of entries. */
+export declare const SPOOL_RETAINED_EVENTS = 256;
+export declare class TurnEventSpool {
+    private readonly root;
+    private readonly instanceDir;
+    private readonly instance;
+    private readonly uid;
+    private readonly options;
+    private seq;
+    private failureCount;
+    private reported;
+    private closed;
+    /** Names of the event files this instance wrote and still keeps, oldest first. The directory is never listed. */
+    private readonly written;
+    private constructor();
+    /**
+     * Creates the root (mode 0700, recursively) if missing, refuses a root that is not a plain
+     * directory owned by the current user without group or other access, and creates this process's
+     * instance directory. Throws `EventSpoolError` and nothing else.
+     */
+    static open(dir: string, options?: EventSpoolOptions): TurnEventSpool;
+    /** The number of events that could not be written. */
+    get failures(): number;
+    /** Writes one event atomically. Never throws; a failure is counted and reported once. */
+    write(fields: TurnEventFields): void;
+    /**
+     * Writes `instance_ended`, then removes the instance directory with its files. Best effort,
+     * idempotent, never throws. Call it only after the registry's shutdown finished, so that
+     * terminal events generated by `close` precede `instance_ended`.
+     */
+    close(reason: "eof" | "signal" | "shutdown"): void;
+    private append;
+    private writeFile;
+    /** Same rules as `open`, applied once more: the root must still be private, and the instance directory a plain one of ours. */
+    private recreateInstanceDirectory;
+    /** Keeps only the newest `SPOOL_RETAINED_EVENTS` files this instance wrote. Best effort. */
+    private retain;
+    private report;
+}
+export {};