humanish 0.104.3 → 0.106.0

package/dist/tui-contract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tui-contract.js","sourceRoot":"","sources":["../src/tui-contract.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,gGAAgG;AAChG,mGAAmG;AACnG,6DAA6D;AAC7D,EAAE;AACF,mGAAmG;AACnG,mBAAmB;AAgHnB,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,gBAAwB,OAAO,CAAC,OAAO;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,kBAAkB,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAKtC;IACC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,+BAA+B,kBAAkB,cAAc,KAAK,CAAC,WAAW,mCAAmC,CAAC;IAC7H,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,OAAO,8GAA8G,CAAC;IACxH,CAAC;IACD,OAAO,KAAK,CAAC,WAAW;QACtB,CAAC,CAAC,yEAAyE;QAC3E,CAAC,CAAC,kJAAkJ,CAAC;AACzJ,CAAC"}

package/dist/tui-launch.js

@@ -1,167 +0,0 @@
-// Starting a run from the terminal surface (#455).
-//
-// THE RUN MUST OUTLIVE THE SURFACE. A study can take minutes and costs real money, so a run
-// started from the TUI cannot be a child of the TUI's event loop: closing the surface, or losing
-// the SSH session it is running over, must not kill it. So this spawns the CLI the same way a
-// person would type it — detached, in its own process group, with its output going to a file
-// rather than to a terminal that may be about to disappear.
-//
-// The surface then learns what happened the same way any other reader does: from `status.json`.
-// It does not hold a handle to the run, parse its stdout, or track it in memory. That is what
-// makes the surface restartable — quit the TUI mid-run, reopen it, and the run is still there,
-// because the filesystem was always the source of truth rather than a process handle.
-import { spawn } from "node:child_process";
-import { constants as fsConstants } from "node:fs";
-import { open } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { resolveLabManifest } from "./labs.js";
-import { prepareManagedHumanishOutputDirectory } from "./selected-output-paths.js";
-/**
- * A lab handle is the manifest FILENAME, which is what `humanish lab run` resolves. Restricted to
- * characters a manifest name can actually contain, and — the part that matters — never allowed to
- * begin with `-`, because argv is positional: a lab called `--json` would otherwise be handed to
- * the CLI as a flag. There is no shell involved, so this is the whole injection surface.
- *
- * A leading underscore IS allowed: `_wip.yaml` is an ordinary way to name a work-in-progress
- * manifest, `humanish lab run _wip` resolves it, and refusing it here would leave the surface
- * listing a lab it will not start. A leading dot stays out — that names a hidden file, not a lab.
- */
-const SAFE_LAB_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9._:-]*$/;
-export function isSafeLabHandle(value) {
-    return SAFE_LAB_HANDLE.test(value) && value.length <= 128;
-}
-/** Where the CLI lives, relative to this compiled module. */
-function defaultCliPath() {
-    return fileURLToPath(new URL("./cli.js", import.meta.url));
-}
-/**
- * Start a run and return as soon as it is running. Never throws: a launch that cannot happen is a
- * result the surface can render, not an exception that would tear down the screen.
- */
-export async function launchRun(options) {
-    if (!isSafeLabHandle(options.lab)) {
-        return {
-            ok: false,
-            error: {
-                code: "HUMANISH_LAUNCH_INVALID_LAB",
-                message: `"${options.lab}" is not a usable lab handle. Run it by path with \`humanish lab run <path>\` instead.`
-            }
-        };
-    }
-    const cwd = path.resolve(options.cwd);
-    let selectedLab = options.lab;
-    if (options.manifestPath !== undefined) {
-        const resolved = await resolveLabManifest(cwd, options.manifestPath);
-        if (!resolved.ok)
-            return { ok: false, error: { code: "HUMANISH_LAUNCH_INVALID_LAB", message: "The selected lab path could not be read safely. Refresh the lab list." } };
-        selectedLab = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
-    }
-    const now = options.now ?? (() => new Date());
-    const spawnFn = options.spawn ?? spawn;
-    const launchedAt = now().toISOString();
-    let logPath;
-    let handle;
-    try {
-        // Contained under `.humanish/`, through the same guard every other output path uses, so a
-        // symlinked directory cannot redirect the log somewhere outside the project.
-        const logDir = await prepareManagedHumanishOutputDirectory(cwd, "launches");
-        const stamp = launchedAt.replace(/[:.]/g, "-");
-        logPath = path.join(logDir.physicalPath, `${stamp}-${options.lab}.log`);
-        // O_NOFOLLOW so a symlink planted at this path cannot redirect a run's output — which may carry
-        // provider error text — outside the project, and cannot defeat the 0600 mode by pointing at a
-        // file that already exists with looser permissions. O_CREAT|O_APPEND keeps ordinary reuse
-        // working; only a symlink is refused (ELOOP).
-        handle = await open(logPath, fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_NOFOLLOW, 0o600);
-    }
-    catch (cause) {
-        return {
-            ok: false,
-            error: {
-                code: "HUMANISH_LAUNCH_FAILED",
-                message: `Could not open a launch log: ${cause instanceof Error ? cause.message : String(cause)}`
-            }
-        };
-    }
-    // `--json` because nothing reads this stream interactively; `--no-open` because the surface owns
-    // the operator's attention and must not have a browser thrown over it.
-    const args = [
-        options.cliPath ?? defaultCliPath(),
-        "lab",
-        "run",
-        "--cwd",
-        cwd,
-        "--json",
-        "--no-open",
-        ...(options.mode === "dry-run" ? ["--dry-run"] : []),
-        // `--` ends option parsing, so the handle can only ever be read as the positional argument.
-        "--",
-        selectedLab
-    ];
-    const spawnOptions = {
-        cwd,
-        env: options.env ?? process.env,
-        // A new process group, so the SIGHUP that arrives when a terminal closes is not delivered here.
-        detached: true,
-        // stdin closed, output to the log: a detached process must never hold the terminal, and
-        // inheriting a pipe nobody reads is how a run blocks forever on a full buffer.
-        stdio: ["ignore", handle.fd, handle.fd]
-    };
-    try {
-        const child = spawnFn(process.execPath, args, spawnOptions);
-        // A spawn failure is delivered ASYNCHRONOUSLY as an 'error' event (EAGAIN, EMFILE, ENOMEM, a
-        // vanished node binary). An 'error' event with no listener is re-thrown by EventEmitter as an
-        // uncaught exception — which would tear down the whole surface, the one thing this module
-        // promises never to do. The run is already unref'd and unobserved, so recording it is all that
-        // is available; the operator learns about it from the launch log and the missing record.
-        child.on("error", () => {
-            // Deliberately empty: see above. The failure surfaces as a run that never reports in.
-        });
-        if (child.pid === undefined) {
-            await handle.close();
-            return {
-                ok: false,
-                error: { code: "HUMANISH_LAUNCH_FAILED", message: "The run process did not start." }
-            };
-        }
-        // Release the surface's hold: the parent can now exit whenever it likes and the run continues,
-        // reparented to init.
-        child.unref();
-        // The child owns the descriptor now.
-        await handle.close();
-        return {
-            ok: true,
-            run: { pid: child.pid, launchedAt, logPath, command: [process.execPath, ...args] }
-        };
-    }
-    catch (cause) {
-        await handle.close().catch(() => undefined);
-        return {
-            ok: false,
-            error: {
-                code: "HUMANISH_LAUNCH_FAILED",
-                message: cause instanceof Error ? cause.message : String(cause)
-            }
-        };
-    }
-}
-/** Read the tail of a launch log — the only account of a run that died before writing evidence. */
-export async function readLaunchLogTail(logPath, maxBytes = 4_000) {
-    try {
-        const handle = await open(logPath, "r");
-        try {
-            const { size } = await handle.stat();
-            const start = Math.max(0, size - maxBytes);
-            const buffer = Buffer.alloc(Math.min(size, maxBytes));
-            await handle.read(buffer, 0, buffer.length, start);
-            return buffer.toString("utf8").trim();
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    catch {
-        return "";
-    }
-}
-//# sourceMappingURL=tui-launch.js.map

package/dist/tui-launch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tui-launch.js","sourceRoot":"","sources":["../src/tui-launch.ts"],"names":[],"mappings":"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"}

package/dist/tui-project.d.ts

@@ -1,9 +0,0 @@
-export declare const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";
-export interface TuiProjectState {
-    schema: typeof TUI_PROJECT_SCHEMA;
-    /** A committed `humanish/` source directory: this project has been `init`-ed. */
-    initialized: boolean;
-    /** A `.humanish/` runtime directory: something has been run here, even if source is absent. */
-    hasRuntime: boolean;
-}
-export declare function readProjectState(cwdInput: string): TuiProjectState;

package/dist/tui-project.js

@@ -1,18 +0,0 @@
-// Is this directory a humanish project at all? (#455)
-//
-// The surface has two very different empty states and used to render one screen for both. A
-// project with no labs yet needs "write one"; a directory that is not a project — someone's home
-// directory, because `npx humanish tui` is easy to type anywhere — needs to know that first. The
-// second is what Daniel hit, and being told "no labs here yet" in `~` reads as a broken tool.
-import { existsSync } from "node:fs";
-import path from "node:path";
-export const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";
-export function readProjectState(cwdInput) {
-    const cwd = path.resolve(cwdInput);
-    return {
-        schema: TUI_PROJECT_SCHEMA,
-        initialized: existsSync(path.join(cwd, "humanish")),
-        hasRuntime: existsSync(path.join(cwd, ".humanish"))
-    };
-}
-//# sourceMappingURL=tui-project.js.map

package/dist/tui-project.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tui-project.js","sourceRoot":"","sources":["../src/tui-project.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,4FAA4F;AAC5F,iGAAiG;AACjG,iGAAiG;AACjG,8FAA8F;AAE9F,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAU5D,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,OAAO;QACL,MAAM,EAAE,kBAAkB;QAC1B,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACnD,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;KACpD,CAAC;AACJ,CAAC"}

package/docs/architecture/examples/state-driven-local-app/README.md

@@ -1,80 +0,0 @@
-# Run a local app through its state contract
-
-This complete library example starts a synthetic loopback HTTP app, reads its
-state with a `CuaExecutor`, sends a greeting through its action endpoint, and
-verifies the resulting Humanish run. It uses a deterministic `CuaProvider` with
-no model calls, API keys, browser, screenshots or E2B resources. It demonstrates
-the integration; it does not test persona behavior or the quality of an app's UI.
-
-## Run from an npm installation
-
-Use Node.js 20.3 or later (`AbortSignal.any`), in a new directory:
-
-```bash
-npm init -y
-npm install humanish
-node node_modules/humanish/docs/architecture/examples/state-driven-local-app/runner.mjs
-```
-
-The package includes both [runner.mjs](runner.mjs) and [app.mjs](app.mjs).
-No checkout, TypeScript loader or initialization command is needed. Each
-invocation starts a fresh app and writes a new run under `.humanish/runs/` in
-your current directory. Run the last command again for an independent repeat.
-Add `.humanish/` to your project's `.gitignore` before adapting this example to
-real app data; running the library directly does not create that ignore rule.
-
-Expected output includes `goal_satisfied`, `sandboxCreated: false`, zero
-screenshots, a successful `verification`, and a synthetic app receipt with
-`greeted: true` and `messages: 1`. The final cleanup line shows
-`serverClosed: true`; `finally` closes the server even when the run or verification
-fails. The evidence remains on disk.
-
-Review the bundle and its sharing grade:
-
-```bash
-npx humanish verify --run latest --json
-npx humanish review --run latest --json
-```
-
-`appState` drives the loop in memory and is not persisted in the actor trace.
-This example separately prints only its own synthetic counters. A successful
-verification describes the evidence bundle, not persona efficacy or human
-task completion. The reported cost basis comes from executing only local code
-and loopback requests; absent model usage is not treated as a billing receipt.
-
-## Adapt the two ports
-
-In `runner.mjs`, replace `createAppContractExecutor` with your trusted bridge to
-your app's `getState()` and actions. Here those calls use `GET /state` and
-`POST /chat`; a browser bridge could call `window.app` through `page.evaluate`.
-Map supported actions explicitly and reject unsupported ones. Forward the
-optional execution signal and check it before dispatching an input.
-
-Replace the deterministic provider if you want a model to choose actions from
-`request.observation.appState`. Keep `requiresFrame: false` for a state-only
-provider. Your replacement owns its model credentials and costs. The
-`openai-computer-use` actor id selects the registered CUA route; the injected
-`buildProvider` chooses the actual provider, so this example never invokes OpenAI.
-
-The runner shows both required discriminant checks: `parseLabConfig` receives
-an object containing `schema: LAB_CONFIG_SCHEMA` and is narrowed on `.ok`;
-`runLab` is narrowed on `backend === "cua"` before inspecting its result.
-Supplying both `buildExecutor` and `buildProvider` selects the library-assisted
-route. It is not a config-only CLI actor or an out-of-tree actor registration API.
-
-Both JavaScript files carry JSDoc types against the public `humanish` exports.
-To check an installed copy against its packaged declarations:
-
-```bash
-npm install --save-dev typescript @types/node@20
-npx tsc --allowJs --checkJs --noEmit --strict --skipLibCheck --types node --target ES2022 --module NodeNext --moduleResolution NodeNext node_modules/humanish/docs/architecture/examples/state-driven-local-app/*.mjs
-```
-
-See the [state-driven executor guide](../../state-driven-executor.md) for progress
-projection limits, runtime-only state, unpinned local-app provenance, and the
-fail-closed guards on this route.
-
-The example explicitly sets `review: { analysis: false }` to keep post-run
-analysis free of provider requests too. Supported live recordings otherwise
-use the separate default analysis budget; a deterministic participant provider
-does not replace the analysis provider.

package/docs/architecture/examples/state-driven-local-app/app.mjs

@@ -1,48 +0,0 @@
-// @ts-check
-import { once } from "node:events";
-import { createServer } from "node:http";
-
-/** A synthetic app with a real loopback HTTP state/action contract. */
-export async function startLocalApp() {
-  let greeted = false;
-  let messages = 0;
-  let stateReads = 0;
-  const server = createServer(async (request, response) => {
-    if (request.method === "GET" && request.url === "/state") {
-      stateReads += 1;
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify({ greeted, messages }));
-    } else if (request.method === "POST" && request.url === "/chat") {
-      // The demo accepts only a short synthetic message; it stores no raw text.
-      let text = "";
-      for await (const chunk of request) {
-        text += chunk.toString();
-        if (text.length > 1024) {
-          response.writeHead(413).end();
-          return;
-        }
-      }
-      messages += 1;
-      if (text.toLowerCase().includes("hello")) greeted = true;
-      response.writeHead(204).end();
-    } else {
-      response.writeHead(404).end();
-    }
-  });
-  server.listen(0, "127.0.0.1");
-  await once(server, "listening");
-  const address = server.address();
-  if (!address || typeof address === "string") throw new Error("No loopback port");
-
-  return {
-    appUrl: `http://127.0.0.1:${address.port}/`,
-    // These counters make real HTTP reads and state-changing writes inspectable.
-    getReceipt: () => ({ greeted, messages, stateReads, serverClosed: !server.listening }),
-    async close() {
-      await new Promise((resolve, reject) => {
-        server.close((error) => error ? reject(error) : resolve(undefined));
-        server.closeAllConnections();
-      });
-    }
-  };
-}

package/docs/architecture/examples/state-driven-local-app/runner.mjs

@@ -1,105 +0,0 @@
-// @ts-check
-import { LAB_CONFIG_SCHEMA, parseLabConfig, runLab, stableProgressKey, verifyRun } from "humanish";
-import { startLocalApp } from "./app.mjs";
-
-/** @param {string} appUrl @returns {import("humanish").CuaExecutor} */
-function createAppContractExecutor(appUrl) {
-  return {
-    async observe() {
-      const response = await fetch(new URL("state", appUrl), { signal: AbortSignal.timeout(5000) });
-      if (!response.ok) throw new Error(`State read failed: HTTP ${response.status}`);
-      const state = await response.json();
-      if (typeof state?.greeted !== "boolean" || !Number.isInteger(state?.messages)) {
-        throw new Error("Unexpected app state");
-      }
-      const appState = { greeted: state.greeted, messages: state.messages };
-      return { stateSignature: stableProgressKey(appState), appState };
-    },
-    async execute(action, signal) {
-      signal?.throwIfAborted();
-      if (action.kind !== "type") throw new Error(`Unsupported app action: ${action.kind}`);
-      const response = await fetch(new URL("chat", appUrl), {
-        method: "POST",
-        body: action.text,
-        signal: AbortSignal.any([AbortSignal.timeout(5000), ...(signal ? [signal] : [])])
-      });
-      if (!response.ok) throw new Error(`Chat write failed: HTTP ${response.status}`);
-    }
-  };
-}
-
-// A deterministic rule, not an AI participant: no model SDK, requests or credentials.
-/** @type {import("humanish").CuaProvider} */
-const provider = {
-  id: "local-app-deterministic-example",
-  version: "1.0.0",
-  requiresFrame: false,
-  capabilities: {
-    headless: true,
-    structuredTrace: true,
-    lanes: ["computer-use"],
-    producesScreenshots: false,
-    byoModel: true,
-    preGrantableApprovals: false,
-    inProcessTools: false,
-    license: "open"
-  },
-  async nextTurn(request, signal) {
-    signal.throwIfAborted();
-    const greeted = request.observation.appState?.greeted;
-    if (typeof greeted !== "boolean") throw new Error("Missing greeted observation");
-    return {
-      actions: greeted ? [] : [{ kind: "type", text: "hello there" }],
-      pendingSafetyChecks: [],
-      done: greeted,
-      message: greeted ? "The app accepted the greeting." : "Sending a greeting."
-    };
-  }
-};
-
-const app = await startLocalApp();
-try {
-  // parseLabConfig accepts a decoded OBJECT, not a YAML string.
-  const parsed = parseLabConfig({
-    schema: LAB_CONFIG_SCHEMA,
-    id: "state-driven-local-app-example",
-    title: "Deterministic local-app integration example",
-    subject: { source: "local-app", appUrl: app.appUrl },
-    // This registry id selects the CUA loop. buildProvider supplies the actual provider.
-    actors: [{ type: "openai-computer-use", persona: "pixel-pat", mission: "Greet the app." }],
-    scenario: { mode: "live" },
-    review: { analysis: false }, // Keep this deterministic example free of provider requests.
-    execution: { timeoutMs: 15_000 }
-  });
-  if (!parsed.ok) throw new Error(parsed.error.message);
-  const outcome = await runLab(parsed.config, {
-    cwd: process.cwd(),
-    dryRun: false,
-    cuaHooks: {
-      buildExecutor: async ({ appUrl }) => createAppContractExecutor(appUrl),
-      buildProvider: async () => provider
-    }
-  });
-  if (outcome.backend !== "cua") throw new Error(`Unexpected backend: ${outcome.backend}`);
-  const { result } = outcome;
-  const verified = await verifyRun(process.cwd(), result.runId);
-  console.log(JSON.stringify({
-    runId: result.runId,
-    ok: result.ok,
-    completionReason: result.session?.completionReason,
-    provider: provider.id,
-    sandboxCreated: result.sandbox !== undefined,
-    screenshots: result.session?.screenshots,
-    verification: verified,
-    app: app.getReceipt(),
-    // A mechanism statement, not an inference from missing provider usage/rates.
-    costBasis: "No model calls or hosted resources; only this process and loopback HTTP."
-  }, null, 2));
-  if (!result.ok || !verified.ok || result.session?.completionReason !== "goal_satisfied"
-    || result.sandbox !== undefined || !app.getReceipt().greeted) {
-    throw new Error(result.error?.message ?? "Local-app example did not complete and verify");
-  }
-} finally {
-  await app.close();
-  console.log(JSON.stringify({ cleanup: app.getReceipt() }));
-}

package/docs/architecture/local-codex-tui-actor.md

@@ -1,213 +0,0 @@
-# Local Codex TUI Actor Contract
-
-Date: 2026-06-02
-
-Status: incremental implementation on issue #28. The repo supports one explicit
-local Codex TUI actor with sanitized lifecycle evidence and fail-fast Codex
-workspace-trust preflight. It also supports explicit noninteractive
-`codex-exec` actor fanout for autonomous local dogfood proof. Requested exec
-lanes are not capped by total run count; they run through bounded concurrency
-controlled by `HUMANISH_LOCAL_CODEX_EXEC_MAX_CONCURRENCY` (default 4). TUI
-autonomous completion and TUI live Observer follow remain follow-up work.
-
-## Goal
-
-Let `humanish run` dogfood `humanish` with a real local Codex TUI actor while
-preserving the public-safe harness contract:
-
-```text
-spawn actor
--> submit bounded prompt
--> stream sanitized lifecycle events
--> write run bundle
--> render Observer while active
--> verify final bundle
-```
-
-This actor proves the local harness substrate. It must not claim target product
-behavior beyond the commands and artifacts it actually observes.
-
-## Explicit Opt-In
-
-The first live actor must require an explicit flag or env var. Non-dry-run
-without opt-in should continue to fail closed.
-
-Suggested gate:
-
-```bash
-humanish run --actor codex-tui --sims 1 --timeout-ms 240000
-```
-
-or, for noninteractive local autonomy:
-
-```bash
-humanish run --actor codex-exec --sims 4 --timeout-ms 240000
-```
-
-or:
-
-```bash
-HUMANISH_ENABLE_LOCAL_CODEX_TUI=1 humanish run --sims 1
-```
-
-or:
-
-```bash
-HUMANISH_ENABLE_LOCAL_CODEX_EXEC=1 humanish run --sims 1
-```
-
-Provider spend, E2B, GitHub mutation, and external network calls remain off
-unless separately and explicitly requested. When real Codex exec auth is used,
-`HUMANISH_LOCAL_CODEX_EXEC_MAX_CONCURRENCY` is the cost/resource rail; there is
-no arbitrary total lane cap.
-
-For deterministic tests or local substrate debugging, `HUMANISH_CODEX_ACTOR_COMMAND`
-can point at a safe fixture command. Real Codex TUI launch uses a Linux
-`script` PTY wrapper when available because the Codex TUI requires a terminal.
-Humanish answers the minimal terminal cursor/color queries needed for headless
-TUI startup and normalizes terminal control sequences before classifying the
-final actor transcript. Once a final
-`HUMANISH_ACTOR_VERDICT=* HUMANISH_ACTOR_NONCE=<run-nonce>` marker appears,
-Humanish terminates the local actor process and records the marker verdict rather
-than waiting for the TUI session to stay open until timeout. The nonce prevents
-the classifier from accepting an echoed prompt or inspected docs as a final
-actor verdict.
-Real Codex exec launch uses `codex exec --skip-git-repo-check --ignore-rules
---ephemeral --sandbox read-only --json` so it can complete without an
-interactive TUI trust prompt while still running with read-only local command
-permissions.
-
-## Lifecycle Events
-
-The actor should append deterministic events to `events.ndjson`:
-
-| Event | Required fields |
-| --- | --- |
-| `actor.spawned` | `simId`, `streamId`, command name, cwd, startedAt |
-| `actor.prompt.submitted` | prompt digest, prompt class, no raw prompt if unsafe |
-| `actor.running` | running snapshot available in `run.json` and `observer/observer-data.json` |
-| `actor.observation` | sanitized transcript tail, byte count, redaction status |
-| `actor.artifact` | relative artifact path, kind, digest |
-| `actor.verdict` | `passed`, `failed`, `blocked`, or `timed_out`; reason |
-| `actor.exited` | exit code, signal, durationMs |
-| `actor.timeout` | timeoutMs, last safe observation |
-| `actor.cancelled` | signal and operator reason |
-
-The Observer should be able to render a live terminal stream from those events
-while the actor is active, then render the final transcript and artifacts after
-exit.
-
-For local Codex actors, the run writes a provisional running bundle and
-`observer/observer-data.json` before awaiting actor completion, then refreshes
-those files with final verdicts and artifact links. This lets an existing
-served Observer poll the same local evidence path during the run.
-
-## Runtime State
-
-All generated state stays under ignored `.humanish/`:
-
-```text
-.humanish/runs/<run-id>/
-  run.json
-  review.json
-  review.md
-  events.ndjson
-  actor.json
-  actors/sim-02-codex-exec.json
-  transcripts/codex-tui-sanitized.txt
-  transcripts/codex-exec-sanitized.jsonl
-  transcripts/sim-02-codex-exec-sanitized.jsonl
-  observer/
-    index.html
-    observer-data.json
-```
-
-No raw terminal output is public by default. The transcript artifact must be
-sanitized before it is linked from the bundle.
-
-For TUI runs, `.humanish/runs/latest.json` is published only after a valid
-running bundle, review, and Observer data exist, then refreshed after final
-artifacts exist. This keeps `humanish verify --run latest` from pointing at an
-incomplete TUI run while still allowing live Observer follow on the active run.
-
-## Redaction Rules
-
-Before any transcript tail or event payload is written:
-
-- redact OpenAI, E2B, GitHub, npm, and generic private-key patterns;
-- redact absolute local home/workspace paths when they are not necessary for
-  proof;
-- block the run if redaction cannot prove `status: passed`;
-- record env var names only, never values.
-
-## Initial Prompt Class
-
-The first actor prompt should be bounded to public-safe dogfood work:
-
-- inspect `humanish/` dogfood config;
-- run at most two read-only inspection commands;
-- avoid commands that write runtime artifacts or temp config, including
-  `pnpm humanish`, `humanish watch`, `humanish feedback`, `humanish init`, tests,
-  builds, installs, and commands that write `.humanish/`;
-- inspect existing artifacts and explain the strongest write-required proof as a
-  follow-up when the TUI actor is running in a read-only sandbox;
-- use `passed` when read-only inspection confirms the committed harness and
-  existing evidence contract; write-required follow-ups alone are not blockers;
-- do not commit, push, publish, file issues, or print secrets;
-- summarize blockers using public-safe evidence paths;
-- finish with exactly one final
-  `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<run-nonce>` line, where
-  `<status>` is `passed`, `blocked`, or `failed`.
-
-The raw prompt can live in source only if it contains no private context and no
-credential values.
-
-## Stop Conditions
-
-The actor must stop and mark the lane `blocked` or `failed` if:
-
-- Codex CLI is not installed or not authenticated;
-- a command requests approval in a non-interactive run;
-- redaction fails;
-- output contains a likely secret after redaction;
-- the actor touches files outside allowed runtime paths without explicit scope;
-- timeout is reached.
-
-## Known First-Slice Boundary
-
-The first real local TUI proof in this environment reached Codex's workspace
-trust prompt. The current TUI implementation detects missing exact project-root
-trust before spawn and writes a `blocked` run bundle instead of waiting for the
-TUI timeout. A follow-up PTY probe showed that the Codex TUI still prompts when
-only a trusted ancestor is configured, so Humanish only treats the exact trust
-root as sufficient for autonomous launch.
-
-With exact trust present, Humanish answers Codex's terminal startup query, strips
-TUI control sequences from the captured transcript, and terminates/classifies on
-an explicit nonce-bearing `HUMANISH_ACTOR_VERDICT=*` marker when present. If
-Codex exits cleanly without a marker, the run is still considered process-passed
-but the transcript remains available for review.
-
-The noninteractive `codex-exec` mode is a separate actor contract for autonomous
-local completion. It can run requested bounded read-only lanes with distinct
-focuses across install readability, public safety, Observer evidence, and
-verification/release gates. It does not replace the TUI contract because it does
-not prove PTY rendering, keyboard focus, or visible live TUI observation.
-
-The next implementation slice should decide whether TUI-specific fanout is
-needed beyond the current 1x TUI proof plus bounded-concurrency noninteractive
-`codex-exec` fanout split.
-
-## Acceptance For First Slice
-
-The implementation slice for this spec should prove:
-
-```bash
-pnpm humanish:doctor
-pnpm humanish -- run --actor codex-tui --sims 1 --timeout-ms 240000 --json
-pnpm humanish -- run --actor codex-exec --sims 1 --timeout-ms 240000 --json
-pnpm humanish -- run --actor codex-exec --sims 4 --timeout-ms 240000 --json
-pnpm humanish -- watch --run latest --detach --json --no-open
-pnpm humanish -- verify --run latest --json
-pnpm check
-```