humanish 0.115.0 → 0.116.0

package/dist/comms/setup.js

@@ -13,6 +13,14 @@ import { resolveStudyManifest } from "../study/discover.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 import { otherStudyFiles } from "../study/files.js";
 import { isNodeError } from "../run/type-guards.js";
+/** The most of a study file the receiving copy reads, for its source and its destination. */
+const MAX_STUDY_COPY_BYTES = 1024 * 1024;
+/** The read found exactly `expected`, or found nothing where `expected` is null. */
+function readsAs(read, expected) {
+    return expected === null
+        ? read.status === "missing"
+        : read.status === "read" && read.bytes.equals(expected);
+}
 export async function checkCommsConnection(args) {
     const base = {
         schema: "humanish.comms-check.v1",
@@ -128,9 +136,10 @@ export async function configureCommsStudy(args) {
         const rel = path
             .relative(root.requestedPath, path.resolve(args.cwd, source.path))
             .replace(/\\/g, "/");
-        const bytes = await readContainedRegularFile(root, rel);
-        if (!bytes || bytes.length > 1024 * 1024)
+        const sourceRead = await readContainedRegularFile(root, rel, MAX_STUDY_COPY_BYTES);
+        if (sourceRead.status !== "read")
             return { ...base, message: "The study file is missing or too large." };
+        const bytes = sourceRead.bytes;
         const text = bytes.toString("utf8");
         const raw = parse(text);
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -182,13 +191,12 @@ export async function configureCommsStudy(args) {
                 ...base,
                 message: `${others.join(", ")} already uses the name ${stem}. Rename or remove it before configuring email, so \`run ${stem}\` reads one file.`,
             };
-        let prior;
-        try {
-            prior = await readContainedRegularFile(root, destination);
-        }
-        catch {
+        // An existing destination is replaced only when its bytes are in the plan token, so one that
+        // cannot be read whole is refused instead of being taken as absent.
+        const destinationRead = await readContainedRegularFile(root, destination, MAX_STUDY_COPY_BYTES);
+        if (destinationRead.status === "refused")
             return { ...base, message: "The local destination could not be read safely." };
-        }
+        const prior = destinationRead.status === "read" ? destinationRead.bytes : null;
         const content = String(study);
         const token = createHash("sha256")
             .update(bytes)
@@ -219,10 +227,8 @@ export async function configureCommsStudy(args) {
         const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
         const identity = await lock.stat();
         try {
-            const currentSource = await readContainedRegularFile(root, rel);
-            const currentDestination = await readContainedRegularFile(root, destination);
-            if (!currentSource?.equals(bytes) ||
-                (prior === null ? currentDestination !== null : !currentDestination?.equals(prior)))
+            const reread = (file) => readContainedRegularFile(root, file, MAX_STUDY_COPY_BYTES);
+            if (!readsAs(await reread(rel), bytes) || !readsAs(await reread(destination), prior))
                 return { ...base, message: "Files changed while saving. Preview again." };
             await writeContainedOutputFile(directory, filename, content, "utf8");
         }

package/dist/evidence/redaction.js

@@ -182,7 +182,15 @@ export function containsSensitive(text) {
 // suffix so redaction cannot turn a string's contents into JSON delimiters.
 // This also works when the closing quote arrives in a later stream callback.
 function redactLocalPaths(text, label) {
-    return LOCAL_PATH_PATTERNS.reduce((current, [pattern, replacement]) => current.replace(pattern, (match) => (label ?? replacement) + (match.match(/\\+$/)?.[0] ?? "")), text);
+    return LOCAL_PATH_PATTERNS.reduce((current, [pattern, replacement]) => current.replace(pattern, (match) => (label ?? replacement) + trailingBackslashes(match)), text);
+}
+// Read from the end: `/\\+$/` retries a run of backslashes from each of its characters when
+// something follows the run, which took 1.4 s on a path holding 40,000 of them.
+function trailingBackslashes(text) {
+    let start = text.length;
+    while (start > 0 && text.charCodeAt(start - 1) === 0x5c)
+        start -= 1;
+    return text.slice(start);
 }
 /**
  * What a shared copy of a run says in place of a provider sandbox id. scripts/public-surface-scan.mjs

package/dist/evidence/secret-scrub.d.ts

@@ -1,12 +1,22 @@
 /**
  * A value as written, and percent-encoded, JSON-escaped once (also with non-ASCII characters as
- * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 at each
- * byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as
- * a string. An
- * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
- * is not ordinary text.
+ * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 padded,
+ * unpadded and at each byte offset, base64url and hex. Twice, because a JSON event can carry a
+ * command's JSON output as a string. An escaped form is searched for at any length, as the value
+ * is: it holds a backslash or a `%`, so it is not ordinary text. A base64 or hex form is searched
+ * for from MIN_ENCODED_FORM characters, so a four-byte value is found in base64 written whole and
+ * not inside a longer run, where four or five of its characters do not depend on its neighbours.
  */
 export declare function encodedForms(value: string): string[];
+/**
+ * A scrub that replaces each non-empty value as written with `[REDACTED_SECRET]`, markers
+ * included. From the start of the text, the longest value that starts at a position is replaced
+ * and the search goes on after it, so the marker it writes is never searched. One global regex of
+ * the values, longest first, does that fastest. V8 compiles it at its first use and refuses it
+ * once a value has 32,768 characters; the scrub then finds each value itself, with the same
+ * output, in time linear in the text for each value.
+ */
+export declare function scrubValuesAsWritten(values: readonly string[]): (text: string) => string;
 /**
  * A check that the text holds one of the values' forms outside the markers in any of its
  * readingsOf. A scrub's output must pass it.

package/dist/evidence/secret-scrub.js

@@ -10,9 +10,12 @@ const REDACTED = REDACTION_MARKERS.secret;
 // of the marker's name. Other bracketed text, such as `[REDACTED_373433393231]`, is searched like
 // any text.
 const MARKER = new RegExp(Object.values(REDACTION_MARKERS).map(escapeRegExp).join("|"), "g");
-// The shortest encoded form searched for. Shorter base64 or hex runs are ordinary text often enough
-// that matching them would redact words. A value itself is searched for at any length.
-const MIN_ENCODED_FORM = 8;
+// The shortest encoded form searched for: the unpadded base64 of a four-byte value, such as a
+// four-digit code. A given form of n characters turns up by chance in random base64 about once in
+// 64^n characters, once in 69 billion at 6 and once in 17 million at 4. In the text of 9 real runs
+// (2.5 million characters) no 6- or 7-character form of any 4-, 5- or 6-digit code occurred. A
+// value itself is searched for at any length.
+const MIN_ENCODED_FORM = 6;
 /**
  * The characters of a value's base64 encoding that do not depend on its neighbours, with 0, 1 or
  * 2 bytes before it. A prefix byte shares the next character with the value, and so does the byte
@@ -31,11 +34,12 @@ function base64Middles(bytes, encoding) {
 }
 /**
  * A value as written, and percent-encoded, JSON-escaped once (also with non-ASCII characters as
- * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 at each
- * byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as
- * a string. An
- * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
- * is not ordinary text.
+ * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 padded,
+ * unpadded and at each byte offset, base64url and hex. Twice, because a JSON event can carry a
+ * command's JSON output as a string. An escaped form is searched for at any length, as the value
+ * is: it holds a backslash or a `%`, so it is not ordinary text. A base64 or hex form is searched
+ * for from MIN_ENCODED_FORM characters, so a four-byte value is found in base64 written whole and
+ * not inside a longer run, where four or five of its characters do not depend on its neighbours.
  */
 export function encodedForms(value) {
     const bytes = Buffer.from(value, "utf8");
@@ -51,8 +55,10 @@ export function encodedForms(value) {
     catch {
         // no percent-encoded form
     }
+    const base64 = bytes.toString("base64");
     const binary = [
-        bytes.toString("base64"),
+        base64,
+        base64.replace(/=+$/, ""),
         bytes.toString("base64url"),
         bytes.toString("hex"),
         ...base64Middles(bytes, "base64"),
@@ -127,6 +133,58 @@ function eachOccurrence(text, form, found) {
         at = matched > 0 ? -1 : text.indexOf(form, next);
     }
 }
+/**
+ * Each value's occurrences, the longest value that starts at a position replaced from the start of
+ * the text on, in time linear in the text for each value.
+ */
+function replaceLongestFirst(text, values) {
+    // The length of the longest value that starts at each position, allocated at the first find.
+    let longest;
+    for (const value of values)
+        eachOccurrence(text, value, (at) => {
+            longest ??= new Uint32Array(text.length);
+            longest[at] = Math.max(longest[at], value.length);
+        });
+    if (longest === undefined)
+        return text;
+    let result = "";
+    let cursor = 0;
+    for (let at = 0; at < text.length; at += 1) {
+        if (longest[at] === 0)
+            continue;
+        result += text.slice(cursor, at) + REDACTED;
+        cursor = at + longest[at];
+        at = cursor - 1;
+    }
+    return result + text.slice(cursor);
+}
+/**
+ * A scrub that replaces each non-empty value as written with `[REDACTED_SECRET]`, markers
+ * included. From the start of the text, the longest value that starts at a position is replaced
+ * and the search goes on after it, so the marker it writes is never searched. One global regex of
+ * the values, longest first, does that fastest. V8 compiles it at its first use and refuses it
+ * once a value has 32,768 characters; the scrub then finds each value itself, with the same
+ * output, in time linear in the text for each value.
+ */
+export function scrubValuesAsWritten(values) {
+    const written = [...new Set(values)].filter((value) => value.length > 0);
+    if (written.length === 0)
+        return (text) => text;
+    let pattern = new RegExp([...written]
+        .sort((left, right) => right.length - left.length)
+        .map(escapeRegExp)
+        .join("|"), "g");
+    return (text) => {
+        if (pattern !== undefined)
+            try {
+                return text.replace(pattern, REDACTED);
+            }
+            catch {
+                pattern = undefined;
+            }
+        return replaceLongestFirst(text, written);
+    };
+}
 /** Every occurrence of every form not wholly inside a marker, in no order. */
 function occurrences(text, forms) {
     const markers = [];

package/dist/feedback/draft.js

@@ -11,7 +11,7 @@ import { loadRunBundlePrepared } from "../run/locate.js";
 import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
 import { runNoteFile } from "../run/note-files.js";
 import { byRunTime } from "../run/note-shape.js";
-import { formatRunTime } from "../run/notes.js";
+import { formatRunTime } from "../run/run-clock.js";
 import { runParticipantCaptions } from "../run/participant-records.js";
 import { isRecord } from "../run/type-guards.js";
 import { feedbackProofCommands, projectFeedbackAcceptanceProof } from "./proof.js";

package/dist/feedback/export-bundle.js

@@ -12,16 +12,16 @@ import { inventorySandboxIds, scrubSandboxIdBytes } from "../run/sandbox-ids.js"
 import { containsSensitive, redactSandboxIds, redactScreenshot, redactText, } from "../evidence/redaction.js";
 import { decodeEscapes, readingsOf } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
-import { streamScreenshotPaths } from "../verify/artifacts.js";
+import { MAX_RUN_ENTRIES, streamScreenshotPaths } from "../verify/artifacts.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import {} from "../run/bundle.js";
 import { runIdOf, isPathInside, prepareRunArtifactPaths, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { isAnalysisRecordPath } from "../analysis/sharing.js";
 import { LOCAL_ONLY_RUN_FILES } from "../run/local-only-files.js";
-import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { readUnchangedFile } from "../run/evidence-files.js";
+import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
 const DERIVATION_SCHEMA = "humanish.redacted-derivation.v1";
-const MAX_FILES = 10_000;
 const TEXT_EXTENSIONS = new Set([
     ".json",
     ".ndjson",
@@ -69,8 +69,8 @@ async function inventory(root, maxBytes) {
         if (!before.isDirectory() || before.isSymbolicLink())
             throw new Error("Source contains an unsafe directory.");
         for (const name of (await readdir(directory)).sort()) {
-            if (++entriesSeen > MAX_FILES)
-                throw new Error(`Source exceeds ${MAX_FILES} inventory entries.`);
+            if (++entriesSeen > MAX_RUN_ENTRIES)
+                throw new Error(`Source exceeds ${MAX_RUN_ENTRIES} inventory entries.`);
             if (name.includes("\\") || name.includes("\0"))
                 throw new Error("Source contains an unsafe path segment.");
             const rel = relative ? `${relative}/${name}` : name;
@@ -86,15 +86,17 @@ async function inventory(root, maxBytes) {
             else {
                 if (path.extname(rel).toLowerCase() === ".mp4")
                     throw new Error("Continuous video/audio cannot be redacted by bundle export. Use --local-only HTML export for a snapshot-only copy.");
-                if (info.size > BigInt(maxBytes - total))
-                    throw new Error("Source inventory exceeds --max-bytes.");
-                const bytes = await readContainedRegularFile(root, rel);
-                if (bytes === null)
+                // At most what is left of --max-bytes, so a file that grows after this lstat is refused
+                // unread. With nothing left, an empty file still reads and any other is refused.
+                const read = await readUnchangedFile(root, rel, Math.max(1, maxBytes - total));
+                if (read.state === "unavailable")
                     throw new Error("Source artifact could not be read through its bound identity.");
-                total += bytes.length;
+                if (read.state === "limit")
+                    throw new Error("Source inventory exceeds --max-bytes.");
+                total += read.bytes.length;
                 if (total > maxBytes)
                     throw new Error("Source inventory exceeds --max-bytes.");
-                files.push({ path: rel, bytes, sha256: hash(bytes) });
+                files.push({ path: rel, bytes: read.bytes, sha256: hash(read.bytes) });
             }
         }
         const after = await lstat(directory, { bigint: true });
@@ -541,10 +543,12 @@ async function buildDerivative(stage, source, runId, bundle, maxBytes) {
         throw new Error("Derivative Observer could not be rebuilt.");
     const generated = [];
     for (const relative of ["observer/index.html", "observer/observer-data.json"]) {
-        const bytes = await readContainedRegularFile(stagePaths, relative);
-        if (bytes === null)
+        const read = await readUnchangedFile(stagePaths, relative, maxBytes);
+        if (read.state === "limit")
+            throw new Error("The regenerated Observer exceeds --max-bytes.");
+        if (read.state === "unavailable")
             throw new Error("Regenerated Observer artifact could not be read safely.");
-        generated.push({ path: relative, sha256: hash(bytes) });
+        generated.push({ path: relative, sha256: hash(read.bytes) });
     }
     await writeContainedOutputFile(stagePaths, "derivation.json", jsonBytes({ ...receipt, generated }));
     const derivativeVerify = await verifyRunPrepared(stage.physicalPath, runId, stagePaths);

package/dist/feedback/feedback.js

@@ -4,7 +4,7 @@ import { realpath } from "node:fs/promises";
 import { runNotFoundMessage } from "../run/run-not-found.js";
 import path from "node:path";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
-import { bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "../run/contained-output.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
 import { readNotesForSharing } from "../run/note-files.js";
 import { cli } from "../cli/invocation.js";
@@ -208,7 +208,9 @@ async function isSafeFeedbackEvidenceFile(context, evidencePath) {
         path.isAbsolute(relative)) {
         return false;
     }
-    return (await readContainedRegularFile(context.preparedRunPaths, relative)) !== null;
+    // Evidence a draft cites must be readable: a refused file is listed with the missing ones.
+    const read = await readContainedRegularFile(context.preparedRunPaths, relative, RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "read";
 }
 export async function renderIssueMarkdown(cwdInput, runInput, repo, options = {}) {
     const verified = await verifyFeedbackBound(cwdInput, runInput, options);
@@ -253,9 +255,22 @@ export async function listFeedback(cwdInput, runInput) {
             },
         };
     }
-    const draftBytes = await readContainedRegularFile(context.preparedRunPaths, path.join("feedback", "draft.json"));
-    const draft = draftBytes === null ? undefined : JSON.parse(draftBytes.toString("utf8"));
+    const draftRead = await readContainedRegularFile(context.preparedRunPaths, path.join("feedback", "draft.json"), RUN_ARTIFACT_MAX_BYTES);
     const draftPath = path.join(context.preparedRunPaths.relativeRunRoot, "feedback", "draft.json");
+    if (draftRead.status === "refused")
+        return {
+            schema: FEEDBACK_RESULT_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            error: {
+                code: "HUMANISH_INVALID_FEEDBACK_DRAFT",
+                message: `The feedback draft could not be read: ${refusalText(draftPath, draftRead)}.`,
+            },
+        };
+    const draft = draftRead.status === "missing"
+        ? undefined
+        : JSON.parse(draftRead.bytes.toString("utf8"));
     return {
         schema: FEEDBACK_RESULT_SCHEMA,
         ok: true,
@@ -284,10 +299,13 @@ async function resolveFeedbackRunContext(cwd, runInput) {
         const runsRoot = await bindExistingManagedHumanishOutputDirectory(physicalCwd, "runs");
         if (!runsRoot)
             return null;
-        const pointerBytes = await readContainedRegularFile(runsRoot, "latest.json");
-        if (!pointerBytes)
+        const pointerRead = await readContainedRegularFile(runsRoot, "latest.json", LATEST_POINTER_MAX_BYTES);
+        if (pointerRead.status === "missing")
             return null;
-        const pointer = JSON.parse(pointerBytes.toString("utf8"));
+        // A pointer that is there and refused names no run, and saying so beats "run not found".
+        if (pointerRead.status === "refused")
+            throw new ContainedReadRefusedError(path.join(".humanish", "runs", "latest.json"), pointerRead);
+        const pointer = JSON.parse(pointerRead.bytes.toString("utf8"));
         if (typeof pointer.runId !== "string" ||
             typeof pointer.path !== "string" ||
             !resolveLatestRunDirectory(physicalCwd, { path: pointer.path, runId: pointer.runId })) {

package/dist/guest/desktop-keys.js

@@ -3,18 +3,35 @@ import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.
 // hand these strings to xdotool, which has a command language, so only names from these tables
 // ever reach it. The guest runtime ships this module, so it lives in src/guest/, which CI's
 // guest-desktop job and scripts/guest-desktop-proof.mjs key on.
+//
+// The tables take the names in OpenAI's computer-use key map, the names @e2b/desktop's press()
+// mapped (the hosted desktop sent keys through it before), and every printable ASCII
+// punctuation character. xdotool finds the key and the Shift level for a keysym itself, so `?`
+// arrives as `question` with Shift held on an American English keymap.
 /** The modifiers a pointer action may hold, keyed by the upper-cased provider name. */
 const modifierNames = Object.freeze({
     CTRL: "ctrl",
     CONTROL: "ctrl",
     ALT: "alt",
+    OPTION: "alt",
     SHIFT: "shift",
     META: "super",
     SUPER: "super",
     CMD: "super",
+    COMMAND: "super",
+    WIN: "super",
+    WINDOWS: "super",
 });
 const keyNames = Object.freeze({
     ...modifierNames,
+    CONTROL_LEFT: "Control_L",
+    CONTROL_RIGHT: "Control_R",
+    ALT_LEFT: "Alt_L",
+    ALT_RIGHT: "Alt_R",
+    SHIFT_LEFT: "Shift_L",
+    SHIFT_RIGHT: "Shift_R",
+    SUPER_LEFT: "Super_L",
+    SUPER_RIGHT: "Super_R",
     ENTER: "Return",
     RETURN: "Return",
     TAB: "Tab",
@@ -24,11 +41,14 @@ const keyNames = Object.freeze({
     " ": "space",
     BACKSPACE: "BackSpace",
     DELETE: "Delete",
+    DEL: "Delete",
     INSERT: "Insert",
     HOME: "Home",
     END: "End",
     PAGEUP: "Prior",
     PAGEDOWN: "Next",
+    PAGE_UP: "Prior",
+    PAGE_DOWN: "Next",
     ARROWUP: "Up",
     ARROWDOWN: "Down",
     ARROWLEFT: "Left",
@@ -37,18 +57,45 @@ const keyNames = Object.freeze({
     DOWN: "Down",
     LEFT: "Left",
     RIGHT: "Right",
+    CAPS_LOCK: "Caps_Lock",
+    NUM_LOCK: "Num_Lock",
+    SCROLL_LOCK: "Scroll_Lock",
+    PAUSE: "Pause",
+    BREAK: "Pause",
+    PRINT: "Print",
+    MENU: "Menu",
+    "!": "exclam",
+    '"': "quotedbl",
+    "#": "numbersign",
+    $: "dollar",
+    "%": "percent",
+    "&": "ampersand",
+    "'": "apostrophe",
+    "(": "parenleft",
+    ")": "parenright",
+    "*": "asterisk",
     "+": "plus",
-    "-": "minus",
-    "=": "equal",
     ",": "comma",
+    "-": "minus",
     ".": "period",
     "/": "slash",
-    "\\": "backslash",
+    ":": "colon",
     ";": "semicolon",
-    "'": "apostrophe",
+    "<": "less",
+    "=": "equal",
+    ">": "greater",
+    "?": "question",
+    "@": "at",
     "[": "bracketleft",
+    "\\": "backslash",
     "]": "bracketright",
+    "^": "asciicircum",
+    _: "underscore",
     "`": "grave",
+    "{": "braceleft",
+    "|": "bar",
+    "}": "braceright",
+    "~": "asciitilde",
 });
 function lookup(table, key) {
     const upper = key.toUpperCase();
@@ -59,9 +106,16 @@ function chord(names) {
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     return names.join("+");
 }
+/**
+ * A name that is itself a chord (`Control+a`, `ctrl++`) split at each plus sign that joins two
+ * names. A lone `+` and a trailing `+` after a joining one are the plus key.
+ */
+function chordParts(key) {
+    return key.length > 1 ? key.split(/\+(?!$)/) : [key];
+}
 /** A keypress chord in xdotool syntax. Unknown or repeated keys are refused before dispatch. */
 export function xdotoolChord(keys) {
-    return chord(keys.map((key) => {
+    return chord(keys.flatMap(chordParts).map((key) => {
         if (/^[a-z0-9]$/i.test(key))
             return key.toLowerCase();
         if (/^F(?:[1-9]|1[0-2])$/i.test(key))

package/dist/keys/key-resolution.d.ts

@@ -1,3 +1,12 @@
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export declare const KEY_VENDORS: string[];
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export declare const LISTED_KEYS: {
+    name: string;
+    use: string;
+}[];
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export declare const DOCTOR_KEYS: string[];
 export interface ResolvedKeyFill {
     name: string;
     /** Human-readable source label (a path or command name), never a value. */

package/dist/keys/key-resolution.js

@@ -24,33 +24,56 @@ import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
 import { humanishConfigFile } from "../cli/user-config.js";
 import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
-/** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
- *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
- *  must never enter process env off a file the operator did not explicitly pass (an explicit
- *  --dotenv remains the operator's own full-file load). */
-const KNOWN_PROVIDER_KEYS = [
-    "OPENAI_API_KEY",
-    "ANTHROPIC_API_KEY",
-    "E2B_API_KEY",
-    "GH_TOKEN",
-    "GITHUB_TOKEN",
-    "CODEX_API_KEY",
-    "AGENTMAIL_API_KEY",
+/**
+ * The provider keys, in the order `humanish keys set` names their vendors. Implicit discovery fills
+ * only these names and the user store holds only these. Everything else in an overlay or store file
+ * is ignored and named: a repo-planted NODE_OPTIONS/LD_PRELOAD must never enter process env off a
+ * file the operator did not explicitly pass (an explicit --dotenv remains the operator's own
+ * full-file load). ANTHROPIC_API_KEY is not listed, and doctor does not report it: a Claude Code
+ * participant runs on its own login and never receives it. CODEX_API_KEY is an alternative spelling
+ * of the OpenAI key for terminal studies. Doctor reports AGENTMAIL_API_KEY only under `--study`, for
+ * a study whose email connection names it, since a connection may name another variable.
+ */
+const PROVIDER_KEYS = [
+    {
+        name: "OPENAI_API_KEY",
+        vendor: "openai",
+        listed: { order: 2, use: "participant model and analysis" },
+        doctor: true,
+    },
+    {
+        name: "E2B_API_KEY",
+        vendor: "e2b",
+        login: "e2b auth login",
+        listed: { order: 1, use: "hosted desktops" },
+        doctor: true,
+    },
+    { name: "ANTHROPIC_API_KEY", vendor: "anthropic" },
+    {
+        name: "GH_TOKEN",
+        vendor: "github",
+        login: "gh auth login",
+        listed: { order: 3, use: "private repository subjects" },
+        doctor: true,
+    },
+    { name: "GITHUB_TOKEN", spellingOf: "GH_TOKEN" },
+    { name: "CODEX_API_KEY", doctor: true },
+    { name: "AGENTMAIL_API_KEY", vendor: "agentmail", listed: { order: 4, use: "email in studies" } },
 ];
-const PROVIDER_KEY_SET = new Set(KNOWN_PROVIDER_KEYS);
+const PROVIDER_KEY_SET = new Set(PROVIDER_KEYS.map((key) => key.name));
+const providerKey = (name) => PROVIDER_KEYS.find((key) => key.name === name);
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export const KEY_VENDORS = PROVIDER_KEYS.flatMap((key) => key.vendor === undefined ? [] : [key.vendor]);
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export const LISTED_KEYS = PROVIDER_KEYS.flatMap(({ name, listed }) => listed === undefined ? [] : [{ name, ...listed }])
+    .sort((a, b) => a.order - b.order)
+    .map(({ name, use }) => ({ name, use }));
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export const DOCTOR_KEYS = PROVIDER_KEYS.flatMap(({ name, doctor }) => (doctor ? [name] : []));
 /** An env for a vendor CLI that discovery runs: the caller's, without any provider key name. */
 function withoutProviderKeys(env) {
     return Object.fromEntries(Object.entries(env).filter(([name]) => !PROVIDER_KEY_SET.has(name)));
 }
-/** `humanish keys set <vendor>` aliases; a raw ENV_NAME is also accepted. A Map, so a name such as
- * `constructor` is no alias. */
-const KEY_VENDOR_ALIASES = new Map([
-    ["openai", "OPENAI_API_KEY"],
-    ["e2b", "E2B_API_KEY"],
-    ["anthropic", "ANTHROPIC_API_KEY"],
-    ["github", "GH_TOKEN"],
-    ["agentmail", "AGENTMAIL_API_KEY"],
-]);
 const PROJECT_OVERLAY_RELATIVE = path.join(".humanish", "local", "provider.env");
 export function userKeyStorePath(env, deps = {}) {
     return humanishConfigFile(env, "keys.env", deps.homeDir);
@@ -230,21 +253,10 @@ function storeLabel(env, deps) {
 /** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
  *  *_KEYS_MISSING errors so the failure names the fix. */
 export function missingKeyHint(name) {
-    switch (name) {
-        case "E2B_API_KEY":
-            return `run \`e2b auth login\`, or \`${cli("keys set e2b")}\``;
-        case "GH_TOKEN":
-        case "GITHUB_TOKEN":
-            return `run \`gh auth login\`, or \`${cli("keys set github")}\``;
-        case "OPENAI_API_KEY":
-            return `run \`${cli("keys set openai")}\``;
-        case "ANTHROPIC_API_KEY":
-            return `run \`${cli("keys set anthropic")}\``;
-        case "AGENTMAIL_API_KEY":
-            return `run \`${cli("keys set agentmail")}\``;
-        default:
-            return `run \`${cli(`keys set ${name}`)}\``;
-    }
+    const named = providerKey(name);
+    const key = named?.spellingOf === undefined ? named : providerKey(named.spellingOf);
+    const set = `\`${cli(`keys set ${key?.vendor ?? name}`)}\``;
+    return key?.login === undefined ? `run ${set}` : `run \`${key.login}\`, or ${set}`;
 }
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each
  *  missing key. Pure text; never values. */
@@ -276,19 +288,18 @@ export async function probeKeySources(names, args) {
         ...(args.deps === undefined ? {} : { deps: args.deps }),
     });
     const bySource = new Map(fills.map((fill) => [fill.name, fill.source]));
+    const setInEnv = (name) => args.env[name] !== undefined && args.env[name]?.trim() !== "";
     return names.map((name) => {
-        const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "" && !placeholder(name);
-        // GH_TOKEN and GITHUB_TOKEN are one credential with two spellings; a doctor row that says
-        // "missing" while GITHUB_TOKEN sits in the env would be wrong.
-        const aliasInEnv = name === "GH_TOKEN" &&
-            args.env.GITHUB_TOKEN !== undefined &&
-            args.env.GITHUB_TOKEN.trim() !== "";
+        const inEnv = setInEnv(name) && !placeholder(name);
+        // A second spelling of the key in the env, such as GITHUB_TOKEN for GH_TOKEN, is the same
+        // credential; a doctor row that says "missing" while it sits in the env would be wrong.
+        const spelling = PROVIDER_KEYS.find((key) => key.spellingOf === name && setInEnv(key.name))?.name;
         const source = inEnv
             ? args.dotenv?.names.includes(name)
                 ? `--dotenv ${args.dotenv.path}`
                 : "process env"
-            : aliasInEnv
-                ? "process env (GITHUB_TOKEN)"
+            : spelling !== undefined
+                ? `process env (${spelling})`
                 : (bySource.get(name) ?? null);
         return {
             name,
@@ -301,9 +312,10 @@ export async function probeKeySources(names, args) {
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Resolve a `humanish keys set` target: a vendor alias or a raw env name. Null = invalid. */
 export function resolveKeyName(vendorOrName) {
-    const alias = KEY_VENDOR_ALIASES.get(vendorOrName.toLowerCase());
-    if (alias !== undefined)
-        return alias;
+    const vendor = vendorOrName.toLowerCase();
+    const key = PROVIDER_KEYS.find((candidate) => candidate.vendor === vendor);
+    if (key !== undefined)
+        return key.name;
     return ENV_NAME.test(vendorOrName) ? vendorOrName : null;
 }
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names