@fitchmultz/pi-subagents 0.52.18 → 0.52.20

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.20",
   "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");

package/src/agent/index.ts

@@ -17,7 +17,14 @@ import {
   signalProcess,
 } from "./process.ts";
 import { stopChildren } from "./shutdown.ts";
-import { isChild, errorText, rememberSDK, retainsChildren } from "./host.ts";
+import {
+  isChild,
+  errorText,
+  managedHost,
+  rememberSDK,
+  retainsChildren,
+  type ManagedHost,
+} from "./host.ts";
 import { serveParked } from "./parking.ts";
 import {
   resultSchema,
@@ -54,24 +61,20 @@ import { getPiAgentDir } from "../pi-intercom/agent-dir.ts";
 import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.ts";
 import { BackgroundReporter } from "../shared/background-reporting.ts";
 
-/** Native fork lifetime owner (`ctx.managedHost`); read structurally so official Pi stays supported. */
-interface ManagedHost {
-  readonly owner: { readonly pid: number };
-  readonly ready: Promise<boolean>;
-}
-function managedHost(context: 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;
+interface AttachmentBinding {
+  readonly context: ExtensionContext;
+  readonly owner: string;
+  readonly base: string;
+  readonly host: ManagedHost | undefined;
 }
+type AttachmentState =
+  | { readonly kind: "detached" }
+  | { readonly kind: "waiting"; readonly binding: AttachmentBinding }
+  | {
+      readonly kind: "attaching" | "attached";
+      readonly binding: AttachmentBinding;
+      readonly generation: string;
+    };
 
 /** Legacy results are optional; their reconciliation reports an invalid configured root. */
 function legacyInput(): string[] {
@@ -82,14 +85,8 @@ function legacyInput(): string[] {
   }
 }
 class AgentRuntime {
-  private ctx?: ExtensionContext | undefined;
+  private attachment: AttachmentState = { kind: "detached" };
   private readonly reporter = new BackgroundReporter(() => this.ctx);
-  // A managed launcher owns children across worker replacement; otherwise this process does.
-  private host?: ManagedHost | undefined;
-  private accepted = false;
-  private base = "";
-  private owner = "";
-  private generation = "";
   // Polling remains only while change hints are unavailable or a reconciliation failed.
   private timer?: NodeJS.Timeout;
   private woken?: NodeJS.Immediate | undefined;
@@ -99,7 +96,6 @@ class AgentRuntime {
   // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
   private observed = new Map<string, string>();
   private probe?: NodeJS.Timeout;
-  private closing = false;
   private reset: Promise<void> = Promise.resolve();
   private readonly shutdown = new AbortController();
   private readonly child = isChild();
@@ -109,11 +105,28 @@ class AgentRuntime {
     this.pi = pi;
     this.watches = new CompletionWatches(this.reporter, this.wake);
   }
+  private get binding(): AttachmentBinding {
+    if (this.attachment.kind === "detached") {
+      throw new Error("Agent runtime is not attached.");
+    }
+    return this.attachment.binding;
+  }
+  private get ctx(): ExtensionContext | undefined {
+    return this.attachment.kind === "attaching" || this.attachment.kind === "attached"
+      ? this.attachment.binding.context
+      : undefined;
+  }
+  private get base(): string {
+    return this.binding.base;
+  }
+  private get owner(): string {
+    return this.binding.owner;
+  }
   private checkMain(): void {
     if (isChild()) {
       throw new Error("Only a main session may delegate or control agent runs.");
     }
-    if (this.closing || !this.ctx || this.base.length === 0) {
+    if (this.shutdown.signal.aborted || this.attachment.kind !== "attached") {
       throw new Error("Agent runtime is not attached.");
     }
   }
@@ -133,17 +146,18 @@ class AgentRuntime {
   };
   private readonly scan = (): void => {
     clearTimeout(this.timer);
-    if (this.closing || !this.ctx || this.child) {
+    if (this.shutdown.signal.aborted || this.attachment.kind !== "attached" || this.child) {
       return;
     }
+    const { context } = this.attachment.binding;
     const inputs = () => [this.base, ...legacyInput(), ...this.awaited];
     const before = new Map(inputs().map((file) => [file, pathStamp(file)]));
     let reconciled = true;
     try {
-      const { notices, awaited } = notifications(this.ctx, this.base, this.owner);
+      const { notices, awaited } = notifications(context, this.base, this.owner);
       this.awaited = awaited;
-      notices.unshift(...reconcileLegacy(this.ctx, this.reporter));
-      deliver(this.pi, this.ctx, notices);
+      notices.unshift(...reconcileLegacy(context, this.reporter));
+      deliver(this.pi, context, notices);
       this.reporter.recover("completion-scan");
     } catch (error) {
       reconciled = false;
@@ -172,23 +186,34 @@ class AgentRuntime {
     this.awaited = new Set();
   }
   private start(context: ExtensionContext): Promise<void> | undefined {
+    if (this.shutdown.signal.aborted) {
+      return;
+    }
     this.reporter.start();
-    this.host = managedHost(context);
-    if (this.host === undefined || this.accepted || this.child) {
-      this.reset = this.reset.then(() => this.attach(context));
+    const owner = context.sessionManager.getSessionId();
+    const host = managedHost(context);
+    const binding = { context, owner, base: ownerDirectory(this.agentDir, owner), host };
+    if (
+      host === undefined ||
+      this.attachment.kind === "attached" ||
+      this.attachment.kind === "attaching" ||
+      this.child
+    ) {
+      this.reset = this.reset.then(() => this.attach(binding));
       return this.reset;
     }
     // Attach and publish only after the launcher retires rollback: an unready replacement
     // must neither adopt children nor append completions to a journal it may abandon.
     // Readiness follows session_start, so never await it here.
-    this.owner = context.sessionManager.getSessionId();
-    this.base = ownerDirectory(this.agentDir, this.owner);
-    this.host.ready
-      .then(async (accepted) => {
-        if (accepted && !this.closing) {
-          this.accepted = true;
-          await this.start(context);
+    const waiting: AttachmentState = { kind: "waiting", binding };
+    this.attachment = waiting;
+    host.ready
+      .then((accepted) => {
+        if (accepted && !this.shutdown.signal.aborted && this.attachment === waiting) {
+          this.reset = this.reset.then(() => this.attach(binding));
+          return this.reset;
         }
+        return null;
       })
       .catch((error: unknown) => {
         this.reporter.report(undefined, `Agent runtime attachment: ${errorText(error)}`);
@@ -196,37 +221,36 @@ class AgentRuntime {
     return undefined;
   }
   private ownerIdentity(): Omit<ProcessIdentity, "token"> {
-    return ownIdentity(this.host?.owner.pid);
+    return ownIdentity(this.binding.host?.owner.pid);
   }
-  private async attach(context: ExtensionContext): Promise<void> {
+  private async attach(binding: AttachmentBinding): Promise<void> {
     this.unwatch();
-    this.ctx = context;
+    const attaching: AttachmentState = { kind: "attaching", binding, generation: randomUUID() };
+    this.attachment = attaching;
     if (this.child) {
+      this.attachment = { ...attaching, kind: "attached" };
       return;
     }
-    this.owner = context.sessionManager.getSessionId();
-    this.base = ownerDirectory(this.agentDir, this.owner);
-    this.generation = randomUUID();
-    await fs.promises.mkdir(this.base, { recursive: true, mode: 0o700 });
-    write(path.join(this.base, "attachment.json"), {
-      ...this.ownerIdentity(),
-      generation: this.generation,
+    await fs.promises.mkdir(binding.base, { recursive: true, mode: 0o700 });
+    write(path.join(binding.base, "attachment.json"), {
+      ...ownIdentity(binding.host?.owner.pid),
+      generation: attaching.generation,
       attached: true,
     });
-    if (this.closing) {
+    if (this.shutdown.signal.aborted) {
       return;
     }
+    this.attachment = { ...attaching, kind: "attached" };
     // Recovery and watch setup stay off the awaited startup path.
     this.timer = setTimeout(this.scan, 200).unref();
     this.probe = setInterval(this.recover, 1000).unref();
   }
   private async dispose(retain: boolean): Promise<void> {
     this.reporter.shutdown();
-    this.closing = true;
     this.unwatch();
     this.shutdown.abort();
     await this.reset;
-    if (!retain && this.base.length > 0) {
+    if (!retain && !this.child && this.attachment.kind !== "detached") {
       const file = path.join(this.base, "attachment.json");
       const attachment = read(file, attachmentSchema);
       if (attachment !== undefined && this.releases(attachment)) {
@@ -240,16 +264,20 @@ class AgentRuntime {
         );
       }
     }
-    this.ctx = undefined;
+    this.attachment = { kind: "detached" };
   }
   private releases(attachment: Attachment): boolean {
-    if (attachment.generation === this.generation) {
-      return true;
+    const state = this.attachment;
+    switch (state.kind) {
+      case "detached":
+        return false;
+      case "waiting":
+        // An unready replacement can release the launcher's existing generation on quit.
+        return attachment.attached && attachment.pid === state.binding.host?.owner.pid;
+      case "attaching":
+      case "attached":
+        return attachment.generation === state.generation;
     }
-    // An unready replacement never attached, but exiting still releases the launcher-owned children.
-    return (
-      this.generation.length === 0 && attachment.attached && attachment.pid === this.host?.owner.pid
-    );
   }
   private stop(launch: Launch) {
     const base = this.base;
@@ -433,6 +461,7 @@ class AgentRuntime {
     this.pi.on("turn_end", (event, context) => {
       // The public pending flag covers user input; the preview also includes custom messages.
       if (
+        this.attachment.kind === "attached" &&
         settle(this.owner, context.hasPendingMessages() || event.context.pendingMessages.length > 0)
       ) {
         // Released admissions may have been dropped from the queue rather than published.
@@ -459,7 +488,7 @@ class AgentRuntime {
       name: "delegate",
       label: "Delegate",
       description:
-        "Run a child on exactly this prompt; main sessions only. Fork copies the full conversation; default is fresh. Returns a receipt; completion is notified later: do other work or end the turn, don't poll.",
+        "Run a child on exactly this prompt; main sessions only. Fork copies the full conversation; default is fresh. Optional thinking overrides inherited effort for this child. Returns a receipt; completion is notified later: do other work or end the turn, don't poll.",
       parameters: delegateSchema,
       exposure: this.child ? "hidden" : "direct",
       renderResult: renderCompactResult,