@relayflows/surface 2.0.30 → 2.0.31

package/dist/completion.d.ts

@@ -7,4 +7,19 @@ export type RunCompletionReason = (typeof RUN_COMPLETION_REASONS)[number];
 /** Authored verdicts include handoff and declination without widening kernel facts. */
 export declare const FLOW_COMPLETION_REASONS: readonly ["success", "step_failed", "canceled", "budget_exceeded", "needs_human", "declined"];
 export type FlowCompletionReason = (typeof FLOW_COMPLETION_REASONS)[number];
+/**
+ * The bound on the optional `done()` detail, in Unicode code points of the
+ * FINAL normalized string — truncation suffix included.
+ *
+ * Stated in code points rather than `String.length` on purpose: `.length`
+ * counts UTF-16 code units, so an emoji-heavy detail measured that way is
+ * half the length a reader would call it. The number is the same order the
+ * kernel uses for a gate's free-text detail
+ * (`kernel/relayflowd/src/engine/remote.rs`), but it is not the same bound:
+ * that one takes 2,000 characters and then appends its suffix.
+ *
+ * The runtime enforces this; it is exported so an author can measure a detail
+ * before passing one.
+ */
+export declare const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;
 //# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,wJAUrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,oEAKzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,+FAI1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,wJAUrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,oEAKzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,+FAI1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,OAAO,CAAC"}

package/dist/completion.js

@@ -23,4 +23,19 @@ export const FLOW_COMPLETION_REASONS = [
     'needs_human',
     'declined',
 ];
+/**
+ * The bound on the optional `done()` detail, in Unicode code points of the
+ * FINAL normalized string — truncation suffix included.
+ *
+ * Stated in code points rather than `String.length` on purpose: `.length`
+ * counts UTF-16 code units, so an emoji-heavy detail measured that way is
+ * half the length a reader would call it. The number is the same order the
+ * kernel uses for a gate's free-text detail
+ * (`kernel/relayflowd/src/engine/remote.rs`), but it is not the same bound:
+ * that one takes 2,000 characters and then appends its suffix.
+ *
+ * The runtime enforces this; it is exported so an author can measure a detail
+ * before passing one.
+ */
+export const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;
 //# sourceMappingURL=completion.js.map

package/dist/completion.js.map

@@ -1 +1 @@
-{"version":3,"file":"completion.js","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,qBAAqB;IACrB,mBAAmB;IACnB,eAAe;IACf,SAAS;IACT,SAAS;IACT,cAAc;IACd,iBAAiB;IACjB,UAAU;CACF,CAAC;AAIX,sEAAsE;AACtE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,aAAa;IACb,UAAU;IACV,iBAAiB;CACT,CAAC;AAIX,uFAAuF;AACvF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,GAAG,sBAAsB;IACzB,aAAa;IACb,UAAU;CACF,CAAC"}
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,qBAAqB;IACrB,mBAAmB;IACnB,eAAe;IACf,SAAS;IACT,SAAS;IACT,cAAc;IACd,iBAAiB;IACjB,UAAU;CACF,CAAC;AAIX,sEAAsE;AACtE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS;IACT,aAAa;IACb,UAAU;IACV,iBAAiB;CACT,CAAC;AAIX,uFAAuF;AACvF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,GAAG,sBAAsB;IACzB,aAAa;IACb,UAAU;CACF,CAAC;AAIX;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,IAAI,CAAC"}

package/dist/context.d.ts

@@ -29,7 +29,19 @@ export interface AgentOptions {
     permissions?: PermissionsSpec;
     cli?: string;
     model?: string;
-    /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+    /**
+     * Directory this agent's CLI is spawned in, relative to the run root — the
+     * flow-runner's working directory, and where the CLI runs when this is
+     * absent. One flow can therefore drive agents in sibling checkouts. The
+     * path must be relative and free of `.`, `..` and empty components, and
+     * must name an existing directory inside the run root at dispatch;
+     * anything else refuses the step instead of running it somewhere else.
+     * An absolute path is accepted when it names a directory inside the run
+     * root — it lowers to the same relative declaration — and refused when it
+     * escapes. `artifacts` are reported relative to this directory. It is a
+     * declaration of where to start, not a sandbox. Not supported with
+     * `transport: 'relay'`. See docs/SURFACE.md.
+     */
     cwd?: string;
     /**
      * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as a
@@ -38,12 +50,55 @@ export interface AgentOptions {
      */
     transport?: 'direct' | 'relay';
 }
+/**
+ * What `f.run` resolves to under `onNonZero: 'record'`.
+ *
+ * Every field is read back from the step's journaled output envelope, never
+ * re-measured: `ok` is the recorded exit code, not a second execution. This is
+ * the point of the policy — `<command> || true` discards the code, so the
+ * branch below it can only ever be taken on faith.
+ */
+export interface RunResult {
+    /** Exactly `exitCode === 0`. */
+    ok: boolean;
+    /** The exit code the kernel journaled for this command. */
+    exitCode: number;
+    /**
+     * `stdout` then `stderr`, joined by a newline when both are nonempty — the
+     * string to hand an agent asked to repair what the command reported. It is a
+     * diagnostic convenience, not a reconstruction of the real interleaving: the
+     * two streams were captured separately and their true ordering is not
+     * journaled. Read `stdout` when you need to parse the command's own output.
+     */
+    output: string;
+    /** stdout tail — the same string the default `f.run` resolves to. */
+    stdout: string;
+    /** stderr tail, where a failing check usually explains itself. */
+    stderr: string;
+}
+export interface RunOptions {
+    /** Command lease: milliseconds or a duration such as "5m"; default 30s, maximum 15m. */
+    timeout?: string | number;
+    /**
+     * What a nonzero exit means. `'fail'` (the default) throws, ending the flow
+     * at this line. `'record'` journals the exit code and output and resolves to
+     * a `RunResult`, so the body can hand a red check's own output to whatever is
+     * built to repair it. A timeout, a signal, or a step that never ran still
+     * throws under either policy: those produced no verdict to record.
+     */
+    onNonZero?: 'fail' | 'record';
+}
 export interface LlmOptions {
     /** JSON Schema checked before the result is accepted by the journal. */
     output: Record<string, unknown>;
     cli?: string;
     model?: string;
 }
+/** The optional second argument to {@link Ctx.done}. */
+export interface DoneOptions {
+    /** Why the flow reached this verdict; redacted, bounded, and journaled. */
+    detail?: string;
+}
 /**
  * The context a journal-backed runtime injects into a flow body.
  *
@@ -56,10 +111,24 @@ export interface Ctx extends Helpers {
         readonly cloud?: CloudCapabilities;
     };
     readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;
-    /** Command lease: milliseconds or a duration such as "5m"; default 30s, maximum 15m. */
-    run(command: string, options?: {
-        timeout?: string | number;
+    /**
+     * Run a command. Resolves to its stdout tail, and a nonzero exit ends the
+     * flow — unless `onNonZero: 'record'` is declared, which resolves to a
+     * `RunResult` carrying the journaled exit code instead.
+     *
+     * The literal overloads come first so the default stays the common case: an
+     * omitted or `'fail'` policy keeps the `Step<string>` every existing body is
+     * written against, and only the literal `'record'` widens the result. The
+     * third is for a policy held in a variable, where neither literal applies and
+     * the author has to narrow the union themselves.
+     */
+    run(command: string, options?: RunOptions & {
+        onNonZero?: 'fail';
     }): Step<string>;
+    run(command: string, options: RunOptions & {
+        onNonZero: 'record';
+    }): Step<RunResult>;
+    run(command: string, options: RunOptions): Step<string | RunResult>;
     llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
     /** JSON Schema validates the value at runtime; narrow unknown in author code. */
     llm(prompt: string, options: LlmOptions): Step<unknown>;
@@ -81,7 +150,21 @@ export interface Ctx extends Helpers {
      * no-op that returns true. A name must appear in the flow header's `hooks`.
      */
     hook(name: string, input: unknown): Step<boolean>;
-    done(reason: FlowCompletionReason): void;
+    /**
+     * End the flow with an authored verdict, and optionally say why.
+     *
+     * `options.detail` is free prose the flow already knows — "review found 1
+     * P2: `review.clean` was not created" — and it is what a reader gets instead
+     * of a generic sentence. It is journaled with the verdict, so it survives
+     * into the run report and `flows status`; the runtime redacts it and bounds
+     * it to `COMPLETION_DETAIL_MAX_CODE_POINTS` code points, truncating
+     * with a visible marker rather than refusing an over-long one.
+     *
+     * Whitespace-only is the same as saying nothing: it normalizes to absence,
+     * and the verdict reports exactly as the one-argument call does. A `detail`
+     * that is present and not a string is refused.
+     */
+    done(reason: FlowCompletionReason, options?: DoneOptions): void;
     cloud: CloudHelper;
     memory: MemoryHelper;
 }

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { EnrollmentReceipt, Heartbeat, JournalStep, RunJournal, ScheduleState, WorkerSummary, CloudHelper, CloudCapabilities, CloudBabysitterTurnCapability, CloudBabysitterTurnDelivery, CloudBabysitterTurnReceipt, } from "./cloud.js";
-export type { AgentOptions, AgentResult, PermissionsSpec, LlmOptions, Ctx } from "./context.js";
-export { COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, type CompletionReason, type RunCompletionReason, type FlowCompletionReason, } from "./completion.js";
+export type { AgentOptions, AgentResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
+export { COMPLETION_DETAIL_MAX_CODE_POINTS, COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, type CompletionReason, type RunCompletionReason, type FlowCompletionReason, } from "./completion.js";
 export type { Step, NamedGate, ReferencesInputNamedGate, SubprocessNamedGate, WordCountBoundsNamedGate, RegexMatchNamedGate, } from "./step.js";
 export { flow, type FlowHandle, type TriggeredFlowHandle, type FlowHeader, } from "./flow.js";
 export { flowRunWritebackIdempotency, type SlackHelper, type SlackReceipt, type SlackBlock, type SlackAttachment, type SlackPostMessage, type SlackPostOptions, } from "./slack.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,IAAI,EACJ,SAAS,EACT,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAC1F,KAAK,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,GACrF,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACpI,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,IAAI,EACJ,SAAS,EACT,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,EAC1F,KAAK,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,GACrF,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, } from "./completion.js";
+export { COMPLETION_DETAIL_MAX_CODE_POINTS, COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, } from "./completion.js";
 export { flow, } from "./flow.js";
 export { flowRunWritebackIdempotency, } from "./slack.js";
 export { webhook } from "./triggers.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAIxB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,IAAI,GAIL,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,GAO5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAwF,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,GAE3F,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAIxB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,IAAI,GAIL,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,2BAA2B,GAO5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAwF,MAAM,eAAe,CAAC;AAC9H,OAAO,EACL,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,SAAS,GAE3F,MAAM,eAAe,CAAC;AACvB,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/surface",
-  "version": "2.0.30",
+  "version": "2.0.31",
   "description": "TypeScript authoring surface for Relayflows.",
   "type": "module",
   "main": "./dist/index.js",

package/src/completion.ts

@@ -31,3 +31,19 @@ export const FLOW_COMPLETION_REASONS = [
 ] as const;
 
 export type FlowCompletionReason = (typeof FLOW_COMPLETION_REASONS)[number];
+
+/**
+ * The bound on the optional `done()` detail, in Unicode code points of the
+ * FINAL normalized string — truncation suffix included.
+ *
+ * Stated in code points rather than `String.length` on purpose: `.length`
+ * counts UTF-16 code units, so an emoji-heavy detail measured that way is
+ * half the length a reader would call it. The number is the same order the
+ * kernel uses for a gate's free-text detail
+ * (`kernel/relayflowd/src/engine/remote.rs`), but it is not the same bound:
+ * that one takes 2,000 characters and then appends its suffix.
+ *
+ * The runtime enforces this; it is exported so an author can measure a detail
+ * before passing one.
+ */
+export const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;

package/src/context.ts

@@ -32,7 +32,19 @@ export interface AgentOptions {
   permissions?: PermissionsSpec;
   cli?: string;
   model?: string;
-  /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+  /**
+   * Directory this agent's CLI is spawned in, relative to the run root — the
+   * flow-runner's working directory, and where the CLI runs when this is
+   * absent. One flow can therefore drive agents in sibling checkouts. The
+   * path must be relative and free of `.`, `..` and empty components, and
+   * must name an existing directory inside the run root at dispatch;
+   * anything else refuses the step instead of running it somewhere else.
+   * An absolute path is accepted when it names a directory inside the run
+   * root — it lowers to the same relative declaration — and refused when it
+   * escapes. `artifacts` are reported relative to this directory. It is a
+   * declaration of where to start, not a sandbox. Not supported with
+   * `transport: 'relay'`. See docs/SURFACE.md.
+   */
   cwd?: string;
   /**
    * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as a
@@ -42,6 +54,46 @@ export interface AgentOptions {
   transport?: 'direct' | 'relay';
 }
 
+/**
+ * What `f.run` resolves to under `onNonZero: 'record'`.
+ *
+ * Every field is read back from the step's journaled output envelope, never
+ * re-measured: `ok` is the recorded exit code, not a second execution. This is
+ * the point of the policy — `<command> || true` discards the code, so the
+ * branch below it can only ever be taken on faith.
+ */
+export interface RunResult {
+  /** Exactly `exitCode === 0`. */
+  ok: boolean;
+  /** The exit code the kernel journaled for this command. */
+  exitCode: number;
+  /**
+   * `stdout` then `stderr`, joined by a newline when both are nonempty — the
+   * string to hand an agent asked to repair what the command reported. It is a
+   * diagnostic convenience, not a reconstruction of the real interleaving: the
+   * two streams were captured separately and their true ordering is not
+   * journaled. Read `stdout` when you need to parse the command's own output.
+   */
+  output: string;
+  /** stdout tail — the same string the default `f.run` resolves to. */
+  stdout: string;
+  /** stderr tail, where a failing check usually explains itself. */
+  stderr: string;
+}
+
+export interface RunOptions {
+  /** Command lease: milliseconds or a duration such as "5m"; default 30s, maximum 15m. */
+  timeout?: string | number;
+  /**
+   * What a nonzero exit means. `'fail'` (the default) throws, ending the flow
+   * at this line. `'record'` journals the exit code and output and resolves to
+   * a `RunResult`, so the body can hand a red check's own output to whatever is
+   * built to repair it. A timeout, a signal, or a step that never ran still
+   * throws under either policy: those produced no verdict to record.
+   */
+  onNonZero?: 'fail' | 'record';
+}
+
 export interface LlmOptions {
   /** JSON Schema checked before the result is accepted by the journal. */
   output: Record<string, unknown>;
@@ -49,6 +101,12 @@ export interface LlmOptions {
   model?: string;
 }
 
+/** The optional second argument to {@link Ctx.done}. */
+export interface DoneOptions {
+  /** Why the flow reached this verdict; redacted, bounded, and journaled. */
+  detail?: string;
+}
+
 /**
  * The context a journal-backed runtime injects into a flow body.
  *
@@ -59,8 +117,20 @@ export interface Ctx extends Helpers {
   /** Host-verified ports. Absent from direct/local runs and ordinary authored execution. */
   readonly capabilities?: { readonly cloud?: CloudCapabilities };
   readonly mcp: Readonly<Record<string, Readonly<Record<string, (args: unknown) => Step<unknown>>>>>;
-  /** Command lease: milliseconds or a duration such as "5m"; default 30s, maximum 15m. */
-  run(command: string, options?: { timeout?: string | number }): Step<string>;
+  /**
+   * Run a command. Resolves to its stdout tail, and a nonzero exit ends the
+   * flow — unless `onNonZero: 'record'` is declared, which resolves to a
+   * `RunResult` carrying the journaled exit code instead.
+   *
+   * The literal overloads come first so the default stays the common case: an
+   * omitted or `'fail'` policy keeps the `Step<string>` every existing body is
+   * written against, and only the literal `'record'` widens the result. The
+   * third is for a policy held in a variable, where neither literal applies and
+   * the author has to narrow the union themselves.
+   */
+  run(command: string, options?: RunOptions & { onNonZero?: 'fail' }): Step<string>;
+  run(command: string, options: RunOptions & { onNonZero: 'record' }): Step<RunResult>;
+  run(command: string, options: RunOptions): Step<string | RunResult>;
   llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
   /** JSON Schema validates the value at runtime; narrow unknown in author code. */
   llm(prompt: string, options: LlmOptions): Step<unknown>;
@@ -80,7 +150,21 @@ export interface Ctx extends Helpers {
    * no-op that returns true. A name must appear in the flow header's `hooks`.
    */
   hook(name: string, input: unknown): Step<boolean>;
-  done(reason: FlowCompletionReason): void;
+  /**
+   * End the flow with an authored verdict, and optionally say why.
+   *
+   * `options.detail` is free prose the flow already knows — "review found 1
+   * P2: `review.clean` was not created" — and it is what a reader gets instead
+   * of a generic sentence. It is journaled with the verdict, so it survives
+   * into the run report and `flows status`; the runtime redacts it and bounds
+   * it to `COMPLETION_DETAIL_MAX_CODE_POINTS` code points, truncating
+   * with a visible marker rather than refusing an over-long one.
+   *
+   * Whitespace-only is the same as saying nothing: it normalizes to absence,
+   * and the verdict reports exactly as the one-argument call does. A `detail`
+   * that is present and not a string is refused.
+   */
+  done(reason: FlowCompletionReason, options?: DoneOptions): void;
   cloud: CloudHelper;
   memory: MemoryHelper;
 }

package/src/index.ts

@@ -11,8 +11,9 @@ export type {
   CloudBabysitterTurnDelivery,
   CloudBabysitterTurnReceipt,
 } from "./cloud.js";
-export type { AgentOptions, AgentResult, PermissionsSpec, LlmOptions, Ctx } from "./context.js";
+export type { AgentOptions, AgentResult, DoneOptions, PermissionsSpec, LlmOptions, RunOptions, RunResult, Ctx } from "./context.js";
 export {
+  COMPLETION_DETAIL_MAX_CODE_POINTS,
   COMPLETION_REASONS,
   RUN_COMPLETION_REASONS,
   FLOW_COMPLETION_REASONS,