@emiliosp/pi-maestro 0.15.0 → 0.17.0

package/docs/configuration.md

@@ -17,45 +17,39 @@ For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi
   "builder": {
     "required": true,
     "model": "openai-codex/gpt-5.6-luna",
-    "thinking": "max",
-    "timeoutMinutes": 60
+    "thinking": "max"
   },
   "simplifier": {
     "required": true,
     "model": "openai-codex/gpt-6.1-sol",
-    "thinking": "high",
-    "timeoutMinutes": 60
+    "thinking": "high"
   },
   "verifier": {
     "required": true,
     "model": "openai-codex/gpt-6.1-sol",
-    "thinking": "high",
-    "timeoutMinutes": 60
+    "thinking": "high"
   }
 }
 ```
 
 ## Fields
 
-| Field                       |                  Required | Default                     | Rules                                                           |
-| --------------------------- | ------------------------: | --------------------------- | --------------------------------------------------------------- |
-| `version`                   | Yes, when the file exists | `1.0.0`                     | Configuration format version. Only `1.0.0` is supported.        |
-| `specDirectory`             |                        No | `.specs`                    | Relative path below the project root.                           |
-| `builder`                   |                        No | `Builder` defaults          | Overrides supported `builder` fields.                           |
-| `builder.required`          |                        No | `true`                      | Boolean selecting the `builder` phase.                          |
-| `builder.model`             |                        No | `openai-codex/gpt-5.6-luna` | Model string passed unchanged to Pi.                            |
-| `builder.thinking`          |                        No | `max`                       | One supported thinking level.                                   |
-| `builder.timeoutMinutes`    |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `builder` `run`.    |
-| `verifier`                  |                        No | `Verifier` defaults         | Overrides supported `verifier` fields.                          |
-| `verifier.required`         |                        No | `true`                      | Boolean selecting the `verifier` phase.                         |
-| `verifier.model`            |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                            |
-| `verifier.thinking`         |                        No | `high`                      | One supported thinking level.                                   |
-| `verifier.timeoutMinutes`   |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `verifier` `run`.   |
-| `simplifier`                |                        No | `Simplifier` defaults       | Overrides supported `simplifier` fields.                        |
-| `simplifier.required`       |                        No | `true`                      | Boolean selecting the `simplifier` phase.                       |
-| `simplifier.model`          |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                            |
-| `simplifier.thinking`       |                        No | `high`                      | One supported thinking level.                                   |
-| `simplifier.timeoutMinutes` |                        No | `60`                        | Integer from `1` to `1440`. Applies to each `simplifier` `run`. |
+| Field                 |                  Required | Default                     | Rules                                                    |
+| --------------------- | ------------------------: | --------------------------- | -------------------------------------------------------- |
+| `version`             | Yes, when the file exists | `1.0.0`                     | Configuration format version. Only `1.0.0` is supported. |
+| `specDirectory`       |                        No | `.specs`                    | Relative path below the project root.                    |
+| `builder`             |                        No | `Builder` defaults          | Overrides supported `builder` fields.                    |
+| `builder.required`    |                        No | `true`                      | Boolean selecting the `builder` phase.                   |
+| `builder.model`       |                        No | `openai-codex/gpt-5.6-luna` | Model string passed unchanged to Pi.                     |
+| `builder.thinking`    |                        No | `max`                       | One supported thinking level.                            |
+| `verifier`            |                        No | `Verifier` defaults         | Overrides supported `verifier` fields.                   |
+| `verifier.required`   |                        No | `true`                      | Boolean selecting the `verifier` phase.                  |
+| `verifier.model`      |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                     |
+| `verifier.thinking`   |                        No | `high`                      | One supported thinking level.                            |
+| `simplifier`          |                        No | `Simplifier` defaults       | Overrides supported `simplifier` fields.                 |
+| `simplifier.required` |                        No | `true`                      | Boolean selecting the `simplifier` phase.                |
+| `simplifier.model`    |                        No | `openai-codex/gpt-6.1-sol`  | Model string passed unchanged to Pi.                     |
+| `simplifier.thinking` |                        No | `high`                      | One supported thinking level.                            |
 
 Model values use the full `provider/model` identifier supplied by Pi's model registry, such as `openrouter/~openai/gpt-mini-latest`. Model IDs may contain additional
 slashes. `Maestro` does not apply a separate format rule; it matches the complete identifier against Pi's available models and passes it unchanged through `pi-subagents`.
@@ -80,12 +74,12 @@ Only `version` is required when the file exists. Each other field overrides its
 {
   "version": "1.0.0",
   "builder": {
-    "timeoutMinutes": 90
+    "thinking": "high"
   }
 }
 ```
 
-This example keeps every default except the `builder` timeout.
+This example keeps every default except the `builder` thinking level.
 
 ## Phase selection
 

package/docs/glossary.md

@@ -6,13 +6,15 @@
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Owner`                       | The person who approves the `spec`, decides questions and `findings`, and performs the final review.                                                                                                                                  |
 | `Maestro`                     | The coordinator that prepares the `spec`, runs the agents, and records `owner` decisions.                                                                                                                                             |
-| `Builder`                     | The agent that implements the approved `spec` and runs its `probes`.                                                                                                                                                                  |
+| `Builder`                     | The agent that implements the approved `spec` and runs every `GIVEN`, `WHEN`, and `THEN` scenario.                                                                                                                                    |
 | `Verifier`                    | The independent agent that checks the implementation and reports technical issues.                                                                                                                                                    |
 | `Simplifier`                  | The agent that refactors accepted code for clarity without changing behavior or introducing check failures.                                                                                                                           |
 | `Spec`                        | A `specification` for one change: `proposal.md` for motivation and scope, `spec.md` for behavior and `acceptance criteria`, and optional `design.md` for technical decisions. The present documents are approved and frozen together. |
 | `Acceptance criterion` (`AC`) | One required, observable result defined in the `spec`.                                                                                                                                                                                |
-| `Probe`                       | A scenario used to test an `acceptance criterion`. Reports record the actual command or procedure and its outcome.                                                                                                                    |
-| `Expected result`             | The observable result that a `probe` must produce.                                                                                                                                                                                    |
+| `GIVEN`                       | The starting conditions of an `acceptance criterion`.                                                                                                                                                                                 |
+| `WHEN`                        | The action or observation that checks the behavior of an `acceptance criterion`.                                                                                                                                                      |
+| `THEN`                        | The measurable outcome the `WHEN` must produce.                                                                                                                                                                                       |
+| `Assumption`                  | A detail the request did not specify or a scope boundary taken as given. A false `assumption` during implementation is an `escalation` trigger.                                                                                       |
 | `Artifact`                    | A saved workflow file, such as a `spec`, or a `handoff` between agents.                                                                                                                                                               |
 | `Handoff`                     | A saved agent report. `Builder` and `verifier` reports include `probe` outcomes. A `simplifier` report includes refactored files, a summary, and notes.                                                                               |
 | `Observability`               | The owner's ability to inspect workflow progress and reported results.                                                                                                                                                                |

package/docs/subagent-integration.md

@@ -16,8 +16,8 @@ The package supplies all three roles and the tools that save their results:
 Each `run` starts with a fresh conversation, not the main session's conversation history. All three agents inherit project instructions, the owner's global `AGENTS.md`,
 and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
 
-`Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md`
-when present) and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
+`Maestro` supplies the `spec` ID, project directory, model, and thinking level. The agents read all approved documents (`proposal.md`, `spec.md`, and `design.md` when
+present) and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
 
 The `owner` does not call agent tools directly. `Maestro` starts the enabled `builder` after `GREEN FLAG` approval. The enabled `verifier` starts after successful
 `builder` completion. The enabled `simplifier` follows the selected preceding phases. Disabled agents are not delegated. See
@@ -38,8 +38,8 @@ If a `run` fails or returns without a valid saved result, `Maestro` reports the
 ## External configuration
 
 The `pi-subagents` extension must be installed and enabled in Pi when `builder` is enabled. Workflows with only an approved `spec` need no agent availability or ping.
-`Builder`, `verifier`, and `simplifier` model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents`
-configuration remains the owner's responsibility.
+`Builder`, `verifier`, and `simplifier` model choices and thinking levels come from [Maestro configuration](configuration.md). `Maestro` does not supply a per-agent
+deadline. Other `pi-subagents` configuration remains the owner's responsibility.
 
 Only `maestro_run_simplifier` checks Git readiness, with `git rev-parse --is-inside-work-tree`. If readiness cannot be confirmed, it warns and completes without
 delegation. The `simplifier` uses Git to select all uncommitted code changes. `Maestro` does not change the Git index or create commits or checkpoints.

package/docs/workflow.md

@@ -5,7 +5,8 @@
 The approved `spec` is one document set: `proposal.md` explains motivation and scope, `spec.md` defines behavior and `acceptance criteria`, and optional `design.md`
 records significant technical decisions. The set forms one contract for the change.
 
-An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
+An `acceptance criterion` contains one `GIVEN`, one `WHEN`, one `THEN`, and an example. `GIVEN` and `WHEN` describe the scenario, and `THEN` states the measurable
+outcome.
 
 A `handoff` is a saved agent report. `Builder` and `verifier` reports contain `probe` outcomes. The simplifier's report records refactored files, a summary, and notes.
 
@@ -14,13 +15,13 @@ issues.
 
 ## Roles
 
-| Role         | Responsibility                                                                                                                                      |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Owner`      | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review.        |
-| `Maestro`    | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions.                         |
-| `Builder`    | Implements the approved `spec` and runs every `probe`. Reports completion or an `escalation`, including technical problems that prevent completion. |
-| `Verifier`   | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code.                                 |
-| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures.                                                        |
+| Role         | Responsibility                                                                                                                                                                   |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Owner`      | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review.                                     |
+| `Maestro`    | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions.                                                      |
+| `Builder`    | Implements the approved `spec` and runs every `GIVEN`, `WHEN`, and `THEN` scenario. Reports completion or an `escalation`, including technical problems that prevent completion. |
+| `Verifier`   | Independently runs every `GIVEN`, `WHEN`, and `THEN` scenario against the live project files. Reports `findings` without repairing product code.                                 |
+| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures.                                                                                     |
 
 `Builder`, `verifier`, and `simplifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
 
@@ -107,18 +108,18 @@ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [c
 
 Each new `spec` uses these documents in the same directory:
 
-| Document      | Content                                                                                           | Presence                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `proposal.md` | Problem, goal, scope, and exclusions.                                                             | Always created.                                                |
-| `spec.md`     | Required behavior, constraints, deltas, and `acceptance criteria` next to their requirements.     | Always created.                                                |
-| `design.md`   | Approved technical decisions, brief reasons, relevant contracts, risks, and prototype references. | Only when significant technical decisions need to be recorded. |
+| Document      | Content                                                                                                      | Presence                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `proposal.md` | Problem, goal, scope, and exclusions.                                                                        | Always created.                                                |
+| `spec.md`     | Required behavior, constraints, deltas, `acceptance criteria` next to their requirements, and `assumptions`. | Always created.                                                |
+| `design.md`   | Approved technical decisions, brief reasons, relevant contracts, risks, and prototype references.            | Only when significant technical decisions need to be recorded. |
 
 ## Spec approval
 
 For the initial `spec`:
 
 1. `Maestro` creates `proposal.md`, `spec.md`, and `workflow.json` in `drafting-spec`, then prepares the documents with the `owner`. It adds `design.md` only when needed.
-2. The `owner` reviews the complete document set: motivation, scope, requirements, `acceptance criteria`, and any approved technical decisions.
+2. The `owner` reviews the complete document set: motivation, scope, requirements, `acceptance criteria`, `assumptions`, and any approved technical decisions.
 3. `Maestro` asks the `owner` to inspect `proposal.md`, `spec.md`, and `design.md` when present and reply `GREEN FLAG` once to approve the entire set and proceed through
    the selected phases.
 4. After that reply, `Maestro` saves `ready-for-builder` and starts the enabled `builder` in the foreground, or saves `candidate-ready` with all agents skipped.
@@ -152,24 +153,23 @@ continuous across the whole document, including standalone regression criteria,
 For example, a change that introduces persistent item titles can describe its requirement and linked `acceptance criterion` in `spec.md` as follows:
 
 ```markdown
-### REQ1: Persist saved titles
+### REQ1: The system MUST persist saved titles
 
 Delta: added
 
-Saving and reopening an item must preserve its title.
-
 Verified by: [AC1](#ac1-saved-title-is-persisted)
 
 #### AC1: Saved title is persisted
 
-1. Probe: Save a change to an item's title, then reopen the item.
-2. Expected result: The saved title is still present.
-3. Example: Change the title from "Draft" to "Ready", save, and reopen the item. The title is "Ready".
+- GIVEN a saved item.
+- WHEN its title is changed and saved, then the item is reopened.
+- THEN the saved title is present.
+- Example: Change the title from "Draft" to "Ready", save, and reopen the item. The title is "Ready".
 ```
 
 A requirement can link to several `acceptance criteria`, and one criterion can verify several requirements (1:N). When an existing test covers the exact starting
-conditions, action, and `expected result`, `Verified by` links to the test file relative to `spec.md` and includes the exact scenario name. No duplicate criterion is
-needed. A requirement can reference both criteria and existing tests.
+conditions, action, and outcome, `Verified by` links to the test file relative to `spec.md` and includes the exact scenario name. No duplicate criterion is needed. A
+requirement can reference both criteria and existing tests.
 
 Before approval, `Maestro` follows the links and checks that their combined scenarios verify the whole requirement. Missing, partial, or uncertain coverage must be
 resolved with an appropriate criterion or a confirmed existing test. References are updated when criterion headings or test locations change, including during `spec`
@@ -190,19 +190,27 @@ For example, if saving item descriptions already works, adding title persistence
 
 ### AC2: Existing descriptions remain saved
 
-1. Probe: Change and save the title of an item with a saved description, then reopen it.
-2. Expected result: The description is unchanged.
-3. Example: An item's saved description is "Buy milk". Change its title from "Draft" to "Shopping", save, and reopen it. Its description is still "Buy milk".
+- GIVEN an item with a saved description.
+- WHEN its title is changed and saved, then the item is reopened.
+- THEN the description is unchanged.
+- Example: An item's saved description is "Buy milk". Change its title from "Draft" to "Shopping", save, and reopen it. Its description is still "Buy milk".
 ```
 
 Both nested and standalone criteria share one continuous AC sequence and are checked by the `builder` and `verifier`. Standalone criteria have the same fields as
 requirement-associated criteria:
 
-| Part              | Content                                                                            |
-| ----------------- | ---------------------------------------------------------------------------------- |
-| `Probe`           | Starting conditions and the action or observation that checks the behavior.        |
-| `Expected result` | The measurable result the `probe` observes.                                        |
-| Example           | Concrete starting conditions, an input or action, and the exact `expected result`. |
+| Part      | Content                                                                  |
+| --------- | ------------------------------------------------------------------------ |
+| `GIVEN`   | Starting conditions.                                                     |
+| `WHEN`    | The action or observation that checks the behavior.                      |
+| `THEN`    | The measurable outcome the `WHEN` must produce.                          |
+| `Example` | Concrete starting conditions, an input or action, and the exact outcome. |
+
+## Assumptions
+
+An `assumption` records a detail the request did not specify or a scope boundary taken as given. `Maestro` writes short `assumptions` in a `## Assumptions` section of
+`spec.md` as a bullet list, without paragraphs. The section is omitted when there are none. An `assumption` that proves false during implementation is an `escalation`
+trigger.
 
 ## Escalations
 
@@ -262,8 +270,8 @@ The revised `spec` controls subsequent work. Earlier `escalations`, `findings`,
 
 ## Verification boundary
 
-The `verifier` can make temporary changes for `probes`. Before submitting its `handoff`, it restores the exact original contents of affected files and removes only files
-it created.
+The `verifier` can make temporary changes to run its checks. Before submitting its `handoff`, it restores the exact original contents of affected files and removes only
+files it created.
 
 Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "keywords": [
     "orchestration",
@@ -66,8 +66,8 @@
     "pi-subagents": "0.78.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.0.3",
-    "@earendil-works/pi-tui": "1.0.3",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
     "@types/node": "26.6.4",
     "@vitest/coverage-v8": "5.0.3",
     "oxfmt": "0.73.0",

package/src/artifacts/builder-handoff/schema.ts

@@ -3,7 +3,6 @@
  * Used: When Maestro handles builder handoff artifacts.
  */
 
-import { StringEnum } from '@earendil-works/pi-ai';
 import { type Static, Type } from 'typebox';
 
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
@@ -26,7 +25,7 @@ export const PROBE_STATUSES = {
 
 export type ProbeStatus = (typeof PROBE_STATUSES)[keyof typeof PROBE_STATUSES];
 
-const ProbeStatusSchema = StringEnum(Object.values(PROBE_STATUSES));
+const ProbeStatusSchema = Type.Enum(PROBE_STATUSES, { type: 'string' });
 
 export const BuilderAcceptanceCriterionSchema = Type.Object(
   {

package/src/config/assertConfiguration.ts

@@ -6,9 +6,7 @@
 import { Value } from 'typebox/value';
 
 import {
-  MAX_TIMEOUT_MINUTES,
   MaestroConfigInputSchema,
-  MIN_TIMEOUT_MINUTES,
   type PartialMaestroConfig,
   SUPPORTED_CONFIG_VERSION,
   THINKING_LEVELS,
@@ -34,10 +32,6 @@ const formatError = (error: SchemaValidationError): string => {
     return `Invalid thinking level at "${path}". Allowed: ${Object.values(THINKING_LEVELS).join(', ')}.`;
   }
 
-  if (path.endsWith('timeoutMinutes')) {
-    return `Invalid timeout at "${path}". Must be an integer between ${MIN_TIMEOUT_MINUTES} and ${MAX_TIMEOUT_MINUTES}.`;
-  }
-
   if (path.endsWith('model')) {
     return `Invalid model at "${path}": expected a string.`;
   }

package/src/config/defaults.ts

@@ -19,8 +19,6 @@ export const DEFAULT_VERIFIER_THINKING = THINKING_LEVELS.HIGH;
 
 export const DEFAULT_SIMPLIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
 
-export const DEFAULT_TIMEOUT_MINUTES = 60;
-
 export const CONFIG_DIRECTORY_NAME = '.pi';
 
 export const CONFIG_FILE_NAME = 'maestro.json';
@@ -34,18 +32,15 @@ export const DEFAULT_CONFIG: MaestroConfig = {
     required: true,
     model: DEFAULT_BUILDER_MODEL,
     thinking: DEFAULT_BUILDER_THINKING,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
   simplifier: {
     required: true,
     model: DEFAULT_SIMPLIFIER_MODEL,
     thinking: THINKING_LEVELS.HIGH,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
   verifier: {
     required: true,
     model: DEFAULT_VERIFIER_MODEL,
     thinking: DEFAULT_VERIFIER_THINKING,
-    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
 };

package/src/config/schema.ts

@@ -25,10 +25,6 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[keyof typeof THINKING_LEVEL
 
 export const SUPPORTED_CONFIG_VERSION = '1.0.0';
 
-export const MIN_TIMEOUT_MINUTES = 1;
-
-export const MAX_TIMEOUT_MINUTES = 1440;
-
 export const ThinkingSchema = Type.Union([
   Type.Literal(THINKING_LEVELS.OFF),
   Type.Literal(THINKING_LEVELS.MINIMAL),
@@ -44,12 +40,6 @@ export const PartialAgentConfigSchema = Type.Object(
     required: Type.Optional(Type.Boolean()),
     model: Type.Optional(Type.String()),
     thinking: Type.Optional(ThinkingSchema),
-    timeoutMinutes: Type.Optional(
-      Type.Integer({
-        minimum: MIN_TIMEOUT_MINUTES,
-        maximum: MAX_TIMEOUT_MINUTES,
-      }),
-    ),
   },
   { additionalProperties: false },
 );
@@ -70,10 +60,6 @@ export const ResolvedAgentConfigSchema = Type.Object(
     required: Type.Boolean(),
     model: Type.String(),
     thinking: ThinkingSchema,
-    timeoutMinutes: Type.Integer({
-      minimum: MIN_TIMEOUT_MINUTES,
-      maximum: MAX_TIMEOUT_MINUTES,
-    }),
   },
   { additionalProperties: false },
 );

package/src/delegation/SubSession.ts

@@ -0,0 +1,102 @@
+/**
+ * Objective: Own the native session, cancellation, and cleanup for one child execution.
+ * Used: By the task executor while opening and closing a fresh SDK conversation.
+ */
+
+import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import {
+  type AgentSession,
+  createAgentSession,
+  type CreateAgentSessionOptions,
+  SessionManager,
+  type ToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+
+import { createChildServices } from '#src/delegation/createChildServices.ts';
+
+export type SubSessionInput = {
+  roleGuidance: string;
+  cwd: string;
+  model: string;
+  thinkingLevel: NonNullable<CreateAgentSessionOptions['thinkingLevel']>;
+  additionalTools: ToolDefinition[];
+  signal?: AbortSignal;
+};
+
+export class SubSession {
+  private session?: AgentSession;
+  private sessionManager?: SessionManager;
+  private abortPromise?: Promise<void>;
+
+  private readonly input: SubSessionInput;
+
+  constructor(input: SubSessionInput) {
+    this.input = input;
+  }
+
+  public getSavedFile = (): string | undefined => {
+    const path = this.sessionManager?.getSessionFile();
+
+    return path && existsSync(path) ? path : undefined;
+  };
+
+  private abort = (): void => {
+    this.abortPromise = this.session?.abort();
+    // The cleanup path awaits this promise. Handle rejection immediately as well.
+    void this.abortPromise?.catch(() => {});
+  };
+
+  public open = async (): Promise<AgentSession> => {
+    const cwd = await realpath(this.input.cwd);
+    const services = await createChildServices({ cwd, roleGuidance: this.input.roleGuidance });
+
+    const model = (await services.modelRuntime.getAvailable()).find(
+      (entry) => `${entry.provider}/${entry.id}` === this.input.model,
+    );
+
+    if (!model) throw new Error(`Model is not available: "${this.input.model}".`);
+
+    this.sessionManager = SessionManager.create(
+      cwd,
+      join(SessionManager.create(cwd).getSessionDir(), 'subagents'),
+    );
+
+    const { session } = await createAgentSession({
+      ...services,
+      sessionManager: this.sessionManager,
+      model,
+      thinkingLevel: this.input.thinkingLevel,
+      customTools: this.input.additionalTools,
+    });
+
+    this.session = session;
+
+    this.input.signal?.addEventListener('abort', this.abort, { once: true });
+
+    await this.session.bindExtensions({ mode: 'print' });
+
+    return this.session;
+  };
+
+  public close = async (): Promise<void> => {
+    this.input.signal?.removeEventListener('abort', this.abort);
+
+    if (!this.session) return;
+
+    try {
+      await this.session.abort();
+      await this.abortPromise;
+    } finally {
+      try {
+        // AgentSession.dispose() does not emit shutdown. This is the native runtime's
+        // shutdown sequence, including extensions such as MCP that own connections.
+        await this.session.extensionRunner.emit({ type: 'session_shutdown', reason: 'quit' });
+      } finally {
+        this.session.dispose();
+      }
+    }
+  };
+}

package/src/delegation/TaskExecutionError.ts

@@ -0,0 +1,20 @@
+/**
+ * Objective: Preserve task execution failures and their saved native session paths.
+ * Used: When standalone SDK execution fails or is interrupted.
+ */
+
+type TaskExecutionErrorInput = {
+  cause: unknown;
+  sessionFile?: string;
+};
+
+export class TaskExecutionError extends Error {
+  readonly sessionFile?: string;
+
+  constructor({ cause, sessionFile }: TaskExecutionErrorInput) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name =
+      cause instanceof Error && cause.name === 'AbortError' ? 'AbortError' : 'TaskExecutionError';
+    this.sessionFile = sessionFile;
+  }
+}

package/src/delegation/createChildServices.ts

@@ -0,0 +1,110 @@
+/**
+ * Objective: Discover native Pi resources without loading the main Maestro extension.
+ * Used: During preparation of each standalone child execution.
+ */
+
+import { realpathSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  createAgentSessionServices,
+  createCodemodeExtension,
+  createMcpExtension,
+  createToolSearchExtension,
+  DefaultPackageManager,
+  getAgentDir,
+  SettingsManager,
+} from '@earendil-works/pi-coding-agent';
+
+const MAIN_EXTENSION = fileURLToPath(new URL('../../extensions/maestro.ts', import.meta.url));
+
+type MaestroPackage = { name: '@emiliosp/pi-maestro' };
+
+const isMaestroPackage = (value: unknown): value is MaestroPackage =>
+  typeof value === 'object' &&
+  value !== null &&
+  'name' in value &&
+  value.name === '@emiliosp/pi-maestro';
+
+const isMainExtension = (path: string): boolean => {
+  if (path.startsWith('builtin:')) return false;
+
+  const canonicalPath = realpathSync(path);
+
+  if (canonicalPath === realpathSync(MAIN_EXTENSION)) return true;
+
+  // Discovery can find an installed copy rather than the currently executing checkout.
+  if (
+    basename(canonicalPath) !== 'maestro.ts' ||
+    basename(dirname(canonicalPath)) !== 'extensions'
+  ) {
+    return false;
+  }
+
+  try {
+    return isMaestroPackage(
+      JSON.parse(readFileSync(join(dirname(canonicalPath), '../package.json'), 'utf8')),
+    );
+  } catch {
+    return false;
+  }
+};
+
+type CreateChildServicesInput = {
+  cwd: string;
+  roleGuidance: string;
+};
+
+export const createChildServices = async ({ cwd, roleGuidance }: CreateChildServicesInput) => {
+  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.create(cwd, agentDir);
+
+  const extensionFactories = [
+    { name: 'codemode', factory: createCodemodeExtension(), builtin: true, replaceable: true },
+    { name: 'tool-search', factory: createToolSearchExtension(), builtin: true, replaceable: true },
+    { name: 'mcp', factory: createMcpExtension(), builtin: true, replaceable: true },
+  ];
+
+  const packages = new DefaultPackageManager({
+    cwd,
+    agentDir,
+    settingsManager,
+    builtinExtensions: extensionFactories.map(({ name }) => name),
+  });
+
+  const resources = await packages.resolve(async () => 'error');
+
+  if (resources.installFailures?.length) {
+    throw new Error(resources.installFailures.map(({ message }) => message).join('\n'));
+  }
+
+  // extensionsOverride filters extensions after Pi has loaded and initialized them.
+  // It would exclude Maestro's event handlers, but its initialization code would still run.
+  // Use additionalExtensionPaths instead to exclude Maestro before loading it,
+  // so none of its code executes in the child session.
+  const additionalExtensionPaths = resources.extensions
+    .filter(({ enabled, path }) => enabled && !isMainExtension(path))
+    .map(({ path }) => path);
+
+  const services = await createAgentSessionServices({
+    cwd,
+    agentDir,
+    settingsManager,
+    resourceLoaderOptions: {
+      noExtensions: true,
+      additionalExtensionPaths,
+      extensionFactories,
+      appendSystemPromptOverride: (base) => [...base, roleGuidance],
+    },
+  });
+
+  const errors = [
+    ...services.resourceLoader.getExtensions().errors.map(({ error }) => error),
+    ...services.diagnostics.filter(({ type }) => type === 'error').map(({ message }) => message),
+  ];
+
+  if (errors.length) throw new Error(errors.join('\n'));
+
+  return services;
+};