@vibesdotdev/host-bun 0.0.0-stage → 1.0.0-rc.3

package/dist/schemas/test-environment.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Bun host's declared test environment options
+ * (`test-tooling/test-environment.impl.bun.ts`): the kernel's declared facts
+ * (`@vibesdotdev/execution-local/test-environment`) plus the Bun host services a
+ * booted declared host registers.
+ */
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import type { DeclaredTestEnvironmentOptions } from '@vibesdotdev/execution-local/test-environment';
+import type { BunEnvironmentOptions } from './environment.ts';
+export interface BunDeclaredTestEnvironmentOptions<TBindings extends object = object> extends DeclaredTestEnvironmentOptions<TBindings> {
+    /**
+     * Registers LocalDB's SQLite driver kind on the booted runtime; defaults to
+     * this host's `bun:sqlite` driver. A test that composes a driver itself
+     * hands a no-op.
+     */
+    sqliteDriver?: (runtime: RuntimeRef) => void;
+    /**
+     * Registers the host's `filesystem/adapter` kind and its adapter on the
+     * booted runtime; defaults to this host's own. A host with no filesystem
+     * passes a no-op: features that read host files through the kind refuse
+     * `UNAVAILABLE filesystem-adapter-not-registered`.
+     */
+    hostFileSystem?: (runtime: RuntimeRef) => void;
+    /** The host's file logging when booted as the environment plugin, as the Bun environment declares it; `{ files: false }` opts out. */
+    logging?: BunEnvironmentOptions['logging'];
+}
+//# sourceMappingURL=test-environment.d.ts.map

package/dist/schemas/test-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-environment.d.ts","sourceRoot":"","sources":["../../src/schemas/test-environment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,MAAM,WAAW,iCAAiC,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,8BAA8B,CAAC,SAAS,CAAC;IACtI;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7C;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IAC/C,sIAAsI;IACtI,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;CAC3C"}

package/dist/schemas/test-environment.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-environment.js.map

package/dist/schemas/test-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-environment.js","sourceRoot":"","sources":["../../src/schemas/test-environment.ts"],"names":[],"mappings":""}

package/dist/serve-stall-start.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Arms the serve stall watch as its own process. The serve thread cannot
+ * notice that it is inside `sqlite3_step`; a child stat of the pid file can.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { ServeStallWatch, ServeStallWatchOptions } from '@vibesdotdev/kernel/kinds/serve-stall.kind';
+export declare function startServeStallWatch(runtime: RuntimeRef, options: ServeStallWatchOptions): Promise<ServeStallWatch>;
+//# sourceMappingURL=serve-stall-start.d.ts.map

package/dist/serve-stall-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall-start.d.ts","sourceRoot":"","sources":["../src/serve-stall-start.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA2C,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAqC1G,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA2C1B"}

package/dist/serve-stall-start.js

@@ -0,0 +1,88 @@
+/**
+ * Arms the serve stall watch as its own process. The serve thread cannot
+ * notice that it is inside `sqlite3_step`; a child stat of the pid file can.
+ */
+import { CapabilityError, getRuntimeHostCommands } from '@vibesdotdev/kernel';
+import { getRuntimeExecution } from '@vibesdotdev/kernel/execution';
+import * as z from 'zod/v4';
+import WATCH_SOURCE from '../resources/serve-stall-watch.impl.bun.mjs' with { type: 'text' };
+import { serveStallBudgetMs } from "./serve-stall.js";
+const HostCwdSchema = z.string().min(1);
+const WatchOptionsSchema = z.object({
+    pidFile: z.string().min(1),
+    intervalMs: z.number().int().positive().safe(),
+    pid: z.number().int().positive().safe()
+});
+const READY = 'serve-stall-ready\n';
+function startupFailed() {
+    return new CapabilityError('Serve stall watch did not acknowledge startup.', 'UNAVAILABLE', {
+        reason: 'serve-stall-start-failed', retryable: false
+    });
+}
+async function acknowledgeStartup(child) {
+    if (!child.stdout)
+        throw startupFailed();
+    const reader = child.stdout.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    try {
+        while (text !== READY) {
+            const next = await reader.read();
+            if (next.done)
+                throw startupFailed();
+            text += decoder.decode(next.value, { stream: true });
+            if (!READY.startsWith(text))
+                throw startupFailed();
+        }
+    }
+    finally {
+        await reader.cancel();
+        reader.releaseLock();
+    }
+}
+export async function startServeStallWatch(runtime, options) {
+    const validated = WatchOptionsSchema.parse(options);
+    const cwd = HostCwdSchema.safeParse(runtime.localEnvironment.getCwd?.());
+    if (!cwd.success) {
+        throw new CapabilityError('Serve stall watch needs the host working directory.', 'UNAVAILABLE', {
+            reason: 'cwd-unavailable',
+            retryable: false
+        });
+    }
+    const execution = await getRuntimeExecution(runtime);
+    const script = (await getRuntimeHostCommands(runtime)).scriptRuntimeArgv();
+    const [command, ...prefix] = script.argv;
+    const watchOptions = {
+        ...validated,
+        budgetMs: serveStallBudgetMs(validated.intervalMs),
+        pollMs: Math.min(5_000, validated.intervalMs),
+        mode: 'kill'
+    };
+    const child = await execution.spawn({
+        command,
+        args: [
+            ...prefix,
+            '--eval', `${WATCH_SOURCE}\nawait runServeStallWatch(${JSON.stringify(watchOptions)});`
+        ],
+        cwd: cwd.data,
+        env: script.env,
+        envMode: 'replace',
+        stdout: 'pipe',
+        stderr: 'ignore',
+        stdin: 'ignore'
+    });
+    try {
+        await runtime.lifecycle.wait(() => acknowledgeStartup(child), {
+            timeoutMs: validated.intervalMs,
+            reason: 'serve-stall-start'
+        });
+    }
+    catch (error) {
+        await child.kill();
+        await child.exited;
+        throw error;
+    }
+    child.unref?.();
+    return { stop: async () => { await child.kill(); await child.exited; } };
+}
+//# sourceMappingURL=serve-stall-start.js.map

package/dist/serve-stall-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall-start.js","sourceRoot":"","sources":["../src/serve-stall-start.ts"],"names":[],"mappings":"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"}

package/dist/serve-stall.d.ts

@@ -0,0 +1,11 @@
+/** Heartbeats a serve thread may miss before it is treated as stuck. */
+export declare const SERVE_STALL_MISSED_HEARTBEATS = 3;
+/** How old a pid-file mtime may be before the serve thread counts as stuck. */
+export declare function serveStallBudgetMs(intervalMs: number): number;
+/**
+ * Whether `ageMs` (now minus the pid file's mtime) means the serve thread
+ * stopped heartbeating. A non-positive interval or a non-finite age is not a
+ * stall: the watch must not kill on a clock or config it cannot read.
+ */
+export declare function serveHeartbeatIsStale(ageMs: number, intervalMs: number): boolean;
+//# sourceMappingURL=serve-stall.d.ts.map

package/dist/serve-stall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall.d.ts","sourceRoot":"","sources":["../src/serve-stall.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAIhF"}

package/dist/serve-stall.js

@@ -0,0 +1,19 @@
+/** Heartbeats a serve thread may miss before it is treated as stuck. */
+export const SERVE_STALL_MISSED_HEARTBEATS = 3;
+/** How old a pid-file mtime may be before the serve thread counts as stuck. */
+export function serveStallBudgetMs(intervalMs) {
+    return intervalMs * SERVE_STALL_MISSED_HEARTBEATS;
+}
+/**
+ * Whether `ageMs` (now minus the pid file's mtime) means the serve thread
+ * stopped heartbeating. A non-positive interval or a non-finite age is not a
+ * stall: the watch must not kill on a clock or config it cannot read.
+ */
+export function serveHeartbeatIsStale(ageMs, intervalMs) {
+    if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0)
+        return false;
+    if (!Number.isFinite(ageMs) || ageMs < 0)
+        return false;
+    return ageMs > serveStallBudgetMs(intervalMs);
+}
+//# sourceMappingURL=serve-stall.js.map

package/dist/serve-stall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall.js","sourceRoot":"","sources":["../src/serve-stall.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACpD,OAAO,UAAU,GAAG,6BAA6B,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,UAAkB;IACtE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,KAAK,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAC/C,CAAC"}

package/dist/serve-stall.plugin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Registers the Bun host's serve stall watch under `runtime/serve-stall`.
+ * The watch module loads only when the kind is first resolved.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+/** The Bun watch's descriptor id. */
+export declare const BUN_SERVE_STALL_ID = "bun";
+/** Register the kind (when absent), the Bun watch's descriptor and its lazy loader on `runtime`. */
+export declare function registerBunServeStall(runtime: RuntimeRef): void;
+//# sourceMappingURL=serve-stall.plugin.d.ts.map

package/dist/serve-stall.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall.plugin.d.ts","sourceRoot":"","sources":["../src/serve-stall.plugin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQnF,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,oGAAoG;AACpG,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAsB/D"}

package/dist/serve-stall.plugin.js

@@ -0,0 +1,34 @@
+/**
+ * Registers the Bun host's serve stall watch under `runtime/serve-stall`.
+ * The watch module loads only when the kind is first resolved.
+ */
+import { createRuntimeImplementation } from '@vibesdotdev/kernel';
+import { SERVE_STALL_KIND, serveStallKind, ServeStallDescriptorSchema } from '@vibesdotdev/kernel/kinds/serve-stall.kind';
+/** The Bun watch's descriptor id. */
+export const BUN_SERVE_STALL_ID = 'bun';
+/** Register the kind (when absent), the Bun watch's descriptor and its lazy loader on `runtime`. */
+export function registerBunServeStall(runtime) {
+    if (!runtime.hasKind(SERVE_STALL_KIND))
+        runtime.registerKind(serveStallKind);
+    runtime.registerDescriptor(SERVE_STALL_KIND, ServeStallDescriptorSchema.parse({
+        id: BUN_SERVE_STALL_ID,
+        kind: SERVE_STALL_KIND,
+        name: 'Bun serve stall watch',
+        description: 'Child process that SIGKILLs a serve whose pid-file heartbeat goes stale',
+        host: 'bun',
+        hardware: ['consumer']
+    }));
+    runtime.registerLoader(SERVE_STALL_KIND, BUN_SERVE_STALL_ID, async () => {
+        const { startServeStallWatch } = await import("./serve-stall-start.js");
+        const implementation = {
+            start: (options) => startServeStallWatch(runtime, options)
+        };
+        return createRuntimeImplementation({
+            kind: SERVE_STALL_KIND,
+            id: BUN_SERVE_STALL_ID,
+            constraint: { hardware: ['consumer'] },
+            implementation
+        });
+    });
+}
+//# sourceMappingURL=serve-stall.plugin.js.map

package/dist/serve-stall.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-stall.plugin.js","sourceRoot":"","sources":["../src/serve-stall.plugin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,2BAA2B,EAAmB,MAAM,qBAAqB,CAAC;AACnF,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAE1B,MAAM,4CAA4C,CAAC;AAEpD,qCAAqC;AACrC,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAExC,oGAAoG;AACpG,MAAM,UAAU,qBAAqB,CAAC,OAAmB;IACxD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;QAAE,OAAO,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAC7E,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,EAAE,0BAA0B,CAAC,KAAK,CAAC;QAC7E,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,yEAAyE;QACtF,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,CAAC,UAAU,CAAC;KACtB,CAAC,CAAC,CAAC;IACJ,OAAO,CAAC,cAAc,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;QACxE,MAAM,cAAc,GAAmB;YACtC,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC;SAC1D,CAAC;QACF,OAAO,2BAA2B,CAAC;YAClC,IAAI,EAAE,gBAAgB;YACtB,EAAE,EAAE,kBAAkB;YACtB,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE;YACtC,cAAc;SACd,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/services/account-home.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The OS account's home directory, from the account database (passwd).
+ *
+ * This is a HOST IDENTITY fact, distinct from both the selected profile home
+ * (`paths/roots`) and `HOME`: `os.homedir()` and `os.userInfo().homedir` both
+ * follow a replacement `HOME` (measured on Bun 1.4.2, in and out of a Seatbelt
+ * profile), while `getpwuid_r` answers the account's own entry. It is read in
+ * process through libc (`bun:ffi`): no child, no environment, no setuid tool.
+ *
+ * `captureAccountHome()` runs once, when the environment is constructed, and
+ * returns the answer or its typed failure; the environment's `accountHome()`
+ * returns the one or throws the other when a reader asks. Nothing requires it
+ * at boot: only a reader that needs the account home fails.
+ */
+import { type Pointer } from 'bun:ffi';
+import { CapabilityError } from '@vibesdotdev/kernel';
+export type AccountHomeCapture = {
+    readonly home: string;
+} | {
+    readonly failure: CapabilityError;
+};
+/** libc's `getpwuid_r`, bound from one opened library. */
+export interface GetpwuidR {
+    getpwuid_r(uid: number, entry: Pointer, strings: Pointer, length: number, result: Pointer): number;
+    close(): void;
+}
+/** Opens the libc at `path` and binds `getpwuid_r`; throws when it cannot. */
+export type OpenGetpwuidR = (path: string) => GetpwuidR;
+/**
+ * Read the account home of `uid` from the account database, once. Never
+ * throws: every failure, a foreign-function fault included, is captured as the
+ * typed `account-home-unavailable` refusal that `accountHomeOf` throws when a
+ * reader asks. The platform and architecture are the host's captured facts
+ * (`getPlatform()`, `getArch()`), never a live read here.
+ */
+export declare function captureAccountHome(platform: NodeJS.Platform, uid: number | undefined, arch: string, open?: OpenGetpwuidR): AccountHomeCapture;
+/** The captured answer, or its typed failure thrown. */
+export declare function accountHomeOf(capture: AccountHomeCapture): string;
+//# sourceMappingURL=account-home.d.ts.map

package/dist/services/account-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-home.d.ts","sourceRoot":"","sources":["../../src/services/account-home.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAuC,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAqB,MAAM,qBAAqB,CAAC;AAGzE,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AA6DnG,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACnG,KAAK,IAAI,IAAI,CAAC;CACd;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;AAyExD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,aAA2B,GAC/B,kBAAkB,CAepB;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAGjE"}

package/dist/services/account-home.js

@@ -0,0 +1,152 @@
+/**
+ * The OS account's home directory, from the account database (passwd).
+ *
+ * This is a HOST IDENTITY fact, distinct from both the selected profile home
+ * (`paths/roots`) and `HOME`: `os.homedir()` and `os.userInfo().homedir` both
+ * follow a replacement `HOME` (measured on Bun 1.4.2, in and out of a Seatbelt
+ * profile), while `getpwuid_r` answers the account's own entry. It is read in
+ * process through libc (`bun:ffi`): no child, no environment, no setuid tool.
+ *
+ * `captureAccountHome()` runs once, when the environment is constructed, and
+ * returns the answer or its typed failure; the environment's `accountHome()`
+ * returns the one or throws the other when a reader asks. Nothing requires it
+ * at boot: only a reader that needs the account home fails.
+ */
+import { CString, dlopen, FFIType, ptr, read } from 'bun:ffi';
+import { CapabilityError, isCapabilityError } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+const ACCOUNT_HOME_UNAVAILABLE = 'account-home-unavailable';
+function accountHomeMessage(detail) {
+    return `The OS account's home could not be read: ${detail}.`;
+}
+function accountHomeUnavailable(platform, detail, details = {}, cause) {
+    return new CapabilityError(accountHomeMessage(detail), 'UNAVAILABLE', {
+        reason: ACCOUNT_HOME_UNAVAILABLE,
+        retryable: false,
+        details: { platform, ...details },
+        cause
+    });
+}
+/**
+ * The class a thrown value names: an `Error`'s own name, else the primitive
+ * kind that was thrown (`string`), else `object`.
+ */
+const ThrownClassSchema = z.union([
+    z.instanceof(Error).transform((error) => error.name),
+    z.string().transform(() => 'string'),
+    z.number().transform(() => 'number'),
+    z.boolean().transform(() => 'boolean'),
+    z.bigint().transform(() => 'bigint'),
+    z.symbol().transform(() => 'symbol'),
+    z.undefined().transform(() => 'undefined')
+]).catch('object');
+/** The 64-bit ABIs whose `struct passwd` layout the offsets below describe. */
+const SUPPORTED_ARCHES = new Set(['x64', 'arm64']);
+/** libc and the `struct passwd` offset of `pw_dir` for this platform (64-bit ABIs only). */
+function libcFor(platform) {
+    if (platform === 'darwin')
+        return { paths: ['/usr/lib/libSystem.B.dylib'], pwDirOffset: 48 };
+    if (platform === 'linux') {
+        // glibc, then musl; both lay out pw_name, pw_passwd, pw_uid, pw_gid, pw_gecos, pw_dir.
+        return {
+            paths: ['libc.so.6', 'libc.musl-x86_64.so.1', 'libc.musl-aarch64.so.1'],
+            pwDirOffset: 32
+        };
+    }
+    return null;
+}
+const openWithFfi = (path) => {
+    const lib = dlopen(path, {
+        getpwuid_r: { args: [FFIType.u32, FFIType.ptr, FFIType.ptr, FFIType.u64, FFIType.ptr], returns: FFIType.i32 }
+    });
+    return {
+        getpwuid_r: (uid, entry, strings, length, result) => lib.symbols.getpwuid_r(uid, entry, strings, length, result),
+        close: () => lib.close()
+    };
+};
+function attemptOpen(path, open) {
+    try {
+        return { lib: open(path) };
+    }
+    catch (failure) {
+        return { failure };
+    }
+}
+function openLibc(platform, paths, open) {
+    const tried = [];
+    const failures = [];
+    for (const path of paths) {
+        const attempt = attemptOpen(path, open);
+        if ('lib' in attempt)
+            return attempt.lib;
+        // Each candidate that cannot be opened is named in the typed failure below.
+        tried.push(path);
+        failures.push(attempt.failure);
+    }
+    throw accountHomeUnavailable(platform, 'libc could not be opened', { cause: 'libc-unavailable', tried }, new AggregateError(failures, 'libc candidates could not be opened'));
+}
+/** One read of the account database; throws on any failure. */
+function readAccountHome(platform, uid, arch, open) {
+    // The pw_dir offsets assume 64-bit pointers; any other ABI is refused, never read at a wrong offset.
+    if (!SUPPORTED_ARCHES.has(arch)) {
+        throw accountHomeUnavailable(platform, `the ${arch} ABI is not supported`, { cause: 'unsupported-abi', arch });
+    }
+    const libc = libcFor(platform);
+    if (!libc || uid === undefined) {
+        throw accountHomeUnavailable(platform, 'this platform has no passwd database', { cause: 'no-passwd-database' });
+    }
+    const lib = openLibc(platform, libc.paths, open);
+    try {
+        const entry = new Uint8Array(128);
+        const strings = new Uint8Array(16 * 1024);
+        const result = new BigUint64Array(1);
+        const status = lib.getpwuid_r(uid, ptr(entry), ptr(strings), strings.length, ptr(result));
+        if (status !== 0)
+            throw accountHomeUnavailable(platform, 'getpwuid_r failed', { cause: 'getpwuid-failed', errno: status });
+        if (result[0] === 0n) {
+            throw accountHomeUnavailable(platform, 'the account database has no entry for this uid', { cause: 'no-entry', uid });
+        }
+        const dir = read.ptr(ptr(entry), libc.pwDirOffset);
+        // SAFETY: getpwuid_r succeeded for this 64-bit ABI; pw_dir is a nonnull C string pointer into the still-live strings buffer.
+        const home = dir ? new CString(dir).toString() : '';
+        if (!home.startsWith('/')) {
+            throw accountHomeUnavailable(platform, 'the account entry names no absolute home', { cause: 'no-absolute-home', uid });
+        }
+        return home;
+    }
+    finally {
+        lib.close();
+    }
+}
+/**
+ * Read the account home of `uid` from the account database, once. Never
+ * throws: every failure, a foreign-function fault included, is captured as the
+ * typed `account-home-unavailable` refusal that `accountHomeOf` throws when a
+ * reader asks. The platform and architecture are the host's captured facts
+ * (`getPlatform()`, `getArch()`), never a live read here.
+ */
+export function captureAccountHome(platform, uid, arch, open = openWithFfi) {
+    try {
+        return { home: readAccountHome(platform, uid, arch, open) };
+    }
+    catch (error) {
+        if (error instanceof Error && isCapabilityError(error) && error.reason === ACCOUNT_HOME_UNAVAILABLE)
+            return { failure: error };
+        // The message and stack of a foreign fault stay out of the refusal; its class names it.
+        return {
+            failure: new CapabilityError(accountHomeMessage('the account database read faulted'), 'UNAVAILABLE', {
+                reason: ACCOUNT_HOME_UNAVAILABLE,
+                retryable: false,
+                details: { platform, cause: 'ffi-fault', errorClass: ThrownClassSchema.parse(error) },
+                cause: error
+            })
+        };
+    }
+}
+/** The captured answer, or its typed failure thrown. */
+export function accountHomeOf(capture) {
+    if ('failure' in capture)
+        throw capture.failure;
+    return capture.home;
+}
+//# sourceMappingURL=account-home.js.map

package/dist/services/account-home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-home.js","sourceRoot":"","sources":["../../src/services/account-home.ts"],"names":[],"mappings":"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"}

package/dist/services/cli-process-host.d.ts

@@ -0,0 +1,50 @@
+import { type createBunHostResources, type BunStandardOutput } from './standard-output.ts';
+/** What a CLI host entry reads from, and does to, its process. */
+export interface BunCliProcessHost {
+    /** The process argv, captured when the host was made. */
+    readonly argv: readonly string[];
+    /**
+     * Whether the thin shim launched THIS process: its version marker is set and
+     * this process is the executable the channel names. The shim runs the host
+     * in-process, so its own process is its published self-spawn (`[execPath]`
+     * compiled, `[bun, shim script]` from source) or, under its execve escape
+     * hatch, the published host entry. A child that merely inherited a parent's
+     * channel is a different executable and never takes the parent's root.
+     */
+    readonly launchedByShim: boolean;
+    /**
+     * The shim-baked build surface, raw: the channel's `VIBES_CLI_MODE`, read
+     * only when the shim launched THIS process (`launchedByShim`). A child that
+     * inherited a parent's channel never takes the parent's build surface;
+     * absent when none was baked.
+     */
+    readonly cliMode: string | undefined;
+    /**
+     * Whether a person's terminal is attached: stdin and stdout are terminals,
+     * or `VIBES_FORCE_TTY=1` declares one. Only then can a command attach a TUI.
+     */
+    readonly attachedTerminal: boolean;
+    /** Text output and the output plane's flush. */
+    readonly output: BunStandardOutput;
+    /** The exit code a command chose so far (`process.exitCode`). */
+    exitCode(): number | undefined;
+    /** End the process with `code`. */
+    exit(code: number): never;
+    /** All of stdin as UTF-8 text, or `undefined` when it held nothing. */
+    readStdin(): Promise<string | undefined>;
+}
+/**
+ * Whether this process is the one that published the shim channel in `env`
+ * (see `launchedByShim`). Reads only what every shipped shim already publishes,
+ * so an installed shim keeps working without a rebuild.
+ */
+export declare function isChannelPublisher(env: Readonly<Record<string, string | undefined>>, execPath: string, argv: readonly string[]): boolean;
+/**
+ * The shim custody this process holds over `env`: whether the shim launched it
+ * (its version marker is set and it is the channel publisher) and, only then,
+ * the build surface the shim baked. Pure over its inputs.
+ */
+export declare function captureShimCustody(env: Readonly<Record<string, string | undefined>>, execPath: string, argv: readonly string[]): Pick<BunCliProcessHost, 'launchedByShim' | 'cliMode'>;
+/** Capture this process for a CLI host entry. */
+export declare function captureBunCliProcessHost(hostResources?: ReturnType<typeof createBunHostResources>): BunCliProcessHost;
+//# sourceMappingURL=cli-process-host.d.ts.map

package/dist/services/cli-process-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-host.d.ts","sourceRoot":"","sources":["../../src/services/cli-process-host.ts"],"names":[],"mappings":"AAcA,OAAO,EAA8C,KAAK,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAWvI,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IACjC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,iEAAiE;IACjE,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,mCAAmC;IACnC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAC1B,uEAAuE;IACvE,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAoBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQxI;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAGtL;AAED,iDAAiD;AACjD,wBAAgB,wBAAwB,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,GAAG,iBAAiB,CAmBrH"}

package/dist/services/cli-process-host.js

@@ -0,0 +1,88 @@
+/**
+ * The CLI executable's process, as the Bun host owns it
+ * (`@vibesdotdev/host-bun/services/cli-process-host`).
+ *
+ * A CLI host entry (`@vibesdotdev/surface-cli/bun/host`) runs before
+ * any runtime exists and ends the process after the last runtime is
+ * disposed, so the process facts it decides on — argv, the shim's custody
+ * markers, stdin for the hook relay, the exit — come from this host module,
+ * captured once, rather than from process globals in a feature package.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import * as z from 'zod/v4';
+import { captureLaunchFacts } from '@vibesdotdev/execution-local';
+import { attemptJson } from '@vibesdotdev/execution-local/host-base';
+import { bunStandardOutput, createBunStandardOutput } from "./standard-output.js";
+/** The shim's launch-custody marker: present (non-blank) when the thin `vibes` shim launched this host. */
+const SHIM_VERSION_KEY = 'VIBES_SHIM_VERSION';
+/** The re-entry argv the shim published for ITS process (JSON array). */
+const SELF_SPAWN_ARGV_KEY = 'VIBES_SELF_SPAWN_ARGV';
+/** The host entry the shim resolved and published. */
+const HOST_ENTRY_KEY = 'VIBES_HOST_ENTRY';
+/** The shim-baked build surface (`public`, `internal`, …), parsed by `parseBuildSurface`. */
+const CLI_MODE_KEY = 'VIBES_CLI_MODE';
+/** An exit code a command set: an integer, else none. */
+const ExitCodeSchema = z.number().int();
+/** The channel's self-spawn argv, or none when it is absent or not a JSON string array. */
+const ArgvSchema = z.array(z.string().min(1)).min(1);
+function channelArgv(raw) {
+    if (!raw)
+        return undefined;
+    const json = attemptJson(raw);
+    if ('failure' in json)
+        return undefined;
+    const parsed = ArgvSchema.safeParse(json.value);
+    return parsed.success ? parsed.data : undefined;
+}
+/** A path's realpath; a path that is not there keeps its spelling. */
+function canonical(path) {
+    return existsSync(path) ? realpathSync(path) : path;
+}
+/**
+ * Whether this process is the one that published the shim channel in `env`
+ * (see `launchedByShim`). Reads only what every shipped shim already publishes,
+ * so an installed shim keeps working without a rebuild.
+ */
+export function isChannelPublisher(env, execPath, argv) {
+    const self = channelArgv(env[SELF_SPAWN_ARGV_KEY]);
+    if (!self || canonical(self[0]) !== canonical(execPath))
+        return false;
+    const script = argv[1];
+    if (self.length === 1)
+        return true;
+    if (self.length !== 2 || !script)
+        return false;
+    const entry = env[HOST_ENTRY_KEY];
+    return canonical(script) === canonical(self[1]) || (entry !== undefined && canonical(script) === canonical(entry));
+}
+/**
+ * The shim custody this process holds over `env`: whether the shim launched it
+ * (its version marker is set and it is the channel publisher) and, only then,
+ * the build surface the shim baked. Pure over its inputs.
+ */
+export function captureShimCustody(env, execPath, argv) {
+    const launchedByShim = Boolean(env[SHIM_VERSION_KEY]?.trim()) && isChannelPublisher(env, execPath, argv);
+    return { launchedByShim, cliMode: launchedByShim ? env[CLI_MODE_KEY] : undefined };
+}
+/** Capture this process for a CLI host entry. */
+export function captureBunCliProcessHost(hostResources) {
+    const argv = Object.freeze([...process.argv]);
+    const { launchedByShim, cliMode } = captureShimCustody(process.env, process.execPath, argv);
+    return Object.freeze({
+        argv,
+        launchedByShim,
+        cliMode,
+        attachedTerminal: (process.stdin.isTTY === true && process.stdout.isTTY === true) ||
+            captureLaunchFacts(process.env).terminal.forceTty,
+        output: hostResources ? createBunStandardOutput(hostResources) : bunStandardOutput,
+        exitCode: () => ExitCodeSchema.safeParse(process.exitCode).data,
+        exit: (code) => process.exit(code),
+        readStdin: async () => {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(Buffer.from(chunk));
+            return chunks.length > 0 ? Buffer.concat(chunks).toString('utf8') : undefined;
+        }
+    });
+}
+//# sourceMappingURL=cli-process-host.js.map

package/dist/services/cli-process-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-host.js","sourceRoot":"","sources":["../../src/services/cli-process-host.ts"],"names":[],"mappings":"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"}

package/dist/services/compatibility-host.impl.bun.d.ts

@@ -0,0 +1,4 @@
+import type { createBunHostResources } from './host-resources.impl.bun.ts';
+/** Before boot and after disposal callers must supply createBunHostResources(). */
+export declare const compatibilityBunHost: ReturnType<typeof createBunHostResources>;
+//# sourceMappingURL=compatibility-host.impl.bun.d.ts.map

package/dist/services/compatibility-host.impl.bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility-host.impl.bun.d.ts","sourceRoot":"","sources":["../../src/services/compatibility-host.impl.bun.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAU3E,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAUzE,CAAC"}