humanish 0.107.0 → 0.108.0

package/dist/evidence/redaction.js

@@ -105,9 +105,9 @@ export function publicPathForTrace(value, rootCwd) {
 // or a logged-in third-party UI. A raw frame must never reach a public artifact.
 // redactScreenshot is the fail-closed primitive that gates that surface. It
 // always returns a freshly re-encoded, downscaled, box-blurred thumbnail (or a
-// neutral placeholder), and NEVER the source pixels. The "too coarse to read"
+// neutral placeholder), and never the source pixels. The "too coarse to read"
 // invariant is enforced in code, not by defaults: the emitted width is hard-
-// capped (a caller may request a SMALLER thumbnail but never a larger one), and
+// capped (a caller may request a smaller thumbnail but never a larger one), and
 // the blur radius is computed internally with a floor, so neither a caller
 // option nor a natively small frame can widen the output back into legibility.
 // On any uncertainty (non-PNG input, an oversized or unreadable PNG, or any
@@ -241,7 +241,7 @@ export function tailText(value, maxChars) {
 }
 /**
  * A redacted, ellipsis-prefixed tail of captured output for a (public-bound)
- * message field. Pattern-redacts the FULL text BEFORE truncating: slicing a tail
+ * message field. Pattern-redacts the full text before truncating: slicing a tail
  * first could cut through a secret's prefix (e.g. drop "sk-proj-") and defeat the
  * pattern matcher on the remainder. Callers should literal-scrub known
  * provisioned values first; this is the pattern pass. Empty output -> "(no output)".
@@ -321,7 +321,7 @@ export function scrubLiterals(values) {
 /**
  * Coerce an unknown thrown value to its message string. Prefer this over the
  * inline `error instanceof Error ? error.message : String(error)` so error
- * stringification stays uniform. Note: this does NOT redact -- sites that emit
+ * stringification stays uniform. Note: this does not redact; sites that emit
  * to public-bound artifacts must run the result through `redactText` first.
  */
 export function toErrorMessage(error) {

package/dist/feedback/draft.js

@@ -49,95 +49,55 @@ export function buildDraft(bundle, bundlePath, candidateId) {
             acceptance_proof: projectFeedbackAcceptanceProof(bundle, candidate),
         };
     }
-    // #392: the fallback below is DRY-RUN-shaped, and it used to be the fallback for every bundle
-    // without a candidate — so a live run whose route filed no participant report got a draft
-    // claiming "no browser behavior was exercised" over 15 screenshots of browser behavior. A live
-    // bundle now gets a draft that describes the run that happened, built from the same review lines
-    // the stakeholder surfaces show (participants and tasks keep their denominators).
-    if (bundle.mode === "live") {
-        const participantEndings = participantOutcomeDetails(bundle.streams);
-        const review = withCuaReviewProvenance(bundle.review, bundle.streams);
-        const actualLines = [
-            review.summary,
-            ...(bundle.review.participants === undefined
-                ? []
-                : [
-                    `Participants: ${formatParticipantOutcomes(bundle.review.participants, participantEndings)}.`,
-                ]),
-            ...(bundle.review.tasks === undefined
-                ? []
-                : [`Tasks: ${formatRunTaskFunnel(bundle.review.tasks)}.`]),
-        ];
-        return {
-            schema: FEEDBACK_SCHEMA,
-            run_id: bundle.runId,
-            adapter_id: bundle.source.packageName ?? bundle.scenario.id,
-            scenario_id: bundle.scenario.id,
-            persona_id: bundle.persona.id,
-            actor: (bundle.streams ?? []).some((stream) => stream.actor?.lane === "computer-use")
-                ? "computer-use"
-                : "unknown",
-            substrate: "unknown",
-            failure_owner: "unknown",
-            summary: "Live study completed without a participant-reported finding",
-            expected: bundle.scenario.goal,
-            actual: actualLines.join(" "),
-            source_bundle: bundlePath,
-            evidence: [
-                {
-                    path: bundlePath,
-                    kind: "state",
-                    note: "Source run bundle.",
-                },
-                {
-                    path: path.join(path.dirname(bundlePath), "review.md"),
-                    kind: "review",
-                    note: "The run's review: verdict, participants, and gaps.",
-                },
-            ],
-            redaction: {
-                status: "passed",
-                notes: bundle.redaction.notes,
-            },
-            idempotency_key: `humanish:${bundle.runId}:live-run-summary`,
-            proposed_next_state: "study-quality-review",
-            acceptance_proof: [
-                feedbackProofCommands(bundle.runId).verify,
-                feedbackProofCommands(bundle.runId).watch,
-            ],
-        };
-    }
+    // A bundle without a candidate gets a draft that describes the run that happened, built from the
+    // same review lines the stakeholder surfaces show (participants and tasks keep their
+    // denominators). Feedback refuses a dry run before it gets here.
+    const participantEndings = participantOutcomeDetails(bundle.streams);
+    const review = withCuaReviewProvenance(bundle.review, bundle.streams);
+    const actualLines = [
+        review.summary,
+        ...(bundle.review.participants === undefined
+            ? []
+            : [
+                `Participants: ${formatParticipantOutcomes(bundle.review.participants, participantEndings)}.`,
+            ]),
+        ...(bundle.review.tasks === undefined
+            ? []
+            : [`Tasks: ${formatRunTaskFunnel(bundle.review.tasks)}.`]),
+    ];
     return {
         schema: FEEDBACK_SCHEMA,
         run_id: bundle.runId,
-        adapter_id: bundle.source.packageName ?? "synthetic-app",
+        adapter_id: bundle.source.packageName ?? bundle.scenario.id,
         scenario_id: bundle.scenario.id,
         persona_id: bundle.persona.id,
-        actor: "synthetic-dry-run",
-        substrate: "local-filesystem",
-        failure_owner: "harness",
-        summary: "Dry-run contract proof needs product-evidence follow-up",
-        expected: "humanish should produce verified, public-safe evidence before product claims are filed.",
-        actual: "This dry-run produced a contract-proof bundle only; no browser or product behavior was exercised.",
+        actor: (bundle.streams ?? []).some((stream) => stream.actor?.lane === "computer-use")
+            ? "computer-use"
+            : "unknown",
+        substrate: "unknown",
+        failure_owner: "unknown",
+        summary: "Live study completed without a participant-reported finding",
+        expected: bundle.scenario.goal,
+        actual: actualLines.join(" "),
         source_bundle: bundlePath,
         evidence: [
             {
                 path: bundlePath,
                 kind: "state",
-                note: "Synthetic run bundle.",
+                note: "Source run bundle.",
             },
             {
                 path: path.join(path.dirname(bundlePath), "review.md"),
                 kind: "review",
-                note: "Review skeleton labels this as contract proof only.",
+                note: "The run's review: verdict, participants, and gaps.",
             },
         ],
         redaction: {
             status: "passed",
             notes: bundle.redaction.notes,
         },
-        idempotency_key: `humanish:${bundle.runId}:dry-run-contract-proof`,
-        proposed_next_state: "watch",
+        idempotency_key: `humanish:${bundle.runId}:live-run-summary`,
+        proposed_next_state: "study-quality-review",
         acceptance_proof: [
             feedbackProofCommands(bundle.runId).verify,
             feedbackProofCommands(bundle.runId).watch,
@@ -254,11 +214,14 @@ export function isUsableFeedbackCandidate(candidate) {
         !item.path.includes("://") &&
         !item.path.includes(".."));
 }
+/** An evidence path inside the run directory, as "run.json" or "screenshots/step-003.png". */
+function runRelative(draft, evidencePath) {
+    const relative = path.relative(path.dirname(draft.source_bundle), evidencePath);
+    return relative === "" || relative.startsWith("..") ? evidencePath : relative;
+}
 export function renderMarkdown(draft, repo) {
     return `This issue was drafted by humanish from a verified humanish run bundle.
 
-It contributes to public-safe simulation harness coverage. The feedback command did not mutate GitHub, commit code, or claim unobserved product behavior.
-
 ## Summary
 
 ${draft.summary}
@@ -273,14 +236,9 @@ ${draft.actual}
 
 ## Evidence
 
-${draft.evidence.map((item) => `- ${item.kind}: \`${item.path}\` - ${item.note}`).join("\n")}
-
-## Filing Notes
+${draft.evidence.map((item) => `- ${item.kind} ${runRelative(draft, item.path)}: ${item.note}`).join("\n")}
 
-- Repository: ${repo}
-- GitHub mutation: not performed
-- Substrate: ${draft.substrate}
-- Production data: not used
+Repository: ${repo}
 
 \`\`\`yaml
 humanish_feedback:

package/dist/feedback/export-bundle.js

@@ -1,4 +1,4 @@
-// The publish boundary for existing raw runs (#136). A derivative is an isolated
+// The publish boundary for existing raw runs. A derivative is an isolated
 // workspace, never a new run in the source history. No provider APIs are involved.
 import { createHash } from "node:crypto";
 import { lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, rmdir } from "node:fs/promises";

package/dist/feedback/export.d.ts

@@ -46,5 +46,9 @@ export interface ExportDeps {
 /** The banner a --local-only export carries. Plain HTML, before the app root, so it renders with JS off. */
 export declare function localOnlyBanner(reasons: string[]): string;
 export declare function exportRun(cwdInput: string, runInput: string, options?: ExportOptions, deps?: ExportDeps): Promise<ExportResult | ExportFailure>;
-export declare function formatExportHuman(result: ExportResult | ExportFailure): string;
+/** Human output; a failure is an error the CLI prints on stderr (HumanOutput in src/cli/io.ts). */
+export declare function formatExportHuman(result: ExportResult): string;
+export declare function formatExportHuman(result: ExportResult | ExportFailure): string | {
+    error: ExportFailure["error"];
+};
 export {};

package/dist/feedback/export.js

@@ -1,4 +1,4 @@
-// `humanish export`: one file a coworker can open (#471).
+// `humanish export`: one file a coworker can open.
 //
 // A run is a directory. Sharing it meant a tunnel (`serve --expose`) or a hand-zipped bundle,
 // neither of which is "send one thing". The Observer is already a single-file artifact with the
@@ -40,7 +40,7 @@ const IMAGE_MIME = {
 export function localOnlyBanner(reasons) {
     const why = reasons.length === 0 ? "" : ` (${reasons.join(", ")})`;
     return (`<div id="humanish-local-only" role="alert" tabindex="0" style="position:sticky;top:0;z-index:2147483647;max-height:40vh;overflow:auto;background:#7a1f1f;color:#fff;font:600 14px/1.4 system-ui,sans-serif;padding:10px 16px;text-align:center">` +
-        `LOCAL ONLY. This export was made from a bundle that is not share-safe${why}. Do not forward it outside the team that owns the run.` +
+        `Local only. This export was made from a bundle that is not share-safe${why}. Do not forward it outside the team that owns the run.` +
         `</div>`);
 }
 async function isInside(root, candidate) {
@@ -146,9 +146,8 @@ async function readObserverSlot(cwd, runInput, runRoot, runId, verified, deps, w
         html = await readFile(observerPath, "utf8");
     }
     catch {
-        // `run` writes observer-data.json and no index.html; `watch` writes both (#597). The
-        // 0.72.0 dogfood participant hit this on its first export. Render it here, from the same
-        // artifact watch uses, so what produced the run never decides whether it can be sent.
+        // `run` writes observer-data.json and no index.html; `watch` writes both. Render it here, from
+        // the same artifact watch uses, so what produced the run never decides whether it can be sent.
         const rendered = await (deps.render ?? ((c, r) => renderObserver(c, r, { open: false })))(cwd, runInput).catch(() => ({ ok: false }));
         try {
             if (!rendered.ok)
@@ -281,7 +280,7 @@ function makePortable(inlined, verified) {
             }
         }
     }
-    // What verify said, in the file, so the chrome can agree with the result envelope (#584).
+    // What verify said, in the file, so the chrome can agree with the result envelope.
     const publicSafety = (inlined.publicSafety ?? {});
     inlined.publicSafety = {
         ...publicSafety,
@@ -358,7 +357,7 @@ function renderExportHtml(inlined, analysis, assets, verified, watermarked, omit
 }
 export function formatExportHuman(result) {
     if (!result.ok)
-        return `${result.error.code}: ${result.error.message}\n`;
+        return { error: result.error };
     if (result.format === "bundle") {
         return [
             `humanish export ${result.runId}`,
@@ -373,7 +372,7 @@ export function formatExportHuman(result) {
     const lines = [
         `humanish export ${result.runId}`,
         `file: ${result.path} (${(result.bytes / 1024).toFixed(0)} KB, ${result.embeddedImages} image(s) embedded)`,
-        `share safety: ${result.shareSafety.status}${result.watermarked ? " — WATERMARKED LOCAL ONLY" : ""}`,
+        `share safety: ${result.shareSafety.status}${result.watermarked ? " (watermarked: local only)" : ""}`,
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ];
     return `${lines.join("\n")}\n`;

package/dist/feedback/feedback.d.ts

@@ -13,11 +13,11 @@ export interface FeedbackResult {
     issueUrl?: string;
     draft?: FeedbackDraft;
     /** Every usable candidate on the bundle, so a multi-participant study's second and third findings can be
-     *  chosen with `--candidate` instead of being invisible behind the first (#609). */
+     *  chosen with `--candidate` instead of being invisible behind the first. */
     candidates?: FeedbackCandidateSummary[];
     shareSafety?: VerifyResult["shareSafety"];
     error?: {
-        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE" | "HUMANISH_INVALID_FEEDBACK_DRAFT" | "HUMANISH_FEEDBACK_SHARE_SAFETY_BLOCKED" | "HUMANISH_FEEDBACK_CANDIDATE_NOT_FOUND";
+        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE" | "HUMANISH_INVALID_FEEDBACK_DRAFT" | "HUMANISH_FEEDBACK_SHARE_SAFETY_BLOCKED" | "HUMANISH_FEEDBACK_CANDIDATE_NOT_FOUND" | "HUMANISH_FEEDBACK_REQUIRES_LIVE_RUN";
         message: string;
     };
 }

package/dist/feedback/feedback.js

@@ -1,6 +1,7 @@
 // The feedback commands: resolve a run, draft a feedback issue from it, verify the draft, render it
 // as an issue body or URL, and list a run's candidates. What a draft contains is in draft.ts.
 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";
@@ -34,7 +35,24 @@ async function draftFeedbackBound(cwdInput, runInput, options = {}) {
                 run: runInput,
                 error: {
                     code: "HUMANISH_RUN_NOT_FOUND",
-                    message: `Run not found: ${runInput}`,
+                    message: await runNotFoundMessage(cwd, runInput),
+                },
+            },
+        };
+    }
+    // A dry run exercised no product, so it has nothing to report upstream; analyze refuses it the
+    // same way (ANALYSIS_REQUIRES_LIVE_RUN).
+    if (context.loaded.bundle.mode !== "live") {
+        return {
+            context,
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                error: {
+                    code: "HUMANISH_FEEDBACK_REQUIRES_LIVE_RUN",
+                    message: `Run ${context.storedRunId} is a dry run, which tests no product behavior. Feedback drafts need a live run.`,
                 },
             },
         };
@@ -204,7 +222,7 @@ export async function listFeedback(cwdInput, runInput) {
             run: runInput,
             error: {
                 code: "HUMANISH_RUN_NOT_FOUND",
-                message: `Run not found: ${runInput}`,
+                message: await runNotFoundMessage(cwd, runInput),
             },
         };
     }
@@ -218,7 +236,7 @@ export async function listFeedback(cwdInput, runInput) {
         run: runInput,
         ...(draft ? { draftPath, draft } : {}),
         // The choice set for `draft --candidate`: a three-participant study has up to three findings,
-        // and until #609 only the first ever reached a draft.
+        // and each can reach a draft.
         candidates: summarizeCandidates(context.loaded.bundle),
     };
 }

package/dist/guest/chromium-text.js

@@ -220,7 +220,7 @@ async function probeElement(op, session, contextId, expression) {
 /**
  * Preparation: the owner check, a CDP session (recorded on the handle as soon as it exists, so
  * disposal detaches a partial acquisition), the owned top frame, an isolated world, and the
- * PREPARE probe.
+ * `PREPARE` probe.
  */
 async function acquireIsolatedWorld(settings, state, detach, prepared, op) {
     await assertOwnerReady(settings, op);
@@ -267,7 +267,7 @@ function disposePrepared(state, detach, prepared, self) {
     return prepared.disposal;
 }
 /**
- * The handle for one preparation. paste inserts the text once: owner check, RECHECK probe, owner
+ * The handle for one preparation. paste inserts the text once: owner check, `RECHECK` probe, owner
  * check, check, then insertText. close is the handle's disposal.
  */
 function preparedHandle(settings, state, prepared, dispose) {

package/dist/guest/desktop-native.d.ts

@@ -9,6 +9,6 @@ export declare function createGuestDesktopNativeTools(options: {
     display: string;
     /** An owner-created private directory inside the disposable guest. */
     temporaryDirectory: string;
-    /** Owner-created cookie file; never inherit an operator's XAUTHORITY. */
+    /** Owner-created cookie file; never inherit an operator's `XAUTHORITY`. */
     xauthority: string;
 }): GuestDesktopNativeTools;

package/dist/guest/runtime.js

@@ -105,7 +105,7 @@ export async function runGuestRuntime(options) {
             isAuthorized: () => !authority.aborted,
             ...(desktop.finishRecording ? { finishRecording: desktop.finishRecording } : {}),
         });
-        // No await in this handoff: an immediate HELLO already has its sole receiver.
+        // No await in this handoff: an immediate hello already has its sole receiver.
         options.transport.write(encodeGuestBootstrap(identity, true), (error) => {
             if (error)
                 terminal();

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-export { runPackageLab as runLab } from "./run-lab.js";
-export type { LabOutcome, LabResult, RunLabOptions } from "./run-lab.js";
-export type { LabEvent } from "./lab/run-lab-events.js";
+export { runPackageLab as runStudy } from "./run-lab.js";
+export type { LabOutcome as StudyOutcome, LabResult as StudyResult, RunLabOptions as RunStudyOptions, } from "./run-lab.js";
+export type { LabEvent as StudyEvent } from "./lab/run-lab-events.js";
 export type { ProviderContext } from "./lab/run-lab-homes.js";
 export { routeOf } from "./lab/plan.js";
-export type { LabRoute } from "./lab/plan.js";
-export { parseLabConfig } from "./lab/config.js";
-export { LAB_CONFIG_SCHEMA } from "./lab/types.js";
-export type { LabConfig } from "./lab/types.js";
+export type { LabRoute as StudyRoute } from "./lab/plan.js";
+export { parseLabConfig as parseStudy } from "./lab/config.js";
+export { STUDY_SCHEMA } from "./lab/types.js";
+export type { LabConfig as StudyConfig } from "./lab/types.js";
 export { verifyRun } from "./verify/verify.js";
 export type { VerifyResult } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
@@ -14,16 +14,18 @@ export type { ObserverResult } from "./observer/render.js";
 export type { RunBundle, RunFeedbackCandidate } from "./run/bundle.js";
 export type { ActorTrace } from "./actors/contract.js";
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";
-export type { CuaAction, CuaExecutor, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaTurn, CuaTurnRequest, } from "./actors/computer-use/loop.js";
+export type { CuaAction as ComputerUseAction, CuaExecutor as ComputerUseExecutor, CuaLoopOptions as ComputerUseLoopOptions, CuaLoopResult as ComputerUseLoopResult, CuaObservation as ComputerUseObservation, CuaProvider as ComputerUseProvider, CuaSafetyCheck as ComputerUseSafetyCheck, CuaTurn as ComputerUseTurn, CuaTurnRequest as ComputerUseTurnRequest, } from "./actors/computer-use/loop.js";
 export type { ActorCapabilities } from "./actors/contract.js";
 export { createOpenAiResponsesProvider } from "./actors/computer-use/openai-provider.js";
 export type { OpenAiResponsesProviderOptions } from "./actors/computer-use/openai-provider.js";
-export { CuaAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+export { CuaAdmissionLimitError as ComputerUseAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
 export { defaultRedactionHooks } from "./evidence/redaction.js";
 export type { RedactionHooks } from "./evidence/redaction.js";
 export type { E2BDesktopSandbox } from "./substrates/e2b/sdk.js";
 export { browserScorer, terminalScorer } from "./lab/adapter-scorer-loader.js";
 export type { AdapterScorerModule, AdapterScoringContext } from "./lab/adapter-scorer-loader.js";
-export type { BrowserLabScoringContext } from "./lab/adapter-extension.js";
+export type { BrowserLabScoringContext as BrowserScoringContext } from "./lab/adapter-extension.js";
 export type { TerminalProductScoringContext } from "./routes/terminal/types.js";
 export type { RunAdapterArtifact, RunAdapterScore } from "./run/bundle.js";
+export { CuaAdmissionLimitError, LAB_CONFIG_SCHEMA, parseLabConfig, runLab, } from "./library-aliases.js";
+export type { BrowserLabScoringContext, CuaAction, CuaExecutor, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaTurn, CuaTurnRequest, LabConfig, LabEvent, LabOutcome, LabResult, LabRoute, RunLabOptions, } from "./library-aliases.js";

package/dist/index.js

@@ -1,18 +1,20 @@
-// The library surface: what an adopter needs to run a lab, read a run, bring a participant or
+// The library surface: what an adopter needs to run a study, read a run, bring a participant or
 // score a run. Everything else is internal and reached through the `humanish` bin. See
 // docs/contracts/schemas.md, "Library options", and the site's library page.
-// Run a lab.
-export { runPackageLab as runLab } from "./run-lab.js";
+// Run a study.
+export { runPackageLab as runStudy } from "./run-lab.js";
 export { routeOf } from "./lab/plan.js";
-export { parseLabConfig } from "./lab/config.js";
-export { LAB_CONFIG_SCHEMA } from "./lab/types.js";
+export { parseLabConfig as parseStudy } from "./lab/config.js";
+export { STUDY_SCHEMA } from "./lab/types.js";
 // Read a run.
 export { verifyRun } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
 // Bring a participant.
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";
 export { createOpenAiResponsesProvider } from "./actors/computer-use/openai-provider.js";
-export { CuaAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+export { CuaAdmissionLimitError as ComputerUseAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
 export { defaultRedactionHooks } from "./evidence/redaction.js";
 // Score a run.
 export { browserScorer, terminalScorer } from "./lab/adapter-scorer-loader.js";
+// The 0.107 names, deprecated until 0.109 removes them. Each is its new name's value or type.
+export { CuaAdmissionLimitError, LAB_CONFIG_SCHEMA, parseLabConfig, runLab, } from "./library-aliases.js";

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

@@ -1,6 +1,6 @@
 export interface ResolvedKeyFill {
     name: string;
-    /** Human-readable source label (a path or command name) — never a value. */
+    /** Human-readable source label (a path or command name), never a value. */
     source: string;
 }
 export interface KeyResolutionDeps {
@@ -29,8 +29,8 @@ export interface KeySourceProbe {
     /** The command/path that would fill it when missing. */
     hint: string;
 }
-/** The nearest fill instruction for a missing key — used by doctor rows and appended to
- *  *_KEYS_MISSING errors so the failure names the fix, not just the absence (#436). */
+/** 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 declare function missingKeyHint(name: string): string;
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each
  *  missing key. Pure text; never values. */
@@ -47,10 +47,10 @@ export declare function probeKeySources(names: readonly string[], args: {
 /** Resolve a `humanish keys set` target: a vendor alias or a raw env name. Null = invalid. */
 export declare function resolveKeyName(vendorOrName: string): string | null;
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names
- *  are storable (the store feeds implicit discovery — an arbitrary-name store would be an env
+ *  are storable (the store feeds implicit discovery, so an arbitrary-name store would be an env
  *  injection vector with extra steps). The value must be a single non-empty line that
  *  round-trips the store's own parser byte-identically, and the write refuses symlinks at the
- *  file and its parent directory (red-team findings). */
+ *  file and its parent directory. */
 export declare function setUserKey(name: string, value: string, env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): {
     path: string;
 };

package/dist/keys/key-resolution.js

@@ -1,21 +1,21 @@
-// Provider-key discovery (#436): resolve the keys a live run needs through each vendor's
+// Provider-key discovery: resolve the keys a live run needs through each vendor's
 // native chain instead of demanding a per-repo --env-file that operators hand-copy keys into.
 //
-// The chain, per key, FILL-ONLY (a rung never overrides anything already present):
-//   1. process env — including whatever --env-file just loaded (explicit always wins);
-//   2. `.humanish/local/provider.env` — the project-local overlay this CLI's own --help
+// The chain, per key, fill-only (a rung never overrides anything already present):
+//   1. process env, including whatever --env-file just loaded (explicit always wins);
+//   2. `.humanish/local/provider.env`, the project-local overlay this CLI's own --help
 //      examples document;
 //   3. the owning vendor's native store, where one exists:
 //        E2B_API_KEY  <- ~/.e2b/config.json (written by `e2b auth login`);
 //        GH_TOKEN     <- `gh auth token` (the gh CLI's credential chain);
 //   4. the humanish user-level store `$XDG_CONFIG_HOME/humanish/keys.env`, written only by
-//      `humanish keys set` (0600, prompted or --stdin) — the fallback for vendors that ship
+//      `humanish keys set` (0600, prompted or --stdin), the fallback for vendors that ship
 //      no machine chain of their own (OpenAI, Anthropic).
 //
 // Every fill is announced by key name + source, never by value. The subject app's own
 // `.env`/`.env.local` are never read: those hold product credentials, a different class
-// (#11); this module only reads humanish-owned files and vendor-owned stores.
-// `HUMANISH_STRICT_KEYS=1` disables every rung below process env (the pre-#436 behavior).
+// of secret; this module only reads humanish-owned files and vendor-owned stores.
+// `HUMANISH_STRICT_KEYS=1` disables every rung below process env.
 import { spawn } from "node:child_process";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync, } from "node:fs";
 import { homedir } from "node:os";
@@ -24,7 +24,7 @@ import { loadEnvFile } from "./env-file.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
- *  --env-file remains the operator's own full-file load). Red-team finding, #436. */
+ *  --env-file remains the operator's own full-file load). */
 const KNOWN_PROVIDER_KEYS = [
     "OPENAI_API_KEY",
     "ANTHROPIC_API_KEY",
@@ -52,7 +52,7 @@ export function userKeyStorePath(env, deps = {}) {
     const home = deps.homeDir ?? homedir();
     const declared = env.XDG_CONFIG_HOME?.trim();
     // The XDG spec: a relative XDG_CONFIG_HOME must be ignored. Honoring one would make the
-    // key store cwd-relative — `humanish keys set` would write a secret into the current repo.
+    // key store cwd-relative: `humanish keys set` would write a secret into the current repo.
     const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
         ? declared
         : path.join(home, ".config");
@@ -151,16 +151,16 @@ export async function discoverProviderKeys(args) {
     const fills = [];
     const ignored = [];
     // Fill-only means presence wins, including an explicitly-set empty value: an operator who
-    // exported OPENAI_API_KEY="" said "off", and a rung that "fixes" that has overridden them
-    // (red-team finding). Only a truly-unset name is fillable.
+    // exported OPENAI_API_KEY="" said "off", and a rung that "fixes" that has overridden them.
+    // Only a truly-unset name is fillable.
     const fillable = (name) => env[name] === undefined;
     const fill = (name, value, source) => {
         env[name] = value;
         fills.push({ name, source });
     };
     // Rung 2: the documented project-local overlay. Parsed atomically against a scratch env so a
-    // file loadEnvFile rejects can never half-apply (red-team finding: earlier lines used to land
-    // in env unannounced before the parse error aborted). Only allowlisted provider names cross
+    // file loadEnvFile rejects can never half-apply: otherwise lines before the parse error would
+    // land in env unannounced. Only allowlisted provider names cross
     // from the file into the real env.
     const overlayPath = path.resolve(cwd, PROJECT_OVERLAY_RELATIVE);
     if (isRegularFile(overlayPath) && !dirIsSymlink(overlayPath)) {
@@ -196,7 +196,7 @@ export async function discoverProviderKeys(args) {
     }
     // Rung 4: the humanish user-level store, read with the same lenient parser `keys set`/`list`
     // use, so one hand-mangled line degrades to that line alone instead of silently voiding the
-    // whole store (red-team finding: the strict parser disagreed with the store's own reader).
+    // whole store, as the strict parser would.
     const storePath = userKeyStorePath(env, deps);
     if (isRegularFile(storePath) && !dirIsSymlink(storePath)) {
         for (const [name, value] of readStoreEntries(storePath)) {
@@ -213,11 +213,11 @@ export async function discoverProviderKeys(args) {
         if (announced === undefined || announced.has(fill_.name))
             announce(`humanish keys: ${fill_.name} from ${fill_.source}`);
     for (const name of ignored)
-        announce(`humanish keys: ignored non-provider name ${name} — implicit discovery fills provider keys only; pass the file via --env-file to load everything in it`);
+        announce(`humanish keys: ignored ${name}, which is not a provider key. Discovery loads provider keys only; pass the file with --env-file to load every name in it.`);
     return fills;
 }
 /** True when the file's parent directory is (or traverses) a symlink at its last component:
- *  the dir-level retarget that defeats a file-level lstat check (red-team finding). */
+ *  the dir-level retarget that defeats a file-level lstat check. */
 function dirIsSymlink(filePath) {
     try {
         return lstatSync(path.dirname(filePath)).isSymbolicLink();
@@ -230,8 +230,8 @@ function storeLabel(env, deps) {
     const home = deps.homeDir ?? homedir();
     return userKeyStorePath(env, deps).replace(home, "~");
 }
-/** The nearest fill instruction for a missing key — used by doctor rows and appended to
- *  *_KEYS_MISSING errors so the failure names the fix, not just the absence (#436). */
+/** 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":
@@ -273,7 +273,7 @@ export async function probeKeySources(names, args) {
     return names.map((name) => {
         const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "";
         // 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 (red-team nit).
+        // "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() !== "";
@@ -294,10 +294,10 @@ export function resolveKeyName(vendorOrName) {
     return ENV_NAME.test(vendorOrName) ? vendorOrName : null;
 }
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names
- *  are storable (the store feeds implicit discovery — an arbitrary-name store would be an env
+ *  are storable (the store feeds implicit discovery, so an arbitrary-name store would be an env
  *  injection vector with extra steps). The value must be a single non-empty line that
  *  round-trips the store's own parser byte-identically, and the write refuses symlinks at the
- *  file and its parent directory (red-team findings). */
+ *  file and its parent directory. */
 export function setUserKey(name, value, env, deps = {}) {
     const trimmed = value.trim();
     if (trimmed.length === 0 || /[\u0000-\u001f\u007f]/.test(trimmed)) {
@@ -363,8 +363,8 @@ function readStoreEntries(storePath) {
 function writeStore(storePath, entries) {
     const body = [...entries.entries()].map(([name, value]) => `${name}=${value}`).join("\n");
     const text = body.length > 0 ? `${body}\n` : "";
-    // O_NOFOLLOW: a symlinked keys.env must never carry the write to its target (red-team
-    // reproduced writing a secret through the link into an attacker-chosen file).
+    // O_NOFOLLOW: a symlinked keys.env must never carry the write to its target, which would put a
+    // secret into an attacker-chosen file.
     const fd = openSync(storePath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_NOFOLLOW, 0o600);
     try {
         ftruncateSync(fd, 0);