@miadi/connector 0.1.9 → 0.1.11

package/README.md

@@ -20,12 +20,13 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 | kind | tools |
 |---|---|
-| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `search` `fetch` |
+| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `read_episode_file` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `mission_status` `provider_capabilities` `search` `fetch` |
 | contributions | `append_observation` `open_inquiry` `link_records` `propose_narrative_beat` `record_evaluation` `register_source_intent` `record_handoff` `update_handoff` `prepare_calendar_event` `save_research` |
-| requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_review_operation` `request_deep_diver` `link_review_to_episode` `request_inquiry_episode` |
+| requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_session_steer` `request_review_operation` `request_deep_diver` `link_review_to_episode` `request_inquiry_episode` |
 | decisions in the conversation | `show_decisions` (cards), `decide_request` (called by the card only) |
 
 - **Reads** need Miadi's read tier and stay within it. A person Miadi gives no API tier reaches only `get_capabilities`. Sessions need the write tier, because a session's name and pane are operator data. For the same reason, below the write tier a record someone else made shows no session, working folder or seat, and no long bodies.
+- **Episode files.** `get_evidence` lists an episode's files; each text file Miadi can preview carries a `read_ref` (`miadi-chronicle://<n>/<path>`). `read_episode_file` (or `fetch` with that ref) returns the file's whole UTF-8 text, read as the person through Miadi's file door, so Miadi's audience and room rules apply. The answer names the episode, the path, the content type, the byte count and the sha256, and `verified` says whether the text received hashes to what Miadi read. Only md, txt, yaml, yml and json files up to 512 KiB are read. A traversal, absolute, hidden or encoded path is refused before any URL is built. A longer text comes in pages cut on character boundaries: pass `page.next` back, and the joined pages hash to `sha256`. Other kinds answer `unsupported`, a file over the limit `too_large`, a missing one `not_found`, a ceremony note below the write gate `forbidden`.
 - **Contributions** need Miadi's read tier and the `miadi:contribute` scope, chosen at sign-in. A record is moved on (`update_handoff`) only by its author or the write tier, and a request's receipt comes only from its decision. They append a record to the ledger and change nothing else, except `save_research`: it saves a report on the inquiry shelf as a new folder (the Markdown exactly as given, owner and visibility recorded, private by default), opens the folder's inquiry issue, and commits and pushes the folder in the shelf's repository. A long report is sent in parts (`part`, `parts`, `upload_id`) and saved when the last part arrives; the answer returns its bytes, sha256 and first and last lines.
 - **Requests** append a record that waits for a decision. The answer gives an `approval_url`; Miadi's `/research` page offers the same decisions to a signed-in person with the write tier, and `show_decisions` shows them as cards inside the conversation (below). The person approves, approves with changes (their instructions are carried into what runs), sends it back for revision with instructions (`revision_requested`, nothing runs, `get_run_result` returns the instructions), or declines. Only the approval door runs a request, once, as that person; a second decision on the same request, at the same time or later, is refused:
   - a run becomes a brief in the factory queue, which the intake delivers to a session;
@@ -40,6 +41,14 @@ The model that asked cannot approve its own request.
 
 `get_run_result` returns one `projection` of the decision, dispatch/completion state, receipt link and outstanding instructions. The in-chat card, approval page and Miadi's research page use that same read model. Asking `show_decisions` for an already-decided `record_id` shows its receipt without issuing another decision token. An in-flight card can refresh status without repeating the operation. A completed basic review with unapplied approval instructions remains open as **changes outstanding**, not falsely finished.
 
+### Following and steering a mission
+
+`mission_status` joins one mission read-only: its source request and decision, the sessions bound to it (each with how it is bound — a signed `session:` ref, the delivered brief's target, or the requested name), its issues and PRs, its steering grant, and where it stands stage by stage — approved, queued, delivered, running, merged, released, closed — each by its evidence, so an idle pane or a merge is never read as completion. Live panes and Miadi's session view are joined only for the write tier.
+
+`request_session_steer` sends one authorized follow-up to one existing live agent, within the steering grant an approved run carries (`steering: { max_attempts, expires_at, pane }` on `request_authorized_run`). It peeks at the bound pane — the grant's pane or the session's first pane, never whichever pane is active — refuses a busy agent or a pane that is not an agent, types the exact instruction literally, and re-peeks to verify the agent accepted it (`accepted`) or only holds it at the prompt (`submitted`). Every attempt leaves a durable artifact with the instruction's sha256, its grant, its target and both captures. A steer the grant does not cover waits for one explicit scoped human decision on its `approval_url`, which runs exactly that instruction once.
+
+`request_authorized_run` may name a `provider` (`codex`, `pi`, `copilot`, `claude`). The connector verifies it is installed on the host before recording anything; an unknown or unavailable provider answers `provider_unavailable` and the mission stays unstarted. With no provider named, the first installed provider in the preference order is resolved and named in the brief; Claude Code is never chosen silently — it runs only when named. `provider_capabilities` (write tier) reports what the host has installed, the sign-in evidence, the preference order, and the read-only Jev routing preflight (`unconfigured` without `MIADI_JEV_URL`). A provider name inside a task's text selects nothing.
+
 ### Deciding inside the conversation
 
 In a client that renders MCP Apps (ChatGPT among them), `show_decisions` draws one card per request awaiting a decision: what is asked, by whom, and what approving does. The person decides on the card with their own click: Approve, Approve with my changes, Send back for revision, or Decline. The card then shows the receipt.

package/dist/approve.d.ts

@@ -16,6 +16,7 @@ import type { MiadiClient } from "./miadi.js";
 import { type MiadiPerson } from "./people.js";
 import { type ConnectorRecord } from "./records.js";
 import { type RequestProjection } from "./request-state.js";
+import { type TmuxLike } from "./steer.js";
 export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 export interface ApprovalDeps {
     config: ConnectorConfig;
@@ -26,6 +27,10 @@ export interface ApprovalDeps {
     /** The factory directory holding queue/ (default ~/.miadi/factory). */
     factoryDir?: string;
     tmuxSessions?: () => string[];
+    /** The steering surface (jgwill/Miadi#893); tests inject a fake, production uses tmux. */
+    tmux?: TmuxLike;
+    /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
+    steerSettleMs?: number;
 }
 /**
  * What a person may decide on a request. Approving with changes runs it with the

package/dist/approve.js

@@ -19,6 +19,7 @@ import { MiadiUnavailable } from "./people.js";
 import { current, newRecordId } from "./records.js";
 import { APPROVABLE, projectRequest } from "./request-state.js";
 import { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
+import { steerAttempts, steerSession, tmuxAdapter } from "./steer.js";
 export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 /**
  * What a person may decide on a request. Approving with changes runs it with the
@@ -67,7 +68,15 @@ export function runBrief(record, approver, sessions, instructions) {
     const short = record.id.split(":")[1]?.slice(0, 8) ?? "run";
     const to = body.session && sessions.includes(body.session) ? body.session : `new:${body.session ?? `connector-${yymmdd()}-${short}`}`;
     const cwd = body.cwd || "/a/src/Miadi-18";
-    const open = [`to="${attr(to)}"`, 'status="send"', 'type="connector-run"', `record="${attr(record.id)}"`, ...(to.startsWith("new:") ? [`cwd="${attr(cwd)}"`] : [])];
+    const open = [
+        `to="${attr(to)}"`,
+        'status="send"',
+        'type="connector-run"',
+        `record="${attr(record.id)}"`,
+        // The provider the connector verified at request time (jgwill/Miadi#893); the intake may honour it or record why not.
+        ...(body.resolved_provider ? [`provider="${attr(body.resolved_provider)}"`] : []),
+        ...(to.startsWith("new:") ? [`cwd="${attr(cwd)}"`] : []),
+    ];
     const lines = [
         `<input ${open.join(" ")}>`,
         `A bounded task requested through the Miadi connector (jgwill/Miadi#815, #816).`,
@@ -202,6 +211,23 @@ export async function executeApproved(record, approver, deps, instructions) {
                 ending: b.ending,
                 note: "Recorded only. The witness seat writes it into the inventory record and closes the session by its own lifecycle.",
             };
+        case "session_steer_request": {
+            // The person's approval of this exact steer is its authorization; the
+            // grant record it cites still binds the session (jgwill/Miadi#893).
+            const grantId = record.refs.find((r) => r.startsWith("run_request:") || r.startsWith("work_proposal:"));
+            const grantRecord = grantId ? current(deps.ledger.all()).find((x) => x.id === grantId) : undefined;
+            if (!grantRecord)
+                return { outcome: "failed", message: "The run whose grant this steer cites is gone." };
+            const result = await steerSession({ tmux: deps.tmux ?? tmuxAdapter(), stateDir: deps.config.stateDir, ...(deps.steerSettleMs !== undefined ? { settleMs: deps.steerSettleMs } : {}) }, { record, grantRecord, priorAttempts: steerAttempts(current(deps.ledger.all()), grantRecord.id), authorized: true });
+            const delivered = result.status === "accepted" || result.status === "submitted";
+            return {
+                outcome: delivered ? result.status : "failed",
+                steer_status: result.status,
+                message: result.message,
+                ...(result.target ? { target: result.target } : {}),
+                ...(result.artifact ? { artifact: result.artifact } : {}),
+            };
+        }
         default:
             return { outcome: "nothing_to_run" };
     }
@@ -398,6 +424,8 @@ export function consequenceOf(r) {
             return b.new_episode ? "Approving mints a new episode with the inquiry woven in." : `Approving weaves the inquiry into episode ${b.episode ?? "?"}.`;
         case "session_completion_proposal":
             return `Approving records the ending (${b.ending ?? "?"}) for the session. No pane is closed.`;
+        case "session_steer_request":
+            return `Approving types exactly this instruction into the bound agent session (${b.session ?? "the run's session"}), once, and records whether the agent accepted it.`;
         default:
             return "Approving runs the request once, as you.";
     }
@@ -594,4 +622,5 @@ export const KIND_LABELS = {
     review_episode_link_request: "Review into an episode",
     inquiry_episode_request: "Inquiry into an episode",
     session_completion_proposal: "Session ending",
+    session_steer_request: "Session steer",
 };

package/dist/episode-files.d.ts

@@ -0,0 +1,62 @@
+/** The extensions Miadi's vessel reads as text (@medicine-wheel/episode-vessel TEXT_EXTENSIONS). */
+export declare const TEXT_TYPES: Record<string, string>;
+/** The vessel's own limit for reading text whole (MAX_TEXT_BYTES). */
+export declare const MAX_TEXT_BYTES: number;
+export declare const DEFAULT_PAGE_BYTES = 100000;
+/** A page must hold the longest UTF-8 character. */
+export declare const MIN_PAGE_BYTES = 4;
+export declare class FileRefusal extends Error {
+    readonly code: "invalid_path" | "invalid_offset" | "unsupported" | "changed";
+    constructor(code: "invalid_path" | "invalid_offset" | "unsupported" | "changed", message: string);
+}
+/** The same rule as the vessel's assertRelativeFile, applied before any URL exists. */
+export declare function checkRelativePath(value: string): string[];
+export declare function extensionOf(path: string): string;
+/** `miadi-chronicle://548/foundations/x/README.md` → its episode and path; null for any other id. */
+export declare function parseFileRef(id: string): {
+    episode: string;
+    path: string;
+} | null;
+export declare function fileRef(episodeNumber: number | string, path: string): string;
+/** The episode number a folder carries (`2026-09-27-episode-548-…` → 548). */
+export declare function episodeNumberOf(folder: string): number | null;
+export interface MiadiText {
+    episode: string;
+    file: string;
+    content: string;
+    size: number;
+    revision?: {
+        sha256?: string;
+        bytes?: number;
+        modifiedAt?: string;
+    };
+}
+/**
+ * One page of a file Miadi returned whole. `offset` must be 0 or a
+ * `next.offset` this function gave, so a page never starts inside a character;
+ * `revision`, when given, must still be the file's sha256, so pages of two
+ * versions are never joined.
+ */
+export declare function pageOf(text: MiadiText, opts?: {
+    offset?: number;
+    maxBytes?: number;
+    revision?: string;
+}): {
+    page: {
+        offset: number;
+        end: number;
+        bytes: number;
+        sha256: string;
+        complete: boolean;
+        next: {
+            offset: number;
+            revision: string;
+        } | null;
+    };
+    text: string;
+    modified_at?: string | undefined;
+    verification?: string | undefined;
+    bytes: number;
+    sha256: string;
+    verified: boolean;
+};

package/dist/episode-files.js

@@ -0,0 +1,115 @@
+/**
+ * Reading one text file an episode holds, through Miadi's file door
+ * (`GET /api/chronicle/episodes/<ref>/files/<path>`, jgwill/Miadi#653), as the
+ * signed-in person. Miadi decides what that person may read: the episode's
+ * audience, the room rule (ceremony notes and captures), the vessel's path
+ * guard and its 512 KiB text limit. The connector adds two things Miadi cannot
+ * see from its side of the URL:
+ *
+ * - the path is checked before a URL is built, because a URL parser folds
+ *   `a/../../people` into another route before Miadi ever reads it;
+ * - the text is paged by UTF-8 bytes on character boundaries, each page
+ *   carrying the whole file's sha256, so a reader can join the pages and prove
+ *   they hold the file exactly (jgwill/Miadi#815).
+ */
+import { createHash } from "node:crypto";
+/** The extensions Miadi's vessel reads as text (@medicine-wheel/episode-vessel TEXT_EXTENSIONS). */
+export const TEXT_TYPES = {
+    ".md": "text/markdown; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".yaml": "application/yaml; charset=utf-8",
+    ".yml": "application/yaml; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+};
+/** The vessel's own limit for reading text whole (MAX_TEXT_BYTES). */
+export const MAX_TEXT_BYTES = 512 * 1024;
+export const DEFAULT_PAGE_BYTES = 100_000;
+/** A page must hold the longest UTF-8 character. */
+export const MIN_PAGE_BYTES = 4;
+export class FileRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** The same rule as the vessel's assertRelativeFile, applied before any URL exists. */
+export function checkRelativePath(value) {
+    if (!value || value.includes("\\") || value.includes("\0") || value.startsWith("/") || /^[a-z]+:/i.test(value)) {
+        throw new FileRefusal("invalid_path", "Name a file by its path inside the episode, as get_evidence lists it (e.g. foundations/<topic>/README.md).");
+    }
+    const segments = value.split("/");
+    if (segments.some((s) => !s || s === "." || s === ".." || s.startsWith(".") || /%2e|%2f|%5c|%00/i.test(s))) {
+        throw new FileRefusal("invalid_path", "The path has an empty, '.', '..', hidden or encoded segment; episode files are read by their listed path only.");
+    }
+    return segments;
+}
+export function extensionOf(path) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot).toLowerCase() : "";
+}
+/** `miadi-chronicle://548/foundations/x/README.md` → its episode and path; null for any other id. */
+export function parseFileRef(id) {
+    const m = /^miadi-chronicle:(?:\/\/)?([^/\s]+)\/(.+)$/.exec(id.trim());
+    return m ? { episode: m[1], path: m[2] } : null;
+}
+export function fileRef(episodeNumber, path) {
+    return `miadi-chronicle://${episodeNumber}/${path}`;
+}
+/** The episode number a folder carries (`2026-09-27-episode-548-…` → 548). */
+export function episodeNumberOf(folder) {
+    const m = /(?:^|-)episode-0*(\d+)(?:-|$)/.exec(folder);
+    return m ? Number.parseInt(m[1], 10) : null;
+}
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/**
+ * One page of a file Miadi returned whole. `offset` must be 0 or a
+ * `next.offset` this function gave, so a page never starts inside a character;
+ * `revision`, when given, must still be the file's sha256, so pages of two
+ * versions are never joined.
+ */
+export function pageOf(text, opts = {}) {
+    const bytes = Buffer.from(text.content, "utf8");
+    const total = bytes.byteLength;
+    const whole = sha256(bytes);
+    if (opts.revision && opts.revision !== whole) {
+        throw new FileRefusal("changed", `The file changed since that page was read (it was ${opts.revision}, it is ${whole} now). Read it again from offset 0.`);
+    }
+    const offset = opts.offset ?? 0;
+    const maxBytes = Math.max(MIN_PAGE_BYTES, opts.maxBytes ?? DEFAULT_PAGE_BYTES);
+    if (!Number.isInteger(offset) || offset < 0 || offset > total || (offset < total && (bytes[offset] & 0xc0) === 0x80)) {
+        throw new FileRefusal("invalid_offset", `offset must be 0 or a next.offset this tool returned (the file has ${total} bytes).`);
+    }
+    let end = Math.min(total, offset + maxBytes);
+    while (end < total && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    const page = bytes.subarray(offset, end);
+    const complete = end === total;
+    // Miadi computed its sha256 over the text it decoded; the bytes on disk are
+    // `size`. Both agree only when the file is valid UTF-8 and was read whole.
+    const miadiSha = text.revision?.sha256;
+    const verified = miadiSha === whole && total === text.size;
+    return {
+        bytes: total,
+        sha256: whole,
+        verified,
+        ...(verified
+            ? {}
+            : {
+                verification: miadiSha !== whole
+                    ? `Miadi named sha256 ${miadiSha ?? "none"}; the text received hashes to ${whole}.`
+                    : `The file is ${text.size} bytes on disk and ${total} bytes as UTF-8 text: it is not valid UTF-8, and the text holds replacement characters.`,
+            }),
+        ...(text.revision?.modifiedAt ? { modified_at: text.revision.modifiedAt } : {}),
+        page: {
+            offset,
+            end,
+            bytes: page.byteLength,
+            sha256: sha256(page),
+            complete,
+            next: complete ? null : { offset: end, revision: whole },
+        },
+        text: page.toString("utf8"),
+    };
+}

package/dist/index.d.ts

@@ -5,4 +5,7 @@ export { MiadiOAuthProvider, SCOPES, SCOPE_READ, SCOPE_CONTRIBUTE, type Person }
 export { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, RECORD_KINDS, current, type ConnectorRecord, type CircleId, type ClaimCategory, type RecordKind, } from "./records.js";
 export { TOOL_STATUS } from "./tools.js";
 export { runBrief, readQueueState } from "./approve.js";
+export { PROVIDERS, discoverProviders, resolveProvider, routerPreflight, type ProviderAvailability, type ProviderId, type ProviderResolution, type RouterPreflight, } from "./providers.js";
+export { missionStatus, resolveMissionSubject, type MissionStatus, type MissionStatusDeps } from "./mission-status.js";
+export { AGENT_COMMANDS, BUSY_PATTERNS, STEER_STATUSES, checkGrant, isBusy, readSteerArtifact, steerAttempts, steerSession, steeringGrantOf, tmuxAdapter, type SteerDeps, type SteerResult, type SteerStatus, type SteeringGrant, type TmuxLike, } from "./steer.js";
 export { VERSION } from "./version.js";

package/dist/index.js

@@ -5,4 +5,7 @@ export { MiadiOAuthProvider, SCOPES, SCOPE_READ, SCOPE_CONTRIBUTE } from "./oaut
 export { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, RECORD_KINDS, current, } from "./records.js";
 export { TOOL_STATUS } from "./tools.js";
 export { runBrief, readQueueState } from "./approve.js";
+export { PROVIDERS, discoverProviders, resolveProvider, routerPreflight, } from "./providers.js";
+export { missionStatus, resolveMissionSubject } from "./mission-status.js";
+export { AGENT_COMMANDS, BUSY_PATTERNS, STEER_STATUSES, checkGrant, isBusy, readSteerArtifact, steerAttempts, steerSession, steeringGrantOf, tmuxAdapter, } from "./steer.js";
 export { VERSION } from "./version.js";

package/dist/mission-status.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Read-only mission status (jgwill/Miadi#893, Phase 1A): where one mission
+ * stands, joined from the connector ledger, the factory queue, tmux, Miadi's
+ * session view and GitHub — with every stage named by its evidence, so an idle
+ * pane or a merge is never read as completion.
+ *
+ * The caller (tools.ts) decides the viewer's tier first: without the write
+ * tier there are no operator details (live panes, session internals); the
+ * record's own standing still answers.
+ */
+import type { ConnectorRecord } from "./records.js";
+import type { RequestProjection } from "./request-state.js";
+export interface MissionSession {
+    /** How this session is bound to the mission: signed_ref (a session: ref on the record), brief_target (the delivered brief's `to`), named (the requested name). */
+    association: "signed_ref" | "brief_target" | "named";
+    session: string;
+    live: "running" | "absent" | "unknown";
+    activity?: "busy" | "idle" | "unknown";
+    /** Present when Miadi's session view was joined (write tier). */
+    miadi?: unknown;
+}
+export interface MissionStageTruth {
+    approved: boolean;
+    queued: boolean;
+    delivered: boolean;
+    /** "evidence" only while a bound session is live; an idle pane proves nothing. */
+    running: "evidence" | "no_evidence";
+    pr_merged: "merged" | "open_or_absent" | "no_pr";
+    released: "evidence" | "no_evidence";
+    closed: boolean;
+}
+export interface MissionStatus {
+    ref: string;
+    found: boolean;
+    via?: string;
+    subject?: {
+        id: string;
+        kind: string;
+        created_at: string;
+        by: string;
+        circle?: string;
+        intention?: string;
+    };
+    standing?: RequestProjection;
+    queue?: {
+        state: string;
+    };
+    sessions?: MissionSession[];
+    issues?: {
+        ref: string;
+        state: string;
+        title?: string;
+        merged?: boolean;
+    }[];
+    steering?: {
+        grant: "none" | "active" | "expired_grant" | "exhausted";
+        attempts_used: number;
+        max_attempts?: number;
+    };
+    stage_truth?: MissionStageTruth;
+    next_authorized_action?: string;
+    notes: string[];
+}
+export interface MissionStatusDeps {
+    queueOf?: (record: ConnectorRecord) => {
+        state: string;
+    } | undefined;
+    projectOf: (record: ConnectorRecord) => RequestProjection | null;
+    /** Live tmux session names, when the host can list them (write tier only). */
+    tmuxSessions?: () => string[];
+    /** Read-only peek: is the named session's first pane mid-turn? (write tier only.) */
+    paneBusy?: (session: string) => "busy" | "idle" | "unknown";
+    /** Miadi's session view by session:<uuid> (write tier only). */
+    sessionOf?: (id: string) => Promise<unknown>;
+    issueOf?: (owner: string, repo: string, n: string) => Promise<{
+        state: string;
+        title?: string;
+        merged?: boolean;
+    }>;
+    now?: () => Date;
+}
+/** The record a mission reference resolves to, and how it was found. */
+export declare function resolveMissionSubject(ref: string, records: ConnectorRecord[]): {
+    record: ConnectorRecord;
+    via: string;
+} | null;
+export declare function missionStatus(ref: string, records: ConnectorRecord[], deps: MissionStatusDeps): Promise<MissionStatus>;

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>;