@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/emit.ts

@@ -1,8 +1,10 @@
 import { randomBytes } from "node:crypto";
 import { isAbsolute, join } from "node:path";
+import type { ClientErrorCode } from "@agentswf/contract/client";
 import {
   type EmitResultJson,
-  MAILBOX_RECORD_VERSION,
+  type EventLine,
+  emitOk,
   type RunPanes,
 } from "@agentswf/contract/records";
 import { parseJsonSchema, validate } from "@agentswf/contract/schema";
@@ -17,18 +19,40 @@ import {
 } from "@agentswf/contract/workflow";
 import { messageOf } from "./errors";
 import { exists } from "./files";
-import { appendMailbox, foldMailbox, readMailbox } from "./mailbox";
+import { appendIn, readIn } from "./in-lines";
+import { checkProjectEngine, EngineRefused } from "./project-engine";
 import { projectOf, projectRunRoot, recordProject } from "./projects";
 import { runLockFile, withRunLock } from "./run-lock";
 import { prepareArgs } from "./run-prepare";
 import type { RunStatus } from "./run-state";
-import { createRun, idProblem, openRun, panesChanged, type Run, readAttempts } from "./runs";
+import {
+  createRun,
+  idProblem,
+  openRun,
+  panesChanged,
+  type Run,
+  RunTaken,
+  readAttempts,
+} from "./runs";
 import { type WakeContext, type Woken, wake } from "./wake";
-import { type EventWorkflow, loadWorkflowFile } from "./workflow-loader";
+import { type EventWorkflow, loadWorkflowFile, WorkflowFileError } from "./workflow-loader";
+
+/**
+ * What an `EmitError` is about, as a program's `ClientError` names it: the event, an id, the
+ * target's `prepare` or `id(args)`, its file, its project, the project's engine, or a run there
+ * started with other arguments or options.
+ */
+export type EmitCode = Extract<
+  ClientErrorCode,
+  "event" | "id" | "prepare" | "file" | "project" | "other-engine" | "no-engine" | "other-args"
+>;
 
 /** An event awf refuses to take at all: a name, shape or id no run of the target could have. */
 export class EmitError extends Error {
-  constructor(message: string) {
+  constructor(
+    message: string,
+    readonly code: EmitCode = "event",
+  ) {
     super(message);
     this.name = "EmitError";
   }
@@ -45,28 +69,35 @@ export type EmitContext = Omit<WakeContext, "file"> & {
  */
 export async function emitEvent(
   target: EventWorkflow,
-  event: { run: string; name: string; data: JsonValue; id?: string },
+  event: { run: string; name: string; data: JsonValue; id?: string; source?: string },
   context: EmitContext,
 ): Promise<EmitResultJson> {
   const workflow = target.meta.name;
-  const { name, data } = event;
+  const { name, data, source } = event;
   checkEvent(target, event);
+  const badSource = source === undefined ? undefined : nameProblem(source);
+  if (badSource) throw new EmitError(`the source ${JSON.stringify(source)}: ${badSource}`);
   const file = fileOf(target);
   const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
   const at = new Date(context.now?.() ?? Date.now()).toISOString();
   const runId = event.run;
   const problem = idProblem(runId);
-  if (problem) throw new EmitError(`the run's id: ${problem}`);
-  const project = await projectOf(file, context.home).catch((error: unknown) => {
-    throw new EmitError(messageOf(error));
-  });
+  if (problem) throw new EmitError(`the run's id: ${problem}`, "id");
+  const project = await targetProject(file, context.home);
   const starts = target.starts?.includes(name) ?? true;
   return deliver(
     {
       runRoot: projectRunRoot(project),
       workflow,
       runId,
-      event: { id, name, data, from: context.from, at },
+      event: {
+        id,
+        name,
+        data,
+        from: context.from,
+        ...(source === undefined ? {} : { source }),
+        at,
+      },
       deduplicate: event.id !== undefined,
       file,
       ...(starts ? { start: { project, target } } : {}),
@@ -79,11 +110,11 @@ export async function emitEvent(
  * `awf emit {ref} {key}:reply …`: a participant's message to the code of a run that is there,
  * checked against the definition in the file a wake would run, its last attempt's, and delivered.
  * It never starts a run, and doesn't ask whether the participant has connected: one sent before
- * the run connects it waits in the mailbox for the run's next wait.
+ * the run connects it waits in `in.jsonl` for the run's next wait.
  */
 export async function emitToRun(
   status: RunStatus,
-  event: { name: string; data: JsonValue; id?: string },
+  event: { name: string; data: JsonValue; id?: string; source?: string },
   context: Omit<WakeContext, "file">,
 ): Promise<EmitResultJson> {
   const { run, ref } = status;
@@ -98,10 +129,13 @@ export async function emitToRun(
   if (status.attempts.at(-1)?.outcome === "completed")
     return deliverReply(status, reply.key, event, context);
   const file = status.attempts.at(-1)?.file ?? run.record.file;
-  if (file === undefined) throw new Error(`${ref} has no file to check the event against`);
-  const { workflow } = await loadWorkflowFile(file, run.record.cwd);
+  if (file === undefined)
+    throw new WorkflowFileError(`${ref} has no file to check the event against`);
+  const { workflow } = await loadWorkflowFile(file, run.record.cwd, context.home);
   if (!isEventWorkflow(workflow) || workflow.meta.name !== run.record.workflow)
-    throw new Error(`${file} is no longer ${run.record.workflow} with events, which ${ref} ran`);
+    throw new WorkflowFileError(
+      `${file} is no longer ${run.record.workflow} with events, which ${ref} ran`,
+    );
   checkEvent(workflow, event, true);
   return deliverReply(status, reply.key, event, context);
 }
@@ -111,12 +145,14 @@ export async function emitToRun(
  * The caller has checked it.
  */
 export function deliverReply(
-  status: RunStatus,
+  status: Pick<RunStatus, "run">,
   key: string,
-  event: { data: JsonValue; id?: string },
+  event: { data: JsonValue; id?: string; source?: string },
   context: Omit<WakeContext, "file">,
 ): Promise<EmitResultJson> {
   const { run } = status;
+  const problem = event.source === undefined ? undefined : nameProblem(event.source);
+  if (problem) throw new EmitError(`the source ${JSON.stringify(event.source)}: ${problem}`);
   const at = new Date(context.now?.() ?? Date.now()).toISOString();
   const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
   return deliver(
@@ -124,7 +160,10 @@ export function deliverReply(
       runRoot: run.root,
       workflow: run.record.workflow,
       runId: run.record.id,
-      event: replyRecord(key, id, event.data, at),
+      event: {
+        ...replyRecord(key, id, event.data, at),
+        ...(event.source === undefined ? {} : { source: event.source }),
+      },
       deduplicate: event.id !== undefined,
     },
     context,
@@ -136,7 +175,7 @@ export type Delivery = {
   runRoot: string;
   workflow: string;
   runId: string;
-  event: { id: string; name: string; data: JsonValue; from: string; at: string };
+  event: { id: string; name: string; data: JsonValue; from: string; source?: string; at: string };
   /** False for an id awf made at random, which nothing repeats. */
   deduplicate: boolean;
   /** Given when the event may start the run: what a new run records, and the workflow it prepares. */
@@ -147,10 +186,10 @@ export type Delivery = {
 
 /**
  * The one way in, for every event a run of a workflow with events gets: a sender's, a participant's reply, or awf's
- * own. Under the run's lock it finds a duplicate, refuses the event, or creates the run, appends
- * the event and wakes the run.
+ * own. Under the run's lock it finds a duplicate, refuses the event, or appends the event, to a run
+ * there or into a new one's `in.jsonl` before the run exists, and wakes the run.
  */
-export async function deliver(
+async function deliver(
   delivery: Delivery,
   context: Omit<WakeContext, "file">,
 ): Promise<EmitResultJson> {
@@ -163,27 +202,46 @@ export async function deliver(
       : undefined;
     // What was due is `awf tick`'s to say; an emit's caller knows it sent an event.
     const result = (outcome: EmitResultJson["outcome"], { cause: _, ...woken }: Woken) =>
-      ({ v: 1, outcome, ref, eventId: event.id, ...woken }) satisfies EmitResultJson;
+      ({
+        v: 1,
+        ok: emitOk(outcome, woken.why),
+        outcome,
+        ref,
+        eventId: event.id,
+        ...woken,
+      }) satisfies EmitResultJson;
     if (run) {
+      // A disk that doesn't tell case apart opens another run for an id differing only in case.
+      if (run.record.id !== runId)
+        throw new EmitError(
+          `${ref} differs only in case from ${run.record.id}, which is there`,
+          "id",
+        );
+      if (!run.record.events)
+        throw new EmitError(`${ref} is a run of a workflow without events, which take none`);
       // Not appended again, but it still wakes the run: a sender retrying after a launch that failed
       // sends the same id.
-      if (delivery.deduplicate && foldMailbox(await readMailbox(run.dir)).events.has(event.id))
+      if (delivery.deduplicate && (await readIn(run.dir)).some((line) => line.id === event.id))
         return result("duplicate", await wake(run, { ...woken, nudgeLive: false }));
       if ((await readAttempts(run)).at(-1)?.outcome === "completed")
         return result("refused", { did: "none", why: "returned" });
     }
-    const starts = !run;
-    if (!run) {
+    if (run) await appendIn(run.dir, event);
+    else {
       if (!start) return result("refused", { did: "none", why: "not-a-start" });
       checkStartArgs(start.target, start.project);
-      run = await createEventRun(runRoot, workflow, runId, start.project, file, context);
+      // In the folder before it is renamed into place: no run exists without its first event.
+      const first: EventLine = { ...event, starts: true };
+      try {
+        run = await createEventRun(runRoot, workflow, runId, start.project, file, context, [], {
+          first,
+        });
+      } catch (error) {
+        // A disk that tells case apart: another case's run is found only as the folder is claimed.
+        if (error instanceof RunTaken) throw new EmitError(messageOf(error), "id");
+        throw error;
+      }
     }
-    await appendMailbox(run.dir, {
-      version: MAILBOX_RECORD_VERSION,
-      kind: "event",
-      ...event,
-      ...(starts ? { starts: true as const } : {}),
-    });
     return result("accepted", await wake(run, woken));
   });
 }
@@ -198,6 +256,7 @@ function checkStartArgs(target: EventWorkflow, project: string): void {
   } catch (error) {
     throw new EmitError(
       `${target.meta.name}: a run an event starts has no arguments, which its prepare refuses: ${messageOf(error)}`,
+      "prepare",
     );
   }
 }
@@ -211,20 +270,31 @@ async function createEventRun(
   file: string | undefined,
   context: Pick<WakeContext, "home" | "environment">,
   argv: readonly string[] = [],
-  panes?: RunPanes,
+  given: { panes?: RunPanes; first?: EventLine } = {},
 ): Promise<Run> {
-  const run = await createRun(runRoot, {
-    id,
-    workflow,
-    argv: [...argv],
-    cwd: project,
-    sandbox: null,
-    events: true,
-    env: { PATH: context.environment.PATH ?? "" },
-    ...(file ? { file } : {}),
-    ...(panes ? { panes } : {}),
-  });
-  await recordProject(context.home, project);
+  const { panes, first } = given;
+  const run = await createRun(
+    runRoot,
+    {
+      id,
+      workflow,
+      argv: [...argv],
+      cwd: project,
+      sandbox: null,
+      events: true,
+      env: { PATH: context.environment.PATH ?? "" },
+      ...(file ? { file } : {}),
+      ...(panes ? { panes } : {}),
+    },
+    undefined,
+    first,
+  );
+  try {
+    await recordProject(context.home, project);
+  } catch (error) {
+    // awf's own record of projects, not the run's: `internal-error`, as `awf run` refuses it.
+    throw new Error(`~/.awf/projects was not written: ${messageOf(error)}`);
+  }
   return run;
 }
 
@@ -246,11 +316,9 @@ export async function openEventRun(
 ): Promise<Opened> {
   const workflow = target.meta.name;
   const problem = idProblem(id);
-  if (problem) throw new EmitError(problem);
+  if (problem) throw new EmitError(problem, "id");
   const file = fileOf(target);
-  const project = await projectOf(file, context.home).catch((error: unknown) => {
-    throw new EmitError(messageOf(error));
-  });
+  const project = await targetProject(file, context.home);
   const runRoot = projectRunRoot(project);
   const ref = `${workflow}/${id}`;
   return withRunLock(runLockFile(runRoot, workflow, id), async () => {
@@ -261,22 +329,39 @@ export async function openEventRun(
         return { run: ref, created: false, did: "none", why: "returned" };
       if (argv.length > 0 && JSON.stringify(argv) !== JSON.stringify(run.record.argv))
         throw new EmitError(
-          `${ref} is there already, started with ${run.record.argv.length > 0 ? "arguments of its own" : "none"}; awf run --id ${id} with none wakes it`,
+          `${ref} is there already, started with ${run.record.argv.length > 0 || run.record.args !== undefined ? "arguments of its own" : "none"}; awf run --id ${id} with none wakes it`,
+          "other-args",
         );
       const changed = panesChanged(run.record, panes);
-      if (changed) throw new EmitError(changed);
+      if (changed) throw new EmitError(changed, "other-args");
       return { run: ref, created: false, ...(await wake(run, woken)) };
     }
     try {
       prepareArgs(target, argv, project);
     } catch (error) {
-      throw new EmitError(`prepare: ${messageOf(error)}`);
+      throw new EmitError(`prepare: ${messageOf(error)}`, "prepare");
     }
-    const run = await createEventRun(runRoot, workflow, id, project, file, context, argv, panes);
+    const run = await createEventRun(runRoot, workflow, id, project, file, context, argv, {
+      ...(panes ? { panes } : {}),
+    });
     return { run: ref, created: true, ...(await wake(run, woken)) };
   });
 }
 
+/** The project `file`'s runs live in, which must run on this engine (ADR 0015). */
+async function targetProject(file: string, home: string): Promise<string> {
+  const project = await projectOf(file, home).catch((error: unknown) => {
+    throw new EmitError(messageOf(error), "project");
+  });
+  try {
+    checkProjectEngine(project, { file });
+  } catch (error) {
+    if (error instanceof EngineRefused) throw new EmitError(error.message, error.code);
+    throw error;
+  }
+  return project;
+}
+
 /**
  * The target's file, which says which project its runs live in and which a start or wake runs:
  * `file`, or the path awf loaded it from. Only a sender holding the workflow itself, as `wf.emit`
@@ -286,12 +371,13 @@ function fileOf(target: EventWorkflow): string {
   if (target.file === undefined)
     throw new EmitError(
       `${target.meta.name} gives no file, by which a sender holding it finds it: file: import.meta.path`,
+      "file",
     );
   return target.file;
 }
 
 /**
- * `{key}:reply`'s event as the mailbox records it: `participant:reply` from its key, whatever the
+ * `{key}:reply`'s event as `in.jsonl` records it: `participant:reply` from its key, whatever the
  * workflow declares it as, so a wait takes it by one name.
  */
 export function replyRecord(
@@ -316,7 +402,10 @@ export function checkEvent(
   const problem = eventWorkflowProblem(target);
   if (problem) throw new EmitError(`${workflow}: ${problem}`);
   if (target.file !== undefined && !isAbsolute(target.file))
-    throw new EmitError(`${workflow}: its file, ${target.file}, is import.meta.path, absolute`);
+    throw new EmitError(
+      `${workflow}: its file, ${target.file}, is import.meta.path, absolute`,
+      "file",
+    );
   const reply = awfEventOf(event.name)?.kind === "reply";
   if (event.name.includes(":") && !(replies && reply))
     throw new EmitError(
@@ -343,7 +432,7 @@ export function checkEvent(
       `${event.name}'s data does not fit its schema: ${errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ")}`,
     );
   const badId = event.id === undefined ? undefined : eventIdProblem(event.id);
-  if (badId) throw new EmitError(`the id ${JSON.stringify(event.id)}: ${badId}`);
+  if (badId) throw new EmitError(`the id ${JSON.stringify(event.id)}: ${badId}`, "id");
 }
 
 /** What is wrong with an id a sender gives an event, if anything: ids starting `awf.` are awf's. */

package/src/event-ids.ts

@@ -0,0 +1,31 @@
+import { AWF_ID_PREFIX } from "@agentswf/contract/workflow";
+import type { DerivedIds } from "./run-policy/waits";
+
+function hashed(kind: string, text: string): string {
+  const hash = new Bun.CryptoHasher("sha256").update(text).digest("hex");
+  return `${AWF_ID_PREFIX}${kind}.${hash.slice(0, 16)}`;
+}
+
+/** The id timer `name` is taken under: made from its name, so it fires once. */
+export function timerEventId(name: string): string {
+  return hashed("timer", name);
+}
+
+/**
+ * The id of branch `branch`'s time read from state, `due` an ISO time: made from both, so a time is
+ * returned once by a branch of that name, whichever loop reads it.
+ */
+export function atEventId(branch: string, due: string): string {
+  return hashed("at", `${branch}\n${due}`);
+}
+
+/**
+ * The id of the end of `agent`'s turn `turn`, begun in attempt `began`: made from the three, so it
+ * fits the grammar whatever each is, and is the same whoever writes it, so one end is ever kept.
+ */
+export function endIdOf(agent: string, turn: string, began: number): string {
+  return hashed("end", `${agent}\0${turn}\0${began}`);
+}
+
+/** The derived ids, as the waits' policy takes them. */
+export const DERIVED_IDS: DerivedIds = { timer: timerEventId, at: atEventId };

package/src/files.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { link, lstat, open, rename, unlink } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 /** `path` with its symlinks resolved, or only made absolute when it doesn't exist. */
 export function realPath(path: string): string {
@@ -32,14 +32,38 @@ export async function writeWhole(path: string, text: string): Promise<void> {
   }
 }
 
+/**
+ * `text` at `path` whole, synchronously, for a writer that must not wait between two steps: a temp
+ * file renamed into place, mode `0600`. Not synced: it needs only to exist and be whole.
+ */
+export function writeWholeSync(path: string, text: string): void {
+  const temporary = temporaryBeside(path);
+  try {
+    writeFileSync(temporary, text, { mode: 0o600, flag: "wx" });
+    renameSync(temporary, path);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Never made, or gone already.
+    }
+    throw error;
+  }
+}
+
 /**
  * Links a complete file holding `value` to `path`, which fails when `path` exists: the first to
  * link holds it. False when it was taken.
  */
-export async function linkNew(path: string, value: unknown): Promise<boolean> {
+export function linkNew(path: string, value: unknown): Promise<boolean> {
+  return linkNewText(path, jsonText(value));
+}
+
+/** As `linkNew`, for text. */
+export async function linkNewText(path: string, text: string): Promise<boolean> {
   const temporary = temporaryBeside(path);
   try {
-    await writeSynced(temporary, jsonText(value));
+    await writeSynced(temporary, text);
     await link(temporary, path);
     return true;
   } catch (error) {
@@ -62,6 +86,22 @@ async function writeSynced(path: string, text: string): Promise<void> {
   }
 }
 
+/** Makes the entries of folder `dir`, a rename or link into it, durable. */
+export async function syncDir(dir: string): Promise<void> {
+  const handle = await open(dir, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Whether `path` is below `root`, not `root` itself; a child named `..x` is below it. */
+export function isInside(root: string, path: string): boolean {
+  const inside = relative(root, path);
+  return inside !== "" && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
+}
+
 /** Whether `path` names anything, a dangling link included. */
 export async function exists(path: string): Promise<boolean> {
   return lstat(path).then(

package/src/hand-over.ts

@@ -0,0 +1,150 @@
+// The global `awf`'s first step, before the engine is imported: a project whose installed `agentswf`
+// is another version runs on that one (ADR 0015). Imports nothing of the engine, so a hand-over
+// costs a Bun start and no more, and the engine's own checks can share how a project's engine is
+// found.
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The `agentswf` installed in a `node_modules` at or above a directory. */
+export type InstalledEngine = {
+  /** Its package's folder, its real path: what `AWF_ENGINE` names. */
+  dir: string;
+  /** The directory whose `node_modules` holds it: where its `awf` is run from. */
+  root: string;
+  /** Its `package.json`'s `version`, not the range a project declares. */
+  version: string;
+  /** Its `awf`, as its `package.json`'s `bin` gives it. */
+  bin: string;
+};
+
+/**
+ * A project's engine: installed, declared in the nearest `package.json` at or above it and not
+ * installed (or installed broken), or none, which any engine runs.
+ */
+export type ProjectEngine =
+  | ({ kind: "installed" } & InstalledEngine)
+  | { kind: "declared"; manifest: string }
+  | { kind: "none" };
+
+/**
+ * The `agentswf` found by walking up from `from` for `node_modules/agentswf/package.json`. Not
+ * Bun's resolver, whose auto-install answers with a cache copy where nothing is installed. One
+ * whose manifest gives no version or `awf` is broken, and its `package.json` is returned instead.
+ */
+export function installedEngine(from: string): InstalledEngine | undefined {
+  const found = findEngine(from);
+  return found && "version" in found ? found : undefined;
+}
+
+function findEngine(from: string): InstalledEngine | { broken: string } | undefined {
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    const manifest = join(dir, "node_modules", "agentswf", "package.json");
+    if (existsSync(manifest)) {
+      const read = readManifest(manifest);
+      const bin = typeof read?.bin === "object" ? read.bin?.awf : read?.bin;
+      if (typeof read?.version !== "string" || typeof bin !== "string") return { broken: manifest };
+      const root = realpathSync(dirname(manifest));
+      return { dir: root, root: dir, version: read.version, bin: resolve(root, bin) };
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * `project`'s engine: the one installed above it, else one the nearest `package.json` at or above
+ * it declares.
+ */
+export function projectEngine(project: string): ProjectEngine {
+  const found = findEngine(project);
+  if (found && "broken" in found) return { kind: "declared", manifest: found.broken };
+  if (found) return { kind: "installed", ...found };
+  for (let dir = resolve(project); ; dir = dirname(dir)) {
+    const manifest = join(dir, "package.json");
+    if (existsSync(manifest)) {
+      const read = readManifest(manifest);
+      const declared = ["dependencies", "devDependencies", "optionalDependencies"].some((field) => {
+        const deps = read?.[field];
+        return typeof deps === "object" && deps !== null && "agentswf" in deps;
+      });
+      return declared ? { kind: "declared", manifest } : { kind: "none" };
+    }
+    if (dirname(dir) === dir) return { kind: "none" };
+  }
+}
+
+type Manifest = Record<string, unknown> & {
+  version?: unknown;
+  bin?: string | { awf?: unknown };
+};
+
+function readManifest(file: string): Manifest | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return typeof value === "object" && value !== null ? (value as Manifest) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Set on an `awf` a hand-over runs: the engine it is, so that one doesn't hand over again. */
+export const ENGINE_VARIABLE = "AWF_ENGINE";
+
+/**
+ * What the global `awf` does first: when the `agentswf` installed above the shell's directory is
+ * another version than its own, it warns, runs that one's `awf` with the same argv, and exits as
+ * it does. Returns when this `awf` runs the command itself. `init`, `help`, `--version` and
+ * `tick --all` name no project's runs, and are never handed over.
+ */
+export async function handOver(own: {
+  /** This `awf`'s `agentswf` folder. */
+  dir: string;
+  version: string;
+  argv?: readonly string[];
+  cwd?: string;
+  environment?: Readonly<Record<string, string | undefined>>;
+}): Promise<void> {
+  const argv = own.argv ?? process.argv.slice(2);
+  const environment = own.environment ?? process.env;
+  const target = handOverTarget(argv, own.cwd ?? process.cwd(), own.version);
+  if (!target) return;
+  // The child, walking from the same directory, finds itself; the guard is for a loop all the same.
+  if (environment[ENGINE_VARIABLE] === realpathSync(own.dir)) return;
+  process.stderr.write(
+    `awf: awf ${own.version} is not this project's ${target.version}; running the project's. Update one, or run bunx awf here.\n`,
+  );
+  const child = Bun.spawn({
+    cmd: [process.execPath, "--no-env-file", target.bin, ...argv],
+    env: { ...environment, [ENGINE_VARIABLE]: target.dir },
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
+  // Each is forwarded, for a signal sent to this process alone. The terminal's Ctrl-C reaches the
+  // child twice, through the process group too, and a run takes a repeat within a second as one;
+  // the prompt comes back once the child has ended, not before.
+  const listeners: [NodeJS.Signals, () => void][] = [
+    ["SIGTERM", forward("SIGTERM")],
+    ["SIGHUP", forward("SIGHUP")],
+    ["SIGINT", forward("SIGINT")],
+  ];
+  for (const [signal, listener] of listeners) process.on(signal, listener);
+  const code = await child.exited;
+  for (const [signal, listener] of listeners) process.off(signal, listener);
+  if (child.signalCode) process.kill(process.pid, child.signalCode);
+  process.exit(code ?? 1);
+}
+
+/** The engine `argv`, typed in `cwd`, is handed over to; undefined when this one runs it. */
+export function handOverTarget(
+  argv: readonly string[],
+  cwd: string,
+  version: string,
+): InstalledEngine | undefined {
+  const [word] = argv;
+  if (word === undefined || NOT_HANDED_OVER.has(word)) return undefined;
+  if (word === "tick" && argv.includes("--all")) return undefined;
+  const installed = installedEngine(cwd);
+  return installed && installed.version !== version ? installed : undefined;
+}
+
+const NOT_HANDED_OVER = new Set(["init", "help", "-h", "--help", "--version"]);

package/src/help/allowance.txt

@@ -8,6 +8,7 @@ none is named: claude, codex, pi, cursor.
 A plan's monthly price is an estimate at the vendor's list price as of the table's date:
 plans 2026-10-05.
 
---json prints one document, the interface for scripts, with the plan as the
-harness names it and no price; what it prints otherwise is for reading. A harness that could
-not be read says why. Exits 0 once every harness was asked, 2 on a usage error.
+--json prints one document, the interface for scripts, with the plan as the harness names it and
+no price; what it prints otherwise is for reading. A harness that could not be read says why; a
+failure is a refusal whose code says why: usage or internal-error. Exits 0 once every harness
+was asked, 2 on a usage error.