pi-session-mcp 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 ## Unreleased
 
+## 0.8.2 — 2026-10-13
+
+- Fixed: recovery of an interrupted skill update no longer deletes operator
+  content in the transaction's `.trash` directory. It deletes that directory
+  only when its contents are the complete, unchanged replaced copy (its
+  version 2 fingerprint equals the replaced fingerprint in the pending record).
+  A partial, modified, added-to, foreign or otherwise unprovable trash, and any
+  trash when the record names no usable replaced fingerprint, is retained and
+  reported as `skill_recovery_retained`; the pending record, the skill
+  directory and the other intermediates stay unchanged. This deliberately
+  replaces the automatic deletion of partial trash trees. See [Pi
+  skills](docs/skills.md#interrupted-updates). Issue #59.
+- Fixed: `--verify` now reports `unsupported` when the client is unsupported or
+  not discoverable (for example its CLI is not on `PATH`) and `inspect_failed`
+  when the inspection fails, instead of `registration_not_equivalent`, which
+  stays for an absent, divergent or differently fingerprinted registration. A
+  failed Doctor ends the target's verify before inspection and the handshake.
+  None of these cases mutates a registration or starts the handshake. See
+  [client setup](docs/client-setup.md#verify-diagnostics). Issue #56.
+- Fixed: `--dry-run` of a pending version 2 skill transaction now reports
+  `skill_recovery_retained` (divergent, exit 1) whenever `--apply` would retain
+  an intermediate, using the same read-only classification as the recovery, and
+  otherwise `skill_recovery_planned`. Before, it announced
+  `skill_recovery_planned` without inspecting the intermediates. A dry-run
+  never writes. See [Pi skills](docs/skills.md#interrupted-updates). Issue #60.
+- Changed: the `pi-session-orchestration` skill classifies every documented
+  `pi_session_start` error code as operator needed, transient or unknown, by
+  the stable code only. A code that is not listed is unknown, and the
+  `startup_failed` diagnostics mean that no MCP server is available. The MCP
+  tool contract and the error codes are unchanged. Issue #62.
+- Acceptance harness (maintainer script `scripts/multi-session-acceptance.mjs`,
+  not part of the npm package and not the package runtime): a run binds the
+  contents of the loaded Pi extensions, Pi's npm installation and the
+  candidate's skills, including content behind links, and passes the agent
+  directory to its server (#66); it binds every Codex skill source, launches
+  Codex with the recorded `CODEX_HOME` and refuses a run when any source holds
+  a differing controller skill, found by directory or declared name (#67); an
+  unreadable or too large bound resource refuses the run and fails the verdict
+  with the new code `resourcesUnbound` (#66, #67); and the handshake test skill
+  is offered only to the task that needs it, through a separate profile (#68).
+  See [acceptance](docs/acceptance.md#multi-session-skill-acceptance).
+- Acceptance harness: a `trio` scenario runs three concurrent sessions from one
+  controller, two writers and a read-only reviewer of a frozen fixture, with a
+  neighbor abort (#71). `abort` and `trio` now judge every `pi_session_abort`
+  call, so an abort that fails or does not target the `wait` session fails the
+  run (new code `offTargetAbort`); `abort` is stricter than before (#71).
+  Harness tests that built several runs inside one test no longer time out on
+  slow macOS runners (#70).
+- Documentation: the Sprint 3 status file
+  ([`docs/sprints/2026-10-13-s3-live-usage.md`](docs/sprints/2026-10-13-s3-live-usage.md))
+  with the first ten-task Level 3 cycle on Pi SDK `1.x`, the R06, R07 and R08
+  live records and a macOS runbook; the Sprint 3 section of
+  [acceptance](docs/acceptance.md#sprint-3-live-acceptance-2026-10-13).
+- CI: the test step runs with `NODE_OPTIONS=--unhandled-rejections=strict` on
+  the existing matrix, the same command that README, [CONTRIBUTING](CONTRIBUTING.md),
+  [Releasing](docs/releasing.md) and acceptance now name. Issue #63.
+- Documentation: delivery-status notes on the historical macOS and Pi
+  extension plans (#64); acceptance wording that separates targeted
+  multi-session evidence from a Level 3 cycle, and one definition of the
+  package version, the MCP tool contract and the setup report `schemaVersion`
+  in the [tool contracts](docs/tool-contracts.md#versions) (#65); the Sprint 2
+  status file ([`docs/sprints/2026-10-13-s2-evidence.md`](docs/sprints/2026-10-13-s2-evidence.md))
+  with the Sprint 1 closure and the roadmap status.
+- Documentation: the Sprint 1 status file
+  ([`docs/sprints/2026-10-13-s1-correctness.md`](docs/sprints/2026-10-13-s1-correctness.md)),
+  the roadmap status, and the v0.8.1 post-release evidence carried from the
+  release notes into [acceptance](docs/acceptance.md).
+
 ## 0.8.1 — 2026-10-12
 
 - `updatedAt` of a running turn now follows public SDK activity. It is the time

package/CONTRIBUTING.md

@@ -14,12 +14,14 @@ Linux or macOS and Node.js 22.19.0 or newer:
 npm ci
 npm run typecheck
 npm run build:cli
-npm test
+NODE_OPTIONS=--unhandled-rejections=strict npm test
 npm run build
 ```
 
-Tests use a fake Pi adapter or a scripted model. They need no provider
-credentials and no network access beyond the npm registry.
+The strict option makes an unhandled promise rejection fail the test run, and
+CI runs the tests with the same setting. Tests use a fake Pi adapter or a
+scripted model. They need no provider credentials and no network access beyond
+the npm registry.
 
 ## Rules
 

package/README.md

@@ -30,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.8.1**.
+The package version is **0.8.2**.
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
@@ -173,6 +173,8 @@ Contract and design:
 Maintain:
 
 - [Acceptance](docs/acceptance.md)
+- [Maintenance roadmap](docs/roadmap.md)
+- [Post-0.8.1 audit and backlog snapshot](docs/reviews/2026-10-13-post-0.8.1-audit.md)
 - [Releasing](docs/releasing.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
@@ -183,11 +185,11 @@ Maintain:
 npm ci
 npm run typecheck
 npm run build:cli
-npm test
+NODE_OPTIONS=--unhandled-rejections=strict npm test
 npm run build
 ```
 
-These are the checks that CI runs. Tests use a fake Pi adapter or a scripted model and need no provider credentials. Every direct dependency is pinned exactly, and the lockfile is committed. The project rules for contributors and coding agents are in [AGENTS.md](AGENTS.md).
+These are the checks that CI runs, with the same strict handling of unhandled promise rejections. Tests use a fake Pi adapter or a scripted model and need no provider credentials. Every direct dependency is pinned exactly, and the lockfile is committed. The project rules for contributors and coding agents are in [AGENTS.md](AGENTS.md).
 
 The Pi SDK moves quickly, so a nightly canary checks the unchanged sources against the newest published SDK without touching the pin. [Releasing](docs/releasing.md) describes how to update the pin, record a client contract, patch audit advisories and prepare a release.
 

package/dist/setup-skills.d.ts

@@ -60,13 +60,19 @@ export declare class FileSetupSkillInstaller implements SetupSkillInstaller {
      * under the backup name.
      */
     private discardBackup;
-    /** Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree. */
+    /**
+     * Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree.
+     * Callers must have proven the trash to be the complete replaced copy; a later recovery retains
+     * a partial tree instead of deleting it.
+     */
     private discardTrash;
     /**
      * Settles an interrupted update of the pending record's transaction, inside the ownership
      * transaction. Only directories with this transaction's exact names are examined, and only
      * verified ones are deleted: the backup must equal the replaced copy, the staging directory
-     * the target or an interrupted write of it. Anything else stays and is reported.
+     * the target or an interrupted write of it, the trash the complete replaced copy. Anything
+     * else stays and is reported, including a partial or changed trash.
+     * A proven trash is still deleted when a later intermediate (backup or staging) is retained.
      *
      * apply, slot absent: a complete staging directory is renamed into the slot (forward);
      * otherwise a verified backup is moved back. remove and rollback do not restore, they delete

package/dist/setup-skills.js

@@ -162,8 +162,11 @@ export class FileSetupSkillInstaller {
                     return finding("skill_recovery_retained", "divergent");
                 recovered = outcome === "recovered";
             }
-            // A dry-run never recovers; it announces the settlement apply would perform for a version 2 transaction.
+            // A dry-run never recovers; it announces the settlement apply would perform for a version 2 transaction, or its retention.
             const recoveryPlanned = operation === "dry-run" && owned?.phase === "pending" && SKILL_TREE_FINGERPRINT_PATTERN.test(owned.fingerprint) && !hasLegacy(owned);
+            // The classification apply's recovery acts on, read-only: an intermediate apply would retain is not announced as planned.
+            if (recoveryPlanned && (await classifyIntermediates(path, name, owned, desired, linkTarget)).state === "retained")
+                return finding("skill_recovery_retained", "divergent");
             const current = await inspectSlot(path, linkTarget);
             if (current.state === "linked") {
                 if (operation === "apply" && owned) {
@@ -307,7 +310,11 @@ export class FileSetupSkillInstaller {
         await this.discardTrash(names, parent, ownership);
         await this.step("trash-deleted");
     }
-    /** Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree. */
+    /**
+     * Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree.
+     * Callers must have proven the trash to be the complete replaced copy; a later recovery retains
+     * a partial tree instead of deleting it.
+     */
     async discardTrash(names, parent, ownership) {
         await removeEntries(names.trash, parent, ownership, () => this.step("trash-entry-removed"));
     }
@@ -315,7 +322,9 @@ export class FileSetupSkillInstaller {
      * Settles an interrupted update of the pending record's transaction, inside the ownership
      * transaction. Only directories with this transaction's exact names are examined, and only
      * verified ones are deleted: the backup must equal the replaced copy, the staging directory
-     * the target or an interrupted write of it. Anything else stays and is reported.
+     * the target or an interrupted write of it, the trash the complete replaced copy. Anything
+     * else stays and is reported, including a partial or changed trash.
+     * A proven trash is still deleted when a later intermediate (backup or staging) is retained.
      *
      * apply, slot absent: a complete staging directory is renamed into the slot (forward);
      * otherwise a verified backup is moved back. remove and rollback do not restore, they delete
@@ -326,26 +335,20 @@ export class FileSetupSkillInstaller {
         const names = intermediates(path, name, record.transactionId);
         const target = record.fingerprint;
         const previous = record.replaces !== undefined && SKILL_TREE_FINGERPRINT_PATTERN.test(record.replaces) ? record.replaces : undefined;
-        const slot = await inspectSlot(path, linkTarget);
-        // Only an empty slot, a link or one of setup's two copies can have intermediates of this transaction settled.
-        if (slot.state === "divergent" || (slot.state === "tree" && slot.fingerprint !== target && slot.fingerprint !== previous))
+        let found = await classifyIntermediates(path, name, record, library, linkTarget);
+        if (found.state === "untouched")
             return "untouched";
-        // A trash directory with the transaction's name was verified before it was renamed, so on
-        // recovery it may be partial. It is deleted after a structural recheck: a real directory,
-        // not a link, only regular files and directories, no hidden entries, within the tree limits.
         let changed = false;
-        if (await present(names.trash)) {
-            if (await collectPlain(names.trash) === undefined)
-                return "retained";
+        if (found.deleteTrash) {
             await this.discardTrash(names, parent, ownership);
             changed = true;
+            // Backup and staging are read again once the trash is gone; the slot stays the one first read.
+            found = await classifyIntermediates(path, name, record, library, linkTarget, found.slot);
         }
-        let backup = await inspectSlot(names.backup);
-        if (backup.state === "divergent" || (backup.state === "tree" && backup.fingerprint !== previous))
-            return "retained";
-        let staging = await classifyStaging(names.staging, target, library);
-        if (staging === "foreign")
-            return "retained";
+        if (found.state !== "settle")
+            return found.state;
+        const { slot } = found;
+        let { backup, staging } = found;
         if (operation === "apply" && slot.state === "absent") {
             if (staging === "complete" || backup.state === "tree") {
                 const source = staging === "complete" ? names.staging : names.backup;
@@ -380,6 +383,41 @@ export class FileSetupSkillInstaller {
         return changed ? "recovered" : "settled";
     }
 }
+/**
+ * Reads a pending version 2 transaction's slot, trash, backup and staging directory, by their
+ * exact names, and never writes. The slot is only inspected when `known` is not given. Shared by
+ * recovery and the dry-run, so both apply the same rules.
+ *
+ * Only an empty slot, a link or one of setup's two copies can have intermediates settled. A trash
+ * is deletable only while it is the complete replaced copy; a partial or changed trash, a backup
+ * that is not the replaced copy and a foreign staging directory are retained.
+ */
+async function classifyIntermediates(path, name, record, library, linkTarget, known) {
+    const names = intermediates(path, name, record.transactionId);
+    const target = record.fingerprint;
+    const previous = record.replaces !== undefined && SKILL_TREE_FINGERPRINT_PATTERN.test(record.replaces) ? record.replaces : undefined;
+    const slot = known ?? await inspectSlot(path, linkTarget);
+    if (slot.state === "divergent" || (slot.state === "tree" && slot.fingerprint !== target && slot.fingerprint !== previous))
+        return { state: "untouched" };
+    // A trash directory with the transaction's name holds the verified replaced copy, but only
+    // while it is complete: it is deleted only when it still equals the record's replaced
+    // fingerprint. A partial trash (an interrupted deletion) or any changed content cannot be
+    // proven to be setup's own, so it is retained and reported for the operator to settle.
+    let deleteTrash = false;
+    if (await present(names.trash)) {
+        const trash = await inspectSlot(names.trash);
+        if (trash.state !== "tree" || previous === undefined || trash.fingerprint !== previous)
+            return { state: "retained", slot, deleteTrash };
+        deleteTrash = true;
+    }
+    const backup = await inspectSlot(names.backup);
+    if (backup.state === "divergent" || (backup.state === "tree" && backup.fingerprint !== previous))
+        return { state: "retained", slot, deleteTrash };
+    const staging = await classifyStaging(names.staging, target, library);
+    if (staging === "foreign")
+        return { state: "retained", slot, deleteTrash };
+    return { state: "settle", slot, deleteTrash, backup, staging };
+}
 function healthy(ownership) { ownership.assertHealthy?.(); }
 /** The owned form of a record, without the replaced fingerprint of a finished update. */
 function ownedRecord(record, fingerprint) {

package/dist/setup.js

@@ -211,11 +211,28 @@ export class SetupOrchestrator {
                 findings.push({ target, status: "failed", code: "release_binding_mismatch" });
                 continue;
             }
-            const doctor = this.dependencies.doctor ? await this.safe(() => this.dependencies.doctor.check()) : { ok: true, code: "doctor_skipped" };
+            if (this.dependencies.doctor) {
+                const doctor = await this.safe(() => this.dependencies.doctor.check());
+                if (!doctor?.ok) {
+                    findings.push({ target, status: "failed", code: doctor?.code ?? "doctor_failed" });
+                    continue;
+                }
+            }
             const inspected = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
-            const equivalent = inspected?.state === "equivalent" && inspected.fingerprint === this.dependencies.intendedFingerprint;
-            const verified = equivalent ? await this.safe(() => adapter.verify(target)) : undefined;
-            findings.push({ target, status: doctor?.ok && equivalent && verified?.ok ? "ok" : "failed", code: !doctor?.ok ? doctor?.code ?? "doctor_failed" : !equivalent ? "registration_not_equivalent" : verified?.code ?? "verify_failed" });
+            if (!inspected) {
+                findings.push({ target, status: "failed", code: "inspect_failed" });
+                continue;
+            }
+            if (inspected.state === "unsupported") {
+                findings.push({ target, status: "unsupported", code: "unsupported" });
+                continue;
+            }
+            if (inspected.state !== "equivalent" || inspected.fingerprint !== this.dependencies.intendedFingerprint) {
+                findings.push({ target, status: "failed", code: "registration_not_equivalent" });
+                continue;
+            }
+            const verified = await this.safe(() => adapter.verify(target));
+            findings.push({ target, status: verified?.ok ? "ok" : "failed", code: verified?.code ?? "verify_failed" });
         }
         return result("verify", findings);
     }