@ferris1225/pi-subagents 4.2.13 → 4.3.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ Published versions of `@ferris1225/pi-subagents`. Unpublished numbers
 (`4.2.3`, `4.2.6`, `4.2.9`–`4.2.11`) never shipped on npm; their changes
 landed in the next published release.
 
+## 4.3.0
+
+- Built-in team is `scout`, `artisan`, and `steward`. All three stay enabled.
+- `explorer` / `executor` configs rename in place (models and thinking
+  overrides follow). `steward` is adopted. That migration is deleted in the
+  next major.
+- Artisan owns implement / fix / refactor / test. Steward owns cleanup, docs
+  sync, and merge — dispatched only when that work exists.
+- Thinking is a role default (scout low, artisan high, steward medium) that
+  `/subagents-setup` can override. Per-call `thinking` and agent-file
+  `thinking` are gone. There is no Auto row.
+- First session and first-run setup explain each role and ask for a model.
+- Unit tests cover catalog migration, role prompts, dispatch routing, and
+  honest footer / truncation notes.
+
 ## 4.2.13
 
 - README: table of contents, a What's new lead-in, and a pointer at this

package/README.md

@@ -6,20 +6,23 @@
 ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 ![pi](https://img.shields.io/badge/pi-extension-orange)
 
-A managed engineering team for [pi](https://github.com/earendil-works/pi): two
+A managed engineering team for [pi](https://github.com/earendil-works/pi): three
 focused sub-agents, durable threads, and Git worktree
 isolation. You install it once and your main agent delegates on its own.
 
 ## What's new
 
+**4.3.0** — the team is `scout`, `artisan`, and `steward`. Existing
+`explorer`/`executor` configs migrate. Thinking is a role default you can
+change in `/subagents-setup` (no Auto, no per-call flag). All three roles
+start on. See [CHANGELOG.md](./CHANGELOG.md).
+
 **4.2.13** — this page now leads with current changes and keeps the 4.2 line
-in [CHANGELOG.md](./CHANGELOG.md).
+in the changelog.
 
 **4.2.12**
 
-- The executor confirms a named defect on current code before it edits.
-- Footer settled counts stay honest, and only while a sibling is still live.
-- Merging to `main` publishes npm and opens a matching GitHub Release.
+- Confirm-before-fix; honest footer counts; `main` publishes npm + GitHub Release.
 
 ## Contents
 
@@ -65,10 +68,10 @@ Requires **pi >= 0.84.4** and **Node.js >= 22.19.0**.
 pi install npm:@ferris1225/pi-subagents
 ```
 
-Open pi and run `/subagents-setup` to choose agents, models, and thinking
-strengths. A fresh install enables every agent on the current main model, and each
-session start points you at the wizard until a config file exists. Then just ask
-for work:
+Open pi and run `/subagents-setup`. The first session tells you how: pick a
+model for `scout`, `artisan`, and `steward` (all three stay on). Each row in
+the wizard names the role and what it owns. Thinking has a role default you
+can change there. Then just ask for work:
 
 ```text
 Map how authentication works, fix the refresh race, run the tests, and review the diff.
@@ -79,10 +82,11 @@ directly when you want exact control.
 
 ## The team
 
-| Agent         | Access    | Best for                                                                                                                                                                                                   |
-| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
-| `executor`    | Full      | A self-contained unit that changes the repository or condenses inputs: implementation, fixes, refactors, tests, evidence-first cleanup, docs/comment sync, or merging a fan-out's results into one brief — carried through verification and a result-only handoff. |
+| Agent      | Access    | Best for                                                                                                                                                                                                   |
+| ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scout`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
+| `artisan`  | Full      | One deliverable that changes the repository: implement, fix, refactor, or test — confirmed on current code, then verified, then a result-only handoff.                                                      |
+| `steward`  | Full      | Use only when that work exists: evidence-first cleanup, docs/comment sync, or merging a fan-out's result artifacts into one brief.                                                                          |
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
 
@@ -91,14 +95,15 @@ memory of your conversation, so the brief is its only input. A good brief carrie
 the goal, exact paths, constraints, and expected output — which is what the
 injected delegation guidance produces when the main agent dispatches for you.
 A named defect is not yet a change: confirm it on current code before fixing
-or briefing a fix. The executor re-reads before it edits.
+or briefing a fix. The artisan re-reads before it edits. Steward is
+dispatched only when cleanup, docs sync, or a merge is actually needed.
 
 ```text
 You
  └─ pi main agent
-     ├─ explorer ─── parallel recon, retrieval leads only
-     └─ executor ─── one deliverable per child: implement, fix, clean up,
-                     sync docs, or merge fan-out results → verify → deliver
+     ├─ scout    ─── parallel recon, retrieval leads only
+     ├─ artisan  ─── implement, fix, refactor, or test → verify → deliver
+     └─ steward  ─── cleanup, docs sync, or merge fan-out results (when needed)
 ```
 
 ## Dispatching work
@@ -106,17 +111,16 @@ You
 ```ts
 // One task
 subagent({
-  agent: "executor",
+  agent: "artisan",
   task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
 });
 
 // Parallel: as many genuinely independent units as the work has
 subagent({
   tasks: [
-    { agent: "explorer", task: "Trace model fallback from dispatch to completion." },
-    { agent: "executor", task: "Add edge-case tests for config migration." },
-    // Optional per-call reasoning strength for a task that needs less of it
-    { agent: "executor", task: "Run the suite and report failures.", thinking: "low" },
+    { agent: "scout", task: "Trace model fallback from dispatch to completion." },
+    { agent: "artisan", task: "Add edge-case tests for config migration." },
+    { agent: "steward", task: "Merge the result artifacts under results/ into one brief." },
   ],
 });
 ```
@@ -140,8 +144,8 @@ main agent inspects the actual changes before calling anything done.
 
 ## Parallel edits
 
-- Single tasks use your checkout. Every parallel write-capable agent (`executor`
-  and custom writers) defaults to a detached Git worktree, so
+- Single tasks use your checkout. Every parallel write-capable agent (`artisan`,
+  `steward`, and custom writers) defaults to a detached Git worktree, so
   parallel writers run at the same time. Worktree mode needs a committed `HEAD`,
   and read-only agents reject it.
 - A role file can pin its own default with `isolation: worktree` or
@@ -213,12 +217,12 @@ two lines: what it is — agent, task, token flow, cost, provider/model, elapsed
 and, dim under the label column, what it is doing right now:
 
 ```text
-● #12 executor  src/cache.ts · worktree:a91f3c · ↑5.2k ↓41.0k R210.0k W6.1k $1.9400 · 12m06s
+● #12 artisan  src/cache.ts · worktree:a91f3c · ↑5.2k ↓41.0k R210.0k W6.1k $1.9400 · 12m06s
   ↳ edit src/auth.ts
-● #15 explorer  src/models.ts · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini · 3m07s
+● #15 scout    src/models.ts · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini · 3m07s
                 ↳ grep fallback
-○ #23 executor  src/config.ts · repo lane
-○ #24 executor ↻  tests/config.test.ts · queued · 5m02s
+○ #23 artisan  src/config.ts · repo lane
+○ #24 artisan ↻  tests/config.test.ts · queued · 5m02s
 ```
 
 Telemetry drops leftmost-first when a row runs out of width (badge, wait
@@ -270,14 +274,13 @@ is missing, rate-limited, or fails at the provider level, the **same retained
 session** continues on the main model, so finished searches, reads, and edits
 survive. Ordinary task failures do not trigger a handoff.
 
-Thinking defaults to **Auto**: the role's own preference, clamped to what the
-effective model supports. `/subagents-setup` → _Configure an agent_ also offers a
-manual strength, listing only the levels that model supports. A dispatch can also
-ask for a strength per call with `thinking`, so a quick check and a deep refactor
-do not have to share one static level. Precedence: your manual
-`/subagents-setup` choice > the per-call `thinking` > the role's frontmatter >
-the default, and the winner is still clamped to the effective model. There is no separate
-vision mode — assign a multimodal model and name the image paths in the task.
+Thinking is a **role default** — scout `low`, artisan `high`, steward
+`medium` — clamped to what the effective model supports. `/subagents-setup` →
+_Configure an agent_ lists only the levels that model supports, with the role
+default marked. There is no Auto choice, no per-dispatch `thinking` flag, and
+no `thinking` field in agent Markdown. Precedence: your setup override > the
+role default, then the model clamp. There is no separate vision mode — assign
+a multimodal model and name the image paths in the task.
 
 Every dispatch, resume, retry, and fallback snapshots the parent's
 currently active tools. A role with no explicit list inherits the full set. An
@@ -297,16 +300,17 @@ child cannot run.
 
 ## Configuration
 
-`/subagents-setup` stays one level deep: enabled agents, plus a model and thinking
-strength per agent. Everything else is config-file only, stored at
+`/subagents-setup` stays one level deep: the team (all three stay on), plus a
+model and optional thinking override per agent. First run explains each role
+before you pick models. Everything else is config-file only, stored at
 `~/.pi/agent/pi-subagents.json` (following `PI_CODING_AGENT_DIR`):
 
 ```json
 {
-  "enabledAgents": ["explorer", "executor"],
-  "knownAgents": ["explorer", "executor"],
-  "agentModels": { "explorer": "anthropic/claude-haiku-4-5" },
-  "agentThinkingLevels": { "executor": "high" },
+  "enabledAgents": ["scout", "artisan", "steward"],
+  "knownAgents": ["scout", "artisan", "steward"],
+  "agentModels": { "scout": "anthropic/claude-haiku-4-5" },
+  "agentThinkingLevels": { "artisan": "high" },
   "maxResultLines": 40,
   "agentScope": "user",
   "idleTimeoutSec": 90
@@ -318,7 +322,7 @@ strength per agent. Everything else is config-file only, stored at
 | `enabledAgents`       | Agents available for discovery and delegation. `[]` disables all.                 |
 | `knownAgents`         | Built-ins this config has seen; automatic bookkeeping — never edit it.            |
 | `agentModels`         | Optional `provider/model-id` per agent; missing = current main model.             |
-| `agentThinkingLevels` | Optional manual level per agent; missing = Auto.                                  |
+| `agentThinkingLevels` | Optional setup override per agent; missing = the role default.                    |
 | `maxResultLines`      | Lines kept in a completion message before the artifact takes over. Default `40`.  |
 | `agentScope`          | Discover `user`, `project`, or `both` agent directories. Default `user`.          |
 | `idleTimeoutSec`      | Seconds without child RPC output before termination; `0` disables. Default `90`.  |
@@ -327,20 +331,22 @@ The delegation directive is always injected; there is no toggle. Invalid values
 fall back safely, and stale keys — including the former `proactiveInjection`,
 `maxConcurrency`, `maxFixRounds`, and `notifyOnReviewPass` knobs — are dropped
 automatically. Built-in roles a newer package no longer ships (such as the
-retired `worker`/`cleaner`/`documenter`/`synthesizer`/`reviewer` set) are pruned
+retired `worker`/`cleaner`/`documenter`/`synthesizer`/`reviewer` set, and the
+renamed `explorer`/`executor` names after they have been mapped) are pruned
 from `enabledAgents`, `knownAgents`, and the model/thinking tables at first
 load, so the setup wizard never mixes old and new roles; custom agents are
-untouched. At session
+untouched. A 4.2 config that still says `explorer`/`executor` is rewritten to
+`scout`/`artisan` and gains `steward`; their model and thinking overrides move
+with the names. That rename lives in `src/config.ts` and will be deleted in
+the next major. At session
 start, model overrides pi no longer reports are removed with a one-time notice. If
 pi's own session compaction fails mid-thread, a notice surfaces the error and the
 automatic retry instead of failing quietly.
 
 Agents shipped by a newer package version turn themselves on at the next
-session: a built-in the config has never seen is adopted into `enabledAgents`
-and follows explorer's configured model and thinking level — the fast lane
-these light roles need — while an agent you disabled stays disabled
-(`knownAgents` is what tells the two cases apart). Enabling a role in
-`/subagents-setup` adopts the same explorer route.
+session. Scout, artisan, and steward stay enabled even if a stale allow-list
+left one off. A one-shot notice then points at `/subagents-setup` so you can
+pick a model for each.
 
 ## Custom agents
 
@@ -352,17 +358,15 @@ Built-ins ship with the package. Add or replace them with Markdown files:
 
 ```yaml
 ---
-name: explorer
+name: scout
 description: Fast read-only codebase reconnaissance
-thinking: low
 isolation: shared
 tools: read, bash
 ---
 …additional system prompt…
 ```
 
-`description` is the routing line the main model reads, and `thinking` is the
-role's Auto preference, which a wizard choice overrides. `isolation` pins the
+`description` is the routing line the main model reads. `isolation` pins the
 role's default boundary as described under [Parallel edits](#parallel-edits).
 Models come only from `/subagents-setup`; an agent file cannot pin one. An
 explicit `tools` list is the capability boundary, and omitting it inherits the
@@ -398,17 +402,19 @@ npm install
 npm run check
 ```
 
-There are no bundled runtime dependencies; pi and TypeBox are peers. The source is
+`npm run check` is `tsc --noEmit` plus the unit tests (`npm test`). There are
+no bundled runtime dependencies; pi and TypeBox are peers. The source is
 split by responsibility: dispatch policy, thread lifecycle, RPC
 transport, worktree integration, completion delivery, tools, and TUI status.
 
 ## Changelog
 
-The 4.2 line lives in [CHANGELOG.md](./CHANGELOG.md). Latest published
-version is **4.2.13**.
+The 4.3 line lives in [CHANGELOG.md](./CHANGELOG.md). Latest published
+version is **4.3.0**.
 
 | Version | What changed |
 | ------- | ------------ |
+| 4.3.0   | Team is `scout` + `artisan` + `steward`; role thinking defaults; config migrate. |
 | 4.2.13  | README navigation, What's new, and this changelog. |
 | 4.2.12  | Confirm-before-fix; honest footer counts; `main` publishes npm + GitHub Release. |
 | 4.2.8   | Footer roll-up; wait-path token usage; hold completions across compaction. |

package/agents/{executor.md → artisan.md}

@@ -1,14 +1,15 @@
 ---
-name: executor
-description: A self-contained unit that changes the repository or condenses inputs — implement, fix, refactor, test, clean up, sync docs, merge fan-out results — carried through verification to a result-only handoff.
-thinking: high
+name: artisan
+description: A self-contained unit that changes the repository — implement, fix, refactor, or test — carried through verification to a result-only handoff.
 # No `tools` field => inherits all tools (full capability).
 ---
 
-You are an executor agent with full capabilities in an isolated context window. You own one delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+You are an artisan with full capabilities in an isolated context window. You own one delegated implementation task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
 
 Repository instructions (AGENTS.md) and any skills available in this session apply to you as to any agent: follow their process for the domains they own (language style, tests, debugging, cleanup discipline, verification). Where a skill covers the same ground as this brief, the skill's discipline wins — except for the release boundary below, which always wins.
 
+Cleanup, documentation sync, and merging fan-out results belong to `steward`. If the brief is only that work, do not improvise it here — say so and stop.
+
 ## Procedure
 
 1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
@@ -17,14 +18,6 @@ Repository instructions (AGENTS.md) and any skills available in this session app
 4. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
 5. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
 
-## Conditional playbooks
-
-Skip both unless the brief matches one.
-
-**Cleanup** (dead code, duplication, simplification): a candidate is not a deletion. Re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report — and search the whole repository for consumers first. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path the brief did not explicitly approve. Finding no safe cut and making zero edits is valid.
-
-**Merging inputs** (result artifacts, reports, logs): read every named input fully before writing, deduplicate restatements into one attributed entry, and report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
-
 ## Boundaries
 
 - Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action, even when repository instructions normally automate release after green checks.

package/agents/{explorer.md → scout.md}

@@ -1,13 +1,12 @@
 ---
-name: explorer
+name: scout
 description: Fast read-only reconnaissance for broad or multi-file search in unfamiliar areas; returns exact paths and compressed findings as retrieval leads.
 tools: read, grep, find, ls, bash
 # At launch, this shell slot follows the parent and parent-active plugin tools
 # are appended; the listed non-shell Pi built-ins remain the permission boundary.
-thinking: low
 ---
 
-You are an explorer agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
+You are a scout: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings so another agent does not repeat the whole search. You have NOT got the caller's conversation history — the task brief is your only input.
 
 ## Hard constraints
 

package/agents/steward.md

@@ -0,0 +1,51 @@
+---
+name: steward
+description: Condenses a finished change or a pile of inputs — evidence-first cleanup, docs/comment sync, or merging fan-out results into one brief.
+# No `tools` field => inherits all tools (full capability).
+---
+
+You are a steward: you tidy, document, or fold inputs together so the caller does not. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+Pick one mode from the brief and skip the others. Finding nothing safe to do and making zero edits is valid.
+
+## Cleanup
+
+A candidate is not a deletion. Re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report — and search the whole repository for consumers first. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path the brief did not explicitly approve.
+
+Honor an explicit scope (uncommitted diff, Git range, directory). With no scope, use the uncommitted work; if the tree is clean, report that nothing is in scope instead of roaming the repository.
+
+## Docs sync
+
+Update comments, README, examples, and user docs to match the code. Never change runtime behavior to make the documentation true. Prefer the current implementation over another document. Do not start a standalone docs pass the brief did not ask for.
+
+## Merging inputs
+
+Read every named input fully before writing. Deduplicate restatements into one attributed entry. Report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
+
+## Boundaries
+
+- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action.
+- Children are leaf processes: you cannot dispatch sub-agents.
+- Implementation, fixes, refactors, and tests belong to `artisan`. If the brief is only that work, say so and stop.
+
+## Output format
+
+Return only the concrete outcome. Do not repeat the task brief, the investigation, or the tool chronology.
+
+## Completed
+
+What was done, in a few lines. For a merge, one brief with conflicts and gaps (omit empty sections).
+
+## Files Changed
+
+- `path/to/file.ts` — what changed. Omit when the mode was read-only merge.
+
+## Verification
+
+Which checks you ACTUALLY ran and their result. State explicitly anything you could not run and why.
+
+## Notes (only when material)
+
+Unresolved blockers, kept candidates that need a product decision, or gaps in the inputs. Omit when nothing actionable.
+
+Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.2.13",
-  "description": "A managed sub-agent team for pi: explorer and executor roles, durable threads, model fallback, and Git worktree isolation.",
+  "version": "4.3.0",
+  "description": "A managed sub-agent team for pi: scout, artisan, and steward roles, durable threads, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,8 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && npm test",
+    "test": "node --experimental-transform-types --test test/*.test.ts",
     "prepack": "npm run check"
   },
   "peerDependencies": {

package/src/agents.ts

@@ -15,7 +15,7 @@ import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "no
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { THINKING_LEVEL_VALUES, type AgentScope, type ThinkingLevel } from "./config.ts";
+import { type AgentScope } from "./config.ts";
 import type { IsolationMode } from "./worktree.ts";
 
 export type AgentSource = "builtin" | "user" | "project";
@@ -26,8 +26,6 @@ export interface AgentConfig {
 	tools?: string[];
 	/** Model ref this run was routed to; filled in by dispatch, never declared by the agent file. */
 	model?: string;
-	/** Per-agent default thinking strength (frontmatter `thinking`); config override wins. */
-	thinking?: ThinkingLevel;
 	/** Role-declared default isolation (frontmatter `isolation`); an explicit
 	 * per-call request wins, and `worktree` applies to write-capable roles only. */
 	isolation?: IsolationMode;
@@ -94,8 +92,8 @@ export function resolveAgentTools(
 export function isWriteCapableAgent(
 	agent: Pick<AgentConfig, "name" | "tools">,
 ): boolean {
-	if (agent.name === "explorer") return false;
-	if (agent.name === "executor") return true;
+	if (agent.name === "scout") return false;
+	if (agent.name === "artisan" || agent.name === "steward") return true;
 	if (!agent.tools) return true;
 	return agent.tools.includes("edit") || agent.tools.includes("write");
 }
@@ -145,10 +143,6 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			?.split(",")
 			.map((t) => t.trim())
 			.filter(Boolean);
-		const rawThinking = str(frontmatter.thinking)?.trim();
-		const thinking = (THINKING_LEVEL_VALUES as readonly string[]).includes(rawThinking ?? "")
-			? (rawThinking as ThinkingLevel)
-			: undefined;
 		const rawIsolation = str(frontmatter.isolation)?.trim();
 		const isolation = rawIsolation === "worktree" || rawIsolation === "shared"
 			? (rawIsolation as IsolationMode)
@@ -158,7 +152,6 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			name,
 			description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			...(thinking ? { thinking } : {}),
 			...(isolation ? { isolation } : {}),
 			systemPrompt: body,
 			source,

package/src/announcements.ts

@@ -2,7 +2,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
-import { loadConfig, saveConfig } from "./config.ts";
+import { FIRST_RUN_SETUP_HINT, loadConfig, saveConfig } from "./config.ts";
 import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
 import { announceRecoveryRecords } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
@@ -39,13 +39,20 @@ async function migrateUnavailableAgentModels(
 export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	pi.on("session_start", async (_event, ctx) => {
 		if (!existsSync(runtime.configPath)) {
-			ctx.ui.notify(
-				"pi-subagents: no configuration yet — run /subagents-setup to pick agents, models, and thinking strengths. Defaults (all built-in agents on the main model) apply until then.",
-				"info",
-			);
+			ctx.ui.notify(`pi-subagents: ${FIRST_RUN_SETUP_HINT}`, "info");
 		}
 		await announceRecoveryRecords(runtime.configPath, ctx);
 		await migrateUnavailableAgentModels(ctx, runtime);
+		try {
+			const config = await loadConfig(runtime.configPath);
+			if (config.pendingSetupNotice) {
+				ctx.ui.notify(`pi-subagents: ${config.pendingSetupNotice}`, "info");
+				const { pendingSetupNotice: _cleared, ...rest } = config;
+				await saveConfig(rest, runtime.configPath);
+			}
+		} catch {
+			/* notice is non-fatal */
+		}
 		// Restore starts at extension load and session_start fires right behind
 		// it, so without this the notice reports whatever the race left behind.
 		await runtime.durableRestore;