@nanonets/graft 0.10.0 → 0.12.0

package/dist/telemetry/track.js

@@ -0,0 +1,108 @@
+/**
+ * `track()` — the only way an event is ever created, and the place the contract
+ * is enforced.
+ *
+ * Call sites pass a name and some properties; this drops anything the contract
+ * (contract.ts) does not list, stamps the common properties, and appends to the
+ * local queue. It never sends, never blocks, and never throws — a telemetry bug
+ * must be incapable of failing a build or a query.
+ *
+ * Two rules do the actual privacy work, and both are enforced here rather than
+ * asked of callers:
+ *
+ *   • unknown event → dropped whole; unknown property key → dropped, the rest of
+ *     the event survives. A careless `track('query', { path })` sends `query`
+ *     without a path.
+ *   • non-string values → dropped. Everything that crosses the wire is a bucket
+ *     label or an enum member, so a raw count or a raw message cannot get out
+ *     even under a key that happens to be allowed.
+ */
+import { EVENTS } from './contract.js';
+import { enqueue } from './queue.js';
+import { telemetryOn } from './gate.js';
+import { installId, repoId } from './identity.js';
+import { runningVersion } from '../upkeep.js';
+/**
+ * Which agent graft is running under, from the surface plus one env probe.
+ *
+ * Only the PRESENCE of `CLAUDECODE` is read, never its value — the distinction
+ * matters: a value could be anything a user's shell profile put there, presence
+ * is a boolean. Anything unrecognised is `cli`, which is the honest answer.
+ */
+export function detectHost(explicit, env = process.env) {
+    if (explicit)
+        return explicit;
+    if (env.CLAUDECODE !== undefined)
+        return 'claude-code';
+    return 'cli';
+}
+/** The properties every event carries. Kept in one place so no call site can
+ *  disagree about them. */
+function commonProps(ctx) {
+    const props = {
+        app_version: runningVersion(),
+        os: process.platform,
+        arch: process.arch,
+        node_major: String(process.versions.node.split('.')[0]),
+        ci: 'false', // an event only exists at all when the CI gate passed
+        agent_host: detectHost(ctx.host, ctx.env ?? process.env),
+    };
+    if (ctx.repo) {
+        try {
+            props.repo_id = repoId(ctx.repo);
+        }
+        catch { /* unwritable cache — omit */ }
+    }
+    return props;
+}
+/**
+ * Record one event, if the contract allows it and the gates are open.
+ *
+ * Returns the event that was queued, or null — the return value exists for
+ * tests and for `graft telemetry debug`, not for control flow at call sites.
+ */
+export function track(event, props = {}, ctx = {}) {
+    try {
+        if (!telemetryOn(ctx.home, ctx.env))
+            return null;
+        // `Object.hasOwn`, not `EVENTS[event]`: a bare object literal inherits from
+        // Object.prototype, so `EVENTS['constructor']` is truthy and would sail past
+        // a plain existence check — only failing later, on a TypeError swallowed by
+        // the catch below. The allowlist must reject by design, not by exception.
+        if (!Object.hasOwn(EVENTS, event))
+            return null;
+        const allowed = EVENTS[event];
+        const properties = commonProps(ctx);
+        for (const [k, v] of Object.entries(props)) {
+            if (allowed.has(k) && typeof v === 'string')
+                properties[k] = v;
+        }
+        const queued = {
+            event,
+            properties,
+            timestamp: new Date().toISOString(),
+            distinct_id: installId(ctx.home).id,
+        };
+        enqueue(queued, ctx.home);
+        return queued;
+    }
+    catch {
+        return null; // telemetry never surfaces as a user-visible failure
+    }
+}
+/**
+ * The `first_run` event, fired the once. Separate from `track` because it is the
+ * only event whose trigger is "the id did not exist a moment ago", which only
+ * `installId()` can know.
+ */
+export function trackFirstRunIfNew(ctx = {}) {
+    try {
+        if (!telemetryOn(ctx.home, ctx.env))
+            return;
+        if (!installId(ctx.home).firstRun)
+            return;
+        track('first_run', {}, ctx);
+    }
+    catch { /* never */ }
+}
+//# sourceMappingURL=track.js.map

package/dist/telemetry/track.js.map

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

package/dist/upkeep-run.d.ts

@@ -0,0 +1,15 @@
+export interface UpkeepResult {
+    /** Lines worth showing the agent/user, already formatted. Usually empty. */
+    lines: string[];
+}
+/**
+ * @param repo    the project dir
+ * @param current the running graft's version
+ * @param opts.background  false in hook contexts: read the update cache, never
+ *   spawn a fetch. Hooks run under a hard timeout and must stay off the network.
+ */
+export declare function runUpkeep(repo: string, current: string, opts?: {
+    background?: boolean;
+    home?: string;
+}): UpkeepResult;
+//# sourceMappingURL=upkeep-run.d.ts.map

package/dist/upkeep-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upkeep-run.d.ts","sourceRoot":"","sources":["../src/upkeep-run.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAyBD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,YAAY,CAad"}

package/dist/upkeep-run.js

@@ -0,0 +1,60 @@
+/**
+ * The wired-up version of `./upkeep.ts` — one call every entry point makes.
+ *
+ * Split from `upkeep.ts` so that module stays pure and unit-testable (no init
+ * writes, no spawning): this file is the only place that knows how to actually
+ * re-run the wiring, and it is deliberately thin.
+ */
+import { runInit } from './claude/init.js';
+import { runHostsInit } from './hosts/init.js';
+import { graftCliPath } from './claude/paths.js';
+import { formatUpdateNudge, formatWiringRefresh, maybeRefreshInBackground, readUpdateCache, reconcileWiring, } from './upkeep.js';
+/**
+ * Re-write the wiring for exactly the hosts a previous `init` chose here, with
+ * exactly the flags it was given.
+ *
+ * `build: false` matters: this runs at session start and at MCP boot, and a graph
+ * build there would stall the agent's first turn.
+ *
+ * The out-of-repo writes (`~/.codex/hooks.json`, `~/.codex/config.toml`) ARE
+ * included, because nothing else would ever refresh them: no skill, rule file, or
+ * MCP instruction tells an agent to run `graft init`, so leaving them out means a
+ * Codex user upgrades the binary and keeps the old hook config forever. They're
+ * safe to replay — `installCodexHooks` no-ops when `~/.codex` is absent, rewrites
+ * only its own entry (matched on `graft-hooks.cjs`), and reports `unchanged` when
+ * the bytes match. A user who declined them at init time is honoured via
+ * `opts.global`/`opts.hooks`, replayed from the stamp.
+ */
+function rewriteWiring(repo, hosts, opts) {
+    if (hosts.includes('claude'))
+        runInit(repo, { build: false, cliPath: graftCliPath() });
+    const others = hosts.filter((h) => h !== 'claude');
+    if (others.length)
+        runHostsInit(repo, { agents: others, global: opts.global, mcp: opts.mcp, hooks: opts.hooks });
+}
+/**
+ * @param repo    the project dir
+ * @param current the running graft's version
+ * @param opts.background  false in hook contexts: read the update cache, never
+ *   spawn a fetch. Hooks run under a hard timeout and must stay off the network.
+ */
+export function runUpkeep(repo, current, opts = {}) {
+    const lines = [];
+    try {
+        const refreshed = reconcileWiring(repo, current, { rewrite: rewriteWiring });
+        const refreshLine = formatWiringRefresh(refreshed);
+        if (refreshLine)
+            lines.push(refreshLine);
+    }
+    catch { /* fail-soft: wiring refresh is never worth breaking a session for */ }
+    try {
+        if (opts.background !== false)
+            maybeRefreshInBackground(opts.home);
+        const nudge = formatUpdateNudge(current, readUpdateCache(opts.home)?.latest);
+        if (nudge)
+            lines.push(nudge);
+    }
+    catch { /* same */ }
+    return { lines };
+}
+//# sourceMappingURL=upkeep-run.js.map

package/dist/upkeep-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upkeep-run.js","sourceRoot":"","sources":["../src/upkeep-run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,eAAe,GAEhB,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;;;;;;;GAeG;AACH,SAAS,aAAa,CAAC,IAAY,EAAE,KAAe,EAAE,IAAgB;IACpE,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;IACvF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,MAAM;QACf,YAAY,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AAClG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,OAAe,EACf,OAAgD,EAAE;IAElD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;QAC7E,MAAM,WAAW,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,WAAW;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC,CAAC,qEAAqE,CAAC,CAAC;IACjF,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,UAAU,KAAK,KAAK;YAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC7E,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/upkeep.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The version of the graft package this code was loaded from.
+ *
+ * Resolved from *this* module rather than the caller's: `readCurrentVersion`
+ * looks one level up from the module URL it's given, which lands on the package
+ * root for `dist/upkeep.js` but misses entirely for `dist/claude/hooks.js` and
+ * `dist/mcp/server.js`. Every caller asking here instead of passing its own
+ * `import.meta.url` is what keeps the hook and the MCP server from reading
+ * `0.0.0` and re-initing on every single session.
+ */
+export declare function runningVersion(): string;
+/** How long a registry answer is considered current. A day: graft ships far less
+ * often than that, and this is a nudge, not a security update. */
+export declare const UPDATE_TTL_MS: number;
+/** Numeric-dotted compare of the release part only (`1.2.3-beta.1` → `1.2.3`).
+ * Prerelease ordering doesn't matter here: the only question either caller asks
+ * is "is the thing on npm ahead of what's on disk", and a prerelease that
+ * compares equal simply produces no nudge. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isNewer(candidate: string | null | undefined, current: string): boolean;
+export interface UpdateCache {
+    /** Latest version seen on npm, or null when the last fetch failed. */
+    latest: string | null;
+    /** Epoch ms of the last *attempt* — written by the parent before it spawns the
+     * fetch, so a repeatedly-failing fetch can't make every command spawn a child. */
+    checkedAt: number;
+}
+/** Machine-global, not per-repo: "what's the latest graft" is one fact, and a
+ * dev with twelve repos should cost the registry one request a day, not twelve. */
+export declare function updateCachePath(home?: string): string;
+export declare function readUpdateCache(home?: string): UpdateCache | null;
+/**
+ * The `graft _update-check` command body: hit the registry, store the answer.
+ * Runs in a detached child so nothing user-facing ever waits on the network.
+ */
+export declare function refreshUpdateCache(home?: string, now?: number): UpdateCache;
+/** True when the cached answer is missing or older than the TTL. */
+export declare function needsRefresh(cache: UpdateCache | null, now?: number): boolean;
+/**
+ * Kick off a background registry check if the cache has gone stale. Touches
+ * `checkedAt` first so concurrent callers (and a child that dies) don't spawn a
+ * fetch per invocation. Never waits, never throws.
+ *
+ * Only called from long-lived or already-slow contexts (a CLI command, MCP
+ * boot) — never from a hook, which reads the cache and nothing else.
+ */
+export declare function maybeRefreshInBackground(home?: string, now?: number): boolean;
+/** One line, or nothing. Nothing is the common case — don't spend context on
+ * "you're up to date". */
+export declare function formatUpdateNudge(current: string, latest: string | null | undefined): string | null;
+/**
+ * The subset of `graft init`'s flags a refresh has to replay.
+ *
+ * Without these, an auto-refresh would install things the user explicitly
+ * declined: someone who ran `graft init --no-global` (or `--no-hooks`) said "keep
+ * out of `~/.codex`", and a later session silently writing there would be graft
+ * overriding a decision rather than maintaining one. Absent from an older stamp →
+ * all true, which is what plain `graft init` does.
+ */
+export interface WiringOpts {
+    /** false → never write outside the repo (`--no-global`). */
+    global: boolean;
+    /** false → skip MCP server registration (`--no-mcp`). */
+    mcp: boolean;
+    /** false → skip hook installation (`--no-hooks`). */
+    hooks: boolean;
+}
+export declare const DEFAULT_WIRING_OPTS: WiringOpts;
+/** An older stamp has no `opts`; a plain `graft init` wired everything. */
+export declare function wiringOpts(stamp: WiringStamp | null): WiringOpts;
+export interface WiringStamp {
+    /** The graft version whose `init` wrote this repo's agent files. */
+    version: string;
+    /** Host ids that were wired, so a refresh re-writes exactly those and never
+     * silently adopts an agent the user declined in the picker. */
+    hosts: string[];
+    /** The init flags to replay — see {@link WiringOpts}. */
+    opts?: Partial<WiringOpts>;
+    at: string;
+}
+/** Under `graft/.cache/`, beside the other derived state: git-ignored, per-clone,
+ * and cheap to lose — a missing stamp just means one idempotent refresh. */
+export declare function stampPath(repo: string): string;
+export declare function readStamp(repo: string): WiringStamp | null;
+export declare function writeStamp(repo: string, version: string, hosts: string[], opts?: Partial<WiringOpts>, at?: string): void;
+/**
+ * Which agents this repo is *already* wired for, read off disk rather than
+ * re-detected. Detection answers "which editors does this machine have"; for a
+ * refresh we need "which files did a previous init actually write" — otherwise
+ * installing Windsurf once would silently add graft rules to every repo.
+ */
+export declare function wiredHostIds(repo: string): string[];
+export interface WiringRefresh {
+    from: string;
+    to: string;
+    hosts: string[];
+    /** True when the refresh included writes outside the repo (`~/.codex/`), so the
+     * caller can say so — a session changing machine-wide config should be visible. */
+    global: boolean;
+}
+/**
+ * Re-run init's writes when the stamp and the running binary disagree.
+ *
+ * Deliberately narrow: it refreshes the hosts already wired, replays the flags
+ * that init was given, never builds the graph (this runs at session start — a
+ * rebuild there would stall the agent's first turn), and no-ops when the repo has
+ * no graft wiring at all.
+ */
+export declare function reconcileWiring(repo: string, current: string, deps: {
+    wired?: (repo: string) => string[];
+    rewrite: (repo: string, hosts: string[], opts: WiringOpts) => void;
+}): WiringRefresh | null;
+export declare function formatWiringRefresh(r: WiringRefresh | null): string | null;
+//# sourceMappingURL=upkeep.d.ts.map

package/dist/upkeep.d.ts.map

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

package/dist/upkeep.js

@@ -0,0 +1,232 @@
+/**
+ * Self-maintenance: keeping an installed graft, and the wiring it wrote, current.
+ *
+ * Two independent kinds of staleness, both invisible to the user today:
+ *
+ *   1. **Binary staleness** — they installed once and never upgraded. `graft
+ *      version` would tell them, but nobody runs it. So we keep a cached,
+ *      machine-global registry answer and let every entry point surface a
+ *      one-line nudge from it.
+ *
+ *   2. **Wiring staleness** — `graft init` copies hooks, shims, skill text and
+ *      rule files INTO the repo. `npm i -g` replaces the binary but touches none
+ *      of them, so a repo wired by 0.7 keeps 0.7's prompts and 0.7's hook
+ *      timeouts forever (see the comment on `promptAskTimeout`, which exists
+ *      only to work around exactly this). A version stamp written next to the
+ *      graph lets any entry point notice the skew and re-run the writes.
+ *
+ * Everything here is fail-soft by construction: it runs inside hooks and inside
+ * the MCP server's boot path, where a throw is a broken session, and it must
+ * never block on the network — the registry is only ever read from cache, and
+ * the refresh happens in a detached child.
+ *
+ * Called from all three hosts' entry points so no editor is left out:
+ *   • Claude Code   — `session-start` hook (src/claude/hooks.ts)
+ *   • Cursor/Codex  — MCP server boot (src/mcp/server.ts), and any CLI command
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readJson, writeJsonAtomic, cacheDir } from './util/state.js';
+import { HOSTS } from './hosts/registry.js';
+import { START } from './hosts/sections.js';
+import { getNpmViewVersion, readCurrentVersion } from './cli-meta.js';
+import { graftCliPath } from './claude/paths.js';
+/**
+ * The version of the graft package this code was loaded from.
+ *
+ * Resolved from *this* module rather than the caller's: `readCurrentVersion`
+ * looks one level up from the module URL it's given, which lands on the package
+ * root for `dist/upkeep.js` but misses entirely for `dist/claude/hooks.js` and
+ * `dist/mcp/server.js`. Every caller asking here instead of passing its own
+ * `import.meta.url` is what keeps the hook and the MCP server from reading
+ * `0.0.0` and re-initing on every single session.
+ */
+export function runningVersion() {
+    try {
+        return readCurrentVersion(import.meta.url);
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** How long a registry answer is considered current. A day: graft ships far less
+ * often than that, and this is a nudge, not a security update. */
+export const UPDATE_TTL_MS = 24 * 60 * 60 * 1000;
+/* -------------------------------------------------------------------------- */
+/* version comparison                                                         */
+/* -------------------------------------------------------------------------- */
+/** Numeric-dotted compare of the release part only (`1.2.3-beta.1` → `1.2.3`).
+ * Prerelease ordering doesn't matter here: the only question either caller asks
+ * is "is the thing on npm ahead of what's on disk", and a prerelease that
+ * compares equal simply produces no nudge. */
+export function compareVersions(a, b) {
+    const parts = (v) => String(v).split('-')[0].split('.').map((n) => Number(n) || 0);
+    const pa = parts(a);
+    const pb = parts(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+export function isNewer(candidate, current) {
+    if (!candidate)
+        return false;
+    return compareVersions(candidate, current) > 0;
+}
+/** Machine-global, not per-repo: "what's the latest graft" is one fact, and a
+ * dev with twelve repos should cost the registry one request a day, not twelve. */
+export function updateCachePath(home = homedir()) {
+    return join(home, '.graft', 'update-check.json');
+}
+export function readUpdateCache(home) {
+    return readJson(updateCachePath(home));
+}
+function writeUpdateCache(cache, home) {
+    try {
+        writeJsonAtomic(updateCachePath(home), cache);
+    }
+    catch { /* unwritable home — skip */ }
+}
+/**
+ * The `graft _update-check` command body: hit the registry, store the answer.
+ * Runs in a detached child so nothing user-facing ever waits on the network.
+ */
+export function refreshUpdateCache(home, now = Date.now()) {
+    const res = getNpmViewVersion();
+    const cache = { latest: res.ok ? (res.version ?? null) : null, checkedAt: now };
+    writeUpdateCache(cache, home);
+    return cache;
+}
+/** True when the cached answer is missing or older than the TTL. */
+export function needsRefresh(cache, now = Date.now()) {
+    return !cache || typeof cache.checkedAt !== 'number' || now - cache.checkedAt >= UPDATE_TTL_MS;
+}
+/**
+ * Kick off a background registry check if the cache has gone stale. Touches
+ * `checkedAt` first so concurrent callers (and a child that dies) don't spawn a
+ * fetch per invocation. Never waits, never throws.
+ *
+ * Only called from long-lived or already-slow contexts (a CLI command, MCP
+ * boot) — never from a hook, which reads the cache and nothing else.
+ */
+export function maybeRefreshInBackground(home, now = Date.now()) {
+    const cache = readUpdateCache(home);
+    if (!needsRefresh(cache, now))
+        return false;
+    writeUpdateCache({ latest: cache?.latest ?? null, checkedAt: now }, home);
+    try {
+        const child = spawn(process.execPath, [graftCliPath(), '_update-check'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false; // no spawn (sandbox, ENOMEM) — the nudge just uses the old cache
+    }
+}
+/** One line, or nothing. Nothing is the common case — don't spend context on
+ * "you're up to date". */
+export function formatUpdateNudge(current, latest) {
+    if (!isNewer(latest, current))
+        return null;
+    return `⬆ graft ${current} → ${latest} available: run \`npm i -g @nanonets/graft@latest\` (restart your agent after).`;
+}
+export const DEFAULT_WIRING_OPTS = { global: true, mcp: true, hooks: true };
+/** An older stamp has no `opts`; a plain `graft init` wired everything. */
+export function wiringOpts(stamp) {
+    return { ...DEFAULT_WIRING_OPTS, ...(stamp?.opts ?? {}) };
+}
+/** Under `graft/.cache/`, beside the other derived state: git-ignored, per-clone,
+ * and cheap to lose — a missing stamp just means one idempotent refresh. */
+export function stampPath(repo) {
+    return join(cacheDir(repo), 'wiring-stamp.json');
+}
+export function readStamp(repo) {
+    return readJson(stampPath(repo));
+}
+export function writeStamp(repo, version, hosts, opts = {}, at = new Date().toISOString()) {
+    try {
+        writeJsonAtomic(stampPath(repo), {
+            version,
+            hosts: [...hosts].sort(),
+            opts: { ...DEFAULT_WIRING_OPTS, ...opts },
+            at,
+        });
+    }
+    catch { /* unwritable graft/ — a refresh will just be retried next session */ }
+}
+/**
+ * Which agents this repo is *already* wired for, read off disk rather than
+ * re-detected. Detection answers "which editors does this machine have"; for a
+ * refresh we need "which files did a previous init actually write" — otherwise
+ * installing Windsurf once would silently add graft rules to every repo.
+ */
+export function wiredHostIds(repo) {
+    const ids = [];
+    if (existsSync(join(repo, '.claude', 'helpers', 'graft-hooks.cjs')))
+        ids.push('claude');
+    for (const host of HOSTS) {
+        const path = join(repo, host.relPath);
+        if (!existsSync(path))
+            continue;
+        // A shared file (AGENTS.md, GEMINI.md) counts only if graft's fenced section
+        // is in it — the user may own the file for entirely unrelated reasons.
+        if (host.kind === 'section') {
+            try {
+                if (!readFileSync(path, 'utf8').includes(START))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        ids.push(host.id);
+    }
+    return ids;
+}
+/**
+ * Re-run init's writes when the stamp and the running binary disagree.
+ *
+ * Deliberately narrow: it refreshes the hosts already wired, replays the flags
+ * that init was given, never builds the graph (this runs at session start — a
+ * rebuild there would stall the agent's first turn), and no-ops when the repo has
+ * no graft wiring at all.
+ */
+export function reconcileWiring(repo, current, deps) {
+    try {
+        const stamp = readStamp(repo);
+        if (stamp && stamp.version === current)
+            return null;
+        // The stamp is the record of *intent* (what the picker chose); disk is the
+        // fallback for repos wired before stamps existed. Union, not just disk:
+        // otherwise a host whose rule file went missing — deleted by hand, lost to a
+        // merge, or clobbered by another tool — is silently dropped from every future
+        // refresh, and that file is precisely what a refresh exists to restore.
+        const onDisk = (deps.wired ?? wiredHostIds)(repo);
+        const hosts = [...new Set([...(stamp?.hosts ?? []), ...onDisk])].sort();
+        if (hosts.length === 0)
+            return null; // never wired here — not our business
+        const opts = wiringOpts(stamp);
+        deps.rewrite(repo, hosts, opts);
+        writeStamp(repo, current, hosts, opts);
+        return { from: stamp?.version ?? 'unwired', to: current, hosts, global: opts.global };
+    }
+    catch {
+        return null; // a refresh is an optimization; never fail the caller over it
+    }
+}
+export function formatWiringRefresh(r) {
+    if (!r)
+        return null;
+    // Name the out-of-repo writes explicitly: those are machine-wide and shared by
+    // every repo, so a user seeing this line should not have to guess what moved.
+    const scope = r.global && r.hosts.includes('agents') ? " (including this machine's ~/.codex config)" : '';
+    return `· graft refreshed this repo's agent wiring${scope} (written by ${r.from}, now ${r.to}): ${r.hosts.join(', ')}.`;
+}
+//# sourceMappingURL=upkeep.js.map

package/dist/upkeep.js.map

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

package/dist/util/num.d.ts

@@ -0,0 +1,3 @@
+/** Thousands-separated integer, identical on every machine. */
+export declare function formatCount(n: number): string;
+//# sourceMappingURL=num.d.ts.map

package/dist/util/num.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"num.d.ts","sourceRoot":"","sources":["../../src/util/num.ts"],"names":[],"mappings":"AAgBA,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/util/num.js

@@ -0,0 +1,20 @@
+/**
+ * Number formatting for text graft emits.
+ *
+ * `toLocaleString()` with no locale follows the MACHINE's locale, which is the
+ * wrong authority for two of graft's outputs. The savings lines are read by an
+ * LLM and explicitly ask it to sum them across calls; on a pt-BR/de-DE box the
+ * bare call renders 1990 as "1.990", which an agent reads as 1.99 — so the
+ * headline "tokens saved this turn" total comes out ~1000× low. The graph's own
+ * stats are compared across machines and CI, where a separator that moves with
+ * the host makes two identical runs look different.
+ *
+ * One pinned locale for both: the output is a data interchange format that
+ * happens to be human-readable, not localized UI.
+ */
+const FORMATTER = new Intl.NumberFormat("en-US");
+/** Thousands-separated integer, identical on every machine. */
+export function formatCount(n) {
+    return FORMATTER.format(Math.round(n));
+}
+//# sourceMappingURL=num.js.map

package/dist/util/num.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"num.js","sourceRoot":"","sources":["../../src/util/num.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC"}

package/dist/util/state.d.ts

@@ -32,16 +32,18 @@ export declare function writeJsonAtomic(p: string, value: unknown, compact?: boo
 export declare function readStats(d: string): Stats | null;
 export declare function writeStats(d: string, s: Stats): void;
 /**
- * Persisted per-repo build configuration — currently just `graft build
- * --include-dir`'s override. An explicit input like the graph itself: absent
- * or empty `includeDirs` means today's default (every `SKIP_DIRS` name stays
- * skipped), so a repo that never used the flag is entirely unaffected.
+ * Persisted per-repo build configuration. Explicit CLI choices live here so
+ * later no-flag builds and automatic refreshes enumerate the same file set.
+ * Missing fields always retain backwards-compatible defaults.
  */
 export interface BuildConfig {
     /** SKIP_DIRS names to include in this repo's walks, persisted so a LATER
      * no-flag build — and the fingerprint/refresh path, which never sees CLI
      * flags at all — behave identically to the invocation that set it. */
     includeDirs?: string[];
+    /** Whether initialized Git submodules are folded into this repo's graph.
+     * Absent/false keeps the historical boundary at the superproject. */
+    followSubmodules?: boolean;
 }
 /** Local, Git-ignored repository configuration. Kept outside generated
  * `graft/` output so deleting/replacing that cache, workspace federation, and
@@ -50,12 +52,17 @@ export declare const BUILD_CONFIG_DIR = ".graft";
 export declare function buildConfigPath(d: string): string;
 export declare function readBuildConfig(d: string): BuildConfig | null;
 export declare function writeBuildConfig(d: string, c: BuildConfig): void;
+/** Merge explicit CLI choices into the existing local config, so updating one
+ * persisted build option cannot erase another. */
+export declare function patchBuildConfig(d: string, patch: BuildConfig): void;
 /** The persisted `--include-dir` override for repo `d`, as a Set — `undefined`
  * when nothing was ever persisted (or the persisted list is empty), which every
  * `shouldSkipDir`/`walkDir` caller treats as "today's default behavior". Shared
  * by every walkDir-driven entry point (source-files.ts, scopes.ts) so a build,
  * a later no-flag rebuild, and the hooks/refresh path all agree. */
 export declare function readIncludeDirs(d: string): Set<string> | undefined;
+/** Missing and explicit false both retain the backwards-compatible default. */
+export declare function readFollowSubmodules(d: string): boolean;
 export declare function patchStats(d: string, patch: Partial<Stats>): Stats;
 export declare function acquireLock(d: string): boolean;
 export declare function releaseLock(d: string): void;