humanish 0.109.1 → 0.110.1

package/dist/run/stored-runs.js

@@ -1,148 +1,17 @@
 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) {
-    const base = { provider: resource.provider, kind: resource.kind, id: resource.id };
-    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);
@@ -207,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) {
@@ -225,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,
@@ -270,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/run-study.js

@@ -19,6 +19,7 @@ import {} from "./routes/shared-world/types.js";
 import { admitTerminalPlan, terminalStudyRefusal } from "./routes/terminal/route.js";
 import {} from "./routes/terminal/types.js";
 import {} from "./run/bundle.js";
+import { publicRunResult } from "./run/sandbox-ids.js";
 import { isLocalBrowserStudy, localBrowserDefaults } from "./substrates/local/runtime-config.js";
 /**
  * Runs a study on its route. The options are checked against the route and mapped into the route's
@@ -100,7 +101,11 @@ export async function prepareStudy(config, options, deps = {}) {
                 // study, so a rebuilt one would leave the participants they start for no finally to close.
                 const outcome = await admitted.run(scorer);
                 outcome.result.warnings.push(...normalized.warnings);
-                return outcome;
+                // The result names each sandbox by digest; the raw ids stay in the run's receipts.
+                return {
+                    ...outcome,
+                    result: await publicRunResult(outcome.result, options.cwd),
+                };
             }
             finally {
                 await vm?.close();

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";
@@ -227,7 +228,7 @@ async function realEmailCheck(connection, keys, args) {
         message: name === null
             ? "The selected email connection is missing or invalid. Open Connections in the TUI."
             : !args.keyPresent(name)
-                ? `Missing ${name} for the selected email connection. Provide it through process env or --env-file. Authentication has not been checked.`
+                ? `Missing ${name} for the selected email connection. Provide it through process env or --dotenv. Authentication has not been checked.`
                 : "Fresh hosted inbox per participant. Local presence only; run humanish comms check --online to authenticate. Provider permissions/capacity and delivery remain untested.",
     };
 }
@@ -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.`,
@@ -300,7 +303,7 @@ function subjectEnvChecks(names, args) {
         ok: !!args.env[name]?.trim() || args.keyPresent(name),
         message: args.env[name]?.trim() || args.keyPresent(name)
             ? "present; value not shown"
-            : "missing declared subject environment variable; provide it with --env-file",
+            : "missing declared subject environment variable; provide it with --dotenv",
     }));
 }
 /** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */

package/dist/study/init-templates.js

@@ -245,9 +245,9 @@ title: Computer-use browser study
 description: >-
   A computer-use participant drives your app in a hosted desktop browser and writes its evidence
   to gitignored .humanish/. Starts as a dry run. For a live session, set mode to live
-  and pass OPENAI_API_KEY and E2B_API_KEY with --env-file. The clone subject below serves your
+  and pass OPENAI_API_KEY and E2B_API_KEY with --dotenv. The clone subject below serves your
   repo inside the sandbox, and the env names declared under subject get their values from
-  --env-file without the values being saved. Screenshots keep full fidelity by default; set
+  --dotenv without the values being saved. Screenshots keep full fidelity by default; set
   policies.redactScreenshots: true to blur them at capture for a bundle you can share as is.
   Typed text is recorded as its length only.
 route: computer-use

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/study/types.d.ts

@@ -239,7 +239,7 @@ export interface StudySubject {
     serve?: StudySubjectServe;
     /**
      * Env var names the subject app needs, provisioned into the sandbox from the caller's
-     * environment (--env-file). Names are recorded in evidence; values never are. Consumed
+     * environment (--dotenv). Names are recorded in evidence; values never are. Consumed
      * on the computer-use clone route.
      */
     env?: string[];

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 {};

package/dist/substrates/e2b/peer-install.js

@@ -0,0 +1,161 @@
+// How to add the optional @e2b/desktop peer depends on where humanish itself is installed: Node
+// resolves the peer from humanish's own directory, not from the project a command runs in. Advice
+// for the wrong place installs a copy Node never reads, and `npm i` in a directory whose manifest
+// does not declare what its node_modules holds prunes it, so a command names only a project whose
+// package.json declares humanish, or npm's or pnpm's global directory.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const NODE_MODULES = `${sep}node_modules${sep}`;
+/** The install `modulePath` belongs to. */
+export function classifyHumanishInstall(modulePath, context) {
+    const { cwd } = context;
+    const segments = modulePath.split(sep);
+    if (segments.includes("_npx") || segments.includes("dlx"))
+        return { kind: "one-shot", unmanagedCwd: context.unmanaged(cwd) };
+    if (modulePath.includes(`${sep}pnpm${sep}global${sep}`))
+        return { kind: "global", manager: "pnpm" };
+    const at = modulePath.indexOf(NODE_MODULES);
+    if (at < 0)
+        return { kind: "checkout" };
+    // The first node_modules is the project's; pnpm keeps humanish's files deeper, in .pnpm.
+    const root = modulePath.slice(0, at);
+    if (root === context.npmGlobalRoot)
+        return { kind: "global", manager: "npm" };
+    if (cwd === root || cwd.startsWith(`${root}${sep}`)) {
+        const manager = modulePath.includes(`${NODE_MODULES}.pnpm${sep}`) ? "pnpm" : "npm";
+        // A workspace member declares humanish in its own package.json, and the root may not.
+        for (let directory = cwd, up = 0;; directory = dirname(directory), up += 1) {
+            if (context.declaresHumanish(directory))
+                return { kind: "project", up, manager };
+            if (directory === root)
+                break;
+        }
+    }
+    return { kind: "other", unmanagedCwd: context.unmanaged(cwd) };
+}
+/** The `prefix` an npmrc file sets, with `~` and `$HOME` expanded; undefined when it sets none. */
+function npmrcPrefix(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const value = /^\s*prefix\s*=\s*(.+?)\s*$/m.exec(text)?.[1];
+    if (value === undefined)
+        return undefined;
+    return value
+        .replace(/^~(?=$|[\\/])/, homedir())
+        .replace(/\$\{?HOME\}?/g, homedir())
+        .replace(/^"(.*)"$/, "$1");
+}
+/**
+ * The global root npm installs to from this environment, by npm's own order: the prefix in the
+ * environment, then the user, global and built-in npmrc files (Homebrew sets it in the built-in
+ * one), then the prefix the Node binary implies.
+ */
+function npmGlobalRoot() {
+    const windows = process.platform === "win32";
+    const nodePrefix = windows ? dirname(process.execPath) : dirname(dirname(process.execPath));
+    const prefix = process.env.npm_config_prefix ||
+        process.env.NPM_CONFIG_PREFIX ||
+        npmrcPrefix(process.env.NPM_CONFIG_USERCONFIG || join(homedir(), ".npmrc")) ||
+        npmrcPrefix(process.env.NPM_CONFIG_GLOBALCONFIG || join(nodePrefix, "etc", "npmrc")) ||
+        npmrcPrefix(windows
+            ? join(nodePrefix, "node_modules", "npm", "npmrc")
+            : join(nodePrefix, "lib", "node_modules", "npm", "npmrc")) ||
+        nodePrefix;
+    return windows ? prefix : join(prefix, "lib");
+}
+function declaresHumanish(directory) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+        return ["dependencies", "devDependencies", "optionalDependencies"].some((field) => {
+            const declared = manifest[field];
+            return typeof declared === "object" && declared !== null && "humanish" in declared;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `npm i` from `directory` would install into a node_modules no package.json declares: npm
+ * installs into the nearest directory, this one or above, that holds either.
+ */
+function unmanaged(directory) {
+    for (let current = directory;; current = dirname(current)) {
+        if (existsSync(join(current, "package.json")))
+            return false;
+        if (existsSync(join(current, "node_modules")))
+            return true;
+        if (dirname(current) === current)
+            return false;
+    }
+}
+/** The running humanish's install, from this file's real path. */
+export function humanishInstall(cwd = process.cwd()) {
+    return classifyHumanishInstall(fileURLToPath(import.meta.url), {
+        cwd,
+        npmGlobalRoot: npmGlobalRoot(),
+        declaresHumanish,
+        unmanaged,
+    });
+}
+/**
+ * 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 function desktopPeerAdvice(install, spec = "@e2b/desktop") {
+    const both = `npm i -D humanish ${spec}`;
+    const relativeTo = "Node resolves the peer relative to humanish itself, so";
+    switch (install.kind) {
+        case "project": {
+            // A directory option, not `cd`: one command, and no `&&` for Windows PowerShell 5.1.
+            const ups = Array.from({ length: install.up }, () => "..").join("/");
+            const command = install.manager === "pnpm"
+                ? `pnpm add -D ${ups ? `--dir ${ups} ` : ""}${spec}`
+                : `npm i -D ${ups ? `--prefix ${ups} ` : ""}${spec}`;
+            const place = ups ? "the project above this directory" : "this project";
+            return {
+                where: "",
+                command,
+                advice: `Install it beside humanish in ${place}: \`${command}\`.`,
+            };
+        }
+        case "global": {
+            const command = install.manager === "pnpm" ? `pnpm add -g ${spec}` : `npm i -g ${spec}`;
+            return {
+                where: ", and humanish is installed globally",
+                command,
+                advice: `${relativeTo} install it globally too: \`${command}\`. That reaches humanish while ` +
+                    "the global directory is still the one it was installed in.",
+            };
+        }
+        case "checkout":
+            return {
+                where: ", and humanish is running from a source checkout",
+                command: "pnpm install",
+                advice: spec === "@e2b/desktop"
+                    ? "Run `pnpm install` in the humanish checkout, which installs it as a dev dependency."
+                    : `Set ${spec} in the humanish checkout's package.json, then run \`pnpm install\` there.`,
+            };
+        case "one-shot":
+        case "other": {
+            const where = install.kind === "one-shot"
+                ? ", and humanish is running from an npx or pnpm dlx cache"
+                : ", and humanish is installed outside this project";
+            const run = `\`${both}\` then \`npx humanish run <study>\``;
+            return {
+                where,
+                command: both,
+                advice: install.unmanagedCwd
+                    ? `${relativeTo} it has to be installed with humanish. From here npm would install into a node_modules folder that no package.json declares, and \`npm i\` would remove what it holds. In your project's directory, run ${run}.`
+                    : `${relativeTo} a copy installed here is not found. Install both into this project and run that copy: ${run}.`,
+            };
+        }
+    }
+}