@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/status.d.ts

@@ -11,18 +11,43 @@
  * CONSTRAINT C-1, NAMED BECAUSE IT DECIDES THE SHAPE OF THIS MODULE.
  * "Never read current state from the tail of an append-only log." The stream
  * at `state/status/stream.jsonl` is the HISTORY and is append-only. The
- * current state is `state/status/current.json`, a whole document rewritten
+ * current state is `status/current.json`, a whole document rewritten
  * atomically on every emit. `readCurrent` opens `current.json` and nothing
  * else; it does not know the stream's path. A truncated, corrupted or
  * half-written stream therefore cannot change what `tiphys status show`
  * reports, and that is the property criterion 7 witnesses in both directions.
  *
+ * THE SPLIT (M4-D-13, decided in the M4-P18 plan section). The two documents
+ * used to sit side by side under the gitignored `state/` prefix, so the one
+ * sentence that says where the pipeline stands did not survive a fleet being
+ * reclaimed: AGENTS.md's `fleet-state-commit-discipline` clause names "the
+ * state file that says where the pipeline stands" as DURABLE, and an ignored
+ * path can be neither committed nor pushed. So the pointer moved OUT of
+ * `state/` to a tracked path and the stream stayed, because the stream is
+ * history that a restart rebuilds.
+ *
+ * C-1 IS THE REASON FOR THE SPLIT AND NOT A CONSTRAINT IT HAS TO DODGE.
+ * `readCurrent` opens the whole document and has no code path that reaches
+ * the stream, so moving the document changes WHERE it lives and changes
+ * NOTHING about how current state is read. The pair of witnesses in
+ * test/status.test.ts is re-pointed at the new layout and still reddens
+ * under the same mutation: `readCurrent` aimed at STREAM_FILE.
+ *
  * ATOMIC REWRITE means write a temp file beside the target and rename. A
  * rename within one directory is atomic on POSIX, so a reader either sees the
  * whole previous document or the whole new one and never a partial write.
+ * The temp file is created beside the DURABLE document, so the two paths in
+ * the rename stay inside one directory after the split.
+ */
+/**
+ * Where the status files live inside a fleet home, and the two directories
+ * are on OPPOSITE sides of the fleet `.gitignore` by design (M4-D-13).
+ * `STATUS_DIR` is under the ignored `state/` prefix and holds the rebuilt
+ * history; `DURABLE_STATUS_DIR` is tracked and holds the one document a
+ * restart must not lose.
  */
-/** Where the status files live inside a fleet home. */
 export declare const STATUS_DIR: string;
+export declare const DURABLE_STATUS_DIR = "status";
 export declare const STREAM_FILE: string;
 export declare const CURRENT_FILE: string;
 /**

package/dist/src/status.js

@@ -11,23 +11,48 @@
  * CONSTRAINT C-1, NAMED BECAUSE IT DECIDES THE SHAPE OF THIS MODULE.
  * "Never read current state from the tail of an append-only log." The stream
  * at `state/status/stream.jsonl` is the HISTORY and is append-only. The
- * current state is `state/status/current.json`, a whole document rewritten
+ * current state is `status/current.json`, a whole document rewritten
  * atomically on every emit. `readCurrent` opens `current.json` and nothing
  * else; it does not know the stream's path. A truncated, corrupted or
  * half-written stream therefore cannot change what `tiphys status show`
  * reports, and that is the property criterion 7 witnesses in both directions.
  *
+ * THE SPLIT (M4-D-13, decided in the M4-P18 plan section). The two documents
+ * used to sit side by side under the gitignored `state/` prefix, so the one
+ * sentence that says where the pipeline stands did not survive a fleet being
+ * reclaimed: AGENTS.md's `fleet-state-commit-discipline` clause names "the
+ * state file that says where the pipeline stands" as DURABLE, and an ignored
+ * path can be neither committed nor pushed. So the pointer moved OUT of
+ * `state/` to a tracked path and the stream stayed, because the stream is
+ * history that a restart rebuilds.
+ *
+ * C-1 IS THE REASON FOR THE SPLIT AND NOT A CONSTRAINT IT HAS TO DODGE.
+ * `readCurrent` opens the whole document and has no code path that reaches
+ * the stream, so moving the document changes WHERE it lives and changes
+ * NOTHING about how current state is read. The pair of witnesses in
+ * test/status.test.ts is re-pointed at the new layout and still reddens
+ * under the same mutation: `readCurrent` aimed at STREAM_FILE.
+ *
  * ATOMIC REWRITE means write a temp file beside the target and rename. A
  * rename within one directory is atomic on POSIX, so a reader either sees the
  * whole previous document or the whole new one and never a partial write.
+ * The temp file is created beside the DURABLE document, so the two paths in
+ * the rename stay inside one directory after the split.
  */
 import { mkdirSync, renameSync, writeFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { refuseOpenForWrite, readRegularFileIfPresent } from "./task.js";
-/** Where the status files live inside a fleet home. */
+/**
+ * Where the status files live inside a fleet home, and the two directories
+ * are on OPPOSITE sides of the fleet `.gitignore` by design (M4-D-13).
+ * `STATUS_DIR` is under the ignored `state/` prefix and holds the rebuilt
+ * history; `DURABLE_STATUS_DIR` is tracked and holds the one document a
+ * restart must not lose.
+ */
 export const STATUS_DIR = join("state", "status");
+export const DURABLE_STATUS_DIR = "status";
 export const STREAM_FILE = join(STATUS_DIR, "stream.jsonl");
-export const CURRENT_FILE = join(STATUS_DIR, "current.json");
+export const CURRENT_FILE = join(DURABLE_STATUS_DIR, "current.json");
 /**
  * The five supervisor-actionable states, blueprint section 5. Duplicated
  * from `schemas/status-line.schema.json` so the CLI can reject a bad state
@@ -66,8 +91,12 @@ export function makeStatusRecord(input) {
  * names an event no record supports.
  */
 export function emitStatus(fleetRoot, record) {
-    const directory = join(fleetRoot, STATUS_DIR);
-    mkdirSync(directory, { recursive: true });
+    /* TWO DIRECTORIES SINCE THE SPLIT, and both are created before either is
+       written: the ephemeral one is rebuilt by `tiphys resume` after a reclaim
+       and the durable one comes across in a clone, so on any given fleet home
+       either can be the one that is absent. */
+    mkdirSync(join(fleetRoot, STATUS_DIR), { recursive: true });
+    mkdirSync(join(fleetRoot, DURABLE_STATUS_DIR), { recursive: true });
     const streamPath = join(fleetRoot, STREAM_FILE);
     const currentPath = join(fleetRoot, CURRENT_FILE);
     const temporaryPath = `${currentPath}.tmp`;

package/dist/src/task.d.ts

@@ -1,4 +1,5 @@
 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:
@@ -65,65 +66,210 @@ import type { Fleet } from "./fleet.ts";
  * the window is now the only way to reach the block rather than the
  * default path to it.
  */
-export type EntryClass = 
-/** Nothing at the path. */
-{
-    kind: "absent";
-}
-/** A link is there and resolves to nothing: it exists, and it is empty of evidence. */
- | {
-    kind: "dangling";
-}
-/** Safe to open. */
- | {
-    kind: "regular";
-}
-/** Present, and opening it is not safe: never opened, always named. */
- | {
-    kind: "irregular";
-    reason: string;
-}
-/** Neither lstat nor stat could answer the question. */
- | {
-    kind: "unexaminable";
-    reason: string;
-};
 /**
- * THE ONE ANSWER TO "may this path be opened". Every reader and every
- * writer of a path this kernel does not itself guarantee to be a regular
- * file goes through this, so there is one implementation of the question
- * and not one per call site.
+ * 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 declare function classifyEntry(path: string): EntryClass;
+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";
 /**
- * Refuse an open-for-WRITE of a path that is not a regular file. The
- * hazard is symmetric: open(2) for writing on a FIFO with no reader blocks
- * exactly as reading one with no writer does, so a staged write and an
- * append are as dangerous as a read. Returns the reason, or undefined when
- * the path may be opened (absent included: creating it is the point).
+ * 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 declare function refuseOpenForWrite(path: string): string | undefined;
-/** What a guarded read of a possibly-absent path produced. */
-export type RegularRead = {
-    kind: "read";
-    body: string;
-} | {
-    kind: "absent";
+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;
 }
-/** Present and not readable, with a reason naming the path. */
- | {
-    kind: "refused";
-    reason: string;
-};
 /**
- * THE ONE READ of a file that might not be there and might not be a file.
- * src/task.ts, src/liveness.ts, src/watcher.ts and src/commands/doctor.ts
- * all read fleet state through this, so "probe before open" is a property
- * of the read and cannot be forgotten by a new caller.
+ * 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 declare function readRegularFileIfPresent(path: string): RegularRead;
-export type TaskShape = "ship" | "scout";
-export type TaskStatus = "open" | "closed";
+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).
@@ -146,6 +292,12 @@ export declare const TASK_SHAPES: readonly TaskShape[];
  *   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;
@@ -157,6 +309,7 @@ export interface TaskMeta {
     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;
@@ -168,9 +321,45 @@ export declare function reportPath(fleet: Fleet, taskId: string): string;
 export declare function renderTaskMeta(meta: TaskMeta): string;
 export declare function writeTaskMeta(fleet: Fleet, meta: TaskMeta): void;
 /**
- * Read meta.json, or undefined when it is absent, is not a regular file,
- * or does not parse. All three mean the same thing to every caller: this
- * is not a readable record, and it is not evidence that the task finished.
+ * 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
@@ -178,6 +367,29 @@ export declare function writeTaskMeta(fleet: Fleet, meta: TaskMeta): void;
  * 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). */
@@ -262,3 +474,31 @@ export type StepResult<T> = {
  * 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>>;