humanish 0.106.1 → 0.108.0

package/dist/feedback/export.js

@@ -1,9 +1,9 @@
-// `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
 // run's data inlined; what keeps it from travelling is the screenshots it references by path.
-// Export embeds each unique raster once and writes ONE .html that opens offline.
+// Export embeds each unique raster once and writes one .html that opens offline.
 //
 // Share safety is the point, not a step: export runs verify inside the flow and refuses a bundle
 // that is not share_ready. A local_only bundle (raw screenshots) exports only with an explicit
@@ -18,10 +18,10 @@ import { resolveRunPath } from "../run/locate.js";
 import { verifyRun } from "../verify/verify.js";
 import {} from "../run/bundle.js";
 import { exportRedactedBundle } from "./export-bundle.js";
-import { loadStudyAnalysis } from "../analysis/load.js";
-import { studyAnalysisSharingProblems } from "../analysis/sharing.js";
+import { loadAnalysis } from "../analysis/load.js";
+import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
-import { readBoundedStudyFile } from "../run/study-files.js";
+import { readBoundedFile } from "../run/evidence-files.js";
 import { shellQuote } from "../substrates/shell.js";
 const EXPORT_SCHEMA = "humanish.export-result.v1";
 /** Past this the file stops being a thing you attach to an email. Declared, never silent. */
@@ -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) {
@@ -73,7 +73,7 @@ export async function exportRun(cwdInput, runInput, options = {}, deps = {}) {
         return slot;
     // Every string in the data that names an image file inside the run becomes an asset reference. Paths are
     // run-root-relative in the data; a path that resolves outside the run is left alone, never read.
-    const analysis = await loadStudyAnalysis(runPaths);
+    const analysis = await loadAnalysis(runPaths);
     const data = await currentObserverData(runPaths, analysis, slot);
     if (data === undefined)
         return exportFailure(cwd, runInput, "HUMANISH_EXPORT_VERIFY_FAILED", "Source evidence changed while preparing the analysis export.");
@@ -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)
@@ -175,7 +174,7 @@ async function currentObserverData(runPaths, analysis, slot) {
     const saved = JSON.parse(slot);
     if (analysis.state !== "ready" || !analysis.analysis)
         return { value: saved };
-    const source = await readBoundedStudyFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
+    const source = await readBoundedFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
     if (!source ||
         createHash("sha256").update(source).digest("hex") !== analysis.analysis.sourceRunSha256)
         return undefined;
@@ -211,7 +210,7 @@ async function inlineImages(runPaths, runRoot, data, analysis, options, warnings
         for (const candidate of candidates) {
             if (!(await isInside(runRoot, candidate)))
                 continue;
-            const bytes = await readBoundedStudyFile(runPaths, path.relative(runRoot, candidate), options.maxBytes ?? DEFAULT_EXPORT_MAX_BYTES);
+            const bytes = await readBoundedFile(runPaths, path.relative(runRoot, candidate), options.maxBytes ?? DEFAULT_EXPORT_MAX_BYTES);
             if (bytes === null)
                 continue;
             if (bytes.byteLength > MAX_PORTABLE_IMAGE_BYTES) {
@@ -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,
@@ -302,7 +301,7 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
     // Revalidate the independent interpretation against source evidence. Never trust a
     // saved HTML slot or traverse model-provided strings as image paths.
     if (analysis.state === "ready" && analysis.analysis) {
-        const source = await readBoundedStudyFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
+        const source = await readBoundedFile(runPaths, "run.json", EVIDENCE_LIMITS.sourceBytes);
         try {
             if (!source)
                 throw new Error("source unavailable");
@@ -312,7 +311,7 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
             return "changed";
         }
     }
-    const analysisSharing = studyAnalysisSharingProblems(analysis);
+    const analysisSharing = analysisSharingProblems(analysis);
     if (!analysisSharing.sensitive && !analysisSharing.unverified)
         return "ok";
     verified.shareSafety = {
@@ -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

@@ -12,12 +12,12 @@ export interface FeedbackResult {
     issueMarkdown?: string;
     issueUrl?: string;
     draft?: FeedbackDraft;
-    /** Every usable candidate on the bundle, so a multi-lane study's second and third findings can be
-     *  chosen with `--candidate` instead of being invisible behind the first (#609). */
+    /** 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. */
     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 { runLab } from "./run-lab.js";
-export type { LabOutcome, LabResult, RunLabOptions } from "./run-lab.js";
-export type { LabEvent } from "./lab/run-lab-events.js";
-export type { ProviderContext } from "./lab/run-lab-options.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,19 +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 { routesToComputerUse, routesToConcurrentSharedWorld, routesToExternalPublicSharedWorld, routesToProvisionedSharedWorld, routesToScriptedBrowser, routesToSharedWorld, routesToTerminalProduct, } from "./lab/routing.js";
-export { selectLabBackend } from "./lab/plan.js";
-export { actorResolvesToTerminal, concurrentSharedWorldValidationReason, cuaLaneCount, cuaLaneValidationReason, externalPublicSharedWorldValidationReason, MAX_CUA_LANES, resolveLabDryRun, resolveSeatUrl, runConcurrentSharedWorld, runCuaActorLab, runCuaActorSession, runDryRun, runScriptedBrowserLab, runTerminalProductLab, sharedWorldValidationReason, } from "./deprecated.js";
-export type { AutomaticAnalysisHooks, BrowserLabAdapterHooks, ConcurrentSharedWorldLabResult, CuaActorLabHooks, CuaActorLabResult, LabBackend, RunConcurrentSharedWorldLabOptions, RunCuaActorLabOptions, RunOptions, RunResult, RunScriptedBrowserLabOptions, RunTerminalProductLabOptions, ScriptedBrowserLabHooks, ScriptedBrowserLabResult, SharedWorldLabHooks, SubjectPhaseEvent, TerminalProductLabHooks, TerminalProductLabResult, } from "./deprecated.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,21 +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 { 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";
-// Routing: the planLab series deprecates these and removes them in the next minor.
-export { routesToComputerUse, routesToConcurrentSharedWorld, routesToExternalPublicSharedWorld, routesToProvisionedSharedWorld, routesToScriptedBrowser, routesToSharedWorld, routesToTerminalProduct, } from "./lab/routing.js";
-export { selectLabBackend } from "./lab/plan.js";
-// Deprecated this minor, removed in the next.
-export { actorResolvesToTerminal, concurrentSharedWorldValidationReason, cuaLaneCount, cuaLaneValidationReason, externalPublicSharedWorldValidationReason, MAX_CUA_LANES, resolveLabDryRun, resolveSeatUrl, runConcurrentSharedWorld, runCuaActorLab, runCuaActorSession, runDryRun, runScriptedBrowserLab, runTerminalProductLab, sharedWorldValidationReason, } from "./deprecated.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 {
@@ -13,12 +13,14 @@ export declare function userKeyStorePath(env: NodeJS.ProcessEnv, deps?: KeyResol
 /**
  * Fill missing provider keys into `env` from the discovery chain, announcing each fill as
  * `NAME from SOURCE`. Returns the fills. Opt-out: HUMANISH_STRICT_KEYS=1 returns [] untouched.
+ * With `announced`, every key is still filled, and only the fills it names are announced.
  */
 export declare function discoverProviderKeys(args: {
     cwd: string;
     env: NodeJS.ProcessEnv;
     announce: (line: string) => void;
     deps?: KeyResolutionDeps;
+    announced?: ReadonlySet<string>;
 }): Promise<ResolvedKeyFill[]>;
 export interface KeySourceProbe {
     name: string;
@@ -27,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. */
@@ -45,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,30 +1,30 @@
-// 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:
+//   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).
+// 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
+// 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";
 import path from "node:path";
 import { loadEnvFile } from "./env-file.js";
-/** The ONLY names implicit discovery may fill (and `humanish keys set` may store). Everything
+/** 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",
@@ -51,8 +51,8 @@ const PROJECT_OVERLAY_RELATIVE = path.join(".humanish", "local", "provider.env")
 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.
+    // 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.
     const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
         ? declared
         : path.join(home, ".config");
@@ -61,7 +61,7 @@ export function userKeyStorePath(env, deps = {}) {
 function e2bConfigPath(deps) {
     return path.join(deps.homeDir ?? homedir(), ".e2b", "config.json");
 }
-/** Default exec: bounded, quiet, stdin closed; null on ANY failure. Never throws. */
+/** Default exec: bounded, quiet, stdin closed; null on any failure. Never throws. */
 function defaultExecText(command, args, timeoutMs, env) {
     return new Promise((resolve) => {
         let child;
@@ -128,7 +128,7 @@ function readE2bConfigKey(deps) {
         return null;
     }
 }
-/** Refuse to READ a store through a symlink: a repo-local overlay that is secretly a link to
+/** Refuse to read a store through a symlink: a repo-local overlay that is secretly a link to
  *  an unrelated file is exactly the retargeting shape the artifact paths refuse elsewhere. */
 function isRegularFile(filePath) {
     try {
@@ -141,25 +141,26 @@ function isRegularFile(filePath) {
 /**
  * Fill missing provider keys into `env` from the discovery chain, announcing each fill as
  * `NAME from SOURCE`. Returns the fills. Opt-out: HUMANISH_STRICT_KEYS=1 returns [] untouched.
+ * With `announced`, every key is still filled, and only the fills it names are announced.
  */
 export async function discoverProviderKeys(args) {
-    const { cwd, env, announce } = args;
+    const { cwd, env, announce, announced } = args;
     const deps = args.deps ?? {};
     if (env.HUMANISH_STRICT_KEYS?.trim() === "1")
         return [];
     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.
+    // 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.
+    // 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
+    // Rung 2: the documented project-local overlay. Parsed atomically against a scratch env so a
+    // 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)) {
@@ -184,7 +185,7 @@ export async function discoverProviderKeys(args) {
         if (teamKey !== null)
             fill("E2B_API_KEY", teamKey, "~/.e2b/config.json (e2b auth login)");
     }
-    // Rung 3b: the gh CLI's credential chain. Only consulted when NEITHER GitHub env name is
+    // Rung 3b: the gh CLI's credential chain. Only consulted when neither GitHub env name is
     // present; fills GH_TOKEN (the name humanish reads first). gh runs without any provider key in
     // its environment, so the keys the rungs above just filled stay in this process.
     if (fillable("GH_TOKEN") && fillable("GITHUB_TOKEN")) {
@@ -193,9 +194,9 @@ export async function discoverProviderKeys(args) {
         if (token !== null)
             fill("GH_TOKEN", token, "gh auth token");
     }
-    // Rung 4: the humanish user-level store — read with the SAME lenient parser `keys set`/`list`
+    // 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)) {
@@ -209,13 +210,14 @@ export async function discoverProviderKeys(args) {
         }
     }
     for (const fill_ of fills)
-        announce(`humanish keys: ${fill_.name} from ${fill_.source}`);
+        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). */
+/** 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. */
 function dirIsSymlink(filePath) {
     try {
         return lstatSync(path.dirname(filePath)).isSymbolicLink();
@@ -228,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":
@@ -271,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() !== "";
@@ -292,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)) {
@@ -320,7 +322,7 @@ export function setUserKey(name, value, env, deps = {}) {
     entries.set(name, trimmed);
     // The written line must read back byte-identically through the store's own parser: a value
     // that parses differently (an embedded '#', a leading quote the env parser would strip)
-    // would silently resolve to a DIFFERENT secret on the next run.
+    // would silently resolve to a different secret on the next run.
     const roundTrip = parseStoreLine(`${name}=${trimmed}`);
     if (roundTrip === null || roundTrip[0] !== name || roundTrip[1] !== trimmed) {
         throw new Error("The value does not round-trip the store format (avoid leading quotes and '#'); pass it via --env-file instead.");
@@ -361,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);