humanish 0.56.0 → 0.58.0

package/README.md

@@ -67,6 +67,44 @@ npx skills add danielgwilson/humanish --skill humanish
 The skill lives at [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md)
 for skills.sh discovery.
 
+## A First Live Run Without a Provider API Key
+
+A live study normally needs a provider API key. If you already have a coding
+agent signed in — Codex on a ChatGPT plan, Claude Code on a Max plan — humanish
+can use it as the participant's brain instead, and then the only credential it
+needs is `E2B_API_KEY`.
+
+```bash
+humanish doctor      # says which local agents are installed and signed in
+```
+
+```yaml
+actors:
+  - type: local-agent   # instead of openai-computer-use
+    persona: synthetic-new-user
+    mission: >-
+      ...
+```
+
+humanish never reads those credentials. It checks that the credential file
+**exists**, spawns the CLI tool-restricted (`--sandbox read-only` for Codex,
+`--allowedTools Read` for Claude Code) in a scratch directory, and hands it one
+screenshot per turn. The agent only **decides**; humanish performs the action
+inside the E2B sandbox, so nothing the persona chooses ever runs on your machine.
+
+Three things to know before you rely on it:
+
+- **It is not free.** Subscription usage consumes your own plan. Runs driven this
+  way record `estimatedCostUsd: null` with `reason: "no_token_usage"` rather than
+  `$0`, because `$0` would be untrue. Rate limits on those plans are built for
+  interactive coding; humanish fails closed with the CLI's own message rather
+  than retrying into them.
+- **It is slower.** Roughly 9 seconds per turn against about 3 for a direct API
+  call, so give the lane a longer `execution.timeoutMs` than you would otherwise.
+- **The evidence says which brain ran it.** The trace records
+  `ids.model: "codex (local, operator-authenticated)"`, so a local-agent run is
+  never silently compared against an API one.
+
 ## Public-Safety Boundary
 
 Humanish is designed for public repositories and public issue queues. The

package/dist/actor-registry.d.ts

@@ -6,7 +6,7 @@ import { type ClaudeAgentSessionOptions, type ClaudeAgentSessionResult, type Cla
 import { type CuaActorSessionOptions } from "./computer-use-actor.js";
 import type { CuaLoopResult } from "./computer-use.js";
 import { type ScriptedBrowserSessionOptions, type ScriptedBrowserSessionResult } from "./scripted-browser-actor.js";
-export type ActorId = "codex-app-server" | "pi-agent-core" | "claude-agent-sdk" | "openai-computer-use" | "scripted-browser" | "codex-exec";
+export type ActorId = "codex-app-server" | "pi-agent-core" | "claude-agent-sdk" | "openai-computer-use" | "local-agent" | "scripted-browser" | "codex-exec";
 interface ActorDescriptorBase {
     id: ActorId;
     label: string;
@@ -30,6 +30,10 @@ export interface CuaActorDescriptor extends ActorDescriptorBase {
     id: "openai-computer-use";
     runSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;
 }
+export interface LocalAgentActorDescriptor extends ActorDescriptorBase {
+    id: "local-agent";
+    runSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;
+}
 export interface ScriptedBrowserActorDescriptor extends ActorDescriptorBase {
     id: "scripted-browser";
     runSession(options: ScriptedBrowserSessionOptions): Promise<ScriptedBrowserSessionResult>;
@@ -38,7 +42,7 @@ export interface TerminalActorDescriptor extends ActorDescriptorBase {
     id: "codex-exec";
     runSession(options: TerminalAgentSessionOptions): Promise<TerminalAgentSessionResult>;
 }
-export type ActorDescriptor = CodexActorDescriptor | PiActorDescriptor | ClaudeActorDescriptor | CuaActorDescriptor | ScriptedBrowserActorDescriptor | TerminalActorDescriptor;
+export type ActorDescriptor = CodexActorDescriptor | PiActorDescriptor | ClaudeActorDescriptor | CuaActorDescriptor | LocalAgentActorDescriptor | ScriptedBrowserActorDescriptor | TerminalActorDescriptor;
 /**
  * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
  * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.

package/dist/actor-registry.js

@@ -4,6 +4,7 @@ import { runTerminalAgentSession } from "./terminal-agent-actor.js";
 import { piSessionToActorTrace } from "./pi-agent-core.js";
 import { claudeSessionToActorTrace, runClaudeAgentSession } from "./claude-agent-sdk.js";
 import { runCuaActorSession } from "./computer-use-actor.js";
+import { LOCAL_AGENT_CAPABILITIES } from "./local-agent-cli.js";
 import { OPENAI_RESPONSES_CU_CAPABILITIES } from "./openai-responses-cu.js";
 import { runScriptedBrowserSession } from "./scripted-browser-actor.js";
 /**
@@ -58,6 +59,17 @@ export const actorRegistry = {
     },
     // The ActorId names the actor slot (keeps the lane open for a future stagehand-cua provider);
     // the trace's `provider` string stays "openai-responses-cu" (the concrete model adapter).
+    // The operator's own signed-in coding agent as the computer-use brain (Codex on a ChatGPT plan,
+    // Claude Code on a Max plan). Same lane, same loop, same evidence — the only difference is where
+    // the next action comes from, which is exactly why it is a provider swap and not a new lane.
+    // It exists so someone new can watch a persona drive a real desktop without first going to find
+    // an API key; the machine they are on very often already has one of these signed in.
+    "local-agent": {
+        id: "local-agent",
+        label: "Local coding agent (operator-authenticated)",
+        capabilities: LOCAL_AGENT_CAPABILITIES,
+        runSession: runCuaActorSession
+    },
     "openai-computer-use": {
         id: "openai-computer-use",
         label: "OpenAI Computer Use",

package/dist/actor-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"actor-registry.js","sourceRoot":"","sources":["../src/actor-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAGzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,EAC7B,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EAIxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EAGxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAwB,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAA+B,MAAM,yBAAyB,CAAC;AAE1F,OAAO,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,yBAAyB,EAG1B,MAAM,6BAA6B,CAAC;AAqErC;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA2B;IAC9D,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAAC,UAA2B;IAC1E,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAA2B;IACnE,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAqC;IAC7D,kBAAkB,EAAE;QAClB,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,kBAAkB;QACzB,YAAY,EAAE,6BAA6B;QAC3C,UAAU,EAAE,wBAAwB;QACpC,YAAY,EAAE,uBAAuB;KACtC;IACD,eAAe,EAAE;QACf,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,eAAe;QACtB,YAAY,EAAE,0BAA0B;QACxC,YAAY,EAAE,qBAAqB;KACpC;IACD,kBAAkB,EAAE;QAClB,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,kBAAkB;QACzB,YAAY,EAAE,6BAA6B;QAC3C,UAAU,EAAE,qBAAqB;QACjC,YAAY,EAAE,yBAAyB;KACxC;IACD,8FAA8F;IAC9F,0FAA0F;IAC1F,qBAAqB,EAAE;QACrB,EAAE,EAAE,qBAAqB;QACzB,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,gCAAgC;QAC9C,UAAU,EAAE,kBAAkB;KAC/B;IACD,uFAAuF;IACvF,8DAA8D;IAC9D,gEAAgE;IAChE,kBAAkB,EAAE;QAClB,EAAE,EAAE,kBAAkB;QACtB,KAAK,EAAE,mDAAmD;QAC1D,YAAY,EAAE,6BAA6B;QAC3C,UAAU,EAAE,yBAAyB;KACtC;IACD,4FAA4F;IAC5F,yFAAyF;IACzF,gGAAgG;IAChG,+DAA+D;IAC/D,YAAY,EAAE;QACZ,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,oDAAoD;QAC3D,YAAY,EAAE,2BAA2B;QACzC,UAAU,EAAE,uBAAuB;KACpC;CACF,CAAC;AAWF,MAAM,UAAU,QAAQ,CAAC,EAAW;IAClC,MAAM,KAAK,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"actor-registry.js","sourceRoot":"","sources":["../src/actor-registry.ts"],"names":[],"mappings":"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"}

package/dist/agent-session.d.ts

@@ -0,0 +1,11 @@
+export interface AgentSession {
+    /** Human-readable runner name, for the refusal message. */
+    runner: string;
+    /** The environment variable that identified it — named so the reader can check us. */
+    marker: string;
+}
+/**
+ * The agent runner driving this process, when one identifies itself. `undefined` means nothing
+ * claimed to be an agent — which is NOT proof a person is there, only the absence of a claim.
+ */
+export declare function detectAgentSession(env?: NodeJS.ProcessEnv): AgentSession | undefined;

package/dist/agent-session.js

@@ -0,0 +1,43 @@
+// Is the terminal on the other end of this process a PERSON's, or an agent's?
+//
+// WHY THIS EXISTS: `humanish tui` refused a non-TTY, on the reasoning that an agent driving an
+// interactive surface has asked for something that cannot exist. A study of that refusal
+// (labs/handed-a-human-surface.yaml) found it never fires: `codex exec` allocates a PTY for the
+// commands it runs, so both streams ARE terminals. The TUI launched, the agent navigated the labs
+// list, opened one, and — its own words — "accidentally triggered a zero-cost dry run while
+// navigating". A stray Enter on a live row is the same two keystrokes as a deliberate one.
+//
+// So a TTY is a real answer to the wrong question. It says a terminal exists; it does not say
+// anyone is reading it. Agent runners announce themselves in the environment, which is the only
+// signal available before the first keystroke, and is what `is-in-ci` has always done for CI.
+//
+// EVERY MARKER BELOW WAS OBSERVED, not guessed. Two runtimes are covered because two are what we
+// could verify: Claude Code (read off a live session) and Codex (read off the study sandbox, by a
+// names-only `env | cut -d= -f1` probe that never touched a value). Others certainly exist — add
+// them the same way, from a real session, rather than from a plausible-looking guess. A marker
+// that is wrong refuses a person for no reason.
+const MARKERS = [
+    { marker: "CLAUDECODE", runner: "Claude Code" },
+    { marker: "CLAUDE_CODE_SESSION_ID", runner: "Claude Code" },
+    { marker: "CODEX_SESSION_ID", runner: "Codex" },
+    { marker: "CODEX_THREAD_ID", runner: "Codex" },
+    // Generic, and set alongside the Claude Code markers on the machine this was written on. Kept
+    // last so a named runner wins the attribution.
+    { marker: "AI_AGENT", runner: "an AI agent runner" }
+];
+/**
+ * The agent runner driving this process, when one identifies itself. `undefined` means nothing
+ * claimed to be an agent — which is NOT proof a person is there, only the absence of a claim.
+ */
+export function detectAgentSession(env = process.env) {
+    for (const { marker, runner } of MARKERS) {
+        const value = env[marker];
+        // Presence is the signal, but an explicitly empty or "0" value is treated as absence: a
+        // wrapper that unsets a marker by blanking it means it.
+        if (value !== undefined && value.trim().length > 0 && value.trim() !== "0") {
+            return { runner, marker };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent-session.js.map

package/dist/agent-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session.js","sourceRoot":"","sources":["../src/agent-session.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,+FAA+F;AAC/F,yFAAyF;AACzF,gGAAgG;AAChG,kGAAkG;AAClG,4FAA4F;AAC5F,2FAA2F;AAC3F,EAAE;AACF,8FAA8F;AAC9F,gGAAgG;AAChG,8FAA8F;AAC9F,EAAE;AACF,iGAAiG;AACjG,kGAAkG;AAClG,iGAAiG;AACjG,+FAA+F;AAC/F,gDAAgD;AAShD,MAAM,OAAO,GAAsD;IACjE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE;IAC/C,EAAE,MAAM,EAAE,wBAAwB,EAAE,MAAM,EAAE,aAAa,EAAE;IAC3D,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO,EAAE;IAC/C,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,OAAO,EAAE;IAC9C,8FAA8F;IAC9F,+CAA+C;IAC/C,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,wFAAwF;QACxF,wDAAwD;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cua-actor-lab.d.ts

@@ -5,6 +5,7 @@ import { type CuaActorDescriptor } from "./actor-registry.js";
 import type { CuaActorSessionOptions } from "./computer-use-actor.js";
 import type { CuaExecutor, CuaLoopResult, CuaProvider } from "./computer-use.js";
 import type { ReasoningEffort } from "./reasoning-effort.js";
+import { type LocalAgentId } from "./local-agent-cli.js";
 import { type E2BDesktopModule, type E2BDesktopSandbox } from "./e2b-desktop-launch.js";
 import { type DetachedTimers } from "./e2b-detached.js";
 import { type DevicePreset } from "./device-presets.js";
@@ -416,6 +417,14 @@ export declare function composeLaneInstructions(args: {
      *  no committed file, unparseable YAML) keeps the honest fallback: the bare line and an EMPTY
      *  traitsApplied, never fabricated traits. Resolved by the caller so this stays pure. */
     resolvedPersona?: ResolvedPersona;
+    /**
+     * desktop-cli (#495): the surface under study is a terminal window, not a page. Said plainly
+     * because a participant whose every prior world was a browser will look for one — and because a
+     * capability nobody declares is one the recording cannot later be read against. It states that a
+     * terminal is open and NOT what to type in it: naming commands would answer the question the
+     * study is asking.
+     */
+    surface?: "desktop-cli";
 }): {
     instructions: string;
     persona: ActorPersonaRef;
@@ -504,7 +513,11 @@ export interface CuaLaneDeps {
     config: LabConfig;
     descriptor: CuaActorDescriptor;
     appUrl: string;
+    /** When set, the computer-use brain is this locally-signed-in CLI instead of a keyed API. */
+    localAgent?: LocalAgentId;
     cloneRoute: boolean;
+    /** desktop-cli (#495): a CLI studied at a desktop. Nothing is cloned and no browser is opened. */
+    desktopCliRoute?: boolean;
     /** Optional so out-of-scope callers building CuaLaneDeps directly (other engines reusing
      *  runCuaLane) do not need to know about the local-tree route; undefined behaves as false. */
     localTreeRoute?: boolean;

package/dist/cua-actor-lab.js

@@ -31,6 +31,8 @@ import { adapterScoreFailureMessage, applyBrowserAdapterHooks } from "./adapter-
 import { actorRegistry, isCuaActorDescriptor } from "./actor-registry.js";
 import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson } from "./browser-evidence-hygiene.js";
 import { DEFAULT_OPENAI_CU_MODEL } from "./openai-responses-cu.js";
+import { createLocalAgentProvider, detectLocalAgents } from "./local-agent-cli.js";
+import { startAppServerSession } from "./local-agent-appserver.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
 import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, collectExternalCommsThread, deployCommsCatch, externalCatchHealthy, externalInboxUrl, refreshInboxSurface, writeInboxSurface } from "./comms-sandbox-catch.js";
@@ -136,9 +138,13 @@ export function composeLaneInstructions(args) {
         ? renderPersonaPromptSection(args.resolvedPersona)
         : args.persona ? `Persona: ${args.persona}.` : undefined;
     const traitsApplied = args.resolvedPersona ? personaToDirectives(args.resolvedPersona).traitsApplied : [];
+    const surfaceLine = args.surface === "desktop-cli"
+        ? "A terminal window is already open on this desktop, and there is a terminal in the dock at the bottom of the screen if you want another. Everything you need is on this machine; there is no browser task here."
+        : undefined;
     const parts = [
         personaLine,
         deviceLine,
+        surfaceLine,
         args.mission,
         taskLines,
         args.instruction ? `Lane focus: ${args.instruction}` : undefined
@@ -291,7 +297,8 @@ function laneSpecsAndPlan(config, opts = {}) {
             ...(personaId === undefined ? {} : { persona: personaId }),
             ...(resolvedPersona === undefined ? {} : { resolvedPersona }),
             ...(((roster ? lane?.instruction : actor?.laneFocus?.instruction)) === undefined ? {} : { instruction: (roster ? lane?.instruction : actor?.laneFocus?.instruction) }),
-            device: { name: device.name, preset: device.preset }
+            device: { name: device.name, preset: device.preset },
+            ...(config.subject.source === "desktop-cli" ? { surface: "desktop-cli" } : {})
         });
         lanes.push({
             laneId,
@@ -1069,6 +1076,91 @@ export async function captureDesktopBrowserGeometry(args) {
 function shellSingleQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+/**
+ * Put a CLI on the desktop before the participant arrives (#495).
+ *
+ * The install runs UNKEYED and before the session starts, for the same reason the clone route
+ * provisions its subject first: what is being studied begins when the participant looks at the
+ * screen, and making them fight an install first would be a study of the install.
+ */
+async function provisionDesktopCli(desktop, args) {
+    const install = args.install;
+    if (install === undefined)
+        return;
+    const now = () => Date.now();
+    if (needsNodeRuntime([install])) {
+        const startedAt = now();
+        emitPhaseStarted(args.onPhase, now, "runtime", "providing the Node runtime the install needs");
+        const bootstrap = await runDetachedStep(desktop, {
+            name: "desktop-cli-runtime-node",
+            command: nodeBootstrapCommand(),
+            cwd: "/home/user",
+            timeoutMs: INSTALL_TIMEOUT_MS,
+            requestTimeoutMs: args.requestTimeoutMs
+        });
+        emitPhaseCompleted(args.onPhase, now, startedAt, "runtime", bootstrap.ok, bootstrap.ok
+            ? "Node runtime ready"
+            : "Node runtime bootstrap failed");
+        if (!bootstrap.ok) {
+            throw new Error(`desktop-cli runtime bootstrap failed for "${args.product}"`);
+        }
+    }
+    const startedAt = now();
+    emitPhaseStarted(args.onPhase, now, "install", `installing ${args.product} on the desktop`);
+    const result = await runDetachedStep(desktop, {
+        name: "desktop-cli-install",
+        command: install,
+        cwd: "/home/user",
+        timeoutMs: INSTALL_TIMEOUT_MS,
+        requestTimeoutMs: args.requestTimeoutMs
+    });
+    emitPhaseCompleted(args.onPhase, now, startedAt, "install", result.ok, result.ok
+        ? `${args.product} installed`
+        : `installing ${args.product} failed`);
+    if (!result.ok) {
+        // Fail closed: a participant handed a desktop where the product is not installed would produce
+        // a transcript about a missing command, and that finding belongs to the harness, not the tool.
+        // The tail rides along, scrubbed before truncation like every other provisioning failure — a
+        // bare "install failed" is unactionable to whoever wrote the command.
+        throw new Error(args.scrub(`desktop-cli install failed for "${args.product}" (${result.timedOut ? "timed out" : `exit ${result.exitCode ?? "?"}`}): ${tailOf(args.scrub(result.logTail))}`));
+    }
+}
+/**
+ * Open a terminal window on the desktop.
+ *
+ * The stock template is XFCE and ships xfce4-terminal (also aliased x-terminal-emulator), verified
+ * live before this route was built. `x-terminal-emulator` is tried first so a template that swaps
+ * the emulator still works; a desktop with neither is a template problem and fails closed rather
+ * than handing a participant an empty screen and calling it a study.
+ */
+async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
+    const dir = workdir ?? "/home/user";
+    const result = await runDetachedStep(desktop, {
+        name: "desktop-cli-terminal",
+        command: [
+            "for candidate in x-terminal-emulator xfce4-terminal gnome-terminal konsole xterm; do",
+            '  if command -v "$candidate" >/dev/null 2>&1; then',
+            // LANG is set on the terminal we open, not globally: the stock image declares no locale, and
+            // a study that measures our own mojibake against an unconfigured template would be measuring
+            // the template. The PRODUCT-side fix (an ASCII fallback when the locale is not UTF-8) is in
+            // src/terminal-encoding.ts, and it is the one that matters for real users.
+            `    (cd ${shellSingleQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 nohup "$candidate" >/dev/null 2>&1 &)`,
+            "    sleep 3",
+            '    echo "humanish: opened $candidate"',
+            "    exit 0",
+            "  fi",
+            "done",
+            "echo 'humanish: no terminal emulator on this desktop template' >&2",
+            "exit 1"
+        ].join("\n"),
+        cwd: "/home/user",
+        timeoutMs: 60_000,
+        requestTimeoutMs
+    });
+    if (!result.ok) {
+        throw new Error("desktop-cli lane could not open a terminal on this desktop template");
+    }
+}
 async function startDesktopStream(desktop, browserWindowId) {
     if (!browserWindowId) {
         await desktop.stream.start({ requireAuth: true });
@@ -1182,6 +1274,10 @@ export function resolveSelfReportedFriction(session) {
  */
 export async function runCuaLane(spec, deps) {
     const { config, appUrl, cloneRoute, localTreeRoute, serve, subjectRepo, subjectEnvNames } = deps;
+    const desktopCliRoute = deps.desktopCliRoute === true;
+    // The local brain, when there is one. `appServer` owns a process, so the lane closes it.
+    let appServer;
+    let localAgentProvider;
     const subjectEnvValues = config.subject.envValues ?? {};
     const targetUrl = spec.targetUrl ?? appUrl;
     const env = deps.env;
@@ -1409,6 +1505,18 @@ export async function runCuaLane(spec, deps) {
                     warnings: [...(desktopGeometry.warnings ?? []), mismatchWarning]
                 };
             }
+            if (desktopCliRoute) {
+                // Put the product on the desktop before the participant sees it. UNKEYED, like every other
+                // provisioning step: the participant's world is prepared by the harness, and what is being
+                // studied starts at the moment they look at the screen.
+                await provisionDesktopCli(desktop, {
+                    product: config.subject.product?.name ?? "",
+                    ...(config.subject.product?.install === undefined ? {} : { install: config.subject.product.install }),
+                    requestTimeoutMs: deps.requestTimeoutMs,
+                    scrub: deps.scrubKnownValues,
+                    onPhase: onSubjectPhase
+                });
+            }
             if (cloneRoute && serve && subjectRepo) {
                 subjectCommit = await provisionCloneSubject(desktop, {
                     repo: subjectRepo,
@@ -1442,28 +1550,62 @@ export async function runCuaLane(spec, deps) {
                     ...(deps.hooks.detachedTimers ?? {})
                 });
             }
-            const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
-            desktopBrowser = browserLaunch.evidence;
-            launchedBrowserFamily = browserLaunch.family;
-            browserLaunchIdentity = browserLaunch.identity;
-            browserLaunched = true;
-            await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+            if (!desktopCliRoute) {
+                const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+                desktopBrowser = browserLaunch.evidence;
+                launchedBrowserFamily = browserLaunch.family;
+                browserLaunchIdentity = browserLaunch.identity;
+                browserLaunched = true;
+                await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+            }
+            else {
+                // A terminal window, opened the way the browser is opened on every other route: the
+                // participant arrives at a desktop with the thing they were asked to use already in front
+                // of them. They can still open another from the dock — that is the point of a desktop.
+                await openDesktopTerminal(desktop, deps.requestTimeoutMs, config.subject.product?.workdir);
+                await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+            }
+            // Start the brain BEFORE the first screenshot: the app-server handshake is ~500ms, and it
+            // is paid here, while the sandbox is still settling, rather than inside turn one.
+            if (deps.localAgent === "codex") {
+                appServer = await startAppServerSession({
+                    ...(spec.reasoningEffort === undefined ? {} : { reasoningEffort: spec.reasoningEffort }),
+                    ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+                    // The persona lives on the THREAD, so it is stated once instead of re-sent every turn.
+                    baseInstructions: spec.instructions
+                });
+                localAgentProvider = appServer.provider;
+            }
+            else if (deps.localAgent === "claude") {
+                localAgentProvider = createLocalAgentProvider({
+                    agent: "claude",
+                    ...(spec.reasoningEffort === undefined ? {} : { reasoningEffort: spec.reasoningEffort }),
+                    ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model })
+                });
+            }
             // World is ready: release the pipeline gate so the remaining lanes may start.
             provisioned = true;
             signal(true);
             try {
-                const browserGeometry = await captureDesktopBrowserGeometry({
-                    desktop,
-                    browserFamily: launchedBrowserFamily,
-                    ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
-                    laneId: spec.laneId,
-                    targetUrl,
-                    requestedScreen: spec.resolution,
-                    requestTimeoutMs: deps.requestTimeoutMs
-                });
-                initialBrowserGeometry = browserGeometry;
-                browserWindowId = browserGeometry.browserWindowId;
-                browserTargetId = browserGeometry.browserTargetId;
+                // No browser means no browser geometry, and none is invented: the CSS-viewport facts a
+                // browser reports have no counterpart in a terminal window, and an empty record shaped like
+                // a measurement would read as one. The screen geometry above is still verified.
+                if (!desktopCliRoute) {
+                    const browserGeometry = await captureDesktopBrowserGeometry({
+                        desktop,
+                        browserFamily: launchedBrowserFamily,
+                        ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
+                        laneId: spec.laneId,
+                        targetUrl,
+                        requestedScreen: spec.resolution,
+                        requestTimeoutMs: deps.requestTimeoutMs
+                    });
+                    initialBrowserGeometry = browserGeometry;
+                    browserWindowId = browserGeometry.browserWindowId;
+                    browserTargetId = browserGeometry.browserTargetId;
+                }
+                // The WHOLE desktop, not one window: a person studying a terminal app opens other windows,
+                // and a stream bound to the first one would quietly stop being evidence.
                 await startDesktopStream(desktop, browserWindowId);
                 const candidateStreamUrl = desktop.stream.getUrl({
                     authKey: desktop.stream.getAuthKey(),
@@ -1506,6 +1648,10 @@ export async function runCuaLane(spec, deps) {
                         : spec.instructions,
                 persona: spec.persona,
                 timeoutMs: deps.timeoutMs,
+                // The brain is either a keyed API client or a CLI the operator is already signed in to.
+                // Everything below this line — loop, executor, trace, affordances — is identical either
+                // way, which is what makes a local-agent run comparable to an API one.
+                ...(localAgentProvider === undefined ? {} : { provider: localAgentProvider }),
                 openai: {
                     apiKey: deps.openaiApiKey,
                     ...(config.actors[0]?.model ? { model: config.actors[0].model } : {}),
@@ -1568,6 +1714,9 @@ export async function runCuaLane(spec, deps) {
         sessionError = redactText(deps.scrubKnownValues(toErrorMessage(error)));
     }
     finally {
+        // The local brain owns a process. Close it before anything else can throw: a leaked
+        // app-server per lane would outlive the run and keep a thread open on the operator's plan.
+        appServer?.close();
         // Stop the mid-run inbox-surface loop FIRST — before the teardown evidence drain below — so the two
         // `cat`s never overlap and the final surface state is deterministic. A surface failure can never
         // block teardown (the loop body is fully try/caught and this await is on its already-caught promise).
@@ -2085,6 +2234,8 @@ async function runCuaActorLabInScope(options) {
     const env = hooks.env ?? process.env;
     const render = hooks.renderObserverFn ?? renderObserver;
     const cloneRoute = config.subject.source === "clone";
+    // A CLI studied at a desktop (#495): nothing cloned, no browser, a terminal instead.
+    const desktopCliRoute = config.subject.source === "desktop-cli";
     const localTreeRoute = config.subject.source === "local-tree";
     // Both routes provision the subject in-sandbox (clone via git, local-tree via pack+upload)
     // and then share the identical install/build/state/start/probe pipeline, so every seam that
@@ -2151,10 +2302,12 @@ async function runCuaActorLabInScope(options) {
             return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", stateReason, descriptor.id);
         }
     }
-    // Re-enforce the entry-target boundary (library API surface).
+    // Re-enforce the entry-target boundary (library API surface). A desktop-cli study has no entry
+    // target at all — the subject is a program on the machine, not an address — so the boundary is
+    // vacuous there rather than violated by an empty string.
     const allowPublicTargets = config.policies?.allowPublicTargets === true;
     const declaredTargets = [appUrl, ...(actor?.lanes ?? []).map((lane) => lane.target).filter((target) => target !== undefined)];
-    const entryTargetSafe = declaredTargets.every((target) => provisionedRoute || localAppSubject
+    const entryTargetSafe = desktopCliRoute || declaredTargets.every((target) => provisionedRoute || localAppSubject
         ? isLoopbackUrl(target)
         : allowPublicTargets
             ? isHttpUrl(target)
@@ -2248,14 +2401,48 @@ async function runCuaActorLabInScope(options) {
     const redactRepoLabel = config.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
     const publicRepo = cloneRoute && subjectRepo ? (redactRepoLabel ? "repo-01" : subjectRepo) : undefined;
     const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
-    // Key-gating is route-aware: the in-process route uses the caller's OWN model + executor.
+    // The operator's own signed-in coding agent is the brain, so there is no provider key to ask
+    // for — the entire point of the actor. E2B is still required: the persona needs a machine.
+    const localAgentRoute = actorType === "local-agent";
+    // Which local CLI, from its OWN field: `model` means the model, so that "Claude Code running
+    // Opus" is sayable. Preflight below refuses when the chosen one is missing or signed out — that
+    // news is worthless after a sandbox is paid for.
+    const preferredLocalAgent = config.actors[0]?.localAgent ?? "codex";
+    // Key-gating is route-aware: the in-process route uses the caller's OWN model + executor, and
+    // the local-agent route uses a CLI the operator has already signed in to.
     if (!dryRun && !inProcessRoute) {
         const missingKeys = [
-            ...(openaiApiKey ? [] : ["OPENAI_API_KEY"]),
+            ...(openaiApiKey || localAgentRoute ? [] : ["OPENAI_API_KEY"]),
             ...(e2bApiKey ? [] : ["E2B_API_KEY"])
         ];
         if (missingKeys.length > 0) {
-            return fail("HUMANISH_CUA_LAB_KEYS_MISSING", `Live computer-use labs need ${missingKeys.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missingKeys, env)}`, descriptor.id);
+            // The moment someone new actually hits the wall. If a signed-in coding agent is sitting
+            // right there, say so HERE rather than making them go and find an API key — that detour is
+            // where most people trying humanish stop.
+            const suggestion = missingKeys.includes("OPENAI_API_KEY")
+                ? await (async () => {
+                    const ready = (await detectLocalAgents()).filter((agent) => agent.credentialsPresent);
+                    return ready.length === 0
+                        ? ""
+                        : ` You have ${ready.map((agent) => agent.label).join(" and ")} signed in on this machine`
+                            + ` — set actors[0].type: local-agent to use ${ready.length === 1 ? "it" : "one"} instead of a key.`;
+                })()
+                : "";
+            return fail("HUMANISH_CUA_LAB_KEYS_MISSING", `Live computer-use labs need ${missingKeys.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missingKeys, env)}${suggestion}`, descriptor.id);
+        }
+        if (localAgentRoute) {
+            // Refuse HERE, before a sandbox exists. "codex is not installed" discovered after the
+            // machine is paid for is the same information delivered at the worst possible moment.
+            const available = await detectLocalAgents();
+            const chosen = available.find((agent) => agent.id === preferredLocalAgent);
+            if (chosen === undefined) {
+                return fail("HUMANISH_CUA_LAB_KEYS_MISSING", `actors[0].type: local-agent needs the ${preferredLocalAgent} CLI on PATH and signed in. `
+                    + `Install it, or set OPENAI_API_KEY and use actors[0].type: openai-computer-use instead.`, descriptor.id);
+            }
+            if (!chosen.credentialsPresent) {
+                return fail("HUMANISH_CUA_LAB_KEYS_MISSING", `${chosen.label} is installed but not signed in — run \`${chosen.bin}\` once to log in. `
+                    + "humanish never reads its credentials; it only checks that the file exists.", descriptor.id);
+            }
         }
         const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
         if (missingSubjectEnv.length > 0) {
@@ -2343,7 +2530,9 @@ async function runCuaActorLabInScope(options) {
         config,
         descriptor,
         appUrl,
+        ...(localAgentRoute ? { localAgent: preferredLocalAgent } : {}),
         cloneRoute,
+        desktopCliRoute,
         localTreeRoute,
         ...(serve === undefined ? {} : { serve }),
         ...(subjectRepo === undefined ? {} : { subjectRepo }),
@@ -4103,7 +4292,13 @@ export function buildCuaFanoutBundle(args) {
     // collapse the run to one word; this does not (docs/principles/three-roles.md).
     const terminalOutcomes = (outcomes ?? []).filter((outcome) => outcome?.session?.status !== undefined);
     const participants = terminalOutcomes.length > 0
-        ? tallyParticipantOutcomes(terminalOutcomes.map((outcome) => outcome.session.status), 
+        ? tallyParticipantOutcomes(
+        // A NO-ENGAGEMENT lane is not a participant who reached the goal. It said "done" having
+        // taken zero actions and said nothing, and `passedLanes` below already refuses to count
+        // it — but `reachedGoal` was reading the trace status directly, so one run could be both
+        // "not a passed lane" AND "1/1 reached the goal". The headline number a researcher reads
+        // first was the dishonest one. Found by a provider bug that ended a study on turn one.
+        terminalOutcomes.map((outcome) => (outcome.noEngagement === true ? "incomplete" : outcome.session.status)), 
         // A participant who reached the goal AND told you the road there was broken is the most
         // useful result a study produces; reporting only the outcome would bury it.
         terminalOutcomes.map((outcome) => outcome.reportedFriction === true))