humanish 0.110.1 → 0.110.3

package/dist/run/sandbox-receipts.js

@@ -1,6 +1,8 @@
-// Every created sandbox id is journaled to the run dir the moment create returns, before any work
-// happens in it. The participant loop lives in the caller's local process, so a sleeping laptop, crash or
-// kill loses every in-memory id; this append-only file keeps them for `humanish reclaim`.
+// Every created sandbox id is journaled to the run dir as soon as it reaches this process: when the
+// desktop startup guard reports it, or when create returns, before any work happens in it. The
+// participant loop lives in the caller's local process, so a sleeping laptop, crash or kill loses
+// every in-memory id; this append-only file keeps them for `humanish reclaim`, and tells verify and
+// the sweep which ids to look for.
 import { appendFile } from "node:fs/promises";
 import { prepareContainedOutputFile } from "./contained-output.js";
 export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
@@ -22,10 +24,11 @@ export function appendedSandboxIds(root) {
     return [...(appended.get(rootKey(root)) ?? [])];
 }
 /**
- * Append one receipt. Best-effort by design: the receipt exists to protect the run, so a failed
- * receipt write must never fail the participant. The only cost of a miss is that `reclaim` cannot see
- * this id and the TTL backstop covers it instead. Containment is the same prepare step every
- * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
+ * Append one receipt; false when the write failed. Best-effort by design: the receipt exists to
+ * protect the run, so a failed receipt write must never fail the participant. The only cost of a
+ * miss is that `reclaim` cannot see this id and the TTL backstop covers it instead. Containment is
+ * the same prepare step every artifact write uses; append (not atomic-replace) keeps racing
+ * participants' receipts intact.
  */
 export async function appendSandboxReceipt(root, receipt) {
     const key = rootKey(root);
@@ -40,9 +43,11 @@ export async function appendSandboxReceipt(root, receipt) {
     try {
         const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
         await appendFile(filePath, `${JSON.stringify(receipt)}\n`, "utf8");
+        return true;
     }
     catch {
         // Swallowed on purpose; see the contract above.
+        return false;
     }
 }
 /** Append one owner line; false when the write failed, which never fails the create. */

package/dist/run/status.d.ts

@@ -80,6 +80,8 @@ export interface RunStatusHandle {
      *  `running` or `finished` over it. When the run had finished it writes nothing, waits for the
      *  writes already queued and resolves false. */
     interrupt(signal: RunInterruptSignal): Promise<boolean>;
+    /** True from the moment `interrupt` accepts a signal, before its write lands. */
+    readonly interrupted: boolean;
 }
 export interface BeginRunStatusOptions {
     runId: string;

package/dist/run/status.js

@@ -69,6 +69,7 @@ export function beginRunStatus(runPaths, options) {
         updatedAt: startedAt,
     };
     let finished = false;
+    let interrupted = false;
     let finishedRecord;
     let writing = Promise.resolve();
     const write = (record) => {
@@ -119,11 +120,15 @@ export function beginRunStatus(runPaths, options) {
                 return false;
             }
             finished = true;
+            interrupted = true;
             clearInterval(timer);
             const completedAt = iso();
             await write({ ...base, state: "interrupted", updatedAt: completedAt, completedAt, signal });
             return true;
         },
+        get interrupted() {
+            return interrupted;
+        },
     };
     return handle;
 }

package/dist/study/agents-section.d.ts

@@ -0,0 +1,21 @@
+export type AgentsSectionReplacement = 
+/** The file has no humanish section. */
+{
+    kind: "absent";
+}
+/** A start marker with no end marker, in text no release wrote: possibly hand-edited. */
+ | {
+    kind: "unknown";
+}
+/** The file with humanish's section replaced; equal to the input when it was already current. */
+ | {
+    kind: "replaced";
+    contents: string;
+};
+/**
+ * `existing` with humanish's section replaced by `section` (as `agentsSection()` returns it, with
+ * its leading blank line). The replaced range runs from the start of the heading line that holds
+ * the start marker to the end of the end marker's line, or, without an end marker, through the
+ * text of the release that wrote it.
+ */
+export declare function replaceAgentsSection(existing: string, section: string): AgentsSectionReplacement;

package/dist/study/agents-section.js

@@ -0,0 +1,86 @@
+// Finds humanish's own section in a project's `AGENTS.md` so init can replace it on a rerun and
+// leave every other byte alone. Releases up to 0.110.1 wrote the section with a start marker and
+// no end marker, so for those the section's extent is known only by matching a text init wrote.
+import { createHash } from "node:crypto";
+import { AGENTS_SECTION_END_MARKER, AGENTS_SECTION_MARKER } from "../cli/first-run-path.js";
+/**
+ * Each section text a release wrote before the end marker existed, from its `## humanish` heading
+ * to its final newline: the UTF-16 length and the sha256 of its UTF-8 bytes. Comparing digests
+ * keeps the retired command and key names those versions taught out of the source.
+ */
+const SECTIONS_WITHOUT_END_MARKER = [
+    {
+        releases: "0.59.0 to 0.80.0",
+        length: 1171,
+        sha256: "3739c98204cc5b2df603238398bffc5c4a491782a3ab72475b0ad9d967698a11",
+    },
+    {
+        releases: "0.81.0 to 0.93.1",
+        length: 1191,
+        sha256: "169d646f329f35af1b5e51eb02cd0454a717cf29a447a230f3aa2d5a7354729c",
+    },
+    {
+        releases: "0.94.0 to 0.99.1",
+        length: 1214,
+        sha256: "68f987769893f041ab78e0b1cb4cd8db14a438511f15b58f9eaa412ea002b51f",
+    },
+    {
+        releases: "0.100.0 to 0.105.0",
+        length: 1548,
+        sha256: "f60c37003d21b1d8280d002f203130c60bc3c23454b018b3207407faa01cb76f",
+    },
+    {
+        releases: "0.106.0 to 0.107.0",
+        length: 1686,
+        sha256: "c2cd9d831e17021ad4477f300dbea13df1613bec8f30ebbabfabcd749b73f7f7",
+    },
+    {
+        releases: "0.108.0",
+        length: 1679,
+        sha256: "6352ec71d7c5073b2bf4993293753944eaf7cfd21169a311f42d9f52bdacfead",
+    },
+    {
+        releases: "0.109.0 to 0.110.0",
+        length: 1681,
+        sha256: "2559a93463cf50225aadf6753e84dd6e32b25aa3afdf8066e90d19c5d88d0ef0",
+    },
+    {
+        releases: "0.110.1",
+        length: 2014,
+        sha256: "9fb4cb94400c7447ab0fece861339e50de8e9be99797cf0763d7502be0fe668d",
+    },
+];
+/**
+ * `existing` with humanish's section replaced by `section` (as `agentsSection()` returns it, with
+ * its leading blank line). The replaced range runs from the start of the heading line that holds
+ * the start marker to the end of the end marker's line, or, without an end marker, through the
+ * text of the release that wrote it.
+ */
+export function replaceAgentsSection(existing, section) {
+    const marker = existing.indexOf(AGENTS_SECTION_MARKER);
+    if (marker < 0)
+        return { kind: "absent" };
+    const start = existing.lastIndexOf("\n", marker) + 1;
+    const replacement = section.replace(/^\n/, "");
+    const endMarker = existing.indexOf(AGENTS_SECTION_END_MARKER, marker);
+    if (endMarker >= 0) {
+        const lineEnd = existing.indexOf("\n", endMarker);
+        const end = lineEnd < 0 ? existing.length : lineEnd + 1;
+        return {
+            kind: "replaced",
+            contents: existing.slice(0, start) + replacement + existing.slice(end),
+        };
+    }
+    for (const known of SECTIONS_WITHOUT_END_MARKER) {
+        const candidate = existing.slice(start, start + known.length);
+        if (candidate.length !== known.length)
+            continue;
+        if (createHash("sha256").update(candidate).digest("hex") !== known.sha256)
+            continue;
+        return {
+            kind: "replaced",
+            contents: existing.slice(0, start) + replacement + existing.slice(start + known.length),
+        };
+    }
+    return { kind: "unknown" };
+}

package/dist/study/composition-rules.js

@@ -51,7 +51,7 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorStudy with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
+// planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";

package/dist/study/doctor.js

@@ -2,12 +2,13 @@ import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
-import { localAgentVersionRefusal } from "../actors/local-agent/cli.js";
+import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
+import { cli } from "../cli/invocation.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -212,7 +213,7 @@ async function localBrowserChecks(config, args) {
             ok: healthy,
             message: healthy
                 ? "Recipient inbox routes are ready. Point your app's email sends at this catch; delivery remains untested. No mailbox-provider credentials are needed, and this does not receive arbitrary internet mail."
-                : "Captured inbox is unavailable or outdated. Start or upgrade and restart humanish comms catch, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.",
+                : `Captured inbox is unavailable or outdated. Start or upgrade and restart ${cli("comms catch")}, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.`,
         });
     }
     return checks;
@@ -229,7 +230,7 @@ async function realEmailCheck(connection, keys, args) {
             ? "The selected email connection is missing or invalid. Open Connections in the TUI."
             : !args.keyPresent(name)
                 ? `Missing ${name} for the selected email connection. Provide it through process env or --dotenv. Authentication has not been checked.`
-                : "Fresh hosted inbox per participant. Local presence only; run humanish comms check --online to authenticate. Provider permissions/capacity and delivery remain untested.",
+                : `Fresh hosted inbox per participant. Local presence only; run ${cli("comms check --online")} to authenticate. Provider permissions/capacity and delivery remain untested.`,
     };
 }
 /** How the participant authenticates: the terminal model key, or a local agent's login. */
@@ -259,7 +260,7 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
     return [
         {
             name: "local participant authentication",
-            ok: agent?.authStatus === "authenticated" && outdated === undefined,
+            ok: agent !== undefined && localAgentReady(agent),
             message: agent?.authStatus === "authenticated"
                 ? (outdated ??
                     `${agent.label}${agent.version === undefined ? "" : ` ${agent.version}`} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`)

package/dist/study/init-templates.d.ts

@@ -24,5 +24,5 @@ export declare const humanishScripts: Record<string, string>;
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId): StarterFile[];
+export declare function starterFilesFor(actor: StarterActor, localBrowser?: LocalBrowserStarter, localAgent?: LocalAgentId, command?: string): StarterFile[];
 export {};

package/dist/study/init-templates.js

@@ -34,6 +34,44 @@ defaults:
 `,
     };
 }
+/**
+ * The `humanish/README.md` init writes. Its commands start with `command`, the invocation init
+ * chose for this install (src/cli/invocation.ts), as in the section init writes to `AGENTS.md`.
+ */
+function readmeFile(command) {
+    return {
+        path: "humanish/README.md",
+        plane: "source",
+        contents: `# humanish
+
+This directory holds the committed definitions of this app's humanish studies: study files,
+personas and scenarios.
+
+Keep this directory public-safe:
+
+- synthetic personas only;
+- synthetic fixtures only;
+- env var names only, never values;
+- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
+
+Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
+
+Studies:
+
+- committed reusable studies live in humanish/studies/*.yaml;
+- private or machine-local studies live in ignored .humanish/studies/*.yaml or
+  .humanish/local/studies/*.yaml;
+- run a study with \`${command} run <study>\`, or \`${command} watch <study>\` to stay attached;
+- files under humanish/labs/ move there with \`${command} migrate\`.
+
+Format standard:
+
+- human-authored humanish source uses .yaml;
+- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
+- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
+`,
+    };
+}
 /**
  * The flagship live study. A ChatGPT-account Codex participant has no API-dollar price, so preflight
  * refuses a dollar cap on it (HUMANISH_COMPUTER_USE_UNPRICED_CAP); that variant is bounded by the
@@ -113,38 +151,7 @@ defaults:
     };
 }
 export const starterFiles = [
-    {
-        path: "humanish/README.md",
-        plane: "source",
-        contents: `# humanish
-
-This directory holds the committed definitions of this app's humanish studies: study files,
-personas and scenarios.
-
-Keep this directory public-safe:
-
-- synthetic personas only;
-- synthetic fixtures only;
-- env var names only, never values;
-- no PII, PHI, secrets, raw private transcripts, private screenshots, customer data, or patient data.
-
-Generated run bundles, screenshots, traces, logs, and local overrides belong in ignored \`.humanish/\`.
-
-Studies:
-
-- committed reusable studies live in humanish/studies/*.yaml;
-- private or machine-local studies live in ignored .humanish/studies/*.yaml or
-  .humanish/local/studies/*.yaml;
-- run a study with \`humanish run <study>\`, or \`humanish watch <study>\` to stay attached;
-- files under humanish/labs/ move there with \`humanish migrate\`.
-
-Format standard:
-
-- human-authored humanish source uses .yaml;
-- generated artifacts, synthetic fixtures, and event streams use .json or .ndjson;
-- .yml is reserved for outside ecosystem files such as GitHub Actions, not humanish source.
-`,
-    },
+    readmeFile("humanish"),
     {
         path: "humanish/personas/synthetic-new-user.yaml",
         plane: "source",
@@ -194,24 +201,6 @@ steps:
     expectation: The user sees a clear next state.
   - name: Capture review notes
     expectation: Notes are public-safe and evidence-backed.
-`,
-    },
-    {
-        path: "humanish/scenarios/onboarding-regression.yaml",
-        plane: "source",
-        contents: `schema: humanish.scenario.v1
-id: onboarding-regression
-title: Onboarding regression
-persona: skeptical-power-user
-goal: Exercise onboarding friction using synthetic inputs and explicit recovery checks.
-mode: dry-run
-steps:
-  - name: Start onboarding
-    expectation: Required information is clear.
-  - name: Use synthetic fixture data
-    expectation: No real user data is entered.
-  - name: Check recovery path
-    expectation: The user can back out or retry safely.
 `,
     },
     {
@@ -308,83 +297,6 @@ execution:
 #   allowPublicTargets: true      # required to drive a non-loopback app-url (a deployment you own)
 defaults:
   open: true
-`,
-    },
-    {
-        path: "humanish/studies/lobby-trivia-3player.yaml",
-        plane: "source",
-        contents: `schema: humanish.study.v3
-id: lobby-trivia-3player
-title: "Shared world on a public app: three mobile participants in one lobby"
-description: >-
-  A worked example of the external-public shared-world route: three participants on mobile layouts
-  play the same multiplayer lobby on a public deployment at the same time. The public site is the
-  shared plane, so there is no clone, subject sandbox or seed. The host participant creates the
-  lobby, humanish reads the session code from the host's page URL, and the other participants get
-  it in their missions and join through the app's own join flow. Starts as a dry run, which writes
-  one evidence bundle at no cost. A live run needs OPENAI_API_KEY, E2B_API_KEY and mode: live. Point appUrl and publicTarget at a public deployment you own or operate. Mobile layout:
-  Chrome's physical window is at least 500px wide and has no touch emulation, desktop pixel ratio
-  and a desktop user agent. Set execution.desktop.fidelity.mobileEmulation to true to request the
-  preset's CSS viewport, touch, pixel ratio and mobile user agent on Chrome or Chromium; the bundle
-  records the measured geometry and emulation fidelity. A run on a public site proves less than a
-  provisioned one: its provenance is external-public, it carries no synthetic-data attestation and
-  no authoritative shared-state proof, and concurrency rests on overlapping sessions and every
-  participant reaching the same lobby.
-route: shared-world
-mode: dry-run # a live run opens three mobile-layout desktops against the public app
-subject:
-  source: app-url # the public deployment is the shared plane: no clone and no getHost
-  appUrl: https://your-public-app.example/ # a deployment you own or operate
-  publicTarget: # required: your attestation that you own or operate this deployment
-    owner: your-org/your-app
-    authorized: true
-policies:
-  allowPublicTargets: true # required: the shared plane is a public, non-loopback deployment
-actor:
-  type: openai-computer-use
-  mission: You are one of several users on the same shared session at once. Play your role, then stop.
-participants: # at least two participants, exactly one with host: true
-  - id: host
-    host: true # this participant creates the shared session
-    device: mobile # 414x896 preset; physical window width floors to 500 (see emulation above)
-    instruction: Create a shared lobby, wait for the others to join, then start and play.
-  - id: player-2
-    device: mobile
-    instruction: Join the lobby you're told the code for, then play.
-  - id: player-3
-    device: small-mobile
-    instruction: Join the lobby you're told the code for, then play.
-execution:
-  target: e2b-desktop
-  # Each participant's session budget, which also bounds the host's handoff deadline. It has to
-  # cover provisioning, joining the shared session and play; 420000 ms (7 minutes) does.
-  timeoutMs: 420000
-  concurrency: 3 # all three participants at once, the default; lower it only to limit paid desktops
-  # desktop:
-  #   fidelity: { mobileEmulation: true } # opt into mobile CSS viewport, touch, DPR and user agent
-defaults:
-  open: true
-`,
-    },
-    {
-        path: "humanish/coverage-map.md",
-        plane: "source",
-        contents: `# Coverage Map
-
-This file should enumerate screens, roles, states, and paths before scenarios are treated as complete.
-
-Current starter coverage is intentionally minimal and synthetic.
-`,
-    },
-    {
-        path: "humanish/coverage-matrix.md",
-        plane: "source",
-        contents: `# Coverage Matrix
-
-| Area | Persona | Happy Path | Sad Path | Status |
-| --- | --- | --- | --- | --- |
-| First run | synthetic-new-user | planned | planned | starter |
-| Onboarding | skeptical-power-user | planned | planned | starter |
 `,
     },
 ];
@@ -412,10 +324,12 @@ export const humanishScripts = {
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
-export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent) {
+export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent, command = "humanish") {
     return starterFiles.map((file) => file.path === "humanish/studies/local-browser.yaml"
         ? localBrowserStudy(localBrowser)
         : file.path === "humanish/studies/try-live.yaml"
             ? tryLiveStudy(actor, localAgent)
-            : file);
+            : file.path === "humanish/README.md"
+                ? readmeFile(command)
+                : file);
 }

package/dist/study/init.js

@@ -1,7 +1,10 @@
 import { realpath } from "node:fs/promises";
 import path from "node:path";
-import { AGENTS_SECTION_MARKER, agentsSection, firstRunGuidance, starterActorFor, starterLocalAgentFor, } from "../cli/first-run-path.js";
+import { agentsSection, firstRunGuidance, starterActorFor, starterLocalAgentFor, } from "../cli/first-run-path.js";
 import { detectLocalAgents } from "../actors/local-agent/cli.js";
+import { humanishCommand } from "../cli/invocation.js";
+import { replaceAgentsSection } from "./agents-section.js";
+import { probeLocalBrowserHost } from "./local-browser-host.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { DEFAULT_LOCAL_BROWSER_STARTER, runtimeDirectories, starterFilesFor, } from "./init-templates.js";
 import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
@@ -38,13 +41,13 @@ export async function runInit(options) {
     if (initialPathCheck) {
         return failed(initialPathCheck);
     }
-    await planAgentsFile(preparedProjectRoot, cwd, plan);
     // The starter live study is written for the brain this machine can actually use. Shipping it as
     // openai-computer-use on a machine with no provider key but a signed-in Codex would hand someone
     // a file that asks for a credential they were just told they do not need.
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
+    await planAgentsFile(preparedProjectRoot, cwd, plan, humanishCommand());
     const starterActor = starterActorFor(machine);
-    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
+    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine), machine.humanish), options.localBrowser !== undefined, plan);
     await planRuntimeDirectories(preparedProjectRoot, cwd, plan);
     const gitignorePlan = await planGitignore(preparedProjectRoot, cwd);
     plan.changes.push(gitignorePlan.change);
@@ -88,47 +91,40 @@ export async function runInit(options) {
 // `humanish init` is a coding agent doing setup on someone's behalf. Without this, the agent
 // that arrives tomorrow finds a humanish/ directory and no idea what to do with it.
 //
-// Append-only and idempotent: an existing `AGENTS.md` is a file someone wrote, so humanish adds its
-// own section once and never rewrites theirs.
-async function planAgentsFile(preparedProjectRoot, cwd, plan) {
+// An existing `AGENTS.md` is a file someone wrote. init appends its own section once, and on a
+// rerun replaces only that section, between its two markers, so the commands match the installed
+// humanish. Every byte outside the markers stays as it was.
+async function planAgentsFile(preparedProjectRoot, cwd, plan, humanish) {
     const agentsPath = "AGENTS.md";
     const existingAgents = await readTextIfExists(preparedProjectRoot, agentsPath);
-    const section = agentsSection();
-    if (existingAgents === null) {
-        plan.changes.push({
-            path: agentsPath,
-            action: "create",
-            target: "source",
-            reason: "how a coding agent runs humanish here",
-        });
+    const section = agentsSection(humanish);
+    const write = (contents, action, reason) => {
+        plan.changes.push({ path: agentsPath, action, target: "source", reason });
         plan.writes.push({
             absolutePath: path.join(cwd, agentsPath),
             relativePath: agentsPath,
-            contents: `# AGENTS.md\n${section}`,
+            contents,
             target: "source",
         });
+    };
+    const skip = (reason) => plan.changes.push({ path: agentsPath, action: "skip", target: "source", reason });
+    if (existingAgents === null) {
+        write(`# AGENTS.md\n${section}`, "create", "how a coding agent runs humanish here");
+        return;
     }
-    else if (existingAgents.includes(AGENTS_SECTION_MARKER)) {
-        plan.changes.push({
-            path: agentsPath,
-            action: "skip",
-            target: "source",
-            reason: "humanish section already present",
-        });
+    const replaced = replaceAgentsSection(existingAgents, section);
+    if (replaced.kind === "absent") {
+        write(`${existingAgents.replace(/\s*$/, "")}\n${section}`, "update", "append how a coding agent runs humanish");
+    }
+    else if (replaced.kind === "unknown") {
+        skip("humanish section edited by hand");
+        plan.warnings.push(`Left the humanish section of ${agentsPath} unchanged: it has no end marker and does not match a version init wrote, so it may hold your edits. To get the current section, delete it from the "## humanish" heading to the end of the section and run init again.`);
+    }
+    else if (replaced.contents === existingAgents) {
+        skip("humanish section is current");
     }
     else {
-        plan.changes.push({
-            path: agentsPath,
-            action: "update",
-            target: "source",
-            reason: "append how a coding agent runs humanish",
-        });
-        plan.writes.push({
-            absolutePath: path.join(cwd, agentsPath),
-            relativePath: agentsPath,
-            contents: `${existingAgents.replace(/\s*$/, "")}\n${section}`,
-            target: "source",
-        });
+        write(replaced.contents, "update", "refresh the humanish section");
     }
 }
 /** Create each starter file that is missing; never overwrite one that exists. */
@@ -318,8 +314,9 @@ async function firstRunEnvironment(env, cwd) {
         localAgents: agents
             .filter((agent) => agent.authStatus === "authenticated")
             .map((agent) => ({ id: agent.id, label: agent.label })),
+        localBrowserHost: await probeLocalBrowserHost(),
         platform: process.platform,
-        arch: process.arch,
+        humanish: humanishCommand(),
     };
 }
 function getMode(options) {

package/dist/study/local-browser-host.d.ts

@@ -0,0 +1,11 @@
+import type { LocalBrowserHost } from "../cli/first-run-path.js";
+export interface LocalBrowserHostProbe {
+    platform: NodeJS.Platform;
+    arch: string;
+    env: NodeJS.ProcessEnv;
+    /** Resolves when `file` can be opened with `mode`; rejects otherwise. */
+    access: (file: string, mode: number) => Promise<void>;
+    /** The Mac's chip name, as `sysctl -n machdep.cpu.brand_string` prints it. */
+    macChip: () => Promise<string>;
+}
+export declare function probeLocalBrowserHost(probe?: LocalBrowserHostProbe): Promise<LocalBrowserHost>;

package/dist/study/local-browser-host.js

@@ -0,0 +1,42 @@
+// init's quick read of whether this host can run a local browser study, so its next steps never
+// send someone to a route the host cannot run. It reads devices, `PATH` and the Mac chip name only;
+// it starts no container and no VM. `doctor --study local-browser` runs the full check, including
+// whether Docker is rootful and local.
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+const defaultProbe = () => ({
+    platform: process.platform,
+    arch: process.arch,
+    env: process.env,
+    access,
+    macChip: async () => (await exec("sysctl", ["-n", "machdep.cpu.brand_string"], { timeout: 5_000 })).stdout,
+});
+export async function probeLocalBrowserHost(probe = defaultProbe()) {
+    const can = async (file, mode) => probe.access(file, mode).then(() => true, () => false);
+    if (probe.platform === "linux" && probe.arch === "x64") {
+        // The same device checks doctor makes. The rootful Docker daemon opens these devices, so this
+        // user needs no access to them.
+        if (!(await can("/dev/kvm", constants.F_OK)))
+            return { ok: false, reason: "/dev/kvm is missing" };
+        if (!(await can("/dev/net/tun", constants.F_OK)))
+            return { ok: false, reason: "/dev/net/tun is missing" };
+        const dirs = (probe.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+        for (const dir of dirs)
+            if (await can(path.join(dir, "docker"), constants.X_OK))
+                return { ok: true };
+        return { ok: false, reason: "the docker command is not on the search path" };
+    }
+    if (probe.platform === "darwin" && probe.arch === "arm64") {
+        // The local route needs nested virtualization, which Apple added with the M3.
+        const chip = await probe.macChip().catch(() => "");
+        const generation = /^Apple M(\d+)/.exec(chip.trim());
+        if (generation !== null && Number(generation[1]) >= 3)
+            return { ok: true };
+        return { ok: false, reason: "they need an M3 or newer Mac" };
+    }
+    return { ok: false, reason: "they need Linux x64 or an M3-or-newer Mac" };
+}

package/dist/study/parse/actors.js

@@ -2,6 +2,7 @@ import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isReasoningEffort, reasoningEffortNames } from "../../actors/reasoning-effort.js";
 import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
 import { isHttpUrl } from "./subject.js";
+import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
 import { invalid, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
@@ -265,13 +266,20 @@ function parseParticipantEntries(raw, actorIndex) {
             if (!isHttpUrl(target)) {
                 return invalid(`actors[${actorIndex}].lanes[${entryIndex}].target must be an absolute http(s) URL.`);
             }
+            const credential = urlCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].target`, target);
+            if (credential)
+                return invalid(credential);
             parsedEntry.target = target;
         }
         // `entry` is shape-captured here; the same-origin-with-serve.url check needs serve context, so
         // it runs in sharedWorldValidationReason (where the route + serve.url are known).
         const entryPath = str(entry.entry);
-        if (entryPath !== undefined)
+        if (entryPath !== undefined) {
+            const credential = entryCredentialReason(`actors[${actorIndex}].lanes[${entryIndex}].entry`, entryPath);
+            if (credential)
+                return invalid(credential);
             parsedEntry.entry = entryPath;
+        }
         // `host` marks the designated host on the external-public shared-world route; the
         // exactly-one-host check runs in externalPublicSharedWorldValidationReason (route context).
         if (entry.host !== undefined) {