@h-rig/cli 0.0.6-alpha.74 → 0.0.6-alpha.75

package/dist/src/commands/run.js

@@ -812,98 +812,6 @@ import { tmpdir } from "os";
 import { join as join2 } from "path";
 import { main as runPiMain } from "@earendil-works/pi-coding-agent";
 import createPiRigExtension from "@rig/pi-rig";
-function setTemporaryEnv(updates) {
-  const previous = new Map;
-  for (const [key, value] of Object.entries(updates)) {
-    previous.set(key, process.env[key]);
-    process.env[key] = value;
-  }
-  return () => {
-    for (const [key, value] of previous) {
-      if (value === undefined)
-        delete process.env[key];
-      else
-        process.env[key] = value;
-    }
-  };
-}
-function buildOperatorPiEnv(input) {
-  return {
-    PI_CODING_AGENT_SESSION_DIR: input.sessionDir,
-    PI_SKIP_VERSION_CHECK: "1",
-    RIG_PI_OPERATOR_SESSION: "1",
-    RIG_RUN_ID: input.runId,
-    RIG_SERVER_URL: input.serverUrl,
-    ...input.authToken ? { RIG_AUTH_TOKEN: input.authToken } : {},
-    ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
-  };
-}
-async function attachRunBundledPiFrontend(context, input) {
-  const tempSessionDir = mkdtempSync(join2(tmpdir(), "rig-pi-frontend-sessions-"));
-  const server = await ensureServerForCli(context.projectRoot);
-  let sessionFileArg = [];
-  try {
-    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(input.runId)}/session-file`);
-    if (payload?.ok && typeof payload.content === "string" && payload.content.trim()) {
-      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${input.runId}.jsonl`;
-      const localSessionPath = join2(tempSessionDir, fileName);
-      const content = payload.content.split(`
-`).map((line, index) => {
-        if (index > 0 || !line.trim())
-          return line;
-        try {
-          const header = JSON.parse(line);
-          if (header.type === "session" && typeof header.cwd === "string") {
-            return JSON.stringify({ ...header, cwd: process.cwd() });
-          }
-        } catch {}
-        return line;
-      }).join(`
-`);
-      writeFileSync2(localSessionPath, content);
-      sessionFileArg = ["--session", localSessionPath];
-    }
-  } catch {}
-  const restoreEnv = setTemporaryEnv(buildOperatorPiEnv({
-    runId: input.runId,
-    serverUrl: server.baseUrl,
-    authToken: server.authToken,
-    serverProjectRoot: server.serverProjectRoot,
-    sessionDir: tempSessionDir
-  }));
-  const piRigExtensionFactory = (pi) => {
-    createPiRigExtension(pi);
-  };
-  let detached = false;
-  try {
-    await runPiMain([
-      "--no-extensions",
-      "--no-skills",
-      "--no-prompt-templates",
-      "--no-context-files",
-      ...sessionFileArg
-    ], {
-      extensionFactories: [piRigExtensionFactory]
-    });
-    detached = true;
-  } finally {
-    restoreEnv();
-    rmSync(tempSessionDir, { recursive: true, force: true });
-  }
-  let run = { runId: input.runId, status: "unknown" };
-  try {
-    run = await getRunDetailsViaServer(context, input.runId);
-  } catch {}
-  return {
-    run,
-    logs: [],
-    timeline: [],
-    timelineCursor: null,
-    steered: input.steered === true,
-    detached,
-    rendered: "stock Pi operator console with the pi-rig extension"
-  };
-}
 
 // packages/cli/src/commands/_async-ui.ts
 import pc from "picocolors";
@@ -1026,6 +934,104 @@ async function withSpinner(label, work, options = {}) {
   }
 }
 
+// packages/cli/src/commands/_pi-frontend.ts
+function setTemporaryEnv(updates) {
+  const previous = new Map;
+  for (const [key, value] of Object.entries(updates)) {
+    previous.set(key, process.env[key]);
+    process.env[key] = value;
+  }
+  return () => {
+    for (const [key, value] of previous) {
+      if (value === undefined)
+        delete process.env[key];
+      else
+        process.env[key] = value;
+    }
+  };
+}
+function buildOperatorPiEnv(input) {
+  return {
+    PI_CODING_AGENT_SESSION_DIR: input.sessionDir,
+    PI_SKIP_VERSION_CHECK: "1",
+    RIG_PI_OPERATOR_SESSION: "1",
+    RIG_RUN_ID: input.runId,
+    RIG_SERVER_URL: input.serverUrl,
+    ...input.authToken ? { RIG_AUTH_TOKEN: input.authToken } : {},
+    ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
+  };
+}
+async function prepareOperatorConsole(context, runId, tempSessionDir) {
+  const server = await ensureServerForCli(context.projectRoot);
+  let sessionFileArg = [];
+  try {
+    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/session-file`);
+    if (payload?.ok && typeof payload.content === "string" && payload.content.trim()) {
+      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${runId}.jsonl`;
+      const localSessionPath = join2(tempSessionDir, fileName);
+      const content = payload.content.split(`
+`).map((line, index) => {
+        if (index > 0 || !line.trim())
+          return line;
+        try {
+          const header = JSON.parse(line);
+          if (header.type === "session" && typeof header.cwd === "string") {
+            return JSON.stringify({ ...header, cwd: process.cwd() });
+          }
+        } catch {}
+        return line;
+      }).join(`
+`);
+      writeFileSync2(localSessionPath, content);
+      sessionFileArg = ["--session", localSessionPath];
+    }
+  } catch {}
+  return { server, sessionFileArg };
+}
+async function attachRunBundledPiFrontend(context, input) {
+  const tempSessionDir = mkdtempSync(join2(tmpdir(), "rig-pi-frontend-sessions-"));
+  const { server, sessionFileArg } = await withSpinner(`Opening Pi console for run ${input.runId}\u2026`, () => prepareOperatorConsole(context, input.runId, tempSessionDir), { outputMode: context.outputMode });
+  const restoreEnv = setTemporaryEnv(buildOperatorPiEnv({
+    runId: input.runId,
+    serverUrl: server.baseUrl,
+    authToken: server.authToken,
+    serverProjectRoot: server.serverProjectRoot,
+    sessionDir: tempSessionDir
+  }));
+  const piRigExtensionFactory = (pi) => {
+    createPiRigExtension(pi);
+  };
+  let detached = false;
+  try {
+    await runPiMain([
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-context-files",
+      ...sessionFileArg
+    ], {
+      extensionFactories: [piRigExtensionFactory]
+    });
+    detached = true;
+  } finally {
+    restoreEnv();
+    rmSync(tempSessionDir, { recursive: true, force: true });
+  }
+  let run = { runId: input.runId, status: "unknown" };
+  try {
+    run = await getRunDetailsViaServer(context, input.runId);
+  } catch {}
+  return {
+    run,
+    logs: [],
+    timeline: [],
+    timelineCursor: null,
+    steered: input.steered === true,
+    detached,
+    rendered: "stock Pi operator console with the pi-rig extension"
+  };
+}
+
 // packages/cli/src/commands/_operator-view.ts
 var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
 function runStatusFromPayload(payload) {

package/dist/src/commands/stats.js

@@ -511,6 +511,18 @@ async function withSpinner(label, work, options = {}) {
 import { intro, log as log2, note as note2, outro } from "@clack/prompts";
 import pc3 from "picocolors";
 var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Pi console",
+    subtitle: "the operator surface \u2014 every attach opens the run's FULL Pi session",
+    commands: [
+      { command: "rig run attach <run-id>", description: "Open the run's Pi console: complete transcript (live AND finished runs), worker turns streaming in live." },
+      { command: "type a message", description: "Inside the console, plain text steers the worker mid-turn \u2014 it lands in the agent's context, not a local model." },
+      { command: "!<command>", description: "Inside the console, runs shell in the WORKER's workspace; output streams back into the transcript." },
+      { command: "/<command>", description: "The palette includes the WORKER session's slash commands ([worker]-tagged) next to /rig." },
+      { command: "/rig abort | /rig stop", description: "Abort the worker's current turn, or stop the whole run, from inside the console." },
+      { command: "rig run steer <id> --message <text>", description: "Steer without attaching \u2014 queue a message; the worker picks it up within seconds." }
+    ]
+  },
   {
     title: "Start here",
     subtitle: "one-time setup, pick a server",
@@ -525,9 +537,9 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "find a task, put an agent on it, answer what it asks",
     commands: [
       { command: "rig task list", description: "What's on the board (from the selected source/server)." },
-      { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
+      { command: "rig task run --next", description: "Dispatch an agent on the next ready task; interactive mode drops you into its Pi console." },
       { command: "rig run status", description: "Active and recent runs at a glance." },
-      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig run attach <id> --follow", description: "Same as plain attach \u2014 the Pi console is always the interactive surface." },
       { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
     ]
   },
@@ -606,29 +618,35 @@ var PRIMARY_GROUPS = [
   },
   {
     name: "run",
-    summary: "Observe, attach to, and control Rig runs.",
-    usage: ["rig run <list|status|show|attach|stop> [options]"],
+    summary: "Observe, attach to, and control Rig runs. `attach` opens the Pi console \u2014 the full worker session, live.",
+    usage: ["rig run <list|status|show|attach|steer|stop|resume|restart> [options]"],
     commands: [
       { command: "list", description: "List recent runs from the selected server or local state.", primary: true },
       { command: "status", description: "Render active and recent run groups.", primary: true },
       { command: "show <id>|--run <id> [--raw]", description: "Show a human run summary; --raw prints the full payload.", primary: true },
-      { command: "attach <run-id>|--run <id> [--follow]", description: "Attach to the run; --follow opens the enriched bundled Pi (worker brain).", primary: true },
+      { command: "attach <run-id>|--run <id>", description: "Open the run's Pi console \u2014 see 'Inside the console' below. Works on live AND finished runs.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching \u2014 delivered into the agent's context within seconds.", primary: true },
       { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
-      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching." },
-      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events." },
+      { command: "resume [<run-id>]", description: "Resume an interrupted run on the selected server (defaults to the most recent resumable)." },
+      { command: "restart [<run-id>]", description: "Re-dispatch a run from a clean runtime, reopening its Pi session where possible." },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events (scripts; humans should attach)." },
       { command: "replay <run-id>|--run <id> [--with-session]", description: "Print the run's consolidated run.jsonl as a merged timeline; --with-session interleaves the Pi session log." },
-      { command: "resume", description: "Resume the most recent interrupted local run." },
-      { command: "restart", description: "Restart the most recent local run from a clean runtime." },
       { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
     ],
     examples: [
+      "rig run attach <run-id>          # full session console \u2014 live mirror, steering, worker shell",
+      "rig run steer <run-id> --message 'focus on the failing test first'",
       "rig run list",
-      "rig run status",
       "rig run show <run-id>",
-      "rig run attach <run-id> --follow",
       "rig run stop <run-id>"
     ],
-    next: ["Use `rig task run --next` to create a new run.", "Use `--json` when scripts need the full structured record."]
+    next: [
+      "Inside the console: the run's COMPLETE transcript loads on open (finished runs too), and new worker turns stream in live.",
+      "Inside the console: plain text = steering into the worker's context \xB7 !<cmd> = shell in the WORKER workspace \xB7 /<cmd> includes the worker session's commands \xB7 /rig abort stops the current turn.",
+      "The console is read-write but remote-only: nothing runs on your machine; the worker keeps running when you exit.",
+      "Use `rig task run --next` to create a new run; interactive mode drops you straight into its console.",
+      "Use `--json` when scripts need the full structured record."
+    ]
   },
   {
     name: "inbox",
@@ -845,7 +863,7 @@ function renderGroup(group) {
 function renderTopLevelHelp() {
   return [
     `${heading("rig")} ${pc3.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
-    pc3.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox gates."),
+    pc3.dim("The loop: pick a task, dispatch an agent, open its Pi console (`rig run attach <id>`) to watch and steer it live, clear inbox gates, merge."),
     "",
     ...TOP_LEVEL_SECTIONS.flatMap((section) => [
       `${pc3.bold(pc3.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc3.dim(section.subtitle)}`,
@@ -897,7 +915,7 @@ function printTopLevelHelp(state = {}) {
     commandLine("--dry-run", "Print the command plan without mutating state.")
   ].join(`
 `), "Global options");
-  outro("init \u2192 task run \u2192 watch \u2192 inbox \u2192 merged.");
+  outro("init \u2192 task run \u2192 attach (Pi console: watch + steer live) \u2192 inbox \u2192 merged.");
 }
 function printGroupHelpDocument(groupName) {
   const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();

package/dist/src/commands/task.js

@@ -1201,14 +1201,13 @@ function buildOperatorPiEnv(input) {
     ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
   };
 }
-async function attachRunBundledPiFrontend(context, input) {
-  const tempSessionDir = mkdtempSync(join(tmpdir(), "rig-pi-frontend-sessions-"));
+async function prepareOperatorConsole(context, runId, tempSessionDir) {
   const server = await ensureServerForCli(context.projectRoot);
   let sessionFileArg = [];
   try {
-    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(input.runId)}/session-file`);
+    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/session-file`);
     if (payload?.ok && typeof payload.content === "string" && payload.content.trim()) {
-      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${input.runId}.jsonl`;
+      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${runId}.jsonl`;
       const localSessionPath = join(tempSessionDir, fileName);
       const content = payload.content.split(`
 `).map((line, index) => {
@@ -1227,6 +1226,11 @@ async function attachRunBundledPiFrontend(context, input) {
       sessionFileArg = ["--session", localSessionPath];
     }
   } catch {}
+  return { server, sessionFileArg };
+}
+async function attachRunBundledPiFrontend(context, input) {
+  const tempSessionDir = mkdtempSync(join(tmpdir(), "rig-pi-frontend-sessions-"));
+  const { server, sessionFileArg } = await withSpinner(`Opening Pi console for run ${input.runId}\u2026`, () => prepareOperatorConsole(context, input.runId, tempSessionDir), { outputMode: context.outputMode });
   const restoreEnv = setTemporaryEnv(buildOperatorPiEnv({
     runId: input.runId,
     serverUrl: server.baseUrl,
@@ -1571,6 +1575,18 @@ async function printPendingInboxFooter(context) {
 import { intro, log as log2, note as note2, outro } from "@clack/prompts";
 import pc3 from "picocolors";
 var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Pi console",
+    subtitle: "the operator surface \u2014 every attach opens the run's FULL Pi session",
+    commands: [
+      { command: "rig run attach <run-id>", description: "Open the run's Pi console: complete transcript (live AND finished runs), worker turns streaming in live." },
+      { command: "type a message", description: "Inside the console, plain text steers the worker mid-turn \u2014 it lands in the agent's context, not a local model." },
+      { command: "!<command>", description: "Inside the console, runs shell in the WORKER's workspace; output streams back into the transcript." },
+      { command: "/<command>", description: "The palette includes the WORKER session's slash commands ([worker]-tagged) next to /rig." },
+      { command: "/rig abort | /rig stop", description: "Abort the worker's current turn, or stop the whole run, from inside the console." },
+      { command: "rig run steer <id> --message <text>", description: "Steer without attaching \u2014 queue a message; the worker picks it up within seconds." }
+    ]
+  },
   {
     title: "Start here",
     subtitle: "one-time setup, pick a server",
@@ -1585,9 +1601,9 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "find a task, put an agent on it, answer what it asks",
     commands: [
       { command: "rig task list", description: "What's on the board (from the selected source/server)." },
-      { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
+      { command: "rig task run --next", description: "Dispatch an agent on the next ready task; interactive mode drops you into its Pi console." },
       { command: "rig run status", description: "Active and recent runs at a glance." },
-      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig run attach <id> --follow", description: "Same as plain attach \u2014 the Pi console is always the interactive surface." },
       { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
     ]
   },
@@ -1666,29 +1682,35 @@ var PRIMARY_GROUPS = [
   },
   {
     name: "run",
-    summary: "Observe, attach to, and control Rig runs.",
-    usage: ["rig run <list|status|show|attach|stop> [options]"],
+    summary: "Observe, attach to, and control Rig runs. `attach` opens the Pi console \u2014 the full worker session, live.",
+    usage: ["rig run <list|status|show|attach|steer|stop|resume|restart> [options]"],
     commands: [
       { command: "list", description: "List recent runs from the selected server or local state.", primary: true },
       { command: "status", description: "Render active and recent run groups.", primary: true },
       { command: "show <id>|--run <id> [--raw]", description: "Show a human run summary; --raw prints the full payload.", primary: true },
-      { command: "attach <run-id>|--run <id> [--follow]", description: "Attach to the run; --follow opens the enriched bundled Pi (worker brain).", primary: true },
+      { command: "attach <run-id>|--run <id>", description: "Open the run's Pi console \u2014 see 'Inside the console' below. Works on live AND finished runs.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching \u2014 delivered into the agent's context within seconds.", primary: true },
       { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
-      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching." },
-      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events." },
+      { command: "resume [<run-id>]", description: "Resume an interrupted run on the selected server (defaults to the most recent resumable)." },
+      { command: "restart [<run-id>]", description: "Re-dispatch a run from a clean runtime, reopening its Pi session where possible." },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events (scripts; humans should attach)." },
       { command: "replay <run-id>|--run <id> [--with-session]", description: "Print the run's consolidated run.jsonl as a merged timeline; --with-session interleaves the Pi session log." },
-      { command: "resume", description: "Resume the most recent interrupted local run." },
-      { command: "restart", description: "Restart the most recent local run from a clean runtime." },
       { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
     ],
     examples: [
+      "rig run attach <run-id>          # full session console \u2014 live mirror, steering, worker shell",
+      "rig run steer <run-id> --message 'focus on the failing test first'",
       "rig run list",
-      "rig run status",
       "rig run show <run-id>",
-      "rig run attach <run-id> --follow",
       "rig run stop <run-id>"
     ],
-    next: ["Use `rig task run --next` to create a new run.", "Use `--json` when scripts need the full structured record."]
+    next: [
+      "Inside the console: the run's COMPLETE transcript loads on open (finished runs too), and new worker turns stream in live.",
+      "Inside the console: plain text = steering into the worker's context \xB7 !<cmd> = shell in the WORKER workspace \xB7 /<cmd> includes the worker session's commands \xB7 /rig abort stops the current turn.",
+      "The console is read-write but remote-only: nothing runs on your machine; the worker keeps running when you exit.",
+      "Use `rig task run --next` to create a new run; interactive mode drops you straight into its console.",
+      "Use `--json` when scripts need the full structured record."
+    ]
   },
   {
     name: "inbox",
@@ -1905,7 +1927,7 @@ function renderGroup(group) {
 function renderTopLevelHelp() {
   return [
     `${heading("rig")} ${pc3.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
-    pc3.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox gates."),
+    pc3.dim("The loop: pick a task, dispatch an agent, open its Pi console (`rig run attach <id>`) to watch and steer it live, clear inbox gates, merge."),
     "",
     ...TOP_LEVEL_SECTIONS.flatMap((section) => [
       `${pc3.bold(pc3.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc3.dim(section.subtitle)}`,
@@ -1957,7 +1979,7 @@ function printTopLevelHelp(state = {}) {
     commandLine("--dry-run", "Print the command plan without mutating state.")
   ].join(`
 `), "Global options");
-  outro("init \u2192 task run \u2192 watch \u2192 inbox \u2192 merged.");
+  outro("init \u2192 task run \u2192 attach (Pi console: watch + steer live) \u2192 inbox \u2192 merged.");
 }
 function printGroupHelpDocument(groupName) {
   const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();

package/dist/src/commands.js

@@ -7698,14 +7698,13 @@ function buildOperatorPiEnv(input) {
     ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
   };
 }
-async function attachRunBundledPiFrontend(context, input) {
-  const tempSessionDir = mkdtempSync(join3(tmpdir(), "rig-pi-frontend-sessions-"));
+async function prepareOperatorConsole(context, runId, tempSessionDir) {
   const server = await ensureServerForCli(context.projectRoot);
   let sessionFileArg = [];
   try {
-    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(input.runId)}/session-file`);
+    const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/session-file`);
     if (payload?.ok && typeof payload.content === "string" && payload.content.trim()) {
-      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${input.runId}.jsonl`;
+      const fileName = typeof payload.fileName === "string" && payload.fileName.trim() ? payload.fileName.replace(/[^A-Za-z0-9._-]/g, "_") : `rig-run-${runId}.jsonl`;
       const localSessionPath = join3(tempSessionDir, fileName);
       const content = payload.content.split(`
 `).map((line, index) => {
@@ -7724,6 +7723,11 @@ async function attachRunBundledPiFrontend(context, input) {
       sessionFileArg = ["--session", localSessionPath];
     }
   } catch {}
+  return { server, sessionFileArg };
+}
+async function attachRunBundledPiFrontend(context, input) {
+  const tempSessionDir = mkdtempSync(join3(tmpdir(), "rig-pi-frontend-sessions-"));
+  const { server, sessionFileArg } = await withSpinner(`Opening Pi console for run ${input.runId}\u2026`, () => prepareOperatorConsole(context, input.runId, tempSessionDir), { outputMode: context.outputMode });
   const restoreEnv = setTemporaryEnv(buildOperatorPiEnv({
     runId: input.runId,
     serverUrl: server.baseUrl,
@@ -8554,6 +8558,18 @@ import { computeRigStats } from "@rig/runtime/control-plane/native/run-stats";
 import { intro as intro3, log as log4, note as note4, outro as outro3 } from "@clack/prompts";
 import pc5 from "picocolors";
 var TOP_LEVEL_SECTIONS = [
+  {
+    title: "Pi console",
+    subtitle: "the operator surface \u2014 every attach opens the run's FULL Pi session",
+    commands: [
+      { command: "rig run attach <run-id>", description: "Open the run's Pi console: complete transcript (live AND finished runs), worker turns streaming in live." },
+      { command: "type a message", description: "Inside the console, plain text steers the worker mid-turn \u2014 it lands in the agent's context, not a local model." },
+      { command: "!<command>", description: "Inside the console, runs shell in the WORKER's workspace; output streams back into the transcript." },
+      { command: "/<command>", description: "The palette includes the WORKER session's slash commands ([worker]-tagged) next to /rig." },
+      { command: "/rig abort | /rig stop", description: "Abort the worker's current turn, or stop the whole run, from inside the console." },
+      { command: "rig run steer <id> --message <text>", description: "Steer without attaching \u2014 queue a message; the worker picks it up within seconds." }
+    ]
+  },
   {
     title: "Start here",
     subtitle: "one-time setup, pick a server",
@@ -8568,9 +8584,9 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "find a task, put an agent on it, answer what it asks",
     commands: [
       { command: "rig task list", description: "What's on the board (from the selected source/server)." },
-      { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
+      { command: "rig task run --next", description: "Dispatch an agent on the next ready task; interactive mode drops you into its Pi console." },
       { command: "rig run status", description: "Active and recent runs at a glance." },
-      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig run attach <id> --follow", description: "Same as plain attach \u2014 the Pi console is always the interactive surface." },
       { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
     ]
   },
@@ -8649,29 +8665,35 @@ var PRIMARY_GROUPS = [
   },
   {
     name: "run",
-    summary: "Observe, attach to, and control Rig runs.",
-    usage: ["rig run <list|status|show|attach|stop> [options]"],
+    summary: "Observe, attach to, and control Rig runs. `attach` opens the Pi console \u2014 the full worker session, live.",
+    usage: ["rig run <list|status|show|attach|steer|stop|resume|restart> [options]"],
     commands: [
       { command: "list", description: "List recent runs from the selected server or local state.", primary: true },
       { command: "status", description: "Render active and recent run groups.", primary: true },
       { command: "show <id>|--run <id> [--raw]", description: "Show a human run summary; --raw prints the full payload.", primary: true },
-      { command: "attach <run-id>|--run <id> [--follow]", description: "Attach to the run; --follow opens the enriched bundled Pi (worker brain).", primary: true },
+      { command: "attach <run-id>|--run <id>", description: "Open the run's Pi console \u2014 see 'Inside the console' below. Works on live AND finished runs.", primary: true },
+      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching \u2014 delivered into the agent's context within seconds.", primary: true },
       { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
-      { command: "steer <run-id> --message <text>", description: "Queue a steering message into a live worker without attaching." },
-      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events." },
+      { command: "resume [<run-id>]", description: "Resume an interrupted run on the selected server (defaults to the most recent resumable)." },
+      { command: "restart [<run-id>]", description: "Re-dispatch a run from a clean runtime, reopening its Pi session where possible." },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events (scripts; humans should attach)." },
       { command: "replay <run-id>|--run <id> [--with-session]", description: "Print the run's consolidated run.jsonl as a merged timeline; --with-session interleaves the Pi session log." },
-      { command: "resume", description: "Resume the most recent interrupted local run." },
-      { command: "restart", description: "Restart the most recent local run from a clean runtime." },
       { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
     ],
     examples: [
+      "rig run attach <run-id>          # full session console \u2014 live mirror, steering, worker shell",
+      "rig run steer <run-id> --message 'focus on the failing test first'",
       "rig run list",
-      "rig run status",
       "rig run show <run-id>",
-      "rig run attach <run-id> --follow",
       "rig run stop <run-id>"
     ],
-    next: ["Use `rig task run --next` to create a new run.", "Use `--json` when scripts need the full structured record."]
+    next: [
+      "Inside the console: the run's COMPLETE transcript loads on open (finished runs too), and new worker turns stream in live.",
+      "Inside the console: plain text = steering into the worker's context \xB7 !<cmd> = shell in the WORKER workspace \xB7 /<cmd> includes the worker session's commands \xB7 /rig abort stops the current turn.",
+      "The console is read-write but remote-only: nothing runs on your machine; the worker keeps running when you exit.",
+      "Use `rig task run --next` to create a new run; interactive mode drops you straight into its console.",
+      "Use `--json` when scripts need the full structured record."
+    ]
   },
   {
     name: "inbox",
@@ -8894,7 +8916,7 @@ function renderGroup(group) {
 function renderTopLevelHelp() {
   return [
     `${heading("rig")} ${pc5.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
-    pc5.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox gates."),
+    pc5.dim("The loop: pick a task, dispatch an agent, open its Pi console (`rig run attach <id>`) to watch and steer it live, clear inbox gates, merge."),
     "",
     ...TOP_LEVEL_SECTIONS.flatMap((section) => [
       `${pc5.bold(pc5.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc5.dim(section.subtitle)}`,
@@ -8978,7 +9000,7 @@ function printTopLevelHelp(state = {}) {
     commandLine("--dry-run", "Print the command plan without mutating state.")
   ].join(`
 `), "Global options");
-  outro3("init \u2192 task run \u2192 watch \u2192 inbox \u2192 merged.");
+  outro3("init \u2192 task run \u2192 attach (Pi console: watch + steer live) \u2192 inbox \u2192 merged.");
 }
 function printAdvancedHelp() {
   if (!shouldUseClackOutput2()) {