opencode-courier 0.8.0 → 0.10.0

package/dist/memory/store.js

@@ -1,12 +1,18 @@
 import { finite, num, obj, str } from "../platform/json.js";
 import { scanEntries } from "../platform/storage.js";
-import { isPartStatus, lessonText, NOT_STATED } from "./domain.js";
-// The memory's storage: the only file that knows its key and layout. A record is read leniently, as one written by
-// hand with `e2e/kv.ts set` is: what is missing takes a default, a part without a session id is left out.
+import { isPartStatus, lessonText, MAX_REVISIONS, NOT_STATED, noteRead, sumReads, } from "./domain.js";
+// The memory's storage: the only file that knows its keys and layout. A record is read leniently, as one written by hand
+// with `e2e/kv.ts set` is; beside it, under its key and each with its own writer, lie the person's pin and each reader tree's reads.
 const PREFIX = "memory/";
 export const recordKey = (projectID, sessionID) => `${PREFIX}${projectID}/${sessionID}`;
 /** The key prefix of a project's records. */
 export const projectPrefix = (projectID) => `${PREFIX}${projectID}/`;
+/** The key prefix of what lies beside a record: its pin and its reads. */
+const besidePrefix = (projectID, sessionID) => `${recordKey(projectID, sessionID)}/`;
+/** The person's pin on a record, `{ at }`; the key's presence pins. */
+export const pinKey = (projectID, sessionID) => `${besidePrefix(projectID, sessionID)}pin`;
+/** The reads of a record by the tree under `by`, `{ shown, read, at }`, written only by that tree's sessions. */
+export const readsKey = (projectID, sessionID, by) => `${besidePrefix(projectID, sessionID)}reads/${by}`;
 function readPart(value) {
     const given = obj(value);
     const sessionID = str(given.sessionID);
@@ -47,7 +53,20 @@ function readLesson(value, movedAt) {
     const depth = num(given.depth);
     return { text, at: num(given.at) ?? movedAt, ...(depth !== undefined && Number.isInteger(depth) && depth > 0 ? { depth } : {}) };
 }
-/** A record as stored, or undefined for a value that is not one. */
+/** The revisions as `{ text, at, parts }`, the newest `MAX_REVISIONS`, leaving out an entry without a text, a time or a count of parts. */
+function readRevisions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const revisions = value.flatMap((entry) => {
+        const given = obj(entry);
+        const text = str(given.text)?.trim();
+        const at = num(given.at);
+        const parts = num(given.parts);
+        return text && at !== undefined && parts !== undefined && parts >= 0 ? [{ text, at, parts }] : [];
+    });
+    return revisions.slice(-MAX_REVISIONS);
+}
+/** A record as stored, or undefined for a value that is not one; its reads and pin lie beside it (`beside`). */
 export function readRecord(value) {
     const given = obj(value);
     if (!Array.isArray(given.parts))
@@ -55,36 +74,101 @@ export function readRecord(value) {
     const recalled = readRecalled(given.recalled);
     const movedAt = num(given.movedAt) ?? num(given.startedAt) ?? 0;
     const lesson = readLesson(given.lesson, movedAt);
+    const revisions = readRevisions(given.revisions);
     return {
         startedAt: num(given.startedAt) ?? 0,
         movedAt,
         title: str(given.title) ?? "",
         split: str(given.split) ?? NOT_STATED,
+        ...(revisions.length ? { revisions } : {}),
         finished: given.finished === true,
         ...(recalled ? { recalled } : {}),
         ...(lesson ? { lesson } : {}),
         parts: given.parts.map(readPart).filter((part) => part !== undefined),
     };
 }
+/** One tree's reads as `{ shown, read, at }`; a count missing is 0, an entry without a time is none. */
+function readReads(value) {
+    const given = obj(value);
+    const at = num(given.at);
+    if (at === undefined)
+        return undefined;
+    const count = (field) => Math.max(0, Math.floor(num(given[field]) ?? 0));
+    return { shown: count("shown"), read: count("read"), at };
+}
+/** The pin as `{ at }`: any value under the key pins, dated 0 when it says no time. */
+const readPinned = (value) => ({ at: num(obj(value).at) ?? 0 });
+/** A record with what lies beside it: its readers' reads as one, and its pin. */
+function beside(record, { pinned, reads }) {
+    const { parts, ...facts } = record;
+    const summed = sumReads(reads);
+    return { ...facts, ...(summed ? { reads: summed } : {}), ...(pinned ? { pinned } : {}), parts };
+}
+/** The key's path under `memory/`, split: `[projectID, sessionID]` a record, then `pin`, or `reads` and the reader. */
+const pathOf = (prefix, key) => `${prefix.slice(PREFIX.length)}${key}`.split("/");
+/** Sorts a scan's entries by record: the record's value, when the scan held it, and what lies beside it. */
+function group(prefix, entries) {
+    const groups = new Map();
+    const of = (projectID, sessionID) => {
+        const id = `${projectID}/${sessionID}`;
+        const found = groups.get(id) ?? { beside: { reads: [] } };
+        groups.set(id, found);
+        return found;
+    };
+    for (const { key, value } of entries) {
+        const [projectID, sessionID, kind, by] = pathOf(prefix, key);
+        if (!projectID || !sessionID)
+            continue;
+        if (kind === undefined)
+            of(projectID, sessionID).record = value;
+        else if (kind === "pin" && by === undefined)
+            of(projectID, sessionID).beside.pinned = readPinned(value);
+        else if (kind === "reads" && by) {
+            const reads = readReads(value);
+            if (reads)
+                of(projectID, sessionID).beside.reads.push(reads);
+        }
+    }
+    return [...groups].map(([id, found]) => {
+        const [projectID, sessionID] = id.split("/");
+        return { projectID, sessionID, ...found };
+    });
+}
 /** The `MemoryStore` over the plugin's storage. */
 export function memoryStore(storage) {
-    const under = async (prefix) => {
-        const entries = await scanEntries(storage, prefix);
-        return entries.flatMap(({ key, value }) => {
-            const parts = `${prefix.slice(PREFIX.length)}${key}`.split("/");
-            const record = parts.length === 2 ? readRecord(value) : undefined;
-            return record ? [{ ...record, projectID: parts[0], sessionID: parts[1] }] : [];
-        });
-    };
+    const scanned = async (prefix) => group(prefix, await scanEntries(storage, prefix));
+    const under = async (prefix) => (await scanned(prefix)).flatMap(({ projectID, sessionID, record: value, beside: others }) => {
+        const record = readRecord(value);
+        return record ? [{ ...beside(record, others), projectID, sessionID }] : [];
+    });
     return {
-        get: async (projectID, sessionID) => readRecord(await storage.get(recordKey(projectID, sessionID))),
-        async put(projectID, sessionID, record) {
+        async get(projectID, sessionID) {
+            const [value, others] = await Promise.all([storage.get(recordKey(projectID, sessionID)), scanned(besidePrefix(projectID, sessionID))]);
+            const record = readRecord(value);
+            return record && beside(record, others[0]?.beside ?? { reads: [] });
+        },
+        // What lies beside the record is never written with it, so no refresh or note can write over a pin or a count.
+        async put(projectID, sessionID, { reads: _reads, pinned: _pinned, ...record }) {
             await storage.set(recordKey(projectID, sessionID), { ...record, parts: record.parts.map((part) => ({ ...part })) });
         },
         async remove(projectID, sessionID) {
-            await storage.remove(recordKey(projectID, sessionID));
+            const others = await scanEntries(storage, besidePrefix(projectID, sessionID));
+            await Promise.all([storage.remove(recordKey(projectID, sessionID)), ...others.map(({ key }) => storage.remove(`${besidePrefix(projectID, sessionID)}${key}`))]);
+        },
+        async noteRead(projectID, sessionID, by, kind, at) {
+            const key = readsKey(projectID, sessionID, by);
+            const reads = noteRead(readReads(await storage.get(key)), kind, at);
+            await storage.set(key, { ...reads });
+            return reads;
+        },
+        async pin(projectID, sessionID, pinned) {
+            if (pinned)
+                await storage.set(pinKey(projectID, sessionID), { ...pinned });
+            else
+                await storage.remove(pinKey(projectID, sessionID));
         },
         ofProject: (projectID) => under(projectPrefix(projectID)),
         all: () => under(PREFIX),
+        strays: async () => (await scanned(PREFIX)).filter(({ record }) => record === undefined).map(({ projectID, sessionID }) => ({ projectID, sessionID })),
     };
 }

package/dist/memory/sweep.d.ts

@@ -1,4 +1,7 @@
 import type { Storage } from "../platform/storage.js";
 import { type StoredRecord } from "./domain.js";
-/** On loading: drops, per project, the records past `MAX_RECORDS` or `RETENTION_MS` at `now`. Returns those dropped. */
+/**
+ * On loading: drops, per project, the records `keep` does not at `now`, the pinned never among them, and the reads or
+ * pin left beside a record removed meanwhile. Returns the records dropped.
+ */
 export declare function sweepRecords(storage: Storage, now: number): Promise<StoredRecord[]>;

package/dist/memory/sweep.js

@@ -1,12 +1,16 @@
 import { keep } from "./domain.js";
 import { memoryStore } from "./store.js";
-/** On loading: drops, per project, the records past `MAX_RECORDS` or `RETENTION_MS` at `now`. Returns those dropped. */
+/**
+ * On loading: drops, per project, the records `keep` does not at `now`, the pinned never among them, and the reads or
+ * pin left beside a record removed meanwhile. Returns the records dropped.
+ */
 export async function sweepRecords(storage, now) {
     const store = memoryStore(storage);
     const byProject = new Map();
     for (const record of await store.all())
         byProject.set(record.projectID, [...(byProject.get(record.projectID) ?? []), record]);
     const dropped = [...byProject.values()].flatMap((records) => keep(records, now).dropped);
-    await Promise.all(dropped.map((record) => store.remove(record.projectID, record.sessionID)));
+    const strays = await store.strays();
+    await Promise.all([...dropped, ...strays].map((record) => store.remove(record.projectID, record.sessionID)));
     return dropped;
 }

package/dist/memory/text.d.ts

@@ -5,14 +5,22 @@ export declare const RECALL_TOOL = "courier_recall";
 export declare const NOTE_TOOL = "courier_note";
 /** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
 export declare function duration(ms: number): string;
+/** How long ago a record last moved: a duration under a day, else whole days, which a record kept for months is read in. */
+export declare function age(ms: number): string;
 /** A lesson as the listing and the note's result show it: dated, and from which depth when a session below the top wrote it. */
 export declare function lessonLine(lesson: Lesson): string;
-/** One record as the listing shows it: its top, when it started, its title, its split line, its parts, how long it ran and what it cost. */
-export declare function recordLine(record: StoredRecord, top: string): string;
+/**
+ * One record as the listing shows it: its top, when it started, its title, its split line and its latest revision as prose,
+ * its parts, how long it ran, how long ago it last moved, what it cost, and whether the person pinned it.
+ */
+export declare function recordLine(record: StoredRecord, top: string, now: number): string;
 /** What courier_recall says when the memory option is off. */
 export declare const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
-/** The listing: every record of the project, newest first, the caller's own tree marked. */
-export declare function recallListText(records: ReadonlyArray<StoredRecord>, top: string): string;
+/**
+ * The listing: every record of the project, the pinned first and then newest first, the caller's own tree marked, each
+ * aged against `now`.
+ */
+export declare function recallListText(records: ReadonlyArray<StoredRecord>, top: string, now: number): string;
 /** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
 export declare function recallRecordText(record: StoredRecord): string;
 export declare const recallMissingText: (sessionID: string) => string;

package/dist/memory/text.js

@@ -1,11 +1,12 @@
 /** The memory's model-facing texts: what courier_recall and courier_note say. */
-import { clipText } from "../kernel/protocol.js";
-import { LESSON_MAX, oneLine, PART_STATUSES } from "./domain.js";
+import { clipText, clipWords } from "../kernel/protocol.js";
+import { LESSON_MAX, oneLine, PART_STATUSES, splitProse } from "./domain.js";
 /** The tool's name, which the skill and the role part name too. */
 export const RECALL_TOOL = "courier_recall";
 /** The lesson tool's name, which the skill's last step names. */
 export const NOTE_TOOL = "courier_note";
 const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+const DAY_MS = 86_400_000;
 /** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
 export function duration(ms) {
     const minutes = Math.round(ms / 60_000);
@@ -15,6 +16,11 @@ export function duration(ms) {
         return `${minutes} min`;
     return `${Math.floor(minutes / 60)} h ${minutes % 60} min`;
 }
+/** How long ago a record last moved: a duration under a day, else whole days, which a record kept for months is read in. */
+export function age(ms) {
+    const days = Math.floor(ms / DAY_MS);
+    return days < 1 ? duration(ms) : count(days, "day");
+}
 /** How a listing counts the parts of a record: by status, in the order of `PART_STATUSES`, plus how many were isolated and how many spawns were refused. */
 function partsLine(parts) {
     if (!parts.length)
@@ -39,32 +45,47 @@ export function lessonLine(lesson) {
     const from = lesson.depth === undefined ? "" : `, from depth ${lesson.depth}`;
     return `lesson (${day(lesson.at)}${from}): "${clipText(oneLine(lesson.text), LESSON_MAX)}"`;
 }
-/** One record as the listing shows it: its top, when it started, its title, its split line, its parts, how long it ran and what it cost. */
-export function recordLine(record, top) {
+/**
+ * One record as the listing shows it: its top, when it started, its title, its split line and its latest revision as prose,
+ * its parts, how long it ran, how long ago it last moved, what it cost, and whether the person pinned it.
+ */
+export function recordLine(record, top, now) {
     const cost = record.parts.reduce((sum, part) => sum + (part.cost ?? 0), 0);
     const costed = record.parts.some((part) => part.cost !== undefined);
+    const revised = record.revisions?.at(-1);
     return [
         `- ${record.sessionID}${record.sessionID === top ? " (this tree)" : ""} ${day(record.startedAt)}: "${clipText(oneLine(record.title), 60)}"`,
-        clipText(oneLine(record.split), 160),
+        clipWords(splitProse(record.split), 160),
+        ...(revised ? [`then, after ${count(revised.parts, "part")}: ${clipWords(splitProse(revised.text), 160)}`] : []),
         partsLine(record.parts),
-        duration(record.movedAt - record.startedAt),
+        `ran ${duration(record.movedAt - record.startedAt)}`,
+        `last moved ${age(now - record.movedAt)} ago`,
         ...(costed ? [`$${cost.toFixed(2)}`] : []),
         record.finished ? "finished" : "not finished",
+        ...(record.pinned ? ["pinned"] : []),
         ...(record.recalled ? [`recalled${record.recalled.at === undefined ? " by a part" : ""}`] : []),
         ...(record.lesson ? [lessonLine(record.lesson)] : []),
     ].join(" · ");
 }
+/** What the listing says of pinned records, when it holds one. */
+const PINNED = "A record marked \"pinned\" is one the person chose to keep and listed first: weigh it before the rest.";
 /** What courier_recall says when the memory option is off. */
 export const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
-/** The listing: every record of the project, newest first, the caller's own tree marked. */
-export function recallListText(records, top) {
+/**
+ * The listing: every record of the project, the pinned first and then newest first, the caller's own tree marked, each
+ * aged against `now`.
+ */
+export function recallListText(records, top, now) {
     const others = records.filter((record) => record.sessionID !== top);
+    const pinned = records.some((record) => record.pinned);
     const intro = others.length
-        ? `${count(others.length, "earlier tree")} recorded in this project, newest first; weigh how they were split and how their parts went before you decide. ` +
-            "A record holds what the plugin saw, not the work, and a lesson what its orchestrator concluded, next to the facts that bear it out: " +
-            "courier_recall with a sessionID gives one in full, with each part's status, duration, cost and context use."
+        ? `${count(others.length, "earlier tree")} recorded in this project, ${pinned ? "pinned first, then newest first" : "newest first"}; weigh how they were split and how their parts went before you decide. ` +
+            "A record holds what the plugin saw, not the work, and a lesson what its orchestrator concluded, next to the facts that bear it out. " +
+            "The facts are as they stood when the tree last moved: \"not finished\" with an old \"last moved\" is a stale record, not a tree running now. " +
+            "courier_recall with a sessionID gives one in full, with each part's status, duration, cost and context use." +
+            (pinned ? ` ${PINNED}` : "")
         : "No earlier tree is recorded in this project: a tree's record is written by a courier_recall call and as each turn in it ends, and kept 90 days. Decide from the task alone.";
-    return [intro, ...records.map((record) => recordLine(record, top))].join("\n");
+    return [intro, ...records.map((record) => recordLine(record, top, now))].join("\n");
 }
 /** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
 export function recallRecordText(record) {

package/dist/memory/tools.js

@@ -21,7 +21,7 @@ export function addMemoryTools(tools, ports) {
         name: RECALL_TOOL,
         options: { codemode: false },
         description: "Look once at what earlier session trees in this project did, before you decide whether and how to split a task: " +
-            "one line per tree, newest first, with how its top split the task, how each part went (its status, how long it ran, " +
+            "one line per tree, those the person pinned first and then newest first, with how its top split the task, how each part went (its status, how long it ran, " +
             "what it cost, how full its context got) and whether a spawn was refused; with sessionID, one tree's record in full. " +
             "Records hold no report bodies or files. Call it once at the start, not in a loop, and not to check on sessions you " +
             "started: their reports wake you.",
@@ -32,7 +32,7 @@ export function addMemoryTools(tools, ports) {
                 case "off":
                     return { content: RECALL_OFF, metadata: { memory: false } };
                 case "list":
-                    return { content: recallListText(result.records, result.top), metadata: { projectID: result.projectID, top: result.top, records: result.records } };
+                    return { content: recallListText(result.records, result.top, ports.memory.now()), metadata: { projectID: result.projectID, top: result.top, records: result.records } };
                 case "record":
                     return { content: recallRecordText(result.record), metadata: { projectID: result.projectID, record: result.record } };
                 case "missing":

package/dist/memory/tui.d.ts

@@ -1,10 +1,10 @@
 import type { Plugin } from "@opencode/plugin/tui";
-import { type Forgotten, type MemoryLesson, type MemoryPart, type MemoryRecord } from "./rpc.js";
+import { type Forgotten, type MemoryLesson, type MemoryPart, type MemoryReads, type MemoryRecord, type Pinned } from "./rpc.js";
 type Context = Plugin.Context;
 /** The command that opens the memory view: `/courier memory`, or the palette. */
 export declare const MEMORY_COMMAND = "courier.memory";
 /** The memory view's line of the `/courier` command's usage. */
-export declare const MEMORY_USAGE = "/courier memory lists this project's tree records, to read or forget";
+export declare const MEMORY_USAGE = "/courier memory lists this project's tree records, to read, pin or forget";
 /** What the view says, in a toast, with the memory option off in the project asked. */
 export declare const MEMORY_OFF = "Memory is off in this project: the plugin's memory option is false, so no record of a session tree is kept or listed here.";
 /** What the view says, in a toast, when the project has no record: when none was written yet, or the last was forgotten. */
@@ -15,6 +15,8 @@ export declare const LESSON_LINE_MAX = 160;
 export declare const ROW_TITLE_MAX = 46;
 /** The group of the records moved on the current local day, over the others' local dates, as the host's Sessions dialog has it. */
 export declare const TODAY = "Today";
+/** The group of the records the person pinned, above the days, shown only while there is one. */
+export declare const PINNED = "Pinned";
 /** The widest a row of the lesson in a record in full is; a longer lesson wraps over rows. */
 export declare const LESSON_ROW = 90;
 /** A record's name, as its rows and confirms show it: its title on one line, else its top session. */
@@ -25,11 +27,16 @@ export declare function partsCounted(parts: ReadonlyArray<MemoryPart>): string;
 export declare function costOf(record: MemoryRecord): number | undefined;
 /** A list row's title: the tree's title, its top session's id without one; the open session's own tree says so. */
 export declare function recordTitle(record: MemoryRecord, open?: string): string;
-/** A list row's group: `Today` for a tree last moved on the local day of `now`, else that local date; the RPC's order, by the last move, keeps the groups newest first. */
+/**
+ * A list row's group: `Pinned` for a pinned record, `Today` for a tree last moved on the local day of `now`, else that
+ * local date; the RPC's order, pinned first and then by the last move, keeps the groups in that order.
+ */
 export declare function recordCategory(record: MemoryRecord, now?: number): string;
+/** How often other trees' courier_recall calls listed the record and opened it in full: "shown 7 times, opened once"; "shown 7 times" alone when none opened it. */
+export declare function readsLine(reads: MemoryReads): string;
 /** A lesson as the view shows it: dated on the local day, from which depth when a session below the top wrote it, and its text. */
 export declare function lessonHeading(lesson: MemoryLesson): string;
-/** A list row's description: its parts by status, how long the tree ran, what its parts cost, and that it is not finished when it is not. */
+/** A list row's description: its parts by status, how long the tree ran, what its parts cost, that it is not finished when it is not, and how often other trees read it. */
 export declare function recordDescription(record: MemoryRecord): string;
 /** The lines under a list row: the lesson, dated and from which depth, clipped; none without a lesson. */
 export declare function recordDetails(record: MemoryRecord): string[];
@@ -63,9 +70,11 @@ export declare function detailOptions(record: MemoryRecord): Array<{
 export declare function forgetMessage(record: MemoryRecord, lesson: boolean): string;
 /** The toast after a forget, as the server reports it. */
 export declare function forgottenLine(record: MemoryRecord, outcome: Forgotten["outcome"]): string;
+/** The toast after a pin, as the server reports it. */
+export declare function pinnedLine(record: MemoryRecord, outcome: Pinned["outcome"]): string;
 /**
  * Adds the memory view: the project's records (the open session's location, else the TUI's, else the server's default) under
- * `Today` and the local days they last moved; `enter` shows one in full, `x` forgets one or its lesson after a confirm, `esc` goes back and closes.
+ * `Pinned`, `Today` and the days they last moved; `enter` shows one in full, `p` pins or unpins one, `x` forgets one or its lesson after a confirm.
  */
 export declare function addMemoryView(ctx: Context): {
     open: () => Promise<void>;

package/dist/rpc.d.ts

@@ -1,3 +1,3 @@
 export { treeRpc, type Row, type Stopped, type Summary, type Tree, type TreeRpc, type Wait } from "./tree/rpc.js";
 export { personRpc, type Answered, type Asks, type PersonRpc } from "./person/rpc.js";
-export { memoryRpc, type Forgotten as MemoryForgotten, type MemoryLesson, type MemoryPart, type MemoryRecord, type MemoryRpc, type Records } from "./memory/rpc.js";
+export { memoryRpc, type Forgotten as MemoryForgotten, type MemoryLesson, type MemoryPart, type MemoryReads, type MemoryRecord, type MemoryRpc, type Pinned as MemoryPinned, type Records } from "./memory/rpc.js";

package/dist/skill.d.ts

@@ -1,7 +1,10 @@
 import type { Plugin } from "@opencode/plugin";
 /** Why a model loads the skill, listed with every session's available skills. */
 export declare const SKILL_DESCRIPTION: string;
-/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+/**
+ * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
+ * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ */
 export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */
 export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];

package/dist/skill.js

@@ -1,34 +1,43 @@
-import { SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
+import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
 // The courier-orchestrate skill: the playbook a session loads with its skill tool.
 /** Why a model loads the skill, listed with every session's available skills. */
 export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, to " +
     "decide whether to split it across OpenCode sessions with courier_spawn and state the decision, and how: plan the " +
     "parts, start them, end your turn, read the reports, verify the work, integrate it and report upward, and what to do " +
     "when a part goes wrong.";
-/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+/**
+ * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
+ * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ */
 export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
         "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
     "",
     "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
         "each part went, so weigh that; one call, before you decide, never in a loop. Split when the task has 2 or more " +
-        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
-        "task: it only adds a hop. What you read and write yourself stays in your context for every later turn, so keep the " +
-        "deciding, checking and integrating, and hand off the long reading and writing. An implementation task with one tightly " +
-        "coupled core usually still has independent parts: finding out what the change needs (a session with isolate: false " +
-        "reads the code, or a library's or a host's source, tries things and reports what it found), its e2e scenario, its " +
-        "documentation, sometimes a second test file, and a review of the core by a session with fresh context, which reads the " +
-        "committed diff against the task and the repository's rules and reports its findings (isolate: false, it edits nothing). " +
-        "Weigh each of them. When the other parts depend on names and texts the core fixes, split in stages: the core first, " +
-        "yourself when it is small or by one session when it is big, merged and committed before the rest start; then, if 2 or " +
-        "more parts remain, one session per remaining part, in one group. A part that is itself big and divisible is split again " +
-        "by the session that gets it; at the deepest level a session does its part itself. " +
-        `Say which in one line of your reply, before you start: ${SPLIT_LINE}, so that a reasoned decision to do it ` +
-        "yourself can be told from one never made.",
+        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or " +
+        "tightly coupled. What you read and write yourself stays in your context for every later turn, so keep the deciding, " +
+        "checking and integrating, and hand off the long reading and writing. Only the root, the session nobody started, may " +
+        "start exactly one session for the whole task, and only when the task is heavy (long reading, many edits, long runs) " +
+        "and its own context is worth keeping: it still verifies and integrates that session's report itself (steps 5 to 7), " +
+        "and does a small task itself. Every other session never starts exactly one session for the whole task: it only adds " +
+        "a hop, and a chain of single hops uses up the tree's depth. A part that is itself big and divisible is split again by " +
+        "the session that gets it; at the deepest level a session does its part itself. " +
+        `Say which in one line of your reply, before you start, so that a reasoned decision to do it yourself can be told ` +
+        `from one never made: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
+    "   When the core is coupled: an implementation task with one tightly coupled core usually still has independent parts: " +
+        "finding out what the change needs (a session with isolate: false reads the code, or a library's or a host's source, " +
+        "tries things and reports what it found), its e2e scenario, its documentation, sometimes a second test file, and a " +
+        "review of the core by a session with fresh context, which reads the committed diff against the task and the " +
+        "repository's rules and reports its findings (isolate: false, it edits nothing). Weigh each of them. When the other " +
+        "parts depend on names and texts the core fixes, split in stages: the core first, yourself when it is small or by one " +
+        "session when it is big, merged and committed before the rest start; then, if 2 or more parts remain, one session per " +
+        "remaining part, in one group. A staged core is one part of the task, not the whole task, so the rule against starting exactly one " +
+        "session for the whole task does not apply to it when 2 or more parts follow it.",
     "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
         "produce and where, how to check it, what to report. Say if it may split its part further, and to run its checks " +
         "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person.",
-    "3. Start them: one courier_spawn per part, all with the same group name, so you are woken once with every report; " +
+    "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so you are woken once with every report; " +
         "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
         "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
     "4. End your turn: reply without calling more tools. Do not poll with courier_status, courier_children, courier_tree or " +

package/dist/tree/mascot.js

@@ -95,7 +95,7 @@ export function digby(rise, { top = 6, eyes = "open", slump = false, shift = 0,
         span(head + 2, 8, "k", (column) => !eyeColumns.includes(column), lean(2));
     span(head + 4, 2, "a", undefined, lean(4));
     span(10, SIZE, ".", (column) => column >= 6 && column <= 9);
-    span(10, top, mound, (column) => column >= 6 && column <= 9, shift);
+    span(10, top, mound, (column) => column + shift >= 6 && column + shift <= 9, shift);
     span(11, 10, mound, undefined, shift);
     span(12, 12, mound, undefined, shift);
     for (const row of [13, 14, 15])

package/dist/tree/rpc-handlers.d.ts

@@ -60,7 +60,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly isolated: boolean;
                     readonly parentID: string;
                     readonly created: number;
-                    readonly state: "stalled" | "running" | "idle" | "gone" | "waiting";
+                    readonly state: "gone" | "stalled" | "running" | "idle" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -102,7 +102,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly isolated: boolean;
                     readonly parentID: string;
                     readonly created: number;
-                    readonly state: "stalled" | "running" | "idle" | "gone" | "waiting";
+                    readonly state: "gone" | "stalled" | "running" | "idle" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -229,12 +229,12 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                 readonly by: import("effect/Schema").String;
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
-                readonly outcome: "removed" | "gone" | "forgotten";
+                readonly outcome: "gone" | "removed" | "forgotten";
             } | {
                 readonly outcome: "kept";
                 readonly reason: string;
             }, {
-                readonly outcome: "removed" | "gone" | "forgotten";
+                readonly outcome: "gone" | "removed" | "forgotten";
             } | {
                 readonly outcome: "kept";
                 readonly reason: string;

package/dist/tree/rpc.d.ts

@@ -227,7 +227,7 @@ export declare const treeRpc: {
                     readonly isolated: boolean;
                     readonly parentID: string;
                     readonly created: number;
-                    readonly state: "stalled" | "running" | "idle" | "gone" | "waiting";
+                    readonly state: "gone" | "stalled" | "running" | "idle" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -269,7 +269,7 @@ export declare const treeRpc: {
                     readonly isolated: boolean;
                     readonly parentID: string;
                     readonly created: number;
-                    readonly state: "stalled" | "running" | "idle" | "gone" | "waiting";
+                    readonly state: "gone" | "stalled" | "running" | "idle" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -415,12 +415,12 @@ export declare const treeRpc: {
                 readonly by: Schema.String;
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
-                readonly outcome: "removed" | "gone" | "forgotten";
+                readonly outcome: "gone" | "removed" | "forgotten";
             } | {
                 readonly outcome: "kept";
                 readonly reason: string;
             }, {
-                readonly outcome: "removed" | "gone" | "forgotten";
+                readonly outcome: "gone" | "removed" | "forgotten";
             } | {
                 readonly outcome: "kept";
                 readonly reason: string;

package/dist/tree/text.js

@@ -1,6 +1,6 @@
 /** The tree's model-facing texts: the child brief, the role part, refusals, reports, notices and tool results. */
 import { obj, str } from "../platform/json.js";
-import { clipText, defuse, END_TURN, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
+import { clipText, defuse, END_TURN, ROOT_SPLIT_LINE, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
 // The envelope and the child brief.
 /** How a text names the statuses a report may carry. */
 const STATUS_LIST = `${STATUSES.slice(0, -1).join(", ")} or ${STATUSES.at(-1)}`;
@@ -47,10 +47,12 @@ function splitRule(parentID, depth, limits) {
         `You are at depth ${depth} of a session tree that goes at most ${limits.maxDepth} deep. Split your task or do it yourself:`,
         "- Split it when it has 2 or more independent parts, each substantial and touching separate files or areas: start one " +
             `session per part with courier_spawn, at most ${limits.maxChildren} of yours running at once and ${limits.maxTotal} in the whole tree.`,
-        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task.",
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task; a core you stage before the rest is one part of it, not the whole, when 2 or more parts follow it.",
         `- Say which in one line of your reply: ${SPLIT_LINE}.`,
-        "- If you split, you orchestrate: end your turn while they work, check and integrate each part yourself when it " +
-            `reports (never hand that checking to another session), then send ${parentID} one combined report.`,
+        "- If you split, you orchestrate: start the parts that run at once in one group, with the same group name for each, " +
+            "then end your turn while they work. Do not poll with courier_status, courier_children, courier_tree or sleep: the group's " +
+            "reports wake you. Check and integrate each part yourself when it reports (never hand that checking to another " +
+            `session), then send ${parentID} one combined report.`,
     ];
 }
 /** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
@@ -65,14 +67,15 @@ export function rolePart(depth, limits) {
     if (depth === null)
         return (`${ROLE_PREFIX} root, no sessions started yet. Before a task that touches several files or areas, load the ` +
             `${SKILL_ID} skill, call courier_recall once for how earlier trees in this project were split and how they went, ` +
-            `and decide whether to split it across sessions (doing it yourself is fine), and say ` +
-            `which in one line of your reply: ${SPLIT_LINE}`);
+            `and decide whether to split it across sessions (doing it yourself is fine; so is handing a heavy task, with long ` +
+            `reading, many edits or long runs, whole to one session to keep your context, but never a small one), and say ` +
+            `which in one line of your reply: ${ROOT_SPLIT_LINE}`);
     if (depth === 0)
         return (`${ROLE_PREFIX} root orchestrator. You started sessions with courier_spawn, and they may start their own, ` +
             `down to ${maxDepth} levels below you. ${budget} Check and integrate what each one reports yourself.`);
     if (depth < maxDepth)
-        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Split your task with courier_spawn or ` +
-            `do it yourself, as your brief says; sessions can be started ${count(maxDepth - depth, "level")} below you. ${budget}`);
+        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you split, load the ${SKILL_ID} ` +
+            `skill. Split your task with courier_spawn or do it yourself, as your brief says; sessions can be started ${count(maxDepth - depth, "level")} below you. ${budget}`);
     return (`${ROLE_PREFIX} leaf, at depth ${depth}, the deepest the session tree goes. You cannot start sessions: do your ` +
         "task yourself and report with courier_send to the session that started you.");
 }