@miadi/connector 0.1.7 → 0.1.9

package/README.md

@@ -38,6 +38,8 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 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.
+
 ### 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

@@ -15,6 +15,8 @@ import type { Ledger } from "./store.js";
 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";
+export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 export interface ApprovalDeps {
     config: ConnectorConfig;
     ledger: Ledger<ConnectorRecord>;
@@ -32,26 +34,14 @@ export interface ApprovalDeps {
  */
 export declare const DECISIONS: readonly ["approve", "approve_with_changes", "request_revision", "decline"];
 export type Decision = (typeof DECISIONS)[number];
-export declare function factoryDir(env?: NodeJS.ProcessEnv): string;
-export declare function runBriefFile(record: {
-    id: string;
-}): string;
-/** Where a run request's brief is: waiting, delivered by the intake, cancelled, or not queued. */
-export declare function readQueueState(record: ConnectorRecord, dir?: string): {
-    state: string;
-    file: string;
-    note?: undefined;
-} | {
-    state: string;
-    file: string;
-    note: string;
-};
 /** The task a work proposal asks for, written from the proposal's own fields. */
 export declare function proposalTask(record: ConnectorRecord): string;
 export declare function runBrief(record: ConnectorRecord, approver: MiadiPerson, sessions: string[], instructions?: string): {
     to: string;
     brief: string;
 };
+/** A request's refs as episode references: an `owner/repo#n` becomes its issue link, anything else stays as written. */
+export declare function episodeReferences(record: ConnectorRecord): string[];
 export declare function executeApproved(record: ConnectorRecord, approver: MiadiPerson, deps: ApprovalDeps, instructions?: string): Promise<Record<string, unknown>>;
 /**
  * Record a person's decision on a request and, when approved, run it once as
@@ -62,6 +52,8 @@ export declare function executeApproved(record: ConnectorRecord, approver: Miadi
 /** A request is decided once: a second decision while one runs, or after it, is refused. */
 export declare class AlreadyDecided extends Error {
 }
+/** Whether a decision on this request is being recorded now, its run may still be going. */
+export declare function isBeingDecided(recordId: string): boolean;
 export declare function decide(r: ConnectorRecord, person: MiadiPerson, choice: Decision, deps: ApprovalDeps, opts: {
     instructions?: string;
     note?: string;
@@ -71,9 +63,34 @@ export declare function decide(r: ConnectorRecord, person: MiadiPerson, choice:
     state: ConnectorRecord["state"];
     receipt: Record<string, unknown>;
 }>;
+/** Whether a request was approved and its run failed, so a person may run it again. */
+export declare function isRerunnable(r: ConnectorRecord | undefined): boolean;
+/**
+ * Run an approved request again when its run failed (state `blocked`): a door
+ * it called was down or refused, and was fixed since. It runs as the person
+ * who asks, with the instructions it was approved with. The approval stays the
+ * decider's; the new receipt names who ran it again and keeps the failed
+ * outcome it replaces. jgwill/Miadi#884
+ */
+export declare function rerun(r: ConnectorRecord, person: MiadiPerson, deps: ApprovalDeps, opts: {
+    via: string;
+}): Promise<{
+    decision: "approved";
+    state: ConnectorRecord["state"];
+    receipt: Record<string, unknown>;
+}>;
 export declare function isApprovable(r: ConnectorRecord | undefined): r is ConnectorRecord;
 /** What approving a request does, in one sentence, for the card a person decides on. */
 export declare function consequenceOf(r: ConnectorRecord): string;
 export declare function registerApprovalRoutes(app: Express, deps: ApprovalDeps): void;
+/** The request, and the decision form for a write-tier person (their token carried in the form they just signed into). */
+/**
+ * Where a request stands, as every surface of the connector reads it (request-state.ts):
+ * the factory queue is read for the two kinds that dispatch a brief.
+ */
+export declare function requestProjection(record: ConnectorRecord, opts?: {
+    reviewBase?: string;
+    factoryDir?: string;
+}): RequestProjection | null;
 /** How a request is named to a person. */
 export declare const KIND_LABELS: Record<string, string>;

package/dist/approve.js

@@ -10,49 +10,22 @@
  * is appended as a record that supersedes the request (state, approval, receipt).
  */
 import express from "express";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { escapeHtml } from "@miadi/node-service-kit/format";
 import { MiadiError } from "./miadi.js";
 import { MiadiUnavailable } from "./people.js";
 import { current, newRecordId } from "./records.js";
-const APPROVABLE = new Set([
-    "run_request",
-    "review_operation_request",
-    "deep_diver_request",
-    "review_episode_link_request",
-    "work_proposal",
-    "session_completion_proposal",
-    "inquiry_episode_request",
-]);
+import { APPROVABLE, projectRequest } from "./request-state.js";
+import { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
+export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 /**
  * What a person may decide on a request. Approving with changes runs it with the
  * approver's instructions carried into what runs; a revision sends it back to
  * whoever asked, with instructions, and runs nothing.
  */
 export const DECISIONS = ["approve", "approve_with_changes", "request_revision", "decline"];
-export function factoryDir(env = process.env) {
-    return env.MIADI_FACTORY_DIR || join(homedir(), ".miadi", "factory");
-}
-export function runBriefFile(record) {
-    return `connector-${record.id.replace(/[^\w-]/g, "-")}.md`;
-}
-/** Where a run request's brief is: waiting, delivered by the intake, cancelled, or not queued. */
-export function readQueueState(record, dir = factoryDir()) {
-    const file = runBriefFile(record);
-    const queue = join(dir, "queue");
-    if (existsSync(join(queue, file)))
-        return { state: "queued", file };
-    if (existsSync(join(queue, "delivered", file)))
-        return { state: "delivered", file };
-    if (existsSync(join(queue, "cancelled", file)))
-        return { state: "cancelled", file };
-    if (existsSync(join(queue, "stale", file)))
-        return { state: "stale", file, note: "Its seat did not take it in time; the intake moved it aside." };
-    return { state: record.approval_state === "approved" ? "missing" : "not_queued", file };
-}
 function liveTmux() {
     try {
         return execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] })
@@ -133,6 +106,13 @@ function plainName(name) {
     const n = name.replace(/[^\w .'-]/g, "").trim().slice(0, 40);
     return /^[^\W_]/.test(n) ? n : "Miadi connector";
 }
+/** A request's refs as episode references: an `owner/repo#n` becomes its issue link, anything else stays as written. */
+export function episodeReferences(record) {
+    return (record.refs ?? []).map((ref) => {
+        const m = /^([\w.-]+)\/([\w.-]+)#(\d+)$/.exec(ref);
+        return m ? `https://github.com/${m[1]}/${m[2]}/issues/${m[3]}` : ref;
+    });
+}
 export async function executeApproved(record, approver, deps, instructions) {
     const f = deps.fetchImpl ?? fetch;
     const b = record.body;
@@ -198,7 +178,9 @@ export async function executeApproved(record, approver, deps, instructions) {
             const inquiry = { artefact: b.artefact, ...(b.issue ? { issue: b.issue } : {}) };
             try {
                 if (b.new_episode) {
-                    const res = await deps.miadi.request(approver.token, "POST", "/api/chronicle/episodes", { title: b.new_episode.title, ...(b.new_episode.goal ? { goal: b.new_episode.goal } : {}), inquiry }, 120_000);
+                    const res = await deps.miadi.request(approver.token, "POST", "/api/chronicle/episodes", 
+                    // The mint needs at least one reference: the request's own refs, an owner/repo#n made a link (jgwill/Miadi#884).
+                    { title: b.new_episode.title, ...(b.new_episode.goal ? { goal: b.new_episode.goal } : {}), inquiry, references: episodeReferences(record) }, 120_000);
                     return { outcome: "minted_and_woven", response: res };
                 }
                 const res = await deps.miadi.request(approver.token, "POST", `/api/chronicle/episodes/${encodeURIComponent(b.episode)}/inquiry`, inquiry, 120_000);
@@ -272,6 +254,10 @@ ${r.refs.length ? `<dt>References</dt><dd>${r.refs.map(escapeHtml).join("<br>")}
 export class AlreadyDecided extends Error {
 }
 const deciding = new Set();
+/** Whether a decision on this request is being recorded now, its run may still be going. */
+export function isBeingDecided(recordId) {
+    return deciding.has(recordId);
+}
 export async function decide(r, person, choice, deps, opts) {
     // Checked again here, with no await between the check and the claim: the
     // page and the card (or two cards) may decide the same request at once.
@@ -287,6 +273,68 @@ export async function decide(r, person, choice, deps, opts) {
         deciding.delete(r.id);
     }
 }
+/** Whether a request was approved and its run failed, so a person may run it again. */
+export function isRerunnable(r) {
+    return !!r && r.approval_state === "approved" && r.state === "blocked";
+}
+/**
+ * Run an approved request again when its run failed (state `blocked`): a door
+ * it called was down or refused, and was fixed since. It runs as the person
+ * who asks, with the instructions it was approved with. The approval stays the
+ * decider's; the new receipt names who ran it again and keeps the failed
+ * outcome it replaces. jgwill/Miadi#884
+ */
+export async function rerun(r, person, deps, opts) {
+    const live = current(deps.ledger.all()).find((x) => x.id === r.id);
+    if (!isRerunnable(live) || deciding.has(r.id)) {
+        throw new AlreadyDecided(deciding.has(r.id) ? "This request is being run." : `This request is ${live?.approval_state ?? "gone"} and ${live?.state ?? "unknown"}; only an approved request whose run failed is run again.`);
+    }
+    deciding.add(r.id);
+    try {
+        const prior = (live.completion_receipt ?? {});
+        const instructions = typeof prior.instructions === "string" ? prior.instructions : undefined;
+        let receipt = {
+            decided_by: prior.decided_by,
+            decided_at: prior.decided_at,
+            decision: prior.decision,
+            ...(instructions ? { instructions } : {}),
+            rerun_by: { person_id: person.id, name: person.name },
+            rerun_at: new Date().toISOString(),
+            via: opts.via,
+            replaces: { outcome: prior.outcome, ...(prior.status !== undefined ? { status: prior.status } : {}), ...(prior.response !== undefined ? { response: prior.response } : {}) },
+        };
+        let state = "completed";
+        try {
+            const outcome = await executeApproved(live, person, deps, instructions);
+            receipt = { ...receipt, ...outcome };
+            if (outcome.outcome === "failed")
+                state = "blocked";
+            if (outcome.outcome === "queued")
+                state = "in_progress";
+        }
+        catch (error) {
+            receipt = { ...receipt, outcome: "failed", message: error instanceof Error ? error.message : String(error) };
+            state = "blocked";
+        }
+        deps.ledger.append({
+            id: newRecordId(r.kind),
+            kind: r.kind,
+            created_at: new Date().toISOString(),
+            actor: { person_id: person.id, name: person.name, client_id: opts.via },
+            refs: r.refs,
+            evidence_refs: [],
+            supersedes: r.id,
+            approval_state: "approved",
+            state,
+            completion_receipt: receipt,
+            body: { decision: "rerun" },
+        });
+        return { decision: "approved", state, receipt };
+    }
+    finally {
+        deciding.delete(r.id);
+    }
+}
 async function decideOnce(r, person, choice, deps, opts) {
     const { instructions } = opts;
     const decision = choice === "approve" || choice === "approve_with_changes" ? "approved" : choice === "request_revision" ? "revision_requested" : "declined";
@@ -388,11 +436,24 @@ export function registerApprovalRoutes(app, deps) {
             return void res.status(403).type("html").send(signInToRead(r, `Reading and deciding this request needs Miadi's write tier; ${person.name} has ${person.api_tier ?? "no API tier"}.`));
         }
         if (!body.decision)
-            return void res.type("html").send(approvePage(r, { token: writer ? token : undefined }));
+            return void res.type("html").send(approvePage(deps, r, { token: writer ? token : undefined }));
         if (!writer)
-            return void res.status(403).type("html").send(approvePage(r, { error: `Deciding needs Miadi's write tier; ${person.name} has ${person.api_tier ?? "no API tier"}.` }));
+            return void res.status(403).type("html").send(approvePage(deps, r, { error: `Deciding needs Miadi's write tier; ${person.name} has ${person.api_tier ?? "no API tier"}.` }));
+        if (body.decision === "rerun") {
+            let ran;
+            try {
+                ran = await rerun(r, person, deps, { via: String(body.via ?? "approval-page").slice(0, 60) });
+            }
+            catch (error) {
+                if (error instanceof AlreadyDecided)
+                    return void res.status(409).type("html").send(approvePage(deps, find(r.id), { token, error: error.message }));
+                throw error;
+            }
+            const failedAgain = ran.receipt.outcome === "failed";
+            return void res.type("html").send(page("Recorded", `<h1>${failedAgain ? "Run again, and it failed again" : "Run again"}</h1>${summary(find(r.id))}<pre>${escapeHtml(JSON.stringify(ran.receipt, null, 2))}</pre>`));
+        }
         if (r.approval_state !== "awaiting_approval") {
-            return void res.status(409).type("html").send(approvePage(r, { error: `This request is already ${r.approval_state}.` }));
+            return void res.status(409).type("html").send(approvePage(deps, r, { error: `This request is already ${r.approval_state}.` }));
         }
         const choice = DECISIONS.includes(String(body.decision)) ? body.decision : "decline";
         const instructions = String(body.instructions ?? "").trim().slice(0, 20000) || undefined;
@@ -400,7 +461,7 @@ export function registerApprovalRoutes(app, deps) {
             return void res
                 .status(400)
                 .type("html")
-                .send(approvePage(r, { token, error: choice === "request_revision" ? "Say what to revise." : "Write the changes to apply." }));
+                .send(approvePage(deps, r, { token, error: choice === "request_revision" ? "Say what to revise." : "Write the changes to apply." }));
         }
         let decided;
         try {
@@ -408,13 +469,21 @@ export function registerApprovalRoutes(app, deps) {
         }
         catch (error) {
             if (error instanceof AlreadyDecided)
-                return void res.status(409).type("html").send(approvePage(find(r.id), { error: error.message }));
+                return void res.status(409).type("html").send(approvePage(deps, find(r.id), { error: error.message }));
             throw error;
         }
         const { decision, receipt } = decided;
-        const failed = receipt.outcome === "failed";
-        const heading = decision === "approved" ? (failed ? "Approved, but running it failed" : "Approved") : decision === "revision_requested" ? "Sent back for revision" : "Declined";
-        res.type("html").send(page("Recorded", `<h1>${heading}</h1>${summary(find(r.id))}<pre>${escapeHtml(JSON.stringify(receipt, null, 2))}</pre>`));
+        const p = projectionOf(find(r.id), deps);
+        const heading = decision === "approved"
+            ? p?.stage === "failed"
+                ? "Approved, but running it failed"
+                : p?.outstanding.length
+                    ? "Approved, changes still to do"
+                    : "Approved"
+            : decision === "revision_requested"
+                ? "Sent back for revision"
+                : "Declined";
+        res.type("html").send(page("Recorded", `<h1>${heading}</h1>${summary(find(r.id))}${projectionBlock(p, receipt)}`));
     });
     // A record's own page, for citations in ChatGPT: its author and anyone with Miadi's read tier may read it.
     app.get("/records/:id", (req, res) => {
@@ -448,9 +517,12 @@ ${error ? `<p class="err" role="alert">${escapeHtml(error)}</p>` : ""}
 <div class="row"><button class="primary" type="submit">Read</button></div></form>`;
 }
 function signInToRead(r, error) {
-    return page("A Miadi request awaits a decision", `<h1>A request awaits a decision</h1>
-<p>${escapeHtml(KIND_LABELS[r.kind] ?? r.kind)}, asked ${escapeHtml(r.created_at.slice(0, 16).replace("T", " "))} UTC. State: ${escapeHtml(r.approval_state ?? "—")}.</p>
-<p>Sign in to read it. A person with Miadi's write tier then decides; whoever asked can read it.</p>
+    // The label names no one and no instruction: this page is shown before sign-in.
+    const open = r.approval_state === "awaiting_approval";
+    const label = projectRequest(r, { recording: isBeingDecided(r.id) })?.label ?? r.approval_state ?? "";
+    return page(open ? "A Miadi request awaits a decision" : "A Miadi request was decided", `<h1>${open ? "A request awaits a decision" : "A request was decided"}</h1>
+<p>${escapeHtml(KIND_LABELS[r.kind] ?? r.kind)}, asked ${escapeHtml(r.created_at.slice(0, 16).replace("T", " "))} UTC. ${escapeHtml(label)}.</p>
+<p>${open ? "Sign in to read it. A person with Miadi's write tier then decides; whoever asked can read it." : "Sign in to read what was decided and what came of it. Whoever asked, and anyone with Miadi's write tier, can read it."}</p>
 ${error ? `<p class="err" role="alert">${escapeHtml(error)}</p>` : ""}
 <form method="post">
 <label for="t">Your Miadi person token</label>
@@ -459,13 +531,41 @@ ${error ? `<p class="err" role="alert">${escapeHtml(error)}</p>` : ""}
 </form>`);
 }
 /** The request, and the decision form for a write-tier person (their token carried in the form they just signed into). */
-function approvePage(r, o = {}) {
-    return page("Approve a Miadi request", `<h1>Approve a request</h1>
-<p>${escapeHtml(consequenceOf(r))} Declining records your refusal. Either is kept in the ledger with your name.</p>
+/**
+ * Where a request stands, as every surface of the connector reads it (request-state.ts):
+ * the factory queue is read for the two kinds that dispatch a brief.
+ */
+export function requestProjection(record, opts = {}) {
+    const queue = record.kind === "run_request" || record.kind === "work_proposal" ? readQueueState(record, opts.factoryDir ?? factoryDir()) : undefined;
+    return projectRequest(record, {
+        ...(opts.reviewBase ? { reviewBase: opts.reviewBase } : {}),
+        ...(queue ? { queue } : {}),
+        recording: isBeingDecided(record.id),
+    });
+}
+function projectionOf(r, deps) {
+    return requestProjection(r, { reviewBase: deps.config.reviewUrl, factoryDir: deps.factoryDir });
+}
+/** Where a request stands, as a page shows it: the label, each line, the review it produced, and the receipt for audit. */
+function projectionBlock(p, receipt) {
+    if (!p)
+        return "";
+    const lines = p.lines.map((l) => `<li>${escapeHtml(l)}</li>`).join("");
+    const review = p.receipt_url ? `<p><a href="${escapeHtml(p.receipt_url)}" rel="noopener">${escapeHtml(p.receipt_url)}</a></p>` : "";
+    const audit = receipt ? `<details><summary>Receipt</summary><pre>${escapeHtml(JSON.stringify(receipt, null, 2))}</pre></details>` : "";
+    return `<section aria-label="Where it stands"><p><strong>${escapeHtml(p.label)}</strong></p>${lines ? `<ul>${lines}</ul>` : ""}${review}${audit}</section>`;
+}
+/** The request, and the decision form for a write-tier person (their token carried in the form they just signed into). */
+function approvePage(deps, r, o = {}) {
+    const open = r.approval_state === "awaiting_approval";
+    // A decision being recorded offers no buttons: a second click would decide the same request again.
+    const actionable = open && !isBeingDecided(r.id);
+    return page("Approve a Miadi request", `<h1>${open ? "Approve a request" : "A decided request"}</h1>
+${actionable ? `<p>${escapeHtml(consequenceOf(r))} Declining records your refusal. Either is kept in the ledger with your name.</p>` : ""}
 ${summary(r)}
-${r.completion_receipt ? `<pre>${escapeHtml(JSON.stringify(r.completion_receipt, null, 2))}</pre>` : ""}
+${projectionBlock(projectionOf(r, deps), open ? undefined : r.completion_receipt)}
 ${o.error ? `<p class="err" role="alert">${escapeHtml(o.error)}</p>` : ""}
-${r.approval_state === "awaiting_approval" && o.token
+${actionable && o.token
         ? `<form method="post">
 <input type="hidden" name="person_token" value="${escapeHtml(o.token)}">
 <label for="i">Instructions (needed to approve with changes or to send back)</label>
@@ -476,9 +576,14 @@ ${r.approval_state === "awaiting_approval" && o.token
 <button type="submit" name="decision" value="request_revision">Send back for revision</button>
 <button type="submit" name="decision" value="decline">Decline</button>
 </div></form>`
-        : r.approval_state === "awaiting_approval"
+        : actionable
             ? "<p>A person with Miadi's write tier decides this request.</p>"
-            : ""}`);
+            : isRerunnable(r) && o.token
+                ? `<p>It was approved, and running it failed. When what it calls has been fixed, it can be run again with the same approval and instructions; the ledger records who ran it again.</p>
+<form method="post">
+<input type="hidden" name="person_token" value="${escapeHtml(o.token)}">
+<div class="row"><button class="primary" type="submit" name="decision" value="rerun">Run it again</button></div></form>`
+                : ""}`);
 }
 /** How a request is named to a person. */
 export const KIND_LABELS = {

package/dist/decisions.d.ts

@@ -15,4 +15,4 @@ export declare class DecisionTokens {
  * and calls `decide_request` through the host. In a host without that bridge it
  * shows each request's approval page instead.
  */
-export declare const DECISIONS_CARD_HTML = "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<style>\n:root{color-scheme:light dark;--fg:#1d1b18;--muted:#5b5650;--line:#d9d4cc;--accent:#7a4a00;--ok:#1d6b3a;--err:#b00020;--chip:#f1ede6}\n@media (prefers-color-scheme:dark){:root{--fg:#ece8e1;--muted:#b3ada4;--line:#3a3631;--accent:#ffd700;--ok:#7fd49b;--err:#ff8a80;--chip:#24211d}}\n*{box-sizing:border-box}\nbody{margin:0;color:var(--fg);font:15px/1.45 system-ui,sans-serif;background:transparent}\nmain{padding:12px;display:grid;gap:12px}\n.empty,.note{color:var(--muted)}\narticle{border:1px solid var(--line);border-radius:10px;padding:12px}\nh2{font-size:15px;margin:0 0 4px}\n.kind{display:inline-block;font-size:12px;padding:1px 8px;border-radius:999px;background:var(--chip);color:var(--muted);margin-bottom:6px}\n.meta{font-size:13px;color:var(--muted);margin:0 0 6px}\n.does{margin:6px 0;font-weight:600}\ndetails{margin:6px 0}\nsummary{cursor:pointer;color:var(--muted);font-size:13px}\npre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;margin:6px 0 0;max-height:240px;overflow:auto}\ntextarea{width:100%;min-height:64px;padding:8px;border:1px solid var(--line);border-radius:8px;background:transparent;color:var(--fg);font:inherit;margin-top:8px}\n.row{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}\nbutton{padding:8px 12px;border-radius:8px;border:1px solid var(--line);background:transparent;color:var(--fg);font:inherit;cursor:pointer;min-height:40px}\nbutton.primary{border-color:var(--accent);outline:1px solid var(--accent)}\nbutton:focus-visible,a:focus-visible,textarea:focus-visible{outline:2px solid var(--accent);outline-offset:2px}\nbutton[disabled]{opacity:.55;cursor:default}\na{color:inherit}\n.done{color:var(--ok);font-weight:600}\n.fail{color:var(--err);font-weight:600}\n</style></head><body><main id=\"root\" aria-live=\"polite\"><p class=\"note\">Loading requests\u2026</p></main>\n<script>\n(function(){\n  var root=document.getElementById(\"root\");\n  var decided={};\n  // A redraw while a decision is being recorded must not offer the buttons again.\n  var pending={};\n  var errors={};\n  function el(tag,attrs,text){var e=document.createElement(tag);if(attrs)for(var k in attrs){if(k===\"class\")e.className=attrs[k];else e.setAttribute(k,attrs[k]);}if(text!=null)e.textContent=text;return e;}\n  function host(){return window.openai||null;}\n  function data(){var h=host();return h&&h.toolOutput?h.toolOutput:null;}\n  function tokens(){var h=host();var m=h&&h.toolResponseMetadata;return (m&&m[\"miadi/decisionTokens\"])||{};}\n  function render(){\n    var d=data();root.textContent=\"\";\n    if(!d){root.appendChild(el(\"p\",{class:\"note\"},\"Waiting for the request list.\"));return;}\n    var list=d.decisions||[];\n    if(!list.length){root.appendChild(el(\"p\",{class:\"empty\"},d.message||\"No request is waiting for a decision.\"));return;}\n    if(!d.can_decide_here&&d.reason){root.appendChild(el(\"p\",{class:\"note\"},d.reason));}\n    var t=tokens();\n    list.forEach(function(r){root.appendChild(card(r,t[r.id]));});\n  }\n  function card(r,token){\n    var a=el(\"article\",{\"aria-label\":r.title});\n    a.appendChild(el(\"span\",{class:\"kind\"},r.kind_label||r.kind));\n    a.appendChild(el(\"h2\",null,r.title));\n    a.appendChild(el(\"p\",{class:\"meta\"},\"Asked by \"+r.by+(r.via?\" through \"+r.via:\"\")+\" \u00B7 \"+new Date(r.created_at).toLocaleString()+(r.circle?\" \u00B7 \"+r.circle+\" circle\":\"\")));\n    a.appendChild(el(\"p\",{class:\"does\"},r.consequence));\n    if(r.intention)a.appendChild(el(\"p\",null,r.intention));\n    var det=el(\"details\");det.appendChild(el(\"summary\",null,\"What exactly is asked\"));det.appendChild(el(\"pre\",null,r.detail||\"\"));a.appendChild(det);\n    var status=el(\"p\",{role:\"status\"});\n    if(decided[r.id]){status.className=decided[r.id].ok?\"done\":\"fail\";status.textContent=decided[r.id].text;a.appendChild(status);return a;}\n    if(pending[r.id]){status.className=\"note\";status.textContent=\"Recording your decision\u2026\";a.appendChild(status);return a;}\n    if(!token||!host()||!host().callTool){\n      var p=el(\"p\",{class:\"note\"});p.appendChild(document.createTextNode(\"Decide on its approval page: \"));\n      var link=el(\"a\",{href:r.approval_url,target:\"_blank\",rel:\"noopener\"},\"open the approval page\");p.appendChild(link);a.appendChild(p);return a;\n    }\n    var ta=el(\"textarea\",{\"aria-label\":\"Instructions or changes (needed to approve with changes or send back)\",placeholder:\"Instructions or changes (needed to approve with changes or send back)\"});\n    a.appendChild(ta);\n    var row=el(\"div\",{class:\"row\"});\n    var buttons=[[\"approve\",\"Approve\",\"primary\"],[\"approve_with_changes\",\"Approve with my changes\",\"\"],[\"request_revision\",\"Send back for revision\",\"\"],[\"decline\",\"Decline\",\"\"]];\n    var btns=[];\n    buttons.forEach(function(b){var x=el(\"button\",{type:\"button\",class:b[2]},b[1]);x.addEventListener(\"click\",function(){go(b[0]);});btns.push(x);row.appendChild(x);});\n    a.appendChild(row);a.appendChild(status);\n    if(errors[r.id]){status.className=\"fail\";status.textContent=errors[r.id];}\n    function go(choice){\n      var text=ta.value.trim();\n      if((choice===\"approve_with_changes\"||choice===\"request_revision\")&&!text){status.className=\"fail\";status.textContent=choice===\"request_revision\"?\"Say what to revise.\":\"Write the changes to apply.\";ta.focus();return;}\n      btns.forEach(function(x){x.disabled=true;});status.className=\"note\";status.textContent=\"Recording your decision\u2026\";pending[r.id]=true;delete errors[r.id];\n      host().callTool(\"decide_request\",{record_id:r.id,decision:choice,instructions:text||undefined,decision_token:token}).then(function(res){\n        var out=(res&&(res.structuredContent||res.structured_content))||null;\n        if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}\n        var ok=out&&!out.error;\n        delete pending[r.id];decided[r.id]={ok:ok,text:ok?(out.summary||\"Recorded.\"):((out&&out.message)||\"Not recorded.\")};render();\n      },function(err){delete pending[r.id];errors[r.id]=\"Not recorded: \"+(err&&err.message?err.message:String(err));render();});\n    }\n    return a;\n  }\n  window.addEventListener(\"openai:set_globals\",render);\n  render();\n})();\n</script></body></html>";
+export declare const DECISIONS_CARD_HTML = "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<style>\n:root{color-scheme:light dark;--fg:#1d1b18;--muted:#5b5650;--line:#d9d4cc;--accent:#7a4a00;--ok:#1d6b3a;--err:#b00020;--chip:#f1ede6}\n@media (prefers-color-scheme:dark){:root{--fg:#ece8e1;--muted:#b3ada4;--line:#3a3631;--accent:#ffd700;--ok:#7fd49b;--err:#ff8a80;--chip:#24211d}}\n*{box-sizing:border-box}\nbody{margin:0;color:var(--fg);font:15px/1.45 system-ui,sans-serif;background:transparent}\nmain{padding:12px;display:grid;gap:12px}\n.empty,.note{color:var(--muted)}\narticle{border:1px solid var(--line);border-radius:10px;padding:12px}\nh2{font-size:15px;margin:0 0 4px}\n.kind{display:inline-block;font-size:12px;padding:1px 8px;border-radius:999px;background:var(--chip);color:var(--muted);margin-bottom:6px}\n.meta{font-size:13px;color:var(--muted);margin:0 0 6px}\n.does{margin:6px 0;font-weight:600}\ndetails{margin:6px 0}\nsummary{cursor:pointer;color:var(--muted);font-size:13px}\npre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;margin:6px 0 0;max-height:240px;overflow:auto}\ntextarea{width:100%;min-height:64px;padding:8px;border:1px solid var(--line);border-radius:8px;background:transparent;color:var(--fg);font:inherit;margin-top:8px}\n.row{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}\nbutton{padding:8px 12px;border-radius:8px;border:1px solid var(--line);background:transparent;color:var(--fg);font:inherit;cursor:pointer;min-height:40px}\nbutton.primary{border-color:var(--accent);outline:1px solid var(--accent)}\nbutton:focus-visible,a:focus-visible,textarea:focus-visible{outline:2px solid var(--accent);outline-offset:2px}\nbutton[disabled]{opacity:.55;cursor:default}\na{color:inherit}\n.done{color:var(--ok);font-weight:600}\n.fail{color:var(--err);font-weight:600}\n</style></head><body><main id=\"root\" aria-live=\"polite\"><p class=\"note\">Loading requests\u2026</p></main>\n<script>\n(function(){\n  var root=document.getElementById(\"root\");\n  var decided={};\n  // A redraw while a decision is being recorded must not offer the buttons again.\n  var pending={};\n  var errors={};\n  function el(tag,attrs,text){var e=document.createElement(tag);if(attrs)for(var k in attrs){if(k===\"class\")e.className=attrs[k];else e.setAttribute(k,attrs[k]);}if(text!=null)e.textContent=text;return e;}\n  function host(){return window.openai||null;}\n  function data(){var h=host();return h&&h.toolOutput?h.toolOutput:null;}\n  function tokens(){var h=host();var m=h&&h.toolResponseMetadata;return (m&&m[\"miadi/decisionTokens\"])||{};}\n  function render(){\n    var d=data();root.textContent=\"\";\n    if(!d){root.appendChild(el(\"p\",{class:\"note\"},\"Waiting for the request list.\"));return;}\n    var list=d.decisions||[];\n    if(!list.length){root.appendChild(el(\"p\",{class:\"empty\"},d.message||\"No request is waiting for a decision.\"));return;}\n    if(!d.can_decide_here&&d.reason){root.appendChild(el(\"p\",{class:\"note\"},d.reason));}\n    var t=tokens();\n    list.forEach(function(r){root.appendChild(card(r,t[r.id]));});\n  }\n  // Where a request stands, as the connector projected it: the label, its lines, and the review it produced.\n  function decidedBlock(d){\n    var box=el(\"div\",{role:\"status\",class:d.cls});\n    if(d.note)box.appendChild(el(\"p\",{class:\"line\"},d.note));\n    box.appendChild(el(\"p\",{class:\"label\"},d.label));\n    (d.lines||[]).forEach(function(l){box.appendChild(el(\"p\",{class:\"line\"},l));});\n    if(d.url){var p=el(\"p\",{class:\"line\"});p.appendChild(el(\"a\",{href:d.url,target:\"_blank\",rel:\"noopener\"},d.url));box.appendChild(p);}\n    return box;\n  }\n  function toolResult(res){\n    var out=(res&&(res.structuredContent||res.structured_content))||null;\n    if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}\n    return out;\n  }\n  function projectionView(p,note){return {cls:p.stage===\"failed\"?\"fail\":\"done\",stage:p.stage,label:p.label,lines:p.lines||[],url:p.receipt_url||null,note:note||null};}\n  function card(r,token){\n    var a=el(\"article\",{\"aria-label\":r.title});\n    a.appendChild(el(\"span\",{class:\"kind\"},r.kind_label||r.kind));\n    a.appendChild(el(\"h2\",null,r.title));\n    a.appendChild(el(\"p\",{class:\"meta\"},\"Asked by \"+r.by+(r.via?\" through \"+r.via:\"\")+\" \u00B7 \"+new Date(r.created_at).toLocaleString()+(r.circle?\" \u00B7 \"+r.circle+\" circle\":\"\")));\n    a.appendChild(el(\"p\",{class:\"does\"},r.consequence));\n    if(r.intention)a.appendChild(el(\"p\",null,r.intention));\n    var det=el(\"details\");det.appendChild(el(\"summary\",null,\"What exactly is asked\"));det.appendChild(el(\"pre\",null,r.detail||\"\"));a.appendChild(det);\n    var status=el(\"p\",{role:\"status\"});\n    if(r.projection&&r.projection.stage!==\"awaiting_decision\"&&(!decided[r.id]||[\"recording\",\"dispatching\"].indexOf(r.projection.stage)===-1)){decided[r.id]=projectionView(r.projection);}\n    if(decided[r.id]){\n      var shown=decided[r.id];a.appendChild(decidedBlock(shown));\n      if([\"recording\",\"dispatching\"].indexOf(shown.stage)!==-1&&host()&&host().callTool){\n        var refresh=el(\"button\",{type:\"button\"},\"Refresh status\");\n        refresh.addEventListener(\"click\",function(){\n          refresh.disabled=true;\n          host().callTool(\"get_run_result\",{record_id:r.id}).then(function(res){\n            var out=toolResult(res);var p=out&&(out.projection||(out.data&&out.data.projection));\n            if(p){decided[r.id]=projectionView(p);delete errors[r.id];}\n            else{errors[r.id]=(out&&out.message)||\"Status could not be refreshed.\";}\n            render();\n          },function(err){errors[r.id]=\"Status could not be refreshed: \"+String(err&&err.message||err);render();});\n        });\n        a.appendChild(refresh);\n      }\n      if(errors[r.id])a.appendChild(el(\"p\",{class:\"fail\",role:\"status\"},errors[r.id]));\n      return a;\n    }\n    if(pending[r.id]){status.className=\"note\";status.textContent=\"Recording your decision\u2026\";a.appendChild(status);return a;}\n    if(!token||!host()||!host().callTool){\n      var p=el(\"p\",{class:\"note\"});p.appendChild(document.createTextNode(\"Decide on its approval page: \"));\n      var link=el(\"a\",{href:r.approval_url,target:\"_blank\",rel:\"noopener\"},\"open the approval page\");p.appendChild(link);a.appendChild(p);return a;\n    }\n    var ta=el(\"textarea\",{\"aria-label\":\"Instructions or changes (needed to approve with changes or send back)\",placeholder:\"Instructions or changes (needed to approve with changes or send back)\"});\n    a.appendChild(ta);\n    var row=el(\"div\",{class:\"row\"});\n    var buttons=[[\"approve\",\"Approve\",\"primary\"],[\"approve_with_changes\",\"Approve with my changes\",\"\"],[\"request_revision\",\"Send back for revision\",\"\"],[\"decline\",\"Decline\",\"\"]];\n    var btns=[];\n    buttons.forEach(function(b){var x=el(\"button\",{type:\"button\",class:b[2]},b[1]);x.addEventListener(\"click\",function(){go(b[0]);});btns.push(x);row.appendChild(x);});\n    a.appendChild(row);a.appendChild(status);\n    if(errors[r.id]){status.className=\"fail\";status.textContent=errors[r.id];}\n    function go(choice){\n      var text=ta.value.trim();\n      if((choice===\"approve_with_changes\"||choice===\"request_revision\")&&!text){status.className=\"fail\";status.textContent=choice===\"request_revision\"?\"Say what to revise.\":\"Write the changes to apply.\";ta.focus();return;}\n      btns.forEach(function(x){x.disabled=true;});status.className=\"note\";status.textContent=\"Recording your decision\u2026\";pending[r.id]=true;delete errors[r.id];\n      host().callTool(\"decide_request\",{record_id:r.id,decision:choice,instructions:text||undefined,decision_token:token}).then(function(res){\n        var out=toolResult(res);\n        // The connector answers with the request's projection, also when a click finds it decided already.\n        var proj=out&&out.projection;\n        var already=!!(out&&out.error===\"already_decided\");\n        var ok=out&&!out.error;\n        delete pending[r.id];\n        if(proj){decided[r.id]=projectionView(proj,already?\"This request was already decided. Here is where it stands.\":null);}\n        else{decided[r.id]={cls:ok?\"done\":\"fail\",label:ok?(out.summary||\"Recorded.\"):((out&&out.message)||\"Not recorded.\"),lines:[],url:null,note:null};}\n        render();\n      },function(err){delete pending[r.id];errors[r.id]=\"Not recorded: \"+(err&&err.message?err.message:String(err));render();});\n    }\n    return a;\n  }\n  window.addEventListener(\"openai:set_globals\",render);\n  render();\n})();\n</script></body></html>";

package/dist/decisions.js

@@ -102,6 +102,21 @@ a{color:inherit}
     var t=tokens();
     list.forEach(function(r){root.appendChild(card(r,t[r.id]));});
   }
+  // Where a request stands, as the connector projected it: the label, its lines, and the review it produced.
+  function decidedBlock(d){
+    var box=el("div",{role:"status",class:d.cls});
+    if(d.note)box.appendChild(el("p",{class:"line"},d.note));
+    box.appendChild(el("p",{class:"label"},d.label));
+    (d.lines||[]).forEach(function(l){box.appendChild(el("p",{class:"line"},l));});
+    if(d.url){var p=el("p",{class:"line"});p.appendChild(el("a",{href:d.url,target:"_blank",rel:"noopener"},d.url));box.appendChild(p);}
+    return box;
+  }
+  function toolResult(res){
+    var out=(res&&(res.structuredContent||res.structured_content))||null;
+    if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}
+    return out;
+  }
+  function projectionView(p,note){return {cls:p.stage==="failed"?"fail":"done",stage:p.stage,label:p.label,lines:p.lines||[],url:p.receipt_url||null,note:note||null};}
   function card(r,token){
     var a=el("article",{"aria-label":r.title});
     a.appendChild(el("span",{class:"kind"},r.kind_label||r.kind));
@@ -111,7 +126,25 @@ a{color:inherit}
     if(r.intention)a.appendChild(el("p",null,r.intention));
     var det=el("details");det.appendChild(el("summary",null,"What exactly is asked"));det.appendChild(el("pre",null,r.detail||""));a.appendChild(det);
     var status=el("p",{role:"status"});
-    if(decided[r.id]){status.className=decided[r.id].ok?"done":"fail";status.textContent=decided[r.id].text;a.appendChild(status);return a;}
+    if(r.projection&&r.projection.stage!=="awaiting_decision"&&(!decided[r.id]||["recording","dispatching"].indexOf(r.projection.stage)===-1)){decided[r.id]=projectionView(r.projection);}
+    if(decided[r.id]){
+      var shown=decided[r.id];a.appendChild(decidedBlock(shown));
+      if(["recording","dispatching"].indexOf(shown.stage)!==-1&&host()&&host().callTool){
+        var refresh=el("button",{type:"button"},"Refresh status");
+        refresh.addEventListener("click",function(){
+          refresh.disabled=true;
+          host().callTool("get_run_result",{record_id:r.id}).then(function(res){
+            var out=toolResult(res);var p=out&&(out.projection||(out.data&&out.data.projection));
+            if(p){decided[r.id]=projectionView(p);delete errors[r.id];}
+            else{errors[r.id]=(out&&out.message)||"Status could not be refreshed.";}
+            render();
+          },function(err){errors[r.id]="Status could not be refreshed: "+String(err&&err.message||err);render();});
+        });
+        a.appendChild(refresh);
+      }
+      if(errors[r.id])a.appendChild(el("p",{class:"fail",role:"status"},errors[r.id]));
+      return a;
+    }
     if(pending[r.id]){status.className="note";status.textContent="Recording your decision…";a.appendChild(status);return a;}
     if(!token||!host()||!host().callTool){
       var p=el("p",{class:"note"});p.appendChild(document.createTextNode("Decide on its approval page: "));
@@ -130,10 +163,15 @@ a{color:inherit}
       if((choice==="approve_with_changes"||choice==="request_revision")&&!text){status.className="fail";status.textContent=choice==="request_revision"?"Say what to revise.":"Write the changes to apply.";ta.focus();return;}
       btns.forEach(function(x){x.disabled=true;});status.className="note";status.textContent="Recording your decision…";pending[r.id]=true;delete errors[r.id];
       host().callTool("decide_request",{record_id:r.id,decision:choice,instructions:text||undefined,decision_token:token}).then(function(res){
-        var out=(res&&(res.structuredContent||res.structured_content))||null;
-        if(!out&&res&&res.content&&res.content[0]&&res.content[0].text){try{out=JSON.parse(res.content[0].text);}catch(e){out={message:res.content[0].text};}}
+        var out=toolResult(res);
+        // The connector answers with the request's projection, also when a click finds it decided already.
+        var proj=out&&out.projection;
+        var already=!!(out&&out.error==="already_decided");
         var ok=out&&!out.error;
-        delete pending[r.id];decided[r.id]={ok:ok,text:ok?(out.summary||"Recorded."):((out&&out.message)||"Not recorded.")};render();
+        delete pending[r.id];
+        if(proj){decided[r.id]=projectionView(proj,already?"This request was already decided. Here is where it stands.":null);}
+        else{decided[r.id]={cls:ok?"done":"fail",label:ok?(out.summary||"Recorded."):((out&&out.message)||"Not recorded."),lines:[],url:null,note:null};}
+        render();
       },function(err){delete pending[r.id];errors[r.id]="Not recorded: "+(err&&err.message?err.message:String(err));render();});
     }
     return a;

package/dist/queue-state.d.ts

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

package/dist/queue-state.js

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

package/dist/records.d.ts

@@ -87,4 +87,7 @@ export declare function newRecordId(kind: RecordKind): string;
  * Fold the ledger: a record superseded by a later one shows the later one's
  * state, approval and receipt, keeping its own id and history.
  */
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
+export type { RequestProjection, RequestStage, RequestStanding, RequestDecision, ProjectionContext } from "./request-state.js";
 export declare function current(records: ConnectorRecord[]): ConnectorRecord[];

package/dist/records.js

@@ -76,6 +76,8 @@ export function newRecordId(kind) {
  * Fold the ledger: a record superseded by a later one shows the later one's
  * state, approval and receipt, keeping its own id and history.
  */
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
 export function current(records) {
     const byId = new Map();
     for (const r of records) {

package/dist/request-state.d.ts

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

package/dist/request-state.js

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

package/dist/tools.js

@@ -16,7 +16,7 @@ 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, KIND_LABELS, consequenceOf, decide, isApprovable, readQueueState } from "./approve.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 { join } from "node:path";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
@@ -461,6 +461,8 @@ export function registerTools(server, ctx) {
             record: r,
             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 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"
                 ? { revision: { instructions: r.completion_receipt?.instructions, next: `Submit a revised request that cites ${r.id} in refs.` } }
                 : {}),
@@ -1083,9 +1085,9 @@ export function registerTools(server, ctx) {
             const { person, auth } = who(extra);
             const writer = person.api_tier === "write";
             const waiting = all()
-                .filter((r) => r.approval_state === "awaiting_approval" && isApprovable(r))
+                .filter((r) => isApprovable(r))
                 .filter((r) => writer || r.actor.person_id === person.id)
-                .filter((r) => !record_id || r.id === record_id)
+                .filter((r) => record_id ? r.id === record_id : r.approval_state === "awaiting_approval")
                 .slice(-20)
                 .reverse();
             const canDecide = writer && auth.scopes.includes(SCOPE_APPROVE) && Boolean(ctx.decisionTokens);
@@ -1107,17 +1109,20 @@ export function registerTools(server, ctx) {
                 consequence: consequenceOf(r),
                 detail: detailOf(r),
                 approval_url: approvalUrl(r.id),
+                projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             }));
-            const tokens = canDecide ? Object.fromEntries(waiting.map((r) => [r.id, ctx.decisionTokens.issue(r.id, person.id, auth.clientId)])) : {};
+            const actionable = decisions.filter((d) => d.projection?.stage === "awaiting_decision");
+            const tokens = canDecide ? Object.fromEntries(actionable.map((r) => [r.id, ctx.decisionTokens.issue(r.id, person.id, auth.clientId)])) : {};
             const structured = {
                 decisions,
                 count: decisions.length,
+                awaiting_count: actionable.length,
                 can_decide_here: canDecide,
                 ...(reason ? { reason } : {}),
                 ...(decisions.length ? {} : { message: record_id ? "That request is not awaiting a decision." : "No request is waiting for a decision." }),
             };
             const text = decisions.length
-                ? `${decisions.length} request(s) await a decision and are shown as cards. ${canDecide ? "The person decides each one on its card; do not decide or claim a decision for them." : reason}`
+                ? `${decisions.length} request(s) shown as cards; ${actionable.length} await a decision. ${canDecide ? "The person decides an awaiting request on its card; do not decide or claim a decision for them." : reason}`
                 : structured.message;
             return { structuredContent: structured, content: [{ type: "text", text }], _meta: { [DECISION_TOKENS_META]: tokens } };
         }
@@ -1153,28 +1158,43 @@ export function registerTools(server, ctx) {
             const check = ctx.decisionTokens.verify(a.decision_token, r.id, person.id, auth.clientId);
             if (check !== "ok")
                 throw new ToolRefusal(check === "expired" ? "token_expired" : "invalid_token", check === "expired" ? "This card is too old; show the requests again." : "This decision did not come from the person's card.");
-            if (r.approval_state !== "awaiting_approval")
-                throw new ToolRefusal("already_decided", `This request is already ${r.approval_state}.`);
+            // A stale card or a second client gets where the request stands, not a bare refusal (jgwill/Miadi#889).
+            const projectionNow = () => requestProjection(all().find((x) => x.id === r.id) ?? r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir });
+            if (r.approval_state !== "awaiting_approval") {
+                throw new ToolRefusal("already_decided", `This request is already ${r.approval_state}.`, { projection: projectionNow() });
+            }
             const instructions = a.instructions?.trim() || undefined;
             if ((a.decision === "approve_with_changes" || a.decision === "request_revision") && !instructions) {
                 throw new ToolRefusal("instructions_required", a.decision === "request_revision" ? "Say what to revise." : "Write the changes to apply.");
             }
             const client = ctx.oauthState.read().clients[auth.clientId];
-            const { decision, state, receipt } = await decide(r, person, a.decision, ctx.approval, {
-                instructions,
-                via: `card:${String(client?.client_name ?? auth.clientId).slice(0, 50)}`,
-            });
+            let decided;
+            try {
+                decided = await decide(r, person, a.decision, ctx.approval, {
+                    instructions,
+                    via: `card:${String(client?.client_name ?? auth.clientId).slice(0, 50)}`,
+                });
+            }
+            catch (error) {
+                // A decision recorded a moment earlier, by another client, is reported with where it stands.
+                if (error instanceof AlreadyDecided)
+                    throw new ToolRefusal("already_decided", error.message, { projection: projectionNow() });
+                throw error;
+            }
+            const { decision, state, receipt } = decided;
+            const projection = projectionNow();
             const summary = decision === "approved"
                 ? `Approved by ${person.name}. ${receipt.outcome === "failed" ? "Running it failed; see the receipt." : `Outcome: ${String(receipt.outcome ?? "recorded").replace(/_/g, " ")}.`}`
                 : decision === "revision_requested"
                     ? `Sent back for revision by ${person.name}.`
                     : `Declined by ${person.name}.`;
-            const out = { record_id: r.id, decision, state, summary, receipt };
+            const out = { record_id: r.id, decision, state, summary, receipt, projection };
             return { structuredContent: out, content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
         }
         catch (error) {
             if (error instanceof ToolRefusal || error instanceof AlreadyDecided) {
-                const out = error instanceof AlreadyDecided ? { error: "already_decided", message: error.message } : { error: error.code, message: error.message };
+                const detail = error instanceof ToolRefusal ? error.detail : undefined;
+                const out = error instanceof AlreadyDecided ? { error: "already_decided", message: error.message } : { error: error.code, message: error.message, ...detail };
                 return { isError: true, structuredContent: out, content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
             }
             return fail({ error: "failed", message: error instanceof Error ? error.message : String(error) });

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",
@@ -26,7 +26,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@miadi/inquiry-weave": "0.18.4",
+    "@miadi/inquiry-weave": "0.18.5",
     "@miadi/node-service-kit": "0.1.2",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "express": "^5.2.1",