@fitchmultz/pi-subagents 0.52.18 → 0.52.19

package/dist/pi-intercom/lifecycle.js

@@ -8,12 +8,8 @@ export function isContextRequest(value) {
 }
 /** Owns native context validity and occupancy, never journal or socket state. */
 export class IntercomLifecycle {
-    context = null;
-    sessionId = null;
+    state = { kind: "inactive", epoch: 0 };
     model = "unknown";
-    disposed = true;
-    epoch = 0;
-    incarnation = null;
     peerId = null;
     guardedDelivery = false;
     applicationGuard;
@@ -29,10 +25,10 @@ export class IntercomLifecycle {
         this.lineage = lineage;
     }
     get generation() {
-        return this.epoch;
+        return this.state.epoch;
     }
     get currentSessionId() {
-        return this.sessionId;
+        return this.state.kind === "inactive" ? null : this.state.sessionId;
     }
     get toolCount() {
         return this.tools.size;
@@ -64,7 +60,7 @@ export class IntercomLifecycle {
         request.respond(this.snapshot());
     }
     snapshot() {
-        if (!this.live()) {
+        if (this.state.kind !== "live" || !this.live()) {
             return {
                 version: 1,
                 rootSessionId: null,
@@ -76,10 +72,10 @@ export class IntercomLifecycle {
         }
         return {
             version: 1,
-            rootSessionId: this.lineage?.rootSessionId ?? this.sessionId,
+            rootSessionId: this.lineage?.rootSessionId ?? this.state.sessionId,
             parentSessionId: this.lineage?.parentSessionId,
             peerId: this.peerId,
-            incarnation: this.incarnation,
+            incarnation: this.state.incarnation,
             connected: this.peerId !== null,
             guardedDelivery: this.guardedDelivery ? 1 : null,
             applicationGuard: this.applicationGuard,
@@ -107,36 +103,40 @@ export class IntercomLifecycle {
             this.applicationGuard === guard.applicationGuard);
     }
     start(ctx) {
-        this.disposed = false;
-        this.epoch += 1;
-        this.context = ctx;
-        this.sessionId = ctx.sessionManager.getSessionId();
-        this.incarnation = randomUUID();
+        this.state = {
+            kind: "live",
+            epoch: this.state.epoch + 1,
+            context: ctx,
+            sessionId: ctx.sessionManager.getSessionId(),
+            incarnation: randomUUID(),
+        };
         this.applicationGuard = undefined;
         this.model = ctx.model?.id ?? "unknown";
         this.running = false;
         this.activity = 0;
         this.tools.clear();
         this.transport(null);
-        return this.epoch;
+        return this.state.epoch;
     }
     invalidate() {
-        this.disposed = true;
-        this.epoch += 1;
+        const epoch = this.state.epoch + 1;
+        this.state =
+            this.state.kind === "inactive"
+                ? { kind: "inactive", epoch }
+                : { kind: "invalidated", epoch, sessionId: this.state.sessionId };
         this.running = false;
         this.tools.clear();
         this.publishContext();
     }
     clear() {
-        this.context = null;
-        this.sessionId = null;
+        this.state = { kind: "inactive", epoch: this.state.epoch };
     }
-    live(ctx = this.context, generation = this.epoch) {
-        if (this.disposed || generation !== this.epoch || !ctx) {
+    live(ctx = this.state.kind === "live" ? this.state.context : null, generation = this.state.epoch) {
+        if (this.state.kind !== "live" || generation !== this.state.epoch || !ctx) {
             return null;
         }
         try {
-            if (this.sessionId !== null && ctx.sessionManager.getSessionId() !== this.sessionId) {
+            if (ctx.sessionManager.getSessionId() !== this.state.sessionId) {
                 return null;
             }
             // Reading a native property detects invalidated contexts without modifying them.
@@ -209,12 +209,12 @@ export class IntercomLifecycle {
     }
     async registration(pendingAsks) {
         const live = this.live();
-        if (!live || this.sessionId === null) {
+        if (!live || this.state.kind !== "live") {
             throw new Error("Intercom runtime not initialized");
         }
         return {
-            ...this.identity(this.sessionId),
-            incarnation: this.incarnation ?? undefined,
+            ...this.identity(this.state.sessionId),
+            incarnation: this.state.incarnation,
             guardedDelivery: 1,
             applicationGuard: this.applicationGuard,
             cwd: live.cwd,

package/dist/shared/post-exit-stdio-guard.js

@@ -280,12 +280,13 @@ export function attachChildProcessLifecycle(child) {
     return new OwnedChildLifecycle(child);
 }
 function attachPostExitStdioGuard(child) {
-    let exited = false;
+    let state = { kind: "waiting" };
     let stdoutEnded = false;
     let stderrEnded = false;
-    let idleTimer;
-    let hardTimer;
     const destroyUnendedStdio = () => {
+        if (state.kind !== "draining") {
+            return;
+        }
         if (!stdoutEnded) {
             try {
                 child.stdout?.destroy();
@@ -302,51 +303,57 @@ function attachPostExitStdioGuard(child) {
                 // The process has exited; failed pipe destruction must not prevent other cleanup.
             }
         }
-    };
-    const clearTimers = () => {
-        if (idleTimer) {
-            clearTimeout(idleTimer);
-            idleTimer = undefined;
-        }
-        if (hardTimer) {
-            clearTimeout(hardTimer);
-            hardTimer = undefined;
-        }
+        cleanup();
     };
     const armIdleTimer = () => {
-        if (!exited) {
+        if (state.kind !== "draining") {
             return;
         }
-        if (idleTimer) {
-            clearTimeout(idleTimer);
-        }
-        idleTimer = setTimeout(destroyUnendedStdio, 2000);
-        idleTimer.unref();
+        clearTimeout(state.idle);
+        state.idle = setTimeout(destroyUnendedStdio, 2000);
+        state.idle.unref();
     };
-    child.stdout?.on("data", armIdleTimer);
-    child.stderr?.on("data", armIdleTimer);
-    child.stdout?.on("end", () => {
+    const stdoutEnd = () => {
         stdoutEnded = true;
         if (stderrEnded) {
-            clearTimers();
+            cleanup();
         }
-    });
-    child.stderr?.on("end", () => {
+    };
+    const stderrEnd = () => {
         stderrEnded = true;
         if (stdoutEnded) {
-            clearTimers();
+            cleanup();
         }
-    });
-    child.on("exit", () => {
-        exited = true;
-        armIdleTimer();
-        if (hardTimer) {
+    };
+    const exited = () => {
+        if (state.kind !== "waiting") {
             return;
         }
-        hardTimer = setTimeout(destroyUnendedStdio, 8000);
-        hardTimer.unref();
-    });
-    child.on("close", clearTimers);
-    child.on("error", clearTimers);
-    return clearTimers;
+        const hard = setTimeout(destroyUnendedStdio, 8000);
+        hard.unref();
+        state = { kind: "draining", idle: undefined, hard };
+        armIdleTimer();
+    };
+    function cleanup() {
+        if (state.kind === "draining") {
+            clearTimeout(state.idle);
+            clearTimeout(state.hard);
+        }
+        state = { kind: "closed" };
+        child.stdout?.off("data", armIdleTimer);
+        child.stderr?.off("data", armIdleTimer);
+        child.stdout?.off("end", stdoutEnd);
+        child.stderr?.off("end", stderrEnd);
+        child.off("exit", exited);
+        child.off("close", cleanup);
+        child.off("error", cleanup);
+    }
+    child.stdout?.on("data", armIdleTimer);
+    child.stderr?.on("data", armIdleTimer);
+    child.stdout?.on("end", stdoutEnd);
+    child.stderr?.on("end", stderrEnd);
+    child.on("exit", exited);
+    child.on("close", cleanup);
+    child.on("error", cleanup);
+    return cleanup;
 }

package/docs/development.md

@@ -23,6 +23,12 @@ Run narrow owner-boundary tests locally through `scripts/run-tests.mjs`. Full
 `npm run ci` belongs in hosted CI and includes package/install smokes and the
 complete suites. Keep the strict Oxlint/Oxfmt rules; see [code quality](code-quality.md).
 
+Builds compile into process-owned staging before replacing `dist`. If a publisher
+exits after retiring the previous build, later builds preserve its complete
+`.previous` tree until a new complete build publishes. A failed build reports
+the retained recovery paths. Recovery never promotes an older backup into a
+concurrent publisher's retirement gap or reaps live or uncertain owners.
+
 ## Native Android/Termux
 
 Use app-private storage, not Android's shared `/sdcard` filesystem. No Termux app
@@ -80,6 +86,25 @@ npm and attached to the matching GitHub release.
 
 ## Isolation and safety
 
+Parent attachment keeps one binding through detached, waiting, attaching and
+attached phases. The existing shutdown signal closes the owner. Managed
+readiness can attach only its own still-current waiting binding; shutdown joins
+admitted publication before releasing the matching generation.
+
+Parking returns resident, exit-with-parked-authority or exit-after-failed-save.
+Both exit outcomes have disposed the native runtime and must exit the actor;
+neither permits a second ordinary disposal. Restore tracks unopened, opening
+and adopted phases, keeping the exact saved cut with the phase that owns it.
+
+Directory watches distinguish unarmed, armed-to-one-inode and polling-only
+availability. Missing paths can be armed later; unsupported or failed native
+watches keep the existing polling fallback. Each coalesced Wake has one waiting
+owner loop.
+
+Smoke child cleanup treats leader exit and pipe closure separately. Pipe draining
+has waiting, draining and closed phases. Closing it cancels its deadlines and
+detaches its listeners, so later events cannot restart cleanup.
+
 Every test/smoke broker uses a short, explicit `PI_INTERCOM_RUNTIME_DIR` owned by
 the fixture. Do not touch `/tmp/pi-intercom-<uid>` to test namespace behavior on a
 workstation with active sessions. Tests for the default path inspect it without

package/docs/intercom.md

@@ -341,6 +341,9 @@ tool to give up the turn.
 
 Shutdown joins admitted inbound work before detaching its native owner. Stale
 runtime generations must not checkpoint or deliver into a replacement session.
+Context state is inactive, live with its session and incarnation, or invalidated
+while transport cleanup retains the session ID. Clearing cleanup drops that ID;
+transport connection and native tool activity remain separate from context validity.
 The native tests own these contracts; neither a timer nor a source-string test is
 publication evidence.
 
@@ -396,4 +399,14 @@ records include native boot/namespace/start identity to reject proven PID reuse;
 ambiguous legacy numeric PIDs remain blocking. A process is never killed merely
 to recover broker startup.
 
+Startup distinguishes absent, live and uncertain ownership. An unreadable or
+invalid PID record is uncertain, not permission to launch another broker.
+A startup claim stays owned while its process is live, regardless of age.
+Only a proven exited or replaced owner permits reclaiming it. Linux claims carry
+the same native process identity as broker PID records. Legacy or incomparable
+identities remain blocking; a timestamp alone cannot prove PID reuse.
+Each starter keeps the claim's
+file descriptor open and releases only the same device/inode, leaving a
+replacement claim untouched.
+
 Remote authenticated mail is separate: see [bridge setup](intercom-bridge.md).

package/docs/reference.md

@@ -12,6 +12,7 @@ delegate({
   name: "optional-readable-name",
   cwd: "/optional/working/directory",
   model: "provider/model",
+  thinking: "low",
   context: "fresh",
 });
 ```
@@ -21,19 +22,27 @@ canned profile. `name` is an optional display name, not a unique identity or rol
 Omitted cwd/model inherit the invoking session's effective selection. A supplied
 model must be available; there is no hidden alternate-model retry catalog.
 
+`thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
+It overrides parent effort for this child without changing the parent. It works
+with an omitted model or a literal model ID on every supported host, including
+official Pi 1.5.0. Omission preserves inherited effort. Pi applies its native
+model-capability clamping; the launch receipt records the requested value, not
+proof of the child's effective effort.
+
 On hosts exporting Pi's native `resolveModelReference`, `model` also accepts
 `provider/model:thinking` (for example `provider/model:low` or `provider/model:off`).
-The explicit suffix overrides inherited thinking for that child only. Literal
+The explicit suffix overrides inherited thinking for that child only. If both
+`thinking` and a suffix specify effort, they must match or the launch fails. Literal
 model IDs take precedence, including IDs containing colons or additional slashes;
 unknown IDs and invalid suffixes fail without fuzzy matching or another provider.
 Native resolution follows Pi's case-insensitive ID matching. Pi still applies the
 selected model's native thinking capabilities.
 
 Official Pi, including 1.5.0, does not export that resolver. Older fork runtimes also
-lack the export. Those hosts retain
-case-sensitive literal-ID overrides and inherited thinking; suffix requests fail with an upgrade
-message rather than being parsed by an extension-side replacement. This requires
-a host with the public resolver export, not merely a matching version number.
+lack the export. Those hosts retain case-sensitive literal-ID overrides and
+support the `thinking` field. Suffix requests fail with an upgrade message rather
+than being parsed by an extension-side replacement. Suffix support requires a
+host with the public resolver export, not merely a matching version number.
 
 Fresh context is the default. Fork uses the native conversation, including
 historical tool calls and results; restricting a child's authority does not erase
@@ -58,6 +67,8 @@ tool or programmatic invocation of `delegate` or `agent_runs`.
 
 Saved runs belong to the native main session that launched them, not its cwd,
 project, display name, or a different session forked from its history.
+Live guidance and saved-run successors keep the child's saved effort even if the
+parent's effort has changed.
 
 | Action     | Purpose                                                                              |
 | ---------- | ------------------------------------------------------------------------------------ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.18",
+  "version": "0.52.19",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/build.mjs

@@ -67,21 +67,37 @@ async function hasPublishedDist(/** @type {string} */ path) {
   }
 }
 
-async function reapStrandedStaging(/** @type {string} */ cwd) {
+/**
+ * @param {string} cwd
+ * @param {import("node:fs").Dirent} entry
+ * @returns {{ path: string, kind: "staging" | "previous" } | undefined}
+ */
+function strandedBuild(cwd, entry) {
   // Signal 0 proves only that the owner was gone at probe time. Pid reuse
   // between this probe and removal is inherent to pid-based reaping.
-  for (const entry of await readdir(cwd, { withFileTypes: true })) {
-    const match = /^dist\.staging\.(\d+)(?:\.previous)?$/.exec(entry.name);
-    if (!match || !entry.isDirectory()) {
-      continue;
-    }
-    const ownerPid = Number(match[1]);
-    if (ownerPid === process.pid || !isOwnerGone(ownerPid)) {
-      continue;
+  const match = /^dist\.staging\.(\d+)(\.previous)?$/.exec(entry.name);
+  if (!match || !entry.isDirectory()) {
+    return;
+  }
+  const ownerPid = Number(match[1]);
+  if (ownerPid === process.pid || !isOwnerGone(ownerPid)) {
+    return;
+  }
+  return { path: join(cwd, entry.name), kind: match[2] === undefined ? "staging" : "previous" };
+}
+
+async function reapStrandedBuilds(/** @type {string} */ cwd) {
+  const stranded = (await readdir(cwd, { withFileTypes: true })).flatMap((entry) => {
+    const build = strandedBuild(cwd, entry);
+    return build ? [build] : [];
+  });
+  for (const entry of stranded) {
+    if (entry.kind === "staging") {
+      await discardStaging(entry.path);
     }
-    // Reap abandoned trees sequentially to bound filesystem removal pressure.
-    await discardStaging(join(cwd, entry.name));
   }
+  // Never promote rollback material into another live publisher's retirement gap.
+  return stranded.filter((entry) => entry.kind === "previous").map((entry) => entry.path);
 }
 
 async function compileProject(
@@ -208,13 +224,24 @@ async function publishStaging(/** @type {string} */ stagingDir, /** @type {strin
 async function main() {
   const cwd = process.cwd();
   const compiler = compilerInvocation(process.argv[2]);
-  await reapStrandedStaging(cwd);
+  const previous = await reapStrandedBuilds(cwd);
   // Pid-scoped staging isolates concurrent emits; only a complete tree publishes.
   const stagingDir = join(cwd, `dist.staging.${process.pid}`);
   await rm(stagingDir, RM_OPTIONS);
   await rm(`${stagingDir}.previous`, RM_OPTIONS);
-  await compileToStaging(cwd, stagingDir, compiler);
-  await publishStaging(stagingDir, join(cwd, "dist"));
+  try {
+    await compileToStaging(cwd, stagingDir, compiler);
+    await publishStaging(stagingDir, join(cwd, "dist"));
+  } catch (error) {
+    for (const retained of previous.filter(existsSync)) {
+      console.warn(`Previous build retained for recovery: ${retained}`);
+    }
+    throw error;
+  }
+  // A complete published winner now replaces these older rollback candidates.
+  for (const retired of previous) {
+    await discardStaging(retired);
+  }
 }
 
 main().catch((/** @type {unknown} */ error) => {

package/skills/pi-subagents/SKILL.md

@@ -14,6 +14,7 @@ profile discovery, loader, role body, chain DSL, or nested delegation.
 delegate({
   prompt: "Complete assignment with constraints and expected output",
   name: "short-name",
+  thinking: "low",
 });
 ```
 
@@ -23,12 +24,14 @@ expected result, and stop boundary. Do not rely on a hidden profile to add them.
 
 Fresh context is default; `context:"fork"` preserves the native conversation,
 including prior tool results. A forked child still cannot delegate. Optional
-`cwd` and `model` are explicit launch overrides; do not change global auth/model
-settings to implement an override.
+`cwd`, `model`, and `thinking` are explicit launch overrides; do not change global
+auth/model settings to implement an override. `thinking` accepts `off`, `minimal`,
+`low`, `medium`, `high`, `xhigh`, or `max`. Omit it to inherit the parent's effort.
+Pi clamps the child's effort to its model capabilities without changing the parent.
 `model:"provider/model:thinking"` uses Pi's native suffix resolver when the host
 exports it; a literal model ID wins before suffix parsing. Without that host API,
-use a literal ID with inherited thinking or upgrade Pi. Never retry another model
-silently.
+use `thinking` with an omitted model or literal ID. If both the field and a native
+suffix supply effort, they must match. Never retry another model silently.
 
 Every launch, continuation and guidance call returns a receipt; no tool waits for
 child completion. Continue useful independent work; when child evidence gates the
@@ -45,6 +48,7 @@ invocation exits after its final turn and stops any remaining children.
 - `inspect` reads a run by ID; follow returned offsets for complete output.
 - `continue` takes a complete follow-up `prompt` and keeps the saved child chat.
   Active work receives guidance; completed work gets an immutable successor.
+  Both keep the child's saved effort, independent of later parent changes.
 - `stop` requests termination. Inspect actual process evidence; request acceptance
   does not prove actor or command exit.
 

package/src/agent/contracts.ts

@@ -93,6 +93,23 @@ export const resultSchema = Type.Object({
   ),
 });
 export type Result = Static<typeof resultSchema>;
+export type AccountingState =
+  | { readonly kind: "unrecorded"; readonly terminalEntryId: string | undefined }
+  | {
+      readonly kind: "verified";
+      readonly contributions: Contribution[];
+      readonly terminalEntryId: string | undefined;
+    }
+  | {
+      readonly kind: "pending";
+      readonly pending: NonNullable<Result["accountingPending"]>;
+      readonly error: string | undefined;
+    }
+  | {
+      readonly kind: "unavailable";
+      readonly error: string;
+      readonly terminalEntryId: string | undefined;
+    };
 export const commandSchema = Type.Object({
   id: Type.String(),
   runId: Type.String(),

package/src/agent/host.ts

@@ -9,6 +9,25 @@ import { readIntercomLineage } from "../pi-intercom/identity.ts";
 
 export { errorMessage as errorText } from "../shared/unknown.ts";
 
+/** Native fork lifetime owner; structural detection keeps official Pi supported. */
+export interface ManagedHost {
+  readonly owner: { readonly pid: number };
+  readonly ready: Promise<boolean>;
+}
+export function managedHost(context: SDK.ExtensionContext): ManagedHost | undefined {
+  const host: unknown = Reflect.get(context, "managedHost");
+  if (typeof host !== "object" || host === null) {
+    return undefined;
+  }
+  const owner: unknown = Reflect.get(host, "owner");
+  const pid: unknown =
+    typeof owner === "object" && owner !== null ? Reflect.get(owner, "pid") : undefined;
+  const ready: unknown = Reflect.get(host, "ready");
+  return typeof pid === "number" && Number.isSafeInteger(pid) && ready instanceof Promise
+    ? { owner: { pid }, ready: ready.then((accepted) => accepted === true) }
+    : undefined;
+}
+
 /** A launcher may still own children while handing off or replacing a worker. */
 export function retainsChildren(event: object): boolean {
   const disposition: unknown = Reflect.get(event, "disposition");