pi-umbra-subagents 0.1.0

package/extensions/umbra-subagents/skills/delegate/beacon.ts

@@ -0,0 +1,210 @@
+// The only thing a headless `pi -p` branch says about itself while it is still running.
+// The delegate skill and the fan extension both seed one JSON file per branch before
+// launching it, hand the path over in PI_BRANCH_STATE, and load this file with `-e`; from
+// that moment this is the file's sole writer. It exists because a branch's report lands only
+// when the branch is over, and the panel needs a sentence a great deal earlier than that.
+//
+// It is never auto-loaded: it lives in the skill folder, not in ~/.pi/agent/extensions/, so
+// the interactive session's extension set is byte-identical with and without it. Nothing
+// here registers a tool, which is what makes the whole feature cost zero prompt tokens.
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BranchState } from "./state.ts";
+
+// A regex would let a runaway pattern eat the whole row; these two caps keep the column
+// width predictable without truncating the part that identifies the file.
+const ARG_W = 32;
+const LINE_W = 72;
+// Tool events arrive in bursts — two `start`s and an `end` inside one animation frame is
+// ordinary — and each write is a tmp file plus a rename. Coalescing to one write per 100 ms
+// stays well under the panel's own tick, so nothing is ever late on screen.
+const WRITE_MS = 100;
+
+const cut = (text: string, width: number) => (text.length <= width ? text : `${text.slice(0, width - 1)}…`);
+
+const str = (value: unknown): string => (typeof value === "string" ? value.trim() : "");
+
+const file = (value: unknown): string => {
+    const path = str(value);
+    // basename handles both separators on win32, so a branch may hand back either.
+    return path ? basename(path) : "";
+};
+
+// Where a tool puts the thing it is working on, most specific first. It is what lets an
+// unknown tool — a provider extension's, a future built-in — still name its subject instead
+// of rendering as a bare noun in the middle column.
+const SUBJECT_KEYS = ["path", "file_path", "file", "filename", "command", "pattern", "query", "url", "name", "text", "message"];
+
+const subject = (args: Record<string, unknown>): string => {
+    for (const key of SUBJECT_KEYS) {
+        const value = args[key];
+        const shown = typeof value === "number" && Number.isFinite(value) ? String(value) : str(value);
+        // A value that looks like a path is shown as its basename: the directory part is the
+        // half of it nobody can read in a 30-column column.
+        if (shown) return /[\\/]/.test(shown) ? basename(shown) : shown;
+    }
+    return "";
+};
+
+/** The reference screen's middle column: present tense, names the thing, no status enums.
+ *  A flat switch rather than a table because it is what someone reads at 3am, and because
+ *  every arm needs a different field off `args`. An unknown tool falls through to the generic
+ *  subject, and a tool that was handed nothing readable falls back to its own name. */
+export const describe = (toolName: string, args: unknown): string => {
+    // SAFETY: pi validated `args` against the tool's own schema before firing the event, so
+    // every field read below is either the declared type or absent; str()/file() treat
+    // absent and wrong-typed identically.
+    const a = (args ?? {}) as Record<string, unknown>;
+    const say = (sentence: string, subj: string) => (subj ? cut(sentence, LINE_W) : toolName);
+
+    switch (toolName) {
+        case "read":
+            return say(`Reading ${file(a.path)}`, file(a.path));
+        case "grep": {
+            const pattern = cut(str(a.pattern), ARG_W);
+            const where = file(a.path) || str(a.glob);
+            return say(where ? `Grepping ${pattern} in ${where}` : `Grepping ${pattern}`, pattern);
+        }
+        case "find":
+            return say(`Finding ${cut(str(a.pattern), ARG_W)}`, str(a.pattern));
+        case "ls":
+            return say(`Listing ${cut(str(a.path) || ".", ARG_W)}`, str(a.path) || ".");
+        case "bash": {
+            // The first token is the command; the rest is flags nobody reads in a 30-column
+            // column.
+            const command = str(a.command).split(/\s+/)[0] ?? "";
+            return say(`Running ${cut(command, ARG_W)}`, command);
+        }
+        default: {
+            const what = subject(a);
+            return what ? cut(`${toolName} ${cut(what, ARG_W)}`, LINE_W) : toolName;
+        }
+    }
+};
+
+const textOf = (message: AssistantMessage): string =>
+    message.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+
+export default function (pi: ExtensionAPI) {
+    const path = process.env.PI_BRANCH_STATE;
+    // Not a delegate branch. This is also what makes a stray `-e beacon.ts` on any other
+    // command line completely inert.
+    if (!path) return;
+
+    let state: BranchState;
+    try {
+        // Read once. Re-reading later would mean racing the panel's poll for nothing: from
+        // here on this process is the file's only writer.
+        // SAFETY: the seed is written by run.sh's heredoc or by the fan extension from
+        // constrained identifiers, so it parses to BranchState or the branch is misconfigured,
+        // which the catch handles by going silent rather than by killing the branch.
+        state = JSON.parse(readFileSync(path, "utf8")) as BranchState;
+    } catch {
+        return;
+    }
+
+    // Whole object every time, through tmp + rename, which is atomic on NTFS and POSIX alike.
+    // That is what lets the panel poll without ever parsing a half-written row.
+    let queued: ReturnType<typeof setTimeout> | undefined;
+    const flush = () => {
+        queued = undefined;
+        try {
+            writeFileSync(`${path}.tmp`, JSON.stringify(state));
+            renameSync(`${path}.tmp`, path);
+        } catch {
+            // A branch must never die because the panel's scratch file could not be written.
+        }
+    };
+
+    /** `soon` for anything the next event would overwrite anyway; the default writes now,
+     *  because a state the branch is about to exit on has no next event to ride along with. */
+    const write = (patch: Partial<BranchState>, soon = false) => {
+        state = { ...state, ...patch, updatedAt: Date.now() };
+        if (!soon) {
+            clearTimeout(queued);
+            flush();
+            return;
+        }
+        if (queued) return;
+        queued = setTimeout(flush, WRITE_MS);
+        // A queued write must never be the reason the branch's process stays alive.
+        queued.unref?.();
+    };
+
+    // One entry per tool call in flight, keyed on the call id pi hands out. A branch runs
+    // tools concurrently, and clearing the sentence on the first `end` would leave the row
+    // reading "Thinking" while the other call is still mid-grep. `.at(-1)` is the newest,
+    // because the sentence people want is the thing that just started.
+    const active = new Map<string, string>();
+    const sentence = () => [...active.values()].at(-1) ?? "Thinking";
+
+    pi.on("session_start", (_event, ctx) => {
+        // process.pid from inside pi's own process, because `$!` under Git Bash is an MSYS
+        // pid that the panel's process.kill would aim at something unrelated.
+        write({ pid: process.pid, model: ctx.model?.name ?? state.model, status: "running", activity: "Thinking" });
+    });
+
+    pi.on("tool_execution_start", (event) => {
+        active.set(event.toolCallId || event.toolName, describe(event.toolName, event.args));
+        write({ activity: sentence() }, true);
+    });
+
+    // Deliberately NOT tool_execution_update: it fires per streamed chunk, which would be a
+    // disk write per token.
+    pi.on("tool_execution_end", (event) => {
+        active.delete(event.toolCallId || event.toolName);
+        write({ activity: sentence() }, true);
+    });
+
+    pi.on("message_end", (event, ctx) => {
+        if (event.message.role !== "assistant") return;
+        // SAFETY: role === "assistant" is the discriminant of the AgentMessage union.
+        const message = event.message as AssistantMessage;
+        // getContextUsage is the figure pi's own status line shows, but it returns null right
+        // after a compaction; the message's own total is always there to fall back on.
+        const tokens = ctx.getContextUsage()?.tokens ?? message.usage.totalTokens;
+        // A provider that reports usage only at completion sends 0 for a while. Keeping the
+        // last real value stops the panel's token column from blinking back to nothing.
+        write({
+            tokens: tokens > 0 ? tokens : state.tokens,
+            // A tool call outlives the message that asked for it, so the sentence wins over
+            // the generic line whenever one is still running.
+            activity: active.size ? sentence() : "Writing the report",
+        });
+    });
+
+    pi.on("agent_end", (event) => {
+        const last = [...event.messages].reverse().find((message) => message.role === "assistant");
+        // SAFETY: same discriminant as above; `last` is undefined only if the loop produced no
+        // assistant message at all, which the ?? covers.
+        const message = last as AssistantMessage | undefined;
+        // The delegate report contract, preserved verbatim: the trailing STATUS line is the
+        // whole reason the parent session reads the .md at all.
+        const text = message ? textOf(message) : "";
+        const match = /^STATUS:\s*(OK|PARTIAL|NEED_STRONGER|ASKING)/m.exec(text);
+        // SAFETY: the alternation in the regex is exactly BranchState["report"] minus null.
+        const report = (match?.[1] ?? null) as BranchState["report"];
+        // The row is where a waiting question gets noticed, so it shows the question itself.
+        const question = str(/^QUESTION:\s*(.+)$/m.exec(text)?.[1]);
+        const failed = message?.stopReason === "error";
+        active.clear();
+        write({
+            status: failed ? "error" : "done",
+            report,
+            error: failed ? (message?.errorMessage ?? "the branch stopped with an error") : null,
+            activity: failed
+                ? "Failed"
+                : report === "ASKING"
+                  ? cut(`Asking: ${question || "see report"}`, LINE_W)
+                  : report
+                    ? `Reported ${report}`
+                    : "Finished",
+        });
+    });
+}

package/extensions/umbra-subagents/skills/delegate/delegate.env

@@ -0,0 +1,12 @@
+# Defaults for the branches. Override any of them in ~/.pi/agent/delegate.env, which run.sh
+# reads after this file.
+#
+# FAST is the model a branch runs on unless the task names another. The default is this
+# session's own model, which pi puts in the environment of every bash call.
+FAST=${FAST:-${PI_PROVIDER:+$PI_PROVIDER/${PI_MODEL-}}}
+# Seconds before a branch that is still running is cut off.
+DELEGATE_TIMEOUT=${DELEGATE_TIMEOUT:-300}
+# Extensions every branch loads. Branches start with --no-extensions, so a provider that
+# comes from an extension (claude-bridge, antigravity...) has to be listed here, e.g.
+# LOAD="-e $HOME/.pi/agent/npm/node_modules/pi-claude-bridge"
+LOAD=${LOAD:-}

package/extensions/umbra-subagents/skills/delegate/report.md

@@ -0,0 +1,15 @@
+Your final message is the only thing the caller reads. Write it in exactly this shape and nothing else:
+
+STATUS: OK
+SUMMARY: the answer, at most 5 lines
+FILES: one path per line that the answer relies on, or "none"
+
+STATUS is OK, PARTIAL (answered part of it), NEED_STRONGER (cannot be answered from reading alone), or ASKING. When in doubt, PARTIAL beats a guess.
+
+ASKING is for a decision only the caller can make, not for anything you can find by reading. Stop at once and end with exactly:
+
+STATUS: ASKING
+QUESTION: one question, answerable in a line
+OPTIONS: the choices you see, separated by " | ", recommended first
+
+Your session is kept; the answer arrives as your next message and you carry on from where you stopped.

package/extensions/umbra-subagents/skills/delegate/run.check.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Proves the bash half without ever starting pi. A stub stands in for the binary, records the
+# argv and the environment it was handed, and exits the way its task text asks; then every
+# file the skill claims to write is checked for being real JSON with the right contents.
+#
+# Run it with:  bash run.check.sh
+set -u
+
+skill=$(cd "$(dirname "$0")" && pwd)
+work=$(mktemp -d)
+cd "$work" || exit 1
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+cat > fake-pi <<'STUB'
+#!/usr/bin/env bash
+# Ignores every flag; the task is the last argument and decides how this branch ends.
+for arg in "$@"; do task=$arg; done
+printf '%s\n' "$PI_BRANCH_STATE" "$*" >> "$RECORD"
+[ "$task" = boom ] && exit 3
+[ "$task" = slow ] && exit 124
+printf 'STATUS: OK\nSUMMARY: fake\nFILES: none\n'
+STUB
+chmod +x fake-pi
+
+desc='A description with "quotes", a \ backslash
+and a newline'
+
+PI=$work/fake-pi
+delegate_skill=$skill
+export RECORD=$work/argv.log
+. "$skill/run.sh"
+
+dstart check "$desc" map design || fail "dstart"
+branch map core-render "$FAST" ok || fail "first branch"
+branch map broken "$FAST" boom || fail "second branch"
+branch map slow "$FAST" slow || fail "third branch"
+branch design review "$FAST" ok || fail "fourth branch"
+branch map core-render "$FAST" again 2>/dev/null && fail "duplicate branch name was accepted"
+dwait
+
+[ -f "$run/run.json" ] || fail "run.json missing"
+node -e 'const fs=require("fs");for(const p of process.argv.slice(1))JSON.parse(fs.readFileSync(p,"utf8"))' \
+    "$run/run.json" "$run"/state/*.json || fail "a seed or run.json is not valid JSON"
+
+node -e '
+const fs = require("fs");
+const run = JSON.parse(fs.readFileSync(process.argv[1] + "/run.json", "utf8"));
+const want = process.argv[2].replace(/[\n\r\t]/g, "");
+if (run.description !== want) throw new Error("description mangled: " + JSON.stringify(run.description));
+if (run.phases.join(",") !== "map,design") throw new Error("phases: " + run.phases);
+if (!/^\d+$/.test(String(run.startedAt))) throw new Error("startedAt: " + run.startedAt);
+const seed = (stem) => JSON.parse(fs.readFileSync(process.argv[1] + "/state/" + stem + ".json", "utf8"));
+const order = ["map-core-render", "map-broken", "map-slow", "design-review"];
+order.forEach((stem, i) => {
+    const s = seed(stem);
+    if (s.index !== i + 1) throw new Error(stem + " index " + s.index + ", expected " + (i + 1));
+    if (s.status !== "starting" || s.pid !== null || s.tokens !== null || s.parent !== null) throw new Error(stem + " seed fields");
+    if (s.activity !== "Starting") throw new Error(stem + " activity");
+});
+' "$run" "$desc" || fail "run.json or a seed has the wrong contents"
+
+for pair in map-core-render:0 map-broken:3 map-slow:124 design-review:0; do
+    stem=${pair%%:*}; want=${pair##*:}
+    got=$(cat "$run/state/$stem.exit" 2>/dev/null)
+    [ "$got" = "$want" ] || fail "$stem exited $got, expected $want"
+done
+
+# The failure this guards is silent from the panel's side: a branch launched without the
+# beacon writes nothing and sits at "starting" until it exits.
+grep -q -- "-e .*beacon\.ts" "$RECORD" || fail "the beacon was not passed to the branch"
+grep -q -- "--session-dir .*/sessions/map-core-render" "$RECORD" || fail "the branch session is not kept per branch"
+grep -q -- "--tools read,grep,find,ls" "$RECORD" || fail "the read-only tool list was dropped"
+grep -q "map-core-render\.json" "$RECORD" || fail "PI_BRANCH_STATE did not reach the branch"
+[ "$(grep -c "state" "$RECORD")" -ge 4 ] || fail "a branch ran without a state path"
+
+# A branch that fans out again: same environment run.sh hands its children, in a subshell so
+# the outer run's variables are untouched. It must join the run above it rather than start a
+# rival one, or the panel draws two runs and nests neither.
+parent_run=$run
+(
+    export PI_BRANCH_RUN="$parent_run" PI_BRANCH_PARENT="map-core-render" PI_BRANCH_PHASE="map"
+    . "$skill/run.sh"
+    dstart nested "a nested run" other || exit 1
+    [ "$run" = "$parent_run" ] || exit 2
+    branch design child "$FAST" ok || exit 3
+    dwait
+) || fail "the nested run did not join its parent (code $?)"
+
+[ -f "$run/state/map-child.json" ] || fail "the nested branch did not land in its parent's phase"
+node -e '
+const fs = require("fs");
+const child = JSON.parse(fs.readFileSync(process.argv[1] + "/state/map-child.json", "utf8"));
+if (child.parent !== "map-core-render") throw new Error("parent link: " + child.parent);
+if (child.phase !== "map") throw new Error("phase: " + child.phase);
+const run = JSON.parse(fs.readFileSync(process.argv[1] + "/run.json", "utf8"));
+if (run.name !== "check") throw new Error("a nested run overwrote run.json: " + run.name);
+' "$run" || fail "the nested branch is not nested under its parent"
+
+# A finished branch continued with an answer: same state file, same session dir, --continue,
+# the answer as the message, and a fresh exit code. A beacon-written row is what dresume resets.
+node -e '
+const fs = require("fs"); const p = process.argv[1] + "/state/map-broken.json";
+const s = JSON.parse(fs.readFileSync(p, "utf8"));
+fs.writeFileSync(p, JSON.stringify({ ...s, pid: 4242, status: "done", report: "ASKING", activity: "Asking: \"which\" one?" }));
+' "$run"
+dresume "$run" map-broken "use the second" || fail "dresume refused a finished branch"
+wait
+node -e '
+const s = JSON.parse(require("fs").readFileSync(process.argv[1] + "/state/map-broken.json", "utf8"));
+if (s.status !== "starting" || s.pid !== null || s.report !== null || s.activity !== "Resuming") throw new Error(JSON.stringify(s));
+' "$run" || fail "dresume did not reset the row"
+[ "$(cat "$run/state/map-broken.exit")" = 0 ] || fail "dresume did not write a new exit code"
+grep -q -- "--session-dir .*/sessions/map-broken --continue" "$RECORD" || fail "dresume did not continue the branch session"
+grep -q -- "-- use the second$" "$RECORD" || fail "dresume did not pass the answer as the message"
+grep -q "^STATUS: OK" "$run/map-broken.md" || fail "dresume did not write the new report"
+dresume "$run" nope "x" 2>/dev/null && fail "dresume accepted an unknown branch"
+
+rm -rf "$work"
+echo "run.check.sh ok"

package/extensions/umbra-subagents/skills/delegate/run.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# The mechanical half of the delegate skill: seed one state file per branch BEFORE the
+# process exists, then launch that branch with the beacon attached to it.
+#
+# It is a sourced file rather than a block pasted into SKILL.md for two reasons. PI_BRANCH_STATE
+# and `-e beacon.ts` have to travel together — a caller who copies one and forgets the other
+# gets a run where every row sits at "starting" forever — and the check drives exactly the
+# code the skill runs instead of a copy of it that drifts.
+#
+# Usage, from the SESSION cwd, before any `cd`:
+#   . <this skill's directory>/run.sh
+#   dstart <slug> "<one-line description>" <phase>...
+#   branch <phase> <name> <model> "<task>"      # repeat, 2 to 6 per run
+#   dwait                                       # writes run.json, then waits
+
+# The directory this file is in, wherever the skill was installed. A caller may still set it.
+delegate_skill=${delegate_skill:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}
+
+# The packaged defaults, then the owner's own settings, which win: $FAST, $LOAD and
+# $DELEGATE_TIMEOUT belong to the machine, not to the skill.
+dconfig() {
+    . "$delegate_skill/delegate.env"
+    local own="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/delegate.env"
+    [ -f "$own" ] && . "$own"
+    return 0
+}
+# Only the check ever overrides this; it swaps in a stub so the whole block can run without pi.
+PI=${PI:-pi}
+
+# MSYS rewrites path-looking *arguments* on the way into a native Windows exe but never
+# rewrites environment variables, so PI_BRANCH_STATE would reach node as "/c/Users/..." and
+# fail every read. cygpath -m gives "C:/Users/..." instead. Absent off Windows, hence the
+# fallback.
+native() {
+    if command -v cygpath >/dev/null 2>&1; then cygpath -m "$1"; else printf '%s' "$1"; fi
+}
+
+# `timeout <seconds> cmd...`. Stock macOS has no timeout (Homebrew coreutils names it
+# gtimeout); with neither, the branch runs without the cap rather than not at all.
+dtimeout() {
+    if command -v timeout >/dev/null 2>&1; then timeout "$@"
+    elif command -v gtimeout >/dev/null 2>&1; then gtimeout "$@"
+    else shift; "$@"; fi
+}
+
+# The pid the panel checks for liveness. Under Git Bash $$ is an MSYS pid, which the Windows
+# process table knows nothing about; /proc/<pid>/winpid holds the real one there.
+dpid() {
+    cat "/proc/$$/winpid" 2>/dev/null || printf '%s' "$$"
+}
+
+# The only free text in either file. Both name and description come from the model, so they
+# are escaped rather than trusted; every other field is a constrained identifier or a number.
+json() {
+    printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\n\r\t'
+}
+
+dstart() {   # slug  description  phase...
+    d_slug=$1
+    d_desc=$2
+    shift 2
+    d_phases=$(printf ',"%s"' "$@")
+    d_phases="[${d_phases:1}]"
+    # $PWD before the skill cd's anywhere: the panel watches the session cwd, so a run
+    # computed after the cd would land in a directory nobody is looking at.
+    d_cwd=$PWD
+    # A branch that fans out again JOINS its parent's run instead of starting a rival one:
+    # same directory, same state dir, same reader. That is the whole of the panel's `└`
+    # nesting, and PI_BRANCH_RUN is exported to every child below, so it is set exactly when
+    # this shell is running inside a branch.
+    run=${PI_BRANCH_RUN:-"$PWD/.pi-out/$(date +%Y%m%d-%H%M%S)-$d_slug"}
+    d_nested=${PI_BRANCH_RUN:+1}
+    d_started=$(( $(date +%s) * 1000 ))
+    d_index=0
+    mkdir -p "$run/state" || return 1
+    contract=$(cat "$delegate_skill/report.md")
+    dconfig
+}
+
+branch() {   # phase  name  model  task
+    # Inside a nested run the phase is the parent's: the sidebar lists the phases the
+    # top-level run declared, and a child's work belongs to the phase its parent is in.
+    local phase=${PI_BRANCH_PHASE:-$1}
+    local stem="$phase-$2"
+    local file="$run/state/$stem.json"
+    # Two branches sharing a name would share a state file, and a file with two writers is the
+    # one corruption this design cannot detect. A duplicate name is a caller bug, so it is
+    # refused rather than auto-renamed.
+    [ -e "$file" ] && { echo "delegate: duplicate branch $stem" >&2; return 1; }
+    d_index=$(( d_index + 1 ))
+    local parent=null
+    [ -n "${PI_BRANCH_PARENT:-}" ] && parent="\"$PI_BRANCH_PARENT\""
+    local now=$(( $(date +%s) * 1000 ))
+    # Every field is populated here, so no column appears for the first time three seconds in
+    # and reflows the row.
+    cat > "$file" <<JSON
+{"phase":"$phase","name":"$2","parent":$parent,"index":$d_index,"model":"$3","pid":null,
+"status":"starting","activity":"Starting","tokens":null,
+"startedAt":$now,"updatedAt":$now,"report":null,"error":null}
+JSON
+    # $LOAD is deliberately unquoted: it carries an `-e <path>` pair that has to word-split.
+    # PI_BRANCH_PARENT, PI_BRANCH_RUN and PI_BRANCH_PHASE are set for the CHILD, so a branch
+    # given `bash` that sources this file again lands in this run directory, under this row.
+    # PI_BRANCH_RUN stays an MSYS path: its only reader is bash inside the branch.
+    # stdin is /dev/null because `pi -p` waits on an open stdin pipe until it closes.
+    ( PI_BRANCH_STATE=$(native "$file") PI_BRANCH_PARENT="$stem" \
+        PI_BRANCH_RUN="$run" PI_BRANCH_PHASE="$phase" \
+        dtimeout "${DELEGATE_TIMEOUT:-300}" "$PI" -p --session-dir "$(native "$run/sessions/$stem")" --no-skills --no-extensions $LOAD \
+            -e "$(native "$delegate_skill/beacon.ts")" \
+            --tools "${DELEGATE_TOOLS:-read,grep,find,ls}" --model "$3" --append-system-prompt "$contract" "$4" \
+            < /dev/null > "$run/$stem.md" 2> "$run/$stem.err"
+      # The one signal that survives a branch dying before its extensions ever bound, and the
+      # only place a `timeout` (124) can be told apart from a crash.
+      printf '%s' "$?" > "$run/state/$stem.exit" ) &
+
+    # After the seed, so the directory is never half-built when the panel first reads it.
+    write_run_json
+}
+
+# The panel treats a missing run.json as "no run", so this file is what makes a run visible at
+# all. It is written after the first seed exists — never before, or a half-built directory
+# would render — and rewritten by every later `branch`, which costs one tiny write and removes
+# the failure this had in real use: a caller who ran `dstart` and `branch` but forgot `dwait`
+# got working reports and a panel that never showed the run, with nothing saying why.
+#
+# A nested run never writes it: the file belongs to the top-level run, and overwriting it would
+# rename the run and drop the phases the sidebar is drawing.
+write_run_json() {
+    [ -n "$d_nested" ] && return 0
+    cat > "$run/run.json" <<JSON
+{"name":"$(json "$d_slug")","description":"$(json "$d_desc")","cwd":"$(json "$(native "$d_cwd")")","startedAt":$d_started,"phases":$d_phases,"pid":$(dpid)}
+JSON
+}
+
+dwait() {
+    write_run_json
+    wait
+}
+
+# A branch that ended on STATUS: ASKING keeps its session under $run/sessions/<stem>, so the
+# answer is simply its next message: `--continue` reopens that session on the same model.
+# Any finished branch can be continued this way, not only an asking one.
+dresume() {   # run  stem  answer
+    run=$1
+    local stem=$2
+    local file="$run/state/$stem.json"
+    [ -f "$file" ] || { echo "delegate: no branch $stem in $run" >&2; return 1; }
+    [ -e "$run/state/$stem.exit" ] || { echo "delegate: $stem is still running" >&2; return 1; }
+    # Joining an existing run: its run.json belongs to whoever started it, so a later dwait in
+    # this shell must not rewrite it.
+    d_nested=${d_nested-1}
+    contract=$(cat "$delegate_skill/report.md")
+    dconfig
+    local phase
+    phase=$(sed -n 's/.*"phase":"\([^"]*\)".*/\1/p' "$file")
+    # Back to a live row before the process exists, the same order the seed uses. The beacon
+    # writes the pid and the rest at session_start.
+    rm "$run/state/$stem.exit"
+    # No `sed -i`: BSD sed reads the -E after it as a backup suffix.
+    sed -E 's/"status":"[a-z]+"/"status":"starting"/; s/"pid":[0-9]+/"pid":null/;
+        s/"report":("[A-Z_]+"|null)/"report":null/; s/"activity":"(\\.|[^"\\])*"/"activity":"Resuming"/' "$file" > "$file.tmp" &&
+        mv "$file.tmp" "$file"
+    ( PI_BRANCH_STATE=$(native "$file") PI_BRANCH_PARENT="$stem" \
+        PI_BRANCH_RUN="$run" PI_BRANCH_PHASE="$phase" \
+        dtimeout "${DELEGATE_TIMEOUT:-300}" "$PI" -p --session-dir "$(native "$run/sessions/$stem")" --continue \
+            --no-skills --no-extensions $LOAD -e "$(native "$delegate_skill/beacon.ts")" \
+            --tools "${DELEGATE_TOOLS:-read,grep,find,ls}" --append-system-prompt "$contract" -- "$3" \
+            < /dev/null > "$run/$stem.md" 2>> "$run/$stem.err"
+      printf '%s' "$?" > "$run/state/$stem.exit" ) &
+}