opencode-courier 0.13.6 → 0.13.8

package/README.md

@@ -23,7 +23,7 @@ A narrated tour of the terminal UI: the tree panel, the asks inbox, failing chil
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.2.4   # OpenCode V2, the version courier is tested on
+npm install -g @opencode/cli@2.2.5   # OpenCode V2, the version courier is tested on
 opencode plugin add opencode-courier
 opencode
 ```
@@ -58,19 +58,21 @@ or stuck, the child calls `courier_send` with a status (`done`, `partial`, `bloc
 The message lands in the parent's inbox and starts a new turn if the parent is idle.
 
 Children started with the same `group` report together, in one message. A child that fails (a
-rate or quota limit with when it lifts), or ends its turn without reporting, is reported to its
-parent. A message that does not wake its session is sent once more, then shown as `stalled`. On
+rate or quota limit with when it lifts) is reported to its parent. One about to end its turn
+without reporting is reminded once, in the same turn, and its parent is told only if it still does
+not report. A message that does not wake its session is sent once more, then shown as `stalled`. On
 OpenCode 2.2.0 a parent's system prompt carries one line per child with its state, kept current,
 so it need not look. Children, held reports and scheduled messages survive a restart. The `courier-orchestrate` skill, listed in every session, tells a model when to
-split a task and how to check and merge the parts. Every detail: [the reference](docs/reference.md).
+split a task and how to check and merge the parts; how to plan and review them is left to
+your own skills. Every detail: [the reference](docs/reference.md).
 
 ## Install
 
 Requires OpenCode V2: the `opencode` command from `@opencode/cli`. Each release is tested against
-one OpenCode version; this one is tested on **OpenCode 2.2.4** (check with `opencode --version`).
+one OpenCode version; this one is tested on **OpenCode 2.2.5** (check with `opencode --version`).
 
 ```bash
-npm install -g @opencode/cli@2.2.4
+npm install -g @opencode/cli@2.2.5
 opencode plugin add opencode-courier
 ```
 
@@ -83,13 +85,13 @@ name, without a version: OpenCode offers updates only for an entry without an ex
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.13.7, 0.13.8 | 2.2.5 |
 | 0.13.6 | 2.2.4 |
 | 0.13.5 | 2.2.3 |
-| 0.13.2, 0.13.3, 0.13.4 | 2.2.2 |
 <!-- compat-table:end -->
 
 Every release: [the full table](docs/reference.md#the-opencode-version). The server part loads on
-any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.2.4 only.
+any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.2.5 only.
 
 ## Options
 

package/dist/index.js

@@ -10,7 +10,7 @@ import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./sche
 import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
 import { addMemoryTools, lessonsOf, memoryEvents, NOTE_TOOL, readMemory, RECALL_TOOL, registerMemoryRpc, sweepRecords } from "./memory/index.js";
 import { addSkill } from "./skill.js";
-import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
+import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, onIdle, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
 /** The spawns under way in the process, outside the hub, so spawns in other locations, copies and hub versions count them. */
 const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() }));
@@ -171,6 +171,11 @@ export const courier = () => Plugin.define({
             log: later.log,
             nudge,
         };
+        // A spawned session about to go idle owing a report is reminded once, in the same execution. The hook is
+        // experimental, and a host before 2.2.4 lacks it: the rest loads all the same, and its parents are told as before.
+        await Promise.resolve()
+            .then(() => ctx.session.hook("experimental.idle", (event) => onIdle(watchPorts, watchState.seen, outside, event).then(() => undefined)))
+            .catch((error) => log(`courier idle: not registered, a child that ends without a report is not reminded: ${String(error)}`));
         // The hub's subscriptions to OpenCode's events, one and a standby, start with this copy's modules.
         watchFromHub(hub, eventModules);
         const member = {

package/dist/skill.d.ts

@@ -2,8 +2,8 @@ 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.
- * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
+ * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
  */
 export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */

package/dist/skill.js

@@ -1,129 +1,116 @@
 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.
+// The courier-orchestrate skill: the text 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, if " +
-    "courier_spawn is among your tools: how to decide whether to split it across OpenCode sessions and state the decision, " +
-    "plan and start the parts, end your turn, verify and integrate the reports, report upward, and handle a part gone wrong.";
+export const SKILL_DESCRIPTION = "How opencode-courier's session tools work. Load before you split a task with courier_spawn: when it has 2 or more " +
+    "independent, substantial parts touching separate files or areas. Starting the parts, waiting without polling, " +
+    "relaying questions and permissions, reading reports, merging and reporting upward.";
 /**
- * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
- * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
+ * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
  */
 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. If " +
-        "courier_spawn is not among your tools, you cannot split: do the task yourself, and report upward as your brief says " +
-        "if a session started you.",
+    "# How opencode-courier's session tools work",
     "",
-    "1. Decide: split or do.",
-    "   - At the root, first call courier_recall once, before you decide and never in a loop: it lists how earlier trees in " +
+    "Your brief, or the opencode-courier role line in your system prompt, names your depth in the session tree and its " +
+        "limits. If courier_spawn is not among your tools, you cannot split: do the task yourself, and report upward as your " +
+        "brief says if a session started you.",
+    "",
+    "This skill says how the tools behave. How to plan the parts, stage a tightly coupled core or review the merged result " +
+        "is a playbook's: if a skill for that is listed to you, load it too.",
+    "",
+    "## 1. Decide: split or do",
+    "",
+    "- 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 " +
+    "- 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. 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: 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 " +
+        "parts: each session runs this skill for its job, so the tree below you repeats its shape once per job.",
+    "- 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). 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, 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), 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 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, 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 " +
-        "notice gives; their answer goes on by itself. When the notice says OpenCode already shows it to the person, call " +
-        "nothing unless they give you their answer. Never answer for them.",
-    "   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. 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 " +
+        "integrates that session's report 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. One session for one stage is a part, not " +
+        "the whole, as your brief says: a core you stage before the rest, when 2 or more parts follow it, or a review of " +
+        "the parts once you have merged them.",
+    `- Say which in one line of your reply, before you start: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
+    "",
+    "## 2. Start the parts",
+    "",
+    "- One courier_spawn per part that runs at once, all with the same group name, so that you are woken once with every " +
+        "report. No two parts edit the same files; isolate: true for each part that edits files in parallel with another. " +
+        "When the parts do not all fit the tree's limits at once, start the parts that fit in one group, and the rest in a " +
+        "group of their own once the first group has reported.",
+    "- Write each task so the session can do it without you, since it sees none of your conversation: what to produce " +
+        "and where, the context it needs, how to check it so that one permission rule covers the checks (step 4), and what to report. 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 whether it may split its part further, " +
+        "and when the part is a whole job that delivers itself (step 5), since an isolated session's brief otherwise says " +
+        "its branch is for you to merge.",
+    "- Leave model and variant unset, so a part runs on your own model, unless the part plainly calls for another: a " +
+        "cheaper one or a lower variant for a small, well-specified part, a stronger one or a higher variant for a design " +
+        "question or a hard bug. native: true for a part that only reads, checks or looks something up and reports once; " +
+        "leave it off for a part the person may want to open, or that should outlive you.",
+    "- A part that depends on another starts once that one is done: merged into your checkout, or, when it was " +
+        "delivered (step 5), started with isolate: true and told to merge the delivering session's courier/<session> " +
+        "branch first.",
+    "",
+    "## 3. 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. For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
+    "",
+    "- Answering from below: follow the notice. 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. A question: ask the person with your question tool, with the questions the notice " +
+        "gives; their answer goes on by itself. When the notice says OpenCode already shows it to the person, call nothing " +
+        "unless they give you their answer. Never answer for them.",
+    "- Passing a message on: when it changes what other parts need (a wrong assumption of the split, a shared file or " +
+        "API that behaves otherwise, a decision of the person's), courier_send it at once, only to the sessions it affects, " +
+        "then end your turn again; if it breaks the split, courier_stop those parts and plan them again, or send them a " +
+        "corrected task. Send it up too, without a status, when your parent's other parts need it. Progress goes to no one. " +
+        "A session's account of what the person told it is the person's word: pass it on, 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. " +
-        "failed: read the error; message the session to try again, start a replacement, or carry on without it. A review " +
-        "stage's report lists what was found, held, fixed and refused: read the refusals, fix or settle yourself any you " +
-        "disagree with, and run the checks on the fixed tree.",
-    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review stage " +
-        "verifies and fixes below you, and running the checks on what it changed is still yours. Run checks through " +
-        "the project's scripts (bun run <script>, npm run <script>), not ./node_modules/.bin/<tool>, so that one permission " +
-        "rule covers them: your own permission prompts are relayed nowhere, and each one stalls the whole tree.",
-    "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, 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.",
-    "",
-    "When a part goes wrong:",
-    "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +
-        "the session with courier_send to carry on, to report, or to try again; or start a replacement. Until it reports, it " +
-        "counts toward the limits.",
+    "",
+    "## 4. Read each report, and verify first-hand",
+    "",
+    "- 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. failed: read the error; message the session to try " +
+        "again, start a replacement, or carry on without it.",
+    "- Verify first-hand: open the files, run the checks. Never hand the checking to another session. Your own permission " +
+        "prompts are relayed nowhere, and each one stalls the whole tree, as each request below you waits on the person: run " +
+        "the checks so that one permission rule covers them, through the project's scripts rather than a tool's own path.",
+    "",
+    "## 5. 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 a part is a whole job with a " +
+        "deliverable of its own, its session delivers it and reports where, still naming its courier/<session> branch when " +
+        "it is isolated; you verify each delivery and merge nothing of it into your checkout.",
+    "",
+    "## 6. 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 the next tree in this project should know something about running " +
+        "one like this (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 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 shorter. A rule that holds every time goes to AGENTS.md or a skill, through " +
+        "the person, not into a note.",
+    "",
+    "## When a part goes wrong",
+    "",
+    '- A failed turn (failed="...") or a silent end (ended="without-report", quoting the session\'s last reply): message ' +
+        "the session with courier_send to carry on, to report, or to try again; or start a replacement. Until it reports, " +
+        "it counts toward the limits.",
     "- A refusal from courier_spawn naming maxDepth, maxChildren or maxTotal: do that part yourself, or end your turn and " +
         "start it once a report has arrived. Do not retry it in a loop.",
     "- Lost track, after a compaction or a restart: one courier_tree shows every session under you with its depth, its " +
         "parent and whether it still owes a report; one look, not a loop.",
-    "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped too, " +
-        "and nothing in it reports back. cleanup: true removes their worktrees.",
+    "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped " +
+        "too, and nothing in it reports back. cleanup: true removes their worktrees.",
 ].join("\n");
 /** A skill's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
 const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;

package/dist/tree/events.js

@@ -3,7 +3,8 @@ import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
 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 { owedUnwaited } from "./nudge.js";
+import { stoppedSincePrompt } from "./report.js";
 import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
@@ -71,6 +72,9 @@ export async function notePrompt(ports, event, inbox) {
     const parentID = await children.indexedParent(sessionID);
     if (parentID === undefined)
         return false;
+    // The reminder to report is not a prompt: it asks for the report the last one owes.
+    if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)
+        return false;
     await children.prompted(sessionID, event.created ?? ports.now());
     await syncStanding(ports, parentID);
     return true;
@@ -122,20 +126,6 @@ export const waitsOn = (...suppliers) => async (ports, sessionID, since) => {
 };
 /** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
 export const together = (...suppliers) => async (ports, sessionID, since) => (await Promise.all(suppliers.map((supplier) => supplier(ports, sessionID, since)))).includes(true);
-/**
- * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
- * its about to be delivered, or what `outside` says it waits on. Cheapest first.
- */
-async function waits(ports, outside, sessionID, prompt) {
-    const children = childStore(ports.storage);
-    const started = await children.children(sessionID);
-    if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
-        return true;
-    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
-    if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
-        return true;
-    return outside(ports, sessionID, prompt);
-}
 /**
  * Tells the parent of a spawned session whose turn ended without reporting to it since its last
  * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
@@ -147,10 +137,8 @@ export async function reportSilent(ports, seen, event, outside) {
     // Claimed after the lookup, so other sessions' turns do not crowd `seen`, and before anything is told.
     if (!entry || !claim(seen, event.id))
         return [];
-    const report = await reportOf(children, sessionID);
-    if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
-        return [];
-    if (await stoppedSincePrompt(children, sessionID).catch(() => false))
+    const report = await owedUnwaited(ports, children, outside, sessionID);
+    if (!report)
         return [];
     // The notice goes out without the reply rather than not at all.
     const lastText = await ports.session.context({ sessionID }).then(lastReply, () => undefined);

package/dist/tree/index.d.ts

@@ -3,6 +3,7 @@ export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
+export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.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";

package/dist/tree/index.js

@@ -5,6 +5,7 @@ export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
+export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS } from "./roster.js";
 export { runs, turnIn, turnOf } from "./running.js";

package/dist/tree/nudge.d.ts

@@ -0,0 +1,28 @@
+import type { ChildStore, Waits, WatchPorts } from "./ports.js";
+/** OpenCode's `experimental.idle` hook event: a session about to go idle, and the background work still running for it or below it. */
+export interface Idle {
+    readonly sessionID: string;
+    readonly background: ReadonlyArray<{
+        readonly sessionID: string;
+    }>;
+}
+/** The ports the reminder is sent through: the watcher's. */
+export type NudgePorts = Pick<WatchPorts, "storage" | "session" | "permissions" | "now" | "log">;
+/**
+ * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
+ * silent-turn notice tells the parent of, and the reminder reminds the session of.
+ */
+export declare function owedUnwaited(ports: NudgePorts, children: ChildStore, outside: Waits, sessionID: string): Promise<{
+    resumesAt?: number | undefined;
+    prompt: number;
+    owes: boolean;
+    progressed: boolean;
+    ended: boolean;
+} | undefined>;
+/**
+ * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
+ * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
+ */
+export declare function nudgeSilent(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;
+/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
+export declare function onIdle(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;

package/dist/tree/nudge.js

@@ -0,0 +1,75 @@
+import { envelope } from "../kernel/protocol.js";
+import { claim } from "../platform/bounded.js";
+import { hasCompleteGroup } from "./group.js";
+import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { childStore, groupStore } from "./store.js";
+import { reportReminder } from "./text.js";
+/**
+ * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
+ * its about to be delivered, or what `outside` says it waits on. Cheapest first.
+ */
+async function waits(ports, outside, sessionID, prompt) {
+    const children = childStore(ports.storage);
+    const started = await children.children(sessionID);
+    if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
+        return true;
+    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
+    if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
+        return true;
+    return outside(ports, sessionID, prompt);
+}
+/**
+ * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
+ * silent-turn notice tells the parent of, and the reminder reminds the session of.
+ */
+export async function owedUnwaited(ports, children, outside, sessionID) {
+    const report = await reportOf(children, sessionID);
+    if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
+        return undefined;
+    if (await stoppedSincePrompt(children, sessionID).catch(() => false))
+        return undefined;
+    return report;
+}
+/**
+ * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
+ * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
+ */
+export async function nudgeSilent(ports, seen, outside, idle) {
+    const { sessionID } = idle;
+    if (idle.background.some((work) => work.sessionID === sessionID))
+        return false;
+    const children = childStore(ports.storage);
+    const parentID = await children.indexedParent(sessionID);
+    if (parentID === undefined)
+        return false;
+    const report = await owedUnwaited(ports, children, outside, sessionID);
+    if (!report)
+        return false;
+    const { at: nudgedAt } = await children.nudgeOf(sessionID);
+    if ((nudgedAt !== undefined && nudgedAt >= report.prompt) || !claim(seen, `nudge/${sessionID}/${report.prompt}`))
+        return false;
+    const at = Math.max(ports.now(), report.prompt);
+    // Noted before it is sent, so a second hook never sends another, and with its id after, before the turn takes it.
+    await children.nudged(sessionID, at);
+    const { id } = await ports.session.synthetic({
+        sessionID,
+        text: envelope("courier", reportReminder(parentID), { reminder: "report" }),
+        description: "Reminded to report",
+        metadata: { source: "courier", reminder: "report", resume: false },
+        delivery: "steer",
+        // The hook's own execution takes it: no wake, and the missed-wake watch leaves it be.
+        resume: false,
+    });
+    await children.nudged(sessionID, at, id);
+    return true;
+}
+/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
+export async function onIdle(ports, seen, outside, idle) {
+    try {
+        return await nudgeSilent(ports, seen, outside, idle);
+    }
+    catch (error) {
+        ports.log(`courier idle: could not remind ${idle.sessionID} to report: ${String(error)}`);
+        return false;
+    }
+}

package/dist/tree/ports.d.ts

@@ -12,7 +12,7 @@ export type RosterStorage = Storage;
 /** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
 export type Settled = "report" | "failed" | "interrupted";
 /** The notes kept of a spawned session's report state; docs/maintainers/architecture.md has each. */
-export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped";
+export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped" | "nudged";
 /** A report note as read: when it was made, and for `settled` how the wait ended, the report's status or a failure's `resumesAt`, as stored. */
 export interface ReportNote {
     readonly at: number | undefined;
@@ -75,6 +75,13 @@ export interface ChildStore {
     untold(sessionID: string, at: number): Promise<void>;
     /** Notes that courier_stop stopped a spawned session at `at`. */
     stopped(sessionID: string, at: number): Promise<void>;
+    /** Notes that a spawned session was reminded at `at` to report, with the reminder's inbox id once it is admitted. */
+    nudged(sessionID: string, at: number, inboxID?: string): Promise<void>;
+    /** When a spawned session was last reminded to report, and the reminder's inbox id. */
+    nudgeOf(sessionID: string): Promise<{
+        readonly at: number | undefined;
+        readonly inboxID?: string;
+    }>;
     /** A `settled` or `progress` note as stored, for `restore` to put back. */
     peek(sessionID: string, field: "settled" | "progress"): Promise<Stored | undefined>;
     /** Puts back a note `peek` read; one that was not there is removed. */

package/dist/tree/store.d.ts

@@ -14,6 +14,7 @@ export declare const settledKey: (sessionID: string) => string;
 export declare const progressKey: (sessionID: string) => string;
 export declare const toldKey: (sessionID: string) => string;
 export declare const stoppedKey: (sessionID: string) => string;
+export declare const nudgedKey: (sessionID: string) => string;
 export declare const memberKey: (parentID: string, group: string, sessionID: string) => string;
 /** The key prefix of a parent's groups, and of one group's members. */
 export declare const groupsPrefix: (parentID: string) => string;

package/dist/tree/store.js

@@ -17,8 +17,8 @@ export function reverseKey(sessionID) {
     return `${BY_CHILD}${sessionID}`;
 }
 /**
- * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled` (with
- * the report's status, or when a failed turn's wait lifts), `progress` (a message to its parent without a status) and `told`; docs/maintainers/architecture.md has each.
+ * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled`, `progress`,
+ * `told`, `stopped` and `nudged` (the reminder to report); docs/maintainers/architecture.md has each.
  */
 const REPORT_PREFIX = "report/";
 export const promptKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/prompt`;
@@ -26,12 +26,14 @@ export const settledKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/settled`;
 export const progressKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/progress`;
 export const toldKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/told`;
 export const stoppedKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/stopped`;
+export const nudgedKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/nudged`;
 const REPORT_KEYS = {
     prompt: promptKey,
     settled: settledKey,
     progress: progressKey,
     told: toldKey,
     stopped: stoppedKey,
+    nudged: nudgedKey,
 };
 /**
  * Join groups: each member of a parent's group under `group/<parentID>/<name>/<sessionID>`, with its
@@ -195,6 +197,14 @@ export function childStore(storage) {
         async stopped(sessionID, at) {
             await storage.set(stoppedKey(sessionID), { at });
         },
+        async nudged(sessionID, at, inboxID) {
+            await storage.set(nudgedKey(sessionID), { at, ...(inboxID === undefined ? {} : { inboxID }) });
+        },
+        async nudgeOf(sessionID) {
+            const value = await storage.get(nudgedKey(sessionID));
+            const inboxID = str(obj(value).inboxID);
+            return { at: timeOf(value), ...(inboxID === undefined ? {} : { inboxID }) };
+        },
         async peek(sessionID, field) {
             const value = await storage.get(REPORT_KEYS[field](sessionID));
             return value;

package/dist/tree/text.d.ts

@@ -108,6 +108,8 @@ export declare function keepReason(state: {
  * retry time (`retryAfterMs`) counts from. Message the child before that and it fails again, so the notice says to wait.
  */
 export declare function failureNotice(title: string, error: ExecutionError, group?: string, at?: number): string;
+/** The one reminder a spawned session gets as it is about to end its turn owing its parent a report; it carries on in the same turn. */
+export declare function reportReminder(parentID: string): string;
 /**
  * What the parent is told when a session it started ends its turn without a report to it;
  * `progressed` when it messaged the parent without a status since its last prompt.

package/dist/tree/text.js

@@ -75,7 +75,7 @@ export function rolePart(depth, limits) {
     const { maxDepth, maxChildren, maxTotal } = limits;
     const budget = `At most ${maxChildren} of the sessions you start run at once, and ${maxTotal} in the whole tree.`;
     if (depth === null)
-        return (`${ROLE_PREFIX} root, no sessions started yet. Before a task that touches several files or areas, load the ` +
+        return (`${ROLE_PREFIX} root, no sessions started yet. Before a task with 2 or more independent, substantial parts touching separate 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; 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 ` +
@@ -364,6 +364,15 @@ export function failureNotice(title, error, group, at) {
             : []),
     ].join("\n");
 }
+/** The one reminder a spawned session gets as it is about to end its turn owing its parent a report; it carries on in the same turn. */
+export function reportReminder(parentID) {
+    return [
+        `You are about to end your turn without reporting to session ${parentID}, which started you.`,
+        `If you are finished, send your report now: call courier_send with sessionID "${parentID}", a short account of what you did and ` +
+            `status ${STATUS_LIST}. If work is left, carry on and report when you finish.`,
+        "This reminder comes once: if you end your turn without a report, the session that started you is told.",
+    ].join("\n");
+}
 /** Longest last reply a notice that a session ended its turn without reporting quotes. */
 const MAX_REPLY = 2000;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.13.6",
+  "version": "0.13.8",
   "description": "Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.",
   "license": "MIT",
   "author": "Ivo Pogace <71701666+ivopogace@users.noreply.github.com>",
@@ -56,12 +56,12 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.2.4",
+    "@opencode/plugin": "2.2.5",
     "effect": "4.0.6"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.2.4",
-    "@opencode/theme": "2.2.4",
+    "@opencode/plugin": "2.2.5",
+    "@opencode/theme": "2.2.5",
     "@opentui/core": "0.8.0",
     "@opentui/solid": "0.8.0",
     "@types/bun": "1.4.2",