@vibest/plugin 0.0.0-stage → 0.0.1-beta.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamdin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@vibest/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1-beta.14",
+  "description": "Authoring API for vibest plugins. vibestd provides this module (and effect) to plugins at runtime.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibest-dev/vibest.git",
+    "directory": "packages/plugin"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "effect": "4.0.2"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsrs --noEmit --fast"
+  }
 }

package/src/index.ts

@@ -0,0 +1,182 @@
+// @vibest/plugin: what an vibest plugin is written against. vibestd maps this module (and `effect`) to its own instances when it
+// loads a plugin, so a plugin imports it normally and never bundles either. See architecture.md §8 and §9.
+import { type Effect, Schema, type Scope } from "effect"
+
+import type { RuntimeRegistry } from "./runtime.ts"
+
+export * as Plugin from "./plugin.ts"
+export * as Runtime from "./runtime.ts"
+
+/** An `agent.start.before` callback fails with this to refuse the start; vibestd reports the reason and the plugin. */
+export class AgentRefused extends Schema.TaggedError<AgentRefused>()("AgentRefused", { reason: Schema.String }) {}
+
+/** One usage window a plugin, or a poll, reports. `percent` is 0–100. */
+export interface SubscriptionLimit {
+  readonly window: string
+  readonly percent: number
+  readonly status: "available" | "limited"
+  readonly resetTime: number | null
+}
+
+/**
+ * One harness login as vibestd last read it. `provider` is empty for Claude Code and Cursor, and set for Pi.
+ * `limits` empty means unknown, not unlimited.
+ */
+export interface SubscriptionSnapshot {
+  readonly harness: string
+  readonly provider: string
+  readonly machine: "local"
+  readonly account: {
+    readonly kind: "subscription" | "api-key" | "none"
+    readonly plan?: string | undefined
+    readonly provider?: string | undefined
+  }
+  readonly limits: ReadonlyArray<SubscriptionLimit>
+  readonly updatedAt: number
+  readonly error?: string | undefined
+}
+
+/** Limits a plugin reports for one `(harness, provider)`. The next poll of a harness that reads usage replaces them. */
+export interface SubscriptionReport {
+  readonly harness: string
+  readonly provider?: string
+  readonly limits: ReadonlyArray<SubscriptionLimit>
+}
+
+/** One runtime as vibestd last saw it on a machine (runtime-port.md §4, §7). */
+export interface MachineRuntime {
+  readonly kind: string
+  readonly status: "online" | "offline" | "blocked"
+  readonly reason?: string | undefined
+}
+
+/** One machine as `agent.start.before` reports it: the runtimes on it and the harnesses vibestd could start there. */
+export interface MachineInfo {
+  readonly machine: string
+  readonly runtimes: ReadonlyArray<MachineRuntime>
+  readonly harnesses: ReadonlyArray<string>
+}
+
+/** A harness vibestd could start, as preflight saw it. */
+export interface HarnessOption {
+  readonly harness: string
+  /** On PATH, logged in, its model list read. false: `problem` says why. */
+  readonly available: boolean
+  readonly problem?: string | undefined
+}
+
+/** One earlier try for this session (a move, or a start that failed or was refused before). */
+export interface Attempt {
+  readonly harness: string
+  readonly provider: string | undefined
+  readonly outcome: "limited" | "start_failed" | "not_confirmed" | "unavailable" | "refused"
+  readonly at: number
+}
+
+/** Read-only context every agent hook gets. */
+export interface AgentContext {
+  /** The project directory. */
+  readonly project: string
+  /** `main` for the project's main agent, otherwise the definition (`general`, `reviewer`, …). */
+  readonly agentType: string
+  /** Who asked; undefined for the main agent and the user's own `vibest run`. */
+  readonly parentSessionId: string | undefined
+  readonly harnesses: ReadonlyArray<HarnessOption>
+  /** Logins and usage windows vibestd has right now, per (harness, provider). */
+  readonly subscriptions: ReadonlyArray<SubscriptionSnapshot>
+  /** Earlier tries for this session, oldest first; empty on a first start. */
+  readonly attempts: ReadonlyArray<Attempt>
+}
+
+/**
+ * Before any Agent starts, the main agent included. Plugins change the writable fields in place; vibestd runs callbacks
+ * one after another in plugin order, so a later plugin sees (and may overwrite) what an earlier one wrote.
+ * vibestd validates `harness` and `runtime` after the chain.
+ */
+export interface AgentStartBefore extends AgentContext {
+  /** The caller's text; a plugin may rewrite it. Empty for the main agent. */
+  prompt: string
+  /** The caller's preference on entry (undefined: none); the builtin default fills it. */
+  harness: string | undefined
+  provider: string | undefined
+  model: string | undefined
+  /** The machine to start on (writable; `local` is all there is today). */
+  machine: { id: string }
+  /** The terminal runtime to start in (writable): a `kind` from `machines`. The builtin choice plugin fills it. */
+  runtime: string | undefined
+  /** The runtime the parent session runs in (a subagent opens beside its parent, runtime-port.md §4); undefined for the user's own run. */
+  readonly parentRuntime: string | undefined
+  /** Every machine vibestd knows, with the runtimes on it and the harnesses it could start there (§7). */
+  readonly machines: ReadonlyArray<MachineInfo>
+}
+
+/**
+ * A started Agent's round failed on `reason`. Set `move` to restart the same session on another harness/provider.
+ */
+export interface AgentFail extends AgentContext {
+  readonly sessionId: string
+  /** Only reason produced today; the type is a union so more can be added. */
+  readonly reason: "limited"
+  /** The harness's own error text. */
+  readonly error: string
+  /** The failed round's text (what will be resent). */
+  readonly turn: string
+  readonly harness: string
+  readonly provider: string | undefined
+  move: { harness: string; provider?: string | undefined; model?: string | undefined } | undefined
+}
+
+/**
+ * A subagent's round is about to go idle. Set `prompt` to keep it working on that text instead.
+ * `prompt` is the only decision. `output` is a failure tail and does not stop the chain.
+ */
+export interface AgentIdle {
+  readonly sessionId: string
+  /** `main` for the project's main agent, otherwise the definition (`general`, …). */
+  readonly agentType: string
+  /** The directory the agent works in. */
+  readonly directory: string
+  /** The agent's last answer. */
+  readonly answer: string
+  /** Finished check attempts for this session, counted by the host. The plugin only compares it to its limit. */
+  readonly checkAttempts: number
+  /** Set once this result's command has finished. The plugin must not ask to run it again. */
+  readonly ran: { readonly ok: boolean; readonly tail: string } | undefined
+  /** Set when the host should run this command outside the lock. Not a decision. */
+  command: string | undefined
+  prompt: string | undefined
+  /** Tail of a failing check once the attempt budget is spent. Not a decision. */
+  output: string | undefined
+}
+
+/** Every hook: the event its callbacks get and the error they may fail with. */
+export interface Hooks {
+  readonly "agent.start.before": { readonly event: AgentStartBefore; readonly error: AgentRefused }
+  readonly "agent.fail": { readonly event: AgentFail; readonly error: never }
+  readonly "agent.idle": { readonly event: AgentIdle; readonly error: never }
+}
+
+/** The hook names of one domain without its prefix: `start.before` for `agent.start.before`. */
+export type HookOf<D extends string> = { [K in keyof Hooks]: K extends `${D}.${infer S}` ? S : never }[keyof Hooks]
+
+export interface Domain<D extends string> {
+  /** Registered until the plugin is unloaded (its scope closes). A name not in `Hooks` fails the plugin's setup. */
+  readonly hook: <N extends HookOf<D>>(
+    name: N,
+    callback: (
+      event: Hooks[Extract<`${D}.${N}`, keyof Hooks>]["event"],
+    ) => Effect.Effect<void, Hooks[Extract<`${D}.${N}`, keyof Hooks>]["error"]>,
+  ) => Effect.Effect<void, never, Scope.Scope>
+}
+
+export interface Context {
+  /** This plugin's `options` from vibest.json. */
+  readonly options: Readonly<Record<string, unknown>>
+  readonly agent: Domain<"agent">
+  /** Register a terminal runtime (`runtime-port.md`). Beside `agent.hook`; kept for the plugin's lifetime. */
+  readonly runtime: RuntimeRegistry
+  readonly subscription: {
+    /** Set the limits for `(harness, provider)` on this machine. Replaces that row's limits until the next usage poll. */
+    readonly report: (input: SubscriptionReport) => Effect.Effect<void>
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,12 @@
+import type { Effect, Scope } from "effect"
+
+import type { Context } from "./index.ts"
+
+export interface Plugin {
+  readonly id: string
+  /** Setup: register hooks. Runs once per load in the plugin's own scope; resources acquired here are released on unload. */
+  readonly effect: (ctx: Context) => Effect.Effect<void, never, Scope.Scope>
+}
+
+/** Returns the plugin unchanged; it only gives the object its type. */
+export const define = (plugin: Plugin) => plugin

package/src/runtime.ts

@@ -0,0 +1,133 @@
+// Runtime plugin API (runtime-port.md, `runtime-api.ts`, accepted). Rules that keep it small and extensible:
+// - No API version field: the API ships with vibest. Additions are optional members; a breaking change ships in a
+//   vibest release and plugins update with it.
+// - Core checks whether an optional member exists, never which runtime it is.
+// - One error type; `code` says what happened.
+// - Connections are the plugin's business: it opens, reuses and re-opens them per machine inside its own scope.
+import { type Effect, Schema, type Stream } from "effect"
+
+/** `local`, or a saved machine; `target` is the runtime's to read (an ssh target, a host label, …). */
+export interface Machine {
+  readonly id: string
+  readonly target?: string
+}
+
+/** A terminal: the machine it is on and the runtime's own id there (opaque to core). Stored on the Agent row. */
+export interface Terminal {
+  readonly machine: string
+  readonly id: string
+}
+
+export class RuntimeError extends Schema.TaggedError<RuntimeError>()("RuntimeError", {
+  /** not_found | busy | unreachable (transient, retried) | incompatible (needs the user) | failed (anything else) */
+  code: Schema.Literals(["not_found", "busy", "unreachable", "incompatible", "failed"]),
+  message: Schema.String,
+}) {}
+
+export type MachineStatus =
+  | { readonly status: "online" }
+  | { readonly status: "offline" | "blocked"; readonly reason: string }
+
+export type AgentState = "idle" | "working" | "blocked" | "unknown"
+
+/** One line of `vibest doctor` about a runtime: what is fine or not, and the command that fixes it. */
+export interface RuntimeCheck {
+  readonly ok: boolean
+  /** What the line is about: a harness id, or none for the runtime itself. */
+  readonly subject?: string
+  readonly text: string
+  readonly fix?: string
+}
+
+/** What `vibest doctor` shows for a runtime on a machine. */
+export interface RuntimeReport {
+  /** The runtime as the user knows it, with its version when known (`herdr 0.9.5`). */
+  readonly name: string
+  readonly checks: ReadonlyArray<RuntimeCheck>
+}
+
+export type RuntimeEvent =
+  | { readonly type: "exited"; readonly terminal: Terminal }
+  | { readonly type: "state"; readonly terminal: Terminal; readonly state: AgentState }
+  /** A machine's connection was re-made or its runtime restarted: core re-reads what it needs there. */
+  | { readonly type: "reset"; readonly machine: string }
+
+/** What a runtime plugin registers. */
+export interface Runtime {
+  /** Stored on each Agent row (`runtime.kind`); unique among loaded plugins. */
+  readonly kind: string
+  /** Usable on this machine now. `local` not installed → blocked with the reason. */
+  readonly status: (machine: Machine) => Effect.Effect<MachineStatus>
+
+  /** A terminal running `argv` exactly, kept with the project's other terminals (the runtime decides how). */
+  readonly open: (
+    machine: Machine,
+    input: {
+      readonly project: string
+      readonly cwd: string
+      readonly argv: ReadonlyArray<string>
+      readonly env: Readonly<Record<string, string>>
+      readonly label: string
+      /** Put it beside this terminal when possible. */
+      readonly near?: Terminal
+      /** As a split beside `near` instead of a tab of its own (`vibest run --peer`), when the runtime can. */
+      readonly split?: boolean
+      /** Focus the terminal when the runtime has such a notion (a terminal the user is waiting to see). */
+      readonly focus?: boolean
+    },
+  ) => Effect.Effect<Terminal, RuntimeError>
+  /** Type text and/or press keys (enter, esc, ctrl+c, …). */
+  readonly send: (
+    terminal: Terminal,
+    input: { readonly text?: string; readonly keys?: ReadonlyArray<string> },
+  ) => Effect.Effect<void, RuntimeError>
+  /** The last `lines` lines of output. */
+  readonly read: (terminal: Terminal, lines: number) => Effect.Effect<string, RuntimeError>
+  /** Is its program still running; its exit code once it is not. `not_found` once the terminal is gone. */
+  readonly process: (
+    terminal: Terminal,
+  ) => Effect.Effect<{ readonly running: boolean; readonly exitCode?: number }, RuntimeError>
+  readonly close: (terminal: Terminal) => Effect.Effect<void, RuntimeError>
+
+  // Optional. Missing → core's fallback in brackets.
+  /** What the runtime sees of the agent; `not_found` when it names no agent in that terminal (core reads "absent"). [vibest's harness integration only] */
+  readonly state?: (terminal: Terminal) => Effect.Effect<AgentState, RuntimeError>
+  /** The harness conversation id the runtime's own agent record names, when it has one. [the harness's reports only] */
+  readonly session?: (terminal: Terminal) => Effect.Effect<string | null, RuntimeError>
+  /**
+   * Run `argv` in an existing terminal once it is back at an idle shell (its program ended): the counterpart of `open` for
+   * a terminal that already exists. Fails when the terminal is gone or its shell does not come back. [no restart in
+   * place: `vibest update` and a usage-limit move leave such a terminal's agent for the user to restart]
+   */
+  readonly run?: (terminal: Terminal, argv: ReadonlyArray<string>) => Effect.Effect<void, RuntimeError>
+  /** Pushed changes, every machine. [poll `process`] */
+  readonly events?: Stream.Stream<RuntimeEvent>
+  /** One-off command on a machine. [run it in a hidden terminal: `open`, wait for exit, `read`] */
+  readonly exec?: (
+    machine: Machine,
+    argv: ReadonlyArray<string>,
+    cwd: string,
+  ) => Effect.Effect<{ readonly code: number; readonly output: string }, RuntimeError>
+  /**
+   * Labels and tokens shown on a terminal. [the `label` given to `open`] The keys vibest sends: `agent`, `harness`,
+   * `title`, `definition` and `session` label the terminal; `project` and `live` label the project's workspace. Any
+   * other key a caller passes is the caller's own; a runtime shows only what it knows a key for.
+   */
+  readonly present?: (terminal: Terminal, info: Readonly<Record<string, string>>) => Effect.Effect<void, RuntimeError>
+  /** Set a machine up on the runtime's side (`vibest machine add`). [the user does it] */
+  readonly prepare?: (machine: Machine) => Effect.Effect<void, RuntimeError>
+  /** What `vibest doctor` shows: anything the runtime needs for `harnesses` to work in it, with fixes. [its `status` only] */
+  readonly doctor?: (machine: Machine, harnesses: ReadonlyArray<string>) => Effect.Effect<RuntimeReport>
+  /** The command that shows this runtime on a machine to the user. [none] */
+  readonly attach?: (machine: Machine) => ReadonlyArray<string>
+}
+
+/** In the plugin context, beside `agent.hook`. Registered for the plugin's lifetime; its connections close with it. */
+export interface RuntimeRegistry {
+  readonly register: (runtime: Runtime) => Effect.Effect<void>
+}
+
+// export default Plugin.define({
+//   id: "runtime-tern",
+//   effect: (context) => context.runtime.register({ kind: "tern", status, open, send, read, process, close, attach: () => ["tern"] }),
+// })

package/src/testing.ts

@@ -0,0 +1,216 @@
+// `runtimeContract` (runtime-port.md §3): every runtime plugin passes this against a real local instance before it
+// ships — the required members first, then each optional member present. Framework-free: it fails with
+// `ContractFailure` naming the member and why, so any runner (a test file, a CLI check) can drive it.
+import { Cause, Duration, Effect, Exit, Option, Ref, Schema, type Scope, Stream } from "effect"
+
+import type * as Runtime from "./runtime.ts"
+
+export { type Runtime } from "./runtime.ts"
+
+/** One contract violation: the member under test and what it did. */
+export class ContractFailure extends Schema.TaggedError<ContractFailure>()("ContractFailure", {
+  member: Schema.String,
+  message: Schema.String,
+}) {}
+
+/** What the contract can fail with: its own violation, or the runtime's error from the call it made. */
+export type ContractError = ContractFailure | Runtime.RuntimeError
+
+const fail = (member: string, message: string) => new ContractFailure({ member, message: `runtime ${message}` })
+const that = (member: string, ok: boolean, message: string) => (ok ? Effect.void : Effect.fail(fail(member, message)))
+
+/** Poll `read` until `ready` is true, `what` names the wait in the failure. */
+const until = <A, E, R>(
+  member: string,
+  read: Effect.Effect<A, E, R>,
+  ready: (value: A) => boolean,
+  what: string,
+  timeout: Duration.Duration,
+) =>
+  Effect.gen(function* () {
+    const deadline = Date.now() + Duration.toMillis(timeout)
+    for (;;) {
+      const value = yield* read
+      if (ready(value)) return value
+      if (Date.now() >= deadline) return yield* Effect.fail(fail(member, `${what} within ${Duration.format(timeout)}`))
+      yield* Effect.sleep("100 millis")
+    }
+  })
+
+export interface ContractOptions {
+  /** Where `open` places its terminal (a scratch directory the caller owns). */
+  readonly cwd: string
+  /** How long one wait may take (default 15 s). */
+  readonly timeout?: Duration.Input
+}
+
+/**
+ * Run the contract: `status`, `open` (argv exactly, env, label), `send` (text and keys), `read`, `process`, `close`,
+ * then `state`, `session`, `exec` and `present` when the runtime has them. `prepare` and `attach` are checked as
+ * members only: `prepare` changes a machine's setup and `attach` opens the runtime's own interface, so the contract
+ * never runs them. `events`, when present, is proven by the `exited` event of the terminal the contract itself closes;
+ * `process` on the closed terminal by `not_found` once it is gone, and on a program that ended on its own by
+ * `running: false` (its exit code when the runtime knows one). `run`, when present, runs a command in that terminal
+ * once its program ended.
+ */
+export const runtimeContract = (
+  runtime: Runtime.Runtime,
+  options: ContractOptions,
+): Effect.Effect<void, ContractError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const timeout = Duration.fromInputUnsafe(options.timeout ?? "15 seconds")
+    const local: Runtime.Machine = { id: "local" }
+    const marker = `vbt-contract-${Math.random().toString(16).slice(2, 8)}`
+    // Typed into the shell `open` started, so the read proves the program ran rather than seeing its own typed command echoed.
+    const ran = (word: string) => `printf 'vbt-%s-${word}\n' "$VBT_CONTRACT"`
+
+    const shown = yield* runtime.status(local)
+    yield* that(
+      "status",
+      shown.status === "online" || shown.status === "offline" || shown.status === "blocked",
+      `reported a status that is not one of online, offline, blocked: ${JSON.stringify(shown)}`,
+    )
+
+    // The events follower runs from the start: the program that ends on its own must be seen without anyone closing it.
+    const seen = yield* Ref.make<ReadonlyArray<Runtime.RuntimeEvent>>([])
+    if (runtime.events !== undefined)
+      yield* runtime.events.pipe(
+        Stream.runForEach((event) => Ref.update(seen, (events) => [...events, event])),
+        Effect.forkScoped,
+        Effect.catchCause(() => Effect.void),
+      )
+
+    // An interactive shell, driven by `send`: the argv runs exactly, and the env it was given reaches what runs there.
+    const terminal = yield* runtime.open(local, {
+      project: options.cwd,
+      cwd: options.cwd,
+      argv: ["/bin/sh"],
+      env: { VBT_CONTRACT: marker },
+      label: `vibest contract ${marker}`,
+    })
+    yield* that("open", typeof terminal.id === "string" && terminal.id !== "", "returned a terminal without an id")
+
+    yield* runtime.send(terminal, { text: ran("sent"), keys: ["enter"] })
+    yield* until(
+      "send",
+      runtime.read(terminal, 40),
+      (out) => out.includes(`vbt-${marker}-sent`),
+      "did not run the text typed with send",
+      timeout,
+    )
+
+    // Polled: a runtime may take a moment to see the program the terminal is running.
+    yield* runtime.send(terminal, { text: "sleep 60", keys: ["enter"] })
+    yield* until(
+      "process",
+      runtime.process(terminal),
+      (state) => state.running,
+      "did not report the program running while it still sleeps",
+      timeout,
+    )
+
+    if (runtime.state !== undefined) {
+      // `not_found` is a valid answer: the runtime names no agent in a terminal it did not start one in (a plain
+      // shell), which core reads as "absent" (§3). Any other answer must be a state of the union.
+      const state = yield* runtime
+        .state(terminal)
+        .pipe(
+          Effect.catchTag("RuntimeError", (e) =>
+            e.code === "not_found" ? Effect.succeed("absent" as const) : Effect.fail(e),
+          ),
+        )
+      yield* that(
+        "state",
+        state === "absent" || state === "idle" || state === "working" || state === "blocked" || state === "unknown",
+        `reported a state that is not one of idle, working, blocked, unknown: ${JSON.stringify(state)}`,
+      )
+    }
+
+    if (runtime.session !== undefined) {
+      const session = yield* runtime.session(terminal)
+      yield* that(
+        "session",
+        session === null || typeof session === "string",
+        `returned something other than a conversation id or null: ${JSON.stringify(session)}`,
+      )
+    }
+
+    if (runtime.present !== undefined) yield* runtime.present(terminal, { contract: marker })
+
+    if (runtime.exec !== undefined) {
+      const ran = yield* runtime.exec(local, ["printf", "contract-exec"], options.cwd)
+      yield* that(
+        "exec",
+        ran.code === 0 && ran.output.includes("contract-exec"),
+        `printf contract-exec gave code ${ran.code} and ${JSON.stringify(ran.output)}`,
+      )
+    }
+
+    if (runtime.attach !== undefined) {
+      const argv = runtime.attach(local)
+      yield* that(
+        "attach",
+        argv.every((part) => typeof part === "string" && part !== ""),
+        "returned something other than a non-empty argv",
+      )
+    }
+
+    // A program that exits on its own: `process` stops reporting it running (its exit code when the runtime knows
+    // one; `not_found` once the terminal went with it) — no `close` ran.
+    const ended = yield* runtime.open(local, {
+      project: options.cwd,
+      cwd: options.cwd,
+      argv: ["/bin/sh", "-c", "exit 3"],
+      env: { VBT_CONTRACT: marker },
+      label: `vibest contract ${marker} exit`,
+    })
+    const gone = yield* until(
+      "process",
+      runtime.process(ended).pipe(Effect.exit),
+      (exit) => {
+        if (Exit.isFailure(exit)) {
+          const error = Cause.squash(exit.cause) as { readonly code?: string }
+          return error.code === "not_found"
+        }
+        return !exit.value.running
+      },
+      "did not report the exited program not running",
+      timeout,
+    )
+    if (Exit.isSuccess(gone) && gone.value.exitCode !== undefined)
+      yield* that(
+        "process",
+        gone.value.exitCode === 3,
+        `reported exit code ${gone.value.exitCode} for a program that ran exit 3`,
+      )
+    // The terminal is back at its shell: `run` starts the next program there.
+    if (runtime.run !== undefined && Exit.isSuccess(gone)) {
+      yield* runtime.run(ended, ["/bin/sh", "-c", ran("again")])
+      yield* until(
+        "run",
+        runtime.read(ended, 40),
+        (out) => out.includes(`vbt-${marker}-again`),
+        "did not run the command in the terminal whose program ended",
+        timeout,
+      )
+    }
+    if (Exit.isSuccess(gone)) yield* runtime.close(ended)
+
+    yield* runtime.close(terminal)
+    if (runtime.events !== undefined)
+      yield* until(
+        "events",
+        Ref.get(seen),
+        (events) => events.some((event) => event.type === "exited" && event.terminal.id === terminal.id),
+        `emitted no exited event for the closed terminal ${terminal.id}`,
+        timeout,
+      )
+
+    yield* until(
+      "process",
+      runtime.process(terminal).pipe(Effect.flip, Effect.option),
+      (found) => Option.isSome(found) && found.value.code === "not_found",
+      `kept answering process for the closed terminal ${terminal.id} instead of not_found`,
+      Duration.fromInputUnsafe("5 seconds"),
+    )
+  }).pipe(Effect.asVoid)

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.