humanish 0.110.0 → 0.110.1

package/dist/run/status.d.ts

@@ -20,9 +20,9 @@ export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 interface RunStatusOutcome {
     /** `review.verdict` verbatim. */
     verdict?: string;
-    /** True when the run's own envelope reported success: the result's ok, recorded after finish. */
+    /** run.json's `outcome.ok`: the route result's ok. */
     ok?: boolean;
-    /** Whether the run worked as an execution, apart from its verdict; recorded after finish. */
+    /** run.json's `outcome.execution`: whether the run worked as an execution, apart from its verdict. */
     execution?: ExecutionOutcome;
     /** `review.participants` counts, when the run recorded any. */
     participants?: {
@@ -72,14 +72,11 @@ export interface RunStatusHandle {
     /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
      *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
-    /** After finish, add the result's ok and execution outcome to the finished record, so status.json
-     *  and the result agree. Before finish it does nothing. */
-    settle(result: {
-        ok: boolean;
-        execution: ExecutionOutcome;
-    }): Promise<void>;
+    /** After finish, replace the finished record's outcome with one read from a rewritten run.json,
+     *  so the two agree. Before finish, and after an interrupt, it does nothing. */
+    restate(outcome: RunStatusOutcome): Promise<void>;
     /** The process is being stopped by `signal`: state `interrupted`, `completedAt` and the signal.
-     *  It stops the cadence and makes a later finish or settle a no-op, so the route cannot write
+     *  It stops the cadence and makes a later finish or restate a no-op, so the route cannot write
      *  `running` or `finished` over it. When the run had finished it writes nothing, waits for the
      *  writes already queued and resolves false. */
     interrupt(signal: RunInterruptSignal): Promise<boolean>;

package/dist/run/status.js

@@ -4,15 +4,14 @@
 //
 // run.json remains the evidence of record. This file is a derived index and liveness record:
 // `verify` never gates on it, nothing here is a claim about what a participant did, and when the
-// two disagree run.json wins and this file can be rebuilt from it.
+// two disagree run.json wins. A finished record copies run.json's outcome, so it can be rebuilt
+// from it; a record written before run.json carried an outcome holds the only copy of the run's ok.
 //
 // Public safety: it holds only the run id, the study id/path/origin (the strings `humanish study list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
 import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
-import { redactText } from "../evidence/redaction.js";
-import { readRunSandboxIds, scrubSandboxIds } from "./sandbox-ids.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
 /** The file, relative to the run directory. */
 export const RUN_STATUS_FILE = "status.json";
@@ -46,6 +45,9 @@ export function runStatusOutcome(bundle) {
         ...(typeof bundle.cost?.fullyEstimated === "boolean"
             ? { estimatedCostComplete: bundle.cost.fullyEstimated }
             : {}),
+        ...(bundle.outcome?.state === "finished"
+            ? { ok: bundle.outcome.ok, execution: bundle.outcome.execution }
+            : {}),
     };
 }
 /**
@@ -103,28 +105,10 @@ export function beginRunStatus(runPaths, options) {
             };
             await write(finishedRecord);
         },
-        async settle(result) {
+        async restate(outcome) {
             if (finishedRecord === undefined)
                 return;
-            // The record is public-safe by construction, so each message passes the shape redaction
-            // again even though the routes scrubbed it. A route settles with its own result, so an SDK
-            // error here can still name a sandbox; the receipts give the ids to replace.
-            const ids = await readRunSandboxIds(runPaths);
-            const redacted = (failure) => ({
-                kind: failure.kind,
-                message: scrubSandboxIds(redactText(failure.message), ids),
-            });
-            const execution = {
-                succeeded: result.execution.succeeded,
-                failures: result.execution.failures.map(redacted),
-                ...(result.execution.warnings === undefined
-                    ? {}
-                    : { warnings: result.execution.warnings.map(redacted) }),
-            };
-            finishedRecord = {
-                ...finishedRecord,
-                outcome: { ...finishedRecord.outcome, ok: result.ok, execution },
-            };
+            finishedRecord = { ...finishedRecord, outcome };
             await write(finishedRecord);
         },
         async interrupt(signal) {

package/dist/run/stored-runs.d.ts

@@ -1,18 +1,7 @@
-import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
-import { type ReviewSummary, type RunBundle } from "./bundle.js";
-import { type CleanupAdapterResult, type CleanupResult } from "./results.js";
+import { type ReviewSummary } from "./bundle.js";
+import { type RunDisplay } from "./display.js";
 import { type VerifyResult } from "../verify/verify.js";
 declare const RUNS_SCHEMA = "humanish.runs-result.v1";
-export interface RunCleanupHooks {
-    /** @deprecated Ignored. Stored provider ids are not authority to load or mutate a provider. */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    cleanupAdapterResources?: (ctx: {
-        cwd: string;
-        runDir: string;
-        bundle: RunBundle;
-    }) => Promise<CleanupAdapterResult[]>;
-    now?: () => Date;
-}
 export interface RunsResult {
     schema: typeof RUNS_SCHEMA;
     ok: boolean;
@@ -22,6 +11,8 @@ export interface RunsResult {
         createdAt: string | null;
         mode: string | null;
         path: string;
+        /** How the run reads (runDisplay in src/run/display.ts); absent when it has no readable run.json. */
+        display?: RunDisplay;
     }>;
     latest: string | null;
     error?: {
@@ -29,10 +20,10 @@ export interface RunsResult {
         message: string;
     };
 }
-export declare function cleanupRun(cwdInput: string, runInput: string, hooks?: RunCleanupHooks): Promise<CleanupResult>;
 export declare function listRuns(cwdInput: string): Promise<RunsResult>;
 export declare function readReview(cwdInput: string, runInput: string): Promise<VerifyResult | (ReviewSummary & {
     path: string;
     runId: string;
+    display?: RunDisplay;
 })>;
 export {};

package/dist/run/stored-runs.js

@@ -1,157 +1,17 @@
-import { REDACTED_SANDBOX_ID, sandboxIdDigest } from "../evidence/redaction.js";
 import { lstat, readdir } from "node:fs/promises";
-import { runNotFoundMessage } from "./run-not-found.js";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
-import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, validatePreparedRunArtifactPaths, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputFile, readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
-import { CLEANUP_SCHEMA, } from "./results.js";
-import { isReviewSummary, isRunBundle } from "./bundle-shape.js";
+import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, } from "./contained-output.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
+import { bundleDisplayFacts, runDisplay } from "./display.js";
+import { RUN_STATUS_FILE } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 import { invalidRunStorageVerifyResult, verifyResolvedRun, } from "../verify/verify.js";
 const RUNS_SCHEMA = "humanish.runs-result.v1";
-/** A cleanup result that refused before inspecting any resource. */
-function cleanupRefusal(cwd, runInput, checkedAt, error, bundlePath) {
-    return {
-        schema: CLEANUP_SCHEMA,
-        ok: false,
-        cwd,
-        run: runInput,
-        ...(bundlePath === undefined ? {} : { bundlePath }),
-        checkedAt,
-        summary: { resources: 0, killed: 0, alreadyClean: 0, failed: 0, skipped: 0 },
-        resources: [],
-        adapterResults: [],
-        warnings: [],
-        error,
-    };
-}
-/** What the recorded evidence says about one provider resource; nothing is killed from here. */
-function recordedResourceResult(resource) {
-    // Named by digest: a run recorded before 0.110 holds the raw id here, which is digested.
-    const raw = resource.id === REDACTED_SANDBOX_ID ? undefined : resource.id;
-    const idDigest = resource.idDigest ?? (raw === undefined ? undefined : sandboxIdDigest(raw));
-    const base = {
-        provider: resource.provider,
-        kind: resource.kind,
-        id: REDACTED_SANDBOX_ID,
-        ...(idDigest === undefined ? {} : { idDigest }),
-    };
-    if (resource.provider !== "e2b-desktop" || resource.kind !== "sandbox") {
-        return {
-            ...base,
-            status: "skipped",
-            message: "cleanup only supports e2b-desktop sandbox resources",
-        };
-    }
-    if (resource.status === "killed" || resource.cleanup?.killed === true) {
-        return {
-            ...base,
-            status: "already_clean",
-            message: "resource was already recorded as killed",
-        };
-    }
-    return {
-        ...base,
-        status: "failed",
-        message: "automatic provider cleanup requires a verified resource lease",
-    };
-}
-export async function cleanupRun(cwdInput, runInput, hooks = {}) {
-    const cwd = path.resolve(cwdInput);
-    const checkedAt = (hooks.now ?? (() => new Date()))().toISOString();
-    let resolved;
-    try {
-        resolved = await resolveRunPath(cwd, runInput);
-    }
-    catch {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_INVALID_RUN_BUNDLE",
-            message: "Run storage failed containment validation.",
-        });
-    }
-    if (!resolved) {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_RUN_NOT_FOUND",
-            message: await runNotFoundMessage(cwd, runInput),
-        });
-    }
-    const runPaths = resolved;
-    const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const cleanupPath = path.join(runPaths.absoluteRunRoot, "cleanup.json");
-    await prepareContainedOutputFile(runPaths, "cleanup.json");
-    const bundleBytes = await readContainedRegularFile(runPaths, RUN_BUNDLE_FILE);
-    let bundle = null;
-    if (bundleBytes) {
-        try {
-            bundle = JSON.parse(bundleBytes.toString("utf8"));
-        }
-        catch {
-            bundle = null;
-        }
-    }
-    if (!isRunBundle(bundle)) {
-        return cleanupRefusal(cwd, runInput, checkedAt, {
-            code: "HUMANISH_INVALID_RUN_BUNDLE",
-            message: "Run bundle failed cleanup shape validation.",
-        }, path.relative(cwd, bundlePath));
-    }
-    const warnings = [];
-    const providerResources = bundle.providerResources ?? [];
-    const resources = providerResources.map(recordedResourceResult);
-    let adapterResults = [];
-    if (hooks.cleanupAdapterResources) {
-        try {
-            adapterResults = await hooks.cleanupAdapterResources({
-                cwd,
-                runDir: runPaths.physicalRunRoot,
-                bundle,
-            });
-        }
-        catch (error) {
-            adapterResults = [
-                {
-                    id: "adapter-cleanup",
-                    ok: false,
-                    message: error instanceof Error ? error.message : String(error),
-                },
-            ];
-        }
-        await validatePreparedRunArtifactPaths(runPaths);
-    }
-    if (providerResources.length === 0 && adapterResults.length === 0) {
-        warnings.push("Run bundle recorded no provider resource evidence; nothing to inspect.");
-    }
-    const summary = {
-        resources: resources.length,
-        killed: 0,
-        alreadyClean: resources.filter((resource) => resource.status === "already_clean").length,
-        failed: resources.filter((resource) => resource.status === "failed").length +
-            adapterResults.filter((result) => !result.ok).length,
-        skipped: resources.filter((resource) => resource.status === "skipped").length,
-    };
-    const ok = summary.failed === 0;
-    const result = {
-        schema: CLEANUP_SCHEMA,
-        ok,
-        cwd: PUBLIC_TARGET_CWD,
-        run: runInput,
-        runId: bundle.runId,
-        bundlePath: path.relative(cwd, bundlePath),
-        cleanupPath: path.relative(cwd, cleanupPath),
-        checkedAt,
-        summary,
-        resources,
-        adapterResults,
-        warnings,
-    };
-    await validatePreparedRunArtifactPaths(runPaths);
-    await writeContainedOutputFile(runPaths, "cleanup.json", `${JSON.stringify(result, null, 2)}\n`, "utf8");
-    return result;
-}
 export async function listRuns(cwdInput) {
     const cwd = path.resolve(cwdInput);
     const runsRootPath = resolveRunsRoot(cwd);
@@ -216,6 +76,7 @@ export async function listRuns(cwdInput) {
             createdAt: isRecord(bundle) && typeof bundle.createdAt === "string" ? bundle.createdAt : null,
             mode: isRecord(bundle) && typeof bundle.mode === "string" ? bundle.mode : null,
             path: path.join(RUNS_RELATIVE_ROOT, entryName),
+            ...(await listedRunDisplay(entryRunPaths, bundle)),
         });
     }
     if (runsRoot) {
@@ -234,6 +95,29 @@ export async function listRuns(cwdInput) {
         latest: latest?.runId ?? null,
     };
 }
+/**
+ * A listed run's display, from its run.json and, for a bundle without an outcome, its status
+ * record. Like the listing's other fields it reads the file without verifying it; a run.json
+ * that is not an object naming a run gets none.
+ */
+async function listedRunDisplay(runPaths, bundle) {
+    if (!isRecord(bundle) || typeof bundle.runId !== "string")
+        return {};
+    const outcome = isRunOutcome(bundle.outcome) ? bundle.outcome : undefined;
+    const status = outcome === undefined ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE) : undefined;
+    const facts = bundleDisplayFacts({
+        runId: bundle.runId,
+        ...(typeof bundle.mode === "string" ? { mode: bundle.mode } : {}),
+        ...(isRecord(bundle.review) && typeof bundle.review.verdict === "string"
+            ? { review: { verdict: bundle.review.verdict } }
+            : {}),
+        ...(Array.isArray(bundle.simulations)
+            ? { simulations: bundle.simulations.filter(isRecord) }
+            : {}),
+        ...(outcome === undefined ? {} : { outcome }),
+    }, status);
+    return { display: runDisplay(facts) };
+}
 function runsUnavailableResult(cwd, error) {
     return {
         schema: RUNS_SCHEMA,
@@ -279,5 +163,6 @@ export async function readReview(cwdInput, runInput) {
         ...projected,
         path: path.relative(cwd, path.join(runPaths.absoluteRunRoot, "review.json")),
         runId: path.basename(runPaths.absoluteRunRoot),
+        ...(runPaths ? await listedRunDisplay(runPaths, bundle) : {}),
     };
 }

package/dist/run/streams.d.ts

@@ -171,8 +171,9 @@ export interface RunStream {
     /**
      * The judge's status for this participant (`judgedStatus` in src/run/judge.ts). It differs from
      * the trace status when a goal_satisfied session reported a blocker or never engaged. Computer-use
-     * fan-out writes it for a finished live participant; rerun selection reads it. Absent elsewhere,
-     * and in bundles written before it existed.
+     * and shared-world runs write it for a participant whose session finished; rerun selection and
+     * the Observer read it. Absent on the terminal and scripted routes, whose judge has no blocker
+     * rule, and in bundles written before it existed.
      */
     judgedStatus?: ActorStatus;
     transport: "snapshot" | "polling" | "sse" | "pty" | "app-server";

package/dist/study/doctor.d.ts

@@ -1,7 +1,7 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import type { StudyConfig } from "./types.js";
 import type { PlanResult } from "./plan-types.js";
-import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
+import { type DetectedLocalAgent } from "../actors/local-agent/cli.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { DoctorCheckDraft } from "../cli/doctor.js";
 import { type CodexInstallation } from "../actors/codex/codex-admission.js";

package/dist/study/doctor.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
+import { localAgentVersionRefusal } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
@@ -254,12 +255,14 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
         return [await hostedCodexParticipantCheck(args, config.actors[0])];
+    const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {
             name: "local participant authentication",
-            ok: agent?.authStatus === "authenticated",
+            ok: agent?.authStatus === "authenticated" && outdated === undefined,
             message: agent?.authStatus === "authenticated"
-                ? `${agent.label} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`
+                ? (outdated ??
+                    `${agent.label}${agent.version === undefined ? "" : ` ${agent.version}`} reports authenticated on the host. E2B supplies the desktop; no OpenAI API key is required for this participant.`)
                 : agent
                     ? `${agent.label} ${agent.authStatus === "unauthenticated" ? "reports not signed in" : "authentication could not be checked"}. Run \`${choice === "codex" ? "codex login status" : "claude auth status"}\`; sign in or update the CLI before running.`
                     : `${choice} is not on this process's PATH. Install and sign in to that CLI, or choose openai-computer-use with OPENAI_API_KEY.`,

package/dist/study/init.js

@@ -5,6 +5,7 @@ import { detectLocalAgents } from "../actors/local-agent/cli.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { DEFAULT_LOCAL_BROWSER_STARTER, runtimeDirectories, starterFilesFor, } from "./init-templates.js";
 import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
+import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { validateCwd } from "../run/project.js";
 import { pathExists, readTextIfExists, validateInitProjectPaths } from "./init-paths.js";
 import { planGitignore, planPackageJson } from "./init-plan.js";
@@ -270,6 +271,18 @@ function validateLocalBrowserStarter(input) {
         return { ok: false, message: "--local-mission must be 4,000 characters or fewer." };
     return { ok: true, value };
 }
+/**
+ * The first-run hint's peer install, ahead of `npx humanish`: beside humanish in its project, else
+ * humanish and the peer together here, where `npx humanish` then finds them. None where `npm i`
+ * would prune a node_modules that no package.json declares.
+ */
+function initDesktopPeerCommand(install) {
+    if (install.kind === "project")
+        return desktopPeerAdvice(install).command;
+    if ((install.kind === "one-shot" || install.kind === "other") && install.unmanagedCwd)
+        return undefined;
+    return "npm i -D humanish @e2b/desktop";
+}
 /**
  * What this machine can run, for the starter study and the next steps. Local CLI status is
  * classified without returning its output or reading its credential file. Provider keys go
@@ -297,10 +310,8 @@ async function firstRunEnvironment(env, cwd) {
     catch {
         hasDesktopSdk = false;
     }
-    const { fileURLToPath } = await import("node:url");
-    const here = fileURLToPath(import.meta.url);
     return {
-        installedInProject: here.startsWith(path.join(process.cwd(), "node_modules") + path.sep),
+        desktopPeerCommand: initDesktopPeerCommand(humanishInstall()),
         hasDesktopSdk,
         hasE2bKey: present("E2B_API_KEY"),
         hasProviderKey: present("OPENAI_API_KEY"),

package/dist/study/keys.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
+ * humanish.study.v3 file can set. A path below a leaf is not one: `scenario.ref`, where `scenario`
+ * is a string, and `review.analysis.question`, whose keys resolveAutomaticAnalysis checks.
+ */
+export declare function isStudyKeyPath(path: string): boolean;
+/**
+ * The dotted path of every key a humanish.study.v3 file can set, down to `depth` levels:
+ * `route`, `caps.maxUsd`, `participants.persona`. scripts/check-doc-study-fields.ts holds the
+ * study file reference to these paths.
+ */
+export declare function studyKeyPaths(depth: number): string[];
 /** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
 export declare function findUnknownV2Key(raw: unknown): string | undefined;
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */

package/dist/study/keys.js

@@ -230,6 +230,38 @@ const STUDY_KEYS = {
     defaults: V2_KEYS.defaults,
     comms: V2_KEYS.comms,
 };
+/**
+ * Whether a dotted key path, such as `caps.maxUsd` or `participants[0].persona`, names a key a
+ * humanish.study.v3 file can set. A path below a leaf is not one: `scenario.ref`, where `scenario`
+ * is a string, and `review.analysis.question`, whose keys resolveAutomaticAnalysis checks.
+ */
+export function isStudyKeyPath(path) {
+    let shape = STUDY_KEYS;
+    for (const segment of path.replaceAll(/\[\d*\]/g, "").split(".")) {
+        if (shape === true || !Object.hasOwn(shape, segment))
+            return false;
+        shape = shape[segment];
+    }
+    return true;
+}
+/**
+ * The dotted path of every key a humanish.study.v3 file can set, down to `depth` levels:
+ * `route`, `caps.maxUsd`, `participants.persona`. scripts/check-doc-study-fields.ts holds the
+ * study file reference to these paths.
+ */
+export function studyKeyPaths(depth) {
+    const paths = [];
+    const visit = (shape, prefix, level) => {
+        for (const [key, child] of Object.entries(shape)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            paths.push(path);
+            if (child !== true && level < depth)
+                visit(child, path, level + 1);
+        }
+    };
+    visit(STUDY_KEYS, "", 1);
+    return paths;
+}
 /** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
 export function findUnknownV2Key(raw) {
     return walk(raw, V2_KEYS, "", "study");

package/dist/study/persona.d.ts

@@ -26,6 +26,10 @@ export interface PersonaDirectives {
     /** Directives included in the prompt, not proof of behavioral adherence. */
     traitsApplied: string[];
 }
+/** The fields a persona file can set; any other warns and is not sent. The study file reference lists each. */
+export declare const PERSONA_FIELDS: Set<string>;
+/** The traits under `traits:` that become directives; any other warns and is not sent. */
+export declare const TRAIT_FIELDS: Set<string>;
 /** Legacy short fields keep their bounds, but every discarded value is diagnosed. */
 export declare function parseResolvedPersona(raw: unknown, fallback: {
     id: string;

package/dist/study/persona.js

@@ -9,7 +9,8 @@ export class PersonaConfigError extends Error {
     }
 }
 const LEVELS = ["low", "medium", "high"];
-const PERSONA_FIELDS = new Set([
+/** The fields a persona file can set; any other warns and is not sent. The study file reference lists each. */
+export const PERSONA_FIELDS = new Set([
     "schema",
     "id",
     "name",
@@ -18,7 +19,8 @@ const PERSONA_FIELDS = new Set([
     "traits",
     "constraints",
 ]);
-const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
+/** The traits under `traits:` that become directives; any other warns and is not sent. */
+export const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
 function cleanText(value) {
     return value
         .replace(/\r\n?/g, "\n")

package/dist/substrates/e2b/peer-install.d.ts

@@ -0,0 +1,51 @@
+type Manager = "npm" | "pnpm";
+/** Where the running humanish is installed, read from its own file's real path. */
+export type HumanishInstall = 
+/** The nearest package.json declaring humanish: the working directory's, or `up` levels above. */
+{
+    kind: "project";
+    up: number;
+    manager: Manager;
+}
+/** A one-shot runner's cache: `npx humanish` or `pnpm dlx humanish`. */
+ | {
+    kind: "one-shot";
+    unmanagedCwd: boolean;
+}
+/** The global directory npm installs to from here, or pnpm's global directory. */
+ | {
+    kind: "global";
+    manager: Manager;
+}
+/** A source checkout of humanish, run with node or tsx. */
+ | {
+    kind: "checkout";
+}
+/** Anywhere else, such as another project or a global prefix npm is not configured for here. */
+ | {
+    kind: "other";
+    unmanagedCwd: boolean;
+};
+export interface InstallContext {
+    cwd: string;
+    /** The directory npm's global installs go to from this environment. */
+    npmGlobalRoot: string;
+    /** Whether the package.json in `directory` declares humanish as a dependency. */
+    declaresHumanish: (directory: string) => boolean;
+    /** Whether `npm i` from `directory` installs into a node_modules no package.json declares. */
+    unmanaged: (directory: string) => boolean;
+}
+/** The install `modulePath` belongs to. */
+export declare function classifyHumanishInstall(modulePath: string, context: InstallContext): HumanishInstall;
+/** The running humanish's install, from this file's real path. */
+export declare function humanishInstall(cwd?: string): HumanishInstall;
+/**
+ * Where this humanish is installed, the command that puts `spec` (`@e2b/desktop`, or a version of
+ * it) where it will resolve, and that command as one or two sentences of advice.
+ */
+export declare function desktopPeerAdvice(install: HumanishInstall, spec?: string): {
+    where: string;
+    command: string;
+    advice: string;
+};
+export {};