opencode-courier 0.2.3 → 0.4.0

package/dist/platform/json.d.ts

@@ -0,0 +1,8 @@
+/** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
+export declare const str: (value: unknown) => string | undefined;
+export declare const num: (value: unknown) => number | undefined;
+export declare const obj: (value: unknown) => Record<string, any>;
+/** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
+export declare function millis(value: unknown): number;
+/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
+export declare const isNotFound: (error: unknown) => boolean;

package/dist/platform/json.js

@@ -0,0 +1,15 @@
+/** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
+export const str = (value) => (typeof value === "string" ? value : undefined);
+export const num = (value) => (typeof value === "number" && Number.isInteger(value) ? value : undefined);
+export const obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+/** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
+export function millis(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return Date.parse(value);
+    const epoch = obj(value).epochMilliseconds;
+    return typeof epoch === "number" ? epoch : Number.NaN;
+}
+/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
+export const isNotFound = (error) => str(obj(error)._tag)?.includes("NotFound") ?? false;

package/dist/platform/version.d.ts

@@ -0,0 +1,16 @@
+import type { App } from "@opencode/plugin/app";
+/** The versions a build of the plugin carries: its own, and the OpenCode it was built and tested against. */
+export interface BuiltVersions {
+    readonly plugin: string;
+    readonly opencode: string;
+}
+/**
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
+ */
+export declare function builtVersions(): BuiltVersions;
+/**
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
+ */
+export declare function versionNotice(built: BuiltVersions, app: Partial<Pick<App, "version" | "channel">> | undefined): string | undefined;

package/dist/{version.js → platform/version.js}

@@ -1,15 +1,11 @@
 import { readFileSync } from "node:fs";
 const README_TABLE = "https://github.com/ivopogace/opencode-courier#supported-opencode-version";
 /**
- * Reads the versions from the package's own package.json, which sits next to `dist/` in the
- * published package as it does next to `src/` in the repository: `version`, and the exact
- * `@opencode/plugin` version under devDependencies, the one installed for the build and both test
- * suites; the peer dependency names the same exact version, as the copy of the plugin API that
- * `opencode plugin add` installs next to the plugin. Throws when the file cannot be read or does
- * not hold both.
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export function builtVersions() {
-    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     const plugin = pkg.version;
     const opencode = pkg.devDependencies?.["@opencode/plugin"];
     if (typeof plugin !== "string")
@@ -19,10 +15,8 @@ export function builtVersions() {
     return { plugin, opencode };
 }
 /**
- * The line for the server log when the running OpenCode is not the one the plugin was built
- * against; undefined when it is. Logged once per plugin load, never in a tool result. An OpenCode
- * whose plugin context does not report a version, as one from before the pinned API or after a
- * change to it may not, is the case the line is for, so it still names the pin then.
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
  */
 export function versionNotice(built, app) {
     const version = typeof app?.version === "string" ? app.version : undefined;

package/dist/rpc.d.ts

@@ -0,0 +1,2 @@
+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";

package/dist/rpc.js

@@ -0,0 +1,3 @@
+// The package's `rpc` entrypoint: the courier's RPC contracts, for a client that calls them.
+export { treeRpc } from "./tree/rpc.js";
+export { personRpc } from "./person/rpc.js";

package/dist/scheduling/index.d.ts

@@ -0,0 +1,6 @@
+import type { TickJob } from "../platform/hub.js";
+export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
+export type { LaterEntry, LaterInput, LaterPorts } from "./later.js";
+export { addSchedulingTools } from "./tools.js";
+/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
+export declare const dueJob: TickJob;

package/dist/scheduling/index.js

@@ -0,0 +1,5 @@
+import { deliverDue } from "./later.js";
+export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
+export { addSchedulingTools } from "./tools.js";
+/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
+export const dueJob = (owner, claimed) => deliverDue(owner.later, claimed);

package/dist/{later.d.ts → scheduling/later.d.ts}

@@ -1,8 +1,6 @@
 import type { Plugin } from "@opencode/plugin";
-import { type Storage } from "./storage.js";
+import { type Storage } from "../platform/storage.js";
 type Context = Plugin.Context;
-/** How often the hub's scheduler looks for due messages; a delivery can be this late. */
-export declare const TICK_MS = 15000;
 export interface LaterEntry {
     readonly id: string;
     readonly sessionID: string;
@@ -13,7 +11,8 @@ export interface LaterEntry {
 }
 export interface LaterPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic">;
+    /** `get` for the release of a join group, which waits for its parent's turn to end. */
+    readonly session: Pick<Context["session"], "synthetic" | "get">;
     readonly now: () => number;
     readonly newID: () => string;
     readonly log: (message: string) => void;
@@ -29,12 +28,17 @@ export interface LaterInput {
 export declare function schedule(ports: LaterPorts, from: string, input: LaterInput): Promise<LaterEntry>;
 /** Drops a pending message; false when there was none, e.g. it was already delivered. */
 export declare function cancel(ports: LaterPorts, id: string): Promise<boolean>;
+/** The messages scheduled for a session that have not been delivered yet. */
+export declare function scheduledFor(storage: Pick<Storage, "scan">, sessionID: string): Promise<LaterEntry[]>;
+/** Cancels every message scheduled for a session; the ids of those cancelled. */
+export declare function cancelScheduled(ports: LaterPorts, sessionID: string): Promise<string[]>;
+/** Whether a session waits on a scheduled message of its own. */
+export declare function isScheduled(ports: {
+    readonly storage: Pick<Storage, "scan">;
+}, sessionID: string): Promise<boolean>;
 /**
- * Delivers every due message once. OpenCode sets the plugin up once per project location, all in
- * one process and over one storage, so the instances share `claimed`: an id is claimed
- * synchronously, re-read after the claim (another instance may have just delivered it), delivered,
- * and only then removed. A crash between delivery and removal delivers it again after a restart,
- * which a check-in survives better than being lost.
+ * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
+ * delivered and only then removed; a crash in between delivers it again after a restart, not never.
  */
 export declare function deliverDue(ports: LaterPorts, claimed: Set<string>): Promise<void>;
 export {};

package/dist/{later.js → scheduling/later.js}

@@ -1,7 +1,5 @@
-import { envelope } from "./notices.js";
-import { scanAll } from "./storage.js";
-/** How often the hub's scheduler looks for due messages; a delivery can be this late. */
-export const TICK_MS = 15_000;
+import { envelope } from "../kernel/protocol.js";
+import { scanAll } from "../platform/storage.js";
 const PREFIX = "later/";
 /** The latest time a Date can hold; a message due after it could never be shown or delivered. */
 const LATEST = 8.64e15;
@@ -60,12 +58,23 @@ export async function cancel(ports, id) {
 function pending(ports) {
     return scanAll(ports.storage, PREFIX);
 }
+/** The messages scheduled for a session that have not been delivered yet. */
+export async function scheduledFor(storage, sessionID) {
+    return (await pending({ storage: storage })).filter((entry) => entry.sessionID === sessionID);
+}
+/** Cancels every message scheduled for a session; the ids of those cancelled. */
+export async function cancelScheduled(ports, sessionID) {
+    const scheduled = await scheduledFor(ports.storage, sessionID);
+    const dropped = await Promise.all(scheduled.map(async (later) => ((await cancel(ports, later.id)) ? later.id : undefined)));
+    return dropped.filter((id) => id !== undefined);
+}
+/** Whether a session waits on a scheduled message of its own. */
+export async function isScheduled(ports, sessionID) {
+    return (await scheduledFor(ports.storage, sessionID)).length > 0;
+}
 /**
- * Delivers every due message once. OpenCode sets the plugin up once per project location, all in
- * one process and over one storage, so the instances share `claimed`: an id is claimed
- * synchronously, re-read after the claim (another instance may have just delivered it), delivered,
- * and only then removed. A crash between delivery and removal delivers it again after a restart,
- * which a check-in survives better than being lost.
+ * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
+ * delivered and only then removed; a crash in between delivers it again after a restart, not never.
  */
 export async function deliverDue(ports, claimed) {
     const now = ports.now();

package/dist/scheduling/text.d.ts

@@ -0,0 +1,6 @@
+/** `own` when the message goes to the session that scheduled it. */
+export declare function laterText(entry: {
+    readonly id: string;
+    readonly sessionID: string;
+}, fireAt: string, own: boolean): string;
+export declare const cancelText: (id: string, cancelled: boolean) => string;

package/dist/scheduling/text.js

@@ -0,0 +1,10 @@
+/** `own` when the message goes to the session that scheduled it. */
+export function laterText(entry, fireAt, own) {
+    const next = own
+        ? "It arrives when due, after your current turn if one is running, so do not wait for it: once nothing " +
+            "else is left to do now, end your turn by replying without calling more tools. If what it checks on " +
+            "reports first, cancel it then with courier_cancel."
+        : "Cancel it with courier_cancel if it is no longer needed.";
+    return `Scheduled ${entry.id} for ${fireAt}, to ${entry.sessionID}. ${next}`;
+}
+export const cancelText = (id, cancelled) => cancelled ? `Cancelled ${id}.` : `Nothing pending under ${id}; it may have been delivered.`;

package/dist/scheduling/tools.d.ts

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+import { type ToolEditor } from "../kernel/tool.js";
+import { type LaterPorts } from "./later.js";
+export declare const LaterInput: Schema.Struct<{
+    readonly message: Schema.String;
+    readonly delayMinutes: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String]>>;
+    readonly at: Schema.optional<Schema.String>;
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const CancelInput: Schema.Struct<{
+    readonly id: Schema.String;
+}>;
+/** Adds `courier_later` and `courier_cancel`. */
+export declare function addSchedulingTools(tools: ToolEditor, later: LaterPorts): void;

package/dist/scheduling/tools.js

@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import { rethrow } from "../kernel/tool.js";
+import { cancel, schedule } from "./later.js";
+import { cancelText, laterText } from "./text.js";
+export const LaterInput = Schema.Struct({
+    message: Schema.String.annotate({ description: "The message to deliver." }),
+    delayMinutes: Schema.optional(
+    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
+    // unchanged after the error, so a string is accepted and schedule reads it as a number.
+    Schema.Union([Schema.Number, Schema.String]).annotate({
+        description: "Deliver this many minutes from now. Give this or at.",
+    })),
+    at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to deliver to; defaults to this one." })),
+});
+export const CancelInput = Schema.Struct({
+    id: Schema.String.annotate({ description: "The id courier_later returned." }),
+});
+/** Adds `courier_later` and `courier_cancel`. */
+export function addSchedulingTools(tools, later) {
+    tools.add({
+        name: "courier_later",
+        options: { codemode: false },
+        description: "Schedule a message for a session (this one by default), delivered when due and waking it if idle. " +
+            "Use it as a safety net when you start sessions: schedule one check-in, end your turn by replying without " +
+            "calling more tools, and cancel it with courier_cancel if the child reports first. Survives server restarts; " +
+            "may arrive up to ~15 seconds late.",
+        input: LaterInput,
+        execute: async (input, context) => {
+            const entry = await schedule(later, context.sessionID, input).catch(rethrow("courier_later"));
+            const fireAt = new Date(entry.fireAt).toISOString();
+            return {
+                content: laterText(entry, fireAt, entry.sessionID === context.sessionID),
+                metadata: { id: entry.id, fireAt, sessionID: entry.sessionID },
+            };
+        },
+    });
+    tools.add({
+        name: "courier_cancel",
+        options: { codemode: false },
+        description: "Cancel a message scheduled with courier_later, e.g. because the child it was waiting for reported.",
+        input: CancelInput,
+        execute: async (input) => {
+            const cancelled = await cancel(later, input.id).catch(rethrow("courier_cancel"));
+            return { content: cancelText(input.id, cancelled), metadata: { id: input.id, cancelled } };
+        },
+    });
+}

package/dist/skill.d.ts

@@ -0,0 +1,17 @@
+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. */
+export declare const SKILL_CONTENT: string;
+/** The editor OpenCode hands a skill transform. */
+export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export declare const orchestrateSkill: () => {
+    readonly id: "courier-orchestrate";
+    readonly name: "courier-orchestrate";
+    readonly description: string;
+    readonly path: "/opencode-courier/courier-orchestrate.md";
+    readonly content: string;
+};
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export declare function addSkill(skills: SkillEditor): void;

package/dist/skill.js

@@ -0,0 +1,62 @@
+import { 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. */
+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. 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. " +
+        "An implementation task with one tightly coupled core usually still has independent parts: 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: do the core yourself first and commit it, so that the names and texts the other parts depend on are " +
+        "fixed, then, if 2 or more remain, start 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.",
+    "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.",
+    "3. Start them: one courier_spawn per part, 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 " +
+        "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.",
+    "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.",
+    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review session's " +
+        "findings are a report to act on, and running the checks 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.",
+    "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; partial, blocked or failed otherwise) and the artifacts. At the top, 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.",
+    "- 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.",
+].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`;
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export const orchestrateSkill = () => ({ id: SKILL_ID, name: SKILL_ID, description: SKILL_DESCRIPTION, path: SKILL_PATH, content: SKILL_CONTENT });
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export function addSkill(skills) {
+    skills.add(orchestrateSkill());
+}

package/dist/{cleanup.d.ts → tree/cleanup.d.ts}

@@ -1,25 +1,4 @@
-import type { Plugin } from "@opencode/plugin";
-import { type CleanupResult } from "./notices.js";
-import { type RosterStorage } from "./roster.js";
-type Context = Plugin.Context;
-/** What would be lost by removing a worktree. */
-export interface WorktreeState {
-    /** Paths with uncommitted changes, untracked files included, as `git status --porcelain` lists them. */
-    readonly changes: readonly string[];
-    /**
-     * Commits reachable from the worktree's HEAD but from no branch, tag or remote-tracking ref, nor
-     * from the commit the worktree was made from, newest first.
-     */
-    readonly commits: readonly string[];
-}
-export interface CleanupPorts {
-    readonly storage: RosterStorage;
-    readonly worktree: Pick<Context["worktree"], "remove">;
-    /** The project of the plugin's location, for roster entries recorded before they carried their project. */
-    readonly projectID: string;
-    /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
-    readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
-}
+import type { CleanupPorts, CleanupResult, WorktreeState } from "./ports.js";
 export interface CleanupInput {
     readonly sessionID: string;
     readonly force?: boolean;
@@ -27,9 +6,8 @@ export interface CleanupInput {
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export declare const MAX_LISTED = 50;
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
+ * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
 /** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
@@ -46,9 +24,10 @@ export declare const GIT_LOCATIONS: Readonly<Record<"posix" | "win32", readonly
 export declare function findGit(env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string;
 /** The commit a worktree is on, or undefined when git cannot tell. */
 export declare function headOf(directory: string): Promise<string | undefined>;
+/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
+export declare function dirtyOf(directory: string): Promise<boolean | undefined>;
 /**
  * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
  * `base`, the commit the worktree was made from, are not its own work and are not listed.
  */
 export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;
-export {};

package/dist/{cleanup.js → tree/cleanup.js}

@@ -1,32 +1,34 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";
-import { keepReason } from "./notices.js";
-import { remove, rosterKey } from "./roster.js";
+import { forgetDropped } from "./forget.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. */
 export const MAX_LISTED = 50;
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
+ * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export async function cleanup(ports, parentID, input) {
-    const entry = (await ports.storage.get(rosterKey(parentID, input.sessionID)));
+    const entry = await childStore(ports.storage).entry(parentID, input.sessionID);
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
-    if (!entry.isolated)
-        throw new Error(`${input.sessionID} ran in ${entry.directory}, not in a worktree of its own; there is nothing to remove.`);
     const { directory } = entry;
-    const forget = () => remove(ports.storage, parentID, input.sessionID);
+    // 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);
+        return group ? { group } : {};
+    };
+    if (!entry.isolated)
+        return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
     // With force the state only decides whether there is anything left to remove, so a worktree git
     // can no longer read is still removed.
     const state = await ports
         .inspect(directory, entry.base)
         .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
-    if (!state) {
-        await forget();
-        return { sessionID: input.sessionID, directory, outcome: "gone" };
-    }
+    if (!state)
+        return { sessionID: input.sessionID, directory, outcome: "gone", ...(await forget()) };
     const reason = keepReason(state);
     if (reason && !input.force)
         return {
@@ -42,8 +44,7 @@ export async function cleanup(ports, parentID, input) {
         directory,
         force: input.force === true,
     });
-    await forget();
-    return { sessionID: input.sessionID, directory, outcome: "removed" };
+    return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
 }
 /** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export const GIT_ENV = "OPENCODE_COURIER_GIT";
@@ -85,6 +86,10 @@ function git(directory, args) {
 export function headOf(directory) {
     return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
 }
+/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
+export function dirtyOf(directory) {
+    return git(directory, ["status", "--porcelain"]).then((out) => out.trim().length > 0, () => undefined);
+}
 /**
  * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
  * `base`, the commit the worktree was made from, are not its own work and are not listed.

package/dist/tree/context.d.ts

@@ -0,0 +1,15 @@
+import type { ContextPorts } from "./ports.js";
+/** The part of a session context this hook changes. */
+export interface Shaped {
+    readonly sessionID: string;
+    tools: Record<string, unknown>;
+    system: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -0,0 +1,34 @@
+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. */
+const ROLES_MAX = 1000;
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export async function shapeContext(ports, event) {
+    try {
+        const depth = await depthOf(ports, event.sessionID);
+        if (depth === null && !event.tools.courier_spawn)
+            return;
+        if (depth !== null && depth >= ports.limits.maxDepth)
+            delete event.tools.courier_spawn;
+        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
+            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) {
+    const known = ports.roles.get(sessionID);
+    if (known !== undefined)
+        return known;
+    // The reverse index alone: a scan here would run for every session's first request, courier or not.
+    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;
+}

package/dist/tree/domain.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The tree's pure rules, on plain data: the limits, a session's lineage, whether it runs, and a group
+ * member's standing. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
+ */
+import type { Plugin } from "@opencode/plugin";
+import type { Status } from "../kernel/protocol.js";
+type Context = Plugin.Context;
+/** The limits on the tree of sessions courier_spawn builds, from the plugin's options. */
+export interface Limits {
+    readonly maxDepth: number;
+    readonly maxChildren: number;
+    readonly maxTotal: number;
+}
+export declare const DEFAULT_LIMITS: Limits;
+/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
+export declare function readLimits(options: unknown): {
+    limits: Limits;
+    problems: string[];
+};
+/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+export declare function readNativeChildren(options: unknown): {
+    nativeChildren: boolean;
+    problems: string[];
+};
+/** A session's times, as `session.get` gives them. */
+type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
+/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+export declare const busy: (time: Pick<Times, "updated" | "idle">) => boolean;
+/** A session started with courier_spawn, recorded under the session that started it. */
+export interface RosterEntry {
+    readonly sessionID: string;
+    readonly parentID: string;
+    readonly title: string;
+    readonly directory: string;
+    readonly isolated: boolean;
+    readonly createdAt: number;
+    /** For an isolated child, the directory its worktree was made from; for the record, nothing acts on it. */
+    readonly source?: string;
+    /** For an isolated child, the project its worktree belongs to; courier_cleanup removes it from there. */
+    readonly project?: string;
+    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
+    readonly base?: string;
+    /** `"status"` when its brief asked for a report with a status; absent for a child an earlier release briefed. */
+    readonly reports?: "status";
+    /** The join group courier_spawn put it in, whose release holds its report; absent for a child in none. */
+    readonly group?: string;
+    /** Created with OpenCode's own `parentID` (the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
+    readonly native?: true;
+}
+/** `lineage` over roster entries already read. */
+export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
+/** Roster entries by their session, for `lineageBy`. */
+export declare function bySession(entries: ReadonlyArray<RosterEntry>): Map<string, RosterEntry>;
+/** `lineage` over roster entries already read and mapped by `bySession`. */
+export declare function lineageBy(bySession: ReadonlyMap<string, RosterEntry>, sessionID: string): RosterEntry[];
+/**
+ * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
+ * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
+ */
+export declare function nativeRootOf(chain: ReadonlyArray<RosterEntry>): string;
+/** What a report lists besides its text; `checks` are the commands the session ran and what each gave. */
+export interface Artifacts {
+    readonly branch?: string;
+    readonly commits?: ReadonlyArray<string>;
+    readonly files?: ReadonlyArray<string>;
+    readonly checks?: ReadonlyArray<{
+        readonly command: string;
+        readonly result: string;
+    }>;
+}
+/** A report held with its group: its status, text and artifacts, as courier_send was given them, and when. */
+export interface HeldReport {
+    readonly at: number;
+    readonly status: Status;
+    readonly message: string;
+    readonly artifacts?: Artifacts;
+}
+/** A member of a group that left it without a report, and why: its turn failed or was interrupted, it was deleted, or courier_cleanup dropped it. */
+export interface LeftMember {
+    readonly sessionID: string;
+    readonly title: string;
+    readonly by: "failed" | "interrupted" | "deleted" | "dropped";
+}
+export declare const isGroupName: (value: unknown) => value is string;
+/** A member of a group, as stored: its title for the release notice, and its report or how it left. */
+export interface Member {
+    readonly title: string;
+    readonly joinedAt: number;
+    readonly report?: HeldReport;
+    readonly left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+}
+/** What is known of a member's standing: its report is held, still out, or it left, or it is no longer in an open group. */
+export type Standing = "held" | "out" | LeftMember["by"] | "released";
+/** A member's standing from its stored value, or `released` when there is none. */
+export declare function standingOf(member: Member | undefined): Standing;
+/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
+export declare const complete: (members: ReadonlyArray<Member>) => boolean;
+export {};