humanish 0.105.0 → 0.106.0

package/dist/subject/local-tree-archive.js

@@ -0,0 +1,431 @@
+// Local working-tree packaging for `subject.source: local-tree`.
+//
+// Enumeration produces ONE file list that drives BOTH the tar archive and the
+// content digest (archiveSha256), so the digest can never diverge from what
+// actually gets packed. A prior in-house harness reimplemented exclusion in a
+// second, independent digest walker that could drift from what its tar
+// `--exclude` flags actually excluded; this file is deliberately designed so
+// that cannot happen: enumerateLocalTree() builds one entries array, and both
+// the hash and the tar file list are derived from that same array.
+//
+// See docs/goals/local-tree-subject/goal.md ("Packing design") for the full
+// contract implemented here. Node builtins only, no npm dependencies.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+/**
+ * Path segments that are always excluded, wherever they appear in a relPath,
+ * in both git and fallback enumeration modes. Not overridable by callers.
+ */
+// ".homun" stays denied: user trees may still carry runtime dirs from before the humanish rename.
+export const LOCAL_TREE_DENYLIST_PATH_SEGMENTS = [
+    ".git",
+    "node_modules",
+    ".humanish",
+    ".homun",
+];
+/**
+ * Basename glob patterns (single leading or trailing `*` only) that are always
+ * excluded, in both git and fallback enumeration modes. Not overridable by
+ * callers. This is a safety net for secret-shaped files that were never
+ * gitignored; in git mode `.gitignore` already handles the bulk (build output,
+ * caches).
+ */
+export const LOCAL_TREE_DENYLIST_BASENAME_PATTERNS = [
+    ".env*",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "id_rsa*",
+    "id_dsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    "*.keystore",
+    "*.jks",
+    "*.ppk",
+    "*.gpg",
+    "*.tfstate",
+    "terraform.tfstate.backup",
+    ".npmrc",
+    ".netrc",
+    ".dockercfg",
+    "kubeconfig",
+    "credentials.json",
+    "service-account.json",
+    "serviceAccount.json",
+    "service_account.json",
+    "secrets.json",
+    "secrets.yaml",
+    "secrets.yml",
+    "auth.json",
+];
+/** Default upload size cap: 256 MiB. */
+export const DEFAULT_LOCAL_TREE_MAX_ARCHIVE_BYTES = 256 * 1024 * 1024;
+/**
+ * Enumerate the packable entries of a local working tree.
+ *
+ * When root is a git work tree, the list is `git ls-files --cached --others
+ * --exclude-standard -z`: tracked files plus untracked-but-not-ignored files,
+ * honoring .gitignore exactly as git does. Entries that no longer exist on
+ * disk (staged deletes) are dropped, and entries that resolve to a directory
+ * on disk (a nested repo or worktree boundary) are dropped rather than
+ * recursed into.
+ *
+ * Otherwise, a recursive readdir walk applies only the always-on denylist
+ * plus extraExclude; .gitignore semantics require git, so this fallback is
+ * coarser by design.
+ *
+ * The always-on denylist is applied in both modes and is not overridable.
+ * The returned entries are sorted bytewise by relPath.
+ */
+export function enumerateLocalTree(root, options = {}) {
+    const resolvedRoot = path.resolve(root);
+    assertValidRoot(resolvedRoot);
+    const extraExclude = (options.extraExclude ?? []).map(normalizeExtraExcludeEntry);
+    if (isGitWorkTree(resolvedRoot)) {
+        const entries = enumerateGitTree(resolvedRoot, extraExclude);
+        const git = captureGitInfo(resolvedRoot);
+        return git ? { entries, git } : { entries };
+    }
+    const entries = [];
+    walkFallbackTree(resolvedRoot, "", extraExclude, entries);
+    entries.sort(compareEntriesByRelPath);
+    return { entries };
+}
+/**
+ * Enumerate a local working tree and pack it into a gzipped tar archive,
+ * computing archiveSha256 from the exact same entries list used for the tar
+ * file list.
+ *
+ * Fails closed when: the root is missing or not a directory; enumeration
+ * produces zero entries; or total packed bytes exceed maxArchiveBytes.
+ */
+export function createLocalTreeArchive(root, options = {}) {
+    const resolvedRoot = path.resolve(root);
+    const extraExclude = options.extraExclude ?? [];
+    const maxArchiveBytes = options.maxArchiveBytes ?? DEFAULT_LOCAL_TREE_MAX_ARCHIVE_BYTES;
+    const { entries, git } = enumerateLocalTree(resolvedRoot, extraExclude.length > 0 ? { extraExclude } : undefined);
+    if (entries.length === 0) {
+        throw new Error(`Local tree root "${path.basename(resolvedRoot)}" produced zero packable entries after the always-on denylist` +
+            (extraExclude.length > 0 ? " and extraExclude" : "") +
+            "; local-tree packing requires at least one non-denylisted file or symlink. (Paths in this message are basenames only; the packed root is the lab resolution cwd.)");
+    }
+    // Check the cap from enumerated sizes BEFORE reading/hashing file bytes, so
+    // an oversized tree fails closed without the cost of hashing all of it.
+    const enumeratedBytes = entries.reduce((sum, entry) => (entry.kind === "file" ? sum + entry.size : sum), 0);
+    if (enumeratedBytes > maxArchiveBytes) {
+        throw new Error(`Local tree archive for "${path.basename(resolvedRoot)}" is ${enumeratedBytes} bytes, exceeding maxArchiveBytes ` +
+            `(${maxArchiveBytes}); pass a larger maxArchiveBytes or exclude more paths via localTree.exclude.`);
+    }
+    const { archiveSha256, totalBytes } = computeArchiveSha256(resolvedRoot, entries);
+    let tempDir;
+    let archivePath;
+    if (options.outputPath) {
+        archivePath = path.resolve(options.outputPath);
+    }
+    else {
+        tempDir = mkdtempSync(path.join(tmpdir(), "humanish-local-tree-"));
+        archivePath = path.join(tempDir, "source.tar.gz");
+    }
+    mkdirSync(path.dirname(archivePath), { recursive: true });
+    try {
+        writeTarArchive(resolvedRoot, entries, archivePath);
+    }
+    catch (error) {
+        // A failed tar can leave a partial archive of the working tree; the temp dir is ours to remove.
+        if (tempDir !== undefined)
+            rmSync(tempDir, { recursive: true, force: true });
+        throw error;
+    }
+    const fileCount = entries.length;
+    return git
+        ? { archivePath, archiveSha256, fileCount, totalBytes, git }
+        : { archivePath, archiveSha256, fileCount, totalBytes };
+}
+function assertValidRoot(root) {
+    let stat;
+    try {
+        stat = statSync(root);
+    }
+    catch {
+        throw new Error(`Local tree root "${path.basename(root)}" does not exist or is not readable; local-tree packing requires an existing directory.`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Local tree root "${path.basename(root)}" is not a directory; local-tree packing requires a directory root.`);
+    }
+}
+function isGitWorkTree(root) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return out.toString("utf8").trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function gitListFiles(root) {
+    const out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+        cwd: root,
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const names = out
+        .toString("utf8")
+        .split("\0")
+        .filter((entry) => entry.length > 0);
+    // During an unresolved merge, `ls-files --cached` emits one entry per
+    // conflict stage for the same path; pack each path exactly once.
+    return [...new Set(names)];
+}
+function captureGitInfo(root) {
+    let commit;
+    try {
+        commit = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString("utf8")
+            .trim();
+    }
+    catch {
+        // Unborn HEAD (git init with no commit yet): the tree is still packable
+        // and .gitignore-aware, but there is no commit to pin and dirty is
+        // meaningless without one, so git info is simply absent.
+        return undefined;
+    }
+    // Pathspec-scoped to the packed root: `git status --porcelain` without a
+    // pathspec reports the WHOLE enclosing repository, which would report a
+    // clean packed subtree as dirty whenever an unrelated sibling package in a
+    // monorepo has in-progress changes.
+    const status = execFileSync("git", ["status", "--porcelain", "--", "."], {
+        cwd: root,
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+    }).toString("utf8");
+    return { commit, dirty: status.trim().length > 0 };
+}
+function enumerateGitTree(root, extraExclude) {
+    const entries = [];
+    for (const relPath of gitListFiles(root)) {
+        if (isPathDenylisted(relPath, extraExclude)) {
+            continue;
+        }
+        const absolutePath = path.join(root, relPath);
+        let stat;
+        try {
+            stat = lstatSync(absolutePath);
+        }
+        catch {
+            // Staged delete: git still tracks it, but it is gone from disk.
+            continue;
+        }
+        if (stat.isDirectory()) {
+            // A nested repo or worktree boundary enumerates as a single
+            // directory-shaped entry from git ls-files; never recurse into it.
+            continue;
+        }
+        if (stat.isSymbolicLink()) {
+            entries.push({ relPath, kind: "symlink", size: stat.size });
+            continue;
+        }
+        if (stat.isFile()) {
+            assertSingleLinkSourceFile(stat);
+            entries.push({ relPath, kind: "file", size: stat.size });
+        }
+    }
+    entries.sort(compareEntriesByRelPath);
+    return entries;
+}
+function walkFallbackTree(root, relDir, extraExclude, out) {
+    const absoluteDir = relDir ? path.join(root, relDir) : root;
+    const names = readdirSync(absoluteDir).sort();
+    for (const name of names) {
+        const relPath = relDir ? `${relDir}/${name}` : name;
+        if (isPathDenylisted(relPath, extraExclude)) {
+            continue;
+        }
+        const absolutePath = path.join(root, relPath);
+        const stat = lstatSync(absolutePath);
+        if (stat.isDirectory()) {
+            walkFallbackTree(root, relPath, extraExclude, out);
+            continue;
+        }
+        if (stat.isSymbolicLink()) {
+            out.push({ relPath, kind: "symlink", size: stat.size });
+            continue;
+        }
+        if (stat.isFile()) {
+            assertSingleLinkSourceFile(stat);
+            out.push({ relPath, kind: "file", size: stat.size });
+        }
+        // Sockets, fifos, and device files are silently skipped: neither a
+        // regular file nor a symlink, so out of scope for packing.
+    }
+}
+function basenameOf(relPath) {
+    return relPath.slice(relPath.lastIndexOf("/") + 1);
+}
+function matchesBasenamePattern(basename, pattern) {
+    if (pattern.endsWith("*")) {
+        return basename.startsWith(pattern.slice(0, -1));
+    }
+    if (pattern.startsWith("*")) {
+        return basename.endsWith(pattern.slice(1));
+    }
+    return basename === pattern;
+}
+function isDenylistedBasename(basename) {
+    return LOCAL_TREE_DENYLIST_BASENAME_PATTERNS.some((pattern) => matchesBasenamePattern(basename, pattern));
+}
+function isDenylistedSegment(relPath) {
+    const segments = relPath.split("/");
+    return segments.some((segment) => LOCAL_TREE_DENYLIST_PATH_SEGMENTS.includes(segment));
+}
+/**
+ * Normalize an author-supplied exclude entry to the relPath shape enumeration
+ * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
+ * are REJECTED, not silently no-op'd: an exclude the author believed in but
+ * that never matches anything is a leak vector, so unusable shapes fail
+ * closed at the packing boundary (and, for lab manifests, already at parse
+ * time in src/lab/parse/subject.ts).
+ */
+export function normalizeExtraExcludeEntry(entry) {
+    const trimmed = entry.trim();
+    if (trimmed.startsWith("/") || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        throw new Error(`localTree.exclude entry "${trimmed}" is an absolute path; entries must be repo-relative path prefixes or basenames (e.g. "big-media" or "fixtures/huge").`);
+    }
+    if (/[*?[\]]/.test(trimmed)) {
+        throw new Error(`localTree.exclude entry "${trimmed}" uses glob syntax, which is not supported; entries match as a repo-relative path prefix or an exact basename.`);
+    }
+    let normalized = trimmed;
+    while (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    while (normalized.endsWith("/"))
+        normalized = normalized.slice(0, -1);
+    if (normalized.length === 0) {
+        throw new Error(`localTree.exclude entry "${entry}" normalizes to an empty path.`);
+    }
+    return normalized;
+}
+function matchesExtraExclude(relPath, basename, extraExclude) {
+    return extraExclude.some((entry) => relPath === entry || relPath.startsWith(`${entry}/`) || basename === entry);
+}
+function isPathDenylisted(relPath, extraExclude) {
+    if (isDenylistedSegment(relPath)) {
+        return true;
+    }
+    const basename = basenameOf(relPath);
+    if (isDenylistedBasename(basename)) {
+        return true;
+    }
+    return matchesExtraExclude(relPath, basename, extraExclude);
+}
+/** Bytewise (UTF-8) comparison, independent of locale/platform string ordering. */
+function compareEntriesByRelPath(a, b) {
+    return Buffer.compare(Buffer.from(a.relPath, "utf8"), Buffer.from(b.relPath, "utf8"));
+}
+function assertSingleLinkSourceFile(stat) {
+    if (stat.nlink > 1) {
+        throw new Error("Local tree contains a hardlinked regular file; hardlinked source files are not packable.");
+    }
+}
+function validateEntryForRead(root, entry) {
+    let stat;
+    try {
+        stat = lstatSync(path.join(root, entry.relPath));
+    }
+    catch {
+        throw new Error("Local tree entry changed after enumeration; refusing to create an inconsistent archive.");
+    }
+    if (entry.kind === "symlink") {
+        if (!stat.isSymbolicLink()) {
+            throw new Error("Local tree entry changed kind after enumeration; refusing to create an inconsistent archive.");
+        }
+        return stat;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== entry.size) {
+        throw new Error("Local tree entry changed after enumeration; refusing to create an inconsistent archive.");
+    }
+    assertSingleLinkSourceFile(stat);
+    return stat;
+}
+function validateEntryIdentity(root, entry, expected) {
+    const current = validateEntryForRead(root, entry);
+    if (current.dev !== expected.dev || current.ino !== expected.ino) {
+        throw new Error("Local tree entry changed physical identity while being read; refusing to create an inconsistent archive.");
+    }
+}
+/**
+ * sha256 over the sorted sequence of records:
+ *   files:    kind\0relPath\0size\0<file bytes>\0
+ *   symlinks: kind\0relPath\0<link target string>\0
+ * Symlinks are never dereferenced: only their target path string is hashed,
+ * never bytes at the target.
+ */
+function computeArchiveSha256(root, entries) {
+    const hash = createHash("sha256");
+    let totalBytes = 0;
+    for (const entry of entries) {
+        const absolutePath = path.join(root, entry.relPath);
+        const expected = validateEntryForRead(root, entry);
+        if (entry.kind === "symlink") {
+            const target = readlinkSync(absolutePath);
+            validateEntryIdentity(root, entry, expected);
+            hash.update(`symlink\0${entry.relPath}\0${target}\0`);
+            continue;
+        }
+        const bytes = readFileSync(absolutePath);
+        validateEntryIdentity(root, entry, expected);
+        hash.update(`file\0${entry.relPath}\0${entry.size}\0`);
+        hash.update(bytes);
+        hash.update("\0");
+        totalBytes += entry.size;
+    }
+    return { archiveSha256: hash.digest("hex"), totalBytes };
+}
+function writeTarArchive(root, entries, archivePath) {
+    // Recheck immediately before tar reads the source tree. Enumeration and
+    // hashing already reject hardlinks; this closes the ordinary mutation gap
+    // between hashing and packing without dereferencing symlinks.
+    for (const entry of entries) {
+        validateEntryForRead(root, entry);
+    }
+    const listDir = mkdtempSync(path.join(tmpdir(), "humanish-local-tree-list-"));
+    const listFile = path.join(listDir, "files.list");
+    try {
+        writeFileSync(listFile, `${entries.map((entry) => entry.relPath).join("\0")}\0`);
+        const darwinArgs = process.platform === "darwin"
+            ? ["--disable-copyfile", "--no-xattrs", "--no-mac-metadata"]
+            : [];
+        // -C must precede -T: both are position-sensitive in GNU tar, and names
+        // read from -T resolve against the directory in effect at that point.
+        // bsdtar tolerates either order; GNU tar does not.
+        const args = [...darwinArgs, "-czf", archivePath, "-C", root, "--null", "-T", listFile];
+        try {
+            execFileSync("tar", args, { stdio: ["ignore", "ignore", "pipe"] });
+        }
+        catch (error) {
+            throw new Error(`Failed to create the local-tree tar archive: ${tarErrorTail(error)}`);
+        }
+    }
+    finally {
+        rmSync(listDir, { recursive: true, force: true });
+    }
+}
+function tarErrorTail(error) {
+    const stderr = error &&
+        typeof error === "object" &&
+        "stderr" in error &&
+        error.stderr instanceof Buffer
+        ? error.stderr.toString("utf8")
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return stderr.trim().slice(-400);
+}

package/dist/subject/local-tree.d.ts

@@ -0,0 +1,28 @@
+import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { RunSubjectStateStepRecord } from "../run/bundle.js";
+import { type DetachedTimers } from "../substrates/detached.js";
+import type { Shell } from "../substrates/shell.js";
+import { type SubjectPhaseEvent } from "./steps.js";
+/**
+ * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
+ * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
+ * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
+ * in-sandbox git refresh: the archive excludes .git entirely (see local-tree-archive.ts), so
+ * subject identity is the host-side LocalTreeArchive captured at pack time, never anything
+ * resolved in-sandbox.
+ */
+export declare function provisionLocalTreeSubject(shell: Shell, args: {
+    /** The once-per-run packed archive bytes (shared byte-identically across every lane). */
+    archiveBuffer: ArrayBuffer;
+    serve: LabSubjectServe;
+    /** Declared subject state (seed steps; external declaration is provenance-only). */
+    state?: LabSubjectState;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    /** Called the moment each state step finishes, success or failure. */
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    /** Called at each phase boundary (started/completed): upload, extract, install, build,
+     *  serve start, ready, and each subject.state seed-step group. */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+} & DetachedTimers): Promise<void>;

package/dist/subject/local-tree.js

@@ -0,0 +1,58 @@
+import { failureTail, toErrorMessage } from "../evidence/redaction.js";
+import { detachedTimersOf, runDetachedStep } from "../substrates/detached.js";
+import { runSubjectServePipeline } from "./serve.js";
+import { SOURCE_TIMEOUT_MS, emitPhaseCompleted, emitPhaseStarted, SUBJECT_DIR, } from "./steps.js";
+// Remote path for the once-per-run packed local-tree archive; removed by the extract step
+// after it unpacks into SUBJECT_DIR.
+const LOCAL_TREE_REMOTE_ARCHIVE_PATH = "/home/user/.humanish-source.tar.gz";
+/**
+ * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
+ * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
+ * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
+ * in-sandbox git refresh: the archive excludes .git entirely (see local-tree-archive.ts), so
+ * subject identity is the host-side LocalTreeArchive captured at pack time, never anything
+ * resolved in-sandbox.
+ */
+export async function provisionLocalTreeSubject(shell, args) {
+    const timers = detachedTimersOf(args);
+    const now = args.now ?? Date.now;
+    const uploadStartedAt = now();
+    emitPhaseStarted(args.onPhase, now, "upload", "uploading packed local-tree archive");
+    try {
+        await shell.writeFile(LOCAL_TREE_REMOTE_ARCHIVE_PATH, args.archiveBuffer, {
+            requestTimeoutMs: args.requestTimeoutMs,
+            retryOnce: {
+                onRetry: (reason) => emitPhaseStarted(args.onPhase, now, "upload-retry", `local-tree archive upload retried once (${failureTail(args.scrub(reason))})`),
+                ...(args.sleep === undefined ? {} : { sleep: args.sleep }),
+            },
+        });
+    }
+    catch (error) {
+        emitPhaseCompleted(args.onPhase, now, uploadStartedAt, "upload", false, "local-tree archive upload failed");
+        throw new Error(`subject-upload failed: ${failureTail(args.scrub(toErrorMessage(error)))}`);
+    }
+    emitPhaseCompleted(args.onPhase, now, uploadStartedAt, "upload", true, "local-tree archive uploaded");
+    const extractCommand = `rm -rf ${SUBJECT_DIR} && mkdir -p ${SUBJECT_DIR} && tar -xzf ${LOCAL_TREE_REMOTE_ARCHIVE_PATH} -C ${SUBJECT_DIR} && rm -f ${LOCAL_TREE_REMOTE_ARCHIVE_PATH}`;
+    const extractStartedAt = now();
+    emitPhaseStarted(args.onPhase, now, "extract", "extracting local-tree archive");
+    const extract = await runDetachedStep(shell, {
+        name: "subject-extract",
+        command: extractCommand,
+        timeoutMs: SOURCE_TIMEOUT_MS,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...timers,
+    });
+    emitPhaseCompleted(args.onPhase, now, extractStartedAt, "extract", extract.ok, extract.ok ? "local-tree archive extracted" : "local-tree archive extraction failed");
+    if (!extract.ok) {
+        throw new Error(`subject extract ${extract.timedOut ? "timed out" : `failed (exit ${extract.exitCode})`}: ${failureTail(args.scrub(extract.logTail))}`);
+    }
+    await runSubjectServePipeline(shell, {
+        serve: args.serve,
+        ...(args.state === undefined ? {} : { state: args.state }),
+        requestTimeoutMs: args.requestTimeoutMs,
+        scrub: args.scrub,
+        ...(args.onStateStep === undefined ? {} : { onStateStep: args.onStateStep }),
+        ...(args.onPhase === undefined ? {} : { onPhase: args.onPhase }),
+        ...timers,
+    });
+}

package/dist/subject/node-bootstrap.d.ts

@@ -0,0 +1,12 @@
+export declare const NODE_NPM_PREFIX_SCRIPT: string;
+/**
+ * The bound on one Node bootstrap attempt. The archive download is one curl with a 90 s limit and
+ * one retry inside 120 s; the rest is local. A step that outlives this is stuck, not slow.
+ */
+export declare const NODE_BOOTSTRAP_TIMEOUT_MS: number;
+/**
+ * Install Node from the pinned official archive when the desktop has no working Node >=20 and
+ * npm. The terminal lane, desktop CLI studies and the subject serve pipeline share it. It needs no
+ * apt: every network call is one bounded curl, so a stalled mirror fails the step within minutes.
+ */
+export declare const NODE_BOOTSTRAP_COMMAND: string;

package/dist/subject/node-bootstrap.js

@@ -0,0 +1,66 @@
+// Node 22 remains a supported LTS line. Pin the official release and trusted archive hashes:
+// https://nodejs.org/en/about/previous-releases
+// https://nodejs.org/dist/v22.23.2/SHASUMS256.txt (checked 2026-09-05)
+// A checksum fetched alongside the archive at runtime would not pin what we trust.
+const NODE_BOOTSTRAP_VERSION = "22.23.2";
+// npm normally derives its global prefix from the real Node executable. This distribution
+// lives under /opt, while its public executables use /usr/local/bin. Set only a missing
+// built-in default; npm's environment, CLI, user and global config still take precedence.
+export const NODE_NPM_PREFIX_SCRIPT = [
+    'const fs = require("node:fs");',
+    "const file = process.argv[1];",
+    'let existing = "";',
+    'try { existing = fs.readFileSync(file, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }',
+    'if (!/^[\\t ]*prefix[\\t ]*=/m.test(existing)) fs.appendFileSync(file, "\\nprefix=/usr/local\\n");',
+].join(" ");
+/**
+ * The bound on one Node bootstrap attempt. The archive download is one curl with a 90 s limit and
+ * one retry inside 120 s; the rest is local. A step that outlives this is stuck, not slow.
+ */
+export const NODE_BOOTSTRAP_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Install Node from the pinned official archive when the desktop has no working Node >=20 and
+ * npm. The terminal lane, desktop CLI studies and the subject serve pipeline share it. It needs no
+ * apt: every network call is one bounded curl, so a stalled mirror fails the step within minutes.
+ */
+export const NODE_BOOTSTRAP_COMMAND = [
+    "set -eu",
+    "# humanish node-bootstrap",
+    "node_major=0",
+    `if command -v node >/dev/null 2>&1; then node_major=$(node -e 'console.log(Number(process.versions.node.split(".")[0]))' 2>/dev/null || echo 0); fi`,
+    `if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 && [ "$node_major" -ge 20 ] && npm --version >/dev/null 2>&1; then`,
+    // An explicit exit under set -e runs the stock login shell's failing clear_console logout hook
+    // and turns this successful fast path into exit 1. Finish the compound command naturally.
+    "  :",
+    "else",
+    `case "$(uname -s):$(uname -m)" in`,
+    `  Linux:x86_64) node_arch=x64; node_sha=b294a556e639d64338823920e5866c21c02741742d2e1529ee1a225c1ec9252a ;;`,
+    `  Linux:aarch64|Linux:arm64) node_arch=arm64; node_sha=013b59cfd2819703a6f4a14ab891fc46fc2a4e3f5bcd92de3fb4929b43e35b30 ;;`,
+    `  *) echo 'humanish: the Node bootstrap requires a supported Linux x64/arm64 desktop or working Node >=20 and npm' >&2; exit 1 ;;`,
+    "esac",
+    "for prerequisite in curl sha256sum tar gzip mktemp sudo; do",
+    `  command -v "$prerequisite" >/dev/null 2>&1 || { echo "humanish: the Node bootstrap requires $prerequisite" >&2; exit 1; }`,
+    "done",
+    `node_archive="node-v${NODE_BOOTSTRAP_VERSION}-linux-$node_arch.tar.gz"`,
+    `node_target="/opt/humanish/node-v${NODE_BOOTSTRAP_VERSION}-linux-$node_arch"`,
+    `node_temp=$(mktemp -d /tmp/humanish-node.XXXXXX)`,
+    `trap 'rm -rf "$node_temp"' EXIT`,
+    `curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 90 --retry 1 --retry-max-time 120 --output "$node_temp/$node_archive" "https://nodejs.org/dist/v${NODE_BOOTSTRAP_VERSION}/$node_archive"`,
+    `(cd "$node_temp" && printf '%s  %s\\n' "$node_sha" "$node_archive" | sha256sum --check --status) || { echo 'humanish: the Node archive checksum did not match the trusted release' >&2; exit 1; }`,
+    // Only a verified official archive reaches privileged extraction. The versioned install is
+    // root-owned; subsequent ordinary and sudo shells find it through standard /usr/local/bin.
+    "sudo -n mkdir -p /opt/humanish /usr/local/bin",
+    `sudo -n tar --extract --gzip --file "$node_temp/$node_archive" --directory /opt/humanish --no-same-owner`,
+    "for executable in node npm npx; do",
+    `  sudo -n ln -sfn "$node_target/bin/$executable" "/usr/local/bin/$executable"`,
+    "done",
+    // Keep global product executables on the existing ordinary/sudo PATH (#679). The new
+    // versioned distribution is the only config we modify; no user/global npmrc or profile.
+    `sudo -n "$node_target/bin/node" -e '${NODE_NPM_PREFIX_SCRIPT}' "$node_target/lib/node_modules/npm/npmrc"`,
+    "hash -r",
+    `node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 20 ? 0 : 1)' && npm --version >/dev/null`,
+    // Product installation already uses sudo; detect a template whose sudo PATH cannot see Node
+    // rather than changing global PATH or permissions to make it look supported.
+    `sudo -n node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 20 ? 0 : 1)' && sudo -n npm --version >/dev/null`,
+    "fi",
+].join("\n");

package/dist/subject/runtime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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;
+/**
+ * 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,50 @@
+// 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));
+}
+/**
+ * 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");
+}