@vincemakes/kiso-runtime 0.48.0 → 0.50.0

package/dist/compose.js

@@ -28,7 +28,22 @@ export function composeToolTable(registry, rules = []) {
         "- end your turn with your findings — never end on a bare tool result",
         ...tools.flatMap((t) => (t.promptSnippet === undefined ? [] : [`- ${t.promptSnippet}`])),
     ];
-    const guidelines = tools.flatMap((t) => (t.promptGuidelines ?? []).map((g) => `- ${t.name}: ${g}`));
+    // Plan B: one statement per fact — a guideline body several tools carry
+    // prints ONCE, naming every tool that carries it, in first-seen order.
+    // The names stay: a host's or an extension's guideline may need its
+    // tool's name to read unambiguously.
+    const byBody = new Map();
+    for (const t of tools) {
+        for (const g of t.promptGuidelines ?? []) {
+            const body = g.trim();
+            const names = byBody.get(body);
+            if (names === undefined)
+                byBody.set(body, [t.name]);
+            else if (!names.includes(t.name))
+                names.push(t.name);
+        }
+    }
+    const guidelines = [...byBody].map(([body, names]) => `- ${names.join(", ")}: ${body}`);
     if (guidelines.length > 0)
         lines.push("Active tool guidelines:", ...guidelines);
     return lines.join("\n");

package/dist/session.d.ts

@@ -130,7 +130,7 @@ export declare class AgentSession {
     /** Deliver this session's task transitions to the model: into a live
      *  run at its next safe point, or — idle — held for the next run, or one
      *  continuation run through `onWake` (off with `wake: false`). */
-    useTasks(manager: TaskManager, options?: Pick<TaskDeliveryOptions, "wake" | "onWake" | "windowMs" | "maxWakes" | "onLost"> & {
+    useTasks(manager: TaskManager, options?: Pick<TaskDeliveryOptions, "wake" | "onWake" | "windowMs" | "maxWakes" | "onLost" | "onBudgetSpent"> & {
         readonly autoDetachMinAgeMs?: number;
     }): () => void;
     /** ADR-0057 §5 (3e D1) — a person's steer arrived: the foreground
@@ -256,6 +256,10 @@ export declare class AgentSession {
      *  binding, restored from the durable profile on open. The status row
      *  reads THIS, so the row and the request can never disagree. */
     get model(): string;
+    /** 0.49.0 C1: the config profile that named the live binding — null for
+     *  a direct provider/model or an SDK caller. Moves with every binding,
+     *  so a delegated child can run on the conversation's own profile. */
+    get profileName(): string | null;
     /** A1a: the parts of the NEXT request as the kernel would assemble them —
      *  the system prompt, the tool table (the same snapshot the loop sends:
      *  live extension tools included), the projected messages with their

package/dist/session.js

@@ -654,6 +654,12 @@ export class AgentSession {
     get model() {
         return this.#model;
     }
+    /** 0.49.0 C1: the config profile that named the live binding — null for
+     *  a direct provider/model or an SDK caller. Moves with every binding,
+     *  so a delegated child can run on the conversation's own profile. */
+    get profileName() {
+        return this.#profileName;
+    }
     /** A1a: the parts of the NEXT request as the kernel would assemble them —
      *  the system prompt, the tool table (the same snapshot the loop sends:
      *  live extension tools included), the projected messages with their

package/dist/tasks/delivery.d.ts

@@ -37,6 +37,15 @@
  * 16 KiB together; members already delivered are named as reported, and
  * only the rest are receipted. A failure goes into a live run at once and
  * never wakes on its own; idle, it waits for its group.
+ *
+ * 0.49.0 A: a delegate call that waits for its children (the join)
+ * CLAIMS each one that ended while it waited, and its own result carries
+ * that child's handoff. Such a member is delivered once the claiming
+ * call's result is durable — an error result included, since it carries
+ * the handoffs too — and the group's notice names it as reported. A claim
+ * whose call never returned (a crash: the kernel records no result, only
+ * an uncertain execution) delivered nothing, so the member rides its
+ * group's notice in full: never in both places, never in neither.
  */
 import { type Event, type UserInputVia } from "@vincemakes/kiso-core";
 import { type Run } from "../run.js";
@@ -64,6 +73,16 @@ export interface TaskDeliveryOptions {
      *  startup or as it is heard — the person can be told at once, while
      *  the model's notice keeps its own turn. A claimed loss never comes. */
     readonly onLost?: (taskIds: readonly string[]) => void;
+    /** Finding 0480-F9: the chain budget is spent — a task's end that would
+     *  have woken the session only notifies. Called ONCE per exhaustion (the
+     *  first such end since the last run a person started; a resume whose log
+     *  already carries the sentence is not told again), so the person can be
+     *  told why the chain went quiet. The model's notice says it either way. */
+    readonly onBudgetSpent?: (info: {
+        readonly wakes: number;
+        readonly maxWakes: number;
+        readonly taskIds: readonly string[];
+    }) => void;
     /** How much of a failed task's output rides its notice. Default 2 KB. */
     readonly tailBytes?: number;
     /** Read a task's output tail (injectable for tests). */

package/dist/tasks/delivery.js

@@ -37,17 +37,30 @@
  * 16 KiB together; members already delivered are named as reported, and
  * only the rest are receipted. A failure goes into a live run at once and
  * never wakes on its own; idle, it waits for its group.
+ *
+ * 0.49.0 A: a delegate call that waits for its children (the join)
+ * CLAIMS each one that ended while it waited, and its own result carries
+ * that child's handoff. Such a member is delivered once the claiming
+ * call's result is durable — an error result included, since it carries
+ * the handoffs too — and the group's notice names it as reported. A claim
+ * whose call never returned (a crash: the kernel records no result, only
+ * an uncertain execution) delivered nothing, so the member rides its
+ * group's notice in full: never in both places, never in neither.
  */
 import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { isRuntimeInput } from "@vincemakes/kiso-core";
 import { NOTICE_FOOTER as FOOTER } from "../run.js";
+import { CHILD_HANDOFF_BYTES, GROUP_HANDOFF_BYTES, handoffBody, handoffRecordOf, TAIL_BYTES } from "./handoff.js";
 import { endTransitionOf } from "./manager.js";
 const key = (i) => `${i.taskId}:${i.transition}`;
 export const DEFAULT_MAX_WAKES = 20;
-/** ADR-0058 3d (D3): a child's excerpt, and a group's excerpts together. */
-const CHILD_EXCERPT_BYTES = 4_096;
-const GROUP_EXCERPT_BYTES = 16_384;
+/** The model's sentence for a spent budget (the text 0.48.0 shipped). */
+const spentSentence = (wakes) => `chain budget spent: ${wakes} autonomous wakes since the person's last message — continue when they speak`;
+/** ADR-0058 3d (D3): a child's excerpt, and a group's excerpts together —
+ *  the handoff format's budgets (0.49.0 C3). */
+const CHILD_EXCERPT_BYTES = CHILD_HANDOFF_BYTES;
+const GROUP_EXCERPT_BYTES = GROUP_HANDOFF_BYTES;
 export class TaskDelivery {
     #o;
     #receipts = new Set();
@@ -62,6 +75,8 @@ export class TaskDelivery {
     /** ended agent tasks waiting for their group (restart: heard at startup) */
     #ended = new Map();
     #recheck = null;
+    /** the person-run the budget was last said spent in (0480-F9) */
+    #spentEpoch = null;
     #unsubscribe;
     constructor(options) {
         this.#o = options;
@@ -75,8 +90,10 @@ export class TaskDelivery {
             const item = itemOf(task);
             if (item === null || item.transition === "ready" || this.#receipts.has(key(item)))
                 continue;
-            // a tool result reported it: the claim alone decides (Amendment 7)
-            if (task.claims?.some((c) => c.transition === item.transition) === true)
+            // a tool result reported it: the claim alone decides (Amendment 7) —
+            // for an agent task, once its claiming call's result is durable (0.49.0 A)
+            const claim = task.claims?.find((c) => c.transition === item.transition);
+            if (claim !== undefined && (task.agent === undefined || this.#toldByResult(claim.executionId)))
                 continue;
             if (item.transition === "unknown")
                 lost.push(task.id);
@@ -167,8 +184,8 @@ export class TaskDelivery {
         const mode = this.#modeOf(task, item);
         if (mode === "silent")
             return;
-        const spent = mode === "notify" && this.#eligible(task, item) && !this.#underBudget();
-        this.#buffer.push({ item, line: spent ? `${this.#line(task, item)}\nchain budget spent: ${this.#wakesSinceLastPerson()} autonomous wakes since the person's last message — continue when they speak` : this.#line(task, item), mode });
+        const spent = mode === "notify" && this.#eligible(task, item) ? this.#spent([task.id]) : null;
+        this.#buffer.push({ item, line: spent !== null ? `${this.#line(task, item)}\n${spent}` : this.#line(task, item), mode });
         if (this.#timer === null)
             this.#timer = setTimeout(() => this.#flush(), this.#o.windowMs ?? 1_000);
     }
@@ -259,6 +276,43 @@ export class TaskDelivery {
     #underBudget() {
         return this.#wakesSinceLastPerson() < (this.#o.maxWakes ?? DEFAULT_MAX_WAKES);
     }
+    /** 0480-F9: the sentence when the budget is spent (null while it is not),
+     *  and the person's hook, once per exhaustion. */
+    #spent(taskIds) {
+        if (this.#underBudget())
+            return null;
+        const wakes = this.#wakesSinceLastPerson();
+        const epoch = this.#personEpoch();
+        if (this.#spentEpoch !== epoch) {
+            this.#spentEpoch = epoch;
+            if (!this.#spentInLog(epoch))
+                this.#o.onBudgetSpent?.({ wakes, maxWakes: this.#o.maxWakes ?? DEFAULT_MAX_WAKES, taskIds });
+        }
+        return spentSentence(wakes);
+    }
+    /** The index of the last run's first input a person started (−1: none). */
+    #personEpoch() {
+        const events = this.#o.events();
+        let epoch = -1;
+        let firstOfRun = true;
+        for (let i = 0; i < events.length; i++) {
+            const e = events[i];
+            if (e.type === "terminal") {
+                firstOfRun = true;
+                continue;
+            }
+            if (e.type !== "user_input" || !firstOfRun)
+                continue;
+            firstOfRun = false;
+            if (!isRuntimeInput(e))
+                epoch = i;
+        }
+        return epoch;
+    }
+    /** A resume: the log already carries the sentence after that run. */
+    #spentInLog(epoch) {
+        return this.#o.events().slice(epoch + 1).some((e) => e.type === "user_input" && typeof e.content === "string" && e.content.includes("chain budget spent:"));
+    }
     #wakesSinceLastPerson() {
         let wakes = 0;
         let firstOfRun = true;
@@ -348,9 +402,11 @@ export class TaskDelivery {
         return { closed: to < events.length && (runEnded || [...calls].every((c) => answered.has(c))), members: members.includes(task.id) ? members : [...members, task.id] };
     }
     #complete(group) {
+        // 0.49.0 B: a member's END, not its process's — a writer being
+        // collected has not ended, so its group is not complete yet
         return group.closed && group.members.every((id) => {
-            const kind = this.#o.manager.get(id)?.state.kind;
-            return kind === undefined || kind === "ended" || kind === "unknown" || kind === "not_run";
+            const task = this.#o.manager.get(id);
+            return task === undefined || endTransitionOf(task) !== null;
         });
     }
     /** ONE notice for a complete group: every member's line, excerpts within
@@ -362,10 +418,19 @@ export class TaskDelivery {
         const tasks = members.map((id) => this.#o.manager.get(id)).filter((t) => t !== undefined);
         const fresh = [];
         const lines = [];
+        const unreturned = new Set();
         for (const task of tasks) {
             const item = itemOf(task);
             if (item === null)
                 continue;
+            // 0.49.0 A: its delegate call's own result carried it
+            const claim = task.claims?.find((c) => c.transition === item.transition);
+            if (claim !== undefined && this.#toldByResult(claim.executionId)) {
+                lines.push(`<kiso-task id="${task.id}" kind="agent" role="${task.agent?.role ?? ""}" status="${item.transition}" reported="earlier"/>`);
+                continue;
+            }
+            if (claim !== undefined)
+                unreturned.add(task.id);
             if (this.#receipts.has(key(item)) || this.#inFlight.has(key(item))) {
                 lines.push(`<kiso-task id="${task.id}" kind="agent" role="${task.agent?.role ?? ""}" status="${item.transition}" reported="earlier"/>`);
                 continue;
@@ -379,11 +444,16 @@ export class TaskDelivery {
         for (const { task, item } of fresh) {
             const excerpt = excerptOf(task, Math.min(CHILD_EXCERPT_BYTES, budget));
             budget -= excerpt.bytes;
-            lines.push(`${this.#agentTag(task, item)}${excerpt.text}`);
+            lines.push(`${this.#agentTag(task, item, unreturned.has(task.id))}${excerpt.text}`);
         }
         const items = fresh.map((f) => f.item);
         const notice = { lines, items };
         const wake = !restart && items.some((i) => this.#wakes(i));
+        // 0480-F9: a group that could have woken but for the budget says why,
+        // as a single task's end does (0.48.0 delivered it silently)
+        const spent = !restart && !wake && fresh.some(({ task, item }) => this.#eligible(task, item)) ? this.#spent(fresh.map((f) => f.task.id)) : null;
+        if (spent !== null)
+            lines.push(spent);
         const run = this.#o.liveRun();
         if (run !== undefined && this.#hand(run, notice, wake))
             return;
@@ -391,6 +461,12 @@ export class TaskDelivery {
             this.#pending.push({ notice, wake });
         this.#pump();
     }
+    /** 0.49.0 A: the call that claimed a child returned — its tool_result is
+     *  durable (error or not: it carries the handoffs either way). A crashed
+     *  call has none: the kernel records an uncertain execution instead. */
+    #toldByResult(executionId) {
+        return this.#o.events().some((e) => e.type === "tool_result" && e.executionId === executionId);
+    }
     /** handed to a run, or held for one, or already in the log */
     #known(k) {
         return this.#receipts.has(k) || this.#inFlight.has(k) || this.#pending.some((p) => p.notice.items.some((i) => key(i) === k));
@@ -400,8 +476,10 @@ export class TaskDelivery {
     #unpend(k) {
         this.#pending = this.#pending.filter((p) => !(p.notice.items.length === 1 && key(p.notice.items[0]) === k));
     }
-    #agentTag(task, item) {
+    #agentTag(task, item, unreturned = false) {
         const attrs = [`id="${task.id}"`, `kind="agent"`, `role="${task.agent?.role ?? ""}"`, `status="${item.transition}"`];
+        if (unreturned)
+            attrs.push(`note="its delegate call never returned"`);
         const outcome = outcomeOf(task);
         if (outcome !== undefined)
             attrs.push(`outcome="${outcome}"`);
@@ -409,8 +487,9 @@ export class TaskDelivery {
             attrs.push(`session="${task.agent.session}"`);
         if (task.endedAt !== undefined)
             attrs.push(`duration="${duration(task.endedAt - task.startedAt)}"`);
+        // I5: the answer is named only once the record commits it
         const result = resultPath(task);
-        attrs.push(existsSync(result) ? `result="${result}"` : `output="${task.outputPath}"`);
+        attrs.push(recordOf(task) !== null && existsSync(result) ? `result="${result}"` : `output="${task.outputPath}"`);
         return `<kiso-task ${attrs.join(" ")}/>`;
     }
     #line(task, item) {
@@ -447,42 +526,62 @@ function itemOf(task, transition) {
     return end === null ? null : { taskId: task.id, transition: end };
 }
 const resultPath = (task) => join(dirname(task.outputPath), "result.md");
-/** The child's outcome, as it wrote it beside its answer. */
+/** The child's outcome, as its result record commits it. */
 function outcomeOf(task) {
+    return recordOf(task)?.outcome;
+}
+/** The child's result record (result.json) — the commit of its result (I5). */
+function recordOf(task) {
+    let raw;
     try {
-        const parsed = JSON.parse(readFileSync(join(dirname(task.outputPath), "result.json"), "utf8"));
-        return typeof parsed.outcome === "string" ? parsed.outcome : undefined;
+        raw = readFileSync(join(dirname(task.outputPath), "result.json"), "utf8");
     }
     catch {
-        return undefined;
+        raw = null;
     }
+    return handoffRecordOf(raw);
 }
-/** A child's answer (result.md) cut to `bytes`, or — with no answer — the
- *  tail of what it printed. `bytes` counts the excerpt, never the pointer. */
+/** A child's handoff (the format in handoff.ts): its error, then its
+ *  answer (result.md, read only beside a valid result.json — I5) cut to
+ *  `bytes`, or — with no answer — the tail of what it printed. `bytes`
+ *  counts what is shown, never the pointer. */
 function excerptOf(task, bytes) {
-    const path = resultPath(task);
-    let answer;
-    try {
-        answer = readFileSync(path, "utf8").trimEnd();
+    const record = recordOf(task);
+    let answer = "";
+    if (record !== null) {
+        try {
+            answer = readFileSync(resultPath(task), "utf8");
+        }
+        catch {
+            answer = "";
+        }
     }
-    catch {
-        const tail = bytes > 0 ? readTail(task, Math.min(bytes, 2_048)) : "";
-        return tail === "" ? { text: "", bytes: 0 } : { text: `\n${tail}`, bytes: Buffer.byteLength(tail) };
-    }
-    if (answer === "")
-        return { text: "", bytes: 0 };
-    const size = Buffer.byteLength(answer);
-    if (size <= bytes)
-        return { text: `\n${answer}`, bytes: size };
-    if (bytes <= 0)
-        return { text: `\n[the whole answer: ${path}]`, bytes: 0 };
-    const cut = Buffer.from(answer).subarray(0, bytes).toString("utf8").replace(/\uFFFD+$/, "");
-    return { text: `\n${cut}\n… [truncated; the whole answer: ${path}]`, bytes: Buffer.byteLength(cut) };
+    const tail = rawTail(task.outputPath, TAIL_BYTES);
+    return handoffBody({ record, answer, tail: tail.text, tailCut: tail.cut, resultPath: resultPath(task) }, bytes);
 }
 function duration(ms) {
     const s = Math.max(0, Math.round(ms / 1000));
     return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
 }
+/** The last `bytes` of a file as read, and whether it held more. */
+function rawTail(path, bytes) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const size = fstatSync(fd).size;
+            const n = Math.min(size, bytes);
+            const buf = Buffer.alloc(n);
+            readSync(fd, buf, 0, n, size - n);
+            return { text: buf.toString("utf8"), cut: size > n };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return { text: "", cut: false };
+    }
+}
 function readTail(task, bytes) {
     try {
         const fd = openSync(task.outputPath, "r");

package/dist/tasks/handoff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The handoff format (ADR-0058, 0.49.0 C3/I7): what the model reads of one
+ * child, byte for byte the same whether the parent waited for it (the
+ * delegate tool's section, rendered by the subagent extension) or heard of
+ * it later (the group notice, rendered here). The extension carries its own
+ * copy, since it has no runtime dependency. The corpus in
+ * tests/fixtures/handoff holds both copies to the same expected bytes.
+ *
+ * The result record (result.json) commits a child's result (I5): the
+ * answer (result.md) is read only beside a valid record. Without one, the
+ * child's output tail is all there is (I6: nothing is inferred from its
+ * session's runs).
+ *
+ * Budgets count UTF-8 bytes of what is shown, never the pointers:
+ * the error line at most ERROR_BYTES, the tail at most TAIL_BYTES, and all
+ * of it within the budget the caller passes (CHILD_HANDOFF_BYTES, or what
+ * is left of GROUP_HANDOFF_BYTES).
+ */
+export declare const CHILD_HANDOFF_BYTES = 4096;
+export declare const GROUP_HANDOFF_BYTES = 16384;
+export declare const TAIL_BYTES = 2048;
+export declare const ERROR_BYTES = 1024;
+export interface HandoffRecord {
+    readonly outcome: string;
+    readonly error?: string;
+}
+export interface HandoffInput {
+    /** result.json, parsed; null when it is absent or unreadable */
+    readonly record: HandoffRecord | null;
+    /** result.md's text ("" when absent) — shown only beside a record */
+    readonly answer: string;
+    /** the last bytes of the child's output, as read (at most TAIL_BYTES) */
+    readonly tail: string;
+    /** whether the output held more than `tail` */
+    readonly tailCut: boolean;
+    readonly resultPath: string;
+}
+/** The record a result.json holds, or null — the commit test (I5). */
+export declare function handoffRecordOf(raw: string | null): HandoffRecord | null;
+/** One child's handoff body: lines each led by "\n", and the bytes shown. */
+export declare function handoffBody(input: HandoffInput, budget: number): {
+    readonly text: string;
+    readonly bytes: number;
+};

package/dist/tasks/handoff.js

@@ -0,0 +1,81 @@
+/**
+ * The handoff format (ADR-0058, 0.49.0 C3/I7): what the model reads of one
+ * child, byte for byte the same whether the parent waited for it (the
+ * delegate tool's section, rendered by the subagent extension) or heard of
+ * it later (the group notice, rendered here). The extension carries its own
+ * copy, since it has no runtime dependency. The corpus in
+ * tests/fixtures/handoff holds both copies to the same expected bytes.
+ *
+ * The result record (result.json) commits a child's result (I5): the
+ * answer (result.md) is read only beside a valid record. Without one, the
+ * child's output tail is all there is (I6: nothing is inferred from its
+ * session's runs).
+ *
+ * Budgets count UTF-8 bytes of what is shown, never the pointers:
+ * the error line at most ERROR_BYTES, the tail at most TAIL_BYTES, and all
+ * of it within the budget the caller passes (CHILD_HANDOFF_BYTES, or what
+ * is left of GROUP_HANDOFF_BYTES).
+ */
+export const CHILD_HANDOFF_BYTES = 4_096;
+export const GROUP_HANDOFF_BYTES = 16_384;
+export const TAIL_BYTES = 2_048;
+export const ERROR_BYTES = 1_024;
+/** The record a result.json holds, or null — the commit test (I5). */
+export function handoffRecordOf(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.outcome !== "string" || parsed.outcome === "")
+            return null;
+        return typeof parsed.error === "string" && parsed.error !== "" ? { outcome: parsed.outcome, error: parsed.error } : { outcome: parsed.outcome };
+    }
+    catch {
+        return null;
+    }
+}
+/** One child's handoff body: lines each led by "\n", and the bytes shown. */
+export function handoffBody(input, budget) {
+    let text = "";
+    let used = 0;
+    const room = () => Math.max(0, budget - used);
+    if (input.record?.error !== undefined) {
+        const line = headOf(`error: ${input.record.error.replace(/\s*\n\s*/g, " ").trim()}`, Math.min(ERROR_BYTES, room()));
+        if (line.text !== "") {
+            text += `\n${line.text}${line.cut ? "…" : ""}`;
+            used += Buffer.byteLength(line.text);
+        }
+    }
+    const answer = input.record === null ? "" : input.answer.trimEnd();
+    if (answer !== "") {
+        if (Buffer.byteLength(answer) <= room())
+            return { text: `${text}\n${answer}`, bytes: used + Buffer.byteLength(answer) };
+        if (room() === 0)
+            return { text: `${text}\n[the whole answer: ${input.resultPath}]`, bytes: used };
+        const cut = headOf(answer, room()).text;
+        return { text: `${text}\n${cut}\n… [truncated; the whole answer: ${input.resultPath}]`, bytes: used + Buffer.byteLength(cut) };
+    }
+    const tail = input.tail.trimEnd();
+    if (tail !== "") {
+        const kept = tailOf(tail, Math.min(TAIL_BYTES, room()));
+        if (kept.text !== "") {
+            text += `\n${input.tailCut || kept.cut ? "…" : ""}${kept.text}`;
+            used += Buffer.byteLength(kept.text);
+        }
+    }
+    return { text, bytes: used };
+}
+/** The first `bytes` of `s`, never splitting a character. */
+function headOf(s, bytes) {
+    const buf = Buffer.from(s, "utf8");
+    if (buf.length <= bytes)
+        return { text: s, cut: false };
+    return { text: buf.subarray(0, Math.max(0, bytes)).toString("utf8").replace(/�+$/, ""), cut: true };
+}
+/** The last `bytes` of `s`, never splitting a character. */
+function tailOf(s, bytes) {
+    const buf = Buffer.from(s, "utf8");
+    if (buf.length <= bytes)
+        return { text: s, cut: false };
+    return { text: buf.subarray(buf.length - Math.max(0, bytes)).toString("utf8").replace(/^�+/, ""), cut: true };
+}

package/dist/tasks/journal.d.ts

@@ -27,7 +27,13 @@ export interface TaskLaunch {
 export interface TaskAgent {
     readonly role: string;
     readonly session: string;
+    /** 0.49.0 B: a writer — its end is its COLLECTION. The process ending
+     *  is not the result: the parent collects what it left (a patch, an
+     *  acceptance) and records `collected`, and only then has it ended. */
+    readonly collect?: true;
 }
+/** 0.49.0 B: how a writer's collection ended. */
+export type CollectionOutcome = "collected" | "unchanged" | "stopped" | "failed";
 export type TaskRecord = {
     readonly type: "planned";
     readonly ts: number;
@@ -89,6 +95,14 @@ export type TaskRecord = {
     readonly ts: number;
     readonly transition: ClaimedTransition;
     readonly executionId: string;
+}
+/** 0.49.0 B: the parent's collection of a writer finished — the LAST
+ *  record of its end; until it is written the writer has not ended. */
+ | {
+    readonly type: "collected";
+    readonly ts: number;
+    readonly outcome: CollectionOutcome;
+    readonly reason?: string;
 };
 /** A transition as the model is told it — a notice's or a result's name. */
 export type ClaimedTransition = "ready" | "exited" | "failed" | "stopped" | "unknown";

package/dist/tasks/manager.d.ts

@@ -21,7 +21,7 @@
  * an idle session wakes (3c).
  */
 import type { AbortSignalLike } from "@vincemakes/kiso-core";
-import { type ClaimedTransition, type TaskAgent, type TaskProfile, type TaskState } from "./journal.js";
+import { type ClaimedTransition, type CollectionOutcome, type TaskAgent, type TaskProfile, type TaskState } from "./journal.js";
 /** Whether a recorded runner is still that process (ADR-0058 §6):
  *  "verified" — the pid is live AND its OS start time is the recorded one;
  *  "gone" — no such process, or another process holds the pid;
@@ -86,7 +86,15 @@ export interface TaskInfo {
         readonly transition: ClaimedTransition;
         readonly executionId: string;
     }[];
+    /** 0.49.0 B: a writer's collection, once recorded (absent until then). */
+    readonly collection?: {
+        readonly outcome: CollectionOutcome;
+        readonly reason?: string;
+    };
 }
+/** 0.49.0 B: a writer whose process ended and whose collection is not yet
+ *  recorded — not ended: never announced, never settled, never complete. */
+export declare function isCollecting(task: TaskInfo): boolean;
 /** The name a task's end (or its runner's vanishing, or a start that never
  *  ran) has for the model — as a notice says it, and as a claim records it. */
 export declare function endTransitionOf(task: TaskInfo): Exclude<ClaimedTransition, "ready"> | null;
@@ -144,6 +152,12 @@ export interface TaskManagerOptions {
     readonly backend: TaskBackend;
     /** A first listener — the same as `subscribe` right after construction. */
     readonly onTransition?: TaskListener;
+    /** 0.49.0 B: the host's collector for a writer that ended — called once
+     *  per collecting task (by the watcher, a wait, or `collectPending`). It
+     *  records `collected` itself, last; a collector that throws leaves the
+     *  record to the manager (`failed`, with the reason), so a writer's end
+     *  is never stuck. */
+    readonly collect?: (task: TaskInfo) => Promise<void>;
     /** How often live tasks are re-read. Default 500 ms. */
     readonly pollMs?: number;
     /** How long a live runner's identity is reused before it is checked
@@ -185,10 +199,16 @@ export declare class TaskManager {
      *  durable first, then the transition counts as seen, so it is never
      *  announced. A timeout, an abort, no execution id, an agent task (its
      *  end belongs to its group, 3d) or a claim that cannot be written
-     *  claim nothing: the transition is announced as before. */
+     *  claim nothing: the transition is announced as before.
+     *
+     *  0.49.0 A: `agentJoin` — the delegate call that started an agent task
+     *  and waits for it (the join) claims its end, so its own result reports
+     *  it and the group's notice names it as reported (I2: only a claim made
+     *  durable counts). While it waits, the watcher never announces it (I1). */
     awaitSettled(id: string, until: "end" | "ready", ms: number, opts?: {
         readonly executionId?: string;
         readonly signal?: AbortSignalLike;
+        readonly agentJoin?: boolean;
     }): Promise<TaskSettled>;
     /** 3e: a running foreground command that can become a task now —
      *  registered by its owner while it runs; returns the unregister. Every
@@ -216,4 +236,8 @@ export declare class TaskManager {
     observe(): void;
     /** Stop watching. Tasks keep running. */
     close(): void;
+    /** 0.49.0 B: collect every writer that ended uncollected — at a session's
+     *  open, BEFORE its delivery is built, so a restart delivers a writer as
+     *  it delivers anything that ended while nobody listened (never a wake). */
+    collectPending(): Promise<void>;
 }

package/dist/tasks/manager.js

@@ -23,10 +23,17 @@
 import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { appendRecord, fsyncDir, readRecords, runnerOf, verdictOf } from "./journal.js";
+/** 0.49.0 B: a writer whose process ended and whose collection is not yet
+ *  recorded — not ended: never announced, never settled, never complete. */
+export function isCollecting(task) {
+    return task.agent?.collect === true && task.state.kind === "ended" && task.collection === undefined;
+}
 /** The name a task's end (or its runner's vanishing, or a start that never
  *  ran) has for the model — as a notice says it, and as a claim records it. */
 export function endTransitionOf(task) {
     const s = task.state;
+    if (isCollecting(task))
+        return null;
     if (s.kind === "ended") {
         if (task.stoppedBy !== undefined)
             return "stopped";
@@ -58,9 +65,13 @@ export class TaskManager {
     #detachable = new Map();
     /** id → how many `awaitSettled` calls wait on it: the watcher skips it */
     #waiting = new Map();
+    /** 0.49.0 B: the host's collector, and the writers being collected now */
+    #collect;
+    #collecting = new Map();
     constructor(options) {
         this.root = options.root;
         this.#backend = options.backend;
+        this.#collect = options.collect;
         if (options.onTransition !== undefined)
             this.#listeners.add(options.onTransition);
         this.#pollMs = options.pollMs ?? 500;
@@ -234,7 +245,12 @@ export class TaskManager {
      *  durable first, then the transition counts as seen, so it is never
      *  announced. A timeout, an abort, no execution id, an agent task (its
      *  end belongs to its group, 3d) or a claim that cannot be written
-     *  claim nothing: the transition is announced as before. */
+     *  claim nothing: the transition is announced as before.
+     *
+     *  0.49.0 A: `agentJoin` — the delegate call that started an agent task
+     *  and waits for it (the join) claims its end, so its own result reports
+     *  it and the group's notice names it as reported (I2: only a claim made
+     *  durable counts). While it waits, the watcher never announces it (I1). */
     async awaitSettled(id, until, ms, opts = {}) {
         if (this.get(id) === undefined)
             throw new Error(`no task ${id} in this session`);
@@ -250,9 +266,10 @@ export class TaskManager {
             const deadline = Date.now() + ms;
             for (;;) {
                 const info = this.#info(id);
+                this.#maybeCollect(info); // a writer it waits for ends only once collected
                 const reached = endTransitionOf(info) ?? (until === "ready" && info.state.kind === "running" && info.state.ready ? "ready" : null);
                 if (reached !== null)
-                    return { info, settled: true, claimed: this.#claim(info, reached, opts.executionId) };
+                    return { info, settled: true, claimed: this.#claim(info, reached, opts.executionId, opts.agentJoin === true) };
                 const left = deadline - Date.now();
                 if (aborted || left <= 0)
                     return { info, settled: false, claimed: false };
@@ -277,8 +294,8 @@ export class TaskManager {
     /** The frozen order: the claim durable, THEN seen — an append that fails
      *  leaves the transition unseen, to be announced (a duplicate is the
      *  lesser evil next to a lost transition). */
-    #claim(info, transition, executionId) {
-        if (executionId === undefined || info.agent !== undefined)
+    #claim(info, transition, executionId, agentJoin = false) {
+        if (executionId === undefined || (info.agent !== undefined && !agentJoin))
             return false;
         try {
             appendRecord(join(this.root, info.id, JOURNAL), { type: "result_claimed", ts: Date.now(), transition, executionId });
@@ -378,9 +395,19 @@ export class TaskManager {
     }
     #poll() {
         for (const id of this.#ids()) {
-            // a tool call is waiting on it: what it sees, its result reports
-            if (this.#waiting.has(id))
+            // a tool call is waiting on it: what it sees, its result reports —
+            // but a writer it waits for is still collected (0.49.0 B)
+            if (this.#waiting.has(id)) {
+                if (this.#collect !== undefined) {
+                    try {
+                        this.#maybeCollect(this.#info(id));
+                    }
+                    catch {
+                        // a corrupt journal: read loudly where it is read on purpose
+                    }
+                }
                 continue;
+            }
             const before = this.#seen.get(id);
             // a lost (`unknown`) task is still read: if its end is recorded
             // later, that end is announced (Amendment 8)
@@ -393,6 +420,7 @@ export class TaskManager {
             catch {
                 continue; // a corrupt journal: reported where it is read, never here in the background
             }
+            this.#maybeCollect(info);
             const now = this.#kindOf(info);
             if (now === before)
                 continue;
@@ -404,8 +432,52 @@ export class TaskManager {
         }
     }
     #kindOf(info) {
+        if (isCollecting(info))
+            return "collecting";
         return info.state.kind === "running" && info.state.ready ? "ready" : info.state.kind;
     }
+    /** 0.49.0 B: start a writer's collection once — never twice at a time. A
+     *  collector that throws (or ends without its record) is recorded as a
+     *  failed collection, so the writer's end is never stuck. */
+    #maybeCollect(info) {
+        if (this.#collect === undefined || !isCollecting(info) || this.#collecting.has(info.id))
+            return;
+        const collect = this.#collect;
+        const journal = join(this.root, info.id, JOURNAL);
+        const done = (async () => {
+            let why;
+            try {
+                await collect(info);
+            }
+            catch (err) {
+                why = err instanceof Error ? err.message : String(err);
+            }
+            if (!readRecords(journal).some((r) => r.type === "collected")) {
+                appendRecord(journal, { type: "collected", ts: Date.now(), outcome: "failed", reason: why ?? "the collector recorded nothing" });
+            }
+        })().finally(() => this.#collecting.delete(info.id));
+        this.#collecting.set(info.id, done);
+    }
+    /** 0.49.0 B: collect every writer that ended uncollected — at a session's
+     *  open, BEFORE its delivery is built, so a restart delivers a writer as
+     *  it delivers anything that ended while nobody listened (never a wake). */
+    async collectPending() {
+        for (const id of this.#ids()) {
+            let info;
+            try {
+                info = this.#info(id);
+            }
+            catch {
+                continue;
+            }
+            if (info === undefined)
+                continue;
+            this.#maybeCollect(info);
+            const pending = this.#collecting.get(id);
+            if (pending !== undefined)
+                await pending;
+        }
+    }
     #info(id) {
         const records = readRecords(join(this.root, id, JOURNAL));
         const planned = records.find((r) => r.type === "planned");
@@ -419,6 +491,7 @@ export class TaskManager {
         const claims = records
             .filter((r) => r.type === "result_claimed")
             .map((r) => ({ transition: r.transition, executionId: r.executionId }));
+        const collected = records.find((r) => r.type === "collected");
         return {
             id,
             command: planned?.command ?? "",
@@ -432,6 +505,7 @@ export class TaskManager {
             startedAt: planned?.ts ?? 0,
             ...(terminal !== undefined ? { endedAt: terminal.ts } : {}),
             ...(claims.length > 0 ? { claims } : {}),
+            ...(collected !== undefined ? { collection: { outcome: collected.outcome, ...(collected.reason !== undefined ? { reason: collected.reason } : {}) } } : {}),
         };
     }
     #ids() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-runtime",
-	"version": "0.48.0",
+	"version": "0.50.0",
 	"description": "kiso runtime \u2014 durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
 	"type": "module",
 	"license": "MIT",
@@ -25,12 +25,12 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.48.0"
+		"@vincemakes/kiso-core": "0.50.0"
 	},
 	"peerDependencies": {
-		"@vincemakes/kiso-provider-anthropic": "0.48.0",
-		"@vincemakes/kiso-provider-openai": "0.48.0",
-		"@vincemakes/kiso-provider-openai-responses": "0.48.0"
+		"@vincemakes/kiso-provider-anthropic": "0.50.0",
+		"@vincemakes/kiso-provider-openai": "0.50.0",
+		"@vincemakes/kiso-provider-openai-responses": "0.50.0"
 	},
 	"peerDependenciesMeta": {
 		"@vincemakes/kiso-provider-anthropic": {
@@ -44,7 +44,7 @@
 		}
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.48.0",
+		"@vincemakes/kiso-evals": "0.50.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"