@selesai/code 0.9.10 → 0.9.12

package/dist/extensions/pi-subagents/package.json

@@ -1,14 +1,16 @@
 {
   "name": "pi-subagents",
-  "version": "0.50.0",
-  "description": "Selesai extension for single-agent delegation, chains, parallel groups, and scripted multi-agent workflows",
+  "version": "0.56.0",
+  "description": "Selesai extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./index.ts",
     "./background-work": "./src/api/background-work.ts",
+    "./external-job-provider": "./src/api/external-job-provider.ts",
     "./external-runs": "./src/api/external-runs.ts",
+    "./agents": "./src/api/agents.ts",
     "./delegation": "./src/api/delegation.ts",
     "./capability-ceiling": "./src/api/capability-ceiling.ts",
     "./preflight": "./src/api/preflight.ts",
@@ -52,7 +54,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "npm run test:unit",
-    "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
+    "test:unit": "node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
     "test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
     "test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
     "test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
@@ -89,6 +91,7 @@
     }
   },
   "dependencies": {
+    "acorn": "8.18.0",
     "jiti": "2.7.0",
     "typebox": "1.1.38",
     "yaml": "2.8.3"

package/dist/extensions/pi-subagents/prompts/council.md

@@ -0,0 +1,60 @@
+---
+description: Run a bounded supervisor-mediated council of advisors and write a decision memo
+argument-hint: "<question> [--advisors name,name] [--max-passes 2|3] [--scope ...] [--non-goals ...]"
+---
+
+Run a bounded, supervisor-mediated council on this question. You, the parent
+session, are the supervisor. You select the roster, curate cross-advisor packets,
+decide which feedback is valid, and write the final memo. Advisors do not talk
+directly or see peer transcripts by default. This is not free-form agent chat.
+
+Before you orchestrate, read `skills/council-mode/SKILL.md` and
+`skills/pi-subagents/references/execution-controls.md`.
+
+Parse the invocation yourself. The flags below are conventions, not runtime
+options. Record a brief with the question, scope, non-goals, evidence targets,
+roster, known advisor context modes, and pass cap. Default `--max-passes` to 2.
+Clamp it to 2 or 3. If the question is trivial or settled, answer directly instead
+of convening a council.
+
+## Roster
+
+- If `--advisors` is given, use exactly those agent names. Fail clearly on an
+  unknown agent. Do not require or invent per-advisor role labels.
+- Otherwise list agents with `subagent({ action: "list" })`, then prefer 2–3
+  executable names that start with `council-`.
+- If fewer than two profiles are available, fill the roster with `oracle`, then
+  `reviewer`, until it has two advisors. Launch fallback `oracle` with
+  `context: "fork"` so global defaults cannot remove its parent-chat context.
+  Let `reviewer` use its normal profile context. Note the fallback and known
+  context modes in the memo.
+- Use the normal single-oracle loop only when a requested roster or unavailable
+  builtins leaves fewer than two advisors. Label the memo as degraded mode.
+
+Profiles provide the model, tools, context, and advisor stance. The council
+question and scope provide the decision frame. If the user wants a specific lens,
+they should put it in the question, scope, or profile definition. Keep the roster
+at 2–3 and never exceed 4.
+
+Package advisors such as Surf's `gpt-pro` are valid only when the package Pi
+extension is installed and its external-job provider is registered. For Surf,
+that means the `surf-cli` Pi extension has loaded and `surf-oracle` appears in
+`subagent({ action: "list" })` or the advisor is explicitly requested in
+`--advisors` after that install. Treat them as external-runner advisors: omit
+child `async` for normal attached council results, do not pass `outputSchema`,
+include any needed evidence in the prompt, and use the fresh fallback cross-exam
+path if the run is not resumable.
+
+## Run the protocol
+
+Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
+and memo requirements in `skills/council-mode/SKILL.md`. Keep the parent as the
+only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
+or transcript sharing.
+
+Use its required boundary checkpoints, yield for each async workflow without
+polling, and write its required final memo.
+
+Question and options from the slash command invocation:
+
+$@

package/dist/extensions/pi-subagents/prompts/parallel-review.md

@@ -28,7 +28,11 @@ Choose or adapt angles when the work calls for it:
 
 Prefer three strong reviewers over many vague reviewers.
 
-Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete, current, caused or made reachable by the target diff, and supported by source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
+
+For a targeted follow-up review, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments.
 
 While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
 - fixes worth doing now

package/dist/extensions/pi-subagents/prompts/review-loop.md

@@ -6,7 +6,7 @@ Run a parent-orchestrated review loop for the requested work.
 
 Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks; they must not run subagents or manage the loop themselves unless the parent intentionally selected an explicit fanout agent whose builtin `tools` includes `subagent` for that assigned fanout.
 
-Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no blockers or fixes worth doing now.
+Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no P0 findings, no P1 fixes worth doing now, and no approved P2 notes that should be handled in this loop.
 
 If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front with `workflowScript` when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflowScript, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
 
@@ -14,12 +14,14 @@ As a conservative orchestration policy, do not set `turnBudget`, a hard `toolBud
 
 For each review round, launch fresh-context `reviewer` agents in parallel. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files.
 
+Tell reviewers to filter on evidence, not severity. They should report only concrete current issues caused or made reachable by the target diff, with source proof, a test or repro, or a contract contradiction. Ask them to label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. P0 blocks merge. P1 should be fixed before release. P2 is report-only. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes.
+
 Choose review angles from the actual change. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API contracts, or user-flow validation when the work calls for it. Prefer three strong reviewers over many vague reviewers.
 
 After reviewers return, synthesize their feedback into:
-- blockers or scope/product/architecture decisions that need user approval;
-- fixes worth doing now;
-- optional improvements;
+- P0 blockers or scope/product/architecture decisions that need user approval;
+- P1 fixes worth doing now;
+- P2 report-only notes or optional improvements;
 - feedback to ignore or defer, with a short reason.
 
 Do not blindly apply every reviewer suggestion. If reviewers surface an unapproved product, scope, or architecture decision, pause and ask me before launching a fix worker.
@@ -30,8 +32,10 @@ When there are fixes worth doing now and the workflow is implementation-authoriz
 
 After a fix worker returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
 
+For a targeted follow-up review, ask only three questions: whether the named finding was resolved, whether the fix introduced a new concrete defect in the fix blast radius, and whether prior P1/P2 notes still stand. End with a fix verdict and the merge verdict.
+
 Stop and summarize when one of these is true:
-- reviewers find no blockers or fixes worth doing now;
+- reviewers find no P0 blockers or P1 fixes worth doing now;
 - remaining feedback is optional, speculative, or intentionally deferred;
 - reviewers surface an unapproved decision that needs me;
 - the max review-round cap is reached.

package/dist/extensions/pi-subagents/skills/council-mode/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: council-mode
+description: Run a bounded supervisor-mediated advisor council. Use when the user asks for council mode, asks to convene advisors, debate a decision, cross-examine recommendations, or run /council.
+---
+
+# Council Mode
+
+This skill is for the parent supervisor only. Do not inject it into advisors. The
+parent selects the roster, curates all cross-advisor communication, decides which
+feedback is valid, and writes the decision memo. Advisors do not talk directly or
+see peer transcripts by default. This is not free-form agent chat.
+
+Use council mode for a material decision with real tradeoffs. Do not use it for a
+trivial or settled question, or for implementation work. Read
+`skills/pi-subagents/references/execution-controls.md` before you launch advisors.
+
+## Roster and limits
+
+Use advisor profile names directly. A `council-*` profile defines model, tools,
+context, output defaults, and any persistent stance in the profile body. Its
+profile configuration or explicit invocation owns its context choice.
+
+Package advisors can also join the roster only when their package Pi extension is
+installed and their external-job provider is registered. For Surf, `gpt-pro` is
+available only after the `surf-cli` Pi extension loads Surf's `surf-oracle`
+provider. Treat it as a normal advisor name in `runs.all` after that provider is
+visible. It is background-only, so omit `async` unless you explicitly want
+detached receipt semantics; workflow execution will await the terminal provider
+result. External runners can lack repo tools, structured-output support, or
+resumability. For them, include the needed evidence or file excerpts in the task,
+use the text JSON contract below instead of `outputSchema`, and use the
+fresh-context fallback path for cross-exam when the run is not resumable.
+
+Create model-based profiles in your user or project agent directory. Do not add
+them to this package. This is a valid example:
+
+```markdown
+---
+name: council-sol
+description: Read-only fresh-context advisor for bounded council decisions
+tools: read, grep, find, ls
+model: openai-codex/gpt-5.6-sol
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+acceptanceRole: read-only
+---
+
+Analyze the council question independently. Inspect evidence directly. Do not
+edit, run mutating commands, commit, push, contact peers, or spawn subagents.
+Return concise, cited advice using the report contract in the council task.
+```
+
+After `subagent({ action: "list" })`, prefer 2–3 executable names that start with
+`council-`. The prefix is a naming convention, not runtime selection. If fewer
+than two profiles are available, fill the roster with `oracle`, then `reviewer`,
+until it has two advisors. Launch fallback `oracle` with `context: "fork"` so
+global defaults cannot remove its parent-chat context. Let fallback `reviewer`
+use its normal profile context. Note the fallback and known context modes in the
+memo. Use the normal single-oracle consultation loop only when a requested roster
+or unavailable builtins leaves fewer than two advisors.
+Label that result as degraded mode. Never use more than four advisors.
+
+Pass 1 is independent reports. Pass 2 is one cross-exam. The default pass cap is
+2. Run pass 3 only when `--max-passes 3` was requested and a material dispute can
+be settled by evidence an advisor can produce. Never run an unbounded loop.
+
+## Protocol
+
+1. The parent writes a brief with the question, scope, non-goals, evidence targets,
+   roster, known advisor context modes, and pass cap. If the user wants a specific
+   lens, keep it in the question, scope, or profile body instead of inventing a
+   per-advisor label.
+2. Before Pass 1, tell the user the roster, requested or known context modes, and
+   pass cap. Use a stable key, `phase`, and concise `label` for every
+   workflow child. For example, use `advisor-oracle`, `phase: "Council pass 1"`,
+   and `label: "Oracle — intent and consistency"`.
+3. Launch one async `workflowScript` with `runs.all` for independent advisor
+   reports. Set `context` when the selected advisor has a known profile context or
+   a fallback rule requests one, because a global default can otherwise override
+   that profile. Set `context: "fork"` for fallback `oracle`. If no advisor context
+   is known, omit `context` and disclose the unknown runtime default in the memo.
+   Each advisor is read-only and must not spawn children, edit files, run mutating
+   commands, commit, or push. Set `output: false` unless separate advisor artifacts
+   are explicitly requested or useful for the decision. When separate artifacts are
+   useful, give advisors relative output paths so the runtime stores them under its
+   managed artifact directory; do not ask them to write root-level council report
+   files. For installed
+   external-runner advisors such as Surf `gpt-pro` after `surf-oracle` is
+   registered, do not pass `outputSchema`; put the schema request in the task text
+   and accept `result.output` as the report.
+4. Return one aggregate Pass 1 receipt. After it completes, tell the user the
+   completion count, agreement count, dispute count, and whether Pass 2 is needed.
+5. The parent synthesizes a claim matrix in session. It contains agreements,
+   disputed claims, missing proof, owner decisions, and a relay set of at most five
+   high-impact claims per advisor. Do not delegate this synthesis.
+6. Before Pass 2, tell the user how many claims are relayed and why each is
+   material. Launch a second async `workflowScript` with `runs.all` resume calls.
+   Each task is a curated challenge packet, not a peer transcript. A resume requires
+   a retained run id and a non-empty task. It excludes `agent` and rejects `gate`.
+   Record the new run id from every resume. Pass 3 resumes those latest ids. Return
+   one aggregate Pass 2 receipt.
+7. After Pass 2, tell the user whether the council converged or which owner
+   decisions remain. The parent writes the final memo. Do not delegate it.
+
+If an advisor is not resumable, run the same profile in fresh context with its own
+pass-1 report and the challenge packet. Label that response as a fresh-context
+fallback, not a true cross-exam.
+
+Do not set `clarify`, `worktree`, `gate`, turn budgets, tool budgets, or tight usage
+budgets on advisors. Bound work through the roster, pass cap, and report length.
+
+## Advisor contracts and pass receipts
+
+Pass-1 reports are at most about 600 words. Give native Pi advisors the same
+`outputSchema`, so reports are comparable without heading cleanup. For
+external-runner advisors, do not pass `outputSchema`; ask them to return compact
+JSON text with the same fields. The following shape is a contract template. Use
+the runtime schema syntax supported by the workflow for native advisors and keep
+narrative fields as strings:
+
+```js
+const pass1OutputSchema = {
+  type: "object",
+  required: [
+    "recommendation", "evidence", "assumptions", "risks", "confidence",
+    "challengeClaims", "ownerDecisions", "changeMyMind"
+  ],
+  properties: {
+    recommendation: { type: "string" },
+    evidence: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["claim", "sources"],
+        properties: {
+          claim: { type: "string" },
+          sources: { type: "array", items: { type: "string" } }
+        }
+      }
+    },
+    assumptions: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["assumption", "status"],
+        properties: {
+          assumption: { type: "string" },
+          status: { enum: ["verified", "unverified"] }
+        }
+      }
+    },
+    risks: { type: "array", items: { type: "string" } },
+    confidence: {
+      type: "object",
+      required: ["level", "reason"],
+      properties: {
+        level: { enum: ["high", "medium", "low"] },
+        reason: { type: "string" }
+      }
+    },
+    challengeClaims: { type: "array", items: { type: "string" }, maxItems: 3 },
+    ownerDecisions: { type: "array", items: { type: "string" } },
+    changeMyMind: { type: "array", items: { type: "string" } }
+  }
+};
+```
+
+Include this contract in each Pass 1 task: inspect supplied evidence directly; do
+not see or ask about other advisors; stay read-only; do not spawn children; return
+only the structured report. For external-runner advisors, say `Return only JSON
+matching this shape. Do not wrap it in Markdown.` and include any evidence they
+cannot read through tools.
+
+After `runs.all`, return one aggregate receipt rather than making the parent find
+separate artifacts. Preserve the result order or map it by stable key so each row
+contains the advisor identity and report:
+
+```js
+return {
+  pass: 1,
+  advisors: results.map((result, index) => ({
+    key: result.key,
+    agent: result.agent,
+    requestedContext: roster[index].context ?? "runtime-default-unknown",
+    runId: result.runId,
+    report: result.structuredOutput ?? result.output
+  }))
+};
+```
+
+Do not replace `runtime-default-unknown` with a guessed context. It records that
+the launch intentionally omitted context.
+
+A challenge packet contains only disputed claims, strong conflicting evidence,
+missing proof, owner decisions, and high-impact risks. Attribute peer content as
+"another advisor". Do not include full peer reports. Use a common Pass 2 contract:
+
+```js
+const pass2OutputSchema = {
+  type: "object",
+  required: ["responses", "recommendationChanged", "outOfScopeFindings"],
+  properties: {
+    responses: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["claimId", "disposition", "reason", "sources"],
+        properties: {
+          claimId: { type: "string" },
+          disposition: {
+            enum: ["accept", "reject", "refine", "owner-decision"]
+          },
+          reason: { type: "string" },
+          sources: { type: "array", items: { type: "string" } }
+        }
+      }
+    },
+    recommendationChanged: {
+      type: "object",
+      required: ["changed", "reason"],
+      properties: { changed: { type: "boolean" }, reason: { type: "string" } }
+    },
+    outOfScopeFindings: { type: "array", items: { type: "string" } }
+  }
+};
+```
+
+Use stable resume keys such as `cross-oracle`, `phase: "Council pass 2"`, concise
+labels, and `output: false` unless separate artifacts are requested or useful. Keep
+any artifact outputs under the managed run artifact directory. Do not pass
+`outputSchema` to external-runner fallback launches; ask for compact JSON text
+instead. The aggregate Pass 2 receipt uses the same row shape as Pass 1, with the
+new `runId` and `structuredOutput ?? output`.
+
+## Stop and memo
+
+Converged means no disputed claim remains that both materially affects the
+recommendation and can plausibly be settled by evidence. Stop at convergence, the
+pass cap, failed fallback, or user interruption. Put unresolved disputes in owner
+decisions. Never add a round for polish or symmetry.
+
+The parent memo states the question and scope, recommendation, rationale, accepted
+and rejected feedback with reasons, owner decisions, evidence and run ids,
+confidence, what would change the decision, and the roster, passes, fallbacks, and
+known advisor context modes. Identify advisors by profile name or model-based
+profile, not by invented role labels. State that fallback `oracle` is context-aware
+and forked.
+
+Council mode is not agent-to-agent chat, a transcript dump, mutation authority,
+auto-escalation to writer lanes, or a council UI. Escalate to a writer only after
+the parent memo and only when the user explicitly requests it.

package/dist/extensions/pi-subagents/skills/pi-subagents/SKILL.md

@@ -1,25 +1,20 @@
 ---
 name: pi-subagents
 description: |
-  Delegate work to builtin or custom subagents with single-agent, chain,
-  parallel, scripted, async, forked-context, mission-backed, and
-  intercom-coordinated workflows. Use for advisory review, implementation
-  handoffs, and multi-step tasks where a single agent stays in control while
-  other agents contribute context, planning, or execution.
+  Delegate work to builtin or custom subagents with single-agent, parallel,
+  scripted-chaining, async, forked-context, and coordinated workflows. Use
+  for advisory review, implementation handoffs, and multi-step tasks where a
+  single agent should stay in control while other agents contribute context,
+  planning, or execution.
 ---
 
-# Selesai Subagents
+# Pi Subagents
 
 This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
 
-Use this skill when the parent orchestrator needs one specialized child or composed orchestration. The `subagent` tool has four first-class execution modes:
+Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child. Chaining is still supported, but it is code-driven: use `await runs.run(...)` for sequential steps, `runs.all([...])` for parallel fanout, and ordinary JavaScript for branching, retries, gate monitors, and aggregation. Keep workflow helpers portable: use plain helper functions or explicit Promise chains, not nested `async function` helpers, async arrows, or async methods. Do not use legacy top-level `chain` / `tasks` inputs or durable `.chain.md` execution. Scripted workflows normally start asynchronously unless config sets `asyncByDefault:false`; set `async:true` explicitly when async behavior matters. Pass `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` for final reviews, backlog gates, run-to-completion convenience, or because no other work is available.
 
-- **SINGLE** — `{ agent, task }` for one child (omit `task` for a self-contained agent).
-- **CHAIN** — `{ chain: [{ agent, task }, ...] }` for sequential steps with `{previous}`, `{outputs.name}`, `phase`/`label`, `outputSchema`, and `{ checkpoint: "name" }` human gates.
-- **PARALLEL** — `{ tasks: [{ agent, task }, ...], concurrency? }` for top-level parallel children, plus in-chain `{ parallel: [...] }` groups and dynamic `expand`/`collect` fanout.
-- **SCRIPTED WORKFLOW** — `{ workflowScript }` with `runs.run`/`runs.all` and ordinary JavaScript for sequence, parallelism, branching, retries, gate monitors, and aggregation. Use `return runs.run("main", { agent, task })` for one child and `runs.all([...])` for coordinated waves. Scripts start asynchronously by default; pass `async:false` only for a small foreground run.
-
-Prefer the declarative modes when the shape is known up front; reach for `workflowScript` when coordination needs dynamic branching or aggregation. Saved `.chain.md` / `.chain.json` workflows (run with `/run-chain`) make repeatable multi-agent flows shareable without rewriting the chain each time.
+Package-installed agents appear in `subagent({ action: "list" })` with builtin, user, and project agents. If `surf-cli` is installed as a Pi package, the Surf browser extension is loaded, and Chrome is logged into a ChatGPT Pro account, Surf can expose `gpt-pro`: a read-only async advisor that reaches ChatGPT web through Surf Oracle. Check it with `subagent({ action: "get", agent: "gpt-pro" })` and run it with `subagent({ agent: "gpt-pro", task: "Review this plan and identify release risks." })`.
 
 ## How to use this router
 
@@ -28,8 +23,10 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 | Task | Read |
 | --- | --- |
 | Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
-| Run single, chain, parallel, scripted, async, scheduled, mission-backed, forked, worktree, watchdog, clarify, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
-| List/create/update/delete/eject/disable agents or chains, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
+| Use council mode, convene several advisors, debate a decision, cross-examine recommendations, critique or improve a plan with multiple model perspectives, or run `/council` | `../council-mode/SKILL.md` |
+| Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
+| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
+| List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
 
 For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
@@ -37,11 +34,15 @@ For broad or uncertain requests, read more than one reference. For complex work,
 ## Always-on constraints
 
 - Keep the parent as orchestrator and final decision-maker.
+- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
+- For plan, design, or architecture advice that asks for council mode, asks to convene several advisors, compare model perspectives, debate a decision, cross-examine recommendations, or critique and improve a plan, read `../council-mode/SKILL.md` and use Council Mode instead of ad hoc parallel oracle calls.
+- For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with one `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
 - Use one writer per cwd/worktree unless isolated worktrees are intentional.
 - For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.
-- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` or parallel `tasks` group with stable keys and aggregate output unless there is truly only one child.
+- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` with stable keys and aggregate output unless there is truly only one child.
 - Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- Use async/background by default when work can proceed independently; do not poll just to wait. For planned human gates, use `{ checkpoint: "name", message?: "..." }` chain steps and approve or reject paused checkpoints with `approve-checkpoint` / `reject-checkpoint`. For adaptive gates, branch in `workflowScript`.
+- Use async/background by default. Final reviews, gate checks, oracle checks, and backlog lanes stay async. Use `async:false` only when the parent must block until completion. Do not poll just to wait. For adaptive gates, branch in `workflowScript`.
+- For Pi extension repos whose canonical checkout is under `~/.selesai/agent/extensions`, never create lane worktrees as sibling directories there. Pi auto-loads `~/.selesai/agent/extensions/*/index.ts`, so sibling worktrees can register duplicate tools. Put lanes under `~/.selesai/agent/worktrees`, another worktree base outside auto-discovery, or a temporary clone. If a lane must run the modified extension itself, use an isolated Pi config home with `SELESAI_CODING_AGENT_DIR=<lane-config> pi --no-extensions -e <lane>/index.ts`. Use full containers only when path and config isolation are insufficient.
 - Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
 - Escalate unresolved product, architecture, authority, release, merge, or safety decisions upward instead of letting a child decide silently.
 - Treat receipts, CI, review bots, and external-run records as evidence, not authority to merge, close, comment, publish, or release.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md

@@ -1,13 +1,15 @@
-# Selesai Subagents: Constraints And Recipes
+# Pi Subagents: Constraints And Recipes
 
 This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 ## Important Constraints
 
-- **Forking requires a persisted parent session.** If the current session does not
-  have a persisted session file, forked runs fail. Packaged `worker`, `oracle`,
-  and `advisor` default to forked context, so use `context: "fresh"` explicitly
-  when that is not available or not wanted.
+- **Explicit forking requires a persisted parent session.** If the current session
+  does not have a persisted session file or current leaf, explicit `context: "fork"`
+  fails. An agent-level `defaultContext: fork` is a preference: packaged `worker`,
+  `oracle`, and `advisor` fall back to `fresh` when those fork preconditions are not
+  met yet. Use `context: "fresh"` when you do not want a fork even after the parent
+  session exists.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
   filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
@@ -19,7 +21,13 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
   become second decision-makers.
 - **Respect the fixed authority policy.** `authorityPolicy` is a small `auto` / `confirm` / `forbid` map for supported operational actions. Worktree discard, destructive cleanup, and spawn-budget grants default to confirmation; stop, steer, and schedule creation remain automatic. Use `worktree.discard` with the durable `handoffPath`; confirm-required actions refuse safely without an interactive UI and retained paths include manual Git recovery commands.
 
-Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `project` (default), `session`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Per-run `artifacts: false` disables artifact capture for that launch. Async status and result artifacts include `lifecycleArtifactVersion` and fields such as `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 16 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
+Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `session` (default), `project`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Per-run `artifacts: false` disables artifact capture for that launch. Async status and result artifacts include `lifecycleArtifactVersion` and fields such as `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 16 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
+
+### Keep report artifacts out of the repository root
+
+Treat lane reports, review notes, council pass reports, and gate logs as scratch unless the user explicitly asks to keep them. Prefer `output: false` and the aggregate workflow result for short reports. When a later step needs a file, use the runtime-managed output artifact by setting a stable child key plus a relative `output` path such as `plans/deploy.md`; relative child outputs are saved under the run artifact directory, not the project root. Do not put `reports/...`, `*-report.json`, or similar repo-root paths in child task text.
+
+For durable evidence, copy only the final summary to session memory, a PR body/comment, a mission artifact, or a user-approved docs path outside the repo. After the PR, issue, or gate reaches a terminal state, delete or move scratch reports from the active worktree before reporting completion. Keep a project `.gitignore` entry for ad-hoc report patterns only as a safety net; it is not the cleanup mechanism.
 
 ## Best Practices
 
@@ -29,11 +37,12 @@ Launch every subagent asynchronously by default. Use `async: true` for scouts, r
 
 ### Use subagent_wait() to block until async runs finish
 
-In an interactive chat, do not call `subagent_wait()` merely to wait after launching background work; return control to the user and Selesai will wake the session on completion. Override that default when the current request is run-to-completion — for example, the user asked you to stay with the task and report results back this turn or a skill must finish in one turn. In a headless run, Selesai auto-drains exact current-session work at `agent_end`; call `subagent_wait()` when this turn must receive results before it ends. In either case, `subagent_wait()` blocks the current turn until the next run completes or needs attention, keeps the turn alive for normal notification delivery, then returns.
+In an interactive chat, do not call `subagent_wait()` merely to wait after launching background work; return control to the user and Pi will wake the session on completion. Override that default when the current request is run-to-completion — for example, the user asked you to stay with the task and report results back this turn or a skill must finish in one turn. In a headless run, Pi auto-drains exact current-session work at `agent_end`; call `subagent_wait()` when this turn must receive results before it ends. In either case, `subagent_wait()` blocks the current turn until the next run completes or needs attention, keeps the turn alive for normal notification delivery, then returns.
 
 - `subagent_wait()` — return when the next initially active async run or registered provider item finishes, or a subagent needs attention.
 - `subagent_wait({ all: true })` — block until every async run and provider item active at call time finishes, or a subagent needs attention.
 - `subagent_wait({ id: "..." })` — block on one async or remembered detached foreground run (id or prefix). Provider items are not selected through this parameter.
+- `subagent_wait({ stopOnAttention: false })` — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
 - `subagent_wait({ timeoutMs })` — cap the block; active work keeps running if it elapses.
 
 Providers are discovered through the `pi-subagents/background-work` registry and must return stable item IDs with exact owning session IDs. Child agents receive no provider automatically: keep `subagent_wait` in the child `tools` allowlist and load provider extensions through `extensions` or `subagentOnlyExtensions`.
@@ -59,10 +68,23 @@ user explicitly requests forked context.
 Give subagents specific tasks rather than vague mandates.
 `Review auth.ts for null-check gaps` works better than `Review everything`.
 
+Before fanout, assign each child a lightweight task profile in the parent prompt:
+work kind, required input, expected output, acceptance check, and context mode.
+Keep the profile prose-only; do not invent runtime fields. Use coarse kinds such
+as `code-write`, `code-read`, `transform`, `summarize`, and `search` only to
+shape the task and choose an existing agent/model setting. If a child task is not
+standalone enough for fresh context, add the missing facts to the prompt, switch
+to forked context, or ask the user. Do not launch vague tasks and rely on
+supervisor round-trips to recover missing context.
+
 ### Escalate decisions upward
 
 If a subagent encounters an unapproved product, architecture, scope, merge, release, credential, or authority choice, it should use `contact_supervisor` and wait for the reply instead of deciding alone. Generic `intercom` is external or provider-supplied only. Use it only when external bridge instructions provide an explicit safe target. External checks, receipts, and review bots provide evidence only; they do not grant authority.
 
+### Use a short oracle consultation for material advice
+
+When a user asks to ask, consult, discuss with, or come to agreement with `oracle` about a plan, design, or architecture decision, do not treat the first advisory report as final when it raises a material challenge or tradeoff. Read it, resume the same oracle session once with a targeted question, then make the parent decision. An explicit one-shot request, a trivial question, or a fully settled first answer does not need a follow-up.
+
 ### Intervene only on clear control signals
 
 Use subagent control proactively when a delegated run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
@@ -77,8 +99,8 @@ Use `/name` so intercom targeting stays stable.
 
 ```js
 subagent({ workflowScript: `
-  const context = await runs.run("recon", { agent: "scout", task: "Inspect the codebase and identify the implementation seam" });
-  return (await runs.run("implement", { agent: "worker", task: "Implement from: " + context.output })).output;
+  const context = await runs.run("recon", { agent: "scout", task: "Start from the named source roots, paths, and symbols. Identify the implementation seam before broad search." });
+  return (await runs.run("implement", { agent: "worker", task: "Read the scout output, plan paths, and named files/seams first. Implement from: " + context.output })).output;
 ` })
 ```