@miadi/connector 0.1.9 → 0.1.10

package/README.md

@@ -20,9 +20,9 @@ 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` `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.
@@ -40,6 +40,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/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>;

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/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"];

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

package/dist/request-state.d.ts

@@ -17,7 +17,7 @@
  * 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"];
+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";

package/dist/request-state.js

@@ -6,6 +6,7 @@ export const APPROVABLE_KINDS = [
     "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. */
@@ -15,6 +16,7 @@ const CHOICE_WORDS = {
     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",
@@ -25,6 +27,8 @@ const OUTCOME_WORDS = {
     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.";
@@ -71,7 +75,10 @@ export function projectRequest(record, ctx = {}) {
             lines.push(`Instructions for whoever asked: ${instructions}`);
         return finish({ ...base, stage: "sent_back", standing: "waiting", decision, label: "Sent back for revision" }, lines);
     }
-    if (record.approval_state !== "approved")
+    // 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;

package/dist/server.d.ts

@@ -3,12 +3,20 @@ import type { MiadiPerson } from "./people.js";
 import { Ledger } from "./store.js";
 import type { ConnectorRecord } from "./records.js";
 import type { ConnectorConfig } from "./config.js";
+import type { TmuxLike } from "./steer.js";
+import type { DiscoveryProbe } from "./providers.js";
 export interface ConnectorDeps {
     identify: (token: string) => Promise<MiadiPerson | null>;
     fetchImpl?: typeof fetch;
     /** 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;
+    /** Provider discovery probes (jgwill/Miadi#893); tests inject fakes. */
+    providersProbe?: DiscoveryProbe;
+    /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
+    steerSettleMs?: number;
     /** Person-token attempts allowed per address in 15 minutes on each sign-in form (default 30). */
     tokenAttemptsPerWindow?: number;
 }

package/dist/server.js

@@ -85,6 +85,8 @@ export function createConnectorApp(config, deps) {
         fetchImpl: deps.fetchImpl,
         factoryDir: deps.factoryDir,
         tmuxSessions: deps.tmuxSessions,
+        tmux: deps.tmux,
+        steerSettleMs: deps.steerSettleMs,
     };
     registerApprovalRoutes(app, approvalDeps);
     const decisionTokens = new DecisionTokens(config.stateDir);
@@ -94,7 +96,20 @@ export function createConnectorApp(config, deps) {
         resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
     });
     const handle = async (req, res) => {
-        const ctx = { config, miadi, reviews, ledger, oauthState, factoryDir: deps.factoryDir, approval: approvalDeps, decisionTokens };
+        const ctx = {
+            config,
+            miadi,
+            reviews,
+            ledger,
+            oauthState,
+            factoryDir: deps.factoryDir,
+            approval: approvalDeps,
+            decisionTokens,
+            tmux: deps.tmux,
+            tmuxSessions: deps.tmuxSessions,
+            providersProbe: deps.providersProbe,
+            steerSettleMs: deps.steerSettleMs,
+        };
         const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
         registerTools(server, ctx);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });

package/dist/steer.d.ts

@@ -0,0 +1,71 @@
+import { execFileSync } from "node:child_process";
+import type { ConnectorRecord } from "./records.js";
+export declare const STEER_STATUSES: readonly ["prepared", "submitted", "accepted", "busy", "blocked", "wrong_pane", "stale_binding", "expired_grant", "duplicate"];
+export type SteerStatus = (typeof STEER_STATUSES)[number];
+/** The steering grant an approved run carries: `body.steering` on the run_request or work proposal. */
+export interface SteeringGrant {
+    /** How many steers the approval covers. */
+    max_attempts?: number;
+    /** ISO time after which no steer runs under this grant. */
+    expires_at?: string;
+    /** The pane the seat lives in, `window.pane` (default the session's first pane). */
+    pane?: string;
+}
+export interface PaneInfo {
+    /** tmux pane id, e.g. %67 — evidence only, never the address. */
+    id: string;
+    window: number;
+    pane: number;
+    command: string;
+    active: boolean;
+}
+/** The tmux surface the steer needs, injectable so tests never touch a live pane. */
+export interface TmuxLike {
+    listPanes(session: string): PaneInfo[];
+    capture(target: string): string;
+    sendLiteral(target: string, text: string): void;
+    sendEnter(target: string): void;
+}
+/** Commands that mark a pane as an agent seat a steer may land in. */
+export declare const AGENT_COMMANDS: string[];
+/** Signs a seat is mid-turn; typed text would queue behind its work. */
+export declare const BUSY_PATTERNS: RegExp[];
+/** The production adapter. All tmux addressing is by exact session and window.pane. */
+export declare function tmuxAdapter(exec?: typeof execFileSync): TmuxLike;
+export declare function steeringGrantOf(run: ConnectorRecord): SteeringGrant | null;
+export type GrantCheck = "ok" | "no_grant" | "expired_grant" | "duplicate";
+/** Whether a grant covers one more steer. `priorAttempts` counts the steers already run under it. */
+export declare function checkGrant(grant: SteeringGrant | null, priorAttempts: number, now?: Date): GrantCheck;
+/** Steers already run under a grant: decided (or grant-covered) steer records that cite it. */
+export declare function steerAttempts(records: ConnectorRecord[], grantId: string): number;
+export declare function isBusy(capture: string, patterns?: RegExp[]): boolean;
+export interface SteerDeps {
+    tmux: TmuxLike;
+    stateDir: string;
+    now?: () => Date;
+    settleMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    agentCommands?: string[];
+}
+export interface SteerResult {
+    status: SteerStatus;
+    message: string;
+    target?: string;
+    artifact?: {
+        file: string;
+        sha256: string;
+    };
+}
+/** The artifact as last written, when a caller asks again with the same idempotency key. */
+export declare function readSteerArtifact(stateDir: string, recordId: string): Record<string, unknown> | null;
+/**
+ * Run one steer under its grant. The record is the session_steer_request; the
+ * grant record is the approved run the steer belongs to. A returned status
+ * other than `accepted`/`submitted` means nothing was typed.
+ */
+export declare function steerSession(deps: SteerDeps, args: {
+    record: ConnectorRecord;
+    grantRecord: ConnectorRecord;
+    priorAttempts: number;
+    authorized?: boolean;
+}): Promise<SteerResult>;

package/dist/steer.js

@@ -0,0 +1,229 @@
+/**
+ * Approval-aware session steering (jgwill/Miadi#893, Phase 1B): one authorized
+ * follow-up to one existing live agent, never raw tmux handed to a model.
+ *
+ * The rules this file keeps:
+ * - The target is the pane the mission is bound to — the pane the grant names,
+ *   else the session's first pane (lowest window, lowest pane, jgwill/Miadi#725).
+ *   The active pane plays no part.
+ * - peek → scoped act → re-peek (jgwill/Miadi#345): visible pasted text is not
+ *   acceptance; acceptance is the pane recaptured and the agent seen
+ *   processing, with the instruction scrolled out of the input line.
+ * - Every attempt leaves a durable artifact: the instruction, its sha256, the
+ *   grant it ran under, the target, the timestamps and both captures.
+ * - Pane content is evidence, never instruction: nothing an agent printed is
+ *   parsed as a directive.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const STEER_STATUSES = [
+    "prepared",
+    "submitted",
+    "accepted",
+    "busy",
+    "blocked",
+    "wrong_pane",
+    "stale_binding",
+    "expired_grant",
+    "duplicate",
+];
+/** Commands that mark a pane as an agent seat a steer may land in. */
+export const AGENT_COMMANDS = ["claude", "codex", "copilot", "pi", "gemini", "node"];
+/** Signs a seat is mid-turn; typed text would queue behind its work. */
+export const BUSY_PATTERNS = [/esc (to )?interrupt/i, /[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/, /\bWorking\b/, /\bThinking\b/];
+/** The production adapter. All tmux addressing is by exact session and window.pane. */
+export function tmuxAdapter(exec = execFileSync) {
+    const tmux = (args) => exec("tmux", args, { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
+    return {
+        listPanes(session) {
+            const out = tmux(["list-panes", "-s", "-t", session, "-F", "#{pane_id}\t#{window_index}\t#{pane_index}\t#{pane_current_command}\t#{pane_active}"]);
+            return out
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => {
+                const [id, w, p, command, active] = line.split("\t");
+                return { id, window: Number(w), pane: Number(p), command, active: active === "1" };
+            })
+                .sort((a, b) => a.window - b.window || a.pane - b.pane);
+        },
+        capture(target) {
+            return tmux(["capture-pane", "-p", "-t", target]);
+        },
+        // -l: the text is literal; no tmux key names in an instruction are interpreted.
+        sendLiteral(target, text) {
+            tmux(["send-keys", "-t", target, "-l", "--", text]);
+        },
+        sendEnter(target) {
+            tmux(["send-keys", "-t", target, "Enter"]);
+        },
+    };
+}
+export function steeringGrantOf(run) {
+    const g = run.body.steering;
+    if (!g || typeof g !== "object")
+        return null;
+    const grant = g;
+    return {
+        ...(typeof grant.max_attempts === "number" ? { max_attempts: grant.max_attempts } : {}),
+        ...(typeof grant.expires_at === "string" ? { expires_at: grant.expires_at } : {}),
+        ...(typeof grant.pane === "string" ? { pane: grant.pane } : {}),
+    };
+}
+/** Whether a grant covers one more steer. `priorAttempts` counts the steers already run under it. */
+export function checkGrant(grant, priorAttempts, now = new Date()) {
+    if (!grant)
+        return "no_grant";
+    if (grant.expires_at && !Number.isNaN(Date.parse(grant.expires_at)) && Date.parse(grant.expires_at) <= now.getTime())
+        return "expired_grant";
+    if ((grant.max_attempts ?? 0) <= priorAttempts)
+        return "duplicate";
+    return "ok";
+}
+/** Steers already run under a grant: decided (or grant-covered) steer records that cite it. */
+export function steerAttempts(records, grantId) {
+    return records.filter((r) => r.kind === "session_steer_request" &&
+        r.refs.includes(grantId) &&
+        (r.approval_state === "approved" || r.approval_state === "not_required") &&
+        r.completion_receipt !== undefined).length;
+}
+const targetName = (session, pane) => `${session}:${pane.window}.${pane.pane}`;
+export function isBusy(capture, patterns = BUSY_PATTERNS) {
+    const tail = capture.split("\n").slice(-25).join("\n");
+    return patterns.some((p) => p.test(tail));
+}
+function artifactPath(stateDir, recordId) {
+    return join(stateDir, "steers", `${recordId.replace(/[^\w-]/g, "-")}.json`);
+}
+function persistArtifact(stateDir, recordId, artifact) {
+    const file = artifactPath(stateDir, recordId);
+    mkdirSync(join(stateDir, "steers"), { recursive: true, mode: 0o700 });
+    const sha256 = createHash("sha256").update(JSON.stringify(artifact.instruction)).digest("hex");
+    writeFileSync(file, JSON.stringify({ ...artifact, instruction_sha256: sha256 }, null, 2) + "\n", { mode: 0o600 });
+    return { file, sha256 };
+}
+/** The artifact as last written, when a caller asks again with the same idempotency key. */
+export function readSteerArtifact(stateDir, recordId) {
+    const file = artifactPath(stateDir, recordId);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const CAPTURE_LINES = 40;
+/**
+ * Run one steer under its grant. The record is the session_steer_request; the
+ * grant record is the approved run the steer belongs to. A returned status
+ * other than `accepted`/`submitted` means nothing was typed.
+ */
+export async function steerSession(deps, args) {
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const agentCommands = deps.agentCommands ?? AGENT_COMMANDS;
+    const { record, grantRecord } = args;
+    const body = record.body;
+    const grant = steeringGrantOf(grantRecord);
+    const instruction = String(body.instruction ?? "");
+    const grantSession = String(grantRecord.body.session ?? "") || undefined;
+    const session = body.session ?? grantSession;
+    const finish = (status, message, extra = {}, target) => {
+        const artifact = persistArtifact(deps.stateDir, record.id, {
+            record: record.id,
+            grant: grantRecord.id,
+            instruction,
+            session,
+            status,
+            message,
+            at: now().toISOString(),
+            ...extra,
+        });
+        return { status, message, ...(target ? { target } : {}), artifact };
+    };
+    if (!instruction.trim())
+        return { status: "blocked", message: "The steer carries no instruction." };
+    if (!session)
+        return finish("stale_binding", "Neither the steer nor its grant names a session; a steer never targets whichever pane is active.");
+    if (body.session && grantSession && body.session !== grantSession) {
+        return finish("stale_binding", `The steer names session "${body.session}" but its grant covers "${grantSession}".`);
+    }
+    // A person's approval of this exact steer covers one attempt even when the
+    // run's grant is exhausted; without it, the grant's own limits decide.
+    if (!args.authorized) {
+        const check = checkGrant(grant, args.priorAttempts, now());
+        if (check === "expired_grant")
+            return finish("expired_grant", `The steering grant expired at ${grant?.expires_at}.`, {}, session);
+        if (check === "duplicate") {
+            return finish("duplicate", `The grant's ${grant?.max_attempts ?? 0} steer(s) are used; a new scoped human decision is needed for more.`, {}, session);
+        }
+    }
+    let panes;
+    try {
+        panes = deps.tmux.listPanes(session);
+    }
+    catch {
+        return finish("stale_binding", `No tmux session named "${session}"; the binding is stale.`, {}, session);
+    }
+    if (!panes.length)
+        return finish("stale_binding", `Session "${session}" has no panes; the binding is stale.`, {}, session);
+    const wanted = body.pane ?? grant?.pane;
+    let pane;
+    if (wanted) {
+        const [w, p] = wanted.split(".").map(Number);
+        pane = panes.find((x) => x.window === w && x.pane === p);
+        if (!pane)
+            return finish("stale_binding", `Pane ${wanted} of "${session}" is gone (stale or renumbered); nothing was typed anywhere else.`, {}, session);
+    }
+    else {
+        pane = panes[0]; // listPanes is sorted: lowest window, lowest pane (jgwill/Miadi#725).
+    }
+    const target = targetName(session, pane);
+    if (!agentCommands.includes(pane.command)) {
+        return finish("wrong_pane", `Pane ${target} runs "${pane.command}", not an agent; nothing was typed.`, { pane: { ...pane } }, target);
+    }
+    let before;
+    try {
+        before = deps.tmux.capture(target);
+    }
+    catch (error) {
+        return finish("blocked", `The pane could not be read (${error instanceof Error ? error.message : String(error)}); nothing was typed.`, {}, target);
+    }
+    if (isBusy(before)) {
+        return finish("busy", `The agent in ${target} is mid-turn; the steer was not typed. Ask again when it is idle.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
+    }
+    deps.tmux.sendLiteral(target, instruction);
+    deps.tmux.sendEnter(target);
+    await sleep(deps.settleMs ?? 4000);
+    let after;
+    try {
+        after = deps.tmux.capture(target);
+    }
+    catch (error) {
+        return finish("submitted", `Typed into ${target}, but the re-peek failed (${error instanceof Error ? error.message : String(error)}); acceptance is unconfirmed.`, { peek: before.split("\n").slice(-CAPTURE_LINES) }, target);
+    }
+    let current;
+    try {
+        current = deps.tmux.listPanes(session).find((x) => x.window === pane.window && x.pane === pane.pane);
+    }
+    catch {
+        current = undefined;
+    }
+    const tail = after.split("\n").slice(-CAPTURE_LINES);
+    const evidence = { peek: before.split("\n").slice(-CAPTURE_LINES), re_peek: tail };
+    if (!current || current.command !== pane.command) {
+        return finish("stale_binding", `Typed into ${target}, but the pane's command changed while sending; the seat may have exited. Acceptance is unconfirmed.`, evidence, target);
+    }
+    const firstLine = instruction.split("\n")[0].slice(0, 80);
+    const echoed = firstLine.length > 0 && after.includes(firstLine);
+    if (isBusy(after) && echoed) {
+        return finish("accepted", `The agent in ${target} is processing the steer.`, evidence, target);
+    }
+    const stillAtPrompt = tail.some((l) => firstLine.length > 0 && l.includes(firstLine)) && !isBusy(after);
+    return finish("submitted", stillAtPrompt
+        ? `The instruction sits at the prompt in ${target}; it was typed but the agent has not accepted it.`
+        : `Typed into ${target}; the pane shows no processing sign, so acceptance is unconfirmed.`, evidence, target);
+}

package/dist/tools.d.ts

@@ -7,6 +7,8 @@ import type { OAuthState } from "./oauth.js";
 import { type ConnectorRecord } from "./records.js";
 import { type ApprovalDeps } from "./approve.js";
 import { type DecisionTokens } from "./decisions.js";
+import { type DiscoveryProbe } from "./providers.js";
+import { type TmuxLike } from "./steer.js";
 export interface ToolContext {
     config: ConnectorConfig;
     miadi: MiadiClient;
@@ -18,6 +20,13 @@ export interface ToolContext {
     /** What the in-chat approval card needs to run a decided request. */
     approval?: ApprovalDeps;
     decisionTokens?: DecisionTokens;
+    /** The steering surface (jgwill/Miadi#893); absent, steering answers unavailable. */
+    tmux?: TmuxLike;
+    tmuxSessions?: () => string[];
+    /** Provider discovery probes; tests inject fakes (jgwill/Miadi#893). */
+    providersProbe?: DiscoveryProbe;
+    /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
+    steerSettleMs?: number;
 }
 export declare function registerTools(server: McpServer, ctx: ToolContext): void;
 /** What get_capabilities reports for each tool. */

package/dist/tools.js

@@ -18,6 +18,9 @@ import { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, current
 import { VERSION } from "./version.js";
 import { AlreadyDecided, DECISIONS, KIND_LABELS, consequenceOf, decide, isApprovable, readQueueState, requestProjection } from "./approve.js";
 import { DECISIONS_CARD_HTML, DECISIONS_CARD_URI, DECISION_TOKENS_META } from "./decisions.js";
+import { discoverProviders, resolveProvider, routerPreflight, PROVIDERS } from "./providers.js";
+import { missionStatus } from "./mission-status.js";
+import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from "./steer.js";
 import { join } from "node:path";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
@@ -468,6 +471,72 @@ export function registerTools(server, ctx) {
                 : {}),
         };
     }));
+    server.registerTool("mission_status", {
+        title: "Where a mission stands",
+        description: "One mission, joined and verified: its source request and decision, the sessions bound to it (live or not), its issues and PRs, what is approved, queued, delivered, running, merged, released or closed — each by its evidence, never inferred from an idle pane — and the next authorized action. Operator details need Miadi's write tier. jgwill/Miadi#893.",
+        inputSchema: {
+            ref: z
+                .string()
+                .min(1)
+                .describe("run_request:<id>, work_proposal:<id>, another record id, session:<uuid>, or owner/repo#n the mission cites."),
+        },
+        annotations: READ,
+    }, wrap(async ({ ref }, extra) => {
+        const { person } = who(extra);
+        const writeTier = person.api_tier === "write";
+        return missionStatus(ref.trim(), records(), {
+            projectOf: (r) => requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
+            queueOf: (r) => (r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined),
+            tmuxSessions: writeTier ? (ctx.tmuxSessions ?? (() => [])) : undefined,
+            paneBusy: writeTier && ctx.tmux
+                ? (session) => {
+                    try {
+                        const pane = ctx.tmux.listPanes(session)[0];
+                        if (!pane)
+                            return "unknown";
+                        return isBusy(ctx.tmux.capture(`${session}:${pane.window}.${pane.pane}`)) ? "busy" : "idle";
+                    }
+                    catch {
+                        return "unknown";
+                    }
+                }
+                : undefined,
+            sessionOf: writeTier ? (id) => miadi.get(person.token, `/api/session/${encodeURIComponent(id)}`) : undefined,
+            issueOf: async (owner, repo, n) => {
+                const f = ctx.approval?.fetchImpl ?? fetch;
+                const headers = {
+                    accept: "application/vnd.github+json",
+                    ...(process.env.GITHUB_TOKEN ? { authorization: "Bearer " + process.env.GITHUB_TOKEN } : {}),
+                };
+                const pr = await f(`https://api.github.com/repos/${owner}/${repo}/pulls/${n}`, { headers, signal: AbortSignal.timeout(15_000) });
+                if (pr.ok) {
+                    const p = await pr.json();
+                    return { state: p.state, title: p.title, merged: Boolean(p.merged_at) };
+                }
+                const res = await f(`https://api.github.com/repos/${owner}/${repo}/issues/${n}`, { headers, signal: AbortSignal.timeout(15_000) });
+                if (!res.ok)
+                    return { state: res.status === 404 ? "not_found_or_private" : `github_${res.status}` };
+                const i = await res.json();
+                return { state: i.state, title: i.title };
+            },
+        });
+    }));
+    server.registerTool("provider_capabilities", {
+        title: "Which agent providers this host can launch",
+        description: "The provider reality of the connector host (jgwill/Miadi#893): which agent CLIs are installed, their versions, whether sign-in evidence exists, the preference order (Codex, Pi, Copilot; Claude Code only on explicit request), and the read-only Jev routing preflight. No token is read or shown. Needs Miadi's write tier: this is host truth.",
+        inputSchema: {},
+        annotations: READ,
+    }, wrap(async (_args, extra) => {
+        const { person } = who(extra);
+        requireTier(person, "write");
+        return {
+            preference_order: PROVIDERS.map((p) => p.id),
+            explicit_only: PROVIDERS.filter((p) => !p.selectable_by_default).map((p) => p.id),
+            providers: discoverProviders(ctx.providersProbe),
+            router: await routerPreflight(process.env, ctx.approval?.fetchImpl ?? fetch),
+            note: "A provider name in a task's text selects nothing; request_authorized_run's provider field is verified against this list, and an unavailable provider leaves the mission unstarted.",
+        };
+    }));
     // search / fetch: the pair ChatGPT uses for connectors in search and deep research.
     server.registerTool("search", {
         title: "Search Miadi",
@@ -815,12 +884,31 @@ export function registerTools(server, ctx) {
             refs,
             session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("An existing tmux session to hand it to, or a name for a new one."),
             cwd: z.string().max(300).optional().describe("Working folder for a new session (default the Miadi checkout)."),
+            provider: z
+                .enum(["codex", "pi", "copilot", "claude"])
+                .optional()
+                .describe("The provider the run should launch with, verified installed on the connector host. Claude Code runs only when named explicitly. Unknown or unavailable leaves the mission unstarted."),
+            steering: z
+                .object({
+                max_attempts: z.number().int().min(1).max(20).describe("How many authorized follow-up steers this approval covers."),
+                expires_at: z.string().optional().describe("ISO time after which no steer runs under this grant."),
+                pane: z.string().regex(/^\d+\.\d+$/).optional().describe("The pane the seat lives in (window.pane); default the session's first pane."),
+            })
+                .optional()
+                .describe("The steering grant the approver covers with this run: bounded follow-ups to the same session through request_session_steer."),
             ...base,
         },
         annotations: WRITE,
     }, wrap(async (a, extra) => {
         const { person, auth } = who(extra);
         requireContribute(auth);
+        const found = discoverProviders(ctx.providersProbe);
+        const resolution = resolveProvider(a.provider, found);
+        if (resolution.state === "provider_unknown")
+            throw new ToolRefusal("invalid_request", resolution.message, { available: resolution.available });
+        if (resolution.state !== "ok") {
+            return { state: resolution.state, message: resolution.message, available: resolution.available, note: "Nothing was recorded or queued; the mission is unstarted." };
+        }
         const r = append("run_request", person, auth, {
             circle: a.circle,
             refs: a.refs,
@@ -829,9 +917,100 @@ export function registerTools(server, ctx) {
             idempotency_key: a.idempotency_key,
             approval_state: "awaiting_approval",
             state: "pending",
-            body: { task: a.task, session: a.session, cwd: a.cwd },
+            body: {
+                task: a.task,
+                session: a.session,
+                cwd: a.cwd,
+                provider: a.provider,
+                resolved_provider: resolution.provider.id,
+                ...(a.steering ? { steering: a.steering } : {}),
+            },
         });
-        return { ...r, approval_url: approvalUrl(r.id) };
+        return {
+            ...r,
+            provider: { requested: a.provider ?? null, resolved: resolution.provider.id, explicit: resolution.explicit, version: resolution.provider.version },
+            approval_url: approvalUrl(r.id),
+        };
+    }));
+    server.registerTool("request_session_steer", {
+        title: "Send one authorized follow-up to a running agent",
+        description: "Steer one existing live agent session within an approved run's steering grant (jgwill/Miadi#893): the exact instruction is typed into the mission's bound pane — never whichever pane is active — after a peek, and a re-peek verifies the agent accepted it. When the approved run carries no steering grant covering this, the steer waits for one explicit scoped human decision on the returned approval_url. Every attempt leaves a durable artifact with its hash and both captures.",
+        inputSchema: {
+            run_request: z.string().min(1).describe("The approved run_request or work_proposal whose steering grant covers this steer."),
+            instruction: z.string().min(1).max(4000).describe("The exact instruction typed into the session. It is material within the approved mission's scope, not new authority."),
+            session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("The session to steer; must be the one the grant binds."),
+            pane: z.string().regex(/^\d+\.\d+$/).optional().describe("The pane (window.pane); default the grant's pane, else the session's first pane. The active pane is never used."),
+            refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        requireTier(person, "write");
+        if (!ctx.tmux)
+            throw new ToolRefusal("unavailable", "The connector host has no steering surface; the steer is unstarted.");
+        const grantRecord = all().find((r) => r.id === a.run_request);
+        if (!grantRecord || (grantRecord.kind !== "run_request" && grantRecord.kind !== "work_proposal")) {
+            throw new ToolRefusal("invalid_ref", "Give the id of the approved run_request or work_proposal this steer belongs to.");
+        }
+        if (grantRecord.approval_state !== "approved") {
+            throw new ToolRefusal("not_approved", `${grantRecord.id} is ${grantRecord.approval_state ?? "not approved"}; a steer needs an approved run's grant or its own human decision.`);
+        }
+        const grant = steeringGrantOf(grantRecord);
+        const priorAttempts = steerAttempts(all(), grantRecord.id);
+        const covered = checkGrant(grant, priorAttempts) === "ok";
+        const body = {
+            instruction: a.instruction,
+            session: a.session ?? grantRecord.body.session,
+            pane: a.pane ?? grant?.pane,
+        };
+        const fields = {
+            circle: grantRecord.circle,
+            refs: [grantRecord.id, ...a.refs],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body,
+        };
+        if (!covered) {
+            // One explicit scoped human decision (jgwill/Miadi#893): the record waits
+            // on the approval page; approving it runs exactly this instruction once.
+            const r = append("session_steer_request", person, auth, { ...fields, approval_state: "awaiting_approval", state: "pending" });
+            return {
+                ...r,
+                approval_url: approvalUrl(r.id),
+                state: "awaiting_approval",
+                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts),
+                message: "The approved run's steering grant does not cover this steer; a person's decision is requested, once, for exactly this instruction.",
+            };
+        }
+        const r = append("session_steer_request", person, auth, { ...fields, approval_state: "not_required" });
+        const result = await steerSession({ tmux: ctx.tmux, stateDir: config.stateDir, ...(ctx.steerSettleMs !== undefined ? { settleMs: ctx.steerSettleMs } : {}) }, { record: r, grantRecord, priorAttempts });
+        const delivered = result.status === "accepted" || result.status === "submitted";
+        ledger.append({
+            id: newRecordId(r.kind),
+            kind: r.kind,
+            created_at: new Date().toISOString(),
+            actor: r.actor,
+            refs: r.refs,
+            evidence_refs: [],
+            supersedes: r.id,
+            approval_state: "not_required",
+            state: delivered ? "completed" : "blocked",
+            completion_receipt: {
+                decision: "covered_by_grant",
+                decided_by: { person_id: person.id, name: person.name },
+                decided_at: new Date().toISOString(),
+                outcome: delivered ? result.status : "failed",
+                steer_status: result.status,
+                message: result.message,
+                ...(result.target ? { target: result.target } : {}),
+                ...(result.artifact ? { artifact: result.artifact } : {}),
+            },
+            body: r.body,
+        });
+        return records().find((x) => x.id === r.id) ?? r;
     }));
     server.registerTool("request_review_operation", {
         title: "Request a review operation",
@@ -1262,6 +1441,8 @@ export const TOOL_STATUS = {
     handoff_status: "live",
     list_records: "live",
     get_run_result: "live",
+    mission_status: "live (operator details need the Miadi write tier)",
+    provider_capabilities: "live, Miadi write tier",
     search: "live",
     fetch: "live",
     append_observation: "live, contribute",
@@ -1275,7 +1456,8 @@ export const TOOL_STATUS = {
     propose_work: "live, contribute, needs_approval (approving starts the work as a factory run)",
     prepare_calendar_event: "live, contribute (draft and .ics only)",
     propose_session_completion: "live, contribute, needs_approval (decision recorded, nothing closed)",
-    request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved)",
+    request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved; may name a verified provider and a bounded steering grant)",
+    request_session_steer: "live, contribute, write tier (runs inside an approved run's steering grant, else one scoped human decision)",
     request_review_operation: "live, contribute, needs_approval",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.9";
+export declare const VERSION = "0.1.10";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.9";
+export const VERSION = "0.1.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "The Miadi connector: one remote MCP service through which a person signed in with their Miadi person token, from ChatGPT or any MCP client, reads sessions, reviews, episodes and circles and records observations, inquiries, handoffs and proposals with their name on each record.",
   "license": "MIT",
   "author": "Miadi",