pi-session-mcp 0.8.0 → 0.8.2

package/.pi-session-mcp-cli/skill-library.js

@@ -59,6 +59,77 @@ export class SkillTreeError extends Error {
         this.name = "SkillTreeError";
     }
 }
+/** A version 2 skill tree fingerprint as it is stored. */
+export const SKILL_TREE_FINGERPRINT_PATTERN = /^v2:[0-9a-f]{64}$/;
+/** A version 1 fingerprint as 0.8.0 stored it: bare SHA-256 hex. */
+export const LEGACY_SKILL_TREE_FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const FINGERPRINT_DOMAIN = "pi-session-mcp skill tree v2\n";
+function uint32(value) {
+    const bytes = Buffer.alloc(4);
+    bytes.writeUInt32BE(value);
+    return bytes;
+}
+function uint64(value) {
+    const bytes = Buffer.alloc(8);
+    bytes.writeBigUInt64BE(BigInt(value));
+    return bytes;
+}
+/**
+ * Version 2: a domain and version tag, the file count, then per file in byte order of the path
+ * the length-prefixed UTF-8 path and the length-prefixed content. Every field has an explicit
+ * length, so two different trees never share an encoding.
+ */
+export function skillTreeFingerprint(files) {
+    const entries = files.map((file) => ({ path: Buffer.from(file.path, "utf8"), bytes: file.bytes }))
+        .sort((left, right) => Buffer.compare(left.path, right.path));
+    const hash = createHash("sha256").update(FINGERPRINT_DOMAIN, "utf8").update(uint32(entries.length));
+    entries.forEach((entry, index) => {
+        if (index > 0 && Buffer.compare(entries[index - 1].path, entry.path) === 0)
+            throw new SkillTreeError("skill_tree_invalid");
+        hash.update(uint32(entry.path.length)).update(entry.path).update(uint64(entry.bytes.length)).update(entry.bytes);
+    });
+    return `v2:${hash.digest("hex")}`;
+}
+/**
+ * Version 1, as 0.8.0 computed it: `path NUL content NUL` per file in reading order. File
+ * content may contain NUL bytes, so two different trees can share this value.
+ */
+export function legacySkillTreeFingerprint(files) {
+    const hash = createHash("sha256");
+    for (const file of files)
+        hash.update(file.path).update("\0").update(file.bytes).update("\0");
+    return hash.digest("hex");
+}
+/**
+ * The shipped skills of every release that recorded version 1 fingerprints (0.8.0 only), as
+ * trusted references for recognizing such records. Computed from the `v0.8.0` tag and checked
+ * against the published npm package.
+ */
+export const RELEASED_SKILL_TREES = Object.freeze([
+    Object.freeze({ name: "pi-session-orchestration", release: "0.8.0", legacyFingerprint: "e2a72b558ea14748a4badd0058ff65b8731cc125033a666706b103842784673a", fingerprint: "v2:39edc4c4783dec7f90345b22844a17e5e48b465722bb0f1b20059d6ee51e1523" }),
+    Object.freeze({ name: "pi-session-implementation", release: "0.8.0", legacyFingerprint: "5f719b44da266d3f66dd5bf3c18f3e3e04ca7df357e2fe2eedbf0409e6c1bf64", fingerprint: "v2:f8ce75eff83a5c952f6ca51c04e1e8025cb7c2c558c30d692f291a3f6594eb12" }),
+    Object.freeze({ name: "pi-session-review", release: "0.8.0", legacyFingerprint: "8cf58ccb8d473a3eedf12ce6b902b1e91dd9e2fef83ad110c4d8e2e6164cb257", fingerprint: "v2:610c0b4829eeb1ce6c9b2000ad73f8e88ca230707eef7f7b1708a80767952bf0" }),
+]);
+/**
+ * Whether a version 1 fingerprint from a record proves that `candidate` is the tree it names:
+ * a trusted reference, a released shipped tree of this name or one of `references` (such as
+ * the current library tree), has exactly this version 1 fingerprint and is byte-identical to
+ * `candidate` by its version 2 fingerprint. The version 1 fingerprint alone never suffices.
+ */
+export function provesLegacyFingerprint(name, legacyFingerprint, candidate, references = [], released = RELEASED_SKILL_TREES) {
+    if (!LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(legacyFingerprint) || !SKILL_TREE_FINGERPRINT_PATTERN.test(candidate.fingerprint))
+        return false;
+    const trusted = [...released.filter((tree) => tree.name === name), ...references];
+    return trusted.some((tree) => tree.legacyFingerprint === legacyFingerprint && tree.fingerprint === candidate.fingerprint);
+}
+/**
+ * The version 2 fingerprint of the released shipped skill that a version 1 fingerprint names,
+ * or undefined. Only released trees qualify: the current shipped tree could share a version 1
+ * fingerprint with an older original without being that original.
+ */
+export function releasedSkillFingerprint(name, legacyFingerprint, released = RELEASED_SKILL_TREES) {
+    return released.find((tree) => tree.name === name && tree.legacyFingerprint === legacyFingerprint)?.fingerprint;
+}
 /**
  * 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
@@ -113,8 +184,5 @@ export async function readSkillTree(directory, options = {}) {
     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") });
+    return Object.freeze({ files: Object.freeze(files), fingerprint: skillTreeFingerprint(files), legacyFingerprint: legacySkillTreeFingerprint(files) });
 }

package/CHANGELOG.md

@@ -2,6 +2,165 @@
 
 ## 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
+  of the last observed assistant message start, update or end and tool
+  execution start, update or end of that turn, and freezes at the terminal
+  transition. Before, it advanced only after a completed tool execution or a
+  completed assistant message, so a turn of an extension provider with its own
+  agent loop, such as `pi-cursor-sdk`, kept `updatedAt == startedAt` while it
+  streamed. Streaming is activity, not evidence of finished or useful work, and
+  work without a public event stays invisible, so an unchanged `updatedAt` is
+  still no proof of a hang. No event content is stored or projected, and the
+  answer still comes only from the final assistant message. See [tool
+  contracts](docs/tool-contracts.md). Issue #47.
+- Skill tree fingerprints are now version 2 (`v2:` and 64 hex digits), an
+  unambiguous encoding with explicit lengths. Version 1 of 0.8.0 hashed
+  `path NUL content NUL` and could give two different trees the same value,
+  because content may contain NUL bytes. A version 1 value never proves
+  identity alone: it counts only when a trusted reference (the shipped skills of
+  0.8.0, or for setup's installed copies the current library tree) has that
+  value and is byte-identical to the tree in question. Issue #51.
+- Skill customization is now serialized across processes. `--apply
+  --customize-skill` takes an exclusive kernel lock on
+  `<override dir>/.pi-session-mcp-bases.lock`, re-reads the bases file under the
+  lock and replaces it atomically, so two runs for different skills no longer
+  lose a base. The wait is bounded at 30 seconds. New codes:
+  `skill_customize_lock_busy` and `skill_customize_lock_unavailable`. The
+  dry-run takes no lock and writes nothing. The bases file is now schema version
+  2; version 1 files are still read, and every write migrates each legacy value
+  that names a released 0.8.0 shipped skill. New codes for a legacy base:
+  `skill_base_migration_planned` and `skill_base_migrated` (it names the current
+  shipped skill), and `skill_base_unverified` (it names no released skill; the
+  Doctor warning `skill_override_outdated` says that the base cannot be
+  confirmed). `skill_customize_planned` and `skill_customized` now also complete
+  a customization whose bases commit failed. See [Pi
+  skills](docs/skills.md#concurrent-runs-and-the-override-lock). Issue #50.
+- Setup's installed skill copies. Ownership records of skill copies now hold
+  version 2 fingerprints. A record that 0.8.0 wrote is migrated only when a
+  trusted reference proves the copy's exact bytes; otherwise dry-run, apply,
+  remove and rollback report the new code `skill_legacy_unverified` and change
+  neither the copy nor the record. Updates now name their intermediate
+  directories after the pending record's transaction id
+  (`.pi-session-mcp-<skill>-<transactionId>.staging`, `.backup`, `.trash`), and
+  `--apply`, `--remove` and `--rollback` first settle an interrupted update.
+  Anything modified or foreign stays and is reported as the new code
+  `skill_recovery_retained`. A failed update leaves its staging directory until
+  the next run settles it. Directories of 0.8.0 updates are never searched for
+  or deleted. When `--apply` settled an interrupted update and needs no further
+  update it reports the new code `skill_recovered`, and a dry-run of a pending
+  update reports `skill_recovery_planned`. Issues #51 and #52.
+- Upgrading from 0.8.0: run `pi-session-mcp-setup` as a dry-run and then with
+  `--apply`. Unchanged copies of the 0.8.0 controller skill are proven against
+  the 0.8.0 table and migrated; others stay and report
+  `skill_legacy_unverified`. Doctor resolves 0.8.0 bases against the same table,
+  and the next `--apply --customize-skill` rewrites the bases file as version 2.
+  0.8.0 rejects the new formats as corrupt (the bases file, and the whole
+  ownership file once it holds a version 2 skill record), so it never acts on
+  them. See [Upgrade from 0.8.0](docs/skills.md#upgrade-from-080) and
+  [Downgrade](docs/skills.md#downgrade).
+- The orchestration skill now says that a successful `pi_session_start` does not
+  prove that the provider accepts requests, asks for a bounded observation and
+  cleanup budget after `abort_timeout`, separates start errors that need the
+  operator from ones that can be transient, and describes `updatedAt` as the
+  last observed public SDK activity. `docs/acceptance.md` records the v0.8.0
+  post-release acceptance and names the method limits of earlier multi-session
+  records. Issue #54.
+- The multi-session acceptance harness (`scripts/multi-session-acceptance.mjs`,
+  not in the npm package) now ends a run within validated time bounds and
+  terminates only processes that provably belong to it (PID and start time). It
+  checks scope against a baseline stored outside the worker workspace (working
+  tree, index and HEAD, so committed changes count) and adds its own business
+  checks to the fixture tests, with Git pinned to the fixture and hooks,
+  `fsmonitor` and replace objects switched off. It binds the build, the
+  controller and worker skills, the override directory, the configuration, the
+  fixture baselines, itself and the operator's own `pi-session-orchestration`
+  copies in `~/.claude/skills` and `~/.agents/skills` at `prepare` and rechecks
+  them before launch and after the run; a Codex run is refused while the home
+  copy differs from the candidate's skill. It records each launch before the
+  controller starts, writes each original result once, records reanalyses
+  separately, and lists every launch in the evidence, marking one without a
+  result. A failed analysis, or a signal to the harness during it, is recorded
+  as `analysisFailed`, never passes, still terminates the run's processes and
+  makes the CLI exit with 1. `prepare --with-extensions` copies the exact
+  extension allowlist of a selected profile for extension providers such as
+  Cursor. Each session reports whether a polled running turn showed
+  `updatedAt` beyond `startedAt`. See
+  [Acceptance](docs/acceptance.md#multi-session-skill-acceptance). Issue #53.
+- A release now travels in the pull request of the change it ships, with the
+  version, the changelog heading and the pre-release acceptance record; records
+  that need the published release follow with the next change. See
+  [Releasing](docs/releasing.md#prepare-a-release).
+
 ## 0.8.0 — 2026-10-12
 
 This is a minor release because the public contract changes, as ADR 0003

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.0**.
+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/doctor.d.ts

@@ -1,5 +1,6 @@
 import { type AppConfig } from "./config.js";
 import { type ExtensionSpec } from "./extension-spec.js";
+import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
 export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "extension_missing" | "extension_version_mismatch" | "skill_missing" | "skill_unreadable" | "skill_duplicate" | "skill_override_outdated";
@@ -44,6 +45,8 @@ export interface DoctorDependencies {
     readonly packageMetadata?: () => Promise<DoctorPackageMetadata>;
     /** Reads the installed manifest of a pinned extension; never imports extension code. */
     readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
+    /** Reference trees that resolve legacy skill bases; defaults to the released shipped skills. */
+    readonly releasedSkillTrees?: readonly ReleasedSkillTree[];
 }
 export declare function runDoctor(dependencies?: DoctorDependencies): Promise<DoctorResult>;
 export declare function renderDoctorJson(result: DoctorResult): string;

package/dist/doctor.js

@@ -6,7 +6,7 @@ import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
 import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
 import { readSkillBases, SkillBasesError } from "./skill-customize.js";
-import { readSkillTree, shippedSkillsDirectory } from "./skill-library.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory } from "./skill-library.js";
 const defaultFileSystem = { readFile, stat, access };
 const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
@@ -67,9 +67,10 @@ async function productionBuildInputMtimes(root) {
 }
 /**
  * Compares the shipped skills with the fingerprints recorded when the operator copied them.
- * Reads only the bases file and the shipped files; nothing is executed or changed.
+ * Reads only the bases file and the shipped files, takes no lock and writes nothing: the bases
+ * file is replaced atomically, so a read sees either the old or the new content.
  */
-async function skillOverrideChecks(overrideDirectory, shippedDirectory) {
+async function skillOverrideChecks(overrideDirectory, shippedDirectory, released) {
     if (overrideDirectory === undefined)
         return [];
     let bases;
@@ -90,9 +91,15 @@ async function skillOverrideChecks(overrideDirectory, shippedDirectory) {
         catch {
             continue;
         }
-        checks.push(fingerprint === base
-            ? ok("skill_override_outdated", `skill:${name}`)
-            : warning("skill_override_outdated", `skill:${name}`, `review the changed shipped skill, then run pi-session-mcp-setup --apply --customize-skill ${name}`));
+        const command = `pi-session-mcp-setup --apply --customize-skill ${name}`;
+        // A legacy base is meaningful only as the version 2 value of the released original it names.
+        const recorded = LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(base) ? releasedSkillFingerprint(name, base, released) : base;
+        if (recorded === undefined)
+            checks.push(warning("skill_override_outdated", `skill:${name}`, `the recorded base predates version 2 fingerprints and cannot be confirmed; review the shipped skill, then run ${command}`));
+        else
+            checks.push(recorded === fingerprint
+                ? ok("skill_override_outdated", `skill:${name}`)
+                : warning("skill_override_outdated", `skill:${name}`, `review the changed shipped skill, then run ${command}`));
     }
     return checks;
 }
@@ -260,7 +267,7 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config)
-        checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot)));
+        checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
     checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
     const hasError = checks.some((check) => check.severity === "error");

package/dist/override-lock.d.ts

@@ -0,0 +1,34 @@
+import { type StatfsReader } from "./setup-platform.js";
+/**
+ * The kernel lock that serializes every read-modify-write of the skill bases file across
+ * processes. It lives on a stable lock file, never on the bases file: that file is replaced by a
+ * rename, which would move the lock onto an unlinked inode. The lock file is never deleted, and a
+ * holder that dies releases the lock through the kernel.
+ */
+export declare const SKILL_BASES_LOCK_FILE = ".pi-session-mcp-bases.lock";
+export declare const DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS = 30000;
+export declare class OverrideLockError extends Error {
+    readonly code: "override_lock_busy" | "override_lock_unavailable";
+    constructor(code: "override_lock_busy" | "override_lock_unavailable");
+}
+export interface OverrideLockOptions {
+    /** Acquisition bound; a busy lock after this fails with `override_lock_busy`. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Test seams for the platform gate; the defaults describe this process. */
+    readonly platform?: NodeJS.Platform;
+    readonly flockCandidates?: readonly string[];
+    readonly isTrustedBinary?: (path: string) => boolean;
+    readonly readStatfs?: StatfsReader;
+}
+export interface OverrideLock {
+    /** Closes the descriptor that holds the lock; safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * Takes the exclusive lock for one override directory, which must exist. Fails closed: an
+ * unsupported platform, a missing trusted `flock`, an unsupported filesystem, a link or non-file
+ * at the lock path and a descriptor that no longer names the path all end in
+ * `override_lock_unavailable`.
+ */
+export declare function acquireOverrideLock(overrideDirectory: string, options?: OverrideLockOptions): Promise<OverrideLock>;

package/dist/override-lock.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSupportedFilesystem, currentSetupPlatform, isTrustedSystemBinary, openLockedDarwin } from "./setup-platform.js";
+/**
+ * The kernel lock that serializes every read-modify-write of the skill bases file across
+ * processes. It lives on a stable lock file, never on the bases file: that file is replaced by a
+ * rename, which would move the lock onto an unlinked inode. The lock file is never deleted, and a
+ * holder that dies releases the lock through the kernel.
+ */
+export const SKILL_BASES_LOCK_FILE = ".pi-session-mcp-bases.lock";
+export const DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS = 30_000;
+const MIN_LOCK_TIMEOUT_MS = 50;
+const MAX_LOCK_TIMEOUT_MS = 120_000;
+/** Exit status of `flock -E` when the lock stayed busy for the whole wait. */
+const FLOCK_BUSY_EXIT = 75;
+const FLOCK_CANDIDATES = ["/usr/bin/flock", "/bin/flock"];
+export class OverrideLockError extends Error {
+    code;
+    constructor(code) {
+        super("Skill override lock is not available");
+        this.code = code;
+        this.name = "OverrideLockError";
+    }
+}
+/**
+ * Takes the exclusive lock for one override directory, which must exist. Fails closed: an
+ * unsupported platform, a missing trusted `flock`, an unsupported filesystem, a link or non-file
+ * at the lock path and a descriptor that no longer names the path all end in
+ * `override_lock_unavailable`.
+ */
+export async function acquireOverrideLock(overrideDirectory, options = {}) {
+    const platform = currentSetupPlatform(options.platform);
+    if (!platform)
+        throw new OverrideLockError("override_lock_unavailable");
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(MIN_LOCK_TIMEOUT_MS, Math.min(options.timeoutMs, MAX_LOCK_TIMEOUT_MS)) : DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS;
+    const flockPath = platform === "linux" ? flockBinary(options) : undefined;
+    if (platform === "linux" && flockPath === undefined)
+        throw new OverrideLockError("override_lock_unavailable");
+    try {
+        await assertSupportedFilesystem(overrideDirectory, platform, options.readStatfs);
+    }
+    catch {
+        throw new OverrideLockError("override_lock_unavailable");
+    }
+    const lockPath = join(overrideDirectory, SKILL_BASES_LOCK_FILE);
+    let handle;
+    try {
+        // macOS takes the kernel lock at open time; on Linux the trusted flock locks this very
+        // open file description, so the lock outlives the flock process and ends with this descriptor.
+        handle = await openLockFile(lockPath, platform, timeoutMs, options.signal);
+        if (flockPath !== undefined)
+            await lockWithFlock(flockPath, handle.fd, timeoutMs, options.signal);
+        // The path may have been replaced while waiting: the lock only counts on the file it names.
+        const [descriptor, linked] = await Promise.all([handle.stat(), lstat(lockPath)]);
+        if (!descriptor.isFile() || !linked.isFile() || descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+            throw new OverrideLockError("override_lock_unavailable");
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw error instanceof OverrideLockError ? error : new OverrideLockError("override_lock_unavailable");
+    }
+    const held = handle;
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await held.close().catch(() => undefined);
+        },
+    };
+}
+function flockBinary(options) {
+    const trusted = options.isTrustedBinary ?? ((path) => isTrustedSystemBinary(path));
+    return (options.flockCandidates ?? FLOCK_CANDIDATES).find((candidate) => trusted(candidate));
+}
+async function openLockFile(lockPath, platform, timeoutMs, signal) {
+    try {
+        if (platform === "darwin")
+            return await openLockedDarwin(lockPath, { timeoutMs, ...(signal ? { signal } : {}) });
+        return await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        throw new OverrideLockError(error.message === "ownership_lock_busy" ? "override_lock_busy" : "override_lock_unavailable");
+    }
+}
+function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new OverrideLockError("override_lock_unavailable"));
+            return;
+        }
+        let locker;
+        try {
+            // flock parses fractional seconds with the locale's decimal separator, so only whole
+            // seconds go on the command line. The exact bound is the timer below, which stops flock.
+            const wholeSeconds = String(Math.max(1, Math.ceil(timeoutMs / 1_000)));
+            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), "-w", wholeSeconds, "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
+        }
+        catch {
+            reject(new OverrideLockError("override_lock_unavailable"));
+            return;
+        }
+        let expired = false;
+        const stop = () => { if (locker.pid !== undefined) {
+            try {
+                process.kill(-locker.pid, "SIGKILL");
+            }
+            catch { /* already gone */ }
+        } };
+        const cleanup = () => { clearTimeout(bound); signal?.removeEventListener("abort", stop); };
+        const bound = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+        signal?.addEventListener("abort", stop, { once: true });
+        locker.once("error", () => { cleanup(); reject(new OverrideLockError("override_lock_unavailable")); });
+        locker.once("close", (code) => {
+            cleanup();
+            if (code === 0)
+                resolve();
+            else
+                reject(new OverrideLockError(code === FLOCK_BUSY_EXIT || expired ? "override_lock_busy" : "override_lock_unavailable"));
+        });
+    });
+}

package/dist/pi-adapter.d.ts

@@ -23,10 +23,12 @@ export interface PiSessionHandle {
     /** Only whitelisted, post-verified selection metadata may cross the adapter boundary. */
     readonly appliedSelection: PiAppliedSelection;
     /**
-     * `onActivity` is an optional content-free liveness callback, invoked after a completed
-     * tool execution and after a completed assistant message. It receives no event payload
-     * and must only be used for timestamping; it never carries tool names, arguments,
-     * results, text, paths, or credentials.
+     * `onActivity` is an optional content-free liveness callback, invoked on observed public
+     * SDK activity of the running prompt: assistant message start, update and end, and tool
+     * execution start, update and end. Streaming is activity, not evidence of finished or
+     * useful work, and internal work without a public event stays invisible. It receives no
+     * event payload and must only be used for timestamping; it never carries tool names,
+     * arguments, results, text, paths, or credentials.
      */
     prompt(text: string, preflight: (accepted: boolean) => void, onActivity?: () => void): Promise<PiTurnOutcome>;
     abort(): Promise<void>;

package/dist/sdk-pi-adapter.js

@@ -192,12 +192,31 @@ class SdkHandle {
             }
             catch { /* Liveness reporting is best effort and content-free. */ }
         };
+        // Activity is the public SDK stream of this prompt: assistant message start, update and end, and
+        // tool execution start, update and end. Only the event discriminant and the message role are
+        // inspected: delta text, thinking, tool arguments and partial results are never read, stored or
+        // forwarded. Streaming is activity, not evidence of finished work; only the last assistant
+        // `message_end` is the answer, and the terminal state comes from the completion paths below.
         const unsubscribe = this.session.subscribe((event) => {
-            if (event.type === "tool_execution_end")
-                reportActivity();
-            else if (event.type === "message_end" && isAssistantMessage(event.message)) {
-                finalAssistant = event.message;
-                reportActivity();
+            switch (event.type) {
+                case "tool_execution_start":
+                case "tool_execution_update":
+                case "tool_execution_end":
+                    reportActivity();
+                    break;
+                case "message_start":
+                case "message_update":
+                    if (hasAssistantRole(event.message))
+                        reportActivity();
+                    break;
+                case "message_end":
+                    if (isAssistantMessage(event.message)) {
+                        finalAssistant = event.message;
+                        reportActivity();
+                    }
+                    break;
+                default:
+                    break;
             }
         });
         let preflightSeen = false;
@@ -264,6 +283,10 @@ function isAssistantMessage(message) {
     const candidate = message;
     return candidate.role === "assistant" && Array.isArray(candidate.content);
 }
+/** Role check only: streaming messages are never inspected for content. */
+function hasAssistantRole(message) {
+    return typeof message === "object" && message !== null && message.role === "assistant";
+}
 function isTextBlock(block) {
     if (!block || typeof block !== "object")
         return false;

package/dist/session-registry.d.ts

@@ -16,10 +16,11 @@ export interface SessionView {
     lastError?: string;
 }
 /**
- * `updatedAt` is the registry's own last-activity stamp: while a turn runs it advances on a
- * completed tool execution or completed assistant message, then freezes at the terminal
- * transition. It is a liveness lower bound, not a progress count, and does not prove that a
- * silent turn is healthy.
+ * `updatedAt` is the time of the last observed public SDK activity of the turn (assistant
+ * message start, update and end; tool execution start, update and end), then freezes at the
+ * terminal transition. Streaming is activity, not evidence of finished or useful work, and
+ * internal work without a public event stays invisible. It is a liveness lower bound, not a
+ * progress count, and does not prove that a silent turn is healthy.
  */
 export interface TurnView {
     turnId: string;
@@ -81,8 +82,9 @@ export declare class SessionRegistry {
     private completeTurn;
     private failTurn;
     /**
-     * Liveness only. A completed tool execution or assistant message advances this turn,
-     * never another turn or the session. Activity after accepted preflight but before
+     * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
+     * execution start, update and end) advances this turn, never another turn or the session.
+     * Streaming is activity, not evidence of finished or useful work. Activity after accepted preflight but before
      * publication is stamped and applied only if the turn is published; callbacks before
      * acceptance or after terminal cleanup cannot publish or revive a turn.
      */

package/dist/session-registry.js

@@ -273,8 +273,9 @@ export class SessionRegistry {
         entry.turn = undefined; if (entry.turnPromise)
         entry.turnPromise = undefined; entry.state = "failed"; entry.updatedAt = turn.updatedAt; entry.lastError = "Pi turn failed"; }
     /**
-     * Liveness only. A completed tool execution or assistant message advances this turn,
-     * never another turn or the session. Activity after accepted preflight but before
+     * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
+     * execution start, update and end) advances this turn, never another turn or the session.
+     * Streaming is activity, not evidence of finished or useful work. Activity after accepted preflight but before
      * publication is stamped and applied only if the turn is published; callbacks before
      * acceptance or after terminal cleanup cannot publish or revive a turn.
      */