pi-session-mcp 0.13.1 → 0.14.1

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);
@@ -74,13 +74,25 @@ export class ConfigError extends Error {
     code;
     /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
     locations;
-    constructor(code, 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.
@@ -115,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" });
@@ -170,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", issueLocations(error.issues));
+            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

@@ -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 }); }
@@ -426,8 +426,12 @@ export async function runDoctor(dependencies = {}) {
         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 : [""]) {
-                checks.push(failure("config_invalid", location ? `configuration:${location}` : "configuration", "fix configuration using the documented schema"));
+                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"));
             }
         }
     }

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/.pi-session-mcp-cli/writer-boundary.js

@@ -6,7 +6,8 @@ import { CONTAINER_EVENTS_DIR, EVENTS_DIR_ENV, writerEventsDir } from "./turn-ev
 import { writerContainerName, writerLabel } from "./writer-fence.js";
 export const NODE_IMAGE_REF = "docker.io/library/node@sha256:c4d5523090a817b7aa86d2111241fdd4f66d1e27782b44160e6aa63b357ecb2d";
 export const IMAGE_PULL_TIMEOUT_MS = 900_000;
-export const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null";
+// Replace refs in a clone are worker-controlled: they could make unexported work look reachable or clean (#193).
+export const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null -c core.useReplaceRefs=false";
 export class BoundaryError extends Error {
     code;
     constructor(code) {

package/.pi-session-mcp-cli/writer-lifecycle.js

@@ -344,7 +344,7 @@ export async function inspectWork(ctx, name) {
     });
     return {
         baseline: head === state.base.commit && refs.length === 1 && refs[0].name === state.base.ref && refs[0].commit === state.base.commit && tree === baseTree,
-        dirty: tree !== headTree, branches: refs.filter(({ name }) => name.startsWith("refs/heads/")),
+        dirty: tree !== headTree, head: head, branches: refs.filter(({ name }) => name.startsWith("refs/heads/")),
         digest: `sha256:${createHash("sha256").update(result.stdout).digest("hex")}`,
     };
 }
@@ -412,10 +412,16 @@ if [ "$tree" != "$(${BOUNDARY_GIT} rev-parse 'HEAD^{tree}')" ]; then
   export GIT_COMMITTER_NAME=pi-writer GIT_COMMITTER_EMAIL=pi-writer@example.invalid
   commit=$(printf '%s\\n' 'WIP collected by pi-session-mcp' | ${BOUNDARY_GIT} commit-tree "$tree" -p HEAD)
   branch=$(${BOUNDARY_GIT} symbolic-ref --short HEAD || printf '%s' "$4")
-  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$branch-wip"; then
+  # A taken name, or one that conflicts with an exported branch path, is refused rather than aborting the export.
+  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$branch-wip" \\
+    || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$branch-wip" "$commit" 2>/dev/null; then
+    printf '%s\\n' ref_name_refused
+  fi
+elif ! ${BOUNDARY_GIT} symbolic-ref -q HEAD >/dev/null 2>&1 && [ -n "$(${BOUNDARY_GIT} rev-list -n 1 HEAD --not --branches)" ]; then
+  # Clean detached HEAD that no branch of the clone reaches: export its commit under a derived name (#193).
+  if ${BOUNDARY_GIT} --git-dir=/tmp/scratch show-ref --verify --quiet "refs/heads/$4-detached" \\
+    || ! ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$4-detached" "$(${BOUNDARY_GIT} rev-parse --verify HEAD)" 2>/dev/null; then
     printf '%s\\n' ref_name_refused
-  else
-    ${BOUNDARY_GIT} --git-dir=/tmp/scratch update-ref "refs/heads/$branch-wip" "$commit"
   fi
 fi
 if [ -z "$(${BOUNDARY_GIT} --git-dir=/tmp/scratch for-each-ref --format='%(refname)')" ]; then
@@ -450,6 +456,14 @@ fi`;
                 return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
             }
             const work = await inspectWork(ctx, name);
+            // Defence in depth (#193): whatever the boundary script exported or reported as nothing to collect,
+            // every commit the clone's work refers to must exist as a commit object in the operator checkout
+            // before a digest is recorded.
+            for (const sha of [work.head, ...work.branches.map((branch) => branch.commit)]) {
+                if (sha === undefined || await git(ctx, ["cat-file", "-e", `${sha}^{commit}`], true) === undefined) {
+                    return { status: "failed", code: "writer_collect_incomplete", refs, refused: findings.length, findings };
+                }
+            }
             await writeWriterState(ctx.home, name, { ...state, collected: { digest: work.digest, at: new Date().toISOString() } });
             return { status: "ok", code: refs.length === 0 ? "nothing_to_collect" : "writer_collected", refs, refused: findings.length, findings };
         }

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 ## Unreleased
 
+## 0.14.1 — 2026-10-30
+
+Patch release under ADR 0003 for Sprint 12. The MCP tool contract, result
+codes and configuration schema are unchanged. `npm audit` still reports
+`undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Sprint 12 fixes three defects that an external audit of `9d9cf8c` reported and
+that were reproduced on that commit
+([Sprint 12](docs/sprints/2026-10-29-s12-audit-fixes.md)). The MCP tool
+contract, result codes and configuration schema are unchanged.
+
+- Read-only sessions no longer load Pi context files (`AGENTS.override.md`,
+  `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD`) from outside the
+  workspace into the model context
+  ([#192](https://github.com/plagor44-ux/pi-session-mcp/issues/192)). Every
+  resource loader of a read-only profile keeps only files whose real path lies
+  inside the workspace's real path, on every reload and before the first
+  provider request, and reads them from that verified path. Behaviour change:
+  context files of directories above the workspace, including a main
+  repository above a linked worktree, are no longer loaded for read-only
+  profiles. Coding profiles are unchanged
+  ([ADR 0013 amendment](docs/adr/0013-hardened-read-only-profiles.md)).
+- Writer collection exports a clean detached `HEAD` whose commit no branch
+  reaches as `<base>-detached`, and records its release digest only when the
+  clone's `HEAD` and every branch commit exist in the operator checkout;
+  otherwise it reports `writer_collect_incomplete`. Before, such a commit was
+  reported as `nothing_to_collect` and finish, reset, recreate and remove
+  discarded it without `--discard`
+  ([#193](https://github.com/plagor44-ux/pi-session-mcp/issues/193)).
+  Clone-side Git, including the writer guard, now ignores replace refs, and a
+  derived `-wip` or `-detached` name that conflicts with an exported branch
+  path is refused instead of aborting the export.
+- The writer relay compares every public capability field of a writer's
+  profile with the host profile before it starts an inner session, including
+  skills, extensions, granted extension tools and shell; a mismatch counts as
+  `settingsChanged`. Before, a writer with a different skill selection was
+  admitted ([#194](https://github.com/plagor44-ux/pi-session-mcp/issues/194)).
+
+## 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

package/README.md

@@ -30,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.13.1**.
+The package version is **0.14.1**.
 
 [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).
 

package/dist/capabilities.d.ts

@@ -1,6 +1,19 @@
 import type { ConfigurationMetadata } from "./config.js";
 import type { WorkspaceModeEntry } from "./execution-modes.js";
 import type { ConfiguredExecutionProfile } from "./execution-profile.js";
+/** The public capability shape of one profile, exactly as `pi_capabilities_get` publishes it. */
+export declare function projectExecutionProfile({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, shell, skills }: ConfiguredExecutionProfile): {
+    alias: string;
+    default: boolean;
+    permissionProfile: import("./execution-profile.js").PermissionProfile;
+    provider: string;
+    model: string;
+    thinkingLevel: import("./execution-profile.js").ThinkingLevel;
+    extensions: string[];
+    grantedExtensionTools: string[];
+    shell: "none" | "sandboxed";
+    skills: string[];
+};
 /** Pure projection of the snapshot captured at load time; never reads the configuration file. */
 export declare function projectCapabilities(workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, configuration: ConfigurationMetadata, workspaceModes?: ReadonlyMap<string, WorkspaceModeEntry>, eventDelivery?: "spool" | "off"): {
     ok: true;

package/dist/capabilities.js

@@ -1,5 +1,21 @@
 import packageMetadata from "../package.json" with { type: "json" };
 const compareAliases = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/** The public capability shape of one profile, exactly as `pi_capabilities_get` publishes it. */
+export function projectExecutionProfile({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, shell, skills }) {
+    return {
+        alias,
+        default: isDefault,
+        permissionProfile,
+        provider,
+        model,
+        thinkingLevel,
+        extensions: (extensions ?? []).map((extension) => extension.spec),
+        grantedExtensionTools: [...(grantedExtensionTools ?? [])],
+        // Configured intent only: whether the server's probe succeeds is a start-time fact.
+        shell: shell ?? "none",
+        skills: (skills ?? []).map((skill) => skill.alias),
+    };
+}
 /** Pure projection of the snapshot captured at load time; never reads the configuration file. */
 export function projectCapabilities(workspaces, executionProfiles, configuration, workspaceModes = new Map(), eventDelivery = "off") {
     return {
@@ -18,18 +34,6 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
         }),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, shell, skills }) => ({
-            alias,
-            default: isDefault,
-            permissionProfile,
-            provider,
-            model,
-            thinkingLevel,
-            extensions: (extensions ?? []).map((extension) => extension.spec),
-            grantedExtensionTools: [...(grantedExtensionTools ?? [])],
-            // Configured intent only: whether the server's probe succeeds is a start-time fact.
-            shell: shell ?? "none",
-            skills: (skills ?? []).map((skill) => skill.alias),
-        })),
+            .map(projectExecutionProfile),
     };
 }

package/dist/config.d.ts

@@ -6,7 +6,9 @@ export declare class ConfigError extends Error {
     readonly code: ConfigErrorCode;
     /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
     readonly locations: readonly string[];
-    constructor(code: ConfigErrorCode, 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;
 /**

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);
@@ -74,13 +74,25 @@ export class ConfigError extends Error {
     code;
     /** Dotted schema issue locations for Doctor; built by `issueLocations`, never a value, message or path. */
     locations;
-    constructor(code, 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.
@@ -115,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" });
@@ -170,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", issueLocations(error.issues));
+            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/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

@@ -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 }); }
@@ -426,8 +426,12 @@ export async function runDoctor(dependencies = {}) {
         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 : [""]) {
-                checks.push(failure("config_invalid", location ? `configuration:${location}` : "configuration", "fix configuration using the documented schema"));
+                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"));
             }
         }
     }

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>;