@fradser/pi-agent-teams 0.7.0 → 0.8.0

package/.memory/team-centric-design.md

@@ -14,7 +14,7 @@ Exploratory / competitive-hypothesis work (multi-hypothesis debugging, three-way
 2. **Unified messaging**: `send_message(to="leader", message, status?)` is a worker report written to the validated outbox; `send_message(to="<peer>", message)` writes the recipient inbox directly; leader-addressed teammate messages route through a running control stream or idle wake queue. `status` is invalid except for `to="leader"`. The first non-empty message line is the console title.
 3. **Declarative role attributes**: agent frontmatter carries `model`, optional `verify`, and boolean `worktree`.Definitions live in one project directory with filename-based scopes: `<name>.local.md` is project-local (personal, never committed) and dedupes against its `<name>.md` counterpart (project scope, git-managed, team-shared); user-level sits in `~/.pi/agent/agents`; precedence is project-local > project > user > bundled and `resolveAgent` exposes scope + gitManaged for provenance. Spawn has no cwd/model/worktree override; create a role variant instead. `worktree: true` gives every instance of that role a dedicated Git worktree and diff capture at shutdown.
 4. **Residents/wake-ups (constitution: detect and notify, never terminate)**: long-lived RPC children, 8-process session cap; wake-up sequences have NO turn-count or duration caps — no configuration may automatically terminate a working teammate. Turn counts and silence durations are telemetry only. The 500ms harness poll drains outboxes, applies intents, routes inboxes, wakes only for queued deliveries or a paced claimable-task notice, and runs the stall heartbeat: 30 minutes without any RPC output (`PI_TEAMMATE_STALL_NOTICE_MS`, 0 disables) sends the leader one actionable notice per silence episode — that notice is the LAST automatic action; continuing, steering, shutting down, or respawning a context-carrying successor (original kickoff + mailbox reports + board claims + liveText tail) belongs to the leader model alone. Any stream event or prompt delivery resets `lastOutputAt` and clears `stallNoticeSentAt`; steering a silent working teammate returns `stalledMs` so the send_message result warns delivery is uncertain.
-5. **Board**: only leader writes `~/.pi/agent/tasks/<sessionKey>/board.json`; workers use exclusive-create claim/submission marker files. Task completion uses effective task verify or agent verify; failed verification returns stderr to the claimer. The board persists across restarts; runtime state does not.
+5. **Board**: only leader writes `~/.pi/agent/tasks/<sessionKey>/board.json`; workers use exclusive-create claim/submission marker files. Task completion uses effective task verify or agent verify; failed verification returns the reviewer's findings to the claimer. The board persists across restarts; runtime state does not.
 6. **Reliability/UI**: per-spawn identity validation, event/message dedup, crash releases claimed tasks, role worktree diff at shutdown. Widget above the input box shows ONLY working/starting teammates as spinner rows with live activity and hides when nobody is working; idle/stopped teammates live only in the /teammate console roster; spawn prints a legacy-style `[agent] started · @name · task` transcript line; `/teammate` offers roster/board pages and message/task detail.
 7. **Node-native TS**: relative imports use explicit `.ts` extensions (root tsconfig permits them), allowing node to strip-types modules in package tests.
 

package/README.md

@@ -6,7 +6,7 @@ Claude-Code-style collaborative agent teams for Pi: named resident teammates, a
 
 ## What This Package Does
 
-The team leader (your Pi session) spawns named teammates as long-lived child Pi processes in RPC mode. Each teammate has an isolated context, a peer inbox, and access to a shared task board. The harness—not the leader model—polls for activity: it drains leader reports, routes peer mail, applies task claims and submissions, runs deterministic verify gates, and wakes idle teammates only when work or mail exists.
+The team leader (your Pi session) spawns named teammates as long-lived child Pi processes in RPC mode. Each teammate has an isolated context, a peer inbox, and access to a shared task board. The harness—not the leader model—polls for activity: it drains leader reports, routes peer mail, applies task claims and submissions, judges verify prompts with fresh one-shot reviewers, and wakes idle teammates only when work or mail exists.
 
 The message surface is deliberately singular: `send_message` is the only messaging primitive. Workers report with `to: "leader"`; teammates address peers by name; the leader addresses teammates by name. The routing implementation varies by destination (outbox, inbox, or control stream), but callers use one schema.
 
@@ -27,25 +27,39 @@ Agent definitions are Markdown files with frontmatter; the body is the role prom
 name: isolated-security-auditor
 description: Read-only security reviewer in an isolated worktree
 tools: read,bash
-model: provider/model       # optional
-verify: npm test            # optional role-default completion gate
+model: provider/model       # optional; "inherit" = the leader's current model at spawn time
+verify: review prompt       # optional role-default gate; a fresh reviewer answers VERDICT: PASS/FAIL
 worktree: true              # optional role-default Git isolation
 ---
 Review the assigned scope for exploitable security problems. Do not edit files.
 ```
 
-Discovery precedence per name (later overrides earlier):
+Teammate model resolution at spawn time, in precedence order: an explicit
+`provider/model` pin wins; `inherit` pins the leader session's current model;
+without a pin, the unified teammate model set from `/agent-teams` (press `m`
+in the roster page for a type-to-filter picker) applies to this session;
+otherwise Pi picks its own default.
+
+Discovery precedence per name (later overrides earlier): user < project <
+project-local, with generated session roles filling only the names no file
+defines. A re-spawn that supplies an explicit inline definition replaces a
+previously generated session role of the same name; definition files are never
+overwritten by inline input.
 
 There are no built-in roles. When a needed role has no definition, the
-leader creates one on demand: it derives the definition from the task using
-the abstract role reference in `references/agent-roles.md` (definition
-anatomy, archetype axes, invariants), writes the file, and then spawns.
+leader creates it in memory for the current session: it derives the definition
+from the task using the abstract role reference in `references/agent-roles.md`
+(definition anatomy, archetype axes, invariants), registers it, and then spawns.
+The role is not written to disk or reused in a later session unless the user
+explicitly requests persistence; only then may the leader set `definition.persist`
+and choose a project or project-local scope.
 
 | Scope | Location | Git semantics |
 |---|---|---|
 | user | `~/.pi/agent/agents/*.md` | system-level, never committed |
 | project | `<cwd>/.pi/agents/<name>.md` | **git-managed** — commit for the team |
 | project-local | `<cwd>/.pi/agents/<name>.local.md` | **local** — personal override, gitignore by convention |
+| session | in-memory registry | **ephemeral** — disappears at session start, no source file |
 
 A teammate definition is just a Markdown file you own. Shared roles live in `.pi/agents/<name>.md`; a personal tweak to that exact role is `<name>.local.md` in the SAME directory — same teammate name, local scope wins, and discovery deduplicates the pair into one entry (never two). `resolveAgent` reports each definition's `scope` and `gitManaged`; guidance lists both so the leader knows provenance.
 
@@ -80,7 +94,7 @@ task_create({
   subject: "Fix auth middleware findings",
   description: "Address the confirmed security findings in packages/api/src/auth.ts",
   dependsOn: ["t_1"],
-  verify: "npm test"
+  verify: "Every scenario in features/gallery.feature holds in the built gallery; no horizontal overflow at 400px."
 })
 ```
 
@@ -96,7 +110,7 @@ send_message({ to, message, status? })
 - The first non-empty line of `message` becomes the console title.
 - Peer traffic never enters the leader model context; inspect it in `/agent-teams` instead.
 
-Only the leader creates tasks. Idle teammates self-claim pending tasks whose dependencies are met. A task-level `verify` command overrides the claiming agent's frontmatter `verify`; zero exit completes the task, while failure returns stderr to the claimer for fix-and-resubmit.
+Only the leader creates tasks. Idle teammates self-claim pending tasks whose dependencies are met. A task-level `verify` prompt overrides the claiming agent's frontmatter `verify`. The harness runs it as a fresh one-shot reviewer that inspects the work independently and answers `VERDICT: PASS` or `VERDICT: FAIL - <reasons>`; PASS completes the task, FAIL feeds the findings back to the claimer for fix-and-resubmit. Write acceptance criteria a reviewer can check, not shell commands.
 
 ## Tools
 
@@ -118,8 +132,10 @@ That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`,
 - **Per-spawn identity validation**: every leader report must match the teammate's current spawn id; stale callbacks and events cannot affect a replacement with the same name.
 - **Sent means written**: peer `send_message` succeeds only after the recipient inbox write succeeds. The harness owns delivery into a recipient turn.
 - **One writer per state file**: only the leader process writes runtime and board snapshots (atomic tmp+rename). Workers append leader reports to their outbox, peer mail to recipient inboxes, and task intent via exclusive-create marker files.
-- **Completion is gated, not self-reported**: a task completes only after its effective verify gate passes when one exists; no gate means the submission itself completes it.
+- **Completion is gated, not self-reported**: a task completes only after its effective verify gate passes when one exists; no gate means the submission itself completes it. A gate that keeps failing parks the task with its holder after the second consecutive failure and escalates to the leader once instead of looping.
 - **No caps, heartbeat only**: teammates run without turn-count or duration ceilings. The harness heartbeat tracks silence per working teammate and — after 30 minutes without any RPC output (`PI_TEAMMATE_STALL_NOTICE_MS`, 0 disables) — sends the leader one actionable notice per silence episode. The notice is the last automatic action: continuing, steering, shutting down, or respawning a context-carrying successor belongs to the leader alone. Any output or prompt delivery re-arms it, and steering a silent teammate warns that delivery is uncertain.
+- **One-shot board notices**: an idle teammate is told about a claimable task exactly once; declined tasks never re-wake it, and released tasks re-arm. Notices are paced at least five minutes apart per teammate (`PI_TEAMMATE_NOTICE_PACE_MS` overrides in milliseconds).
+- **One end-of-life line per teammate**: the first terminal report of a spawn incarnation renders the finish entry; shutting that incarnation down afterwards adds no second event row.
 - **Failure semantics**: an unexpected crash marks the teammate stopped, reports a diagnostic, and releases its claimed tasks.
 
 ## State and Sessions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Multi-agent team system for Pi — resident teammates, shared task board, and peer-to-peer messaging",
   "keywords": [
     "pi-package",
@@ -39,6 +39,6 @@
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.3.0"
+    "@fradser/pi-kit": "0.4.0"
   }
 }

package/src/agents.ts

@@ -13,8 +13,10 @@
  *   name        — unique agent id (required)
  *   description — routing contract: when the leader should choose this agent
  *   tools       — comma-separated list or YAML list of Pi tool ids
- *   model       — optional provider/model pin
- *   verify      — optional role-default completion gate command (zero exit passes)
+ *   model       — optional provider/model pin, or "inherit" for the leader's
+ *                 current model at spawn time
+ *   verify      — optional role-default completion gate: a review prompt a
+ *                 fresh one-shot reviewer answers with VERDICT: PASS/FAIL
  *   worktree    — optional role-default Git worktree isolation (true/false)
  * The Markdown body is the worker's role prompt.
  */
@@ -24,7 +26,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export type AgentScope = "user" | "project" | "project-local";
+export type AgentScope = "user" | "project" | "project-local" | "session";
 
 export interface AgentDefinition {
   name: string;
@@ -42,8 +44,97 @@ export interface AgentDefinition {
   /** True only for the shared project scope that is expected to be git-managed.
    * user and project-local definitions are machine/personal by definition. */
   gitManaged: boolean;
-  /** Absolute path of the definition file. */
-  source: string;
+  /** Absolute path of the definition file; absent for session-only roles. */
+  source?: string;
+}
+
+export interface AgentDefinitionInput {
+  name: string;
+  description: string;
+  tools: string[];
+  model?: string;
+  verify?: string;
+  worktree?: boolean;
+  prompt: string;
+}
+
+/** Reserved model value meaning "use the leader session's current model",
+ *  resolved at spawn time (Claude-Code-style inherit). */
+export const MODEL_INHERIT_ALIAS = "inherit";
+
+const sessionAgents = new Map<string, AgentDefinition>();
+const AGENT_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
+
+function normalizeAgentInput(input: AgentDefinitionInput): AgentDefinitionInput {
+  const name = input.name.trim();
+  if (!AGENT_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid agent name "${name}". Use letters, digits, dots, dashes, underscores.`);
+  }
+  const prompt = input.prompt.trim();
+  if (!prompt) throw new Error(`Agent "${name}" prompt must not be empty.`);
+  return {
+    ...input,
+    name,
+    description: input.description.trim(),
+    tools: input.tools.map((tool) => tool.trim()).filter(Boolean),
+    model: input.model?.trim() || undefined,
+    verify: input.verify?.trim() || undefined,
+    worktree: input.worktree ?? false,
+    prompt,
+  };
+}
+
+/** Register a generated role for this session without writing a definition file. */
+export function registerSessionAgent(input: AgentDefinitionInput): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const definition: AgentDefinition = {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope: "session",
+    gitManaged: false,
+    source: undefined,
+  };
+  sessionAgents.set(definition.name, definition);
+  return definition;
+}
+
+/** Persist a generated role only when the user explicitly requests it. */
+export function persistAgentDefinition(
+  input: AgentDefinitionInput,
+  scope: "project" | "project-local",
+  cwd = process.cwd(),
+): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const directory = agentsDir("project", cwd);
+  fs.mkdirSync(directory, { recursive: true });
+  const filename = `${normalized.name}${scope === "project-local" ? LOCAL_DEFINITION_SUFFIX : ".md"}`;
+  const source = path.join(directory, filename);
+  const frontmatter = [
+    "---",
+    `name: ${normalized.name}`,
+    `description: ${normalized.description.replace(/[\\r\\n]+/g, " ")}`,
+    `tools: ${normalized.tools.join(", ")}`,
+    ...(normalized.model ? [`model: ${normalized.model}`] : []),
+    ...(normalized.verify ? [`verify: ${normalized.verify.replace(/[\\r\\n]+/g, " ")}`] : []),
+    `worktree: ${normalized.worktree ? "true" : "false"}`,
+    "---",
+    normalized.prompt,
+    "",
+  ].join("\n");
+  fs.writeFileSync(source, frontmatter, { encoding: "utf8", mode: 0o600 });
+  sessionAgents.delete(normalized.name);
+  return {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope,
+    gitManaged: scope === "project",
+    source,
+  };
+}
+
+/** Drop generated session roles; persistent user/project definitions remain discoverable. */
+export function clearSessionAgents(): void {
+  sessionAgents.clear();
 }
 
 /** Shipped role templates: reference material for generating new definitions
@@ -172,6 +263,9 @@ export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
   const agents = new Map<string, AgentDefinition>();
   loadDir("user", agentsDir("user", cwd), agents);
   loadDir("project", agentsDir("project", cwd), agents);
+  // Generated roles fill gaps only: filesystem scopes keep precedence over
+  // session memory.
+  for (const [name, definition] of sessionAgents) if (!agents.has(name)) agents.set(name, definition);
   return agents;
 }
 
@@ -197,7 +291,7 @@ export function formatAgentGuidance(cwd?: string): string {
       agent.model ? `Model: ${agent.model}` : "",
       agent.verify ? `Verify: ${agent.verify}` : "",
       agent.worktree ? "Worktree: true" : "",
-      agent.gitManaged ? "git-managed" : "local",
+      agent.scope === "session" ? "in-memory" : agent.gitManaged ? "git-managed" : "local",
     ].filter(Boolean);
     lines.push(`- **${agent.name}** (${agent.scope})`);
     if (agent.description) lines.push(`  ${agent.description}`);

package/src/guidance.ts

@@ -21,8 +21,9 @@ you consume nothing.
 - The shared task board is coordination state. Read it with task_list, claim
   pending tasks whose dependencies are met with task_claim (claims are
   atomic; losing a race means try another), and submit outcomes with
-  task_submit. Completion may pass through a verify gate: if it fails, stderr
-  feedback arrives in your inbox — fix and resubmit.
+  task_submit. Completion may pass through a verify gate: a fresh reviewer
+  checks the work independently, and on VERDICT: FAIL its findings arrive in
+  your inbox — fix and resubmit.
 - Coordinate file ownership with peers through send_message before writing.
 
 Do not use leader tools (spawning or shutting down teammates, creating
@@ -39,11 +40,16 @@ delegation, synthesis, and the final user-facing answer. Teammates are named
 resident child processes with isolated contexts; they do not see this
 conversation unless you put the needed context in their prompts.
 
-### Agents are declarative files, created on demand
+### Agents are declarative files, with ephemeral generated roles by default
 
-Agents live in Markdown files with frontmatter (name, description, tools,
-optional model, optional verify, optional worktree); the body is the role
-prompt. There are no built-in roles. Discovery precedence per name:
+Persistent agents live in Markdown files with frontmatter (name, description,
+tools, optional model — a provider/model pin or "inherit" for the leader's
+current model at spawn time — optional verify, optional worktree); the body
+is the role prompt. There are no built-in roles. Generated roles are session-scoped
+and held in memory by default: they have no filesystem source and disappear on
+the next session. Do not write
+an agent definition unless the user explicitly asks to keep the role for future
+sessions. Discovery precedence per name:
 project-local \`<cwd>/.pi/agents/<name>.local.md\` > project
 \`<cwd>/.pi/agents/<name>.md\` > user \`~/.pi/agent/agents\`. Same-name
 project/project-local pairs deduplicate into one definition, with
@@ -55,14 +61,18 @@ to differ.
 Available agents:
 ${agents}
 
+Definitions are resolved live at spawn time: if a spawn says a listed role is
+gone, its definition file changed mid-session — recreate it on demand instead
+of retrying.
+
 When an assignment or user request needs an agent whose name has no
-definition yet, create it first: derive it from the shipped abstract role
-reference at \`${AGENT_REFERENCE_PATH}\` — its definition anatomy, archetype
-axes, and invariants (read it before inventing a novel role) — tailor it to
-the task, and write
-the definition to \`<cwd>/.pi/agents/<name>.md\` for a git-managed project
-role or \`<name>.local.md\` for a personal override; discovery picks it up
-immediately and spawning can proceed.
+definition yet, create it in memory first: derive it from the shipped abstract
+role reference at \`${AGENT_REFERENCE_PATH}\` — its definition anatomy,
+archetype axes, and invariants (read it before inventing a novel role) — tailor
+it to the task, register the session role, and spawn immediately. Only after an
+explicit request to keep the role for future sessions should you set
+\`definition.persist=true\` (optionally choosing \`persistScope\`) so the spawn
+writes \`<cwd>/.pi/agents/<name>.md\` or \`<name>.local.md\`.
 
 ### Build a team in one step per teammate
 
@@ -87,9 +97,11 @@ context — inspect it in /agent-teams instead.
 
 Create shared work with task_create(subject, description?, dependsOn?,
 verify?). Idle teammates notice claimable work automatically and self-claim;
-dependencies unlock downstream tasks without your involvement. An explicit
-verify command makes completion deterministic: zero exit completes, failure
-feeds stderr back to the claimer for fix-and-resubmit.
+dependencies unlock downstream tasks without your involvement. The verify
+prompt is judged by a fresh one-shot reviewer that inspects the work itself:
+VERDICT: PASS completes, FAIL feeds the reviewer's findings back to the
+claimer for fix-and-resubmit. Write gates as acceptance criteria a reviewer
+can check (behavior, constraints, evidence), not as shell commands.
 
 ### Teammates are autonomous: recover, never punish
 

package/src/index.ts

@@ -8,7 +8,8 @@
 import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildTeamLeaderGuidance, WORKER_GUIDANCE } from "./guidance.ts";
-import { initTeamMachine, removeRuntimeDir, shutdownTeamMachine, teardownTeammates } from "./team-machine.ts";
+import { clearSessionAgents } from "./agents.ts";
+import { initTeamMachine, markTeammateFinished, removeRuntimeDir, shutdownTeamMachine, teardownTeammates } from "./team-machine.ts";
 import { cleanupExpiredStateDirs } from "./statefile.ts";
 import { resetState } from "./state.ts";
 import { ensureTeamWidget, refreshTeamUI, stopUiTimers } from "./ui.ts";
@@ -23,9 +24,6 @@ const STATE_DIR_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 let leaderPi: ExtensionAPI | undefined;
 let leaderCtx: ExtensionContext | undefined;
 let followUpQueue: FollowUpQueue | undefined;
-// One "Teammate finished" announcement per spawn incarnation; repeated
-// terminal reports from the same resident stay ordinary report rows.
-const announcedFinishKeys = new Set<string>();
 
 const REPORT_COLORS = ["success", "warning", "error", "mdLink"] as const;
 export const TEAMMATE_FINISHED_ENTRY_TYPE = "agent-teams-teammate-finished";
@@ -91,7 +89,7 @@ export default function (pi: ExtensionAPI) {
     if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
     const reports = extractReports(event.message.details);
     for (const report of reports) {
-      if (!markTeammateFinished(announcedFinishKeys, report)) continue;
+      if (!markTeammateFinished(report)) continue;
       pi.appendEntry(TEAMMATE_FINISHED_ENTRY_TYPE, {
         teammate: report.teammate ?? report.agent,
         agent: report.agent,
@@ -100,9 +98,9 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    clearSessionAgents();
     resetState();
     followUpQueue?.reset();
-    announcedFinishKeys.clear();
     leaderCtx = ctx;
     followUpQueue = new FollowUpQueue({
       isIdle: () => Boolean(leaderCtx?.isIdle()),
@@ -162,21 +160,3 @@ function extractReports(details: unknown): FollowUpReport[] {
   if (typed && "teammate" in typed) return [typed as FollowUpReport];
   return [];
 }
-
-/**
- * Announce a finished entry only on the first terminal report of a spawn
- * incarnation. Reports without a spawn identity key on the session scope so
- * crash diagnostics always stay visible. Returns true when the caller should
- * append the finished entry.
- */
-export function markTeammateFinished(
-  seen: Set<string>,
-  report: Pick<FollowUpReport, "teammate" | "agent" | "spawnId" | "finished">,
-): boolean {
-  if (!report.finished) return false;
-  const name = report.teammate ?? report.agent ?? "teammate";
-  const key = `${name}:${report.spawnId ?? "session"}`;
-  if (seen.has(key)) return false;
-  seen.add(key);
-  return true;
-}

package/src/picker-keys.ts

@@ -0,0 +1,30 @@
+/**
+ * Keystroke routing for the teammate-model picker. Pure mapping from raw
+ * terminal input to picker actions so the collision-prone decision table is
+ * unit-testable without a TUI: every printable character (letters included)
+ * must route to typing, never to a shortcut.
+ */
+
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+
+export type PickerKeyAction =
+  | { kind: "type"; text: string }
+  | { kind: "backspace" }
+  | { kind: "up" }
+  | { kind: "down" }
+  | { kind: "confirm" }
+  | { kind: "cancel" };
+
+/** Map one raw input event to a picker action, or undefined when the event
+ *  is not a picker key (multi-byte pastes, unhandled control sequences). */
+export function mapPickerKey(data: string): PickerKeyAction | undefined {
+  if (matchesKey(data, Key.escape)) return { kind: "cancel" };
+  if (matchesKey(data, Key.enter)) return { kind: "confirm" };
+  if (matchesKey(data, Key.up)) return { kind: "up" };
+  if (matchesKey(data, Key.down)) return { kind: "down" };
+  if (matchesKey(data, Key.backspace) || matchesKey(data, Key.delete)) return { kind: "backspace" };
+  // Printable characters are always search text — letters like "c" must
+  // never double as shortcuts in a type-to-filter list.
+  if (data.length === 1 && data >= " ") return { kind: "type", text: data };
+  return undefined;
+}

package/src/state.ts

@@ -13,6 +13,7 @@ import {
   type TeamState,
   type WorkerReportEvent,
 } from "./types.ts";
+import { nonEmpty } from "@fradser/pi-kit";
 
 export const MAX_LEADER_MAILBOX_MESSAGES = 4096;
 /** FIFO cap of remembered peer message ids per inbox (dedup guard). */
@@ -22,10 +23,9 @@ export const MAX_TASK_DEPENDENCIES = 32;
 function emptyState(): TeamState {
   return {
     teammates: {},
-    tasks: {},
+    tasks: emptyTaskMap(),
     leaderMailbox: [],
     messageCounter: 0,
-    taskCounter: 0,
     workerEventOffsets: {},
     workerEventIds: {},
     peerInboxOffsets: {},
@@ -58,11 +58,30 @@ function nextMessageId(): string {
   return `msg_${++state.messageCounter}`;
 }
 
+/** Task maps must not inherit Object.prototype: slug ids like "constructor"
+ *  are legal task ids and must never alias inherited properties. */
+function emptyTaskMap(): Record<string, BoardTask> {
+  return Object.create(null);
+}
+
 export function resetState(): void {
   state = emptyState();
   markStateDirty();
 }
 
+// ── Team default model ──────────────────────────────────────
+
+/** The unified teammate model for this session, or undefined when Pi picks. */
+export function getTeamDefaultModel(): string | undefined {
+  return state.defaultModel;
+}
+
+/** Set (or clear with undefined) the unified teammate model for later spawns. */
+export function setTeamDefaultModel(ref: string | undefined): void {
+  state.defaultModel = nonEmpty(ref);
+  markStateDirty();
+}
+
 // ── Roster queries ────────────────────────────────────────────────
 
 const NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
@@ -204,6 +223,26 @@ export function setPeerInboxOffset(inboxName: string, offset: number): void {
 
 // ── Board: creation and queries ───────────────────────────────────
 
+/** Maximum characters in a generated slug task id (suffix included). */
+const MAX_TASK_ID_LENGTH = 48;
+
+/** A readable, filesystem-safe id derived from the subject:
+ *  "Polish login flow" -> "polish-login-flow"; duplicates get -2, -3, ... */
+export function taskIdFromSubject(subject: string, taken: ReadonlySet<string>): string {
+  const base = subject
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_TASK_ID_LENGTH)
+    .replace(/-+$/g, "") || "task";
+  let id = base;
+  for (let n = 2; taken.has(id); n++) {
+    const suffix = `-${n}`;
+    id = base.slice(0, Math.max(1, MAX_TASK_ID_LENGTH - suffix.length)).replace(/-+$/g, "") + suffix;
+  }
+  return id;
+}
+
 export function createTask(input: {
   subject: string;
   description?: string;
@@ -219,7 +258,7 @@ export function createTask(input: {
   for (const dep of dependsOn) {
     if (!state.tasks[dep]) return { ok: false, error: `Task depends on unknown task "${dep}".` };
   }
-  const id = `t_${++state.taskCounter}`;
+  const id = taskIdFromSubject(subject, new Set(Object.keys(state.tasks)));
   const task: BoardTask = {
     id,
     subject,
@@ -350,8 +389,6 @@ export function loadBoard(tasks: Record<string, BoardTask>): number {
       updatedAt: Date.now(),
     };
     state.tasks[restored.id] = restored;
-    const numeric = Number(restored.id.slice(2));
-    if (Number.isFinite(numeric)) state.taskCounter = Math.max(state.taskCounter, numeric);
     reloaded++;
   }
   if (reloaded > 0) markStateDirty();