@selesai/code 0.9.11 → 0.9.13

package/dist/extensions/pi-subagents/README.md

@@ -4,7 +4,7 @@
 
 # pi-subagents
 
-`pi-subagents` lets Selesai delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.
+`pi-subagents` lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.
 
 <https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1>
 
@@ -18,7 +18,7 @@ That is the only required step.
 
 ## Try this first
 
-You do not need to create agents, write config, or learn slash commands. After installing, ask Selesai in plain language:
+You do not need to create agents, write config, or learn slash commands. After installing, ask Pi in plain language:
 
 ```text
 Use reviewer to review this diff.
@@ -36,15 +36,15 @@ Use scout to understand this code based on our discussion, then ask me clarifica
 Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.
 ```
 
-That is enough to start. Selesai decides whether to call the `subagent` tool, which agent to use, and how to compose the work.
+That is enough to start. Pi decides whether to call the `subagent` tool, which agent to use, and how to compose the work.
 
 ## How it works
 
-Selesai is the parent session. A subagent is a focused child Selesai session with its own job.
+Pi is the parent session. A subagent is a focused child Pi session with its own job.
 
-When you ask for a subagent, Selesai starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
+When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
 
-Installing the extension does not start an automatic reviewer in the background. It gives Selesai a delegation tool. If you want every implementation reviewed, say so in your prompt or project instructions:
+Installing the extension does not start an automatic reviewer in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say so in your prompt or project instructions:
 
 ```text
 When you finish implementing, run a reviewer subagent before summarizing.
@@ -57,28 +57,26 @@ The extension ships with agents you can use immediately:
 | Agent | Use it when you want... |
 |-------|--------------------------|
 | `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks. |
-| `explorer` | Selesai-native recon: read-only findings in its final response (≈ `scout`). |
 | `researcher` | Web/docs research with sources and a concise research brief. |
 | `worker` | Implementation work. Edits files, validates, escalates unapproved decisions instead of guessing. |
-| `builder` | Selesai-native implementation (≈ `worker`). Fresh context by default; single-writer with decision escalation. |
 | `reviewer` | Code review and small fixes against the task/plan, tests, edge cases, and simplicity. |
-| `commentator` | Selesai-native review (≈ `reviewer`). Strictly read-only, evidence-backed findings. |
-| `advisor` | Claude Code-compatible alias for `oracle`. |
-| `architect` | A written implementation plan before coding. Read-only. |
-| `recapper` | A self-contained current-state handoff for the next session or agent. |
 | `oracle` | A second opinion before acting. Challenges assumptions without editing. |
 | `delegate` | A lightweight general delegate that behaves close to the parent session. |
 
-Rule of thumb: `scout`/`explorer` before you understand the code, `researcher` before you trust external facts, `worker`/`builder` to implement, `reviewer`/`commentator` to check, `architect` when a plan would help, `recapper` to hand off state, and `oracle` when the decision itself feels risky.
+Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
 
 ## Common workflows
 
+The package includes `/council` and `council-mode`, plus documented model-based
+`council-*` profile examples that you add in your own agent directory.
+
 | Want | Ask naturally |
 |------|---------------|
 | Get a second opinion | "Ask oracle to review this plan and challenge assumptions." |
 | Solve a hard problem | "Use oracle to investigate this bug before we edit." |
 | Review a diff | "Use reviewer to review this diff." |
 | Run parallel reviewers | "Run reviewers for correctness, tests, and cleanup." |
+| Debate a material decision | "Use `/council` with model-based advisors to compare this decision." |
 | Implement then review | "Implement this, then review it." |
 | Review until clean | "Run a review loop on this change with a max of 3 rounds." |
 | Execute a plan carefully | "Have worker implement this approved plan, then run reviewers and apply the feedback." |
@@ -95,9 +93,9 @@ For implementation work, the recommended loop is `clarify → scout → worker
 
 Foreground runs stream progress in the conversation. Background runs keep working after control returns to you.
 
-Use `subagent({ action: "status" })` to inspect active async runs, `view: "transcript"` to read recent child output, and `steer` or `stop` to control a running run. You can also ask: "Show me the current async runs."
+In the TUI, a persistent FleetView below the editor keeps active work visible. `/subagents-fleet` opens a live inspector where you can browse children, read transcripts, steer a running child, or stop a run. You can also just ask: "Show me the current async runs."
 
-Details and machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
+Details, keybindings, and the machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
 
 For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical children in one run tree. It defaults to 64 and stays separate from active concurrency and the session-wide cumulative spawn budget. See [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md#maxsubagentspawnsperrun).
 
@@ -122,7 +120,7 @@ The full reference lives in `docs/`:
 | [Workflows](https://github.com/nicobailon/pi-subagents/blob/main/docs/workflows.md) | Orchestration patterns, prompt shortcuts, scripted workflows, worktree isolation, child-to-parent coordination, the recursion guard. |
 | [Watchdog](https://github.com/nicobailon/pi-subagents/blob/main/docs/watchdog.md) | The opt-in adversarial change reviewer, scope monitoring, LSP checks, and child tool permissions. |
 | [Tool reference](https://github.com/nicobailon/pi-subagents/blob/main/docs/tool-reference.md) | Every `subagent` parameter, management actions, status/control actions, acceptance gates, external CLI runners. |
-| [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md) | Run status, transcripts, lifecycle artifacts, events, logs, and session sharing. |
-| [Missions](https://github.com/nicobailon/pi-subagents/blob/main/docs/missions.md) | Durable mission records and delivery receipts. |
+| [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md) | FleetView, the fleet inspector, lifecycle artifacts, events, logs, session sharing. |
+| [Missions and schedules](https://github.com/nicobailon/pi-subagents/blob/main/docs/missions.md) | Durable mission records, delivery receipts, timed and recurring runs. |
 | [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md) | Every `config.json` key and environment variable. |
 | [Extension API](https://github.com/nicobailon/pi-subagents/blob/main/docs/extension-api.md) | The RPC, delegation API, preflight, capability ceilings, background-work providers, Herdr integration. |

package/dist/extensions/pi-subagents/agents/oracle.md

@@ -16,7 +16,9 @@ Your primary job is to prevent the main agent from making hidden, conflicting, o
 
 Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
 
-If the task is framed as asking or consulting the oracle, treat it as a live consultation unless the parent explicitly requests a one-shot report. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
+Match search scope to the question. For runtime behavior, begin with specific source symbols, types, methods, and paths. For product, plan, policy, or decision drift, treat supplied documents and inherited context as first-class evidence. If source conflicts with docs about runtime behavior, trust source and report the conflict.
+
+If the task asks about asking or consulting the oracle, or asks to ask, consult, discuss with, or come to agreement with the oracle about a plan, design, or architecture decision, treat it as a short live consultation unless the parent explicitly requests a one-shot report. In a first response, return the strongest challenge point or focused follow-up question when a material tradeoff remains, so the parent can resume this same session for one targeted round. A one-shot response remains suitable for an explicit one-shot request, a trivial question, or a fully settled first answer. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
 
 If you need clarification from the main agent and bridge instructions provide `contact_supervisor`, use it with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
 

package/dist/extensions/pi-subagents/agents/researcher.md

@@ -1,33 +1,52 @@
 ---
 name: researcher
-description: Read-only external and code-first research
-tools: read, mcp:grep_app_search, mcp:grep_app_fetch, web_explore
+description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
+tools: read, write, web_search, fetch_content, get_search_content
 thinking: medium
 systemPromptMode: replace
-inheritProjectContext: false
+inheritProjectContext: true
 inheritSkills: false
-defaultContext: fresh
-skill: ponytail
-acceptanceRole: read-only
+output: research.md
+defaultProgress: true
 ---
 
-You are a code-first research subagent. Answer the supplied question with a concise, well-sourced brief. Do not edit project files, write output files, or launch subagents.
+You are a research subagent.
 
-Start with `grep_app_search` for public-code evidence and use `grep_app_fetch` only for the most relevant source files. Search 2–4 distinct angles, prefer original implementations and repository-owned examples, then narrow follow-ups only for material gaps.
+Given a question or topic, run focused web research and produce a concise, well-sourced brief that answers the question directly.
 
-Treat `web_explore` as a last resort: use it only when grep.app cannot answer the question, the task requires non-code sources or official documentation, or grep.app fails. If `web_explore` is unavailable, report the gap instead of fetching URLs through shell commands.
+Working rules:
+- Break the problem into 2-4 distinct research angles.
+- Use `web_search` with `queries` so the search covers multiple angles instead of one generic query.
+- Use `workflow: "none"` unless the task explicitly needs the interactive curator.
+- Read the search results first. Then fetch full content only for the most promising source URLs.
+- Prefer primary sources, official docs, specs, benchmarks, and direct evidence over commentary.
+- Drop stale, redundant, or SEO-heavy sources.
+- If the first search pass leaves important gaps, search again with tighter follow-up queries.
 
-Output:
+Search strategy:
+- direct answer query
+- authoritative source query
+- practical experience or benchmark query
+- recent developments query when the topic is time-sensitive
+
+Output format:
 
 # Research: [topic]
 
 ## Summary
+2-3 sentence direct answer.
 
 ## Findings
-1. **Finding** — evidence. [Source](url)
+Numbered findings with inline source citations.
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
 
 ## Sources
-- Kept: title (url) — relevance.
+- Kept: Source Title (url) — why it matters
+- Dropped: Source Title — why it was excluded
 
 ## Gaps
-- What remains uncertain and the smallest next step.
+What could not be answered confidently. Suggested next steps.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed research brief normally.

package/dist/extensions/pi-subagents/agents/reviewer.md

@@ -50,6 +50,7 @@ Review a PR or issue by understanding the context, then verifying:
 - Tests and docs are updated as needed.
 
 ## Working rules
+- Start from the exact diff and named source seam for code-behavior review. Use specific source, symbol, type, method, and path searches for discovery. Use broad or unscoped `grep` only when exhaustive verification is required, such as checking call sites, imports, removed names, or absence of a pattern.
 - Read the relevant files first. Read plan and progress when the task supplies them.
 - Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
 - Do not use shell commands or write files. Report any test or Git command that a supervisor must run.
@@ -71,8 +72,18 @@ Structure your findings clearly:
 ## Review
 - Correct: what is already good (with evidence)
 - Fixed: issue, location, and resolution (if you applied a fix)
-- Blocker: critical issue that must be resolved before proceeding
-- Note: observation, risk, or follow-up item
+- Finding: P0/P1/P2, issue, location, evidence, and smallest fix
+- Merge verdict: BLOCK, OK, or OK with notes
 ```
 
 When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.
+
+Filter findings by evidence, not by severity. Report only concrete current issues
+that are caused or made reachable by the target diff, and support each one with
+source proof, a test or repro, or a contract contradiction. Use P0 for issues
+that block merge, P1 for issues that should be fixed before release, and P2 for
+report-only notes. Say exactly `No issues found.` when nothing qualifies.
+
+Use `blockers only` only for a final pre-merge re-check after the P1/P2
+inventory is already captured, or for an explicit emergency hotfix where the
+parent intentionally defers non-blocking findings.

package/dist/extensions/pi-subagents/agents/scout.md

@@ -12,7 +12,7 @@ defaultProgress: true
 
 You are a scouting subagent running inside pi.
 
-Use the provided tools directly. Move fast, but do not guess. Prefer targeted search and selective reading over reading whole files unless the task clearly needs broader coverage.
+Use the provided tools directly. Move fast, but do not guess. Start discovery with task-provided paths and specific symbols, types, methods, filenames, or likely source roots. Use `find` for path discovery. Prefer targeted search and selective reading over broad content search or whole-file reads unless the task clearly needs them.
 
 Focus on the minimum context another agent needs in order to act:
 - relevant entry points
@@ -22,7 +22,7 @@ Focus on the minimum context another agent needs in order to act:
 - constraints, risks, and open questions
 
 Working rules:
-- Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper.
+- Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper. Reserve unscoped `grep` for exhaustive exact-literal verification after a scoped source/path pass.
 - Use `bash` only for non-interactive inspection commands.
 - When you cite code, use exact file paths and line ranges.
 - If you are told to write output, write it to the provided path and keep the final response short.

package/dist/extensions/pi-subagents/agents/worker.md

@@ -16,7 +16,7 @@ You are `worker`: the implementation subagent.
 
 You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
 
-Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
+Use the provided tools directly. First read the inherited context, supplied files, plan, task paths, and named seams. Then implement carefully and minimally. Use broad search only to verify or expand from that starting point.
 
 The builtin worker uses a strict tool allowlist. It does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
 
@@ -34,6 +34,7 @@ Default responsibilities:
 
 Working rules:
 - Prefer narrow, correct changes over broad rewrites.
+- Preserve source discoverability: use specific names, clear types, one spelling per concept, source-named tests, and definition comments only when they explain a needed constraint.
 - Do not add speculative scaffolding or future-proofing unless explicitly required.
 - Do not leave placeholder code, TODOs, or silent scope changes.
 - Use `bash` for inspection, validation, and relevant tests.

package/dist/extensions/pi-subagents/async-retention-discovery-worker.mjs

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parentPort } from "node:worker_threads";
+
+const ACTIVE_RUN_INDEX_DIR = ".active-runs";
+const RESULT_TOMBSTONE_PREFIX = ".deleting-result-";
+
+function compareRelative(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+
+function insertSmallest(entries, candidate, limit) {
+	if (limit <= 0) return;
+	const index = entries.findIndex((entry) => compareRelative(candidate.relative, entry.relative) < 0);
+	if (index === -1) entries.push(candidate);
+	else entries.splice(index, 0, candidate);
+	if (entries.length > limit) entries.pop();
+}
+
+function streamDirWindow(dir, limit, after, relativePath, usable) {
+	if (limit <= 0) return { entries: [], rawReads: 0, exhausted: true, cursorCleared: false };
+	let handle;
+	try {
+		handle = fs.opendirSync(dir);
+		const next = [];
+		const wrapped = [];
+		let rawReads = 0;
+		while (true) {
+			const entry = handle.readSync();
+			if (!entry) break;
+			rawReads += 1;
+			const relative = relativePath(entry);
+			if (!usable(entry, relative)) continue;
+			const candidate = { relative, name: entry.name };
+			insertSmallest(wrapped, candidate, limit);
+			if (after === undefined || compareRelative(relative, after) > 0) insertSmallest(next, candidate, limit);
+		}
+		const cursorCleared = after !== undefined && next.length === 0;
+		return { entries: cursorCleared ? wrapped : next, rawReads, exhausted: true, cursorCleared };
+	} catch (error) {
+		if (error?.code === "ENOENT") return { entries: [], rawReads: 0, exhausted: true, cursorCleared: false };
+		throw error;
+	} finally {
+		handle?.closeSync();
+	}
+}
+
+function discover(request) {
+	const startedAt = Date.now();
+	const cursor = structuredClone(request.cursor);
+	const raw = { reads: 0, exhausted: {} };
+	const record = (source, scan) => {
+		raw.reads += scan.rawReads;
+		raw.exhausted[source] = scan.exhausted;
+	};
+	const runScan = streamDirWindow(
+		request.asyncDirRoot,
+		request.runBudget,
+		cursor.runAfter,
+		(entry) => entry.name,
+		(entry) => entry.isDirectory() && entry.name !== ACTIVE_RUN_INDEX_DIR,
+	);
+	record("runs", runScan);
+	if (runScan.cursorCleared) delete cursor.runAfter;
+	const runCandidates = runScan.entries.slice(0, request.runBudget);
+	for (const candidate of runCandidates) cursor.runAfter = candidate.relative;
+
+	const resultCandidates = [];
+	const sourceLimit = Math.max(1, Math.ceil(request.resultBudget / 4));
+	const addFiles = (dir, kind, cursorTarget, source, budget = sourceLimit) => {
+		const remaining = Math.min(budget, request.resultBudget - resultCandidates.length);
+		if (remaining <= 0) return 0;
+		const before = resultCandidates.length;
+		const after = cursorTarget.type === "pending"
+			? cursor.resultPendingAfterBySession?.[cursorTarget.session]
+			: cursor[cursorTarget.key];
+		const scan = streamDirWindow(
+			dir,
+			remaining,
+			after,
+			(entry) => path.relative(request.resultsDir, path.join(dir, entry.name)),
+			(entry) => entry.isFile() && (entry.name.startsWith(RESULT_TOMBSTONE_PREFIX) || entry.name.endsWith(".json")),
+		);
+		record(source, scan);
+		if (scan.cursorCleared) {
+			if (cursorTarget.type === "pending") delete cursor.resultPendingAfterBySession?.[cursorTarget.session];
+			else delete cursor[cursorTarget.key];
+		}
+		for (const candidate of scan.entries.slice(0, remaining)) {
+			const tombstone = candidate.name.startsWith(RESULT_TOMBSTONE_PREFIX);
+			resultCandidates.push({
+				name: candidate.name,
+				relative: candidate.relative,
+				kind: tombstone ? "tombstone" : kind,
+				cursor: cursorTarget,
+			});
+			if (cursorTarget.type === "pending") {
+				cursor.resultPendingAfterBySession ??= {};
+				cursor.resultPendingAfterBySession[cursorTarget.session] = candidate.relative;
+			} else cursor[cursorTarget.key] = candidate.relative;
+		}
+		return resultCandidates.length - before;
+	};
+
+	addFiles(request.resultsDir, "public", { type: "result", key: "resultPublicAfter" }, "results.public");
+	const pendingRoot = path.join(request.resultsDir, "result-pending");
+	const pendingRemaining = Math.min(request.resultBudget, sourceLimit, request.resultBudget - resultCandidates.length);
+	const pendingScan = streamDirWindow(
+		pendingRoot,
+		pendingRemaining,
+		cursor.pendingSessionAfter,
+		(entry) => entry.name,
+		(entry) => entry.isDirectory(),
+	);
+	record("results.pendingSessions", pendingScan);
+	const livePendingSessions = new Set(pendingScan.entries.map((entry) => entry.relative));
+	if (cursor.resultPendingAfterBySession) {
+		let pruned = 0;
+		for (const session of Object.keys(cursor.resultPendingAfterBySession).sort()) {
+			if (pruned >= request.resultBudget) break;
+			if (!livePendingSessions.has(session) && !fs.existsSync(path.join(pendingRoot, session))) {
+				delete cursor.resultPendingAfterBySession[session];
+				pruned += 1;
+			}
+		}
+		if (Object.keys(cursor.resultPendingAfterBySession).length === 0) delete cursor.resultPendingAfterBySession;
+	}
+	if (pendingScan.cursorCleared) delete cursor.pendingSessionAfter;
+	const pendingSessions = pendingScan.entries.slice(0, pendingRemaining);
+	let pendingFileBudget = Math.min(sourceLimit, request.resultBudget - resultCandidates.length);
+	for (const session of pendingSessions) {
+		if (pendingFileBudget <= 0) break;
+		cursor.pendingSessionAfter = session.relative;
+		pendingFileBudget -= addFiles(
+			path.join(pendingRoot, session.name),
+			"pending",
+			{ type: "pending", session: session.relative },
+			`results.pending.${session.name}`,
+			pendingFileBudget,
+		);
+	}
+	addFiles(path.join(request.resultsDir, "completion-replay"), "replay", { type: "result", key: "resultReplayAfter" }, "results.replay");
+	addFiles(path.join(request.resultsDir, "output-archives"), "archive", { type: "result", key: "resultArchiveAfter" }, "results.archive");
+
+	const cursorOps = [];
+	for (const key of ["runAfter", "resultPublicAfter", "resultReplayAfter", "resultArchiveAfter", "pendingSessionAfter"]) {
+		if (cursor[key] === request.cursor[key]) continue;
+		cursorOps.push(cursor[key] === undefined ? { type: "delete", key } : { type: "set", key, value: cursor[key] });
+	}
+	const oldPending = request.cursor.resultPendingAfterBySession ?? {};
+	const nextPending = cursor.resultPendingAfterBySession ?? {};
+	for (const session of new Set([...Object.keys(oldPending), ...Object.keys(nextPending)])) {
+		if (oldPending[session] === nextPending[session]) continue;
+		cursorOps.push(nextPending[session] === undefined
+			? { type: "delete-pending", session }
+			: { type: "set-pending", session, value: nextPending[session] });
+	}
+	return {
+		type: "result",
+		passId: request.passId,
+		discoveryDurationMs: Math.max(0, Date.now() - startedAt),
+		rawReads: raw.reads,
+		sourceExhausted: raw.exhausted,
+		runCandidates,
+		resultCandidates,
+		cursorOps,
+	};
+}
+
+if (!parentPort) throw new Error("Async retention discovery requires a worker parent port.");
+parentPort.on("message", (request) => {
+	const passId = request?.passId;
+	try {
+		parentPort.postMessage(discover(request));
+	} catch (error) {
+		parentPort.postMessage({ type: "error", passId, error: error instanceof Error ? error.message : String(error) });
+	}
+});