@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/task.d.ts

@@ -0,0 +1,504 @@
+import type { Fleet } from "./fleet.ts";
+import { classifyPathEntry as classifyEntry, readRegularPathIfPresent as readRegularFileIfPresent, refuseOpenPathForWrite as refuseOpenForWrite } from "./fleet.ts";
+/**
+ * Task state (kernel plan v1, M1-P4 step 1). A task's durable state is
+ * <fleet>/tasks/<id>/, holding plain JSON per plan decision D-3:
+ *
+ *   meta.json    the task record written by spawn and closed by teardown
+ *   brief.md     the assembled brief (src/brief.ts)
+ *   turn-end     the payload's completion record (src/hooks.ts)
+ *   executor.json the launch record written by the executor adapter
+ *   report.md    a scout's report, the teardown gate for shape scout
+ *
+ * PLAN CONSTRAINT C-1 (FM-052, FM-049), binding on every consumer: the
+ * ONE current-state authority for a task is meta.json's status plus the
+ * turn-end file's recorded exit code. Currency is never derived from the
+ * tail of an event or status log, and the turn-end file is a completion
+ * NOTIFICATION, not the task's state: a missing turn-end never means
+ * success (tuition T-002).
+ *
+ * The task directory deliberately sits OUTSIDE the worktree (FM-059), so
+ * the pool's dirty check never needs an exemption list for the kernel's
+ * own injected files. That invariant is absolute: nothing this phase
+ * writes may ever land inside <fleet>/worktrees/<id>.
+ */
+/**
+ * OPEN NOTHING WHOSE TYPE HAS NOT BEEN ESTABLISHED (fix round 4, CR-520).
+ *
+ * THE MECHANISM AND ITS RULE. Opening a path is not a total operation.
+ * open(2) on a named pipe with no peer BLOCKS IN THE KERNEL, for reading
+ * and for writing, until a peer appears. A block is not an exception, so
+ * no try/catch sees it, no "this function never raises" reasoning touches
+ * it, and no error classification reaches it. Every process that reaches
+ * such an open stops forever with no output at all.
+ *
+ * This project has now paid for that mechanism three times in one phase:
+ * once at tasks/<id>/meta.json (delta review NEW-2), then on six further
+ * paths after the first fix was applied at ONE CALL SITE instead of at the
+ * read (CR-520), then on four more this round found by deriving the
+ * inventory again rather than inheriting it. The lesson recorded in
+ * tuition T-005 is that a rule fixed at a call site does not travel; the
+ * rule has to be a property of the operation.
+ *
+ * So the probe lives HERE, in the readers and in one classifier, and every
+ * caller is protected by construction rather than by remembering:
+ *
+ *   - lstat the path (the link itself), then stat (what it resolves to),
+ *     and open ONLY when that is a regular file;
+ *   - a directory, FIFO, socket, device node, or a symlink resolving to
+ *     any of those is classified WITHOUT being opened;
+ *   - nothing at the path is not an error, because absence is the normal
+ *     transient shape of most of this kernel's state files.
+ *
+ * WHY THIS LIVES IN src/task.ts. It is a general filesystem rule and not a
+ * task rule, and a dedicated module would be its right home. This module
+ * is the lowest one in the import graph that the fix round authorized to
+ * touch (src/liveness.ts imports it, src/watcher.ts imports it, and it
+ * imports neither), and it already carries one cross-cutting helper for
+ * the same reason (runStep, below). Moving both to their own module is
+ * recorded as an M2 item rather than done here without authorization.
+ *
+ * RESIDUAL, stated rather than papered over: the probe and the open are
+ * two syscalls, so a path that changes type between them can still be
+ * opened as something other than a regular file. Closing that needs
+ * open(O_NONBLOCK) followed by fstat, which Node's synchronous fs API
+ * does not expose for reads. Nothing in this kernel writes that state, and
+ * the window is now the only way to reach the block rather than the
+ * default path to it.
+ */
+/**
+ * ONE IMPLEMENTATION, RE-EXPORTED, AND THAT IS THE DR-0047 SWEEP ROUND 2
+ * CONSOLIDATION.
+ *
+ * The paragraphs above explain WHY the probe exists and they still hold. What
+ * changed is where it lives. Until this round there were TWO byte-equivalent
+ * copies of it: `classifyEntry`/`readRegularFileIfPresent`/`refuseOpenForWrite`
+ * here, and `classifyPathEntry`/`readRegularPathIfPresent`/
+ * `refuseOpenPathForWrite` in src/fleet.ts, with identical types, identical
+ * bodies and identical sentences. Round 1 created the second deliberately and
+ * both implementers flagged it: src/lock.ts and src/exclusion.ts sit BELOW this
+ * module in the import graph, so importing from here would have made a cycle.
+ *
+ * THE DIRECTION THAT REMOVES THE COPY WITHOUT MAKING A CYCLE IS DOWNWARD, AND
+ * IT IS THE ONE THE COMMENT ABOVE ALREADY ASKED FOR. src/fleet.ts imports NO
+ * local module at all, so it is the leaf; this module already imports
+ * `Fleet` from it. The chain is task -> fleet, and lock -> fleet, and nothing
+ * points back. The alternative, making lock and exclusion call into here, is
+ * the cycle task -> lock -> task and is what round 1 correctly refused.
+ *
+ * THE NAMES HERE ARE KEPT AS ALIASES rather than the 88 call sites in 31 files
+ * being rewritten. The names are the whole reason the rewrite would be
+ * expensive and none of the reason the duplication was a defect: what mattered
+ * was two bodies that could drift, and there is now one body.
+ */
+export type { PathEntryClass as EntryClass, RegularPathRead as RegularRead } from "./fleet.ts";
+export { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite };
+export type TaskShape = "ship" | "scout";
+export type TaskStatus = "open" | "closed";
+/**
+ * WHOSE AUTHORITY A PAYLOAD RUNS UNDER (M4-P8 step 2).
+ *
+ * `orchestrator` is the process that plans, reviews and merges, and is the
+ * only payload class the declared credential escape hatch was ever written
+ * for (SpawnOptions.allowPrCredentials, M2-P8 criterion 1: "for the
+ * orchestrator's own spawns, never for an implementer payload"). `project`
+ * is every payload that works inside a project clone.
+ *
+ * It is DECLARED, never derived. The kernel cannot infer it from a command,
+ * a role or a branch without holding a vocabulary for one of those, and a
+ * derived answer would be wrong in the one direction that matters.
+ */
+export type PayloadClass = "orchestrator" | "project";
+/**
+ * One granted allowlist extension, as it is recorded in meta.json.
+ *
+ * BUILT THROUGH THE ACCESSORS, NEVER BY READING `entry.name` DIRECTLY
+ * (CR-B-002, the half of it that is about the record). A bare-string entry
+ * has no `name` property, so `{name: entry.name, reason: entry.reason}`
+ * produced the literal record `{}`: an operator opening the task directory
+ * could see THAT a widening happened and not WHICH name was widened. The
+ * record is now built with `extensionName` / `extensionReason`
+ * (src/exec/env.ts), which read both forms.
+ *
+ * `reason` is OPTIONAL HERE AND REQUIRED ON THE AUDITED ROUTE, and the
+ * difference is the point rather than an inconsistency. This type describes
+ * what was actually recorded; the audited route refuses an entry with no
+ * usable reason before this record is built, so an entry reaching meta.json
+ * without one came through a seam that does not demand one. Recording the
+ * absence AS an absence (the key is simply not present in the JSON) is what
+ * keeps it distinguishable from a blank reason. Defaulting it to `""` would
+ * substitute a valid-looking value for a missing one, which is the same
+ * mechanism as CR-B-002 wearing a record's clothes.
+ */
+export interface CredentialExtensionRecord {
+    name: string;
+    reason?: string;
+}
+/**
+ * THE HANDOVER COMPARISON (M4-P8 criterion 6): what the kernel handed the
+ * adapter against what actually reached the child.
+ *
+ * TWO PROPERTIES, AND THE STATUS WORD NAMES WHICH OF THEM WERE CHECKED.
+ * That is finding CR-B-001 (clean-room-retro-B-criteria, HIGH) and it is
+ * worth stating as a mechanism rather than as one word: `status: "compared"`
+ * used to be written after comparing NAME SETS ONLY, while an operator reads
+ * "compared" as "the handover was verified". An adapter that keeps the name
+ * set byte-identical and merely restores `HOME` and `XDG_CONFIG_HOME` to
+ * their real paths defeats the whole M2R-004 defense, because that defense
+ * works by REDIRECTING those names rather than by dropping them, and the
+ * record then POSITIVELY ASSERTED a clean handover while the child read the
+ * real gh credential store. The general shape is a record whose status word
+ * is stronger than the check behind it.
+ *
+ * Both halves of the repair are here. The word is weakened so it can only
+ * say what was checked, and the check is strengthened so the pointer VALUES
+ * are compared too.
+ *
+ *   compared          names AND the five CREDENTIAL_STORE_REDIRECTIONS
+ *                     pointers were both in hand and both compared.
+ *   names-compared    the name sets were compared and NO pointer evidence
+ *                     was available. This is the value the old `compared`
+ *                     should have carried: it is a true statement about one
+ *                     property of two, and it never reads as a clean bill.
+ *   pointers-compared the pointers were observed in the child and compared,
+ *                     and the adapter reported no name set. Reachable with
+ *                     any adapter written before M4-P8, which reports
+ *                     nothing, running under the current turn-end hook.
+ *   unreported        neither property could be checked: no reported name
+ *                     set and no pointer evidence.
+ *   not-applicable    the spawn ran under the declared escape hatch, so the
+ *                     kernel handed over no environment at all and there is
+ *                     nothing a difference could be measured against.
+ *
+ * NO VALUE OF ANY VARIABLE IS RECORDED HERE, and the original design's
+ * reason for that is untouched and right: a value comparison that WROTE the
+ * values would put credential material into a record an operator reads.
+ * `changedRedirections` carries NAMES only. The five redirection targets are
+ * harness-owned paths inside the task directory and carry no credential
+ * material, but recording only the names that differ is strictly less and is
+ * enough to act on.
+ */
+export interface CredentialHandoverRecord {
+    status: "compared" | "names-compared" | "pointers-compared" | "unreported" | "not-applicable";
+    /** Names the adapter reported that the kernel did not hand over. */
+    added: string[];
+    /** Names the kernel handed over that the adapter did not report. */
+    removed: string[];
+    /**
+     * Credential-store pointers whose value where the payload ran is not the
+     * harness-owned path the kernel handed over. Names only, never values.
+     * Empty when the pointers were compared and agreed, and also empty when
+     * there was no pointer evidence, which is why `status` and not this array
+     * is what says whether the comparison happened.
+     */
+    changedRedirections: string[];
+    /**
+     * WHICH ARTIFACT THE POINTER EVIDENCE WAS READ FROM, absent when there was
+     * none. It is a statement about a FILE, not a provenance the kernel
+     * verified, and the value used to say otherwise.
+     *
+     *   turn-end-record  read from tasks/<id>/turn-end. The kernel generates the
+     *                    hook that normally writes it, and for an adapter that
+     *                    honours the contract those values come from inside the
+     *                    child environment. THE FILE IS ALSO ADAPTER-REACHABLE:
+     *                    the adapter is handed `hookPath` and the record sits
+     *                    beside it, so an adapter that skips the hook and writes
+     *                    the record itself produces a record the kernel cannot
+     *                    tell from the hook's.
+     *   adapter          read from the adapter's launch outcome. The adapter's
+     *                    word about its own behaviour, and always was.
+     *
+     * THE VALUE WAS `child` UNTIL THE DR-0047 SWEEP FIX ROUND (CR-F-CRED-001,
+     * MEDIUM). Measured: an adapter that reverted HOME and XDG_CONFIG_HOME for
+     * its payload and wrote the turn-end record itself produced
+     * `{"status":"compared","changedRedirections":[],"redirectionSource":"child"}`
+     * while the payload could reach a real gh credential store. The word `child`
+     * asserted an observation no child had made. Neither value is evidence that
+     * the adapter was honest, and the record now says only what it can support.
+     * This is CR-B-001's own mechanism, a record whose status word is stronger
+     * than the check behind it, recurring one level up inside the same record;
+     * see src/hooks.ts for why a nonce does not close it and a rename does.
+     */
+    redirectionSource?: "turn-end-record" | "adapter";
+}
+/**
+ * THE CREDENTIAL DECISION FOR ONE SPAWN (M4-P8 step 6), recorded in the
+ * file the kernel already owns rather than in a new one across a new seam.
+ *
+ * The hazard this phase names is "a credential reaches a project payload
+ * and no artifact says so". Every arm of the decision is therefore written
+ * down even when it is the boring one: the payload class, whether the
+ * scrub ran, every widening with the reason it was granted, the handover
+ * comparison, and the refusal if one fired after this record existed.
+ */
+export interface TaskCredentialRecord {
+    payloadClass: PayloadClass;
+    /**
+     * `scrubbed` when buildChildEnv constructed the environment, `inherited`
+     * when allowPrCredentials handed the parent's environment over unchanged.
+     *
+     * THIS FIELD RECORDS THE KERNEL'S DECISION AND ITS OWN CONSTRUCTION, NOT
+     * WHAT THE CHILD RECEIVED, and it is spelled out because it is the second
+     * member of CR-B-001's class found in this record (the derivation is in
+     * delivery/work-history/credential-route-fixes.md). "scrubbed" is a strong
+     * word: it says buildChildEnv ran, staged the five empty redirect targets
+     * and returned an environment, because a failure there is a rollback. It
+     * does NOT say the payload ran with that environment, because between this
+     * field being written and the payload starting there is an adapter. The
+     * field that speaks to what reached the child is `handover`, and it says
+     * which of its two properties it checked.
+     */
+    scrubMode: "scrubbed" | "inherited";
+    /** Every granted extension, in the order the caller declared them. */
+    extensions: CredentialExtensionRecord[];
+    /**
+     * ABSENT UNTIL THE LAUNCH HAS REPORTED, and the absence is a fact rather
+     * than an omission: this record is written BEFORE the payload starts,
+     * which is what makes a failure to write it safe to roll back, and at
+     * that moment no adapter has launched anything to compare. It is the same
+     * reason `ExecutorRecord` carries no resolved model.
+     */
+    handover?: CredentialHandoverRecord;
+    /**
+     * The refusal that fired AFTER this record was written, if one did.
+     *
+     * The step-5 refusal (the escape hatch asked for on a project payload) is
+     * deliberately absent from this field and cannot appear in it: that one
+     * refuses before the task directory exists, so there is no meta.json to
+     * record it in, and creating one would undo the property that a refused
+     * spawn creates nothing.
+     */
+    refusal?: string;
+}
+export declare const TASK_SHAPES: readonly TaskShape[];
+/**
+ * Task meta (the plan's field set, M1-P4 step 1).
+ *
+ * - id: the task id, a safe path segment (pool's TASK_ID_PATTERN).
+ * - project: absolute path of the project clone the worktree came from.
+ * - shape: ship or scout; it selects teardown's refusal rules.
+ * - branch: the TASK branch (task/<id>), the branch teardown judges for
+ *   landedness. Note the deliberate naming difference from the pool
+ *   record, whose "branch" is the project's default branch and whose
+ *   "branchName" is this one; meta records the branch the task works on.
+ * - worktree: absolute path of the task worktree.
+ * - baseSha: the fetched base SHA pool create emitted (EXT-F-03).
+ * - baseOffline: provenance, COPIED from the pool record's offline field
+ *   and never recomputed (PR-212). It is true only when the fetch failed
+ *   and --offline authorized falling back to the last fetched
+ *   remote-tracking SHA. A spawn that recomputed it from its own flags
+ *   would report a fetched base as offline whenever a contended fetch
+ *   succeeded on retry, which is exactly the provenance inversion V-2
+ *   produced in M1-P3.
+ * - status: open at spawn, closed by a successful teardown.
+ * - createdAt: ISO-8601 timestamp of the spawn.
+ * - credentials: the M4-P8 credential decision for this spawn. OPTIONAL in
+ *   the type, and the optionality is about READING rather than writing:
+ *   every spawn from M4-P8 on writes it, and `readTaskMeta` deliberately
+ *   does not require it, so a record written by an earlier kernel still
+ *   reads instead of becoming an unreadable task whose worktree nobody can
+ *   tear down. Consumers that need it check for it.
+ */
+export interface TaskMeta {
+    id: string;
+    project: string;
+    shape: TaskShape;
+    branch: string;
+    worktree: string;
+    baseSha: string;
+    baseOffline: boolean;
+    status: TaskStatus;
+    createdAt: string;
+    credentials?: TaskCredentialRecord;
+}
+export declare function taskDir(fleet: Fleet, taskId: string): string;
+export declare function metaPath(fleet: Fleet, taskId: string): string;
+export declare function briefPath(fleet: Fleet, taskId: string): string;
+export declare function turnEndPath(fleet: Fleet, taskId: string): string;
+export declare function executorRecordPath(fleet: Fleet, taskId: string): string;
+export declare function reportPath(fleet: Fleet, taskId: string): string;
+/** Serialize meta the way every kernel JSON state file is written. */
+export declare function renderTaskMeta(meta: TaskMeta): string;
+export declare function writeTaskMeta(fleet: Fleet, meta: TaskMeta): void;
+/**
+ * THE FOUR WAYS A TASK RECORD FAILS TO READ, KEPT APART (CR-F02, MEDIUM;
+ * T-036's mechanism).
+ *
+ * `absent` is a category that is empty BY OBSERVATION: the kernel looked and
+ * there is no record. Every other member is a category that is empty BY
+ * CONSTRUCTION: there IS something there and this read could not turn it into
+ * a record. Collapsing them makes "nothing here" and "something here I could
+ * not read" the same answer, and a task killed mid-write is the ordinary
+ * failure this repository keeps meeting, so the two are not the same answer at
+ * any caller that decides whether work is in flight.
+ */
+export type TaskMetaRead = 
+/** A record that read and passed the field check. */
+{
+    kind: "read";
+    meta: TaskMeta;
+}
+/** Nothing at this path. Empty by observation. */
+ | {
+    kind: "absent";
+}
+/** Present and not openable as a regular file, with the probe's reason. */
+ | {
+    kind: "unreadable";
+    reason: string;
+}
+/** Present, opened, and not JSON. The truncated-mid-write shape. */
+ | {
+    kind: "unparsable";
+    reason: string;
+}
+/** Present, parsed, and not a task record. Names the first bad field. */
+ | {
+    kind: "malformed";
+    reason: string;
+};
+/**
+ * THE ONE READ of a task record, and the one that says WHICH of the four
+ * outcomes happened.
+ *
+ * The type probe is INSIDE this function and not in front of one of its
+ * callers (CR-520, CR-521). There is exactly one implementation of "read a
+ * task record", every caller of it is protected, and adding a caller
+ * cannot reopen the hole: src/teardown.ts reaches this directly, without
+ * going through the liveness classifier, and a named pipe here used to
+ * hang it forever.
+ *
+ * WHY THIS IS A SEPARATE FUNCTION FROM `readTaskMeta` RATHER THAN ITS NEW
+ * SIGNATURE, declared rather than left to be inferred. Widening the return
+ * type of `readTaskMeta` is the shape this repair wants, and it is a
+ * compile-time break in four modules that this fix round's file list does not
+ * own (src/pool.ts, src/liveness.ts, src/teardown.ts, src/commands/next.ts).
+ * The distinction is therefore made AVAILABLE upstream of all of them here,
+ * `readTaskMeta` is documented as the deliberate NARROWING of it, and the
+ * sites that still collapse are named in the fix round's work history rather
+ * than quietly left.
+ */
+export declare function classifyTaskMeta(fleet: Fleet, taskId: string): TaskMetaRead;
+/**
+ * Read meta.json, or undefined when it is absent, is not a regular file,
+ * does not parse, or parses and is not a task record.
+ *
+ * THIS IS A DELIBERATE NARROWING OF `classifyTaskMeta` AND THE COLLAPSE IS THE
+ * WHOLE OF CR-F02. `undefined` answers "is there a readable record" and it
+ * cannot answer "is there a task here", because it is returned both when the
+ * kernel looked and found nothing and when it found something it could not
+ * read. A caller that reports an absence, skips an entry, or decides nothing
+ * is in flight must call `classifyTaskMeta` instead; a caller that REFUSES on
+ * every one of the four (teardown does) loses nothing by using this.
+ */
+export declare function readTaskMeta(fleet: Fleet, taskId: string): TaskMeta | undefined;
+/** Set meta.json status (teardown's last step; C-1's state authority). */
+export declare function setTaskStatus(fleet: Fleet, meta: TaskMeta, status: TaskStatus): void;
+export type GuardResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Holdership guard for the task-mutating commands (PR-203), shared by
+ * spawn and teardown so there is exactly one implementation of the rule.
+ * It lives here rather than in a guard module of its own because this
+ * phase's files-to-touch list has no shared-guard file and the rule is a
+ * precondition of every task mutation.
+ *
+ * The transport is M1-P3's, unchanged and not re-invented: lock acquire
+ * PRINTS the opaque holderId, the operator carries it, and here it
+ * arrives as the TIPHYS_HOLDER_ID environment variable. No second
+ * identity mechanism exists, and nothing about the holder is derived
+ * from the running program (plan constraint C-2): this reads the lease
+ * FILE and nothing else.
+ *
+ * With no lease file present the command proceeds (the plan's M1 test
+ * contexts). A lease that exists but is unreadable, expired, or held by
+ * a different holder refuses: fail closed, because every one of those
+ * states means this caller cannot prove it is the one orchestrator.
+ */
+export declare function checkHoldership(fleet: Fleet): GuardResult;
+/** True when the task directory already exists (spawn's rollback scope). */
+export declare function taskDirExists(fleet: Fleet, taskId: string): boolean;
+/**
+ * True when tasks/<id>/ already holds a previous incarnation of the task
+ * id, which spawn refuses (CR-301).
+ *
+ * The task directory is the DURABLE record: teardown removes the worktree
+ * and the pool record but deliberately leaves tasks/<id>/ behind, so the
+ * id is free from the pool's point of view and occupied from the task
+ * state's. Spawning into it would overwrite the closed task's records,
+ * hand the launch-failure rollback files it did not create, and leave the
+ * previous incarnation's turn-end file readable while the new
+ * incarnation's meta says open, which is a completion that did not happen
+ * sitting under the C-1 state authority.
+ *
+ * A path that exists but is not a directory counts as occupied too: it is
+ * not a state this kernel may write into, and refusing costs the operator
+ * one rename while guessing could cost the record.
+ */
+export declare function taskDirOccupied(fleet: Fleet, taskId: string): boolean;
+/**
+ * Collapse captured git or error output to ONE line (CR-303). Plan step 5 ends
+ * "every refusal is exit nonzero plus a single reason line", and git's
+ * own stderr is routinely five lines, so any interpolation of it must be
+ * flattened rather than trusted to be short. The M1-P6 harness reads
+ * these reason lines as evidence.
+ */
+export declare function singleLine(text: string): string;
+export type StepResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Run one step that may signal failure by THROWING, and fold a raised
+ * error into the same ok/reason shape every other step in spawn and
+ * teardown returns (F-1, F-2).
+ *
+ * This exists because the modules were written as a result type end to
+ * end while the Node fs calls underneath them are not: writeFileSync and
+ * mkdirSync raise. Every returned failure was handled correctly and every
+ * THROWN one walked straight past the handler, out of the command, and
+ * onto stderr as a stack trace, taking spawn's rollback and teardown's
+ * state update with it. Wrapping is therefore not defensive decoration
+ * for a state M1 never reaches: it is the difference between a rollback
+ * that runs and an orphaned worktree, and between a task marked closed
+ * and a meta.json that lies about a worktree that is already gone.
+ *
+ * It never swallows: the caller still gets a reason naming the step, and
+ * still decides whether to roll back, report a partial failure, or refuse.
+ */
+export declare function runStep<T>(what: string, step: () => T): StepResult<T>;
+/**
+ * runStep's shape for a step that returns a PROMISE (M4-P2 step 2).
+ *
+ * This is a PROMOTION, not a new function. It lived module-private in
+ * src/watcher.ts, where its own comment said "src/task.ts covers the sync
+ * one"; spawn's launch call site needs the same shape now that
+ * `ExecutorAdapter.launch` returns a promise, and T-005's one-mechanism
+ * rule makes copying it a third time the wrong answer. The promotion was
+ * measured before it was made: the two functions were run side by side over
+ * six `what`/thrown-error pairs covering an ordinary Error, an Error with an
+ * empty message, a thrown string, a thrown object with a custom toString, an
+ * Error subclass and a multi-line pair, and their reason strings were
+ * compared as buffers. All six were byte-identical, so no watcher message
+ * changes on any of those six. The capture is in the M4-P2 work history
+ * under `delivery/work-history/m4-p2.md`.
+ *
+ * WHY A SEPARATE FUNCTION RATHER THAN WIDENING runStep. `runStep` returns
+ * `{ok: true, value}` the instant its callback returns, and a callback that
+ * returns a promise returns one IMMEDIATELY. So `runStep` over an async
+ * step is not merely imprecise: its `ok: true` is a claim that the step
+ * SUCCEEDED when nothing has run yet, and a later rejection escapes the
+ * result type entirely as an unhandled rejection. That is the exact defect
+ * this phase's criterion 4 witness reddens against.
+ *
+ * It never swallows, on the same terms as the sync one: the caller gets a
+ * reason naming the step and still decides what to do about it.
+ */
+export declare function runStepAsync<T>(what: string, step: () => Promise<T>): Promise<StepResult<T>>;