@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/worktree.js

@@ -0,0 +1,288 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { runGit } from "./git-process.js";
+export function isMissing(error) {
+    return Boolean(error && typeof error === "object" && error.code === "ENOENT");
+}
+export function isWithin(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === "" || (fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+export const WORKTREES_DIRNAME = ".worktrees";
+const BRANCH_NAMESPACE = "pi-subagent";
+const NAME_COMPONENT_LIMIT = 24;
+const NAME_LIMIT = 72;
+export const READABLE_BRANCH_PATTERN = new RegExp(`^${BRANCH_NAMESPACE}/subagent-[a-z0-9](?:[a-z0-9-]{0,${NAME_LIMIT - 2}}[a-z0-9])?-[0-9a-f]{24}$`);
+/** Keep saved opaque names eligible for exact recovery and cleanup. */
+export const OWNED_BRANCH_PATTERN = new RegExp(`${READABLE_BRANCH_PATTERN.source}|^${BRANCH_NAMESPACE}/subagent-[0-9a-f]{24}$`);
+export class WorktreeSetupError extends Error {
+    name = "WorktreeSetupError";
+    worktree;
+    constructor(message, worktree) {
+        super(message);
+        this.worktree = worktree;
+    }
+}
+const sanitizeShortId = (childId) => createHash("sha256").update(childId).digest("hex").slice(0, 24);
+function nameSlug(parts) {
+    return parts.map((part) => part.toLowerCase().replace(/[^a-z0-9]+/g, "-")
+        .slice(0, NAME_COMPONENT_LIMIT).replace(/^-+|-+$/g, "") || "task")
+        .join("-").slice(0, NAME_LIMIT).replace(/-+$/, "") || "task";
+}
+const stripGitLineEnd = (value) => value.replace(/\r?\n$/, "");
+function hasRepositoryMarker(cwd) {
+    for (let directory = resolve(cwd);; directory = dirname(directory)) {
+        try {
+            lstatSync(join(directory, ".git"));
+            return true;
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || !["ENOENT", "ENOTDIR"].includes(String(error.code)))
+                return true;
+        }
+        if (dirname(directory) === directory)
+            return false;
+    }
+}
+/** Keeps ".worktrees/" out of git status via the common repository's exclude file; never dirties any checkout. */
+async function ensureLocalExclude(gitDir) {
+    const entry = `/${WORKTREES_DIRNAME}/`;
+    const exclude = join(gitDir, "info", "exclude");
+    try {
+        await mkdir(join(gitDir, "info"), { recursive: true });
+        let existing = "";
+        try {
+            existing = await readFile(exclude, "utf8");
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT")
+                throw error;
+        }
+        if (existing.split("\n").some((line) => line.trim() === entry))
+            return;
+        await appendFile(exclude, `${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`);
+    }
+    catch (error) {
+        throw new Error(`Could not update ${exclude}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Creates one worktree per child from parent HEAD. Returns undefined only when
+ * the workspace is not a git repository or HEAD is unborn — callers degrade
+ * silently to the shared working directory. Setup failures in a real git
+ * repository (unwritable path, stale branch, git lock) throw so an isolated
+ * role never silently loses its isolation.
+ */
+export async function createChildWorktree(cwd, childId, run = runGit, signal, onPrepared, nameParts = [childId]) {
+    const root = await run(["rev-parse", "--show-toplevel"], cwd, signal);
+    signal?.throwIfAborted();
+    if (root.code === -1)
+        throw new Error(`git rev-parse failed (${root.stderr.trim().slice(0, 200)})`);
+    if (root.code !== 0) {
+        signal?.throwIfAborted();
+        const repository = await run(["-c", "safe.directory=*", "rev-parse", "--show-toplevel"], cwd, signal);
+        signal?.throwIfAborted();
+        if (repository.code === -1)
+            throw new Error(`git rev-parse failed (${repository.stderr.trim().slice(0, 200)})`);
+        if (repository.code !== 0 && !hasRepositoryMarker(cwd) && !process.env.GIT_DIR && !process.env.GIT_WORK_TREE)
+            return undefined;
+        throw new Error(`git rev-parse failed (${root.stderr.trim().slice(0, 200)})`); // dubious ownership, timeout, …
+    }
+    const repoRoot = stripGitLineEnd(root.stdout);
+    if (!repoRoot)
+        return undefined;
+    const prefix = await run(["rev-parse", "--show-prefix"], cwd, signal);
+    if (prefix.code !== 0)
+        throw new Error(`git rev-parse --show-prefix failed (${prefix.stderr.trim().slice(0, 200)})`);
+    const relativeCwd = stripGitLineEnd(prefix.stdout);
+    const base = await run(["rev-parse", "HEAD"], repoRoot, signal);
+    signal?.throwIfAborted();
+    if (base.code === -1)
+        throw new Error(`git rev-parse HEAD failed (${base.stderr.trim().slice(0, 200)})`);
+    if (base.code !== 0) {
+        signal?.throwIfAborted();
+        const head = await run(["symbolic-ref", "--quiet", "HEAD"], repoRoot, signal);
+        signal?.throwIfAborted();
+        const reference = stripGitLineEnd(head.stdout);
+        if (head.code === 0 && reference) {
+            const exists = await run(["show-ref", "--verify", "--quiet", reference], repoRoot, signal);
+            signal?.throwIfAborted();
+            if (exists.code === 1)
+                return undefined; // unborn HEAD
+        }
+        throw new Error(`git rev-parse HEAD failed (${base.stderr.trim().slice(0, 200)})`);
+    }
+    const baseCommit = base.stdout.trim();
+    const superproject = await run(["rev-parse", "--show-superproject-working-tree"], repoRoot, signal);
+    if (superproject.code !== 0) {
+        throw new Error(`git rev-parse --show-superproject-working-tree failed (${superproject.stderr.trim().slice(0, 200)})`);
+    }
+    if (stripGitLineEnd(superproject.stdout)) {
+        throw new Error("Worktree isolation is unavailable inside Git submodules because parent cleanup can remove their Git metadata.");
+    }
+    const common = await run(["rev-parse", "--git-common-dir"], repoRoot, signal);
+    const rawCommonGitDir = stripGitLineEnd(common.stdout);
+    if (common.code !== 0 || !rawCommonGitDir) {
+        throw new Error(`git rev-parse --git-common-dir failed (${common.stderr.trim().slice(0, 200)})`);
+    }
+    const current = await run(["rev-parse", "--git-dir"], repoRoot, signal);
+    const rawCurrentGitDir = stripGitLineEnd(current.stdout);
+    if (current.code !== 0 || !rawCurrentGitDir) {
+        throw new Error(`git rev-parse --git-dir failed (${current.stderr.trim().slice(0, 200)})`);
+    }
+    const gitDir = isAbsolute(rawCommonGitDir) ? rawCommonGitDir : join(repoRoot, rawCommonGitDir);
+    const currentGitDir = isAbsolute(rawCurrentGitDir) ? rawCurrentGitDir : join(repoRoot, rawCurrentGitDir);
+    let stableRepoRoot = repoRoot;
+    if (currentGitDir !== gitDir) {
+        const worktrees = await run(["worktree", "list", "--porcelain", "-z"], repoRoot, signal);
+        const primary = worktrees.stdout.split("\0", 1)[0];
+        if (worktrees.code !== 0 || !primary?.startsWith("worktree ") || primary.length === "worktree ".length) {
+            throw new Error(`git worktree list failed (${worktrees.stderr.trim().slice(0, 200)})`);
+        }
+        stableRepoRoot = primary.slice("worktree ".length);
+    }
+    signal?.throwIfAborted();
+    const worktreesRoot = join(stableRepoRoot, WORKTREES_DIRNAME);
+    const name = `subagent-${nameSlug(nameParts)}-${sanitizeShortId(childId)}`;
+    const branch = `${BRANCH_NAMESPACE}/${name}`;
+    const path = join(worktreesRoot, name);
+    const worktree = { path, cwd: join(path, relativeCwd), branch, repoRoot: stableRepoRoot, baseCommit };
+    if (onPrepared)
+        await onPrepared(worktree);
+    signal?.throwIfAborted();
+    try {
+        await mkdir(worktreesRoot, { recursive: true });
+    }
+    catch (error) {
+        throw new Error(`Could not create ${worktreesRoot}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    await ensureLocalExclude(gitDir);
+    signal?.throwIfAborted();
+    const added = await run(["worktree", "add", path, "-b", branch, baseCommit], repoRoot, signal);
+    if (added.code !== 0) {
+        throw new WorktreeSetupError(`git worktree add failed after attempting path=${JSON.stringify(path)} branch=${JSON.stringify(branch)} base=${baseCommit}: ${added.stderr.trim().slice(0, 200)}`, worktree);
+    }
+    return worktree;
+}
+/** Records only measurements that completed before recovery became necessary. */
+function recoveryPayload(info, reason, measurements = {}, action = `Inspect ${info.path} (branch ${info.branch}) before assuming no work.`) {
+    const unknown = [
+        ...(measurements.commits === undefined ? ["commits"] : []),
+        ...(measurements.dirty === undefined ? ["dirty"] : []),
+    ].join("/");
+    return {
+        outcome: "recovery",
+        path: info.path,
+        branch: info.branch,
+        ...(measurements.commits === undefined ? {} : { commits: measurements.commits }),
+        ...(measurements.dirty === undefined ? {} : { dirty: measurements.dirty }),
+        note: `Worktree recovery required (${reason})${unknown ? `: ${unknown} UNKNOWN` : ""}. ${action}`,
+    };
+}
+export async function inspectIndexFlags(cwd, run = runGit, signal) {
+    const flags = await run(["ls-files", "-v", "-z"], cwd, signal);
+    if (flags.code !== 0)
+        return { hidden: false, failure: `ls-files exit ${flags.code}: ${flags.stderr.trim().slice(0, 200)}` };
+    return { hidden: flags.stdout.split("\0").some((entry) => /^(?:[a-z]|S) /.test(entry)) };
+}
+async function inspectDirty(run, cwd, includeIgnored = true) {
+    const refreshed = await run(["update-index", "--really-refresh"], cwd);
+    if (refreshed.code !== 0 && refreshed.code !== 1) {
+        return { dirty: false, failure: `update-index exit ${refreshed.code}: ${refreshed.stderr.trim().slice(0, 200)}` };
+    }
+    const status = await run(["status", "--porcelain", "--untracked-files=all", ...(includeIgnored ? ["--ignored=matching"] : []), "--ignore-submodules=none"], cwd);
+    if (status.code !== 0)
+        return { dirty: false, failure: `status exit ${status.code}: ${status.stderr.trim().slice(0, 200)}` };
+    if (refreshed.code === 1 || status.stdout.trim())
+        return { dirty: true };
+    const flags = await inspectIndexFlags(cwd, run);
+    if (flags.failure)
+        return { dirty: false, failure: flags.failure };
+    if (flags.hidden)
+        return { dirty: false, failure: "assume-unchanged or skip-worktree index entries remain" };
+    return { dirty: false };
+}
+/** Proves a worktree has no tracked, untracked, index-hidden, or nested submodule work; cleanup also checks ignored files. */
+export async function inspectWorktreeDirty(cwd, run = runGit, includeIgnored = true) {
+    const root = await inspectDirty(run, cwd, includeIgnored);
+    if (root.dirty || root.failure)
+        return root;
+    const modules = await run(["submodule", "status", "--recursive"], cwd);
+    if (modules.code !== 0)
+        return { dirty: false, failure: `submodule list exit ${modules.code}: ${modules.stderr.trim().slice(0, 200)}` };
+    const initializedSubmodules = modules.stdout.split("\n").some((line) => line && !line.startsWith("-"));
+    if (initializedSubmodules) {
+        const listed = await run(["submodule", "foreach", "--recursive", "--quiet", "printf '%s\\0' \"$PWD\""], cwd);
+        if (listed.code !== 0)
+            return { dirty: false, failure: `submodule list exit ${listed.code}: ${listed.stderr.trim().slice(0, 200)}` };
+        const paths = listed.stdout.split("\0").filter(Boolean);
+        if (!paths.length)
+            return { dirty: false, failure: "initialized submodule paths unavailable" };
+        for (const path of paths) {
+            const nested = await inspectDirty(run, path, includeIgnored);
+            if (nested.failure)
+                return { dirty: false, failure: `submodule ${path}: ${nested.failure}` };
+            if (nested.dirty)
+                return { dirty: true };
+        }
+    }
+    const rechecked = await inspectDirty(run, cwd, includeIgnored);
+    return initializedSubmodules ? { ...rechecked, initializedSubmodules } : rechecked;
+}
+/**
+ * Inspects and possibly prunes a child worktree after it finishes. Commit count
+ * reads the dedicated branch and refuses to prune when checkout HEAD no longer
+ * names it; the clean-tree proof includes untracked, ignored, and submodule
+ * changes despite repository config. A worktree with zero branch commits and a
+ * clean tree is removed only when every probe succeeds and base_commit was
+ * recorded; any uncertainty preserves work and omits unknown measurements.
+ */
+export async function finalizeChildWorktree(info, run = runGit) {
+    const checkoutExists = existsSync(info.path);
+    const gitCwd = checkoutExists ? info.path : info.repoRoot || info.path;
+    if (!info.baseCommit)
+        return recoveryPayload(info, "no base_commit recorded — commit count unmeasurable");
+    const counted = await run(["rev-list", "--count", `${info.baseCommit}..${info.branch}`], gitCwd);
+    const commits = Number.parseInt(counted.stdout.trim(), 10);
+    const countFailure = counted.code !== 0
+        ? `rev-list exit ${counted.code}: ${counted.stderr.trim().slice(0, 200)}`
+        : Number.isNaN(commits) ? "rev-list produced non-numeric output" : undefined;
+    const inspection = checkoutExists ? await inspectDirty(run, info.path, true) : undefined;
+    const measurements = {
+        ...(countFailure === undefined ? { commits } : {}),
+        ...(inspection?.failure === undefined && inspection !== undefined ? { dirty: inspection.dirty } : {}),
+    };
+    if (countFailure || inspection?.failure) {
+        return recoveryPayload(info, [countFailure, inspection?.failure].filter(Boolean).join("; "), measurements);
+    }
+    let forceRemove = false;
+    if (checkoutExists) {
+        const dirty = inspection.dirty;
+        if (commits > 0 || dirty)
+            return { outcome: "retained", path: info.path, branch: info.branch, commits, dirty };
+        const head = await run(["symbolic-ref", "--quiet", "HEAD"], info.path);
+        if (head.code !== 0 || head.stdout.trim() !== `refs/heads/${info.branch}`) {
+            return recoveryPayload(info, "HEAD is detached, switched, or unreadable", measurements);
+        }
+        const rechecked = await inspectWorktreeDirty(info.path, run);
+        if (rechecked.failure)
+            return recoveryPayload(info, `final ${rechecked.failure}`, { commits });
+        if (rechecked.dirty)
+            return { outcome: "retained", path: info.path, branch: info.branch, commits, dirty: true };
+        forceRemove = Boolean(rechecked.initializedSubmodules);
+    }
+    else if (commits > 0) {
+        return recoveryPayload(info, "worktree checkout is missing", { commits });
+    }
+    const cleanupCwd = info.repoRoot || info.path;
+    const removed = await run(["worktree", "remove", ...(forceRemove ? ["--force"] : []), info.path], cleanupCwd);
+    if (removed.code !== 0)
+        return recoveryPayload(info, `worktree remove exit ${removed.code}: ${removed.stderr.trim().slice(0, 200)}`);
+    const deleted = await run(["update-ref", "-d", `refs/heads/${info.branch}`, info.baseCommit], cleanupCwd);
+    if (deleted.code !== 0) {
+        return recoveryPayload(info, `branch delete exit ${deleted.code}: ${deleted.stderr.trim().slice(0, 200)}`, {}, `Inspect branch ${info.branch}; recreate ${info.path} from it before assuming no work.`);
+    }
+    return { outcome: "pruned", path: info.path, branch: info.branch };
+}

package/docs/orchestration-architecture.html

@@ -0,0 +1,138 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Pi Subagent isolated workflow</title>
+  <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
+  <style>
+    * { box-sizing: border-box; }
+    body { margin: 0; padding: 32px; background: #f0eee9; color: #101828; font-family: 'Geist', sans-serif; }
+    .frame { width: 100%; max-width: 1280px; margin: auto; }
+    h1 { margin: 0 0 24px; font: 400 28px 'Instrument Serif', serif; }
+    .diagram-scroll { overflow-x: auto; }
+    svg { display: block; width: 100%; min-width: 1280px; height: auto; }
+  </style>
+</head>
+<body>
+  <main class="frame">
+    <h1>Stage ready candidates before all workers finish</h1>
+    <div class="diagram-scroll">
+      <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="orchestration-architecture-title orchestration-architecture-desc">
+        <title id="orchestration-architecture-title">Pi Subagent isolated workflow</title>
+        <desc id="orchestration-architecture-desc">Workers commit checked candidates for Main to stage while siblings run, advance dependent waves, validate the combined tip, and explicitly promote into unchanged clean Main.</desc>
+        <defs>
+          <style>
+            .section { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; letter-spacing: .12em; }
+            .node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
+            .input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
+            .focal { fill: #1d4ed8; fill-opacity: .08; stroke: #1d4ed8; stroke-width: 1.2; }
+            .optional { fill: #101828; fill-opacity: .02; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 4 3; }
+            .tag { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; }
+            .name { fill: #101828; font: 600 12px 'Geist', sans-serif; text-anchor: middle; }
+            .detail { fill: #4c5665; font: 400 12px 'Geist', sans-serif; text-anchor: middle; }
+            .code { fill: #4c5665; font: 400 8px 'Geist Mono', monospace; text-anchor: middle; }
+            .edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#arrow); }
+            .branch { fill: none; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 5 4; marker-end: url(#arrow); }
+            .approved { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#arrow-accent); }
+            .label-mask { fill: #f0eee9; }
+            .label { fill: #4c5665; font: 500 8px 'Geist Mono', monospace; text-anchor: middle; }
+            .note-title { fill: #101828; font: 600 12px 'Geist', sans-serif; }
+            .note { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }
+            .key { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }
+          </style>
+          <marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+            <polygon points="0 0,8 3,0 6" fill="#4c5665"/>
+          </marker>
+          <marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+            <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
+          </marker>
+        </defs>
+        <rect width="1280" height="720" fill="#f0eee9"/>
+        <text class="section" x="40" y="120">CANDIDATE PRODUCTION</text>
+        <text class="section" x="40" y="320">MAIN'S EXPLICIT ACTIONS</text>
+
+        <!-- Draw connectors and their labels before nodes. -->
+        <line class="edge" x1="256" y1="208" x2="304" y2="208"/>
+        <line class="edge" x1="560" y1="208" x2="608" y2="208"/>
+        <line class="edge" x1="880" y1="208" x2="928" y2="208"/>
+        <line class="edge" x1="1064" y1="272" x2="1064" y2="344"/>
+        <line class="edge" x1="928" y1="408" x2="880" y2="408"/>
+        <line class="approved" x1="568" y1="408" x2="472" y2="408"/>
+        <line class="branch" x1="1064" y1="472" x2="1064" y2="520"/>
+        <path class="branch" d="M1200 564 H1224 Q1232 564 1232 556 V96 Q1232 88 1224 88 H440 Q432 88 432 96 V144"/>
+        <rect class="label-mask" x="884" y="388" width="40" height="12" rx="2"/>
+        <text class="label" x="904" y="396">SETTLED</text>
+        <rect class="label-mask" x="500" y="388" width="40" height="12" rx="2"/>
+        <text class="label" x="520" y="396">PASS</text>
+        <rect class="label-mask" x="1072" y="488" width="72" height="12" rx="2"/>
+        <text class="label" x="1108" y="496">DEPENDENTS</text>
+        <rect class="label-mask" x="716" y="68" width="80" height="12" rx="2"/>
+        <text class="label" x="756" y="76">STAGED BASE</text>
+
+        <rect class="input" x="40" y="144" width="216" height="128" rx="6"/>
+        <text class="tag" x="56" y="168">MAIN</text>
+        <text class="name" x="148" y="200">Start isolated request</text>
+        <text class="code" x="148" y="224">delegate_task · mode: isolated</text>
+        <text class="detail" x="148" y="248">Keep the durable request ID.</text>
+
+        <rect class="node" x="304" y="144" width="256" height="128" rx="6"/>
+        <text class="tag" x="320" y="168">WORKERS</text>
+        <text class="name" x="432" y="200">Commit candidates</text>
+        <text class="detail" x="432" y="224">Use owned worktrees.</text>
+        <text class="detail" x="432" y="248">No tracked or untracked changes.</text>
+
+        <rect class="node" x="608" y="144" width="272" height="128" rx="6"/>
+        <text class="tag" x="624" y="168">RUNNER</text>
+        <text class="name" x="744" y="200">Run preliminary checks</text>
+        <text class="detail" x="744" y="224">Include optional task judgment.</text>
+        <text class="detail" x="744" y="248">Bind evidence to the exact candidate.</text>
+
+        <rect class="node" x="928" y="144" width="272" height="128" rx="6"/>
+        <text class="tag" x="944" y="168">RUNNER → MAIN</text>
+        <text class="name" x="1064" y="200">Send ready follow-up</text>
+        <text class="detail" x="1064" y="224">Readiness is not promotion.</text>
+        <text class="code" x="1064" y="248">subagent_status</text>
+
+        <rect class="focal" x="928" y="344" width="272" height="128" rx="6"/>
+        <text class="tag" x="944" y="368">MAIN · INTEGRATION CHECKOUT</text>
+        <text class="name" x="1064" y="400">Stage exact candidates</text>
+        <text class="code" x="1064" y="424">subagent_stage</text>
+        <text class="detail" x="1064" y="448">Stage while siblings run.</text>
+
+        <rect class="node" x="568" y="344" width="312" height="128" rx="6"/>
+        <text class="tag" x="584" y="368">MAIN · AFTER THE WAVE SETTLES</text>
+        <text class="name" x="724" y="400">Validate the exact combined tip</text>
+        <text class="code" x="724" y="424">subagent_integrate validate</text>
+        <text class="detail" x="724" y="448">Final checks and optional final judgment</text>
+
+        <rect class="focal" x="160" y="344" width="312" height="128" rx="6"/>
+        <text class="tag" x="176" y="368">MAIN · EXPLICIT PROMOTION</text>
+        <text class="name" x="316" y="400">Promote passing work</text>
+        <text class="code" x="316" y="424">subagent_integrate promote</text>
+        <text class="detail" x="316" y="448">Main must be unchanged and clean.</text>
+
+        <rect class="optional" x="928" y="520" width="272" height="88" rx="6"/>
+        <text class="name" x="1064" y="544">Advance dependent tasks</text>
+        <text class="code" x="1064" y="564">subagent_integrate advance</text>
+        <text class="detail" x="1064" y="588">Run from the selected staged snapshot.</text>
+
+        <!-- Safety details remain in the README as text. -->
+        <text class="note-title" x="40" y="536">Blocked promotion preserves evidence.</text>
+        <text class="note" x="40" y="560">Failures, conflicts, changed identities, or uncertain</text>
+        <text class="note" x="40" y="580">outcomes require inspection, not replay.</text>
+        <text class="note-title" x="520" y="536">One combined correction</text>
+        <text class="note" x="520" y="560">After a definitive combined check or review failure,</text>
+        <text class="note" x="520" y="580">commit one correction, record it, then validate again.</text>
+
+        <line x1="40" y1="640" x2="1240" y2="640" stroke="#101828" stroke-opacity=".141"/>
+        <line class="edge" x1="40" y1="672" x2="88" y2="672"/>
+        <text class="key" x="104" y="676">Checked sequence</text>
+        <line class="branch" x1="304" y1="672" x2="352" y2="672"/>
+        <text class="key" x="368" y="676">Dependent wave, if needed</text>
+        <text class="key" x="704" y="676">Staging, validation, and promotion require exact, clean Main.</text>
+      </svg>
+    </div>
+  </main>
+</body>
+</html>

package/docs/orchestration-architecture.svg

@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="orchestration-architecture-title orchestration-architecture-desc" id="orchestration-architecture-root">
+        <title id="orchestration-architecture-title">Pi Subagent isolated workflow</title>
+        <desc id="orchestration-architecture-desc">Workers commit checked candidates for Main to stage while siblings run, advance dependent waves, validate the combined tip, and explicitly promote into unchanged clean Main.</desc>
+        <defs>
+      <style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;family=Noto+Serif:ital@0;1&amp;family=Noto+Sans+KR:wght@400;500;600&amp;family=Noto+Serif+KR:wght@400&amp;family=Noto+Sans+TC:wght@400;500;600&amp;family=Noto+Serif+TC:wght@400&amp;display=swap');
+      #orchestration-architecture-root { color: #101828; font-family: 'Geist', sans-serif; }
+      #orchestration-architecture-root .diagram-scroll { overflow-x: auto; }
+      #orchestration-architecture-root .section { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; letter-spacing: .12em; }
+      #orchestration-architecture-root .node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
+      #orchestration-architecture-root .input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
+      #orchestration-architecture-root .focal { fill: #1d4ed8; fill-opacity: .08; stroke: #1d4ed8; stroke-width: 1.2; }
+      #orchestration-architecture-root .optional { fill: #101828; fill-opacity: .02; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 4 3; }
+      #orchestration-architecture-root .tag { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; }
+      #orchestration-architecture-root .name { fill: #101828; font: 600 12px 'Geist', sans-serif; text-anchor: middle; }
+      #orchestration-architecture-root .detail { fill: #4c5665; font: 400 12px 'Geist', sans-serif; text-anchor: middle; }
+      #orchestration-architecture-root .code { fill: #4c5665; font: 400 8px 'Geist Mono', monospace; text-anchor: middle; }
+      #orchestration-architecture-root .edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#orchestration-architecture-arrow); }
+      #orchestration-architecture-root .branch { fill: none; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 5 4; marker-end: url(#orchestration-architecture-arrow); }
+      #orchestration-architecture-root .approved { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#orchestration-architecture-arrow-accent); }
+      #orchestration-architecture-root .label-mask { fill: #f0eee9; }
+      #orchestration-architecture-root .label { fill: #4c5665; font: 500 8px 'Geist Mono', monospace; text-anchor: middle; }
+      #orchestration-architecture-root .note-title { fill: #101828; font: 600 12px 'Geist', sans-serif; }
+      #orchestration-architecture-root .note { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }
+      #orchestration-architecture-root .key { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }</style>
+          <style>
+            .section { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; letter-spacing: .12em; }
+            .node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
+            .input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
+            .focal { fill: #1d4ed8; fill-opacity: .08; stroke: #1d4ed8; stroke-width: 1.2; }
+            .optional { fill: #101828; fill-opacity: .02; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 4 3; }
+            .tag { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; }
+            .name { fill: #101828; font: 600 12px 'Geist', sans-serif; text-anchor: middle; }
+            .detail { fill: #4c5665; font: 400 12px 'Geist', sans-serif; text-anchor: middle; }
+            .code { fill: #4c5665; font: 400 8px 'Geist Mono', monospace; text-anchor: middle; }
+            .edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#orchestration-architecture-arrow); }
+            .branch { fill: none; stroke: #4c5665; stroke-width: 1; stroke-dasharray: 5 4; marker-end: url(#orchestration-architecture-arrow); }
+            .approved { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#orchestration-architecture-arrow-accent); }
+            .label-mask { fill: #f0eee9; }
+            .label { fill: #4c5665; font: 500 8px 'Geist Mono', monospace; text-anchor: middle; }
+            .note-title { fill: #101828; font: 600 12px 'Geist', sans-serif; }
+            .note { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }
+            .key { fill: #4c5665; font: 400 12px 'Geist', sans-serif; }
+          </style>
+          <marker id="orchestration-architecture-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+            <polygon points="0 0,8 3,0 6" fill="#4c5665"/>
+          </marker>
+          <marker id="orchestration-architecture-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+            <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
+          </marker>
+        </defs>
+        <rect width="1280" height="720" fill="#f0eee9"/>
+        <text class="section" x="40" y="120">CANDIDATE PRODUCTION</text>
+        <text class="section" x="40" y="320">MAIN'S EXPLICIT ACTIONS</text>
+
+        <!-- Draw connectors and their labels before nodes. -->
+        <line class="edge" x1="256" y1="208" x2="304" y2="208"/>
+        <line class="edge" x1="560" y1="208" x2="608" y2="208"/>
+        <line class="edge" x1="880" y1="208" x2="928" y2="208"/>
+        <line class="edge" x1="1064" y1="272" x2="1064" y2="344"/>
+        <line class="edge" x1="928" y1="408" x2="880" y2="408"/>
+        <line class="approved" x1="568" y1="408" x2="472" y2="408"/>
+        <line class="branch" x1="1064" y1="472" x2="1064" y2="520"/>
+        <path class="branch" d="M1200 564 H1224 Q1232 564 1232 556 V96 Q1232 88 1224 88 H440 Q432 88 432 96 V144"/>
+        <rect class="label-mask" x="884" y="388" width="40" height="12" rx="2"/>
+        <text class="label" x="904" y="396">SETTLED</text>
+        <rect class="label-mask" x="500" y="388" width="40" height="12" rx="2"/>
+        <text class="label" x="520" y="396">PASS</text>
+        <rect class="label-mask" x="1072" y="488" width="72" height="12" rx="2"/>
+        <text class="label" x="1108" y="496">DEPENDENTS</text>
+        <rect class="label-mask" x="716" y="68" width="80" height="12" rx="2"/>
+        <text class="label" x="756" y="76">STAGED BASE</text>
+
+        <rect class="input" x="40" y="144" width="216" height="128" rx="6"/>
+        <text class="tag" x="56" y="168">MAIN</text>
+        <text class="name" x="148" y="200">Start isolated request</text>
+        <text class="code" x="148" y="224">delegate_task · mode: isolated</text>
+        <text class="detail" x="148" y="248">Keep the durable request ID.</text>
+
+        <rect class="node" x="304" y="144" width="256" height="128" rx="6"/>
+        <text class="tag" x="320" y="168">WORKERS</text>
+        <text class="name" x="432" y="200">Commit candidates</text>
+        <text class="detail" x="432" y="224">Use owned worktrees.</text>
+        <text class="detail" x="432" y="248">No tracked or untracked changes.</text>
+
+        <rect class="node" x="608" y="144" width="272" height="128" rx="6"/>
+        <text class="tag" x="624" y="168">RUNNER</text>
+        <text class="name" x="744" y="200">Run preliminary checks</text>
+        <text class="detail" x="744" y="224">Include optional task judgment.</text>
+        <text class="detail" x="744" y="248">Bind evidence to the exact candidate.</text>
+
+        <rect class="node" x="928" y="144" width="272" height="128" rx="6"/>
+        <text class="tag" x="944" y="168">RUNNER → MAIN</text>
+        <text class="name" x="1064" y="200">Send ready follow-up</text>
+        <text class="detail" x="1064" y="224">Readiness is not promotion.</text>
+        <text class="code" x="1064" y="248">subagent_status</text>
+
+        <rect class="focal" x="928" y="344" width="272" height="128" rx="6"/>
+        <text class="tag" x="944" y="368">MAIN · INTEGRATION CHECKOUT</text>
+        <text class="name" x="1064" y="400">Stage exact candidates</text>
+        <text class="code" x="1064" y="424">subagent_stage</text>
+        <text class="detail" x="1064" y="448">Stage while siblings run.</text>
+
+        <rect class="node" x="568" y="344" width="312" height="128" rx="6"/>
+        <text class="tag" x="584" y="368">MAIN · AFTER THE WAVE SETTLES</text>
+        <text class="name" x="724" y="400">Validate the exact combined tip</text>
+        <text class="code" x="724" y="424">subagent_integrate validate</text>
+        <text class="detail" x="724" y="448">Final checks and optional final judgment</text>
+
+        <rect class="focal" x="160" y="344" width="312" height="128" rx="6"/>
+        <text class="tag" x="176" y="368">MAIN · EXPLICIT PROMOTION</text>
+        <text class="name" x="316" y="400">Promote passing work</text>
+        <text class="code" x="316" y="424">subagent_integrate promote</text>
+        <text class="detail" x="316" y="448">Main must be unchanged and clean.</text>
+
+        <rect class="optional" x="928" y="520" width="272" height="88" rx="6"/>
+        <text class="name" x="1064" y="544">Advance dependent tasks</text>
+        <text class="code" x="1064" y="564">subagent_integrate advance</text>
+        <text class="detail" x="1064" y="588">Run from the selected staged snapshot.</text>
+
+        <!-- Safety details remain in the README as text. -->
+        <text class="note-title" x="40" y="536">Blocked promotion preserves evidence.</text>
+        <text class="note" x="40" y="560">Failures, conflicts, changed identities, or uncertain</text>
+        <text class="note" x="40" y="580">outcomes require inspection, not replay.</text>
+        <text class="note-title" x="520" y="536">One combined correction</text>
+        <text class="note" x="520" y="560">After a definitive combined check or review failure,</text>
+        <text class="note" x="520" y="580">commit one correction, record it, then validate again.</text>
+
+        <line x1="40" y1="640" x2="1240" y2="640" stroke="#101828" stroke-opacity=".141"/>
+        <line class="edge" x1="40" y1="672" x2="88" y2="672"/>
+        <text class="key" x="104" y="676">Checked sequence</text>
+        <line class="branch" x1="304" y1="672" x2="352" y2="672"/>
+        <text class="key" x="368" y="676">Dependent wave, if needed</text>
+        <text class="key" x="704" y="676">Staging, validation, and promotion require exact, clean Main.</text>
+      </svg>