@nanonets/graft 0.16.0 → 0.19.0

package/dist/brain/signup.js

@@ -0,0 +1,186 @@
+/**
+ * Getting a brain without leaving the terminal.
+ *
+ * Until now a brain could only begin in the browser. You signed up on Trail, it
+ * created the brain, and handed you a `graft init --brain <id>:<token>` line to
+ * paste. That is the right way round when the website is where you already are,
+ * and the wrong way round when you are standing in a repository with graft
+ * already installed — which is where most people meet graft first.
+ *
+ * So `graft brain push` on an unlinked repo starts here instead of stopping.
+ * Graft opens a listener on loopback, sends the browser to Trail carrying the
+ * repository it is standing in and the port to answer on, and waits. Trail does
+ * the signing up, makes a brain for that repository, and redirects back to the
+ * listener with the brain id and its read token. The push then carries on as if
+ * the repo had been linked all along.
+ *
+ * Two things keep that safe. The listener binds to 127.0.0.1, so nothing off
+ * this machine can reach it. And it accepts only a handoff echoing the random
+ * state it just generated, so some other page the user happens to have open
+ * cannot push a brain of its own choosing into their repository.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+/** Default web host. Overridden by GRAFT_BRAIN_URL, for staging and self-hosted.
+ *
+ * Trail's own front end, not the shared `agents.nanonets.com` one that `link.ts`
+ * calls for the API. Both are served by the same backend, so either would mint a
+ * working token — but this URL is the one a person looks at, and it has to be
+ * the Trail-branded build, with Trail's Auth0 redirect behind the signup. */
+const DEFAULT_WEB_BASE_URL = "https://app.trailhq.com";
+/** How long the listener waits for the browser before giving up. A signup can
+ * involve reading an email, so this is minutes rather than seconds. */
+export const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
+/** The one path the listener answers on. */
+export const CALLBACK_PATH = "/graft/callback";
+/** Constant-time compare of two states, length included. */
+function sameState(got, want) {
+    const a = Buffer.from(got);
+    const b = Buffer.from(want);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** The page the user is left looking at. Deliberately plain: it exists to say
+ * "go back to your terminal", and it is served from a throwaway port that is
+ * about to close, so there is nothing to style around. */
+function donePage(ok) {
+    const msg = ok
+        ? "Your brain is connected. Return to your terminal — the push is already running."
+        : "That handoff did not match this terminal. Run `graft brain push` again.";
+    return `<!doctype html><meta charset="utf-8"><title>graft</title><body style="font:15px/1.5 system-ui,sans-serif;margin:3rem auto;max-width:32rem;color:#1F2129"><p>${msg}</p><p style="color:#676767">You can close this tab.</p>`;
+}
+/**
+ * Start listening for the browser's handoff.
+ *
+ * Port 0 so the OS picks a free one: a fixed port would collide with whatever
+ * else the developer is running, and a second graft in another terminal.
+ */
+export async function startHandoff() {
+    const state = randomBytes(24).toString("base64url");
+    let settle = () => { };
+    const answered = new Promise((resolve) => {
+        settle = resolve;
+    });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== CALLBACK_PATH) {
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("not found");
+            return;
+        }
+        // Checked before anything is read out of the query, so a mismatched handoff
+        // never reaches the link-writing path at all.
+        if (!sameState(url.searchParams.get("state") ?? "", state)) {
+            res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+            res.end(donePage(false));
+            return;
+        }
+        const brainId = (url.searchParams.get("brain") ?? "").trim();
+        const token = (url.searchParams.get("token") ?? "").trim();
+        if (!brainId || !token) {
+            res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+            res.end(donePage(false));
+            settle({ error: "the browser came back without a brain id and token", reason: "bad_callback" });
+            return;
+        }
+        // 303 so the browser issues a plain GET, and Location built from
+        // GRAFT_BRAIN_URL rather than anything the query carried — the same reason
+        // the Trail side builds its callback rather than being told one.
+        res.writeHead(303, { location: brainUrl(brainId), "cache-control": "no-store" });
+        res.end();
+        // No `baseUrl` stored, matching `connect`: GRAFT_BRAIN_URL is read again on
+        // every use, so persisting it here would only freeze a host that the env
+        // var is already free to move.
+        settle({ link: { brainId, token } });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.removeAllListeners("error");
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        server.close();
+    };
+    return {
+        port,
+        state,
+        close,
+        async wait(timeoutMs = HANDOFF_TIMEOUT_MS) {
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ error: "timed out waiting for the browser — run `graft brain push` again, or use the link above", reason: "timed_out" }), timeoutMs);
+                // The timer must not hold the process open once the browser has answered.
+                timer.unref?.();
+            });
+            try {
+                return await Promise.race([answered, timeout]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                close();
+            }
+        },
+    };
+}
+/** The Trail front end this machine is pointed at, without a trailing slash.
+ *
+ * Read at the moment it is needed rather than captured once, matching the rest
+ * of the brain code: GRAFT_BRAIN_URL is free to move between calls. */
+export function webBaseUrl(baseUrl) {
+    return (process.env.GRAFT_BRAIN_URL || baseUrl || DEFAULT_WEB_BASE_URL).replace(/\/+$/, "");
+}
+/** Where the browser is sent once the handoff has been accepted.
+ *
+ * Back into Trail, at the screen that shows the brain being built. The
+ * alternative — leaving the person on a local page that says "go back to your
+ * terminal" — ends the flow on a blank throwaway served by a port that is about
+ * to close, at exactly the moment there is something to watch.
+ *
+ * NOT `/brain/<id>`, which is where this pointed first. That route redirects to
+ * the brain's graph, and the redirect fires the instant the row exists — which
+ * is minutes before it has any rules in it. Every terminal signup therefore
+ * landed on an empty visualisation of a brain that was, at that moment, being
+ * built perfectly well. The build screen is the same wait the browser-first
+ * flow shows, and it leads to the graph once there is a graph. */
+export function brainUrl(brainId, baseUrl) {
+    return `${webBaseUrl(baseUrl)}/get-started?step=build&brain=${encodeURIComponent(brainId)}`;
+}
+/** Where to send the browser for a repo's brain. */
+export function signupUrl(opts) {
+    const base = webBaseUrl(opts.baseUrl);
+    const q = new URLSearchParams({
+        step: "repo",
+        graft_repo: opts.repo,
+        graft_port: String(opts.port),
+        graft_state: opts.state,
+    });
+    return `${base}/get-started?${q.toString()}`;
+}
+/** Open the user's browser, best effort. A machine with no opener is not an
+ * error: the URL is printed too, and that is the fallback everywhere.
+ *
+ * GRAFT_NO_BROWSER leaves the printed URL as the only route, which is what a
+ * test wants, and what someone on a machine whose `open` does something
+ * surprising wants too. */
+export function openBrowser(url) {
+    if (process.env.GRAFT_NO_BROWSER)
+        return;
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(opener, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    }
+    catch {
+        /* the printed URL is the fallback */
+    }
+}
+//# sourceMappingURL=signup.js.map

package/dist/brain/signup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signup.js","sourceRoot":"","sources":["../../src/brain/signup.ts"],"names":[],"mappings":"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"}

package/dist/brain/watch.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Watching a brain being built, from the terminal.
+ *
+ * `graft brain push` used to end at "it is being mined into rules now — a few
+ * minutes. Watch it finish in your browser." and hand the prompt straight back.
+ * That sentence is the last thing this process ever says about the work, and it
+ * is said BEFORE the part that actually fails: of the repo brains attempted in
+ * production, roughly a third die inside the miner, after the push succeeded.
+ * The terminal has already returned by then, so on this side the failure does
+ * not exist at all — and on a CI runner or over SSH, where nobody is going to
+ * open a browser, it exists nowhere.
+ *
+ * So the push now holds the line and reports the same four stages the browser
+ * shows, off the same row. Ctrl-C detaches without cancelling anything, because
+ * the work is server-side and killing a watcher must never look like killing
+ * the build.
+ *
+ * What it holds the line UNTIL changed with slicing. The history is now mined in
+ * several calls rather than one, and the first of them returns in about ten
+ * seconds; filing all of the rules into the graph takes minutes more. Mining is
+ * where the failures are — the thing this watcher exists to report — and filing
+ * is long, dull and reliable, so the line is held through the first and handed
+ * back before the second. Holding a terminal through five minutes of successful
+ * filing buys nobody anything, and on a CI runner it is five minutes of a job
+ * sitting idle.
+ */
+import type { BrainLink } from "./link.js";
+/** The stages, in the order they happen. The wording matches Trail's build
+ *  screen deliberately: two products describing one process differently is how
+ *  a person ends up unsure whether they are looking at the same thing. */
+export declare const STAGES: readonly [{
+    readonly id: "reach";
+    readonly label: "reaching the repository";
+}, {
+    readonly id: "read";
+    readonly label: "reading its history";
+}, {
+    readonly id: "mine";
+    readonly label: "mining the rules";
+}, {
+    readonly id: "file";
+    readonly label: "filing them into the brain";
+}];
+export type StageId = (typeof STAGES)[number]["id"];
+export type StageState = "waiting" | "doing" | "done" | "failed";
+export interface Stage {
+    id: StageId;
+    label: string;
+    state: StageState;
+    /** A count worth printing beside a stage that has produced one. */
+    detail?: string;
+}
+/** The repo row, as the public endpoint returns it. Only the fields the stages
+ *  read, so a field added server-side cannot quietly change what is printed. */
+export interface RepoState {
+    status: string;
+    errorMessage?: string;
+    ruleCount: number;
+    commitCount: number;
+    threadCount: number;
+    /** Rules in the graph right now, from the job still running. The row's own
+     *  `ruleCount` is only written when that job finishes, so mid-build it is
+     *  zero however many rules are already there.
+     *
+     *  Optional because an older Trail does not send it, and a graft pointed at
+     *  one must fall back to waiting for the finished row rather than reading a
+     *  missing field as "no rules". */
+    filedSoFar?: number;
+    /** Rules the miner has handed over so far. Grows with every slice of the
+     *  history that comes back, so it is a floor and never a total. */
+    foundSoFar?: number;
+}
+export interface BuildView {
+    stages: Stage[];
+    /**
+     * True once rules are in the graph — which is when this watcher has nothing
+     * left to report, not when the job ends. The rest of the slices keep mining
+     * and filing after the prompt comes back.
+     */
+    ready: boolean;
+    done: boolean;
+    /** The server's own words, when it failed. */
+    error: string | null;
+}
+/**
+ * Which stage the work is in.
+ *
+ * The rule that matters is where a failure lands. A row that never left
+ * `pending` failed at the access check; one that read 412 commits and then died
+ * failed in the miner. Reporting both as "could not reach it" would send someone
+ * to fix repository access for a problem that has nothing to do with it.
+ */
+export declare function stagesFrom(repo: RepoState | null): BuildView;
+/**
+ * Read the repo row this brain is building.
+ *
+ * The same endpoint `fetchExpectedRepo` uses, read for its counts rather than
+ * its slug. Null on any failure, so a watcher that cannot reach the API prints
+ * nothing new rather than inventing a failure the build did not have.
+ */
+export declare function fetchRepoState(link: BrainLink, fetchImpl?: typeof fetch): Promise<RepoState | null>;
+/** One printable line per stage that has moved since it was last printed. */
+export declare function linesFor(view: BuildView, already: Set<string>): string[];
+export interface WatchOptions {
+    /** How long to hold before giving up on a build that is still running. */
+    timeoutMs?: number;
+    pollMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Where the lines go. Injected so the tests do not need a console. */
+    write?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How the watch ended.
+ *
+ * `building` is the ordinary success: rules are in the brain and the rest of the
+ * history is still being read behind the prompt. `completed` is the same thing
+ * after the whole job has finished, which only happens for a repository small
+ * enough to be mined in one slice.
+ */
+export type WatchOutcome = "completed" | "building" | "failed" | "timed_out" | "unreachable";
+/**
+ * Hold until the brain has rules, printing each stage as it settles.
+ *
+ * Returns on the first rules rather than on the finished job: mining is what
+ * fails and it is done by then, and filing the rest is minutes of work nobody
+ * needs to watch. The caller prints where to see the rest.
+ *
+ * Fifteen minutes by default. That is far more than the mining now takes, and it
+ * stays generous on purpose: a watcher that gives up before the build does would
+ * report a healthy build as a timeout, which is the exact confusion this is
+ * meant to remove. Giving up says so and says the work continues, because it
+ * does.
+ */
+export declare function watchBuild(link: BrainLink, opts?: WatchOptions): Promise<WatchOutcome>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/brain/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/brain/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;0EAE0E;AAC1E,eAAO,MAAM,MAAM;;;;;;;;;;;;EAKT,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AACpD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;gFACgF;AAChF,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;uCAMmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;uEACmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,CAsD5D;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA2BhH;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAcxE;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAE7F;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgChG"}

package/dist/brain/watch.js

@@ -0,0 +1,172 @@
+import { baseUrlFor } from "./link.js";
+/** The stages, in the order they happen. The wording matches Trail's build
+ *  screen deliberately: two products describing one process differently is how
+ *  a person ends up unsure whether they are looking at the same thing. */
+export const STAGES = [
+    { id: "reach", label: "reaching the repository" },
+    { id: "read", label: "reading its history" },
+    { id: "mine", label: "mining the rules" },
+    { id: "file", label: "filing them into the brain" },
+];
+const num = (v) => (typeof v === "number" && v > 0 ? v : 0);
+/**
+ * Which stage the work is in.
+ *
+ * The rule that matters is where a failure lands. A row that never left
+ * `pending` failed at the access check; one that read 412 commits and then died
+ * failed in the miner. Reporting both as "could not reach it" would send someone
+ * to fix repository access for a problem that has nothing to do with it.
+ */
+export function stagesFrom(repo) {
+    const commits = num(repo?.commitCount);
+    const threads = num(repo?.threadCount);
+    const rules = num(repo?.ruleCount);
+    const filedSoFar = num(repo?.filedSoFar);
+    const foundSoFar = num(repo?.foundSoFar);
+    const reached = !!repo && repo.status !== "pending";
+    const readIt = commits > 0 || threads > 0;
+    // Rules that exist, whether the job has finished writing its count or not.
+    const hasRules = filedSoFar > 0 || rules > 0;
+    const filed = rules > 0;
+    const failed = repo?.status === "failed";
+    const failedAt = !failed ? null : !reached || !readIt ? "reach" : !hasRules ? "mine" : "file";
+    const order = STAGES.map((s) => s.id);
+    const state = (id) => {
+        if (failedAt === id)
+            return "failed";
+        if (failedAt && order.indexOf(id) > order.indexOf(failedAt))
+            return "waiting";
+        switch (id) {
+            case "reach":
+                return reached ? "done" : "doing";
+            case "read":
+                return readIt ? "done" : reached ? "doing" : "waiting";
+            case "mine":
+                // Done on the first slice's rules. The remaining slices are still being
+                // mined at this point, behind the prompt this watcher is about to
+                // return — which is the whole change.
+                return hasRules ? "done" : readIt ? "doing" : "waiting";
+            case "file":
+                return filed ? "done" : hasRules ? "doing" : readIt ? "waiting" : "waiting";
+        }
+    };
+    const detail = (id) => {
+        if (id === "read" && (commits || threads)) {
+            return [commits ? `${commits} commits` : null, threads ? `${threads} discussions` : null].filter(Boolean).join(", ");
+        }
+        // "so far" because the count grows with each slice that lands. Printing it
+        // as a total would promise history that has not been read yet.
+        if (id === "mine" && foundSoFar)
+            return `${foundSoFar} rules so far`;
+        if (id === "file" && rules)
+            return `${rules} rules`;
+        if (id === "file" && filedSoFar)
+            return `${filedSoFar} rules so far`;
+        return undefined;
+    };
+    return {
+        stages: STAGES.map((s) => ({ id: s.id, label: s.label, state: state(s.id), detail: detail(s.id) })),
+        ready: hasRules && !failed,
+        done: repo?.status === "completed" && filed,
+        error: failed ? (repo?.errorMessage?.trim() || "the read stopped before it finished") : null,
+    };
+}
+/**
+ * Read the repo row this brain is building.
+ *
+ * The same endpoint `fetchExpectedRepo` uses, read for its counts rather than
+ * its slug. Null on any failure, so a watcher that cannot reach the API prints
+ * nothing new rather than inventing a failure the build did not have.
+ */
+export async function fetchRepoState(link, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`, {
+            headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body.repo)
+            return null;
+        return {
+            status: String(body.repo.status ?? ""),
+            errorMessage: body.repo.error_message,
+            ruleCount: num(body.repo.rule_count),
+            commitCount: num(body.repo.commit_count),
+            threadCount: num(body.repo.thread_count),
+            filedSoFar: num(body.build?.filed_so_far),
+            foundSoFar: num(body.build?.found_so_far),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** One printable line per stage that has moved since it was last printed. */
+export function linesFor(view, already) {
+    const out = [];
+    for (const s of view.stages) {
+        // Only settled states are printed. A line per poll for a stage that is
+        // merely still running would bury the four that matter under a hundred
+        // that do not — this is a log, not a redrawn frame.
+        if (s.state !== "done" && s.state !== "failed")
+            continue;
+        const key = `${s.id}:${s.state}`;
+        if (already.has(key))
+            continue;
+        already.add(key);
+        const mark = s.state === "done" ? "✓" : "✗";
+        out.push(`  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ""}`);
+    }
+    return out;
+}
+/**
+ * Hold until the brain has rules, printing each stage as it settles.
+ *
+ * Returns on the first rules rather than on the finished job: mining is what
+ * fails and it is done by then, and filing the rest is minutes of work nobody
+ * needs to watch. The caller prints where to see the rest.
+ *
+ * Fifteen minutes by default. That is far more than the mining now takes, and it
+ * stays generous on purpose: a watcher that gives up before the build does would
+ * report a healthy build as a timeout, which is the exact confusion this is
+ * meant to remove. Giving up says so and says the work continues, because it
+ * does.
+ */
+export async function watchBuild(link, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 15 * 60 * 1000;
+    const pollMs = opts.pollMs ?? 4000;
+    const write = opts.write ?? ((l) => console.error(l));
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+    const printed = new Set();
+    const startedAt = Date.now();
+    // A row we could never read at all, as opposed to one that answered once and
+    // then stopped answering: the first is a broken link or a host that is down
+    // and is worth saying, the second is a blip the next poll usually covers.
+    let everRead = false;
+    for (;;) {
+        const repo = await fetchRepoState(link, opts.fetchImpl);
+        if (repo) {
+            everRead = true;
+            const view = stagesFrom(repo);
+            for (const line of linesFor(view, printed))
+                write(line);
+            if (view.error) {
+                write(`✗ ${view.error}`);
+                return "failed";
+            }
+            if (view.done)
+                return "completed";
+            // The ordinary ending now. The job is still filing the rules the miner
+            // has handed over, and still mining the older slices of the history, and
+            // neither is worth a terminal sitting on it.
+            if (view.ready)
+                return "building";
+        }
+        if (Date.now() - startedAt >= timeoutMs)
+            return everRead ? "timed_out" : "unreachable";
+        await sleep(pollMs);
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/brain/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/brain/watch.ts"],"names":[],"mappings":"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"}

package/dist/brain/wire.d.ts

@@ -0,0 +1,38 @@
+import { type HostTarget } from '../hosts/registry.js';
+import { type UpsertAction } from '../hosts/sections.js';
+import type { BrainRule } from './link.js';
+/** What a rules write did to one host's file. */
+export interface BrainWrite {
+    id: string;
+    path: string;
+    action: UpsertAction;
+}
+/**
+ * Render the rules block for an instruction file.
+ *
+ * Grouped by the file the rule governs, because that is how someone reads a
+ * codebase, and repo-wide rules (no symbol) come first — they apply everywhere,
+ * so they should not be buried under a path heading.
+ */
+export declare function renderBrainSection(rules: BrainRule[], repoLabel: string): string;
+/**
+ * Every instruction file a brain section should go in.
+ *
+ * `section`-kind hosts only. An `owned`-kind host (Cursor's `.mdc`, Kiro's
+ * steering file, a `SKILL.md`) is a file graft rewrites whole from a pure
+ * template, so a second managed region inside one would be erased by the next
+ * `init` — those agents get their rules through `graft ask` instead, which they
+ * all call.
+ *
+ * Deduplicated by path: three hosts target `AGENTS.md`, and writing it three
+ * times in one pass is just three identical upserts.
+ */
+export declare function brainSectionTargets(repo: string, home: string, ids?: string[]): HostTarget[];
+/**
+ * Write the brain's rules into each selected host's instruction file.
+ *
+ * Best-effort per file: one unwritable path must not stop the rest, since a
+ * partially delivered rulebook is strictly better than none.
+ */
+export declare function writeBrainSections(repo: string, home: string, rules: BrainRule[], repoLabel: string, ids?: string[]): BrainWrite[];
+//# sourceMappingURL=wire.d.ts.map

package/dist/brain/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/brain/wire.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAK3C,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqChF;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAa5F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,EAAE,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,EAAE,GACb,UAAU,EAAE,CAed"}