opencode-courier 0.5.0 → 0.7.0

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

@@ -21,7 +21,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly members: number;
                 }[];
                 readonly waiting: number;
-                readonly truncated?: number | undefined;
+                readonly stalled?: number | undefined;
             }, {
                 readonly running: number;
                 readonly idle: number;
@@ -31,17 +31,17 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly members: number;
                 }[];
                 readonly waiting: number;
-                readonly truncated?: number | undefined;
+                readonly stalled?: number | undefined;
             }> & import("effect/Schema").Struct<{
                 readonly running: import("effect/Schema").Int;
                 readonly waiting: import("effect/Schema").Int;
                 readonly idle: import("effect/Schema").Int;
+                readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
                 readonly groups: import("effect/Schema").$Array<import("effect/Schema").Struct<{
                     readonly name: import("effect/Schema").String;
                     readonly reported: import("effect/Schema").Int;
                     readonly members: import("effect/Schema").Int;
                 }>>;
-                readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
             }>;
         };
         readonly tree: {
@@ -60,7 +60,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -68,17 +68,22 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | {
                         readonly type: "question";
                         readonly question: string;
+                    } | {
+                        readonly type: "form";
+                        readonly title: string;
                     })[];
                     readonly group?: {
                         readonly name: string;
                         readonly standing: string;
                     } | undefined;
+                    readonly stopped?: boolean | undefined;
                     readonly idle?: number | undefined;
                     readonly report?: {
                         readonly progressed: boolean;
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -86,6 +91,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }, {
                 readonly rows: readonly {
@@ -95,7 +101,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -103,17 +109,22 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | {
                         readonly type: "question";
                         readonly question: string;
+                    } | {
+                        readonly type: "form";
+                        readonly title: string;
                     })[];
                     readonly group?: {
                         readonly name: string;
                         readonly standing: string;
                     } | undefined;
+                    readonly stopped?: boolean | undefined;
                     readonly idle?: number | undefined;
                     readonly report?: {
                         readonly progressed: boolean;
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -121,6 +132,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }> & import("effect/Schema").Struct<{
                 readonly rows: import("effect/Schema").$Array<import("effect/Schema").Struct<{
@@ -128,8 +140,10 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly parentID: import("effect/Schema").String;
                     readonly title: import("effect/Schema").String;
                     readonly depth: import("effect/Schema").Int;
-                    readonly state: import("effect/Schema").Literals<readonly ["running", "waiting", "idle", "gone"]>;
+                    readonly state: import("effect/Schema").Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+                    readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
                     readonly outcome: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+                    readonly stopped: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
                     readonly report: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
                         readonly state: import("effect/Schema").Literals<readonly ["owed", "reported", "ended"]>;
                         readonly status: import("effect/Schema").optionalKey<import("effect/Schema").String>;
@@ -154,9 +168,13 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     }>, import("effect/Schema").Struct<{
                         readonly type: import("effect/Schema").Literal<"question">;
                         readonly question: import("effect/Schema").String;
+                    }>, import("effect/Schema").Struct<{
+                        readonly type: import("effect/Schema").Literal<"form">;
+                        readonly title: import("effect/Schema").String;
                     }>]>>;
                 }>>;
                 readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+                readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
             }>;
         };
         readonly stop: {
@@ -196,6 +214,37 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                 readonly refused: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
             };
         };
+        readonly cleanup: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly by: string;
+            }, {
+                readonly sessionID: string;
+                readonly by: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+                readonly by: import("effect/Schema").String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "removed" | "gone" | "forgotten";
+            } | {
+                readonly outcome: "kept";
+                readonly reason: string;
+            }, {
+                readonly outcome: "removed" | "gone" | "forgotten";
+            } | {
+                readonly outcome: "kept";
+                readonly reason: string;
+            }> & import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+                readonly outcome: import("effect/Schema").Literals<readonly ["forgotten", "removed", "gone"]>;
+            }>, import("effect/Schema").Struct<{
+                readonly outcome: import("effect/Schema").Literal<"kept">;
+                readonly reason: import("effect/Schema").String;
+            }>]>;
+            readonly errors: {
+                readonly refused: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
     };
     readonly events: {};
 }>>;

package/dist/tree/rpc-handlers.js

@@ -1,9 +1,14 @@
+import { describeFailure } from "../kernel/protocol.js";
+import { isNotFound } from "../platform/json.js";
+import { cleanup } from "./cleanup.js";
 import { panel } from "./panel.js";
 import { treeRpc } from "./rpc.js";
 import { stop } from "./stop.js";
+import { childStore } from "./store.js";
 import { summary } from "./summary.js";
 /** Serves the tree's RPC at the plugin's location, through the same use cases as the tools; disposed with the plugin. */
 export function registerTreeRpc(rpc, ports) {
+    const refused = (cause) => (cause instanceof Error ? cause.message : String(cause));
     return rpc.register(treeRpc, {
         summary: ({ sessionID }) => summary(ports.courier, sessionID),
         tree: ({ sessionID }) => panel(ports.courier, sessionID),
@@ -13,8 +18,32 @@ export function registerTreeRpc(rpc, ports) {
                 return { stopped: stopped.map(({ sessionID, title, outcome }) => ({ sessionID, title, outcome })), cancelled: cancelled.length };
             }
             catch (cause) {
-                return error("refused", cause instanceof Error ? cause.message : String(cause), {});
+                return error("refused", refused(cause), {});
+            }
+        },
+        cleanup: async ({ sessionID, by }, { error }) => {
+            try {
+                return await forget(ports, by, sessionID);
+            }
+            catch (cause) {
+                return error("refused", refused(cause), {});
             }
         },
     });
 }
+/**
+ * Forgets a session OpenCode no longer knows as courier_cleanup called from its own parent, once `by` is found above it,
+ * as courier_stop checks. A session OpenCode still has, or cannot say it lost, is refused: forgetting it loses its report.
+ */
+async function forget(ports, by, sessionID) {
+    const chain = await childStore(ports.courier.storage).lineage(sessionID);
+    if (!chain.length)
+        throw new Error(`${sessionID} was not started with courier_spawn, so there is nothing to forget.`);
+    if (!chain.some((entry) => entry.parentID === by))
+        throw new Error(`${by} is not above ${sessionID}: only a session above it, in the line of sessions that started it with courier_spawn, can forget it.`);
+    const known = await ports.courier.session.get({ sessionID }).then(() => `${sessionID} is still known to OpenCode: only a gone session is forgotten here.`, (error) => (isNotFound(error) ? undefined : describeFailure("session.get", error).message));
+    if (known)
+        throw new Error(known);
+    const result = await cleanup(ports.cleanup, chain[0].parentID, { sessionID });
+    return result.outcome === "kept" ? { outcome: "kept", reason: result.reason } : { outcome: result.outcome };
+}

package/dist/tree/rpc.d.ts

@@ -1,22 +1,22 @@
 import { Schema } from "effect";
 /** The sessions started under a session, as the prompt footer's status entry shows them. */
 declare const Summary: Schema.Struct<{
-    /** Running, and waiting on no request. */
+    /** Running, and waiting on no request or form. */
     readonly running: Schema.Int;
-    /** Waiting on a permission request or a question, which go to the person. */
+    /** Waiting on a permission request, a question or a form it shows, which go to the person. */
     readonly waiting: Schema.Int;
     /** Not running: done, or waiting for a message. */
     readonly idle: Schema.Int;
+    /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+    readonly stalled: Schema.optionalKey<Schema.Int>;
     readonly groups: Schema.$Array<Schema.Struct<{
         readonly name: Schema.String;
         readonly reported: Schema.Int;
         readonly members: Schema.Int;
     }>>;
-    /** Set when the subtree had more sessions than `maxTotal`, which were not counted. */
-    readonly truncated: Schema.optionalKey<Schema.Int>;
 }>;
 export type Summary = typeof Summary.Type;
-/** A request a session waits on until the person answers it: a permission request, or its first question. */
+/** A request a session waits on until the person answers it: a permission request, its first question, or a form it shows. */
 declare const Wait: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"permission">;
     readonly action: Schema.String;
@@ -24,6 +24,9 @@ declare const Wait: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly type: Schema.Literal<"question">;
     readonly question: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"form">;
+    readonly title: Schema.String;
 }>]>;
 /** One session of the tree panel: what courier_tree shows of it, and what it is doing, in epoch milliseconds. */
 declare const Row: Schema.Struct<{
@@ -32,10 +35,17 @@ declare const Row: Schema.Struct<{
     readonly title: Schema.String;
     /** A child of the panel's session is at depth 1. */
     readonly depth: Schema.Int;
-    /** `waiting` on a request to the person; `gone` when OpenCode no longer knows it. */
-    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+    /**
+     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+     */
+    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+    readonly stalled: Schema.optionalKey<Schema.Number>;
     /** How its last turn ended. */
     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+    /** Set when courier_stop stopped it since its last prompt. */
+    readonly stopped: Schema.optionalKey<Schema.Boolean>;
     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
     readonly report: Schema.optionalKey<Schema.Struct<{
         readonly state: Schema.Literals<readonly ["owed", "reported", "ended"]>;
@@ -65,9 +75,12 @@ declare const Row: Schema.Struct<{
     }>, Schema.Struct<{
         readonly type: Schema.Literal<"question">;
         readonly question: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"form">;
+        readonly title: Schema.String;
     }>]>>;
 }>;
-/** The sessions under a session, as courier_tree reads them, in the order a tree is drawn. */
+/** The sessions under a session, as courier_tree lists them, in the order a tree is drawn. */
 declare const Tree: Schema.Struct<{
     readonly rows: Schema.$Array<Schema.Struct<{
         readonly sessionID: Schema.String;
@@ -75,10 +88,17 @@ declare const Tree: Schema.Struct<{
         readonly title: Schema.String;
         /** A child of the panel's session is at depth 1. */
         readonly depth: Schema.Int;
-        /** `waiting` on a request to the person; `gone` when OpenCode no longer knows it. */
-        readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+        /**
+         * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+         * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+         */
+        readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+        /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+        readonly stalled: Schema.optionalKey<Schema.Number>;
         /** How its last turn ended. */
         readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+        /** Set when courier_stop stopped it since its last prompt. */
+        readonly stopped: Schema.optionalKey<Schema.Boolean>;
         /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
         readonly report: Schema.optionalKey<Schema.Struct<{
             readonly state: Schema.Literals<readonly ["owed", "reported", "ended"]>;
@@ -108,10 +128,15 @@ declare const Tree: Schema.Struct<{
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"question">;
             readonly question: Schema.String;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"form">;
+            readonly title: Schema.String;
         }>]>>;
     }>>;
-    /** Set when the subtree had more sessions than `maxTotal`, which were left out. */
+    /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
     readonly truncated: Schema.optionalKey<Schema.Int>;
+    /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+    readonly stalled: Schema.optionalKey<Schema.Number>;
 }>;
 export type Row = typeof Row.Type;
 export type Tree = typeof Tree.Type;
@@ -127,6 +152,14 @@ declare const Stopped: Schema.Struct<{
     readonly cancelled: Schema.Int;
 }>;
 export type Stopped = typeof Stopped.Type;
+/** What courier_cleanup did: forgot it, removed its worktree, found that already gone, or kept the worktree, saying why. */
+declare const Forgotten: Schema.Union<readonly [Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["forgotten", "removed", "gone"]>;
+}>, Schema.Struct<{
+    readonly outcome: Schema.Literal<"kept">;
+    readonly reason: Schema.String;
+}>]>;
+export type Forgotten = typeof Forgotten.Type;
 export declare const treeRpc: {
     readonly id: "courier";
     readonly methods: {
@@ -147,7 +180,7 @@ export declare const treeRpc: {
                     readonly members: number;
                 }[];
                 readonly waiting: number;
-                readonly truncated?: number | undefined;
+                readonly stalled?: number | undefined;
             }, {
                 readonly running: number;
                 readonly idle: number;
@@ -157,21 +190,21 @@ export declare const treeRpc: {
                     readonly members: number;
                 }[];
                 readonly waiting: number;
-                readonly truncated?: number | undefined;
+                readonly stalled?: number | undefined;
             }> & Schema.Struct<{
-                /** Running, and waiting on no request. */
+                /** Running, and waiting on no request or form. */
                 readonly running: Schema.Int;
-                /** Waiting on a permission request or a question, which go to the person. */
+                /** Waiting on a permission request, a question or a form it shows, which go to the person. */
                 readonly waiting: Schema.Int;
                 /** Not running: done, or waiting for a message. */
                 readonly idle: Schema.Int;
+                /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+                readonly stalled: Schema.optionalKey<Schema.Int>;
                 readonly groups: Schema.$Array<Schema.Struct<{
                     readonly name: Schema.String;
                     readonly reported: Schema.Int;
                     readonly members: Schema.Int;
                 }>>;
-                /** Set when the subtree had more sessions than `maxTotal`, which were not counted. */
-                readonly truncated: Schema.optionalKey<Schema.Int>;
             }>;
         };
         readonly tree: {
@@ -190,7 +223,7 @@ export declare const treeRpc: {
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -198,17 +231,22 @@ export declare const treeRpc: {
                     } | {
                         readonly type: "question";
                         readonly question: string;
+                    } | {
+                        readonly type: "form";
+                        readonly title: string;
                     })[];
                     readonly group?: {
                         readonly name: string;
                         readonly standing: string;
                     } | undefined;
+                    readonly stopped?: boolean | undefined;
                     readonly idle?: number | undefined;
                     readonly report?: {
                         readonly progressed: boolean;
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -216,6 +254,7 @@ export declare const treeRpc: {
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }, {
                 readonly rows: readonly {
@@ -225,7 +264,7 @@ export declare const treeRpc: {
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -233,17 +272,22 @@ export declare const treeRpc: {
                     } | {
                         readonly type: "question";
                         readonly question: string;
+                    } | {
+                        readonly type: "form";
+                        readonly title: string;
                     })[];
                     readonly group?: {
                         readonly name: string;
                         readonly standing: string;
                     } | undefined;
+                    readonly stopped?: boolean | undefined;
                     readonly idle?: number | undefined;
                     readonly report?: {
                         readonly progressed: boolean;
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -251,6 +295,7 @@ export declare const treeRpc: {
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }> & Schema.Struct<{
                 readonly rows: Schema.$Array<Schema.Struct<{
@@ -259,10 +304,17 @@ export declare const treeRpc: {
                     readonly title: Schema.String;
                     /** A child of the panel's session is at depth 1. */
                     readonly depth: Schema.Int;
-                    /** `waiting` on a request to the person; `gone` when OpenCode no longer knows it. */
-                    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+                    /**
+                     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+                     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+                     */
+                    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+                    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+                    readonly stalled: Schema.optionalKey<Schema.Number>;
                     /** How its last turn ended. */
                     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+                    /** Set when courier_stop stopped it since its last prompt. */
+                    readonly stopped: Schema.optionalKey<Schema.Boolean>;
                     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
                     readonly report: Schema.optionalKey<Schema.Struct<{
                         readonly state: Schema.Literals<readonly ["owed", "reported", "ended"]>;
@@ -292,10 +344,15 @@ export declare const treeRpc: {
                     }>, Schema.Struct<{
                         readonly type: Schema.Literal<"question">;
                         readonly question: Schema.String;
+                    }>, Schema.Struct<{
+                        readonly type: Schema.Literal<"form">;
+                        readonly title: Schema.String;
                     }>]>>;
                 }>>;
-                /** Set when the subtree had more sessions than `maxTotal`, which were left out. */
+                /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
                 readonly truncated: Schema.optionalKey<Schema.Int>;
+                /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+                readonly stalled: Schema.optionalKey<Schema.Number>;
             }>;
         };
         /** Stops `sessionID` and everything under it, as courier_stop called from `by`, which must be above it. */
@@ -337,6 +394,38 @@ export declare const treeRpc: {
                 readonly refused: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
             };
         };
+        /** Forgets `sessionID` as courier_cleanup called from its parent, without `force`; `by` must be above it. */
+        readonly cleanup: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly by: string;
+            }, {
+                readonly sessionID: string;
+                readonly by: string;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly by: Schema.String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "removed" | "gone" | "forgotten";
+            } | {
+                readonly outcome: "kept";
+                readonly reason: string;
+            }, {
+                readonly outcome: "removed" | "gone" | "forgotten";
+            } | {
+                readonly outcome: "kept";
+                readonly reason: string;
+            }> & Schema.Union<readonly [Schema.Struct<{
+                readonly outcome: Schema.Literals<readonly ["forgotten", "removed", "gone"]>;
+            }>, Schema.Struct<{
+                readonly outcome: Schema.Literal<"kept">;
+                readonly reason: Schema.String;
+            }>]>;
+            readonly errors: {
+                readonly refused: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+            };
+        };
     };
     readonly events: {};
 };

package/dist/tree/rpc.js

@@ -9,20 +9,21 @@ const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 const Group = Schema.Struct({ name: Schema.String, reported: Count, members: Count });
 /** The sessions started under a session, as the prompt footer's status entry shows them. */
 const Summary = Schema.Struct({
-    /** Running, and waiting on no request. */
+    /** Running, and waiting on no request or form. */
     running: Count,
-    /** Waiting on a permission request or a question, which go to the person. */
+    /** Waiting on a permission request, a question or a form it shows, which go to the person. */
     waiting: Count,
     /** Not running: done, or waiting for a message. */
     idle: Count,
+    /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+    stalled: Schema.optionalKey(Count),
     groups: Schema.Array(Group),
-    /** Set when the subtree had more sessions than `maxTotal`, which were not counted. */
-    truncated: Schema.optionalKey(Count),
 });
-/** A request a session waits on until the person answers it: a permission request, or its first question. */
+/** A request a session waits on until the person answers it: a permission request, its first question, or a form it shows. */
 const Wait = Schema.Union([
     Schema.Struct({ type: Schema.Literal("permission"), action: Schema.String, resources: Schema.Array(Schema.String) }),
     Schema.Struct({ type: Schema.Literal("question"), question: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("form"), title: Schema.String }),
 ]);
 /** One session of the tree panel: what courier_tree shows of it, and what it is doing, in epoch milliseconds. */
 const Row = Schema.Struct({
@@ -31,10 +32,17 @@ const Row = Schema.Struct({
     title: Schema.String,
     /** A child of the panel's session is at depth 1. */
     depth: Count,
-    /** `waiting` on a request to the person; `gone` when OpenCode no longer knows it. */
-    state: Schema.Literals(["running", "waiting", "idle", "gone"]),
+    /**
+     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+     */
+    state: Schema.Literals(["running", "waiting", "idle", "stalled", "gone"]),
+    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+    stalled: Schema.optionalKey(Schema.Number),
     /** How its last turn ended. */
     outcome: Schema.optionalKey(Schema.Literals(["succeeded", "failed", "interrupted"])),
+    /** Set when courier_stop stopped it since its last prompt. */
+    stopped: Schema.optionalKey(Schema.Boolean),
     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
     report: Schema.optionalKey(Schema.Struct({ state: Schema.Literals(["owed", "reported", "ended"]), status: Schema.optionalKey(Schema.String), progressed: Schema.Boolean })),
     /** Its join group, and its standing there: `held`, `out`, how it left, or `released`. */
@@ -49,11 +57,13 @@ const Row = Schema.Struct({
     tool: Schema.optionalKey(Schema.Struct({ name: Schema.String, at: Schema.Number })),
     waits: Schema.Array(Wait),
 });
-/** The sessions under a session, as courier_tree reads them, in the order a tree is drawn. */
+/** The sessions under a session, as courier_tree lists them, in the order a tree is drawn. */
 const Tree = Schema.Struct({
     rows: Schema.Array(Row),
-    /** Set when the subtree had more sessions than `maxTotal`, which were left out. */
+    /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
     truncated: Schema.optionalKey(Count),
+    /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+    stalled: Schema.optionalKey(Schema.Number),
 });
 /** What a stop did to each session, deepest first, as courier_stop reports it. */
 const Stopped = Schema.Struct({
@@ -61,6 +71,11 @@ const Stopped = Schema.Struct({
     /** How many scheduled messages were cancelled. */
     cancelled: Count,
 });
+/** What courier_cleanup did: forgot it, removed its worktree, found that already gone, or kept the worktree, saying why. */
+const Forgotten = Schema.Union([
+    Schema.Struct({ outcome: Schema.Literals(["forgotten", "removed", "gone"]) }),
+    Schema.Struct({ outcome: Schema.Literal("kept"), reason: Schema.String }),
+]);
 export const treeRpc = Rpc.define({
     id: "courier",
     methods: {
@@ -78,6 +93,12 @@ export const treeRpc = Rpc.define({
             output: Schema.toStandardSchemaV1(Stopped),
             errors: { refused: Schema.toStandardSchemaV1(Schema.Struct({})) },
         },
+        /** Forgets `sessionID` as courier_cleanup called from its parent, without `force`; `by` must be above it. */
+        cleanup: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, by: Schema.String })),
+            output: Schema.toStandardSchemaV1(Forgotten),
+            errors: { refused: Schema.toStandardSchemaV1(Schema.Struct({})) },
+        },
     },
     events: {},
 });

package/dist/tree/stop.js

@@ -4,6 +4,7 @@ import { cleanup } from "./cleanup.js";
 import { childStore } from "./store.js";
 import { subtree } from "./subtree.js";
 import { stoppedNotice } from "./text.js";
+import { forgetWakes } from "./wake.js";
 /** Rounds of looking again for sessions started while others were being stopped. */
 const ROUNDS = 3;
 /**
@@ -62,6 +63,7 @@ async function silence(ports, sessionID, cancelled) {
     catch (error) {
         log(`courier_stop: could not cancel the messages scheduled for ${sessionID}: ${String(error)}`);
     }
+    await forgetWakes(ports.courier, sessionID).catch((error) => log(`courier_stop: could not drop the wake watch of ${sessionID}: ${String(error)}`));
 }
 async function interrupt(ports, { entry, depth }) {
     const { sessionID, title } = entry;