pi-session-mcp 0.13.0 → 0.14.0

package/.pi-session-mcp-cli/config.js

@@ -6,7 +6,7 @@ import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js"
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
 import { builtinSkillName, isSkillCatalogPath, MAX_PROFILE_SKILLS, MAX_SKILL_CATALOG_ENTRIES } from "./skill-catalog.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
-import { builtinSkillPath, skillOverrideDirectory } from "./skill-library.js";
+import { builtinSkillPath, CONTROLLER_SKILLS, skillOverrideDirectory } from "./skill-library.js";
 import { loadExecutionModes } from "./execution-modes.js";
 import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS, PROFILE_TOOLS } from "./session-tools.js";
 const alias = z.string().regex(ALIAS_PATTERN);
@@ -72,12 +72,43 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    /** `skillCatalog` aliases refused because they name a controller skill (#188); Doctor reports them on their own. */
+    refusedControllerSkills;
+    constructor(code, locations = [], refusedControllerSkills = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
+        this.refusedControllerSkills = Object.freeze([...refusedControllerSkills]);
     }
 }
+const CONTROLLER_SKILL_ISSUE = "controller_skill";
+/** Catalog aliases of controller-skill issues; only alias-shaped keys, so no value or path can pass. */
+function controllerSkillAliases(issues) {
+    return [...new Set(issues.flatMap((issue) => {
+            const skillAlias = issue.path[1];
+            return issue.code === "custom" && issue.params?.reason === CONTROLLER_SKILL_ISSUE && issue.path[0] === "skillCatalog"
+                && typeof skillAlias === "string" && ALIAS_PATTERN.test(skillAlias) ? [skillAlias] : [];
+        }))].sort();
+}
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -96,6 +127,12 @@ export const configSchema = z.object({
 }).strict().superRefine((config, context) => {
     // A profile may select only cataloged skills; there is no implicit or default skill.
     const catalog = config.skillCatalog ?? {};
+    // The catalog serves Pi workers, which are never the controlling agent (#188).
+    for (const [skillAlias, value] of Object.entries(catalog)) {
+        if (CONTROLLER_SKILLS.includes(builtinSkillName(value) ?? "")) {
+            context.addIssue({ code: "custom", path: ["skillCatalog", skillAlias], message: "A controller skill cannot be a worker skill", params: { reason: CONTROLLER_SKILL_ISSUE } });
+        }
+    }
     for (const [profileAlias, profile] of Object.entries(config.executionProfiles)) {
         if ((profile.skills ?? []).some((skill) => !Object.hasOwn(catalog, skill))) {
             context.addIssue({ code: "custom", path: ["executionProfiles", profileAlias, "skills"], message: "A selected skill must be a skillCatalog alias" });
@@ -151,7 +188,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
             const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues), controllerSkillAliases(error.issues));
         }
         throw error;
     }

package/.pi-session-mcp-cli/doctor.js

@@ -8,7 +8,7 @@ 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 { ConfigError, loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
@@ -33,7 +33,7 @@ async function readPrefix(path, maxBytes) {
     }
 }
 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", "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", "sandbox_unavailable", "workspace_git_unavailable", "event_spool_root"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "skill_controller_selected", "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", "sandbox_unavailable", "workspace_git_unavailable", "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 }); }
@@ -423,8 +423,17 @@ export async function runDoctor(dependencies = {}) {
             checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
         else if (isUnreadable(error))
             checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
-        else
-            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+        else {
+            // Locations name the offending field; an error without one, or at the root, keeps the plain subject.
+            const locations = error instanceof ConfigError ? error.locations : [];
+            const controller = new Set((error instanceof ConfigError ? error.refusedControllerSkills : []).map((skillAlias) => `skillCatalog.${skillAlias}`));
+            for (const location of locations.length ? locations : [""]) {
+                const subject = location ? `configuration:${location}` : "configuration";
+                checks.push(controller.has(location)
+                    ? failure("skill_controller_selected", subject, "remove this skillCatalog entry: controller skills are for the controlling agent, not for Pi workers")
+                    : failure("config_invalid", subject, "fix configuration using the documented schema"));
+            }
+        }
     }
     if (config) {
         for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {

package/.pi-session-mcp-cli/skill-library.js

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

package/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 ## Unreleased
 
+## 0.14.0 — 2026-10-29
+
+Minor release under ADR 0003 for
+[ADR 0014](docs/adr/0014-profile-probe-and-model-catalog.md)
+([#139](https://github.com/plagor44-ux/pi-session-mcp/issues/139)):
+agent-driven execution-profile setup. The MCP tool contract is unchanged. Setup
+gains `--list-models` and `--probe-profile`, setup installs a second controller
+skill, Doctor gains the check `skill_controller_selected`, and a configuration
+whose skill catalog names a controller skill no longer loads
+([#188](https://github.com/plagor44-ux/pi-session-mcp/issues/188)). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release,
+with eight advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Pre-release acceptance on the candidate: Level 1 except `npm audit`, and Level 2
+in the working tree and for the packed tarball, each with delivery off and on
+([acceptance record](docs/acceptance.md#v0140-pre-release-acceptance)). The
+Level 2 harness now expects both controller skills. Not established: an
+agent-driven profile change end to end, a container writer acceptance of a new
+profile, and Level 3.
+
+Agent-driven execution-profile setup
+([#139](https://github.com/plagor44-ux/pi-session-mcp/issues/139),
+[ADR 0014](docs/adr/0014-profile-probe-and-model-catalog.md)):
+
+- `pi-session-mcp-setup --list-models` prints the provider and model ids Pi
+  knows offline, with authentication presence only. Ids that could read as a
+  path are omitted and counted; providers registered only by extensions are not
+  listed.
+- `pi-session-mcp-setup --probe-profile <alias>[,<alias>...]` checks profiles
+  offline (dry run by default); with `--apply` it sends one fixed PONG prompt
+  per profile in a private temporary directory and never prints the reply. It
+  is the only setup operation that uses a provider.
+- The shipped controller skill `pi-session-profiles` lets a controlling agent
+  create, change or retire execution profiles itself. Setup installs it next to
+  `pi-session-orchestration`, so every client target reports one more skill
+  finding.
+
+Controller skills as worker skills
+([#188](https://github.com/plagor44-ux/pi-session-mcp/issues/188)):
+
+- The configuration rejects the controller skills as worker skills: a
+  `skillCatalog` value `builtin:pi-session-orchestration` or
+  `builtin:pi-session-profiles` makes it invalid
+  (`invalid_execution_profile_config`), and Doctor reports the new error check
+  `skill_controller_selected` for `configuration:skillCatalog.<alias>`, which
+  blocks setup and the probe like `config_invalid`. A
+  configuration that used such an entry no longer starts; remove the entry.
+
+## 0.13.1 — 2026-10-29
+
+Patch release under ADR 0003 with an unchanged MCP contract. It ships the
+fixes after 0.13.0: Doctor names where the configuration schema rejects a
+file ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)),
+read-only confinement of Pi's agent directory
+([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)), a writer
+added without `--base` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)),
+stale waiter-lock reclamation in the wake hook
+([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)) and
+per-writer reconcile failures
+([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)). Setup
+reports change for a broken kept writer: it now carries its own code on its
+target instead of `writer_reconcile_failed`. `npm audit` still reports
+`undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release, now with
+eight advisories ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading follows [Installation](docs/installation.md#upgrade); writers must be
+accepted again after the upgrade, as after every release.
+
+### Changed
+
+- Doctor's `config_invalid` names where the schema rejects the configuration:
+  one check per issue location (at most five) with the subject
+  `configuration:<location>`, for example
+  `configuration:executionProfiles.review.default`. Locations hold only schema
+  field names, aliases and array indexes; an unknown key that is not a schema
+  field name, and any other key that is not a valid alias, is shown as
+  `<key>`, and values and messages are never reported. An error without a
+  location keeps the subject `configuration`
+  ([#173](https://github.com/plagor44-ux/pi-session-mcp/issues/173)).
+
+### Added
+
+- Issue forms for bug reports, change proposals and maintenance tasks, and a
+  pull request template, written so that a person or a coding agent can carry
+  an issue out and a reviewer can check it
+  ([#178](https://github.com/plagor44-ux/pi-session-mcp/issues/178)).
+
+### Fixed
+
+- Security, in the lockfile only, development path: `@hono/node-server`
+  2.1.1 → 2.1.5 (via MCP Inspector; GHSA-rmxm-3fg6-px4f). Still open:
+  `undici` 8.10.2 in the production path, pinned exactly by Pi SDK 1.4.0, now
+  with eight advisories (GHSA-4qv8-2p9j-2685, GHSA-f72v-6w45-q472,
+  GHSA-xjj6-f33q-929c, GHSA-4w7w-5xrc-9h26, GHSA-2m5v-pch6-74hx,
+  GHSA-qrxm-fqhp-jwvm, GHSA-9fm3-97px-rjf6, GHSA-55wc-3pg8-jfw6), so
+  `npm audit` still reports it
+  ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+- Writer reconciliation reports a kept writer that fails, for example with
+  a missing wrapper after a crash during provisioning, on that writer's
+  target with its own code (`writer_state_invalid`) and still reconciles the
+  other writers. Only failures of shared setup state (configuration,
+  ownership) end the whole step with `writer_reconcile_failed`
+  ([#180](https://github.com/plagor44-ux/pi-session-mcp/issues/180)).
+- Wake hook: reclaiming a stale waiter lock is serialized by an exclusive
+  `<lock>.reclaim` guard, and the lock is judged again while holding it. Two
+  waiters that both saw the same stale lock can no longer both take the turn
+  and send a duplicate wake reminder
+  ([#179](https://github.com/plagor44-ux/pi-session-mcp/issues/179)).
+- Read-only confinement protects Pi's agent directory (`~/.pi/agent`, or
+  `PI_CODING_AGENT_DIR`) and, for a symlinked configuration file, its target's
+  directory: a skill directory that equals or contains either contributes only
+  the skill file as a read root. Before, a skill file placed directly in the
+  agent directory made `auth.json` readable. The real file of a symlinked skill
+  file is now a read root too, so the model can read a skill it was given
+  ([#177](https://github.com/plagor44-ux/pi-session-mcp/issues/177)).
+- Setup provisions a writer added without `--base` (for example by raising
+  `--writers`) on the workspace's recorded default base, as finish and recreate
+  already did. Before, it landed on `origin/HEAD` and default starts never
+  leased it. A recorded base that is the repository default still provisions
+  from `origin/HEAD` ([#176](https://github.com/plagor44-ux/pi-session-mcp/issues/176)).
+
 ## 0.13.0 — 2026-10-28
 
 Minor release under ADR 0003 for

package/CONTRIBUTING.md

@@ -42,7 +42,14 @@ ones:
 Pull requests are limited to collaborators. If you are not a collaborator and
 want to contribute a fix, open an issue that describes it.
 
-- Keep a pull request to one focused change, and say which issue it addresses.
+Issues use the forms in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/):
+bug report, change proposal or maintenance task. Each asks for acceptance
+criteria and a way to verify them, so that a person or a coding agent can carry
+the issue out and a reviewer can check it. Pull requests use
+[`.github/pull_request_template.md`](.github/pull_request_template.md).
+
+- Keep a pull request to one focused change, and name every issue it addresses
+  with its own closing keyword (`Closes #12. Closes #13.`).
 - Run the checks above and `npm audit` before opening it.
 - Describe what you verified and how. State only what was run: provider-free
   tests do not establish live client or model behavior.

package/README.md

@@ -30,10 +30,12 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.13.0**.
+The package version is **0.14.0**.
 
 [Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 
+Every read-only profile reads only inside its workspace and the directories of its selected skills, and a read-only profile on Linux can opt into a bubblewrap shell without network, home or host writes (`shell: "sandboxed"`, [ADR 0013](docs/adr/0013-hardened-read-only-profiles.md)).
+
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
 - **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
@@ -113,7 +115,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 ```
 
 - A workspace alias maps to a directory. Clients can select aliases only.
-- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
+- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`. A read-only profile can add `shell: "sandboxed"` on Linux.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
 - An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
 - An optional top-level `"events": { "delivery": "spool" }` turns on content-free turn events, so that a Claude Code hook can wake the controller when a turn ends instead of polling. It is off by default and changes nothing for Codex. See [Wake the controller](docs/installation.md#wake-the-controller-claude-code).

package/dist/config.d.ts

@@ -4,8 +4,20 @@ import { type WorkspaceModeEntry } from "./execution-modes.js";
 export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level" | "invalid_execution_modes" | "invalid_event_delivery";
 export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
-    constructor(code: ConfigErrorCode);
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    readonly locations: readonly string[];
+    /** `skillCatalog` aliases refused because they name a controller skill (#188); Doctor reports them on their own. */
+    readonly refusedControllerSkills: readonly string[];
+    constructor(code: ConfigErrorCode, locations?: readonly string[], refusedControllerSkills?: readonly string[]);
 }
+export declare const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export declare function issueLocations(issues: readonly z.core.$ZodIssue[]): string[];
 export declare const configSchema: z.ZodObject<{
     events: z.ZodOptional<z.ZodObject<{
         delivery: z.ZodEnum<{

package/dist/config.js

@@ -6,7 +6,7 @@ import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js"
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
 import { builtinSkillName, isSkillCatalogPath, MAX_PROFILE_SKILLS, MAX_SKILL_CATALOG_ENTRIES } from "./skill-catalog.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
-import { builtinSkillPath, skillOverrideDirectory } from "./skill-library.js";
+import { builtinSkillPath, CONTROLLER_SKILLS, skillOverrideDirectory } from "./skill-library.js";
 import { loadExecutionModes } from "./execution-modes.js";
 import { isAcceptableExtensionToolName, MAX_GRANTED_EXTENSION_TOOLS, PROFILE_TOOLS } from "./session-tools.js";
 const alias = z.string().regex(ALIAS_PATTERN);
@@ -72,12 +72,43 @@ const CONFIG_ERROR_MESSAGES = {
 };
 export class ConfigError extends Error {
     code;
-    constructor(code) {
+    /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
+    locations;
+    /** `skillCatalog` aliases refused because they name a controller skill (#188); Doctor reports them on their own. */
+    refusedControllerSkills;
+    constructor(code, locations = [], refusedControllerSkills = []) {
         super(CONFIG_ERROR_MESSAGES[code]);
         this.name = "ConfigError";
         this.code = code;
+        this.locations = Object.freeze([...locations]);
+        this.refusedControllerSkills = Object.freeze([...refusedControllerSkills]);
     }
 }
+const CONTROLLER_SKILL_ISSUE = "controller_skill";
+/** Catalog aliases of controller-skill issues; only alias-shaped keys, so no value or path can pass. */
+function controllerSkillAliases(issues) {
+    return [...new Set(issues.flatMap((issue) => {
+            const skillAlias = issue.path[1];
+            return issue.code === "custom" && issue.params?.reason === CONTROLLER_SKILL_ISSUE && issue.path[0] === "skillCatalog"
+                && typeof skillAlias === "string" && ALIAS_PATTERN.test(skillAlias) ? [skillAlias] : [];
+        }))].sort();
+}
+export const MAX_CONFIG_ISSUE_LOCATIONS = 5;
+/**
+ * Sorted, deduplicated and bounded issue locations; an issue at the root has the empty location.
+ * A segment is kept only if it is a schema field name, or, inside the path, a key that has the alias
+ * form (record keys are aliases, which Doctor already reports). Any other key, and every unrecognized
+ * key that is not a schema field name, could be a path or a secret and becomes `<key>`.
+ */
+export function issueLocations(issues) {
+    const fields = new Set([...Object.keys(configSchema.shape), ...Object.keys(profileSchema.shape), ...Object.keys(eventsSchema.shape)]);
+    const segment = (value, aliasAllowed) => typeof value === "number" ? String(value) : typeof value === "string" && (fields.has(value) || (aliasAllowed && ALIAS_PATTERN.test(value))) ? value : "<key>";
+    const locations = issues.flatMap((issue) => {
+        const path = issue.path.map((value) => segment(value, true));
+        return issue.code === "unrecognized_keys" ? issue.keys.map((key) => [...path, segment(key, false)]) : [path];
+    });
+    return [...new Set(locations.map((path) => path.join(".")))].sort().slice(0, MAX_CONFIG_ISSUE_LOCATIONS);
+}
 const eventsSchema = z.object({ delivery: z.enum(["spool", "off"]) }).strict();
 export const configSchema = z.object({
     events: eventsSchema.optional(),
@@ -96,6 +127,12 @@ export const configSchema = z.object({
 }).strict().superRefine((config, context) => {
     // A profile may select only cataloged skills; there is no implicit or default skill.
     const catalog = config.skillCatalog ?? {};
+    // The catalog serves Pi workers, which are never the controlling agent (#188).
+    for (const [skillAlias, value] of Object.entries(catalog)) {
+        if (CONTROLLER_SKILLS.includes(builtinSkillName(value) ?? "")) {
+            context.addIssue({ code: "custom", path: ["skillCatalog", skillAlias], message: "A controller skill cannot be a worker skill", params: { reason: CONTROLLER_SKILL_ISSUE } });
+        }
+    }
     for (const [profileAlias, profile] of Object.entries(config.executionProfiles)) {
         if ((profile.skills ?? []).some((skill) => !Object.hasOwn(catalog, skill))) {
             context.addIssue({ code: "custom", path: ["executionProfiles", profileAlias, "skills"], message: "A selected skill must be a skillCatalog alias" });
@@ -151,7 +188,7 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
             const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
             // Only the events field's own issues map to the delivery code; an unknown top-level key stays a profile-config error.
             const eventsIssue = error.issues.some((issue) => issue.path[0] === "events");
-            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : eventsIssue ? "invalid_event_delivery" : "invalid_execution_profile_config", issueLocations(error.issues), controllerSkillAliases(error.issues));
         }
         throw error;
     }

package/dist/confined-tools.d.ts

@@ -7,6 +7,7 @@ export declare const CONFINED_TOOL_NAMES: readonly string[];
  * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
  * A skill directory that equals or contains a protected path (the operator's home, the configuration
  * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
  */
 export declare function allowedReadRoots(workspace: string, skills: readonly Skill[], protectedPaths?: readonly string[]): Promise<string[]>;
 /**

package/dist/confined-tools.js

@@ -32,13 +32,17 @@ function isWithin(path, root) {
  * The allowed read roots: the workspace and the directory of each selected skill file, as real paths.
  * A skill directory that equals or contains a protected path (the operator's home, the configuration
  * directory, the Pi agent directory) would expose it, so only the skill file itself is a root then.
+ * A symlinked skill file resolves outside its directory, so its real file is a root as well.
  */
 export async function allowedReadRoots(workspace, skills, protectedPaths = []) {
     const roots = new Set([await realpath(workspace)]);
     const protectedReal = await Promise.all(protectedPaths.map((path) => canonical(path)));
     for (const skill of skills) {
-        const directory = await realpath(dirname(skill.filePath));
-        roots.add(protectedReal.some((path) => isWithin(path, directory)) ? await realpath(skill.filePath) : directory);
+        const directory = await realpath(dirname(skill.filePath)), file = await canonical(skill.filePath);
+        const root = protectedReal.some((path) => isWithin(path, directory)) ? file : directory;
+        roots.add(root);
+        if (!isWithin(file, root))
+            roots.add(file);
     }
     return [...roots];
 }

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" | "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" | "sandbox_unavailable" | "workspace_git_unavailable" | "event_spool_root";
+export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "skill_controller_selected" | "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" | "sandbox_unavailable" | "workspace_git_unavailable" | "event_spool_root";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;

package/dist/doctor.js

@@ -8,7 +8,7 @@ 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 { ConfigError, loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
@@ -33,7 +33,7 @@ async function readPrefix(path, maxBytes) {
     }
 }
 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", "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", "sandbox_unavailable", "workspace_git_unavailable", "event_spool_root"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "skill_controller_selected", "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", "sandbox_unavailable", "workspace_git_unavailable", "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 }); }
@@ -423,8 +423,17 @@ export async function runDoctor(dependencies = {}) {
             checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
         else if (isUnreadable(error))
             checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
-        else
-            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+        else {
+            // Locations name the offending field; an error without one, or at the root, keeps the plain subject.
+            const locations = error instanceof ConfigError ? error.locations : [];
+            const controller = new Set((error instanceof ConfigError ? error.refusedControllerSkills : []).map((skillAlias) => `skillCatalog.${skillAlias}`));
+            for (const location of locations.length ? locations : [""]) {
+                const subject = location ? `configuration:${location}` : "configuration";
+                checks.push(controller.has(location)
+                    ? failure("skill_controller_selected", subject, "remove this skillCatalog entry: controller skills are for the controlling agent, not for Pi workers")
+                    : failure("config_invalid", subject, "fix configuration using the documented schema"));
+            }
+        }
     }
     if (config) {
         for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {

package/dist/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { stdoutGuard } from "./stdout-guard-install.js";
+import { realpath } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
 import { RoutingPiSessionAdapter, WriterRelayAdapter } from "./writer-relay.js";
@@ -47,10 +48,13 @@ async function main() {
                 spool = TurnEventSpool.open(directory, { diagnostic: writeDiagnostic });
         }
         const events = spool;
+        // The configuration directory must never become readable through a skill directory: the directory
+        // named by the variable and, for a symlinked configuration file, the directory of its target.
+        // loadConfig has read the file, so the variable is set and the path exists.
+        const configFile = resolve(process.env.PI_SESSION_MCP_CONFIG);
         const hostAdapter = new SdkPiSessionAdapter({
             diagnosticSink: writeDiagnostic,
-            // The configuration directory must never become readable through a skill directory.
-            ...(process.env.PI_SESSION_MCP_CONFIG === undefined || process.env.PI_SESSION_MCP_CONFIG === "" ? {} : { protectedReadPaths: [dirname(resolve(process.env.PI_SESSION_MCP_CONFIG))] }),
+            protectedReadPaths: [dirname(configFile), dirname(await realpath(configFile))],
         });
         const relay = guardPath === undefined;
         const adapter = relay ? new RoutingPiSessionAdapter(hostAdapter, new WriterRelayAdapter({

package/dist/model-catalog.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Offline view of Pi's model registry behind an injectable interface, so tests and callers need no
+ * provider credentials. Only documented package-root exports of the SDK are used.
+ */
+export interface CatalogProvider {
+    readonly id: string;
+    readonly authConfigured: boolean;
+    readonly models: readonly string[];
+}
+export interface ModelCatalog {
+    providers(): readonly CatalogProvider[];
+}
+/**
+ * A provider or model id that is safe to print: no whitespace and no leading `/`, so it never starts a path.
+ * A leading `@` is allowed for scoped model ids; ids may contain `/` after the first character.
+ */
+export declare const CATALOG_ID_PATTERN: RegExp;
+/** Bound for one offline authentication lookup. */
+export declare const AUTH_CHECK_TIMEOUT_MS = 5000;
+/** The part of the SDK's `ModelRuntime` the catalog reads; created without model network and without a refresh. */
+export interface CatalogRuntime {
+    getProviders(): readonly {
+        readonly id: string;
+    }[];
+    getModels(providerId: string): readonly {
+        readonly id: string;
+    }[];
+    /** Resolves the configured authentication's kind, or `undefined` when none is configured. */
+    checkAuth(providerId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/**
+ * Reads the provider ids Pi knows offline, whether each has configured authentication, and its model
+ * ids. `checkAuth` reports only whether and how a provider is configured; its result is reduced to a
+ * boolean. `hasConfiguredAuth` is not used: it reads a snapshot that only an online availability refresh
+ * fills. Never calls `getAuth` or `getAvailable`, so no credential value is resolved and no provider is
+ * contacted. Providers registered only by Pi extensions are not part of the registry.
+ */
+export declare function createModelCatalog(createRuntime?: () => Promise<CatalogRuntime>): Promise<ModelCatalog>;

package/dist/model-catalog.js

@@ -0,0 +1,38 @@
+/**
+ * A provider or model id that is safe to print: no whitespace and no leading `/`, so it never starts a path.
+ * A leading `@` is allowed for scoped model ids; ids may contain `/` after the first character.
+ */
+export const CATALOG_ID_PATTERN = /^[A-Za-z0-9@][A-Za-z0-9._:@\/-]{0,255}$/;
+/** Bound for one offline authentication lookup. */
+export const AUTH_CHECK_TIMEOUT_MS = 5_000;
+const createCatalogRuntime = () => import("@earendil-works/pi-coding-agent").then(({ ModelRuntime }) => ModelRuntime.create({ refreshOnCreate: false, allowModelNetwork: false }));
+const compareIds = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/** True only for a settled, present result; a rejection or a lookup past the bound counts as not configured. */
+const authConfigured = (runtime, providerId) => new Promise((resolve) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); resolve(false); }, AUTH_CHECK_TIMEOUT_MS);
+    Promise.resolve()
+        .then(() => runtime.checkAuth(providerId, { signal: controller.signal }))
+        .then((auth) => resolve(auth !== undefined && auth !== null), () => resolve(false))
+        .finally(() => clearTimeout(timer));
+});
+/**
+ * Reads the provider ids Pi knows offline, whether each has configured authentication, and its model
+ * ids. `checkAuth` reports only whether and how a provider is configured; its result is reduced to a
+ * boolean. `hasConfiguredAuth` is not used: it reads a snapshot that only an online availability refresh
+ * fills. Never calls `getAuth` or `getAvailable`, so no credential value is resolved and no provider is
+ * contacted. Providers registered only by Pi extensions are not part of the registry.
+ */
+export async function createModelCatalog(createRuntime = createCatalogRuntime) {
+    const runtime = await createRuntime();
+    const providers = await Promise.all(runtime.getProviders().map(async (provider) => {
+        const configured = await authConfigured(runtime, provider.id);
+        return Object.freeze({
+            id: provider.id,
+            authConfigured: configured,
+            models: Object.freeze(runtime.getModels(provider.id).map((model) => model.id).sort(compareIds)),
+        });
+    }));
+    providers.sort((left, right) => compareIds(left.id, right.id));
+    return Object.freeze({ providers: () => Object.freeze(providers) });
+}

package/dist/profile-probe.d.ts

@@ -0,0 +1,28 @@
+import type { AppConfig } from "./config.js";
+import type { DoctorResult } from "./doctor.js";
+import type { ModelCatalog } from "./model-catalog.js";
+import { type PiSessionAdapter } from "./pi-adapter.js";
+import type { ProbeReport } from "./setup-probe-result.js";
+export declare const PROBE_PROMPT = "Reply with exactly the word PONG and nothing else.";
+export declare const PROBE_DEADLINES: {
+    readonly startMs: 60000;
+    readonly turnMs: 120000;
+    readonly cleanupMs: 10000;
+};
+export declare function isPong(reply: string): boolean;
+export interface ProbeDependencies {
+    readonly configPath: string;
+    readonly loadConfig: (path: string) => Promise<AppConfig>;
+    readonly doctor: () => Promise<DoctorResult>;
+    readonly catalog: () => Promise<ModelCatalog>;
+    readonly adapter: () => Promise<PiSessionAdapter>;
+    readonly makeTempDir: () => Promise<string>;
+    readonly removeDir: (path: string) => Promise<void>;
+    readonly now?: () => number;
+    readonly deadlines?: typeof PROBE_DEADLINES;
+    readonly signal?: AbortSignal;
+}
+export declare function runProfileProbe(request: {
+    profiles: readonly string[];
+    apply: boolean;
+}, deps: ProbeDependencies): Promise<ProbeReport>;