@playfast/muxmaxing-config 0.1.1

package/README.md

@@ -0,0 +1,60 @@
+# @playfast/muxmaxing-config
+
+Author API for a repo-committed `muxmaxing.config.ts` — a hook bridge between the **host
+device** (the machine running mux) and a **work unit** (the pod/VM muxmaxing creates for
+your repo). Declare a typed `hostInput` payload, collect it on the host (env, CLIs,
+logins), and act on unit lifecycle moments with it. Hooks are Effect-native and run
+host-side in a Bun Worker, only for repos the user has explicitly approved.
+
+## Example — preconfigure the Doppler CLI in every work unit
+
+```ts
+// muxmaxing.config.ts (repo root, committed)
+import { defineConfig } from '@playfast/muxmaxing-config'
+import { Effect, Schema as S } from 'effect'
+
+const TokenJson = S.parseJson(S.Struct({ key: S.String, slug: S.String }))
+
+export default defineConfig({
+  hostInput: S.Struct({ dopplerToken: S.String, tokenSlug: S.String }),
+
+  // Runs ON THE HOST: mint an ephemeral read-only token with the user's own login.
+  collectHostDeviceInput: ({ host, unit }) =>
+    Effect.gen(function* () {
+      const minted = yield* host.bash(
+        `doppler configs tokens create mux-${unit.id} --project my-app --config dev --max-age 24h --json`,
+      )
+      const token = yield* S.decode(TokenJson)(minted.stdout)
+      return { dopplerToken: token.key, tokenSlug: token.slug }
+    }),
+
+  // Runs when the unit is up: `ctx.unit.bash` execs INSIDE the unit.
+  onWorkUnitMachineCreated: (ctx) =>
+    Effect.gen(function* () {
+      yield* ctx.unit.bash(
+        `doppler configure set token ${ctx.hostInput.dopplerToken} --scope ${ctx.unit.workspaceFolder}`,
+      )
+      yield* ctx.log('doppler CLI preconfigured')
+    }),
+
+  // Runs at teardown ON THE HOST: revoke exactly the token this unit was minted.
+  onWorkUnitRemoved: (ctx) =>
+    ctx.host.bash(
+      `doppler configs tokens revoke --slug ${ctx.hostInput.tokenSlug} --project my-app --config dev`,
+    ),
+})
+```
+
+## Contract
+
+- `hostInput` — an Effect Schema; its encoded side must be plain JSON (it crosses the
+  worker boundary and is cached memory-only by the engine between hooks).
+- `collectHostDeviceInput(ctx)` — runs once per unit on the host; produces the payload.
+- `onWorkUnitMachineCreated(ctx)` / `onNewTerminal(ctx)` — `ctx.unit.bash` execs in the
+  unit, `ctx.host.bash` on the host, `ctx.log` writes to the unit's creation pane.
+- `onWorkUnitRemoved(ctx)` — host-side cleanup; the unit may already be gone (no unit bash).
+- A bash result is `{ stdout, stderr, exitCode }`; a non-zero exit is not an error — only
+  a transport failure fails the Effect.
+
+Trust model: hooks run on the host in a Bun Worker — a thread boundary, **not** a security
+sandbox. muxmaxing runs them only for repos the user approved (Settings → Hooks).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@playfast/muxmaxing-config",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Author API for muxmaxing.config.ts — a repo-committed hook bridge between the host device and muxmaxing work units: typed host-input collection plus Effect-native lifecycle hooks (machine created, new terminal, removed) with bash bridged into the unit.",
+  "keywords": [
+    "muxmaxing",
+    "effect",
+    "hooks",
+    "devcontainer",
+    "provisioning"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/playfast/reform.git",
+    "directory": "packages/muxmaxing-config"
+  },
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .tsbuildinfo",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src"
+  },
+  "peerDependencies": {
+    "effect": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/fixtures/sample.config.ts

@@ -0,0 +1,35 @@
+import { Effect, Schema as S, String as Str } from 'effect'
+import { defineConfig, type MuxmaxingConfig } from '@playfast/muxmaxing-config'
+
+// The worker-entry test fixture — shaped like a real repo's `muxmaxing.config.ts`
+// (imports the package by name, exercises host bash, unit bash, log, and hostInput).
+// The explicit annotation is only for THIS package's `isolatedDeclarations` check —
+// a real repo's config just default-exports `defineConfig({...})`.
+
+interface SampleInput {
+  readonly token: string
+  readonly slug: string
+}
+
+const config: MuxmaxingConfig<SampleInput, SampleInput> = defineConfig({
+  hostInput: S.Struct({ token: S.String, slug: S.String }),
+
+  collectHostDeviceInput: ({ host, unit }) =>
+    Effect.gen(function* () {
+      const minted = yield* host.bash(`fake-mint ${unit.id}`)
+      return { token: Str.trim(minted.stdout), slug: `slug-${unit.id}` }
+    }),
+
+  onWorkUnitMachineCreated: (ctx) =>
+    Effect.gen(function* () {
+      yield* ctx.log('configuring')
+      const configured = yield* ctx.unit.bash(`configure ${ctx.hostInput.token}`)
+      if (configured.exitCode !== 0) {
+        return yield* Effect.fail(`configure exited ${configured.exitCode}`)
+      }
+    }),
+
+  onWorkUnitRemoved: (ctx) => Effect.asVoid(ctx.host.bash(`revoke ${ctx.hostInput.slug}`)),
+})
+
+export default config

package/src/index.ts

@@ -0,0 +1,136 @@
+import { type Cause, Data, type Effect, Schema as S } from 'effect'
+
+// The author API for a repo-committed `muxmaxing.config.ts` — a HOOK BRIDGE between the
+// host device (the machine running mux) and a work unit (the pod/VM muxmaxing created for
+// the repo). The author declares a typed `hostInput` payload, collects it ON THE HOST
+// (read host env, exec host CLIs — e.g. mint an ephemeral Doppler token with the user's
+// own login), and acts on unit lifecycle moments with it (`ctx.bash` execs IN the unit).
+//
+// Hooks are Effect-native: each returns an `Effect`, never a Promise. They run host-side
+// in a Bun Worker — a THREAD boundary, not a security sandbox — so muxmaxing only runs
+// them for repos the user has explicitly approved.
+
+/** The captured streams + exit code of a bridged bash execution (unit or host). A
+ *  non-zero exit is NOT an error — it's a successful run whose `exitCode` the hook
+ *  interprets; only a transport failure (the command could not RUN) fails the Effect. */
+export interface BashResult {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+/** The constructor shape `Data.TaggedError(tag)<A>` produces, named so the generated
+ *  `.d.ts` can describe the `extends` base under `isolatedDeclarations` (which forbids
+ *  an inferred expression in an extends clause) — the reform-db errors pattern. */
+type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
+  args: A,
+) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
+
+const HookBashErrorBase: TaggedErrorClass<'HookBashError', { readonly reason: string }> =
+  Data.TaggedError('HookBashError')<{ readonly reason: string }>
+
+/** Transport failure of a bridged bash call — the command could not be executed at all
+ *  (unit unreachable, host spawn failed, bridge torn down). */
+export class HookBashError extends HookBashErrorBase {
+  // Surface `reason` wherever the error is rendered (`Cause.pretty` would otherwise
+  // print the generic "An error has occurred" — the reform-db errors gotcha).
+  override get message(): string {
+    return this.reason
+  }
+}
+
+/** The host-device side of the bridge: exec on the machine running mux + its env. */
+export interface HostBridge {
+  /** Run a bash command ON THE HOST DEVICE. */
+  readonly bash: (command: string) => Effect.Effect<BashResult, HookBashError>
+  /** The host process env (hooks share the host process — no sandbox). */
+  readonly env: Readonly<Record<string, string | undefined>>
+}
+
+/** The work unit a hook invocation is about. */
+export interface UnitInfo {
+  readonly id: string
+  /** The unit-side folder the repo is checked out under (bash cwd for unit execs). */
+  readonly workspaceFolder: string
+}
+
+/** The work-unit side of the bridge: the unit's identity + exec INSIDE it — the mirror
+ *  of `HostBridge`, so hooks read as `ctx.host.bash(...)` / `ctx.unit.bash(...)`. */
+export interface UnitBridge extends UnitInfo {
+  /** Run a bash command INSIDE the work unit. */
+  readonly bash: (command: string) => Effect.Effect<BashResult, HookBashError>
+}
+
+/** Ctx for `collectHostDeviceInput` — host-only (the payload doesn't exist yet). */
+export interface CollectCtx {
+  readonly host: HostBridge
+  readonly unit: UnitInfo
+  /** Surface a line in the unit's creation pane. */
+  readonly log: (line: string) => Effect.Effect<void>
+}
+
+/** Ctx for unit-lifecycle hooks: the decoded `hostInput` + both sides of the bridge
+ *  (`ctx.unit.bash` execs in the unit, `ctx.host.bash` on the host device). */
+export interface HookCtx<A> {
+  readonly hostInput: A
+  readonly host: HostBridge
+  readonly unit: UnitBridge
+  readonly log: (line: string) => Effect.Effect<void>
+}
+
+/** Ctx for `onWorkUnitRemoved` — the unit may already be gone, so there is no unit
+ *  bash; cleanup acts on the host (e.g. revoke the token minted at collect time). */
+export interface RemovedCtx<A> {
+  readonly hostInput: A
+  readonly host: HostBridge
+  readonly unit: UnitInfo
+  readonly log: (line: string) => Effect.Effect<void>
+}
+
+/** The `muxmaxing.config.ts` contract. `A` is the decoded host-input payload; its
+ *  ENCODED side `I` must be plain JSON — it crosses the worker boundary and is cached
+ *  (memory-only) by the engine between hooks.
+ *
+ *  `ExternalApi` postfix: this shape is authored by EXTERNAL repos (their
+ *  `muxmaxing.config.ts`), where optional hook fields are the ergonomic contract. */
+export interface MuxmaxingConfigExternalApi<A, I> {
+  /** The Schema of the payload that crosses host → hooks (encoded side: plain JSON). */
+  readonly hostInput: S.Schema<A, I, never>
+  /** Runs ON THE HOST when the unit machine comes up; produces the `hostInput` every
+   *  later hook receives. Collected ONCE per unit and cached by the engine. */
+  readonly collectHostDeviceInput: (ctx: CollectCtx) => Effect.Effect<A, unknown>
+  /** Fired when the unit is up and reachable (after devcontainer lifecycle hooks). */
+  readonly onWorkUnitMachineCreated?: (ctx: HookCtx<A>) => Effect.Effect<void, unknown>
+  /** Fired when a terminal opens in the unit. */
+  readonly onNewTerminal?: (ctx: HookCtx<A>) => Effect.Effect<void, unknown>
+  /** Fired at unit teardown — host-side cleanup (revoke what collect minted). */
+  readonly onWorkUnitRemoved?: (ctx: RemovedCtx<A>) => Effect.Effect<void, unknown>
+}
+
+/** The public name for the config contract. */
+export type MuxmaxingConfig<A, I> = MuxmaxingConfigExternalApi<A, I>
+
+/** Identity with types — the `defineConfig` a repo's `muxmaxing.config.ts` default-exports. */
+export const defineConfig = <A, I>(config: MuxmaxingConfig<A, I>): MuxmaxingConfig<A, I> =>
+  config
+
+/** Runtime narrowing for the worker entry: the default export of a fetched config module,
+ *  checked structurally (schema + functions). The `hostInput` Schema remains the real
+ *  gate for the DATA; this predicate gates the SHAPE. */
+export const isMuxmaxingConfig = (
+  candidate: unknown,
+): candidate is MuxmaxingConfig<unknown, unknown> => {
+  if (typeof candidate !== 'object' || candidate === null) {
+    return false
+  }
+  const record: Record<string, unknown> = { ...candidate }
+  const optionalHook = (name: string): boolean =>
+    record[name] === undefined || typeof record[name] === 'function'
+  return (
+    S.isSchema(record['hostInput']) &&
+    typeof record['collectHostDeviceInput'] === 'function' &&
+    optionalHook('onWorkUnitMachineCreated') &&
+    optionalHook('onNewTerminal') &&
+    optionalHook('onWorkUnitRemoved')
+  )
+}

package/src/protocol.ts

@@ -0,0 +1,103 @@
+import { Schema as S } from 'effect'
+
+// The postMessage wire protocol between the engine (main thread) and the per-invocation
+// hook worker. Every message is encoded before `postMessage` and decoded on receipt via
+// these schemas — plain JSON only (structured clone fast path, no class prototypes on
+// the wire). One worker serves exactly ONE `RunHook`; `Bash` requests stream back from
+// the worker while its hook runs, each answered by a `BashReply`.
+//
+// Annotated `TaggedStruct` consts (not `S.TaggedClass`) so the declarations survive
+// `isolatedDeclarations` — the same reason reform-db's errors annotate their base.
+
+/** Which hook the worker should run. `collect` produces the hostInput; the rest consume it. */
+export const HookName: S.Literal<['collect', 'machineCreated', 'newTerminal', 'removed']> =
+  S.Literal('collect', 'machineCreated', 'newTerminal', 'removed')
+export type HookName = typeof HookName.Type
+
+export const UnitRef: S.Struct<{ id: typeof S.String; workspaceFolder: typeof S.String }> =
+  S.Struct({ id: S.String, workspaceFolder: S.String })
+export type UnitRef = typeof UnitRef.Type
+
+// ── engine → worker ───────────────────────────────────────────────────────────
+
+/** The single invocation a worker serves. `configPath` is the materialised config module
+ *  to import; `hostInput` is the ENCODED payload (`null` for `collect`, which creates it). */
+export const RunHookRequest: S.TaggedStruct<
+  'RunHook',
+  {
+    hook: typeof HookName
+    configPath: typeof S.String
+    hostInput: S.NullOr<typeof S.Unknown>
+    unit: typeof UnitRef
+  }
+> = S.TaggedStruct('RunHook', {
+  hook: HookName,
+  configPath: S.String,
+  hostInput: S.NullOr(S.Unknown),
+  unit: UnitRef,
+})
+export type RunHookRequest = typeof RunHookRequest.Type
+
+export const BashOk: S.TaggedStruct<
+  'BashOk',
+  { stdout: typeof S.String; stderr: typeof S.String; exitCode: typeof S.Number }
+> = S.TaggedStruct('BashOk', { stdout: S.String, stderr: S.String, exitCode: S.Number })
+export type BashOk = typeof BashOk.Type
+
+export const BashFailed: S.TaggedStruct<'BashFailed', { reason: typeof S.String }> =
+  S.TaggedStruct('BashFailed', { reason: S.String })
+export type BashFailed = typeof BashFailed.Type
+
+/** The engine's answer to one `Bash` request, correlated by `id`. */
+export const BashReply: S.TaggedStruct<
+  'BashReply',
+  { id: typeof S.Number; result: S.Union<[typeof BashOk, typeof BashFailed]> }
+> = S.TaggedStruct('BashReply', { id: S.Number, result: S.Union(BashOk, BashFailed) })
+export type BashReply = typeof BashReply.Type
+
+export const EngineToWorker: S.Union<[typeof RunHookRequest, typeof BashReply]> = S.Union(
+  RunHookRequest,
+  BashReply,
+)
+export type EngineToWorker = typeof EngineToWorker.Type
+
+// ── worker → engine ───────────────────────────────────────────────────────────
+
+/** A bridged bash execution request: `unit` execs inside the work unit, `host` on the
+ *  host device. The engine replies with a `BashReply` carrying the same `id`. */
+export const BashRequest: S.TaggedStruct<
+  'Bash',
+  {
+    id: typeof S.Number
+    target: S.Literal<['unit', 'host']>
+    command: typeof S.String
+  }
+> = S.TaggedStruct('Bash', {
+  id: S.Number,
+  target: S.Literal('unit', 'host'),
+  command: S.String,
+})
+export type BashRequest = typeof BashRequest.Type
+
+/** A line for the unit's creation pane (the hook's `ctx.log`). */
+export const LogMessage: S.TaggedStruct<'Log', { line: typeof S.String }> = S.TaggedStruct(
+  'Log',
+  { line: S.String },
+)
+export type LogMessage = typeof LogMessage.Type
+
+/** The hook finished. `hostInput` carries the freshly ENCODED payload for `collect`
+ *  (the engine caches it, memory-only) and is `null` for every other hook. */
+export const HookDone: S.TaggedStruct<'HookDone', { hostInput: S.NullOr<typeof S.Unknown> }> =
+  S.TaggedStruct('HookDone', { hostInput: S.NullOr(S.Unknown) })
+export type HookDone = typeof HookDone.Type
+
+/** The hook (or the config module itself) failed — best-effort reporting, never retried. */
+export const HookFailed: S.TaggedStruct<'HookFailed', { reason: typeof S.String }> =
+  S.TaggedStruct('HookFailed', { reason: S.String })
+export type HookFailed = typeof HookFailed.Type
+
+export const WorkerToEngine: S.Union<
+  [typeof BashRequest, typeof LogMessage, typeof HookDone, typeof HookFailed]
+> = S.Union(BashRequest, LogMessage, HookDone, HookFailed)
+export type WorkerToEngine = typeof WorkerToEngine.Type

package/src/worker-entry.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import { Schema as S } from 'effect'
+import { fileURLToPath } from 'node:url'
+import {
+  BashReply,
+  EngineToWorker,
+  type HookName,
+  RunHookRequest,
+  WorkerToEngine,
+} from './protocol'
+
+// Drives the REAL worker entry end-to-end: spawn a Bun Worker on `worker-entry.ts`,
+// point it at the fixture config (which imports the package by name, like a real repo),
+// answer its bridged Bash requests with canned results, and assert the final message.
+// Needs the Bun runtime (`bun --bun run vitest`) for the `Worker` global.
+
+const workerUrl = new URL('./worker-entry.ts', import.meta.url)
+// fileURLToPath so the SPACE in this repo's path survives (URL.pathname would %20 it).
+const fixtureConfigPath = fileURLToPath(new URL('./fixtures/sample.config.ts', import.meta.url))
+
+const encodeToWorker = S.encodeSync(EngineToWorker)
+const decodeFromWorker = S.decodeUnknownSync(WorkerToEngine)
+
+interface DrivenHook {
+  /** Every worker→engine message, in arrival order (Bash/Log/HookDone/HookFailed). */
+  readonly messages: ReadonlyArray<WorkerToEngine>
+}
+
+/** Run ONE hook through a fresh worker, answering each `Bash` via `answerBash`. */
+const driveHook = (input: {
+  readonly hook: HookName
+  readonly hostInput: unknown
+  readonly answerBash: (request: { target: string; command: string }) => BashReply['result']
+}): Promise<DrivenHook> =>
+  new Promise((resolve, reject) => {
+    const worker = new Worker(workerUrl)
+    const seen: Array<WorkerToEngine> = []
+    const finish = (outcome: DrivenHook): void => {
+      worker.terminate()
+      resolve(outcome)
+    }
+    const timer = setTimeout(() => {
+      worker.terminate()
+      reject(new Error(`hook ${input.hook} timed out; saw ${JSON.stringify(seen)}`))
+    }, 15_000)
+    worker.onmessage = (event: MessageEvent): void => {
+      const message = decodeFromWorker(event.data)
+      seen.push(message)
+      if (message._tag === 'Bash') {
+        worker.postMessage(
+          encodeToWorker(
+            BashReply.make({
+              id: message.id,
+              result: input.answerBash({ target: message.target, command: message.command }),
+            }),
+          ),
+        )
+        return
+      }
+      if (message._tag === 'HookDone' || message._tag === 'HookFailed') {
+        clearTimeout(timer)
+        finish({ messages: seen })
+      }
+    }
+    worker.postMessage(
+      encodeToWorker(
+        RunHookRequest.make({
+          hook: input.hook,
+          configPath: fixtureConfigPath,
+          hostInput: input.hostInput,
+          unit: { id: 'unit-1', workspaceFolder: '/workspace/repo' },
+        }),
+      ),
+    )
+  })
+
+const okBash = (stdout: string): BashReply['result'] => ({
+  _tag: 'BashOk',
+  stdout,
+  stderr: '',
+  exitCode: 0,
+})
+
+describe('worker-entry', () => {
+  it('collect: runs collectHostDeviceInput on the host bridge and returns encoded hostInput', async () => {
+    const driven = await driveHook({
+      hook: 'collect',
+      hostInput: null,
+      answerBash: (request) => {
+        expect(request.target).toBe('host')
+        expect(request.command).toBe('fake-mint unit-1')
+        return okBash('tok-123\n')
+      },
+    })
+    const done = driven.messages.at(-1)
+    expect(done?._tag).toBe('HookDone')
+    if (done?._tag === 'HookDone') {
+      expect(done.hostInput).toEqual({ token: 'tok-123', slug: 'slug-unit-1' })
+    }
+  })
+
+  it('machineCreated: decodes hostInput, logs, and bashes into the unit', async () => {
+    const driven = await driveHook({
+      hook: 'machineCreated',
+      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
+      answerBash: (request) => {
+        expect(request.target).toBe('unit')
+        expect(request.command).toBe('configure tok-123')
+        return okBash('')
+      },
+    })
+    const tags = driven.messages.map((message) => message._tag)
+    expect(tags).toEqual(['Log', 'Bash', 'HookDone'])
+  })
+
+  it('newTerminal: a hook the config leaves undefined is a silent no-op success', async () => {
+    const driven = await driveHook({
+      hook: 'newTerminal',
+      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
+      answerBash: () => okBash(''),
+    })
+    expect(driven.messages.map((message) => message._tag)).toEqual(['HookDone'])
+  })
+
+  it('removed: cleanup runs on the HOST bridge with the cached hostInput', async () => {
+    const driven = await driveHook({
+      hook: 'removed',
+      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
+      answerBash: (request) => {
+        expect(request.target).toBe('host')
+        expect(request.command).toBe('revoke slug-unit-1')
+        return okBash('')
+      },
+    })
+    expect(driven.messages.at(-1)?._tag).toBe('HookDone')
+  })
+
+  it('malformed hostInput fails the hook (Schema is the gate), reported as HookFailed', async () => {
+    const driven = await driveHook({
+      hook: 'machineCreated',
+      hostInput: { token: 42 },
+      answerBash: () => okBash(''),
+    })
+    expect(driven.messages.at(-1)?._tag).toBe('HookFailed')
+  })
+
+  it('a failing unit bash surfaces the hook error as HookFailed', async () => {
+    const driven = await driveHook({
+      hook: 'machineCreated',
+      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
+      answerBash: () => ({ _tag: 'BashFailed', reason: 'pod unreachable' }),
+    })
+    const failed = driven.messages.at(-1)
+    expect(failed?._tag).toBe('HookFailed')
+    if (failed?._tag === 'HookFailed') {
+      expect(failed.reason).toContain('pod unreachable')
+    }
+  })
+})

package/src/worker-entry.ts

@@ -0,0 +1,237 @@
+import { Cause, Data, Effect, Either, Match, Option, Ref, Schema as S } from 'effect'
+import {
+  type BashReply,
+  BashRequest,
+  EngineToWorker,
+  HookDone,
+  HookFailed,
+  LogMessage,
+  type RunHookRequest,
+  WorkerToEngine,
+} from './protocol'
+import {
+  type BashResult,
+  HookBashError,
+  type HostBridge,
+  isMuxmaxingConfig,
+  type MuxmaxingConfig,
+  type UnitInfo,
+} from './index'
+
+// The per-invocation hook worker: serves exactly ONE `RunHook`, bridging the hook's
+// `ctx.bash`/`ctx.host.bash` back to the engine over postMessage (the engine owns the
+// actual pod-exec / host-spawn). When the hook settles, the worker reports `HookDone`
+// (or `HookFailed`), drops its message listener so the event loop drains, and exits;
+// the engine's scope finalizer additionally calls `worker.terminate()`.
+
+declare const self: Worker
+
+class WorkerHookError extends Data.TaggedError('WorkerHookError')<{
+  readonly reason: string
+}> {
+  // Without this getter `Cause.pretty` renders the generic "An error has occurred",
+  // hiding the actual failure from the HookFailed report (the reform-db errors gotcha).
+  override get message(): string {
+    return this.reason
+  }
+}
+
+const send = (message: WorkerToEngine): void => {
+  self.postMessage(S.encodeSync(WorkerToEngine)(message))
+}
+
+const describe = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause)
+
+// One in-flight resolver per bridged bash `id` — the engine answers each `Bash` with a
+// correlated `BashReply`. Hooks run their bash calls through `Effect.async` below.
+const pendingBash = new Map<number, (reply: BashReply) => void>()
+
+const makeBridgedBash =
+  (idRef: Ref.Ref<number>, target: 'unit' | 'host') =>
+  (command: string): Effect.Effect<BashResult, HookBashError> =>
+    Ref.updateAndGet(idRef, (previous) => previous + 1).pipe(
+      Effect.flatMap((id) =>
+        Effect.async<BashResult, HookBashError>((resume) => {
+          pendingBash.set(id, (reply) => {
+            resume(
+              Match.value(reply.result).pipe(
+                Match.tags({
+                  BashOk: (ok) =>
+                    Effect.succeed<BashResult>({
+                      stdout: ok.stdout,
+                      stderr: ok.stderr,
+                      exitCode: ok.exitCode,
+                    }),
+                  BashFailed: (failed) =>
+                    Effect.fail(new HookBashError({ reason: failed.reason })),
+                }),
+                Match.exhaustive,
+              ),
+            )
+          })
+          send(BashRequest.make({ id, target, command }))
+        }),
+      ),
+    )
+
+const log = (line: string): Effect.Effect<void> =>
+  Effect.sync(() => send(LogMessage.make({ line })))
+
+const loadConfig = (
+  configPath: string,
+): Effect.Effect<MuxmaxingConfig<unknown, unknown>, WorkerHookError> =>
+  Effect.tryPromise({
+    try: (): Promise<unknown> => import(configPath),
+    catch: (cause) =>
+      new WorkerHookError({ reason: `config import failed: ${describe(cause)}` }),
+  }).pipe(
+    Effect.flatMap((moduleExports) => {
+      const record: Record<string, unknown> =
+        typeof moduleExports === 'object' && moduleExports !== null
+          ? { ...moduleExports }
+          : {}
+      const defaulted = Option.fromNullable(record['default'])
+      return Option.match(defaulted, {
+        onNone: () =>
+          Effect.fail(new WorkerHookError({ reason: 'config has no default export' })),
+        onSome: (config) => {
+          if (isMuxmaxingConfig(config)) {
+            return Effect.succeed(config)
+          }
+          return Effect.fail(
+            new WorkerHookError({
+              reason:
+                'default export is not a muxmaxing config (expected defineConfig({ hostInput, collectHostDeviceInput, ... }))',
+            }),
+          )
+        },
+      })
+    }),
+  )
+
+const decodeHostInput = (
+  config: MuxmaxingConfig<unknown, unknown>,
+  encoded: unknown,
+): Effect.Effect<unknown, WorkerHookError> =>
+  S.decodeUnknown(config.hostInput)(encoded).pipe(
+    Effect.mapError(
+      (issue) => new WorkerHookError({ reason: `hostInput decode failed: ${String(issue)}` }),
+    ),
+  )
+
+const hookFailure =
+  (hookName: string) =>
+  (cause: unknown): WorkerHookError =>
+    new WorkerHookError({ reason: `${hookName} failed: ${describe(cause)}` })
+
+const runRequested = Effect.fn('runRequested')(
+  function* (request: RunHookRequest): Effect.fn.Return<HookDone, WorkerHookError> {
+    const config = yield* loadConfig(request.configPath)
+    const idRef = yield* Ref.make(0)
+    const unit: UnitInfo = {
+      id: request.unit.id,
+      workspaceFolder: request.unit.workspaceFolder,
+    }
+    const host: HostBridge = { bash: makeBridgedBash(idRef, 'host'), env: Bun.env }
+    const unitBridge = { ...unit, bash: makeBridgedBash(idRef, 'unit') }
+
+    // A consuming hook that the config leaves undefined is a silent no-op success.
+    const runOptional = <Ctx>(
+      hookName: string,
+      hook: ((ctx: Ctx) => Effect.Effect<void, unknown>) | undefined,
+      makeCtx: (hostInput: unknown) => Ctx,
+    ): Effect.Effect<HookDone, WorkerHookError> =>
+      Option.match(Option.fromNullable(hook), {
+        onNone: () => Effect.succeed(HookDone.make({ hostInput: null })),
+        onSome: (run) =>
+          decodeHostInput(config, request.hostInput).pipe(
+            Effect.flatMap((hostInput) =>
+              run(makeCtx(hostInput)).pipe(Effect.mapError(hookFailure(hookName))),
+            ),
+            Effect.map(() => HookDone.make({ hostInput: null })),
+          ),
+      })
+
+    return yield* Match.value(request.hook).pipe(
+      Match.when('collect', () =>
+        config
+          .collectHostDeviceInput({ host, unit, log })
+          .pipe(
+            Effect.mapError(hookFailure('collectHostDeviceInput')),
+            Effect.flatMap((collected) =>
+              S.encodeUnknown(config.hostInput)(collected).pipe(
+                Effect.mapError(
+                  (issue) =>
+                    new WorkerHookError({
+                      reason: `hostInput encode failed: ${String(issue)}`,
+                    }),
+                ),
+              ),
+            ),
+            Effect.map((encoded) => HookDone.make({ hostInput: encoded ?? null })),
+          ),
+      ),
+      Match.when('machineCreated', () =>
+        runOptional('onWorkUnitMachineCreated', config.onWorkUnitMachineCreated, (hostInput) => ({
+          hostInput,
+          host,
+          unit: unitBridge,
+          log,
+        })),
+      ),
+      Match.when('newTerminal', () =>
+        runOptional('onNewTerminal', config.onNewTerminal, (hostInput) => ({
+          hostInput,
+          host,
+          unit: unitBridge,
+          log,
+        })),
+      ),
+      Match.when('removed', () =>
+        runOptional('onWorkUnitRemoved', config.onWorkUnitRemoved, (hostInput) => ({
+          hostInput,
+          host,
+          unit,
+          log,
+        })),
+      ),
+      Match.exhaustive,
+    )
+  })
+
+const handleRunHook = (request: RunHookRequest): void => {
+  void Effect.runPromise(
+    runRequested(request).pipe(
+      Effect.flatMap((done) => Effect.sync(() => send(done))),
+      Effect.catchAllCause((cause) =>
+        Effect.sync(() => send(HookFailed.make({ reason: Cause.pretty(cause) }))),
+      ),
+      // Drop the listener so the event loop drains and the worker exits on its own;
+      // the engine's scope finalizer also terminates it (belt and suspenders).
+      Effect.ensuring(
+        Effect.sync(() => {
+          self.onmessage = null
+        }),
+      ),
+    ),
+  )
+}
+
+self.onmessage = (event: MessageEvent): void => {
+  Either.match(S.decodeUnknownEither(EngineToWorker)(event.data), {
+    onLeft: () => send(HookFailed.make({ reason: 'undecodable engine message' })),
+    onRight: (message) =>
+      Match.value(message).pipe(
+        Match.tags({
+          RunHook: (request) => handleRunHook(request),
+          BashReply: (reply) => {
+            const resume = pendingBash.get(reply.id)
+            pendingBash.delete(reply.id)
+            resume?.(reply)
+          },
+        }),
+        Match.exhaustive,
+      ),
+  })
+}