@miadi/connector 0.1.13 → 0.1.15

package/README.md

@@ -42,6 +42,14 @@ The model that asked cannot approve its own request.
 
 `get_run_result` returns one `projection` of the decision, dispatch/completion state, receipt link and outstanding instructions. The in-chat card, approval page and Miadi's research page use that same read model. Asking `show_decisions` for an already-decided `record_id` shows its receipt without issuing another decision token. An in-flight card can refresh status without repeating the operation. A completed basic review with unapplied approval instructions remains open as **changes outstanding**, not falsely finished.
 
+### Revising a mission before it is decided
+
+A mission is revised, never re-requested (jgwill/Miadi#919). `revise_pending_request` changes an agent run or work proposal that still awaits a decision, or that its approver sent back, and gives it its next version. Pass the version you read as `expected_version` and only the fields that change. The request keeps its id, its approval page and its one card. A change of `provider` is verified on the host again. Each revision is a record in the ledger carrying the whole new content, its reason, author, changed fields and `sha256` content hash, so every earlier version stays readable verbatim with `get_request_history`. A request already approved, queued or declined is refused: a change after a decision is a new request or a steer.
+
+A decision names the version it decides. The approval page carries the version it shows, and each card's decision token is bound to its version. A page or card that showed an earlier version is refused as `stale_version`, so no brief is queued for a version the person did not read. The receipt and the brief (`version="N"`, and the hash) name the version approved.
+
+Requests made before this, one new request per revision, are joined with `supersede_pending_requests`: name the request that stands and the exact ids of the earlier ones. Each earlier request must still await a decision and be asked by the same person. It is retired (`Superseded by a later version`: it can no longer be approved, and its page says which request to decide) and becomes an earlier version of the standing request. All are checked before anything is written, and a request already approved or queued is refused, never cancelled.
+
 ### Following and steering a mission
 
 `mission_status` joins one mission read-only: its source request and decision, the sessions bound to it (each with how it is bound — a signed `session:` ref, the delivered brief's target, or the requested name), its issues and PRs, its steering grant, and where it stands stage by stage — approved, queued, delivered, running, merged, released, closed — each by its evidence, so an idle pane or a merge is never read as completion. Live panes and Miadi's session view are joined only for the write tier.
@@ -60,7 +68,7 @@ In a client that renders MCP Apps (ChatGPT among them), `show_decisions` draws o
 
 The model that asked cannot decide for the person:
 - `decide_request` is declared for the card only (`_meta.ui.visibility: ["app"]`), so the host does not offer it to the model.
-- It requires a decision token that travels only in the `_meta` of the `show_decisions` result. Hosts deliver that metadata to the card and keep it from the model. The token is bound to one request, one person and one OAuth client, and expires after 30 minutes. A decided request no longer awaits a decision, so a token works once.
+- It requires a decision token that travels only in the `_meta` of the `show_decisions` result. Hosts deliver that metadata to the card and keep it from the model. The token is bound to one request at the version its card shows, one person and one OAuth client, and expires after 30 minutes. A decided request no longer awaits a decision, so a token works once.
 - The sign-in must carry `miadi:approve`. A person grants it by ticking "Let me approve requests on cards inside this client" on the sign-in page. Only a person with Miadi's write tier receives it, only for a client that sends people back to chatgpt.com, and it ends when Miadi no longer gives them the write tier. A person token used directly as Bearer never carries it.
 
 The approval page itself (`/approve/<record>`) names only the kind of request until someone signs in. A write-tier person then reads and decides it, and whoever asked can read it.

package/dist/approve.d.ts

@@ -24,7 +24,7 @@ export interface ApprovalDeps {
     miadi: MiadiClient;
     identify: (token: string) => Promise<MiadiPerson | null>;
     fetchImpl?: typeof fetch;
-    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    /** The factory directory holding queue/ (default /srv/miadi/factory). */
     factoryDir?: string;
     tmuxSessions?: () => string[];
     /** The steering surface (jgwill/Miadi#893); tests inject a fake, production uses tmux. */
@@ -57,12 +57,19 @@ 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 {
 }
+/** A decision on a version the request no longer holds: it was revised after the page or card was read (#919). */
+export declare class StaleVersion extends AlreadyDecided {
+    readonly currentVersion: number;
+    readonly decidedVersion: number;
+    constructor(currentVersion: number, decidedVersion: number);
+}
 /** 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;
     via: string;
+    expectedVersion?: number;
 }): Promise<{
     decision: NonNullable<ConnectorRecord["approval_state"]>;
     state: ConnectorRecord["state"];

package/dist/approve.js

@@ -20,6 +20,7 @@ import { current, newRecordId } from "./records.js";
 import { APPROVABLE, projectRequest } from "./request-state.js";
 import { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 import { steerAttempts, steerSession, tmuxAdapter } from "./steer.js";
+import { contentHash, versionOf } from "./revisions.js";
 export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
 /**
  * What a person may decide on a request. Approving with changes runs it with the
@@ -67,21 +68,23 @@ export function runBrief(record, approver, sessions, instructions) {
     const body = (record.kind === "work_proposal" ? { task: proposalTask(record) } : record.body);
     const short = record.id.split(":")[1]?.slice(0, 8) ?? "run";
     const to = body.session && sessions.includes(body.session) ? body.session : `new:${body.session ?? `connector-${yymmdd()}-${short}`}`;
-    const cwd = body.cwd || "/a/src/Miadi-18";
+    // A new session opens where the request says, else where the factory runner's config says (defaultCwd): no host path here (#911).
+    const cwd = body.cwd;
     const open = [
         `to="${attr(to)}"`,
         'status="send"',
         'type="connector-run"',
         `record="${attr(record.id)}"`,
+        `version="${versionOf(record)}"`,
         // The provider the connector verified at request time (jgwill/Miadi#893); the intake may honour it or record why not.
         ...(body.resolved_provider ? [`provider="${attr(body.resolved_provider)}"`] : []),
-        ...(to.startsWith("new:") ? [`cwd="${attr(cwd)}"`] : []),
+        ...(to.startsWith("new:") && cwd ? [`cwd="${attr(cwd)}"`] : []),
     ];
     const lines = [
         `<input ${open.join(" ")}>`,
         `A bounded task requested through the Miadi connector (jgwill/Miadi#815, #816).`,
         "",
-        `- Record: ${text(record.id)}`,
+        `- Record: ${text(record.id)}, version ${versionOf(record)} (${contentHash(record)})`,
         `- Requested by: ${text(record.actor.name)}${record.actor.client_name ? ` through ${text(record.actor.client_name)}` : ""}, ${text(record.created_at)}`,
         `- Approved by: ${text(approver.name)}, ${new Date().toISOString()}`,
         ...(record.circle ? [`- Accountable circle: ${text(record.circle)}`] : []),
@@ -106,7 +109,7 @@ export function runBrief(record, approver, sessions, instructions) {
         "",
         "When it is done, reply with what was achieved, the evidence (commits, paths, URLs), what is still open, and whether this session should end. Then record the receipt through the connector's update_handoff if a handoff names this record, and end the session per its lifecycle.",
         "",
-        "Queued by the Miadi connector's approval door, delivered by the factory intake.",
+        "Queued by the Miadi connector's approval door, delivered by the factory runner (@miadi/factory-runner).",
         "</input>",
     ];
     return { to, brief: `${lines.join("\n")}\n` };
@@ -267,6 +270,7 @@ ${r.circle ? `<dt>Circle</dt><dd>${escapeHtml(r.circle)}</dd>` : ""}
 ${r.intention ? `<dt>Intention</dt><dd>${escapeHtml(r.intention)}</dd>` : ""}
 ${r.refs.length ? `<dt>References</dt><dd>${r.refs.map(escapeHtml).join("<br>")}</dd>` : ""}
 <dt>State</dt><dd>${escapeHtml(r.approval_state ?? "—")}</dd>
+${versionOf(r) > 1 ? `<dt>Version</dt><dd>${versionOf(r)}, the one a decision here decides. Earlier versions stay in the ledger.</dd>` : ""}
 </dl>
 <pre>${escapeHtml(JSON.stringify(shown, null, 2))}</pre>`;
 }
@@ -279,6 +283,16 @@ ${r.refs.length ? `<dt>References</dt><dd>${r.refs.map(escapeHtml).join("<br>")}
 /** A request is decided once: a second decision while one runs, or after it, is refused. */
 export class AlreadyDecided extends Error {
 }
+/** A decision on a version the request no longer holds: it was revised after the page or card was read (#919). */
+export class StaleVersion extends AlreadyDecided {
+    currentVersion;
+    decidedVersion;
+    constructor(currentVersion, decidedVersion) {
+        super(`This request was revised to version ${currentVersion} after version ${decidedVersion} was shown. Read version ${currentVersion} and decide again.`);
+        this.currentVersion = currentVersion;
+        this.decidedVersion = decidedVersion;
+    }
+}
 const deciding = new Set();
 /** Whether a decision on this request is being recorded now, its run may still be going. */
 export function isBeingDecided(recordId) {
@@ -286,11 +300,17 @@ export function isBeingDecided(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.
+    // page and the card (or two cards) may decide the same request at once, and
+    // a revision may land between reading a version and deciding it (#919).
     const live = current(deps.ledger.all()).find((x) => x.id === r.id);
     if (!live || live.approval_state !== "awaiting_approval" || deciding.has(r.id)) {
         throw new AlreadyDecided(deciding.has(r.id) ? "A decision on this request is being recorded." : `This request is already ${live?.approval_state ?? "gone"}.`);
     }
+    // A decision that names no version (a page opened before versions, a surface that sends none) decides version 1:
+    // a request revised since is refused, never decided blind (#919 review F1).
+    const decidedVersion = opts.expectedVersion ?? 1;
+    if (versionOf(live) !== decidedVersion)
+        throw new StaleVersion(versionOf(live), decidedVersion);
     deciding.add(r.id);
     try {
         return await decideOnce(live, person, choice, deps, opts);
@@ -368,6 +388,9 @@ async function decideOnce(r, person, choice, deps, opts) {
         decided_by: { person_id: person.id, name: person.name },
         decided_at: new Date().toISOString(),
         decision: choice,
+        // The exact version decided, so the brief, the receipt and the history name the same content (#919).
+        version: versionOf(r),
+        content_hash: contentHash(r),
         via: opts.via,
         ...(instructions ? { instructions } : {}),
         note: opts.note,
@@ -397,7 +420,7 @@ async function decideOnce(r, person, choice, deps, opts) {
         supersedes: r.id,
         approval_state: decision,
         state,
-        ...(decision === "revision_requested" ? { next_action: `Revise and submit a new request that cites ${r.id} in refs.` } : {}),
+        ...(decision === "revision_requested" ? { next_action: `Revise it in place with revise_pending_request (request_id ${r.id}, expected_version ${versionOf(r)}).` } : {}),
         completion_receipt: receipt,
         body: { decision: choice, ...(instructions ? { instructions } : {}) },
     });
@@ -493,9 +516,17 @@ export function registerApprovalRoutes(app, deps) {
         }
         let decided;
         try {
-            decided = await decide(r, person, choice, deps, { instructions, note: body.note || undefined, via: String(body.via ?? "approval-page").slice(0, 60) });
+            const shown = Number(body.version);
+            decided = await decide(r, person, choice, deps, {
+                instructions,
+                note: body.note || undefined,
+                via: String(body.via ?? "approval-page").slice(0, 60),
+                ...(Number.isInteger(shown) && shown >= 1 ? { expectedVersion: shown } : {}),
+            });
         }
         catch (error) {
+            if (error instanceof StaleVersion)
+                return void res.status(409).type("html").send(approvePage(deps, find(r.id), { token, error: error.message }));
             if (error instanceof AlreadyDecided)
                 return void res.status(409).type("html").send(approvePage(deps, find(r.id), { error: error.message }));
             throw error;
@@ -596,6 +627,7 @@ ${o.error ? `<p class="err" role="alert">${escapeHtml(o.error)}</p>` : ""}
 ${actionable && o.token
         ? `<form method="post">
 <input type="hidden" name="person_token" value="${escapeHtml(o.token)}">
+<input type="hidden" name="version" value="${versionOf(r)}">
 <label for="i">Instructions (needed to approve with changes or to send back)</label>
 <textarea id="i" name="instructions" rows="4"></textarea>
 <div class="row">

package/dist/decisions.d.ts

@@ -6,8 +6,10 @@ export declare class DecisionTokens {
     private readonly secret;
     constructor(stateDir: string);
     private sign;
-    issue(recordId: string, personId: string, clientId: string, now?: number): string;
-    verify(token: string, recordId: string, personId: string, clientId: string, now?: number): "ok" | "expired" | "invalid";
+    /** A token for one card: one request, at the version the card shows, for one person in one client. */
+    issue(recordId: string, personId: string, clientId: string, now?: number, version?: number): string;
+    /** `stale`: the token is genuine but was minted for a version the request no longer holds. */
+    verify(token: string, recordId: string, personId: string, clientId: string, now?: number, currentVersion?: number): "ok" | "expired" | "invalid" | "stale";
 }
 /**
  * The card. Self-contained: no network, no external script. It reads the

package/dist/decisions.js

@@ -30,23 +30,32 @@ export class DecisionTokens {
             writeFileSync(file, newSecret(32), { mode: 0o600, flag: "wx" });
         this.secret = readFileSync(file, "utf8").trim();
     }
-    sign(recordId, personId, clientId, exp) {
-        return createHmac("sha256", this.secret).update(`${recordId}\n${personId}\n${clientId}\n${exp}`).digest("base64url");
+    sign(recordId, personId, clientId, exp, version) {
+        // A token is bound to the version the card showed (jgwill/Miadi#919); one minted before versions has none.
+        const v = version === undefined ? "" : `\nv${version}`;
+        return createHmac("sha256", this.secret).update(`${recordId}\n${personId}\n${clientId}\n${exp}${v}`).digest("base64url");
     }
-    issue(recordId, personId, clientId, now = Math.floor(Date.now() / 1000)) {
+    /** A token for one card: one request, at the version the card shows, for one person in one client. */
+    issue(recordId, personId, clientId, now = Math.floor(Date.now() / 1000), version = 1) {
         const exp = now + DECISION_TOKEN_TTL;
-        return `${exp}.${this.sign(recordId, personId, clientId, exp)}`;
+        return `${exp}.v${version}.${this.sign(recordId, personId, clientId, exp, version)}`;
     }
-    verify(token, recordId, personId, clientId, now = Math.floor(Date.now() / 1000)) {
-        const [expRaw, mac] = String(token ?? "").split(".");
-        const exp = Number(expRaw);
+    /** `stale`: the token is genuine but was minted for a version the request no longer holds. */
+    verify(token, recordId, personId, clientId, now = Math.floor(Date.now() / 1000), currentVersion = 1) {
+        const parts = String(token ?? "").split(".");
+        const exp = Number(parts[0]);
+        const versioned = parts.length === 3 && /^v\d+$/.test(parts[1]);
+        const version = versioned ? Number(parts[1].slice(1)) : undefined;
+        const mac = versioned ? parts[2] : parts.length === 2 ? parts[1] : "";
         if (!Number.isInteger(exp) || !mac)
             return "invalid";
-        const expected = Buffer.from(this.sign(recordId, personId, clientId, exp));
+        const expected = Buffer.from(this.sign(recordId, personId, clientId, exp, version));
         const given = Buffer.from(mac);
         if (expected.length !== given.length || !timingSafeEqual(expected, given))
             return "invalid";
-        return exp < now ? "expired" : "ok";
+        if (exp < now)
+            return "expired";
+        return (version ?? 1) === currentVersion ? "ok" : "stale";
     }
 }
 /**

package/dist/mission-status.js

@@ -34,7 +34,8 @@ export function resolveMissionSubject(ref, records) {
     const exact = records.find((r) => r.id === ref);
     if (exact)
         return { record: exact, via: "record_id", resolution: "exact", candidates: [] };
-    const missions = records.filter((r) => MISSION_KINDS.has(r.kind)).sort(newestFirst);
+    // A request retired as an earlier version of another (jgwill/Miadi#919) is not a mission of its own.
+    const missions = records.filter((r) => MISSION_KINDS.has(r.kind) && r.completion_receipt?.decision !== "superseded").sort(newestFirst);
     if (SESSION_REF.test(ref)) {
         const citing = missions.filter((r) => r.refs.includes(ref));
         if (!citing.length)

package/dist/queue-state.js

@@ -1,9 +1,9 @@
 /** 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");
+    // The factory's data folder, beside the connector's own /srv/miadi/connector: never a home directory (jgwill/Miadi#911).
+    return env.MIADI_FACTORY_DIR || "/srv/miadi/factory";
 }
 export function runBriefFile(record) {
     return `connector-${record.id.replace(/[^\w-]/g, "-")}.md`;

package/dist/records.d.ts

@@ -1,3 +1,4 @@
+import type { RequestLineage, RequestRevision } from "./revisions.js";
 export declare const CIRCLES: readonly [{
     readonly id: "story";
     readonly glyph: "📖";
@@ -81,13 +82,21 @@ export interface ConnectorRecord {
     supersedes?: string;
     idempotency_key?: string;
     completion_receipt?: Record<string, unknown>;
+    /** A revision of a waiting request: this record carries its whole new content (jgwill/Miadi#919). */
+    revision?: RequestRevision;
+    /** The requests a waiting request adopted as its earlier versions (jgwill/Miadi#919). */
+    lineage?: RequestLineage;
+    /** Folded only: the version the request is at, counted across its lineage. Absent means 1. */
+    version?: number;
 }
 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";
+/**
+ * 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. A revision also
+ * replaces the content (intention, circle, refs, body) and moves the version;
+ * a lineage adds the versions of the requests it adopted (jgwill/Miadi#919).
+ */
 export declare function current(records: ConnectorRecord[]): ConnectorRecord[];

package/dist/records.js

@@ -73,19 +73,27 @@ export const APPROVAL_STATES = ["awaiting_approval", "approved", "declined", "re
 export function newRecordId(kind) {
     return `${kind}:${randomUUID()}`;
 }
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
 /**
  * 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.
+ * state, approval and receipt, keeping its own id and history. A revision also
+ * replaces the content (intention, circle, refs, body) and moves the version;
+ * a lineage adds the versions of the requests it adopted (jgwill/Miadi#919).
  */
-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) {
         if (r.supersedes && byId.has(r.supersedes)) {
             const base = byId.get(r.supersedes);
+            const adopted = r.lineage ? r.lineage.adopted.reduce((n, a) => n + (byId.get(a)?.version ?? 1), 0) : 0;
             byId.set(r.supersedes, {
                 ...base,
+                ...(r.revision
+                    ? { intention: r.intention, circle: r.circle ?? base.circle, refs: r.refs, body: r.body, version: r.revision.version }
+                    : r.lineage
+                        ? { version: (base.version ?? 1) + adopted }
+                        : {}),
                 state: r.state ?? base.state,
                 approval_state: r.approval_state ?? base.approval_state,
                 next_action: r.next_action ?? base.next_action,

package/dist/request-state.d.ts

@@ -54,6 +54,10 @@ export interface RequestProjection {
     outstanding: string[];
     /** Every sentence a surface shows under the label, names and instructions included. */
     lines: string[];
+    /** The version the request is at (jgwill/Miadi#919); a decision names it. 1 for a request never revised. */
+    version: number;
+    /** A request retired as an earlier version of another: the request to decide instead. */
+    superseded_by?: string;
 }
 export interface ProjectionContext {
     /** The review service's public address, for receipt_url. Default MIADI_REVIEW_BASE_URL, else the public service. */
@@ -65,5 +69,9 @@ export interface ProjectionContext {
     /** 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. */
+/**
+ * The projection of an approvable request, or null for a record that is not one. A
+ * request retired as an earlier version of another reads as superseded; a revised one
+ * says its version, and a request sent back says which version answers it (#919).
+ */
 export declare function projectRequest(record: ConnectorRecord, ctx?: ProjectionContext): RequestProjection | null;

package/dist/request-state.js

@@ -17,6 +17,7 @@ const CHOICE_WORDS = {
     request_revision: "Sent back for revision",
     decline: "Declined",
     covered_by_grant: "Covered by the approved run's steering grant",
+    superseded: "Superseded by a later version",
 };
 const OUTCOME_WORDS = {
     queued: "queued for the factory intake",
@@ -37,8 +38,43 @@ 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. */
+/**
+ * The projection of an approvable request, or null for a record that is not one. A
+ * request retired as an earlier version of another reads as superseded; a revised one
+ * says its version, and a request sent back says which version answers it (#919).
+ */
 export function projectRequest(record, ctx = {}) {
+    const p = projectCore(record, ctx);
+    if (!p)
+        return null;
+    const version = typeof record.version === "number" && record.version >= 1 ? record.version : 1;
+    const receipt = (record.completion_receipt ?? {});
+    if (record.approval_state === "declined" && receipt.decision === "superseded") {
+        const by = text(receipt.superseded_by);
+        const who = text(receipt.decided_by?.name) || "someone";
+        const when = text(receipt.decided_at) ? ` at ${text(receipt.decided_at)}` : "";
+        const why = text(receipt.reason) ? `: ${text(receipt.reason).replace(/[.\s]+$/, "")}` : "";
+        return {
+            ...p,
+            version,
+            label: "Superseded by a later version",
+            decision: p.decision ? { ...p.decision, choice: "superseded" } : p.decision,
+            ...(by ? { superseded_by: by } : {}),
+            lines: [`Superseded by ${by || "a later request"}, as ${who} asked${when}${why}.`, `Nothing runs from this version. Decide ${by || "the later request"} instead.`],
+        };
+    }
+    const lines = [...p.lines];
+    if (record.approval_state === "awaiting_approval" && receipt.decision === "request_revision" && receipt.answered_by_version) {
+        const who = text(receipt.decided_by?.name) || "someone";
+        const asked = text(receipt.instructions).replace(/[.\s]+$/, "");
+        const answered = Number(receipt.answered_by_version);
+        lines.push(`Sent back for revision by ${who}${asked ? `: ${asked}` : ""}. Version ${answered} ${answered === version ? "answers" : "answered"} it.`);
+    }
+    if (version > 1)
+        lines.unshift(`Version ${version}; the earlier versions stay readable (get_request_history).`);
+    return { ...p, version, lines };
+}
+function projectCore(record, ctx = {}) {
     if (!APPROVABLE.has(record.kind))
         return null;
     const receipt = (record.completion_receipt ?? {});

package/dist/revisions.d.ts

@@ -0,0 +1,110 @@
+import type { ConnectorRecord } from "./records.js";
+/** The kinds that open a session when approved, and the only ones revised in place. */
+export declare const REVISABLE_KINDS: ReadonlySet<string>;
+/** A request is revised only before a decision runs it: waiting, or sent back by its approver. */
+export declare const REVISABLE_STATES: ReadonlySet<string>;
+/** What a revision record carries beside the new content. */
+export interface RequestRevision {
+    /** The version this record makes current, counted across the lineage (2, 3, …). */
+    version: number;
+    previous_version: number;
+    reason: string;
+    /** The fields that differ from the previous version. */
+    changed: string[];
+    content_hash: string;
+    previous_hash: string;
+    author: {
+        person_id: string;
+        name: string;
+    };
+    at: string;
+}
+/** What a lineage record carries: the requests the standing one adopted as its earlier versions. */
+export interface RequestLineage {
+    adopted: string[];
+    reason: string;
+    author: {
+        person_id: string;
+        name: string;
+    };
+    at: string;
+}
+/** The fields that make a request's content: what a version is. */
+export declare const CONTENT_FIELDS: readonly ["intention", "circle", "refs", "body"];
+/** The content of a request version, as the hash and the history show it. */
+export declare function contentOf(r: Pick<ConnectorRecord, "kind" | "intention" | "circle" | "refs" | "body">): Record<string, unknown>;
+/** sha256 of the canonical JSON of a version's content. */
+export declare function contentHash(r: Pick<ConnectorRecord, "kind" | "intention" | "circle" | "refs" | "body">): string;
+/** The version a folded request is at: 1 for a request never revised. */
+export declare function versionOf(r: Pick<ConnectorRecord, "version"> | undefined): number;
+/** The names of the content fields (body fields by name) that differ between two versions. */
+export declare function changedFields(before: Record<string, unknown>, after: Record<string, unknown>): string[];
+/** One version of a request, as the history returns it. */
+export interface RequestVersion {
+    version: number;
+    /** The record whose content this version is: the request itself, a revision record, or an adopted request. */
+    record_id: string;
+    /** The request this version belongs to when it is not the standing one (an adopted, retired request). */
+    request_id: string;
+    at: string;
+    author: string;
+    reason?: string;
+    changed?: string[];
+    content_hash: string;
+    content: Record<string, unknown>;
+    current: boolean;
+}
+/**
+ * Every version of a request, oldest first, numbered across its lineage: the requests
+ * it adopted (each with its own versions) and then its own. `raw` is the unfolded ledger,
+ * `folded` the folded one (`current()`).
+ */
+export declare function requestHistory(id: string, raw: ConnectorRecord[], folded?: ConnectorRecord[]): RequestVersion[];
+/** A revision refused, with the code a tool answers. */
+export declare class RevisionRefused extends Error {
+    readonly code: "not_found" | "not_revisable" | "forbidden" | "stale_version" | "being_decided" | "no_change" | "invalid_request";
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: "not_found" | "not_revisable" | "forbidden" | "stale_version" | "being_decided" | "no_change" | "invalid_request", message: string, detail?: Record<string, unknown> | undefined);
+}
+/**
+ * The new record that revises a waiting request, or a refusal. `next` holds the new
+ * content (kind, intention, circle, refs, body); `live` is the folded request.
+ */
+export declare function revisionRecord(live: ConnectorRecord | undefined, next: {
+    intention?: string;
+    circle?: ConnectorRecord["circle"];
+    refs: string[];
+    body: Record<string, unknown>;
+}, o: {
+    id: string;
+    person: {
+        id: string;
+        name: string;
+        writer: boolean;
+    };
+    actor: ConnectorRecord["actor"];
+    expectedVersion: number;
+    reason: string;
+    beingDecided: boolean;
+    idempotency_key?: string;
+    now?: string;
+}): ConnectorRecord;
+/**
+ * The records that make `standingId` the one request of a lineage: one retirement for
+ * each named request still waiting, and one lineage record on the standing request.
+ * Every named request is checked before anything is written; one refusal writes none.
+ * Only a request named by its exact id is retired, never one that looks similar, and a
+ * request already decided (approved, queued, declined) is refused, never cancelled.
+ */
+export declare function supersedeRecords(folded: ConnectorRecord[], standingId: string, retire: string[], o: {
+    person: {
+        id: string;
+        name: string;
+        writer: boolean;
+    };
+    actor: ConnectorRecord["actor"];
+    reason: string;
+    beingDecided: (id: string) => boolean;
+    newId: (kind: ConnectorRecord["kind"]) => string;
+    now?: string;
+}): ConnectorRecord[];

package/dist/revisions.js

@@ -0,0 +1,245 @@
+/**
+ * One mission, many versions, one decision (jgwill/Miadi#919).
+ *
+ * A request that still waits for a decision is revised in place: a revision is a
+ * record appended to the ledger that supersedes the request and carries the whole
+ * new content, so the request keeps its id, its approval page and its card, and
+ * every earlier version stays readable verbatim. Requests made separately before
+ * this existed (one new request per revision) are joined by `supersedePending`: the
+ * request that stands adopts the others as its earlier versions, and each adopted
+ * one is retired, so only the standing request can be approved.
+ *
+ * A decision names the version it decides. The approval page and the card carry it,
+ * and a decision on any other version is refused as stale, so no brief is ever
+ * queued for a version the person did not read.
+ */
+import { createHash } from "node:crypto";
+/** The kinds that open a session when approved, and the only ones revised in place. */
+export const REVISABLE_KINDS = new Set(["run_request", "work_proposal"]);
+/** A request is revised only before a decision runs it: waiting, or sent back by its approver. */
+export const REVISABLE_STATES = new Set(["awaiting_approval", "revision_requested"]);
+/** The fields that make a request's content: what a version is. */
+export const CONTENT_FIELDS = ["intention", "circle", "refs", "body"];
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value)
+            .filter((k) => value[k] !== undefined)
+            .sort()
+            .map((k) => [k, canonical(value[k])]));
+    }
+    return value;
+}
+/** The content of a request version, as the hash and the history show it. */
+export function contentOf(r) {
+    return { kind: r.kind, intention: r.intention, circle: r.circle, refs: r.refs ?? [], body: r.body ?? {} };
+}
+/** sha256 of the canonical JSON of a version's content. */
+export function contentHash(r) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonical(contentOf(r)))).digest("hex")}`;
+}
+/** The version a folded request is at: 1 for a request never revised. */
+export function versionOf(r) {
+    return typeof r?.version === "number" && r.version >= 1 ? r.version : 1;
+}
+/** The names of the content fields (body fields by name) that differ between two versions. */
+export function changedFields(before, after) {
+    const out = [];
+    const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+    for (const k of ["intention", "circle", "refs"])
+        if (!same(before[k], after[k]))
+            out.push(k);
+    const b = (before.body ?? {});
+    const a = (after.body ?? {});
+    for (const k of [...new Set([...Object.keys(b), ...Object.keys(a)])].sort())
+        if (!same(b[k], a[k]))
+            out.push(k);
+    return out;
+}
+/**
+ * Every version of a request, oldest first, numbered across its lineage: the requests
+ * it adopted (each with its own versions) and then its own. `raw` is the unfolded ledger,
+ * `folded` the folded one (`current()`).
+ */
+export function requestHistory(id, raw, folded = []) {
+    // `current` marks the version the request holds now: the last one.
+    const own = (rid, seen) => {
+        if (seen.has(rid))
+            return [];
+        seen.add(rid);
+        const base = raw.find((r) => r.id === rid);
+        if (!base)
+            return [];
+        const out = [];
+        const lineage = raw.filter((r) => r.supersedes === rid && r.lineage).flatMap((r) => r.lineage.adopted);
+        const adopted = lineage
+            .map((a) => raw.find((r) => r.id === a))
+            .filter((r) => !!r)
+            .sort((x, y) => x.created_at.localeCompare(y.created_at));
+        for (const a of adopted)
+            out.push(...own(a.id, seen));
+        out.push({ record_id: base.id, request_id: rid, at: base.created_at, author: base.actor?.name ?? "someone", content_hash: contentHash(base), content: contentOf(base) });
+        for (const rev of raw.filter((r) => r.supersedes === rid && r.revision)) {
+            out.push({
+                record_id: rev.id,
+                request_id: rid,
+                at: rev.revision.at,
+                author: rev.revision.author.name,
+                reason: rev.revision.reason,
+                changed: rev.revision.changed,
+                content_hash: rev.revision.content_hash,
+                content: contentOf(rev),
+            });
+        }
+        return out;
+    };
+    void folded;
+    const versions = own(id, new Set());
+    return versions.map((v, i) => ({ ...v, version: i + 1, current: i === versions.length - 1 }));
+}
+/** A revision refused, with the code a tool answers. */
+export class RevisionRefused extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+    }
+}
+/**
+ * The new record that revises a waiting request, or a refusal. `next` holds the new
+ * content (kind, intention, circle, refs, body); `live` is the folded request.
+ */
+export function revisionRecord(live, next, o) {
+    if (!live)
+        throw new RevisionRefused("not_found", "No request with that id.");
+    if (!REVISABLE_KINDS.has(live.kind))
+        throw new RevisionRefused("invalid_request", `A ${live.kind} is not revised in place; only agent runs and work proposals are.`);
+    if (!o.person.writer && live.actor?.person_id !== o.person.id) {
+        throw new RevisionRefused("forbidden", "Only whoever asked, or a person with Miadi's write tier, revises a request.");
+    }
+    if (o.beingDecided)
+        throw new RevisionRefused("being_decided", "A decision on this request is being recorded; it cannot be revised now.");
+    if (!REVISABLE_STATES.has(live.approval_state ?? "")) {
+        throw new RevisionRefused("not_revisable", `This request is already ${live.approval_state ?? "decided"}. A change after a decision is a new request, or a steer of the session it opened (request_session_steer).`);
+    }
+    const current = versionOf(live);
+    if (o.expectedVersion !== current) {
+        throw new RevisionRefused("stale_version", `The request is at version ${current}, not ${o.expectedVersion}. Read it with get_request_history and revise version ${current}.`, {
+            current_version: current,
+        });
+    }
+    const before = contentOf(live);
+    const after = contentOf({ kind: live.kind, intention: next.intention, circle: next.circle, refs: next.refs, body: next.body });
+    const changed = changedFields(before, after);
+    if (!changed.length)
+        throw new RevisionRefused("no_change", `Version ${current} already says this; nothing was recorded.`, { current_version: current });
+    const at = o.now ?? new Date().toISOString();
+    const sentBack = live.approval_state === "revision_requested";
+    return {
+        id: o.id,
+        kind: live.kind,
+        created_at: at,
+        actor: o.actor,
+        refs: next.refs,
+        evidence_refs: [],
+        ...(next.intention !== undefined ? { intention: next.intention } : {}),
+        ...(next.circle !== undefined ? { circle: next.circle } : {}),
+        body: next.body,
+        supersedes: live.id,
+        approval_state: "awaiting_approval",
+        state: "pending",
+        next_action: `Awaiting a decision on version ${current + 1}.`,
+        ...(o.idempotency_key ? { idempotency_key: o.idempotency_key } : {}),
+        // A request sent back keeps the approver's instructions on its receipt, now as what the revision answers.
+        ...(sentBack && live.completion_receipt ? { completion_receipt: { ...live.completion_receipt, answered_by_version: current + 1 } } : {}),
+        revision: {
+            version: current + 1,
+            previous_version: current,
+            reason: o.reason,
+            changed,
+            content_hash: contentHash({ kind: live.kind, intention: next.intention, circle: next.circle, refs: next.refs, body: next.body }),
+            previous_hash: contentHash(live),
+            author: { person_id: o.person.id, name: o.person.name },
+            at,
+        },
+    };
+}
+/**
+ * The records that make `standingId` the one request of a lineage: one retirement for
+ * each named request still waiting, and one lineage record on the standing request.
+ * Every named request is checked before anything is written; one refusal writes none.
+ * Only a request named by its exact id is retired, never one that looks similar, and a
+ * request already decided (approved, queued, declined) is refused, never cancelled.
+ */
+export function supersedeRecords(folded, standingId, retire, o) {
+    const standing = folded.find((r) => r.id === standingId);
+    if (!standing)
+        throw new RevisionRefused("not_found", `No request ${standingId}.`);
+    if (!REVISABLE_KINDS.has(standing.kind))
+        throw new RevisionRefused("invalid_request", "Only agent runs and work proposals carry versions.");
+    if (!REVISABLE_STATES.has(standing.approval_state ?? "")) {
+        throw new RevisionRefused("not_revisable", `The request that stands is already ${standing.approval_state}; earlier versions are joined only to a request still waiting.`);
+    }
+    if (o.beingDecided(standingId))
+        throw new RevisionRefused("being_decided", "A decision on the request that stands is being recorded; nothing was retired.");
+    // Earlier requests come before the standing one's own versions: joined after an in-place revision,
+    // the numbers it was given would shift (#919 review F4).
+    if (versionOf(standing) > 1) {
+        throw new RevisionRefused("not_revisable", `The request that stands is already at version ${versionOf(standing)}: join earlier requests to it before revising it in place, or revise it instead.`);
+    }
+    const ids = [...new Set(retire.map((x) => x.trim()).filter(Boolean))];
+    if (!ids.length)
+        throw new RevisionRefused("invalid_request", "Name at least one earlier request by its exact id.");
+    if (ids.includes(standingId))
+        throw new RevisionRefused("invalid_request", "The request that stands cannot also be retired.");
+    const may = (r) => o.person.writer || r.actor?.person_id === o.person.id;
+    if (!may(standing))
+        throw new RevisionRefused("forbidden", "Only whoever asked, or a person with Miadi's write tier, joins versions of a request.");
+    const olds = [];
+    for (const id of ids) {
+        const r = folded.find((x) => x.id === id);
+        if (!r)
+            throw new RevisionRefused("not_found", `No request ${id}; nothing was retired.`);
+        if (r.kind !== standing.kind)
+            throw new RevisionRefused("invalid_request", `${id} is a ${r.kind}, the request that stands a ${standing.kind}; nothing was retired.`);
+        if (!may(r))
+            throw new RevisionRefused("forbidden", `${id} was asked by someone else; nothing was retired.`);
+        if (o.beingDecided(id))
+            throw new RevisionRefused("being_decided", `A decision on ${id} is being recorded; nothing was retired.`);
+        if (!REVISABLE_STATES.has(r.approval_state ?? "")) {
+            throw new RevisionRefused("not_revisable", `${id} is already ${r.approval_state}: a decided request is never retired. Nothing was retired.`);
+        }
+        olds.push(r);
+    }
+    const at = o.now ?? new Date().toISOString();
+    const by = { person_id: o.person.id, name: o.person.name };
+    const out = olds.map((r) => ({
+        id: o.newId(r.kind),
+        kind: r.kind,
+        created_at: at,
+        actor: o.actor,
+        refs: r.refs,
+        evidence_refs: [],
+        supersedes: r.id,
+        approval_state: "declined",
+        state: "withdrawn",
+        next_action: `Superseded by ${standingId}: decide that request instead.`,
+        completion_receipt: { decision: "superseded", superseded_by: standingId, decided_by: by, decided_at: at, via: o.actor.client_name ?? o.actor.client_id, reason: o.reason },
+        body: { decision: "superseded", superseded_by: standingId },
+    }));
+    out.push({
+        id: o.newId(standing.kind),
+        kind: standing.kind,
+        created_at: at,
+        actor: o.actor,
+        refs: standing.refs,
+        evidence_refs: [],
+        supersedes: standingId,
+        body: { decision: "lineage" },
+        lineage: { adopted: olds.map((r) => r.id), reason: o.reason, author: by, at },
+    });
+    return out;
+}

package/dist/server.d.ts

@@ -9,7 +9,7 @@ import type { JevAdapter } from "./model-preflight.js";
 export interface ConnectorDeps {
     identify: (token: string) => Promise<MiadiPerson | null>;
     fetchImpl?: typeof fetch;
-    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    /** The factory directory holding queue/ (default /srv/miadi/factory). */
     factoryDir?: string;
     tmuxSessions?: () => string[];
     /** The steering surface (jgwill/Miadi#893); tests inject a fake, production uses tmux. */
@@ -29,4 +29,4 @@ export declare function createConnectorApp(config: ConnectorConfig, deps: Connec
     provider: MiadiOAuthProvider;
     ledger: Ledger<ConnectorRecord>;
 };
-export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and submit a revised request citing the old id in refs), or decline.\n- A research report (a Deep Research report) is delivered with save_research exactly as written, never summarised or shortened, with its sources; a long report goes in parts. Check the bytes and first and last lines the answer returns against what you sent.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";
+export declare const INSTRUCTIONS = "Miadi is a relational software factory: agent sessions, Miadi reviews of screenwalks, Chronicle episodes, talking circles and the five accountable circles (Story, Stewardship, Engineering, Evaluation, Continuity) across three domains (Creative, Ceremonial, Engineering).\n\nStart with get_capabilities: it says who you are signed in as, which tools are live, and which return not_implemented.\n\nRules every tool keeps:\n- Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.\n- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and revise it in place with revise_pending_request), or decline.\n- A mission is revised, never re-requested: to change a run or work proposal that still awaits a decision, call revise_pending_request with its id and the version you read (expected_version). It keeps one id, one approval page and one card; get_request_history shows every version. A new request_authorized_run or propose_work is for a new mission only. Requests made earlier as separate versions are joined with supersede_pending_requests, naming their exact ids, only when the person names or confirms them.\n- A research report (a Deep Research report) is delivered with save_research exactly as written, never summarised or shortened, with its sources; a long report goes in parts. Check the bytes and first and last lines the answer returns against what you sent.\n- An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.\n- Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.";

package/dist/server.js

@@ -145,7 +145,8 @@ Start with get_capabilities: it says who you are signed in as, which tools are l
 
 Rules every tool keeps:
 - Every record names the person who made it, with a claim category: observed, hypothesis, desired_future, fiction or verified_implementation. Keep fiction and desired futures apart from what was observed.
-- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and submit a revised request citing the old id in refs), or decline.
+- Requests (runs, work proposals, review operations, Deep Diver, review-to-episode links, inquiry-to-episode weaves, session completion) are recorded as awaiting_approval. Nothing runs, publishes or closes until a person decides. After making a request, call show_decisions: it shows the request as a card in the conversation, where the person decides with their own click (or follows its approval page). Never claim a decision the card has not reported. The person may approve, approve with changes (their instructions are carried into what runs), send it back for revision with instructions (approval_state revision_requested; read the instructions with get_run_result and revise it in place with revise_pending_request), or decline.
+- A mission is revised, never re-requested: to change a run or work proposal that still awaits a decision, call revise_pending_request with its id and the version you read (expected_version). It keeps one id, one approval page and one card; get_request_history shows every version. A new request_authorized_run or propose_work is for a new mission only. Requests made earlier as separate versions are joined with supersede_pending_requests, naming their exact ids, only when the person names or confirms them.
 - A research report (a Deep Research report) is delivered with save_research exactly as written, never summarised or shortened, with its sources; a long report goes in parts. Check the bytes and first and last lines the answer returns against what you sent.
 - An unknown id is answered as not found, never invented. A missing backing service is answered as unavailable.
 - Use the miadi-review:<uuid>, miadi-chronicle://<n>, owner/repo#n and session:<uuid> reference forms.`;

package/dist/tools.d.ts

@@ -16,7 +16,7 @@ export interface ToolContext {
     reviews: ReviewClient;
     ledger: Ledger<ConnectorRecord>;
     oauthState: JsonFile<OAuthState>;
-    /** The factory directory holding queue/ (default ~/.miadi/factory). */
+    /** The factory directory holding queue/ (default /srv/miadi/factory). */
     factoryDir?: string;
     /** What the in-chat approval card needs to run a decided request. */
     approval?: ApprovalDeps;

package/dist/tools.js

@@ -16,7 +16,8 @@ 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, requestProjection } from "./approve.js";
+import { AlreadyDecided, DECISIONS, KIND_LABELS, StaleVersion, consequenceOf, decide, isApprovable, isBeingDecided, readQueueState, requestProjection } 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";
@@ -638,12 +639,14 @@ export function registerTools(server, ctx) {
             return { state: "not_found", record_id };
         return {
             record: r,
+            version: versionOf(r),
+            ...(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 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.` } }
+                ? { revision: { instructions: r.completion_receipt?.instructions, next: `Revise it in place: revise_pending_request with request_id ${r.id} and expected_version ${versionOf(r)}.` } }
                 : {}),
         };
     }));
@@ -1051,7 +1054,7 @@ export function registerTools(server, ctx) {
     }));
     server.registerTool("propose_work", {
         title: "Propose work to a circle",
-        description: "Propose a bounded piece of work: what should exist when it is done, the circle accountable, the sources. Nothing starts until a person decides. Approving it starts the work as a factory run, with any changes the person writes; the person may instead send it back for revision with instructions (approval_state revision_requested, instructions in completion_receipt): then submit a revised proposal citing the old id in refs.",
+        description: "Propose a bounded piece of work: what should exist when it is done, the circle accountable, the sources. Nothing starts until a person decides. Approving it starts the work as a factory run, with any changes the person writes; the person may instead send it back for revision with instructions (approval_state revision_requested, instructions in completion_receipt): then revise it in place with revise_pending_request (same id). To change a proposal still awaiting a decision, revise it the same way rather than proposing again.",
         inputSchema: {
             title: z.string().min(1).max(200),
             desired_outcome: z.string().min(1).max(6000),
@@ -1135,14 +1138,14 @@ export function registerTools(server, ctx) {
     // ── requests: recorded, approved by a person on the approval page, then run ──
     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.",
+        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.",
         inputSchema: {
             task: z.string().min(1).max(12000).describe("What the session does and what it returns."),
             circle,
             refs,
             primary_issue: primaryIssue,
             session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional().describe("An existing tmux session to hand it to, or a name for a new one."),
-            cwd: z.string().max(300).optional().describe("Working folder for a new session (default the Miadi checkout)."),
+            cwd: z.string().max(300).optional().describe("Working folder for a new session (default: the factory runner's defaultCwd on the host)."),
             provider: z
                 .enum(["codex", "pi", "copilot", "claude"])
                 .optional()
@@ -1192,6 +1195,178 @@ export function registerTools(server, ctx) {
             approval_url: approvalUrl(r.id),
         };
     }));
+    // ── one mission, many versions, one decision (jgwill/Miadi#919) ────────────
+    const revisionOut = (r) => {
+        const live = all().find((x) => x.id === r.id) ?? r;
+        return {
+            request_id: live.id,
+            version: versionOf(live),
+            approval_url: approvalUrl(live.id),
+            projection: requestProjection(live, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
+        };
+    };
+    server.registerTool("revise_pending_request", {
+        title: "Revise a request that still awaits a decision",
+        description: "Change an agent run or a work proposal that waits for a decision, or that its approver sent back for revision, without making a new request. The request keeps its id, its approval page and its one card; the new content becomes the next version and every earlier version stays readable with get_request_history. Pass the version you are revising as expected_version: a request revised or decided since then is refused. Give only the fields that change. A request already approved, queued or declined is not revised: a change after a decision is a new request or a steer. Call show_decisions afterwards so the person sees the one current card.",
+        inputSchema: {
+            request_id: z.string().min(1).describe("The request's id, run_request:<uuid> or work_proposal:<uuid>."),
+            expected_version: z.number().int().min(1).describe("The version you read and are revising (projection.version, 1 for a request never revised)."),
+            reason: z.string().min(1).max(2000).describe("Why it changes, in the person's words when they gave them."),
+            changes: z
+                .object({
+                task: z.string().min(1).max(12000).optional().describe("Agent run: what the session does and returns."),
+                title: z.string().min(1).max(200).optional().describe("Work proposal: its title."),
+                desired_outcome: z.string().min(1).max(6000).optional().describe("Work proposal: what should exist when it is done."),
+                repo: z.string().max(120).optional(),
+                intention: z.string().max(2000).optional(),
+                circle: circle.optional(),
+                refs: z.array(z.string()).max(50).optional().describe("The whole new list of refs, replacing the old one."),
+                primary_issue: primaryIssue,
+                session: z.string().regex(/^[A-Za-z0-9._-]{3,80}$/).optional(),
+                cwd: z.string().max(300).optional(),
+                provider: z.enum(["codex", "pi", "copilot", "claude"]).optional().describe("Verified installed on the connector host again, as request_authorized_run does."),
+                steering: z
+                    .object({ max_attempts: z.number().int().min(1).max(20), expires_at: z.string().optional(), pane: z.string().regex(/^\d+\.\d+$/).optional() })
+                    .optional(),
+            })
+                .describe("Only the fields that change."),
+            idempotency_key: z.string().max(200).optional().describe("Repeat the same key to get the same revision back instead of a second one."),
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        const raw = ledger.all();
+        if (a.idempotency_key) {
+            const prior = raw.find((r) => r.supersedes === a.request_id && r.revision && r.idempotency_key === a.idempotency_key && r.actor.person_id === person.id);
+            if (prior)
+                return { ...revisionOut({ ...prior, id: a.request_id }), revised: prior.revision, repeated: true };
+        }
+        const live = all().find((r) => r.id === a.request_id);
+        const c = (a.changes ?? {});
+        const body = { ...(live?.body ?? {}) };
+        let provider;
+        if (live?.kind === "run_request") {
+            for (const k of ["task", "session", "cwd"])
+                if (c[k] !== undefined)
+                    body[k] = c[k];
+            if (c.steering !== undefined)
+                body.steering = c.steering;
+            if (c.provider !== undefined) {
+                const resolution = resolveProvider(c.provider, discoverProviders(ctx.providersProbe));
+                if (resolution.state === "provider_unknown")
+                    throw new ToolRefusal("invalid_request", resolution.message, { available: resolution.available });
+                if (resolution.state !== "ok")
+                    return { state: resolution.state, message: resolution.message, available: resolution.available, note: "Nothing was recorded; the request stays at its version." };
+                body.provider = c.provider;
+                body.resolved_provider = resolution.provider.id;
+                provider = { requested: c.provider, resolved: resolution.provider.id, explicit: resolution.explicit, version: resolution.provider.version };
+            }
+        }
+        else if (live?.kind === "work_proposal") {
+            for (const k of ["title", "desired_outcome", "repo"])
+                if (c[k] !== undefined)
+                    body[k] = c[k];
+        }
+        if (c.primary_issue !== undefined)
+            body.primary_issue = c.primary_issue;
+        const nextRefs = withPrimary(c.refs ?? live?.refs ?? [], c.primary_issue ?? body.primary_issue);
+        let record;
+        try {
+            record = revisionRecord(live, { intention: c.intention ?? live?.intention, circle: c.circle ?? live?.circle, refs: nextRefs, body }, {
+                id: newRecordId(live?.kind ?? "run_request"),
+                person: { id: person.id, name: person.name, writer: person.api_tier === "write" },
+                actor: actorOf(person, auth),
+                expectedVersion: a.expected_version,
+                reason: a.reason,
+                beingDecided: isBeingDecided(a.request_id),
+                idempotency_key: a.idempotency_key,
+            });
+        }
+        catch (error) {
+            if (error instanceof RevisionRefused) {
+                throw new ToolRefusal(error.code, error.message, { ...(error.detail ?? {}), ...(live ? revisionOut(live) : {}) });
+            }
+            throw error;
+        }
+        ledger.append(record);
+        return {
+            ...revisionOut(record.supersedes ? { ...record, id: record.supersedes } : record),
+            revised: record.revision,
+            ...(provider ? { provider } : {}),
+            note: `One request, one approval: its page and card now show version ${record.revision.version}. Earlier versions stay readable with get_request_history.`,
+        };
+    }));
+    server.registerTool("get_request_history", {
+        title: "Every version of a request",
+        description: "Every version of an agent run or work proposal, oldest first, with who changed it, when, why, which fields changed and each version's content hash, and the decisions taken on it. Earlier requests joined to it as its earlier versions (supersede_pending_requests) are included. A request retired that way names the request that stands.",
+        inputSchema: { request_id: z.string().min(1) },
+        annotations: READ,
+    }, wrap(async ({ request_id }, extra) => {
+        const { person } = who(extra);
+        const live = all().find((r) => r.id === request_id);
+        if (!live || !isApprovable(live))
+            return { state: "not_found", request_id };
+        if (person.api_tier !== "write" && live.actor.person_id !== person.id) {
+            throw new ToolRefusal("forbidden", "A request's history is read by whoever asked and by people with Miadi's write tier.");
+        }
+        const raw = ledger.all();
+        const versions = requestHistory(request_id, raw, all()).map((v) => {
+            const content = v.content;
+            const shownBody = redact({ ...live, body: (content.body ?? {}) }).body;
+            return { ...v, content: { ...content, body: shownBody } };
+        });
+        const decisions = raw
+            .filter((r) => r.supersedes && versions.some((v) => v.request_id === r.supersedes) && !r.revision && !r.lineage && r.completion_receipt)
+            .map((r) => {
+            const rc = r.completion_receipt;
+            return { request_id: r.supersedes, at: rc.decided_at ?? r.created_at, decision: rc.decision, by: rc.decided_by?.name, version: rc.version, superseded_by: rc.superseded_by, instructions: rc.instructions, reason: rc.reason };
+        });
+        const receipt = (live.completion_receipt ?? {});
+        return {
+            request_id,
+            version: versionOf(live),
+            versions,
+            decisions,
+            ...(receipt.decision === "superseded" ? { superseded_by: receipt.superseded_by, note: `This request was retired as an earlier version of ${receipt.superseded_by}; read that one's history for every version.` } : {}),
+            projection: requestProjection(live, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
+        };
+    }));
+    server.registerTool("supersede_pending_requests", {
+        title: "Join earlier requests to the one that stands",
+        description: "For requests made before revise_pending_request existed, one new request per revision: name the request that stands and, by exact id, the earlier requests that are its earlier versions. Each named request must still await a decision and be asked by the same person; each is retired (it can no longer be approved, and its card and page say which request to decide instead) and becomes an earlier version of the standing request, readable with get_request_history. All are checked before anything is written. Never infer which requests are duplicates: retire only ids the person named or confirmed. A request already approved or queued is refused, never cancelled.",
+        inputSchema: {
+            request_id: z.string().min(1).describe("The request that stands, the one the person will decide."),
+            supersede: z.array(z.string().min(1)).min(1).max(10).describe("The exact ids of the earlier requests it replaces."),
+            reason: z.string().min(1).max(2000).describe("Why they are one mission, in the person's words when they gave them."),
+        },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        let out;
+        try {
+            out = supersedeRecords(all(), a.request_id, a.supersede, {
+                person: { id: person.id, name: person.name, writer: person.api_tier === "write" },
+                actor: actorOf(person, auth),
+                reason: a.reason,
+                beingDecided: isBeingDecided,
+                newId: newRecordId,
+            });
+        }
+        catch (error) {
+            if (error instanceof RevisionRefused)
+                throw new ToolRefusal(error.code, error.message, error.detail);
+            throw error;
+        }
+        for (const r of out)
+            ledger.append(r);
+        return {
+            ...revisionOut({ ...out[out.length - 1], id: a.request_id }),
+            retired: a.supersede,
+            note: "The standing request is now the one card to decide; the retired requests are its earlier versions (get_request_history).",
+        };
+    }));
     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.",
@@ -1539,7 +1714,8 @@ export function registerTools(server, ctx) {
                 id: r.id,
                 kind: r.kind,
                 kind_label: KIND_LABELS[r.kind] ?? r.kind,
-                title: titleOf(r),
+                title: versionOf(r) > 1 ? `${titleOf(r)} · version ${versionOf(r)}` : titleOf(r),
+                version: versionOf(r),
                 by: r.actor.name,
                 via: r.actor.client_name,
                 created_at: r.created_at,
@@ -1551,7 +1727,8 @@ export function registerTools(server, ctx) {
                 projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             }));
             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)])) : {};
+            // Each token is bound to the version its card shows: a card left open while the request is revised cannot approve it (#919).
+            const tokens = canDecide ? Object.fromEntries(actionable.map((r) => [r.id, ctx.decisionTokens.issue(r.id, person.id, auth.clientId, undefined, r.version)])) : {};
             const structured = {
                 decisions,
                 count: decisions.length,
@@ -1594,11 +1771,14 @@ export function registerTools(server, ctx) {
             const r = all().find((x) => x.id === a.record_id);
             if (!isApprovable(r))
                 throw new ToolRefusal("not_found", "No request with that id.");
-            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.");
             // 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 });
+            const check = ctx.decisionTokens.verify(a.decision_token, r.id, person.id, auth.clientId, undefined, versionOf(r));
+            if (check === "stale") {
+                throw new ToolRefusal("stale_version", `This card showed an earlier version; the request is now at version ${versionOf(r)}. Show the requests again and decide version ${versionOf(r)}.`, { projection: projectionNow() });
+            }
+            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}.`, { projection: projectionNow() });
             }
@@ -1612,9 +1792,12 @@ export function registerTools(server, ctx) {
                 decided = await decide(r, person, a.decision, ctx.approval, {
                     instructions,
                     via: `card:${String(client?.client_name ?? auth.clientId).slice(0, 50)}`,
+                    expectedVersion: versionOf(r),
                 });
             }
             catch (error) {
+                if (error instanceof StaleVersion)
+                    throw new ToolRefusal("stale_version", error.message, { projection: projectionNow() });
                 // 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() });
@@ -1627,7 +1810,7 @@ export function registerTools(server, ctx) {
                 : decision === "revision_requested"
                     ? `Sent back for revision by ${person.name}.`
                     : `Declined by ${person.name}.`;
-            const out = { record_id: r.id, decision, state, summary, receipt, projection };
+            const out = { record_id: r.id, version: versionOf(r), decision, state, summary, receipt, projection };
             return { structuredContent: out, content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
         }
         catch (error) {
@@ -1719,6 +1902,9 @@ export const TOOL_STATUS = {
     prepare_calendar_event: "live, contribute (draft and .ics only)",
     propose_session_completion: "live, contribute, needs_approval (decision recorded, nothing closed)",
     request_authorized_run: "live, contribute, needs_approval (queues a factory brief once approved; may name a verified provider and a bounded steering grant)",
+    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)",
     request_review_operation: "live, contribute, needs_approval",
     request_deep_diver: "live, contribute, needs_approval",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.13";
+export declare const VERSION = "0.1.15";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.13";
+export const VERSION = "0.1.15";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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",