pi-daddy 0.13.0 → 0.15.0

package/dist/skill-packages.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Which installed npm packages ship `SKILL.md` definitions — read from their own manifests.
+ *
+ * `pi-daddy init` scaffolds a governed project from whatever skill packages are already installed, and
+ * this is how it finds them: **a package declares its skills in `package.json`'s `pi.skills` array**, which
+ * is pi's own convention and how pi itself loads them. Measured against `principal-pi-skills@2.3.1`:
+ *
+ * ```json
+ * "pi": { "skills": ["./decide", "./architect", "./plan", "./build", "./review", "./debug", "./git-ops"] }
+ * ```
+ *
+ * **A declaration, never a heuristic.** Walking `node_modules` looking for files called `SKILL.md` would
+ * find a package's test fixtures, its examples, and its vendored copies of someone else's skills — and
+ * would then offer to install them as spawnable sub-agents. A package that says which of its files are
+ * skills has said so on purpose, and that is the only list this reads.
+ *
+ * What it deliberately does NOT do: scan `~/.pi/agent/skills/`. Definitions already in a skill root are
+ * discovered by `loadDefinitions` and governed as they stand; copying them into a project would duplicate
+ * them under a name that shadows the original (project wins on collision), which is a change nobody asked
+ * for.
+ *
+ * **Everything read here comes from a third party**, so this module is also where the refusals live: a
+ * name, a declared capability id, or a path that cannot safely be written into a generated file is refused
+ * with a reason rather than passed on (R-77, R-78, R-80). `init` generates a shell file an operator
+ * `source`s; the only strings that may reach it are ones that survived a whitelist here.
+ */
+import { type SkillDefinition } from "./definitions.ts";
+import { type Capability } from "./resolve.ts";
+export interface DiscoveredSkill {
+    definition: SkillDefinition;
+    /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
+    text: string;
+    path: string;
+}
+/** Why a declared skill was refused before it could be planned. Each has a different fix. */
+export type RefusalReason = 
+/** The name cannot be a capability id, a line in a sourced file, or a path segment. */
+"unsafe-name"
+/** A declared `allowed-tools` entry cannot be one either — R-78, the sibling of R-77. */
+ | "unsafe-capability"
+/** The declaration claims `tool:*` or `agent:*`: root authority, which a package may not hand itself. */
+ | "wildcard"
+/** The bytes are not valid UTF-8, so "copied verbatim" could not be honoured. */
+ | "not-utf8";
+export interface RefusedSkill {
+    /** The `pi.skills` entry or the definition name, whichever the operator can act on. */
+    subject: string;
+    reason: RefusalReason;
+    /** The offending id(s), when the reason names any. */
+    detail: string[];
+}
+export interface SkillPackage {
+    name: string;
+    version: string;
+    /** Paths `pi.skills` named that could not be read as a `SKILL.md`, so the report can say so out loud. */
+    unreadable: string[];
+    /** Skills refused for a reason that would otherwise reach a generated file. Never silently dropped. */
+    refused: RefusedSkill[];
+    skills: DiscoveredSkill[];
+}
+/**
+ * May this definition's name be written into a capability id, a shell file and a path?
+ *
+ * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
+ * definition's identity is its directory name, and `init` interpolates that name into three places at once:
+ * `agent:<name>` inside a **comma-separated** `PI_GRANTS_GRANT`, a `.pi/grants.env` an operator **sources**,
+ * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
+ *
+ * ```
+ * export PI_GRANTS_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
+ * ```
+ *
+ * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
+ * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
+ * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
+ *
+ * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
+ */
+export declare function isSafeName(name: string): boolean;
+/**
+ * May this DECLARED capability id be written into the generated grant? — R-78.
+ *
+ * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
+ * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
+ * package declaring
+ *
+ * ```yaml
+ * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="
+ * ```
+ *
+ * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
+ * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
+ * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
+ * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
+ * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
+ *
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
+ * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
+ * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ */
+export declare function isSafeCapability(id: Capability): boolean;
+/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
+export declare function readSkillPackage(packageDir: string): Promise<SkillPackage | null>;
+/**
+ * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
+ *
+ * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
+ * `node_modules`: a transitive skill package is not something an operator asked to install definitions
+ * from, and scaffolding one into their project would be a surprise wearing a helpful face.
+ */
+/**
+ * Every place a pi package can be installed, most specific first (R-75).
+ *
+ * **Two roots, because pi has two install paths and only one of them is `npm install`.** `pi install
+ * npm:principal-pi-skills` — the documented, pi-native way, and the only one that registers the package so
+ * pi will auto-load its extension — puts it in `$PI_CODING_AGENT_DIR/npm/node_modules`, and leaves the
+ * project without a `node_modules` at all. Searching only `<cwd>/node_modules` therefore found **nothing**
+ * for an operator who followed pi's own instructions, and said "install principal-pi-skills" to somebody
+ * who just had.
+ *
+ * Measured, in a fresh `PI_CODING_AGENT_DIR` with an empty project: `pi install` populates the agent root
+ * and creates no project root.
+ *
+ * Project first when both exist, because a package pinned in the repository is the one the team agreed on.
+ */
+export declare function skillPackageRoots(cwd: string): string[];
+export declare function discoverSkillPackages(cwd: string): Promise<SkillPackage[]>;
+//# sourceMappingURL=skill-packages.d.ts.map

package/dist/skill-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-packages.d.ts","sourceRoot":"","sources":["../src/skill-packages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEpG,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,2GAA2G;IAC3G,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa;AACvB,uFAAuF;AACrF,aAAa;AACf,yFAAyF;GACvF,mBAAmB;AACrB,yGAAyG;GACvG,UAAU;AACZ,iFAAiF;GAC/E,UAAU,CAAC;AAEf,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yGAAyG;IACzG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uGAAuG;IACvG,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAMxD;AA2DD,2GAA2G;AAC3G,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkCvF;AAED;;;;;;GAMG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAGvD;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBhF"}

package/dist/skill-packages.js

@@ -0,0 +1,245 @@
+/**
+ * Which installed npm packages ship `SKILL.md` definitions — read from their own manifests.
+ *
+ * `pi-daddy init` scaffolds a governed project from whatever skill packages are already installed, and
+ * this is how it finds them: **a package declares its skills in `package.json`'s `pi.skills` array**, which
+ * is pi's own convention and how pi itself loads them. Measured against `principal-pi-skills@2.3.1`:
+ *
+ * ```json
+ * "pi": { "skills": ["./decide", "./architect", "./plan", "./build", "./review", "./debug", "./git-ops"] }
+ * ```
+ *
+ * **A declaration, never a heuristic.** Walking `node_modules` looking for files called `SKILL.md` would
+ * find a package's test fixtures, its examples, and its vendored copies of someone else's skills — and
+ * would then offer to install them as spawnable sub-agents. A package that says which of its files are
+ * skills has said so on purpose, and that is the only list this reads.
+ *
+ * What it deliberately does NOT do: scan `~/.pi/agent/skills/`. Definitions already in a skill root are
+ * discovered by `loadDefinitions` and governed as they stand; copying them into a project would duplicate
+ * them under a name that shadows the original (project wins on collision), which is a change nobody asked
+ * for.
+ *
+ * **Everything read here comes from a third party**, so this module is also where the refusals live: a
+ * name, a declared capability id, or a path that cannot safely be written into a generated file is refused
+ * with a reason rather than passed on (R-77, R-78, R-80). `init` generates a shell file an operator
+ * `source`s; the only strings that may reach it are ones that survived a whitelist here.
+ */
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { ceilingForDefinition, parseSkillDefinition } from "./definitions.js";
+import { WILDCARD } from "./pi-tools.js";
+import { AGENT_WILDCARD } from "./resolve.js";
+/**
+ * May this definition's name be written into a capability id, a shell file and a path?
+ *
+ * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
+ * definition's identity is its directory name, and `init` interpolates that name into three places at once:
+ * `agent:<name>` inside a **comma-separated** `PI_GRANTS_GRANT`, a `.pi/grants.env` an operator **sources**,
+ * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
+ *
+ * ```
+ * export PI_GRANTS_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
+ * ```
+ *
+ * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
+ * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
+ * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
+ *
+ * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
+ */
+export function isSafeName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+/**
+ * May this DECLARED capability id be written into the generated grant? — R-78.
+ *
+ * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
+ * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
+ * package declaring
+ *
+ * ```yaml
+ * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="
+ * ```
+ *
+ * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
+ * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
+ * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
+ * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
+ * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
+ *
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
+ * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
+ * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ */
+export function isSafeCapability(id) {
+    const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+    return (new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+        new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id));
+}
+/** The two ids that confer root authority. A package declaring one is claiming it, not describing a need. */
+function wildcardsIn(capabilities) {
+    return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD);
+}
+/**
+ * Everything about one declared skill that would make it unsafe to scaffold. `null` when it is fine.
+ *
+ * Ordered so the operator is told the most actionable thing: a wildcard is a deliberate claim, an unsafe id
+ * is probably a typo or an attack, and a bad name is neither.
+ */
+function refusalFor(skill) {
+    const name = skill.definition.name;
+    if (!isSafeName(name))
+        return { subject: name, reason: "unsafe-name", detail: [name] };
+    const ceiling = ceilingForDefinition(skill.definition);
+    const wildcards = wildcardsIn(ceiling.capabilities);
+    if (wildcards.length > 0)
+        return { subject: name, reason: "wildcard", detail: wildcards };
+    const unsafe = ceiling.capabilities.filter((c) => !isSafeCapability(c));
+    if (unsafe.length > 0)
+        return { subject: name, reason: "unsafe-capability", detail: unsafe };
+    return null;
+}
+/** One `pi.skills` entry: a directory holding `SKILL.md`, or a `.md` file — the same two shapes pi allows. */
+async function readSkill(packageDir, entry) {
+    const target = resolve(packageDir, entry);
+    // A manifest is data from another package, so an entry escaping its own directory is refused rather than
+    // followed. **`realpath`, not a lexical prefix test** (R-80): `resolve()` normalises `..` and knows
+    // nothing about symlinks, so a packaged symlink walked straight past the first version of this check and
+    // a definition from outside the package was copied in, with its `allowed-tools` landing in the operator's
+    // grant. Measured. This is the same lesson as the `realpathSync` fix in `cli.ts`, which was found by the
+    // smoke test one day earlier and not applied here.
+    const realPackageDir = await realpath(packageDir).catch(() => packageDir);
+    for (const path of [join(target, "SKILL.md"), ...(target.endsWith(".md") ? [target] : [])]) {
+        let bytes;
+        try {
+            bytes = await readFile(path);
+        }
+        catch {
+            continue;
+        }
+        const realPath = await realpath(path).catch(() => path);
+        if (!realPath.startsWith(realPackageDir + sep))
+            return null;
+        // "The file verbatim … nothing is lost in a round trip" is a claim this module makes, so bytes that
+        // cannot survive the round trip are refused rather than silently replaced. A latin-1 `0xE9` used to come
+        // back as U+FFFD, changing the file's length and its digest, with no warning.
+        const text = bytes.toString("utf8");
+        if (!Buffer.from(text, "utf8").equals(bytes))
+            return "not-utf8";
+        const definition = parseSkillDefinition(path, text);
+        return definition ? { definition, text, path } : null;
+    }
+    return null;
+}
+/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
+export async function readSkillPackage(packageDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const declared = manifest.pi?.skills;
+    if (!Array.isArray(declared) || declared.length === 0)
+        return null;
+    const skills = [];
+    const unreadable = [];
+    const refused = [];
+    for (const entry of declared) {
+        if (typeof entry !== "string")
+            continue;
+        const skill = await readSkill(packageDir, entry);
+        if (skill === null) {
+            unreadable.push(entry);
+        }
+        else if (skill === "not-utf8") {
+            refused.push({ subject: entry, reason: "not-utf8", detail: [] });
+        }
+        else {
+            const refusal = refusalFor(skill);
+            if (refusal)
+                refused.push(refusal);
+            else
+                skills.push(skill);
+        }
+    }
+    return {
+        name: manifest.name ?? packageDir.split(sep).pop() ?? "(unnamed)",
+        version: manifest.version ?? "(no version)",
+        unreadable,
+        refused,
+        skills,
+    };
+}
+/**
+ * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
+ *
+ * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
+ * `node_modules`: a transitive skill package is not something an operator asked to install definitions
+ * from, and scaffolding one into their project would be a surprise wearing a helpful face.
+ */
+/**
+ * Every place a pi package can be installed, most specific first (R-75).
+ *
+ * **Two roots, because pi has two install paths and only one of them is `npm install`.** `pi install
+ * npm:principal-pi-skills` — the documented, pi-native way, and the only one that registers the package so
+ * pi will auto-load its extension — puts it in `$PI_CODING_AGENT_DIR/npm/node_modules`, and leaves the
+ * project without a `node_modules` at all. Searching only `<cwd>/node_modules` therefore found **nothing**
+ * for an operator who followed pi's own instructions, and said "install principal-pi-skills" to somebody
+ * who just had.
+ *
+ * Measured, in a fresh `PI_CODING_AGENT_DIR` with an empty project: `pi install` populates the agent root
+ * and creates no project root.
+ *
+ * Project first when both exist, because a package pinned in the repository is the one the team agreed on.
+ */
+export function skillPackageRoots(cwd) {
+    const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+    return [join(cwd, "node_modules"), join(agentDir, "npm", "node_modules")];
+}
+export async function discoverSkillPackages(cwd) {
+    const dirs = [];
+    const seenNames = new Set();
+    for (const root of skillPackageRoots(cwd))
+        await collectFrom(root, dirs);
+    const packages = [];
+    for (const dir of dirs) {
+        const found = await readSkillPackage(dir);
+        // First root wins on a name collision: the project's pinned copy outranks the machine-wide one, and
+        // silently preferring the other would make a committed lockfile stop meaning anything.
+        if (found && !seenNames.has(found.name)) {
+            seenNames.add(found.name);
+            packages.push(found);
+        }
+    }
+    return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Append every package directory under one `node_modules`, scoped packages included. */
+async function collectFrom(root, dirs) {
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return; // a root that does not exist is a normal state, not a failure
+    }
+    for (const entry of entries.sort()) {
+        if (entry.startsWith("."))
+            continue; // .bin, .package-lock.json
+        if (entry.startsWith("@")) {
+            try {
+                for (const scoped of (await readdir(join(root, entry))).sort())
+                    dirs.push(join(root, entry, scoped));
+            }
+            catch {
+                continue;
+            }
+        }
+        else {
+            dirs.push(join(root, entry));
+        }
+    }
+}
+//# sourceMappingURL=skill-packages.js.map

package/dist/skill-packages.js.map

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

package/extensions/grants-command.ts

@@ -43,6 +43,15 @@ export interface GrantsCommandContext {
    * R-28 discipline where it belongs: this command asks what would happen instead of working it out.
    */
   previewDelegation: (name: string) => Promise<GatedPlan>;
+  /**
+   * Run `/grants init`: scaffold definitions, ask about the withheld capabilities only, store the answer
+   * outside the workspace, and apply it to this session (ADR-0030).
+   *
+   * Injected rather than imported so this module stays what it is — a read-only diagnostic that cannot
+   * become a governance path by accident. The one command here that *writes* takes its ability to do so
+   * from the caller, visibly.
+   */
+  runInit: () => Promise<void>;
 }
 
 /**
@@ -51,6 +60,9 @@ export interface GrantsCommandContext {
  */
 const PREVIEW_LIMIT = 12;
 
+/** The verbs `/grants` answers to. Anything else is refused rather than silently treated as no verb. */
+const KNOWN_SUBCOMMANDS: readonly string[] = ["init", "ledger", "approvals", "revoke"];
+
 export const grantsCommand = {
   description:
     "Show this session's capability grant, delegation depth, and known agent-type ceilings; " +
@@ -65,6 +77,11 @@ handler: async (args: string, ctx: any) => {
 
     const [sub, target] = args.trim().split(/\s+/).filter(Boolean);
 
+    if (sub === "init") {
+      await ctx.grants.runInit();
+      return;
+    }
+
     if (sub === "ledger") {
       // The detector, made reachable. `verifyLedger` exists because nothing in this package had ever read
       // a ledger back, so a torn line was indistinguishable from a spawn that never happened — and a
@@ -265,6 +282,20 @@ handler: async (args: string, ctx: any) => {
       return;
     }
 
+    // **An unrecognised subcommand is refused, not ignored (R-74).** Every `sub` that is not a known verb
+    // fell through to this status screen with the word silently dropped, so `/grants init` — a command that
+    // does not exist — printed a healthy-looking report and read as though it had run. `/grants ledgr` did
+    // the same. A diagnostic that answers a question nobody asked is worse than one that refuses: it is
+    // indistinguishable from success, which is the shape this package spends most of its risk register on.
+    if (sub !== undefined && !KNOWN_SUBCOMMANDS.includes(sub)) {
+      ctx.ui.notify(
+        `grants: unknown subcommand "${sub}" — did nothing. Known: ${KNOWN_SUBCOMMANDS.join(", ")}. ` +
+          `Plain /grants shows this session's status.`,
+        "warning",
+      );
+      return;
+    }
+
     const { valid } = await loadApprovals({ cwd, now: new Date(), snapshotOf });
     const lines = [
       governed ? "grants: ACTIVE" : "grants: inactive (set PI_GRANTS_GRANT to govern this session)",

package/extensions/grants.ts

@@ -30,12 +30,17 @@ import { legacyApprovalsPath, sharedApprovalsPath } from "../src/approval-store.
 import { buildCatalog } from "../src/catalog.ts";
 import { loadDefinitions } from "../src/definitions.ts";
 import { appendRecord, buildRecord, verifyLedger } from "../src/ledger.ts";
-import { deriveOwnGrant, observeToolNames } from "../src/propagation.ts";
+import {
+  ENV_GRANT, deriveOwnGrant, observeToolNames } from "../src/propagation.ts";
 import { snapshotOf } from "./approvals.ts";
 import { registerDelegationTools } from "./delegation.ts";
 import { grantsCommand } from "./grants-command.ts";
+import { runInit } from "./init-command.ts";
+import type { Capability } from "../src/resolve.ts";
+
 import { planWithApprovals } from "./run-delegation.ts";
-import { createGrantsSession } from "./session.ts";
+import { createGrantsSession, loadProjectDefinitions, type GrantsSession } from "./session.ts";
+import { renderSpawnableSummary, summariseSpawnable } from "./spawn-summary.ts";
 
 const SPAWN_TOOLS = new Set(["Agent", "subagent", "spawn_agent"]);
 
@@ -59,6 +64,20 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     session.cwd = ctx.cwd;
+    // The one case the stored-grant lookup can get wrong (ADR-0030). The factory reads the store keyed by
+    // `process.cwd()` because it runs before any hook and therefore before `ctx` exists — and S-5 forces
+    // that ordering, since whether `delegate` is registered is decided there. Almost always the two agree.
+    // When they do not, the session is governed by a different directory's decision than the one it is
+    // working in, which is exactly the confusion a grant must never cause, so it is said out loud rather
+    // than left to be inferred from a surprising refusal. Sync, so it is not the R-60 shape.
+    if (session.storeCwd !== ctx.cwd && process.env[ENV_GRANT] === undefined) {
+      ctx.ui.notify(
+        `grants: this session's stored grant was read for ${session.storeCwd}, but pi is working in ` +
+          `${ctx.cwd}. A grant belongs to a directory, so run /grants init here, or set PI_GRANTS_GRANT ` +
+          `explicitly — the environment always wins.`,
+        "warning",
+      );
+    }
     try {
       // Guarded together, and guarded at all because of R-60 rather than because either one throws today:
       // both loaders swallow their own filesystem errors, so this catch is currently unreachable. The point
@@ -68,9 +87,7 @@ export default function (pi: ExtensionAPI) {
       // delegate by `tools:`, and an operator whose `agent:` spawns have all started failing deserves to
       // know it was the *scan* that broke rather than the grant.
       try {
-        session.definitions = await loadDefinitions(ctx.cwd);
-        session.catalogReady = buildCatalog({ cwd: ctx.cwd, observedTools: session.observedTools });
-        session.catalog = await session.catalogReady;
+        await loadProjectDefinitions(session, ctx.cwd);
       } catch (error) {
         ctx.ui.notify(
           `grants: could not read this project's definitions or capability catalog ` +
@@ -207,6 +224,35 @@ export default function (pi: ExtensionAPI) {
           `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,
           "info",
         );
+        // B1 / P4. The grant alone never named the definitions, never said where they came from, and never
+        // said which ones were being WITHHELD — so an operator who had just installed a package of
+        // `SKILL.md` files could not tell governance-is-working from did-the-install-fail. Classified by the
+        // real planner (see `./spawn-summary.ts`), never by a second reading of the rules.
+        //
+        // Its own try/catch, and not because `summariseSpawnable` throws today: this is the R-60 shape
+        // exactly — one added `await` inside the blanket catch cancelling every control below it in
+        // silence. There is nothing below it now; there will be.
+        try {
+          const line = renderSpawnableSummary(
+            await summariseSpawnable(
+              session.definitions,
+              (name) => planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
+              // The session facts that make every per-definition verdict identical. `mayDelegate` in
+              // particular: without `tool:delegate` there is no delegate tool at all, and the line used to
+              // report definitions as spawnable in the one session where nothing can ever be spawned.
+              { mayDelegate: session.mayDelegate, depth: session.depth, maxDepth: session.maxDepth },
+            ),
+            session.definitions.size,
+          );
+          if (line) ctx.ui.notify(line, "info");
+        } catch (error) {
+          ctx.ui.notify(
+            `grants: could not work out which definitions are spawnable ` +
+              `(${error instanceof Error ? error.message : String(error)}) — run /grants for the per-definition ` +
+              `verdict. Nothing about the grant or its enforcement depends on this line.`,
+            "warning",
+          );
+        }
       }
     } catch (error) {
       // Rule 8 — fail closed, and be LOUD about it. Swallowing is still right: a startup fault must not
@@ -338,9 +384,15 @@ export default function (pi: ExtensionAPI) {
           // says so: stored approvals count exactly as they would for a spawn, and no human is asked
           // (R-38). Passing `ctx` here would let `/grants` raise a dialog, and passing `hasUI: false` would
           // make every gated definition report "no interactive user" instead of what actually blocks it.
+          runInit: () =>
+            runInit(session, ctx, async () => {
+              await loadProjectDefinitions(session, ctx.cwd);
+              delegation.refreshSpawnable();
+            }),
           previewDelegation: (name: string) =>
             planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
         },
       }),
   });
 }
+