pi-session-mcp 0.7.1 → 0.8.0

package/dist/skill-customize.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { result } from "./setup-result.js";
+import { readSkillTree, shippedSkillsDirectory, SKILL_NAME_PATTERN, SkillTreeError, skillOverrideDirectory } from "./skill-library.js";
+/**
+ * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
+ * starting point, and records the shipped fingerprint it was based on. The operator's files are
+ * never overwritten or edited; a changed original is only reported and acknowledged by moving
+ * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ */
+export const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
+export const MAX_SKILL_BASES_BYTES = 64 * 1024;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+export class SkillBasesError extends Error {
+    constructor() {
+        super("Skill bases file is not usable");
+        this.name = "SkillBasesError";
+    }
+}
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export async function readSkillBases(overrideDirectory) {
+    const path = join(overrideDirectory, SKILL_BASES_FILE);
+    let text;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        const bytes = await readFile(path);
+        if (bytes.length > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            throw error;
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return Object.freeze({});
+        throw new SkillBasesError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillBasesError();
+    }
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion" || parsed.schemaVersion !== 1)
+        throw new SkillBasesError();
+    const bases = parsed.bases;
+    if (!isPlainObject(bases))
+        throw new SkillBasesError();
+    const entries = Object.entries(bases);
+    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && typeof value === "string" && FINGERPRINT_PATTERN.test(value)))
+        throw new SkillBasesError();
+    return Object.freeze(Object.fromEntries(entries));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Atomic replacement: a private temporary file in the same directory, then a rename. */
+async function writeSkillBases(overrideDirectory, bases) {
+    const sorted = Object.fromEntries(Object.entries(bases).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+    const content = Buffer.from(`${JSON.stringify({ schemaVersion: 1, bases: sorted })}\n`, "utf8");
+    if (content.length > MAX_SKILL_BASES_BYTES)
+        throw new SkillBasesError();
+    const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function report(request, status, code) {
+    // The name is echoed only when it is a valid skill name, so arbitrary input never reaches a report.
+    const alias = SKILL_NAME_PATTERN.test(request.name) ? request.name : "invalid";
+    const target = { client: "skills", scope: "override", alias };
+    const finding = { target, status, code };
+    // A planned change reports `planned` overall, like a registration dry-run.
+    return result(request.apply ? "apply" : "dry-run", [finding], status === "planned" ? "planned" : undefined);
+}
+export async function customizeSkill(request) {
+    const done = (status, code) => report(request, status, code);
+    if (!SKILL_NAME_PATTERN.test(request.name))
+        return done("failed", "skill_not_shipped");
+    try {
+        const shippedDirectory = join(shippedSkillsDirectory(request.packageRoot), request.name);
+        let shipped;
+        try {
+            shipped = await readSkillTree(shippedDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError && error.code === "skill_tree_missing")
+                return done("failed", "skill_not_shipped");
+            return done("failed", "skill_customize_failed");
+        }
+        const overrideDirectory = skillOverrideDirectory(request.configPath);
+        let bases;
+        try {
+            bases = await readSkillBases(overrideDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillBasesError)
+                return done("failed", "skill_bases_corrupt");
+            throw error;
+        }
+        const overridePath = join(overrideDirectory, request.name);
+        let exists = true;
+        try {
+            const info = await lstat(overridePath);
+            if (!info.isDirectory())
+                return done("failed", "skill_override_invalid");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            exists = false;
+        }
+        if (!exists) {
+            if (!request.apply)
+                return done("planned", "skill_customize_planned");
+            await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
+            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
+            return done("ok", "skill_customized");
+        }
+        try {
+            await readSkillTree(overridePath);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError)
+                return done("failed", "skill_override_invalid");
+            throw error;
+        }
+        if (bases[request.name] === shipped.fingerprint)
+            return done("unchanged", "skill_override_current");
+        if (!request.apply)
+            return done("planned", "skill_override_outdated");
+        // Only the recorded base moves: it acknowledges that the operator reviewed the changed original.
+        await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
+        return done("ok", "skill_base_updated");
+    }
+    catch {
+        return done("failed", "skill_customize_failed");
+    }
+}
+async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
+    await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+    const temporary = join(overrideDirectory, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await mkdir(temporary, { mode: 0o755 });
+        for (const file of files) {
+            const destination = join(temporary, ...file.path.split("/"));
+            await mkdir(dirname(destination), { recursive: true });
+            await writeFile(destination, file.bytes, { flag: "wx", mode: 0o644 });
+        }
+        // The override must not appear while the copy runs, and an operator's directory is never replaced.
+        if (await lstat(overridePath).then(() => true, (error) => { if (isMissing(error))
+            return false; throw error; }))
+            throw new Error("override appeared");
+        await rename(temporary, overridePath);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/skill-library.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export declare const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export declare const CONTROLLER_SKILLS: readonly string[];
+export declare const MAX_SKILL_TREE_FILES = 32;
+export declare const MAX_SKILL_TREE_BYTES: number;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export declare const PACKAGE_ROOT: string;
+export declare function shippedSkillsDirectory(packageRoot?: string): string;
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export declare function skillOverrideDirectory(configPath: string): string;
+export interface LibrarySkill {
+    readonly name: string;
+    readonly source: "override" | "shipped";
+    /** Absolute directory that holds the skill's `SKILL.md`. Internal; never reported. */
+    readonly directory: string;
+}
+export interface LibraryRoots {
+    readonly overrideDirectory: string;
+    readonly packageRoot?: string;
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export declare function resolveLibrarySkill(name: string, roots: LibraryRoots): LibrarySkill | undefined;
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export declare function builtinSkillPath(name: string, roots: LibraryRoots): string;
+export interface SkillTreeFile {
+    /** Path relative to the skill directory, with `/` separators. */
+    readonly path: string;
+    readonly bytes: Buffer;
+}
+export interface SkillTree {
+    readonly files: readonly SkillTreeFile[];
+    /** SHA-256 hex over the sorted relative paths and contents; path-free and stable. */
+    readonly fingerprint: string;
+}
+export declare class SkillTreeError extends Error {
+    readonly code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large";
+    constructor(code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large");
+}
+export interface ReadSkillTreeOptions {
+    /**
+     * `skip` (default) ignores entries whose name starts with `.`, as for a source tree. `reject`
+     * fails on them, for an installed copy: setup never writes hidden entries, so one there is
+     * operator content that a fingerprint over the visible files would not protect.
+     */
+    readonly hidden?: "skip" | "reject";
+}
+/**
+ * Reads the regular files below a skill directory in a stable order. Entries whose name starts
+ * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export declare function readSkillTree(directory: string, options?: ReadSkillTreeOptions): Promise<SkillTree>;

package/dist/skill-library.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+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 MAX_SKILL_TREE_FILES = 32;
+export const MAX_SKILL_TREE_BYTES = 1024 * 1024;
+const MAX_SKILL_TREE_DEPTH = 8;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+export function shippedSkillsDirectory(packageRoot = PACKAGE_ROOT) {
+    return join(packageRoot, "skills");
+}
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export function skillOverrideDirectory(configPath) {
+    return join(dirname(resolve(configPath)), "skills");
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export function resolveLibrarySkill(name, roots) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return undefined;
+    const override = join(roots.overrideDirectory, name);
+    if (isRegularFile(join(override, "SKILL.md")))
+        return Object.freeze({ name, source: "override", directory: override });
+    const shipped = join(shippedSkillsDirectory(roots.packageRoot), name);
+    if (isRegularFile(join(shipped, "SKILL.md")))
+        return Object.freeze({ name, source: "shipped", directory: shipped });
+    return undefined;
+}
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export function builtinSkillPath(name, roots) {
+    const skill = resolveLibrarySkill(name, roots);
+    return join(skill?.directory ?? join(shippedSkillsDirectory(roots.packageRoot), name), "SKILL.md");
+}
+export class SkillTreeError extends Error {
+    code;
+    constructor(code) {
+        super("Skill directory is not usable");
+        this.code = code;
+        this.name = "SkillTreeError";
+    }
+}
+/**
+ * Reads the regular files below a skill directory in a stable order. Entries whose name starts
+ * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export async function readSkillTree(directory, options = {}) {
+    let root;
+    try {
+        root = await realpath(directory);
+    }
+    catch {
+        throw new SkillTreeError("skill_tree_missing");
+    }
+    const files = [];
+    let bytes = 0;
+    const visit = async (current, prefix, depth) => {
+        if (depth > MAX_SKILL_TREE_DEPTH)
+            throw new SkillTreeError("skill_tree_invalid");
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            throw new SkillTreeError("skill_tree_invalid");
+        }
+        for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+            if (entry.name.startsWith(".")) {
+                if (options.hidden === "reject")
+                    throw new SkillTreeError("skill_tree_invalid");
+                continue;
+            }
+            const path = join(current, entry.name);
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                await visit(path, relativePath, depth + 1);
+                continue;
+            }
+            if (!info.isFile())
+                throw new SkillTreeError("skill_tree_invalid");
+            if (files.length + 1 > MAX_SKILL_TREE_FILES || bytes + info.size > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            const content = await readFile(path);
+            // Counted as read, so a file that grew after lstat cannot pass the limit.
+            bytes += content.length;
+            if (bytes > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            files.push(Object.freeze({ path: relativePath, bytes: content }));
+        }
+    };
+    await visit(root, "", 0);
+    if (!files.some((file) => file.path === "SKILL.md"))
+        throw new SkillTreeError("skill_tree_missing");
+    const hash = createHash("sha256");
+    for (const file of files)
+        hash.update(file.path).update("\0").update(file.bytes).update("\0");
+    return Object.freeze({ files: Object.freeze(files), fingerprint: hash.digest("hex") });
+}

package/docs/acceptance.md

@@ -97,7 +97,12 @@ env -i HOME="$DISPOSABLE_HOME" PATH="$PATH" PI_SESSION_MCP_CONFIG="$ACCEPTANCE_C
 ### Pass criteria
 
 - All nine operations report the expected overall status, finding and exit
-  status.
+  status. From the change that tracks #46 on, every operation also reports the
+  controller skill finding (`skill_absent` twice, `skill_installed`,
+  `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.
 - 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
@@ -323,6 +328,99 @@ Manual, on a machine with Pi, `pi-cursor-sdk@0.5.3` and a stored Cursor key. Run
 
 Record date, source commit, versions and outcome under Status. No secret, path or prompt content goes into the record.
 
+## Multi-session skill acceptance
+
+A targeted live check for profile skill selection ([skills](skills.md)) and for
+several Pi sessions that one real controller drives at the same time. It is not
+the ten-task Level 3 cycle and does not replace it.
+
+The maintainer script `scripts/multi-session-acceptance.mjs` prepares the run,
+starts the controller and checks the outcome. The controller itself calls the
+Pi Session MCP tools; the script never does.
+
+### Preparation
+
+- Candidate: a separate detached checkout of the commit under test, built with
+  `npm ci`, `npm run build` and `npm run build:cli`. `prepare` records the
+  commit, whether the checkout is clean, the SHA-256 of `dist/main.js` and,
+  from the harness of `cc810c9` on, a SHA-256 over every built module in
+  `dist/`; `run` refuses a changed build.
+- Configuration: `prepare --base-config <operator config> --from-profile
+  <alias>` copies only provider, model and thinking level of one working profile
+  without extensions or MCP servers into a temporary configuration with two
+  profiles: `accept-read` (default, `read-only`, skill `review`) and
+  `accept-code` (`coding`, skills `implementation` and `handshake`). From the
+  harness of `3f98104` on, all three are `builtin:` references: the two worker
+  skills ship with the candidate, and the `handshake` skill sits in the
+  override directory `skills/` next to the run configuration, so the run also
+  exercises library resolution. The `handshake` skill is generated per run and
+  holds a random token that no controller prompt contains.
+- Fixtures: four small synthetic git repositories per client (`slug`, `stats`,
+  `wait`, `range`), each a separate workspace alias (`cc-*` for Claude Code,
+  `cx-*` for Codex). Both clients use the same configuration and build.
+- Controller skill: from the harness of `3f98104` on, `prepare` installs the
+  Claude Code controller skill the way an operator does, with the candidate's
+  `pi-session-mcp-setup --apply --target claude-code:project:pi-session-mcp` in
+  the controller's directory. The setup step runs with a disposable `HOME`, so
+  setup state and client files of that step never touch the real home; it must
+  report `applied` and `skill_installed` and leave a regular copy identical to
+  the shipped skill. Codex installs skills only in the user's home, which the
+  run must not change, so the Codex controller gets one run-scoped symbolic link
+  in `.agents/skills` of its directory. Earlier runs linked both. No global
+  skill directory changes.
+- Clients: Claude Code runs as `claude -p` with `--mcp-config`,
+  `--strict-mcp-config`, `--setting-sources project,local`,
+  `--permission-mode dontAsk` and an `--allowedTools` list of the eight tools
+  plus read-only file tools, `sleep`, `node --test` and `git -C`. Codex runs as
+  `codex exec --ignore-user-config --sandbox read-only` with the server
+  defined through `-c mcp_servers.pi-candidate.*` and the three per-tool
+  approvals from [client setup](client-setup.md#run-codex-without-prompts).
+  Neither run changes a persistent registration, `HOME` or `CODEX_HOME`, and
+  both use the existing authentication.
+
+### Scenarios
+
+Each client runs two invocations, one per scenario:
+
+| Scenario | What the controller does | What is checked |
+| --- | --- | --- |
+| `parallel` | Capabilities first; two sessions of `accept-code` on `slug` and `stats`; both first turns started before waiting; one follow-up in the `slug` session that adds a test and completes the handshake from the worker's skills; own verification; close both | Candidate version and configuration fingerprint seen through capabilities; `skills` of `accept-code`; first turns overlap by the server's `startedAt` and `completedAt`; follow-up completed; tests pass and only allowed files changed; handshake file holds the token although no prompt contained it |
+| `abort` | Two sessions on `wait` (a bounded `sleep 120` command) and `range` (a bounded `sleep 45`, then the change); abort `wait` about 15 seconds after both turns started, while `range` runs; verify and close both | Every abort result is `ok` (an `abort_timeout` stays on record even after a retry); the first successful abort comes before `pi_turn_get` shows the `wait` turn `aborted`, and both before its session is closed; its abort time lies inside the running interval of `range`; `range` completed and verified; at the end of the run no late file exists and no worker `sleep` remains |
+
+### Independent checks
+
+- The script watches `/proc` during the run and records every process of the
+  controller tree, every server of this run (entry point and configuration
+  path) and every process whose working directory lies inside the run, by PID
+  and start time. After the controller exits and the server's 15-second
+  shutdown bound has passed, none of them may remain.
+- From the controller transcript it extracts only tool names, aliases, states,
+  timestamps and counts. It scans every Pi Session MCP result, with
+  `assistantText` removed, for local paths, the token and credential markers,
+  and counts mentions in `assistantText` separately.
+- Fixture oracles run on the workspace after the controller exits: `node
+  --test` and `git status` per fixture. Every changed file must have been last
+  written during a worker turn of its task's session, and `HANDSHAKE.txt`
+  during the follow-up turn, by the server's turn timestamps. This catches a
+  write outside the worker turns, not one during them.
+- Controller writes are limited by the client restrictions: the Codex
+  controller runs in a read-only sandbox, and the Claude Code controller has no
+  write or edit tool, although its allowed `git -C` could still change a
+  fixture.
+- The handshake token must appear neither in a worker prompt nor anywhere in
+  the controller transcript, and no worker prompt may name a private path or a
+  skill file. The controller's own reads and commands must not name the run's
+  private directory or its files; this is a marker check, not a sandbox.
+- The harness records its own SHA-256 at `prepare` and refuses to run or
+  re-evaluate a run with another version.
+- `evidence` writes one sanitized JSON record and refuses to write a local path
+  or the token. Transcripts and the configuration stay in the run's private
+  directory and are never published.
+
+A controller that reports success does not count; only the checks above do.
+If a client or its authentication is not available, record that client's part
+as blocked.
+
 ## Evidence rules
 
 - Record only sanitized evidence: statuses, booleans, counts, durations,
@@ -612,3 +710,147 @@ Pi extension live check with the operator's configuration on 2026-10-11:
   prompt.
 - Two Cursor sessions completed in parallel.
 - No process remained, and no foreign line reached the MCP stdout.
+
+Profile skill selection (#46) passed a multi-session skill acceptance with Claude
+Code and Codex on 2026-10-12, on Linux (`x64`) with Node.js `26.11.1`, Claude
+Code `2.1.296`, Codex CLI `0.162.1` and Pi SDK `1.1.0`:
+- Candidate: detached checkouts of `bcef6ba` (runs 1 to 3), `a086339` (run 4)
+  and `b6cf624` (run 5), each clean and built with `npm ci`, `npm run build`
+  and `npm run build:cli`. `dist/main.js` has the same SHA-256 in all five
+  runs, `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`:
+  the commits after `bcef6ba` change only the orchestration skill text, the
+  acceptance harness and documentation.
+- Level 1 on `bcef6ba`, from the command output of the maintainer's gate run:
+  every command exited with `0`. The test run reported
+  40 files, 761 passed and 5 skipped; `npm audit` reported 0 vulnerabilities;
+  `npm pack --dry-run` listed the three skills and no harness. The test suite
+  passed again on `a086339` with the same counts.
+- Configuration: the same bytes in every run, fingerprint
+  `sha256:b754f0f5e4702d81d99183817abb379eeed2fb5733f93373852eb827ec16d687`,
+  with the profiles `accept-read` and `accept-code` derived from an OpenAI
+  `gpt-6-luna` profile with thinking level `low`, and the fixture aliases
+  `cc-slug`, `cc-stats`, `cc-wait`, `cc-range`, `cx-slug`, `cx-stats`, `cx-wait`
+  and `cx-range`. Offline Doctor reported no finding for it.
+- Every invocation confirmed the candidate's version and this fingerprint
+  through `pi_capabilities_get` as its first call, and saw the skills
+  `implementation` and `handshake` on `accept-code`. Exactly one server of the
+  run was observed per invocation, and no process of the controller tree, the
+  server or the fixtures remained afterwards. No Pi Session MCP result
+  contained a local path, the token or a credential marker, and no
+  `assistantText` mentioned one.
+
+Run 5, on `b6cf624` with the harness of that commit (SHA-256
+`ca851130bbade9f0b2700a43059b7ac3ce349dad40ad2b647133f950a408c719`), passed
+every check of all four invocations:
+
+| Client | Scenario | Result |
+| --- | --- | --- |
+| Claude Code | `parallel` | First turns overlapped by 25.1 s; follow-up in the same session completed; both fixtures pass their tests with only the allowed files changed, each last written during a worker turn; `HANDSHAKE.txt` holds the token and was written during the follow-up turn, although no worker prompt contained the token and the token never appeared in the controller transcript; no controller action named the private run directory; both sessions closed |
+| Claude Code | `abort` | First turns overlapped by 23.7 s; one abort, result `ok`; `aborted` seen through `pi_turn_get` before close; the abort fell inside the running interval of the neighbor, which then completed and passes its tests; the worker's `sleep 120` was observed running, and at the end of the run it was gone and had written no file; both sessions closed |
+| Codex | `parallel` | As for Claude Code, with an overlap of 24.8 s |
+| Codex | `abort` | As for Claude Code, with an overlap of 22.4 s |
+
+The controllers made 1 to 6 `pi_turn_get` calls per session and waited between
+polls with `sleep`. Each invocation took 93 to 156 seconds. The run's
+transcripts were also checked afterwards against the criteria the harness
+gained after run 5: in both `abort` invocations the first successful abort came
+before the first `aborted` observation, and no worker prompt named a private
+path or a skill file. Run 5 used the harness of `b6cf624`; the head's harness
+adds these two checks and the run-time checksum check, and changes nothing
+else.
+
+Earlier attempts on the same build, kept on record:
+- Run 1 (Claude Code only, with the harness of `bcef6ba`, which did not record
+  its checksum yet): `parallel` passed
+  every check. In `abort` the abort itself passed (result `ok`, `aborted` seen
+  before close, the worker's `sleep` ended, no late file), but the neighbor
+  turn had completed about three seconds before the abort, so the run shows no
+  neighbor that keeps running. The neighbor task now starts with a bounded
+  `sleep 45` and the abort comes after about 15 seconds.
+- Run 2: three invocations passed every check. In Codex `parallel` every
+  functional check passed, including the handshake written during the
+  follow-up turn with a token that no prompt contained, but the controller
+  then read the run's private handshake skill to confirm the token. The
+  controller prompt now confines reads and commands to the fixtures.
+- Run 3: three invocations passed every check. In Codex `abort` the abort, the
+  running neighbor and cleanup passed, but the controller told both workers to
+  "follow configured handshake instructions" because capabilities listed a
+  `handshake` skill, so both fixtures got an extra `HANDSHAKE.txt`. The
+  orchestration skill now says that a listed skill is not a task.
+- Run 4 (`a086339`): three invocations passed every check. The Codex
+  `parallel` controller read the fixtures-only rule as excluding its own skill
+  directory, worked from `./fixtures`, and stopped after
+  `pi_capabilities_get` without starting a session. The rule now allows the
+  controller's own skill directory.
+
+No run showed a Pi Session MCP defect. The deviations were controller
+behavior and harness wording.
+
+This is a targeted check of skill selection and of two concurrent sessions
+per client. It is not the ten-task Level 3 cycle. It covers neither the
+extension profile path live (the automated SDK contract tests cover it), nor
+`read-only` workers, nor more than two concurrent sessions, nor macOS.
+
+After the owner asked on 2026-10-12 that skills install without manual linking
+and can be adjusted and extended, the same change gained the skill library,
+`builtin:` references, `--customize-skill` and the controller-skill
+installation through `setup`. Its final candidate `0ebbaa0` passed on
+2026-10-12, on Linux (`x64`) with Node.js `26.11.1`, Claude Code `2.1.296`,
+Codex CLI `0.162.1` and Pi SDK `1.1.0`:
+- Level 1 on a clean detached checkout: every command exited with `0`. The
+  test run reported 43 files, 884 passed and 5 skipped; `npm audit` reported 0
+  vulnerabilities; `npm pack --dry-run` listed 125 files with the three skills
+  and no acceptance harness. `git diff --check` from `0cb3c60` reported nothing.
+- Level 2 through `scripts/setup-acceptance.mjs` with the setup of that
+  checkout: 160 of 160 checks passed. All nine steps passed on all four
+  targets, including the controller skill finding of every step, the skill file
+  after steps 3 and 7 and its absence after steps 6 and 9, and a foreign skill
+  that stayed unchanged. The real client registrations were unchanged, no
+  process remained, no report leaked a path, and the build was unchanged.
+  Earlier candidates `24ab13d` and `37034dd` of the same change had passed
+  Level 2 with 160 of 160 as well, before the review fixes that followed them.
+- Multi-session skill acceptance, run 7, with the harness of that checkout
+  (SHA-256 `42d46f86ae617c229568437e6d96c93f965c27778c3e2fde51e1c449ef35fb12`)
+  and the dist tree SHA-256
+  `957dfac67bf0c3c179bff6584b3bda49bedad2fe1642790537f6790b31f5ef37`:
+  - `prepare` installed the Claude Code controller skill with the candidate's
+    `setup --apply` for the controller's project scope: `applied` and
+    `skill_installed`, a regular copy identical to the shipped skill.
+  - The configuration (fingerprint
+    `sha256:b8a341c9ff48ecd7c02f8959b8e4e696f305431945b659ea35d2d98485e948c3`)
+    referenced all three skills with `builtin:`: the two shipped worker skills
+    and the `handshake` skill from the override directory next to it.
+  - All four invocations passed every check: Claude Code `parallel` (first
+    turns overlapped by 21.5 s) and `abort` (22.1 s), Codex `parallel` (22.9 s)
+    and `abort` (18.9 s). In both `parallel` invocations the worker wrote the
+    handshake token, which existed only in the override-directory skill,
+    during the follow-up turn. In both `abort` invocations the one abort
+    returned `ok`, came before the `aborted` observation and fell inside the
+    running neighbor, which completed and passed its tests. No process
+    remained, and no result leaked a path, the token or a credential marker.
+- Run 6 on `cc810c9`, before the last review fixes, had passed every check of
+  all four invocations with the same configuration fingerprint and the
+  setup-installed Claude Code skill.
+
+These runs do not cover macOS, Codex skill discovery from the user's home
+(setup installs it there, and Level 2 checks the file, but no live Codex
+controller read it from there), the extension profile path live, or more than
+two concurrent sessions.
+
+Before its release, `v0.8.0` passed Level 1 and the working-tree Level 2 on
+its release candidate `6d197a0` on Linux (`x64`), with Node.js `26.11.1`, Codex
+CLI `0.162.1` and Claude Code `2.1.296`, on 2026-10-12:
+- Level 1: every command exited with `0`.
+  - The test run reported 43 files, 884 passed and 5 skipped.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 125 files, including the three skills.
+  - Doctor reported `packageVersion` `0.8.0`. With the example
+    configuration its only finding was the missing placeholder workspace.
+- Level 2 ran through `scripts/setup-acceptance.mjs` on the candidate's
+  working tree: 160 of 160 checks passed. All nine steps passed on all four
+  targets, including the controller skill finding of every step. The real
+  client registrations were unchanged, no process remained, and the built
+  files were unchanged.
+- Apart from the version, the candidate's sources equal the merge of #48,
+  whose final candidate `0ebbaa0` passed the multi-session skill acceptance
+  recorded above.

package/docs/adr/0006-pi-extension-allowlist.md

@@ -3,6 +3,9 @@
 **Status:** Accepted (2026-10-11). Issue #34. Design:
 [Pi extensions design](../pi-extensions-design.md).
 
+Amended by [ADR 0007](0007-profile-skill-selection.md) for skills that extension
+packages ship.
+
 ## Context
 
 Embedded sessions loaded no Pi extensions. Providers that exist only as Pi