pi-better-harness 0.11.0 → 0.12.0

package/node_modules/pi-better-subagents/README.md

@@ -44,11 +44,14 @@ nontrivial role-owned task, while the foreground coordinates, integrates, and
 verifies. See [usage notes](docs/usage.md#delegation-mode).
 
 `agents_catalog` shows each role's and named agent's default model and effort,
-such as `default openai/gpt-6-sol@high`. To launch on that default, omit
+such as `role developer "Developer" … default openai/gpt-6-sol@high`. Roles are
+listed and passed by short name (`role: "developer"`); the stored id
+`role.developer` also works, and named agents keep their full id
+(`agent: "agent.payments"`). To launch on that default, omit
 `model` and `thinking` on a role or agent spawn; name one only for a stated
 reason. When a launch's model or effort differs from the default, its launch
 line says so, for example
-`model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`.
+`model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`.
 
 ## When To Use
 

package/node_modules/pi-better-subagents/agent-commands.ts

@@ -15,7 +15,9 @@ import {
     CATALOG_SCHEMA_VERSION,
     DiagnosticCodes,
     EFFORT_LEVELS,
+    canonicalRoleId,
     parseDefinition,
+    shortRoleName,
     type AgentDefinition,
     type Diagnostic,
     type InstructionMode,
@@ -52,9 +54,9 @@ const KNOWN_FLAGS = new Set(["role", "scope", "name", "id", "mode", "description
 const USAGE = [
     "/agents list",
     "/agents show <id>    (inspect is the same command)",
-    "/agents create [--role <role-id>] [--name <name>] [--scope user|project] [--mode add|replace] [--instructions <text>] [--model <provider/model>] [--effort <level>] [--tier <label>]",
+    "/agents create [--role <role>] [--name <name>] [--scope user|project] [--mode add|replace] [--instructions <text>] [--model <provider/model>] [--effort <level>] [--tier <label>]",
     "/agents reload",
-    "/agents import-codex <file.toml> [--scope user|project] [--role <role-id>]",
+    "/agents import-codex <file.toml> [--scope user|project] [--role <role>]",
     "Create and import write to the personal catalog unless --scope project is set.",
     "Import confirms one base role and replace mode. It does not scan .codex/agents.",
 ].join("\n");
@@ -263,14 +265,14 @@ async function runCreate(
     deps: AgentCommandDeps,
 ): Promise<AgentCommandResult> {
     if (parsed.positionals.length > 1) {
-        return result("error", "create", false, "create takes flags, not a bare role name. Use --role <role-id>. Nothing was written.");
+        return result("error", "create", false, "create takes flags, not a bare role name. Use --role <role>. Nothing was written.");
     }
     const scope = readScope(parsed.flags);
     if (scope.error) return result("error", "create", false, `${scope.error} Nothing was written.`);
     if (scope.value === "project" && !loc.projectTrusted) return untrusted("create");
     const snapshot = readCatalog(loc);
     const roles = catalogRoles(snapshot);
-    let roleIds = [...(parsed.flags.get("role") ?? [])];
+    let roleIds = (parsed.flags.get("role") ?? []).map(canonicalRoleId);
     if (roleIds.length > 1) {
         const decision = await resolveRoleAssignment(roleIds.map((roleId) => ({ roleId })), {
             hasUI: host.hasUI,
@@ -284,7 +286,7 @@ async function runCreate(
     let roleId = roleIds[0];
     if (!roleId) {
         if (!host.hasUI) {
-            return clarification("create", `create needs --role <role-id>. UI is unavailable, so no role was chosen. Roles: ${roles.map((role) => role.id).join(", ") || "none"}. Nothing was written.`);
+            return clarification("create", `create needs --role <role>. UI is unavailable, so no role was chosen. Roles: ${roles.map((role) => shortRoleName(role.id)).join(", ") || "none"}. Nothing was written.`);
         }
         if (roles.length === 0) return result("error", "create", false, "No roles are available to use as a base. Nothing was written.");
         const selected = await host.ui.select("Choose one base role", roles.map(roleOption));
@@ -292,7 +294,7 @@ async function runCreate(
         roleId = selected.split(" ")[0];
     }
     if (!roleId || !roles.some((role) => role.id === roleId)) {
-        return result("error", "create", false, `Unknown role ${roleId ?? ""}. Nothing was written. Use /agents list and pass one role id.`);
+        return result("error", "create", false, `Unknown role ${shortRoleName(roleId ?? "")}. Valid roles: ${roles.map((role) => shortRoleName(role.id)).join(", ") || "none"}. Nothing was written.`);
     }
     let name = parsed.flags.get("name")?.[0];
     if (!name?.trim()) {
@@ -407,7 +409,7 @@ async function runImport(
     const roles = catalogRoles(snapshot);
     if (roles.length === 0) return result("error", "import-codex", false, "No roles are available to use as the one base role. Nothing was imported.");
     const suggestion = suggestBaseRoles(`${document.name}\n${document.description}\n${document.developerInstructions}`, roles);
-    const requestedRoles = [...(parsed.flags.get("role") ?? [])];
+    const requestedRoles = (parsed.flags.get("role") ?? []).map(canonicalRoleId);
     if (requestedRoles.length > 1) {
         const decision = await resolveRoleAssignment(requestedRoles.map((roleId) => ({ roleId })), {
             hasUI: host.hasUI,
@@ -420,7 +422,7 @@ async function runImport(
     }
     let roleId = requestedRoles[0];
     if (roleId && !roles.some((role) => role.id === roleId)) {
-        return result("error", "import-codex", false, `Unknown role ${roleId}. Nothing was imported.`);
+        return result("error", "import-codex", false, `Unknown role ${shortRoleName(roleId)}. Valid roles: ${roles.map((role) => shortRoleName(role.id)).join(", ")}. Nothing was imported.`);
     }
     const sourceRef = codexSourceRef(resolved);
     const existingLookup = matchExisting(listScopeAgents(loc, scope.value).agents, document.proposedId, sourceRef);

package/node_modules/pi-better-subagents/agent-inspection.ts

@@ -8,7 +8,7 @@
  * and a catalog block stays not launchable even if enrichment disagrees.
  */
 import { inspectCatalog, listCatalog, type CatalogInspection } from "./catalog-resolver.ts";
-import { formatDiagnostic, type Diagnostic } from "./catalog-schema.ts";
+import { formatDiagnostic, shortRoleName, type Diagnostic } from "./catalog-schema.ts";
 import type { CatalogSnapshot } from "./catalog-store.ts";
 import { loadConfig, normalizeTools, SAFE_DEFAULT_TOOLS, type SubagentConfig } from "./config.ts";
 import { resolveExtensions } from "./extensions.ts";
@@ -227,7 +227,7 @@ export function presentCatalog(snapshot: CatalogSnapshot, enrich?: LaunchEnriche
         "Definition validity is not launchability. Model availability is decided only by the injected resolver.",
         ...snapshot.diagnostics.map((diagnostic) => formatDiagnostic(diagnostic)),
         ...entries.flatMap((entry) => [
-            entry.text.split("\n")[0] ?? entry.id,
+            renderCatalogListLine(entry),
             `  description: ${JSON.stringify(entry.identity.description ?? "")}`,
         ]),
     ];
@@ -361,10 +361,10 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
     return view;
 }
 
-export function renderOperationView(view: OperationView): string {
-    const header = [
+function renderHeader(view: OperationView, shownId: string): string {
+    return [
         view.identity.kind ?? "missing",
-        view.id,
+        shownId,
         view.identity.name ? JSON.stringify(view.identity.name) : "unnamed",
         `scope=${view.identity.scope ?? "none"}`,
         `definitionValid=${yesNo(view.definitionValid)}`,
@@ -372,6 +372,19 @@ export function renderOperationView(view: OperationView): string {
         `launchable=${view.launchable === null ? "unknown" : yesNo(view.launchable)}`,
         ...(view.defaults ? [`default ${view.defaults.label}`] : []),
     ].join(" ");
+}
+
+/**
+ * One `agents_catalog` list line. A role shows its short name (`role developer
+ * "Developer" …`), which is what the `role` field accepts; a named agent keeps
+ * its full id. Inspect output and structured details keep the full id.
+ */
+export function renderCatalogListLine(view: OperationView): string {
+    return renderHeader(view, view.identity.kind === "role" ? shortRoleName(view.id) : view.id);
+}
+
+export function renderOperationView(view: OperationView): string {
+    const header = renderHeader(view, view.id);
     const lines = [
         header,
         `identity: id=${view.id} kind=${view.identity.kind ?? "unknown"} name=${JSON.stringify(view.identity.name ?? "")} description=${JSON.stringify(view.identity.description ?? "")}`,

package/node_modules/pi-better-subagents/agents-catalog-tool.ts

@@ -4,6 +4,7 @@
  * collected. This module does not write files.
  */
 import { presentCatalog, presentCatalogEntry, type LaunchEnricher } from "./agent-inspection.ts";
+import { canonicalCatalogId } from "./catalog-schema.ts";
 import { defaultUserRoot, loadCatalog } from "./catalog-store.ts";
 
 type TypeModule = {
@@ -41,6 +42,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
         promptSnippet: "List and inspect catalog roles and named agents, including inheritance and whether launchability is known.",
         promptGuidelines: [
             "Use agents_catalog to discover roles and named agents before subagent_spawn. It is read-only.",
+            "Roles are listed by short name. Pass that name as role (role: \"developer\"). Pass a named agent by its full id (agent: \"agent.payments\").",
             "Do not treat a valid definition as launchable. definitionValid and catalogLaunchable do not select a model or start a child.",
             "A role name or instruction that says read-only is not enforcement. Unsupported execution restrictions stay blocking.",
             "Ask the user to run /agents create or /agents import-codex for writes. Those commands confirm role, scope, and import replacement.",
@@ -50,7 +52,7 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
         ],
         parameters: Type.Object({
             action: Type.String({ description: "list or inspect. No other action is accepted." }),
-            id: Type.Optional(Type.String({ description: "Role or agent id for inspect. Display names and filenames are not ids." })),
+            id: Type.Optional(Type.String({ description: "What to inspect: a role's short name (developer) or a named agent's id (agent.payments). The prefixed role id (role.developer) also works. Display names and filenames are not ids." })),
         }),
         async execute(
             _toolCallId: string,
@@ -72,8 +74,8 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
                     details: { action, wrote: false, revision: listed.revision, entries: listed.entries, diagnostics: listed.diagnostics },
                 };
             }
-            if (!params.id?.trim()) return toolError("inspect needs an id. Call agents_catalog with action list to see ids. Nothing was written.");
-            const view = presentCatalogEntry(loadCatalog(host), params.id.trim(), deps.enrich);
+            if (!params.id?.trim()) return toolError("inspect needs a role name or agent id. Call agents_catalog with action list to see them. Nothing was written.");
+            const view = presentCatalogEntry(loadCatalog(host), canonicalCatalogId(params.id), deps.enrich);
             return {
                 content: [{ type: "text" as const, text: view.text }],
                 details: { action, wrote: false, view },

package/node_modules/pi-better-subagents/catalog-resolver.ts

@@ -8,6 +8,7 @@
 import {
     DiagnosticCodes,
     hasBlockingDiagnostic,
+    shortRoleName,
     type CatalogDefinition,
     type CatalogKind,
     type Diagnostic,
@@ -161,9 +162,12 @@ export function listCatalog(snapshot: CatalogSnapshot): CatalogListEntry[] {
 export function inspectCatalog(snapshot: CatalogSnapshot, id: string): CatalogInspection {
     const entry = findEntry(snapshot, id);
     if (!entry) {
+        const isAgent = id.trim().toLowerCase().startsWith("agent.");
         const diagnostic = blockedDiagnostic(
-            id.startsWith("agent.") ? DiagnosticCodes.unknownAgent : DiagnosticCodes.unknownRole,
-            `No catalog definition has id ${id}. Check the id, or reload after adding the file. Display names and filenames are not ids.`,
+            isAgent ? DiagnosticCodes.unknownAgent : DiagnosticCodes.unknownRole,
+            isAgent
+                ? `No catalog definition has id ${id}. Check the id, or reload after adding the file. Display names and filenames are not ids.`
+                : `No role named ${shortRoleName(id)}. ${validRolesSentence(snapshot)} Check the name, or reload after adding the file. Display names and filenames are not ids.`,
             id,
         );
         return {
@@ -212,7 +216,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
         return {
             status: "not-found",
             launchable: false,
-            diagnostics: [blockedDiagnostic(DiagnosticCodes.unknownRole, `Unknown role ${roleId}. It was not launched.`, roleId)],
+            diagnostics: [blockedDiagnostic(DiagnosticCodes.unknownRole, `Unknown role ${shortRoleName(roleId)}. ${validRolesSentence(snapshot)} It was not launched.`, roleId)],
         };
     }
     if (entry.duplicate || !entry.definition || entry.definition.kind !== "role") {
@@ -393,6 +397,16 @@ function absentField<T>(): FieldValue<T> {
     return { value: null, source: "absent", explicit: false };
 }
 
+/** Valid short role names, for an unknown-role message. */
+function validRoleNames(snapshot: CatalogSnapshot): string[] {
+    return [...snapshot.roles.keys()].map(shortRoleName).sort();
+}
+
+function validRolesSentence(snapshot: CatalogSnapshot): string {
+    const names = validRoleNames(snapshot);
+    return names.length > 0 ? `Valid roles: ${names.join(", ")}.` : "No roles are defined.";
+}
+
 function findEntry(snapshot: CatalogSnapshot, id: string): CatalogEntry | undefined {
     return snapshot.roles.get(id) ?? snapshot.agents.get(id) ?? snapshot.blocked.find((entry) => entry.id === id);
 }

package/node_modules/pi-better-subagents/catalog-runtime.ts

@@ -22,7 +22,7 @@ import {
 import { allocateCatalogLabel } from "./catalog-identity.ts";
 import { resolveRoleAssignment, type RoleAssignment } from "./role-assignment.ts";
 import { configureTierPolicy, DEFAULT_TIER_POLICY, type TierPolicy, type TierSpec } from "./tier-policy.ts";
-import type { Diagnostic, ThinkingLevel } from "./catalog-schema.ts";
+import { canonicalAgentId, canonicalRoleId, shortRoleName, type Diagnostic, type ThinkingLevel } from "./catalog-schema.ts";
 
 export interface CatalogHost {
     cwd: string;
@@ -256,14 +256,14 @@ export async function clarifyCatalogRequest(
  * Launch-line note for a catalog run whose effective model or effort differs
  * from the role or agent default. The wording names the cause, so a fallback
  * or a capped effort is not mistaken for a caller override:
- * - override: `model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`
- * - fallback: `model xai/grok-4.7@high (role default openai/gpt-6-sol@high unavailable; foreground fallback)`
- * - capped effort: `model openai/gpt-6-sol@medium (role default openai/gpt-6-sol@high; effort capped at medium by the model)`
+ * - override: `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`
+ * - fallback: `model xai/grok-4.7@high (role developer default openai/gpt-6-sol@high unavailable; foreground fallback)`
+ * - capped effort: `model openai/gpt-6-sol@medium (role developer default openai/gpt-6-sol@high; effort capped at medium by the model)`
  * Undefined for a non-catalog run, a definition with no default, or a launch
  * that matches the default. Only the fields the definition sets are compared.
  */
 export function catalogDefaultNote(
-    record: Pick<CatalogRunRecord, "kind" | "effective" | "modelSelection" | "effortSelection"> | undefined,
+    record: Pick<CatalogRunRecord, "kind" | "effective" | "modelSelection" | "effortSelection"> & { id?: string } | undefined,
     model: string | undefined,
     thinking: string | undefined,
 ): string | undefined {
@@ -279,8 +279,10 @@ export function catalogDefaultNote(
     const effortDiffers = defaultEffort !== null && (thinking ?? null) !== defaultEffort;
     if (!modelDiffers && !effortDiffers) return undefined;
     const actual = formatModelEffort(model ?? "Pi default", thinking) ?? "Pi default";
+    // A role run names its short role (`role developer default …`); an agent run keeps `agent default …`.
+    const owner = record.kind === "role" && record.id ? `role ${shortRoleName(record.id)}` : record.kind;
     const causes = [
-        modelFallback ? `${record.kind} default ${defaultLabel} unavailable; ${FALLBACK_LABELS[modelSource!] ?? modelSource} fallback` : `${record.kind} default ${defaultLabel}`,
+        modelFallback ? `${owner} default ${defaultLabel} unavailable; ${FALLBACK_LABELS[modelSource!] ?? modelSource} fallback` : `${owner} default ${defaultLabel}`,
         ...(effortCapped ? [`effort capped at ${thinking ?? "the model default"} by the model`] : []),
     ];
     return `model ${actual} (${causes.join("; ")})`;
@@ -547,8 +549,7 @@ async function allocateDirectRoleLabel(input: { roleId: string; roleName: string
 }
 
 export function roleSlug(roleId: string): string {
-    const raw = roleId.startsWith("role.") ? roleId.slice("role.".length) : roleId;
-    return raw.trim().toLowerCase();
+    return shortRoleName(roleId).trim().toLowerCase();
 }
 
 function composePrompt(instructions: string, task: string): string {
@@ -558,7 +559,28 @@ function composePrompt(instructions: string, task: string): string {
 }
 
 function agentIdOf(job: { agent?: unknown }): string | undefined {
-    return typeof job.agent === "string" && job.agent.trim() !== "" ? job.agent.trim() : undefined;
+    return typeof job.agent === "string" && job.agent.trim() !== "" ? canonicalAgentId(job.agent) : undefined;
+}
+
+/**
+ * Error text for a selector that is present but blank (`role: "  "`,
+ * `agent: ""`, or an empty or blank role array). Absent or null means no
+ * selector and returns undefined. `where` names the field's owner, such as
+ * `shared` or `jobs[1]`.
+ */
+export function blankCatalogSelector(input: { agent?: unknown; role?: unknown } | undefined, where?: string): string | undefined {
+    if (!input) return undefined;
+    const field = (name: string) => (where ? `${where}.${name}` : name);
+    const blank = (value: unknown) => typeof value !== "string" || value.trim() === "";
+    if (input.agent !== undefined && input.agent !== null && blank(input.agent)) {
+        return `${field("agent")} is blank. Pass a named agent id such as agent.payments, or omit agent. No child was started.`;
+    }
+    const role = input.role;
+    if (role === undefined || role === null) return undefined;
+    if (Array.isArray(role) ? role.length === 0 || role.some(blank) : blank(role)) {
+        return `${field("role")} is blank. Pass a role name such as developer, or omit role. No child was started.`;
+    }
+    return undefined;
 }
 
 function roleIdsOf(job: { role?: unknown; roleIds?: unknown }): string[] {
@@ -569,8 +591,11 @@ function roleIdsOf(job: { role?: unknown; roleIds?: unknown }): string[] {
     const ids: string[] = [];
     for (const value of values) {
         if (typeof value !== "string") continue;
-        const trimmed = value.trim();
-        if (trimmed && !ids.includes(trimmed)) ids.push(trimmed);
+        // A bare name (`developer`) and the prefixed id (`role.developer`) are
+        // the same role. The canonical id always starts with `role.`, so a
+        // role field never reaches an `agent.*` named agent.
+        const id = canonicalRoleId(value);
+        if (id && !ids.includes(id)) ids.push(id);
     }
     return ids;
 }

package/node_modules/pi-better-subagents/catalog-schema.ts

@@ -252,6 +252,40 @@ export function kindForId(id: string): CatalogKind | undefined {
     return undefined;
 }
 
+/** Prefix every role id carries. Stored ids and files keep it; people type and read the short name. */
+export const ROLE_ID_PREFIX = "role.";
+
+/** Short, user-facing role name: `role.developer` becomes `developer`. Any other id is returned unchanged. */
+export function shortRoleName(id: string): string {
+    return id.startsWith(ROLE_ID_PREFIX) ? id.slice(ROLE_ID_PREFIX.length) : id;
+}
+
+/**
+ * Canonical role id for a value typed into a `role` field. Trimmed and
+ * lowercased; a bare name gains the `role.` prefix, so `Developer` becomes
+ * `role.developer`. The result always starts with `role.`, so a role field
+ * can never select an `agent.*` named agent.
+ */
+export function canonicalRoleId(value: string): string {
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed === "") return trimmed;
+    return trimmed.startsWith(ROLE_ID_PREFIX) ? trimmed : `${ROLE_ID_PREFIX}${trimmed}`;
+}
+
+/** Canonical named-agent id: trimmed and lowercased, since ids are lowercase-only. */
+export function canonicalAgentId(value: string): string {
+    return value.trim().toLowerCase();
+}
+
+/**
+ * Canonical id for a field that takes either kind, such as `agents_catalog`
+ * inspect. An `agent.` id (any case) is lowercased; anything else is read as a role.
+ */
+export function canonicalCatalogId(value: string): string {
+    const lowered = value.trim().toLowerCase();
+    return lowered.startsWith("agent.") ? lowered : canonicalRoleId(lowered);
+}
+
 export function isPreferenceKey(value: string): value is PreferenceKey {
     return (PREFERENCE_KEYS as readonly string[]).includes(value);
 }

package/node_modules/pi-better-subagents/delegation.ts

@@ -15,7 +15,7 @@ export function delegationPrompt(mode: DelegationMode): string {
         case "manual":
             return "Delegation mode: manual. Do not proactively delegate work. Use subagents only when the user explicitly asks for delegation or an active workflow explicitly requires it. A structured plan or plan mode does not override this restriction; perform planned work in the foreground unless explicitly required otherwise.";
         case "coordinator":
-            return "Delegation mode: coordinator. The foreground coordinates, integrates, and verifies. Call agents_catalog to discover current available roles and inspect their descriptions. Delegate every nontrivial task covered by an available role according to its current description; do not assume bundled roles are unchanged. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground. Inspect results and failures before concluding; do not poll for running children.";
+            return "Delegation mode: coordinator. The foreground coordinates, integrates, and verifies. Call agents_catalog to discover current available roles and inspect their descriptions. Pass a role to subagent_spawn by its short name, as listed (role: \"developer\"). Delegate every nontrivial task covered by an available role according to its current description; do not assume bundled roles are unchanged. Keep orchestration, cross-role decisions, unowned or ambiguous work, integration, and final verification in the foreground. Inspect results and failures before concluding; do not poll for running children.";
         case "adaptive":
             return "Delegation mode: adaptive. Delegate bounded, substantial independent work when a suitable subagent is available and useful; continue unblocked foreground work. Keep small, tightly coupled, or interactive work in the foreground. Inspect and integrate delegated results before final verification; do not poll.";
     }

package/node_modules/pi-better-subagents/docs/agent-catalog-lifecycle.md

@@ -6,6 +6,8 @@ Catalog launches use the existing `spawnSubagentRun` path. There is no second sc
 
 `subagent_spawn`, batch `shared`, and each batch job accept optional `agent`, `role`, and `alias`.
 
+- `role` takes a role's short name (`role: "developer"`). It is trimmed and case-insensitive, and the stored id (`role.developer`) also works. A bare name only ever selects a role, never an `agent.*` named agent. An unknown name fails and lists the valid role names. `agent` ids are trimmed and lowercased the same way.
+- A `role` or `agent` that is present but blank (`role: "  "`) is rejected before any launch. Only an absent field means no selector.
 - A per-job `agent` or `role` replaces the shared selector pair. It does not combine `shared.agent` with `job.role`.
 - `model` and `thinking` still merge per field. Per-job wins.
 - One agent or one role is a normal launch. Both, or more than one role id, asks the UI to choose one or split into separate runs.
@@ -28,7 +30,7 @@ The first `meta.json` write stores the launched `model` and `effort` plus a JSON
 
 A named agent displays its defined name. A direct role asks `allocateCatalogLabel({ roleId, roleName, alias })` when that module is present. `roleName` is the slug (`developer`), not `role.developer`. The label is allocated in the local run registry. An explicit `alias` (or the legacy `name` when `alias` is omitted) is the alias; collisions are the allocator's numeric suffix. Batch-generated `job-N` labels are not aliases.
 
-Navigator rows keep the display name, model, and effort. Details include the run id and, for catalog runs, the role id.
+Navigator rows keep the display name, model, and effort. Details include the run id and, for catalog runs, the short role name (`developer`). The full `roleId` stays in `meta.json`.
 
 ## Tier candidates
 

package/node_modules/pi-better-subagents/docs/agent-catalog-operations.md

@@ -52,7 +52,7 @@ Codex applies the agent file's model and `model_reasoning_effort` ahead of the c
 
 `agents_catalog` accepts `list` and `inspect` only. It uses the same inspection view as `/agents show`. It has no write path. Launch remains `subagent_spawn` or the batch tool, with at most one `agent` or `role` selector. Those selectors are lifecycle's wiring, not this tool.
 
-Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role default openai/gpt-6-sol@high)`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role default openai/gpt-6-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
+A list line names a role by its short name (`role developer "Developer" …`), the form the `role` field takes; the inspect header, `identity.id`, and the structured `id` keep the stored id `role.developer`. Named agents show their full `agent.<slug>` id in both. Each list line and the inspect header end with the definition's default model and effort when one is set, such as `default openai/gpt-6-sol@high`: a role's own default, or a named agent's override or inherited role default. The structured view carries the same value as `defaults: { model, effort, label }`, or `null` when neither is set. A spawn that omits `model` and `thinking` uses it. When a catalog launch's model or effort differs from it, the launch line (and each batch job line) adds a note such as `model openai/gpt-6-astra@high (role developer default openai/gpt-6-sol@high)`; a named agent's note reads `agent default …`. Only the fields the definition sets are compared. The note names the cause: a fallback from an unavailable default reads `(role developer default openai/gpt-6-sol@high unavailable; foreground fallback)` (or `same-tier` / `configured-default`), and an effort the model cannot run adds `effort capped at <level> by the model`.
 
 ## Lifecycle attachment
 

package/node_modules/pi-better-subagents/docs/agent-catalog.md

@@ -50,6 +50,8 @@ Look at payment edge cases before editing.
 | `name` | Display text. Changing it does not change `id`. |
 | Filename | Not an id. Discovery reads every `*.md` file in the scope directory, one level deep. |
 
+People type and read a role by its short name: `developer` is `role.developer`. The `role` field of `subagent_spawn` and `subagent_spawn_batch` and the `agents_catalog` inspect id accept it (trimmed, case-insensitive), and `agents_catalog` lists roles by it. The prefixed id is what files, `roleId`, and run metadata store, and it keeps working as input. Named agents keep their full `agent.<slug>` id everywhere.
+
 `kind` must match the id prefix. `roleIds`, `baseRoles`, `inherits`, and a list of roles are rejected. Agentier executable-role memberships are eligibility data, not extra inheritance parents, and are not accepted as additional `roleId`s.
 
 ## Portable preferences vs host controls
@@ -96,14 +98,14 @@ Model availability, same-tier fallback, and nearest-effort adjustment are not de
 
 ## Approved bundled roles
 
-| Id | Name | Model | Effort | Tier |
-| --- | --- | --- | --- | --- |
-| `role.researcher` | Researcher | `openai/gpt-6-sol` | medium | balanced |
-| `role.explorer` | Explorer | `openai/gpt-6-luna` | medium | efficient |
-| `role.product-manager` | Product Manager | `openai/gpt-6-sol` | medium | balanced |
-| `role.developer` | Developer | `openai/gpt-6-sol` | high | balanced |
-| `role.reviewer` | Reviewer | `openai/gpt-6-astra` | medium | frontier |
-| `role.architect` | Architect | `openai/gpt-6-astra` | high | frontier |
+| Role | Stored id | Name | Model | Effort | Tier |
+| --- | --- | --- | --- | --- | --- |
+| `researcher` | `role.researcher` | Researcher | `openai/gpt-6-sol` | medium | balanced |
+| `explorer` | `role.explorer` | Explorer | `openai/gpt-6-luna` | medium | efficient |
+| `product-manager` | `role.product-manager` | Product Manager | `openai/gpt-6-sol` | medium | balanced |
+| `developer` | `role.developer` | Developer | `openai/gpt-6-sol` | high | balanced |
+| `reviewer` | `role.reviewer` | Reviewer | `openai/gpt-6-astra` | medium | frontier |
+| `architect` | `role.architect` | Architect | `openai/gpt-6-astra` | high | frontier |
 
 Bundled descriptions are routing boundaries for coordinator mode. Researcher owns
 external and documentary evidence; Explorer maps repository code paths; Product

package/node_modules/pi-better-subagents/index.ts

@@ -147,6 +147,7 @@ import { createAgentOperations } from "./agent-operations.ts";
 import {
     clarifyCatalogRequest,
     createLaunchEnricher,
+    blankCatalogSelector,
     hasCatalogSelector,
     loadLaunchSnapshot,
     noteCatalogHost,
@@ -178,7 +179,7 @@ const projectConfigDirName = typeof (PiCodingAgent as { CONFIG_DIR_NAME?: unknow
 const CATALOG_GUIDELINES = [
     "With an agent or role, omit model and thinking to launch on its default model and effort, which agents_catalog shows. Name a model or effort only for a stated reason, such as a task or workflow instruction, and never copy one from another role's runs.",
     "When a task, workflow, or skill instruction names a model or effort, translate that authoritative choice into the structured model and thinking arguments before spawning. The runtime does not parse prose, quoted model names, or comparisons, and copying a model into the child prompt does not change the launch.",
-    "Optional agent, role, and alias select a catalog definition. Pass one agent id or one role id. Pass an array of role ids when one run was given more than one role: that call asks to choose one or split, and without a UI choice it returns clarification-needed and starts no child. Naming both an agent and a role does the same. One job's choice does not change another job. A named agent displays its defined name. A direct role displays the label allocated from the local run registry. Calls without agent or role keep the existing name and model chain.",
+    "Optional agent, role, and alias select a catalog definition. Pass one named agent id (agent: \"agent.payments\") or one role by its short name (role: \"developer\"); the role.developer form also works. Pass an array of role names when one run was given more than one role: that call asks to choose one or split, and without a UI choice it returns clarification-needed and starts no child. Naming both an agent and a role does the same. One job's choice does not change another job. A named agent displays its defined name. A direct role displays the label allocated from the local run registry. Calls without agent or role keep the existing name and model chain.",
     "Catalog model and effort are resolved before the child starts. An unavailable explicit model or unsupported explicit effort does not launch and does not fall back. The catalog grants no tools, sandbox modes, extensions, or permissions.",
 ];
 
@@ -1425,8 +1426,8 @@ function timingSchemaFields() {
 
 /** String for one role, or an array when the caller assigns more than one. Arrays reach clarification instead of being rejected. */
 function catalogRoleSchema(purpose: string) {
-    const one = `One role id (role.<slug>) for this ${purpose}. Mutually exclusive with agent.`;
-    const many = `Two or more role ids for this ${purpose}. An array is ambiguous and asks to choose one role or split into separate runs. No child launches until that choice is made.`;
+    const one = `One role by short name (developer) for this ${purpose}; role.developer also works, case-insensitive. Mutually exclusive with agent.`;
+    const many = `Two or more role names for this ${purpose}. An array is ambiguous and asks to choose one role or split into separate runs. No child launches until that choice is made.`;
     return Type.Optional(Type.Union([
         Type.String({ description: one }),
         Type.Array(Type.String({ minLength: 1 }), { minItems: 1, description: many }),
@@ -1818,6 +1819,9 @@ export default function (pi: ExtensionAPI) {
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const p = params as SpawnParams;
             if (p.prompt.trim() === "") throw new Error("prompt is empty.");
+            // A present-but-blank role or agent is a mistake, not a request for a catalog-free child.
+            const blankSelector = blankCatalogSelector(p);
+            if (blankSelector) throw new Error(blankSelector);
 
             const cfg = loadConfig();
             const maxConcurrent = cfg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
@@ -1962,6 +1966,10 @@ export default function (pi: ExtensionAPI) {
             const gate = getSharedCapacityGate(countRunning);
 
             validateBatchPlan({ shared: p.shared, jobs: p.jobs, onCapacity: p.onCapacity, config: cfg });
+            // A present-but-blank role or agent rejects the whole batch before any launch.
+            const blankSelector = blankCatalogSelector(p.shared, "shared")
+                ?? p.jobs.map((job, index) => blankCatalogSelector(job, `jobs[${index}]`)).find(Boolean);
+            if (blankSelector) throw new Error(blankSelector);
 
             let catalogSnapshot: CatalogSnapshot | undefined;
             let catalogHost: CatalogHost | undefined;

package/node_modules/pi-better-subagents/navigator.mjs

@@ -399,7 +399,7 @@ export function buildNavigatorDetail(id, deps) {
     return {
         id: meta.id,
         name: meta.name,
-        role: meta.catalog?.roleId || meta.catalog?.roleName || undefined,
+        role: meta.catalog?.roleName || (meta.catalog?.roleId ? String(meta.catalog.roleId).replace(/^role\./, "") : undefined) || undefined,
         status,
         model: deps.shortModel(meta.model),
         effort: effortRaw ? String(effortRaw) : undefined,

package/node_modules/pi-better-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -55,7 +55,7 @@
     "pi-better-plan": "0.5.0",
     "pi-better-sandbox": "0.7.1",
     "pi-better-ssh": "0.1.1",
-    "pi-better-subagents": "0.8.0",
+    "pi-better-subagents": "0.9.0",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   },