pi-session-mcp 0.13.1 → 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);
@@ -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/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## 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

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.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).
 

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

package/dist/profile-probe.js

@@ -0,0 +1,164 @@
+import { toResolvedExecutionProfile } from "./execution-profile.js";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { GLOBAL_ERRORS } from "./setup-writers-common.js";
+export const PROBE_PROMPT = "Reply with exactly the word PONG and nothing else.";
+export const PROBE_DEADLINES = { startMs: 60_000, turnMs: 120_000, cleanupMs: 10_000 };
+export function isPong(reply) {
+    return reply.trim().replace(/\.$/, "").toUpperCase() === "PONG";
+}
+class ProbeTimeout extends Error {
+}
+class ProbeInterrupted extends Error {
+}
+/** Always detach the timer and listener, including when the operation rejects. */
+async function bounded(operation, ms, signal) {
+    if (signal?.aborted)
+        throw new ProbeInterrupted();
+    let timer;
+    let interrupt;
+    const stop = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new ProbeTimeout()), ms);
+        interrupt = () => reject(new ProbeInterrupted());
+        signal?.addEventListener("abort", interrupt, { once: true });
+    });
+    try {
+        return await Promise.race([Promise.resolve().then(operation), stop]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (interrupt)
+            signal?.removeEventListener("abort", interrupt);
+    }
+}
+async function dispose(handle, ms, abort) {
+    // An uncooperative abort must not prevent disposal or directory removal.
+    if (abort)
+        await bounded(() => handle.abort(), ms).catch(() => undefined);
+    await bounded(() => handle.dispose(), ms).catch(() => undefined);
+}
+async function probe(profile, adapter, deps) {
+    const deadlines = deps.deadlines ?? PROBE_DEADLINES;
+    const now = deps.now ?? Date.now;
+    const started = now();
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    deps.signal?.addEventListener("abort", interrupt, { once: true });
+    if (deps.signal?.aborted)
+        controller.abort();
+    let cwd;
+    let handle;
+    let abandoned = false;
+    let providerTurn = false;
+    let code = "probe_start_failed";
+    let startCode;
+    let abort = false;
+    try {
+        cwd = await deps.makeTempDir();
+        const input = { cwd, workspace: "profile-probe", executionProfile: toResolvedExecutionProfile(profile), signal: controller.signal };
+        handle = await bounded(async () => {
+            const created = await adapter.create(input);
+            // A create that ignores cancellation may finish after its deadline.
+            if (abandoned) {
+                await dispose(created, deadlines.cleanupMs, true);
+                throw new ProbeTimeout();
+            }
+            return created;
+        }, deadlines.startMs, deps.signal);
+        code = "probe_turn_failed";
+        const outcome = await bounded(() => handle.prompt(PROBE_PROMPT, (accepted) => {
+            if (accepted)
+                providerTurn = true;
+        }), deadlines.turnMs, deps.signal);
+        code = outcome.status === "completed"
+            ? isPong(outcome.assistantText) ? "probe_passed" : "probe_unexpected_reply"
+            : "probe_turn_failed";
+    }
+    catch (error) {
+        if (error instanceof ProbeTimeout || error instanceof ProbeInterrupted) {
+            abandoned = true;
+            controller.abort();
+            abort = true;
+            if (error instanceof ProbeTimeout)
+                code = "probe_timeout";
+        }
+        else if (handle === undefined) {
+            startCode = error instanceof PiSessionCreationError ? error.code : "pi_session_creation_failed";
+        }
+    }
+    finally {
+        deps.signal?.removeEventListener("abort", interrupt);
+        try {
+            if (handle)
+                await dispose(handle, deadlines.cleanupMs, abort || deps.signal?.aborted === true);
+        }
+        finally {
+            if (cwd !== undefined)
+                await deps.removeDir(cwd);
+        }
+    }
+    return {
+        profile: profile.alias, status: code === "probe_passed" ? "ok" : "failed", code,
+        ...(startCode === undefined ? {} : { startCode }), providerTurn, durationMs: Math.max(0, now() - started),
+    };
+}
+export async function runProfileProbe(request, deps) {
+    const profiles = [...new Set(request.profiles)];
+    const doctor = { blocking: [], other: [] };
+    const findings = [];
+    const report = (refusal) => {
+        const status = refusal !== undefined || findings.some((finding) => finding.status === "failed")
+            ? "failed" : request.apply ? "ok" : "planned";
+        return {
+            schemaVersion: 1, operation: request.apply ? "apply" : "dry-run", status,
+            ...(refusal === undefined ? {} : { refusal }), doctor, findings, usage: "unknown",
+            exitCode: refusal === "operation_interrupted" ? 130 : status === "failed" ? 1 : 0,
+        };
+    };
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    const diagnosis = await deps.doctor();
+    for (const check of diagnosis.checks) {
+        if (check.severity === "ok")
+            continue;
+        const list = check.severity === "error" && (GLOBAL_ERRORS.has(check.id) || profiles.includes(check.subject.split(":")[0]))
+            ? doctor.blocking : doctor.other;
+        if (!list.includes(check.id))
+            list.push(check.id);
+    }
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    if (doctor.blocking.length)
+        return report("doctor_failed");
+    let config;
+    try {
+        config = await deps.loadConfig(deps.configPath);
+    }
+    catch {
+        return report(deps.signal?.aborted ? "operation_interrupted" : "config_unusable");
+    }
+    if (deps.signal?.aborted)
+        return report("operation_interrupted");
+    const catalog = await deps.catalog();
+    let adapter;
+    for (const alias of profiles) {
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+        const profile = config.executionProfiles.get(alias);
+        const provider = profile && catalog.providers().find((entry) => entry.id === profile.provider);
+        const code = !profile ? "probe_profile_unknown"
+            : !provider ? "probe_provider_unknown"
+                : !provider.models.includes(profile.model) ? "probe_model_unknown"
+                    : !provider.authConfigured ? "probe_auth_missing" : "probe_planned";
+        if (code !== "probe_planned" || !request.apply) {
+            findings.push({ profile: alias, status: code === "probe_planned" ? "planned" : "failed", code, providerTurn: false });
+            continue;
+        }
+        adapter ??= await deps.adapter();
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+        findings.push(await probe(profile, adapter, deps));
+        if (deps.signal?.aborted)
+            return report("operation_interrupted");
+    }
+    return report();
+}

package/dist/setup-cli.d.ts

@@ -19,6 +19,13 @@ export interface SetupCliRequest extends SetupRequest {
         alias: string;
         apply: boolean;
     };
+    /** `--list-models`: prints the offline provider/model catalog. */
+    readonly listModels?: true;
+    /** `--probe-profile <alias>[,<alias>...]`: checks profiles offline, then probes them with `--apply`. */
+    readonly probe?: {
+        readonly profiles: readonly string[];
+        readonly apply: boolean;
+    };
 }
 export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
 /** Both report modes are projections of the same sanitized result. */

package/dist/setup-cli.js

@@ -1,5 +1,6 @@
 import { cpusSchema, cpuSharesSchema, memorySchema } from "./writer-limits.js";
 import { WRITER_NAME_PATTERN } from "./writer-state.js";
+import { ALIAS_PATTERN } from "./execution-profile.js";
 export function parseSetupArgs(argv) {
     let operation;
     let json = false;
@@ -10,6 +11,8 @@ export function parseSetupArgs(argv) {
     let acceptHostWrites = false;
     let writer, writerOperation, baseRef;
     let discard = false, codex = false, isolationControl = false;
+    let listModels = false;
+    let probeProfiles;
     const container = {};
     const modeFlags = new Set();
     const clearLimits = [];
@@ -60,6 +63,24 @@ export function parseSetupArgs(argv) {
             json = true;
             continue;
         }
+        if (argument === "--list-models") {
+            if (listModels)
+                throw new Error("usage_invalid");
+            listModels = true;
+            continue;
+        }
+        if (argument === "--probe-profile") {
+            if (probeProfiles !== undefined)
+                throw new Error("usage_invalid");
+            const value = argv[++index];
+            if (value === undefined || value === "")
+                throw new Error("usage_invalid");
+            const aliases = value.split(",");
+            if (aliases.some((alias) => !ALIAS_PATTERN.test(alias)))
+                throw new Error("usage_invalid");
+            probeProfiles = [...new Set(aliases)];
+            continue;
+        }
         if (argument === "--dry-run" || argument === "--apply" || argument === "--verify" || argument === "--rollback" || argument === "--remove") {
             if (operation)
                 throw new Error("operation_repeated");
@@ -173,6 +194,21 @@ export function parseSetupArgs(argv) {
         }
         throw new Error("argument_unsupported");
     }
+    if (listModels || probeProfiles !== undefined) {
+        if (listModels && probeProfiles !== undefined)
+            throw new Error("usage_invalid");
+        if (targets.length > 0 || modeFlags.size > 0 || customizeSkill !== undefined || writer !== undefined || writerOperation !== undefined || isolationControl || discard || baseRef || codex) {
+            throw new Error(listModels ? "list_models_combination" : "probe_combination");
+        }
+        if (listModels) {
+            if (operation !== undefined && operation !== "dry-run")
+                throw new Error("list_models_combination");
+            return { ...(operation ? { operation } : {}), targets, json, listModels: true };
+        }
+        if (operation !== undefined && operation !== "dry-run" && operation !== "apply")
+            throw new Error("probe_combination");
+        return { ...(operation ? { operation } : {}), targets, json, probe: { profiles: probeProfiles, apply: operation === "apply" } };
+    }
     if (writer !== undefined) {
         if (operation === "remove" || operation === "verify") {
             if (writerOperation)