@miadi/connector 0.1.12 → 0.1.14

package/README.md

@@ -20,7 +20,7 @@ Call `get_capabilities` first. It names the signed-in person, their Miadi API ti
 
 | kind | tools |
 |---|---|
-| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `read_episode_file` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `mission_status` `provider_capabilities` `search` `fetch` |
+| reads | `get_capabilities` `get_context` `list_circles` `get_circle` `list_sessions` `get_session` `get_evidence` `read_episode_file` `get_evaluations` `get_narrative_beats` `review_lookup` `review_versions` `handoff_status` `list_records` `get_run_result` `mission_status` `provider_capabilities` `mission_model_preflight` `search` `fetch` |
 | contributions | `append_observation` `open_inquiry` `link_records` `propose_narrative_beat` `record_evaluation` `register_source_intent` `record_handoff` `update_handoff` `prepare_calendar_event` `save_research` |
 | requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_session_steer` `request_review_operation` `request_deep_diver` `link_review_to_episode` `request_inquiry_episode` |
 | decisions in the conversation | `show_decisions` (cards), `decide_request` (called by the card only) |
@@ -42,13 +42,25 @@ 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.
 
+A mission is found by the issue it implements (jgwill/Miadi#913). `request_authorized_run` and `propose_work` take `primary_issue`; older requests are read by their first issue ref, as an inference. An issue held as primary by several requests answers `ambiguous_mission` with the candidates, an issue only cited answers `related_only`, and only a record id or a declared primary that no older request holds by inference (`contested`) authorizes a steer, release or closure (`identity.authorizes_actions`). A release receipt names artifact, target, production check and check time; record it as `completion_receipt.release` on a handoff that cites the mission. `released` is `verified` only when the connector confirms it itself (the target is `miadi-connector` and the running version is the one released); any other complete receipt within seven days is `receipt_recorded`, with who recorded it and whether that was the approver. Old checks are `stale`; a version string, a future date or an incomplete receipt is `claimed_unverified`. `closed` needs an approved `propose_session_completion` ending (`exit` or `complete_then_exit`) that names the mission in its `mission` field and ends one of the mission's sessions; a completed request is `request_completed`. A GitHub reference the connector cannot read is `unverified`, with the reason (`no_github_token`, `not_visible_to_token`…), never `not_found`.
+
 `request_session_steer` sends one authorized follow-up to one existing live agent, within the steering grant an approved run carries (`steering: { max_attempts, expires_at, pane }` on `request_authorized_run`). It peeks at the bound pane — the grant's pane or the session's first pane, never whichever pane is active — refuses a busy agent or a pane that is not an agent, types the exact instruction literally, and re-peeks to verify the agent accepted it (`accepted`) or only holds it at the prompt (`submitted`). Every attempt leaves a durable artifact with the instruction's sha256, its grant, its target and both captures. A steer the grant does not cover waits for one explicit scoped human decision on its `approval_url`, which runs exactly that instruction once.
 
-`request_authorized_run` may name a `provider` (`codex`, `pi`, `copilot`, `claude`). The connector verifies it is installed on the host before recording anything; an unknown or unavailable provider answers `provider_unavailable` and the mission stays unstarted. With no provider named, the first installed provider in the preference order is resolved and named in the brief; Claude Code is never chosen silently — it runs only when named. `provider_capabilities` (write tier) reports what the host has installed, the sign-in evidence, the preference order, and the read-only Jev routing preflight (`unconfigured` without `MIADI_JEV_URL`). A provider name inside a task's text selects nothing.
+`request_authorized_run` may name a `provider` (`codex`, `pi`, `copilot`, `claude`). The connector verifies it is installed on the host before recording anything; an unknown or unavailable provider answers `provider_unavailable` and the mission stays unstarted. With no provider named, the first installed provider in the preference order is resolved and named in the brief; Claude Code is never chosen silently — it runs only when named. `provider_capabilities` (write tier) reports what the host has installed, the sign-in evidence, the preference order, and the read-only Jev check: `unconfigured` without `JEV_AI_API_KEY` or `TYPESAFE_API_KEY` in the connector's environment, else the models Jev lists for the key (no charge). A provider name inside a task's text selects nothing.
+
+`mission_model_preflight` (write tier) answers, for one mission, which provider and model fit its task type and criticality, and how that is known: contract `miadi.mission_model_preflight` v1, candidates with their configured default model, sign-in evidence (config directory only), quota `unknown`, policy eligibility, a review floor, and a recommendation or an abstention with reasons. Its `decider.source` is `static_fallback`, `jev` or `synthetic_fixture`. Jev is asked only with `consult_jev: true` and a key on the host; it is sent task type, criticality and candidates, never task text, mission id or repository, and its answer is advisory: uncalibrated, below 0.8 or outside the contract, the preflight abstains. A reported `launch` on another provider than the approved one answers `provider_mismatch` before anything is asked. It authorizes nothing. `bench/model-preflight-bench.mjs` compares the 0.1.12 baseline, the static preflight and Jev on synthetic scenarios; `bench/results/` keeps the runs.
 
 ### Deciding inside the conversation
 
@@ -56,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/index.d.ts

@@ -5,7 +5,8 @@ export { MiadiOAuthProvider, SCOPES, SCOPE_READ, SCOPE_CONTRIBUTE, type Person }
 export { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, RECORD_KINDS, current, type ConnectorRecord, type CircleId, type ClaimCategory, type RecordKind, } from "./records.js";
 export { TOOL_STATUS } from "./tools.js";
 export { runBrief, readQueueState } from "./approve.js";
-export { PROVIDERS, discoverProviders, resolveProvider, routerPreflight, type ProviderAvailability, type ProviderId, type ProviderResolution, type RouterPreflight, } from "./providers.js";
-export { missionStatus, resolveMissionSubject, type MissionStatus, type MissionStatusDeps } from "./mission-status.js";
+export { PROVIDERS, discoverProviders, jevConfigOf, resolveProvider, routerPreflight, type JevConfig, type ProviderAvailability, type ProviderId, type ProviderResolution, type RouterPreflight, } from "./providers.js";
+export { missionStatus, primaryIssueOf, resolveMissionSubject, type MissionStatus, type MissionStatusDeps, type MissionIdentity } from "./mission-status.js";
+export { modelPreflight, candidatesFor, buildJevRequest, decisionState, jevAdapter, reviewFloor, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, JEV_CONFIDENCE_FLOOR, type ModelPreflight, type ModelCandidate, type JevAdapter, type JevRequest, } from "./model-preflight.js";
 export { AGENT_COMMANDS, BUSY_PATTERNS, STEER_STATUSES, checkGrant, isBusy, readSteerArtifact, steerAttempts, steerSession, steeringGrantOf, tmuxAdapter, type SteerDeps, type SteerResult, type SteerStatus, type SteeringGrant, type TmuxLike, } from "./steer.js";
 export { VERSION } from "./version.js";

package/dist/index.js

@@ -5,7 +5,8 @@ export { MiadiOAuthProvider, SCOPES, SCOPE_READ, SCOPE_CONTRIBUTE } from "./oaut
 export { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, RECORD_KINDS, current, } from "./records.js";
 export { TOOL_STATUS } from "./tools.js";
 export { runBrief, readQueueState } from "./approve.js";
-export { PROVIDERS, discoverProviders, resolveProvider, routerPreflight, } from "./providers.js";
-export { missionStatus, resolveMissionSubject } from "./mission-status.js";
+export { PROVIDERS, discoverProviders, jevConfigOf, resolveProvider, routerPreflight, } from "./providers.js";
+export { missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.js";
+export { modelPreflight, candidatesFor, buildJevRequest, decisionState, jevAdapter, reviewFloor, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, JEV_CONFIDENCE_FLOOR, } from "./model-preflight.js";
 export { AGENT_COMMANDS, BUSY_PATTERNS, STEER_STATUSES, checkGrant, isBusy, readSteerArtifact, steerAttempts, steerSession, steeringGrantOf, tmuxAdapter, } from "./steer.js";
 export { VERSION } from "./version.js";

package/dist/mission-status.d.ts

@@ -1,8 +1,19 @@
 /**
- * Read-only mission status (jgwill/Miadi#893, Phase 1A): where one mission
- * stands, joined from the connector ledger, the factory queue, tmux, Miadi's
- * session view and GitHub — with every stage named by its evidence, so an idle
- * pane or a merge is never read as completion.
+ * Read-only mission status (jgwill/Miadi#893, Phase 1A; corrected by #913): where
+ * one mission stands, joined from the connector ledger, the factory queue, tmux,
+ * Miadi's session view and GitHub — with every stage named by its evidence, so an
+ * idle pane, a merge, a version string or a completed request is never read as
+ * release or closure.
+ *
+ * Mission identity (#913 A). A record's *primary* issue is the one it implements:
+ * `body.primary_issue` when the requester declared it (provenance `declared`),
+ * else, for records made before that field, the first owner/repo#n in its refs
+ * (provenance `first_issue_ref`, an inference). Every other issue it cites is
+ * *related*. An issue or session reference resolves to one mission only when one
+ * candidate holds it as primary; several are `ambiguous_mission`, and a reference
+ * cited only as related is `related_only`. Newest-first selection is gone.
+ * Only `exact` (a record id) and `declared_primary` authorize a steer, release or
+ * closure against the answer; an inference names its candidate and authorizes nothing.
  *
  * The caller (tools.ts) decides the viewer's tier first: without the write
  * tier there are no operator details (live panes, session internals); the
@@ -19,20 +30,96 @@ export interface MissionSession {
     /** Present when Miadi's session view was joined (write tier). */
     miadi?: unknown;
 }
+/** What the connector could establish about a GitHub reference. `unverified` is never `not_found`: without access the connector cannot tell. */
+export interface IssueLookup {
+    state: string;
+    title?: string;
+    merged?: boolean;
+    /** Why the state is `unverified`: no_github_token, not_visible_to_token, token_rejected, forbidden_or_rate_limited, github_<status>, unreachable. */
+    access?: string;
+}
+/** A release receipt: what was released, where, and how production was checked, when. */
+export interface ReleaseEvidence {
+    artifact: string;
+    target: string;
+    verified_at: string;
+    verification: string;
+    /** The record that carries it and who made it. */
+    record: string;
+    by: string;
+    /** The receipt was recorded by the person who approved the mission. */
+    by_approver: boolean;
+    /** The version the connector itself is running, when the receipt's target is the connector. */
+    live_version?: string;
+}
+export interface ClosureEvidence {
+    record: string;
+    ending: string;
+    session_id: string;
+    /** The ending names one of the mission's own sessions. False when the mission names none to compare. */
+    session_bound: boolean;
+    decided_by?: string;
+    decided_at?: string;
+}
 export interface MissionStageTruth {
     approved: boolean;
+    /** The decision as taken: approve or approve_with_changes, the approver's instructions and what is still outstanding. */
+    approval: {
+        state: string;
+        choice?: string;
+        instructions?: string;
+        outstanding: string[];
+    };
     queued: boolean;
     delivered: boolean;
     /** "evidence" only while a bound session is live; an idle pane proves nothing. */
     running: "evidence" | "no_evidence";
-    pr_merged: "merged" | "open_or_absent" | "no_pr";
-    released: "evidence" | "no_evidence";
+    /** The run_request or work_proposal finished. This is the request, not the mission. */
+    request_completed: boolean;
+    /** "unverified": GitHub could not be read, so no merge state is claimed either way. */
+    pr_merged: "merged" | "open_or_absent" | "no_pr" | "unverified";
+    /**
+     * verified: the connector itself confirmed it: the receipt targets miadi-connector and the running version
+     * is the one released. receipt_recorded: a complete, fresh receipt (artifact, target, production check, time)
+     * recorded by the named person; the connector cannot check it. stale: the check is older than the freshness
+     * window. live_mismatch: the connector runs another version than its receipt names. claimed_unverified: a
+     * version, a published flag, an incomplete or future-dated release object. no_evidence: nothing.
+     */
+    released: "verified" | "receipt_recorded" | "stale" | "live_mismatch" | "claimed_unverified" | "no_evidence";
+    release_evidence?: ReleaseEvidence;
+    /** True only with an approved ending (exit or complete_then_exit) naming this mission in its `mission` field, for one of its sessions. A completed request is not a closure. */
     closed: boolean;
+    closure_evidence?: ClosureEvidence;
+}
+export type MissionResolution = "exact" | "declared_primary" | "inferred_primary" | "ambiguous_mission" | "related_only";
+export interface MissionCandidate {
+    id: string;
+    kind: string;
+    created_at: string;
+    /** primary: the reference is this record's primary issue. related: an issue it cites and does not implement. cited: a session it cites. */
+    relation: "primary" | "related" | "cited";
+    /** declared: body.primary_issue. first_issue_ref: inferred from the first issue in refs. cited_ref: the reference is in its refs. */
+    provenance: "declared" | "first_issue_ref" | "cited_ref";
+    primary_issue?: string;
+}
+export interface MissionIdentity {
+    resolution: MissionResolution;
+    /** A declared primary that another request also holds by inference: reported, not authorizing. */
+    contested?: boolean;
+    /** True only for exact and an uncontested declared_primary: a steer, release or closure may name this mission. */
+    authorizes_actions: boolean;
+    primary_issue?: {
+        ref: string;
+        provenance: "declared" | "first_issue_ref";
+    };
+    /** Every request citing the reference, newest first, with its relation. Empty for an exact id. */
+    candidates: MissionCandidate[];
 }
 export interface MissionStatus {
     ref: string;
     found: boolean;
     via?: string;
+    identity?: MissionIdentity;
     subject?: {
         id: string;
         kind: string;
@@ -48,9 +135,11 @@ export interface MissionStatus {
     sessions?: MissionSession[];
     issues?: {
         ref: string;
+        relation: "primary" | "related";
         state: string;
         title?: string;
         merged?: boolean;
+        access?: string;
     }[];
     steering?: {
         grant: "none" | "active" | "expired_grant" | "exhausted";
@@ -72,16 +161,33 @@ export interface MissionStatusDeps {
     paneBusy?: (session: string) => "busy" | "idle" | "unknown";
     /** Miadi's session view by session:<uuid> (write tier only). */
     sessionOf?: (id: string) => Promise<unknown>;
-    issueOf?: (owner: string, repo: string, n: string) => Promise<{
-        state: string;
-        title?: string;
-        merged?: boolean;
-    }>;
+    issueOf?: (owner: string, repo: string, n: string) => Promise<IssueLookup>;
+    /** The version a package runs at on this host, when the connector can know it (its own VERSION). */
+    liveVersionOf?: (pkg: string) => string | undefined;
+    /** How old a production check may be and still count as verified. Default seven days. */
+    releaseFreshnessMs?: number;
     now?: () => Date;
 }
-/** The record a mission reference resolves to, and how it was found. */
-export declare function resolveMissionSubject(ref: string, records: ConnectorRecord[]): {
-    record: ConnectorRecord;
+export declare const RELEASE_FRESHNESS_MS: number;
+/** The issue a mission implements, and how that is known. */
+export declare function primaryIssueOf(record: ConnectorRecord): {
+    ref: string;
+    provenance: "declared" | "first_issue_ref";
+} | undefined;
+export interface ResolvedSubject {
+    record?: ConnectorRecord;
     via: string;
-} | null;
+    resolution: MissionResolution;
+    contested?: boolean;
+    candidates: MissionCandidate[];
+}
+/** Whether a resolved reference may be acted on: an exact id, or a declared primary nobody else holds. */
+export declare function authorizesActions(found: Pick<ResolvedSubject, "resolution" | "contested">): boolean;
+/**
+ * The record a mission reference resolves to, how it was found, and every other
+ * candidate. `record` is absent when the reference is ambiguous or only related.
+ * Expects the folded ledger (`current()`), so a superseding record never stands
+ * as a mission of its own.
+ */
+export declare function resolveMissionSubject(ref: string, records: ConnectorRecord[]): ResolvedSubject | null;
 export declare function missionStatus(ref: string, records: ConnectorRecord[], deps: MissionStatusDeps): Promise<MissionStatus>;