@buyong/pi-devin 0.1.4 → 0.1.6

package/src/pi/features/runs/admission.ts

@@ -0,0 +1,36 @@
+import { Deferred, Effect, Exit } from "effect";
+
+interface Ticket {
+  turn: Deferred.Deferred<void>;
+  hasLeft: boolean;
+}
+
+export interface AdmissionTicket {
+  /** Waits until everyone who entered earlier has left. */
+  readonly turn: Effect.Effect<void>;
+  /** Idempotent. Also used by a request that gives up before its turn; those behind it still wait for everyone ahead of it. */
+  readonly leave: Effect.Effect<void>;
+}
+
+/** Admits one request at a time, strictly in the order they entered. A new arrival never takes a turn ahead of a waiting one. */
+export class AdmissionLine {
+  private readonly line: Ticket[] = [];
+
+  enter(): AdmissionTicket {
+    const ticket: Ticket = { turn: Deferred.makeUnsafe<void>(), hasLeft: false };
+    this.line.push(ticket);
+    if (this.line.length === 1) Deferred.doneUnsafe(ticket.turn, Exit.void);
+    return {
+      turn: Deferred.await(ticket.turn),
+      leave: Effect.sync(() => this.leave(ticket)),
+    };
+  }
+
+  private leave(ticket: Ticket): void {
+    if (ticket.hasLeft) return;
+    ticket.hasLeft = true;
+    while (this.line[0]?.hasLeft) this.line.shift();
+    const front = this.line[0];
+    if (front) Deferred.doneUnsafe(front.turn, Exit.void);
+  }
+}

package/src/pi/features/runs/lifecycle.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Exit } from "effect";
+import { makeCancellation, type Cancellation } from "../../../core/cancellation.ts";
+import { Cancelled, type DevinError, type DevinFailure } from "../../../core/errors.ts";
+import { failWith } from "../../../core/validation.ts";
+import { AdmissionLine, type AdmissionTicket } from "./admission.ts";
+import { freshState, MAX_STEP_INDEX, restoreState } from "./state.ts";
+import type { DevinSessionState, ExecutionKind, ExecutionState, RequestLease, SessionBinding } from "./types.ts";
+
+interface Execution {
+  data: ExecutionState;
+  /** Ends the run's work with a reason: a finished run or an invalidated login. */
+  cancellation: Cancellation;
+  /** Requests of one run are admitted one at a time, in order. */
+  admission: AdmissionLine;
+  cleanups: Set<Effect.Effect<void>>;
+  activeRequests: number;
+  hasStarted: boolean;
+  nextIsRecovery: boolean;
+  hasCheckpoint: boolean;
+}
+
+const cancelled = () => new Cancelled({ message: "The previous Devin run ended." });
+const runQuietly = (cleanup: Effect.Effect<void>) => Effect.catchCause(cleanup, () => Effect.void);
+
+/** Runs of one extension instance and its attached session. It never builds its own tool or retry loop. */
+export class DevinLifecycle {
+  private binding?: SessionBinding;
+  private state: DevinSessionState = freshState(randomUUID());
+  private execution?: Execution;
+  private isClosed = false;
+  private isAuxiliary = false;
+
+  private constructor() {}
+
+  static readonly make: Effect.Effect<DevinLifecycle> = Effect.sync(() => new DevinLifecycle());
+
+  get snapshot(): Effect.Effect<DevinSessionState> {
+    return Effect.sync(() => structuredClone(this.state));
+  }
+
+  private checkpoint(): Effect.Effect<void, Cancelled> {
+    return Effect.suspend(() => {
+      if (this.binding && this.binding.getSessionId() !== this.state.sessionId) return Effect.fail(cancelled());
+      this.binding?.append(structuredClone(this.state));
+      return Effect.void;
+    });
+  }
+
+  private activate(data: ExecutionState, hasCheckpoint = false): Execution {
+    this.state.execution = data;
+    return this.execution = {
+      data, cancellation: makeCancellation(), admission: new AdmissionLine(), cleanups: new Set(),
+      activeRequests: 0, hasStarted: false, nextIsRecovery: false, hasCheckpoint,
+    };
+  }
+
+  attach(binding: SessionBinding): Effect.Effect<void, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      yield* this.abort(cancelled());
+      this.binding = binding;
+      this.state = yield* restoreState(binding);
+      this.execution = undefined; this.isClosed = false; this.isAuxiliary = false;
+      if (this.state.execution && !this.state.execution.settled) this.activate({ ...this.state.execution, kind: "recovered" }, true);
+    });
+  }
+
+  begin(kind: ExecutionKind): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (this.isClosed) return yield* Effect.fail(cancelled());
+      const current = this.execution;
+      if (current && !current.data.settled) {
+        if (kind === "agent" && ["pending", "recovered"].includes(current.data.kind)) current.data.kind = "agent";
+        else if (kind === "agent" && ["manual", "tree", "direct"].includes(current.data.kind) && current.activeRequests === 0) yield* this.finish;
+        else return; // Retries and tool follow-up calls stay in the same run.
+        if (this.execution) return;
+      }
+      this.activate({ id: randomUUID(), settled: false, kind });
+    });
+  }
+
+  get agentStarted(): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (!this.execution) yield* this.begin("agent");
+      const execution = this.execution!;
+      execution.nextIsRecovery = execution.hasStarted;
+      execution.hasStarted = true;
+    });
+  }
+
+  beforeCompaction(reason: "manual" | "threshold" | "overflow"): Effect.Effect<void, Cancelled> {
+    return Effect.andThen(this.begin(reason === "manual" ? "manual" : "pending"), Effect.sync(() => { this.isAuxiliary = true; }));
+  }
+
+  afterCompaction(reason: "manual" | "threshold" | "overflow"): Effect.Effect<void, Cancelled> {
+    return Effect.suspend(() => {
+      this.isAuxiliary = false;
+      return reason === "manual" && this.execution?.data.kind === "manual" ? this.finish : Effect.void;
+    });
+  }
+
+  get beforeTree(): Effect.Effect<void, Cancelled> {
+    return Effect.andThen(this.begin("tree"), Effect.sync(() => { this.isAuxiliary = true; }));
+  }
+
+  get finish(): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      const execution = this.execution;
+      if (!execution) return;
+      execution.data.settled = true;
+      yield* this.abort(cancelled());
+      if (execution.hasCheckpoint) yield* this.checkpoint();
+      this.execution = undefined; this.isAuxiliary = false;
+    });
+  }
+
+  /** Stops the run's waiting and running requests with the reason. A cleanup failure never skips releasing other resources. */
+  abort(reason: DevinFailure): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const active = this.execution;
+      if (!active) return Effect.void;
+      active.cancellation.cancelUnsafe(reason);
+      return Effect.forEach([...active.cleanups], runQuietly, { discard: true });
+    });
+  }
+
+  get shutdown(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      if (this.isClosed) return Effect.void;
+      // An unfinished run stays in the checkpoint so a reload resumes it with the same execution ID.
+      return Effect.andThen(this.abort(cancelled()), Effect.sync(() => { this.isClosed = true; }));
+    });
+  }
+
+  get treeChanged(): Effect.Effect<void, DevinError | Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (!this.binding) return;
+      yield* this.abort(cancelled());
+      this.state = yield* restoreState(this.binding);
+      this.state.trajectoryId = randomUUID(); this.state.nextStepIndex = 0;
+      this.state.execution = undefined; this.execution = undefined; this.isAuxiliary = false;
+      if (this.state.ownerHash) yield* this.checkpoint();
+    });
+  }
+
+  acquire(ownerHash: string): Effect.Effect<RequestLease, DevinFailure> {
+    return Effect.gen({ self: this }, function* () {
+      if (this.isClosed) return yield* Effect.fail(cancelled());
+      if (!/^[a-f0-9]{64}$/.test(ownerHash)) return yield* failWith("A verified Devin account scope is required.");
+      if (this.state.ownerHash && this.state.ownerHash !== ownerHash) return yield* failWith("This Pi session is bound to a different Devin account or endpoint. Start a new session.");
+      this.state.ownerHash = ownerHash;
+      if (!this.execution) yield* this.begin("direct");
+      const active = this.execution!, state = this.state;
+      const ownCleanups = new Set<Effect.Effect<void>>();
+      let isCounted = false, hasReleased = false;
+      let ticket: AdmissionTicket | undefined;
+      const release = Effect.suspend(() => {
+        if (hasReleased) return Effect.void;
+        hasReleased = true;
+        for (const cleanup of ownCleanups) active.cleanups.delete(cleanup);
+        return Effect.forEach([...ownCleanups], runQuietly, { discard: true }).pipe(Effect.andThen(Effect.suspend(() => {
+          if (isCounted) active.activeRequests--;
+          return ticket ? ticket.leave : Effect.void;
+        })));
+      });
+      const assertCurrent = Effect.suspend(() => {
+        const reason = active.cancellation.reason();
+        if (reason) return Effect.fail(reason);
+        if (this.execution !== active || this.state !== state || this.isClosed || (this.binding && this.binding.getSessionId() !== state.sessionId)) return Effect.fail(cancelled());
+        return Effect.void;
+      });
+      const admitted = Effect.gen({ self: this }, function* () {
+        // Entered inside the effect whose exit releases it, so an interruption cannot leave the line blocked.
+        ticket = active.admission.enter();
+        yield* active.cancellation.guard(ticket.turn);
+        yield* assertCurrent;
+        if (state.nextStepIndex >= MAX_STEP_INDEX) return yield* failWith("The Devin step number limit was reached. Start a new session.");
+        active.activeRequests++; isCounted = true;
+        const stepIndex = state.nextStepIndex++;
+        active.hasCheckpoint = true;
+        yield* this.checkpoint();
+        const isAuxiliary = this.isAuxiliary;
+        const isRecovery = !isAuxiliary && active.nextIsRecovery;
+        if (!isAuxiliary) active.nextIsRecovery = false;
+        const lease: RequestLease = {
+          executionId: active.data.id, cascadeId: state.cascadeId, trajectoryId: state.trajectoryId,
+          sessionId: state.sessionId, stepIndex, isAuxiliary, isRecovery,
+          cancellation: active.cancellation,
+          assertAttempt: assertCurrent,
+          addCleanup: (cleanup) => Effect.suspend(() => {
+            let hasCleaned = false;
+            const once = Effect.suspend(() => {
+              if (hasCleaned) return Effect.void;
+              hasCleaned = true;
+              return cleanup;
+            });
+            ownCleanups.add(once); active.cleanups.add(once);
+            return active.cancellation.isCancelled() ? runQuietly(once) : Effect.void;
+          }),
+          release,
+        };
+        return lease;
+      });
+      return yield* admitted.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : release));
+    });
+  }
+}

package/src/pi/features/runs/service.ts

@@ -0,0 +1,10 @@
+import { Context, Layer } from "effect";
+import { DevinLifecycle } from "./lifecycle.ts";
+
+/**
+ * Runs of the attached Pi session: admission order, request leases and the stored session state.
+ * A run spans many provider calls and ends at `agent_settled`, never when one response ends.
+ */
+export class Runs extends Context.Service<Runs, DevinLifecycle>()("pi-devin/Runs") {}
+
+export const RunsLive = Layer.effect(Runs, DevinLifecycle.make);

package/src/pi/features/runs/state.ts

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import { failWith } from "../../../core/validation.ts";
+import type { DevinSessionState, SessionBinding } from "./types.ts";
+
+export const DEVIN_STATE_ENTRY = "pi-devin.state.v1";
+export const MAX_STEP_INDEX = 2_147_483_647;
+
+const UUID = Schema.String.check(Schema.isPattern(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/));
+const isStoredState = Schema.is(Schema.Struct({
+  version: Schema.Literal(1),
+  sessionId: Schema.String,
+  ownerHash: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/))),
+  cascadeId: UUID,
+  trajectoryId: UUID,
+  nextStepIndex: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: MAX_STEP_INDEX })),
+  // `used` is the request budget count saved by 0.1.5 and earlier; it is accepted and dropped.
+  execution: Schema.optionalKey(Schema.Struct({ id: UUID, used: Schema.optionalKey(Schema.Int), settled: Schema.Boolean })),
+}));
+
+export function freshState(sessionId: string): DevinSessionState {
+  return { version: 1, sessionId, cascadeId: randomUUID(), trajectoryId: randomUUID(), nextStepIndex: 0 };
+}
+
+/** The newest state of this session's branch. Another session's state starts fresh; a corrupt one stops instead of resetting the IDs. */
+export function restoreState(binding: SessionBinding): Effect.Effect<DevinSessionState, DevinError> {
+  return Effect.suspend(() => {
+    const sessionId = binding.getSessionId();
+    const entry = [...binding.getBranch()].reverse().find((item) => item.type === "custom" && item.customType === DEVIN_STATE_ENTRY);
+    if (!entry) return Effect.succeed(freshState(sessionId));
+    if (!isStoredState(entry.data)) return failWith("The Devin session state is corrupt or an unsupported version. Start a new session.");
+    if (entry.data.sessionId !== sessionId) return Effect.succeed(freshState(sessionId));
+    const { execution, ...state } = structuredClone(entry.data);
+    return Effect.succeed({ ...state, ...(execution ? { execution: { id: execution.id, settled: execution.settled } } : {}) } as DevinSessionState);
+  });
+}

package/src/pi/features/runs/types.ts

@@ -0,0 +1,43 @@
+import type { Effect } from "effect";
+import type { Cancellation } from "../../../core/cancellation.ts";
+import type { DevinFailure } from "../../../core/errors.ts";
+
+export type ExecutionKind = "agent" | "pending" | "manual" | "tree" | "direct" | "recovered";
+export interface ExecutionState { id: string; settled: boolean; kind: ExecutionKind }
+
+/** The `pi-devin.state.v1` session entry. Holds no token, fingerprint or message. */
+export interface DevinSessionState {
+  version: 1;
+  sessionId: string;
+  ownerHash?: string;
+  cascadeId: string;
+  trajectoryId: string;
+  nextStepIndex: number;
+  execution?: ExecutionState;
+}
+
+/** Pi's current session as the run service sees it: its ID, its branch entries and a way to append a state entry. */
+export interface SessionBinding {
+  getSessionId(): string;
+  getBranch(): readonly { type: string; customType?: string; data?: unknown }[];
+  append(data: DevinSessionState): void;
+}
+
+/** One admitted model request of a run. */
+export interface RequestLease {
+  executionId: string;
+  cascadeId: string;
+  trajectoryId: string;
+  sessionId: string;
+  stepIndex: number;
+  isAuxiliary: boolean;
+  isRecovery: boolean;
+  /** Ends when the run is aborted, failing with its reason. */
+  cancellation: Cancellation;
+  /** Checked before each model HTTP request: fails once the run has ended or the session has changed. */
+  assertAttempt: Effect.Effect<void, DevinFailure>;
+  /** Runs once when the run is aborted or the lease is released. */
+  addCleanup(cleanup: Effect.Effect<void>): Effect.Effect<void>;
+  /** Idempotent. Lets the next request of the run in. */
+  release: Effect.Effect<void>;
+}

package/src/pi/features/settings/service.ts

@@ -0,0 +1,46 @@
+import { Context, Effect, Layer } from "effect";
+import type { FusionSelection } from "../catalog/types.ts";
+import type { AccountUsage } from "../usage/types.ts";
+import type { DevinPreferences, DisplaySettingsShape, FusionSettingsShape, UsageStoreShape } from "./types.ts";
+
+export const DEFAULT_PREFERENCES: DevinPreferences = { recommendedOnly: false, showUsageStatus: false };
+
+export class FusionSettings extends Context.Service<FusionSettings, FusionSettingsShape>()("pi-devin/FusionSettings") {}
+export class DisplaySettings extends Context.Service<DisplaySettings, DisplaySettingsShape>()("pi-devin/DisplaySettings") {}
+export class UsageStore extends Context.Service<UsageStore, UsageStoreShape>()("pi-devin/UsageStore") {}
+
+/** A newer record replaces an older one of the same scope; another scope's record is always replaced. */
+export const isNotOlder = (current: AccountUsage | undefined, next: AccountUsage) => !current || next.fetchedAtMs >= current.fetchedAtMs;
+
+/** Memory stores, so SDK callers and tests never write to the real agent directory. */
+export function memoryFusionSettings(initial?: FusionSelection): FusionSettingsShape {
+  let current = initial;
+  return {
+    read: Effect.sync(() => current),
+    write: (selection) => Effect.sync(() => { current = { ...selection }; }),
+  };
+}
+
+export function memoryDisplaySettings(initial: Partial<DevinPreferences> = {}): DisplaySettingsShape {
+  let current: DevinPreferences = { ...DEFAULT_PREFERENCES, ...initial };
+  return {
+    read: Effect.sync(() => ({ ...current })),
+    write: (preferences) => Effect.sync(() => { current = { ...preferences }; }),
+  };
+}
+
+export function memoryUsageStore(): UsageStoreShape {
+  let record: { scope: string; usage: AccountUsage } | undefined;
+  return {
+    read: (scope) => Effect.sync(() => record?.scope === scope ? { ...record.usage } : undefined),
+    write: (scope, usage) => Effect.sync(() => {
+      if (record?.scope !== scope || isNotOlder(record.usage, usage)) record = { scope, usage: { ...usage } };
+    }),
+  };
+}
+
+export const MemorySettings = (initial: { fusion?: FusionSelection; display?: Partial<DevinPreferences> } = {}) => Layer.mergeAll(
+  Layer.sync(FusionSettings, () => memoryFusionSettings(initial.fusion)),
+  Layer.sync(DisplaySettings, () => memoryDisplaySettings(initial.display)),
+  Layer.sync(UsageStore, memoryUsageStore),
+);

package/src/pi/features/settings/types.ts

@@ -0,0 +1,36 @@
+import type { Effect } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import type { FusionSelection } from "../catalog/types.ts";
+import type { AccountUsage } from "../usage/types.ts";
+
+/** Display settings toggled by `/devin`. Both default to off and never change how models are used or requested. */
+export interface DevinPreferences {
+  /** Lists only the models that have a variant the catalog marks as recommended. */
+  recommendedOnly: boolean;
+  /** Shows quota and session usage in the TUI status line. */
+  showUsageStatus: boolean;
+}
+
+/** Global store for the lead and sidekick chosen with `/devin-fusion`. Every session uses the same value. */
+export interface FusionSettingsShape {
+  /** Never fails: a missing or unreadable store reads as no saved pair. */
+  readonly read: Effect.Effect<FusionSelection | undefined>;
+  write(selection: FusionSelection): Effect.Effect<void, DevinError>;
+}
+
+export interface DisplaySettingsShape {
+  /** Never fails: a missing or unreadable store reads as the defaults. */
+  readonly read: Effect.Effect<DevinPreferences>;
+  write(preferences: DevinPreferences): Effect.Effect<void, DevinError>;
+}
+
+/**
+ * Last account quota received by any Pi process that shares the agent directory, such as subagents and the Fusion sidekick.
+ * Keyed by the credential scope hash. No token, account ID or raw response is stored.
+ */
+export interface UsageStoreShape {
+  /** Never fails: a missing or unreadable record reads as none. */
+  read(scope: string): Effect.Effect<AccountUsage | undefined>;
+  /** Replaces the record unless the stored one for the same scope was fetched later. */
+  write(scope: string, usage: AccountUsage): Effect.Effect<void, DevinError>;
+}

package/src/pi/features/sidekick/child.ts

@@ -0,0 +1,228 @@
+import type { ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { Deferred, Effect, Exit } from "effect";
+import { toDevinError, type DevinError } from "../../../core/errors.ts";
+import { launchArgs } from "./command.ts";
+import type { Handoff, HandoffProgress, HandoffReport, SidekickLauncherShape, SidekickLaunch } from "./types.ts";
+
+const STDERR_TAIL = 2048;
+const RECENT_TOOLS = 5;
+const KILL_GRACE_MS = 2000;
+
+export interface SidekickChildOptions {
+  launcher: SidekickLauncherShape;
+  childEnv: Record<string, string>;
+  onProgress?: () => void;
+  /** Runs work that child process events start, in a fiber its owner tracks. */
+  fork: (effect: Effect.Effect<void>) => void;
+}
+
+interface PendingHandoff {
+  id: string;
+  startedAt: number;
+  toolCalls: number;
+  recentTools: string[];
+  lastError?: string;
+  isAborted: boolean;
+  done: Deferred.Deferred<HandoffReport>;
+}
+
+const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+/**
+ * Sidekick child Pi RPC process bound to one lead session. Started on the first handoff; keeps its context for the rest of the session.
+ * A handoff during a run adds instructions with `steer`; when the child run ends (`agent_settled`), the last assistant text is returned as the report.
+ */
+export class SidekickChild {
+  readonly launch: SidekickLaunch;
+  private readonly options: SidekickChildOptions;
+  private child: ChildProcess | undefined;
+  private pending: PendingHandoff | undefined;
+  private stderrTail = "";
+  private readonly waiting = new Map<string, Deferred.Deferred<string | undefined>>();
+
+  constructor(launch: SidekickLaunch, options: SidekickChildOptions) {
+    this.launch = launch;
+    this.options = options;
+  }
+
+  isBusy(): boolean { return this.pending !== undefined; }
+  isAlive(): boolean { return this.child !== undefined && this.child.exitCode === null && this.child.signalCode === null; }
+
+  progress(): HandoffProgress | undefined {
+    const current = this.pending;
+    return current ? { toolCalls: current.toolCalls, recentTools: [...current.recentTools], elapsedMs: Date.now() - current.startedAt } : undefined;
+  }
+
+  /** Starts a handoff, or steers the running one. Fails only when the child cannot be started. */
+  handoff(message: string): Effect.Effect<Handoff, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      const current = this.pending;
+      if (current) {
+        this.send({ type: "steer", message });
+        return { id: current.id, done: current.done, isSteer: true };
+      }
+      if (!this.isAlive()) yield* this.start;
+      const id = randomUUID();
+      const done = Deferred.makeUnsafe<HandoffReport>();
+      this.pending = { id, startedAt: Date.now(), toolCalls: 0, recentTools: [], isAborted: false, done };
+      this.send({ id, type: "prompt", message });
+      return { id, done, isSteer: false };
+    });
+  }
+
+  get abort(): Effect.Effect<void> {
+    return Effect.sync(() => {
+      if (!this.pending) return;
+      this.pending.isAborted = true;
+      this.send({ type: "abort" });
+    });
+  }
+
+  /** Stops the child: its handoff ends as aborted and every RPC wait is released. Termination continues in the background. */
+  get close(): Effect.Effect<void> {
+    return Effect.sync(() => this.closeChild());
+  }
+
+  private closeChild(): void {
+    const child = this.child;
+    this.child = undefined;
+    if (this.pending) this.finish("aborted", "", "Stopped the sidekick process.");
+    for (const waiter of this.waiting.values()) Deferred.doneUnsafe(waiter, Exit.succeed(undefined));
+    this.waiting.clear();
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    child.stdin?.end();
+    const timer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL"); }, KILL_GRACE_MS);
+    timer.unref();
+    child.once("close", () => clearTimeout(timer));
+    child.kill("SIGTERM");
+  }
+
+  private get start(): Effect.Effect<void, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      const { launcher } = this.options;
+      const base = yield* launcher.resolveCommand;
+      const args = [...base.args, ...launchArgs(this.launch, launcher.packageRoot)];
+      const child = yield* Effect.try({
+        try: () => launcher.spawn(base.command, args, {
+          cwd: this.launch.cwd,
+          env: { ...launcher.env, ...this.options.childEnv },
+          stdio: ["pipe", "pipe", "pipe"],
+        }),
+        catch: toDevinError,
+      });
+      this.child = child;
+      this.stderrTail = "";
+      this.listen(child);
+    });
+  }
+
+  private listen(child: ChildProcess): void {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      if (this.child !== child) return;
+      buffer += decoder.write(chunk);
+      let index: number;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        let line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        if (line.endsWith("\r")) line = line.slice(0, -1);
+        if (!line) continue;
+        let record: Record<string, unknown>;
+        try { record = JSON.parse(line) as Record<string, unknown>; } catch { continue; }
+        this.handle(record);
+        if (this.child !== child) return;
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => { if (this.child === child) this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL); });
+    child.stdin?.on("error", (error) => this.fail(child, error.message));
+    child.on("error", (error) => this.fail(child, error.message));
+    child.on("close", () => this.fail(child, this.stderrTail.trim() || "The sidekick process exited."));
+  }
+
+  /** Transport errors settle the handoff and all RPC waits once, even if the failed child closes after its replacement starts. */
+  private fail(child: ChildProcess | undefined, error: string): void {
+    if (this.child !== child) return;
+    this.finish(this.pending?.isAborted ? "aborted" : "error", "", error);
+    this.closeChild();
+  }
+
+  private send(value: Record<string, unknown>): void {
+    const child = this.child;
+    try {
+      if (!child?.stdin?.writable) throw new Error("Cannot write to the sidekick process.");
+      child.stdin.write(JSON.stringify(value) + "\n");
+    } catch (error) {
+      this.fail(child, errorMessage(error));
+    }
+  }
+
+  /** Sends the request at once; the returned wait is released with `undefined` when the child stops. */
+  private request(type: string): Effect.Effect<string | undefined> {
+    const id = randomUUID();
+    const waiter = Deferred.makeUnsafe<string | undefined>();
+    this.waiting.set(id, waiter);
+    this.send({ id, type });
+    return Deferred.await(waiter);
+  }
+
+  private handle(record: Record<string, unknown>): void {
+    const current = this.pending;
+    switch (record.type) {
+      case "response": {
+        const waiter = typeof record.id === "string" ? this.waiting.get(record.id) : undefined;
+        if (waiter) {
+          this.waiting.delete(record.id as string);
+          const data = record.data as { text?: unknown } | undefined;
+          Deferred.doneUnsafe(waiter, Exit.succeed(typeof data?.text === "string" ? data.text : undefined));
+        } else if (current && record.command === "prompt" && record.success === false) {
+          this.finish("error", "", String(record.error ?? "The sidekick did not receive the instructions."));
+        }
+        return;
+      }
+      case "extension_ui_request":
+        // The sidekick never talks to the user. Dialogs that need an answer are returned as cancelled.
+        if (["select", "confirm", "input", "editor"].includes(String(record.method))) {
+          this.send({ type: "extension_ui_response", id: record.id, cancelled: true });
+        }
+        return;
+      case "tool_execution_start":
+        if (!current) return;
+        current.toolCalls++;
+        current.recentTools = [...current.recentTools, String(record.toolName ?? "tool")].slice(-RECENT_TOOLS);
+        this.options.onProgress?.();
+        return;
+      case "message_end": {
+        const message = record.message as { role?: unknown; stopReason?: unknown; errorMessage?: unknown } | undefined;
+        if (current && message?.role === "assistant") {
+          current.lastError = message.stopReason === "error" && typeof message.errorMessage === "string" ? message.errorMessage : undefined;
+        }
+        return;
+      }
+      case "agent_settled":
+        if (current) this.options.fork(this.complete(current, record.aborted === true));
+        return;
+    }
+  }
+
+  private complete(current: PendingHandoff, isAborted: boolean): Effect.Effect<void> {
+    return Effect.map(this.request("get_last_assistant_text"), (text) => {
+      if (this.pending !== current) return;
+      if (isAborted || current.isAborted) this.finish("aborted", text ?? "");
+      else if (current.lastError) this.finish("error", text ?? "", current.lastError);
+      else this.finish("completed", text ?? "");
+    });
+  }
+
+  private finish(status: HandoffReport["status"], text: string, error?: string): void {
+    const current = this.pending;
+    if (!current) return;
+    this.pending = undefined;
+    Deferred.doneUnsafe(current.done, Exit.succeed({
+      id: current.id, status, text, toolCalls: current.toolCalls, durationMs: Date.now() - current.startedAt, ...(error ? { error } : {}),
+    }));
+    this.options.onProgress?.();
+  }
+}