Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(trail): chunked upload, live watch and pull for all context files (#493)
anirudhkumar-nanonetse91e194df470
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 3736ac0d..d00fc73a 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -47,7 +47,7 @@ The events:| `build_failed` | `stage`, `code` — both fixed enums | A build throws || `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command || `brain_signup_opened` | — | `graft trail push` on a repo with no brain opens your browser to make one |-| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`), `duration_bucket` | That handoff ends, one way or the other |+| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`/`stopped`), `duration_bucket` | That handoff ends, one way or the other || `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |Two rules govern every value above, and both are enforced in code rather than bydiff --git a/src/app/history.ts b/src/app/history.tsindex b2677e06..71e13e83 100644--- a/src/app/history.ts+++ b/src/app/history.ts@@ -127,11 +127,48 @@ export function readCommits(root: string, max = MAX_COMMITS): HistoryCommit[] {const MAX_THREADS = 200;const MAX_COMMENT_PAGES = 3;/** How many threads' comments are fetched at once. Two requests per pull- * request, so this is the real cost of a repository read; 8 keeps it quick- * without crowding an installation's rate limit. */-const THREAD_FETCH_CONCURRENCY = 8;+ * request, so this is the real cost of a repository read. A pool of 24 (so at+ * most 48 requests in flight) stays well under GitHub's secondary limit on+ * concurrent requests, and a slow thread no longer holds up the seven that+ * happened to share its batch. */+export const THREAD_FETCH_CONCURRENCY = 24;-interface PullListItem {+/**+ * What one push has already asked GitHub, shared between its reads.+ *+ * The early upload reads the newest pull requests and the full read reads them+ * again as part of the 200. Promises rather than results, so a full read that+ * starts while the early one is still in flight waits on the same request+ * instead of sending a second — and threads with no discussion are remembered+ * too, which a map of finished threads could not say.+ */+export interface ThreadReadCache {+ /** Pages of the closed-pull-request list, by page number. */+ pages: Map<number, Promise<PullListItem[] | null>>;+ /** One pull request's discussion, by number; null when it had none. */+ threads: Map<number, Promise<HistoryThread | null>>;+}++export function newThreadReadCache(): ThreadReadCache {+ return { pages: new Map(), threads: new Map() };+}++/** Run `fn` over `items` with at most `limit` in flight, results in input order. */+export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {+ const out = new Array<R>(items.length);+ let next = 0;+ const worker = async () => {+ for (;;) {+ const i = next++;+ if (i >= items.length) return;+ out[i] = await fn(items[i]!, i);+ }+ };+ await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));+ return out;+}++export interface PullListItem {number?: number;title?: string;body?: string | null;@@ -172,53 +209,79 @@ export async function readThreads(// Threads already read (the early upload's newest ones), reused rather than// fetched a second time.known: ReadonlyMap<number, HistoryThread> = new Map(),+ // Everything this push has already asked GitHub, in flight or finished. See+ // ThreadReadCache; a fresh one when the caller has nothing to share.+ cache: ThreadReadCache = newThreadReadCache(),): Promise<HistoryThread[]> {const headers = ghHeaders(token);+ const readPage = (page: number): Promise<PullListItem[] | null> => {+ const cached = cache.pages.get(page);+ if (cached) return cached;+ const pending = (async () => {+ const res = await fetchImpl(+ `${api}/repos/${owner}/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`,+ { headers },+ );+ if (!res.ok) return null;+ const batch = JSON.parse(await res.text()) as PullListItem[];+ return Array.isArray(batch) ? batch : null;+ })();+ // A failed page is forgotten, so the next read asks again rather than+ // inheriting one blip for the rest of the push.+ pending.catch(() => cache.pages.delete(page));+ cache.pages.set(page, pending);+ return pending;+ };+const pulls: PullListItem[] = [];// 100 per page, up to the cap. Sorted by GitHub as most-recently-updated,// which is the right window: rules decided two years ago that still hold get// restated in newer threads, and ones that do not are usually superseded.for (let page = 1; pulls.length < max && page <= Math.ceil(max / 100); page++) {- const res = await fetchImpl(- `${api}/repos/${owner}/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`,- { headers },- );- if (!res.ok) break;- const batch = JSON.parse(await res.text()) as PullListItem[];- if (!Array.isArray(batch) || batch.length === 0) break;+ const batch = await readPage(page);+ if (!batch || batch.length === 0) break;pulls.push(...batch);}- const candidates = pulls.filter((p): p is PullListItem & { number: number } => typeof p.number === "number").slice(0, max);+ // Deduplicated: a pull request updated between two page reads moves up the+ // list and would otherwise be read, and sent, twice.+ const seenNumbers = new Set<number>();+ const candidates = pulls+ .filter((p): p is PullListItem & { number: number } => typeof p.number === "number")+ .filter((p) => !seenNumbers.has(p.number) && (seenNumbers.add(p.number), true))+ .slice(0, max);- // Bounded concurrency rather than one at a time: two requests per pull- // request over 200 of them is 400 sequential round trips, which is minutes of- // a person waiting on a progress screen.- const threads: HistoryThread[] = [];- for (let i = 0; i < candidates.length; i += THREAD_FETCH_CONCURRENCY) {- const slice = candidates.slice(i, i + THREAD_FETCH_CONCURRENCY);- const fetched = await Promise.all(- slice.map(async (p) => {- const seen = known.get(p.number);- if (seen) return seen;- const [issueComments, reviewComments] = await Promise.all([- readComments(`${api}/repos/${owner}/${repo}/issues/${p.number}/comments`, headers, fetchImpl),- readComments(`${api}/repos/${owner}/${repo}/pulls/${p.number}/comments`, headers, fetchImpl),- ]);- const comments = [...issueComments, ...reviewComments];- if (comments.length === 0) return null;- return {- number: p.number,- title: (p.title ?? "").trim(),- body: (p.body ?? "").trim(),- mergeSha: (p.merge_commit_sha ?? "").trim(),- comments,- } satisfies HistoryThread;- }),- );- for (const t of fetched) if (t) threads.push(t);- }+ const readThread = (p: PullListItem & { number: number }): Promise<HistoryThread | null> => {+ const seen = known.get(p.number);+ if (seen) return Promise.resolve(seen);+ const cached = cache.threads.get(p.number);+ if (cached) return cached;+ const pending = (async () => {+ const [issueComments, reviewComments] = await Promise.all([+ readComments(`${api}/repos/${owner}/${repo}/issues/${p.number}/comments`, headers, fetchImpl),+ readComments(`${api}/repos/${owner}/${repo}/pulls/${p.number}/comments`, headers, fetchImpl),+ ]);+ const comments = [...issueComments, ...reviewComments];+ if (comments.length === 0) return null;+ return {+ number: p.number,+ title: (p.title ?? "").trim(),+ body: (p.body ?? "").trim(),+ mergeSha: (p.merge_commit_sha ?? "").trim(),+ comments,+ } satisfies HistoryThread;+ })();+ pending.catch(() => cache.threads.delete(p.number));+ cache.threads.set(p.number, pending);+ return pending;+ };++ // A pool rather than one at a time: two requests per pull request over 200+ // of them is 400 sequential round trips, which is minutes of a person+ // waiting on a progress screen.+ const fetched = await mapPool(candidates, THREAD_FETCH_CONCURRENCY, readThread);+ const threads: HistoryThread[] = fetched.filter((t): t is HistoryThread => t !== null);// Most-discussed first, because the digest renderer spends its budget in this// order and a twenty-comment thread contains an argument while a one-commentdiff --git a/src/app/sources.ts b/src/app/sources.tsindex a4365558..48017e10 100644--- a/src/app/sources.ts+++ b/src/app/sources.ts@@ -87,11 +87,130 @@ export function readAgentInstructions(root: string): HistorySource[] {".github/copilot-instructions.md",".windsurf/rules/graft.md",...filesIn(root, ".cursor/rules", (n) => n.endsWith(".mdc") || n.endsWith(".md")),+ // The same files one folder down: a monorepo keeps its frontend's rules in+ // web/CLAUDE.md, and those are as deliberate as the root's.+ ...folderInstructionFiles(root),+ // Skills a team wrote for its agents. Graft's own is left out for the same+ // reason its managed blocks are: the brain must not learn graft from graft.+ ...skillFiles(root),];const out: HistorySource[] = [];+ const seen = new Set<string>();for (const rel of candidates) {+ const key = rel.replace(/\\/g, "/");+ if (seen.has(key)) continue;+ seen.add(key);const text = stripManagedBlocks(readText(root, rel) ?? "");- if (text.trim()) out.push({ kind: "agent_instructions", path: rel, text });+ if (text.trim()) out.push({ kind: "agent_instructions", path: key, text });+ }+ return out;+}++/** Instruction files below the root that are worth reading as instructions. */+const FOLDER_INSTRUCTION_NAMES = new Set(["CLAUDE.md", "AGENTS.md"]);+/** How deep below the root a folder instruction file may sit (a/b/c/d/CLAUDE.md). */+const MAX_FOLDER_DEPTH = 4;+/** Most folder instruction files, and most skills, carried per push. */+export const MAX_FOLDER_FILES = 30;+export const MAX_SKILL_FILES = 30;++/** Directories never searched for instruction files: dependencies, build+ * output, graft's own cache. Dot-directories are skipped as a class. */+const SKIP_INSTRUCTION_DIRS = new Set([+ "node_modules",+ "dist",+ "build",+ "out",+ "vendor",+ "graft",+ "target",+ "coverage",+ "__pycache__",+ "venv",+ "bower_components",+]);++function skippedSegment(seg: string): boolean {+ return seg.startsWith(".") || SKIP_INSTRUCTION_DIRS.has(seg);+}++/**+ * `**\/CLAUDE.md` and `**\/AGENTS.md` below the root, shallowest first.+ *+ * Asked of git first, because git already knows what the repository ignores:+ * a CLAUDE.md inside an ignored folder is someone's scratch, not the team's.+ * The walk is the fallback for a checkout git cannot answer for.+ */+export function folderInstructionFiles(root: string, max = MAX_FOLDER_FILES): string[] {+ const keep = (rel: string): boolean => {+ const parts = rel.split("/");+ const name = parts[parts.length - 1] ?? "";+ const dirs = parts.slice(0, -1);+ if (!FOLDER_INSTRUCTION_NAMES.has(name)) return false;+ if (dirs.length === 0 || dirs.length > MAX_FOLDER_DEPTH) return false;+ return !dirs.some(skippedSegment);+ };+ let found: string[] | null = null;+ const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*CLAUDE.md", "*AGENTS.md"]);+ if (listed !== null) found = [...new Set(listed.split("\0").filter(Boolean))].filter(keep);+ if (found === null) found = walkFor(root, keep);+ const depth = (p: string) => p.split("/").length;+ return found+ .filter((rel) => existsSync(join(root, rel)))+ .sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))+ .slice(0, max);+}++/** The filesystem walk behind folderInstructionFiles, for a tree git cannot list. */+function walkFor(root: string, keep: (rel: string) => boolean): string[] {+ const out: string[] = [];+ const visit = (rel: string, depth: number) => {+ if (depth > MAX_FOLDER_DEPTH) return;+ let names: string[];+ try {+ names = readdirSync(join(root, rel));+ } catch {+ return;+ }+ for (const name of names) {+ const child = rel ? `${rel}/${name}` : name;+ let isDir = false;+ try {+ isDir = statSync(join(root, child)).isDirectory();+ } catch {+ continue;+ }+ if (isDir) {+ if (!skippedSegment(name)) visit(child, depth + 1);+ } else if (depth > 0 && keep(child)) {+ out.push(child);+ }+ }+ };+ visit("", 0);+ return out;+}++/** `.claude/skills/<name>/SKILL.md`, graft's own skill excluded. */+export function skillFiles(root: string, max = MAX_SKILL_FILES): string[] {+ const dir = join(root, ".claude", "skills");+ let names: string[];+ try {+ names = readdirSync(dir).sort();+ } catch {+ return [];+ }+ const out: string[] = [];+ for (const name of names) {+ if (name === "graft" || name.startsWith(".")) continue;+ const rel = `.claude/skills/${name}/SKILL.md`;+ try {+ if (!statSync(join(root, rel)).isFile()) continue;+ } catch {+ continue;+ }+ out.push(rel);+ if (out.length >= max) break;}return out;}diff --git a/src/brain/claude-md.ts b/src/brain/claude-md.tsindex 0aeb132a..8267861e 100644--- a/src/brain/claude-md.ts+++ b/src/brain/claude-md.ts@@ -1,6 +1,7 @@/**- * `graft claude-md pull`: write the CLAUDE.md changes accepted in Trail into- * this checkout's instruction file.+ * The CLAUDE.md half of `graft trail pull` (and of `graft claude-md pull`, its+ * old name): write the CLAUDE.md changes accepted in Trail into this checkout's+ * instruction file.** Trail compares the repository's CLAUDE.md with what its history says and* suggests edits and new sections; a person accepts some of them on the brain's@@ -50,7 +51,7 @@ export interface ApplyResult {export async function fetchAcceptedChanges(link: BrainLink,fetchImpl: typeof fetch = fetch,-): Promise<ClaudeMdPull | { error: string }> {+): Promise<ClaudeMdPull | { error: string; unsupported?: boolean }> {const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/claude-md`;try {const res = await fetchImpl(url, {@@ -59,7 +60,7 @@ export async function fetchAcceptedChanges(});const body = await res.text();if (res.status === 404 || res.status === 503) {- return { error: "this brain has no CLAUDE.md suggestions yet — its Trail may be older than the feature" };+ return { error: "this trail has no CLAUDE.md suggestions yet — its Trail may be older than the feature", unsupported: true };}if (!res.ok) return { error: `Trail refused the pull: ${res.status} ${body.slice(0, 200)}` };const parsed = JSON.parse(body) as Partial<ClaudeMdPull>;diff --git a/src/brain/context-files.ts b/src/brain/context-files.tsnew file mode 100644index 00000000..c727c074--- /dev/null+++ b/src/brain/context-files.ts@@ -0,0 +1,281 @@+/**+ * `graft trail pull`, for every context file rather than only the root CLAUDE.md.+ *+ * Trail suggests changes to the files a repository hands its coding agents —+ * AGENTS.md, a folder's own CLAUDE.md, Cursor rules, Claude skills — and a+ * person accepts some of them. This fetches the accepted ones and writes them.+ *+ * Edits and new sections go through the same line-by-line patcher as the root+ * CLAUDE.md (see claude-md.ts), so everything a change does not name comes back+ * byte for byte. A `create` carries a whole file, and it is never allowed to+ * overwrite a file someone wrote here: an existing file with other content is a+ * conflict to report, unless graft itself owns that file. A `replace` (how a+ * Cursor rule is edited) carries the whole new file and the whole file it was+ * computed against, and is written only while the file here is still that one.+ */+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";+import { applyChanges, type ClaudeMdChange } from "./claude-md.js";+import { baseUrlFor, type BrainLink } from "./link.js";++export type ContextFileKind = "agents_md" | "folder_claude_md" | "cursor_rule" | "skill";++/** One accepted change to one context file. */+export interface ContextFileChange {+ id: string;+ kind: "edit" | "add" | "create" | "replace";+ heading?: string;+ after_heading?: string;+ find?: string;+ /** edit/add: as in claude-md.ts. create/replace: the whole file. For+ * replace, `find` is the whole file the suggestion was computed against. */+ text: string;+ reason?: string;+}++export interface ContextFile {+ kind: ContextFileKind | string;+ path: string;+ exists?: boolean;+ managed_by_graft?: boolean;+ changes: ContextFileChange[];+}++export interface ContextFilesPull {+ head_sha: string;+ files: ContextFile[];+}++/**+ * Which picked agents read a file of this kind. A file whose readers were not+ * picked is neither listed nor written: `graft init` is where someone said which+ * agents this repo is for, and a pull must not quietly add files for others.+ */+const READERS: Record<string, string[]> = {+ claude_md: ["claude"],+ folder_claude_md: ["claude"],+ skill: ["claude"],+ agents_md: ["agents", "hermes", "antigravity"],+ cursor_rule: ["cursor"],+};++/** The kind of a context file, from its path — for the root CLAUDE.md pull,+ * which names a path but no kind. */+export function kindForPath(path: string): string {+ const p = path.replace(/\\/g, "/");+ const name = p.split("/").pop() ?? "";+ if (name === "CLAUDE.md") return p.includes("/") ? "folder_claude_md" : "claude_md";+ if (name === "AGENTS.md") return "agents_md";+ if (p.startsWith(".cursor/rules/")) return "cursor_rule";+ if (p.startsWith(".claude/skills/")) return "skill";+ return "";+}++/**+ * Whether a file of `kind` is for one of the `wired` agents. Everything passes+ * when nothing is wired — there is no choice to respect — and so does a kind+ * graft does not know, rather than dropping what Trail sent.+ */+export function readByWired(kind: string, wired: readonly string[]): boolean {+ if (wired.length === 0) return true;+ const readers = READERS[kind];+ if (!readers) return true;+ return readers.some((r) => wired.includes(r));+}++/** The agents among `wired` that read a file of `kind`. */+export function readersOf(kind: string, wired: readonly string[]): string[] {+ const readers = READERS[kind] ?? [];+ return wired.filter((w) => readers.includes(w));+}++/** GET /api/public/brains/:id/context-files. `unsupported` on a 404: an older Trail. */+export async function fetchContextFiles(+ link: BrainLink,+ fetchImpl: typeof fetch = fetch,+): Promise<ContextFilesPull | { unsupported: true } | { error: string }> {+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/context-files`;+ try {+ const res = await fetchImpl(url, {+ headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },+ signal: AbortSignal.timeout(15_000),+ });+ const body = await res.text();+ if (res.status === 404) return { unsupported: true };+ if (!res.ok) return { error: `Trail refused the pull: ${res.status} ${body.slice(0, 200)}` };+ const parsed = JSON.parse(body) as Partial<ContextFilesPull>;+ const files = Array.isArray(parsed.files) ? parsed.files : [];+ return {+ head_sha: String(parsed.head_sha ?? ""),+ files: files+ .filter((f) => f && typeof f.path === "string")+ .map((f) => ({ ...f, changes: Array.isArray(f.changes) ? f.changes : [] })),+ };+ } catch (e) {+ return { error: `could not reach Trail: ${e instanceof Error ? e.message : e}` };+ }+}++/** POST /api/public/brains/:id/context-files/applied, 100 ids per request. */+export async function markContextFilesApplied(link: BrainLink, ids: string[], fetchImpl: typeof fetch = fetch): Promise<boolean> {+ if (ids.length === 0) return true;+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/context-files/applied`;+ try {+ for (let i = 0; i < ids.length; i += 100) {+ const res = await fetchImpl(url, {+ method: "POST",+ headers: {+ authorization: `Bearer ${link.token}`,+ "content-type": "application/json",+ accept: "application/json",+ },+ body: JSON.stringify({ ids: ids.slice(i, i + 100) }),+ signal: AbortSignal.timeout(15_000),+ });+ if (!res.ok) return false;+ }+ return true;+ } catch {+ return false;+ }+}++/** What a pull will do (or did) to one file. */+export interface FilePlan {+ /** Repo-relative, forward slashes. */+ path: string;+ /** M: an existing file changes. A: a new file. "": nothing to write. */+ status: "M" | "A" | "";+ /** The file's new text, when status is set. */+ text?: string;+ written: ContextFileChange[];+ /** Already there: counts as applied, nothing to write. */+ present: ContextFileChange[];+ skipped: Array<{ change: ContextFileChange; why: string }>;+}++/**+ * The repo-relative form of a path Trail sent, or null when it points+ * anywhere but a file inside this checkout. Trail is trusted to suggest text,+ * not to choose where on this machine it lands.+ */+export function safeRelPath(root: string, path: string): string | null {+ const raw = path.replace(/\\/g, "/").trim();+ if (!raw || isAbsolute(raw) || /^[a-zA-Z]:/.test(raw)) return null;+ const parts = raw.split("/");+ if (parts.some((p) => p === ".." || p === "")) return null;+ if (parts[0] === ".git") return null;+ const abs = resolve(root, normalize(raw));+ const rel = relative(resolve(root), abs);+ if (!rel || rel.startsWith("..") || isAbsolute(rel)) return null;+ return rel.split(sep).join("/");+}++/**+ * Work out one file's changes against what is on disk. Pure but for reading+ * the file, so the command, the dry run and the tests share it.+ */+export function planContextFile(root: string, file: ContextFile): FilePlan {+ const rel = safeRelPath(root, file.path);+ const plan: FilePlan = { path: rel ?? file.path, status: "", written: [], present: [], skipped: [] };+ if (!rel) {+ for (const c of file.changes) plan.skipped.push({ change: c, why: "the path points outside this repo" });+ return plan;+ }+ const abs = join(root, rel);+ const existed = existsSync(abs);+ let original = "";+ if (existed) {+ try {+ original = readFileSync(abs, "utf8");+ } catch {+ for (const c of file.changes) plan.skipped.push({ change: c, why: "the file here could not be read" });+ return plan;+ }+ }++ let text = original;+ let changed = false;+ // Whole files first; the edits and sections after them may be relative to one.+ for (const c of file.changes.filter((x) => x.kind === "create")) {+ const want = c.text.replace(/\r\n/g, "\n");+ const have = text.replace(/\r\n/g, "\n");+ if (!existed && !changed) {+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;+ changed = true;+ plan.written.push(c);+ } else if (have.trimEnd() === want.trimEnd()) {+ plan.present.push(c);+ } else if (file.managed_by_graft) {+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;+ changed = true;+ plan.written.push(c);+ } else {+ plan.skipped.push({ change: c, why: "a file with other content is already there" });+ }+ }++ // Whole-file replacements, guarded by the text they were computed against.+ const same = (a: string, b: string) => a.replace(/\r\n/g, "\n").trimEnd() === b.replace(/\r\n/g, "\n").trimEnd();+ for (const c of file.changes.filter((x) => x.kind === "replace")) {+ if (same(text, c.text)) {+ plan.present.push(c);+ } else if (same(text, c.find ?? "") && (existed || changed || (c.find ?? "").trim() === "")) {+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;+ changed = true;+ plan.written.push(c);+ } else {+ plan.skipped.push({ change: c, why: "the file changed here since Trail read it" });+ }+ }++ const patches = file.changes.filter((x) => x.kind === "edit" || x.kind === "add");+ if (patches.length > 0) {+ // A file that is not here yet is an empty one: an edit to a section of it+ // becomes that section, so the change lands rather than being skipped for+ // a heading nobody could have written.+ const fresh = !existed && !changed;+ const r = applyChanges(+ text,+ patches.map(+ (c) =>+ ({+ ...c,+ heading: c.heading ?? "",+ kind: fresh && c.kind === "edit" ? "add" : c.kind,+ ...(fresh && c.kind === "edit" ? { after_heading: "" } : {}),+ }) as ClaudeMdChange,+ ),+ );+ const byId = new Map(patches.map((c) => [c.id, c]));+ for (const w of r.written) plan.written.push(byId.get(w.id)!);+ for (const p of r.present) plan.present.push(byId.get(p.id)!);+ for (const s of r.skipped) plan.skipped.push({ change: byId.get(s.change.id)!, why: s.why });+ if (r.written.length > 0) {+ text = r.text;+ changed = true;+ }+ }++ if (changed && text !== original) {+ plan.status = existed ? "M" : "A";+ plan.text = text;+ }+ return plan;+}++/** Write a planned file, making its folder when it is new. */+export function writePlannedFile(root: string, plan: FilePlan): void {+ if (!plan.status || plan.text === undefined) return;+ const abs = join(root, plan.path);+ mkdirSync(dirname(abs), { recursive: true });+ writeFileSync(abs, plan.text);+}++/** `+ Money · ~ Commands` — a new section is +, an edited one ~, a whole file nothing. */+export function changeSummary(changes: Array<{ kind: string; heading?: string }>): string {+ return changes+ .filter((c) => c.kind === "add" || c.kind === "edit")+ .map((c) => `${c.kind === "add" ? "+" : "~"} ${c.heading ?? ""}`.trim())+ .join(" · ");+}diff --git a/src/brain/pull.ts b/src/brain/pull.tsnew file mode 100644index 00000000..6c62d53e--- /dev/null+++ b/src/brain/pull.ts@@ -0,0 +1,165 @@+/**+ * `graft trail pull`: one command for both things a trail hands this repo.+ *+ * First the rules, refreshed into graft's own blocks in the agent files (what+ * `graft trail pull` always did). Then every change accepted in Trail, for every+ * context file the picked agents read — the root CLAUDE.md (what `graft+ * claude-md pull` did, and still does, as an alias of this), and then AGENTS.md,+ * folder CLAUDE.md files, Cursor rules and skills when Trail serves them.+ *+ * Files for agents that were not picked are neither listed nor written.+ */+import { isAbsolute, relative } from "node:path";+import { connectBrain, type ConnectResult } from "./connect.js";+import { fetchAcceptedChanges, markApplied } from "./claude-md.js";+import {+ changeSummary,+ fetchContextFiles,+ kindForPath,+ markContextFilesApplied,+ planContextFile,+ readByWired,+ writePlannedFile,+ type ContextFile,+ type FilePlan,+} from "./context-files.js";+import type { BrainLink } from "./link.js";+import { reviewUrl } from "./signup.js";++export interface PullOptions {+ home: string;+ /** The agents this repo is wired for; empty means no choice was recorded. */+ wired: string[];+ dryRun?: boolean;+ fetchImpl?: typeof fetch;+ write?: (line: string) => void;+}++/** Repo-relative, forward slashes, for printing. */+function show(repo: string, path: string): string {+ const rel = isAbsolute(path) ? relative(repo, path) : path;+ return rel.split("\\").join("/");+}++/** The rules line: how many, and which files they are in. */+export function rulesLine(repo: string, res: ConnectResult): string | null {+ if (res.warning) return `⚠ ${res.warning}`;+ if (res.ruleCount === 0) return "· the trail has no rules yet — run graft trail push to read this repo into it";+ const n = res.ruleCount.toLocaleString("en-US");+ const where = res.writes.map((w) => show(repo, w.path)).join(", ");+ const rules = `${n} rule${res.ruleCount === 1 ? "" : "s"}`;+ if (!where) return `✓ ${rules} pulled · no instruction file to write them into — graft ask still carries them`;+ if (res.writes.every((w) => w.action === "unchanged")) return `✓ rules already current · ${n} in ${where}`;+ return `✓ ${rules} refreshed in ${where}`;+}++/** Everything the pull will write, file by file, with where each change came from. */+interface Planned {+ plan: FilePlan;+ source: "claude-md" | "context-files";+}++/**+ * Run the pull. Returns the exit code; every line goes through `write`.+ */+export async function runTrailPull(repo: string, link: BrainLink, opts: PullOptions): Promise<number> {+ const write = opts.write ?? ((l: string) => console.error(l));+ const fetchImpl = opts.fetchImpl ?? fetch;+ let code = 0;++ // 1. The rules. Skipped on a dry run, which writes nothing at all.+ if (!opts.dryRun) {+ const res = await connectBrain(repo, link, {+ home: opts.home,+ ids: opts.wired.length > 0 ? opts.wired : undefined,+ fetchImpl,+ });+ const line = rulesLine(repo, res);+ if (line) write(line);+ if (res.warning) code = 1;+ }++ // 2. Accepted changes: the root CLAUDE.md, then every other context file.+ const planned: Planned[] = [];+ let accepted = 0;++ const md = await fetchAcceptedChanges(link, fetchImpl);+ if ("error" in md) {+ if (!md.unsupported) {+ write(`✗ ${md.error}`);+ code = 1;+ }+ } else if (md.changes.length > 0) {+ const file: ContextFile = { kind: kindForPath(md.path || "CLAUDE.md"), path: md.path || "CLAUDE.md", changes: md.changes };+ if (readByWired(file.kind, opts.wired)) {+ accepted += file.changes.length;+ planned.push({ plan: planContextFile(repo, file), source: "claude-md" });+ }+ }++ const ctx = await fetchContextFiles(link, fetchImpl);+ if ("error" in ctx) {+ write(`✗ ${ctx.error}`);+ code = 1;+ } else if (!("unsupported" in ctx)) {+ for (const file of ctx.files) {+ if (file.changes.length === 0 || !readByWired(file.kind, opts.wired)) continue;+ accepted += file.changes.length;+ planned.push({ plan: planContextFile(repo, file), source: "context-files" });+ }+ }++ if (accepted === 0) {+ if (code === 0) {+ write("· nothing accepted in Trail yet — review:");+ write(` ${reviewUrl(link.brainId)}`);+ }+ return code;+ }++ const writing = planned.filter((p) => p.plan.status);+ const changes = writing.reduce((n, p) => n + p.plan.written.length, 0);+ if (writing.length > 0) {+ write(`✓ ${opts.dryRun ? "would write" : "wrote"} ${changes} accepted change${changes === 1 ? "" : "s"}`);+ const width = Math.max(30, ...writing.map((p) => p.plan.path.length)) + 2;+ for (const { plan } of writing) {+ const summary = changeSummary(plan.written);+ write(` ${plan.status} ${summary ? plan.path.padEnd(width) : plan.path}${summary}`.trimEnd());+ }+ } else if (planned.some((p) => p.plan.present.length > 0)) {+ write("✓ every accepted change is already in these files");+ }++ for (const { plan } of planned) {+ for (const s of plan.skipped) {+ const what = s.change.kind === "edit" || s.change.kind === "add" ? `${changeSummary([s.change])} in ${plan.path}` : plan.path;+ write(`⚠ skipped ${what} — ${s.why}; edit it in Trail, then pull again`);+ code = 1;+ }+ }++ if (opts.dryRun) {+ write("· dry run — nothing written, and Trail was not told");+ return code;+ }++ for (const { plan } of writing) {+ try {+ writePlannedFile(repo, plan);+ } catch (e) {+ write(`✗ could not write ${plan.path}: ${e instanceof Error ? e.message : e}`);+ // Nothing from a file that was not written is reported as applied.+ plan.written = [];+ plan.present = [];+ code = 1;+ }+ }++ // Written now or already there: either way Trail should stop listing it.+ const done = (source: Planned["source"]) =>+ planned.filter((p) => p.source === source).flatMap((p) => [...p.plan.written, ...p.plan.present].map((c) => c.id));+ const told = (await markApplied(link, done("claude-md"), fetchImpl)) && (await markContextFilesApplied(link, done("context-files"), fetchImpl));+ if (!told) write("⚠ could not tell Trail which changes were written; it may still list them");+ if (writing.length > 0) write("· review with git diff, then commit");+ return code;+}diff --git a/src/brain/push.ts b/src/brain/push.tsindex 9cbf5d01..fefa2343 100644--- a/src/brain/push.ts+++ b/src/brain/push.ts@@ -17,11 +17,13 @@import { spawnSync } from "node:child_process";import {buildDigest,+ newThreadReadCache,readCommits,readSymbols,readThreads,type HistoryThread,type RepoDigest,+ type ThreadReadCache,} from "../app/history.js";import {budgetSources,@@ -36,6 +38,7 @@ import {} from "../app/sources.js";import type { GraphV1 } from "../graph/types.js";import { baseUrlFor, type BrainLink } from "./link.js";+import { postDigestOnce, uploadDigest, type UploadCaps, type UploadOptions } from "./upload.js";/** What a local ingest read, for the caller to print. */export interface PushResult {@@ -115,8 +118,16 @@ export interface ExpectedRepo {slug: string;status: string;brainName: string;+ /** Rules the trail already holds; 0 before its first build. */+ ruleCount: number;/** The brain accepts an early upload (see pushEarlyDigest). */earlyUpload: boolean;+ /** POST /repo takes a gzipped body (`gzip_upload`). */+ gzipUpload: boolean;+ /** The chunked /repo/uploads routes exist (`chunked_upload`). */+ chunkedUpload: boolean;+ /** GET /events streams the build (`events`). */+ events: boolean;}/**@@ -128,6 +139,10 @@ export interface ExpectedRepo {* afterwards — the rules simply describe someone else's codebase — so the round* trip is worth it.*+ * The same read says what the server can take: gzip, chunks, a live event+ * stream. Every flag defaults to off, so an older Trail gets exactly the+ * requests it always did.+ ** Null on any failure, which keeps an older brain (or an unreachable one)* working exactly as it did before this check existed.*/@@ -139,22 +154,34 @@ export async function fetchExpectedRepo(link: BrainLink, fetchImpl: typeof fetch});if (!res.ok) return null;const body = (await res.json()) as {- repo?: { slug?: string; status?: string } | null;+ repo?: { slug?: string; status?: string; rule_count?: number } | null;brain_name?: string;early_upload?: boolean;+ gzip_upload?: boolean;+ chunked_upload?: boolean;+ events?: boolean;};if (!body.repo?.slug) return null;return {slug: body.repo.slug,status: String(body.repo.status ?? ""),brainName: String(body.brain_name ?? ""),+ ruleCount: typeof body.repo.rule_count === "number" && body.repo.rule_count > 0 ? body.repo.rule_count : 0,earlyUpload: body.early_upload === true,+ gzipUpload: body.gzip_upload === true,+ chunkedUpload: body.chunked_upload === true,+ events: body.events === true,};} catch {return null;}}+/** The upload capabilities an expected-repo read advertised. */+export function uploadCaps(expected: ExpectedRepo | null): UploadCaps {+ return { gzip: expected?.gzipUpload === true, chunked: expected?.chunkedUpload === true };+}+/** Whether two repo slugs name the same repository. GitHub is case-insensitive. */export function sameRepo(a: string, b: string): boolean {return a.trim().toLowerCase() === b.trim().toLowerCase();@@ -165,6 +192,42 @@ export function sameRepo(a: string, b: string): boolean {export const EARLY_THREADS = 30;export const EARLY_COMMITS = 80;+/**+ * What one push reads once and shares between its early and full digests: the+ * repository's identity, the GitHub token, whether it is private, and every+ * request already made to GitHub for its pull requests.+ */+export interface PushContext {+ owner: string;+ name: string;+ token: string | null;+ fetchImpl: typeof fetch;+ headSha: string;+ branch: string;+ /** Asked once, when first needed. */+ isPrivate: () => Promise<boolean>;+ threads: ThreadReadCache;+}++/** The shared context for a push from `root`, or null without a GitHub origin. */+export function pushContext(root: string, opts: { fetchImpl?: typeof fetch } = {}): PushContext | null {+ const slug = repoSlugFromGit(root);+ if (!slug) return null;+ const fetchImpl = opts.fetchImpl ?? fetch;+ const token = githubToken();+ let privacy: Promise<boolean> | null = null;+ return {+ owner: slug.owner,+ name: slug.name,+ token,+ fetchImpl,+ headSha: git(root, ["rev-parse", "HEAD"]) ?? "",+ branch: currentBranch(root),+ isPrivate: () => (privacy ??= isPrivate(slug.owner, slug.name, token, fetchImpl)),+ threads: newThreadReadCache(),+ };+}+/*** The early upload: the instruction files, the newest pull requests and the* newest commits, read before the rest of the history.@@ -174,34 +237,36 @@ export const EARLY_COMMITS = 80;* beyond the newest few. Sent first, they start while the full read is still* going here, and the full upload that follows mines as before.*- * Returns the threads it read, so the full read reuses them instead of asking- * GitHub twice. Null when there is nothing worth sending early.+ * Only the newest commits are read here, not the thousand the full read takes,+ * so nothing but these few requests stands between the push starting and Trail+ * starting. The pull requests go through the shared cache, so the full read+ * asks GitHub for none of them again — not even one still in flight.+ *+ * Null when there is nothing worth sending early.*/export async function buildEarlyDigest(root: string,- opts: { fetchImpl?: typeof fetch } = {},+ opts: { fetchImpl?: typeof fetch; context?: PushContext } = {},): Promise<{ digest: RepoDigest; threads: HistoryThread[] } | null> {- const slug = repoSlugFromGit(root);- if (!slug) return null;- const fetchImpl = opts.fetchImpl ?? fetch;- const token = githubToken();+ const ctx = opts.context ?? pushContext(root, opts);+ if (!ctx) return null;// Oldest first, like the full read, so the newest are the tail.- const commits = readCommits(root).slice(-EARLY_COMMITS);+ const commits = readCommits(root, EARLY_COMMITS);if (commits.length === 0) return null;let threads: HistoryThread[] = [];- if (token) {+ if (ctx.token) {try {- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, EARLY_THREADS);+ threads = await readThreads(ctx.owner, ctx.name, ctx.token, ctx.fetchImpl as never, undefined, EARLY_THREADS, undefined, ctx.threads);} catch {threads = [];}}const digest = buildDigest({- owner: slug.owner,- name: slug.name,- headSha: git(root, ["rev-parse", "HEAD"]) ?? "",- defaultBranch: currentBranch(root),- isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),+ owner: ctx.owner,+ name: ctx.name,+ headSha: ctx.headSha,+ defaultBranch: ctx.branch,+ isPrivate: await ctx.isPrivate(),commits,threads,symbols: [],@@ -212,20 +277,15 @@ export async function buildEarlyDigest(}/** Send the early upload. Best-effort: false on any failure, and the full- * upload still does everything. */-export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetchImpl: typeof fetch = fetch): Promise<boolean> {- const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo?stage=early`;+ * upload still does everything. Gzipped when the server takes it. */+export async function pushEarlyDigest(+ link: BrainLink,+ digest: RepoDigest,+ fetchImpl: typeof fetch = fetch,+ opts: { gzip?: boolean } = {},+): Promise<boolean> {try {- const res = await fetchImpl(url, {- method: "POST",- headers: {- authorization: `Bearer ${link.token}`,- "content-type": "application/json",- accept: "application/json",- },- body: JSON.stringify(digest),- signal: AbortSignal.timeout(15_000),- });+ const res = await postDigestOnce(link, digest, { gzip: opts.gzip, fetchImpl, query: "?stage=early", timeoutMs: 15_000 });if (!res.ok) return false;return ((await res.json()) as { early?: boolean }).early === true;} catch {@@ -237,14 +297,13 @@ export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetchexport async function buildLocalDigest(root: string,graph: GraphV1 | null,- opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[] } = {},+ opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[]; context?: PushContext } = {},): Promise<{ digest: RepoDigest; warning?: string } | { error: string }> {- const slug = repoSlugFromGit(root);- if (!slug) {+ const ctx = opts.context ?? pushContext(root, opts);+ if (!ctx) {return { error: "this directory has no GitHub `origin` remote — graft can only push a GitHub repository today" };}- const fetchImpl = opts.fetchImpl ?? fetch;- const token = githubToken();+ const { token, fetchImpl } = ctx;const commits = readCommits(root);if (commits.length === 0) {@@ -254,10 +313,18 @@ export async function buildLocalDigest(let threads: Awaited<ReturnType<typeof readThreads>> = [];let warning: string | undefined;+ // The GitHub-side sources start with the threads rather than after them:+ // they are a request or two each, and waiting behind 400 is waiting for no reason.+ const remote = token+ ? Promise.all([+ readBranchProtection(ctx.owner, ctx.name, ctx.branch, token, fetchImpl as never),+ readDeclinedIssues(ctx.owner, ctx.name, token, fetchImpl as never),+ ])+ : Promise.resolve([[], []] as const);if (token) {try {const known = new Map((opts.knownThreads ?? []).map((t) => [t.number, t]));- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, undefined, known);+ threads = await readThreads(ctx.owner, ctx.name, token, fetchImpl as never, undefined, undefined, known, ctx.threads);} catch {warning = "could not read pull-request discussion; mining commits and repo files only";}@@ -265,8 +332,8 @@ export async function buildLocalDigest(warning ="no GitHub token found (`gh auth login`, or GH_TOKEN) — mining commits and repo files only, without pull-request discussion";}+ const [protection, declined] = await remote;- const branch = currentBranch(root);const sources = budgetSources([...readAgentInstructions(root),...readDecisionDocs(root),@@ -274,16 +341,16 @@ export async function buildLocalDigest(...readCodifiedRules(root),...readReverts(root),...readTestNames(symbols.map((s) => ({ name: s.name, path: s.path }))),- ...(token ? await readBranchProtection(slug.owner, slug.name, branch, token, fetchImpl as never) : []),- ...(token ? await readDeclinedIssues(slug.owner, slug.name, token, fetchImpl as never) : []),+ ...protection,+ ...declined,]);const digest = buildDigest({- owner: slug.owner,- name: slug.name,- headSha: git(root, ["rev-parse", "HEAD"]) ?? "",- defaultBranch: branch,- isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),+ owner: ctx.owner,+ name: ctx.name,+ headSha: ctx.headSha,+ defaultBranch: ctx.branch,+ isPrivate: await ctx.isPrivate(),commits,threads,symbols,@@ -293,27 +360,18 @@ export async function buildLocalDigest(return { digest, warning };}-/** Send a digest to the brain and return the job to poll. */+/**+ * Send a digest to the brain and return the job to poll.+ *+ * Chunked and gzipped when the server advertises both, gzipped in one POST when+ * it advertises only gzip, and today's plain POST otherwise.+ */export async function pushDigest(link: BrainLink,digest: RepoDigest,fetchImpl: typeof fetch = fetch,+ caps: UploadCaps = {},+ opts: Omit<UploadOptions, "fetchImpl"> = {},): Promise<{ jobId: string } | { error: string }> {- const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`;- try {- const res = await fetchImpl(url, {- method: "POST",- headers: {- authorization: `Bearer ${link.token}`,- "content-type": "application/json",- accept: "application/json",- },- body: JSON.stringify(digest),- });- const text = await res.text();- if (!res.ok) return { error: `the brain refused the ingest: ${res.status} ${text.slice(0, 200)}` };- return { jobId: String((JSON.parse(text) as { job_id?: string }).job_id ?? "") };- } catch (e) {- return { error: `could not reach the brain: ${e instanceof Error ? e.message : e}` };- }+ return uploadDigest(link, digest, caps, { ...opts, fetchImpl });}diff --git a/src/brain/signup.ts b/src/brain/signup.tsindex d9da4952..fe3f87e8 100644--- a/src/brain/signup.ts+++ b/src/brain/signup.ts@@ -76,8 +76,8 @@ function sameState(got: string, want: string): boolean {* about to close, so there is nothing to style around. */function donePage(ok: boolean): string {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 trail push` again.";+ ? "Your trail is connected. Return to your terminal — the push is already running."+ : "That sign-up doesn't match this terminal. Run graft trail 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>`;}@@ -116,7 +116,7 @@ export async function startHandoff(): Promise<Handoff> {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" });+ settle({ error: "sign-up came back incomplete · nothing was sent — run graft trail push again", reason: "bad_callback" });return;}@@ -155,7 +155,13 @@ export async function startHandoff(): Promise<Handoff> {let timer: NodeJS.Timeout | undefined;const timeout = new Promise<HandoffResult>((resolve) => {timer = setTimeout(- () => resolve({ error: "timed out waiting for the browser — run `graft trail push` again, or use the link above", reason: "timed_out" }),+ () =>+ resolve({+ error: `no sign-up after ${+ timeoutMs >= 60_000 ? `${Math.round(timeoutMs / 60_000)} minutes` : `${Math.max(1, Math.round(timeoutMs / 1000))} seconds`+ } · nothing was sent — run graft trail push again`,+ reason: "timed_out",+ }),timeoutMs,);// The timer must not hold the process open once the browser has answered.@@ -196,6 +202,11 @@ export function brainUrl(brainId: string, baseUrl?: string): string {return `${webBaseUrl(baseUrl)}/get-started?step=build&brain=${encodeURIComponent(brainId)}`;}+/** Where a trail's suggested context-file changes are reviewed and accepted. */+export function reviewUrl(brainId: string, baseUrl?: string): string {+ return `${webBaseUrl(baseUrl)}/brain/${encodeURIComponent(brainId)}/claude-md`;+}+/** Where to send the browser for a repo's brain. */export function signupUrl(opts: { repo: string; port: number; state: string; baseUrl?: string }): string {const base = webBaseUrl(opts.baseUrl);diff --git a/src/brain/upload.ts b/src/brain/upload.tsnew file mode 100644index 00000000..b9fc70df--- /dev/null+++ b/src/brain/upload.ts@@ -0,0 +1,254 @@+/**+ * Getting a digest to Trail quickly, and getting it there at all.+ *+ * A busy repository's digest is several megabytes of JSON — a thousand commit+ * messages, two hundred threads of discussion, four thousand symbols — and it+ * used to go up as one uncompressed POST with no retry. On a hotel connection+ * that is a minute of upload and one dropped packet from starting over.+ *+ * JSON compresses about tenfold, so the body is gzipped whenever the server+ * says it takes gzip. When it also says it takes chunked uploads, the gzip is+ * cut into 1 MiB pieces and sent four at a time, each retried on its own: a+ * blip costs one chunk, not the push. Against an older Trail neither flag is+ * set and the upload is exactly the single POST it always was.+ */+import { gzip as gzipCb } from "node:zlib";+import { promisify } from "node:util";+import type { RepoDigest } from "../app/history.js";+import { baseUrlFor, type BrainLink } from "./link.js";++const gzipAsync = promisify(gzipCb);++/** The size of one chunk: the index-th slice of the gzip is bytes [i*CHUNK, (i+1)*CHUNK). */+export const CHUNK_BYTES = 1024 * 1024;+/** Chunks in flight at once. */+export const CHUNK_CONCURRENCY = 4;+/** Waits before each retry. Four retries, so five attempts in all. */+export const RETRY_DELAYS_MS = [500, 1000, 2000, 4000] as const;++/** What the server said it accepts, from GET /repo. */+export interface UploadCaps {+ /** `gzip_upload: true` — POST /repo takes `Content-Encoding: gzip`. */+ gzip?: boolean;+ /** `chunked_upload: true` — the /repo/uploads routes exist. */+ chunked?: boolean;+}++export interface UploadOptions {+ fetchImpl?: typeof fetch;+ sleep?: (ms: number) => Promise<void>;+ chunkBytes?: number;+ concurrency?: number;+}++export type UploadResult = { jobId: string } | { error: string };++const realSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));++/** The digest as the exact bytes a single POST would carry, gzipped. */+export async function gzipDigest(digest: RepoDigest): Promise<Buffer> {+ return gzipAsync(Buffer.from(JSON.stringify(digest), "utf8"));+}++/** Retry on what a retry can fix: the network, the server, the rate limit. */+function retryable(status: number): boolean {+ return status >= 500 || status === 429;+}++/**+ * One request, retried with backoff on network errors, 5xx and 429.+ *+ * Returns the last response when retries run out on a status (so the caller+ * can print the server's own words), or throws the last network error.+ */+async function withRetry(+ send: () => Promise<Response>,+ sleep: (ms: number) => Promise<void>,+): Promise<{ res: Response; attempts: number; sawNetworkError: boolean }> {+ let sawNetworkError = false;+ let lastError: unknown;+ for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {+ if (attempt > 0) await sleep(RETRY_DELAYS_MS[attempt - 1]!);+ try {+ const res = await send();+ if (!retryable(res.status) || attempt === RETRY_DELAYS_MS.length) {+ return { res, attempts: attempt + 1, sawNetworkError };+ }+ // Drain it so the connection is released before the next attempt.+ await res.arrayBuffer().catch(() => undefined);+ } catch (e) {+ sawNetworkError = true;+ lastError = e;+ }+ }+ throw lastError instanceof Error ? lastError : new Error(String(lastError));+}++function authHeaders(link: BrainLink, extra: Record<string, string> = {}): Record<string, string> {+ return { authorization: `Bearer ${link.token}`, accept: "application/json", ...extra };+}++/** Today's response to an ingest, read the same way for every route that returns it. */+async function ingestResult(res: Response): Promise<UploadResult> {+ const text = await res.text();+ if (!res.ok) return { error: `Trail refused the upload: ${res.status} ${text.slice(0, 200)}` };+ try {+ return { jobId: String((JSON.parse(text) as { job_id?: string }).job_id ?? "") };+ } catch {+ return { jobId: "" };+ }+}++/**+ * The single POST to /repo — gzipped when the server takes it, plain otherwise.+ * Not retried: a repeated POST of a whole ingest is not idempotent, and a 409+ * for "already running" on the retry would read as a refusal.+ */+export async function postDigestOnce(+ link: BrainLink,+ digest: RepoDigest,+ opts: { gzip?: boolean; fetchImpl?: typeof fetch; query?: string; timeoutMs?: number } = {},+): Promise<Response> {+ const fetchImpl = opts.fetchImpl ?? fetch;+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo${opts.query ?? ""}`;+ const json = JSON.stringify(digest);+ const body = opts.gzip ? await gzipAsync(Buffer.from(json, "utf8")) : json;+ const headers = authHeaders(link, { "content-type": "application/json" });+ if (opts.gzip) headers["content-encoding"] = "gzip";+ return fetchImpl(url, {+ method: "POST",+ headers,+ body: body as unknown as RequestInit["body"],+ ...(opts.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),+ });+}++/**+ * Upload the full digest by whichever route the server advertises.+ *+ * Chunked when `caps.chunked`; if the upload session cannot even be opened+ * (a 404 from a server that advertised the flag but not the route), it falls+ * back to the single POST rather than failing a push that would otherwise work.+ */+export async function uploadDigest(+ link: BrainLink,+ digest: RepoDigest,+ caps: UploadCaps,+ opts: UploadOptions = {},+): Promise<UploadResult> {+ if (caps.chunked) {+ const chunked = await uploadChunked(link, digest, opts);+ if (!("fallback" in chunked)) return chunked;+ }+ try {+ return await ingestResult(await postDigestOnce(link, digest, { gzip: caps.gzip, fetchImpl: opts.fetchImpl }));+ } catch (e) {+ return { error: `could not reach Trail: ${e instanceof Error ? e.message : e}` };+ }+}++/**+ * The chunked route:+ *+ * POST /repo/uploads {stage, auto_approve, chunks, bytes} → {upload_id}+ * PUT /repo/uploads/:id/chunks/:index raw gzip slice, idempotent → 204+ * POST /repo/uploads/:id/complete → today's /repo response+ *+ * `{fallback: true}` means the session could not be opened and nothing was+ * sent, so the caller may use the single POST instead.+ */+export async function uploadChunked(+ link: BrainLink,+ digest: RepoDigest,+ opts: UploadOptions = {},+): Promise<UploadResult | { fallback: true }> {+ const fetchImpl = opts.fetchImpl ?? fetch;+ const sleep = opts.sleep ?? realSleep;+ const chunkBytes = opts.chunkBytes ?? CHUNK_BYTES;+ const base = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo/uploads`;++ const gz = await gzipDigest(digest);+ const chunks = Math.max(1, Math.ceil(gz.length / chunkBytes));++ let uploadId = "";+ try {+ const { res } = await withRetry(+ () =>+ fetchImpl(base, {+ method: "POST",+ headers: authHeaders(link, { "content-type": "application/json" }),+ body: JSON.stringify({ stage: "full", auto_approve: digest.auto_approve, chunks, bytes: gz.length }),+ }),+ sleep,+ );+ const text = await res.text();+ if (res.status === 404 || res.status === 405) return { fallback: true };+ if (!res.ok) {+ // 409 is the one refusal worth passing on as-is: an ingest is already+ // running, and a single POST would be told the same.+ if (res.status === 409) return { error: `Trail refused the upload: ${res.status} ${text.slice(0, 200)}` };+ return { fallback: true };+ }+ uploadId = String((JSON.parse(text) as { upload_id?: string }).upload_id ?? "");+ } catch {+ return { fallback: true };+ }+ if (!uploadId) return { fallback: true };++ // Chunks, four at a time, each retried on its own.+ const concurrency = Math.max(1, opts.concurrency ?? CHUNK_CONCURRENCY);+ let next = 0;+ let failure: string | null = null;+ const worker = async () => {+ for (;;) {+ if (failure) return;+ const i = next++;+ if (i >= chunks) return;+ const slice = gz.subarray(i * chunkBytes, Math.min(gz.length, (i + 1) * chunkBytes));+ try {+ const { res } = await withRetry(+ () =>+ fetchImpl(`${base}/${encodeURIComponent(uploadId)}/chunks/${i}`, {+ method: "PUT",+ headers: authHeaders(link, { "content-type": "application/octet-stream" }),+ body: slice as unknown as RequestInit["body"],+ }),+ sleep,+ );+ if (!res.ok) {+ const text = await res.text().catch(() => "");+ failure = `Trail refused part ${i + 1} of ${chunks}: ${res.status} ${text.slice(0, 200)}`;+ return;+ }+ await res.arrayBuffer().catch(() => undefined);+ } catch (e) {+ failure = `could not send part ${i + 1} of ${chunks} to Trail: ${e instanceof Error ? e.message : e}`;+ return;+ }+ }+ };+ await Promise.all(Array.from({ length: Math.min(concurrency, chunks) }, worker));+ if (failure) return { error: failure };++ try {+ const { res, sawNetworkError } = await withRetry(+ () =>+ fetchImpl(`${base}/${encodeURIComponent(uploadId)}/complete`, {+ method: "POST",+ headers: authHeaders(link, { "content-type": "application/json" }),+ body: "{}",+ }),+ sleep,+ );+ // A complete that was lost on the way back may have started the ingest, so+ // its retry being told "already running" means it worked. The watcher that+ // follows reads the build either way.+ if (res.status === 409 && sawNetworkError) {+ await res.arrayBuffer().catch(() => undefined);+ return { jobId: "" };+ }+ return await ingestResult(res);+ } catch (e) {+ return { error: `could not reach Trail to finish the upload: ${e instanceof Error ? e.message : e}` };+ }+}diff --git a/src/brain/watch.ts b/src/brain/watch.tsindex 43e3ab57..c72066ff 100644--- a/src/brain/watch.ts+++ b/src/brain/watch.ts@@ -67,6 +67,24 @@ export interface RepoState {/** 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;+ /** Suggested changes to the repo's context files, when Trail sends them. */+ suggestions?: Suggestions;+}++/**+ * The suggestions Trail has for this repository's context files so far.+ *+ * Counts, because that is all the terminal prints; the changes themselves are+ * reviewed in Trail and written by `graft trail pull`.+ */+export interface Suggestions {+ /** Changes suggested for the root CLAUDE.md. */+ claudeMd: number;+ /** Changes suggested for every other context file, all kinds together. */+ contextFiles: number;+ /** Per file, when Trail lists them — which is what lets the count be cut to+ * the files the wired agents actually read. */+ files?: Array<{ kind: string; path: string; changes: number }>;}export interface BuildView {@@ -148,6 +166,51 @@ export function stagesFrom(repo: RepoState | null): BuildView {};}+/** A count from a field Trail may send as a number or as the list itself. */+const countOf = (v: unknown): number => (Array.isArray(v) ? v.length : num(v));++/** The fields of an expected-repo body the watcher reads, as Trail sends them. */+interface RepoBody {+ repo?: { status?: string; error_message?: string; rule_count?: number; commit_count?: number; thread_count?: number } | null;+ // Absent on an older API, which is why every read of it defaults to zero:+ // a graft that cannot see the in-flight counts falls back to waiting for+ // the finished row, exactly as it did before.+ build?: { found_so_far?: number; filed_so_far?: number } | null;+ claude_md?: { status?: string; quick_ready?: boolean; full_ready?: boolean; changes?: unknown } | null;+ context_files?: { files?: unknown; changes?: unknown } | null;+}++/**+ * The repo state out of an expected-repo body — the polled GET and every SSE+ * `progress` event carry the same shape. Null when there is no repo row.+ */+export function parseRepoBody(body: unknown): RepoState | null {+ const b = (body ?? {}) as RepoBody;+ if (!b.repo || typeof b.repo !== "object") return null;+ const state: RepoState = {+ status: String(b.repo.status ?? ""),+ errorMessage: b.repo.error_message,+ ruleCount: num(b.repo.rule_count),+ commitCount: num(b.repo.commit_count),+ threadCount: num(b.repo.thread_count),+ filedSoFar: num(b.build?.filed_so_far),+ foundSoFar: num(b.build?.found_so_far),+ };+ if (b.claude_md || b.context_files) {+ const files = Array.isArray(b.context_files?.files)+ ? (b.context_files!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>)+ .filter((f) => f && typeof f === "object")+ .map((f) => ({ kind: String(f.kind ?? ""), path: String(f.path ?? ""), changes: countOf(f.changes) }))+ : undefined;+ state.suggestions = {+ claudeMd: countOf(b.claude_md?.changes),+ contextFiles: b.context_files?.changes !== undefined ? countOf(b.context_files.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),+ ...(files ? { files } : {}),+ };+ }+ return state;+}+/*** Read the repo row this brain is building.*@@ -162,45 +225,72 @@ export async function fetchRepoState(link: BrainLink, fetchImpl: typeof fetch =signal: AbortSignal.timeout(5000),});if (!res.ok) return null;- const body = (await res.json()) as {- repo?: { status?: string; error_message?: string; rule_count?: number; commit_count?: number; thread_count?: number } | null;- // Absent on an older API, which is why every read of it defaults to zero:- // a graft that cannot see the in-flight counts falls back to waiting for- // the finished row, exactly as it did before.- build?: { found_so_far?: number; filed_so_far?: number } | null;- };- 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),- };+ return parseRepoBody(await res.json());} catch {return null;}}-/** One printable line per stage that has moved since it was last printed. */-export function linesFor(view: BuildView, already: Set<string>): string[] {+/** Past tense, for the no-TTY log: each line reports a stage that finished. */+const DONE_LABEL: Record<StageId, string> = {+ reach: "reached the repository",+ read: "read its history",+ mine: "mined the rules",+ file: "filed them into the trail",+};++/** What the spinner says while a stage is running. */+export const DOING_LABEL: Record<StageId, string> = {+ reach: "reaching the repository",+ read: "reading its history",+ mine: "mining rules",+ file: "filing the rules",+};++/** The first rules there are, from whichever count the row has. */+export function rulesSoFar(repo: RepoState | null): number {+ return Math.max(num(repo?.ruleCount), num(repo?.filedSoFar), num(repo?.foundSoFar));+}++/**+ * One printable line per stage that has finished since it was last printed.+ *+ * Only for a log with no terminal to redraw — on a TTY the spinner says which+ * stage is running and these lines are never printed. Filing is left out: the+ * watcher hands the prompt back on the first rules, before filing finishes, and+ * the closing line says how many there are.+ */+export function linesFor(view: BuildView, already: Set<string>, repo: RepoState | null = null): string[] {const out: string[] = [];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;+ if (s.state !== "done" || s.id === "file") 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}` : ""}`);+ const rules = rulesSoFar(repo);+ const label =+ s.id === "mine" && rules > 0+ ? `mined the first ${rules.toLocaleString("en-US")} rule${rules === 1 ? "" : "s"}`+ : DONE_LABEL[s.id];+ out.push(` ✓ ${label}`);}return out;}+/** The stage the build is in now, for the spinner. */+export function currentStage(view: BuildView): StageId {+ return (view.stages.find((s) => s.state === "doing" || s.state === "failed") ?? view.stages[view.stages.length - 1]!).id;+}++/** The failure line: where it stopped, and that nothing was lost. The server's+ * own words follow on the next line, in full. */+export function failureLines(view: BuildView): string[] {+ const at = view.stages.find((s) => s.state === "failed")?.id ?? "mine";+ const lines = [`✗ the build stopped while ${DOING_LABEL[at]} · nothing was lost — run graft trail push again`];+ if (view.error) lines.push(` ${view.error}`);+ return lines;+}+export interface WatchOptions {/** How long to hold before giving up on a build that is still running. */timeoutMs?: number;@@ -209,6 +299,16 @@ export interface WatchOptions {/** Where the lines go. Injected so the tests do not need a console. */write?: (line: string) => void;sleep?: (ms: number) => Promise<void>;+ /** Print a line per finished stage. Off on a TTY, where a spinner says it. */+ stageLines?: boolean;+ /** Every state read, with its view — the spinner's feed. */+ onState?: (view: BuildView, repo: RepoState) => void;+ /** Follow `GET /events` instead of polling (the server advertised `events`). */+ events?: boolean;+ /** Silence on the stream for this long counts as a drop. Keep-alives come every 15 s. */+ idleMs?: number;+ /** Stream reconnects before falling back to polling. */+ maxReconnects?: number;}/**@@ -222,12 +322,17 @@ export interface WatchOptions {export type WatchOutcome = "completed" | "building" | "failed" | "timed_out" | "unreachable";/**- * Hold until the brain has rules, printing each stage as it settles.+ * Hold until the brain has rules, reporting 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.*+ * Live when the server streams events: each change arrives as it happens+ * instead of up to four seconds late. A stream that drops is reopened up to+ * three times, and after that the watcher polls as it always did — so the+ * worst a broken stream costs is the old behaviour.+ ** 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@@ -238,32 +343,182 @@ export async function watchBuild(link: BrainLink, opts: WatchOptions = {}): Promconst timeoutMs = opts.timeoutMs ?? 15 * 60 * 1000;const pollMs = opts.pollMs ?? 4000;const write = opts.write ?? ((l: string) => console.error(l));- const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms).unref?.()));+ // Not unref'd: between polls this timer is the only thing the process is+ // waiting on, and an unref'd one let it exit mid-watch with nothing printed.+ const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));+ const fetchImpl = opts.fetchImpl ?? fetch;+ const stageLines = opts.stageLines !== false;const printed = new Set<string>();const startedAt = Date.now();+ const deadline = startedAt + timeoutMs;// 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";+ /** One state read → the outcome it settles, or null to keep watching. */+ const settle = (repo: RepoState | null): WatchOutcome | null => {+ if (!repo) return null;+ everRead = true;+ const view = stagesFrom(repo);+ opts.onState?.(view, repo);+ if (stageLines) for (const line of linesFor(view, printed, repo)) write(line);+ if (view.error) {+ for (const line of failureLines(view)) write(line);+ 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";+ return null;+ };++ if (opts.events) {+ let drops = 0;+ const maxReconnects = opts.maxReconnects ?? 3;+ while (drops <= maxReconnects && Date.now() < deadline) {+ const r = await streamOnce(link, fetchImpl, settle, deadline, opts.idleMs ?? 45_000);+ if (r.outcome) return r.outcome;+ if (r.end === "unsupported" || r.end === "deadline") break;+ if (r.end === "done") {+ // The build ended without the event saying how: read the row once.+ const final = settle(await fetchRepoState(link, fetchImpl));+ if (final) return final;+ break;}- 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";+ drops++;+ if (drops <= maxReconnects) await sleep(Math.min(1000 * drops, 4000));}- if (Date.now() - startedAt >= timeoutMs) return everRead ? "timed_out" : "unreachable";+ }++ for (;;) {+ const outcome = settle(await fetchRepoState(link, fetchImpl));+ if (outcome) return outcome;+ if (Date.now() >= deadline) return everRead ? "timed_out" : "unreachable";await sleep(pollMs);}}++/** One server-sent event. */+export interface SseEvent {+ event: string;+ data: string;+}++/**+ * An incremental text/event-stream parser: feed it chunks as they arrive,+ * get back the events they completed. Comments (`: ping`) are dropped; a+ * missing `event:` field means `message`, per the spec.+ */+export class SseParser {+ private buf = "";+ private event = "";+ private data: string[] = [];++ push(chunk: string): SseEvent[] {+ this.buf += chunk;+ const out: SseEvent[] = [];+ for (;;) {+ const nl = this.buf.search(/\r\n|\r|\n/);+ if (nl < 0) break;+ const sep = this.buf.startsWith("\r\n", nl) ? 2 : 1;+ // A lone \r at the very end may be the first half of \r\n: wait for more.+ if (this.buf[nl] === "\r" && sep === 1 && nl === this.buf.length - 1) break;+ const line = this.buf.slice(0, nl);+ this.buf = this.buf.slice(nl + sep);+ if (line === "") {+ if (this.data.length > 0) out.push({ event: this.event || "message", data: this.data.join("\n") });+ this.event = "";+ this.data = [];+ continue;+ }+ if (line.startsWith(":")) continue;+ const colon = line.indexOf(":");+ const field = colon < 0 ? line : line.slice(0, colon);+ let value = colon < 0 ? "" : line.slice(colon + 1);+ if (value.startsWith(" ")) value = value.slice(1);+ if (field === "event") this.event = value;+ else if (field === "data") this.data.push(value);+ // id and retry are not used: a reconnect starts from a fresh `progress`.+ }+ return out;+ }+}++type StreamEnd = "done" | "dropped" | "unsupported" | "deadline";++/**+ * One connection to `GET /events`. Resolves with the outcome when an event+ * settled the watch, or with how the stream ended when none did.+ */+async function streamOnce(+ link: BrainLink,+ fetchImpl: typeof fetch,+ settle: (repo: RepoState | null) => WatchOutcome | null,+ deadline: number,+ idleMs: number,+): Promise<{ outcome?: WatchOutcome; end?: StreamEnd }> {+ const ctl = new AbortController();+ let res: Response;+ try {+ res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/events`, {+ headers: { authorization: `Bearer ${link.token}`, accept: "text/event-stream", "cache-control": "no-cache" },+ signal: ctl.signal,+ });+ } catch {+ return { end: "dropped" };+ }+ // A server without the route, or one that answered with something other+ // than a stream: polling is the answer, not three more tries.+ if (res.status === 404 || res.status === 405 || res.status === 501) return { end: "unsupported" };+ if (!res.ok) return { end: "dropped" };+ const type = res.headers?.get?.("content-type") ?? "text/event-stream";+ if (!res.body || !/event-stream/i.test(type)) return { end: "unsupported" };++ const reader = res.body.getReader();+ const decoder = new TextDecoder();+ const parser = new SseParser();+ try {+ for (;;) {+ const left = deadline - Date.now();+ if (left <= 0) return { end: "deadline" };+ let timer: NodeJS.Timeout | undefined;+ const idle = new Promise<"idle">((r) => {+ // Not unref'd: while the stream is quiet this timer is what the+ // process is waiting on, and it is cleared the moment a chunk lands.+ timer = setTimeout(() => r("idle"), Math.min(idleMs, left));+ });+ const got = await Promise.race([reader.read(), idle]).finally(() => clearTimeout(timer));+ if (got === "idle") return { end: Date.now() >= deadline ? "deadline" : "dropped" };+ if (got.done) return { end: "dropped" };+ for (const ev of parser.push(decoder.decode(got.value, { stream: true }))) {+ let payload: unknown = null;+ try {+ payload = ev.data ? JSON.parse(ev.data) : null;+ } catch {+ payload = null;+ }+ if (ev.event === "progress" || ev.event === "message") {+ const outcome = settle(parseRepoBody(payload));+ if (outcome) return { outcome };+ } else if (ev.event === "done") {+ const outcome = settle(parseRepoBody(payload));+ if (outcome) return { outcome };+ return { end: "done" };+ }+ }+ }+ } catch {+ return { end: "dropped" };+ } finally {+ ctl.abort();+ try {+ reader.releaseLock();+ } catch {+ /* already released by the abort */+ }+ }+}diff --git a/src/claude/build-progress.ts b/src/claude/build-progress.tsnew file mode 100644index 00000000..035bf160--- /dev/null+++ b/src/claude/build-progress.ts@@ -0,0 +1,83 @@+/**+ * `graft build`, run from `graft init` as one line that redraws in place.+ *+ * `buildGraphIfMissing` hands the child the terminal, which prints a `parsing+ * N/M: path` line and four more after it. That is the right output for someone+ * who ran `graft build`, and five lines of someone else's output in the middle+ * of init. Here the child's output is read instead: its progress becomes the+ * spinner's `1,204 of 1,942 files`, its totals become init's one summary line,+ * and any warning or error it printed is passed on whole.+ */+import { spawn } from "node:child_process";+import { hasGraftIndex } from "../graph/root.js";+import { startSpinner } from "../util/spinner.js";++export interface BuiltGraph {+ nodes: number;+ edges: number;+ files: number;+}++const n = (s: string | undefined) => Number((s ?? "0").replace(/,/g, "")) || 0;++/** The totals out of `graft build`'s stdout, or null when it printed none. */+export function parseBuildSummary(stdout: string): BuiltGraph | null {+ const wiring = /✓ wiring: ([\d,]+) nodes.*?, ([\d,]+) edges/.exec(stdout);+ if (!wiring) return null;+ const parsed = /parsed: [\d,]+ of ([\d,]+) files/.exec(stdout);+ return { nodes: n(wiring[1]), edges: n(wiring[2]), files: n(parsed?.[1]) };+}++/** The last `parsing N/M` in a chunk of the child's stderr. */+export function parseProgress(chunk: string): { index: number; total: number } | null {+ let last: { index: number; total: number } | null = null;+ for (const m of chunk.matchAll(/(?:parsing|summarizing) (\d+)\/(\d+)/g)) last = { index: n(m[1]), total: n(m[2]) };+ return last;+}++/**+ * Build the graph for `dir` unless it has one, showing progress on a spinner.+ *+ * `built: false` with no `failed` means there was nothing to do (`--no-build`,+ * or a graph already there). Warning and error lines the build printed come+ * back in `messages`, for the caller to print in full.+ */+export async function buildGraphWithProgress(+ dir: string,+ opts: { build?: boolean; cliPath?: string },+): Promise<{ built: boolean; graph?: BuiltGraph; failed?: boolean; messages: string[] }> {+ if (opts.build === false || !opts.cliPath || hasGraftIndex(dir)) return { built: false, messages: [] };+ const spinner = startSpinner("building the graph");+ let stdout = "";+ let stderr = "";+ const fmt = (x: number) => x.toLocaleString("en-US");+ const code = await new Promise<number | null>((resolve) => {+ const child = spawn(process.execPath, [...process.execArgv, opts.cliPath!, "build", "."], {+ cwd: dir,+ stdio: ["ignore", "pipe", "pipe"],+ });+ const timer = setTimeout(() => child.kill(), 300_000);+ timer.unref?.();+ child.stdout.setEncoding("utf8");+ child.stderr.setEncoding("utf8");+ child.stdout.on("data", (d: string) => (stdout += d));+ child.stderr.on("data", (d: string) => {+ stderr += d;+ const p = parseProgress(d);+ if (p) spinner.update(`building the graph · ${fmt(p.index)} of ${fmt(p.total)} files`);+ });+ child.on("error", () => resolve(null));+ child.on("close", (c) => {+ clearTimeout(timer);+ resolve(c);+ });+ });+ spinner.stop();+ const messages = `${stdout}\n${stderr.replace(/\r[^\n]*/g, "\n")}`+ .split("\n")+ .map((l) => l.trimEnd())+ .filter((l) => /^\s*[⚠✗]/.test(l));+ const graph = parseBuildSummary(stdout) ?? undefined;+ if (code !== 0) return { built: false, failed: true, messages };+ return { built: true, graph, messages };+}diff --git a/src/cli-picker.ts b/src/cli-picker.tsindex 40b0db4c..6e0b816a 100644--- a/src/cli-picker.ts+++ b/src/cli-picker.ts@@ -56,6 +56,43 @@ export function describeWrites(return parts.join(' · ');}+/**+ * The picker's and init's one-line summary: at most two repo entries, a folder+ * written into several times shown once as `folder/` when something else sits+ * beside it, then the count of writes outside the repo. `.claude/, .mcp.json ·+ * + 3 in ~/` rather than five paths nobody reads.+ */+export function compactWrites(writes: PlannedWrite[], repo: string, home: string, maxShown = 2): string {+ const repoPaths = writes.filter((w) => w.scope === 'repo').map((w) => relative(repo, w.path));+ const tops = new Map<string, string[]>();+ for (const p of repoPaths) {+ const top = p.split(sep)[0] ?? p;+ const list = tops.get(top) ?? [];+ list.push(p);+ tops.set(top, list);+ }+ const entries: string[] = [];+ if (tops.size >= 2) {+ for (const [top, paths] of tops) entries.push(paths.length >= 2 ? `${top}${sep}` : paths[0]!);+ } else {+ entries.push(...repoPaths);+ }+ const parts: string[] = [];+ if (entries.length > 0) {+ parts.push(+ entries.length <= maxShown+ ? entries.join(', ')+ : `${entries.slice(0, maxShown).join(', ')} +${entries.length - maxShown} more`,+ );+ }+ const globals = writes.filter((w) => w.scope === 'global');+ if (globals.length > 0) {+ const where = tilde(commonDir(globals.map((w) => w.path)), home);+ parts.push(`+ ${globals.length} in ${where}${where.endsWith(sep) ? '' : sep}`);+ }+ return parts.join(' · ');+}+export interface PickerRow {id: string;detected: boolean;@@ -85,10 +122,18 @@ export const TELEMETRY_ROW_ID = '__telemetry';export interface PickerState {rows: PickerRow[];+ /** Index into {@link visibleRows}, not into `rows`. */cursor: number;checked: ReadonlySet<string>;done: boolean;aborted: boolean;+ /** Agents graft cannot find on this machine are folded into one line until `m`. */+ showHidden?: boolean;+}++/** The rows on screen: undetected agents only once `m` has unfolded them. */+export function visibleRows(state: PickerState): PickerRow[] {+ return state.rows.filter((r) => r.kind === 'setting' || r.detected || state.showHidden);}/**@@ -108,7 +153,7 @@ export function initialPickerState(label: p.id,kind: 'host' as const,detected: p.detected,- summary: describeWrites(p.writes, repo, home),+ summary: compactWrites(p.writes, repo, home),hasGlobal: p.writes.some((w) => w.scope === 'global'),}));const checked = new Set(plan.some((p) => p.id === 'claude') ? ['claude'] : []);@@ -118,7 +163,7 @@ export function initialPickerState(label: 'anonymous usage stats',kind: 'setting',detected: true,- summary: 'no code, no file paths, no queries · TELEMETRY.md',+ summary: 'no code, no file paths, no queries',hasGlobal: false,});checked.add(TELEMETRY_ROW_ID);@@ -126,7 +171,7 @@ export function initialPickerState(return { rows, cursor: 0, checked, done: false, aborted: false };}-export type PickerKey = 'up' | 'down' | 'space' | 'all' | 'enter' | 'abort';+export type PickerKey = 'up' | 'down' | 'space' | 'all' | 'more' | 'enter' | 'abort';export const KEY_UP = '\x1b[A';export const KEY_DOWN = '\x1b[B';@@ -140,6 +185,7 @@ export function keyOf(chunk: string): PickerKey | null {case KEY_DOWN: case 'j': return 'down';case ' ': return 'space';case 'a': return 'all';+ case 'm': return 'more';case '\r': case '\n': return 'enter';case KEY_ESC: case KEY_CTRL_C: case 'q': return 'abort';default: return null;@@ -173,7 +219,8 @@ export function keysOf(chunk: string): PickerKey[] {}export function reducePicker(state: PickerState, key: PickerKey): PickerState {- const n = state.rows.length;+ const visible = visibleRows(state);+ const n = visible.length;switch (key) {case 'up':return { ...state, cursor: (state.cursor - 1 + n) % n };@@ -181,20 +228,37 @@ export function reducePicker(state: PickerState, key: PickerKey): PickerState {return { ...state, cursor: (state.cursor + 1) % n };case 'space': {const next = new Set(state.checked);- const id = state.rows[state.cursor].id;+ const id = visible[state.cursor]!.id;if (next.has(id)) next.delete(id); else next.add(id);return { ...state, checked: next };}case 'all': {- // Hosts only. `a` means "wire everything"; a user who pressed it to select- // every agent has not thereby said anything about usage stats, so whatever- // they chose on that row survives untouched.- const hosts = state.rows.filter((r) => r.kind === 'host');+ // The agents on screen only: `a` must never select one the user cannot+ // see. And agents only — a user who pressed it to select every agent has+ // not thereby said anything about usage stats, so whatever they chose on+ // that row survives untouched.+ const hosts = visible.filter((r) => r.kind === 'host');const allOn = hosts.every((r) => state.checked.has(r.id));- const next = new Set(state.rows.filter((r) => r.kind === 'setting' && state.checked.has(r.id)).map((r) => r.id));- if (!allOn) for (const r of hosts) next.add(r.id);+ const next = new Set(state.checked);+ for (const r of hosts) {+ if (allOn) next.delete(r.id);+ else next.add(r.id);+ }return { ...state, checked: next };}+ case 'more': {+ if (!state.rows.some((r) => r.kind === 'host' && !r.detected)) return state;+ // Keep the cursor on the row it was on, wherever that row lands.+ const at = visible[state.cursor]?.id;+ const toggled = { ...state, showHidden: !state.showHidden };+ const after = visibleRows(toggled);+ // Folding away the row under the cursor puts the cursor back at the top.+ const idx = after.findIndex((r) => r.id === at);+ // Anything the fold hides is unchecked, so nothing invisible gets wired.+ const checked = new Set(state.checked);+ if (!toggled.showHidden) for (const r of state.rows) if (r.kind === 'host' && !r.detected) checked.delete(r.id);+ return { ...toggled, cursor: idx >= 0 ? idx : 0, checked };+ }case 'enter':return { ...state, done: true };case 'abort':@@ -202,33 +266,49 @@ export function reducePicker(state: PickerState, key: PickerKey): PickerState {}}-export function renderPicker(state: PickerState, tty = true): string {+export function renderPicker(state: PickerState, tty = true, opts: { title?: string | null } = {}): string {const dim = tty ? muted : (s: string) => s;const hot = tty ? indigo : (s: string) => s;const warn = tty ? amber : (s: string) => s;+ const visible = visibleRows(state);+ const hidden = state.rows.filter((r) => r.kind === 'host' && !r.detected);// Pad on the plain label so the summary column lines up regardless of which// rows carry the '(not detected)' tag or the cursor's colour codes.- const label = (r: PickerRow) => `${r.label}${r.detected ? '' : ' (not detected)'}`;- const width = Math.max(...state.rows.map((r) => label(r).length));- const lines = ['graft init — select what to wire into this repo:', ''];+ const label = (r: PickerRow) => `${r.label}${r.detected || r.kind === 'setting' ? '' : ' (not detected)'}`;+ const width = Math.max(...visible.filter((r) => r.kind === 'host').map((r) => label(r).length), 12);+ const title = opts.title === undefined ? 'graft init — pick the agents your team uses:' : opts.title;+ const lines = title ? [title, ''] : [];let ruled = false;- for (const [i, row] of state.rows.entries()) {+ const foldLine = () => {+ if (hidden.length === 0) return;+ lines.push(+ dim(+ state.showHidden+ ? ` m to fold the ${hidden.length} not detected`+ : ` + ${hidden.length} not detected (${hidden.map((r) => r.label).join(', ')}) · m to show`,+ ),+ );+ };+ for (const [i, row] of visible.entries()) {// One rule between the agents and the settings, so the consent row reads as// a separate question rather than as another thing being installed.if (row.kind === 'setting' && !ruled) {- lines.push(dim(` ${'─'.repeat(width + 24)}`));+ foldLine();+ lines.push(dim(` ${'─'.repeat(40)}`));ruled = true;}const here = i === state.cursor;const box = state.checked.has(row.id) ? '[x]' : '[ ]';- const gap = ' '.repeat(width - label(row).length);+ const gap = ' '.repeat(Math.max(0, width - label(row).length));const name = here ? hot(row.label) : row.label;const tag = row.detected || row.kind === 'setting' ? '' : dim(' (not detected)');const summary = row.hasGlobal ? warn(row.summary) : dim(row.summary);- lines.push(`${here ? '›' : ' '} ${box} ${name}${tag}${gap} ${summary}`);+ lines.push(`${here ? '›' : ' '} ${box} ${name}${tag}${gap} ${summary}`);}- lines.push('', dim('↑↓ move · space toggle · a all · enter confirm · esc cancel'));+ if (!ruled) foldLine();+ const keys = ['↑↓ move', 'space toggle', 'a all', ...(hidden.length ? ['m more'] : []), 'enter confirm', 'esc cancel'];+ lines.push('', dim(keys.join(' · ')));return lines.join('\n');}@@ -265,7 +345,7 @@ export async function runPicker(plan: HostPlan[],repo: string,home: string,- opts: { offerTelemetry?: boolean } = {},+ opts: { offerTelemetry?: boolean; title?: string | null } = {},): Promise<Picked | null> {let state = initialPickerState(plan, repo, home, opts);const out = process.stderr;@@ -274,7 +354,7 @@ export async function runPicker(let lastLines = 0;const draw = () => {if (lastLines > 0) out.write(`\x1b[${lastLines}A\x1b[0J`);- const text = renderPicker(state);+ const text = renderPicker(state, true, { title: opts.title });out.write(`${text}\n`);lastLines = text.split('\n').length;};@@ -291,7 +371,10 @@ export async function runPicker(const finish = (onData: (b: Buffer) => void) => {stdin.off('data', onData);stdin.off('end', onEnd);- draw();+ // Erased, not redrawn: the choice is reported by what init prints next,+ // and an interactive widget left in the scrollback is noise.+ if (lastLines > 0) out.write(`\x1b[${lastLines}A\x1b[0J`);+ lastLines = 0;resolve(state.aborted ? null : { hosts: pickedHostIds(state), telemetry: pickedTelemetry(state) });};const onData = (buf: Buffer) => {diff --git a/src/cli.ts b/src/cli.tsindex e3d64c78..f8c661a4 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -24,22 +24,25 @@ import {buildEarlyDigest,buildLocalDigest,fetchExpectedRepo,+ pushContext,pushDigest,pushEarlyDigest,repoSlugFromGit,sameRepo,+ uploadCaps,} from "./brain/push.js";-import type { HistoryThread } from "./app/history.js";import { readLink, writeLink } from "./brain/link.js";import { withLegacyNames } from "./legacy-args.js";-import { applyChanges, fetchAcceptedChanges, markApplied } from "./brain/claude-md.js";-import { watchBuild } from "./brain/watch.js";-import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";+import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState, type Suggestions } from "./brain/watch.js";+import { brainUrl, openBrowser, reviewUrl, signupUrl, startHandoff } 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 {@@ -53,14 +56,15 @@ import {import { formatInitEpilogue } from "./cli-epilogue.js";import { planInit, selectedWrites } from "./hosts/plan.js";import { planRetract, runRetract, changed, type Retraction } 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, type BuildConfig } 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, wiredHostIds, writeStamp } from "./upkeep.js";+import { formatUpdateNudge, maybeRefreshInBackground, readStamp, readUpdateCache, refreshUpdateCache, wiredHostIds, writeStamp } from "./upkeep.js";import {errorCode,filesBucket,@@ -960,10 +964,24 @@ program.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("--trail <handoff>", "attach a Trail: <brainId>:<token> (or a bare id with GRAFT_BRAIN_TOKEN set)")- .action((dir: string, opts: InitOptions) => runInitCommand(dir, opts));+ .option("--verbose", "print every file written, the graph build's own output and the closing banner")+ .action(async (dir: string, opts: InitOptions) => {+ await runInitCommand(dir, opts);+ });/** `graft init`'s flags, as commander hands them over. */-interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; trail?: string }+interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; trail?: string; verbose?: boolean }++/** `a, b and c`. */+function joinAnd(items: string[]): string {+ 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: string, path: string): string {+ return relative(repo, path).split("\\").join("/");+}/*** `graft init`. Also run by `graft trail push` on a repo graft has not been set@@ -971,10 +989,14 @@ interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean;* 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: string, opts: InitOptions, how: { epilogue?: boolean } = {}): Promise<void> {+async function runInitCommand(+ dir: string,+ opts: InitOptions,+ how: { epilogue?: boolean; push?: boolean } = {},+): Promise<{ ids: string[] } | null> {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.@@ -984,7 +1006,7 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:if ("error" in parsed) {console.error(`✗ --trail: ${parsed.error}`);process.exitCode = 1;- return;+ return null;}brainLink = parsed;}@@ -1023,16 +1045,18 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?: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@@ -1056,11 +1080,11 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?: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");@@ -1069,9 +1093,60 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?: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: WireReport[] = [];for (const target of targets) {- if (target !== repo) console.error(`\n— ${relative(repo, target)}/`);- wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude });+ if (verbose && target !== repo) console.error(`\n— ${relative(repo, target)}/`);+ 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: string | null = 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<GlobalOpts>().dir));+ const fmt = (x: number) => 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: string) =>+ (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@@ -1079,11 +1154,35 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:// 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: string[] = [];+ 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@@ -1092,7 +1191,7 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:const graphs = (children.length ? children.map((c) => join(repo, c)) : [repo]).map((d) => loadGraphCached(contextDirFor(d, children.length ? undefined : globalDir))).filter((g): g is NonNullable<typeof g> => g !== null);- if (how.epilogue !== false) console.error(+ if (verbose && how.epilogue !== false) console.error("\n" +formatInitEpilogue({graphBuilt: graphs.length > 0,@@ -1106,6 +1205,15 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:{ agents: [...ids].sort().join(","), consent: consent === undefined ? "unasked" : String(consent) },{ repo },);+ return { ids };+}++/** What one target's wiring did, for the compact summary to report. */+interface WireReport {+ /** Hosts whose files were removed because they were not selected. */+ retracted: string[];+ /** ⚠ lines, printed in full. */+ warnings: string[];}/** One repo's worth of `init` writes — the parent, then each workspace child. */@@ -1118,9 +1226,20 @@ function wireTarget(plan: ReturnType<typeof planInit>;wantClaude: boolean;opts: { build?: boolean; mcp?: boolean; hooks?: boolean; global?: boolean; statusline?: boolean };+ /** Collect warnings and removals instead of printing a line per file, and+ * leave the graph build to the caller (see buildGraphWithProgress). */+ quiet?: boolean;},-): void {- const { home, cliPath, plan, wantClaude, opts } = ctx;+): WireReport {+ const { home, cliPath, plan, wantClaude } = ctx;+ const quiet = ctx.quiet === true;+ const opts = quiet ? { ...ctx.opts, build: false } : ctx.opts;+ const report: WireReport = { retracted: [], warnings: [] };+ // Every per-file line goes through here; in quiet mode only ⚠ lines survive.+ const say = (line: string) => {+ 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@@ -1132,25 +1251,26 @@ function wireTarget(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`);+ for (const r of retracted) 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}`);- for (const s of res.shims) console.error(`✓ wrote ${s}`);- console.error(`✓ wrote ${res.skill}`);+ say(`✓ wrote ${res.settingsPath}`);+ for (const s of res.shims) 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");- if (!wantStatusline) console.error("· skipped Claude Code statusLine (--no-statusline)");- for (const w of res.warnings) console.error(`⚠ ${w}`);+ 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) say("· skipped Claude Code statusLine (--no-statusline)");+ for (const w of res.warnings) say(`⚠ ${w}`);}// `ids` is already resolved, so hosts init is always driven by an explicit@@ -1164,12 +1284,12 @@ function wireTarget(hooks: opts.hooks,global: opts.global,});- for (const w of r.written) console.error(`✓ ${w.id}: ${w.path} (${w.action})`);- for (const m of r.mcp) console.error(`✓ mcp ${m.id}: ${m.path} (${m.action})`);- for (const h of r.hooks) console.error(`✓ hook ${h.id}: ${h.path} (${h.action})`);+ for (const w of r.written) say(`✓ ${w.id}: ${w.path} (${w.action})`);+ for (const m of r.mcp) say(`✓ mcp ${m.id}: ${m.path} (${m.action})`);+ for (const h of r.hooks) 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.@@ -1187,13 +1307,14 @@ function wireTarget(// 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". */@@ -1265,12 +1386,13 @@ const brain = program.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: string, slug: string): Promise<BrainLink | null> {const handoff = await startHandoff();@@ -1286,13 +1408,14 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n// 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:`);+ // "Opening your browser" only where one is about to open.+ console.error(`· ${slug} has no trail yet — ${process.stderr.isTTY ? "opening your browser to make one" : "make one at"}:`);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 trail connect <brainId>:<token>` here");+ console.error("· not a terminal — open the link above, then run graft trail connect <trailId>:<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.@@ -1302,9 +1425,25 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n}openBrowser(url);- console.error("· waiting for you to finish signing up…");-- const got = await handoff.wait();+ 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: (() => void) | undefined;+ const stopped = new Promise<"stopped">((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", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });+ process.exitCode = 130;+ return null;+ }if ("error" in got) {console.error(`✗ ${got.error}`);// The category, never the sentence: `got.error` names the repo and the link.@@ -1312,7 +1451,7 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | nreturn null;}writeLink(repo, got.link);- console.error(`✓ brain connected to ${slug}`);+ console.error(`✓ trail connected · ${slug} — your browser shows it building`);track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });return got.link;}@@ -1349,94 +1488,142 @@ brainbrain.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: string) => {- const repo = resolve(dir);- const res = await pullBrain(repo, { home: homedir() });- if (!res) {- console.error("· no brain attached — run `graft trail connect <brainId>:<token>`");- return;- }- if (res.warning) {- console.error(`⚠ ${res.warning}`);- process.exitCode = 1;- return;- }- console.error(`✓ pulled ${res.ruleCount} rule(s)`);- for (const w of res.writes) console.error(`✓ ${w.path} (${w.action})`);+ .option("--dry-run", "show what would change without writing anything or telling Trail")+ .action(async (dir: string, opts: { dryRun?: boolean }) => {+ await runTrailPullCommand(dir, opts);});+/** `graft trail pull`, and `graft claude-md pull` which is now the same thing. */+async function runTrailPullCommand(dir: string, opts: { dryRun?: boolean }): Promise<void> {+ const repo = resolve(dir);+ const link = readLink(repo);+ if (!link) {+ console.error("✗ this repo has no trail yet — run graft trail push first");+ process.exitCode = 1;+ return;+ }+ 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: Suggestions | undefined, wired: string[], again: boolean): string | null {+ if (!s) return null;+ let count = 0;+ const kinds = new Set<string>();+ 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")- .action(async (dir: string, opts: { approve?: boolean; watch?: boolean }) => {+ .option("--verbose", "print each step's counts and every build stage as it finishes")+ .action(async (dir: string, opts: { approve?: boolean; watch?: boolean; verbose?: boolean }) => {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;-- 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.");- // The instruction file and the newest pull requests go first, when the brain- // takes them: its CLAUDE.md suggestions start from those while the rest of- // the history is still being read here. Not awaited — the full read starts- // at once, reusing the threads the early one already fetched.- let early: Promise<unknown> = Promise.resolve();- let knownThreads: HistoryThread[] = [];+ // 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<void> = Promise.resolve();if (expected?.earlyUpload) {- const first = await buildEarlyDigest(repo);- if (first) {- knownThreads = first.threads;- early = pushEarlyDigest(link, first.digest).then((ok) => {- if (ok) console.error("· CLAUDE.md suggestions are on their way in your browser, from the newest pull requests");- });- }+ 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 — after the early- // upload has gone, so the CLAUDE.md suggestions are not held up by the graph- // build. Same picker as init: it is how someone agrees to what gets written,- // so a non-interactive push only says what to run.++ // 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 && process.stderr.isTTY) {- // Its one line of output lands before the picker, not across it.- await early;- console.error("· graft is not set up in this repo yet — setting it up first, the same as `graft init`");- await runInitCommand(repo, { build: true, mcp: true, hooks: true, statusline: true, global: true }, { epilogue: false });+ 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 is not set up in this repo — run `graft init` so your coding agent reads these rules");+ console.error("· graft isn't set up here — run graft init so your agents read these rules");}}@@ -1444,130 +1631,133 @@ brain// 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<GlobalOpts>().dir));- if (!graph) console.error("· no graph yet — run `graft build` first so rules can be anchored to symbols");- const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, knownThreads });- await early;+ if (!graph) 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: number) => 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: RepoState | null = 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 as RepoState | null)?.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 trail 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");+ } else {+ console.error("· still building after 15 minutes — not failed, just long; 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.");+ 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 brain suggested and you accepted in Trail");+ .description("The CLAUDE.md changes this repo's trail suggested (now part of graft trail pull)");claudeMd.command("pull")- .description("Write the CLAUDE.md changes you accepted in Trail into this repo's instruction file")+ .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 the file or telling Trail")+ .option("--dry-run", "show what would change without writing anything or telling Trail").action(async (dir: string, opts: { dryRun?: boolean }) => {- const repo = resolve(dir);- const link = readLink(repo);- if (!link) {- console.error("✗ this repo has no brain attached — run `graft trail push` first");- process.exitCode = 1;- return;- }- const pulled = await fetchAcceptedChanges(link);- if ("error" in pulled) {- console.error(`✗ ${pulled.error}`);- process.exitCode = 1;- return;- }- if (pulled.changes.length === 0) {- console.error("· nothing accepted yet — accept suggestions on the brain's CLAUDE.md page, then pull again");- return;- }- // The file Trail read, or a new CLAUDE.md when the repo had none.- const rel = pulled.path || "CLAUDE.md";- const file = join(repo, rel);- const { existsSync, readFileSync, writeFileSync } = await import("node:fs");- const before = existsSync(file) ? readFileSync(file, "utf8") : "";- const result = applyChanges(before, pulled.changes);-- for (const c of result.written) console.error(` + ${c.kind === "add" ? "new section" : "edit"} · ${c.heading}`);- for (const c of result.present) console.error(` = already in the file · ${c.heading}`);- for (const s of result.skipped) console.error(` ! skipped · ${s.change.heading} — ${s.why}`);-- if (opts.dryRun) {- console.error(`· dry run: ${result.written.length} change(s) would be written to ${rel}; nothing was written`);- return;- }- if (result.written.length > 0) writeFileSync(file, result.text);- // Written now or already there: either way the page should stop listing it.- const done = [...result.written, ...result.present].map((c) => c.id);- const told = await markApplied(link, done);- if (result.written.length > 0) {- console.error(`✓ wrote ${result.written.length} change(s) to ${rel} — review and commit it like any other edit`);- } else if (result.present.length > 0) {- console.error(`✓ ${rel} already has every accepted change`);- }- if (!told) console.error("⚠ could not tell Trail which changes were written; the page may still list them");- if (result.skipped.length > 0) {- console.error(- `· ${result.skipped.length} change(s) no longer match the local file — edit them on the CLAUDE.md page, or apply them by hand`,- );- process.exitCode = 1;- }+ console.error("· graft claude-md pull is now part of graft trail pull — running that");+ await runTrailPullCommand(dir, opts);});braindiff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex 2933b1af..49c09378 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -109,14 +109,15 @@ export function isTrackedCommand(name: string): name is TrackedCommand {/*** How a `graft trail push` signup ended.*- * Four categories and nothing else, because the alternative — the error string+ * Five categories and nothing else, because the alternative — the error string* the CLI already prints — carries a repo slug and a URL. `timed_out` and* `no_tty` are deliberately apart: one is a person who opened the browser and* did not finish, the other is a machine that was never able to open one, and* treating them alike would read as a product problem where there is only a- * remote shell.+ * remote shell. `stopped` is Ctrl-C while waiting: a person changing their+ * mind, not a browser that never came back.*/-export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback'] as const;+export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback', 'stopped'] as const;export type BrainSignupOutcome = (typeof BRAIN_SIGNUP_OUTCOMES)[number];/** Where a failing build died. Coarse on purpose: enough to route a bug, notdiff --git a/src/util/spinner.ts b/src/util/spinner.tsnew file mode 100644index 00000000..149a7e8f--- /dev/null+++ b/src/util/spinner.ts@@ -0,0 +1,63 @@+/**+ * One line that redraws in place while something runs, and is erased when it+ * stops — so nothing interactive is left in the scrollback.+ *+ * Only on a TTY. Anywhere else every method is a no-op, and the caller prints+ * whatever finished lines it wants a log to keep.+ */+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];++export interface Spinner {+ /** Change the text after the frame. */+ update(text: string): void;+ /** Print a finished line above the spinner, which keeps spinning below it. */+ print(line: string): void;+ /** Erase the line and stop. Safe to call more than once. */+ stop(): void;+ readonly active: boolean;+}++export function startSpinner(+ text: string,+ opts: { stream?: NodeJS.WriteStream; enabled?: boolean; intervalMs?: number } = {},+): Spinner {+ const out = opts.stream ?? process.stderr;+ const enabled = opts.enabled ?? Boolean(out.isTTY);+ if (!enabled) {+ return { update() {}, print: (line) => out.write(`${line}\n`), stop() {}, active: false };+ }+ let current = text;+ let frame = 0;+ let stopped = false;+ const width = () => Math.max(20, (out.columns || 100) - 1);+ const draw = () => {+ if (stopped) return;+ const line = `${FRAMES[frame % FRAMES.length]} ${current}`;+ out.write(`\r\x1b[2K${line.length > width() ? line.slice(0, width()) : line}`);+ frame++;+ };+ const clear = () => out.write("\r\x1b[2K");+ draw();+ const timer = setInterval(draw, opts.intervalMs ?? 80);+ timer.unref?.();+ return {+ get active() {+ return !stopped;+ },+ update(next: string) {+ current = next;+ draw();+ },+ print(line: string) {+ clear();+ out.write(`${line}\n`);+ draw();+ },+ stop() {+ if (stopped) return;+ stopped = true;+ clearInterval(timer);+ clear();+ },+ };+}diff --git a/test/app-sources-context.test.ts b/test/app-sources-context.test.tsnew file mode 100644index 00000000..14b64d51--- /dev/null+++ b/test/app-sources-context.test.ts@@ -0,0 +1,80 @@+/**+ * The early upload carries every file a team wrote for its agents, not only+ * the root ones: folder CLAUDE.md / AGENTS.md files and Claude skills. What+ * matters is which ones — shallow enough, outside dependencies and build+ * output, not ignored, never graft's own — and that there is a cap.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdirSync, writeFileSync } from 'node:fs';+import { spawnSync } from 'node:child_process';+import { dirname, join } from 'node:path';+import { folderInstructionFiles, readAgentInstructions, skillFiles } from '../src/app/sources.js';+import { tmpRepo } from './helpers.js';++function put(root: string, rel: string, text: string): void {+ mkdirSync(dirname(join(root, rel)), { recursive: true });+ writeFileSync(join(root, rel), text);+}++function fixture(): string {+ const root = tmpRepo('sources');+ put(root, 'CLAUDE.md', '# root\n\nUse pnpm.\n');+ put(root, 'web/CLAUDE.md', '# web\n\nComponents are PascalCase.\n');+ put(root, 'services/api/AGENTS.md', '# api\n\nHandlers stay thin.\n');+ put(root, 'a/b/c/d/CLAUDE.md', '# depth four\n\nStill read.\n');+ put(root, 'a/b/c/d/e/CLAUDE.md', '# depth five\n\nToo deep.\n');+ put(root, 'node_modules/pkg/CLAUDE.md', '# dependency\n');+ put(root, 'dist/CLAUDE.md', '# build output\n');+ put(root, 'graft/CLAUDE.md', '# graft cache\n');+ put(root, '.hidden/CLAUDE.md', '# dot dir\n');+ put(root, 'scratch/CLAUDE.md', '# ignored by the repo\n');+ put(root, '.gitignore', 'scratch/\n');+ put(root, '.claude/skills/deploy/SKILL.md', '---\nname: deploy\n---\nAlways deploy from main.\n');+ put(root, '.claude/skills/graft/SKILL.md', '---\nname: graft\n---\ngraft teaches graft\n');+ put(root, '.claude/skills/empty/README.md', 'no skill file here\n');+ put(root, 'web/AGENTS.md', 'before\n<!-- graft:start -->\ngraft block\n<!-- graft:end -->\nafter\n');+ return root;+}++test('folder instruction files: shallow ones, outside ignored and generated dirs, shallowest first', () => {+ const root = fixture();+ spawnSync('git', ['init', '-q'], { cwd: root });+ const got = folderInstructionFiles(root);+ assert.deepEqual(got, ['web/AGENTS.md', 'web/CLAUDE.md', 'services/api/AGENTS.md', 'a/b/c/d/CLAUDE.md']);+});++test('folder instruction files are found without git too', () => {+ const root = fixture();+ const got = folderInstructionFiles(root);+ // No git to read .gitignore, so scratch/ is read; everything else is the same.+ assert.ok(got.includes('web/CLAUDE.md') && got.includes('a/b/c/d/CLAUDE.md'));+ assert.ok(!got.some((p) => /node_modules|dist|graft\/|\.hidden|\/e\//.test(p)), got.join(', '));+});++test('folder instruction files are capped', () => {+ const root = tmpRepo('sources-cap');+ for (let i = 0; i < 40; i++) put(root, `pkg${String(i).padStart(2, '0')}/CLAUDE.md`, `# ${i}\n\nrule ${i}\n`);+ assert.equal(folderInstructionFiles(root).length, 30);+ assert.equal(folderInstructionFiles(root, 5).length, 5);+});++test('skills: every SKILL.md but graft\'s own', () => {+ const root = fixture();+ assert.deepEqual(skillFiles(root), ['.claude/skills/deploy/SKILL.md']);+});++test('readAgentInstructions carries them all as agent_instructions, graft blocks stripped', () => {+ const root = fixture();+ spawnSync('git', ['init', '-q'], { cwd: root });+ const got = readAgentInstructions(root);+ const paths = got.map((s) => s.path);+ for (const p of ['CLAUDE.md', 'web/CLAUDE.md', 'services/api/AGENTS.md', '.claude/skills/deploy/SKILL.md']) {+ assert.ok(paths.includes(p), `${p} missing from ${paths.join(', ')}`);+ }+ assert.ok(got.every((s) => s.kind === 'agent_instructions'));+ const web = got.find((s) => s.path === 'web/AGENTS.md')!;+ assert.doesNotMatch(web.text, /graft block/);+ assert.match(web.text, /before[\s\S]*after/);+ assert.ok(!paths.includes('.claude/skills/graft/SKILL.md'));+});diff --git a/test/brain-context-files-pull.test.ts b/test/brain-context-files-pull.test.tsnew file mode 100644index 00000000..6449429b--- /dev/null+++ b/test/brain-context-files-pull.test.ts@@ -0,0 +1,215 @@+/**+ * `graft trail pull` writes accepted changes into every context file, not only+ * the root CLAUDE.md. It edits files people also edit by hand, so the tests are+ * about restraint: a whole-file change never overwrites someone's file, a+ * replace only lands on the file it was computed against, a path from Trail+ * never escapes the repo, and files for agents nobody picked are left alone.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { dirname, join } from 'node:path';+import { planContextFile, readByWired, safeRelPath, writePlannedFile, type ContextFile } from '../src/brain/context-files.js';+import { runTrailPull } from '../src/brain/pull.js';+import type { BrainLink } from '../src/brain/link.js';+import { tmpRepo } from './helpers.js';++function put(root: string, rel: string, text: string): void {+ mkdirSync(dirname(join(root, rel)), { recursive: true });+ writeFileSync(join(root, rel), text);+}++const AGENTS = ['# api', '', '## Commands', '', '- `make test` runs the unit tests.', '', '## Style', '', '- gofmt everything.', ''].join('\n');++test('edit and add patch the file exactly as the CLAUDE.md pull does', () => {+ const root = tmpRepo('ctx-edit');+ put(root, 'services/api/AGENTS.md', AGENTS);+ const plan = planContextFile(root, {+ kind: 'agents_md',+ path: 'services/api/AGENTS.md',+ changes: [+ { id: 'e1', kind: 'edit', heading: 'Commands', find: '- `make test` runs the unit tests.', text: '- `make test` runs unit and integration tests.' },+ { id: 'a1', kind: 'add', heading: 'Money', after_heading: 'Commands', text: 'Amounts are integer cents.' },+ ],+ });+ assert.equal(plan.status, 'M');+ assert.deepEqual(plan.written.map((c) => c.id), ['e1', 'a1']);+ assert.match(plan.text!, /## Commands\n\n- `make test` runs unit and integration tests\.\n\n## Money\n\nAmounts are integer cents\.\n\n## Style/);+ assert.match(plan.text!, /- gofmt everything\./, 'untouched sections come back as they were');+});++test('create writes a new file, folders and all', () => {+ const root = tmpRepo('ctx-create');+ const plan = planContextFile(root, {+ kind: 'cursor_rule',+ path: '.cursor/rules/money.mdc',+ changes: [{ id: 'c1', kind: 'create', text: '---\ndescription: money\n---\nAmounts are integer cents.' }],+ });+ assert.equal(plan.status, 'A');+ writePlannedFile(root, plan);+ assert.equal(readFileSync(join(root, '.cursor/rules/money.mdc'), 'utf8'), '---\ndescription: money\n---\nAmounts are integer cents.\n');+});++test('create over an identical file counts as applied and writes nothing', () => {+ const root = tmpRepo('ctx-same');+ put(root, 'web/CLAUDE.md', '# web\r\n\r\nPascalCase components.\r\n');+ const plan = planContextFile(root, {+ kind: 'folder_claude_md',+ path: 'web/CLAUDE.md',+ changes: [{ id: 'c2', kind: 'create', text: '# web\n\nPascalCase components.' }],+ });+ assert.equal(plan.status, '');+ assert.deepEqual(plan.present.map((c) => c.id), ['c2']);+});++test('create over a different file is a conflict, and the file is left alone', () => {+ const root = tmpRepo('ctx-conflict');+ put(root, 'web/CLAUDE.md', '# web\n\nOurs.\n');+ const plan = planContextFile(root, {+ kind: 'folder_claude_md',+ path: 'web/CLAUDE.md',+ changes: [{ id: 'c3', kind: 'create', text: '# web\n\nTheirs.\n' }],+ });+ assert.equal(plan.status, '');+ assert.equal(plan.skipped.length, 1);+ assert.match(plan.skipped[0].why, /other content/);+});++test('create over a file graft owns replaces it', () => {+ const root = tmpRepo('ctx-managed');+ put(root, '.cursor/rules/graft.mdc', 'old graft rule\n');+ const plan = planContextFile(root, {+ kind: 'cursor_rule',+ path: '.cursor/rules/graft.mdc',+ managed_by_graft: true,+ changes: [{ id: 'c4', kind: 'create', text: 'new graft rule\n' }],+ });+ assert.equal(plan.status, 'M');+ assert.equal(plan.text, 'new graft rule\n');+});++test('replace lands only on the file it was computed against', () => {+ const root = tmpRepo('ctx-replace');+ put(root, '.cursor/rules/style.mdc', 'Use tabs.\r\n');+ const change = { id: 'r1', kind: 'replace' as const, find: 'Use tabs.\n', text: 'Use two spaces.\n' };+ const ok = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });+ assert.equal(ok.status, 'M');+ assert.equal(ok.text, 'Use two spaces.\n');++ put(root, '.cursor/rules/style.mdc', 'Use tabs. And semicolons.\n');+ const moved = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });+ assert.equal(moved.status, '');+ assert.match(moved.skipped[0].why, /changed here since Trail read it/);++ put(root, '.cursor/rules/style.mdc', 'Use two spaces.\n');+ const done = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });+ assert.deepEqual(done.present.map((c) => c.id), ['r1']);+});++test('an edit to a file that is not here yet creates it', () => {+ const root = tmpRepo('ctx-missing');+ const plan = planContextFile(root, {+ kind: 'folder_claude_md',+ path: 'web/CLAUDE.md',+ changes: [{ id: 'e2', kind: 'edit', heading: 'Frontend', find: '', text: 'Components are PascalCase.' }],+ });+ assert.equal(plan.status, 'A');+ assert.equal(plan.text, '## Frontend\n\nComponents are PascalCase.\n');+});++test('a path from Trail never leaves the repo', () => {+ const root = tmpRepo('ctx-safe');+ for (const bad of ['../outside.md', '/etc/passwd', 'a/../../b.md', '.git/config', 'C:/x.md', '']) {+ assert.equal(safeRelPath(root, bad), null, bad);+ }+ assert.equal(safeRelPath(root, 'web/CLAUDE.md'), 'web/CLAUDE.md');+ const plan = planContextFile(root, { kind: 'agents_md', path: '../AGENTS.md', changes: [{ id: 'x', kind: 'create', text: 'x' }] });+ assert.equal(plan.status, '');+ assert.equal(plan.skipped.length, 1);+});++test('files are only for the agents that were picked', () => {+ assert.equal(readByWired('cursor_rule', ['claude']), false);+ assert.equal(readByWired('agents_md', ['claude', 'agents']), true);+ assert.equal(readByWired('skill', ['claude']), true);+ assert.equal(readByWired('cursor_rule', []), true, 'nothing wired means no choice to respect');+});++// --- the whole pull, against a fake Trail ---------------------------------------++const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;+const json = (body: unknown, status = 200) =>+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });++function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing' } = {}) {+ const applied: Record<string, string[]> = {};+ const f = (async (u: string, init?: RequestInit) => {+ const path = new URL(u).pathname;+ if (path.endsWith('/rules/anchors')) return json({ anchors: [] });+ if (path.endsWith('/claude-md')) {+ return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });+ }+ if (path.endsWith('/context-files')) {+ return opts.contextFiles === 'missing' ? json({ error: 'not found' }, 404) : json({ head_sha: 'abc', files });+ }+ if (path.endsWith('/applied')) {+ applied[path] = (JSON.parse(String(init?.body)) as { ids: string[] }).ids;+ return json({ applied: 1 });+ }+ return json({ error: 'unexpected' }, 500);+ }) as typeof fetch;+ return { f, applied };+}++test('a pull writes the CLAUDE.md changes, then every other file, and tells Trail which', async () => {+ const root = tmpRepo('ctx-pull');+ put(root, 'CLAUDE.md', '# app\n\n## Commands\n\n- `npm test`\n');+ put(root, 'web/CLAUDE.md', '# web\n\nOurs.\n');+ const { f, applied } = fakeTrail([+ { kind: 'agents_md', path: 'AGENTS.md', changes: [{ id: 'g1', kind: 'create', text: '# agents\n\nInteger cents.\n' }] },+ { kind: 'folder_claude_md', path: 'web/CLAUDE.md', changes: [{ id: 'w1', kind: 'create', text: '# web\n\nTheirs.\n' }] },+ { kind: 'cursor_rule', path: '.cursor/rules/money.mdc', changes: [{ id: 'k1', kind: 'create', text: 'cents\n' }] },+ ]);+ const lines: string[] = [];+ const code = await runTrailPull(root, link, { home: root, wired: ['claude', 'agents'], fetchImpl: f, write: (l) => lines.push(l) });+ const out = lines.join('\n');++ assert.equal(code, 1, 'the conflict makes it exit non-zero, as claude-md pull did');+ assert.match(out, /✓ wrote 2 accepted changes/);+ assert.match(out, / M CLAUDE\.md +\+ Money/);+ assert.match(out, / A AGENTS\.md/);+ assert.match(out, /⚠ skipped web\/CLAUDE\.md — a file with other content is already there; edit it in Trail, then pull again/);+ assert.doesNotMatch(out, /money\.mdc/, 'cursor was not picked, so its rule is neither listed nor written');+ assert.match(out, /review with git diff, then commit/);++ assert.match(readFileSync(join(root, 'CLAUDE.md'), 'utf8'), /## Money\n\nInteger cents\./);+ assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# agents\n\nInteger cents.\n');+ assert.equal(readFileSync(join(root, 'web/CLAUDE.md'), 'utf8'), '# web\n\nOurs.\n');+ assert.ok(!existsSync(join(root, '.cursor/rules/money.mdc')));++ assert.deepEqual(applied['/api/public/brains/b1/claude-md/applied'], ['m1']);+ assert.deepEqual(applied['/api/public/brains/b1/context-files/applied'], ['g1'], 'only what was written, never the conflict');+});++test('a dry run writes nothing and tells Trail nothing', async () => {+ const root = tmpRepo('ctx-dry');+ const { f, applied } = fakeTrail([+ { kind: 'agents_md', path: 'AGENTS.md', changes: [{ id: 'g1', kind: 'create', text: 'x\n' }] },+ ]);+ const lines: string[] = [];+ await runTrailPull(root, link, { home: root, wired: [], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });+ assert.match(lines.join('\n'), /✓ would write 2 accepted changes/);+ assert.match(lines.join('\n'), /dry run — nothing written, and Trail was not told/);+ assert.ok(!existsSync(join(root, 'AGENTS.md')) && !existsSync(join(root, 'CLAUDE.md')));+ assert.deepEqual(applied, {});+});++test('a Trail without context files still pulls CLAUDE.md, silently', async () => {+ const root = tmpRepo('ctx-older');+ const { f } = fakeTrail([], { contextFiles: 'missing' });+ const lines: string[] = [];+ const code = await runTrailPull(root, link, { home: root, wired: ['claude'], fetchImpl: f, write: (l) => lines.push(l) });+ assert.equal(code, 0);+ assert.match(lines.join('\n'), /✓ wrote 1 accepted change\n A CLAUDE\.md +\+ Money/);+ assert.doesNotMatch(lines.join('\n'), /✗/);+});diff --git a/test/brain-early-upload.test.ts b/test/brain-early-upload.test.tsindex 52613dd3..741efab3 100644--- a/test/brain-early-upload.test.ts+++ b/test/brain-early-upload.test.ts@@ -8,7 +8,7 @@import { test } from 'node:test';import assert from 'node:assert/strict';import { fetchExpectedRepo, pushEarlyDigest } from '../src/brain/push.js';-import { readThreads, type HistoryThread, type RepoDigest } from '../src/app/history.js';+import { newThreadReadCache, readThreads, THREAD_FETCH_CONCURRENCY, type HistoryThread, type RepoDigest } from '../src/app/history.js';import type { BrainLink } from '../src/brain/link.js';const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;@@ -71,3 +71,48 @@ test('the full read reuses threads the early upload already fetched', async () =assert.ok(!fetched.some((u) => /\/(issues|pulls)\/2\/comments/.test(u)), 'no comment request for #2');assert.ok(fetched.some((u) => /\/(issues|pulls)\/1\/comments/.test(u)));});++// The early read and the full read share one cache, so a thread the early read+// is still fetching is waited on, not fetched again — and one with no+// discussion is remembered too, which a map of finished threads cannot say.+test('the early and full reads share every GitHub request, even ones in flight', async () => {+ const fetched: string[] = [];+ const fake = (async (u: string) => {+ fetched.push(u);+ await new Promise((r) => setTimeout(r, 5));+ if (u.includes('/pulls?state=closed')) {+ return json(/&page=1$/.test(u) ? Array.from({ length: 40 }, (_, i) => ({ number: 40 - i, title: `pr ${40 - i}` })) : []);+ }+ // Odd pull requests have no discussion at all.+ const n = Number(/\/(\d+)\/comments/.exec(u)?.[1]);+ return json(n % 2 ? [] : [{ body: `on #${n}`, user: { type: 'User' } }]);+ }) as never;++ const cache = newThreadReadCache();+ const [early, full] = await Promise.all([+ readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 30, undefined, cache),+ readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 200, undefined, cache),+ ]);+ assert.equal(early.length, 15);+ assert.equal(full.length, 20);+ const perThread = fetched.filter((u) => /\/issues\/\d+\/comments/.test(u));+ assert.equal(perThread.length, 40, 'each pull request asked about once, however many reads wanted it');+ assert.equal(fetched.filter((u) => u.includes('/pulls?state=closed') && /&page=1$/.test(u)).length, 1, 'the first page of the list is read once');+});++test('comment reads run in a pool, not in batches that wait for their slowest', async () => {+ let inFlight = 0;+ let peak = 0;+ const fake = (async (u: string) => {+ if (u.includes('/pulls?state=closed')) {+ return json(/&page=1$/.test(u) ? Array.from({ length: 60 }, (_, i) => ({ number: i + 1 })) : []);+ }+ inFlight++;+ peak = Math.max(peak, inFlight);+ await new Promise((r) => setTimeout(r, 2));+ inFlight--;+ return json([]);+ }) as never;+ await readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 60);+ assert.equal(peak, THREAD_FETCH_CONCURRENCY * 2, 'two comment endpoints per pull request, 24 pull requests at once');+});diff --git a/test/brain-signup.test.ts b/test/brain-signup.test.tsindex 1561f14c..84c0b0eb 100644--- a/test/brain-signup.test.ts+++ b/test/brain-signup.test.ts@@ -64,7 +64,7 @@ test("handoff: the wait gives up rather than hanging forever", async () => {const h = await startHandoff();const got = await h.wait(150);assert.ok("error" in got);- assert.match((got as { error: string }).error, /timed out/);+ assert.match((got as { error: string }).error, /no sign-up after .* · nothing was sent — run graft trail push again/);});test("signup url: carries the repo, the port and the state", () => {diff --git a/test/brain-upload.test.ts b/test/brain-upload.test.tsnew file mode 100644index 00000000..6daf4520--- /dev/null+++ b/test/brain-upload.test.ts@@ -0,0 +1,243 @@+/**+ * The full digest goes up gzipped, and in retried 1 MiB chunks when Trail says+ * it takes them. What matters: the chunks reassemble into exactly the gzip of+ * the body a single POST would have sent, a blip costs one chunk rather than+ * the push, and an older Trail still gets the plain POST it always did.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { gunzipSync } from 'node:zlib';+import { uploadDigest, uploadChunked, RETRY_DELAYS_MS } from '../src/brain/upload.js';+import { fetchExpectedRepo, pushEarlyDigest, uploadCaps } from '../src/brain/push.js';+import type { RepoDigest } from '../src/app/history.js';+import type { BrainLink } from '../src/brain/link.js';++const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;+const json = (body: unknown, status = 200) =>+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });++/** A digest big enough to need several chunks at a small chunk size. */+function digest(): RepoDigest {+ return {+ provider: 'github',+ owner: 'chalk',+ name: 'chalk',+ head_sha: 'abc',+ default_branch: 'main',+ is_private: false,+ commits: Array.from({ length: 400 }, (_, i) => ({+ sha: `${i}`.padStart(40, '0'),+ subject: `commit ${i} ${Math.random().toString(36)}`,+ body: '',+ files: [`src/${i}.ts`],+ symbols: [],+ })),+ threads: [],+ symbols: [],+ sources: [],+ auto_approve: true,+ };+}++interface Call {+ method: string;+ url: string;+ headers: Record<string, string>;+ body: unknown;+}++function recorder(respond: (c: Call, n: number) => Response | Promise<Response>) {+ const calls: Call[] = [];+ const f = (async (u: string, init?: RequestInit) => {+ const c: Call = {+ method: init?.method ?? 'GET',+ url: u,+ headers: (init?.headers ?? {}) as Record<string, string>,+ body: init?.body,+ };+ calls.push(c);+ return respond(c, calls.length);+ }) as typeof fetch;+ return { calls, f };+}++const noSleep = { sleep: async () => {} };++test('chunks reassemble into the gzip of exactly the body a single POST would send', async () => {+ const d = digest();+ const chunks = new Map<number, Buffer>();+ let opened: Record<string, unknown> = {};+ const { calls, f } = recorder((c) => {+ if (c.method === 'POST' && c.url.endsWith('/repo/uploads')) {+ opened = JSON.parse(String(c.body));+ return json({ upload_id: 'u-1' }, 201);+ }+ const m = /\/uploads\/u-1\/chunks\/(\d+)$/.exec(c.url);+ if (c.method === 'PUT' && m) {+ chunks.set(Number(m[1]), Buffer.from(c.body as Uint8Array));+ return new Response(null, { status: 204 });+ }+ if (c.url.endsWith('/uploads/u-1/complete')) return json({ repo: {}, job_id: 'job-9', status: 'queued' }, 202);+ return json({ error: 'unexpected' }, 500);+ });++ const got = await uploadDigest(link, d, { gzip: true, chunked: true }, { fetchImpl: f, chunkBytes: 2048, ...noSleep });+ assert.deepEqual(got, { jobId: 'job-9' });++ assert.equal(opened.stage, 'full');+ assert.equal(opened.auto_approve, true);+ assert.equal(opened.chunks, chunks.size);+ assert.ok(chunks.size > 1, 'the test digest must need more than one chunk');+ const joined = Buffer.concat([...chunks.keys()].sort((a, b) => a - b).map((i) => chunks.get(i)!));+ assert.equal(opened.bytes, joined.length);+ assert.equal(gunzipSync(joined).toString('utf8'), JSON.stringify(d));++ const put = calls.find((c) => c.method === 'PUT')!;+ assert.equal(put.headers['content-type'], 'application/octet-stream');+ assert.equal(put.headers.authorization, 'Bearer gbt_1.x');+ assert.match(put.url, /^http:\/\/trail\.test\/api\/public\/brains\/b1\/repo\/uploads\/u-1\/chunks\/\d+$/);+});++test('a chunk that fails is retried on its own, on 5xx, 429 and network errors', async () => {+ const attempts = new Map<string, number>();+ const waits: number[] = [];+ const { f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-2' }, 201);+ if (c.method === 'PUT') {+ const n = (attempts.get(c.url) ?? 0) + 1;+ attempts.set(c.url, n);+ if (c.url.endsWith('/chunks/1')) {+ if (n === 1) return json({ error: 'busy' }, 503);+ if (n === 2) return json({ error: 'slow down' }, 429);+ if (n === 3) throw new Error('ECONNRESET');+ }+ return new Response(null, { status: 204 });+ }+ return json({ job_id: 'job-2' }, 202);+ });+ const got = await uploadChunked(link, digest(), {+ fetchImpl: f,+ chunkBytes: 2048,+ sleep: async (ms) => void waits.push(ms),+ });+ assert.deepEqual(got, { jobId: 'job-2' });+ assert.equal(attempts.get('http://trail.test/api/public/brains/b1/repo/uploads/u-2/chunks/1'), 4);+ assert.equal(attempts.get('http://trail.test/api/public/brains/b1/repo/uploads/u-2/chunks/0'), 1, 'the others went once');+ assert.deepEqual(waits, [500, 1000, 2000], 'backoff doubles from half a second');+});++test('a chunk that keeps failing gives up after four retries and says which part', async () => {+ let tries = 0;+ const { f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-3' }, 201);+ if (c.method === 'PUT') {+ tries++;+ return json({ error: 'down' }, 502);+ }+ return json({ job_id: 'never' }, 202);+ });+ const got = await uploadChunked(link, digest(), { fetchImpl: f, chunkBytes: 1 << 20, ...noSleep });+ assert.ok('error' in got && /part 1 of 1: 502/.test(got.error), JSON.stringify(got));+ assert.equal(tries, RETRY_DELAYS_MS.length + 1);+});++test('complete is retried on 5xx, and returns today\'s ingest response', async () => {+ let completes = 0;+ const { f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-4' }, 201);+ if (c.method === 'PUT') return new Response(null, { status: 204 });+ completes++;+ return completes < 3 ? json({ error: 'hiccup' }, 500) : json({ repo: {}, job_id: 'job-4', status: 'queued' }, 202);+ });+ assert.deepEqual(await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep }), { jobId: 'job-4' });+ assert.equal(completes, 3);+});++test('a 409 from complete is passed on as a refusal, as the single POST would be', async () => {+ const { f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-5' }, 201);+ if (c.method === 'PUT') return new Response(null, { status: 204 });+ return json({ error: 'an ingest is already running' }, 409);+ });+ const got = await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep });+ assert.ok('error' in got && /409 .*already running/.test(got.error));+});++test('a complete lost on the way back, then told 409 on its retry, counts as started', async () => {+ let completes = 0;+ const { f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-6' }, 201);+ if (c.method === 'PUT') return new Response(null, { status: 204 });+ completes++;+ if (completes === 1) throw new Error('socket hang up');+ return json({ error: 'an ingest is already running' }, 409);+ });+ assert.deepEqual(await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep }), { jobId: '' });+});++test('a server that advertised chunks but has no route falls back to the single POST', async () => {+ const { calls, f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ error: 'not found' }, 404);+ return json({ job_id: 'job-7' }, 202);+ });+ const got = await uploadDigest(link, digest(), { chunked: true, gzip: true }, { fetchImpl: f, ...noSleep });+ assert.deepEqual(got, { jobId: 'job-7' });+ const post = calls.at(-1)!;+ assert.equal(post.url, 'http://trail.test/api/public/brains/b1/repo');+ assert.equal(post.headers['content-encoding'], 'gzip');+});++test('an older Trail gets the plain POST it always did', async () => {+ const d = digest();+ const { calls, f } = recorder(() => json({ job_id: 'job-8' }, 202));+ assert.deepEqual(await uploadDigest(link, d, {}, { fetchImpl: f }), { jobId: 'job-8' });+ assert.equal(calls.length, 1);+ assert.equal(calls[0].headers['content-encoding'], undefined);+ assert.equal(calls[0].body, JSON.stringify(d));+});++test('gzip alone is one gzipped POST of the same body', async () => {+ const d = digest();+ const { calls, f } = recorder(() => json({ job_id: 'job-10' }, 202));+ await uploadDigest(link, d, { gzip: true }, { fetchImpl: f });+ assert.equal(calls.length, 1);+ assert.equal(calls[0].headers['content-encoding'], 'gzip');+ assert.equal(gunzipSync(Buffer.from(calls[0].body as Uint8Array)).toString('utf8'), JSON.stringify(d));+});++test('the early upload is gzipped only when Trail says it takes gzip', async () => {+ const { calls, f } = recorder(() => json({ early: true }, 202));+ assert.equal(await pushEarlyDigest(link, digest(), f, { gzip: true }), true);+ assert.equal(calls[0].headers['content-encoding'], 'gzip');+ assert.match(calls[0].url, /\/repo\?stage=early$/);+ await pushEarlyDigest(link, digest(), f);+ assert.equal(calls[1].headers['content-encoding'], undefined);+});++test('the capability flags are read off the expected-repo response, and default to off', async () => {+ const older = await fetchExpectedRepo(link, (async () => json({ repo: { slug: 'chalk/chalk' } })) as typeof fetch);+ assert.deepEqual(uploadCaps(older), { gzip: false, chunked: false });+ assert.equal(older?.events, false);+ const newer = await fetchExpectedRepo(link, (async () =>+ json({ repo: { slug: 'chalk/chalk', rule_count: 12 }, gzip_upload: true, chunked_upload: true, events: true })) as typeof fetch);+ assert.deepEqual(uploadCaps(newer), { gzip: true, chunked: true });+ assert.equal(newer?.events, true);+ assert.equal(newer?.ruleCount, 12);+});++test('every call honours GRAFT_BRAIN_URL', async () => {+ const before = process.env.GRAFT_BRAIN_URL;+ process.env.GRAFT_BRAIN_URL = 'https://staging-agents.test/';+ try {+ const { calls, f } = recorder((c) => {+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-9' }, 201);+ if (c.method === 'PUT') return new Response(null, { status: 204 });+ return json({ job_id: 'j' }, 202);+ });+ await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep });+ for (const c of calls) assert.ok(c.url.startsWith('https://staging-agents.test/api/public/brains/b1/repo/uploads'), c.url);+ } finally {+ if (before === undefined) delete process.env.GRAFT_BRAIN_URL;+ else process.env.GRAFT_BRAIN_URL = before;+ }+});diff --git a/test/brain-watch-events.test.ts b/test/brain-watch-events.test.tsnew file mode 100644index 00000000..3ee65fe9--- /dev/null+++ b/test/brain-watch-events.test.ts@@ -0,0 +1,183 @@+/**+ * The live watch: when Trail streams the build, the terminal follows it as it+ * happens instead of polling every four seconds. What matters is that the+ * stream is parsed exactly (keep-alives, split chunks, CRLF), that the suggestion+ * counts ride along, and that a stream which drops costs nothing but the old+ * polling behaviour.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { parseRepoBody, SseParser, watchBuild } from '../src/brain/watch.js';++const LINK = { brainId: 'b1', token: 'gbt_1.sig', baseUrl: 'http://trail.test' };++// --- the parser ---------------------------------------------------------------++test('events are parsed across chunk boundaries, and keep-alives are dropped', () => {+ const p = new SseParser();+ assert.deepEqual(p.push(': ping\n\nevent: prog'), []);+ assert.deepEqual(p.push('ress\ndata: {"a":'), []);+ assert.deepEqual(p.push('1}\n\n'), [{ event: 'progress', data: '{"a":1}' }]);+ assert.deepEqual(p.push('event: done\r\ndata: {}\r\n\r\n'), [{ event: 'done', data: '{}' }]);+});++test('multi-line data is joined, and a missing event name means message', () => {+ const p = new SseParser();+ assert.deepEqual(p.push('data: one\ndata:two\n\n'), [{ event: 'message', data: 'one\ntwo' }]);+});++test('a lone CR at the end of a chunk waits for its LF', () => {+ const p = new SseParser();+ assert.deepEqual(p.push('data: x\r'), []);+ assert.deepEqual(p.push('\n\r\n'), [{ event: 'message', data: 'x' }]);+});++test('the suggestion counts are read whether Trail sends numbers or lists', () => {+ const counted = parseRepoBody({+ repo: { status: 'ingesting' },+ claude_md: { status: 'ready', quick_ready: true, changes: 3 },+ context_files: { files: 2, changes: 5 },+ });+ assert.deepEqual(counted?.suggestions, { claudeMd: 3, contextFiles: 5 });+ const listed = parseRepoBody({+ repo: { status: 'ingesting' },+ claude_md: { changes: [{}, {}] },+ context_files: { files: [{ kind: 'agents_md', path: 'AGENTS.md', changes: [{}, {}, {}] }] },+ });+ assert.deepEqual(listed?.suggestions, {+ claudeMd: 2,+ contextFiles: 3,+ files: [{ kind: 'agents_md', path: 'AGENTS.md', changes: 3 }],+ });+ assert.equal(parseRepoBody({ repo: { status: 'ingesting' } })?.suggestions, undefined, 'an older Trail sends none');+});++// --- the stream ---------------------------------------------------------------++/** A text/event-stream response that sends each part in turn, then ends (or not). */+function stream(parts: string[], opts: { end?: boolean } = {}): Response {+ const enc = new TextEncoder();+ let i = 0;+ const body = new ReadableStream<Uint8Array>({+ pull(ctl) {+ if (i < parts.length) ctl.enqueue(enc.encode(parts[i++]));+ else if (opts.end !== false) ctl.close();+ },+ });+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } });+}++const progress = (body: unknown) => `event: progress\ndata: ${JSON.stringify(body)}\n\n`;+const NOW = { timeoutMs: 60_000, pollMs: 0, sleep: async () => {} };++test('the stream settles the watch on the first rules, with the suggestions it carried', async () => {+ const urls: string[] = [];+ const accepts: string[] = [];+ let seen: unknown = null;+ const outcome = await watchBuild(LINK, {+ ...NOW,+ events: true,+ write: () => {},+ onState: (_v, repo) => (seen = repo.suggestions),+ fetchImpl: (async (u: string, init?: RequestInit) => {+ urls.push(u);+ accepts.push(String((init?.headers as Record<string, string>).accept));+ return stream([+ ': ping\n\n',+ progress({ repo: { status: 'ingesting', commit_count: 412 } }),+ progress({+ repo: { status: 'ingesting', commit_count: 412 },+ build: { found_so_far: 40, filed_so_far: 5 },+ claude_md: { changes: 4 },+ context_files: { changes: 2 },+ }),+ ], { end: false });+ }) as typeof fetch,+ });+ assert.equal(outcome, 'building');+ assert.deepEqual(urls, ['http://trail.test/api/public/brains/b1/events'], 'one connection, no polling');+ assert.equal(accepts[0], 'text/event-stream');+ assert.deepEqual(seen, { claudeMd: 4, contextFiles: 2 });+});++test('a done event reports a failed build the same way polling would', async () => {+ const lines: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ events: true,+ write: (l) => lines.push(l),+ fetchImpl: (async () =>+ stream([+ progress({ repo: { status: 'ingesting', commit_count: 10 } }),+ `event: done\ndata: ${JSON.stringify({ repo: { status: 'failed', commit_count: 10, error_message: 'miner fell over' } })}\n\n`,+ ])) as typeof fetch,+ });+ assert.equal(outcome, 'failed');+ assert.match(lines.join('\n'), /the build stopped while mining rules · nothing was lost/);+ assert.match(lines.join('\n'), /miner fell over/);+});++test('a stream that keeps dropping is reopened three times, then the watcher polls', async () => {+ const hits: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ events: true,+ write: () => {},+ fetchImpl: (async (u: string) => {+ hits.push(u.endsWith('/events') ? 'events' : 'poll');+ if (u.endsWith('/events')) return stream([progress({ repo: { status: 'ingesting' } })]);+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 42, commit_count: 9 } }), { status: 200 });+ }) as typeof fetch,+ });+ assert.equal(outcome, 'completed');+ assert.deepEqual(hits, ['events', 'events', 'events', 'events', 'poll']);+});++test('a Trail without the stream falls straight back to polling', async () => {+ const hits: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ events: true,+ write: () => {},+ fetchImpl: (async (u: string) => {+ hits.push(u.endsWith('/events') ? 'events' : 'poll');+ if (u.endsWith('/events')) return new Response('not found', { status: 404 });+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 1, commit_count: 1 } }), { status: 200 });+ }) as typeof fetch,+ });+ assert.equal(outcome, 'completed');+ assert.deepEqual(hits, ['events', 'poll']);+});++test('a silent stream counts as dropped once the keep-alives stop', async () => {+ let connections = 0;+ const outcome = await watchBuild(LINK, {+ ...NOW,+ events: true,+ idleMs: 20,+ maxReconnects: 0,+ write: () => {},+ fetchImpl: (async (u: string) => {+ if (u.endsWith('/events')) {+ connections++;+ return stream([], { end: false });+ }+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 3, commit_count: 1 } }), { status: 200 });+ }) as typeof fetch,+ });+ assert.equal(outcome, 'completed');+ assert.equal(connections, 1);+});++test('without the events flag nothing asks for the stream', async () => {+ const hits: string[] = [];+ await watchBuild(LINK, {+ ...NOW,+ write: () => {},+ fetchImpl: (async (u: string) => {+ hits.push(u);+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 1, commit_count: 1 } }), { status: 200 });+ }) as typeof fetch,+ });+ assert.ok(hits.every((u) => u.endsWith('/repo')));+});diff --git a/test/brain-watch.test.ts b/test/brain-watch.test.tsindex cbd64a85..b9a9c162 100644--- a/test/brain-watch.test.ts+++ b/test/brain-watch.test.ts@@ -5,7 +5,7 @@*/import { test } from 'node:test';import assert from 'node:assert/strict';-import { linesFor, stagesFrom, watchBuild, type RepoState } from '../src/brain/watch.js';+import { failureLines, linesFor, stagesFrom, watchBuild, type RepoState } from '../src/brain/watch.js';import { brainUrl } from '../src/brain/signup.js';const row = (over: Partial<RepoState> = {}): RepoState => ({@@ -62,15 +62,23 @@ test('done means the rules are in the brain, not just that the row closed', () =// This is a log, not a redrawn frame: a line per poll for a stage that is merely// still running would bury the four that matter under a hundred that do not.-test('only settled stages print, and each prints once', () => {+test('only finished stages print, each once, in the past tense', () => {const printed = new Set<string>();- const first = linesFor(stagesFrom(row({ commitCount: 412, threadCount: 89 })), printed);- assert.equal(first.length, 2, 'reach and read have settled; mine and file have not');- assert.match(first[1], /412 commits, 89 discussions/);- assert.deepEqual(linesFor(stagesFrom(row({ commitCount: 412, threadCount: 89 })), printed), [], 'nothing reprints');- const later = linesFor(stagesFrom(row({ status: 'completed', commitCount: 412, threadCount: 89, ruleCount: 42 })), printed);- assert.equal(later.length, 2, 'mine and file settle later and print then');- assert.match(later.join('\n'), /42 rules/);+ const reading = row({ commitCount: 412, threadCount: 89 });+ const first = linesFor(stagesFrom(reading), printed, reading);+ assert.deepEqual(first, [' ✓ reached the repository', ' ✓ read its history'], 'reach and read have settled; mine has not');+ assert.deepEqual(linesFor(stagesFrom(reading), printed, reading), [], 'nothing reprints');+ const done = row({ status: 'completed', commitCount: 412, threadCount: 89, ruleCount: 42 });+ const later = linesFor(stagesFrom(done), printed, done);+ assert.deepEqual(later, [' ✓ mined the first 42 rules'], 'filing is left to the closing line');+});++test('a failure says where it stopped, that nothing was lost, and the server\'s own words', () => {+ const view = stagesFrom(row({ status: 'failed', commitCount: 412, errorMessage: 'parse response: unexpected end of JSON input' }));+ assert.deepEqual(failureLines(view), [+ '✗ the build stopped while mining rules · nothing was lost — run graft trail push again',+ ' parse response: unexpected end of JSON input',+ ]);});// --- the watcher ------------------------------------------------------------@@ -109,8 +117,8 @@ test('the watcher holds until the brain is built', async () => {]),});assert.equal(outcome, 'completed');- assert.match(lines.join('\n'), /reaching the repository/);- assert.match(lines.join('\n'), /42 rules/);+ assert.match(lines.join('\n'), /reached the repository/);+ assert.match(lines.join('\n'), /mined the first 42 rules/);});test('the watcher reports a failure rather than waiting out the clock', async () => {@@ -201,7 +209,7 @@ test('the watcher hands the prompt back on the first rules, while the job runs o]),});assert.equal(outcome, 'building');- assert.match(lines.join('\n'), /mining the rules — 62 rules so far/);+ assert.match(lines.join('\n'), /mined the first 62 rules/);});// A graft pointed at a Trail that does not send the in-flight counts must falldiff --git a/test/claude-init.test.ts b/test/claude-init.test.tsindex 2a7fbf6d..3894bf04 100644--- a/test/claude-init.test.ts+++ b/test/claude-init.test.ts@@ -84,7 +84,7 @@ test('CLI: --no-statusline leaves statusLine unset', () => {const d = fresh();const res = spawnSync(process.execPath,- ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--no-statusline'],+ ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--no-statusline', '--verbose'],{ encoding: 'utf8' },);assert.equal(res.status, 0, res.stderr);@@ -160,7 +160,7 @@ test('formatInitEpilogue: graph not built shows "build the graph" as step 1, noassert.equal(col(built, 'restart your agent'), col(notBuilt, 'restart your agent'));});-test('CLI: graft init epilogue has the wordmark + next steps, and never mentions OPENROUTER', () => {+test('CLI: graft init prints one line per step, and no banner', () => {const d = fresh();const res = spawnSync(process.execPath,@@ -168,6 +168,22 @@ test('CLI: graft init epilogue has the wordmark + next steps, and never mentions{ encoding: 'utf8' },);assert.equal(res.status, 0, res.stderr);+ assert.match(res.stderr, /skipped the graph build — run graft build/);+ assert.match(res.stderr, /✓ claude +\.claude[\\/], \.mcp\.json/);+ assert.match(res.stderr, /restart your agents so a new session picks up graft/);+ assert.match(res.stderr, /commit \.claude\/ \.mcp\.json to share it — graft\/ stays local and git-ignored/);+ assert.ok(!res.stderr.includes('|___/'), 'the banner is --verbose only');+ assert.ok(!res.stderr.includes('✓ wrote'), 'file-by-file lines are --verbose only');+});++test('CLI: graft init --verbose epilogue has the wordmark + next steps, and never mentions OPENROUTER', () => {+ const d = fresh();+ const res = spawnSync(+ process.execPath,+ ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--verbose'],+ { encoding: 'utf8' },+ );+ assert.equal(res.status, 0, res.stderr);assert.ok(res.stderr.includes('|___/'), 'wordmark present');assert.ok(res.stderr.includes('code as usual'));assert.ok(res.stderr.includes('restart your agent'));diff --git a/test/cli-picker.test.ts b/test/cli-picker.test.tsindex d13f049c..a519f5fb 100644--- a/test/cli-picker.test.ts+++ b/test/cli-picker.test.ts@@ -7,7 +7,7 @@ import { planInit } from '../src/hosts/plan.js';import {KEY_CTRL_C, KEY_DOWN, KEY_ESC, KEY_UP,describeWrites, formatNonInteractiveHelp, formatPlan, initialPickerState,- keyOf, keysOf, pickedHostIds, pickedIds, pickedTelemetry, reducePicker, renderPicker, tilde,+ compactWrites, keyOf, keysOf, pickedHostIds, pickedIds, pickedTelemetry, reducePicker, renderPicker, tilde, visibleRows,TELEMETRY_ROW_ID,type PickerKey,} from '../src/cli-picker.js';@@ -100,16 +100,21 @@ test('down then space adds the second host', () => {assert.deepEqual(pickedIds(state), ['claude', 'agents']);});+/** Rows on screen before `m`: the agents graft found, and nothing else. */+function shownCount(repo: string, home: string): number {+ return visibleRows(initialPickerState(planInit(repo, { home }), repo, home)).length;+}+test('cursor wraps at both ends', () => {const repo = fresh(); const home = fullHome();- const n = planInit(repo, { home }).length;+ const n = shownCount(repo, home);assert.equal(drive(repo, home, ['up']).cursor, n - 1);assert.equal(drive(repo, home, Array(n).fill('down') as PickerKey[]).cursor, 0);});test('a toggles all on, then all off', () => {const repo = fresh(); const home = fullHome();- const n = planInit(repo, { home }).length;+ const n = shownCount(repo, home);assert.equal(pickedIds(drive(repo, home, ['all'])).length, n);assert.deepEqual(pickedIds(drive(repo, home, ['all', 'all'])), []);});@@ -169,15 +174,38 @@ test('describeWrites truncates long path lists', () => {assert.match(describeWrites(claude.writes, repo, home), /\+2 more/);});-test('renderPicker marks the cursor, the checkboxes and undetected hosts', () => {+test('renderPicker marks the cursor and folds undetected hosts into one line', () => {const repo = fresh(); const home = fresh(); // nothing installedconst state = initialPickerState(planInit(repo, { home }), repo, home);const text = renderPicker(state, false);+ assert.match(text, /^graft init — pick the agents your team uses:/);assert.match(text, /› \[x\] claude/);- assert.match(text, /\[ \] cursor.*\(not detected\)/);- assert.match(text, /space toggle/);- // Every host gets a row, plus header, blank lines and the key legend.- assert.equal(text.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, state.rows.length);+ assert.doesNotMatch(text, /\[ \] cursor/, 'an agent graft cannot find is folded away');+ assert.match(text, /\+ \d+ not detected \(.*cursor.*\) · m to show/);+ assert.match(text, /space toggle · a all · m more · enter confirm/);+ // Only the detected rows get a checkbox until `m`.+ assert.equal(text.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, visibleRows(state).length);++ const opened = reducePicker(state, 'more');+ const all = renderPicker(opened, false);+ assert.match(all, /\[ \] cursor \(not detected\)/);+ assert.equal(all.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, state.rows.length);+});++test('a never selects an agent that is folded away', () => {+ const repo = fresh(); const home = fresh();+ const state = reducePicker(initialPickerState(planInit(repo, { home }), repo, home), 'all');+ for (const id of pickedIds(state)) {+ assert.ok(state.rows.find((r) => r.id === id)?.detected, `${id} was folded and must not be picked`);+ }+});++test('compactWrites shows a folder written into several times once, and two entries at most', () => {+ const repo = fresh(); const home = fullHome();+ const [claude] = planInit(repo, { home, ids: ['claude'] });+ assert.equal(compactWrites(claude.writes, repo, home), `.claude${sep}, .mcp.json · + 3 in ~${sep}`);+ const cursor = planInit(repo, { home, ids: ['cursor'] })[0];+ assert.match(compactWrites(cursor.writes, repo, home), /^[^,]+, [^,]+ \+\d+ more$/);});test('formatPlan separates repo writes from machine-wide ones', () => {@@ -273,7 +301,7 @@ test('the consent row is never returned as an agent to wire', () => {test('a (toggle all) is about agents and leaves the consent answer alone', () => {const repo = fresh(); const home = fullHome();- const n = planInit(repo, { home }).length;+ const n = shownCount(repo, home);// On: every agent selected, consent still the default yes.const on = driveWithConsent(repo, home, ['all']);assert.equal(pickedHostIds(on).length, n);@@ -293,7 +321,6 @@ test('the rendered row shows the label, a rule, and what is not collected', () =const out = renderPicker(initialPickerState(planInit(repo, { home }), repo, home, { offerTelemetry: true }), false);assert.match(out, /\[x\] anonymous usage stats/);assert.match(out, /no code, no file paths, no queries/);- assert.match(out, /TELEMETRY\.md/);assert.equal(out.includes(TELEMETRY_ROW_ID), false, 'the internal id must never be shown');assert.match(out, /─/, 'a rule separates the settings from the agents');});diff --git a/test/hosts-init.test.ts b/test/hosts-init.test.tsindex cbbd3c37..f7b7d188 100644--- a/test/hosts-init.test.ts+++ b/test/hosts-init.test.ts@@ -218,7 +218,7 @@ test('CLI: --yes wires every detected agent (the pre-0.8 default)', () => {test('CLI: --no-global writes AGENTS.md but leaves ~/.codex alone', () => {const home = fresh(); const repo = fresh();mkdirSync(join(home, '.codex'), { recursive: true });- const out = cliStderr(repo, home, ['--agents', 'agents', '--no-global']);+ const out = cliStderr(repo, home, ['--agents', 'agents', '--no-global', '--verbose']);assert.ok(existsSync(join(repo, 'AGENTS.md')));assert.deepEqual(readdirSync(join(home, '.codex')), []);assert.match(out, /skipped out-of-repo writes/);@@ -230,7 +230,7 @@ test('CLI: the graph build is attempted even when claude is not selected', () =>// Regression: the build used to sit inside `if (wantClaude)`, so picking only// cursor wired .cursor/ and never built the graph its rule file points at.const out = cliStderr(repo, home, ['--agents', 'cursor']);- assert.match(out, /(built the graph|skipped graph build)/);+ assert.match(out, /(built the graph|graph built|skipped graph build|skipped the graph build)/);});test('CLI: --no-global stays quiet when the selection has nothing out-of-repo', () => {