@miadi/connector 0.1.19 → 0.1.21

package/dist/tools.js

@@ -16,17 +16,24 @@ import { reviewIdOf, videoIdOf } from "./reviews.js";
 import { SCOPE_APPROVE, SCOPE_CONTRIBUTE } from "./oauth.js";
 import { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, current, newRecordId, } from "./records.js";
 import { VERSION } from "./version.js";
-import { AlreadyDecided, DECISIONS, DecisionConflict, KIND_LABELS, STILL_RUNNING, StaleVersion, approvalStateOf, consequenceOf, decide, decisionWaitOf, isApprovable, isBeingDecided, logDecision, readQueueState, requestProjection, settleWithin, } from "./approve.js";
+import { AlreadyDecided, DECISIONS, DecisionConflict, KIND_LABELS, ProviderChoiceRequired, STILL_RUNNING, StaleVersion, approvalStateOf, consequenceOf, decide, decisionWaitOf, isApprovable, isBeingDecided, logDecision, readQueueState, requestProjection, settleWithin, } from "./approve.js";
 import { RevisionRefused, requestHistory, revisionRecord, supersedeRecords, versionOf } from "./revisions.js";
 import { DECISIONS_CARD_HTML, DECISIONS_CARD_URI, DECISION_TOKENS_META } from "./decisions.js";
 import { discoverProviders, jevConfigOf, resolveProvider, routerPreflight, PROVIDERS } from "./providers.js";
 import { authorizesActions, missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.js";
+import { authorizationReceipt, authorizeProvider, CHOICE_PROVIDERS, isPersonId, needsPersonChoice, providerPolicyOf } from "./provider-policy.js";
 import { candidatesFor, CRITICALITIES, jevAdapter, modelPreflight, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, TASK_TYPES, } from "./model-preflight.js";
-import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from "./steer.js";
+import { ShelfRefusal, listShelfArtefacts, readShelfArtefact } from "./research-shelf.js";
+import { CLAUDE_ADAPTER, DELIVERY_STATES, readSteerDelivery, revokeInInbox, settlementOf } from "./runtime-steer.js";
+import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steeringRevoked, steerSession } from "./steer.js";
 import { factoryLedgerPath, readFactoryReceipts, receiptsForRecord, recordsForSession } from "./factory-receipt.js";
 import { missionResult, redactResult } from "./mission-result.js";
 import { factoryDir as defaultFactoryDir } from "./queue-state.js";
 import { join } from "node:path";
+import { readingScope, canonicalVideo, suppliedDialogue } from "./reading/contract.js";
+import { workflowId } from "./reading/workflow.js";
+import { readingTask } from "./reading/adapters.js";
+import { canReadReading, readingOwner } from "./reading/privacy.js";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
 import { DEFAULT_PAGE_BYTES, FOUNDATIONS_PERMISSION, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, holdsFoundationRead, isFoundationDoc, pageOf, parseFileRef, } from "./episode-files.js";
@@ -145,6 +152,27 @@ export function githubGetter(fetchImpl = fetch, token = process.env.GITHUB_TOKEN
     };
 }
 /** Whether the steering transport works now: registered is not operational (jgwill/Miadi#909). */
+/**
+ * The provider interface as a client reads it (jgwill/Miadi#930). A correction goes to the session's
+ * own runtime, and busy is normal. Only the adapter named here exists. No other provider is assumed
+ * to behave like Claude Code.
+ */
+/** A steer being sent now, by its record: a retry arriving during it waits for this answer and sends nothing (jgwill/Miadi#930). */
+const steersInFlight = new Map();
+export const STEERING_CONTRACT = {
+    busy_is_normal: true,
+    connector: "Admits the steer, resolves mission → session → runtime, hands it to that session's inbox and reports what the runtime accepted. It does not watch tools or wait for idle.",
+    runtime: "The agent's own lifecycle presents it to its model at the next supported continuation in the same turn.",
+    delivery_states: DELIVERY_STATES,
+    provider_adapters: {
+        claude: { route: "claude_hook_inbox", continuation: "PostToolUse, PostToolUseFailure, then Stop if no tool follows", needs: `${CLAUDE_ADAPTER}, loaded when the session started` },
+        codex: { route: "unsupported" },
+        copilot: { route: "unsupported" },
+        pi: { route: "unsupported" },
+        gemini: { route: "unsupported" },
+    },
+    idle_seat: "An idle seat has no continuation coming, so its steer is typed into its bound pane once the prompt reads empty.",
+};
 export function steeringTransport(tmux) {
     if (!tmux)
         return { tool: "registered", transport: "unavailable", reason: "The connector host was started without a steering surface." };
@@ -179,7 +207,14 @@ export function registerTools(server, ctx) {
     const redact = (r) => {
         if (!viewer || viewer.api_tier === "write" || r.actor.person_id === viewer.id)
             return r;
+        if (r.body.reading && r.kind === "observation") {
+            const stage = r.body.reading;
+            return { ...r, refs: [], evidence_refs: [], body: { reading: { workflow_id: stage.workflow_id, stage: stage.stage, status: stage.status, sha256: stage.sha256, visibility: "source_owner_or_factory_operator" } } };
+        }
         const body = { ...r.body };
+        // Grants contain source rights and locators; only the owner and operators inspect them.
+        if (body.reading)
+            body.reading = { visibility: "source_owner_or_factory_operator" };
         // A steer's binding, pane, target and artifact path name the seat as the session does (#922 R2).
         for (const k of ["session", "cwd", "session_id", "binding", "pane"])
             delete body[k];
@@ -220,9 +255,81 @@ export function registerTools(server, ctx) {
             ...fields,
         });
     };
+    /**
+     * A forwarded steer's record moves when the runtime's evidence moves: done once the model has it,
+     * stopped once it never will. The ledger then agrees with its delivery on every surface that reads it
+     * (jgwill/Miadi#930). This only reads the inbox and the transcript, and appends when something changed.
+     */
+    const settleSteers = () => {
+        if (!ctx.steeringRuntime)
+            return;
+        for (const r of current(ledger.all())) {
+            if (r.kind !== "session_steer_request")
+                continue;
+            const settled = settlementOf(ctx.steeringRuntime, r);
+            if (!settled)
+                continue;
+            ledger.append({
+                id: newRecordId(r.kind),
+                kind: r.kind,
+                created_at: new Date().toISOString(),
+                actor: r.actor,
+                refs: r.refs,
+                evidence_refs: r.evidence_refs,
+                supersedes: r.id,
+                ...(r.approval_state ? { approval_state: r.approval_state } : {}),
+                state: settled.state,
+                completion_receipt: { ...r.completion_receipt, outcome: settled.outcome, delivery_state: settled.outcome, settled_at: new Date().toISOString(), ...(settled.at ? { delivered_at: settled.at } : {}), message: settled.message },
+                body: r.body,
+            });
+        }
+    };
     /** Every record, folded; for logic. What a tool returns goes through `shown`. */
-    const all = () => current(ledger.all());
-    const records = () => all().map(redact);
+    const all = () => {
+        settleSteers();
+        return current(ledger.all());
+    };
+    const records = () => {
+        const raw = all();
+        // Completion results can contain exact drafts too. Hide their parent mission as
+        // well, so missionStatus/get_run_result cannot rehydrate it from trusted records.
+        return raw.filter(r => !viewer || canReadReading(r, raw, viewer)).map(r => {
+            // The source owner can read a factory-authored result for their private mission.
+            if (readingOwner(r, raw) === viewer?.id)
+                return r;
+            return redact(r);
+        });
+    };
+    /** Which provider a run may launch with and who authorized it, as every surface shows it (jgwill/Miadi#926). */
+    const providerAuthorizationOf = (r) => r && r.kind === "run_request" ? authorizeProvider(r, ledger.all(), { requireFresh: r.approval_state === "awaiting_approval" }) : undefined;
+    const authorizationOut = (a) => ({
+        ...authorizationReceipt(a),
+        explanation: a.explanation,
+        ...(a.not_binding ? { not_binding: a.not_binding } : {}),
+    });
+    /** A mission's status with the authorization of its provider, and a note when the provider that ran was never authorized. */
+    const withProviderAuthorization = (status) => {
+        const subject = status?.subject?.id ? all().find((r) => r.id === status.subject.id) : undefined;
+        const a = providerAuthorizationOf(subject);
+        if (!a)
+            return status;
+        // An approval records the authorization it was given; a run approved before jgwill/Miadi#926 recorded none.
+        const given = subject?.completion_receipt?.provider_authorization;
+        const actual = typeof status.provider?.actual === "string" ? status.provider.actual : null;
+        const unauthorizedLaunch = Boolean(actual && needsPersonChoice(actual) && !a.authorized && !given?.authorized);
+        return {
+            ...status,
+            provider_authorization: { ...authorizationOut(a), ...(given ? { at_approval: given } : {}), ...(unauthorizedLaunch ? { launched_without_authorization: true } : {}) },
+            ...(unauthorizedLaunch
+                ? {
+                    notes: [
+                        ...(Array.isArray(status.notes) ? status.notes : []),
+                        `${actual} ran for this mission without ${a.requester.name}'s own choice for it on record (jgwill/Miadi#926). Nothing was stopped or re-run because of it.`,
+                    ],
+                }
+                : {}),
+        };
+    };
     const uploads = new ResearchUploads(join(config.stateDir, "uploads"));
     const touching = (ref) => records().filter((r) => r.refs.includes(ref) || r.evidence_refs.includes(ref) || r.id === ref);
     /** The factory runner's delivery receipts, read fresh: operator data, for the write tier only. */
@@ -248,6 +355,13 @@ export function registerTools(server, ctx) {
             service: "@miadi/connector",
             version: VERSION,
             contract: "jgwill/Miadi#815 Connector v2, jgwill/Miadi#816 Review Bridge",
+            reading_workflow: {
+                contract: "transcript-first-v1",
+                provider_runtime: process.env.MIADI_READING_ADAPTER ? "host_configured_not_verified" : "not_configured",
+                transcript_store: "private connector ledger source-part receipts before generation",
+                import: "blocked_until_authenticated_sha256_cas_v1_handshake",
+                publication: "separate_exact_candidate_approval",
+            },
             signed_in_as: { person_id: person.id, name: person.name, role: person.role ?? null, miadi_api_tier: person.api_tier, via: auth.clientId },
             scopes: auth.scopes,
             can_contribute: auth.scopes.includes(SCOPE_CONTRIBUTE),
@@ -258,7 +372,7 @@ export function registerTools(server, ctx) {
             },
             tools: TOOL_STATUS,
             // Registered is not operational: whether a steer can reach a pane on this host now (jgwill/Miadi#909).
-            steering: steeringTransport(ctx.tmux),
+            steering: { ...steeringTransport(ctx.tmux), runtime_route: ctx.steeringRuntime ? "configured" : "not_configured", contract: STEERING_CONTRACT },
             foundation_read: {
                 permission: FOUNDATIONS_PERMISSION,
                 held: foundations,
@@ -710,6 +824,8 @@ export function registerTools(server, ctx) {
             ...(versionOf(r) > 1 ? { history: "Earlier versions: get_request_history." } : {}),
             approval_url: r.approval_state === "awaiting_approval" ? approvalUrl(r.id) : undefined,
             queue: r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined,
+            // Where a steer stands, joined to its id: operator detail, as mission_status has it (jgwill/Miadi#930).
+            ...(r.kind === "session_steer_request" && ctx.steeringRuntime && person.api_tier === "write" ? { delivery: readSteerDelivery(ctx.steeringRuntime, all().find((x) => x.id === r.id) ?? r) ?? undefined } : {}),
             // Where the request stands, in the words every surface uses (jgwill/Miadi#889).
             projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             ...(r.approval_state === "revision_requested"
@@ -732,9 +848,17 @@ export function registerTools(server, ctx) {
     }, wrap(async ({ ref }, extra) => {
         const { person } = who(extra);
         const writeTier = person.api_tier === "write";
-        return missionStatus(ref.trim(), records(), {
+        return withProviderAuthorization(await 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),
+            ...(writeTier && ctx.steeringRuntime
+                ? {
+                    steerDeliveryOf: (r) => {
+                        const stored = all().find((x) => x.id === r.id) ?? r;
+                        return readSteerDelivery(ctx.steeringRuntime, stored);
+                    },
+                }
+                : {}),
             // Without a lister the host cannot say which sessions live: unknown, never "absent" (jgwill/Miadi#909).
             tmuxSessions: writeTier ? (ctx.tmuxSessions ?? (ctx.tmux?.listSessions ? () => ctx.tmux.listSessions() : undefined)) : undefined,
             paneBusy: writeTier && ctx.tmux
@@ -788,11 +912,11 @@ export function registerTools(server, ctx) {
                 return { state: i.state, title: i.title };
             },
             liveVersionOf: (pkg) => (pkg === "@miadi/connector" ? VERSION : undefined),
-        });
+        }));
     }));
     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.",
+        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 (Pi, Copilot by default; Codex and Claude Code only when a request names them), the rule that a named Codex runs only on the requester's own choice for that mission or their own policy (jgwill/Miadi#926), your own provider policy, 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) => {
@@ -801,9 +925,12 @@ export function registerTools(server, ctx) {
         return {
             preference_order: PROVIDERS.map((p) => p.id),
             explicit_only: PROVIDERS.filter((p) => !p.selectable_by_default).map((p) => p.id),
+            needs_person_choice: [...CHOICE_PROVIDERS],
+            your_policy: providerPolicyOf(ledger.all(), person.id),
+            policy_page: `${config.publicUrl}/providers`,
             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.",
+            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. A request may name Codex, but it runs only when its requester chooses Codex for that mission on the approval page, or their own policy on the providers page says so; a generic approval, the assistant's provider field, the host's order or Jev never choose it.",
         };
     }));
     server.registerTool("mission_model_preflight", {
@@ -842,7 +969,8 @@ export function registerTools(server, ctx) {
         const body = record.body;
         const provider = (typeof body.resolved_provider === "string" ? body.resolved_provider : typeof body.provider === "string" ? body.provider : null);
         const basis = record.approval_state === "approved" ? "approved" : "requested";
-        const candidates = candidatesFor(discoverProviders(ctx.providersProbe), provider, ctx.modelOf, basis);
+        const authorization = providerAuthorizationOf(record);
+        const candidates = candidatesFor(discoverProviders(ctx.providersProbe), provider, ctx.modelOf, basis, authorization);
         const jevConfig = jevConfigOf(process.env);
         const jev = a.consult_jev ? (ctx.jevAdapter ?? (jevConfig ? jevAdapter(jevConfig, ctx.approval?.fetchImpl ?? fetch) : undefined)) : undefined;
         const configured = Boolean(jevConfig);
@@ -859,6 +987,7 @@ export function registerTools(server, ctx) {
             task: a.task_type,
             criticality: a.criticality,
             candidates,
+            ...(authorization ? { provider_authorization: authorizationOut(authorization) } : {}),
             ...(a.launch ? { launch: a.launch } : {}),
             ...(jev ? { adapter: jev } : { routerWhenAbsent: configured ? "not_requested" : "router_unconfigured" }),
         });
@@ -1064,6 +1193,17 @@ export function registerTools(server, ctx) {
         const video = videoIdOf(a.video);
         if (!video)
             throw new ToolRefusal("invalid_ref", "Give a YouTube URL or an 11-character video id.");
+        const prior = all().find(r => r.kind === "source_intent" && r.actor.person_id === person.id && r.idempotency_key === `${video}:${a.purpose}`);
+        if (prior && prior.body.readiness !== a.readiness) {
+            // Release/withdrawal is an explicit source-owner contribution, not processing authority.
+            const transition = {
+                id: newRecordId("source_intent"), kind: "source_intent", created_at: new Date().toISOString(), actor: actorOf(person, auth), supersedes: prior.id,
+                refs: prior.refs, evidence_refs: [], state: a.readiness === "released_for_review" ? "ready" : a.readiness === "withheld" ? "blocked" : "pending",
+                body: { ...prior.body, readiness: a.readiness, source_readiness_transition: true },
+            };
+            ledger.appendDurable(transition);
+            return all().find(r => r.id === prior.id);
+        }
         return append("source_intent", person, auth, {
             circle: "continuity",
             refs: [...a.refs, `https://youtu.be/${video}`],
@@ -1281,6 +1421,55 @@ export function registerTools(server, ctx) {
         };
     }));
     // ── requests: recorded, approved by a person on the approval page, then run ──
+    server.registerTool("request_screenwalk_reading", {
+        title: "Release a source for a bounded research reading",
+        description: "One approved run archives the released source transcript before generating V1, an academic survey and a labelled reflective reading. It stops at the exact candidate's editorial gate. No paid fallback, public release, Deep Diver or Chronicle is included. A host runtime adapter must be configured; unavailable providers are reported as blockers.",
+        inputSchema: { scope: readingScope, companion: suppliedDialogue.optional(), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        const scope = readingScope.parse(a.scope);
+        const source = all().find(r => r.id === scope.source_intent);
+        if (!source || source.kind !== "source_intent" || source.actor.person_id !== person.id || source.state !== "ready" || source.body.readiness !== "released_for_review")
+            throw new ToolRefusal("source_not_released", "The source owner must explicitly register this source as released_for_review before requesting processing.");
+        const video = canonicalVideo(String(source.body.video_id));
+        const id = workflowId(person.id, video, scope.revision_of);
+        if (scope.revision_of) {
+            const prior = ledger.all().find(r => r.kind === "observation" && r.body.reading?.workflow_id === scope.revision_of && r.body.reading?.stage === "registration");
+            const priorRequest = all().find(r => r.kind === "run_request" && r.body.workflow_id === scope.revision_of && r.actor.person_id === person.id && r.approval_state === "approved" && r.body.reading?.source_intent === scope.source_intent);
+            if ((!prior && !priorRequest) || (prior && (prior.actor.person_id !== person.id || prior.body.reading?.video_id !== video)))
+                throw new ToolRefusal("invalid_revision", "A revision must name your prior workflow for the same video.");
+        }
+        const existing = all().find(r => r.kind === "run_request" && r.actor.person_id === person.id && r.body.workflow_id === id);
+        if (existing)
+            return { ...redact(existing), workflow_id: id, approval_url: approvalUrl(existing.id), replayed: true, note: "This video's bounded request already exists; read or resume it. The new scope was not substituted." };
+        const resolution = resolveProvider(undefined, discoverProviders(ctx.providersProbe));
+        if (resolution.state !== "ok")
+            return { state: resolution.state, note: "No runtime provider was verified; nothing was queued." };
+        const r = append("run_request", person, auth, {
+            circle: "engineering", refs: [source.id, `https://youtu.be/${video}`], intention: a.intention,
+            idempotency_key: id, approval_state: "awaiting_approval", state: "pending",
+            body: { task: readingTask(scope), reading: scope, ...(a.companion ? { reading_companion: a.companion } : {}), session: `reading-${id.slice(8)}`, workflow_id: id, resolved_provider: resolution.provider.id },
+        });
+        return { ...r, workflow_id: id, approval_url: approvalUrl(r.id), gates: ["editorial_public_import", "deep_diver", "chronicle", "cultural_reuse"] };
+    }));
+    server.registerTool("request_reading_import", {
+        title: "Approve the exact staged reading for public import",
+        description: "Request a separate editorial decision for one candidate hash and its exact base. Import is a public release; it refuses legacy unconditional writes. Does not authorize Deep Diver, Chronicle or further reuse.",
+        inputSchema: { workflow_id: z.string().regex(/^reading:[a-f\d]{32}$/), sha256: z.string().regex(/^[a-f\d]{64}$/), expected_version: z.number().int().min(0), expected_sha256: z.string().regex(/^[a-f\d]{64}$/), public_release: z.literal(true), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        // Read from the existing ledger, without constructing a second workflow store.
+        const candidates = ledger.all().filter(r => r.kind === "observation" && r.body.reading?.workflow_id === a.workflow_id && r.body.reading?.stage === "v3" && r.body.reading?.status === "completed");
+        const candidate = candidates[0]?.body.reading?.artifact;
+        if (!candidate || candidates[0].actor.person_id !== person.id || candidate.sha256 !== a.sha256 || candidate.expected_version !== a.expected_version || candidate.expected_sha256 !== a.expected_sha256)
+            throw new ToolRefusal("candidate_mismatch", "Read this person's staged candidate and request its exact hash and base.");
+        const r = append("run_request", person, auth, { circle: "story", refs: [a.workflow_id], intention: a.intention, idempotency_key: `${a.workflow_id}:import:${a.sha256}`, state: "pending", approval_state: "awaiting_approval", body: { task: "Run node packages/connector/scripts/reading.mjs import <this-run-request-id>. Only import the exact typed reading_import candidate after the service proves atomic CAS and durable idempotency; read it back exactly. Stop on any mismatch. No Deep Diver or Chronicle.", reading_import: { workflow_id: a.workflow_id, sha256: a.sha256, expected_version: a.expected_version, expected_sha256: a.expected_sha256, public_release: true }, reading_preview: { markdown: candidate.markdown, diffs: candidate.diffs, manifest: candidate.manifest } } });
+        return { ...r, approval_url: approvalUrl(r.id), candidate: { sha256: candidate.sha256, bytes: candidate.bytes, diff: candidate.diffs, manifest: candidate.manifest } };
+    }));
     server.registerTool("request_authorized_run", {
         title: "Request a bounded agent run",
         description: "Ask for an agent session to do one bounded task. The request waits for a person with Miadi's write tier to approve it on the returned approval_url; once approved, a brief is queued for the factory intake, which opens or reaches the session within minutes. Read it back with get_run_result. This is for a new mission only: to change a request that still awaits a decision, call revise_pending_request with its id, so the person keeps one card to decide.",
@@ -1294,7 +1483,7 @@ export function registerTools(server, ctx) {
             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."),
+                .describe("The provider the run should launch with, verified installed on the connector host. Name it only when the person asked for that provider for this mission. Claude Code runs only when named. Codex runs only when the person also chooses Codex for this mission on the approval page (or their own policy allows it): naming it here does not choose it for them (jgwill/Miadi#926). Unknown or unavailable leaves the mission unstarted, and nothing falls back to Codex."),
             steering: z
                 .object({
                 max_attempts: z.number().int().min(1).max(20).describe("How many authorized follow-up steers this approval covers."),
@@ -1334,10 +1523,25 @@ export function registerTools(server, ctx) {
                 ...(a.steering ? { steering: a.steering } : {}),
             },
         });
+        const authorization = providerAuthorizationOf(all().find((x) => x.id === r.id) ?? r);
         return {
             ...r,
-            provider: { requested: a.provider ?? null, resolved: resolution.provider.id, explicit: resolution.explicit, version: resolution.provider.version },
+            provider: {
+                requested: a.provider ?? null,
+                resolved: resolution.provider.id,
+                explicit: resolution.explicit,
+                version: resolution.provider.version,
+                authorization: authorizationOut(authorization),
+            },
             approval_url: approvalUrl(r.id),
+            ...(authorization.authorized
+                ? {}
+                : {
+                    // #926 review R4, RR5: a provider is revised to another one, never cleared; a service token cannot choose at all.
+                    next_action: isPersonId(person.id)
+                        ? `Tell ${person.name} that a Codex run needs their own choice on the approval page (${approvalUrl(r.id)}); approving alone, on the page or a card, will not run it. Do not choose for them. If they did not ask for Codex for this mission, revise the request with another provider (pi, copilot or claude).`
+                        : `A request made with a service token cannot run Codex: only a person chooses it, for a request of their own. Revise it with another provider (pi, copilot or claude).`,
+                }),
         };
     }));
     // ── one mission, many versions, one decision (jgwill/Miadi#919) ────────────
@@ -1435,10 +1639,13 @@ export function registerTools(server, ctx) {
             throw error;
         }
         ledger.append(record);
+        // A revision moves the version: a provider choice made for an earlier version no longer binds (jgwill/Miadi#926).
+        const revisedAuthorization = providerAuthorizationOf(all().find((x) => x.id === (record.supersedes ?? record.id)));
         return {
             ...revisionOut(record.supersedes ? { ...record, id: record.supersedes } : record),
             revised: record.revision,
             ...(provider ? { provider } : {}),
+            ...(revisedAuthorization ? { provider_authorization: authorizationOut(revisedAuthorization) } : {}),
             note: `One request, one approval: its page and card now show version ${record.revision.version}. Earlier versions stay readable with get_request_history.`,
         };
     }));
@@ -1514,10 +1721,11 @@ export function registerTools(server, ctx) {
     }));
     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.",
+        description: "Send one correction to a running agent within an approved run's steering grant (jgwill/Miadi#893, #930). Busy is normal: send it while the agent works, once, and do not watch its tools, wait for idle or retry. The connector hands it to the bound session's own inbox, and the agent's runtime presents it to its model at its next continuation in the same turn. The answer's delivery says which state it reached, each with its source and time: forwarded_to_runtime and queued_at_runtime do not show the model read it; delivered_to_agent_context, acknowledged and behavior_adjusted are read from the session's transcript. A provider with no adapter, or a session started before the adapter, answers unsupported with the reason and uses no attempt. An idle seat has no continuation coming, so its steer is typed into the mission's bound pane, never whichever pane is active. When the run's grant does not cover this, the steer waits for one explicit scoped human decision on the returned approval_url. Read it later with get_run_result on the steer's id or with mission_status.",
         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."),
+            instruction: z.string().min(1).max(4000).describe("The exact instruction for the agent. It is material within the approved mission's scope, not new authority."),
+            expect_next_action: z.string().min(1).max(200).optional().describe("Words to look for in the agent's next tool inputs. When they appear after delivery, the state becomes behavior_adjusted; without this, whether the next actions follow the correction is a person's judgment."),
             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,
@@ -1541,15 +1749,36 @@ export function registerTools(server, ctx) {
         }
         const grant = steeringGrantOf(grantRecord);
         const priorAttempts = steerAttempts(all(), grantRecord.id);
-        const covered = checkGrant(grant, priorAttempts) === "ok";
+        const deliveryOf = (rec) => (ctx.steeringRuntime ? readSteerDelivery(ctx.steeringRuntime, rec) ?? undefined : undefined);
+        const wasSent = (rec) => {
+            const receipt = rec.completion_receipt;
+            return receipt?.typed === true || receipt?.forwarded === true;
+        };
+        const attemptsNow = (counted) => ({ used: steerAttempts(all(), grantRecord.id), ...(grant?.max_attempts !== undefined ? { max: grant.max_attempts } : {}), counted });
+        // The same key after a client's retry or a dropped connection gets the first answer, whatever the grant says by now.
+        if (a.idempotency_key) {
+            const sameKey = all().find((x) => x.kind === "session_steer_request" && x.idempotency_key === a.idempotency_key && x.actor.person_id === person.id && x.refs.includes(grantRecord.id));
+            if (sameKey && wasSent(sameKey))
+                return { ...sameKey, delivery: deliveryOf(sameKey), attempts: attemptsNow(false) };
+            if (sameKey && steersInFlight.has(sameKey.id)) {
+                await steersInFlight.get(sameKey.id);
+                const settled = all().find((x) => x.id === sameKey.id) ?? sameKey;
+                return { ...settled, delivery: deliveryOf(settled), attempts: attemptsNow(false) };
+            }
+        }
+        const revoked = steeringRevoked(all(), grantRecord.id);
+        const covered = checkGrant(grant, priorAttempts, new Date(), revoked) === "ok";
         // The pane the factory delivered this mission to: the steer goes there and nowhere else (jgwill/Miadi#909).
         const bound = receiptsForRecord(receipts(), grantRecord.id)[0];
-        const binding = bound ? { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}) } : undefined;
+        const binding = bound
+            ? { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}), ...(bound.session_id ? { session_id: bound.session_id } : {}), ...(bound.provider ? { provider: bound.provider } : {}) }
+            : undefined;
         const body = {
             instruction: a.instruction,
             session: a.session ?? bound?.tmux_session ?? grantRecord.body.session,
             pane: a.pane ?? grant?.pane,
-            ...(binding ? { binding: { ...binding, by: "factory_receipt", delivered_at: bound.at, ...(bound.session_id ? { session_id: bound.session_id } : {}) } } : {}),
+            ...(a.expect_next_action ? { expect_next_action: a.expect_next_action } : {}),
+            ...(binding ? { binding: { ...binding, by: "factory_receipt", delivered_at: bound.at } } : {}),
         };
         const fields = {
             circle: grantRecord.circle,
@@ -1567,42 +1796,113 @@ export function registerTools(server, ctx) {
                 ...r,
                 approval_url: approvalUrl(r.id),
                 state: "awaiting_approval",
-                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts),
+                reason: !grant ? "no_grant" : checkGrant(grant, priorAttempts, new Date(), revoked),
                 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, ...(binding ? { binding } : {}) });
-        // A typed steer is never "failed": failed is re-runnable, and that would type it twice (#922 R8).
-        const delivered = result.typed;
-        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,
-                typed: result.typed,
-                message: result.message,
-                ...(result.target ? { target: result.target } : {}),
-                ...(result.artifact ? { artifact: result.artifact } : {}),
-            },
-            body: r.body,
+        const sameWords = all().find((x) => x.kind === "session_steer_request" && x.id !== r.id && x.refs.includes(grantRecord.id) && x.body.instruction === a.instruction && wasSent(x));
+        let finishSend = () => { };
+        steersInFlight.set(r.id, new Promise((resolve) => (finishSend = resolve)));
+        try {
+            const result = await steerSession({ tmux: ctx.tmux, stateDir: config.stateDir, ...(ctx.steeringRuntime ? { runtime: ctx.steeringRuntime } : {}), ...(ctx.steerSettleMs !== undefined ? { settleMs: ctx.steerSettleMs } : {}) }, { record: r, grantRecord, priorAttempts, ...(binding ? { binding } : {}), ...(sameWords ? { sameInstructionSent: sameWords.id } : {}) });
+            // A typed or forwarded steer is never "failed": failed is re-runnable, and that would send it twice (#922 R8).
+            const delivered = result.typed || result.forwarded === true;
+            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",
+                // Forwarded is under way: the runtime has not presented it yet, and delivery reads where it stands.
+                state: result.forwarded ? "in_progress" : 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,
+                    typed: result.typed,
+                    ...(result.forwarded ? { forwarded: true } : {}),
+                    ...(result.route ? { route: result.route } : {}),
+                    ...(result.transcript_offset !== undefined ? { transcript_offset: result.transcript_offset } : {}),
+                    message: result.message,
+                    ...(result.target ? { target: result.target } : {}),
+                    ...(result.artifact ? { artifact: result.artifact } : {}),
+                },
+                body: r.body,
+            });
+            const stored = all().find((x) => x.id === r.id) ?? r;
+            return {
+                ...(records().find((x) => x.id === r.id) ?? r),
+                delivery: deliveryOf(stored),
+                attempts: attemptsNow(delivered),
+            };
+        }
+        finally {
+            finishSend();
+            steersInFlight.delete(r.id);
+        }
+    }));
+    server.registerTool("revoke_session_steering", {
+        title: "Stop a run's steering, or one steer still waiting",
+        description: "A person stops a correction before its agent reads it (jgwill/Miadi#930). Name the run to stop all further steers under its grant and everything still waiting in its session's inbox, or add steer to stop only that one. The agent's runtime checks again when it would consume it. The answer says exactly what was revoked and what the agent already consumed: a correction already read cannot be taken back.",
+        inputSchema: {
+            run_request: z.string().min(1).describe("The run_request or work_proposal the steering belongs to."),
+            steer: z.string().min(1).optional().describe("One session_steer_request to stop; without it, the run's whole steering grant is revoked."),
+            reason: z.string().min(1).max(1000),
+            refs,
+            ...base,
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        requireTier(person, "write");
+        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 run_request or work_proposal whose steering this stops.");
+        }
+        if (a.steer) {
+            const steer = all().find((r) => r.id === a.steer);
+            if (!steer || steer.kind !== "session_steer_request" || !steer.refs.includes(grantRecord.id))
+                throw new ToolRefusal("invalid_ref", `${a.steer} is not a steer of ${grantRecord.id}.`);
+        }
+        const r = append("steering_revocation", person, auth, {
+            circle: grantRecord.circle,
+            refs: [grantRecord.id, ...(a.steer ? [a.steer] : []), ...a.refs],
+            intention: a.intention,
+            role: a.role,
+            idempotency_key: a.idempotency_key,
+            body: { reason: a.reason, ...(a.steer ? { steer: a.steer } : {}) },
         });
-        const after = steerAttempts(all(), grantRecord.id);
-        return {
-            ...(records().find((x) => x.id === r.id) ?? r),
-            attempts: { used: after, ...(grant?.max_attempts !== undefined ? { max: grant.max_attempts } : {}), counted: result.typed },
-        };
+        // A steer still waiting for a person's decision is closed too, so approving it later cannot run it.
+        if (a.steer) {
+            const waiting = all().find((x) => x.id === a.steer);
+            if (waiting?.approval_state === "awaiting_approval") {
+                ledger.append({
+                    id: newRecordId(waiting.kind),
+                    kind: waiting.kind,
+                    created_at: new Date().toISOString(),
+                    actor: waiting.actor,
+                    refs: waiting.refs,
+                    evidence_refs: [],
+                    supersedes: waiting.id,
+                    approval_state: "declined",
+                    state: "withdrawn",
+                    completion_receipt: { decision: "revoked", decided_by: { person_id: person.id, name: person.name }, decided_at: new Date().toISOString(), outcome: "revoked", steer_status: "blocked", typed: false, message: a.reason },
+                    body: waiting.body,
+                });
+            }
+        }
+        const sessions = [...new Set(receiptsForRecord(receipts(), grantRecord.id).map((x) => x.session_id).filter((x) => Boolean(x)))];
+        const inboxes = ctx.steeringRuntime
+            ? sessions.map((session_id) => ({ session_id, ...revokeInInbox(ctx.steeringRuntime, session_id, { grant: grantRecord.id, ...(a.steer ? { steer: a.steer } : {}) }, a.reason) }))
+            : [];
+        return { ...r, inboxes, note: a.steer ? "This steer was stopped where it had not been consumed." : "No further steer runs under this grant without a person's decision on that exact steer." };
     }));
     server.registerTool("request_review_operation", {
         title: "Request a review operation",
@@ -1775,6 +2075,78 @@ export function registerTools(server, ctx) {
             research_url: `${config.miadiPublicUrl}/research`,
         };
     }));
+    server.registerTool("list_research_artifacts", {
+        title: "List what is on the inquiry shelf",
+        description: "Reports and folders on Miadi's private inquiry shelf, as you may read them: each one's title, opening, words, sections, sources, files, date, owner, visibility, issue, episodes and, for a saved report, its sha256. All of it is computed from the files, never summarised. scope mine lists what you own; scope all, for Miadi's write tier, lists every folder. Search with query, narrow with kind, order with sort, and page with offset and next_offset. Read one with read_research_artifact. Read only: nothing is changed.",
+        inputSchema: {
+            scope: z.enum(["mine", "all"]).default("mine"),
+            query: z.string().max(200).optional().describe("Words to find in a title, an opening, a heading or a folder's name."),
+            kind: z.enum(["report", "folder", "notes"]).optional().describe("report: saved through a door. folder: holds a document. notes: agent instructions or unreadable files only."),
+            sort: z.enum(["newest", "oldest", "longest", "title"]).default("newest"),
+            limit: z.number().int().min(1).max(200).default(50),
+            offset: z.number().int().min(0).default(0).describe("0, or next_offset from the previous page."),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        const { person } = who(extra);
+        if (!config.inquiryRoot)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        try {
+            const { scope, query, kind, sort, limit, offset } = a;
+            return await listShelfArtefacts(config.inquiryRoot, person, {
+                ...(scope ? { scope } : {}),
+                ...(query ? { query } : {}),
+                ...(kind ? { kind } : {}),
+                ...(sort ? { sort } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(offset !== undefined ? { offset } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ShelfRefusal)
+                throw new ToolRefusal(error.code, error.message);
+            throw error;
+        }
+    }));
+    server.registerTool("read_research_artifact", {
+        title: "Read a document on the inquiry shelf",
+        description: "Read back what is on Miadi's private inquiry shelf, as you: a folder's owner, visibility, its issue, its episodes, the commit that holds it, whether anything on disk differs from that commit, and every file with its bytes and sha256. With the folder's report, or the file you name, you also get its text, in pages when long: pass page.next back; joined, the pages hash to sha256. integrity says whether a saved report's bytes are still the bytes saved. Only the folder's owner or a person with Miadi's write tier can read it. Text files only; hidden files and links are never served. Read only: nothing is changed.",
+        inputSchema: {
+            artefact: z.string().min(1).max(300).describe("The shelf folder's name, inquiry-artefact:<name> or the research_artifact record id save_research returned."),
+            file: z.string().min(1).max(500).optional().describe("A path in the folder, as files lists it. Default: its saved report, if it has one."),
+            offset: z.number().int().min(0).optional().describe("0, or page.next.offset from the previous page."),
+            revision: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("page.next.revision from the previous page: refuses with changed if the file moved since."),
+            max_bytes: z.number().int().min(MIN_PAGE_BYTES).max(MAX_TEXT_BYTES).optional().describe(`Page size in bytes (default ${DEFAULT_PAGE_BYTES}).`),
+        },
+        annotations: READ,
+    }, wrap(async (a, extra) => {
+        const { person } = who(extra);
+        if (!config.inquiryRoot)
+            throw new ToolRefusal("unavailable", "This connector host has no inquiry shelf configured.");
+        const ref = a.artefact.trim();
+        let name = ref.replace(/^inquiry-artefact:/, "");
+        if (ref.startsWith("research_artifact:")) {
+            const held = all().find((r) => r.id === ref && r.kind === "research_artifact");
+            const artefact = held?.body?.artefact;
+            if (typeof artefact !== "string")
+                throw new ToolRefusal("not_found", `No research_artifact ${ref}.`);
+            name = artefact;
+        }
+        try {
+            const { file, offset, revision, max_bytes: maxBytes } = a;
+            return await readShelfArtefact(config.inquiryRoot, name, person, {
+                ...(file !== undefined ? { file } : {}),
+                ...(offset !== undefined ? { offset } : {}),
+                ...(revision !== undefined ? { revision } : {}),
+                ...(maxBytes !== undefined ? { maxBytes } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof ShelfRefusal)
+                throw new ToolRefusal(error.code, error.message);
+            throw error;
+        }
+    }));
     server.registerTool("request_inquiry_episode", {
         title: "Request that an inquiry be woven into an episode, or start one",
         description: "Ask that a folder on the inquiry shelf (from save_research) be woven into a Chronicle episode, or that a new episode be started from it. Weaving copies the folder into the episode, so the approval page shows its visibility. Waits for a person's approval; on approval it runs once through Miadi's episode doors.",
@@ -1878,8 +2250,9 @@ export function registerTools(server, ctx) {
                 created_at: r.created_at,
                 circle: r.circle,
                 intention: r.intention,
-                consequence: consequenceOf(r),
+                consequence: consequenceOf(r, providerAuthorizationOf(r)),
                 detail: detailOf(r),
+                ...(r.kind === "run_request" ? { provider_authorization: authorizationOut(providerAuthorizationOf(r)) } : {}),
                 approval_url: approvalUrl(r.id),
                 projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             }));
@@ -1972,6 +2345,13 @@ export function registerTools(server, ctx) {
                 decided = settled;
             }
             catch (error) {
+                // No projection here: the card shows this message, and the request still awaits a decision (jgwill/Miadi#926).
+                if (error instanceof ProviderChoiceRequired) {
+                    throw new ToolRefusal("provider_choice_required", `${error.message} Open its approval page: ${approvalUrl(r.id)}`, {
+                        approval_url: approvalUrl(r.id),
+                        provider_authorization: authorizationOut(error.authorization),
+                    });
+                }
                 if (error instanceof StaleVersion)
                     throw new ToolRefusal("stale_version", error.message, { projection: projectionNow(), approval_url: approvalUrl(r.id) });
                 // A different decision recorded a moment earlier, by another click or client, is reported with where it stands.
@@ -2084,11 +2464,16 @@ export const TOOL_STATUS = {
     revise_pending_request: "live, contribute (a waiting or sent-back run or proposal gets its next version; same id, same card)",
     get_request_history: "live (every version of a request, oldest first; whoever asked, or the write tier)",
     supersede_pending_requests: "live, contribute (retires named earlier requests still waiting and joins them as earlier versions of the one that stands)",
-    request_session_steer: "live, contribute, write tier (runs inside an approved run's steering grant, else one scoped human decision; get_capabilities.steering says whether the transport works now)",
+    request_session_steer: "live, contribute, write tier (one correction to a working agent, forwarded to its runtime; runs inside an approved run's steering grant, else one scoped human decision; get_capabilities.steering says whether the transport works now and which providers have an adapter)",
+    revoke_session_steering: "live, contribute, write tier (stops a run's steering, or one steer not yet consumed)",
     request_review_operation: "live, contribute, needs_approval",
+    request_screenwalk_reading: "live, contribute, needs_approval (host provider adapter required; stops at editorial decision)",
+    request_reading_import: "live, contribute, needs_approval (exact public import; atomic service contract required)",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",
     save_research: "live, contribute (the whole report, in parts when long; saved on the inquiry shelf with its issue, pushed; private by default)",
+    list_research_artifacts: "live (the shelf as you may read it: yours, or every folder for the write tier; searched, sorted, paged)",
+    read_research_artifact: "live (a shelf folder's manifest and its text files, paged, with sha256 and the commit that holds them; its owner or Miadi's write tier)",
     request_inquiry_episode: "live, contribute, needs_approval (weaves a shelf folder into an episode or starts one)",
     show_decisions: "live (cards in the conversation; deciding on them needs the write tier and the miadi:approve sign-in)",
     decide_request: "card only: the person's click on a decisions card; not offered to the assistant",