opencode-courier 0.8.0 → 0.10.0

package/README.md

@@ -108,7 +108,7 @@ version than the pinned one writes one line to the server log
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.7.3, 0.8.0 | 2.0.32 |
+| 0.7.3, 0.8.0, 0.9.0, 0.10.0 | 2.0.32 |
 | 0.7.2 | 2.0.31 |
 | 0.7.1 | 2.0.30 |
 <!-- compat-table:end -->
@@ -246,13 +246,21 @@ Each spawned session's brief says when to split its task and when to do it itsel
 ## Memory
 
 The plugin keeps **one record per session tree** in the project, from facts it already has: when the
-tree started and last moved, the top session's title and `split:` line, and for each session started
+tree started and last moved, the top session's title and first `split:` line, with up to 3 later ones
+that read otherwise (when each was stated, and after how many parts), and for each session started
 in the tree its title, depth, isolation, join group, status, duration, cost, context use and spawns
-refused; never a report's body or artifacts. The one thing a model writes into it is **the tree's
+refused; never a report's body or artifacts. A session deleted since keeps its last status and
+duration, or reads `gone` when it had not settled, so it never holds its tree at `not finished`.
+The one thing a model writes into it is **the tree's
 lesson**, with `courier_note`: one line of at most 300 characters, from the session that verified the
-tree, with the job it comes from and the reason. `courier_recall` reads the records back; the
-`courier-orchestrate` skill asks for one call before the split decision and one `courier_note` before
-the top replies. Each project keeps its newest 30 records and none older than 90 days. `"memory":
+tree, with the job it comes from and the reason. `courier_recall` reads the records back, each line
+showing the split line as prose (its markdown marks dropped, the asterisks of its globs kept) cut at a
+word, then the latest later one (`then, after 1 part: split: 2 parts: …`), and saying how long the tree ran and how long ago it last moved; the `courier-orchestrate` skill asks for
+one call before the split decision and one `courier_note` before the top replies. Each record counts
+how often other trees' `courier_recall` calls listed it and opened it in full, and when last, so the
+person can tell a lesson still read from one nobody reads; a record the person pins in the terminal
+is listed first and never swept. Each project keeps 30 unpinned records, those with a lesson first,
+and none older than 90 days. `"memory":
 false` in the plugin's `options` turns it off ([more](docs/reference.md#memory)).
 
 ## In the terminal
@@ -292,10 +300,11 @@ permission prompt or form is shown in the session, OpenCode hides the footer, so
 `ctrl+x k`.
 
 `/courier memory` (or the palette's "Courier: memory") lists the project's [tree records](#memory),
-newest first, grouped by the day each tree last moved, one row each with its lesson under it.
-`enter` shows one in full; `x` forgets the record under the row, or in a record on its lesson's rows
-only the lesson, after a confirm; `esc` goes back and closes. The search takes every letter but `x`
-([more](docs/reference.md#the-memory-view)).
+pinned first, then newest first grouped by the day each tree last moved, one row each with how often
+other trees read it and its lesson under it. `enter` shows one in full; `p` pins or unpins the record,
+and a pinned one is listed first and never swept; `x` forgets the record under the row, or in a
+record on its lesson's rows only the lesson, after a confirm; `esc` goes back and closes. The search
+takes every letter but `x` and `p` ([more](docs/reference.md#the-memory-view)).
 
 ## Native child sessions
 

package/dist/kernel/protocol.d.ts

@@ -11,9 +11,15 @@ export type Status = (typeof STATUSES)[number];
 export declare const isStatus: (value: unknown) => value is Status;
 /** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
 export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+/** The third form, for the root alone: it hands a heavy task whole to one session, to keep its own context. */
+export declare const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+/** `SPLIT_LINE` with the root's third form: the root's pointer offers it, a child's brief and role part never do. */
+export declare const ROOT_SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part) or split: 1 part: <the task>, to keep my context";
 export declare const SKILL_ID = "courier-orchestrate";
 export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
 export declare function clipText(text: string, max?: number): string;
+/** `clipText` cut at the last space within `max` instead, so no word is cut in two, unless that keeps less than half of `max`. */
+export declare function clipWords(text: string, max: number): string;
 /** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
 export declare function defuse(text: string): string;
 /** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */

package/dist/kernel/protocol.js

@@ -10,6 +10,10 @@ export const STATUSES = ["done", "partial", "blocked", "failed"];
 export const isStatus = (value) => typeof value === "string" && STATUSES.includes(value);
 /** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
 export const SPLIT_LINE = "split: no, because …; considered: <the parts you weighed> or split: <n> parts: … (one phrase per part)";
+/** The third form, for the root alone: it hands a heavy task whole to one session, to keep its own context. */
+export const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+/** `SPLIT_LINE` with the root's third form: the root's pointer offers it, a child's brief and role part never do. */
+export const ROOT_SPLIT_LINE = `${SPLIT_LINE} or ${ONE_PART_LINE}`;
 export const SKILL_ID = "courier-orchestrate";
 export function envelope(from, message, attributes = {}) {
     const extra = Object.entries(attributes)
@@ -19,8 +23,16 @@ export function envelope(from, message, attributes = {}) {
 }
 /** Longest piece of free text (a review body, a generic payload) copied into a delivered message. */
 const MAX_TEXT = 1500;
+const clipped = (text, kept) => `${kept}… [${text.length - kept.length} more characters]`;
 export function clipText(text, max = MAX_TEXT) {
-    return text.length > max ? `${text.slice(0, max)}… [${text.length - max} more characters]` : text;
+    return text.length > max ? clipped(text, text.slice(0, max)) : text;
+}
+/** `clipText` cut at the last space within `max` instead, so no word is cut in two, unless that keeps less than half of `max`. */
+export function clipWords(text, max) {
+    if (text.length <= max)
+        return text;
+    const space = text.lastIndexOf(" ", max);
+    return clipped(text, (space >= max / 2 ? text.slice(0, space) : text.slice(0, max)).trimEnd());
 }
 /** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
 export function defuse(text) {

package/dist/memory/domain.d.ts

@@ -1,11 +1,11 @@
 /**
- * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line, the
- * retention and how a refresh keeps the parts the roster has forgotten. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
+ * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line and its revisions,
+ * its reads and pin, the retention and how a refresh keeps the parts the roster has forgotten. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
  */
 import { type Status } from "../kernel/protocol.js";
-/** How many records a project keeps, the newest by `movedAt`. */
+/** How many unpinned records a project keeps: those with a lesson first, then the newest by `movedAt`. */
 export declare const MAX_RECORDS = 30;
-/** Records that last moved longer ago than this are dropped when the plugin loads. */
+/** Unpinned records that last moved longer ago than this are dropped when the plugin loads. */
 export declare const RETENTION_MS: number;
 /** A record's `split` while its top has stated no split line. */
 export declare const NOT_STATED = "not stated";
@@ -13,11 +13,13 @@ export declare const NOT_STATED = "not stated";
 export declare const LESSON_MAX = 300;
 /**
  * How a part stands: its last report's status, how its wait ended without one (`failed`, `interrupted`), `stopped` by
- * courier_stop, `stalled` on a message it will not take, or `out`: it owes a report, running or not.
+ * courier_stop, `gone` before it settled, `stalled` on a message it will not take, or `out`: it owes a report.
  */
-export declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"];
+export declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
 export type PartStatus = (typeof PART_STATUSES)[number];
 export declare const isPartStatus: (value: unknown) => value is PartStatus;
+/** Whether a part has settled, as every part of a finished tree has: it neither owes a report nor is stalled. */
+export declare const isSettled: (status: PartStatus) => status is "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone";
 /** One session started in a tree, as its record keeps it; `duration` is in milliseconds, `context` a share of its model's window. */
 export interface PartRecord {
     readonly sessionID: string;
@@ -49,6 +51,29 @@ export interface Lesson {
     readonly at: number;
     readonly depth?: number;
 }
+/**
+ * How often other trees' courier_recall calls listed the record (`shown`) or gave it in full (`read`), and when one last
+ * did (`at`). Kept per reader tree and summed when read; a listing to the tree's own sessions counts nothing.
+ */
+export interface Reads {
+    readonly shown: number;
+    readonly read: number;
+    readonly at: number;
+}
+/** What a courier_recall call did with a record: listed it, or gave it in full. */
+export type ReadKind = "shown" | "read";
+/** The person's pin, set in the memory view: when. A pinned record is listed first and never swept. */
+export interface Pinned {
+    readonly at: number;
+}
+/** How many revisions of the split line a record keeps, the newest. */
+export declare const MAX_REVISIONS = 3;
+/** A later split line the top stated, worded otherwise than the one before it: when, and how many parts the tree had then. */
+export interface Revision {
+    readonly text: string;
+    readonly at: number;
+    readonly parts: number;
+}
 /** What is remembered of one tree: its top session and each session started in it, never a report's body or artifacts. */
 export interface TreeRecord {
     /** When the top session was created, epoch milliseconds. */
@@ -56,13 +81,22 @@ export interface TreeRecord {
     /** When a turn in the tree last ended, or the record was first written. */
     readonly movedAt: number;
     readonly title: string;
-    /** The top's split line, as `e2e/real-model-recursive.mjs` reads it, or `not stated`. */
+    /**
+     * The top's first split line, as `e2e/real-model-recursive.mjs` reads it, or `not stated`; a stated line takes precedence over a
+     * mention, which it replaces once, and is never replaced.
+     */
     readonly split: string;
+    /** Absent until the top states a split line worded otherwise than `split`; newest last, at most `MAX_REVISIONS`. */
+    readonly revisions?: ReadonlyArray<Revision>;
     /** Whether, at the last refresh, no session in the tree ran and every part had settled: none was out or stalled. */
     readonly finished: boolean;
     readonly recalled?: Recalled;
     /** Absent until a session of the tree that is not a leaf wrote one; a second note replaces the first. */
     readonly lesson?: Lesson;
+    /** Absent until another tree's courier_recall listed or read the record; kept beside the record, never written with it. */
+    readonly reads?: Reads;
+    /** Absent until the person pinned the record in the memory view; kept beside the record, never written with it. */
+    readonly pinned?: Pinned;
     readonly parts: ReadonlyArray<PartRecord>;
 }
 /** A record with where it is kept: its project and its top session. */
@@ -77,6 +111,29 @@ export declare function readMemory(options: unknown): {
 };
 /** The split line a text states, as the real-model checker reads it: a line beginning with `split:` after any markdown, else one holding it. */
 export declare function splitLineOf(text: string): string | undefined;
+/** Whether a split line is stated, beginning with `split:` after any markdown, not a passing mention nor `not stated`. */
+export declare const isStated: (line: string) => boolean;
+/** The record's `split` once `text` is read: kept once stated; a mention gives way to the first stated line; `not stated` to either. */
+export declare function splitOf(recorded: string, text: string): string;
+/** Every line of a text that begins with `split:` after any markdown, trimmed: a passing mention of a split is none. */
+export declare const splitLinesOf: (text: string) => string[];
+/** A split line the top's replies state, with when its reply was created when the message says. */
+export interface Stated {
+    readonly text: string;
+    readonly at?: number;
+}
+/**
+ * The revisions once the split lines `stated` are read at a refresh at `at` with `parts` parts: those `statedSince` the line recorded
+ * last, each appended when its words differ from the line before, so a re-read appends nothing.
+ */
+export declare function revise(previous: Pick<TreeRecord, "split" | "revisions">, stated: ReadonlyArray<Stated>, at: number, parts: number): Revision[] | undefined;
+/**
+ * The split and revisions once the stated line `found` replaces a mention: when `found` is among the revisions (recorded beside the
+ * mention before #294), the first of them was stated first and is `split`, the rest stay; else `found` is, beside them all.
+ */
+export declare function replacingMention(found: string, revisions: ReadonlyArray<Revision> | undefined): Pick<TreeRecord, "split" | "revisions">;
+/** A split line as the listing shows it: one line, without its block marks, the asterisks wrapping it or a span in it, nor an underscore or code span wrapping it. */
+export declare function splitProse(split: string): string;
 /** What a part's status is read from: whether courier_stop stopped it, whether it is stalled, and its report state. */
 export interface Standing {
     readonly stopped: boolean;
@@ -91,8 +148,13 @@ export interface Standing {
 /** A part's status by `Standing`; one whose report state is not known is still out. */
 export declare function partStatus({ stopped, stalled, report }: Standing): PartStatus;
 /**
- * The parts of a refreshed record: those recorded before, in their order, each as read now when the roster still has it,
- * else as last recorded, then those first seen now, in the order the tree is drawn.
+ * A part whose session could not be read, from what was read of it and its last record: its title, duration and cost as
+ * last recorded; once OpenCode no longer knows it (`gone`), settled as read, else as last recorded, else `gone`.
+ */
+export declare function unreadPart(read: PartRecord, last: PartRecord | undefined, gone: boolean): PartRecord;
+/**
+ * The parts of a refreshed record: those recorded before, in their order, each as `current` has it (read now, or found
+ * gone), else as last recorded, then those first seen now, in the order the tree is drawn.
  */
 export declare function mergeParts(previous: ReadonlyArray<PartRecord>, current: ReadonlyArray<PartRecord>): PartRecord[];
 /** `recalled` after one more call at `at`, the top's first call noted when `byTop`. */
@@ -110,10 +172,17 @@ export declare function lessonText(text: string): {
     text: string;
     clipped: number;
 };
-/** The records a project keeps at `now`: the newest `MAX_RECORDS` by `movedAt`, none older than `RETENTION_MS`; the rest are dropped. */
-export declare function keep<T extends Pick<StoredRecord, "movedAt">>(records: ReadonlyArray<T>, now: number): {
+/** One reader tree's `reads` after courier_recall listed the record or gave it in full at `at`. */
+export declare function noteRead(reads: Reads | undefined, kind: ReadKind, at: number): Reads;
+/** The reads of every reader tree as one: the counts summed, `at` the latest; none without a reader. */
+export declare function sumReads(reads: ReadonlyArray<Reads>): Reads | undefined;
+/**
+ * The records a project keeps at `now`: every pinned one, whatever its age, and of the rest the first `MAX_RECORDS` by
+ * whether each has a lesson, then by `movedAt`, none older than `RETENTION_MS`; the rest are dropped.
+ */
+export declare function keep<T extends Pick<StoredRecord, "movedAt" | "lesson" | "pinned">>(records: ReadonlyArray<T>, now: number): {
     kept: T[];
     dropped: T[];
 };
-/** Records newest first, by when each last moved. */
-export declare const newestFirst: <T extends Pick<StoredRecord, "movedAt">>(records: ReadonlyArray<T>) => T[];
+/** Records as courier_recall and the memory view list them: the pinned first, then by when each last moved, newest first. */
+export declare const pinnedFirst: <T extends Pick<StoredRecord, "movedAt" | "pinned">>(records: ReadonlyArray<T>) => T[];

package/dist/memory/domain.js

@@ -1,12 +1,12 @@
 /**
- * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line, the
- * retention and how a refresh keeps the parts the roster has forgotten. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
+ * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line and its revisions,
+ * its reads and pin, the retention and how a refresh keeps the parts the roster has forgotten. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
  */
 import { STATUSES } from "../kernel/protocol.js";
 import { obj } from "../platform/json.js";
-/** How many records a project keeps, the newest by `movedAt`. */
+/** How many unpinned records a project keeps: those with a lesson first, then the newest by `movedAt`. */
 export const MAX_RECORDS = 30;
-/** Records that last moved longer ago than this are dropped when the plugin loads. */
+/** Unpinned records that last moved longer ago than this are dropped when the plugin loads. */
 export const RETENTION_MS = 90 * 24 * 60 * 60_000;
 /** A record's `split` while its top has stated no split line. */
 export const NOT_STATED = "not stated";
@@ -14,10 +14,14 @@ export const NOT_STATED = "not stated";
 export const LESSON_MAX = 300;
 /**
  * How a part stands: its last report's status, how its wait ended without one (`failed`, `interrupted`), `stopped` by
- * courier_stop, `stalled` on a message it will not take, or `out`: it owes a report, running or not.
+ * courier_stop, `gone` before it settled, `stalled` on a message it will not take, or `out`: it owes a report.
  */
-export const PART_STATUSES = [...STATUSES, "interrupted", "stopped", "stalled", "out"];
+export const PART_STATUSES = [...STATUSES, "interrupted", "stopped", "gone", "stalled", "out"];
 export const isPartStatus = (value) => typeof value === "string" && PART_STATUSES.includes(value);
+/** Whether a part has settled, as every part of a finished tree has: it neither owes a report nor is stalled. */
+export const isSettled = (status) => status !== "out" && status !== "stalled";
+/** How many revisions of the split line a record keeps, the newest. */
+export const MAX_REVISIONS = 3;
 /** The `memory` option: whether records are kept and listed; on unless `false`. */
 export function readMemory(options) {
     const value = obj(options).memory;
@@ -34,6 +38,101 @@ export function splitLineOf(text) {
     const lines = text.split("\n");
     return (lines.find((line) => STARTS_SPLIT.test(line)) ?? lines.find((line) => HOLDS_SPLIT.test(line)))?.trim();
 }
+/** Whether a split line is stated, beginning with `split:` after any markdown, not a passing mention nor `not stated`. */
+export const isStated = (line) => STARTS_SPLIT.test(line);
+/** The record's `split` once `text` is read: kept once stated; a mention gives way to the first stated line; `not stated` to either. */
+export function splitOf(recorded, text) {
+    if (isStated(recorded))
+        return recorded;
+    const found = splitLineOf(text);
+    return found !== undefined && (recorded === NOT_STATED || isStated(found)) ? found : recorded;
+}
+/** Every line of a text that begins with `split:` after any markdown, trimmed: a passing mention of a split is none. */
+export const splitLinesOf = (text) => text
+    .split("\n")
+    .filter((line) => STARTS_SPLIT.test(line))
+    .map((line) => line.trim());
+/**
+ * The lines after the one recorded last: after its reply, else (compacted, or unread by an overlapping refresh) those stated since its
+ * time; without a revision, after `split`'s first statement; all when neither is found.
+ */
+function statedSince(previous, stated) {
+    const last = previous.revisions?.at(-1);
+    const words = (line) => splitProse(line.text);
+    if (!last)
+        return stated.slice(stated.findIndex((line) => words(line) === splitProse(previous.split)) + 1);
+    const inReply = stated.findLastIndex((line) => words(line) === splitProse(last.text) && line.at === last.at);
+    if (inReply >= 0)
+        return stated.slice(inReply + 1);
+    if (stated.some((line) => line.at !== undefined))
+        return stated.filter((line) => line.at !== undefined && line.at > last.at);
+    return stated.slice(stated.findLastIndex((line) => words(line) === splitProse(last.text)) + 1);
+}
+/**
+ * The revisions once the split lines `stated` are read at a refresh at `at` with `parts` parts: those `statedSince` the line recorded
+ * last, each appended when its words differ from the line before, so a re-read appends nothing.
+ */
+export function revise(previous, stated, at, parts) {
+    const recorded = splitProse(previous.revisions?.at(-1)?.text ?? previous.split);
+    const { added } = statedSince(previous, stated).reduce(({ last, added }, line) => {
+        const words = splitProse(line.text);
+        return words === last ? { last, added } : { last: words, added: [...added, { text: line.text, at: line.at ?? at, parts }] };
+    }, { last: recorded, added: [] });
+    const revisions = [...(previous.revisions ?? []), ...added].slice(-MAX_REVISIONS);
+    return revisions.length ? revisions : undefined;
+}
+/**
+ * The split and revisions once the stated line `found` replaces a mention: when `found` is among the revisions (recorded beside the
+ * mention before #294), the first of them was stated first and is `split`, the rest stay; else `found` is, beside them all.
+ */
+export function replacingMention(found, revisions) {
+    const [first, ...rest] = revisions ?? [];
+    if (!first || !revisions.some((one) => splitProse(one.text) === splitProse(found)))
+        return { split: found, ...(first ? { revisions } : {}) };
+    return { split: first.text, ...(rest.length ? { revisions: rest } : {}) };
+}
+/** Heading, quote and list marks before a line's words, each with the space markdown puts after it, unlike the `#` of `#282`. */
+const BLOCK_MARKS = /^(?:\s|#+\s|>\s|[-+*]\s|\d+[.)]\s)*/;
+/** A bold or bold italic span within a line, opening at a word's start and closing at its end, unlike the asterisks of `2**3` or a `**` beside a slash. */
+const BOLD = /(?<=^|[\s(["'])(\*\*\*?)([^\s*/][^*]*?)(?<![\s(/])\1(?=$|[\s.,;:!?)\]"'])/gu;
+/** An italic span opens only before a letter, digit, quote or code span, which tells it from the globs of `*.ts and *.md` or `src/*.ts`. */
+const ITALIC = /(?<=^|[\s(["'])\*([\p{L}\p{N}\0"'][^*]*?)(?<![\s(/])\*(?=$|[\s.,;:!?)\]"'])/gu;
+/** A label the line opens with in underscores or a code span (`_split:_`, `` `split:` ``), which its colon tells from `__init__`. */
+const LABEL = /^(__?|`)([^\s_`][^_`]*:)\1(?=\s)/;
+/** A code span, whose asterisks are its words', and the stand-in it is masked by while emphasis is taken off. */
+const CODE_SPAN = /`[^`]*`/g;
+const MASKED = /\0(\d+)\0/g;
+/** Marks taken off a line they wrap whole, with what its words must open with; `*` may recur inside as a glob's, the others not at all. */
+const STARS = [
+    ["***", /[^\s*/]/],
+    ["**", /[^\s*/]/],
+    ["*", /[\p{L}\p{N}\0"']/u],
+];
+const WRAPS = [
+    ["__", /[^\s_]/],
+    ["_", /[^\s_]/],
+    ["`", /[^\s`]/],
+];
+const unwrapped = (line, marks) => {
+    const inner = (mark) => line.slice(mark.length, -mark.length);
+    const wraps = ([mark, opens]) => {
+        const words = inner(mark);
+        const apart = mark === "*" ? !words.includes("* ") && !words.includes(" *") : !words.includes(mark);
+        return line.length > 2 * mark.length && line.startsWith(mark) && line.endsWith(mark) && opens.test(words[0]) && !/[\s(/]/.test(words.at(-1)) && apart;
+    };
+    const found = marks.find(wraps);
+    return found ? inner(found[0]).trim() : line;
+};
+/** A split line as the listing shows it: one line, without its block marks, the asterisks wrapping it or a span in it, nor an underscore or code span wrapping it. */
+export function splitProse(split) {
+    const code = [];
+    const masked = oneLine(split.replaceAll("\0", ""))
+        .replace(BLOCK_MARKS, "")
+        .replace(LABEL, "$2")
+        .replace(CODE_SPAN, (span) => `\0${code.push(span) - 1}\0`);
+    const prose = unwrapped(masked, STARS).replace(BOLD, "$2").replace(ITALIC, "$1");
+    return unwrapped(prose.replace(MASKED, (_, i) => code[Number(i)]), WRAPS);
+}
 /** A part's status by `Standing`; one whose report state is not known is still out. */
 export function partStatus({ stopped, stalled, report }) {
     if (stopped)
@@ -47,8 +146,18 @@ export function partStatus({ stopped, stalled, report }) {
     return report.status ?? "done";
 }
 /**
- * The parts of a refreshed record: those recorded before, in their order, each as read now when the roster still has it,
- * else as last recorded, then those first seen now, in the order the tree is drawn.
+ * A part whose session could not be read, from what was read of it and its last record: its title, duration and cost as
+ * last recorded; once OpenCode no longer knows it (`gone`), settled as read, else as last recorded, else `gone`.
+ */
+export function unreadPart(read, last, gone) {
+    const settledLast = last && isSettled(last.status) ? last.status : "gone";
+    const status = !gone || isSettled(read.status) ? read.status : settledLast;
+    const { title, duration, cost } = last ?? read;
+    return { ...read, title, status, ...(duration !== undefined ? { duration } : {}), ...(cost !== undefined ? { cost } : {}) };
+}
+/**
+ * The parts of a refreshed record: those recorded before, in their order, each as `current` has it (read now, or found
+ * gone), else as last recorded, then those first seen now, in the order the tree is drawn.
  */
 export function mergeParts(previous, current) {
     const now = new Map(current.map((part) => [part.sessionID, part]));
@@ -74,11 +183,27 @@ export function lessonText(text) {
         return { text: line };
     return { text: line.slice(0, LESSON_MAX).trimEnd(), clipped: line.length };
 }
-/** The records a project keeps at `now`: the newest `MAX_RECORDS` by `movedAt`, none older than `RETENTION_MS`; the rest are dropped. */
+/** One reader tree's `reads` after courier_recall listed the record or gave it in full at `at`. */
+export function noteRead(reads, kind, at) {
+    return { shown: (reads?.shown ?? 0) + (kind === "shown" ? 1 : 0), read: (reads?.read ?? 0) + (kind === "read" ? 1 : 0), at: Math.max(reads?.at ?? 0, at) };
+}
+/** The reads of every reader tree as one: the counts summed, `at` the latest; none without a reader. */
+export function sumReads(reads) {
+    if (!reads.length)
+        return undefined;
+    return reads.reduce((sum, one) => ({ shown: sum.shown + one.shown, read: sum.read + one.read, at: Math.max(sum.at, one.at) }));
+}
+/**
+ * The records a project keeps at `now`: every pinned one, whatever its age, and of the rest the first `MAX_RECORDS` by
+ * whether each has a lesson, then by `movedAt`, none older than `RETENTION_MS`; the rest are dropped.
+ */
 export function keep(records, now) {
-    const newest = records.toSorted((a, b) => b.movedAt - a.movedAt);
-    const kept = newest.filter((record, index) => index < MAX_RECORDS && now - record.movedAt <= RETENTION_MS);
-    return { kept, dropped: newest.filter((record) => !kept.includes(record)) };
+    const pinned = records.filter((record) => record.pinned);
+    // Aged out first, so that a stale record takes no slot from a live one behind it in the order.
+    const live = records.filter((record) => !record.pinned && now - record.movedAt <= RETENTION_MS);
+    const ordered = live.toSorted((a, b) => Number(Boolean(b.lesson)) - Number(Boolean(a.lesson)) || b.movedAt - a.movedAt);
+    const kept = [...pinned, ...ordered.slice(0, MAX_RECORDS)];
+    return { kept, dropped: records.filter((record) => !kept.includes(record)) };
 }
-/** Records newest first, by when each last moved. */
-export const newestFirst = (records) => records.toSorted((a, b) => b.movedAt - a.movedAt);
+/** Records as courier_recall and the memory view list them: the pinned first, then by when each last moved, newest first. */
+export const pinnedFirst = (records) => records.toSorted((a, b) => Number(Boolean(b.pinned)) - Number(Boolean(a.pinned)) || b.movedAt - a.movedAt);

package/dist/memory/index.d.ts

@@ -1,10 +1,11 @@
 export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
 export { memoryEvents, type MemoryEventPorts } from "./events.js";
 export { note, type Noted, type NoteInput } from "./note.js";
-export type { Lesson, MemoryPorts, MemoryState, PartRecord, PartStatus, Recalled, RefreshPorts, StoredRecord, TreeRecord } from "./ports.js";
+export { pin, type PinOutcome } from "./pin.js";
+export type { Lesson, MemoryPorts, MemoryState, PartRecord, PartStatus, Pinned, Reads, Recalled, RefreshPorts, Revision, StoredRecord, TreeRecord } from "./ports.js";
 export { recall, type Recall, type RecallInput } from "./recall.js";
 export { refresh } from "./record.js";
-export { registerMemoryRpc } from "./rpc-handlers.js";
+export { registerMemoryRpc, type MemoryRpcPorts } from "./rpc-handlers.js";
 export { sweepRecords } from "./sweep.js";
 export { NOTE_TOOL, RECALL_TOOL } from "./text.js";
 export { addMemoryTools, type MemoryToolPorts } from "./tools.js";

package/dist/memory/index.js

@@ -3,6 +3,7 @@
 export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
 export { memoryEvents } from "./events.js";
 export { note } from "./note.js";
+export { pin } from "./pin.js";
 export { recall } from "./recall.js";
 export { refresh } from "./record.js";
 export { registerMemoryRpc } from "./rpc-handlers.js";

package/dist/memory/pin.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryPorts } from "./ports.js";
+/** What pinning did: the record is pinned, unpinned, or there is no record to pin. */
+export type PinOutcome = "pinned" | "unpinned" | "none";
+/**
+ * Pins the record of the tree under `sessionID` in the ports' project, as the memory view's `p` does, or with `pinned`
+ * false unpins it; a record pinned already keeps when it was. Whatever the memory option says: a pin is the person's.
+ */
+export declare function pin(ports: Pick<MemoryPorts, "storage" | "projectID" | "now">, sessionID: string, pinned: boolean): Promise<PinOutcome>;

package/dist/memory/pin.js

@@ -0,0 +1,13 @@
+import { memoryStore } from "./store.js";
+/**
+ * Pins the record of the tree under `sessionID` in the ports' project, as the memory view's `p` does, or with `pinned`
+ * false unpins it; a record pinned already keeps when it was. Whatever the memory option says: a pin is the person's.
+ */
+export async function pin(ports, sessionID, pinned) {
+    const store = memoryStore(ports.storage);
+    const record = await store.get(ports.projectID, sessionID);
+    if (!record)
+        return "none";
+    await store.pin(ports.projectID, sessionID, pinned ? (record.pinned ?? { at: ports.now() }) : undefined);
+    return pinned ? "pinned" : "unpinned";
+}

package/dist/memory/ports.d.ts

@@ -2,8 +2,8 @@
 import type { Plugin } from "@opencode/plugin";
 import type { Storage } from "../platform/storage.js";
 import type { ModelWindow } from "../tree/index.js";
-import type { StoredRecord, TreeRecord } from "./domain.js";
-export type { Lesson, PartRecord, PartStatus, Recalled, StoredRecord, TreeRecord } from "./domain.js";
+import type { Pinned, ReadKind, Reads, StoredRecord, TreeRecord } from "./domain.js";
+export type { Lesson, PartRecord, PartStatus, Pinned, ReadKind, Reads, Recalled, Revision, StoredRecord, TreeRecord } from "./domain.js";
 type Context = Plugin.Context;
 /** What refreshing a record runs on: every hub-v2 member's watch ports have these, so the event module runs through any. */
 export interface RefreshPorts {
@@ -32,13 +32,24 @@ export interface MemoryState {
     /** The turn ends recorded, so the hub's two subscriptions refresh once. */
     readonly seen: Set<string>;
 }
-/** The records, by project and top session. */
+/** The records, by project and top session, each read with its reads and pin, which lie beside it and are written apart. */
 export interface MemoryStore {
     get(projectID: string, sessionID: string): Promise<TreeRecord | undefined>;
+    /** Writes the record's facts; its `reads` and `pinned` are left out, as nothing but `noteRead` and `pin` write them. */
     put(projectID: string, sessionID: string, record: TreeRecord): Promise<void>;
+    /** Removes the record with its reads and pin. */
     remove(projectID: string, sessionID: string): Promise<void>;
+    /** Counts a listing or a full read of the record by the tree under `by` at `at`; gives that tree's reads of it. */
+    noteRead(projectID: string, sessionID: string, by: string, kind: ReadKind, at: number): Promise<Reads>;
+    /** Pins the record, or with `undefined` unpins it. */
+    pin(projectID: string, sessionID: string, pinned: Pinned | undefined): Promise<void>;
     /** A project's records, in key order. */
     ofProject(projectID: string): Promise<StoredRecord[]>;
     /** Every project's records. */
     all(): Promise<StoredRecord[]>;
+    /** The trees with reads or a pin but no record, left by a record removed while it was read or pinned. */
+    strays(): Promise<Array<{
+        projectID: string;
+        sessionID: string;
+    }>>;
 }

package/dist/memory/recall.d.ts

@@ -21,7 +21,7 @@ export type Recall = {
     readonly sessionID: string;
 };
 /**
- * courier_recall: notes the call on the caller's tree, then lists the project's records newest first, or gives the one
- * under `sessionID` in full. With the memory option off, nothing is written or read.
+ * courier_recall: notes the call on the caller's tree, then lists the project's records, pinned first and then newest first,
+ * or gives the one under `sessionID` in full, each counted on the other trees' records; with the memory option off, nothing is written or read.
  */
 export declare function recall(ports: MemoryPorts, state: Pick<MemoryState, "tops">, callerID: string, input: RecallInput): Promise<Recall>;

package/dist/memory/recall.js

@@ -1,7 +1,7 @@
 import { addBounded, SEEN_MAX } from "../platform/bounded.js";
 import { finite, millis } from "../platform/json.js";
 import { lineage } from "../tree/index.js";
-import { newestFirst, NOT_STATED, noteRecall } from "./domain.js";
+import { NOT_STATED, noteRead, noteRecall, pinnedFirst } from "./domain.js";
 import { memoryStore } from "./store.js";
 /** The top of the caller's tree: the top of its lineage, or itself. */
 async function topOfCaller(ports, callerID) {
@@ -27,8 +27,20 @@ async function note(ports, top, byTop) {
     });
 }
 /**
- * courier_recall: notes the call on the caller's tree, then lists the project's records newest first, or gives the one
- * under `sessionID` in full. With the memory option off, nothing is written or read.
+ * Counts, on each record of another tree, that this call listed it or gave it in full, best effort: a count lost is
+ * logged, never the call's failure. Gives the reads of the reader's tree on each, in order, or undefined where it failed.
+ */
+function count(ports, top, kind, sessionIDs) {
+    const store = memoryStore(ports.storage);
+    const now = ports.now();
+    return Promise.all(sessionIDs.map((sessionID) => store.noteRead(ports.projectID, sessionID, top, kind, now).catch((error) => {
+        ports.log(`courier memory: could not count the ${kind === "shown" ? "listing" : "read"} of the record under ${sessionID}: ${String(error)}`);
+        return undefined;
+    })));
+}
+/**
+ * courier_recall: notes the call on the caller's tree, then lists the project's records, pinned first and then newest first,
+ * or gives the one under `sessionID` in full, each counted on the other trees' records; with the memory option off, nothing is written or read.
  */
 export async function recall(ports, state, callerID, input) {
     if (!ports.memory)
@@ -42,7 +54,14 @@ export async function recall(ports, state, callerID, input) {
     const wanted = typeof input.sessionID === "string" ? input.sessionID.trim() : "";
     if (wanted) {
         const record = await store.get(projectID, wanted);
-        return record ? { kind: "record", projectID, record: { ...record, projectID, sessionID: wanted } } : { kind: "missing", projectID, sessionID: wanted };
+        if (!record)
+            return { kind: "missing", projectID, sessionID: wanted };
+        // Another tree's record is given with this read added to the reads just read; the caller's own is not counted.
+        const [counted] = wanted === top ? [undefined] : await count(ports, top, "read", [wanted]);
+        const reads = counted ? noteRead(record.reads, "read", counted.at) : record.reads;
+        return { kind: "record", projectID, record: { ...record, ...(reads ? { reads } : {}), projectID, sessionID: wanted } };
     }
-    return { kind: "list", projectID, top, records: newestFirst(await store.ofProject(projectID)) };
+    const records = pinnedFirst(await store.ofProject(projectID));
+    await count(ports, top, "shown", records.flatMap((record) => (record.sessionID === top ? [] : [record.sessionID])));
+    return { kind: "list", projectID, top, records };
 }

package/dist/memory/record.d.ts

@@ -2,6 +2,6 @@ import { type TreeRecord } from "./domain.js";
 import type { MemoryState, RefreshPorts } from "./ports.js";
 /**
  * Writes the record of the tree under `top` as it stands at `at`, after the turn of `ended`; a part the roster has forgotten
- * keeps its last recorded state. Nothing for a top unknown to OpenCode or in a location with memory off; returns the record.
+ * keeps its last recorded state, unless found gone before it settled. Nothing for a top unknown to OpenCode or with memory off.
  */
 export declare function refresh(ports: RefreshPorts, state: Pick<MemoryState, "windows" | "off">, top: string, at: number, ended?: string): Promise<TreeRecord | undefined>;