@nanonets/graft 0.19.0 → 0.21.0

package/dist/cli.js

@@ -19,29 +19,34 @@ import { hostIds } from "./hosts/registry.js";
 import { parseBrainArg, connectBrain, pullBrain, brainStatus } from "./brain/connect.js";
 import { rulesForPointers } from "./brain/attach.js";
 import { clearLink } from "./brain/link.js";
-import { buildLocalDigest, fetchExpectedRepo, pushDigest, repoSlugFromGit, sameRepo } from "./brain/push.js";
-import { readLink, writeLink } from "./brain/link.js";
-import { watchBuild } from "./brain/watch.js";
-import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";
+import { buildEarlyDigest, buildLocalDigest, fetchExpectedRepo, pushContext, pushDigest, pushEarlyDigest, repoSlugFromGit, sameRepo, uploadCaps, } from "./brain/push.js";
+import { apiBaseUrl, clearPendingSignup, readLink, readPendingSignup, writeLink, writePendingSignup } from "./brain/link.js";
+import { withLegacyNames } from "./legacy-args.js";
+import { currentStage, DOING_LABEL, rulesSoFar, watchBuild } from "./brain/watch.js";
+import { AGENT_WAIT_MS, brainUrl, newSignupState, openBrowser, PENDING_SIGNUP_TTL_MS, reviewUrl, signupUrl, startHandoff, waitForSignup, } from "./brain/signup.js";
+import { runTrailPull } from "./brain/pull.js";
+import { readByWired, readersOf } from "./brain/context-files.js";
+import { startSpinner } from "./util/spinner.js";
 import { contextDirFor } from "./context/node-file.js";
 import { loadGraphCached } from "./graph/load.js";
 import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";
 import { isWorkspaceBuildRoot, readWorkspace } from "./graph/workspace.js";
-import { nearestGraftRoot } from "./graph/root.js";
+import { hasGraftIndex, nearestGraftRoot } from "./graph/root.js";
 import { unsupportedExtensions, supportedExtensions } from "./graph/source-files.js";
 import { discoverWorkspaceChildren } from "./graph/scopes.js";
 import { runWorkspaceAsk, runWorkspaceBuild, runWorkspaceCallers, runWorkspaceCheck, runWorkspaceGrep, runWorkspaceMap, } from "./graph/workspace-cli.js";
 import { formatInitEpilogue } from "./cli-epilogue.js";
 import { planInit, selectedWrites } from "./hosts/plan.js";
 import { planRetract, runRetract, changed } from "./hosts/retract.js";
-import { formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
+import { compactWrites, formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
+import { buildGraphWithProgress } from "./claude/build-progress.js";
 import { homedir } from "node:os";
 import { formatUpgradeReport, formatVersionReport, getNpmViewVersion, readCurrentVersion, runUpgrade } from "./cli-meta.js";
 import { patchBuildConfig } from "./util/state.js";
 import { normalizePathPrefix } from "./util/paths.js";
 import { latestSession, formatSessionStats, sessionInputRate } from "./claude/session-metrics.js";
 import { setInputRate } from "./context/savings.js";
-import { formatUpdateNudge, maybeRefreshInBackground, readUpdateCache, refreshUpdateCache, writeStamp } from "./upkeep.js";
+import { formatUpdateNudge, maybeRefreshInBackground, readStamp, readUpdateCache, refreshUpdateCache, wiredHostIds, writeStamp } from "./upkeep.js";
 import { errorCode, filesBucket, durationBucket, formatDebug, formatStatus, firstRunNotice, isTrackedCommand, langsValue, offReason, maybeFlushInBackground, patchState, runFlush, track, trackFirstRunIfNew, } from "./telemetry/index.js";
 const program = new Command();
 const currentVersion = readCurrentVersion(import.meta.url);
@@ -817,22 +822,42 @@ program
     .option("--dry-run", "print every file init would touch, then exit without writing")
     .option("-y, --yes", "skip the picker and wire every detected agent (the pre-0.8 default)")
     .option("--no-global", "skip writes outside this repo (the ~/.codex/ config + hooks)")
-    .option("--brain <handoff>", "attach a Trail brain: <brainId>:<token> (or a bare brain id with GRAFT_BRAIN_TOKEN set)")
+    .option("--trail <handoff>", "attach a Trail: <brainId>:<token> (or a bare id with GRAFT_BRAIN_TOKEN set)")
+    .option("--verbose", "print every file written, the graph build's own output and the closing banner")
     .action(async (dir, opts) => {
+    await runInitCommand(dir, opts);
+});
+/** `a, b and c`. */
+function joinAnd(items) {
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+/** Repo-relative with forward slashes, for printing. */
+function shown(repo, path) {
+    return relative(repo, path).split("\\").join("/");
+}
+/**
+ * `graft init`. Also run by `graft trail push` on a repo graft has not been set
+ * up in — the Trail pages start people at push, and a trail whose rules no
+ * coding agent reads is only half set up. `epilogue: false` leaves out the
+ * closing banner when push is going to keep talking.
+ */
+async function runInitCommand(dir, opts, how = {}) {
     if (opts.listAgents) {
         for (const id of [...hostIds(), "claude"])
             console.log(id);
-        return;
+        return null;
     }
     // Parsed before anything is written: a mistyped handoff should cost the user
     // an error, not a half-wired repo they have to `graft uninstall` out of.
     let brainLink;
-    if (opts.brain) {
-        const parsed = parseBrainArg(opts.brain);
+    if (opts.trail) {
+        const parsed = parseBrainArg(opts.trail);
         if ("error" in parsed) {
-            console.error(`✗ --brain: ${parsed.error}`);
+            console.error(`✗ --trail: ${parsed.error}`);
             process.exitCode = 1;
-            return;
+            return null;
         }
         brainLink = parsed;
     }
@@ -872,17 +897,19 @@ program
         const reason = offReason();
         const picked = await runPicker(plan, repo, home, {
             offerTelemetry: reason === null || reason === "disabled",
+            // From push, the line above the picker already asks the question.
+            ...(how.push ? { title: null } : {}),
         });
         if (picked === null) {
             console.error("· cancelled — nothing written");
-            return;
+            return null;
         }
         ids = picked.hosts;
         consent = picked.telemetry;
     }
     else {
         console.error(formatNonInteractiveHelp(detectedIds));
-        return;
+        return null;
     }
     // The picker's answer, recorded before anything is wired: a user who
     // unchecked the row must not have this run's init_completed sent.
@@ -903,34 +930,121 @@ program
         console.error(formatPlan(plan, ids, repo, home));
         for (const child of children)
             console.error(`\n— ${child}/ (workspace child)\n` + formatPlan(planInit(join(repo, child), { home }), ids, join(repo, child), home));
-        return;
+        return null;
     }
     if (ids.length === 0) {
         console.error("· no agents selected — nothing written");
-        return;
+        return null;
     }
     const wantClaude = ids.includes("claude");
     const cliPath = fileURLToPath(import.meta.url);
     if (children.length)
         console.error(`· workspace: wiring ${repo} and ${children.length} child repo(s) — ${children.join(", ")}`);
+    // Today's output, file by file, behind --verbose. Everything else gets one
+    // line per step: the graph, then one per agent.
+    const verbose = opts.verbose === true;
+    const reports = [];
     for (const target of targets) {
-        if (target !== repo)
+        if (verbose && target !== repo)
             console.error(`\n— ${relative(repo, target)}/`);
-        wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude });
+        reports.push(wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude, quiet: !verbose }));
+    }
+    // The graph, built once after the wiring: a workspace parent's build is
+    // the workspace build, so it covers every child.
+    let graphLine = null;
+    let graphNodes = 0;
+    if (!verbose) {
+        const res = await buildGraphWithProgress(repo, { build: opts.build, cliPath });
+        for (const m of res.messages)
+            console.error(m);
+        const existing = res.built ? null : loadGraphCached(contextDirFor(repo, children.length ? undefined : program.opts().dir));
+        const fmt = (x) => x.toLocaleString("en-US");
+        if (res.graph) {
+            graphNodes = res.graph.nodes;
+            graphLine = `✓ graph built · ${fmt(res.graph.nodes)} nodes, ${fmt(res.graph.edges)} edges${res.graph.files ? ` from ${fmt(res.graph.files)} file${res.graph.files === 1 ? "" : "s"}` : ""}`;
+        }
+        else if (res.built) {
+            graphLine = "✓ graph built";
+        }
+        else if (res.failed) {
+            graphLine = "⚠ the graph build failed — run graft build to see why";
+        }
+        else if (existing) {
+            graphNodes = existing.meta.nodeCount;
+            graphLine = `✓ graph ready · ${fmt(existing.meta.nodeCount)} nodes, ${fmt(existing.meta.edgeCount)} edges`;
+        }
+        else if (hasGraftIndex(repo)) {
+            graphLine = "✓ graph ready";
+        }
+        else {
+            graphLine = "· skipped the graph build — run graft build";
+        }
+    }
+    if (!verbose) {
+        // Warnings and removals in full, whatever else is folded.
+        const removed = [...new Set(reports.flatMap((r) => r.retracted))];
+        for (const id of removed)
+            console.error(`- removed ${id} — agent not selected`);
+        for (const w of reports.flatMap((r) => r.warnings))
+            console.error(w);
+        const writesFor = (id) => (plan.find((p) => p.id === id)?.writes ?? []).filter((w) => opts.global !== false || w.scope !== "global");
+        if (how.push) {
+            const built = graphLine?.startsWith("✓ graph built") ? `graph built, ${graphNodes.toLocaleString("en-US")} nodes` : graphLine?.startsWith("✓") ? "graph ready" : null;
+            console.error(`✓ wired ${joinAnd(ids)}${built ? ` · ${built}` : ""}`);
+            if (graphLine && !graphLine.startsWith("✓"))
+                console.error(graphLine);
+        }
+        else {
+            if (graphLine)
+                console.error(graphLine);
+            const width = Math.max(...ids.map((id) => id.length));
+            for (const id of ids) {
+                const summary = compactWrites(writesFor(id), repo, home);
+                console.error(`✓ ${id.padEnd(width)}   ${summary}`.trimEnd());
+            }
+        }
     }
     // The brain comes last, after the graph exists: its rules are anchored to
-    // symbols, and `graft brain status` can only report how many of them resolve
+    // symbols, and `graft trail status` can only report how many of them resolve
     // once there is a graph to resolve them against.
     if (brainLink) {
         const res = await connectBrain(repo, brainLink, { home, ids });
-        if (res.warning)
-            console.error(`⚠ brain: ${res.warning}`);
-        else
-            console.error(`✓ brain: pulled ${res.ruleCount} rule(s) from ${brainLink.brainId}`);
-        for (const w of res.writes)
-            console.error(`✓ brain rules: ${w.path} (${w.action})`);
-        if (res.ruleCount > 0 && res.writes.length === 0)
-            console.error("· no instruction file to write rules into — graft ask still carries them");
+        if (verbose) {
+            if (res.warning)
+                console.error(`⚠ brain: ${res.warning}`);
+            else
+                console.error(`✓ brain: pulled ${res.ruleCount} rule(s) from ${brainLink.brainId}`);
+            for (const w of res.writes)
+                console.error(`✓ brain rules: ${w.path} (${w.action})`);
+            if (res.ruleCount > 0 && res.writes.length === 0)
+                console.error("· no instruction file to write rules into — graft ask still carries them");
+        }
+        else if (res.warning) {
+            console.error(`⚠ trail: ${res.warning}`);
+        }
+        else if (res.ruleCount === 0) {
+            console.error("✓ trail connected · no rules yet — graft trail push reads this repo into it");
+        }
+        else {
+            const where = res.writes.map((w) => shown(repo, w.path)).join(", ");
+            const n = `${res.ruleCount.toLocaleString("en-US")} rule${res.ruleCount === 1 ? "" : "s"}`;
+            console.error(`✓ trail connected · ${n}${where ? ` in ${where}` : ""}`);
+        }
+    }
+    if (!verbose && how.epilogue !== false) {
+        // What there is to commit: the top-level entries the picked agents wrote.
+        const tops = [];
+        for (const w of selectedWrites(plan, ids)) {
+            if (w.scope !== "repo")
+                continue;
+            const parts = shown(repo, w.path).split("/");
+            const top = parts.length > 1 ? `${parts[0]}/` : parts[0];
+            if (!tops.includes(top))
+                tops.push(top);
+        }
+        console.error("· restart your agents so a new session picks up graft");
+        if (tops.length)
+            console.error(`· commit ${tops.slice(0, 4).join(" ")}${tops.length > 4 ? ` +${tops.length - 4} more` : ""} to share it — graft/ stays local and git-ignored`);
     }
     // One epilogue for the whole run. A workspace parent holds no nodes of its
     // own, so the totals come from the children — the graph the user actually got.
@@ -938,18 +1052,30 @@ program
     const graphs = (children.length ? children.map((c) => join(repo, c)) : [repo])
         .map((d) => loadGraphCached(contextDirFor(d, children.length ? undefined : globalDir)))
         .filter((g) => g !== null);
-    console.error("\n" +
-        formatInitEpilogue({
-            graphBuilt: graphs.length > 0,
-            nodes: graphs.reduce((n, g) => n + g.meta.nodeCount, 0),
-            edges: graphs.reduce((n, g) => n + g.meta.edgeCount, 0),
-        }));
+    if (verbose && how.epilogue !== false)
+        console.error("\n" +
+            formatInitEpilogue({
+                graphBuilt: graphs.length > 0,
+                nodes: graphs.reduce((n, g) => n + g.meta.nodeCount, 0),
+                edges: graphs.reduce((n, g) => n + g.meta.edgeCount, 0),
+            }));
     // Sorted so `claude,cursor` and `cursor,claude` aggregate as one value.
     track("init_completed", { agents: [...ids].sort().join(","), consent: consent === undefined ? "unasked" : String(consent) }, { repo });
-});
+    return { ids };
+}
 /** One repo's worth of `init` writes — the parent, then each workspace child. */
 function wireTarget(repo, ids, ctx) {
-    const { home, cliPath, plan, wantClaude, opts } = ctx;
+    const { home, cliPath, plan, wantClaude } = ctx;
+    const quiet = ctx.quiet === true;
+    const opts = quiet ? { ...ctx.opts, build: false } : ctx.opts;
+    const report = { retracted: [], warnings: [] };
+    // Every per-file line goes through here; in quiet mode only ⚠ lines survive.
+    const say = (line) => {
+        if (!quiet)
+            console.error(line);
+        else if (line.startsWith("⚠"))
+            report.warnings.push(line);
+    };
     const wantStatusline = statuslineWanted({ statusline: opts.statusline });
     // Converge, don't just add. init writes the selected hosts; without this it
     // never touches the rest, so a repo wired by an older version (or by the same
@@ -959,27 +1085,28 @@ function wireTarget(repo, ids, ctx) {
     // be rewritten, and the graph cache is kept (init is one step from using it).
     const retracted = changed(runRetract(repo, { home, apply: true, global: opts.global, cache: false, exclude: ids })).filter((r) => r.action !== "skipped-unparseable");
     for (const r of retracted)
-        console.error(`- removed ${r.path} (${r.what}) — agent not selected`);
+        say(`- removed ${r.path} (${r.what}) — agent not selected`);
+    report.retracted = [...new Set(retracted.map((r) => r.hostId))];
     if (wantClaude) {
         // `global`/`home` are threaded through alongside `statusline`: the claude layer
         // writes under `~/.claude` now (hosts/claude-global.ts), so --no-global has to
         // reach it or the flag would silently mean "no out-of-repo writes, except three".
         const res = runInit(repo, { build: opts.build, cliPath, statusline: wantStatusline, global: opts.global, home });
-        console.error(`✓ wrote ${res.settingsPath}`);
+        say(`✓ wrote ${res.settingsPath}`);
         for (const s of res.shims)
-            console.error(`✓ wrote ${s}`);
-        console.error(`✓ wrote ${res.skill}`);
+            say(`✓ wrote ${s}`);
+        say(`✓ wrote ${res.skill}`);
         if (res.mcp.action === "skipped-unparseable")
-            console.error(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON) — add the graft server manually`);
+            say(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON) — add the graft server manually`);
         else if (res.mcp.action === "unchanged")
-            console.error(`· mcp claude: ${res.mcp.path} (already registered)`);
+            say(`· mcp claude: ${res.mcp.path} (already registered)`);
         else
-            console.error(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
-        console.error(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
+            say(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
+        say(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
         if (!wantStatusline)
-            console.error("· skipped Claude Code statusLine (--no-statusline)");
+            say("· skipped Claude Code statusLine (--no-statusline)");
         for (const w of res.warnings)
-            console.error(`⚠ ${w}`);
+            say(`⚠ ${w}`);
     }
     // `ids` is already resolved, so hosts init is always driven by an explicit
     // list — never by its own detection fallback.
@@ -993,14 +1120,14 @@ function wireTarget(repo, ids, ctx) {
             global: opts.global,
         });
         for (const w of r.written)
-            console.error(`✓ ${w.id}: ${w.path} (${w.action})`);
+            say(`✓ ${w.id}: ${w.path} (${w.action})`);
         for (const m of r.mcp)
-            console.error(`✓ mcp ${m.id}: ${m.path} (${m.action})`);
+            say(`✓ mcp ${m.id}: ${m.path} (${m.action})`);
         for (const h of r.hooks)
-            console.error(`✓ hook ${h.id}: ${h.path} (${h.action})`);
+            say(`✓ hook ${h.id}: ${h.path} (${h.action})`);
         // Only worth saying when there was actually something out-of-repo to skip.
         if (opts.global === false && selectedWrites(plan, ids).some((w) => w.scope === "global"))
-            console.error("· skipped out-of-repo writes (--no-global)");
+            say("· skipped out-of-repo writes (--no-global)");
     }
     // Record WHICH graft wrote this repo's agent files, and under which flags.
     // Every entry point compares this against the running binary and re-writes
@@ -1016,10 +1143,12 @@ function wireTarget(repo, ids, ctx) {
     // Every host's wiring points at graft/, so the graph is built whatever was
     // selected — not only when Claude Code is in the list (runInit does its own).
     if (!wantClaude) {
-        console.error(buildGraphIfMissing(repo, { build: opts.build, cliPath })
-            ? "✓ built the graph (graft build)"
-            : "· skipped graph build");
+        if (!quiet)
+            say(buildGraphIfMissing(repo, { build: opts.build, cliPath })
+                ? "✓ built the graph (graft build)"
+                : "· skipped graph build");
     }
+    return report;
 }
 /** Group a retraction report by host, so the output reads as "what leaves each agent". */
 function formatRetractions(rs, apply) {
@@ -1078,18 +1207,24 @@ program
         ? `\n⚠ ${bad.length} file(s) could not be parsed and were left as-is — see above.`
         : "\n✓ graft fully removed. `graft init` re-wires from scratch.");
 });
+// `graft trail …` still works: see legacy-args.ts.
 const brain = program
-    .command("brain")
-    .description("The Trail brain attached to this repo: the rules mined from its own history");
+    .command("trail")
+    .description("The Trail attached to this repo: the rules mined from its own history");
 /**
- * Get this repo a brain from the terminal, by sending the user through signup
+ * Get this repo a trail from the terminal, by sending the user through signup
  * in their browser and catching the handoff on loopback.
  *
  * Returns the link, already saved, or null when the user should be left alone —
  * every failure prints its own reason first, because the caller only needs to
- * know whether to carry on.
+ * know whether to carry on. Nothing about the repository has been read or sent
+ * by then, and every message says so.
  */
 async function signUpForBrain(repo, slug) {
+    // No terminal means an agent is running this, and a loopback listener cannot
+    // outlive the command it is waiting in: see signUpWithoutTerminal.
+    if (!process.stderr.isTTY)
+        return signUpWithoutTerminal(repo, slug);
     const handoff = await startHandoff();
     const url = signupUrl({ repo: slug, port: handoff.port, state: handoff.state });
     const startedAt = Date.now();
@@ -1097,37 +1232,96 @@ async function signUpForBrain(repo, slug) {
     // the outcome is the one thing a terminal handoff can lose: a user who reads
     // the URL and walks away kills the process, and only an event already on disk
     // survives that. This is the denominator; `brain_signup_settled` is not.
-    track("brain_signup_opened", {}, { repo });
+    track("brain_signup_opened", { mode: "terminal" }, { repo });
     // Printed before the browser opens, and printed whether or not it opens: on a
     // remote shell nothing can open, and on a desktop the window sometimes lands
     // behind the terminal. The URL is the thing that always works.
-    console.error(`· ${slug} has no brain yet. Opening your browser to make one:`);
+    console.error(`· ${slug} has no trail yet — opening your browser to make one:`);
     console.error(`  ${url}`);
-    // A non-interactive shell has nobody to click anything, so waiting five
-    // minutes for a browser that will never come is worse than saying so now.
-    if (!process.stderr.isTTY) {
-        console.error("· not a terminal — open that link, then run `graft brain connect <brainId>:<token>` here");
-        // Its own outcome, not a timeout: nothing here could have opened a browser,
-        // so folding the two together would read as people abandoning signup when
-        // it is only a remote shell doing what it has to.
-        track("brain_signup_settled", { outcome: "no_tty", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+    openBrowser(url);
+    const spinner = startSpinner("waiting for you to finish signing up · Ctrl-C to stop");
+    // Ctrl-C while waiting is a person changing their mind, not a crash: say that
+    // nothing was sent, and leave with the usual interrupted exit code.
+    let onSigint;
+    const stopped = new Promise((resolve) => {
+        onSigint = () => resolve("stopped");
+        process.once("SIGINT", onSigint);
+    });
+    const got = await Promise.race([handoff.wait(), stopped]);
+    if (onSigint)
+        process.off("SIGINT", onSigint);
+    spinner.stop();
+    if (got === "stopped") {
         handoff.close();
+        console.error("· stopped — nothing was sent; run graft trail push again when you're ready");
+        track("brain_signup_settled", { outcome: "stopped", mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+        process.exitCode = 130;
         return null;
     }
-    openBrowser(url);
-    console.error("· waiting for you to finish signing up…");
-    const got = await handoff.wait();
     if ("error" in got) {
         console.error(`✗ ${got.error}`);
         // The category, never the sentence: `got.error` names the repo and the link.
-        track("brain_signup_settled", { outcome: got.reason, duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+        track("brain_signup_settled", { outcome: got.reason, mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
         return null;
     }
     writeLink(repo, got.link);
-    console.error(`✓ brain connected to ${slug}`);
-    track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+    console.error(`✓ trail connected · ${slug} — your browser shows it building`);
+    track("brain_signup_settled", { outcome: "linked", mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
     return got.link;
 }
+/**
+ * The same sign-up when an agent runs the push, in two runs of one command.
+ *
+ * An agent shows the person nothing until a command exits, so the first run
+ * opens the sign-up page, saves the state in its link and exits at once, with
+ * a line telling the agent what to do next. The run after that finds the saved
+ * state and asks Trail for the trail it made, for up to AGENT_WAIT_MS, then
+ * carries on with the push. Still not signed up by then, it says so and the
+ * agent runs it again. Nothing about the repository is read or sent until the
+ * trail is linked.
+ */
+async function signUpWithoutTerminal(repo, slug) {
+    const startedAt = Date.now();
+    const settled = (outcome) => track("brain_signup_settled", { outcome, mode: "agent", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+    const pending = readPendingSignup(repo, slug, PENDING_SIGNUP_TTL_MS);
+    if (!pending) {
+        const state = newSignupState();
+        writePendingSignup(repo, { state, repo: slug, createdAt: Date.now() });
+        const url = signupUrl({ repo: slug, state });
+        track("brain_signup_opened", { mode: "agent" }, { repo });
+        openBrowser(url);
+        console.error(`· ${slug} has no trail yet — opened Trail's sign-up page in the browser:`);
+        console.error(`  ${url}`);
+        console.error("· nothing has been read or sent yet.");
+        console.error("· next: ask the user to sign up in the tab that just opened (or at the link above), then run `graft trail push` again straight away — it waits for the sign-up to finish and carries on with the push. Don't wait for them to reply first.");
+        settled("agent_link_opened");
+        process.exitCode = 1;
+        return null;
+    }
+    const url = signupUrl({ repo: slug, state: pending.state });
+    console.error(`· waiting up to ${Math.round(AGENT_WAIT_MS / 1000)} s for the sign-up for ${slug} to finish:`);
+    console.error(`  ${url}`);
+    const got = await waitForSignup(pending.state, apiBaseUrl());
+    if ("link" in got) {
+        clearPendingSignup(repo);
+        writeLink(repo, got.link);
+        console.error(`✓ trail connected · ${slug}`);
+        settled("linked");
+        return got.link;
+    }
+    if ("pending" in got) {
+        console.error("· not signed up yet — nothing has been read or sent.");
+        console.error("· next: run `graft trail push` again to keep waiting. The link above stays valid for about 15 minutes.");
+        settled("still_waiting");
+        process.exitCode = 1;
+        return null;
+    }
+    clearPendingSignup(repo);
+    console.error(`✗ ${got.error}`);
+    settled(got.reason);
+    process.exitCode = 1;
+    return null;
+}
 brain
     .command("connect")
     .description("Attach a brain to this repo and pull its rules")
@@ -1151,7 +1345,7 @@ brain
         // read the repo yet. Saying "0 rules" without saying why reads as a
         // failure, and the next step is the whole point.
         console.error("✓ attached this repo to the brain — it has no rules yet");
-        console.error("· run `graft brain push` to read this repository into it");
+        console.error("· run `graft trail push` to read this repository into it");
         return;
     }
     console.error(`✓ pulled ${res.ruleCount} rule(s) from ${parsed.brainId}`);
@@ -1160,129 +1354,274 @@ brain
 });
 brain
     .command("pull")
-    .description("Re-pull the attached brain's rules and rewrite the agent instruction files")
+    .description("Refresh the trail's rules and write every change you accepted in Trail into this repo's context files")
     .argument("[dir]", "target repo directory", ".")
-    .action(async (dir) => {
+    .option("--dry-run", "show what would change without writing anything or telling Trail")
+    .action(async (dir, opts) => {
+    await runTrailPullCommand(dir, opts);
+});
+/** `graft trail pull`, and `graft claude-md pull` which is now the same thing. */
+async function runTrailPullCommand(dir, opts) {
     const repo = resolve(dir);
-    const res = await pullBrain(repo, { home: homedir() });
-    if (!res) {
-        console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");
-        return;
-    }
-    if (res.warning) {
-        console.error(`⚠ ${res.warning}`);
+    const link = readLink(repo);
+    if (!link) {
+        console.error("✗ this repo has no trail yet — run graft trail push first");
         process.exitCode = 1;
         return;
     }
-    console.error(`✓ pulled ${res.ruleCount} rule(s)`);
-    for (const w of res.writes)
-        console.error(`✓ ${w.path} (${w.action})`);
-});
+    const stamp = readStamp(repo);
+    const wired = [...new Set([...(stamp?.hosts ?? []), ...wiredHostIds(repo)])];
+    const code = await runTrailPull(repo, link, { home: homedir(), wired, dryRun: opts.dryRun });
+    if (code !== 0)
+        process.exitCode = code;
+}
+/**
+ * The suggestions line after a build, cut to the files the wired agents read:
+ * `● 18 suggestions for the files claude, agents and cursor read`. Null when
+ * there are none to mention.
+ */
+function suggestionsLine(s, wired, again) {
+    if (!s)
+        return null;
+    let count = 0;
+    const kinds = new Set();
+    if (s.claudeMd > 0 && readByWired("claude_md", wired)) {
+        count += s.claudeMd;
+        kinds.add("claude_md");
+    }
+    if (s.files) {
+        for (const f of s.files) {
+            if (f.changes <= 0 || !readByWired(f.kind, wired))
+                continue;
+            count += f.changes;
+            kinds.add(f.kind);
+        }
+    }
+    else if (s.contextFiles > 0) {
+        // No per-file list from this Trail, so no way to cut it to the wired agents'
+        // files: the count is Trail's total.
+        count += s.contextFiles;
+        for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"])
+            kinds.add(k);
+    }
+    if (count === 0)
+        return null;
+    const readers = wired.length
+        ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))
+        : [];
+    const whose = readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files";
+    return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;
+}
 brain
     .command("push")
-    .description("Read THIS repo on your machine and build its brain — no GitHub App, works on private repos")
+    .description("Read THIS repo on your machine and build its trail — no GitHub App, works on private repos")
     .argument("[dir]", "target repo directory", ".")
     .option("--no-approve", "leave the mined rules as drafts for review")
     .option("--no-watch", "return as soon as the push is sent, without following the build")
+    .option("--verbose", "print each step's counts and every build stage as it finishes")
     .action(async (dir, opts) => {
     const repo = resolve(dir);
+    const tty = Boolean(process.stderr.isTTY);
+    const verbose = opts.verbose === true;
     // Resolved before the link, because an unlinked repo now signs up for a
-    // brain and Trail creates that brain FOR a named repository. Without a slug
+    // trail and Trail creates that trail FOR a named repository. Without a slug
     // there is nothing to name it after — and the digest builder would fail on
     // the same missing remote a moment later regardless.
     const here = repoSlugFromGit(repo);
     let link = readLink(repo);
+    // Set when this run opened the browser, which then sits on Trail's build
+    // page: the closing lines point at that tab instead of printing a new link.
+    let browserOpen = false;
     if (!link) {
         if (!here) {
-            console.error("✗ this directory has no GitHub `origin` remote — graft can only push a GitHub repository today");
+            console.error("✗ this directory has no GitHub origin remote — graft can only push a GitHub repository today");
             process.exitCode = 1;
             return;
         }
         const signedUp = await signUpForBrain(repo, `${here.owner}/${here.name}`);
         if (!signedUp) {
-            process.exitCode = 1;
+            if (!process.exitCode)
+                process.exitCode = 1;
             return;
         }
         link = signedUp;
+        browserOpen = true;
     }
-    // What the website said this brain is for. Checked BEFORE any reading, so
-    // standing in the wrong checkout costs a message rather than a brain full
+    // What the website said this trail is for. Checked BEFORE any reading, so
+    // standing in the wrong checkout costs a message rather than a trail full
     // of another repository's rules — a mistake that is silent afterwards,
     // because the rules look perfectly plausible, just not about your code.
     const expected = await fetchExpectedRepo(link);
     if (expected && here && !sameRepo(expected.slug, `${here.owner}/${here.name}`)) {
-        console.error(`✗ this brain is for ${expected.slug}, but you are in ${here.owner}/${here.name}`);
-        console.error(`  cd into ${expected.slug} and run this again, or attach a different brain here.`);
+        console.error(`✗ this trail is for ${expected.slug}, but you are in ${here.owner}/${here.name}`);
+        console.error(`  cd into ${expected.slug} and run this again, or attach a different trail here.`);
+        process.exitCode = 1;
+        return;
+    }
+    const ctx = pushContext(repo);
+    if (!ctx) {
+        console.error("✗ this directory has no GitHub origin remote — graft can only push a GitHub repository today");
         process.exitCode = 1;
         return;
     }
+    const firstPush = !expected || expected.ruleCount === 0;
+    // The instruction files and the newest pull requests go first, when the
+    // trail takes them: its suggestions start from those while the rest of the
+    // history is still being read here. In the background, from here on — the
+    // picker, the graph build and the full read all happen while it goes, and
+    // the full read reuses every GitHub request it made.
+    let early = Promise.resolve();
+    if (expected?.earlyUpload) {
+        early = (async () => {
+            const first = await buildEarlyDigest(repo, { context: ctx });
+            if (!first)
+                return;
+            const ok = await pushEarlyDigest(link, first.digest, fetch, { gzip: expected.gzipUpload });
+            if (ok && verbose)
+                console.error("· sent the instruction files and the newest pull requests first, so suggestions start now");
+        })().catch(() => undefined);
+    }
+    // A repo graft was never set up in gets `graft init` first. Same picker as
+    // init: it is how someone agrees to what gets written, so a
+    // non-interactive push only says what to run.
+    if (wiredHostIds(repo).length === 0) {
+        if (process.stdin.isTTY && tty) {
+            console.error("· graft isn't set up here yet — pick the agents your team uses:");
+            await runInitCommand(repo, { build: true, mcp: true, hooks: true, statusline: true, global: true, verbose }, { epilogue: false, push: !verbose });
+        }
+        else {
+            console.error("· graft isn't set up here — run graft init so your agents read these rules");
+        }
+    }
     // The graph is what symbol anchors are resolved against, so a rule mined
     // here can later go stale on its own. Without one the ingest still works;
     // its rules simply govern the repo rather than a symbol in it.
     const graph = loadGraphCached(contextDirFor(repo, program.opts().dir));
     if (!graph)
-        console.error("· no graph yet — run `graft build` first so rules can be anchored to symbols");
-    const label = expected?.slug ?? (here ? `${here.owner}/${here.name}` : "this repository");
-    console.error(`· reading ${label} — commit messages, pull-request discussion and the docs in the tree.`);
-    console.error("  No file contents leave this machine.");
-    const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false });
+        console.error("· no graph yet — run graft build so rules can be anchored to symbols");
+    const reading = startSpinner(`reading ${ctx.owner}/${ctx.name} · commits, pull-request discussion and the docs in the tree`);
+    const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, context: ctx });
     if ("error" in built) {
+        reading.stop();
         console.error(`✗ ${built.error}`);
         process.exitCode = 1;
         return;
     }
     const d = built.digest;
+    reading.update("sending it to Trail");
+    await early;
+    const sent = await pushDigest(link, d, fetch, uploadCaps(expected));
+    reading.stop();
     if (built.warning)
         console.error(`⚠ ${built.warning}`);
-    console.error(`· ${d.commits.length} commits, ${d.threads.length} discussions, ${d.symbols.length} symbols, ${d.sources.length} stated sources`);
-    const sent = await pushDigest(link, d);
     if ("error" in sent) {
         console.error(`✗ ${sent.error}`);
         process.exitCode = 1;
         return;
     }
-    const brainLabel = expected?.brainName ? `“${expected.brainName}”` : link.brainId;
-    console.error(`✓ sent ${d.owner}/${d.name} to ${brainLabel}`);
+    const fmt = (x) => x.toLocaleString("en-US");
+    const trailLabel = expected?.brainName ? `“${expected.brainName}”` : `${d.owner}/${d.name}`;
+    console.error(`✓ sent ${fmt(d.commits.length)} commits and ${fmt(d.threads.length)} discussions to ${trailLabel} · no file contents left this machine`);
+    if (verbose)
+        console.error(`  ${fmt(d.symbols.length)} symbols, ${fmt(d.sources.length)} stated sources`);
+    const buildPage = brainUrl(link.brainId);
     // Held rather than handed back. Everything above this line succeeded even
     // in the runs that end badly: the push lands, and then the miner fails —
-    // which is where roughly a third of production's repo brains die. Returning
+    // which is where roughly a third of production's repo trails die. Returning
     // the prompt here is what made that invisible from this side, on CI and
     // over SSH permanently so. `--no-watch` is for a caller that genuinely
-    // wants fire-and-forget, and it prints the old two lines instead.
+    // wants fire-and-forget.
     if (opts.watch === false) {
-        console.error("· it is being mined into rules now — a few minutes. Watch it finish in your browser.");
-        console.error("  The rules reach this repo on their own; nothing else to run.");
+        console.error("· building now — the rules reach this repo on their own; watch it at");
+        console.error(`  ${buildPage}`);
         return;
     }
-    console.error("· building the brain — Ctrl-C detaches, it keeps going without you");
-    const outcome = await watchBuild(link);
+    const live = tty && !verbose;
+    if (!live)
+        console.error("· building the trail");
+    const spinner = live ? startSpinner("building the trail · reaching the repository · Ctrl-C detaches") : null;
+    let last = null;
+    // Ctrl-C detaches: the work is server-side, and killing a watcher must
+    // never look like killing the build.
+    const onSigint = () => {
+        spinner?.stop();
+        console.error("· detached — the build keeps going; watch it at");
+        console.error(`  ${buildPage}`);
+        process.exit(130);
+    };
+    process.once("SIGINT", onSigint);
+    const outcome = await watchBuild(link, {
+        events: expected?.events === true,
+        stageLines: !live,
+        write: (line) => (spinner ? spinner.print(line) : console.error(line)),
+        onState: (view, repoState) => {
+            last = repoState;
+            spinner?.update(`building the trail · ${DOING_LABEL[currentStage(view)]} · Ctrl-C detaches`);
+        },
+    });
+    process.off("SIGINT", onSigint);
+    spinner?.stop();
+    const ruleCount = rulesSoFar(last);
+    const rules = `${fmt(ruleCount)} rule${ruleCount === 1 ? "" : "s"}`;
+    const wired = [...new Set([...(readStamp(repo)?.hosts ?? []), ...wiredHostIds(repo)])];
+    const closing = () => {
+        const line = suggestionsLine(last?.suggestions, wired, !firstPush);
+        if (!line)
+            return;
+        if (browserOpen) {
+            console.error(`${line} — they are in the Trail tab in your browser`);
+            console.error(`  ${reviewUrl(link.brainId)}`);
+        }
+        else {
+            console.error(line);
+            console.error(`  review: ${reviewUrl(link.brainId)}`);
+        }
+    };
     if (outcome === "completed") {
-        console.error("✓ the brain is built — its rules reach this repo on their own; nothing else to run");
+        console.error(`✓ trail built · ${rules}, reaching this repo on their own`);
+        closing();
         return;
     }
     // The ordinary ending for anything but a small repository. The history is
     // mined in slices, and the prompt comes back on the first of them: mining is
     // the part that fails and it has now succeeded, and the rest is filing,
-    // which is minutes of reliable work nobody gains by watching. The rules
-    // already in the brain are already being served.
+    // which is minutes of reliable work nobody gains by watching.
     if (outcome === "building") {
-        console.error("✓ the brain has its first rules — they reach this repo on their own; nothing else to run");
-        console.error("  The rest of the history is still being read. Watch it fill in your browser.");
+        console.error(firstPush
+            ? `✓ trail has its first ${rules} · they reach this repo on their own`
+            : `✓ trail updated · ${rules}, reaching this repo on their own`);
+        closing();
         return;
     }
     if (outcome === "failed") {
         // A non-zero exit, unlike every other ending here: this is the one case
-        // where the work did not produce a brain, and a CI step that ran the push
-        // should hear about it the way it hears about any other failure.
-        console.error("  Nothing was lost — the brain is still there. Run `graft brain push` again to retry the read.");
+        // where the work did not produce a trail, and a CI step that ran the push
+        // should hear about it the way it hears about any other failure. The
+        // watcher has already printed where it stopped and why.
         process.exitCode = 1;
         return;
     }
     if (outcome === "unreachable") {
-        console.error("· could not reach Trail to follow the build — it is still running. Watch it finish in your browser.");
-        return;
+        console.error("· lost touch with Trail — the build keeps going; watch it at the link below");
     }
-    console.error("· still building after 15 minutes — it has not failed, it is just long. Watch it finish in your browser.");
+    else {
+        console.error("· still building after 15 minutes — not failed, just long; watch it at the link below");
+    }
+    console.error(`  ${buildPage}`);
+});
+// `graft claude-md pull` is `graft trail pull` now: the CLAUDE.md changes are
+// the first half of what that writes. Kept so the old name keeps working.
+const claudeMd = program
+    .command("claude-md")
+    .description("The CLAUDE.md changes this repo's trail suggested (now part of graft trail pull)");
+claudeMd
+    .command("pull")
+    .description("Same as graft trail pull: write every change you accepted in Trail into this repo")
+    .argument("[dir]", "target repo directory", ".")
+    .option("--dry-run", "show what would change without writing anything or telling Trail")
+    .action(async (dir, opts) => {
+    console.error("· graft claude-md pull is now part of graft trail pull — running that");
+    await runTrailPullCommand(dir, opts);
 });
 brain
     .command("status")
@@ -1303,7 +1642,7 @@ brain
         return;
     }
     if (!link) {
-        console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");
+        console.error("· no brain attached — run `graft trail connect <brainId>:<token>`");
         return;
     }
     console.error(`brain ${link.brainId}`);
@@ -1329,7 +1668,7 @@ brain
     clearLink(resolve(dir));
     console.error(`✓ detached the brain from ${repo}`);
 });
-program.parseAsync().catch((err) => {
+program.parseAsync(withLegacyNames(process.argv)).catch((err) => {
     console.error(err instanceof Error ? err.message : err);
     process.exit(1);
 });