@miadi/connector 0.1.8 → 0.1.10

package/dist/mission-status.js

@@ -0,0 +1,144 @@
+import { steerAttempts, steeringGrantOf, checkGrant } from "./steer.js";
+const ISSUE_REF = /^([\w.-]+)\/([\w.-]+)#(\d+)$/;
+const SESSION_REF = /^session:([0-9a-f-]{36})$/;
+/** The record a mission reference resolves to, and how it was found. */
+export function resolveMissionSubject(ref, records) {
+    const exact = records.find((r) => r.id === ref);
+    if (exact)
+        return { record: exact, via: "record_id" };
+    const session = SESSION_REF.exec(ref);
+    if (session) {
+        const citing = records
+            .filter((r) => (r.kind === "run_request" || r.kind === "work_proposal") && r.refs.includes(ref))
+            .sort((a, b) => b.created_at.localeCompare(a.created_at));
+        if (citing.length)
+            return { record: citing[0], via: "session_ref" };
+        return null;
+    }
+    if (ISSUE_REF.test(ref)) {
+        const citing = records
+            .filter((r) => (r.kind === "run_request" || r.kind === "work_proposal") && (r.refs.includes(ref) || r.evidence_refs.includes(ref)))
+            .sort((a, b) => b.created_at.localeCompare(a.created_at));
+        if (citing.length)
+            return { record: citing[0], via: "issue_ref" };
+        return null;
+    }
+    return null;
+}
+function nextAction(record, standing, queue) {
+    if (!standing)
+        return "Read the record itself; it is not an approvable request.";
+    switch (standing.stage) {
+        case "awaiting_decision":
+            return "A person with Miadi's write tier decides on its approval page or a decisions card.";
+        case "recording":
+            return "A decision is being recorded; read it again shortly.";
+        case "declined":
+        case "sent_back":
+            return standing.stage === "declined" ? "Nothing runs; a new request is needed." : "Submit a revised request citing the old id.";
+        case "dispatching":
+            return queue?.state === "delivered"
+                ? "The brief is with its session. Follow it, or steer it with request_session_steer inside the approved grant."
+                : "Wait for the factory intake to deliver the brief.";
+        case "failed":
+            return standing.rerun.available ? "A write-tier person may run it again with the same approval." : "Read the failure and decide.";
+        case "completed":
+            return standing.outstanding.length
+                ? "The approved changes are still outstanding; they need their own authorized step."
+                : "The request is done. A mission closes when its session's ending is decided, not when this request completes.";
+    }
+}
+export async function missionStatus(ref, records, deps) {
+    const notes = [];
+    const found = resolveMissionSubject(ref, records);
+    if (!found)
+        return { ref, found: false, notes: ["No mission record resolves from this reference."] };
+    const { record, via } = found;
+    const standing = deps.projectOf(record) ?? undefined;
+    const queue = deps.queueOf?.(record);
+    const now = deps.now?.() ?? new Date();
+    // The sessions this mission names, each with how it is bound.
+    const sessions = [];
+    const live = deps.tmuxSessions ? new Set(deps.tmuxSessions()) : undefined;
+    const briefTo = (record.completion_receipt ?? {}).to;
+    const named = String(record.body.session ?? "") || undefined;
+    const seen = new Set();
+    const addSession = (session, association) => {
+        const key = `${association}:${session}`;
+        if (seen.has(session))
+            return;
+        seen.add(session);
+        sessions.push({
+            association,
+            session,
+            live: live ? (live.has(session) ? "running" : "absent") : "unknown",
+            ...(deps.paneBusy && live?.has(session) ? { activity: deps.paneBusy(session) } : {}),
+        });
+        void key;
+    };
+    if (typeof briefTo === "string" && briefTo)
+        addSession(briefTo.replace(/^new:/, ""), "brief_target");
+    if (named)
+        addSession(named, "named");
+    for (const r of record.refs) {
+        const m = SESSION_REF.exec(r);
+        if (m) {
+            const miadi = deps.sessionOf ? await deps.sessionOf(m[1]).catch(() => ({ state: "unavailable" })) : undefined;
+            sessions.push({ association: "signed_ref", session: r, live: "unknown", ...(miadi ? { miadi } : {}) });
+        }
+    }
+    if (!live)
+        notes.push("Live session state was not joined (the viewer's tier or the host does not allow it).");
+    const issues = [];
+    if (deps.issueOf) {
+        for (const r of [...record.refs, ...record.evidence_refs]) {
+            const m = ISSUE_REF.exec(r);
+            if (!m)
+                continue;
+            const issue = await deps
+                .issueOf(m[1], m[2], m[3])
+                .catch(() => ({ state: "unavailable" }));
+            issues.push({ ref: r, state: issue.state, ...(issue.title ? { title: issue.title } : {}), ...(issue.merged !== undefined ? { merged: issue.merged } : {}) });
+        }
+    }
+    const grant = steeringGrantOf(record);
+    const attempts = steerAttempts(records, record.id);
+    const grantCheck = grant ? checkGrant(grant, attempts, now) : null;
+    const grantState = grantCheck === null ? "none" : grantCheck === "ok" ? "active" : grantCheck === "expired_grant" ? "expired_grant" : "exhausted";
+    const receipt = (record.completion_receipt ?? {});
+    const anyLive = sessions.some((s) => s.live === "running");
+    const prs = issues.filter((i) => i.merged !== undefined);
+    const stageTruth = {
+        approved: record.approval_state === "approved",
+        queued: queue?.state === "queued" || queue?.state === "delivered",
+        delivered: queue?.state === "delivered",
+        running: anyLive ? "evidence" : "no_evidence",
+        pr_merged: prs.length ? (prs.every((p) => p.merged) ? "merged" : "open_or_absent") : "no_pr",
+        released: receipt.published || receipt.version ? "evidence" : "no_evidence",
+        closed: standing?.stage === "completed" && standing?.standing === "done",
+    };
+    if (stageTruth.running === "no_evidence" && record.approval_state === "approved") {
+        notes.push("No bound session shows live; an idle or absent pane is not proof of completion or failure.");
+    }
+    return {
+        ref,
+        found: true,
+        via,
+        subject: {
+            id: record.id,
+            kind: record.kind,
+            created_at: record.created_at,
+            by: record.actor.name,
+            ...(record.circle ? { circle: record.circle } : {}),
+            ...(record.intention ? { intention: record.intention } : {}),
+        },
+        ...(standing ? { standing } : {}),
+        ...(queue ? { queue } : {}),
+        sessions,
+        issues,
+        steering: { grant: grantState, attempts_used: attempts, ...(grant?.max_attempts !== undefined ? { max_attempts: grant.max_attempts } : {}) },
+        stage_truth: stageTruth,
+        next_authorized_action: nextAction(record, standing ?? null, queue),
+        notes,
+    };
+}

package/dist/providers.d.ts

@@ -0,0 +1,61 @@
+export type ProviderId = "codex" | "pi" | "copilot" | "claude";
+export interface ProviderSpec {
+    id: ProviderId;
+    cli: string;
+    name: string;
+    /** False when a provider may run only on an explicit, authorized request. */
+    selectable_by_default: boolean;
+    /** Config paths whose existence suggests a sign-in; contents are never read. */
+    auth_evidence: string[];
+}
+/** Preference order when a run request names no provider (jgwill/Miadi#893). */
+export declare const PROVIDERS: ProviderSpec[];
+export interface ProviderAvailability {
+    id: ProviderId;
+    name: string;
+    cli: string;
+    installed: boolean;
+    version?: string;
+    auth_evidence: "found" | "none";
+    selectable_by_default: boolean;
+}
+export interface DiscoveryProbe {
+    which?: (cli: string) => string | null;
+    versionOf?: (cli: string) => string | undefined;
+    exists?: (path: string) => boolean;
+    home?: string;
+}
+export declare function discoverProviders(probe?: DiscoveryProbe, specs?: ProviderSpec[]): ProviderAvailability[];
+export type ProviderResolution = {
+    state: "ok";
+    provider: ProviderAvailability;
+    explicit: boolean;
+} | {
+    state: "provider_unknown" | "provider_unavailable" | "provider_needs_explicit_selection";
+    message: string;
+    available: ProviderAvailability[];
+};
+/**
+ * Resolve the provider a run will ask the intake for. A requested provider must
+ * be known and installed; with no request the first installed provider in the
+ * preference order that may be selected by default wins — Claude Code only ever
+ * by an explicit request.
+ */
+export declare function resolveProvider(requested: string | undefined, found: ProviderAvailability[]): ProviderResolution;
+export type RouterPreflight = {
+    state: "unconfigured";
+    note: string;
+} | {
+    state: "reachable";
+    url: string;
+} | {
+    state: "router_unavailable";
+    url: string;
+    message: string;
+};
+/**
+ * The read-only Jev routing preflight (jgwill/Miadi#893, section E): is a Jev
+ * decision-aide endpoint configured and reachable from this host? Nothing is
+ * sent but a health probe; no key is read here and no source text ever leaves.
+ */
+export declare function routerPreflight(env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<RouterPreflight>;

package/dist/providers.js

@@ -0,0 +1,120 @@
+/**
+ * Provider capability discovery and selection policy (jgwill/Miadi#893, Phase 1C).
+ *
+ * The connector never assumes a provider works because a task text names one:
+ * it reports what is installed on this host, what sign-in evidence exists (the
+ * presence of the provider's own config directory — never its contents), and
+ * applies an explicit preference order. Claude Code is never selected silently:
+ * it requires an explicit request. When nothing safe is configured the answer
+ * is `provider_unavailable` and the mission is left unstarted.
+ *
+ * No bearer token is read, logged or returned here. Version probes run the
+ * provider's own `--version` with a short timeout.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Preference order when a run request names no provider (jgwill/Miadi#893). */
+export const PROVIDERS = [
+    { id: "codex", cli: "codex", name: "Codex CLI", selectable_by_default: true, auth_evidence: [".codex"] },
+    { id: "pi", cli: "pi", name: "Pi coding agent", selectable_by_default: true, auth_evidence: [".pi", ".config/pi"] },
+    { id: "copilot", cli: "copilot", name: "GitHub Copilot CLI", selectable_by_default: true, auth_evidence: [".copilot"] },
+    { id: "claude", cli: "claude", name: "Claude Code", selectable_by_default: false, auth_evidence: [".claude"] },
+];
+const defaultWhich = (cli) => {
+    try {
+        return execFileSync("sh", ["-c", `command -v "$1"`, "sh", cli], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+const defaultVersionOf = (cli) => {
+    try {
+        return execFileSync(cli, ["--version"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).split("\n")[0]?.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export function discoverProviders(probe = {}, specs = PROVIDERS) {
+    const which = probe.which ?? defaultWhich;
+    const versionOf = probe.versionOf ?? defaultVersionOf;
+    const exists = probe.exists ?? existsSync;
+    const home = probe.home ?? homedir();
+    return specs.map((s) => {
+        const installed = which(s.cli) !== null;
+        return {
+            id: s.id,
+            name: s.name,
+            cli: s.cli,
+            installed,
+            ...(installed ? { version: versionOf(s.cli) } : {}),
+            auth_evidence: s.auth_evidence.some((p) => exists(join(home, p))) ? "found" : "none",
+            selectable_by_default: s.selectable_by_default,
+        };
+    });
+}
+/**
+ * Resolve the provider a run will ask the intake for. A requested provider must
+ * be known and installed; with no request the first installed provider in the
+ * preference order that may be selected by default wins — Claude Code only ever
+ * by an explicit request.
+ */
+export function resolveProvider(requested, found) {
+    const installed = found.filter((p) => p.installed);
+    if (requested) {
+        const spec = PROVIDERS.find((p) => p.id === requested || p.cli === requested);
+        if (!spec) {
+            return {
+                state: "provider_unknown",
+                message: `Unknown provider "${requested}". Known: ${PROVIDERS.map((p) => p.id).join(", ")}.`,
+                available: installed,
+            };
+        }
+        const avail = found.find((p) => p.id === spec.id);
+        if (!avail.installed) {
+            return {
+                state: "provider_unavailable",
+                message: `${avail.name} is not installed on the connector host. The mission is left unstarted; name an available provider or install this one.`,
+                available: installed,
+            };
+        }
+        return { state: "ok", provider: avail, explicit: true };
+    }
+    const first = PROVIDERS.map((s) => found.find((p) => p.id === s.id)).find((p) => p.installed && p.selectable_by_default);
+    if (first)
+        return { state: "ok", provider: first, explicit: false };
+    if (installed.length) {
+        return {
+            state: "provider_needs_explicit_selection",
+            message: `Only providers that need an explicit request are installed (${installed.map((p) => p.id).join(", ")}). Name one in the request; none is chosen silently.`,
+            available: installed,
+        };
+    }
+    return { state: "provider_unavailable", message: "No agent provider is installed on the connector host.", available: [] };
+}
+/**
+ * The read-only Jev routing preflight (jgwill/Miadi#893, section E): is a Jev
+ * decision-aide endpoint configured and reachable from this host? Nothing is
+ * sent but a health probe; no key is read here and no source text ever leaves.
+ */
+export async function routerPreflight(env = process.env, fetchImpl = fetch) {
+    const url = (env.MIADI_JEV_URL ?? "").replace(/\/$/, "");
+    if (!url) {
+        return {
+            state: "unconfigured",
+            note: "No MIADI_JEV_URL on the connector host: model/tool routing falls back to the explicit provider policy and the person's choice, never to a silent default.",
+        };
+    }
+    try {
+        const res = await fetchImpl(`${url}/health`, { signal: AbortSignal.timeout(5000) });
+        if (res.ok)
+            return { state: "reachable", url };
+        return { state: "router_unavailable", url, message: `Jev answered ${res.status}; route by the explicit provider policy instead.` };
+    }
+    catch (error) {
+        return { state: "router_unavailable", url, message: `Jev is not reachable (${error instanceof Error ? error.message : String(error)}); route by the explicit provider policy instead.` };
+    }
+}

package/dist/queue-state.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectorRecord } from "./records.js";
+export declare function factoryDir(env?: NodeJS.ProcessEnv): string;
+export declare function runBriefFile(record: {
+    id: string;
+}): string;
+/** Evidence only: never creates a queue, dispatches work, or changes a request. */
+export declare function readQueueState(record: ConnectorRecord, dir?: string): {
+    state: string;
+    file: string;
+    note?: undefined;
+} | {
+    state: string;
+    file: string;
+    note: string;
+};

package/dist/queue-state.js

@@ -0,0 +1,24 @@
+/** Shared, read-only factory queue evidence for every request-state surface. */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function factoryDir(env = process.env) {
+    return env.MIADI_FACTORY_DIR || join(homedir(), ".miadi", "factory");
+}
+export function runBriefFile(record) {
+    return `connector-${record.id.replace(/[^\w-]/g, "-")}.md`;
+}
+/** Evidence only: never creates a queue, dispatches work, or changes a request. */
+export function readQueueState(record, dir = factoryDir()) {
+    const file = runBriefFile(record);
+    const queue = join(dir, "queue");
+    if (existsSync(join(queue, file)))
+        return { state: "queued", file };
+    if (existsSync(join(queue, "delivered", file)))
+        return { state: "delivered", file };
+    if (existsSync(join(queue, "cancelled", file)))
+        return { state: "cancelled", file };
+    if (existsSync(join(queue, "stale", file)))
+        return { state: "stale", file, note: "Its seat did not take it in time; the intake moved it aside." };
+    return { state: record.approval_state === "approved" ? "missing" : "not_queued", file };
+}

package/dist/records.d.ts

@@ -35,7 +35,7 @@ export declare const DOMAINS: readonly ["creative", "ceremonial", "engineering"]
 /** #815 "claim category": what kind of statement a record makes. */
 export declare const CLAIM_CATEGORIES: readonly ["observed", "hypothesis", "desired_future", "fiction", "verified_implementation"];
 export type ClaimCategory = (typeof CLAIM_CATEGORIES)[number];
-export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request"];
+export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request", "session_steer_request"];
 export type RecordKind = (typeof RECORD_KINDS)[number];
 /** #816 handoff states. */
 export declare const HANDOFF_STATES: readonly ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];
@@ -87,4 +87,7 @@ export declare function newRecordId(kind: RecordKind): string;
  * Fold the ledger: a record superseded by a later one shows the later one's
  * state, approval and receipt, keeping its own id and history.
  */
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
+export type { RequestProjection, RequestStage, RequestStanding, RequestDecision, ProjectionContext } from "./request-state.js";
 export declare function current(records: ConnectorRecord[]): ConnectorRecord[];

package/dist/records.js

@@ -60,6 +60,7 @@ export const RECORD_KINDS = [
     "session_completion_proposal",
     "research_artifact",
     "inquiry_episode_request",
+    "session_steer_request",
 ];
 /** #816 handoff states. */
 export const HANDOFF_STATES = ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];
@@ -76,6 +77,8 @@ export function newRecordId(kind) {
  * Fold the ledger: a record superseded by a later one shows the later one's
  * state, approval and receipt, keeping its own id and history.
  */
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
 export function current(records) {
     const byId = new Map();
     for (const r of records) {

package/dist/request-state.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a request stands, read once for every surface that shows it: the
+ * decision card in the conversation, the approval page, get_run_result and
+ * Miadi's /research (jgwill/Miadi#889, Mission A). A surface shows the
+ * projection's `label` and `lines`. It does not read the record's state,
+ * approval state or receipt by itself.
+ *
+ * Stages, from the ledger's folded record (see `current()`):
+ * - awaiting_decision: awaiting_approval, nothing decided
+ * - declined, sent_back: decided, nothing ran
+ * - dispatching: approved, and its brief is queued or running (state in_progress)
+ * - completed: approved, and its run finished (state completed)
+ * - failed: approved, and its run failed (state blocked); the same approval may run it again
+ *
+ * Approving with changes keeps the changes with the decision. A kind whose run
+ * does not carry instructions (approve.ts runBrief carries them only for runs and
+ * work proposals) lists them as outstanding. The projection never says they ran.
+ */
+import type { ConnectorRecord } from "./records.js";
+export declare const APPROVABLE_KINDS: readonly ["run_request", "review_operation_request", "deep_diver_request", "review_episode_link_request", "work_proposal", "session_completion_proposal", "inquiry_episode_request", "session_steer_request"];
+export declare const APPROVABLE: ReadonlySet<string>;
+/** `recording`: a decision was taken a moment ago and its run may still be going; it is not the ledger's state. */
+export type RequestStage = "awaiting_decision" | "recording" | "declined" | "sent_back" | "dispatching" | "completed" | "failed";
+export type RequestStanding = "waiting" | "open" | "done" | "stopped";
+export interface RequestDecision {
+    /** approve, approve_with_changes, request_revision or decline, as the person chose. */
+    choice: string;
+    by: string;
+    by_id?: string;
+    at?: string;
+    via?: string;
+    instructions?: string;
+    rerun_by?: string;
+}
+export interface RequestProjection {
+    ref: string;
+    kind: string;
+    stage: RequestStage;
+    standing: RequestStanding;
+    /** Plain words for where it stands. Names, times and instructions are not in it, so it is safe before sign-in. */
+    label: string;
+    decision?: RequestDecision;
+    /** The receipt's outcome: queued, done, failed, linked, woven, minted_and_woven, marked_ready, decided, nothing_to_run. */
+    outcome?: string;
+    failure?: string;
+    /** The review the request produced or changed, at the review service, when the receipt names one. */
+    receipt_url?: string;
+    /** Approved and failed: a write-tier person may run it again with the same approval and instructions. */
+    rerun: {
+        available: boolean;
+        by?: string;
+    };
+    /** Work the approver asked for that did not run. Empty when nothing is outstanding. */
+    outstanding: string[];
+    /** Every sentence a surface shows under the label, names and instructions included. */
+    lines: string[];
+}
+export interface ProjectionContext {
+    /** The review service's public address, for receipt_url. Default MIADI_REVIEW_BASE_URL, else the public service. */
+    reviewBase?: string;
+    /** The factory queue state of a brief (queued, delivered, missing, not_queued), when the caller read it. */
+    queue?: {
+        state: string;
+    };
+    /** A decision on this request is being recorded now (its run may still be going). */
+    recording?: boolean;
+}
+/** The projection of an approvable request, or null for a record that is not one. */
+export declare function projectRequest(record: ConnectorRecord, ctx?: ProjectionContext): RequestProjection | null;

package/dist/request-state.js

@@ -0,0 +1,180 @@
+export const APPROVABLE_KINDS = [
+    "run_request",
+    "review_operation_request",
+    "deep_diver_request",
+    "review_episode_link_request",
+    "work_proposal",
+    "session_completion_proposal",
+    "inquiry_episode_request",
+    "session_steer_request",
+];
+export const APPROVABLE = new Set(APPROVABLE_KINDS);
+/** The kinds whose approved run carries the approver's instructions into what it does. */
+const CARRIES_INSTRUCTIONS = new Set(["run_request", "work_proposal"]);
+const CHOICE_WORDS = {
+    approve: "Approved",
+    approve_with_changes: "Approved with changes",
+    request_revision: "Sent back for revision",
+    decline: "Declined",
+    covered_by_grant: "Covered by the approved run's steering grant",
+};
+const OUTCOME_WORDS = {
+    queued: "queued for the factory intake",
+    done: "done",
+    linked: "filed in the episode",
+    woven: "woven into the episode",
+    minted_and_woven: "a new episode minted with it",
+    marked_ready: "marked ready for Deep Diver",
+    decided: "recorded",
+    nothing_to_run: "nothing to run",
+    accepted: "accepted by the session",
+    submitted: "typed into the session, acceptance unconfirmed",
+    failed: "failed",
+};
+const NOT_CARRIED = "The changes you approved are recorded and did not run: this kind of request does not carry instructions into its run. They are still to do.";
+const text = (v) => (typeof v === "string" ? v.trim() : "");
+function reviewBaseOf(ctx) {
+    const base = ctx.reviewBase ?? process.env.MIADI_REVIEW_BASE_URL ?? "https://miadi-review-service.vercel.app";
+    return base.replace(/\/$/, "");
+}
+/** The projection of an approvable request, or null for a record that is not one. */
+export function projectRequest(record, ctx = {}) {
+    if (!APPROVABLE.has(record.kind))
+        return null;
+    const receipt = (record.completion_receipt ?? {});
+    const choice = text(receipt.decision) || undefined;
+    const instructions = text(receipt.instructions) || undefined;
+    const decision = record.approval_state === "awaiting_approval" || !choice
+        ? undefined
+        : {
+            choice,
+            by: text(receipt.decided_by?.name) || "someone",
+            ...(receipt.decided_by?.person_id ? { by_id: String(receipt.decided_by.person_id) } : {}),
+            ...(text(receipt.decided_at) ? { at: text(receipt.decided_at) } : {}),
+            ...(text(receipt.via) ? { via: text(receipt.via) } : {}),
+            ...(instructions ? { instructions } : {}),
+            ...(text(receipt.rerun_by?.name) ? { rerun_by: text(receipt.rerun_by.name) } : {}),
+        };
+    const base = { ref: record.id, kind: record.kind, rerun: { available: false }, outstanding: [] };
+    if (record.approval_state === "awaiting_approval" && ctx.recording) {
+        return finish({ ...base, stage: "recording", standing: "open", label: "Being recorded" }, [
+            "A decision on this request is being recorded. It shows here when it is done.",
+        ]);
+    }
+    if (record.approval_state === "awaiting_approval") {
+        return finish({ ...base, stage: "awaiting_decision", standing: "waiting", label: "Awaiting a decision" }, [
+            "Waiting for a person with Miadi's write tier to decide.",
+        ]);
+    }
+    if (record.approval_state === "declined") {
+        return finish({ ...base, stage: "declined", standing: "stopped", decision, label: "Declined" }, decisionLines(decision));
+    }
+    if (record.approval_state === "revision_requested") {
+        const lines = decisionLines(decision);
+        if (instructions)
+            lines.push(`Instructions for whoever asked: ${instructions}`);
+        return finish({ ...base, stage: "sent_back", standing: "waiting", decision, label: "Sent back for revision" }, lines);
+    }
+    // A grant-covered steer runs without its own decision: its authorization is
+    // the approved run's steering grant, which the receipt names.
+    const approved = record.approval_state === "approved" || (record.approval_state === "not_required" && record.kind === "session_steer_request");
+    if (!approved)
+        return null;
+    const changes = choice === "approve_with_changes";
+    const outcome = text(receipt.outcome) || undefined;
+    const outcomeWord = outcome ? (OUTCOME_WORDS[outcome] ?? outcome.replace(/_/g, " ")) : undefined;
+    const rerunBy = decision?.rerun_by;
+    if (record.state === "blocked") {
+        const resp = (receipt.response ?? {});
+        const status = typeof receipt.status === "number" ? receipt.status : undefined;
+        const failure = text(receipt.message) || text(resp.message) || text(resp.error) || (status !== undefined ? `the door answered ${status}` : "the door it called refused");
+        const outstanding = outstandingFor(record, decision);
+        const lines = [...decisionLines(decision), `Failure: ${failure}`];
+        if (receipt.outcome)
+            lines.push(`Outcome: ${outcomeWord}.`);
+        lines.push(...outstanding);
+        return finish({
+            ...base,
+            stage: "failed",
+            standing: "stopped",
+            decision,
+            label: `${changes ? "Approved with changes" : "Approved"}, but running it failed`,
+            outcome: outcome ?? "failed",
+            failure,
+            rerun: { available: true, ...(rerunBy ? { by: rerunBy } : {}) },
+            outstanding,
+        }, lines);
+    }
+    if (record.state === "in_progress") {
+        const delivered = ctx.queue?.state === "delivered";
+        const outstanding = [];
+        if (ctx.queue?.state === "missing")
+            outstanding.push("The brief is missing from the factory queue, so the intake cannot deliver it.");
+        if (ctx.queue?.state === "cancelled" || ctx.queue?.state === "stale") {
+            outstanding.push(`The factory intake set the brief aside (${ctx.queue.state}), so nothing is running for it.`);
+        }
+        const lines = [...decisionLines(decision), outcomeWord ? `Outcome: ${outcomeWord}.` : "Outcome: queued for the factory intake."];
+        if (delivered)
+            lines.push("Delivered to an agent session.");
+        lines.push(...outstanding);
+        return finish({
+            ...base,
+            stage: "dispatching",
+            standing: "open",
+            decision,
+            label: `${changes ? "Approved with changes" : "Approved"}, ${delivered ? "delivered to a session" : "dispatching"}`,
+            outcome,
+            outstanding,
+        }, lines);
+    }
+    const outstanding = outstandingFor(record, decision);
+    const receiptUrl = reviewUrlOf(record, receipt, ctx);
+    const lines = [...decisionLines(decision)];
+    if (outcomeWord)
+        lines.push(`Outcome: ${outcomeWord}.`);
+    if (receiptUrl)
+        lines.push(`Review: ${receiptUrl}`);
+    lines.push(...outstanding);
+    return finish({
+        ...base,
+        stage: "completed",
+        standing: outstanding.length ? "open" : "done",
+        decision,
+        label: outstanding.length
+            ? "Approved with changes, changes outstanding"
+            : `${changes ? "Approved with changes" : "Approved"}${outcomeWord ? `, ${outcomeWord}` : ""}`,
+        outcome,
+        ...(receiptUrl ? { receipt_url: receiptUrl } : {}),
+        outstanding,
+    }, lines);
+}
+function finish(p, lines) {
+    return { ...p, lines: lines.filter((l) => l.length > 0) };
+}
+function decisionLines(decision) {
+    if (!decision)
+        return [];
+    const when = decision.at ? ` at ${decision.at}` : "";
+    const through = decision.via ? ` (through ${decision.via})` : "";
+    const out = [`${CHOICE_WORDS[decision.choice] ?? decision.choice} by ${decision.by}${when}${through}.`];
+    if (decision.instructions)
+        out.push(`Instructions: ${decision.instructions}`);
+    if (decision.rerun_by)
+        out.push(`Run again by ${decision.rerun_by}.`);
+    return out;
+}
+function outstandingFor(record, decision) {
+    if (decision?.choice !== "approve_with_changes" || !decision.instructions)
+        return [];
+    if (CARRIES_INSTRUCTIONS.has(record.kind))
+        return [];
+    return [NOT_CARRIED];
+}
+function reviewUrlOf(record, receipt, ctx) {
+    if (record.kind !== "review_operation_request" && record.kind !== "deep_diver_request")
+        return undefined;
+    if (receipt.outcome !== "done" && receipt.outcome !== "marked_ready")
+        return undefined;
+    const id = text(receipt.response?.id) || text(record.body.review_id);
+    return id ? `${reviewBaseOf(ctx)}/review/${encodeURIComponent(id)}` : undefined;
+}