humanish 0.110.1 → 0.110.2

package/dist/observer/run-routes.js

@@ -4,6 +4,7 @@
 import path from "node:path";
 import { isAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
+import { isLocalOnlyRunFile, isLocalOnlyRunFileIdentity } from "../run/local-only-files.js";
 import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
@@ -70,9 +71,11 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     // file serving bypass its current-content checks or a warmed source-only admission cache.
     const derivedRoot = cleanedRelativePath.split("/")[0];
     const derivedLeaf = path.posix.basename(cleanedRelativePath);
+    // Local-only files (raw sandbox ids, the recording pid) are read in process, never served.
     if (derivedRoot === ".analysis-lock" ||
         derivedLeaf.startsWith(".humanish-write-") ||
-        isAnalysisRecordPath(cleanedRelativePath)) {
+        isAnalysisRecordPath(cleanedRelativePath) ||
+        isLocalOnlyRunFile(cleanedRelativePath)) {
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
         return;
     }
@@ -103,6 +106,10 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         await serveContainedMedia(runRoot, filePath, response, request);
         return;
     }
+    if (await isLocalOnlyRunFileIdentity(root, filePath)) {
+        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
+        return;
+    }
     try {
         const body = await readContainedFile(runRoot, filePath);
         if (!body) {

package/dist/observer/serve.js

@@ -10,6 +10,7 @@ import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin, } from "./ht
 import { isSafeRunIdSegment } from "../run/paths.js";
 import { listRuns } from "../run/stored-runs.js";
 import { verifyRun } from "../verify/verify.js";
+import { cli } from "../cli/invocation.js";
 export const SERVE_SCHEMA = "humanish.serve-result.v1";
 export function createShareSafetyAdmission(cwd, options = {}) {
     const verifyImpl = options.verifyImpl ?? verifyRun;
@@ -196,7 +197,7 @@ export async function serveObserverLibrary(cwdInput, options) {
             ok: false,
             error: {
                 code: "HUMANISH_RUN_NOT_FOUND",
-                message: "No run library found under .humanish/runs. Run `humanish watch` to create the first run.",
+                message: `No run library found under .humanish/runs. Run \`${cli("run first-run")}\` to create the first run.`,
             },
         };
     }

package/dist/routes/computer-use/plan.js

@@ -5,6 +5,7 @@
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { isHttpUrl, isLoopbackUrl } from "../../study/parse/subject.js";
+import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
@@ -134,6 +135,10 @@ function subjectStructureReason(config, subjectRoute) {
  */
 function entryTargetReason(config, subjectRoute) {
     const { desktopCliRoute, provisionedRoute, localAppSubject, appUrl } = subjectRoute;
+    // A library caller's config skips the parser, which refuses these first.
+    const credential = studyUrlCredentialReason(config);
+    if (credential)
+        return { code: "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE", message: credential };
     if (desktopCliRoute)
         return undefined;
     const allowPublicTargets = config.policies?.allowPublicTargets === true;

package/dist/routes/shared-world/plan.js

@@ -3,6 +3,7 @@
 // external state: keys and subject env values, the external comms catch, the packed working tree
 // and email receiving setup.
 import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provider.js";
+import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { brainOf, capsOf, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
@@ -48,7 +49,10 @@ export function planSharedWorldStudy(config, input) {
     // exists because getHost is internet-reachable and harness-owned, and a public site the harness
     // neither provisioned nor exposed is neither.
     const externalPublic = config.subject.source === "app-url";
-    const invalidReason = outputTokenLimitValidationReason(config) ??
+    const invalidReason = 
+    // A library caller's config skips the parser, which refuses these first.
+    studyUrlCredentialReason(config) ??
+        outputTokenLimitValidationReason(config) ??
         scenarioCapsValidationReason(config) ??
         (externalPublic
             ? externalPublicSharedWorldValidationReason(config)

package/dist/routes/terminal/bundle.js

@@ -6,6 +6,7 @@ import { reviewOutcome } from "../../run/display.js";
 import {} from "../../run/streams.js";
 import { participantEvent, participantIds, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { TERMINAL_EVENTS_ARTIFACT, TERMINAL_LEDGERS_ARTIFACT, TERMINAL_TRANSCRIPT_ARTIFACT, } from "../../run/terminal-contract.js";
+import { DEFAULT_RUNTIME_AUTH } from "./runtime-auth.js";
 import { describeMeasuredSpend, noSpendLineMeasured, noSpendNotEstablished } from "./ledger.js";
 /**
  * Project the terminal-product run into a humanish.run-bundle.v1 (no schema change: a new
@@ -59,7 +60,7 @@ export function buildTerminalProductBundle(args) {
             type: "terminal-lab.credentials.declared",
             // Names-only evidence: the runtime-auth channel is declared; no value is ever
             // recorded. The deny-by-default policies are recorded so the credential posture is auditable.
-            message: `Runtime auth channel: ${args.runtimeAuth ?? "none declared"} (names only; values never persist; the live engine applies the selected key placement, while this dry-run performs no injection). Credential policies (deny-by-default): allowPrivateRepoAccess=${args.policies.allowPrivateRepoAccess}, allowProviderCredentials=${args.policies.allowProviderCredentials}, allowPaymentCredentials=${args.policies.allowPaymentCredentials}, allowGitHubMutation=${args.policies.allowGitHubMutation}.`,
+            message: `Runtime auth channel: ${args.runtimeAuth ?? `${DEFAULT_RUNTIME_AUTH}, the default`} (names only; values never persist; the live engine applies the selected key placement, while this dry-run performs no injection). Credential policies (deny-by-default): allowPrivateRepoAccess=${args.policies.allowPrivateRepoAccess}, allowProviderCredentials=${args.policies.allowProviderCredentials}, allowPaymentCredentials=${args.policies.allowPaymentCredentials}, allowGitHubMutation=${args.policies.allowGitHubMutation}.`,
         }),
         participantEvent(TERMINAL_IDS, {
             id: "event-003-caps",

package/dist/routes/terminal/credentials.d.ts

@@ -1,12 +1,12 @@
 import type { StudyRuntimeAuth } from "../../study/types.js";
 /**
- * Resolve the runtime key on the host. Legacy openai-env passes it command-scoped; openai-egress
- * returns an inert command env while retaining the actual value for the external transform and
- * literal redaction. Only CODEX_API_KEY/OPENAI_API_KEY are accepted as sources. No other operator
- * credential is forwarded. The real value must never be logged or persisted in either mode.
+ * Resolve the runtime key on the host. openai-egress, the default, returns an inert command env
+ * while retaining the actual value for the external transform and literal redaction; openai-env
+ * passes it command-scoped. Only CODEX_API_KEY/OPENAI_API_KEY are accepted as sources. No other
+ * operator credential is forwarded. The real value must never be logged or persisted in either mode.
  */
 export declare function buildRuntimeAuth(args: {
-    /** Undefined retains the historical openai-env default. */
+    /** Undefined selects openai-egress, so the raw key stays out of the sandbox unless a study opts in. */
     runtimeAuth: StudyRuntimeAuth | undefined;
     /** The operator environment the key value is read from (process.env or a test fake). */
     env: Record<string, string | undefined>;

package/dist/routes/terminal/credentials.js

@@ -1,10 +1,10 @@
-import { E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER } from "./runtime-auth.js";
+import { DEFAULT_RUNTIME_AUTH, E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER, } from "./runtime-auth.js";
 import { TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA } from "./types.js";
 /**
- * Resolve the runtime key on the host. Legacy openai-env passes it command-scoped; openai-egress
- * returns an inert command env while retaining the actual value for the external transform and
- * literal redaction. Only CODEX_API_KEY/OPENAI_API_KEY are accepted as sources. No other operator
- * credential is forwarded. The real value must never be logged or persisted in either mode.
+ * Resolve the runtime key on the host. openai-egress, the default, returns an inert command env
+ * while retaining the actual value for the external transform and literal redaction; openai-env
+ * passes it command-scoped. Only CODEX_API_KEY/OPENAI_API_KEY are accepted as sources. No other
+ * operator credential is forwarded. The real value must never be logged or persisted in either mode.
  */
 export function buildRuntimeAuth(args) {
     // The "openai-env" channel accepts CODEX_API_KEY or OPENAI_API_KEY as the runtime key source
@@ -46,7 +46,15 @@ export function buildRuntimeAuth(args) {
     // GITHUB_TOKEN/GH_TOKEN, no payment/deploy/db/media key, excluded by construction. When the
     // source was OPENAI_API_KEY, the same value is also injected as CODEX_API_KEY so codex exec's
     // documented single-invocation auth channel is populated either way (see the comment above).
-    const mode = args.runtimeAuth ?? "openai-env";
+    const mode = args.runtimeAuth ?? DEFAULT_RUNTIME_AUTH;
+    // Only the exact openai-env value places the raw key in the command, so a misspelled mode from a
+    // config that skipped the planner is refused, never read as openai-env.
+    if (mode !== "openai-egress" && mode !== "openai-env")
+        return {
+            ok: false,
+            code: "HUMANISH_TERMINAL_CREDENTIAL_DENIED",
+            message: "Runtime auth must be openai-egress or openai-env; no key was placed.",
+        };
     const envs = mode === "openai-egress"
         ? // Codex documents this verified-TLS trust channel. The stock image's default OpenSSL CA
             // file can be absent even though E2B has installed its proxy CA in the system bundle.

package/dist/routes/terminal/plan.js

@@ -6,6 +6,7 @@ import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { isReasoningEffort } from "../../actors/reasoning-effort.js";
 import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.js";
 import { isNonEmpty, planBase } from "../../study/plan-base.js";
+import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
@@ -26,6 +27,13 @@ export function planTerminalStudy(config, input) {
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
         return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", mediaReason);
+    // A library caller's config skips the parser, which refuses these first.
+    const credential = studyUrlCredentialReason(config);
+    if (credential)
+        return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", credential);
+    const runtimeAuth = config.execution?.runtimeAuth;
+    if (runtimeAuth !== undefined && runtimeAuth !== "openai-egress" && runtimeAuth !== "openai-env")
+        return refuse("HUMANISH_TERMINAL_CREDENTIAL_DENIED", "`execution.runtimeAuth` must be openai-egress or openai-env. Leave it out for openai-egress, which keeps the OpenAI key outside the sandbox.");
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);

package/dist/routes/terminal/route.js

@@ -11,10 +11,11 @@
 // The safety contract (`docs/history/goals/terminal-product-lane/goal.md`) is enforced by construction in
 // the files each item names, and checked by the verifier (verify/actor.ts
 // validateTerminalProductEvidence):
-//   1. Explicit key placement. openai-env (default) injects the raw runtime key command-scoped,
-//      never through Sandbox.create({envs}). Opt-in openai-egress sends it only in the host-side E2B
-//      header transform and passes an inert command placeholder. The proxy is spendable by every
-//      sandbox process from creation; this protects the raw key, not provider spending.
+//   1. Explicit key placement. openai-egress (default) sends the raw runtime key only in the
+//      host-side E2B header transform and passes an inert command placeholder. The proxy is
+//      spendable by every sandbox process from creation; this protects the raw key, not provider
+//      spending. Opt-in openai-env injects the raw key command-scoped, never through
+//      Sandbox.create({envs}).
 //      Enforced in credentials.ts and runtime-auth.ts.
 //   2. Fail-closed cap. The live key is never exercised without scenario.caps in force: maxUsd
 //      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).

package/dist/routes/terminal/runtime-auth.d.ts

@@ -1,4 +1,10 @@
+import type { StudyRuntimeAuth } from "../../study/types.js";
 import type { E2BNetworkOptions } from "../../substrates/e2b/sdk.js";
+/**
+ * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
+ * so the raw key stays in the host-side E2B request unless a study declares openai-env.
+ */
+export declare const DEFAULT_RUNTIME_AUTH: StudyRuntimeAuth;
 /** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
 export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
 /** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */

package/dist/routes/terminal/runtime-auth.js

@@ -1,3 +1,8 @@
+/**
+ * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
+ * so the raw key stays in the host-side E2B request unless a study declares openai-env.
+ */
+export const DEFAULT_RUNTIME_AUTH = "openai-egress";
 const OPENAI_EGRESS_HOST = "api.openai.com";
 /** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
 export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";

package/dist/run/dry-run.js

@@ -11,6 +11,7 @@ import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./
 import { loadDryRunInputs } from "./dry-run-inputs.js";
 import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk, verdictText, } from "./judge.js";
 import { reviewOutcome } from "./display.js";
+import { cli } from "../cli/invocation.js";
 /**
  * The preview route's run. The run scope closes the run it started on every exit, including
  * the fail-closed ones. It renders an Observer only when `options.observer` asks for one.
@@ -49,7 +50,7 @@ async function runDryRunInScope(options, scope) {
     if (!options.dryRun) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_LIVE_RUN_UNIMPLEMENTED",
-            message: "humanish run needs a study. List studies with humanish study list, or run humanish run --dry-run for a sample bundle.",
+            message: `humanish run needs a study. List studies with ${cli("study list")}, or run ${cli("run --dry-run")} for a sample bundle.`,
         });
     }
     const createdAt = new Date().toISOString();

package/dist/run/judge.js

@@ -12,6 +12,7 @@
 //   4. foldScorerFailures, which every route with a scorer applies before the run finishes;
 //   5. the outcome: judgeExecution applies the route's policy to its execution failures, and
 //      resultOk gives the result's ok.
+import { cli } from "../cli/invocation.js";
 /**
  * The participant said it reached the goal having taken no action and said nothing, and no stop
  * condition ended the session. It most likely saw a blank or loading screen, so it is not a pass.
@@ -126,7 +127,7 @@ export const EXECUTION_FAILURE_KINDS = [
 export function sandboxCleanupFailure(owner, warning, runId, recovery) {
     return {
         kind: "sandbox-cleanup",
-        message: `${owner}: ${warning ?? "Sandbox release is unconfirmed."} ${recovery ?? `Reclaim it by recorded id with \`humanish reclaim --run ${runId}\`.`}`,
+        message: `${owner}: ${warning ?? "Sandbox release is unconfirmed."} ${recovery ?? `Reclaim it by recorded id with \`${cli(`reclaim --run ${runId}`)}\`.`}`,
     };
 }
 /** Each route's outcome policy, in one place. */

package/dist/run/local-only-files.d.ts

@@ -0,0 +1,13 @@
+/** Each local-only file, relative to the run directory, with why a shared copy omits it. */
+export declare const LOCAL_ONLY_RUN_FILES: ReadonlyMap<string, string>;
+/**
+ * Whether a run-relative posix path names a local-only file. Case is ignored, so a request that
+ * spells the name differently cannot reach the file on a case-insensitive filesystem.
+ */
+export declare function isLocalOnlyRunFile(relativePath: string): boolean;
+/**
+ * Whether `filePath` is one of the local-only files of the run at `runRoot` under another
+ * spelling: the same device and inode. A case-insensitive filesystem also folds Unicode, so a name
+ * check alone cannot rule every spelling out.
+ */
+export declare function isLocalOnlyRunFileIdentity(runRoot: string, filePath: string): Promise<boolean>;

package/dist/run/local-only-files.js

@@ -0,0 +1,35 @@
+// Run files that mean something only on the machine that recorded the run. sandbox-receipts.ndjson
+// holds the raw sandbox ids reclaim kills by, and status.json holds the recording process's pid.
+// Bundle export leaves both out of a shared copy, and the Observer servers never hand them out.
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { SANDBOX_RECEIPTS_ARTIFACT } from "./sandbox-receipts.js";
+import { RUN_STATUS_FILE } from "./status.js";
+/** Each local-only file, relative to the run directory, with why a shared copy omits it. */
+export const LOCAL_ONLY_RUN_FILES = new Map([
+    [RUN_STATUS_FILE, "local process status is not a new attempt"],
+    [SANDBOX_RECEIPTS_ARTIFACT, "operational journal does not confer a derivative resource lease"],
+]);
+/**
+ * Whether a run-relative posix path names a local-only file. Case is ignored, so a request that
+ * spells the name differently cannot reach the file on a case-insensitive filesystem.
+ */
+export function isLocalOnlyRunFile(relativePath) {
+    return LOCAL_ONLY_RUN_FILES.has(relativePath.toLowerCase());
+}
+/**
+ * Whether `filePath` is one of the local-only files of the run at `runRoot` under another
+ * spelling: the same device and inode. A case-insensitive filesystem also folds Unicode, so a name
+ * check alone cannot rule every spelling out.
+ */
+export async function isLocalOnlyRunFileIdentity(runRoot, filePath) {
+    const requested = await lstat(filePath, { bigint: true }).catch(() => null);
+    if (requested === null)
+        return false;
+    for (const name of LOCAL_ONLY_RUN_FILES.keys()) {
+        const local = await lstat(path.join(runRoot, name), { bigint: true }).catch(() => null);
+        if (local !== null && local.dev === requested.dev && local.ino === requested.ino)
+            return true;
+    }
+    return false;
+}

package/dist/run/reclaim.d.ts

@@ -18,6 +18,11 @@ export interface ReclaimResult {
     tagSearch: ReclaimTagSearch;
     /** Creates that had not returned when reclaim finished; only the signal handler sees any. */
     createsInFlight: number;
+    /**
+     * Why there was nothing to look for: `dry-run` when run.json or status.json records the run as
+     * a dry run, which creates no sandboxes. Reclaim then contacts E2B for nothing.
+     */
+    reason?: "dry-run";
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";

package/dist/run/reclaim.js

@@ -11,12 +11,16 @@
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
 import { containedPathAbsent, readContainedRegularFile, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
-import { resolveRunPath } from "./locate.js";
+import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { RUN_STATUS_FILE } from "./status.js";
+import { isRecord } from "./type-guards.js";
 import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 import { sandboxOwnerTags, } from "./sandbox-creates.js";
 import { earlierOutcomes, GONE, RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, receiptWriter, rootState, searchTagSets, settledWithin, targetSet, } from "./reclaim-outcomes.js";
 import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { runIdOf } from "./paths.js";
+import { cli } from "../cli/invocation.js";
 export { RECLAIM_RECEIPT_ARTIFACT };
 export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
     return reclaimRun(cwd, runInput, () => resolveRunPath(cwd, runInput), hooks);
@@ -54,11 +58,14 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
             ...base,
             error: {
                 code: "HUMANISH_RECLAIM_RUN_NOT_FOUND",
-                message: `No run found for "${runInput}" (use \`humanish runs\` to list runs).`,
+                message: `No run found for "${runInput}" (use \`${cli("runs")}\` to list runs).`,
             },
         };
     }
     const runId = runIdOf(runPaths);
+    // The signal handler passes the creates it stopped and decides from what they reported.
+    if (hooks.creates === undefined && (await recordedDryRun(runPaths)))
+        return { ...base, ok: true, state: "clean", runId, reason: "dry-run" };
     const reclaimed = await reclaimRoot(runPaths, runId, hooks, warnings);
     if (reclaimed.kind === "module-unavailable")
         return {
@@ -85,6 +92,31 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
         createsInFlight,
     };
 }
+/**
+ * Whether the run records that it was a dry run: run.json and status.json, each one present, say
+ * `dry-run`. A run with neither record is not taken for one. A journal with any line in it, or an
+ * earlier reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a
+ * live one whatever its records say.
+ */
+async function recordedDryRun(runPaths) {
+    const modes = [];
+    for (const file of [RUN_BUNDLE_FILE, RUN_STATUS_FILE]) {
+        const record = await readRunJsonIfExists(runPaths, file);
+        if (isRecord(record))
+            modes.push(record.mode);
+    }
+    if (modes.length === 0 || modes.some((mode) => mode !== "dry-run"))
+        return false;
+    if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
+        const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+        if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
+            return false;
+    }
+    if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
+        return true;
+    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
+    return journal !== null && journal.toString("utf8").trim() === "";
+}
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/run-not-found.js

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { resolveRunsRoot } from "./paths.js";
+import { cli } from "../cli/invocation.js";
 /**
  * The message for a run that is not there: how to start one when the project has no runs, or how
  * to list them when it has. Only the runs directory's entry names are read.
@@ -10,6 +11,6 @@ export async function runNotFoundMessage(cwdInput, runInput) {
     const entries = await readdir(resolveRunsRoot(cwd)).catch(() => []);
     const hasRun = entries.some((name) => !name.startsWith(".") && !name.endsWith(".json"));
     return hasRun
-        ? `No run ${runInput}; humanish runs lists them.`
-        : `No runs in ${cwd} yet; start one with humanish run first-run.`;
+        ? `No run ${runInput}; ${cli("runs")} lists them.`
+        : `No runs in ${cwd} yet; start one with ${cli("run first-run")}.`;
 }

package/dist/run/sandbox-creates.js

@@ -1,7 +1,9 @@
 // The sandboxes this process is creating for each run directory, and the E2B tags that name the
-// directory. A receipt reaches sandbox-receipts.ndjson only after `Sandbox.create` resolves, and
-// on @e2b/desktop that is after desktop startup, seconds after E2B has created the sandbox. The
-// CLI's signal handler (src/cli/commands/run-signals.ts) uses this registry to cover that window:
+// directory. E2B creates a sandbox before its id reaches this process: on @e2b/desktop the startup
+// guard reports the id, and its receipt is written, only once the SDK has the handle, and a
+// create from an SDK without the guard reports it when `Sandbox.create` resolves, after desktop
+// startup. The CLI's signal handler (src/cli/commands/run-signals.ts) uses this registry to cover
+// the window before a receipt lands:
 // it stops new creates, kills every id a create has reported, and kills each in-flight create's
 // sandbox as soon as its id arrives. The tags let `humanish reclaim` find a sandbox whose id
 // never reached this process at all.

package/dist/run/sandbox-receipts.d.ts

@@ -23,12 +23,13 @@ export interface ParsedSandboxReceipt extends Omit<SandboxReceipt, "provider"> {
 /** The ids this process has receipted for `root`, whether or not the journal write landed. */
 export declare function appendedSandboxIds(root: PreparedOutputRoot): string[];
 /**
- * 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 declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<void>;
+export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<boolean>;
 /** Append one owner line; false when the write failed, which never fails the create. */
 export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags): Promise<boolean>;
 /** The owner tags every sandbox carries; sandboxOwnerTags in src/run/sandbox-creates.ts. */

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/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" };
+}