opencode-courier 0.12.0 → 0.13.1

package/dist/skill.js

@@ -15,74 +15,69 @@ export const SKILL_CONTENT = [
         "if a session started you.",
     "",
     "1. Decide: split or do.",
-    "   - At the root, 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. Below the root, read none: the records " +
-        "describe whole trees, and the root weighed them before it split.",
+    "   - At the root, first call courier_recall once, before you decide and never in a loop: it lists how earlier trees in " +
+        "this project were split and how each part went. Below the root, read none: the records describe whole trees, which " +
+        "the root weighed before it split.",
     "   - 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. A part that is itself big and divisible is split again by the " +
-        "session that gets it. Several whole jobs in one prompt, such as 4 tickets, are that many parts: each session runs " +
+        "when it is small, sequential or tightly coupled. Several whole jobs in one prompt, such as 4 tickets, are that many " +
+        "parts: each session runs " +
         "this playbook for its job, stages, review and all, so the tree below you repeats its shape once per job.",
-    "   - What you read and write yourself stays in your context for every later turn, so keep the deciding, checking and " +
+    "   - What you read and write yourself stays in your context for every later turn: 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.",
-    "   - 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}.`,
+        "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). 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.",
+    `   - Say which in one line of your reply, before you start: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
     "   Parts a task can have, besides its edits, each one session where it is worth a context of its own:",
     "   - a scout: a session with isolate: false reads the code, or a library's or a host's source, tries things and " +
         "reports what it found, before you plan;",
     "   - the implementers, isolate: true where two edit at once, each with its checks and what to report;",
     "   - its e2e scenario, its documentation, sometimes a second test file;",
-    "   - a review stage, after the merge, when the changes are done and it is to see the whole: one review session with " +
-        "fresh context, which makes no fixes of its own. Put in its task the diff to read: when you are isolated, your own " +
-        "courier/<session> branch, committed first, against the commit your worktree started from; else your checkout's HEAD, " +
-        "with the merges committed, against the commit you started from, which you note before your first spawn. It may hand the " +
-        "reading to 2 or more reviewers (one group, each reads that diff from one angle and reports its findings), then " +
-        "starts one verifier with their reports: a fresh session that checks each finding against the diff, drops what " +
-        "does not hold, and starts one implementor for what holds, or 2 or more when the fixes are independent, isolate: " +
-        "true each then, merging their branches after (step 7); an implementor fixes what it should and refuses, with the " +
-        "reason, what it should not. Where the code is: when you work in the project's checkout, the review session, the " +
-        "verifier and a lone implementor go without isolate, and it commits in place; when you are isolated, start each of " +
-        "them with isolate: true, so that each worktree starts from the one above, and each merges the branch reported to " +
-        "it before it reports (step 7); reviewers only read and need no worktree. Each reports to the one that started " +
-        "it; the review session reports to " +
-        "you what was found, what held, what was fixed (the commits) and what was refused and why. It does not replace " +
-        "step 6: running the checks on the fixed tree stays yours, and so does settling a refusal you disagree with. Go " +
-        "through steps 3 to 7 once more for the stage, and do its work yourself when the levels below you are too few for " +
-        "it. One session for one stage, after a stage of 2 or more parts or one you did yourself, is a part of the task, " +
-        "like a staged core, not the whole; a reviewer alone with nothing before it is not a stage.",
-    "   When the core is coupled: an implementation task with one tightly coupled core usually still has parts from that " +
-        "list; 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.",
+    "   - a review stage, after the merge, to see the whole: one review session with fresh context, which makes no fixes " +
+        "of its own. Put in its task the diff to read: your checkout's HEAD, with the " +
+        "merges committed, against the commit you started from, which you note before your first spawn; when you are " +
+        "isolated, your own courier/<session> branch, committed first, against the commit your worktree started from. It " +
+        "may hand the reading to 2 or more reviewers (one group, each reads the diff from one angle and reports its " +
+        "findings), then starts one verifier with their reports: a fresh session that checks each finding against the diff, " +
+        "drops what does not hold, and starts one implementor for what holds, or 2 or more with isolate: true when the fixes " +
+        "are independent, merging their branches after (step 7); an implementor fixes what it should and refuses, with the " +
+        "reason, what it should not. In the project's checkout, the review session, the verifier and a lone implementor go " +
+        "without isolate and commit in place; when you are isolated, start each of them with isolate: true, so that each " +
+        "worktree starts from the one above; reviewers only read and need no worktree. The review session reports to you " +
+        "what was found, what held, what was fixed (the commits) and what was refused and why. It does not replace step 6: " +
+        "running the checks on the fixed tree stays yours, and so does settling a refusal you disagree with. Go through " +
+        "steps 3 to 7 once more for the stage, and do its work yourself when the levels below you are too few for it. One " +
+        "session for one stage, after a stage of 2 or more parts or one you did yourself, is a part of the task, not the " +
+        "whole; a reviewer alone with nothing before it is not a stage.",
+    "   When the core is coupled: a task with one tightly coupled core usually still has parts from that list; weigh each. " +
+        "When the rest 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 part, in one group. A staged core is one part of the task, not the whole task, 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. " +
+        "through the project's scripts (step 6), since each permission request below you wakes you and waits on the person. " +
         "Name the skills it should load for its part, from those listed to you: it sees the same list, not your choice; one " +
         "permission rule for skill covers their loads, as one covers the checks. Say in the task when the part is a whole job " +
         "that delivers itself (step 7), since an isolated session's brief otherwise says its branch is for you to merge.",
-    "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). When each part runs a review stage of its own, count 6 live sessions per part against maxTotal (a part, " +
-        "its review session and its reviewers are live together at the peak): start the parts that fit in one group, and the " +
-        "rest in a group of their own once the first group has reported. A job that depends on another starts after that one " +
-        "is done, as a stage: merged into your checkout, or, when it was delivered instead (step 7), started with isolate: " +
-        "true and told the delivering session's courier/<session> branch, from its report, to merge into its worktree first. " +
+    "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so that you are woken once " +
+        "with every report, and isolate: true for each part that edits files in parallel with another. When each part runs " +
+        "a review stage of its own, count 6 live sessions per part against maxTotal (a part, its review session and its " +
+        "reviewers are live together at the peak): start the parts that fit in one group, and the rest in a group of their " +
+        "own once the first group has reported. A job that depends on another starts after that one is done, as a stage: " +
+        "merged into your checkout, or, when it was delivered instead (step 7), started with isolate: true and told the " +
+        "delivering session's courier/<session> branch, from its report, to merge first. " +
         "Leave model and variant unset, so a part runs on your own model, unless the part plainly calls for another: a " +
         "cheaper model or a lower variant for a small, well-specified part (a rename, a lookup), a stronger model or a higher " +
         "variant for a design question or a hard bug. " +
         "native: true for a part nobody needs to open on its own: it reads, checks or looks something up, reports once and is " +
         "done; leave it off for a part the person may want to open, or that should outlive you. " +
         "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 " +
-        "sleep. The group's reports, a blocked report, a question, a permission request, a failed turn or a silent end each start " +
-        "a new turn for you. So does a session's message without a status, and one from the person or from the session that " +
-        "started you.",
+    "4. End your turn: reply without calling more tools, and do not poll with courier_children, courier_tree " +
+        "or sleep. The group's reports, a blocked report, a message without a status, a question, a permission request, a " +
+        "failed turn or a silent end each start a new turn for you; so does a message from the person or from the session " +
+        "that started you.",
     "   Answering from below: follow the notice. For a permission request, propose once with courier_answer, or reject with " +
         "the reason when the person has told you to refuse it or it plainly goes against what they asked; the person decides, " +
         "in OpenCode's prompt in your session. For a question, ask the person with your question tool, with the questions the " +
@@ -91,8 +86,10 @@ export const SKILL_CONTENT = [
     "   Passing a message on: when it changes what other parts need (an assumption of the split that is wrong, a shared file " +
         "or API that behaves otherwise, a decision of the person's), pass it on at once with courier_send, only to the sessions " +
         "it affects, before they go further, then end your turn again; if it breaks the split, courier_stop the parts it breaks " +
-        "and plan them again, or send them a corrected task. If a session started you and its other parts need it too, send it " +
-        "up to that session as well, without a status. Progress that changes nothing for the others goes to no one.",
+        "and plan them again, or send them a corrected task. Send it up too, without a status, when the other parts of the " +
+        "session that started you need it. Progress that changes nothing for the others goes to no one. A session's account " +
+        "of what the person told it is the person's word: pass it on to the parts it affects, do not judge it against the " +
+        "original task, and never tell a session to undo what the person asked.",
     "5. Read each report by its status and its artifacts (branch, commits, files, checks). done: verify it. partial: what is " +
         "left and why; have the session finish it with a courier_send, or do it yourself. blocked: make the decision it asks for " +
         "and send it with courier_send; if only the person can make it, ask them with your question tool and pass the answer on. " +
@@ -106,16 +103,16 @@ export const SKILL_CONTENT = [
     "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
         "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with. When the parts are " +
         "whole jobs with a deliverable each (a ticket with its own branch or pull request), the session delivers it and " +
-        "reports the link in its message, still naming its courier/<session> branch when it is isolated; you verify each " +
-        "delivery and merge nothing of it into your checkout.",
+        "reports the link, still naming its courier/<session> branch when it is isolated; you verify each delivery and merge " +
+        "nothing of it into your checkout.",
     "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
-        "part is verified and integrated, or verified and delivered; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
-        "to the person: if there is something the next tree in this project should know about running a tree like this one (how " +
-        "it was split, what a part got wrong and what caught it, what a brief should have said, what the person decided), one " +
-        "courier_note with that one line; none when there is nothing. Name the job it comes from and the reason, so that a " +
-        "lesson for one kind of job is not taken for every job; the tool refuses a line over its limit rather than clipping " +
-        "it, so write it again shorter. A rule that holds every time goes to AGENTS.md or the skill, through the person, not " +
-        "into a note. Then reply to the person.",
+        "part is verified and integrated, or verified and delivered; partial, blocked or failed otherwise) and the artifacts. " +
+        "At the top, before you reply to the person: if there is something the next tree in this project should know about " +
+        "running a tree like this one (how it was split, what a part got wrong and what caught it, what a brief should have " +
+        "said, what the person decided), one courier_note with that one line; none when there is nothing. Name the job it " +
+        "comes from and the reason, so that a lesson for one kind of job is not taken for every job; the tool refuses a line " +
+        "over its limit rather than clipping it, so write it again shorter. A rule that holds every time goes to AGENTS.md or " +
+        "the skill, through the person, not into a note. Then reply to the person.",
     "",
     "When a part goes wrong:",
     "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +

package/dist/tree/cleanup.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { forgetDropped } from "./forget.js";
+import { syncStanding } from "./standing.js";
 import { childStore } from "./store.js";
 import { keepReason } from "./text.js";
 /** At most this many changes and commits are returned; the reason still counts them all. */
@@ -18,6 +19,7 @@ export async function cleanup(ports, parentID, input) {
     // A member still out is dropped from its group, so the group is released without it; the result names that group.
     const forget = async () => {
         const group = await forgetDropped(ports, entry);
+        await syncStanding(ports, parentID);
         return group ? { group } : {};
     };
     if (!entry.isolated)

package/dist/tree/context.d.ts

@@ -9,7 +9,7 @@ export interface Shaped {
     }>;
 }
 /**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
- * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
+ * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
  */
 export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -1,28 +1,31 @@
 import { setBounded } from "../platform/bounded.js";
 import { childStore } from "./store.js";
-import { ROLE_PREFIX, rolePart } from "./text.js";
-/** How many sessions' depths an instance remembers. */
+import { ROLE_KEY, ROLE_PREFIX, rolePart } from "./text.js";
+/** How many sessions' roles an instance remembers. */
 const ROLES_MAX = 1000;
+/** A role part, or the role entry's block, already in the system prompt, wherever its part begins. */
+const ROLE_LINE = new RegExp(`^${ROLE_PREFIX}`, "m");
 /**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
- * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
+ * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
  */
 export async function shapeContext(ports, event) {
     try {
-        const depth = await depthOf(ports, event.sessionID);
+        const { depth, entry } = await roleOf(ports, event.sessionID);
         if (depth === null && !event.tools.courier_spawn)
             return;
         if (depth !== null && depth >= ports.limits.maxDepth)
             for (const tool of ["courier_spawn", ...(ports.hiddenFromLeaf ?? [])])
                 delete event.tools[tool];
-        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
-            event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
+        if (entry || event.system.some((part) => ROLE_LINE.test(part.text)))
+            return;
+        event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
     }
     catch (error) {
         ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
     }
 }
-async function depthOf(ports, sessionID) {
+async function roleOf(ports, sessionID) {
     const known = ports.roles.get(sessionID);
     if (known !== undefined)
         return known;
@@ -30,6 +33,19 @@ async function depthOf(ports, sessionID) {
     const children = childStore(ports.storage);
     const chain = await children.indexedLineage(sessionID);
     const depth = chain.length || ((await children.children(sessionID)).length ? 0 : null);
-    setBounded(ports.roles, sessionID, depth, ROLES_MAX);
-    return depth;
+    const role = { depth, entry: depth !== null && (await hasEntry(ports, sessionID)) };
+    setBounded(ports.roles, sessionID, role, ROLES_MAX);
+    return role;
+}
+/** Whether the session carries the role entry, listed when its role is looked up; one that cannot be read gets the part. */
+async function hasEntry(ports, sessionID) {
+    if (!ports.instructions)
+        return false;
+    try {
+        return (await ports.instructions.entry.list({ sessionID })).some((entry) => entry.key === ROLE_KEY);
+    }
+    catch (error) {
+        ports.log(`courier: cannot read the instruction entries of session ${sessionID}, so its role goes in a system part: ${String(error)}`);
+        return false;
+    }
 }

package/dist/tree/domain.d.ts

@@ -73,6 +73,18 @@ export declare function cut<T extends Cuttable>(nodes: ReadonlyArray<T>, max: nu
     kept: T[];
     leftOut: number;
 };
+/**
+ * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
+ * except isolated children whose worktree is still there: those stay until courier_cleanup.
+ */
+export declare const RETENTION_MS: number;
+/** Whether a directory still exists; tests pass a fake. */
+export type Exists = (directory: string) => boolean;
+/**
+ * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
+ * child whose worktree exists, which is kept so it can still be cleaned up.
+ */
+export declare const isExpired: (entry: RosterEntry, now: number, exists: Exists) => boolean;
 /** A session started with courier_spawn, recorded under the session that started it. */
 export interface RosterEntry {
     readonly sessionID: string;

package/dist/tree/domain.js

@@ -70,6 +70,16 @@ export function cut(nodes, max) {
     }
     return { kept: nodes.filter((node) => kept.has(node.sessionID)), leftOut: nodes.length - kept.size };
 }
+/**
+ * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
+ * except isolated children whose worktree is still there: those stay until courier_cleanup.
+ */
+export const RETENTION_MS = 14 * 24 * 60 * 60_000;
+/**
+ * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
+ * child whose worktree exists, which is kept so it can still be cleaned up.
+ */
+export const isExpired = (entry, now, exists) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory));
 /** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
 export function startedAs(entry) {
     return { isolated: entry.isolated, ...(entry.native ? { native: true } : {}), ...(entry.model ? { model: entry.model } : {}) };

package/dist/tree/events.js

@@ -4,6 +4,7 @@ import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
 import { failureNotice, silentNotice } from "./text.js";
@@ -43,6 +44,7 @@ export async function reportFailure(ports, seen, event) {
     finally {
         if (completed.includes(true))
             ports.nudge();
+        await Promise.all(entries.map((entry) => syncStanding(ports, entry.parentID)));
     }
     return entries.map((entry) => entry.parentID);
 }
@@ -66,9 +68,11 @@ export async function notePrompt(ports, event, inbox) {
     if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
         return false;
     const children = childStore(ports.storage);
-    if ((await children.indexedParent(sessionID)) === undefined)
+    const parentID = await children.indexedParent(sessionID);
+    if (parentID === undefined)
         return false;
     await children.prompted(sessionID, event.created ?? ports.now());
+    await syncStanding(ports, parentID);
     return true;
 }
 /**
@@ -88,6 +92,7 @@ export async function noteInterrupted(ports, event) {
     const member = await outIn(ports, entry);
     if (member && (await leave(ports, member, "interrupted", at)))
         ports.nudge();
+    await syncStanding(ports, entry.parentID);
     return true;
 }
 /**
@@ -104,6 +109,8 @@ export async function noteDeleted(ports, event) {
     await forgetDeleted(ports, sessionID, forgotten, member, event.created);
     if (parentID !== undefined && entry && !entry.isolated && started.length === 0)
         await forgetChild(ports.storage, parentID, sessionID);
+    if (parentID !== undefined)
+        await syncStanding(ports, parentID);
     return forgotten;
 }
 /** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
@@ -165,6 +172,7 @@ export async function reportSilent(ports, seen, event, outside) {
         await children.untold(sessionID, toldAt).catch(() => undefined);
         throw error;
     }
+    await syncStanding(ports, entry.parentID);
     return [entry.parentID];
 }
 /**
@@ -179,6 +187,17 @@ export async function reportDeclined(ports, seen, event, outside) {
     return reportSilent(ports, seen, event, outside);
 }
 const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+/** What `route` and `after` dispatch on; the wake watch needs `inbox.enqueued` and `execution.started` both. */
+const TREE_TYPES = [
+    "session.execution.started",
+    "session.execution.succeeded",
+    "session.execution.failed",
+    "session.execution.interrupted",
+    "session.inbox.enqueued",
+    "session.inbox.delivered",
+    "session.inbox.cancelled",
+    "session.deleted",
+];
 /** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now; not a shutdown's, which stamps no idle time. */
 async function sealGroups(ports, event) {
     if (event.data.reason === "shutdown")
@@ -239,6 +258,7 @@ async function route(ports, state, outside, event) {
  */
 export function treeEvents(state, outside) {
     return {
+        types: TREE_TYPES,
         handle: (ports, event) => route(ports, state, outside, event),
         // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
         after: (ports, event) => (TURN_ENDS.has(event.type) ? sealGroups(ports, event) : undefined),

package/dist/tree/group.js

@@ -1,6 +1,7 @@
 import { isNotFound, millis } from "../platform/json.js";
 import { envelope } from "../kernel/protocol.js";
 import { complete, standingOf } from "./domain.js";
+import { syncStanding } from "./standing.js";
 import { groupStore } from "./store.js";
 import { groupNotice } from "./text.js";
 /** Makes a spawned session a member of its parent's group, opening the group if it was not. */
@@ -182,6 +183,8 @@ async function release(ports, parentID, group) {
         }
     }
     await drop(ports, parentID, group, members);
+    // Delivered: the members read as released in the parent's standing, which its next step shows.
+    await syncStanding(ports, parentID);
 }
 /** Drops a group's members once delivered, or unsent, saying why. */
 async function drop(ports, parentID, group, members, unsent) {

package/dist/tree/index.d.ts

@@ -4,7 +4,7 @@ export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } fro
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { contextOf } from "./panel.js";
-export type { CleanupPorts, CourierPorts, ModelWindow, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export type { CleanupPorts, CourierPorts, Entries, Entry, Instructions, ModelWindow, Pending, PendingPrompt, Role, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
 export { runs, turnIn, turnOf, type Turn } from "./running.js";
 export { subtree, type Below } from "./subtree.js";

package/dist/tree/ports.d.ts

@@ -43,6 +43,8 @@ export interface ChildStore {
     entriesOf(sessionID: string): Promise<RosterEntry[]>;
     /** The session that started a session, by the reverse index alone, without scanning the roster. */
     indexedParent(sessionID: string): Promise<string | undefined>;
+    /** The sessions above a session, its parent first, by the reverse index alone: empty when it does not name the session. */
+    indexedAncestors(sessionID: string): Promise<ReadonlyArray<string>>;
     /** A session's roster entry, by the reverse index alone, without scanning the roster. */
     indexedEntry(sessionID: string): Promise<RosterEntry | undefined>;
     /**
@@ -149,10 +151,42 @@ export interface Sent {
     readonly status?: Status;
     readonly report?: boolean;
     readonly held?: Held;
+    /** The status it was sent with to a session below the sender, where a status means nothing. */
+    readonly dropped?: Status;
+}
+/**
+ * What the `context` hook remembers of a session: its depth, null for one nobody spawned that has started none, and
+ * whether it carries the role entry (`ROLE_KEY`), which then names its role in place of the hook's system part.
+ */
+export interface Role {
+    readonly depth: number | null;
+    readonly entry: boolean;
+}
+/** The keyed session entries, missing on a host before 2.2.0 (every copy's ports carry the host's `session`): an entry is then skipped. */
+export type Instructions = Partial<Pick<Context["session"], "instructions">>;
+/** A keyed session instruction entry: its key, `^[a-z0-9][a-z0-9._-]*$`, and its text. */
+export interface Entry {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Supplies the entries other modules write to a spawned session below `maxDepth` before its prompt, and to a root at its
+ * first spawn beside its role; `src/index.ts` composes it from the modules' suppliers, as it does the `Waits` port.
+ */
+export type Entries = () => Promise<ReadonlyArray<Entry>>;
+/** What writing a parent's `standing` entry needs: the tools', the watcher's and the scheduler's ports all have these. */
+export interface StandingPorts {
+    readonly storage: RosterStorage;
+    readonly now: () => number;
+    readonly session?: Instructions;
+    readonly log?: (message: string) => void;
 }
 /** The slice of the plugin context the courier tools use; tests pass a fake. */
 export interface CourierPorts {
-    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt">;
+    /** `instructions`, the keyed session entries, is missing on a host before 2.2.0: the role then goes in a system part. */
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt"> & Instructions;
+    /** The entries of other modules a spawned session gets before its prompt, the memory's lessons; none when not given. */
+    readonly entries?: Entries;
     readonly agent: Pick<Context["agent"], "get">;
     readonly worktree: Pick<Context["worktree"], "create" | "remove">;
     /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
@@ -176,8 +210,8 @@ export interface CourierPorts {
     /** The `nativeChildren` option: a child started without isolate and without `native` is created with OpenCode's own `parentID`. */
     readonly nativeChildren?: boolean;
     readonly gate: SpawnGate;
-    /** The depths the `context` hook remembers; a parent's is dropped when it starts a child. */
-    readonly roles: Map<string, number | null>;
+    /** The roles the `context` hook remembers; a parent's is dropped when it starts a child, a root's kept once its entry is written. */
+    readonly roles: Map<string, Role>;
     /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
     readonly nudge: () => void;
     readonly log: (message: string) => void;
@@ -276,6 +310,9 @@ export interface CleanupPorts {
     readonly now: () => number;
     /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
     readonly nudge: () => void;
+    /** For the parent's `standing` entry once the child is forgotten; without them it is left as it was. */
+    readonly session?: Instructions;
+    readonly log?: (message: string) => void;
 }
 export interface StopPorts {
     readonly courier: CourierPorts;
@@ -285,7 +322,8 @@ export interface StopPorts {
 }
 export interface GroupPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic" | "get">;
+    readonly session: Pick<Context["session"], "synthetic" | "get"> & Instructions;
+    readonly now: () => number;
     readonly log: (message: string) => void;
 }
 /** The error of OpenCode's `session.execution.failed` event. */
@@ -299,7 +337,7 @@ export interface ExecutionError {
 export interface WatchPorts {
     readonly storage: RosterStorage;
     /** `context` reads the last reply of a session that ended its turn without reporting; `get` is what every member joins with too. */
-    readonly session: Pick<Context["session"], "synthetic" | "context" | "get">;
+    readonly session: Pick<Context["session"], "synthetic" | "context" | "get"> & Instructions;
     readonly event: Pick<Context["event"], "subscribe">;
     /** The permission domains of every loaded location, which the `Waits` suppliers ask; an isolated child's are in its worktree's. */
     readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
@@ -326,8 +364,10 @@ export type Waits = (ports: Pick<WatchPorts, "storage" | "permissions">, session
 export interface ContextPorts {
     readonly storage: RosterStorage;
     readonly limits: Limits;
-    /** Each session's depth once looked up: null for one nobody spawned that has started none, until it starts one. */
-    readonly roles: Map<string, number | null>;
+    /** Each session's role once looked up; a session nobody spawned reads as depth null until it starts one. */
+    readonly roles: Map<string, Role>;
+    /** The keyed session entries, listed when a session's role is looked up; missing on a host before 2.2.0, which gets the system part. */
+    readonly instructions?: Context["session"]["instructions"];
     /** Tools of other modules hidden from a leaf alongside courier_spawn; `src/index.ts` names courier_recall and courier_note. */
     readonly hiddenFromLeaf?: ReadonlyArray<string>;
     readonly log: (message: string) => void;

package/dist/tree/roster.d.ts

@@ -1,10 +1,7 @@
 import { type Status } from "../kernel/protocol.js";
+import { type Exists } from "./domain.js";
 import type { RosterEntry, RosterStorage } from "./ports.js";
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
-export declare const RETENTION_MS: number;
+export { RETENTION_MS, type Exists } from "./domain.js";
 /** Every parent's children. */
 export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
 /**
@@ -33,12 +30,7 @@ export declare function reportState(storage: RosterStorage, sessionID: string):
  * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
  */
 export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
-/** Whether a directory still exists; tests pass a fake. */
-export type Exists = (directory: string) => boolean;
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
+/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
 export declare const isExpired: (entry: RosterEntry, now: number, exists?: Exists) => boolean;
 /** A parent's children, oldest first, after dropping the expired ones. */
 export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;

package/dist/tree/roster.js

@@ -1,13 +1,10 @@
 import { existsSync } from "node:fs";
 import { isStatus } from "../kernel/protocol.js";
+import { isExpired as expiredBy } from "./domain.js";
 import { forgetChild, forgetReports } from "./forget.js";
 import { stoppedSincePrompt } from "./report.js";
 import { childStore } from "./store.js";
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
-export const RETENTION_MS = 14 * 24 * 60 * 60_000;
+export { RETENTION_MS } from "./domain.js";
 /** Every parent's children. */
 export async function allEntries(storage) {
     return childStore(storage).all();
@@ -54,11 +51,8 @@ export async function answeringTop(storage, sessionID, callerID, what) {
         throw new Error(`${sessionID}'s ${what} go to ${top}, the session at the top of the sessions started from it with courier_spawn; ${callerID} cannot answer them.`);
     return top;
 }
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
-export const isExpired = (entry, now, exists = existsSync) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory));
+/** `domain.ts`'s `isExpired`, asking the file system whether an isolated child's worktree is still there unless a test passes a fake. */
+export const isExpired = (entry, now, exists = existsSync) => expiredBy(entry, now, exists);
 /** Forgets the given entries that are expired at `now`, and returns the rest. */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => isExpired(entry, now, exists)));