@miadi/connector 0.1.19 → 0.1.21

package/dist/runtime-steer.js

@@ -0,0 +1,543 @@
+/**
+ * The connector's half of the terminal-agent steering contract (jgwill/Miadi#930).
+ *
+ * The connector admits a correction and hands it to the bound session's own inbox. It never
+ * watches tools, never waits for idle and never decides when the model reads it: that is the
+ * runtime's. For Claude Code the runtime half is the hook adapter in the kit plugin
+ * miadi-session-observability (hooks/steering_inbox.mjs), which holds the file contract:
+ * <root>/<session_id>/{adapter.json,pending,claimed,expired,withdrawn,rejected,revoked,receipts.jsonl}.
+ *
+ * Other providers have no adapter here, so they answer unsupported with the exact reason. Claude
+ * Code's hook semantics are never assumed of Copilot, Pi or Codex.
+ *
+ * Delivery is read from its own evidence: the connector's write, the runtime hook's receipt and
+ * the transcript record Claude Code itself wrote. A pane echo or a spinner is none of these.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { factoryDir } from "./queue-state.js";
+export const STEER_PROTOCOL = 1;
+/** A correction no continuation consumed in a day is stale: the work has moved on. A grant's own expiry comes sooner when it has one. */
+export const ENVELOPE_TTL_MS = 24 * 60 * 60 * 1000;
+export const CLAUDE_ADAPTER = "miadi-session-observability 0.1.34 or later";
+const INBOX_DIRS = ["pending", "claimed", "expired", "withdrawn", "rejected"];
+/** How much transcript one read scans after the steer was queued. */
+const MAX_TRANSCRIPT_SCAN = 32 * 1024 * 1024;
+const MAX_NEXT_ACTIONS = 5;
+export const DELIVERY_STATES = [
+    "authorized",
+    "forwarded_to_runtime",
+    "queued_at_runtime",
+    "delivered_to_agent_context",
+    "acknowledged",
+    "behavior_adjusted",
+    "unsupported",
+    "expired",
+    "blocked",
+    "unknown",
+];
+export function steeringRoot(env = process.env) {
+    return env.MIADI_STEERING_DIR || join(factoryDir(env), "steering");
+}
+export function defaultRuntime(env = process.env) {
+    return { root: steeringRoot(env), claudeDir: env.CLAUDE_CONFIG_DIR || join(env.HOME || homedir(), ".claude") };
+}
+const safe = (id) => id.replace(/[^\w-]/g, "-");
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const statOrNull = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+};
+const readJson = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+};
+/** The token the agent names back in its own text: the same rule as the adapter's ackToken. */
+export const ackToken = (steerId) => `steer ${safe(steerId).replace(/^session_steer_request-/, "").slice(0, 8)}`;
+/** Claude Code's own record of a running session, `<claudeDir>/sessions/<pid>.json`, if its process lives. */
+export function readClaudeSession(deps, sessionId) {
+    const dir = join(deps.claudeDir, "sessions");
+    const alive = deps.isAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => /^\d+\.json$/.test(n));
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        const r = readJson(join(dir, name));
+        if (r?.sessionId === sessionId && typeof r.pid === "number" && alive(r.pid))
+            return r;
+    }
+    return null;
+}
+/**
+ * Mission → session → runtime, from what each one signed: the runner's receipt names the session,
+ * Claude Code's registry says it runs and in which pane, and the adapter's file says this session
+ * loaded its hooks. The inbox belongs to this Unix account alone or it is not used.
+ */
+export function resolveRuntime(deps, binding) {
+    const { session_id, pane_id, provider } = binding;
+    if (provider && provider !== "claude") {
+        return { route: "none", code: "unsupported", reason: `No steering adapter is installed for provider "${provider}". Claude Code's hooks are not assumed of it.` };
+    }
+    if (!session_id)
+        return { route: "none", code: "unsupported", reason: "The mission's binding names no session id, so no exact session's inbox can be addressed." };
+    const record = readClaudeSession(deps, session_id);
+    if (!record)
+        return { route: "none", code: "stale_binding", reason: `Claude Code session ${session_id} is not running on this host.` };
+    const seatPane = record.tmux?.match(/%\d+$/)?.[0];
+    if (pane_id && seatPane && seatPane !== pane_id) {
+        return { route: "none", code: "wrong_pane", reason: `Claude Code session ${session_id} is in pane ${seatPane}, not ${pane_id}, the pane its mission is bound to.` };
+    }
+    const dir = join(deps.root, safe(session_id));
+    const st = statOrNull(dir);
+    const adapter = st?.isDirectory() && st.uid === process.getuid?.() && (st.mode & 0o022) === 0 ? readJson(join(dir, "adapter.json")) : null;
+    if (!adapter || adapter.protocol !== STEER_PROTOCOL || adapter.session_id !== session_id) {
+        return {
+            route: "none",
+            code: "unsupported",
+            reason: `Claude Code session ${session_id} has no steering adapter loaded. Hooks load at session start, so a session started before ${CLAUDE_ADAPTER} cannot receive a correction mid-turn.`,
+        };
+    }
+    return { route: "claude_hook_inbox", session_id, seat: record.status ?? "unknown", ...(typeof adapter.transcript_path === "string" ? { transcript_path: adapter.transcript_path } : {}) };
+}
+function findEnvelope(root, sessionId, steer) {
+    const dir = join(root, safe(sessionId));
+    const suffix = `-${safe(steer)}.json`;
+    for (const state of INBOX_DIRS) {
+        let names;
+        try {
+            names = readdirSync(join(dir, state));
+        }
+        catch {
+            continue;
+        }
+        const name = names.find((n) => n.endsWith(suffix));
+        if (name)
+            return { state, file: join(dir, state, name), envelope: readJson(join(dir, state, name)) };
+    }
+    return null;
+}
+/** The steer already on its way with these same words under this grant: one correction, one delivery. */
+export function sameInstructionInFlight(deps, sessionId, grant, instruction) {
+    const dir = join(deps.root, safe(sessionId));
+    const hash = sha256(instruction);
+    for (const state of ["pending", "claimed"]) {
+        let names;
+        try {
+            names = readdirSync(join(dir, state));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const e = readJson(join(dir, state, name));
+            if (e?.grant === grant && e.instruction_sha256 === hash)
+                return e.steer;
+        }
+    }
+    return null;
+}
+/**
+ * Put one correction in the session's inbox, durably: fsync, then one rename into pending/, so the
+ * adapter never reads half a file. The steer's id keeps it single across a retry or a connector restart.
+ */
+export function enqueueSteer(deps, args) {
+    const known = findEnvelope(deps.root, args.session_id, args.steer);
+    if (known?.envelope)
+        return { already: true, file: known.file, envelope: known.envelope };
+    const now = args.now ?? new Date();
+    const dir = join(deps.root, safe(args.session_id));
+    const pending = join(dir, "pending");
+    mkdirSync(pending, { recursive: true, mode: 0o700 });
+    const ttl = now.getTime() + ENVELOPE_TTL_MS;
+    const grantEnd = args.grant_expires_at ? Date.parse(args.grant_expires_at) : NaN;
+    const envelope = {
+        protocol: STEER_PROTOCOL,
+        steer: args.steer,
+        grant: args.grant,
+        session_id: args.session_id,
+        instruction: args.instruction,
+        instruction_sha256: sha256(args.instruction),
+        from: args.from,
+        queued_at: now.toISOString(),
+        expires_at: new Date(Number.isNaN(grantEnd) ? ttl : Math.min(ttl, grantEnd)).toISOString(),
+        ...(args.decided ? { decided: true } : {}),
+        ...(args.transcript_path ? { transcript_path: args.transcript_path, transcript_offset: transcriptSize(args.transcript_path) } : {}),
+    };
+    // Ordered by name: never before an envelope already waiting.
+    const last = readdirSync(pending).filter((n) => n.endsWith(".json")).sort().at(-1);
+    const order = Math.max(now.getTime(), last ? Number(last.split("-")[0]) + 1 : 0);
+    const name = `${String(order).padStart(15, "0")}-${safe(args.steer)}.json`;
+    const tmp = join(dir, `.tmp-${safe(args.steer)}`);
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeSync(fd, JSON.stringify(envelope));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, join(pending, name));
+    return { already: false, file: join(pending, name), envelope };
+}
+function transcriptSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Revoke a grant or one steer for this session. The marker stops whatever the adapter would consume
+ * next, and what is still pending moves out at once. A rename decides any race with the adapter,
+ * so the answer is exact: revoked here, or already consumed.
+ */
+export function revokeInInbox(deps, sessionId, target, reason) {
+    const dir = join(deps.root, safe(sessionId));
+    const out = { revoked: [], already_consumed: [] };
+    if (!statOrNull(dir))
+        return out;
+    mkdirSync(join(dir, "revoked"), { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, "revoked", safe(target.steer ?? target.grant)), `${JSON.stringify({ reason, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+    const pending = join(dir, "pending");
+    mkdirSync(join(dir, "withdrawn"), { recursive: true, mode: 0o700 });
+    let names = [];
+    try {
+        names = readdirSync(pending);
+    }
+    catch {
+        // Nothing queued.
+    }
+    for (const name of names) {
+        const e = readJson(join(pending, name));
+        if (!e || e.grant !== target.grant || (target.steer && e.steer !== target.steer))
+            continue;
+        try {
+            renameSync(join(pending, name), join(dir, "withdrawn", name));
+            appendFileSync(join(dir, "receipts.jsonl"), `${JSON.stringify({ at: new Date().toISOString(), source: "connector", steer: e.steer, state: "revoked", reason })}\n`, { mode: 0o600 });
+            out.revoked.push(e.steer);
+        }
+        catch {
+            out.already_consumed.push(e.steer);
+        }
+    }
+    // What the agent's runtime already took cannot be stopped, and the answer says which.
+    let taken = [];
+    try {
+        taken = readdirSync(join(dir, "claimed"));
+    }
+    catch {
+        // Nothing consumed yet.
+    }
+    for (const name of taken) {
+        const e = readJson(join(dir, "claimed", name));
+        if (!e || e.grant !== target.grant || (target.steer && e.steer !== target.steer) || out.already_consumed.includes(e.steer))
+            continue;
+        out.already_consumed.push(e.steer);
+    }
+    return out;
+}
+function readTail(path, offset) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = statSync(path).size;
+        const start = Math.max(Math.min(offset, size), size - MAX_TRANSCRIPT_SCAN);
+        const buffer = Buffer.alloc(size - start);
+        readSync(fd, buffer, 0, buffer.length, start);
+        return buffer.toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const textOf = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((b) => (b && typeof b === "object" && b.type === "text" ? String(b.text ?? "") : "")).join("\n");
+};
+/**
+ * What Claude Code itself recorded about this steer. Only an attachment naming the steer's id shows
+ * it entered the model's context, and only the agent's own later text can acknowledge it. Tool
+ * results and the agent's quotes of the id do not count as delivery.
+ */
+export function readTranscriptEvidence(path, offset, steer) {
+    const out = { next_actions: [], actions_seen: 0, raw_inputs: [] };
+    const text = readTail(path, offset);
+    if (text === null)
+        return out;
+    const token = `${ackToken(steer)} received`.toLowerCase();
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        if (!out.delivered && !line.includes(steer))
+            continue;
+        let d;
+        try {
+            d = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!out.delivered) {
+            // Claude Code writes hook_success with the hook's stdout first: that shows the hook exited. These show it entered the context.
+            const admitted = d.type === "attachment" && ["hook_additional_context", "hook_blocking_error", "queued_command"].includes(d.attachment?.type);
+            // A woken model reads it as a meta user message, never a tool result that quotes the id.
+            const wakeMessage = d.type === "user" && d.isMeta === true && textOf(d.message?.content).includes(steer);
+            if (!admitted && !wakeMessage)
+                continue;
+            out.delivered = {
+                at: d.timestamp,
+                attachment: admitted ? d.attachment.type : "meta_user_message",
+                hook_event: admitted ? (d.attachment.hookEvent ?? "Stop") : "Stop",
+                ...(admitted && d.attachment.toolUseID ? { tool_use_id: d.attachment.toolUseID } : {}),
+            };
+            continue;
+        }
+        if (d.type !== "assistant")
+            continue;
+        const content = d.message?.content;
+        const said = textOf(content);
+        if (!out.acknowledged && said.toLowerCase().includes(token))
+            out.acknowledged = { at: d.timestamp, text: said.slice(0, 500) };
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type !== "tool_use")
+                continue;
+            out.actions_seen++;
+            const input = JSON.stringify(block.input ?? {});
+            if (out.next_actions.length < MAX_NEXT_ACTIONS) {
+                out.next_actions.push({ at: d.timestamp, tool: String(block.name), input: input.slice(0, 200) });
+                out.raw_inputs.push(input);
+            }
+        }
+    }
+    return out;
+}
+/** Whether a prompt typed into the bound pane reached the session: Claude Code's own user or queued-prompt record. A pane echo proves nothing. */
+export function typedLineInTranscript(path, offset, instruction) {
+    const text = readTail(path, offset);
+    if (text === null)
+        return null;
+    const firstLine = instruction.split("\n")[0].slice(0, 80);
+    if (!firstLine.trim())
+        return null;
+    const needle = JSON.stringify(firstLine).slice(1, -1);
+    for (const line of text.split("\n")) {
+        if (!line.includes(needle))
+            continue;
+        try {
+            const d = JSON.parse(line);
+            if (d.type === "attachment" && d.attachment?.type === "queued_command")
+                return { at: d.timestamp, record: "queued_command" };
+            // The person's prompt, never a tool's output that quotes the words.
+            if (d.type === "user" && textOf(d.message?.content).includes(firstLine))
+                return { at: d.timestamp, record: "user" };
+        }
+        catch {
+            // A partial last line: the next read has it whole.
+        }
+    }
+    return null;
+}
+/** Find a session's transcript when its adapter did not name it. */
+export function transcriptPathOf(deps, sessionId) {
+    const adapter = readJson(join(deps.root, safe(sessionId), "adapter.json"));
+    if (typeof adapter?.transcript_path === "string")
+        return adapter.transcript_path;
+    const projects = join(deps.claudeDir, "projects");
+    try {
+        for (const project of readdirSync(projects)) {
+            const file = join(projects, project, `${sessionId}.jsonl`);
+            if (existsSync(file))
+                return file;
+        }
+    }
+    catch {
+        // No projects folder: no transcript to read.
+    }
+    return undefined;
+}
+/**
+ * Where one steer stands, each state with its source and time, for request_session_steer,
+ * mission_status and get_run_result. It only reads, and it can be read at any time: ChatGPT
+ * disconnecting or the connector restarting changes nothing here.
+ */
+export function readSteerDelivery(deps, record, now = new Date()) {
+    const receipt = record.completion_receipt;
+    if (!receipt)
+        return null;
+    const binding = record.body.binding;
+    const route = String(receipt.route ?? (receipt.typed ? "tmux_exact_pane" : "none"));
+    const session_id = binding?.session_id;
+    const receipts = [];
+    const authorizedAt = receipt.decided_at;
+    receipts.push({ state: "authorized", at: authorizedAt, source: "connector", detail: { by: receipt.decided_by, decision: receipt.decision } });
+    const base = { route, ...(session_id ? { session_id } : {}) };
+    if (route === "tmux_exact_pane") {
+        receipts.push({ state: "seat_was_idle", at: authorizedAt, source: "connector", detail: { target: receipt.target } });
+        receipts.push({ state: "forwarded_to_runtime", at: authorizedAt, source: "connector", detail: { target: receipt.target, typed: receipt.typed } });
+        const path = session_id ? transcriptPathOf(deps, session_id) : undefined;
+        const landed = path ? typedLineInTranscript(path, Number(receipt.transcript_offset ?? 0), String(record.body.instruction ?? "")) : null;
+        if (landed) {
+            receipts.push({ state: "delivered_to_agent_context", at: landed.at, source: "claude_transcript", detail: { record: landed.record } });
+            return { ...base, state: "delivered_to_agent_context", receipts, note: "Claude Code recorded the prompt in the session's transcript." };
+        }
+        return { ...base, state: "unknown", receipts, note: "It was typed into the bound pane of an idle seat. No transcript record of it has been read, and a pane echo is not proof the model read it." };
+    }
+    if (route !== "claude_hook_inbox" || !session_id) {
+        const status = String(receipt.steer_status ?? "");
+        const state = status === "unsupported" ? "unsupported" : status === "expired_grant" ? "expired" : "blocked";
+        return { ...base, state, receipts, note: String(receipt.message ?? "Nothing was forwarded.") };
+    }
+    const found = findEnvelope(deps.root, session_id, record.id);
+    const forwardedAt = found?.envelope?.queued_at ?? authorizedAt;
+    receipts.push({ state: "forwarded_to_runtime", at: forwardedAt, source: "connector", detail: { route } });
+    if (!found)
+        return { ...base, state: "unknown", receipts, note: "The session's inbox no longer holds this steer, so where it went cannot be read." };
+    receipts.push({ state: "queued_at_runtime", at: forwardedAt, source: "runtime_inbox", detail: { file: found.file, expires_at: found.envelope?.expires_at } });
+    const hook = hookReceipts(deps.root, session_id, record.id);
+    for (const r of hook) {
+        if (r.state === "emitted") {
+            const { at, state: _state, source: _source, steer: _steer, ...detail } = r;
+            receipts.push({ state: "runtime_hook_emitted", at, source: "runtime_hook", detail });
+        }
+    }
+    const refused = hook.find((r) => r.state === "expired" || r.state === "revoked" || r.state === "blocked");
+    if (found.state === "pending") {
+        const expiresAt = found.envelope?.expires_at;
+        if (expiresAt && Date.parse(expiresAt) <= now.getTime()) {
+            receipts.push({ state: "expired", at: expiresAt, source: "connector_clock" });
+            return { ...base, state: "expired", receipts, note: "It expired in the inbox before any continuation consumed it. It will not reach the model." };
+        }
+        const seat = readClaudeSession(deps, session_id);
+        for (const r of hook.filter((x) => x.state === "woken"))
+            receipts.push({ state: "seat_woken", at: r.at, source: "factory_runner", detail: { pane: r.pane } });
+        if (!seat)
+            return { ...base, state: "queued_at_runtime", continuation: "session_not_running", receipts, note: `It waits in the inbox of a session that is not running. It reaches the model if that session resumes before ${expiresAt}, and otherwise expires.` };
+        if (seat.status === "idle")
+            return { ...base, state: "queued_at_runtime", continuation: "runner_wakes_idle_seat", receipts, note: "The seat went idle before a continuation carried it. The factory runner's next pass, within minutes, prompts the seat, and the correction arrives with that prompt. Nobody has to send it again." };
+        return { ...base, state: "queued_at_runtime", continuation: "next_tool_or_turn_end", receipts, note: "It waits in the session's inbox. The agent's next tool end, or the end of its turn, presents it. This does not yet show the model read it." };
+    }
+    if (found.state === "expired") {
+        receipts.push({ state: "expired", at: refused?.at, source: "runtime_hook", detail: { reason: refused?.reason } });
+        return { ...base, state: "expired", receipts, note: "It expired before a continuation consumed it. It never reached the model." };
+    }
+    if (found.state === "withdrawn" || found.state === "rejected") {
+        receipts.push({ state: "blocked", at: refused?.at, source: refused?.source === "connector" ? "connector" : "runtime_hook", detail: { reason: refused?.reason, moved_to: found.state } });
+        return { ...base, state: "blocked", receipts, note: `It never reached the model: ${refused?.reason ?? found.state}.` };
+    }
+    // Claimed: taken for delivery, exactly once, never again whatever happens next.
+    const path = found.envelope?.transcript_path;
+    const evidence = path ? readTranscriptEvidence(path, found.envelope?.transcript_offset ?? 0, record.id) : null;
+    if (!evidence?.delivered) {
+        const emitted = hook.some((r) => r.state === "emitted");
+        return {
+            ...base,
+            state: "unknown",
+            receipts,
+            note: emitted
+                ? "The runtime hook printed it, and the transcript does not show it entered the model's context yet."
+                : "The hook claimed it and left no receipt, so delivery is ambiguous. It is not sent again.",
+        };
+    }
+    receipts.push({ state: "delivered_to_agent_context", at: evidence.delivered.at, source: "claude_transcript", detail: { attachment: evidence.delivered.attachment, hook_event: evidence.delivered.hook_event, tool_use_id: evidence.delivered.tool_use_id } });
+    let state = "delivered_to_agent_context";
+    if (evidence.acknowledged) {
+        state = "acknowledged";
+        receipts.push({ state: "acknowledged", at: evidence.acknowledged.at, source: "claude_transcript", detail: { text: evidence.acknowledged.text } });
+    }
+    const expect = typeof record.body.expect_next_action === "string" ? record.body.expect_next_action : undefined;
+    let behavior = evidence.actions_seen ? "not_judged" : "not_observed_yet";
+    if (expect && evidence.actions_seen) {
+        const seen = evidence.raw_inputs.findIndex((i) => i.includes(JSON.stringify(expect).slice(1, -1)));
+        behavior = seen >= 0 ? "expected_action_seen" : "expected_action_not_seen";
+        if (seen >= 0) {
+            state = "behavior_adjusted";
+            receipts.push({ state: "behavior_adjusted", at: evidence.next_actions[seen]?.at, source: "claude_transcript", detail: { expected: expect, action: evidence.next_actions[seen] } });
+        }
+    }
+    return {
+        ...base,
+        state,
+        receipts,
+        next_actions: evidence.next_actions,
+        behavior,
+        note: state === "behavior_adjusted"
+            ? "The transcript shows the action this steer named, after it entered the model's context."
+            : "The transcript shows it entered the model's context. Whether the next actions follow it is a person's judgment unless the steer named expect_next_action.",
+    };
+}
+function hookReceipts(root, sessionId, steer) {
+    let text;
+    try {
+        text = readFileSync(join(root, safe(sessionId), "receipts.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r.steer === steer)
+                out.push(r);
+        }
+        catch {
+            // A torn line is not a receipt.
+        }
+    }
+    return out;
+}
+/**
+ * What a forwarded steer's ledger record should now say, from its delivery: done once the model has
+ * it, stopped once it never will. Null while it is still on its way, or if it has already settled.
+ */
+export function settlementOf(deps, record, now = new Date()) {
+    if (record.state !== "in_progress" || record.completion_receipt?.forwarded !== true)
+        return null;
+    const delivery = readSteerDelivery(deps, record, now);
+    if (!delivery)
+        return null;
+    const at = delivery.receipts.filter((r) => r.state === delivery.state).at(-1)?.at;
+    if (delivery.state === "delivered_to_agent_context" || delivery.state === "acknowledged" || delivery.state === "behavior_adjusted") {
+        return { state: "completed", outcome: delivery.state, message: delivery.note, ...(at ? { at } : {}) };
+    }
+    if (delivery.state === "expired" || delivery.state === "blocked") {
+        return { state: "blocked", outcome: delivery.state, message: delivery.note, ...(at ? { at } : {}) };
+    }
+    return null;
+}

package/dist/server.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The connector's HTTP surface:
+ *
+ *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
+ *   /authorize /token /register /revoke, /authorize/confirm   sign-in
+ *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
+ *   /health                     liveness, no data
+ *
+ * Every MCP request carries the signed-in person, and each tool call runs
+ * as that person (see tools.ts).
+ */
+import type { RuntimeDeps } from "./runtime-steer.js";
 import { MiadiOAuthProvider } from "./oauth.js";
 import type { MiadiPerson } from "./people.js";
 import { Ledger } from "./store.js";
@@ -21,6 +33,8 @@ export interface ConnectorDeps {
     jevAdapter?: JevAdapter;
     /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
     steerSettleMs?: number;
+    /** Where sessions and their steering inboxes live (jgwill/Miadi#930). */
+    steeringRuntime?: RuntimeDeps;
     /** Person-token attempts allowed per address in 15 minutes on each sign-in form (default 30). */
     tokenAttemptsPerWindow?: number;
     /** Where decision events go (default: one JSON line on stdout, the service journal); tests collect them (jgwill/Miadi#924). */

package/dist/server.js

@@ -1,14 +1,3 @@
-/**
- * The connector's HTTP surface:
- *
- *   /.well-known/oauth-*        OAuth discovery (MCP authorization spec)
- *   /authorize /token /register /revoke, /authorize/confirm   sign-in
- *   /mcp                        the MCP endpoint (streamable HTTP, stateless)
- *   /health                     liveness, no data
- *
- * Every MCP request carries the signed-in person, and each tool call runs
- * as that person (see tools.ts).
- */
 import express from "express";
 import { rateLimit } from "express-rate-limit";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -16,7 +5,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { mcpAuthRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { MiadiOAuthProvider, SCOPES, SCOPE_CONTRIBUTE, SCOPE_READ, emptyOAuthState } from "./oauth.js";
-import { reconcileInterrupted, registerApprovalRoutes } from "./approve.js";
+import { reconcileInterrupted, registerApprovalRoutes, registerProviderPolicyRoutes } from "./approve.js";
 import { DecisionTokens } from "./decisions.js";
 import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
 import { registerTools } from "./tools.js";
@@ -87,11 +76,13 @@ export function createConnectorApp(config, deps) {
         tmuxSessions: deps.tmuxSessions,
         tmux: deps.tmux,
         steerSettleMs: deps.steerSettleMs,
+        ...(deps.steeringRuntime ? { steeringRuntime: deps.steeringRuntime } : {}),
         log: deps.log,
     };
     // A run the connector was recording when it last stopped is failed now, so a person may run it again (#924).
     reconcileInterrupted(approvalDeps);
     registerApprovalRoutes(app, approvalDeps);
+    registerProviderPolicyRoutes(app, approvalDeps);
     const decisionTokens = new DecisionTokens(config.stateDir, config.decisionTokenTtl);
     const bearer = requireBearerAuth({
         verifier: provider,
@@ -126,6 +117,7 @@ export function createConnectorApp(config, deps) {
             modelOf: deps.modelOf,
             jevAdapter: deps.jevAdapter,
             steerSettleMs: deps.steerSettleMs,
+            ...(deps.steeringRuntime ? { steeringRuntime: deps.steeringRuntime } : {}),
         };
         const server = new McpServer({ name: "miadi", version: VERSION }, { instructions: INSTRUCTIONS });
         registerTools(server, ctx);

package/dist/steer.d.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
+import { type RuntimeDeps } from "./runtime-steer.js";
 import type { ConnectorRecord } from "./records.js";
-export declare const STEER_STATUSES: readonly ["prepared", "submitted", "accepted", "busy", "blocked", "wrong_pane", "stale_binding", "expired_grant", "duplicate", "composing"];
+export declare const STEER_STATUSES: readonly ["prepared", "submitted", "accepted", "busy", "blocked", "wrong_pane", "stale_binding", "expired_grant", "duplicate", "composing", "queued_at_runtime", "unsupported"];
 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 {
@@ -49,14 +50,16 @@ export declare function tmuxAdapter(exec?: typeof execFileSync): TmuxLike;
  */
 export declare function composingText(capture: string): string | null;
 export declare function steeringGrantOf(run: ConnectorRecord): SteeringGrant | null;
-export type GrantCheck = "ok" | "no_grant" | "expired_grant" | "duplicate";
+export type GrantCheck = "ok" | "no_grant" | "expired_grant" | "duplicate" | "revoked";
 /** 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;
+export declare function checkGrant(grant: SteeringGrant | null, priorAttempts: number, now?: Date, revoked?: boolean): GrantCheck;
+/** Whether a person revoked this run's steering, or just this one steer when `steer` is given (jgwill/Miadi#930). */
+export declare function steeringRevoked(records: ConnectorRecord[], grantId: string): boolean;
 /**
  * Steers already run under a grant: decided (or grant-covered) steer records that cite it and
- * typed their instruction (jgwill/Miadi#909). A steer stopped before typing (busy, composing,
- * wrong or stale pane, transport down) uses none of the grant's attempts. Receipts made before
- * `typed` was recorded count when their outcome says the text was delivered.
+ * typed or forwarded their instruction (jgwill/Miadi#909, #930). A steer stopped before that
+ * (composing, unsupported, wrong or stale pane, transport down) uses none of the grant's attempts.
+ * Receipts made before `typed` was recorded count when their outcome says the text was delivered.
  */
 export declare function steerAttempts(records: ConnectorRecord[], grantId: string): number;
 export declare function isBusy(capture: string, patterns?: RegExp[]): boolean;
@@ -67,13 +70,20 @@ export interface SteerDeps {
     settleMs?: number;
     sleep?: (ms: number) => Promise<void>;
     agentCommands?: string[];
+    /** Where sessions and their inboxes live (jgwill/Miadi#930). Absent, no runtime route is known. */
+    runtime?: RuntimeDeps;
 }
 export interface SteerResult {
     status: SteerStatus;
     message: string;
     target?: string;
-    /** Whether the instruction was typed into the pane. Only a typed steer uses one of the grant's attempts. */
+    /** Whether the instruction was typed into the pane. A typed or forwarded steer uses one of the grant's attempts. */
     typed: boolean;
+    /** Whether it was handed to the runtime's inbox. That is not proof the model read it. */
+    forwarded?: boolean;
+    route?: "claude_hook_inbox" | "tmux_exact_pane";
+    transcript_path?: string;
+    transcript_offset?: number;
     artifact?: {
         file: string;
         sha256: string;
@@ -99,5 +109,9 @@ export declare function steerSession(deps: SteerDeps, args: {
     binding?: {
         session: string;
         pane_id?: string;
+        session_id?: string;
+        provider?: string;
     };
+    /** A steer already sent with these same words under this grant. One correction is sent once, unless a person approves it again. */
+    sameInstructionSent?: string;
 }): Promise<SteerResult>;