pi-session-mcp 0.13.1 → 0.14.1

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/sdk-pi-adapter.d.ts

@@ -74,7 +74,7 @@ export type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightR
  * typecheck (and therefore the Pi SDK canary) instead of being mapped silently.
  */
 export declare function admitsTurn(disposition: PromptDisposition): boolean;
-export declare function createPhase0ResourceLoader(cwd: string, skills?: readonly Skill[]): Promise<{
+export declare function createPhase0ResourceLoader(cwd: string, skills?: readonly Skill[], permissionProfile?: ResolvedExecutionProfile["permissionProfile"]): Promise<{
     resourceLoader: DefaultResourceLoader;
     settingsManager: SettingsManager;
 }>;

package/dist/sdk-pi-adapter.js

@@ -1,6 +1,7 @@
 import { createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashToolDefinition, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { readFileSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { allowedReadRoots, createConfinedReadOnlyTools } from "./confined-tools.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-tools.js";
@@ -298,7 +299,7 @@ function isTextBlock(block) {
     return candidate.type === "text" && typeof candidate.text === "string";
 }
 /** Independently validated skills replace package and extension discovery on every reload. */
-function phase0ResourceLoaderOptions(skills) {
+function phase0ResourceLoaderOptions(skills, confinedCwd) {
     // Keep the closure's snapshot private: the SDK may annotate or mutate returned objects.
     const selected = skills.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } }));
     return {
@@ -307,6 +308,24 @@ function phase0ResourceLoaderOptions(skills) {
         noPromptTemplates: true,
         noThemes: true,
         noContextFiles: false,
+        ...(confinedCwd === undefined ? {} : {
+            agentsFilesOverride: (current) => ({
+                agentsFiles: current.agentsFiles.flatMap((file) => {
+                    try {
+                        const workspace = realpathSync(confinedCwd), real = realpathSync(file.path);
+                        const path = relative(workspace, real);
+                        if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+                            return [];
+                        // Re-read from the verified real path: the SDK read the link before this check.
+                        return [{ path: file.path, content: readFileSync(real, "utf-8").replace(/^\uFEFF/, "") }];
+                    }
+                    catch {
+                        // Unresolvable context files never enter a read-only session's model context.
+                        return [];
+                    }
+                }),
+            }),
+        }),
         systemPrompt: "phase-0-system-prompt-disabled",
         appendSystemPrompt: [],
         systemPromptOverride: () => undefined,
@@ -316,9 +335,9 @@ function phase0ResourceLoaderOptions(skills) {
         themesOverride: () => ({ themes: [], diagnostics: [] }),
     };
 }
-export async function createPhase0ResourceLoader(cwd, skills = []) {
+export async function createPhase0ResourceLoader(cwd, skills = [], permissionProfile) {
     const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
-    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills) });
+    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills, permissionProfile === "read-only" ? cwd : undefined) });
     await resourceLoader.reload();
     return { resourceLoader, settingsManager };
 }
@@ -367,7 +386,7 @@ export class SdkPiSessionAdapter {
         let resourceLoader;
         let settingsManager;
         try {
-            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills));
+            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills, executionProfile.permissionProfile));
         }
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
@@ -426,7 +445,7 @@ export class SdkPiSessionAdapter {
                 agentDir: cwd,
                 modelRuntime: runtime,
                 settingsManager: SettingsManager.inMemory(undefined, { projectTrusted: false }),
-                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills), additionalExtensionPaths: directories },
+                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills, executionProfile.permissionProfile === "read-only" ? cwd : undefined), additionalExtensionPaths: directories },
             }));
             this.checkResources(services.resourceLoader, skills, executionProfile, "extension_load");
             const loaded = services.resourceLoader.getExtensions();

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)

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/dist/writer-boundary.d.ts

@@ -2,7 +2,7 @@ import type { CommandRunner } from "./client-adapters/types.js";
 import { writerPaths, type WriterState } from "./writer-state.js";
 export declare const NODE_IMAGE_REF = "docker.io/library/node@sha256:c4d5523090a817b7aa86d2111241fdd4f66d1e27782b44160e6aa63b357ecb2d";
 export declare const IMAGE_PULL_TIMEOUT_MS = 900000;
-export declare const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null";
+export declare const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null -c core.useReplaceRefs=false";
 type WriterPaths = ReturnType<typeof writerPaths>;
 export declare class BoundaryError extends Error {
     readonly code: "image_unavailable" | "clone_verification_failed" | "writer_fenced";

package/dist/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/dist/writer-guard.js

@@ -13,7 +13,7 @@ const guardSchema = z.object({
 }).strict();
 const run = promisify(execFile);
 const defaultGit = async (cwd) => {
-    const git = async (...args) => (await run("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args], { cwd, timeout: 10_000, encoding: "utf8" })).stdout;
+    const git = async (...args) => (await run("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "core.useReplaceRefs=false", ...args], { cwd, timeout: 10_000, encoding: "utf8" })).stdout;
     const [status, head, refs] = await Promise.all([
         git("status", "--porcelain=v1", "-uall"),
         git("rev-parse", "HEAD"),

package/dist/writer-lifecycle.d.ts

@@ -66,6 +66,7 @@ export declare function provisionWriter(ctx: WriterContext, input: {
 export declare function inspectWork(ctx: WriterContext, name: string): Promise<{
     baseline: boolean;
     digest: string;
+    head?: string;
     branches: readonly {
         name: string;
         commit: string;