humanish 0.39.0 → 0.40.0

package/dist/subject-runtime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Does this serve pipeline need a Node runtime? Matches a bare command word at a token boundary, so
+ * `npm install` and `sudo -n npm ci` count while `my-npm-wrapper` or a path containing "node" does
+ * not. Being wrong in the permissive direction only costs a skipped bootstrap probe; being wrong in
+ * the strict direction costs a paid sandbox and a cryptic exit 127.
+ */
+export declare function needsNodeRuntime(commands: readonly (string | undefined)[]): boolean;
+/** Major Node version installed when the template has none. Matches the terminal lane's choice. */
+export declare const BOOTSTRAP_NODE_MAJOR = 22;
+/**
+ * The bootstrap command. Idempotent and cheap when Node is already present: it probes first and
+ * exits 0 without touching apt, so a custom template that ships its own runtime is untouched.
+ *
+ * `sudo -n` (non-interactive) matches the terminal lane — the desktop user has passwordless sudo,
+ * and failing fast is better than hanging on a password prompt nobody can answer.
+ */
+export declare function nodeBootstrapCommand(major?: number): string;
+/**
+ * Package managers that need their own install step after Node exists. npm and npx arrive with
+ * Node; pnpm, yarn and bun do not, and `corepack enable` is the supported way to get the first two
+ * without a second network fetch.
+ */
+export declare function corepackCommandFor(commands: readonly (string | undefined)[]): string | undefined;

package/dist/subject-runtime.js

@@ -0,0 +1,70 @@
+// Provide the runtime a subject's serve pipeline needs, instead of failing at exit 127 (#371).
+//
+// The stock E2B `desktop` template ships python3 and curl but NO Node. That fact has now been
+// rediscovered three times: the in-sandbox comms catch was rewritten from node to python3 in 0.29.0
+// for exactly this reason, the terminal lane bootstraps Node explicitly, and the computer-use
+// clone/local-tree route did neither — so any lab whose `serve.install` runs npm or pnpm died with
+// `pnpm: command not found` AFTER a sandbox had been created and paid for.
+//
+// It failed invisibly up front: `lab inspect` was clean, the plan printed normally, the sandbox
+// provisioned, and the first signal was a shell exit code attributed to "subject install failed".
+// Nobody can debug that from the outside.
+//
+// The posture here is PROVIDE, not warn. An adopter writing a lab for a Node app should not have to
+// know which binaries the template happens to carry — that is the harness's job, and the terminal
+// lane already treats it that way. Detection is conservative and the bootstrap is skipped whenever
+// a runtime is already present, so a custom template that ships Node pays nothing.
+/** Package managers and runtimes whose absence on the stock template breaks a serve pipeline. */
+const NODE_COMMANDS = ["npm", "npx", "pnpm", "yarn", "bun", "node", "vite", "next", "tsx"];
+/**
+ * Does this serve pipeline need a Node runtime? Matches a bare command word at a token boundary, so
+ * `npm install` and `sudo -n npm ci` count while `my-npm-wrapper` or a path containing "node" does
+ * not. Being wrong in the permissive direction only costs a skipped bootstrap probe; being wrong in
+ * the strict direction costs a paid sandbox and a cryptic exit 127.
+ */
+export function needsNodeRuntime(commands) {
+    const pattern = new RegExp(`(^|[\\s;&|(])(${NODE_COMMANDS.join("|")})([\\s;&|)]|$)`);
+    return commands.some((command) => (command ? pattern.test(command) : false));
+}
+/** Major Node version installed when the template has none. Matches the terminal lane's choice. */
+export const BOOTSTRAP_NODE_MAJOR = 22;
+/**
+ * The bootstrap command. Idempotent and cheap when Node is already present: it probes first and
+ * exits 0 without touching apt, so a custom template that ships its own runtime is untouched.
+ *
+ * `sudo -n` (non-interactive) matches the terminal lane — the desktop user has passwordless sudo,
+ * and failing fast is better than hanging on a password prompt nobody can answer.
+ */
+export function nodeBootstrapCommand(major = BOOTSTRAP_NODE_MAJOR) {
+    return [
+        "if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then",
+        '  echo "humanish: node $(node --version) already present; skipping bootstrap";',
+        "else",
+        `  curl -fsSL https://deb.nodesource.com/setup_${major}.x | sudo -n -E bash - &&`,
+        "  sudo -n apt-get install -y nodejs;",
+        "fi"
+    ].join("\n");
+}
+/**
+ * Package managers that need their own install step after Node exists. npm and npx arrive with
+ * Node; pnpm, yarn and bun do not, and `corepack enable` is the supported way to get the first two
+ * without a second network fetch.
+ */
+export function corepackCommandFor(commands) {
+    const joined = commands.filter((c) => Boolean(c)).join("\n");
+    const wantsPnpm = /(^|[\s;&|(])pnpm([\s;&|)]|$)/.test(joined);
+    const wantsYarn = /(^|[\s;&|(])yarn([\s;&|)]|$)/.test(joined);
+    if (!wantsPnpm && !wantsYarn)
+        return undefined;
+    // Probe first for the same reason as above: a template that already has it pays nothing.
+    const binary = wantsPnpm ? "pnpm" : "yarn";
+    return [
+        `if command -v ${binary} >/dev/null 2>&1; then`,
+        `  echo "humanish: ${binary} already present; skipping corepack";`,
+        "else",
+        "  sudo -n corepack enable >/dev/null 2>&1 || true;",
+        `  corepack prepare ${binary}@latest --activate 2>/dev/null || sudo -n npm install -g ${binary};`,
+        "fi"
+    ].join("\n");
+}
+//# sourceMappingURL=subject-runtime.js.map

package/dist/subject-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-runtime.js","sourceRoot":"","sources":["../src/subject-runtime.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,EAAE;AACF,8FAA8F;AAC9F,oGAAoG;AACpG,8FAA8F;AAC9F,mGAAmG;AACnG,2EAA2E;AAC3E,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,0CAA0C;AAC1C,EAAE;AACF,oGAAoG;AACpG,kGAAkG;AAClG,mGAAmG;AACnG,mFAAmF;AAEnF,iGAAiG;AACjG,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAyC;IACxE,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,iBAAiB,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACrF,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,mGAAmG;AACnG,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,oBAAoB;IACvE,OAAO;QACL,4EAA4E;QAC5E,gFAAgF;QAChF,MAAM;QACN,iDAAiD,KAAK,2BAA2B;QACjF,sCAAsC;QACtC,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyC;IAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,yFAAyF;IACzF,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO;QACL,iBAAiB,MAAM,wBAAwB;QAC/C,qBAAqB,MAAM,uCAAuC;QAClE,MAAM;QACN,oDAAoD;QACpD,sBAAsB,MAAM,4DAA4D,MAAM,GAAG;QACjG,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.39.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.40.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.

package/docs/goals/current.md

@@ -16,7 +16,7 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.39.0`)
+## Current Program Truth (source `0.40.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
@@ -33,7 +33,7 @@ The immutable 2026-06-10 proof-roadmap packet is paired with a
 | Public proof | A legible four-persona Observer hero from a verified real public-application study (commit-pinned drawDB) shipped in the npm payload (`0.16.0`) | Coverage beyond a single studied subject; the stratified breadth panel remains unbuilt |
 | OSS meta-lab | Dry-run contract and separate disposable smoke harness | Live meta-lab execution; disabled until repository instructions and actor credentials have an isolated boundary |
 | Observer serving | `watch`/`observe` loopback servers plus `serve` — the run-library surface with loopback default, capability-link exposure, `share_ready`-gated open mode, and optional operator-run tunnel; streams never served remotely | A remote live-stream (`--live-streams`) design; a persistent capability-link store; a control plane that can start runs |
-| Off-app comms | Vendor-neutral in-sandbox email/SMS catch, a minimal persona inbox surface, and digest-only `humanish.comms-thread.v1` evidence; wired into the computer-use and shared-world routes and live-proven on computer-use | An adopter-hosted / app-url ingress plane; real-provider delivery |
+| Off-app comms | Vendor-neutral in-sandbox email/SMS catch, a minimal persona inbox surface, and digest-only `humanish.comms-thread.v1` evidence; wired into the computer-use and shared-world routes over both HTTP and SMTP; live-proven end to end on 2026-08-08 — a persona signed up for a public app, read the emailed link in its inbox, and reached the signed-in product (`docs/goals/email-gated-signup/receipts/signup-verify-live-2026-08-08.md`) | An adopter-hosted / app-url ingress plane; real-provider delivery |
 
 Capability proof and adopter replacement are different gates. A deterministic
 test or kept live receipt proves that a Humanish mechanism works. The depth-axis

package/docs/principles/three-roles.md

@@ -0,0 +1,68 @@
+# Three roles: researcher, stakeholder, participant
+
+Humanish runs user research. Every design decision should be checked against the
+three people a study actually involves, because they want different things and
+conflating any two of them produces a specific, recurring class of bug.
+
+## The roles
+
+**The researcher** designs the study and runs it. In humanish this is usually an
+agent invoking the CLI, not a person clicking. A researcher wants a protocol they
+can express and defend: tasks with success criteria, a panel with declared
+coverage, a pilot before the panel spends, and structured per-task outcomes back.
+They care about rigor and control, and they need output they can reason over and
+adjust.
+
+**The stakeholder** watches. In a real study they sit behind the glass in the
+viewing room; here they open Observer, `watch`, or `serve`. They want none of the
+protocol. They want to know what happened, where people got stuck, how bad it is,
+and whether anyone succeeded — moments, severity, and the denominator.
+
+**The participant** is the persona. They have a goal, limited patience, and their
+own idea of how the product works. They are the subject of the study, never its
+instrument.
+
+## Why the distinction earns its place
+
+Two of humanish's worst bugs were category errors between these roles, not
+missing features.
+
+**Fusing the participant into the harness** made abandonment look like a
+malfunction. `gave_up` mapped to a `failed` status, so a persona giving up — the
+single most valuable thing a usability study produces — dragged the run verdict
+red as though the instrument had broken. A participant abandoning a task is a
+finding. The harness only fails when the harness fails.
+
+**Fusing the researcher's question with the stakeholder's** put one pass/fail
+verdict on a bundle that answers two different questions. "Is this evidence
+trustworthy?" is genuinely pass/fail: did the harness do what it claimed, with a
+real sandbox, real actions, and cost lines nobody forged. "What did we learn?" has
+no pass/fail at all — asking whether a study passed is a category error. Because
+there was one slot, a session that stopped early had to be called `passed`, and a
+truncated study was reported as a green one.
+
+## Checks worth applying
+
+When adding a surface, a default, or a verdict, ask:
+
+- **Which role is this for?** A knob that serves the researcher does not belong in
+  the stakeholder's view, and a highlight reel is not evidence.
+- **Is this a participant outcome or a harness outcome?** Abandonment, confusion,
+  and running out of session are things that happened to a participant. Only a
+  broken sandbox, a forged artifact, or an unreachable service is a harness
+  failure.
+- **Does the number travel with its denominator?** A stakeholder behind glass
+  forms conclusions from vivid moments; that is the classic failure of the viewing
+  room, and it is why researchers synthesize rather than letting the room decide.
+  Anything shown to a stakeholder carries its count and its confidence, or it
+  becomes a machine for manufacturing certainty from n=1.
+- **Would a researcher recognize this as a study?** Budgets are recruiting
+  decisions made once, up front — how many participants can we afford. No
+  researcher has ever ended a session because it got expensive.
+
+## Related
+
+- [invariants-and-defaults.md](invariants-and-defaults.md) — fail-closed rules and
+  what defaults are allowed to assume
+- [actor-fidelity.md](actor-fidelity.md) — what a claim about persona realism can
+  and cannot mean

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.39.0` (2026-08-08). The containment boundary introduced in
+Package/source version in this tree: `0.40.0` (2026-08-08). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [