pi-better-harness 0.34.1 → 0.35.0

package/bin/pi-agent-catalog.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "pi-better-subagents/agent-catalog.mjs";
+
+process.exitCode = await runCli();

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/shared-navigator.ts

@@ -348,20 +348,60 @@ type MainListWidget = Component & {
   handleMouse(event: WidgetMouseEvent): WidgetMouseResult | undefined;
 };
 
+const BACK_TO_MAIN = "← main (Esc)";
+const BACK_TARGET = "back-to-main";
+
+function highlightPointerTarget(theme: unknown, line: string, width: number): string {
+  const colors = theme as { bg?(color: string, value: string): string } | undefined;
+  return colors?.bg?.("selectedBg", line + " ".repeat(Math.max(0, width - visibleWidth(line))))
+    ?? themeFgFromTheme(theme)("accent", line);
+}
+
+function createPointerNavigation(targetAt: (event: WidgetMouseEvent) => string | undefined, activate: (target: string) => boolean) {
+  let hovered: string | undefined;
+  let pressed: { target: string; y: number } | undefined;
+  return {
+    get hovered() { return hovered; },
+    reset() { hovered = undefined; pressed = undefined; },
+    handleMouse(event: WidgetMouseEvent): WidgetMouseResult | undefined {
+      if (event.type === "move" || event.type === "leave") {
+        const target = event.type === "leave" ? undefined : targetAt(event);
+        const changed = hovered !== target;
+        hovered = target;
+        return changed || target ? { handled: true, render: changed } : undefined;
+      }
+      if (event.button !== "left" || event.shift || event.alt || event.ctrl) {
+        pressed = undefined;
+        return undefined;
+      }
+      if (event.type === "press") {
+        const target = targetAt(event);
+        pressed = target ? { target, y: event.y } : undefined;
+        return target ? { handled: true, render: false } : undefined;
+      }
+      if (event.type !== "click") return undefined;
+      const claim = pressed;
+      pressed = undefined;
+      if (!claim || claim.y !== event.y || targetAt(event) !== claim.target || !activate(claim.target)) return undefined;
+      return { handled: true, render: true };
+    },
+  };
+}
+
 function createMainListWidget(tui: { requestRender?(): void }, theme: unknown, deps: HostDeps): MainListWidget {
   const requestRender = () => tui.requestRender?.();
   state().mainListRequestRender = requestRender;
   // navigatorId per rendered line, so a pointer row resolves by structure, never by row text.
   let lineOwners: Array<string | undefined> = [];
   let lineWidth = MAIN_LIST_FALLBACK_WIDTH;
-  // Pi synthesizes a click only for the component that handled the initial press.
-  let pressedRow: { navigatorId: string; y: number } | undefined;
   const rowAt = (event: WidgetMouseEvent): string | undefined => {
     const width = Number.isFinite(event.width) && event.width > 0 ? Math.floor(event.width) : lineWidth;
     if (!Number.isFinite(event.x) || event.x < 0 || event.x >= width) return undefined;
     if (!Number.isInteger(event.y) || event.y < 0 || event.y >= lineOwners.length) return undefined;
-    return lineOwners[event.y];
+    const id = lineOwners[event.y];
+    return id && listRows().some((row) => row.navigatorId === id) ? id : undefined;
   };
+  const pointer = createPointerNavigation(rowAt, openNavigatorRow);
   return {
     render(width: number): string[] {
       const rows = listRows();
@@ -369,7 +409,7 @@ function createMainListWidget(tui: { requestRender?(): void }, theme: unknown, d
       if (!rows.length) {
         state().lastMainListLines = undefined;
         lineOwners = [];
-        pressedRow = undefined;
+        pointer.reset();
         return [];
       }
       const layout = buildMainListLayout(rows, renderWidth(width), deps.truncate, themeFgFromTheme(theme), {
@@ -379,41 +419,24 @@ function createMainListWidget(tui: { requestRender?(): void }, theme: unknown, d
       lineWidth = renderWidth(width);
       // The leading gap line belongs to the widget too, so its slot stays ownerless.
       lineOwners = [undefined, ...layout.owners];
-      const lines = ["", ...layout.lines];
+      const lines = ["", ...layout.lines].map((line, index) =>
+        pointer.hovered && lineOwners[index] === pointer.hovered ? highlightPointerTarget(theme, line, lineWidth) : line);
       state().lastMainListLines = lines;
       return lines;
     },
     handleMouse(event: WidgetMouseEvent): WidgetMouseResult | undefined {
-      // Only an unmodified left press is ours; every other gesture reaches the host untouched.
-      if (event.button !== "left" || event.shift === true || event.alt === true || event.ctrl === true) {
-        pressedRow = undefined;
-        return undefined;
-      }
-      if (event.type === "press") {
-        pressedRow = undefined;
-        const navigatorId = rowAt(event);
-        if (!navigatorId || !listRows().some((row) => row.navigatorId === navigatorId)) return undefined;
-        pressedRow = { navigatorId, y: event.y };
-        return { handled: true, render: false };
-      }
-      if (event.type !== "click") return undefined;
-      const pressed = pressedRow;
-      pressedRow = undefined;
-      // A click after another component's press, or after the layout moved, is not the row we claimed.
-      if (!pressed || pressed.y !== event.y || rowAt(event) !== pressed.navigatorId) return undefined;
-      if (!openNavigatorRow(pressed.navigatorId)) return undefined;
-      return { handled: true, render: true };
+      return pointer.handleMouse(event);
     },
     invalidate() {
       state().lastMainListLines = undefined;
       lineOwners = [];
-      pressedRow = undefined;
+      pointer.reset();
     },
     dispose() {
       const s = state();
       if (s.mainListRequestRender === requestRender) s.mainListRequestRender = undefined;
       lineOwners = [];
-      pressedRow = undefined;
+      pointer.reset();
     },
   };
 }
@@ -958,6 +981,22 @@ function createOverlayComponent(
   let closed = false;
   let transcriptDetail: BackgroundWorkDetail | null = null;
   let transcriptComponent: Component | null = null;
+  let pointerTargets: Array<string | undefined> = [];
+  let pointerWidth = 0;
+  const pointer = createPointerNavigation((event) => {
+    if (closed || !Number.isInteger(event.y) || !Number.isFinite(event.x) || event.x < 0 || event.x >= pointerWidth) return undefined;
+    const target = pointerTargets[event.y];
+    if (target === BACK_TARGET) return event.x >= 3 && event.x < 3 + visibleWidth(BACK_TO_MAIN) ? target : undefined;
+    return target && listRows().some((row) => row.navigatorId === target) ? target : undefined;
+  }, (target) => {
+    if (target === BACK_TARGET) { backToMain(); return true; }
+    refreshRows();
+    const index = overlayState.rows.findIndex((row) => row.navigatorId === target);
+    if (index < 0) return false;
+    selectOverlayRow(index);
+    openDetail();
+    return true;
+  });
 
   const fg = (color: string, value: string) => theme?.fg ? theme.fg(color, value) : value;
 
@@ -1036,6 +1075,11 @@ function createOverlayComponent(
     try { done(null); } catch { /* ignore */ }
   }
 
+  function backToMain(): void {
+    unfocusMainList();
+    close();
+  }
+
   function handleCloseKey(): void {
     const row = selectedRow();
     if (!row || row.parentRow) return;
@@ -1101,14 +1145,17 @@ function createOverlayComponent(
     render(width: number) {
       closeIfEditorReplaced();
       refreshRows();
-      const railLines = buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
+      const rail = buildMainListLayout(overlayState.rows, width, deps.truncate, fg, {
         selectedId: selectedRow()?.navigatorId,
         focused: true,
       });
+      const railLines = rail.lines;
       const editorLines = renderEditorLines(width);
       const bottomLines = [...railLines, ...editorLines];
       const overlayRows = state().detailOverlayRows;
       const detailRows = overlayRows === undefined ? undefined : Math.max(1, overlayRows - bottomLines.length);
+      const backControl = pointer.hovered === BACK_TARGET
+        ? highlightPointerTarget(theme, BACK_TO_MAIN, visibleWidth(BACK_TO_MAIN)) : undefined;
       let contentLines: string[];
       if (detail?.transcript && deps.createTranscriptComponent) {
         if (transcriptDetail !== detail || !transcriptComponent) {
@@ -1121,18 +1168,30 @@ function createOverlayComponent(
           width,
           deps.truncate,
           fg,
-          { minRows: detailRows, maxRows: detailRows, bottomFooter: false, logTailRows },
+          { minRows: detailRows, maxRows: detailRows, bottomFooter: false, logTailRows, backControl },
         );
       } else {
         transcriptDetail = null;
         transcriptComponent = null;
-        contentLines = buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows, maxRows: detailRows, bottomFooter: false });
+        contentLines = buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows, maxRows: detailRows, bottomFooter: false, backControl });
       }
-      if (overlayRows === undefined || detailRows === undefined) return [...contentLines, ...bottomLines];
-      const fittedContent = contentLines.slice(0, detailRows);
-      while (fittedContent.length < detailRows) fittedContent.push("");
-      // A terminal shorter than rail + editor keeps the bottom rows (the input frame) and drops the top.
-      return [...fittedContent, ...bottomLines].slice(-Math.max(1, overlayRows));
+      const fittedContent = detailRows === undefined ? contentLines : contentLines.slice(0, detailRows);
+      if (detailRows !== undefined) while (fittedContent.length < detailRows) fittedContent.push("");
+      const contentTargets = fittedContent.map((_, index) => index === 1 ? BACK_TARGET : undefined);
+      const allLines = [...fittedContent, ...bottomLines];
+      const allTargets = [...contentTargets, ...rail.owners, ...editorLines.map(() => undefined)];
+      // Match hit targets to the same viewport clipping as the visible lines.
+      const start = overlayRows === undefined ? 0 : Math.max(0, allLines.length - Math.max(1, overlayRows));
+      pointerTargets = allTargets.slice(start);
+      pointerWidth = renderWidth(width);
+      return allLines.slice(start).map((line, index) => {
+        if (!pointer.hovered || pointerTargets[index] !== pointer.hovered) return line;
+        if (pointer.hovered === BACK_TARGET) return line;
+        return highlightPointerTarget(theme, line, width);
+      });
+    },
+    handleMouse(event: WidgetMouseEvent): WidgetMouseResult | undefined {
+      return pointer.handleMouse(event);
     },
     handleInput(data: string) {
       if (closed) return;
@@ -1151,7 +1210,7 @@ function createOverlayComponent(
       else if (deps.matchKey(data, "left")) {
         const mainIdx = overlayState.rows.findIndex((row) => row.parentRow && row.id === "main");
         if (mainIdx >= 0) selectOverlayRow(mainIdx);
-        close();
+        backToMain();
       }
       else if (deps.matchKey(data, "enter")) {
         const row = selectedRow();
@@ -1179,8 +1238,7 @@ function createOverlayComponent(
         requestRender();
       }
       else if (deps.matchKey(data, "escape")) {
-        unfocusMainList();
-        close();
+        backToMain();
       }
     },
     /** Show another row's detail in this overlay (the main list moved while it was unfocused). */
@@ -1195,8 +1253,10 @@ function createOverlayComponent(
     },
     /** Close the overlay (done), e.g. when the navigator is disposed. */
     dismiss() { close(); },
-    invalidate() { transcriptComponent?.invalidate(); },
+    invalidate() { pointer.reset(); pointerTargets = []; transcriptComponent?.invalidate(); },
     dispose() {
+      pointer.reset();
+      pointerTargets = [];
       clearCloseArm();
       detailScheduler.dispose();
     },
@@ -1233,14 +1293,14 @@ function buildTranscriptDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { minRows?: number; maxRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
+  options: { minRows?: number; maxRows?: number; bottomFooter?: boolean; logTailRows?: number; backControl?: string } = {},
 ): string[] {
-  const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
+  const actions = [...(detail.footerActions ?? ["x close"])].join(" · ");
   const tailRows = options.logTailRows ?? DEFAULT_LOG_TAIL_ROWS;
   let shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
   const lines: string[] = [
     fg("accent", rule(detail.title, width)),
-    dim(`   ← main · ${actions}`, fg),
+    `   ${options.backControl ?? fg("accent", BACK_TO_MAIN)}${dim(` · ${actions}`, fg)}`,
     "",
     `   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`,
   ];
@@ -1264,7 +1324,7 @@ function buildTranscriptDetailLines(
   lines.push(...shownTranscriptLines);
   lines.push("");
   if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
-  const footerLines = [dim(`   ← main · ${actions}`, fg), dim(rule("", width), fg)];
+  const footerLines = [dim(`   ${BACK_TO_MAIN} · ${actions}`, fg), dim(rule("", width), fg)];
   padBeforeFooter(lines, footerLines.length, options.minRows);
   lines.push(...footerLines);
   return lines.map((line) => safeTruncate(line, width, truncate));
@@ -1320,10 +1380,10 @@ function buildDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { expandedSections?: Set<string>; logTailRows?: number; minRows?: number; maxRows?: number; bottomFooter?: boolean } = {},
+  options: { expandedSections?: Set<string>; logTailRows?: number; minRows?: number; maxRows?: number; bottomFooter?: boolean; backControl?: string } = {},
 ): string[] {
   if (!detail) {
-    const lines = [rule("Work unavailable", width), dim("   ← back · Esc close", fg), ""];
+    const lines = [rule("Work unavailable", width), `   ${options.backControl ?? fg("accent", BACK_TO_MAIN)}`, ""];
     if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
     const footerLines = [dim(rule("", width), fg)];
     padBeforeFooter(lines, footerLines.length, options.minRows);
@@ -1336,8 +1396,8 @@ function buildDetailLines(
   const foldedAction = toggleableSectionId
     ? (options.expandedSections?.has(toggleableSectionId) ? "Enter collapse" : "Enter expand")
     : null;
-  const actions = [foldedAction, ...(detail.footerActions?.length ? detail.footerActions : ["x close"]), "l 10/25", "Esc close"].filter(Boolean).join(" · ");
-  lines.push(dim(`   ← back · ${actions}`, fg));
+  const actions = [foldedAction, ...(detail.footerActions?.length ? detail.footerActions : ["x close"]), "l 10/25"].filter(Boolean).join(" · ");
+  lines.push(`   ${options.backControl ?? fg("accent", BACK_TO_MAIN)}${dim(` · ${actions}`, fg)}`);
   lines.push("");
   lines.push(`   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`);
   if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
@@ -1393,7 +1453,7 @@ function buildDetailLines(
   }
   lines.push("");
   if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));
-  const footerLines = [dim(`   ← back · ${actions}`, fg), dim(rule("", width), fg)];
+  const footerLines = [dim(`   ${BACK_TO_MAIN} · ${actions}`, fg), dim(rule("", width), fg)];
   padBeforeFooter(lines, footerLines.length, options.minRows);
   lines.push(...footerLines);
   return lines.map((line) => safeTruncate(line, width, truncate));

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

@@ -25,6 +25,23 @@ launch starts it again. No separate background task or coordinator heartbeat is
 needed. Completion delivery retries use the callback batcher's own timer. Lost-run
 alerts retain supervision until their handoff is handled, so lost work is not silent.
 
+## Worker Ownership
+
+Every child launch, including clean, batch and unsandboxed launches, loads a Pi
+hook that keeps external CI/PR monitoring with its coordinator. Workers finish
+their assigned implementation or diagnosis, run focused checks, push only when
+authorized, write the result, and return. Pending CI is a valid handoff, not a pass.
+
+The hook refuses recognized `gh run watch`, `gh pr checks --watch`, and bundled
+delivery-watcher commands through `bash` and `run_application`. Short status reads,
+failed-log retrieval, and legitimate long local tests and builds remain allowed.
+If background tools are explicitly available to a child, recognized watcher
+commands are refused there too. Coordinator sessions are unaffected.
+
+This is an operational ownership guard, not a security boundary or a classifier
+for arbitrary programs. Indirect scripts and custom polling implementations still
+rely on the worker handoff contract. Command permissions and timeouts are unchanged.
+
 ## Install
 
 ```sh
@@ -93,13 +110,18 @@ line says so, for example
 
 ## When To Use
 
+Skills can use the same role definitions on Pi and Codex through the standalone
+`pi-agent-catalog` JSON CLI, without starting Pi. The CLI checks supplied host
+capabilities and returns a worker plan; it never launches workers or substitutes
+prompt text for model selection. See [shared worker catalog](docs/worker-catalog.md).
+
 Use this package for independent coding, review, research, or verification work that can finish later. Do not use it for steps that need immediate foreground interaction or user clarification.
 
 ## Compatibility
 
 | Requirement | Support |
 |-------------|---------|
-| Pi | Required |
+| Pi | Required for worker execution through this extension; not for standalone catalog planning |
 | Install method | `pi install npm:pi-better-subagents` |
 | macOS sandboxing | Supported when enabled |
 | Linux sandboxing | Requires usable `bubblewrap` when enabled |

package/node_modules/pi-better-subagents/agent-catalog.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export async function runCli(args = process.argv.slice(2), input = () => readFileSync(0, 'utf8')) {
+    if (args.includes('--help')) {
+        console.log('pi-agent-catalog [resolve-workers] < request.json\nResolves shared agent roles against explicit host model and effort capabilities. No workers are launched.');
+        return 0;
+    }
+    if (args.length > 1 || (args.length === 1 && args[0] !== 'resolve-workers')) {
+        console.error('Usage: pi-agent-catalog [resolve-workers] < request.json');
+        return 2;
+    }
+    try {
+        // Register only for this import. The portable resolver never loads Pi extensions or credentials.
+        const { tsImport } = await import('tsx/esm/api');
+        const { planWorkers } = await tsImport('./worker-catalog.ts', import.meta.url);
+        const text = input();
+        if (Buffer.byteLength(text) > 1024 * 1024) throw new Error('worker request exceeds 1 MiB');
+        console.log(JSON.stringify(planWorkers(JSON.parse(text))));
+        return 0;
+    } catch (error) {
+        console.error(`pi-agent-catalog: ${error.message}`);
+        console.log(JSON.stringify({ version: 1, ok: false, code: 'worker-catalog-error', reason: error.message }));
+        return 2;
+    }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exitCode = await runCli();

package/node_modules/pi-better-subagents/child-ownership.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { parse } from "shell-quote";
+import { STEER_FILE_ENV } from "./child-steer.ts";
+
+export const WORKER_HANDOFF = "Worker ownership: complete your assigned implementation or diagnosis, run focused checks, push only when authorized, write the requested result, then return. Pending CI is a handoff, not a failed implementation or a CI pass. The coordinator owns CI/PR monitoring, review scheduling, readiness, enqueueing and merge. Do not start external delivery watchers or background monitoring. Short status reads and failed-log retrieval for diagnosis are allowed. Legitimate local tests and builds may run to completion within their command limits.";
+const REFUSAL = "Worker ownership: CI/PR monitoring belongs to the coordinator. Return the PR/run ID, pushed HEAD and current evidence with CI pending; do not retry the watcher through another tool or script. Local tests/builds and short diagnostic status/log reads remain allowed.";
+const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
+const nameOf = (value: string) => value.replaceAll("\\", "/").split("/").at(-1)!.replace(/\.exe$/i, "");
+
+// Preserve command boundaries without treating multiline strings or heredoc data as commands.
+function commandLines(command: string): string[] {
+    const lines: string[] = [];
+    const documents: { delimiter: string; tabs: boolean }[] = [];
+    let quote = "", escaped = false, out = "";
+    for (const line of command.split("\n")) {
+        if (documents.length) {
+            const document = documents[0]!;
+            if ((document.tabs ? line.replace(/^\t+/, "") : line) === document.delimiter) documents.shift();
+            continue;
+        }
+        let comment = false;
+        for (const char of `${line}\n`) {
+            if (!quote && !escaped && char === "#" && (!out || /[\s;&|()<>]$/.test(out))) comment = true;
+            if (comment && char !== "\n") continue;
+            if (escaped) { out += char === "\n" ? "" : `\\${char}`; escaped = false; continue; }
+            if (char === "\\" && quote !== "'") { escaped = true; continue; }
+            if (char === quote) quote = "";
+            else if (!quote && (char === "'" || char === '"')) quote = char;
+            if (char !== "\n" || quote) { out += char; continue; }
+            lines.push(out);
+            try {
+                const tokens = parse(out);
+                for (let i = 0; i < tokens.length; i++) {
+                    const token = tokens[i], delimiter = tokens[i + 1];
+                    if (typeof token === "object" && "op" in token && ["<<", "<<-"].includes(token.op) && typeof delimiter === "string") {
+                        documents.push({ delimiter, tabs: token.op === "<<-" });
+                    }
+                }
+            } catch { /* The command tool, not this operational guard, validates shell syntax. */ }
+            out = "";
+        }
+    }
+    if (out) lines.push(out);
+    return lines;
+}
+
+function shellWatcher(command: string, depth: number): boolean {
+    if (depth > 3) return false;
+    let tokens;
+    try { tokens = commandLines(command).flatMap((line) => [...parse(line), { op: ";" as const }]); } catch { return false; }
+    let words: string[] = [];
+    let redirect = false;
+    for (const token of tokens) {
+        if (typeof token === "string" || ("op" in token && token.op === "glob")) {
+            if (redirect) { redirect = false; continue; }
+            words.push(typeof token === "string" ? token : token.pattern);
+        } else if ("op" in token && ["<", ">", ">>", ">&", "<&", ">|", "<>", "&>", "&>>", "<<", "<<-", "<<<"].includes(token.op)) {
+            if (words.length === 1 && /^\d+$/.test(words[0]!)) words = [];
+            redirect = true;
+        } else {
+            if (argvWatcher(words, depth + 1)) return true;
+            words = [];
+            redirect = false;
+        }
+    }
+    return argvWatcher(words, depth + 1);
+}
+
+function argvWatcher(input: readonly string[], depth = 0): boolean {
+    if (depth > 4) return false;
+    let words = [...input];
+    while (/^[A-Za-z_][A-Za-z_0-9]*=/.test(words[0] ?? "")) words.shift();
+    if (nameOf(words[0] ?? "") === "env") {
+        words.shift();
+        while (words.length) {
+            if (["-u", "--unset", "-C", "--chdir"].includes(words[0]!)) words.splice(0, 2);
+            else if (words[0] === "--" || words[0]!.startsWith("-") || /^[A-Za-z_][A-Za-z_0-9]*=/.test(words[0]!)) words.shift();
+            else break;
+        }
+    }
+    const program = nameOf(words.shift() ?? "");
+    if (["bash", "sh", "zsh", "dash"].includes(program)) {
+        const at = words.findIndex((word) => /^-[^-]*c/.test(word));
+        return at >= 0 && typeof words[at + 1] === "string" && shellWatcher(words[at + 1]!, depth + 1);
+    }
+    if (words.includes("--help") || words.includes("-h")) return false;
+    if (program === "gh") {
+        while (words.length) {
+            if (["--repo", "-R", "--hostname"].includes(words[0]!)) words.splice(0, 2);
+            else if (/^(?:--repo=.+|--hostname=.+|-R.+)$/.test(words[0]!)) words.shift();
+            else break;
+        }
+        return (words[0] === "run" && words[1] === "watch") ||
+            (words[0] === "pr" && words[1] === "checks" && words.slice(2).some((word) => ["--watch", "--watch=true"].includes(word)));
+    }
+    if (WATCH_SCRIPTS.has(program)) return true;
+    if (program === "node" || program === "nodejs") {
+        while (words[0]?.startsWith("-")) {
+            if (["-e", "--eval", "-p", "--print"].includes(words[0])) return false;
+            const takesValue = ["--import", "--loader", "--require", "-r"].includes(words[0]);
+            words.splice(0, takesValue ? 2 : 1);
+        }
+        return WATCH_SCRIPTS.has(nameOf(words[0] ?? ""));
+    }
+    return false;
+}
+
+/** Recognizes supported watcher entrypoints, not arbitrary program semantics or a security boundary. */
+export function workerMonitoringRefusal(toolName: string, input: unknown): string | undefined {
+    if (!input || typeof input !== "object") return;
+    const value = input as Record<string, unknown>;
+    const argv = toolName === "run_application" && typeof value.executable === "string" &&
+        (value.args === undefined || (Array.isArray(value.args) && value.args.every((arg) => typeof arg === "string")))
+        ? [value.executable, ...((value.args ?? []) as string[])] : undefined;
+    if (argv && argvWatcher(argv)) return REFUSAL;
+    if (["bash", "remote_bash", "bg_task", "bg_task_spawn", "bg_task_watch"].includes(toolName)) {
+        if (typeof value.command === "string" && shellWatcher(value.command, 0)) return REFUSAL;
+        if (Array.isArray(value.argv) && value.argv.every((arg) => typeof arg === "string") && argvWatcher(value.argv)) return REFUSAL;
+    }
+}
+
+export default function childOwnership(pi: Pick<ExtensionAPI, "on">, env: NodeJS.ProcessEnv = process.env): void {
+    // This marker is supplied by the parent on every child launch, including clean/unsandboxed runs.
+    if (!env[STEER_FILE_ENV]) return;
+    pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` }));
+    pi.on("tool_call", (event) => {
+        const reason = workerMonitoringRefusal(event.toolName, event.input);
+        if (reason) return { block: true, reason };
+    });
+}

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

@@ -1,6 +1,6 @@
 # Native agent catalog (`pi-agent/v1`)
 
-Portable role and named-agent definitions for `pi-better-subagents`. This is the local contract for DEV-23 / GitHub #289. It is not an Agentier importer, a Codex runtime, or a second launch path.
+Portable role and named-agent definitions for `pi-better-subagents`. This is the local contract for DEV-23 / GitHub #289. It is not an Agentier importer or a second launch path. The [shared worker catalog](worker-catalog.md) exposes these definitions to skills on Pi and Codex through host-specific planning, without launching workers itself.
 
 Normative behavior is DEV-23 and the accepted ADR `docs/adr/0003-native-agent-catalog-live-inheritance.md`. Field names below are the engineering schema those decisions require.
 

package/node_modules/pi-better-subagents/docs/agent-model-resolution.md

@@ -1,6 +1,6 @@
 # Agent model resolution
 
-Resolver for DEV-23 model and effort choices. `model-resolution.ts` and `tier-policy.ts` do not spawn a child and do not edit the catalog. Lifecycle calls them before `spawnSubagentRun`.
+Resolver for DEV-23 model and effort choices. `model-resolution-core.ts` owns portable resolution; `model-resolution.ts` supplies Pi's effort-support helper. Neither spawns a child or edits the catalog. Lifecycle calls the Pi adapter before `spawnSubagentRun`. Skills on other hosts use the [shared worker catalog](worker-catalog.md).
 
 Normative rules are R3, R4, R8, and the resolver half of R10. Prose parsing and real Pi delegation stay with the acceptance unit.
 

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

@@ -0,0 +1,116 @@
+# Shared worker catalog
+
+Skills request roles; the harness catalog owns their instructions, preferred
+models, and effort. Skills must not turn a model recommendation into an explicit
+launch override. This interface plans workers; it does not launch them.
+
+`pi-agent-catalog [resolve-workers]` reads one JSON request from stdin and emits
+one JSON plan. Install the harness or subagents npm package to expose the binary,
+or run its `agent-catalog.mjs` directly. No Pi session, credentials, provider
+discovery, extensions, or network connection is needed. The CLI uses the packaged
+`tsx` loader; the portable TypeScript API is `pi-better-subagents/catalog`.
+
+## Request
+
+```json
+{
+  "version": 1,
+  "harness": "codex",
+  "cwd": "/workspace/project",
+  "projectTrusted": false,
+  "available": [
+    {
+      "model": "openai/gpt-6.1-sol",
+      "nativeModel": "gpt-6.1-sol",
+      "supportedEfforts": ["low", "medium", "high"]
+    },
+    {
+      "model": "openai/gpt-6-luna",
+      "nativeModel": "gpt-6-luna",
+      "supportedEfforts": ["low", "medium", "high"]
+    },
+    {
+      "model": "openai/gpt-6-astra",
+      "nativeModel": "gpt-6-astra",
+      "supportedEfforts": ["low", "medium", "high"]
+    }
+  ],
+  "launchCapabilities": {
+    "model": true,
+    "effort": true,
+    "instructions": true
+  },
+  "hostPreferences": {
+    "developer": {"model": "openai/gpt-6.1-sol", "effort": "high"}
+  }
+}
+```
+
+This is an example shape, not evidence that these models or controls are available
+in any Codex installation. The caller supplies capabilities from its current host.
+Do not copy an availability list from Pi, infer supported effort from a model name,
+or treat a configured model as available without runtime evidence. A native model
+name maps to exactly one canonical `provider/model`; ambiguous mappings fail.
+
+The catalog still uses project > personal > bundled definitions. Personal storage
+is `userRoot`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent`, shared across hosts.
+The CLI never scans `.codex/agents` or writes user configuration. Project catalog
+files contribute only when `projectTrusted` is explicitly true. Host preferences
+are supplied configuration, not another copied catalog or a write to a role.
+
+Optional `overrides` selects `implementer`, `explorer`, `diagnoser`, or `reviewer`:
+
+```json
+{"overrides": {"implementer": {"model": "deepseek/deepseek-flash@max"}}}
+```
+
+Model and effort resolve independently: task override > host preference > catalog
+default. A model-only override keeps the resolved effort. Unsupported explicit
+model/effort choices block; inherited effort can use the catalog's documented
+nearest-level adjustment. Pi retains its existing tier/foreground fallback policy.
+Codex and Claude Code require an explicit configured `tiers` policy or
+`fallbackToForeground: true` to permit those default-model substitutions. An
+explicit task or host model is never silently substituted.
+
+## Plan And Execution
+
+The plan maps implementer and diagnoser to Developer, explorer to Explorer, and
+reviewer to Reviewer. Every worker reports `role`, `model`, `nativeModel`, `effort`,
+`instructions`, `selection`, `catalogDigest`, `diagnostics`,
+and `launch`. All four use the same immutable catalog snapshot. A reviewer that
+resolves to the implementer's model blocks preflight; the skill must not invent
+another model to make the check pass.
+
+- **Pi:** `launch` is `{role: "developer"}` by default. Only explicit task or host
+  model/effort choices add `model` or `thinking`. The coordinator adds its task
+  prompt, alias, workspace, and authorized controls to the existing spawn tool.
+  Live Pi launch resolution remains authoritative, including branch-local session
+  preferences that an out-of-process CLI cannot read. Record the actual launch
+  provenance, not just the preflight prediction.
+- **Codex / Claude Code:** `launch` contains the verified native `model`, `effort`,
+  and resolved role `instructions`. The adapter uses actual launch/configuration
+  controls supported by its current surface and appends the task instructions.
+  If the surface cannot apply a required field, do not launch. Saying a model name
+  in a worker prompt is not model selection. This API is a plan, not a claim that
+  every native `spawn_agent` surface supports per-call model or effort fields.
+
+The catalog grants no sandbox, tool, filesystem, credential, or delegation
+permissions. Existing host launch controls still apply.
+
+On a blocked plan, `ok` is false and **every** `launch` is null. A model recorded
+in an unsuccessful decision is diagnostic evidence, not launch authorization.
+The CLI returns status 0 for a valid plan, including a blocked plan, and status 2
+for malformed input or an invocation error. Consumers must check `ok`, not just
+the process exit status. No automatic retry, install, or post-start substitution
+is performed.
+
+## Modules
+
+- `catalog-schema.ts`, `catalog-store.ts`, `catalog-resolver.ts`: existing shared
+  definitions and live inheritance, unchanged storage format.
+- `model-resolution-core.ts`: portable availability and effort resolution, with
+  host-provided supported effort levels or an injected effort-support function.
+- `model-resolution.ts`: Pi wrapper, supplying `getSupportedThinkingLevels` from
+  Pi's registry. Existing Pi callers retain their API and semantics.
+- `worker-catalog.ts`: workflow slots, host adaptation, independence, and a single
+  batch snapshot. It does not import a Pi SDK.