humanish 0.107.0 → 0.109.0

package/dist/verify/verify.js

@@ -8,13 +8,16 @@ import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA } from "../run/bundle.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
 import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
+import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
 import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, } from "./artifacts.js";
+import { flatContextWarnings } from "./context-growth.js";
 import { runNotFinishedWarnings } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
 import { sharedWorldEvidenceFindings } from "./shared-world.js";
 import { subjectStateFindings, undeclaredSubjectStateWarnings } from "./subject.js";
+import { plural } from "../run/text.js";
 export const VERIFY_SCHEMA = "humanish.verify-result.v1";
 // The UNSCANNED_ARTIFACT reason names this many paths and counts the rest.
 const MAX_LISTED_UNSCANNED = 10;
@@ -57,26 +60,16 @@ export function invalidRunStorageVerifyResult(cwd, runInput) {
 export async function verifyResolvedRun(cwd, runInput, runPaths) {
     const checks = [];
     if (!runPaths) {
+        const message = await runNotFoundMessage(cwd, runInput);
         return {
             schema: VERIFY_SCHEMA,
             ok: false,
             cwd,
             run: runInput,
             checks,
-            shareSafety: {
-                status: "blocked",
-                reasons: [
-                    {
-                        code: "VERIFY_FAILED",
-                        message: `Run not found: ${runInput}`,
-                    },
-                ],
-            },
+            shareSafety: { status: "blocked", reasons: [{ code: "VERIFY_FAILED", message }] },
             warnings: [],
-            error: {
-                code: "HUMANISH_RUN_NOT_FOUND",
-                message: `Run not found: ${runInput}`,
-            },
+            error: { code: "HUMANISH_RUN_NOT_FOUND", message },
         };
     }
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
@@ -84,7 +77,10 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     const cleanupJson = await readRunJsonIfExists(runPaths, "cleanup.json");
     const reviewJson = await readRunJsonIfExists(runPaths, "review.json");
     const reviewMarkdown = await readRunTextIfExists(runPaths, "review.md");
-    checks.push(...bundlePresenceChecks(bundle, reviewJson !== null && reviewMarkdown !== null));
+    checks.push(...bundlePresenceChecks(bundle, {
+        json: reviewJson !== null,
+        markdown: reviewMarkdown !== null,
+    }));
     const derivedPublicSafetyFindings = [];
     const unscannedArtifacts = [];
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
@@ -104,7 +100,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         name: "public-safety scan",
         ok: publicSafetyFindings.length === 0,
         message: publicSafetyFindings.length === 0
-            ? "run text artifacts and public-proof paths must not match known secret or browser-profile patterns"
+            ? "no run text artifact or public-proof path matches a known secret or browser-profile pattern"
             : `public-safety findings: ${publicSafetyFindings.slice(0, 5).join(", ")}`,
     });
     const missingEvidenceArtifacts = isRunBundle(bundle)
@@ -118,7 +114,9 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         name: "local evidence artifacts exist",
         ok: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0,
         message: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0
-            ? "referenced local screenshot/trace/log/filesystem artifacts are present"
+            ? isRunBundle(bundle)
+                ? "every referenced screenshot, trace, log and filesystem artifact is present"
+                : SHAPE_UNCHECKED
             : invalidEvidenceReferences.length > 0
                 ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
                 : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
@@ -137,6 +135,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
             ...undeclaredSubjectStateWarnings(bundle),
             ...desktopGeometryWarnings(bundle),
+            ...flatContextWarnings(bundle),
             ...(await runNotFinishedWarnings(runPaths, bundle)),
         ]
         : [];
@@ -189,33 +188,76 @@ export async function verifyRunPrepared(cwdInput, runInput, runPaths) {
     }
     return verifyResolvedRun(cwd, runInput, runPaths);
 }
-/** Whether run.json, its schema, shape and redaction, and the review artifacts are present. */
-function bundlePresenceChecks(bundle, reviewArtifactsExist) {
+/** The top-level run.json sections the shape guard requires. */
+const REQUIRED_SECTIONS = [
+    "source",
+    "persona",
+    "scenario",
+    "lifecycle",
+    "simulations",
+    "streams",
+    "events",
+    "artifacts",
+    "review",
+    "redaction",
+    "feedbackCandidates",
+];
+/**
+ * Whether run.json, its schema, shape and redaction, and the review artifacts are present. Each
+ * check says what it found, so a failing row never prints the rule it enforces.
+ */
+function bundlePresenceChecks(bundle, review) {
+    const record = isRecord(bundle) ? bundle : undefined;
+    const schema = record?.schema;
+    const schemaOk = schema === RUN_BUNDLE_SCHEMA;
+    const redactionRecord = record?.redaction;
+    const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
+    const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
+    const missingReview = [
+        ...(review.json ? [] : ["review.json is missing or not valid JSON"]),
+        ...(review.markdown ? [] : ["review.md is missing"]),
+    ];
     return [
         {
             name: "run.json exists",
             ok: bundle !== null,
-            message: bundle === null ? "run.json missing" : "run.json present",
+            message: bundle === null ? "run.json is missing or not valid JSON" : "run.json is present",
         },
         {
             name: "run schema",
-            ok: isRecord(bundle) && bundle.schema === RUN_BUNDLE_SCHEMA,
-            message: "run bundle schema is humanish.run-bundle.v1",
+            ok: schemaOk,
+            message: schemaOk
+                ? `run.json declares ${RUN_BUNDLE_SCHEMA}`
+                : record === undefined
+                    ? "no readable run.json, so no schema"
+                    : `run.json declares ${typeof schema === "string" ? schema : "no schema"}; verify reads ${RUN_BUNDLE_SCHEMA}`,
         },
         {
             name: "run bundle shape",
             ok: isRunBundle(bundle),
-            message: "run bundle must include source, persona, scenario, lifecycle, simulations, streams, events, artifacts, review, and feedback candidates",
+            message: isRunBundle(bundle)
+                ? "run.json has every required section"
+                : record === undefined
+                    ? "no readable run.json, so no sections"
+                    : missingSections.length > 0
+                        ? `run.json is missing ${missingSections.join(", ")}`
+                        : schemaOk
+                            ? "one or more run.json sections have the wrong shape"
+                            : "sections not checked, because the schema differs",
         },
         {
             name: "redaction passed",
-            ok: isRecord(bundle) && isRecord(bundle.redaction) && bundle.redaction.status === "passed",
-            message: "redaction status must be passed",
+            ok: redaction === "passed",
+            message: redaction === "passed"
+                ? "redaction passed"
+                : `redaction did not pass (status: ${typeof redaction === "string" ? redaction : "missing"})`,
         },
         {
             name: "review artifacts exist",
-            ok: reviewArtifactsExist,
-            message: "review.json and review.md must exist",
+            ok: missingReview.length === 0,
+            message: missingReview.length === 0
+                ? "review.json and review.md are present"
+                : missingReview.join("; "),
         },
     ];
 }
@@ -242,38 +284,46 @@ async function applyAnalysisSharing(runPaths, warnings, shareSafety) {
         shareSafety.status = "local_only";
 }
 /** Passes when `findings` is empty; otherwise lists them after `failLabel`. */
-function findingsCheck(name, findings, okMessage, failLabel, failSuffix = "") {
+function findingsCheck(name, findings, okMessage, failLabel) {
     return {
         name,
         ok: findings.length === 0,
-        message: findings.length === 0 ? okMessage : `${failLabel}: ${findings.join(", ")}${failSuffix}`,
+        message: findings.length === 0 ? okMessage : `${failLabel}: ${findings.join(", ")}`,
     };
 }
+/**
+ * The pass message of a check that reads bundle content when run.json failed its shape guard. The
+ * check has no findings and stays ok; the shape check is the failure.
+ */
+const SHAPE_UNCHECKED = "not checked, because run.json failed the shape check";
 /** The bundle-content checks, in report order. A bundle that fails its shape guard has no findings. */
 async function evidenceChecks(runPaths, bundle, cleanupJson) {
     const valid = isRunBundle(bundle) ? bundle : null;
+    const pass = (message) => (valid ? message : SHAPE_UNCHECKED);
     const checks = [
-        findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], "live terminal-product streams either are absent or carry the substrate/cleanup/interventions/cost ledgers + a ledger-derived no-spend proof + redacted terminal evidence, with proven teardown and known spend within the declared cap", "terminal-product findings"),
-        findingsCheck("codex app-server evidence", valid ? await validateCodexAppServerEvidence(runPaths, valid) : [], "live Codex app-server streams either are absent or include valid redacted trace evidence", "codex app-server findings"),
-        findingsCheck("actor engagement", valid ? noEngagementActorFindings(valid) : [], "live actor traces that claim goal_satisfied carry at least one action or message", "no-engagement findings", " — a hollow run is not credible evidence"),
-        findingsCheck("actor verdict consistency", valid ? actorVerdictConsistencyFindings(valid) : [], "live pass verdicts do not hide failed, blocked, or timed-out actor traces", "actor verdict findings"),
-        findingsCheck("subject state provenance", valid ? subjectStateFindings(valid) : [], "subject state claims match the recorded seed/external evidence (or the subject block is honestly absent)", "subject state findings"),
-        findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], "live shared-world runs either are absent or carry well-formed evidence for their mode (concurrent participant windows, state series and outcomes covering every role, or an older run's sequential timeline), single-plane provenance, digest-only checkpoints and the mandatory attributionLimits", "shared-world findings"),
+        findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], pass("live terminal-product evidence is complete (ledgers, redacted output, proven teardown, known spend within the cap), or the run has none"), "terminal-product findings"),
+        findingsCheck("codex app-server evidence", valid ? await validateCodexAppServerEvidence(runPaths, valid) : [], pass("live Codex app-server traces are valid and redacted, or the run has none"), "codex app-server findings"),
+        findingsCheck("actor engagement", valid ? noEngagementActorFindings(valid) : [], pass("every live actor that claims its goal took at least one action or sent a message"), "no-engagement findings"),
+        findingsCheck("actor verdict consistency", valid ? actorVerdictConsistencyFindings(valid) : [], pass("no live pass verdict hides a failed, blocked or timed-out actor"), "actor verdict findings"),
+        findingsCheck("subject state provenance", valid ? subjectStateFindings(valid) : [], pass("subject state claims match the recorded seed and external evidence, or the run makes none"), "subject state findings"),
+        findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], pass("live shared-world evidence is well formed for its mode, with single-plane provenance, digest-only checkpoints and attributionLimits, or the run has none"), "shared-world findings"),
         {
             name: "cleanup receipt",
             ok: cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok),
             message: cleanupJson === null
-                ? "cleanup receipt not present; cleanup was not requested"
-                : isCleanupResult(cleanupJson) && cleanupJson.ok
-                    ? "cleanup receipt is present and successful"
-                    : "cleanup receipt is present but malformed or failed",
+                ? "no cleanup.json; cleanup was not requested"
+                : !isCleanupResult(cleanupJson)
+                    ? "cleanup.json is malformed"
+                    : cleanupJson.ok
+                        ? "cleanup.json records a successful cleanup"
+                        : "cleanup.json records a failed cleanup",
         },
-        findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], "rerun bundles either are absent or link selected participants to their prior status and a fan-out rerun event", "rerun lineage findings"),
-        // Cost is ADVISORY on magnitude, FAIL-CLOSED on labeling/provenance (claims match mechanism).
-        // Absence PASSES (fail-open on display); a claimed dollar figure without its ratesAsOf date +
-        // source, or a total that does not match its known lines, FAILS. Magnitude is never inspected —
+        findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], pass("rerun participants link to their prior status and a fan-out rerun event, or this run is not a rerun"), "rerun lineage findings"),
+        // Cost is advisory on magnitude and fail-closed on labeling/provenance (claims match mechanism).
+        // Absence passes (fail-open on display); a claimed dollar figure without its ratesAsOf date +
+        // source, or a total that does not match its known lines, fails. Magnitude is never inspected:
         // a correctly-labeled huge estimate still passes.
-        findingsCheck("cost estimate labeling", valid ? costAndReceiptFindings(valid) : [], "cost figures are absent, or every claimed estimate carries its ratesAsOf date + source and the total matches its known lines (estimates never presented as exact)", "cost labeling findings"),
+        findingsCheck("cost estimate labeling", valid ? costAndReceiptFindings(valid) : [], pass("every cost estimate carries its ratesAsOf date and source and the total matches its lines, or the run claims no cost"), "cost labeling findings"),
     ];
     return checks;
 }
@@ -313,7 +363,7 @@ function buildShareSafety(args) {
         const more = paths.length - MAX_LISTED_UNSCANNED;
         reasons.push({
             code: "UNSCANNED_ARTIFACT",
-            message: `The public-safety scan cannot read ${paths.length} file(s) as text, and they are not stream screenshots under screenshots/ or registered recordings: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
+            message: `The public-safety scan cannot read ${plural(paths.length, "file")} as text that ${paths.length === 1 ? "is not a stream screenshot under screenshots/ or a registered recording" : "are not stream screenshots under screenshots/ or registered recordings"}: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
         });
     }
     const rawStreamIds = rawScreenshotStreamIds(args.bundle, args.redactedShapeFrames);

package/docs/README.md

@@ -1,31 +1,17 @@
 # Find the right doc
 
-Start with the reading order in [CONTRIBUTING.md](../CONTRIBUTING.md#read-these-in-order). This page
-sorts everything under `docs/` by what it is for. Nothing here moves files; a folder that holds more
-than one kind is split file by file.
+User guides live at [humanish.dev/docs](https://humanish.dev/docs). This page sorts the contributor
+reference under `docs/` by what it is for. To make a first change, start with
+[CONTRIBUTING.md](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#make-your-first-change).
 
 ## Follow a guide to do a task
 
-- [ramp/README.md](ramp/README.md): current state, how to pick work and the quality bar.
-- [architecture/local-browser-runtime.md](architecture/local-browser-runtime.md): run a study in a
-  local Firecracker browser.
-- [architecture/real-email-receiving.md](architecture/real-email-receiving.md) and
-  [architecture/comms-inbox.md](architecture/comms-inbox.md): give participants real or captured
-  inboxes.
-- [architecture/participant-media.md](architecture/participant-media.md) and
-  [architecture/desktop-recording.md](architecture/desktop-recording.md): add a camera, speech or
-  a desktop video.
-- [architecture/observer-review.md](architecture/observer-review.md): watch and review a study.
-- [architecture/project-layout.md](architecture/project-layout.md): the `humanish/` and
-  `.humanish/` folders `init` creates.
-- [product/lobby-trivia-3player-external-public.md](product/lobby-trivia-3player-external-public.md):
-  a worked example of the external-public shared-world lab.
-- [release/open-source-readiness.md](release/open-source-readiness.md): the release gates and the
-  publish procedure. Its opening audit is a dated snapshot.
+- [ramp/README.md](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md): current state, how to pick work and the quality bar.
+- [release/publish.md](https://github.com/danielgwilson/humanish/blob/main/docs/release/publish.md): check a release candidate, tag it and publish it.
 
 ## Look up what the code does now
 
-- [contracts/](contracts/schemas.md): bundle, lab, policy, feedback, analysis and cost contracts.
+- [contracts/](contracts/README.md): bundle, study, policy, feedback, analysis and cost contracts.
   Documented fields are API. [contracts/schemas.md](contracts/schemas.md) indexes every schema.
 - [architecture/observer.md](architecture/observer.md), [architecture/serve.md](architecture/serve.md):
   the Observer and the run library server.
@@ -33,35 +19,42 @@ than one kind is split file by file.
   [architecture/browser-control.md](architecture/browser-control.md),
   [architecture/guest-desktop.md](architecture/guest-desktop.md): hosted desktops, the browser
   control protocol and the guest runtime.
-- [architecture/state-driven-executor.md](architecture/state-driven-executor.md): the `CuaExecutor`
+- [architecture/state-driven-executor.md](architecture/state-driven-executor.md): the `ComputerUseExecutor`
   library path.
 - [architecture/task-protocol-support.md](architecture/task-protocol-support.md): which routes
-  accept `actors[0].tasks`.
+  accept `actor.tasks`.
 - [architecture/external-public-shared-world.md](architecture/external-public-shared-world.md) and
   [architecture/terminal-product-route.md](architecture/terminal-product-route.md): two routes in
-  depth. Both keep dated slice notes beside the current rules.
+  depth.
 - [architecture/restricted-codex-analysis.md](architecture/restricted-codex-analysis.md) and
   [product/automatic-analysis.md](product/automatic-analysis.md): study analysis.
-- [release/public-readiness-standard.md](release/public-readiness-standard.md): what may appear in
+- [release/public-readiness-standard.md](https://github.com/danielgwilson/humanish/blob/main/docs/release/public-readiness-standard.md): what may appear in
   the public repository and the npm package.
 
 ## Read why the code is shaped this way
 
-- [principles/](principles/engineering.md): engineering, invariants and defaults, actor fidelity,
-  the three roles and the self-driving harness.
+- [principles/engineering.md](principles/engineering.md),
+  [principles/invariants-and-defaults.md](principles/invariants-and-defaults.md),
+  [principles/actor-fidelity.md](principles/actor-fidelity.md),
+  [principles/three-roles.md](principles/three-roles.md) and
+  [principles/self-driving-harness.md](principles/self-driving-harness.md): engineering,
+  invariants and defaults, actor fidelity, the three roles and the self-driving harness.
 - [decisions/](decisions/README.md): one record per decision, each naming the code or test that
   enforces it.
 - [architecture/actor-contract.md](architecture/actor-contract.md) and
   [architecture/github-feedback-loop.md](architecture/github-feedback-loop.md): design records with
   their context and open items.
-- [product/open-source-install-experience.md](product/open-source-install-experience.md): the
-  product target for install and first run.
 
-## Treat these folders as history
+## Check the current state and the evidence behind it
 
-`goals/`, `plans/` and `roadmap/` hold dated plans, status logs and receipts. They may name files
+- [status.md](https://github.com/danielgwilson/humanish/blob/main/docs/status.md): what ships today, by surface, and the work that is gated.
+- [evidence/](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/README.md): dated study records that the README, the site and these pages
+  cite. `docs:check` covers them.
+
+## Treat history as history
+
+[history/](https://github.com/danielgwilson/humanish/blob/main/docs/history/README.md) holds dated goal packets, plans and the roadmap. They may name files
 that have since moved, so `docs:check` skips them (`HISTORY_DIRECTORIES` in
-[scripts/lib/doc-paths.ts](../scripts/lib/doc-paths.ts)). One file there is current:
-[goals/current.md](goals/current.md), the live status page.
+[scripts/lib/doc-paths.ts](https://github.com/danielgwilson/humanish/blob/main/scripts/lib/doc-paths.ts)).
 
 `assets/` holds images that ship in the npm package, such as the README hero.