pi-session-mcp 0.13.1 → 0.14.0

package/dist/setup-main.js

@@ -26,9 +26,14 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     const failureTargets = request.writer ? [{ client: "writer", scope: request.writer.name.slice(0, request.writer.name.lastIndexOf("-w")), alias: request.writer.name }] : request.isolationControl ? [{ client: "writer", scope: "host", alias: "control" }] : request.repo !== undefined ? [{ client: "modes", scope: "workspace", alias: request.repo.alias }] : request.customizeSkill === undefined ? request.targets : [skillTarget(request.customizeSkill)];
     if (!currentSetupPlatform())
         return write(cliFailure(operation, failureTargets, "platform_unsupported", 1), request.json);
+    if (request.listModels)
+        return (await import("./setup-probe-main.js")).runListModels(request.json);
     const config = process.env.PI_SESSION_MCP_CONFIG;
-    if (!config)
+    if (!config) {
+        if (request.probe)
+            return (await import("./setup-probe-main.js")).runProbe(request.probe, request.json, "", new AbortController().signal);
         return write(cliFailure(operation, failureTargets, "config_required", 1), request.json);
+    }
     if (request.customizeSkill !== undefined) {
         const name = request.customizeSkill;
         try {
@@ -41,12 +46,14 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     const root = dependencies.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
     const controller = new AbortController();
     let interrupted;
-    const onInterrupt = () => { interrupted ??= 130; controller.abort(); };
-    const onTerminate = () => { interrupted ??= 143; controller.abort(); };
+    const onInterrupt = () => { interrupted ??= 130; controller.abort(interrupted); };
+    const onTerminate = () => { interrupted ??= 143; controller.abort(interrupted); };
     process.on("SIGINT", onInterrupt);
     process.on("SIGTERM", onTerminate);
     let setup;
     try {
+        if (request.probe)
+            return await (await import("./setup-probe-main.js")).runProbe(request.probe, request.json, resolve(config), controller.signal, { packageRoot: root });
         const writerDeps = { configPath: resolve(config), releaseRoot: root, signal: controller.signal };
         if (request.repo !== undefined) {
             try {

package/dist/setup-probe-main.d.ts

@@ -0,0 +1,14 @@
+import { type DoctorResult } from "./doctor.js";
+import { type ModelCatalog } from "./model-catalog.js";
+import type { PiSessionAdapter } from "./pi-adapter.js";
+export interface ProbeMainDependencies {
+    readonly catalog?: () => Promise<ModelCatalog>;
+    readonly adapter?: () => Promise<PiSessionAdapter>;
+    readonly doctor?: () => Promise<DoctorResult>;
+    readonly packageRoot?: string;
+}
+export declare function runListModels(json: boolean, deps?: ProbeMainDependencies): Promise<number>;
+export declare function runProbe(request: {
+    profiles: readonly string[];
+    apply: boolean;
+}, json: boolean, configPath: string, signal: AbortSignal, deps?: ProbeMainDependencies): Promise<number>;

package/dist/setup-probe-main.js

@@ -0,0 +1,76 @@
+import { stdoutGuard } from "./stdout-guard-install.js";
+import { chmod, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { createModelCatalog } from "./model-catalog.js";
+import { runProfileProbe } from "./profile-probe.js";
+import { SdkPiSessionAdapter } from "./sdk-pi-adapter.js";
+import { catalogReport, formatCatalogHuman, formatProbeHuman } from "./setup-probe-result.js";
+export async function runListModels(json, deps = {}) {
+    let report;
+    try {
+        report = catalogReport(await (deps.catalog ?? createModelCatalog)());
+    }
+    catch {
+        report = catalogReport(undefined);
+    }
+    stdoutGuard.transportStdout.write(json ? JSON.stringify(report) + "\n" : formatCatalogHuman(report));
+    return report.exitCode;
+}
+function refused(apply, refusal) {
+    return {
+        schemaVersion: 1, operation: apply ? "apply" : "dry-run", status: "failed", refusal,
+        doctor: { blocking: [], other: [] }, findings: [], usage: "unknown", exitCode: refusal === "operation_interrupted" ? 130 : 1,
+    };
+}
+export async function runProbe(request, json, configPath, signal, deps = {}) {
+    let report;
+    let catalogFailed = false;
+    try {
+        if (!configPath)
+            report = refused(request.apply, "config_required");
+        else {
+            const configFile = resolve(configPath);
+            const packageRoot = deps.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
+            report = await runProfileProbe(request, {
+                configPath: configFile, loadConfig, signal,
+                doctor: deps.doctor ?? (() => runDoctor({ packageRoot, configPath: configFile, loadConfig: () => loadConfig(configFile) })),
+                catalog: async () => {
+                    try {
+                        return await (deps.catalog ?? createModelCatalog)();
+                    }
+                    catch (error) {
+                        catalogFailed = true;
+                        throw error;
+                    }
+                },
+                adapter: deps.adapter ?? (async () => new SdkPiSessionAdapter({
+                    diagnosticSink: (diagnostic) => { process.stderr.write(JSON.stringify(diagnostic) + "\n"); },
+                    protectedReadPaths: [dirname(configFile), dirname(await realpath(configFile))],
+                })),
+                makeTempDir: async () => {
+                    const directory = await mkdtemp(join(tmpdir(), "pi-session-mcp-probe-"));
+                    try {
+                        await chmod(directory, 0o700);
+                        return directory;
+                    }
+                    catch (error) {
+                        await rm(directory, { recursive: true, force: true });
+                        throw error;
+                    }
+                },
+                removeDir: (directory) => rm(directory, { recursive: true, force: true }),
+            });
+        }
+    }
+    catch {
+        report = refused(request.apply, signal.aborted ? "operation_interrupted" : catalogFailed ? "catalog_unavailable" : "operation_failed");
+    }
+    if (signal.aborted)
+        report = { ...report, status: "failed", refusal: "operation_interrupted", exitCode: signal.reason === 143 ? 143 : 130 };
+    stdoutGuard.transportStdout.write(json ? JSON.stringify(report) + "\n" : formatProbeHuman(report));
+    return report.exitCode;
+}

package/dist/setup-probe-result.d.ts

@@ -0,0 +1,39 @@
+import { type CatalogProvider, type ModelCatalog } from "./model-catalog.js";
+import type { PiSessionCreationErrorCode } from "./pi-adapter.js";
+/** Public, path-free `--list-models` report. */
+export interface ModelCatalogReport {
+    readonly schemaVersion: 1;
+    readonly status: "ok" | "failed";
+    readonly code?: "catalog_unavailable";
+    readonly providers: readonly CatalogProvider[];
+    readonly omittedIds: number;
+    readonly note: "extension_providers_not_listed";
+    readonly exitCode: 0 | 1;
+}
+/** Fails closed when no catalog could be created; drops ids that are not plain catalog ids. */
+export declare function catalogReport(catalog: ModelCatalog | undefined): ModelCatalogReport;
+/** One line per provider with its auth presence and model ids, then the fixed extension note. */
+export declare function formatCatalogHuman(report: ModelCatalogReport): string;
+export type ProbeCode = "probe_planned" | "probe_profile_unknown" | "probe_provider_unknown" | "probe_model_unknown" | "probe_auth_missing" | "probe_passed" | "probe_unexpected_reply" | "probe_turn_failed" | "probe_start_failed" | "probe_timeout";
+export interface ProbeFinding {
+    readonly profile: string;
+    readonly status: "planned" | "ok" | "failed";
+    readonly code: ProbeCode;
+    readonly startCode?: PiSessionCreationErrorCode;
+    readonly providerTurn: boolean;
+    readonly durationMs?: number;
+}
+export interface ProbeReport {
+    readonly schemaVersion: 1;
+    readonly operation: "dry-run" | "apply";
+    readonly status: "planned" | "ok" | "failed";
+    readonly refusal?: "doctor_failed" | "config_required" | "config_unusable" | "operation_interrupted" | "catalog_unavailable" | "operation_failed";
+    readonly doctor: {
+        readonly blocking: readonly string[];
+        readonly other: readonly string[];
+    };
+    readonly findings: readonly ProbeFinding[];
+    readonly usage: "unknown";
+    readonly exitCode: 0 | 1 | 130 | 143;
+}
+export declare function formatProbeHuman(report: ProbeReport): string;

package/dist/setup-probe-result.js

@@ -0,0 +1,62 @@
+import { CATALOG_ID_PATTERN } from "./model-catalog.js";
+const compareIds = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const providersOf = (catalog) => {
+    let omittedIds = 0;
+    const providers = [];
+    for (const provider of [...catalog.providers()].sort((left, right) => compareIds(left.id, right.id))) {
+        if (!CATALOG_ID_PATTERN.test(provider.id)) {
+            omittedIds += 1;
+            continue;
+        }
+        const models = new Set();
+        for (const model of provider.models) {
+            if (!CATALOG_ID_PATTERN.test(model)) {
+                omittedIds += 1;
+                continue;
+            }
+            models.add(model);
+        }
+        providers.push(Object.freeze({
+            id: provider.id,
+            authConfigured: provider.authConfigured === true,
+            models: Object.freeze([...models].sort(compareIds)),
+        }));
+    }
+    return Object.freeze({ providers: Object.freeze(providers), omittedIds });
+};
+/** Fails closed when no catalog could be created; drops ids that are not plain catalog ids. */
+export function catalogReport(catalog) {
+    if (catalog === undefined) {
+        return Object.freeze({
+            schemaVersion: 1,
+            status: "failed",
+            code: "catalog_unavailable",
+            providers: Object.freeze([]),
+            omittedIds: 0,
+            note: "extension_providers_not_listed",
+            exitCode: 1,
+        });
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        status: "ok",
+        ...providersOf(catalog),
+        note: "extension_providers_not_listed",
+        exitCode: 0,
+    });
+}
+/** One line per provider with its auth presence and model ids, then the fixed extension note. */
+export function formatCatalogHuman(report) {
+    const lines = report.providers.map((provider) => `${provider.id} (auth: ${provider.authConfigured ? "yes" : "no"}): ${provider.models.join(", ")}`);
+    if (report.status === "failed")
+        lines.unshift("Model catalog unavailable.");
+    lines.push("Providers registered only by Pi extensions are not listed.");
+    return `${lines.join("\n")}\n`;
+}
+export function formatProbeHuman(report) {
+    const lines = report.findings.map((finding) => `${finding.profile}: ${finding.status} (${finding.code}${finding.startCode === undefined ? "" : ` ${finding.startCode}`})`);
+    if (report.refusal !== undefined)
+        lines.unshift(`Probe refused: ${report.refusal}`);
+    lines.push(`provider turns: ${report.findings.filter((finding) => finding.providerTurn).length}, usage: unknown`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/setup-writers-common.js

@@ -24,7 +24,7 @@ export const FENCE_CODES = ["writer_busy", "writer_fenced", "writer_lease_unavai
  * store's own failures count; `ownership_unavailable` and `ownership_diverged` concern one writer's registration.
  */
 export const INFRASTRUCTURE_CODE = /^(?:ownership_(?!unavailable$|diverged$)[a-z_]+|config_[a-z_]+|operation_aborted|platform_unsupported)$/;
-export const GLOBAL_ERRORS = new Set(["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid"]);
+export const GLOBAL_ERRORS = new Set(["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "skill_controller_selected"]);
 const safeAlias = (alias) => ALIAS_PATTERN.test(alias) ? alias : "invalid";
 export const targetFor = (alias, name) => ({ client: "writer", scope: safeAlias(alias), alias: WRITER_NAME_PATTERN.test(name) || (alias === "host" && name === "control") ? name : "invalid" });
 export const modesTarget = (alias) => ({ client: "modes", scope: "workspace", alias: safeAlias(alias) });

package/dist/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/docs/acceptance.md

@@ -112,7 +112,9 @@ env -i HOME="$DISPOSABLE_HOME" PATH="$PATH" PI_SESSION_MCP_CONFIG="$ACCEPTANCE_C
   `skill_already_equivalent`, `skill_verified`, `skill_removed`,
   `skill_installed`, `skill_verified`, `skill_removed`); the skill file exists
   after steps 3 and 7 and is gone after steps 6 and 9; a foreign skill placed
-  in the same skill directory stays unchanged throughout.
+  in the same skill directory stays unchanged throughout. From 0.14.0 on
+  (#139), that holds for both controller skills, `pi-session-orchestration`
+  and `pi-session-profiles`, each with its own finding in that order.
 - Steps 1 and 2 leave the client state unchanged.
 - After step 9 the `pi-session-mcp` registration is absent, the sentinel is still
   present, and the ownership record set is empty. The ownership directory has
@@ -2535,6 +2537,127 @@ Not established for `0.13.0`: the sandbox on a host that restricts unprivileged
 user namespaces; Git inside the sandbox on a linked worktree in live use (the
 bubblewrap-gated tests cover it); the macOS upgrade; Level 3.
 
+### v0.13.1 post-release evidence
+
+Recorded on 2026-10-29 for the published release `0.13.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.13.1` (tag object
+`57c0786f1db3f732db797c8204e338ce17cf7fb2`) peels to the merge commit
+`c25c7687ecb66043a001c689c64e77be3cd25952` of #185, and
+`git describe --tags --exact-match` reports `v0.13.1`. CI on the merge commit
+(run 40832546742) and on the tag (run 40833087074) passed on the first attempt.
+
+- Level 1 on the tag clone after `npm ci`, from 07:32 to 07:34 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (136 files, 3948 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean. Doctor
+  reported `packageVersion` `0.13.1` and exited with `2` because no
+  configuration was set (`config_missing`). The manifests were unchanged
+  afterwards.
+- `pi-session-mcp@0.13.1` on npm: 922 files, shasum
+  `e2e0e2652a2cab6bf891e61bcfa14754258eb59b`, `gitHead` `c25c768` (the merge
+  commit). It was staged and approved by the maintainer; `npm pack` of the tag
+  clone and the dry run of the publishing clone give the same shasum and file
+  count.
+- Published npm package, Level 2 from a fresh prefix, 07:34 to 07:36 UTC:
+  160 of 160 with delivery off and 228 of 228 with `--events spool`; real
+  registrations and built files unchanged, no process left, leak check passed.
+  Clients: Codex CLI `0.162.1` and Claude Code `2.1.312`. The install smoke on
+  the published package reported `smoke_passed` with version `0.13.1`.
+- The GitHub release `v0.13.1` was published the same day.
+
+Operator upgrade of the workstation from `0.13.0` to `0.13.1` on 2026-10-29
+from 09:35 UTC, following
+[Installation](installation.md#container-writers): no writer container ran at
+the start; controller sessions without a coding session stayed open and need a
+reconnect. Both client targets were removed with `0.13.0`, then
+`npm install -g pi-session-mcp@0.13.1`. Doctor reported only
+`writer_not_ready` for the 18 writers. A dry run of each provisioning command
+with unchanged settings reported `mode_unchanged` and `writer_planned`; with
+`--apply`, five container repositories with 18 writers (2 with
+`--tags reachable`, 4, 4 with `--cache go`, 4 with base `dev`, 4 with
+`--cache uv`, three of them with operator images) reported `writer_accepted`
+from 09:36 to 09:39 UTC. Client-target `--apply` and `--verify` passed for
+`claude-code:user` and `codex:user` (`mcp_verified`, `skill_verified`, and
+`hook_verified` for the wake hook); `--writer <name> --verify` passed for all
+18 writers. Doctor reported no error, only the known `workspace_gitfile` and
+`workspace_mode_unset` warnings of the worktree aliases.
+
+Operator upgrade of the second machine (Linux) from `0.13.0` to `0.13.1` on
+2026-10-29 from 09:47 UTC, with Node.js `24.22.0` and the same steps: no
+writer container and no server process of a client session ran at the start.
+Both client targets were removed with `0.13.0`, then
+`npm install -g pi-session-mcp@0.13.1`; Doctor reported only
+`writer_not_ready` for the 14 writers. The dry runs reported `mode_unchanged`
+and `writer_planned`; with `--apply`, four container repositories with 14
+writers (4, 2, 4 with an operator image and `--cache go`, 4 with an operator
+image) reported `writer_accepted` from 09:48 to 09:51 UTC. Client-target
+`--apply` and `--verify` passed for `claude-code:user` and `codex:user`
+(`mcp_verified`, `skill_verified`), and `--writer <name> --verify` passed for
+all 14 writers. Doctor reported no error, only `workspace_mode_unset` for one
+workspace without a mode.
+
+### v0.14.0 pre-release acceptance
+
+`v0.14.0` was accepted on 2026-10-29 from 17:56 to 18:01 UTC on its release
+candidate `6e18659`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.162.1` and Claude Code `2.1.312`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The minor release ships #139 ([ADR 0014](adr/0014-profile-probe-and-model-catalog.md))
+and #188. The MCP tool contract is unchanged. Setup gains `--list-models` and
+`--probe-profile`, installs a second controller skill (`pi-session-profiles`)
+and so reports one more skill finding per client target; Doctor gains the
+check `skill_controller_selected`.
+
+The first working-tree run on the earlier candidate `08fc620` failed 36 of 160
+checks: the Level 2 harness still expected one controller skill finding, so
+every step saw one finding too many. Setup itself reported the expected
+findings. The candidate `6e18659` teaches the harness both controller skills
+with the same number of checks; every result below is from that candidate.
+
+- Level 1 in a clean worktree of the candidate after `npm ci`: every command
+  exited with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    139 files, 4005 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` 8.10.2 finding through `@earendil-works/pi-coding-agent`
+    1.4.0, the latest SDK release, with eight advisories
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 932 files (tarball shasum
+    `4eb9b77c9484292a8533c6be0fda44ac18656787`, identical in three packs). A
+    scan of the unpacked files for private names, hosts and the maintainer's
+    home path found none.
+  - Doctor reported `packageVersion` `0.14.0`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke from another fresh prefix
+  reported `smoke_passed` with version `0.14.0`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained, the leak check passed and the disposable directories were removed.
+- Podman-gated writer tests on the candidate (Podman `6.1.4`): 7 of 7 passed.
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+- Live checks before the candidate, on the merged #139 code: `--list-models`
+  against a real local Pi installation reported authentication for the
+  configured providers, the probe dry run planned two profiles, and one
+  `--probe-profile <alias> --apply` returned `probe_passed` with one provider
+  turn.
+- Review: #139 had three cross-family reviews (author family OpenAI and
+  Anthropic, reviewer family GLM) and #188 one, each without blocking findings;
+  their findings were fixed or declined with a reason in #187 and #189. The
+  harness fix in this release was checked by its live run above.
+
+Not established for `0.14.0`: an agent-driven profile change end to end with
+the `pi-session-profiles` skill, a container writer acceptance of a newly
+created profile, client-target `--verify` through the installed package, which
+follows the upgrade; Level 3.
+
 ### v0.13.1 pre-release acceptance
 
 `v0.13.1` was accepted on 2026-10-29 from 06:40 to 06:48 UTC on its release

package/docs/adr/0014-profile-probe-and-model-catalog.md

@@ -0,0 +1,89 @@
+# ADR 0014: Profile probe and offline model catalog
+
+**Status:** Accepted (2026-10-29); unreleased. Issue #139.
+
+## Context
+
+The running MCP server reads its configuration once at startup. A controlling
+agent cannot reconnect its own server to prove a changed execution profile.
+Asking for a manual reconnect prevents autonomous profile setup; starting a
+nested controller would add another agent without testing a different boundary.
+The agent also needs an authoritative offline catalog rather than guessing
+provider and model ids or inspecting credential files.
+
+## Decision
+
+### 1. Offline model catalog
+
+`pi-session-mcp-setup --list-models` reports provider ids, model ids and only
+whether authentication is configured. Package-root `ModelRuntime` access sits
+behind injectable `ModelCatalog`. Creation disables model network access and
+refresh (`allowModelNetwork: false`, `refreshOnCreate: false`); the catalog
+uses only `getProviders`, `getModels` and `checkAuth`. `checkAuth` reads the
+local auth configuration offline and returns only its source and kind; the
+catalog reduces that to a boolean and bounds each lookup. `hasConfiguredAuth`
+is not used because it reads a snapshot that only an online availability
+refresh fills, so offline it always reports no authentication. The catalog
+never calls `getAuth` or `getAvailable`. This is a second narrow exception
+next to the writer wrapper's credential refresh (#142), not general permission
+to bypass `PiSessionAdapter`.
+
+Providers registered only by extensions are not listed; every catalog report
+states this limitation. Invalid catalog ids are omitted, never echoed.
+
+### 2. Opt-in profile probe
+
+`--probe-profile review,code` runs Doctor and offline profile, provider, model
+and authentication-presence checks. Only adding `--apply` authorizes one fixed
+PONG turn per passing profile, sequentially, through `PiSessionAdapter`. The
+production dependency is `SdkPiSessionAdapter`, resolving the profile as the
+server does and protecting both the named and canonical configuration
+directories from read-root expansion through skills.
+
+Doctor blocks on global configuration/build/version errors and errors about
+the requested profiles. Other errors and warnings are reported by check id
+without blocking this request. Tests inject a fake catalog, adapter and Doctor;
+no provider credentials are needed.
+
+The session uses a private empty temporary directory, mode 0700, created
+internally and removed after bounded session cleanup. This is a narrow
+exception to the configured-workspace rule: the directory is not a workspace
+alias and is never supplied as a tool or CLI argument. It avoids exposing a
+real repository as the probe's working directory; it does not sandbox trusted
+extensions or change coding profiles' existing authority.
+
+Start, turn and cleanup deadlines are 60, 120 and 10 seconds respectively.
+Interrupts abort and dispose the current session and skip remaining profiles.
+The fixed prompt is not configurable, the reply text is never reported, usage
+is `unknown`, and each finding records whether a provider turn was accepted.
+No event spool is enabled.
+
+### 3. Guarded, lazy CLI entry
+
+Ordinary setup requests never import the probe entry or install its stdout
+guard. The catalog and probe load it dynamically after the platform gate;
+the catalog needs no configuration. Its first import installs the same stdout
+guard as the server before SDK evaluation. Only the guard's transport writer
+emits reports; foreign stdout, including extension `console.log`, is dropped.
+Adapter diagnostics are structured JSON on stderr without prompts or secrets.
+Operational exceptions produce fixed refusal codes rather than raw errors.
+
+## Contract change and versioning
+
+The new setup flags and report schemas are additive public CLI contract
+changes under [ADR 0003](0003-post-mvp-maintenance.md#versioning). This decision
+does not itself bump the version or authorize publication.
+
+## Consequences
+
+- Doctor and `--verify` remain provider-free. Only
+  `--probe-profile … --apply` uses a provider among setup operations.
+- Catalog and probe run on Linux and macOS without acquiring the setup lock
+  or changing registrations or configuration.
+- The probe proves the profile on the host using the host Pi agent directory.
+  Container acceptance remains Doctor's `container_profile_refused` check and
+  writer provisioning, not this probe.
+- A successful probe does not reload any running controller's configuration;
+  an MCP server restart or reconnect is still required.
+- Reports expose only sanitized findings, durations and provider-turn presence,
+  not paths, credential values, environment values, prompts or reply text.

package/docs/client-setup.md

@@ -53,6 +53,9 @@ npm run --silent setup -- --apply --target codex:user:pi-session-mcp
 npm run --silent setup -- --verify --target codex:user:pi-session-mcp
 npm run --silent setup -- --rollback --target codex:user:pi-session-mcp
 npm run --silent setup -- --remove --target codex:user:pi-session-mcp
+npm run --silent setup -- --list-models --json
+npm run --silent setup -- --probe-profile review,code --json
+npm run --silent setup -- --probe-profile review,code --apply --json
 ```
 
 Setup runs the previously built `dist/setup-main.js`. The dry-run operation
@@ -109,27 +112,30 @@ inspected:
 None of the failure rows changes a registration or starts the handshake, and
 each exits with `1`.
 
-### Controller skill
+### Controller skills
 
-Besides the registration, `--apply` installs the controller skill
-`pi-session-orchestration` for each target, as a real copy of the effective
-skill: your override in the skill library if you have one, else the skill
-shipped in the package ([Pi skills](skills.md)). Clients discover it without
-further steps.
+Besides the registration, `--apply` installs the controller skills
+`pi-session-orchestration` (delegating work to Pi workers) and
+`pi-session-profiles` (creating, changing and retiring execution profiles) for
+each target, each as a real copy of the effective skill: your override in the
+skill library if you have one, else the skill shipped in the package
+([Pi skills](skills.md)). Clients discover them without further steps.
 
-| Target | Where the skill goes |
+| Target | Where the skills go |
 | --- | --- |
-| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
-| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` (one shared directory) |
-| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration`, where `<project>` is the directory in which setup runs |
+| `codex:user:pi-session-mcp` | `~/.agents/skills/<skill>` |
+| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/<skill>` (one shared directory per skill) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/<skill>`, where `<project>` is the directory in which setup runs |
 
-Every result therefore has a second finding per target, with the same client
-and scope and the alias `pi-session-orchestration`:
+`<skill>` is `pi-session-orchestration` or `pi-session-profiles`. Every result
+therefore has one more finding per skill and target, with the same client and
+scope and the skill name as alias:
 
 ```text
 apply: ok
 claude-code/user/pi-session-mcp: ok (applied)
 claude-code/user/pi-session-orchestration: ok (skill_installed)
+claude-code/user/pi-session-profiles: ok (skill_installed)
 ```
 
 Skill findings per operation:

package/docs/doctor-design.md

@@ -28,6 +28,7 @@ and owners are:
 | `config_missing` | `PI_SESSION_MCP_CONFIG` is not set, or the file it names is absent | `configuration` |
 | `config_unreadable` | The supported configuration path cannot be read | `configuration` |
 | `config_invalid` | Production `loadConfig` rejects the configuration. One check per schema issue location, at most five, sorted | `configuration:<location>`, a dotted path of schema field names, aliases and array indexes such as `configuration:executionProfiles.review.default`; an unknown key that is not a schema field name, and any other key that is not a valid alias, is shown as `<key>`, because it could be a path or a secret. `configuration` when the error has no location |
+| `skill_controller_selected` | Production `loadConfig` rejects the configuration because a `skillCatalog` value names a controller skill (`builtin:pi-session-orchestration` or `builtin:pi-session-profiles`). Reported instead of `config_invalid` for that location and blocks like it | `configuration:skillCatalog.<alias>` |
 | `workspace_missing` | A resolved configured workspace does not exist | validated workspace alias |
 | `workspace_not_directory` | A resolved workspace is not a directory | validated workspace alias |
 | `workspace_unreadable` | A resolved workspace cannot be read | validated workspace alias |

package/docs/installation.md

@@ -89,6 +89,89 @@ local user's existing Pi authentication and never prints it. Automated writers
 keep selected provider credentials in their private boundary agent copy; see
 [Execution modes](execution-modes.md#writer-storage-launch-and-readiness).
 
+## Check profiles: model catalog and probe
+
+List the providers and model ids Pi knows locally, with authentication presence
+only (never credential values):
+
+```bash
+pi-session-mcp-setup --list-models
+pi-session-mcp-setup --list-models --json
+```
+
+This is offline and read-only: no provider request, credential refresh, model
+network access or setup lock. It requires no `PI_SESSION_MCP_CONFIG`.
+Providers registered only by Pi extensions are not listed; the report includes
+that note. Invalid catalog ids are omitted and counted in `omittedIds`.
+Catalog creation failures report `catalog_unavailable`.
+
+With `PI_SESSION_MCP_CONFIG` already set to the configuration to check:
+
+```bash
+pi-session-mcp-setup --probe-profile review,code --json
+pi-session-mcp-setup --probe-profile review,code --apply --json
+```
+
+The first command is a dry run: Doctor runs offline, followed by profile,
+provider, model and authentication-presence checks. Only `--apply` sends a
+provider turn: one fixed PONG request per profile that passes the offline
+checks, sequentially. Duplicate aliases are checked once in request order.
+Point the variable at a candidate configuration to check it before going live;
+the commands do not write configuration or registrations. The running MCP
+server still needs a restart or reconnect to read changes.
+
+The Doctor gate blocks global configuration/build/version errors and errors
+whose subject is a requested profile. Unrelated errors and all warnings are
+listed by check id in `doctor.other`, without blocking. A blocked request
+reports `doctor_failed`; missing or unusable configuration reports
+`config_required` or `config_unusable`. Unexpected operational failures report
+`operation_failed`, and catalog creation failures report `catalog_unavailable`.
+No raw exception text is printed.
+
+Each applied probe starts the normal adapter with the resolved profile in a
+private empty temporary directory (mode 0700), not a real repository. This
+directory is created internally, never supplied as an argument or workspace
+alias, and removed after cleanup. Start and turn deadlines are 60 and 120
+seconds; session cleanup is bounded to 10 seconds. Interrupts abort and dispose
+the current session and skip the remaining profiles. Reports never include
+paths, credential values, environment values, the prompt or reply text.
+Foreign stdout from profiles/extensions is suppressed so JSON remains intact;
+sanitized structured diagnostics go to stderr. No turn event spool is used.
+
+| Code | Status | Meaning |
+| --- | --- | --- |
+| `probe_planned` | planned | Dry run: offline checks passed |
+| `probe_profile_unknown` | failed | Alias not in the configuration |
+| `probe_provider_unknown` | failed | Provider not in the catalog (offline) |
+| `probe_model_unknown` | failed | Model not in the provider's catalog (offline) |
+| `probe_auth_missing` | failed | Provider has no configured authentication (offline) |
+| `probe_passed` | ok | Session started, reply was `PONG` |
+| `probe_unexpected_reply` | failed | Turn completed with another reply |
+| `probe_turn_failed` | failed | Turn failed or was aborted |
+| `probe_start_failed` | failed | Session creation refused; carries the existing sanitized `PiSessionCreationErrorCode` |
+| `probe_timeout` | failed | Start or turn deadline passed; the session was aborted and disposed |
+
+A profile that fails an offline check is not started; the other profiles are
+still checked. Apply findings include `durationMs`. `providerTurn` records
+whether a provider turn was accepted, including turns that failed or timed out;
+a `false` finding did not spend a provider turn. Provider usage and monetary
+cost remain `unknown`.
+
+Exit codes: `0` for a successful catalog, a clean dry run (`planned`) or an
+apply where every profile passed; `1` for a failed check or refusal; `64` for
+invalid usage; `130` for SIGINT and `143` for SIGTERM during a probe (both
+report `operation_interrupted`). Both operations run on Linux and macOS and
+need no setup lock. Probe requests cannot be combined with `--target`,
+`--repo`, `--writer`, `--customize-skill`, `--list-models`, `--verify`,
+`--rollback` or `--remove`. `--list-models` is standalone apart from `--json` and the default `--dry-run`.
+Doctor and `--verify` remain provider-free.
+
+**Container repositories:** the probe proves the profile on the host, with
+the host's Pi agent directory. Writer acceptance stays with Doctor's
+`container_profile_refused` check and writer provisioning; a host probe does
+not prove a container writer. See [Execution modes](execution-modes.md) and
+[ADR 0014](adr/0014-profile-probe-and-model-catalog.md).
+
 ## 1. Install
 
 ### From npm
@@ -701,6 +784,10 @@ choose skills.
   directory, so concurrent runs cannot lose a recorded base.
 - A `builtin:` name with no override and no shipped skill makes Doctor report
   `skill_missing` and the session start fail with `skill_load_failed`.
+- The controller skills `pi-session-orchestration` and `pi-session-profiles`
+  are not worker skills: a `builtin:` catalog entry for either makes the
+  configuration invalid, and Doctor reports `skill_controller_selected` for
+  `configuration:skillCatalog.<alias>`.
 - An extension allowlist alone makes none of a package's skills available. If a
   profile relied on them, add a catalog entry with the absolute path of the
   package's `SKILL.md` and select it; see the migration section of [Pi