humanish 0.111.4 → 0.113.0

package/dist/cli/secret-prompt.js

@@ -1,6 +1,10 @@
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
-/** Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal. */
+/**
+ * Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal.
+ * Resolves to the trimmed line, an empty string when Enter was pressed alone, or null when the
+ * person cancelled or there is no terminal.
+ */
 export async function promptSecret(label, stdin, stdout) {
     if (!stdin.isTTY || !stdout.isTTY)
         return null;
@@ -27,7 +31,7 @@ export async function promptSecret(label, stdin, stdout) {
             stdout.write("\n");
             resolve(value);
         };
-        reader.once("line", (line) => finish(line.trim() || null));
+        reader.once("line", (line) => finish(line.trim()));
         reader.once("SIGINT", () => finish(null));
         reader.once("close", () => finish(null));
         reader.once("error", () => finish(null));

package/dist/cli/update-check-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/update-check-worker.js

@@ -0,0 +1,5 @@
+// Started detached by startRefreshWorker in update-check.ts, with the cache path as its argument.
+import { refreshUpdateCache } from "./update-check.js";
+const cachePath = process.argv[2];
+if (cachePath !== undefined)
+    await refreshUpdateCache({ cachePath });

package/dist/cli/update-check.d.ts

@@ -0,0 +1,46 @@
+export interface UpdateCheckContext {
+    /** The running CLI's version. */
+    installed: string;
+    env: NodeJS.ProcessEnv;
+    /** Whether stderr is a terminal. */
+    terminal: boolean;
+    /** Whether the command prints a JSON document. */
+    json: boolean;
+    /** Whether this CLI runs from humanish's own source checkout. */
+    ownCheckout: boolean;
+    /** The clock, in epoch milliseconds. */
+    now: number;
+    home?: string;
+    /** Starts the background registry request that writes the cache. Never awaited. */
+    startRefresh: (cachePath: string) => void;
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export declare function checkForUpdate(context: UpdateCheckContext): string | undefined;
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export declare function recordedVersion(installed: string, env: NodeJS.ProcessEnv, home?: string): {
+    newer: boolean;
+    message: string;
+} | undefined;
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export declare function refreshUpdateCache(args: {
+    cachePath: string;
+    fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
+    now?: () => number;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export declare function startRefreshWorker(cachePath: string): void;

package/dist/cli/update-check.js

@@ -0,0 +1,203 @@
+// Tells a person when a newer humanish is published, as npm, gh and the Vercel CLI do. A command
+// only reads a small cache and prints at most one line from it; the registry request runs in a
+// detached process that writes the cache for a later command, so the check never delays or fails
+// the command that started it.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { disabledByEnvironment } from "./telemetry.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_DIST_TAGS = "https://registry.npmjs.org/-/package/humanish/dist-tags";
+/** Next to telemetry.json, under the same XDG rule the key store uses. */
+function updateCachePath(env, home = homedir()) {
+    const declared = env.XDG_CONFIG_HOME?.trim();
+    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
+        ? declared
+        : path.join(home, ".config");
+    return path.join(configHome, "humanish", "update-check.json");
+}
+function readUpdateCache(cachePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return {};
+        const record = parsed;
+        const text = (field) => typeof record[field] === "string" ? record[field] : undefined;
+        const cache = {};
+        const checkedAt = text("checkedAt");
+        const latest = text("latest");
+        const notifiedAt = text("notifiedAt");
+        if (checkedAt !== undefined)
+            cache.checkedAt = checkedAt;
+        if (latest !== undefined && parseVersion(latest) !== undefined)
+            cache.latest = latest;
+        if (notifiedAt !== undefined)
+            cache.notifiedAt = notifiedAt;
+        return cache;
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateCache(cachePath, cache) {
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `candidate` is a higher release than `installed`. */
+function isNewer(candidate, installed) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(installed);
+    if (a === undefined || b === undefined)
+        return false;
+    for (let index = 0; index < 3; index += 1)
+        if (a[index] !== b[index])
+            return a[index] > b[index];
+    return false;
+}
+/** True when `timestamp` is missing, unreadable, or at least a day before `now`. */
+function dayPassed(timestamp, now) {
+    const then = timestamp === undefined ? Number.NaN : Date.parse(timestamp);
+    return Number.isNaN(then) || now - then >= DAY_MS;
+}
+const truthy = (value) => value !== undefined &&
+    value.trim() !== "" &&
+    value.trim() !== "0" &&
+    value.trim().toLowerCase() !== "false";
+/**
+ * Only a person at a terminal is told, and only when nothing has switched the check off. A pipe,
+ * CI and a JSON document have a program reading them. A study participant runs the version the
+ * study chose, and a notice would send it to another. The telemetry switches turn this off too:
+ * someone who opted out of telemetry expects no unprompted requests.
+ */
+function checkAllowed(context) {
+    const env = context.env;
+    return (context.terminal &&
+        !context.json &&
+        !context.ownCheckout &&
+        !truthy(env.CI) &&
+        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
+        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !disabledByEnvironment(env));
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export function checkForUpdate(context) {
+    try {
+        if (!checkAllowed(context))
+            return undefined;
+        const cachePath = updateCachePath(context.env, context.home);
+        const cache = readUpdateCache(cachePath);
+        const stamp = new Date(context.now).toISOString();
+        const next = { ...cache };
+        // Stamped before the request starts, so an offline machine asks once a day rather than on
+        // every command. The request writes `latest` when it succeeds.
+        const refresh = dayPassed(cache.checkedAt, context.now);
+        if (refresh)
+            next.checkedAt = stamp;
+        const latest = cache.latest;
+        const notice = latest !== undefined &&
+            isNewer(latest, context.installed) &&
+            dayPassed(cache.notifiedAt, context.now)
+            ? `humanish ${context.installed} is out of date; the latest is ${latest}. Run npx humanish@latest to use it.`
+            : undefined;
+        if (notice !== undefined)
+            next.notifiedAt = stamp;
+        if (refresh || notice !== undefined)
+            writeUpdateCache(cachePath, next);
+        if (refresh)
+            context.startRefresh(cachePath);
+        return notice;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export function recordedVersion(installed, env, home) {
+    const cache = readUpdateCache(updateCachePath(env, home));
+    if (cache.latest === undefined)
+        return undefined;
+    const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;
+    return isNewer(cache.latest, installed)
+        ? {
+            newer: true,
+            message: `${installed} installed; ${cache.latest} is the latest${checked}. Run npx humanish@latest to use it.`,
+        }
+        : { newer: false, message: `${installed} installed, the latest published${checked}` };
+}
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export async function refreshUpdateCache(args) {
+    try {
+        const fetchFn = args.fetchFn ?? globalThis.fetch;
+        const response = await fetchFn(REGISTRY_DIST_TAGS, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(args.timeoutMs ?? 3_000),
+        });
+        if (!response.ok)
+            return;
+        const body = await response.json();
+        const latest = body !== null && typeof body === "object"
+            ? body.latest
+            : undefined;
+        if (typeof latest !== "string" || parseVersion(latest) === undefined)
+            return;
+        const now = (args.now ?? Date.now)();
+        writeUpdateCache(args.cachePath, {
+            ...readUpdateCache(args.cachePath),
+            checkedAt: new Date(now).toISOString(),
+            latest,
+        });
+    }
+    catch {
+        // Offline, slow or refused: the next check is a day away either way.
+    }
+}
+/** What the worker's environment keeps: how this machine reaches the network, and no credentials. */
+const WORKER_ENV_NAMES = [
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+    "NODE_USE_ENV_PROXY",
+    "NODE_EXTRA_CA_CERTS",
+    "SYSTEMROOT",
+];
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export function startRefreshWorker(cachePath) {
+    const worker = fileURLToPath(new URL("./update-check-worker.js", import.meta.url));
+    if (!existsSync(worker))
+        return;
+    const env = Object.fromEntries(WORKER_ENV_NAMES.flatMap((name) => {
+        const value = process.env[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+    const child = spawn(process.execPath, [worker, cachePath], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env,
+    });
+    child.on("error", () => { });
+    child.unref();
+}

package/dist/feedback/draft.js

@@ -120,7 +120,8 @@ export async function buildAnalysisDraft(context, options) {
     const root = path.dirname(context.loaded.bundlePath);
     const evidenceIds = new Set(finding.observations.flatMap((item) => item.evidenceIds));
     const evidence = analysis.evidence.filter((item) => evidenceIds.has(item.id));
-    const claim = correction?.status === "amended" ? correction.replacementClaim : finding.title;
+    const amended = correction?.status === "amended";
+    const claim = amended ? correction.replacementClaim : (finding.headline ?? finding.title);
     const firstLine = claim.trim().split(/\r?\n/)[0] || `Reviewed finding ${finding.id}`;
     const summary = Array.from(firstLine).length > 160
         ? Array.from(firstLine).slice(0, 159).join("") + "…"
@@ -144,13 +145,23 @@ export async function buildAnalysisDraft(context, options) {
         summary,
         expected: "Review the cited behavior against the participant assignment and confirm the expected product behavior.",
         actual: [
+            // The plain account leads; an amendment makes it stale, so the draft says so in its place.
+            ...(finding.headline === undefined
+                ? []
+                : amended
+                    ? [
+                        "This finding was corrected in human review. The reviewer's claim above replaces its original headline and account.",
+                        "",
+                    ]
+                    : finding.experience === undefined
+                        ? []
+                        : [finding.experience, ""]),
             "Independent study analysis; does not replace participant feedback or recorded completion outcomes.",
-            correction?.status === "amended"
-                ? `Amended claim: ${claim}. Original analysis: ${finding.summary}`
-                : finding.summary,
+            amended ? `Amended claim: ${claim}. Original analysis: ${finding.summary}` : finding.summary,
             `Impact: ${finding.impact}. ${finding.affectedStreamIds.length} affected / ${finding.exposedStreamIds.length} observed exposed participants. ${finding.exposureReason}`,
             `Recovery: ${finding.recovery}. Confidence: ${finding.confidence}.`,
             ...finding.observations.map((item) => `${item.basis}: ${item.claim}${item.limitation ? ` Limitation: ${item.limitation}` : ""}`),
+            ...citedImpressions(bundle, evidence).map(({ streamId, kind, text }) => `Participant ${streamId} said at the end (${kind.replaceAll("_", " ")}): ${text}`),
             `Next check: ${finding.nextStep}`,
             correction
                 ? `Human review: ${correction.status}. ${correction.reason}`
@@ -196,6 +207,23 @@ export async function buildAnalysisDraft(context, options) {
         ],
     };
 }
+/**
+ * The participant impressions among a finding's cited evidence. Only an impression whose text the
+ * cited entry carries whole is quoted, so the draft repeats nothing the analysis share check did
+ * not read.
+ */
+function citedImpressions(bundle, evidence) {
+    return evidence.flatMap((item) => {
+        const impressions = bundle.streams.find((stream) => stream.id === item.streamId)?.actor
+            ?.impressions;
+        const impression = impressions?.status === "collected"
+            ? impressions.items.find((entry) => entry.messageId === item.eventId)
+            : undefined;
+        return impression === undefined || !item.text.includes(impression.text)
+            ? []
+            : [{ streamId: item.streamId, kind: impression.kind, text: impression.text }];
+    });
+}
 export function isUsableFeedbackCandidate(candidate) {
     if (!isRecord(candidate) ||
         candidate.schema !== "humanish.feedback-candidate.v1" ||

package/dist/keys/key-resolution.js

@@ -245,6 +245,8 @@ export function missingKeyHint(name) {
             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}`)}\``;
     }

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

@@ -0,0 +1,37 @@
+import { type KeyResolutionDeps, type KeySourceProbe } from "./key-resolution.js";
+interface KeyStatusRow extends KeySourceProbe {
+    /** What humanish uses the key for, in a few words. */
+    use: string;
+}
+export declare function keyStatus(args: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+}): Promise<KeyStatusRow[]>;
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export declare function otherStoredKeys(env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): string[];
+export declare function formatKeyStatus(rows: readonly KeyStatusRow[], otherStored?: readonly string[]): string;
+interface MissingKeysOutcome {
+    stored: string[];
+    /** Keys left unset because the person pressed Enter without a value. */
+    skipped: string[];
+    /** Keys whose value the store refused, with the reason. */
+    rejected?: Array<{
+        name: string;
+        message: string;
+    }>;
+    /** The key whose prompt was cancelled. No later key was asked for. */
+    stoppedAt?: string;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export declare function askForMissingKeys(args: {
+    rows: readonly KeyStatusRow[];
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+    prompt: (label: string) => Promise<string | null>;
+}): Promise<MissingKeysOutcome>;
+export {};

package/dist/keys/key-status.js

@@ -0,0 +1,68 @@
+// `humanish keys`: which provider keys are set and where each comes from, through the same chain a
+// live command resolves. Never a value.
+import { cli } from "../cli/invocation.js";
+import { listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
+/**
+ * The keys a person sets for humanish, in the order the status lists them and `keys set` asks for
+ * them. ANTHROPIC_API_KEY is left out: 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.
+ */
+const STATUS_KEYS = [
+    { name: "E2B_API_KEY", use: "hosted desktops" },
+    { name: "OPENAI_API_KEY", use: "participant model and analysis" },
+    { name: "GH_TOKEN", use: "private repository subjects" },
+    { name: "AGENTMAIL_API_KEY", use: "email in studies" },
+];
+export async function keyStatus(args) {
+    const probes = await probeKeySources(STATUS_KEYS.map((key) => key.name), {
+        cwd: args.cwd,
+        env: args.env,
+        ...(args.deps === undefined ? {} : { deps: args.deps }),
+    });
+    return probes.map((probe, index) => ({ ...probe, use: STATUS_KEYS[index].use }));
+}
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export function otherStoredKeys(env, deps = {}) {
+    const listed = new Set(STATUS_KEYS.map((key) => key.name));
+    return listUserKeys(env, deps).filter((name) => !listed.has(name));
+}
+export function formatKeyStatus(rows, otherStored = []) {
+    const lines = rows.map((row) => `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`);
+    if (otherStored.length > 0)
+        lines.push(`Also in the user store: ${otherStored.join(", ")}. humanish does not use ${otherStored.length === 1 ? "it" : "them"} today.`);
+    const missing = rows.some((row) => row.source === null);
+    lines.push("", missing
+        ? `Values are never printed. \`${cli("keys set")}\` asks for each missing key in turn.`
+        : "Values are never printed.");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export async function askForMissingKeys(args) {
+    const outcome = { stored: [], skipped: [] };
+    for (const row of args.rows) {
+        if (row.source !== null)
+            continue;
+        const value = await args.prompt(`${row.name} for ${row.use}`);
+        if (value === null)
+            return { ...outcome, stoppedAt: row.name };
+        if (value === "") {
+            outcome.skipped.push(row.name);
+            continue;
+        }
+        try {
+            setUserKey(row.name, value, args.env, args.deps);
+            outcome.stored.push(row.name);
+        }
+        catch (error) {
+            (outcome.rejected ??= []).push({
+                name: row.name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return outcome;
+}

package/dist/observer/run-routes.js

@@ -8,6 +8,7 @@ import { isLocalOnlyRunFile, isLocalOnlyRunFileIdentity } from "../run/local-onl
 import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
+import { isRunOutcome } from "../run/bundle-shape.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
@@ -138,7 +139,7 @@ async function readObserverData(runRoot, runtimeStreamUrls = []) {
         if (!bundleBytes)
             throw new Error("run.json unavailable");
         const bundle = JSON.parse(bundleBytes.toString("utf8"));
-        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record)), runtimeStreamUrls);
+        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
     }
     catch { }
     try {
@@ -166,12 +167,12 @@ async function readLocalRunStatus(runRoot) {
     }
 }
 /**
- * Liveness is a current read of a contained local status record, separate from run evidence.
+ * A recorded bundle outcome wins; otherwise runtime status reads the contained local heartbeat.
  * A stale heartbeat means unknown: neither an old timestamp nor a persisted PID proves that a
  * process died (the evidence may have been copied from another machine). A record its stopped
  * process wrote is interrupted. No PID is served/probed.
  */
-function withLocalRunStatus(record, input) {
+function withLocalRunStatus(record, input, outcome) {
     // A served observation must never be inherited from a persisted projection or export.
     const { runtime: _persistedRuntime, ...data } = input;
     if (record === undefined || record.runId !== data.run.runId || record.mode !== data.run.mode)
@@ -181,7 +182,10 @@ function withLocalRunStatus(record, input) {
     const updated = Date.parse(record.updatedAt);
     const timestampsValid = Number.isFinite(started) && Number.isFinite(updated) && started <= updated && updated <= now;
     let state = "unknown";
-    if (timestampsValid) {
+    if (isRunOutcome(outcome)) {
+        state = outcome.state;
+    }
+    else if (timestampsValid) {
         if (record.state === "finished") {
             state = "finished";
         }