pi-daddy 0.28.0 → 0.32.1

package/dist/kernel/skill-packages.js

@@ -0,0 +1,300 @@
+/**
+ * Setup discovers enabled Pi resources in place through its package resolver. Configured packages
+ * are never copied into another autoload root. For legacy npm installs unregistered with Pi only,
+ * the explicit package.json pi.skills declaration remains a scaffold source (ADR-0074).
+ * Names, ceilings and bytes are checked before they can enter the generated shell grant.
+ */
+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 { resolveSkillResources, skillResourceName } from "./skill-resources.js";
+import { WILDCARD } from "./pi-tools.js";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD } from "./resolve.js";
+import { isSafeCapability } from "./capabilities.js";
+import { agentDir as resolveAgentDir } from "./project-paths.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_DADDY_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_DADDY_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_DADDY_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 the README documents: `tool:<name>`, `skill:<name>`, `agent:<name>`,
+ * `workspace:<id>`, 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".
+ *
+ * `workspace:` was absent until 2026-08-21, so the boundary that GENERATES grants could not emit the one
+ * capability ADR-0035's breaking change made mandatory: a package needing to route was reported as declaring
+ * something that "is not a name". A namespace has to be added here as well as to the enforcing path, and
+ * that is the whole lesson of the review this came out of.
+ */
+// Imported as well as re-exported: a bare `export … from` does not bind the name in this module's scope, and
+// `refusalFor` below calls it. Re-exported because this has been the import site since 0.13.0.
+export { isSafeCapability };
+/**
+ * The ids that confer authority over a whole namespace. A package declaring one is claiming it, not
+ * describing a need — so it is reported as a *wildcard claim* rather than as a malformed name, which is a
+ * different sentence to show an operator. `workspace:*` belongs here for the same reason `agent:*` does.
+ */
+function wildcardsIn(capabilities) {
+    return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD || c === WORKSPACE_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 = resolveAgentDir();
+    return [join(cwd, "node_modules"), join(agentDir, "npm", "node_modules")];
+}
+export async function discoverSkillPackages(cwd) {
+    const resolved = await resolveSkillResources(cwd);
+    const packages = [];
+    const seenSkills = new Set();
+    const runtimeNames = new Set(resolved.skills.map((s) => skillResourceName(s.path)));
+    const configuredRoots = new Set(resolved.configured.flatMap((p) => (p.installedPath ? [resolve(p.installedPath)] : [])));
+    const configuredNames = new Set(resolved.configured.flatMap((p) => {
+        if (!p.source.startsWith("npm:"))
+            return [];
+        const spec = p.source.slice(4);
+        const versionAt = spec.indexOf("@", 1);
+        return [versionAt < 0 ? spec : spec.slice(0, versionAt)];
+    }));
+    for (const root of configuredRoots) {
+        try {
+            configuredNames.add(JSON.parse(await readFile(join(root, "package.json"), "utf8")).name);
+        }
+        catch {
+            /* absent */
+        }
+    }
+    for (const resource of resolved.skills) {
+        const bytes = await readFile(resource.path).catch(() => null);
+        if (bytes === null)
+            continue;
+        const text = bytes.toString("utf8");
+        const resourceName = skillResourceName(resource.path);
+        if (seenSkills.has(resourceName))
+            continue;
+        seenSkills.add(resourceName);
+        let name = resource.metadata.source;
+        let version = "local";
+        if (resource.metadata.origin === "package" && resource.metadata.baseDir) {
+            try {
+                const manifest = JSON.parse(await readFile(join(resource.metadata.baseDir, "package.json"), "utf8"));
+                name = manifest.name ?? name;
+                version = manifest.version ?? version;
+            }
+            catch {
+                /* the resource can be used without optional display metadata */
+            }
+        }
+        else
+            name = `${resource.metadata.scope} skills`;
+        let pkg = packages.find((p) => p.name === name && p.version === version);
+        if (!pkg) {
+            pkg = { name, version, skills: [], refused: [], unreadable: [] };
+            packages.push(pkg);
+        }
+        if (!Buffer.from(text, "utf8").equals(bytes)) {
+            pkg.refused.push({ subject: resourceName, reason: "not-utf8", detail: [] });
+            continue;
+        }
+        const definition = parseSkillDefinition(resource.path, text);
+        if (!definition)
+            continue;
+        const skill = { definition, text, path: resource.path, referenced: true };
+        const refusal = refusalFor(skill);
+        if (refusal)
+            pkg.refused.push(refusal);
+        else
+            pkg.skills.push(skill);
+    }
+    // Compatibility for npm installs that were never registered with Pi. Runtime discovery never scans
+    // node_modules. A configured package (including one disabled by a filter) must not re-enter here.
+    const dirs = [];
+    for (const root of skillPackageRoots(cwd))
+        await collectFrom(root, dirs);
+    const seenNames = new Set(packages.map((p) => p.name));
+    for (const dir of dirs) {
+        if (configuredRoots.has(resolve(dir)))
+            continue;
+        const found = await readSkillPackage(dir);
+        if (!found || configuredNames.has(found.name) || seenNames.has(found.name))
+            continue;
+        seenNames.add(found.name);
+        found.skills = found.skills.filter((skill) => !runtimeNames.has(skill.definition.name));
+        packages.push(found);
+    }
+    return packages;
+}
+/** 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/kernel/skill-packages.js.map

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

package/dist/kernel/skill-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-resources.d.ts","sourceRoot":"","sources":["../../src/kernel/skill-resources.ts"],"names":[],"mappings":"AAMA,UAAU,cAAc;IACtB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/E,EAAE,CAAC;IACJ,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA0ChF"}

package/dist/kernel/skill-resources.js

@@ -0,0 +1,56 @@
+/** Read Pi's configured resource surface without locks, installs, extension execution or model calls. */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { piProjectDir } from "./project-paths.js";
+export function skillResourceName(path) {
+    const parts = path.split(/[\\/]/);
+    const file = parts.at(-1) ?? "";
+    return file.toLowerCase() === "skill.md" ? (parts.at(-2) ?? "") : file.replace(/\.md$/i, "");
+}
+export async function resolveSkillResources(cwd) {
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.fromStorage({
+        withLock(scope, read) {
+            const path = scope === "global" ? join(agentDir, "settings.json") : join(piProjectDir(cwd), "settings.json");
+            let text;
+            try {
+                text = readFileSync(path, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            // This storage is intentionally read-only: no lock files or migrated settings are persisted.
+            read(text);
+        },
+    });
+    const errors = settingsManager.drainErrors();
+    if (errors.length)
+        throw new Error(`Cannot discover skills: ${errors.map((e) => `${e.scope} settings: ${e.error.message}`).join("; ")}`);
+    const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const resolved = await manager.resolve(async () => "skip");
+    // Pi has already applied package identity, scope, manifest and settings filters and precedence.
+    const seen = new Set();
+    const skills = resolved.skills
+        .filter((resource) => resource.enabled)
+        .flatMap((resource) => {
+        try {
+            const path = statSync(resource.path).isDirectory() ? join(resource.path, "SKILL.md") : resource.path;
+            return statSync(path).isFile() ? [{ ...resource, path }] : [];
+        }
+        catch {
+            return [];
+        }
+    })
+        .filter((resource) => {
+        // Reserve identity before parsing: a malformed local override cannot reveal a wider package ceiling.
+        const name = skillResourceName(resource.path);
+        if (seen.has(name))
+            return false;
+        seen.add(name);
+        return true;
+    });
+    return { skills, configured: manager.listConfiguredPackages() };
+}
+//# sourceMappingURL=skill-resources.js.map

package/dist/kernel/skill-resources.js.map

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

package/dist/kernel/spawn.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Build the argv for a governed descendant pi process.
+ *
+ * The enforcement point is pi core, not this package: `--tools` and `--no-tools` hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them (verified,
+ * probe `pi-fabric-eval` probes 9–11). So governance reduces to "compute the allowlist correctly
+ * and hand it to pi", with no runtime inside the descendant.
+ */
+import { type Capability } from "./resolve.ts";
+export interface SpawnPlanInput {
+    effective: Capability[];
+    prompt: string;
+    model?: string;
+    provider?: string;
+    thinking?: string;
+    /** Session file path, or omit for an ephemeral child. */
+    sessionFile?: string;
+    /** Non-interactive by default: a governed child should not prompt a human. */
+    print?: boolean;
+    /**
+     * Absolute path per skill NAME (`review` -> `/…/review`), as the catalog discovered them.
+     *
+     * R-32. Only skills named by a `skill:` capability in `effective` are passed, and a granted skill
+     * absent from this map is reported in `unresolvedSkills` rather than dropped.
+     */
+    skillPaths?: Record<string, string>;
+    /**
+     * Let the child load `AGENTS.md` / `CLAUDE.md`. **Default false** — see the `--no-context-files`
+     * note in `planSpawn`.
+     */
+    contextFiles?: boolean;
+    /**
+     * Instructions appended to the child's system prompt — a definition's `SKILL.md` body (ADR-0016).
+     *
+     * Appended rather than replacing, so pi's own coding-assistant prompt survives underneath and a
+     * definition only has to describe its own job.
+     */
+    systemPrompt?: string;
+}
+export interface SpawnPlan {
+    args: string[];
+    /** The tool names pi will allow, for the ledger. `null` means no tools at all. */
+    allowlist: string[] | null;
+    /** Skill paths handed to the child, for the ledger. */
+    skills: string[];
+    /**
+     * Granted `skill:` capabilities with no known path. **Non-empty means the caller should refuse**:
+     * the child would silently lack a capability its grant says it holds.
+     */
+    unresolvedSkills: Capability[];
+}
+/**
+ * Produce `pi` arguments enforcing `effective`.
+ *
+ * Note the `--no-tools` branch: pi rejects an empty `--tools` list, and passing no flag at all would
+ * silently fall back to pi's defaults — which is the opposite of a zero grant. An empty grant must be
+ * expressed explicitly.
+ */
+export declare function planSpawn(input: SpawnPlanInput): SpawnPlan;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/kernel/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/kernel/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,gBAAgB,EAAE,UAAU,EAAE,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CA8D1D"}

package/dist/kernel/spawn.js

@@ -0,0 +1,116 @@
+/**
+ * Build the argv for a governed descendant pi process.
+ *
+ * The enforcement point is pi core, not this package: `--tools` and `--no-tools` hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them (verified,
+ * probe `pi-fabric-eval` probes 9–11). So governance reduces to "compute the allowlist correctly
+ * and hand it to pi", with no runtime inside the descendant.
+ */
+import { toPiToolsAllowlist } from "./resolve.js";
+/**
+ * Produce `pi` arguments enforcing `effective`.
+ *
+ * Note the `--no-tools` branch: pi rejects an empty `--tools` list, and passing no flag at all would
+ * silently fall back to pi's defaults — which is the opposite of a zero grant. An empty grant must be
+ * expressed explicitly.
+ */
+export function planSpawn(input) {
+    const allowlist = toPiToolsAllowlist(input.effective);
+    const args = [];
+    if (input.print !== false)
+        args.push("--print");
+    if (input.provider)
+        args.push("--provider", input.provider);
+    if (input.model)
+        args.push("--model", input.model);
+    if (input.thinking)
+        args.push("--thinking", input.thinking);
+    if (input.sessionFile)
+        args.push("--session", input.sessionFile);
+    else
+        args.push("--no-session");
+    // Disable discovery so ambient user extensions cannot widen a governed child's surface. Explicit
+    // `-e` paths would still load, so this package never passes one.
+    args.push("--no-extensions");
+    // R-32. `--no-extensions` governs EXTENSIONS ONLY — measured, not assumed: a child spawned with
+    // `--tools read` still loaded all eight of the operator's skills and `CLAUDE.md`
+    // (probe `g16-herdr` §4-5). Skills are injected into the system prompt rather than passed as
+    // tools, so `--tools` cannot reach them and the `skill:` namespace enforced nothing at all.
+    //
+    // `--no-skills` is unconditional and `--skill` is added on top, because that is exactly how pi
+    // resolves them (`dist/core/resource-loader.js:329`): with `noSkills` set, discovered skills are
+    // dropped and explicitly-passed paths are kept. Passing `--skill` WITHOUT `--no-skills` would add to
+    // the discovered set instead of replacing it — an allowlist that widens, which is the failure
+    // direction this package exists to prevent.
+    const skills = [];
+    const unresolvedSkills = [];
+    for (const capability of input.effective) {
+        if (!capability.startsWith("skill:"))
+            continue;
+        const path = input.skillPaths?.[capability.slice(6)];
+        if (path)
+            skills.push(path);
+        else
+            unresolvedSkills.push(capability);
+    }
+    args.push("--no-skills");
+    for (const path of skills)
+        args.push("--skill", path);
+    // Context files are model-directing text that NO capability describes and no ledger line records, so
+    // a child inheriting them holds influence its grant does not express. Under ADR-0012's threat model
+    // — prompt injection explicitly in scope — an untrusted repository's `CLAUDE.md` reaching a governed
+    // child is the injection vector. Off by default therefore, but deliberately still expressible:
+    // inheriting a project's conventions is often exactly what an operator wants, and that should be a
+    // decision they make rather than one this package makes silently in either direction.
+    if (!input.contextFiles)
+        args.push("--no-context-files");
+    // Prompt templates are the third resource class that `--no-extensions` does not cover — found in the
+    // banner of the very run that verified the two above. Lower risk than skills (a template is expanded
+    // when a human invokes `/name`, not injected into the system prompt) but withheld for consistency:
+    // under a herdr backend a governed child runs in an attachable pane WITH a human, so "only what the
+    // grant names" must not depend on which executor ran it.
+    args.push("--no-prompt-templates");
+    // A definition's body, so the child IS the reviewer rather than merely holding a reviewer's tools.
+    // Note this is operator-authored text from a file on disk, not a model-chosen string — the model
+    // picks WHICH definition, never its contents. That is what keeps it out of `neutralisePrompt`'s
+    // remit: the G1 hazard is a model-controlled string reaching a parser, and this is not one.
+    if (input.systemPrompt)
+        args.push("--append-system-prompt", input.systemPrompt);
+    if (allowlist)
+        args.push("--tools", allowlist.join(","));
+    else
+        args.push("--no-tools");
+    args.push(neutralisePrompt(input.prompt));
+    return { args, allowlist, skills, unresolvedSkills };
+}
+/**
+ * Make a model-controlled task unparseable by pi's CLI.
+ *
+ * pi's usage is `pi [options] [@files...] [messages...]`, and both of the non-message forms are reached
+ * by the FIRST CHARACTER of an argv element:
+ *
+ *  - `@…` is resolved as a file and its contents injected into the child's prompt — absolute paths, `~`
+ *    expansion, no sandbox. This happens in `main.js` before any tool is constructed, so `--tools` and
+ *    `--no-tools` never apply to it. A child granted nothing at all still reads the file. Verified
+ *    against pi 0.83.0 (review finding A-C1 / B-C7, and probe `g1-argv`).
+ *  - `-…` is parsed as a flag, and pi ships `--approve` ("trust project-local files for this run").
+ *
+ * The task comes from the model, so this is the one place in the package where a model-authored string
+ * would otherwise reach a parser that outranks the enforcement point. A single leading space removes it
+ * from both branches: pi does not trim before dispatching on the prefix (measured), and a leading space
+ * is semantically nil inside a prompt.
+ *
+ * **It is applied unconditionally, and that is the point.** Rewriting only arguments that start with
+ * `@` or `-` would encode pi 0.83.0's current parser into this package and silently re-open the hole
+ * the moment pi — or an extension registering its own flags — adds a third prefix. The guarantee here is
+ * positional rather than pattern-based: the first character of that argv element is never the task's.
+ *
+ * Deliberately NOT a refusal. The review also suggested rejecting `@`/`-` tasks in `planDelegation` so
+ * they land in the ledger. Neutralising costs no false refusals and needs no judgement about which
+ * prompts are legitimate, so it is the whole fix; recording an attempt is an audit question (G6), not a
+ * security one, and is left to that group.
+ */
+function neutralisePrompt(prompt) {
+    return ` ${prompt}`;
+}
+//# sourceMappingURL=spawn.js.map

package/dist/kernel/spawn.js.map

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

package/dist/kernel/workspace.d.ts

@@ -0,0 +1,51 @@
+export { ENV_WORKSPACE_REGISTRY } from "./env-names.ts";
+export type WorkspaceAccess = "read" | "write";
+export interface WorkspaceRegistryFile {
+    version: 1;
+    workspaces: Record<string, {
+        path: string;
+    }>;
+    /**
+     * Where this was loaded from, carried so a refusal can NAME it.
+     *
+     * The README claimed an unregistered id is refused "with `WORKSPACE_NOT_REGISTERED`, which names the
+     * file", and `catalog.ts` justified exempting the whole namespace from the unknown check on the strength of
+     * that — *"a second, weaker check here can only turn that precise refusal into a misleading one"*. The
+     * refusal named no file: the registry object had no idea where it came from. Carried on the object rather
+     * than passed per call so a caller cannot forget it. Optional because a hand-built literal (tests,
+     * `workspaceEntries` fixtures) has no source.
+     */
+    source?: string;
+}
+export interface ValidatedWorkspace {
+    workspaceId: string;
+    /** Canonical Git worktree root and the child's validated initial CWD. Not a sandbox. */
+    root: string;
+    gitCommonDir: string;
+}
+export declare function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegistryFile>;
+/**
+ * The registered workspace ids, for `planInit` to scaffold and `/grants` to list. `[]` when there is no registry or it is broken.
+ *
+ * Fails SOFT, and only because nothing here is an authority: this decides which ids appear as COMMENTS in a
+ * generated file. `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that refusal is
+ * the operator's signal at the point of use, where routing genuinely depends on it. Swallowing it there
+ * would be unsafe; swallowing it here costs a suggestion. Same argument as `buildCatalog`'s.
+ *
+ * Lives here rather than in `init.ts` because it reads the filesystem, and `planInit` — the centrepiece of
+ * that module — documents itself as "Pure: no filesystem". It is a registry concern; this is where the
+ * registry lives. Moved when `init.ts` crossed the 400-line ceiling, which this project splits for rather
+ * than raising (`delegate.ts` at 413, `grants.ts` at 398).
+ */
+export declare function registeredWorkspaceIds(registryPath?: string | undefined): Promise<string[]>;
+export declare function resolveWorkspace(registry: WorkspaceRegistryFile, workspaceId: string): Promise<ValidatedWorkspace>;
+/**
+ * Canonicalize and validate the initial workspace against Git's registered worktree list.
+ * This prevents accidental misrouting. It does not constrain any path a child accesses after spawn.
+ */
+export declare function validateRegisteredWorkspace(input: {
+    workspaceId: string;
+    registeredRoot: string;
+    suppliedRoot?: string;
+}): Promise<ValidatedWorkspace>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/kernel/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/kernel/workspace.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAsBD,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAoKxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,YAAY,qBAAsC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOlH;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,qBAAqB,EAC/B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0D9B"}