@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/operator-cli.ts

@@ -2,12 +2,13 @@
 import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
-import type { HarnessAllowance } from "@agentswf/contract/records";
+import type { HarnessAllowance, RefusalCode } from "@agentswf/contract/records";
 import type { JsonObject, JsonValue } from "@agentswf/contract/workflow";
-import { type Harness, handBack, type RunProcess } from "@agentswf/harness";
+import { type Harness, handBack, type RunProcess, terminalAttached } from "@agentswf/harness";
 import manifest from "../package.json" with { type: "json" };
 import { stageFigures } from "./accounting/format";
-import { allowanceCommand } from "./allowance-command";
+import { earlierSpent, unreadEarlier } from "./accounting/spent";
+import { ALLOWANCE_V, allowanceCommand } from "./allowance-command";
 import {
   type AttemptEnd,
   cleanupFailed,
@@ -19,6 +20,7 @@ import {
 } from "./attempt-ending";
 import { type Kept, keepRecords } from "./attempt-output";
 import { continueCommand, printEnding, toldOf } from "./attempt-view";
+import { placeFlags, shellLine } from "./command-line";
 import { type CommandName, helpOf, index, isCommand, reference, unknownCommand } from "./commands";
 import {
   type LineReader,
@@ -28,24 +30,29 @@ import {
 } from "./coordinator-prompt";
 import { coordinatorSocket, prepareCoordinatorDir } from "./coordinator-socket";
 import { EmitError, emitEvent, openEventRun } from "./emit";
-import { emitCommand } from "./emit-command";
+import { didOf, EMIT_V, emitCommand, launchExit } from "./emit-command";
 import { messageOf } from "./errors";
+import { isInside } from "./files";
+import { installedEngine } from "./hand-over";
 import { type Caller, showOwnTab, startHere, takeCaller } from "./here";
-import { holderCommand } from "./holder-command";
-import { inboxCommand } from "./inbox-command";
+import { HOLDER_V, holderCommand } from "./holder-command";
+import { INBOX_V, inboxCommand } from "./inbox-command";
 import { initCommand } from "./init-command";
-import { logsCommand } from "./logs-command";
+import { LOGS_V, logsCommand } from "./logs-command";
 import { coordinatorDir, machinePaths, sandboxesDirOf } from "./machine";
+import { OPEN_V, openCommand } from "./open-command";
 import {
   allowanceReader,
   herdrConfig,
   installOperatorRuntime,
   type OperatorRuntimeInstallation,
+  openRuntime,
   type RunSession,
 } from "./operator-runtime";
 import { ANSI, describeRunSession, type Terminal, watchProgress } from "./progress-view";
-import { parseCommand, type RunCommand, usage } from "./run-command";
-import { placeFlags, shellLine, startedLine } from "./run-commands";
+import { asksJson, NO_JSON, printRefusal, readFailureCode, refusalLine } from "./refusals";
+import { parseCommand, RUN_V, type RunCommand, usage } from "./run-command";
+import { startedLine } from "./run-commands";
 import { runLockFile, withRunLock } from "./run-lock";
 import {
   claimNext,
@@ -56,10 +63,11 @@ import {
 } from "./run-prepare";
 import { findRun } from "./run-state";
 import { type Attempt, createRun, discardRun, endAttempt, type Run, RunRefused } from "./runs";
-import { runsCommand } from "./runs-command";
+import { RUNS_V, runsCommand } from "./runs-command";
+import { readSpent } from "./spend";
 import { stopCrashed } from "./stop-crashed";
 import { testCommand } from "./test-command";
-import { tickCommand } from "./tick-command";
+import { TICK_V, tickCommand } from "./tick-command";
 import type { Launch } from "./wake";
 import type { EventWorkflow, LoadedWorkflow } from "./workflow-loader";
 import {
@@ -102,6 +110,11 @@ export type OperatorEnvironment = {
   readAllowance?: (harness: Harness) => Promise<HarnessAllowance>;
   /** Starts or continues an event run's attempt for `awf emit`; absent, a detached `awf run`. */
   launch?: Launch;
+  /**
+   * The background launch that started this process, which its attempt records; absent, the
+   * environment's `AWF_LAUNCH`.
+   */
+  launchId?: string;
   /**
    * Where agents may `--await-reply`, past the engine's list: for the live checks that decide
    * what goes on it (story 029's M2 gate).
@@ -118,6 +131,12 @@ export type OperatorEnvironment = {
   stdin?: () => Promise<string>;
 };
 
+/** An operator environment with the operator's home and environment variables resolved. */
+type Resolved = OperatorEnvironment & {
+  home: string;
+  environment: Readonly<Record<string, string | undefined>>;
+};
+
 type Output = {
   stdout: (text: string) => void;
   stderr: (text: string) => void;
@@ -127,11 +146,38 @@ type Output = {
   now: () => number;
 };
 
+/**
+ * `given`, its launch taken: the launch names this process's attempt only, so it is read once and
+ * kept from anything the process spawns, `process.env` and an injected environment alike, and a run
+ * an agent starts doesn't record it.
+ */
+export function takeLaunch(given: OperatorEnvironment): OperatorEnvironment {
+  const launchId = given.launchId ?? (given.environment ?? process.env).AWF_LAUNCH;
+  delete process.env.AWF_LAUNCH;
+  const { AWF_LAUNCH: _, ...kept } = given.environment ?? {};
+  return {
+    ...given,
+    ...(given.environment ? { environment: kept } : {}),
+    ...(launchId === undefined ? {} : { launchId }),
+  };
+}
+
 export async function runOperatorCli(
   argv: readonly string[],
-  environment: OperatorEnvironment = {},
+  given: OperatorEnvironment = {},
 ): Promise<number> {
-  const stdout = environment.stdout ?? ((text) => console.log(text));
+  const taken = takeLaunch(given);
+  const environment: Resolved = {
+    ...taken,
+    home: taken.home ?? homedir(),
+    environment: taken.environment ?? process.env,
+  };
+  const print = environment.stdout ?? ((text) => console.log(text));
+  let printed = false;
+  const stdout = (text: string) => {
+    printed = true;
+    print(text);
+  };
   const write = (text: string) => void process.stderr.write(text);
   const stderr =
     environment.stderr ??
@@ -158,16 +204,17 @@ export async function runOperatorCli(
       stderr,
       stdin: environment.stdin ?? (() => new Response(Bun.stdin.stream()).text()),
       ...(environment.stdin ? {} : { stdinIsTerminal: process.stdin.isTTY === true }),
-      ...(environment.environment ? { environment: environment.environment } : {}),
-      ...(environment.home ? { home: environment.home } : {}),
+      environment: environment.environment,
+      home: environment.home,
     });
   const wakes = {
-    home: environment.home ?? homedir(),
-    environment: environment.environment ?? process.env,
+    home: environment.home,
+    environment: environment.environment,
     ...(environment.launch ? { launch: environment.launch } : {}),
   };
+  const output = { stdout, stderr, notice, terminal, now };
   const handlers = {
-    run: () => runCommand(argv, environment, { stdout, stderr, notice, terminal, now }),
+    run: () => runCommand(argv, environment, output),
     test: () => {
       const captured = environment.stdout || environment.stderr ? { stdout, stderr } : undefined;
       return testCommand(argv.slice(1), cwd, {
@@ -185,14 +232,36 @@ export async function runOperatorCli(
       }),
     emit: () => emitCommand(argv.slice(1), cwd, { stdout, stderr }, wakes),
     tick: () => tickCommand(argv.slice(1), cwd, { stdout, stderr }, wakes),
-    runs: () => runsCommand(argv.slice(1), cwd, { stdout, stderr }, Date.now(), wakes.home),
-    logs: () => logsCommand(argv.slice(1), cwd, { stdout, stderr }, undefined, wakes.home),
+    runs: () => runsCommand(argv.slice(1), cwd, { stdout, stderr }, now(), environment.home),
+    logs: () =>
+      logsCommand(
+        argv.slice(1),
+        cwd,
+        { stdout, stderr },
+        { now, sleep: (ms) => Bun.sleep(ms) },
+        environment.home,
+      ),
+    open: () =>
+      openCommand(
+        argv.slice(1),
+        cwd,
+        { stdout, stderr },
+        {
+          home: environment.home,
+          environment: environment.environment,
+          ...openRuntime(environment.environment),
+          ...(environment.signal ? { signal: environment.signal } : {}),
+          ...(environment.stdin
+            ? { stdin: environment.stdin }
+            : { stdinIsTerminal: process.stdin.isTTY === true }),
+        },
+      ),
     inbox: () =>
       inboxCommand(
         argv.slice(1),
         cwd,
         { stdout, stderr },
-        { home: wakes.home, ...(environment.signal ? { signal: environment.signal } : {}) },
+        { home: environment.home, ...(environment.signal ? { signal: environment.signal } : {}) },
       ),
     reply: () => holder(),
     send: () => holder(),
@@ -202,12 +271,7 @@ export async function runOperatorCli(
         stderr,
         read:
           environment.readAllowance ??
-          allowanceReader(
-            environment.environment ?? process.env,
-            undefined,
-            environment.signal,
-            environment.home ?? homedir(),
-          ),
+          allowanceReader(environment.environment, undefined, environment.signal, environment.home),
         now,
       }),
   } satisfies Record<CommandName, () => Promise<number>>;
@@ -222,14 +286,56 @@ export async function runOperatorCli(
       return 2;
     }
     stdout(describeVersion());
+    // Never handed over: what the project here would run on is said beside it.
+    const project = installedEngine(cwd);
+    if (project) stdout(`this project's agentswf ${project.version}, in ${project.dir}`);
     return 0;
   }
   if (word === "help" || word === "-h" || word === "--help") return help(rest, stdout, stderr);
-  if (isCommand(word)) return handlers[word]();
+  if (isCommand(word)) {
+    if (asksHelp(rest)) {
+      stdout(helpOf(word));
+      return 0;
+    }
+    const v = JSON_VERSION[word as keyof typeof JSON_VERSION];
+    if (v === undefined || !asksJson(rest)) return handlers[word]();
+    // What a command didn't foresee still ends its stdout with a document, unless it printed one.
+    try {
+      return await handlers[word]();
+    } catch (error) {
+      if (!printed) printRefusal({ stdout, stderr }, { json: true, v }, error, "internal-error");
+      // The stack is the only clue to a failure no command foresaw.
+      if (error instanceof Error && error.stack) stderr(error.stack);
+      return 1;
+    }
+  }
   stderr(unknownCommand(word));
   return 2;
 }
 
+/** Each `--json` command's `"v"`, which a refusal carries: `awf runs`'s list's for `awf runs`. */
+const JSON_VERSION = {
+  run: RUN_V,
+  emit: EMIT_V,
+  tick: TICK_V,
+  runs: RUNS_V,
+  logs: LOGS_V,
+  inbox: INBOX_V,
+  reply: HOLDER_V,
+  send: HOLDER_V,
+  allowance: ALLOWANCE_V,
+  open: OPEN_V,
+} as const;
+
+/**
+ * One rule for every command: `-h` or `--help` anywhere before `--` prints its help. A word that
+ * must be either, a message's text say, goes after `--`.
+ */
+function asksHelp(words: readonly string[]): boolean {
+  const end = words.indexOf("--");
+  return (end < 0 ? words : words.slice(0, end)).some((word) => word === "-h" || word === "--help");
+}
+
 /** `awf help`, `awf help {command}` and `awf help reference`; `-h` and `--help` are `help`. */
 function help(
   words: readonly string[],
@@ -254,14 +360,13 @@ function help(
   return 0;
 }
 
-/** `awf run`: parses it, then starts or continues the run, here or in a tab. */
 /**
  * `awf run --id` for a workflow with events: the run is made with no event and started detached, as
  * an event starts one, so it runs to its first wait and parks; one already there is only woken.
  */
 async function openRun(
   { loaded, id, argv, panes }: OpensEventRun,
-  environment: OperatorEnvironment,
+  environment: Resolved,
   { stdout, stderr }: Output,
 ): Promise<number> {
   try {
@@ -270,53 +375,42 @@ async function openRun(
       id,
       argv,
       {
-        home: environment.home ?? homedir(),
-        environment: environment.environment ?? process.env,
+        home: environment.home,
+        environment: environment.environment,
         ...(environment.launch ? { launch: environment.launch } : {}),
       },
       panes,
     );
-    const did = opened.did === "none" ? opened.why : opened.did;
-    stdout(
-      `${opened.run}${opened.created ? "" : " was there"}${did === undefined ? "" : `: ${did}`}`,
-    );
-    if (opened.why !== "launch-failed") return 0;
-    stderr(`awf: the run's attempt did not start: ${opened.error}`);
-    return 1;
+    stdout(`${opened.run}${opened.created ? "" : " was there"}${didOf(opened)}`);
+    return launchExit(opened, { stdout, stderr });
   } catch (error) {
-    stderr(`awf: ${messageOf(error)}`);
+    printRefusal({ stdout, stderr }, NO_JSON, error, readFailureCode(error));
     return error instanceof EmitError ? 2 : 1;
   }
 }
 
+/** `awf run`: parses it, then starts or continues the run, here or in a tab. */
 async function runCommand(
   argv: readonly string[],
-  environment: OperatorEnvironment,
+  environment: Resolved,
   output: Output,
 ): Promise<number> {
-  const { stdout, stderr, notice, terminal, now } = output;
-  let parsed: RunCommand | "help";
+  const { stdout, stderr, notice, now } = output;
+  let parsed: RunCommand;
   try {
-    parsed = parseCommand(argv, environment.cwd ?? process.cwd(), stderr);
+    parsed = parseCommand(argv, environment.cwd ?? process.cwd());
   } catch (error) {
-    stderr(`awf: ${messageOf(error)}\n\n${usage}`);
+    printRefusal({ stdout, stderr }, { json: asksJson(argv), v: RUN_V }, error, "usage", usage);
     return 2;
   }
-  if (parsed === "help") {
-    stdout(usage);
-    return 0;
-  }
   let command: RunCommand = parsed;
+  // With --json, what makes no run is a refusal, as its sentence on stderr says.
+  const refused = (code: RefusalCode, error: string) =>
+    printRefusal({ stdout, stderr }, { json: command.json, v: RUN_V }, error, code);
   const meant = await runNamed(command);
   if (meant) {
-    const look = shellLine([
-      "awf",
-      "runs",
-      meant,
-      ...(command.cwdGiven ? ["--cwd", command.cwd] : []),
-      ...(command.runRootGiven ? ["--run-root", command.runRoot] : []),
-    ]);
-    stderr(`awf: ${command.workflowFile} is not a workflow file; did you mean: ${look}`);
+    const look = shellLine(["awf", "runs", meant, ...placeFlags(command)]);
+    refused("file", `${command.workflowFile} is not a workflow file; did you mean: ${look}`);
     return 2;
   }
   if (command.here) return startHere(argv, command, environment, stdout, stderr, notice);
@@ -326,19 +420,20 @@ async function runCommand(
     if (command.session !== undefined) await showOwnTab(environment);
     return exitCode;
   };
-  const home = environment.home ?? homedir();
+  const { home } = environment;
   const { sandboxes, callers } = machinePaths(home);
   const ready = await loadAndPrepare(command, now(), home);
   if ("refused" in ready) {
-    stderr(`awf: ${ready.refused}`);
+    refused(ready.code, ready.refused);
     return unstarted(2);
   }
   if ("opens" in ready) return openRun(ready.opens, environment, output);
   // After loading: an event run's root is its project's, which this checks too.
   command = ready.command;
-  if (!relative(command.runRoot, sandboxes).startsWith("..")) {
-    stderr(
-      `awf: --run-root ${command.runRoot} holds ${sandboxes}, which every sandbox must reach and none may reach the run root`,
+  if (relative(command.runRoot, sandboxes) === "" || isInside(command.runRoot, sandboxes)) {
+    refused(
+      "usage",
+      `--run-root ${command.runRoot} holds ${sandboxes}, which every sandbox must reach and none may reach the run root`,
     );
     return unstarted(2);
   }
@@ -347,28 +442,24 @@ async function runCommand(
   // Loading the workflow imports operator-supplied code before anything listens to the signal, so
   // a Ctrl-C in it would otherwise be swallowed and have to be pressed again.
   if (environment.signal?.aborted) {
+    if (command.json) stdout(refusalLine(RUN_V, "not-started", CANCELLED));
     return unstarted(cancelledBeforeStart(environment.signal, stderr));
   }
   let calling: { caller: Caller; release: () => void } | undefined;
   if (command.session !== undefined) {
     const taken = await takeCaller(command.session, callers, environment);
     if (typeof taken === "string") {
-      stderr(`awf: --session: ${taken}`);
+      refused("not-started", `--session: ${taken}`);
       return 1;
     }
     calling = taken;
     if (environment.signal?.aborted) {
       calling.release();
+      if (command.json) stdout(refusalLine(RUN_V, "not-started", CANCELLED));
       return cancelledBeforeStart(environment.signal, stderr);
     }
   }
-  return runAttempt(command, ready, calling, environment, home, {
-    stdout,
-    stderr,
-    notice,
-    terminal,
-    now,
-  });
+  return runAttempt(command, ready, calling, environment, output);
 }
 
 /** The run `awf run {ref}` names where `{ref}` is no file: one meant for `awf runs`. */
@@ -386,11 +477,11 @@ async function runAttempt(
   command: RunCommand,
   { loaded, prepared }: { loaded: LoadedWorkflow; prepared: PreparedRun },
   calling: { caller: Caller; release: () => void } | undefined,
-  environment: OperatorEnvironment,
-  home: string,
+  environment: Resolved,
   output: Output,
 ): Promise<number> {
   const { stdout, stderr, notice, terminal, now } = output;
+  const { home } = environment;
   const { workflow } = loaded;
   const { meta } = workflow;
   /** The run, once it is claimed. */
@@ -410,21 +501,21 @@ async function runAttempt(
     if (failed) stderr(`awf: the calling session was not told the run ended: ${failed}`);
   };
 
-  const refuse = async (why: string) => {
-    stderr(`awf: ${why}`);
+  const refuse = async (why: string, code: RefusalCode) => {
+    printRefusal({ stdout, stderr }, { json: command.json, v: RUN_V }, why, code);
     await handOver(`did not start: ${why}`);
     return 2;
   };
   // The operator's, never where the workflow's agents work.
-  const coordinatorRoot = coordinatorDir(home, environment.environment ?? process.env);
+  const coordinatorRoot = coordinatorDir(home, environment.environment);
   try {
     await prepareCoordinatorDir(
       coordinatorRoot,
       command.cwd,
-      Boolean((environment.environment ?? process.env).AWF_COORDINATOR_DIR),
+      Boolean(environment.environment.AWF_COORDINATOR_DIR),
     );
   } catch (error) {
-    return refuse(messageOf(error));
+    return refuse(messageOf(error), "internal-error");
   }
   try {
     run =
@@ -440,15 +531,16 @@ async function runAttempt(
   } catch (error) {
     return refuse(
       `${error instanceof RunRefused ? "" : `${command.runRoot}: `}${messageOf(error)}`,
+      readFailureCode(error),
     );
   }
   let attempt: Attempt;
   try {
-    attempt = await claimNext(run, loaded, command, notice, now());
+    attempt = await claimNext(run, loaded, command, notice, now(), environment.launchId);
   } catch (error) {
     // A run this call created and never ran is not left to hold its id.
     if (!prepared.continued) await discardRun(run).catch(() => undefined);
-    return refuse(messageOf(error));
+    return refuse(messageOf(error), readFailureCode(error));
   }
   const { id, cwd } = run.record;
   const locked = <T>(work: () => Promise<T>) =>
@@ -462,7 +554,7 @@ async function runAttempt(
   if (run.record.events && previous && previous.ended === undefined)
     await stopCrashed(previous, workspaceLabel(meta.name, run.record.id, previous.attempt), {
       home,
-      environment: environment.environment ?? process.env,
+      environment: environment.environment,
     }).catch((error: unknown) =>
       notice(
         `awf: what attempt ${previous.attempt} left running was not all stopped: ${messageOf(error)}`,
@@ -473,14 +565,26 @@ async function runAttempt(
     attempt,
     loaded,
     stderr,
+    now,
     ...(!run.record.events ? {} : { locked }),
   };
-  const close = (end: AttemptEnd, kept: Kept, cleanupAlso?: string) =>
-    printEnding(end, kept, {
+  const close = async (end: AttemptEnd, kept: Kept, cleanupAlso?: string) => {
+    const earlier = prepared.continued?.attempts ?? [];
+    // Priced now, from what each earlier attempt's operations recorded, its claim's settling included.
+    const spentBefore =
+      n > 1
+        ? await readSpent(run.dir, earlier).then(
+            (spent) => earlierSpent(spent, earlier, n),
+            // Still a total, with every earlier attempt's cost unknown.
+            () => unreadEarlier(earlier, n),
+          )
+        : undefined;
+    return printEnding(end, kept, {
       workflow,
       run: { id, dir: run.dir },
       n,
-      earlier: prepared.continued?.attempts ?? [],
+      earlier,
+      ...(spentBefore ? { spentBefore } : {}),
       json: command.json,
       fromStage: command.fromStage !== undefined,
       now: now(),
@@ -492,6 +596,7 @@ async function runAttempt(
       stderr,
       notice,
     });
+  };
   // Timed from here: finding the calling session can take minutes the run itself never had.
   const startedAt = now();
   // Every way out from here writes the attempt's ending, before the hand-back: a session told the
@@ -510,7 +615,12 @@ async function runAttempt(
       const said = cancelled
         ? "run cancelled before it started"
         : `${end.ending.reason}; the run did not start`;
-      stderr(`awf: ${said}, and nothing of it is kept`);
+      printRefusal(
+        { stdout, stderr },
+        { json: command.json, v: RUN_V },
+        `${said}, and nothing of it is kept`,
+        "not-started",
+      );
       await handOver(`did not start: ${cancelled ? "cancelled" : end.ending.reason}`);
       return end.exitCode;
     }
@@ -556,7 +666,7 @@ async function runAttempt(
   placed = (session) => {
     progress.placedIn(session.name);
     const label = workspaceLabel(meta.name, id, n);
-    const insideHerdr = (environment.environment ?? process.env).HERDR_ENV === "1";
+    const insideHerdr = environment.environment.HERDR_ENV === "1";
     for (const line of describeRunSession(session, label, insideHerdr)) progress.log(line);
   };
   // Interactive: a coordinator's questions are asked here, unless the output is for a program.
@@ -590,7 +700,8 @@ async function runAttempt(
       run: {
         dir: run.dir,
         id,
-        attempt: n,
+        lines: attempt.lines,
+        ops: attempt.ops,
         label: workspaceLabel(meta.name, id, n),
         ...(command.fromStage === undefined ? {} : { fromStage: command.fromStage }),
         ...(command.values === undefined ? {} : { values: command.values.stages }),
@@ -617,7 +728,7 @@ async function runAttempt(
           await emitEvent(target, event, {
             from,
             home,
-            environment: environment.environment ?? process.env,
+            environment: environment.environment,
             ...(environment.launch ? { launch: environment.launch } : {}),
           })
         ).outcome,
@@ -698,8 +809,10 @@ export function stderrLines(
   };
 }
 
+const CANCELLED = "run cancelled before it started";
+
 function cancelledBeforeStart(signal: AbortSignal, stderr: (line: string) => void): number {
-  stderr("awf: run cancelled before it started");
+  stderr(`awf: ${CANCELLED}`);
   return signalExitCode(signal.reason);
 }
 
@@ -738,16 +851,19 @@ const EXIT_GRACE_MS = 2_000;
  * Cancels `controller` at the first signal that asks the run to stop, and stops the process at
  * once at a second the operator sends, without the run's cleanup. Ctrl-C reaches the whole
  * process group and `bun awf` forwards it once more, so a repeat within `REPEAT_MS` is ignored:
- * taken as the second, it would kill the run mid-cleanup and leave its sandboxes behind. Returns
- * what removes the handlers.
+ * taken as the second, it would kill the run mid-cleanup and leave its sandboxes behind. While a
+ * person's TUI has the terminal, Ctrl-C is the TUI's: ending awf then would leave it writing a
+ * session nothing holds. Returns what removes the handlers.
  */
 export function cancelOnSignals(
   controller: AbortController,
   exit: (code: number) => void = (code) => process.exit(code),
   now: () => number = Date.now,
+  attached: () => boolean = terminalAttached,
 ): () => void {
   let first: number | undefined;
   const cancel = (signal: NodeJS.Signals) => {
+    if (signal === "SIGINT" && attached()) return;
     if (first === undefined) {
       first = now();
       controller.abort(signal);

package/src/operator-runtime.ts

@@ -23,6 +23,7 @@ import {
   readClaudeBilling,
   readCodexBilling,
   readCursorLogin,
+  runAttached,
   runProcess,
   withholding,
 } from "@agentswf/harness";
@@ -37,7 +38,7 @@ import { createSrtProvider, findSrt } from "@agentswf/sandbox/srt";
 import { createOpenRouterProvider } from "./decisions/openrouter";
 import type { DecisionInstallation } from "./decisions/seam";
 import { messageOf } from "./errors";
-import { findOrigin, namedSession, workspaceLock } from "./herdr-placement";
+import { findOrigin, workspaceLock } from "./herdr-placement";
 import {
   ensureRunSession,
   parseSessions,
@@ -48,6 +49,7 @@ import { markWorkspace } from "./herdr-workspace-marks";
 
 export type { RunSession } from "./herdr-run-session";
 
+import type { Attach } from "./open-command";
 import { OPERATOR_ALIASES } from "./operator-aliases";
 
 export type OperatorRuntimeInstallation = {
@@ -129,7 +131,6 @@ export async function installOperatorRuntime(
           const config: HerdrConfig = {
             ...runConfig(name),
             onRunWorkspace: mark.bind,
-            sessionFor: (named) => namedSession(named, { run, environment, home }),
             origin: () =>
               findOrigin({
                 run,
@@ -424,6 +425,27 @@ const WITHHELD_ENVIRONMENT = [
   "AWF_CALLER_SESSIONS",
 ];
 
+/**
+ * How `awf open` runs a harness on an agent's session: its fork and `-p` turn, and its TUI on this
+ * terminal, each withholding what no agent inherits (story 042).
+ */
+export function openRuntime(environment: Readonly<Record<string, string | undefined>>): {
+  run: RunProcess;
+  attach: Attach;
+  providers: () => Promise<SandboxProviders>;
+} {
+  const withheld = Object.fromEntries(WITHHELD_ENVIRONMENT.map((name) => [name, undefined]));
+  return {
+    run: withholding(runProcess, WITHHELD_ENVIRONMENT),
+    // A sandbox's command has exactly its own environment; on the host, the operator's less these.
+    attach: (input) =>
+      input.exact
+        ? runAttached(input, {})
+        : runAttached({ ...input, env: { ...input.env, ...withheld } }, environment),
+    providers: () => installSandboxes(environment),
+  };
+}
+
 /**
  * Unset in a run's panes besides: the config the run session's server starts with, which a `herdr`
  * started in a pane would otherwise read in place of the operator's.