@miadi/connector 0.1.20 → 0.1.21

package/README.md

@@ -20,9 +20,9 @@ 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` `mission_model_preflight` `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` `list_research_artifacts` `read_research_artifact` |
 | 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` |
+| requests (approved by a person) | `propose_work` `propose_session_completion` `request_authorized_run` `request_session_steer` `revoke_session_steering` `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) |
 
 - **Reads** need Miadi's read tier and stay within it. A person Miadi gives no API tier reaches only `get_capabilities`. Sessions need the write tier, because a session's name and pane are operator data. For the same reason, below the write tier a record someone else made shows no session, working folder or seat, and no long bodies.
@@ -60,7 +60,40 @@ A mission is found by the issue it implements (jgwill/Miadi#913). `request_autho
 
 **The agent's result (jgwill/Miadi#921).** An agent returns its work with `propose_session_completion` naming the mission in `mission`, from its bound session, with its evidence refs and, optionally, a structured `result`: `summary`, `outputs` (`ref`, `label`, `git_sha`), `tests` (`command`, `passed`, `failed`, `skipped`) and `blockers`. `mission_status` and `get_run_result` read it back by the mission id as `result`: the standing submission (the newest `verified` one: it names the mission, ends a bound session and was submitted with Miadi's write tier or the factory's writer token, which the connector records on the ending as `submitted_with_tier`; anything else naming the mission is `unverified_association` with an `association_code`, a mere citation `cited_only` and never a result), its summary, tests and blockers as the agent's claim, and each output typed and checked when read. A commit or file on GitHub is read through GitHub (`GITHUB_TOKEN` when the host has one): `verified` with its sha, `changed_since_submission` when its declared `git_sha` no longer matches or the file changed on its branch after the submission, `unverified` with the reason when GitHub cannot be read, never `not_found`. A connector record id the ledger does not hold is `not_found`. Bound sessions are taken from the factory's receipts for every reader, so the verdict is the same at every tier; below the write tier the session ids are left out. The completion decision stays the person's, and only a verified submission sets it: `stage_truth.completion` is `pending_approval`, `accepted`, `declined` or `revision_requested` (`none` for an unverified one, whose stage is `result_submitted_unverified`; an approved exit submitted below the write tier closes nothing), `pending_human_gates` lists what waits on a person with its approval page, and `mission_stage` names the furthest stage with evidence (`result_submitted_awaiting_completion_approval`, `completion_accepted`, `merged`, `released`, `closed`…). A duplicate submission (same session, ending and mission, still pending) is handed back with `replayed: true`, and `not_recorded` names what the second call carried that was not kept.
 
-`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. When the factory recorded the mission's pane, the steer goes to that pane id and nowhere else: another session is `stale_binding`, another pane `wrong_pane`, a replaced pane `stale_binding`, and text already at the prompt `composing` (nothing typed, Enter not pressed). A pane whose prompt box cannot be read (any TUI but Claude Code's today) is `blocked`. Every tmux address is exact (`=name:w.p`), because tmux otherwise matches a session by the start of its name. Only a steer that typed its instruction uses one of the grant's attempts (`typed`, and `attempts` in the answer). The connector's service steers through the tmux server of the user it runs as; `get_capabilities.steering` says whether that transport answers now, and while it does not, `request_session_steer` records nothing and uses no attempt. 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_session_steer` sends one person's correction to a running agent, within the steering grant an approved run carries (`steering: { max_attempts, expires_at, pane }` on `request_authorized_run`). Busy is the normal case (jgwill/Miadi#930).
+
+| who | owns | never does |
+|---|---|---|
+| The person, through ChatGPT or any client | one correction, in scope | watch tools, wait for idle, send it again |
+| The connector | who may send it, the grant, mission → session → runtime, idempotency, handing it to that session's inbox, reporting what happened | decide when the model reads it, type into a working agent's pane, call a forward a delivery |
+| The runtime (Claude Code hooks: `miadi-session-observability` 0.1.34, `hooks/steering_inbox.mjs`) | the inbox, its order, the checks again at consumption, when its model reads it | deliver anything to a subagent or to another session |
+| The model | reading it and changing what it does next | |
+
+The route comes from what each part signed: the factory's receipt names the session, Claude Code's own registry says it runs and in which pane, and the adapter's `adapter.json` says this session loaded its hooks. A wrong session is `stale_binding`, a wrong pane `wrong_pane`. A provider with no adapter, or a Claude session started before the adapter (hooks load at session start), answers `unsupported` with the reason and uses no attempt. No Claude Code behaviour is assumed of Codex, Copilot or Pi, and `get_capabilities.steering.contract` names the adapters that exist.
+
+The inbox is `$MIADI_STEERING_DIR` (default `<factory>/steering`), `<session_id>/pending/` and its siblings, one Unix account's, `0700`. The connector writes one envelope with fsync and rename. The adapter takes it at the next `PostToolUse` or `PostToolUseFailure` as `additionalContext` in the same turn, or at `Stop` with `decision: block` when no further tool follows. A correction landing while the turn ends, after `Stop` has looked, is caught by a background watcher that runs for 30 seconds after each turn (`asyncRewake`): exit 2 wakes the model with it, so a working agent never waits for idle or a timer. A seat already idle is typed at once (below). The factory runner's next pass is the last net for anything left (`wakeIdleSteers`, once per envelope, only if the prompt box is clear), for example a session that resumed with a correction waiting. `delivery.continuation` says which of these is coming: `next_tool_or_turn_end`, `runner_wakes_idle_seat` or `session_not_running`. One rename into `claimed/` decides who delivers, so it is delivered once and never replayed. The adapter checks the session, the hash, the expiry (the grant's, or one day) and revocation again when it consumes. The hook does not poll: it runs in the agent's own lifecycle, and nothing outside watches it. A hook on an interrupted tool does not consume, because Claude Code drops hook messages there, and a subagent's tool does not consume either.
+
+Why hooks: Claude Code 2.1.318 has a native mid-turn queue, and `claude --help` offers no outside door to it. Typing reaches it through the keyboard, which is the terminal heuristic this replaces. The cross-session socket (`messagingSocketPath`) belongs to Claude sessions speaking to each other: its protocol is not published, and a connector speaking it would pose as a session. `PostToolUse.additionalContext` and `Stop` are its documented interface, so that is the adapter. Pi, Codex and Copilot have their own in-turn mechanisms, and none has an adapter here yet.
+
+`delivery` in the answer, in `get_run_result` on the steer's id, and in `mission_status.steering.steers` (write tier) says where it stands, each state with its source and time:
+
+| state | means | source |
+|---|---|---|
+| `authorized` | the grant or a person's decision covered it | connector |
+| `forwarded_to_runtime`, `queued_at_runtime` | it is in the session's inbox; the model has not necessarily read it | connector, runtime inbox |
+| `delivered_to_agent_context` | Claude Code recorded it entering the context | the transcript's attachment record |
+| `acknowledged` | the agent's own next text names `steer <id> received` | the transcript |
+| `behavior_adjusted` | a later tool input holds what the steer named in `expect_next_action`; without that, `behavior: not_judged` and the next actions are shown for a person to judge | the transcript |
+| `unsupported`, `expired`, `blocked` | it never reached the model, with the reason | connector or runtime hook |
+| `unknown` | claimed with no transcript record: ambiguous, and it is not sent again | |
+
+The record itself moves with its evidence: `completed` once the model has it, `blocked` once it never will, on the next read by anyone. So the ledger, `mission_status` and the decision surfaces say the same thing.
+
+`revoke_session_steering` stops a run's steering or one steer. What is still pending moves out at once, a marker stops anything later, and the answer says exactly what was revoked and what the agent had already consumed. The same idempotency key gets the first answer back, and the same words under a new key answer `duplicate`. Only a typed or forwarded steer uses one of the grant's attempts.
+
+An idle seat has no continuation coming, so it is the one case still typed: into the mission's bound pane, never whichever pane is active, with an exact tmux address (`=name:w.p`). It peeks first and re-peeks after. Text already at the prompt, or a prompt box that cannot be read, goes to the inbox when the seat has one and otherwise is `composing` or `blocked`, with nothing typed. A pane echo is not delivery: only a user record in the transcript moves it to `delivered_to_agent_context`. Every attempt leaves a durable artifact with the instruction's sha256, its grant and its target. The connector's service reaches the tmux server of the user it runs as; `get_capabilities.steering` says whether that answers now, and while it does not, `request_session_steer` records nothing and uses no attempt. A steer the grant does not cover waits for one explicit scoped human decision on its `approval_url`, which runs exactly that instruction once.
+
+Rollback: run the connector version before this one (`git checkout` of its `dist`, then `systemctl --user restart miadi-connector`). A working agent's steer then answers `busy` again and nothing else changes. To stop the runtime half, remove the plugin's `steering_inbox.sh` entries from `hooks/hooks.json`; a new session then has no `adapter.json` and answers `unsupported`. Envelopes already queued stay on disk, unread.
 
 `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 that may be picked by default (Pi, then Copilot) is resolved and named in the brief; Codex and Claude Code are never chosen silently, each 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.
 
@@ -101,7 +134,7 @@ MIADI_CONNECTOR_PUBLIC_URL=https://mcp.sanctuaireagentique.com node packages/con
 | `MIADI_REVIEW_BASE_URL` | `https://miadi-review-service.vercel.app` | the review service |
 | `MIADI_REVIEW_TOKEN` | read from `~/.env` | review search and approved review operations |
 | `MIADI_FACTORY_DIR` | `~/.miadi/factory` | the queue approved runs are written to |
-| `MIADI_INQUIRY_DIR` | `/a/src/IAIP/prototypes/artefacts` | the inquiry shelf `save_research` writes to, inside a git checkout it pushes |
+| `MIADI_INQUIRY_DIR` | `/a/src/IAIP/prototypes/artefacts` | the inquiry shelf `save_research` writes to, inside a git checkout it pushes, and `list_research_artifacts` and `read_research_artifact` read back |
 | `MIADI_INQUIRY_GITHUB_REPO` | `miadisabelle/Etuaptmumk-RSM` | where a saved report's inquiry issue is opened, with the host's `gh` login |
 | `MIADI_CONNECTOR_DECISION_TOKEN_TTL` | `604800` (7 days) | seconds a card's decision token stays usable, held between 300 and 2592000 |
 | `MIADI_CONNECTOR_DECISION_WAIT_MS` | `20000` | how long a decision answer waits for its run before answering it as recorded and running, at most 50000 |

package/dist/approve.d.ts

@@ -16,6 +16,7 @@ import type { MiadiClient } from "./miadi.js";
 import { type MiadiPerson } from "./people.js";
 import { type ConnectorRecord } from "./records.js";
 import { type RequestProjection } from "./request-state.js";
+import type { RuntimeDeps } from "./runtime-steer.js";
 import { type TmuxLike } from "./steer.js";
 import { type ProviderAuthorization } from "./provider-policy.js";
 export { factoryDir, runBriefFile, readQueueState } from "./queue-state.js";
@@ -32,6 +33,8 @@ export interface ApprovalDeps {
     tmux?: TmuxLike;
     /** Re-peek delay after a steer is typed (default 4000ms; tests pass 0). */
     steerSettleMs?: number;
+    /** Where sessions and their steering inboxes live (jgwill/Miadi#930). Absent, no runtime route is known. */
+    steeringRuntime?: RuntimeDeps;
     /** Where decision events go (default: one JSON line on stdout, the service journal); tests collect them. */
     log?: (event: Record<string, unknown>) => void;
 }

package/dist/approve.js

@@ -289,18 +289,21 @@ export async function executeApproved(record, approver, deps, instructions) {
                 return { outcome: "failed", message: "The run whose grant this steer cites is gone." };
             // The pane the factory delivered the mission to, when it recorded one (jgwill/Miadi#909).
             const bound = receiptsForRecord(readFactoryReceipts(factoryLedgerPath(deps.factoryDir ?? factoryDir())), grantRecord.id)[0];
-            const result = await steerSession({ tmux: deps.tmux ?? tmuxAdapter(), stateDir: deps.config.stateDir, ...(deps.steerSettleMs !== undefined ? { settleMs: deps.steerSettleMs } : {}) }, {
+            const result = await steerSession({ tmux: deps.tmux ?? tmuxAdapter(), stateDir: deps.config.stateDir, ...(deps.steeringRuntime ? { runtime: deps.steeringRuntime } : {}), ...(deps.steerSettleMs !== undefined ? { settleMs: deps.steerSettleMs } : {}) }, {
                 record,
                 grantRecord,
                 priorAttempts: steerAttempts(current(deps.ledger.all()), grantRecord.id),
                 authorized: true,
-                ...(bound ? { binding: { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}) } } : {}),
+                ...(bound ? { binding: { session: bound.tmux_session, ...(bound.pane_id ? { pane_id: bound.pane_id } : {}), ...(bound.session_id ? { session_id: bound.session_id } : {}), ...(bound.provider ? { provider: bound.provider } : {}) } } : {}),
             });
-            // A typed steer is never "failed": failed is re-runnable, and that would type it twice (#922 R8).
+            // A typed or forwarded steer is never "failed": failed is re-runnable, and that would send it twice (#922 R8).
             return {
-                outcome: result.typed ? result.status : "failed",
+                outcome: result.typed || result.forwarded ? result.status : "failed",
                 steer_status: result.status,
                 typed: result.typed,
+                ...(result.forwarded ? { forwarded: true } : {}),
+                ...(result.route ? { route: result.route } : {}),
+                ...(result.transcript_offset !== undefined ? { transcript_offset: result.transcript_offset } : {}),
                 message: result.message,
                 ...(result.target ? { target: result.target } : {}),
                 ...(result.artifact ? { artifact: result.artifact } : {}),
@@ -533,7 +536,7 @@ export async function rerun(r, person, deps, opts) {
             receipt = { ...receipt, ...outcome };
             if (outcome.outcome === "failed")
                 state = "blocked";
-            if (outcome.outcome === "queued")
+            if (outcome.outcome === "queued" || outcome.outcome === "queued_at_runtime")
                 state = "in_progress";
         }
         catch (error) {
@@ -600,7 +603,7 @@ async function decideOnce(r, person, choice, deps, opts) {
             receipt = { ...receipt, ...outcome };
             if (outcome.outcome === "failed")
                 state = "blocked";
-            if (outcome.outcome === "queued")
+            if (outcome.outcome === "queued" || outcome.outcome === "queued_at_runtime")
                 state = "in_progress";
         }
         catch (error) {

package/dist/bin.js

@@ -4,6 +4,7 @@ import { createConnectorApp } from "./server.js";
 import { identifyThroughMiadi } from "./people.js";
 import { steeringTransport } from "./tools.js";
 import { tmuxAdapter } from "./steer.js";
+import { defaultRuntime } from "./runtime-steer.js";
 import { VERSION } from "./version.js";
 const config = configFromEnv();
 // The host's steering surface (jgwill/Miadi#909): the tmux server of the user the service runs as,
@@ -13,6 +14,8 @@ const { app } = createConnectorApp(config, {
     identify: identifyThroughMiadi(config.miadiUrl),
     tmux,
     tmuxSessions: () => tmux.listSessions(),
+    // Each session's own steering inbox and Claude Code's registry of running sessions (jgwill/Miadi#930).
+    steeringRuntime: defaultRuntime(),
 });
 app.listen(config.port, config.host, () => {
     console.log(`@miadi/connector ${VERSION} on http://${config.host}:${config.port}`);

package/dist/mission-status.d.ts

@@ -21,6 +21,7 @@
  */
 import type { ConnectorRecord } from "./records.js";
 import type { RequestProjection } from "./request-state.js";
+import type { SteerDelivery } from "./runtime-steer.js";
 import type { FactoryReceipt } from "./factory-receipt.js";
 import { type GithubGet, type MissionResult } from "./mission-result.js";
 export interface MissionSession {
@@ -184,9 +185,18 @@ export interface MissionStatus {
         access?: string;
     }[];
     steering?: {
-        grant: "none" | "active" | "expired_grant" | "exhausted";
+        grant: "none" | "active" | "expired_grant" | "exhausted" | "revoked";
         attempts_used: number;
         max_attempts?: number;
+        /** Each correction sent under this mission and where it stands, by its own evidence (jgwill/Miadi#930; write tier). */
+        steers?: {
+            id: string;
+            at: string;
+            by: string;
+            state: string;
+            route: string;
+            delivery: SteerDelivery;
+        }[];
     };
     stage_truth?: MissionStageTruth;
     /**
@@ -216,6 +226,8 @@ export interface MissionStatusDeps {
     tmuxSessions?: () => string[];
     /** Read-only peek: is the named session's pane mid-turn? The pane id when the binding names one, else the first pane. (write tier only.) */
     paneBusy?: (session: string, paneId?: string) => "busy" | "idle" | "unknown";
+    /** Where one steer stands, read from the runtime's inbox and the session's transcript (write tier only). */
+    steerDeliveryOf?: (steer: ConnectorRecord) => SteerDelivery | null;
     /** Whether the tmux session still holds the pane id (write tier only); undefined when it cannot be listed. */
     panePresent?: (session: string, paneId: string) => boolean | undefined;
     /** The factory runner's delivery receipts for one record, newest first (write tier only). */

package/dist/mission-status.js

@@ -1,4 +1,4 @@
-import { steerAttempts, steeringGrantOf, checkGrant } from "./steer.js";
+import { steerAttempts, steeringGrantOf, steeringRevoked, checkGrant } from "./steer.js";
 import { missionResult, redactResult, submittedWithWriteTier } from "./mission-result.js";
 const ISSUE_REF = /^([\w.-]+)\/([\w.-]+)#(\d+)$/;
 const SESSION_REF = /^session:([0-9a-f-]{36})$/;
@@ -389,8 +389,14 @@ export async function missionStatus(ref, records, deps) {
     }
     const grant = steeringGrantOf(record);
     const attempts = steerAttempts(records, record.id);
-    const grantCheck = grant ? checkGrant(grant, attempts, now) : null;
-    const grantState = grantCheck === null ? "none" : grantCheck === "ok" ? "active" : grantCheck === "expired_grant" ? "expired_grant" : "exhausted";
+    const grantCheck = grant ? checkGrant(grant, attempts, now, steeringRevoked(records, record.id)) : null;
+    const grantState = grantCheck === null ? "none" : grantCheck === "ok" ? "active" : grantCheck === "expired_grant" ? "expired_grant" : grantCheck === "revoked" ? "revoked" : "exhausted";
+    const steers = deps.steerDeliveryOf
+        ? records.filter((r) => r.kind === "session_steer_request" && r.refs.includes(record.id)).flatMap((r) => {
+            const delivery = deps.steerDeliveryOf(r);
+            return delivery ? [{ id: r.id, at: r.created_at, by: r.actor.name, state: delivery.state, route: delivery.route, delivery }] : [];
+        })
+        : [];
     const receipt = (record.completion_receipt ?? {});
     const anyLive = sessions.some((s) => s.live === "running");
     const prs = issues.filter((i) => i.merged !== undefined);
@@ -464,7 +470,7 @@ export async function missionStatus(ref, records, deps) {
         ...(queue ? { queue } : {}),
         sessions,
         issues,
-        steering: { grant: grantState, attempts_used: attempts, ...(grant?.max_attempts !== undefined ? { max_attempts: grant.max_attempts } : {}) },
+        steering: { grant: grantState, attempts_used: attempts, ...(grant?.max_attempts !== undefined ? { max_attempts: grant.max_attempts } : {}), ...(steers.length ? { steers } : {}) },
         ...(provider ? { provider } : {}),
         stage_truth: stageTruth,
         mission_stage: missionStage(standing ?? null, stageTruth),

package/dist/records.d.ts

@@ -36,7 +36,7 @@ export declare const DOMAINS: readonly ["creative", "ceremonial", "engineering"]
 /** #815 "claim category": what kind of statement a record makes. */
 export declare const CLAIM_CATEGORIES: readonly ["observed", "hypothesis", "desired_future", "fiction", "verified_implementation"];
 export type ClaimCategory = (typeof CLAIM_CATEGORIES)[number];
-export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request", "session_steer_request", "provider_choice", "provider_policy"];
+export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request", "session_steer_request", "steering_revocation", "provider_choice", "provider_policy"];
 export type RecordKind = (typeof RECORD_KINDS)[number];
 /** #816 handoff states. */
 export declare const HANDOFF_STATES: readonly ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];

package/dist/records.js

@@ -61,6 +61,8 @@ export const RECORD_KINDS = [
     "research_artifact",
     "inquiry_episode_request",
     "session_steer_request",
+    // A person stops a run's steering, or one steer still waiting at the runtime (jgwill/Miadi#930).
+    "steering_revocation",
     // A requester's own per-mission provider choice and provider policy, made on the connector's pages (jgwill/Miadi#926).
     "provider_choice",
     "provider_policy",

package/dist/request-state.js

@@ -29,7 +29,12 @@ const OUTCOME_WORDS = {
     marked_ready: "marked ready for Deep Diver",
     decided: "recorded",
     nothing_to_run: "nothing to run",
-    accepted: "accepted by the session",
+    accepted: "typed into an idle session, which turned busy; its delivery says whether the model read it",
+    queued_at_runtime: "handed to the session's inbox, on its way to the model",
+    delivered_to_agent_context: "delivered: the model has it",
+    acknowledged: "delivered, and the agent said so",
+    behavior_adjusted: "delivered, and the agent's next action shows it",
+    expired: "expired before the model read it",
     submitted: "typed into the session, acceptance unconfirmed",
     failed: "failed",
 };

package/dist/research-digest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a shelf report is, read from its own Markdown, for a shelf a person can look through: its
+ * title, its opening, how long it is, what is inside, how many sources it cites. Everything here is
+ * computed from the file; nothing is summarised or invented. jgwill/Miadi#879.
+ */
+export interface ReportDigest {
+    title: string;
+    /** The document names itself; otherwise the title is its folder's name. */
+    titled: boolean;
+    /** The report's first paragraph of prose, without Markdown marks. */
+    excerpt?: string;
+    words: number;
+    minutes: number;
+    /** Its `##` and `###` headings, in order. */
+    headings: string[];
+    sections: number;
+    /** Distinct web addresses it cites. */
+    sources: number;
+}
+/** `jacqueline-m-quinless-…-261029-0e1f…` → `jacqueline m quinless …`: the date and uuid a folder name ends in are not its name. */
+export declare function folderTitle(name: string): string;
+export declare function digestReport(markdown: string, folder: string): ReportDigest;
+/**
+ * The text as the page shows it. A stray fence would turn the rest of a report into one code box, so
+ * a fence with no close in reach is left out of the display. The file itself is never changed.
+ */
+export declare function readableMarkdown(markdown: string): {
+    markdown: string;
+    repaired: boolean;
+};

package/dist/research-digest.js

@@ -0,0 +1,104 @@
+/**
+ * What a shelf report is, read from its own Markdown, for a shelf a person can look through: its
+ * title, its opening, how long it is, what is inside, how many sources it cites. Everything here is
+ * computed from the file; nothing is summarised or invented. jgwill/Miadi#879.
+ */
+const WORDS_PER_MINUTE = 230;
+const MAX_HEADINGS = 6;
+const MAX_EXCERPT = 280;
+/** A stray fence must not swallow a report: a block longer than this is not treated as code. */
+const MAX_FENCE_LINES = 60;
+const MAX_TITLE = 100;
+/** `jacqueline-m-quinless-…-261029-0e1f…` → `jacqueline m quinless …`: the date and uuid a folder name ends in are not its name. */
+export function folderTitle(name) {
+    const bare = name
+        .replace(/^ep\d+[-_]/i, "")
+        .replace(/-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, "")
+        .replace(/-\d{6,10}(-[0-9a-f]{6,})?$/i, "")
+        .replace(/[-_]+/g, " ")
+        .trim();
+    return bare ? bare[0].toUpperCase() + bare.slice(1) : name;
+}
+function plain(text) {
+    return text
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/[`*_~]+/g, "")
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** The lines outside fenced code, with a fence left alone when no close comes within reach. */
+function outsideFences(lines) {
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const open = /^(```|~~~)/.exec(lines[i]);
+        if (!open) {
+            out.push(lines[i]);
+            continue;
+        }
+        const close = lines.slice(i + 1, i + 1 + MAX_FENCE_LINES).findIndex((l) => l.trimEnd() === open[1]);
+        if (close < 0)
+            continue;
+        i += close + 1;
+    }
+    return out;
+}
+/** A heading that is a prompt, a command or a chat fragment is not the document's name. */
+const nameable = (t) => t.length > 0 && t.length <= MAX_TITLE && !/^@/.test(t) && !/\s--[a-z]/.test(t) && !/^(hey|hi|ok|okay|so|please|can you|could you)\b/i.test(t);
+/** How a document was made is not what it is about. */
+const PROVENANCE = /^(parent vessel|inquiry vessel|author role|mission|seed for|for the author's review|rendered from|status:|date:|woven to|generated)\b|\/(srv|workspace|a\/src|home)\/|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+export function digestReport(markdown, folder) {
+    const clean = outsideFences(markdown.replace(/^---\n[\s\S]*?\n---\n/, "").split("\n"));
+    const body = clean.join("\n");
+    const h1 = clean.find((l) => /^#\s+\S/.test(l));
+    const h1Text = h1 ? plain(h1.replace(/^#\s+/, "")) : "";
+    const headings = clean.filter((l) => /^#{2,3}\s+\S/.test(l)).map((l) => plain(l.replace(/^#+\s+/, "")));
+    let excerpt;
+    for (const block of body.split(/\n\s*\n/)) {
+        const t = block.trim();
+        if (!t || /^(#|\||>|[-*+]\s|\d+\.\s|!\[|<|---|===)/.test(t))
+            continue;
+        const p = plain(t);
+        if (p.split(" ").length < 8 || PROVENANCE.test(p))
+            continue;
+        excerpt = p.length > MAX_EXCERPT ? `${p.slice(0, MAX_EXCERPT).replace(/\s+\S*$/, "")}…` : p;
+        break;
+    }
+    const words = plain(body.replace(/^#+\s+/gm, "")).split(" ").filter(Boolean).length;
+    const titled = nameable(h1Text);
+    return {
+        title: titled ? h1Text : folderTitle(folder),
+        titled,
+        ...(excerpt ? { excerpt } : {}),
+        words,
+        minutes: Math.max(1, Math.round(words / WORDS_PER_MINUTE)),
+        headings: headings.slice(0, MAX_HEADINGS),
+        sections: headings.length,
+        sources: new Set(markdown.match(/https?:\/\/[^\s)\]>"']+/g) ?? []).size,
+    };
+}
+/**
+ * The text as the page shows it. A stray fence would turn the rest of a report into one code box, so
+ * a fence with no close in reach is left out of the display. The file itself is never changed.
+ */
+export function readableMarkdown(markdown) {
+    const lines = markdown.split("\n");
+    const out = [];
+    let repaired = false;
+    for (let i = 0; i < lines.length; i++) {
+        const open = /^(```|~~~)/.exec(lines[i]);
+        if (!open) {
+            out.push(lines[i]);
+            continue;
+        }
+        const close = lines.slice(i + 1, i + 1 + MAX_FENCE_LINES).findIndex((l) => l.trimEnd() === open[1]);
+        if (close < 0) {
+            repaired = true;
+            continue;
+        }
+        out.push(...lines.slice(i, i + close + 2));
+        i += close + 1;
+    }
+    return { markdown: out.join("\n"), repaired };
+}

package/dist/research-shelf.d.ts

@@ -0,0 +1,173 @@
+import { type ArtefactWeave } from "@miadi/inquiry-weave";
+import { type ReportDigest } from "./research-digest.js";
+/** A saved report may be 1 MB of characters; several times that is not a document anyone reads through a tool. */
+export declare const MAX_SHELF_FILE_BYTES: number;
+export declare class ShelfRefusal extends Error {
+    readonly code: "invalid_ref" | "not_found" | "forbidden";
+    constructor(code: "invalid_ref" | "not_found" | "forbidden", message: string);
+}
+/** Who may read a folder. `weave` is undefined for a folder no one saved through a door. */
+export declare function canReadShelf(weave: ArtefactWeave | undefined, person: {
+    id: string;
+    api_tier: string | null;
+}): boolean;
+export interface ShelfReadOptions {
+    file?: string;
+    offset?: number;
+    revision?: string;
+    maxBytes?: number;
+}
+/** The folder's manifest, and one file's page when a file is named or the folder holds its report. */
+export declare function readShelfArtefact(root: string, name: string, person: {
+    id: string;
+    api_tier: string | null;
+}, opts?: ShelfReadOptions): Promise<{
+    note: string;
+    files_truncated?: string | undefined;
+    episodes: string[];
+    git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files: {
+        path: string;
+        bytes: number;
+        sha256?: string;
+        readable: boolean;
+    }[];
+    saved?: {
+        file: string;
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via: string | undefined;
+        refs: string[];
+    } | undefined;
+    issue?: string | undefined;
+    issue_url?: string | undefined;
+    circle?: string | undefined;
+    visibility: "circle" | "published" | "private" | "proposed";
+    owner?: {
+        person_id: string;
+        name: string | undefined;
+    } | undefined;
+    artefact: string;
+} | {
+    page: {
+        offset: number;
+        end: number;
+        bytes: number;
+        sha256: string;
+        complete: boolean;
+        next: {
+            offset: number;
+            revision: string;
+        } | null;
+    };
+    text: string;
+    modified_at?: string | undefined;
+    verification?: string | undefined;
+    bytes: number;
+    sha256: string;
+    verified: boolean;
+    file: string;
+    content_type: string;
+    integrity: string;
+    file_git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files_truncated?: string | undefined;
+    episodes: string[];
+    git: {
+        commit?: string;
+        committed_at?: string;
+        uncommitted_changes?: boolean;
+        state: "known" | "unknown";
+    };
+    files: {
+        path: string;
+        bytes: number;
+        sha256?: string;
+        readable: boolean;
+    }[];
+    saved?: {
+        file: string;
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via: string | undefined;
+        refs: string[];
+    } | undefined;
+    issue?: string | undefined;
+    issue_url?: string | undefined;
+    circle?: string | undefined;
+    visibility: "circle" | "published" | "private" | "proposed";
+    owner?: {
+        person_id: string;
+        name: string | undefined;
+    } | undefined;
+    artefact: string;
+}>;
+/** One thing on the shelf, as its own files say it is: computed from them, never summarised. */
+export interface ShelfListing extends ReportDigest {
+    ref: string;
+    artefact: string;
+    /** `report`: saved through a door, with its hash. `folder`: anything else with a document. `notes`: agent instructions or unreadable files only. */
+    kind: "report" | "folder" | "notes";
+    /** The document its title and opening come from, the one a reader opens on. */
+    main?: string;
+    files: number;
+    /** Saved, or last woven, or its main document's last change. */
+    at?: string;
+    owner?: {
+        person_id: string;
+        name?: string;
+    };
+    visibility: string;
+    circle?: string;
+    issue?: string;
+    issue_url?: string;
+    episodes: {
+        number?: number;
+        title: string;
+    }[];
+    saved?: {
+        sha256: string;
+        bytes: number;
+        saved_at: string;
+        via?: string;
+        refs: string[];
+    };
+}
+/** One folder's listing. A folder that cannot be read is listed by its name. */
+export declare function shelfListing(root: string, name: string, weave: ArtefactWeave | undefined): ShelfListing;
+export type ShelfSort = "newest" | "oldest" | "longest" | "title";
+export declare function sortListings(items: ShelfListing[], sort?: ShelfSort): ShelfListing[];
+/**
+ * The shelf as this person may read it. `mine` is what they own. `all` is every folder, the write
+ * tier's alone, because a folder another person owns or no one owns is theirs to read and no one else's.
+ */
+export declare function listShelfArtefacts(root: string, person: {
+    id: string;
+    api_tier: string | null;
+}, opts?: {
+    scope?: "mine" | "all";
+    query?: string;
+    kind?: ShelfListing["kind"];
+    sort?: ShelfSort;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    scope: "mine" | "all";
+    total: number;
+    offset: number;
+    limit: number;
+    items: ShelfListing[];
+    next_offset: number | null;
+    read_with: string;
+}>;