humanish 0.114.0 → 0.115.0

package/dist/actors/contract.d.ts

@@ -1,8 +1,10 @@
 import type { AffordanceUse } from "./affordance.js";
 import type { ActorEstimatedCost } from "../run/pricing.js";
 import type { TaskFunnel } from "../study/tasks.js";
+import type { ParticipantClosingReport, ParticipantImpression } from "./closing-report.js";
 import { type CuaProviderFailurePhase } from "./computer-use/provider-error.js";
 export declare const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
+export type { ParticipantClosingReport, ParticipantImpression } from "./closing-report.js";
 /**
  * How a session ended, from the point of view of the study rather than the harness.
  *
@@ -182,25 +184,6 @@ export interface ActorProviderRequest extends ProviderRequestReceipt {
 export declare function validActorExecutionProfile(value: unknown): value is ActorExecutionProfile;
 /** Closed per-attempt evidence; dollar amounts are never part of account usage. */
 export declare function validActorProviderRequests(value: unknown): value is ActorProviderRequest[];
-/** The participant's account, not an independently confirmed product diagnosis. */
-export interface ParticipantClosingReport {
-    summary: string;
-    frictionReports: string[];
-    /** Absent when the provider did not ask for impressions; empty when the participant had none. */
-    impressions?: ParticipantImpression[];
-}
-/**
- * What a participant can say about the product at the end of a session, beyond friction.
- * `unlike_my_work` compares the screen with how the persona does the same task in its own work or
- * life.
- */
-export declare const PARTICIPANT_IMPRESSION_KINDS: readonly ["unclear", "unfinished", "untrustworthy", "liked", "missing", "unlike_my_work"];
-type ParticipantImpressionKind = (typeof PARTICIPANT_IMPRESSION_KINDS)[number];
-/** One first-person impression about something the participant saw in the session. */
-export interface ParticipantImpression {
-    kind: ParticipantImpressionKind;
-    text: string;
-}
 /** An impression as the trace keeps it, with the message that quotes it. */
 interface RecordedImpression extends ParticipantImpression {
     /** The trace message carrying the impression, which the analysis quotes and cites. */
@@ -399,4 +382,3 @@ export interface ActorSessionResult {
 export declare const CODEX_APP_SERVER_CAPABILITIES: ActorCapabilities;
 export declare const SCRIPTED_BROWSER_CAPABILITIES: ActorCapabilities;
 export declare const TERMINAL_AGENT_CAPABILITIES: ActorCapabilities;
-export {};

package/dist/actors/contract.js

@@ -168,19 +168,6 @@ export function validActorProviderRequests(value) {
                     usage.input));
     });
 }
-/**
- * What a participant can say about the product at the end of a session, beyond friction.
- * `unlike_my_work` compares the screen with how the persona does the same task in its own work or
- * life.
- */
-export const PARTICIPANT_IMPRESSION_KINDS = [
-    "unclear",
-    "unfinished",
-    "untrustworthy",
-    "liked",
-    "missing",
-    "unlike_my_work",
-];
 export const CODEX_APP_SERVER_CAPABILITIES = {
     headless: true,
     structuredTrace: true,

package/dist/analysis/admission.d.ts

@@ -24,10 +24,20 @@ export interface RefusedAnalysisCost {
     worstCaseCostUsd: number;
     maxCostUsd: number;
 }
-/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
-export declare function admittingMaxCost(cost: RefusedAnalysisCost): number;
-/** Why admission refused an analysis, in plain words. */
-export declare function costRefusalText(cost: RefusedAnalysisCost): string;
+/** A cost refusal in plain words, and the command that runs the analysis under a cap that admits it. */
+export interface CostRefusal {
+    /** The costs, the cap and that no request was sent, ending in the lead-in to `command`. */
+    text: string;
+    /** `analyze` with `--max-cost` at the worst case rounded up to a whole dollar, at least 1. */
+    command: string;
+}
+/**
+ * Words a cost refusal. `runFlags` are the `analyze` flags that select the run, such as
+ * `--run <id>`. `cli` prefixes a humanish command: the CLI passes `cli` from
+ * src/cli/invocation.ts, and the Observer, which cannot read the install, a bare `humanish`.
+ * This module keeps only type imports, so the Observer can bundle it.
+ */
+export declare function costRefusal(cost: RefusedAnalysisCost, runFlags: string, cli: (rest: string) => string): CostRefusal;
 /** The admission's refused cost, when it refused the analysis for its cost. */
 export declare function refusedCost(admission: {
     error: string | null;

package/dist/analysis/admission.js

@@ -1,5 +1,5 @@
-// The admission cost model for one study analysis request: the expected cost, the worst case, and
-// the figure admission compares with the cap.
+// The admission cost model for one study analysis request: the expected cost, the worst case, the
+// figure admission compares with the cap, and the words and command a cost refusal gives.
 /**
  * UTF-8 bytes per input token for the instructions, evidence packet and schema. On 148 billed
  * gpt-6-astra analyses the evidence packet ran 3.1 to 3.3 bytes per token and the instructions
@@ -40,13 +40,18 @@ export function estimateAnalysisCost(rate, size) {
         admittedCostUsd: Math.min(worstCaseCostUsd, roundUp(expectedCostUsd * ADMISSION_MARGIN)),
     };
 }
-/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
-export function admittingMaxCost(cost) {
-    return Math.max(1, Math.ceil(cost.worstCaseCostUsd));
-}
-/** Why admission refused an analysis, in plain words. */
-export function costRefusalText(cost) {
-    return `The expected cost is $${cost.expectedCostUsd.toFixed(2)} and the worst case is $${cost.worstCaseCostUsd.toFixed(2)}. With a ${Math.round((ADMISSION_MARGIN - 1) * 100)}% margin the expected cost is over the $${cost.maxCostUsd} cap, so no request was sent.`;
+/**
+ * Words a cost refusal. `runFlags` are the `analyze` flags that select the run, such as
+ * `--run <id>`. `cli` prefixes a humanish command: the CLI passes `cli` from
+ * src/cli/invocation.ts, and the Observer, which cannot read the install, a bare `humanish`.
+ * This module keeps only type imports, so the Observer can bundle it.
+ */
+export function costRefusal(cost, runFlags, cli) {
+    const margin = Math.round((ADMISSION_MARGIN - 1) * 100);
+    return {
+        text: `The expected cost is $${cost.expectedCostUsd.toFixed(2)} and the worst case is $${cost.worstCaseCostUsd.toFixed(2)}. With a ${margin}% margin the expected cost is over the $${cost.maxCostUsd} cap, so no request was sent. To run it, raise the cap:`,
+        command: cli(`analyze ${runFlags} --max-cost ${Math.max(1, Math.ceil(cost.worstCaseCostUsd))}`),
+    };
 }
 /** The admission's refused cost, when it refused the analysis for its cost. */
 export function refusedCost(admission) {

package/dist/analysis/execute.d.ts

@@ -16,6 +16,11 @@ export interface AnalysisAdmission {
     estimatedCostUsd: number | null;
     /** The cost if the analyst spends its whole output allowance. */
     worstCaseCostUsd: number | null;
+    /**
+     * The expected cost plus the margin, or the worst case when that is lower: the figure admission
+     * compares with maxCostUsd, so the smallest cap that admits this analysis.
+     */
+    admittedCostUsd: number | null;
     maxCostUsd: number | null;
     ratesAsOf: string | null;
 }

package/dist/analysis/execute.js

@@ -145,6 +145,7 @@ export function estimateAnalysisAdmission(input, config) {
         outputTokenAllowance: 0,
         estimatedCostUsd: null,
         worstCaseCostUsd: null,
+        admittedCostUsd: null,
         maxCostUsd: null,
         ratesAsOf: null,
     });
@@ -178,6 +179,7 @@ export function estimateAnalysisAdmission(input, config) {
             outputTokenAllowance: null,
             estimatedCostUsd: null,
             worstCaseCostUsd: null,
+            admittedCostUsd: null,
             maxCostUsd: null,
             ratesAsOf: null,
         };
@@ -207,6 +209,7 @@ export function estimateAnalysisAdmission(input, config) {
         outputTokenAllowance: config.maxOutputTokens,
         estimatedCostUsd: cost.expectedCostUsd,
         worstCaseCostUsd: cost.worstCaseCostUsd,
+        admittedCostUsd: cost.admittedCostUsd,
         maxCostUsd: config.maxCostUsd,
         ratesAsOf: rate.asOf,
     };

package/dist/analysis/finding-lead.d.ts

@@ -0,0 +1,27 @@
+import type { AnalysisCorrection, AnalysisResult } from "./types.js";
+type Severity = NonNullable<AnalysisResult["designFindings"]>[number]["severity"];
+export interface FindingLead {
+    /** The reviewer's amended claim, or the plain headline. */
+    headline: string;
+    /**
+     * The line under the headline: the plain experience, or after an amendment a sentence saying the
+     * reviewer's claim replaced the headline and account. Null when the analysis wrote no experience.
+     */
+    account: string | null;
+    /** The headline is a reviewer's amended claim. */
+    corrected: boolean;
+}
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export declare function findingLead(finding: {
+    headline?: string | null;
+    experience?: string | null;
+}, correction: Pick<AnalysisCorrection, "status" | "replacementClaim"> | null | undefined): FindingLead | null;
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export declare function bySeverity<T extends {
+    severity: Severity;
+}>(findings: readonly T[]): T[];
+export {};

package/dist/analysis/finding-lead.js

@@ -0,0 +1,23 @@
+// How a finding opens for a reader, the same in `review`, a feedback draft and the Observer. The
+// Observer bundles this module, so it imports types only (observer/tests/contract-lock.test.ts).
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export function findingLead(finding, correction) {
+    if (finding.headline === undefined || finding.headline === null)
+        return null;
+    if (correction?.status === "amended" && correction.replacementClaim)
+        return {
+            headline: correction.replacementClaim,
+            account: "Corrected in human review. The reviewer's claim replaces the original headline and account.",
+            corrected: true,
+        };
+    return { headline: finding.headline, account: finding.experience ?? null, corrected: false };
+}
+const SEVERITY_ORDER = ["major", "moderate", "minor"];
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export function bySeverity(findings) {
+    return findings.toSorted((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity));
+}

package/dist/analysis/service.js

@@ -17,7 +17,8 @@ import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalys
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
 import { loadAnalysis } from "./load.js";
-import { admittingMaxCost, costRefusalText, refusedCost } from "./admission.js";
+import { costRefusal, refusedCost } from "./admission.js";
+import { cli } from "../cli/invocation.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -191,13 +192,14 @@ function analyzeConfigRefusal(config) {
 function admissionOnlyResult(base, config) {
     if (!base.admission.allowed) {
         const cost = refusedCost(base.admission);
+        const refusal = cost && costRefusal(cost, `--run ${base.run}`, cli);
         return {
             ...base,
             ok: false,
             error: {
                 code: base.admission.error ?? "analysis_admission_denied",
-                message: cost
-                    ? `${costRefusalText(cost)} To run it, raise the cap: humanish analyze --run ${base.run} --max-cost ${admittingMaxCost(cost)}`
+                message: refusal
+                    ? `${refusal.text} ${refusal.command}`
                     : "The analysis input or configuration did not pass admission. No provider request was sent.",
             },
         };

package/dist/cli/commands/notes.js

@@ -1,7 +1,9 @@
 import { renderObserver } from "../../observer/render.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
-import { addRunNote, formatRunTime, readRunNotes, runParticipantCaptions, } from "../../run/notes.js";
-import { streamParticipantIdOf } from "../../run/participant-records.js";
+import { readRunNotes } from "../../run/note-files.js";
+import { byRunTime } from "../../run/note-shape.js";
+import { addRunNote, formatRunTime } from "../../run/notes.js";
+import { runParticipantCaptions, streamParticipantIdOf } from "../../run/participant-records.js";
 import { resolvePhysicalCwd, runIdOf } from "../../run/paths.js";
 import { runNotFoundMessage } from "../../run/run-not-found.js";
 import { cli } from "../invocation.js";
@@ -42,7 +44,6 @@ function parseRunTime(value) {
     const match = /^(\d{1,4}):([0-5]\d)$/.exec(value.trim());
     return match ? (Number(match[1]) * 60 + Number(match[2])) * 1000 : null;
 }
-const byRunTime = (notes) => [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
 async function handleNotes(io, run, text, options, command) {
     const base = {
         schema: NOTES_RESULT_SCHEMA,

package/dist/cli/findings.js

@@ -2,8 +2,9 @@
 // `humanish.analysis-findings.v1` projection and its text. The analysis artifact stays the record;
 // this reads the version `analyze show` selects and never starts an analysis.
 import path from "node:path";
-import { admittingMaxCost, costRefusalText } from "../analysis/admission.js";
+import { costRefusal } from "../analysis/admission.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { bySeverity, findingLead } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
@@ -64,20 +65,13 @@ function evidenceOf(finding, analysis, runRoot) {
         ...entry,
     }));
 }
-const SEVERITY_RANK = {
-    major: 0,
-    moderate: 1,
-    minor: 2,
-};
 /** Most severe first; equal severity keeps the analysis order. */
 function designFindingViews(analysis, runRoot) {
     const designFindings = analysis.result?.designFindings;
     if (designFindings === undefined)
         return null;
     const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
-    return [...designFindings]
-        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
-        .map((finding) => ({
+    return bySeverity(designFindings).map((finding) => ({
         id: finding.id,
         headline: finding.headline,
         screen: finding.screen,
@@ -200,8 +194,10 @@ export function analysisFindings(source) {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
     }
-    if (job?.state === "skipped" && job.admission)
-        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${costRefusalText(job.admission)}`, cli(`analyze --run ${source.runId}${source.cwdFlag} --max-cost ${admittingMaxCost(job.admission)}`));
+    if (job?.state === "skipped" && job.admission) {
+        const refusal = costRefusal(job.admission, `--run ${source.runId}${source.cwdFlag}`, cli);
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${refusal.text}`, refusal.command);
+    }
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run says why, and for a cost refusal names the --max-cost that admits it." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
@@ -342,18 +338,6 @@ function captureFiles(evidence, runRoot) {
             .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
     ];
 }
-/**
- * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
- * since the headline and experience describe the claim it replaced. Null before headlines existed.
- */
-function leadOf(finding) {
-    const amended = finding.correction?.status === "amended" ? finding.correction : null;
-    if (finding.headline === null)
-        return null;
-    return amended?.replacementClaim
-        ? { headline: amended.replacementClaim, corrected: true }
-        : { headline: finding.headline, corrected: false };
-}
 function findingLines(finding, runRoot) {
     const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
     const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
@@ -361,19 +345,13 @@ function findingLines(finding, runRoot) {
     const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
     const captures = captureFiles(finding.evidence, runRoot);
     const correction = finding.correction;
-    const lead = leadOf(finding);
+    const lead = findingLead(finding, correction);
     return [
         ...(lead === null
             ? [`${finding.id} ${finding.title}`]
             : [
                 `${finding.id} ${lead.headline}`,
-                ...(lead.corrected
-                    ? [
-                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
-                    ]
-                    : finding.experience === null
-                        ? []
-                        : [`   ${finding.experience}`]),
+                ...(lead.account === null ? [] : [`   ${lead.account}`]),
                 `   evidence: ${finding.title}`,
             ]),
         `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
@@ -451,7 +429,7 @@ export function formatFindingsSummary(view, fullCommand, limit = 3) {
         `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
         ...shown.map((finding) => {
             const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
-            const lead = leadOf(finding);
+            const lead = findingLead(finding, finding.correction);
             if (lead === null)
                 return `- ${finding.id} ${qualities}: ${finding.title}`;
             return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;

package/dist/cli/io.js

@@ -1,5 +1,5 @@
 import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
-import { admittingMaxCost, costRefusalText, refusedCost, } from "../analysis/admission.js";
+import { costRefusal, refusedCost } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
@@ -189,8 +189,9 @@ export function writeResult(command, io, result, formatHuman) {
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
             const cost = analysis?.result?.admission && refusedCost(analysis.result.admission);
-            if (cost)
-                io.writeOut(`analysis: refused before it started. ${refusedAnalysisText(cost, analysis.result?.run ?? "latest")}\n`);
+            const refusal = cost && costRefusal(cost, `--run ${analysis.result?.run ?? "latest"}`, cli);
+            if (refusal)
+                io.writeOut(`analysis: refused before it started. ${refusal.text} ${refusal.command}\n`);
             else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
@@ -306,10 +307,6 @@ export function analysisOutcomeText(analysis) {
         return analysis.state;
     return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
 }
-/** What a refused analysis would cost and the command that runs it with a cap that admits it. */
-function refusedAnalysisText(cost, runId) {
-    return `${costRefusalText(cost)} To run it, raise the cap: ${cli(`analyze --run ${runId} --max-cost ${admittingMaxCost(cost)}`)}`;
-}
 /** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||

package/dist/cli/telemetry.js

@@ -12,9 +12,9 @@
 import { isCuaDiagnosticCategory, isCuaDiagnosticStopCause, } from "../routes/computer-use/diagnostics.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import path from "node:path";
 import { STUDY_RESULT_SCHEMA } from "../run/study-result.js";
+import { envFlag, humanishConfigFile } from "./user-config.js";
 /** Write-only PostHog project key. Public by design: it can ingest, and can read nothing. */
 const INGEST_KEY = "phc_oeMeBqxDZhZ9tCHMSnuDFimLqHpU5Myc847WD33hAh4C";
 const INGEST_HOST = "https://us.i.posthog.com";
@@ -26,26 +26,16 @@ const STARTER_STUDIES = new Set([
     "local-browser",
     "lobby-trivia-3player",
 ]);
-export function telemetryStatePath(env = process.env, home = homedir()) {
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    // Same XDG rule the key store uses: a relative value must be ignored, or state becomes
-    // cwd-relative and follows people between projects.
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "telemetry.json");
+export function telemetryStatePath(env = process.env, home) {
+    return humanishConfigFile(env, "telemetry.json", home);
 }
 /**
  * Off means off, from any of the three switches people already expect: the cross-tool
  * `DO_NOT_TRACK` standard, our own env var, and the persisted opt-out.
  */
 export function disabledByEnvironment(env) {
-    const truthy = (value) => value !== undefined &&
-        value.trim() !== "" &&
-        value.trim() !== "0" &&
-        value.trim().toLowerCase() !== "false";
-    return (truthy(env.DO_NOT_TRACK) ||
-        truthy(env.HUMANISH_TELEMETRY_DISABLED) ||
+    return (envFlag(env.DO_NOT_TRACK) ||
+        envFlag(env.HUMANISH_TELEMETRY_DISABLED) ||
         // Our own development and test runs must never reach the adoption dataset. In the first two
         // days after telemetry shipped, 82% of events (4,042 of 4,932, from 49 of 59 anonymous ids)
         // came from humanish's own CI and suite: ~50 ids each running nearly every subcommand about
@@ -55,7 +45,7 @@ export function disabledByEnvironment(env) {
         // Deliberately not keyed on CI. An adopter running humanish in their pipeline is real usage
         // and stays countable; the `ci` property already separates it, which is what Next.js does.
         // This keys on being inside the humanish source tree, which only we ever are.
-        truthy(env.HUMANISH_DEV));
+        envFlag(env.HUMANISH_DEV));
 }
 /**
  * True when this process is running from a humanish source checkout rather than an install.
@@ -101,7 +91,7 @@ export function inHumanishCheckout(startDir, readFileSyncFn) {
 export function isOwnCheckoutRun(cwd, cliDir, readFileSyncFn) {
     return inHumanishCheckout(cwd, readFileSyncFn) || inHumanishCheckout(cliDir, readFileSyncFn);
 }
-export async function readTelemetryState(env = process.env, home = homedir()) {
+export async function readTelemetryState(env = process.env, home) {
     try {
         const raw = await readFile(telemetryStatePath(env, home), "utf8");
         const parsed = JSON.parse(raw);
@@ -115,7 +105,7 @@ export async function readTelemetryState(env = process.env, home = homedir()) {
         return { enabled: true, anonymousId: randomUUID(), noticed: false };
     }
 }
-export async function writeTelemetryState(state, env = process.env, home = homedir()) {
+export async function writeTelemetryState(state, env = process.env, home) {
     const file = telemetryStatePath(env, home);
     await mkdir(path.dirname(file), { recursive: true });
     await writeFile(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
@@ -162,15 +152,13 @@ export function buildPayload(args) {
         version: args.version,
         os: args.platform ?? process.platform,
         node: (args.nodeVersion ?? process.version).split(".")[0].replace("v", ""),
-        ci: env.CI !== undefined && env.CI !== "" && env.CI !== "0",
+        ci: envFlag(env.CI),
         // A humanish study participant is a real cold install on a machine we do not own, so it emits
         // like any other new adopter and is indistinguishable from one. It is also the exact
         // population we are trying to count, so a busy self-study day reads as an adoption spike.
         // Stamped rather than suppressed, the same shape as `ci`: participant runs stay visible and
         // stay separable, and we keep a genuine measurement of what a cold install does.
-        studyParticipant: env.HUMANISH_STUDY_PARTICIPANT !== undefined &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "" &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "0",
+        studyParticipant: envFlag(env.HUMANISH_STUDY_PARTICIPANT),
     };
     const given = args.properties ?? {};
     if (given.command !== undefined)

package/dist/cli/update-check.js

@@ -4,20 +4,12 @@
 // 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";
+import { envFlag, humanishConfigFile } from "./user-config.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"));
@@ -65,10 +57,6 @@ 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
@@ -80,9 +68,9 @@ function checkAllowed(context) {
     return (context.terminal &&
         !context.json &&
         !context.ownCheckout &&
-        !truthy(env.CI) &&
-        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
-        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !envFlag(env.CI) &&
+        !envFlag(env.HUMANISH_NO_UPDATE_CHECK) &&
+        !envFlag(env.HUMANISH_STUDY_PARTICIPANT) &&
         !disabledByEnvironment(env));
 }
 /**
@@ -94,7 +82,7 @@ export function checkForUpdate(context) {
     try {
         if (!checkAllowed(context))
             return undefined;
-        const cachePath = updateCachePath(context.env, context.home);
+        const cachePath = humanishConfigFile(context.env, "update-check.json", context.home);
         const cache = readUpdateCache(cachePath);
         const stamp = new Date(context.now).toISOString();
         const next = { ...cache };
@@ -126,7 +114,7 @@ export function checkForUpdate(context) {
  * cache only; undefined until a check has succeeded on this machine.
  */
 export function recordedVersion(installed, env, home) {
-    const cache = readUpdateCache(updateCachePath(env, home));
+    const cache = readUpdateCache(humanishConfigFile(env, "update-check.json", home));
     if (cache.latest === undefined)
         return undefined;
     const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;

package/dist/cli/user-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export declare function humanishConfigFile(env: NodeJS.ProcessEnv, fileName: string, home?: string): string;
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export declare function envFlag(value: string | undefined): boolean;

package/dist/cli/user-config.js

@@ -0,0 +1,25 @@
+// Where humanish keeps per-user files (the key store, telemetry state, the update-check cache) and
+// how it reads an on/off environment variable. The key store, telemetry and the update check each
+// had their own copy of both.
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export function humanishConfigFile(env, fileName, 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", fileName);
+}
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export function envFlag(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed !== "" && trimmed !== "0" && trimmed.toLowerCase() !== "false";
+}

package/dist/comms/email-catch.js

@@ -9,6 +9,7 @@
 //
 // 127.0.0.1 only; request bodies are never logged; request size is capped.
 import { createServer } from "node:http";
+import { readBodyAtMost } from "../observer/http.js";
 import { capturedInlineImages } from "./images.js";
 // ---------------------------------------------------------------- shared parse helpers
 function str(value) {
@@ -116,26 +117,6 @@ export const DEFAULT_EMAIL_PROFILES = [
     sendgridEmailProfile,
 ];
 // ---------------------------------------------------------------- server
-class BodyTooLargeError extends Error {
-}
-function readBody(req, limit) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        req.on("data", (chunk) => {
-            size += chunk.length;
-            if (size > limit) {
-                // Reject without destroying the socket here: the handler responds 413 cleanly first (a
-                // write-after-destroy would otherwise reset the connection), then tears the request down.
-                reject(new BodyTooLargeError("request body too large"));
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-        req.on("error", reject);
-    });
-}
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
 /**
  * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
@@ -170,21 +151,16 @@ export async function startEmailCatchServer(channel, options = {}) {
             respondJson(res, 404, { error: "not found" });
             return;
         }
-        let raw;
-        try {
-            raw = await readBody(req, MAX_BODY_BYTES);
-        }
-        catch (error) {
-            if (!res.headersSent)
-                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, {
-                    error: "request body could not be read",
-                });
-            req.destroy();
+        const body = await readBodyAtMost(req, MAX_BODY_BYTES).catch(() => undefined);
+        if (body === null || body === undefined) {
+            // The rest of the body is never read, so the connection closes after this answer.
+            res.setHeader("connection", "close");
+            respondJson(res, body === null ? 413 : 400, { error: "request body could not be read" });
             return;
         }
         let parsed;
         try {
-            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+            parsed = JSON.parse(body.length > 0 ? body.toString("utf8") : "{}");
         }
         catch {
             respondJson(res, 422, { error: "invalid JSON body" });