dsh-graft-plugin 0.1.0

package/scripts/test-harness.mjs

@@ -0,0 +1,240 @@
+/**
+ * Terminal harness for graft-status.
+ *
+ * Everything runs against fixtures, including a synthetic graft repo built in
+ * a temp directory, so the suite passes on a fresh clone with no graft index
+ * and no graft installed anywhere on the machine.
+ *
+ * That synthetic repo is laid out exactly as index.js probes for and reads,
+ * so it exercises the real contract rather than a mock of it. `npm run
+ * test:live` is where the same code is checked against a genuine index.
+ *
+ * Run:  npm test
+ */
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { computeStatus, countWiring, findGraftRoot, freshnessOf } from '../src/index.js'
+
+let failures = 0
+const check = (label, ok, extra = '') => {
+  console.log((ok ? 'PASS  ' : 'FAIL  ') + label + (extra ? '  -> ' + extra : ''))
+  if (!ok) failures += 1
+}
+
+const exists = async (path) => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+const readJson = async (path) => {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+const io = { exists, readJson, readSavedTokens: async () => 0 }
+
+/**
+ * Same directory, however it happens to be spelled.
+ *
+ * `path.join` emits backslashes on Windows while the literals here use forward
+ * slashes, so a raw `===` would fail on a walk that is actually correct. The
+ * product never compares these strings — it only shows the basename — so
+ * normalising in the assertion tests the claim that matters (which directory)
+ * rather than an incidental one (which separator).
+ */
+const samePath = (a, b) =>
+  typeof a === 'string' && a.replace(/\\/g, '/').toLowerCase() === b.replace(/\\/g, '/').toLowerCase()
+
+console.log('--- freshness ---')
+check('dirty reads as stale', freshnessOf({ dirty: true }) === 'stale')
+check('syncing outranks dirty', freshnessOf({ dirty: true, syncing: true }) === 'syncing')
+check('staleCount alone is stale', freshnessOf({ dirty: false, staleCount: 3 }) === 'stale')
+check('clean reads as synced', freshnessOf({ dirty: false, staleCount: 0 }) === 'synced')
+check('no stats is unknown', freshnessOf(null) === 'unknown')
+
+console.log('\n--- wiring counts ---')
+check('counts nodes and edges', JSON.stringify(countWiring({ nodes: [1, 2, 3], edges: [1] })) === '{"nodeCount":3,"edgeCount":1}')
+check('missing edges is zero, not a crash', countWiring({ nodes: [] })?.edgeCount === 0)
+check('a non-graph yields undefined', countWiring({ what: 1 }) === undefined)
+check('null yields undefined', countWiring(null) === undefined)
+
+/* ------------------------------------------------------------------------ *
+ * A synthetic graft repo, so this suite runs anywhere.
+ *
+ * The layout is the one index.js actually probes for, not an invention:
+ *
+ *   <repo>/graft/INDEX.md              one of the three root markers
+ *   <repo>/graft/.cache/stats.json     the live cache, the preferred source
+ *   <repo>/graft/.graph/wiring.json    the graph, the fallback source
+ *
+ * One fixture repo deliberately carries a SPACE in its name. Every path here
+ * reaches a shell-free spawn eventually, and a space is what breaks that.
+ * ------------------------------------------------------------------------ */
+const fixture = await mkdtemp(join(tmpdir(), 'dsh-graft-test-'))
+const REPO = join(fixture, 'repo')
+const OTHER = join(fixture, 'other repo')
+const BARE = join(fixture, 'bare')
+
+await mkdir(join(REPO, 'graft', '.cache'), { recursive: true })
+await mkdir(join(REPO, 'graft', '.graph'), { recursive: true })
+await mkdir(join(REPO, 'profiles', 'web'), { recursive: true })
+await mkdir(join(OTHER, 'graft'), { recursive: true })
+await mkdir(BARE, { recursive: true })
+await writeFile(join(REPO, 'graft', 'INDEX.md'), '# graft repo map\n')
+await writeFile(
+  join(REPO, 'graft', '.cache', 'stats.json'),
+  JSON.stringify({ nodeCount: 1284, edgeCount: 5312, dirty: false, staleCount: 0, syncedAt: '2026-09-11T09:00:00.000Z' }),
+)
+await writeFile(
+  join(REPO, 'graft', '.graph', 'wiring.json'),
+  JSON.stringify({ nodes: Array.from({ length: 97 }, (_, i) => i), edges: Array.from({ length: 41 }, (_, i) => i) }),
+)
+await writeFile(join(OTHER, 'graft', 'INDEX.md'), '# graft repo map\n')
+
+console.log('\n--- root resolution ---')
+const fromRepo = await findGraftRoot(REPO, exists)
+check('finds an indexed repo', samePath(fromRepo, REPO), String(fromRepo))
+
+// The property the chip depends on: launched deeper in the tree, it must walk
+// UP to the same repo — this is exactly what `graft mcp` does from dsh's cwd.
+const fromNested = await findGraftRoot(join(REPO, 'profiles', 'web'), exists)
+check('walks up from a nested dir to the same root', samePath(fromNested, REPO), String(fromNested))
+
+const fromOther = await findGraftRoot(OTHER, exists)
+check('finds a second repo, not the first', samePath(fromOther, OTHER), String(fromOther))
+check('and a space in the path does not break it', OTHER.includes(' '))
+
+const nowhere = await findGraftRoot(BARE, exists)
+check('an unindexed tree resolves to nothing', nowhere === undefined, String(nowhere))
+
+console.log('\n--- status from the cache ---')
+const status = await computeStatus(REPO, io)
+check('reports the cache node count', status.nodeCount === 1284, String(status.nodeCount))
+check('reports the cache edge count', status.edgeCount === 5312, String(status.edgeCount))
+check('carries the root back', samePath(status.root, REPO))
+check('freshness is a known word', ['synced', 'stale', 'syncing', 'unknown'].includes(status.freshness), status.freshness)
+check('came from the live cache', status.source === 'cache', status.source)
+
+console.log('\n--- the graph fallback ---')
+// stats.json absent: must fall back to the wiring graph rather than report
+// "no graph", which is the bug graft's own statusline documents.
+const noCache = await computeStatus(REPO, {
+  ...io,
+  readJson: async (path) => (path.endsWith('stats.json') ? undefined : readJson(path)),
+})
+check('falls back to the wiring graph', noCache.source === 'graph', noCache.source)
+check('counts from the graph, not the cache', noCache.nodeCount === 97, String(noCache.nodeCount))
+check('admits it has no drift signal', noCache.freshness === 'synced')
+
+console.log('\n--- a repo with no graft at all ---')
+const bare = await computeStatus(BARE, io)
+check('reports not-ok rather than throwing', bare.ok === false, JSON.stringify(bare))
+
+/* ========================================================================== *
+ * The visualiser
+ * ========================================================================== */
+
+console.log('\n--- the workspace comes from the SESSION, not the launch dir ---')
+const { cwdForSession } = await import('../src/index.js')
+// The exact failure reported: dsh launched from a directory with no graft index
+// above it, while the session's workspace had one.
+const HOME = BARE
+const fakeSessions = { get: (id) => (id === 'sess-street' ? { header: { cwd: OTHER } } : undefined) }
+check('a session cwd wins over the launch dir', cwdForSession(fakeSessions, 'sess-street', HOME) === OTHER)
+check('and it is the one that resolves a graft root', (await findGraftRoot(cwdForSession(fakeSessions, 'sess-street', HOME), exists)) !== undefined)
+check('while the launch dir resolves nothing', (await findGraftRoot(HOME, exists)) === undefined)
+check('an unknown session falls back', cwdForSession(fakeSessions, 'nope', HOME) === HOME)
+check('a session with no cwd falls back', cwdForSession({ get: () => ({ header: {} }) }, 'x', HOME) === HOME)
+check('no sessions service at all falls back', cwdForSession(undefined, 'x', HOME) === HOME)
+check('a throwing service falls back', cwdForSession({ get: () => { throw new Error('nope') } }, 'x', HOME) === HOME)
+check('no session id falls back', cwdForSession(fakeSessions, undefined, HOME) === HOME)
+
+console.log('\n--- graft viz: port choice and startup ---')
+const { startViz, pickPort } = await import('../src/index.js')
+
+const never = { exitCode: null }
+const wait = async () => {}
+
+// One `graft viz` serves ONE repo, so a server this plugin did not start is
+// useless to it: from the outside there is no way to tell which repo the thing
+// on that port is serving. An earlier version adopted it anyway, which is
+// invisible and wrong the moment a second repo is open. Free ports instead.
+check('takes the base port when it is free', (await pickPort(4400, { alive: async () => false })) === 4400)
+check(
+  'steps over a port something else holds',
+  (await pickPort(4400, { alive: async (p) => p < 4402 })) === 4402,
+)
+check(
+  'gives up rather than looping forever',
+  (await pickPort(4400, { alive: async () => true }, 3)) === undefined,
+)
+
+// Not yet listening, then listening: must wait for the socket, not the banner.
+let polls = 0
+const started = await startViz('C:/x', 4400, {
+  alive: async () => (polls++ > 1),
+  wait,
+  spawn: () => never,
+})
+check('waits for the port, then reports the url', started.ok === true && started.url === 'http://127.0.0.1:4400/', JSON.stringify(started))
+
+// A child that dies must fail immediately rather than burn the whole deadline.
+const died = await startViz('C:/x', 4400, {
+  alive: async () => false,
+  wait,
+  spawn: () => ({ exitCode: 9 }),
+})
+check('a child that exits is reported, not awaited', died.ok === false && /exited with code 9/.test(died.reason), String(died.reason))
+
+const cannotSpawn = await startViz('C:/x', 4400, {
+  alive: async () => false,
+  wait,
+  spawn: () => { throw new Error('graft not on PATH') },
+})
+check('an unspawnable graft is a reason, not a throw', cannotSpawn.ok === false && /not on PATH/.test(cannotSpawn.reason))
+
+/* ========================================================================== *
+ * The new-tab handle (a source-level guard)
+ * ========================================================================== */
+
+console.log('\n--- window.open must keep its handle ---')
+// Asserted against the SOURCE because this failure is unreachable from Node and
+// invisible at runtime: `window.open` returns null when `noopener` is set — that
+// is the flag's whole purpose — so a caller that needs the handle and passes it
+// anyway opens a tab it can never write to or navigate. That shipped once and
+// showed up as a permanent blank page, with no error anywhere.
+const clientSource = await readFile(new URL('../src/client.js', import.meta.url), 'utf8')
+const opens = clientSource.match(/window\.open\([^)]*\)/g) ?? []
+check('the tab is opened exactly once', opens.length === 1, opens.join(' | '))
+check('and never with noopener', opens.every((call) => !call.includes('noopener')), opens.join(' | '))
+check('and opened blank, to be navigated later', (opens[0] ?? '').includes('"", "_blank"'), opens[0])
+
+console.log('\n--- the sidebar tab is a consumer, not a patch ---')
+// dsh-better-sidebar is never edited by this plugin: the tab is contributed
+// through its documented `ctx.betterSidebar` service, which its README states
+// third-party tabs and its own built-in eight share.
+check('registers a tab through the public service', clientSource.includes('betterSidebar.registerTab('))
+// Resolved through the inject-free accessor, then called — `ctx.betterSidebar`
+// would throw without a declared inject, which is exactly what must not happen
+// in a profile that lacks the sidebar.
+check('resolves the service without requiring an inject', clientSource.includes('ctx.get("betterSidebar")'))
+check('opens the tab through it', /\.openTab\(\{ type: TAB_TYPE/.test(clientSource))
+// A HARD dependency would stop this whole plugin — chip included — from
+// activating in a profile without the sidebar. It must stay a soft one.
+check(
+  'declares the dependency softly (ctx.inject, not the module inject list)',
+  clientSource.includes('ctx.inject(["betterSidebar"]') && /const inject = \[[^\]]*\]/.exec(clientSource)?.[0].includes('betterSidebar') === false,
+  /const inject = \[[^\]]*\]/.exec(clientSource)?.[0],
+)
+check('the browser tab survives only as the fallback', clientSource.includes('no dsh-better-sidebar'))
+
+await rm(fixture, { recursive: true, force: true })
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-tools.mjs

@@ -0,0 +1,53 @@
+import { graftTools, repoFor, runGraft } from '../src/graft-tools.js'
+import { findGraftRoot } from '../src/index.js'
+import { access } from 'node:fs/promises'
+
+let failures = 0
+const check = (label, ok, extra = '') => {
+  console.log((ok ? 'PASS  ' : 'FAIL  ') + label + (extra ? '  -> ' + extra : ''))
+  if (!ok) failures += 1
+}
+const exists = async (p) => { try { await access(p); return true } catch { return false } }
+
+const HOME = 'C:/Users/adith'
+const STREET = 'B:/Research/Local_LLmtest/Street Yeet'
+const deps = { fallbackCwd: HOME, findRoot: (s) => findGraftRoot(s, exists) }
+const tools = graftTools(deps)
+const byName = new Map(tools.map((t) => [t.name, t]))
+
+console.log('--- the repo comes from the CALL, not the process ---')
+check('session cwd wins', repoFor({ agent: { session: { header: { cwd: STREET } } } }, HOME) === STREET)
+check('no agent falls back', repoFor(undefined, HOME) === HOME)
+check('agent with no cwd falls back', repoFor({ agent: { session: { header: {} } } }, HOME) === HOME)
+
+console.log('\n--- the five tools are registered ---')
+for (const n of ['graft_ask', 'graft_grep', 'graft_callers', 'graft_skeleton', 'graft_map']) {
+  check(n + ' exists', byName.has(n))
+}
+check('none declares a boolean parameter (the leak bug)',
+  tools.every((t) => Object.values(t.parameters?.properties ?? {}).every((p) => p.type !== 'boolean')))
+check('all declare a timeout so dsh bounds them', tools.every((t) => typeof t.timeoutMs === 'number'))
+
+console.log('\n--- real calls against the REAL repos ---')
+// dsh's process cwd is deliberately HOME here: the exact broken situation.
+const street = { agent: { session: { header: { cwd: STREET } } } }
+const map = await byName.get('graft_map').execute({ max_dirs: 3 }, street)
+check('graft_map answers about Street Yeet', /tokens saved/.test(map.text) && !/no graph/i.test(map.text), map.text.split('\n')[0].slice(0, 80))
+
+const ask = await byName.get('graft_ask').execute({ query: 'punch animation' }, street)
+check('graft_ask finds code there', /tokens saved/.test(ask.text), ask.text.split('\n')[0].slice(0, 80))
+
+const grep = await byName.get('graft_grep').execute({ pattern: 'def ', match: 'literal' }, street)
+check('graft_grep runs with an enum flag', !/error|unknown option/i.test(grep.text), grep.text.split('\n')[0].slice(0, 80))
+
+// A different session in the SAME dsh must get a different repo.
+const dsh = { agent: { session: { header: { cwd: 'C:/Users/adith/.dsh' } } } }
+const dshMap = await byName.get('graft_map').execute({ max_dirs: 3 }, dsh)
+check('a second workspace gets ITS own graph', /tokens saved/.test(dshMap.text) && dshMap.text !== map.text)
+
+console.log('\n--- a workspace with no index explains itself ---')
+const bare = await byName.get('graft_map').execute({}, { agent: { session: { header: { cwd: 'C:/Windows' } } } })
+check('says how to fix it, does not just fail', /Run `graft build`/.test(bare.text), bare.text.split('\n')[0].slice(0, 90))
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/src/auto-sync.js

@@ -0,0 +1,262 @@
+/**
+ * Keep the graft graph current as the model edits code.
+ *
+ * WHAT CLAUDE CODE GETS THAT dsh DOES NOT
+ *
+ * `graft init` installs two hooks there: a post-edit hook that marks the graph
+ * dirty, and a Stop hook that rebuilds it at the end of a turn. dsh is not one
+ * of the agents `graft init` knows (`--list-agents`: agents, adal, cursor,
+ * gemini, grok, hermes, antigravity, copilot, kiro, windsurf, claude), so a dsh
+ * user is left running `graft build` by hand and, in practice, forgetting to.
+ *
+ * This is the same two hooks on dsh's own seams — `tools/execute` for the edit
+ * signal, `agent/turn-stopping` for the rebuild — plus a third trigger graft
+ * does not need: a debounced rebuild DURING a turn. Claude Code turns are short;
+ * one turn here can run half an hour across dozens of edits, and waiting for its
+ * end would leave the model querying a graph it had already invalidated.
+ *
+ * IT REUSES GRAFT'S OWN SCRIPT, NOT A REIMPLEMENTATION
+ *
+ * The rebuild is graft's `dist/claude/sync-run.js`, spawned exactly as its Stop
+ * hook spawns it, and the dirty/lock bookkeeping goes through graft's own
+ * `state.js`. That matters for three reasons: `sync-run` already patches
+ * `stats.json` on the way out (clearing `dirty`, stamping `syncedAt`, writing
+ * the new counts), which is the file the status chip reads — so the chip shows
+ * "syncing" then "in sync" for free; the lock is graft's, so a dsh rebuild and
+ * a Claude Code rebuild in the same repo cannot run over each other; and its
+ * money guard travels with it.
+ *
+ * THE MONEY GUARD
+ *
+ * `sync-run.js` carries the comment "MONEY GUARD: plain `graft build` only —
+ * structural, $0, offline. Never --deep." Calling that script rather than
+ * assembling an argv here is what keeps that promise true: an automatic
+ * rebuild can never start billing an LLM, because the code that decides the
+ * arguments is graft's, not this plugin's.
+ *
+ * @module graft-status/auto-sync
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Tools whose success means the working tree may have moved.
+ *
+ * THESE ARE dsh's REAL WIRE NAMES. The list previously read `write_file`,
+ * `terminal` and `shell` — none of which dsh registers — while omitting `write`
+ * and `str_replace_editor`, which it does. The effect was worst in exactly the
+ * case it should have handled best: in a NEW repo every file arrives through
+ * `write`, so nothing was ever marked dirty and the graph stayed at whatever
+ * `/graft` first built until someone ran `graft build` by hand. `edit` and the
+ * shells worked, which is why it looked intermittent rather than broken.
+ *
+ * Source of truth, from the packages that register them:
+ *   dsh-tool-fs                  write · edit   (also read, read_image)
+ *   dsh-tool-str-replace-editor  str_replace_editor
+ *   dsh-tool-bash / -pwsh        bash · pwsh
+ *
+ * The shells are on the list deliberately. graft's own post-edit hook watches
+ * file-editing tools, but in this deployment most files arrive from a script
+ * the model runs — a Blender export, a Godot build — and an edit-tools-only
+ * trigger would miss exactly the changes that matter most. The cost of being
+ * broad is bounded by the design: the flag only marks the graph dirty, and the
+ * debounce collapses a burst of writes into a single rebuild.
+ *
+ * Override with the row's `autoBuildTools` if a deployment registers others.
+ */
+const DEFAULT_WRITE_TOOLS = ['write', 'edit', 'str_replace_editor', 'pwsh', 'bash']
+
+/** Graft's own state helpers, loaded from wherever graft is installed. */
+async function loadGraftState(cliPath) {
+  const claudeDir = join(dirname(cliPath), 'claude')
+  const statePath = join(claudeDir, 'state.js')
+  const syncRun = join(claudeDir, 'sync-run.js')
+  if (!existsSync(statePath) || !existsSync(syncRun)) return undefined
+  try {
+    const state = await import(pathToFileURL(statePath).href)
+    if (typeof state.readStats !== 'function' || typeof state.patchStats !== 'function') return undefined
+    return { state, syncRun }
+  } catch {
+    // A graft too old or too new to expose these. Auto-sync simply does not
+    // run; every other part of this plugin is unaffected.
+    return undefined
+  }
+}
+
+/**
+ * @param deps.cliPath - graft's `dist/cli.js`, from which its `claude/` dir is found.
+ * @param deps.minIntervalMs - floor between rebuilds of the same repo.
+ */
+export function createAutoSync(deps = {}) {
+  const writeTools = new Set(Array.isArray(deps.writeTools) ? deps.writeTools : DEFAULT_WRITE_TOOLS)
+  /**
+   * Floor between rebuild ATTEMPTS on one repo.
+   *
+   * Was 30s, which was wrong: a structural build of a normal repo takes about a
+   * second, so a 30s floor meant that in a quick back-and-forth most turns were
+   * refused with `too-soon` and the graph simply stayed stale — the opposite of
+   * the point. Overlapping builds are already prevented by graft's own lock,
+   * which is what that lock is for; this is only a brake on a spawn storm if
+   * the lock is ever unavailable.
+   */
+  const minIntervalMs = Number.isInteger(deps.minIntervalMs) ? deps.minIntervalMs : 5_000
+  const spawnFn = deps.spawn ?? spawn
+  const now = deps.now ?? (() => Date.now())
+
+  /**
+   * Quiet period after the last write before rebuilding mid-turn.
+   *
+   * The turn boundary alone is not enough. One agentic turn here routinely runs
+   * for tens of minutes across dozens of edits — a graph marked dirty in its
+   * first minute then stayed stale for the next thirty-five, and every
+   * `graft_ask` the model made in between answered from it. Waiting for a lull
+   * instead of for the turn means a burst of edits still costs ONE rebuild,
+   * while a long turn no longer reasons about its own stale graph.
+   *
+   * Set to 0 to go back to turn-end-only.
+   */
+  const debounceMs = Number.isInteger(deps.debounceMs) ? deps.debounceMs : 20_000
+
+  /** Roots edited since their last rebuild. */
+  const pending = new Set()
+  /** root -> when a rebuild was last STARTED, for the interval floor. */
+  const lastRun = new Map()
+  /** root -> pending debounce timer. */
+  const timers = new Map()
+  const setTimer = deps.setTimeout ?? setTimeout
+  const clearTimer = deps.clearTimeout ?? clearTimeout
+
+  let loaded
+  const graft = async () => {
+    if (loaded === undefined) {
+      loaded = deps.graft !== undefined ? deps.graft : await loadGraftState(deps.cliPath)
+      if (loaded === undefined) loaded = null
+    }
+    return loaded
+  }
+
+  const api = {
+    /** Whether a finished tool call means the tree may have changed. */
+    touches: (toolName) => writeTools.has(toolName),
+
+    /**
+     * Record that a repo's code moved.
+     *
+     * Written through graft's `patchStats` so the flag lands in the same field,
+     * in the same file, that graft's own hooks and `graft check` use — a chip
+     * reading `dirty` cannot then disagree with the CLI about the same repo.
+     */
+    markDirty: async (root) => {
+      if (typeof root !== 'string' || root === '') return
+      pending.add(root)
+
+      // Restarted on every write, so a run of edits rebuilds once at the end of
+      // the burst rather than once per file.
+      if (debounceMs > 0) {
+        clearTimer(timers.get(root))
+        timers.set(
+          root,
+          setTimer(() => {
+            timers.delete(root)
+            void api.syncIfDirty(root)
+          }, debounceMs),
+        )
+      }
+
+      const g = await graft()
+      if (g === null) return
+      try {
+        g.state.patchStats(root, { dirty: true })
+      } catch {
+        // The in-memory `pending` set still carries the turn-end trigger, so a
+        // failed write costs the chip's live dirty flag, not the rebuild.
+      }
+    },
+
+    /**
+     * Rebuild one repo if it needs it. Called at the turn boundary, and from
+     * the debounce timer once writing has gone quiet mid-turn.
+     *
+     * @returns why it did or did not run, for the harness and the log.
+     */
+    syncIfDirty: async (root) => {
+      if (typeof root !== 'string' || root === '') return 'no-root'
+      const g = await graft()
+      if (g === null) return 'graft-unavailable'
+
+      const since = now() - (lastRun.get(root) ?? -Infinity)
+      if (since < minIntervalMs) return 'too-soon'
+
+      // graft's own gate: its `dirty` flag is the shared source of truth, so an
+      // edit made in another client counts, and a repo nothing touched is
+      // never rebuilt just because a turn ended here.
+      let stats
+      try {
+        stats = g.state.readStats(root)
+      } catch {
+        return 'unreadable'
+      }
+      if (stats?.dirty !== true && !pending.has(root)) return 'clean'
+
+      // The lock is graft's, so a rebuild already running — started here, or by
+      // Claude Code in the same repo — is left alone rather than raced.
+      try {
+        if (typeof g.state.acquireLock === 'function' && !g.state.acquireLock(root)) return 'locked'
+        g.state.patchStats(root, { syncing: true })
+      } catch {
+        return 'unreadable'
+      }
+
+      pending.delete(root)
+      lastRun.set(root, now())
+      try {
+        /*
+         * NOT detached, and that is load-bearing on Windows.
+         *
+         * `sync-run.js` does its actual work through
+         *
+         *     execFileSync(process.execPath, [cli, 'build', '.'], { stdio: 'ignore' })
+         *
+         * with no `windowsHide`. A console process started without
+         * CREATE_NO_WINDOW inherits its parent's console — but DETACHED_PROCESS
+         * (which is what `detached: true` means here) leaves this child with no
+         * console at all, so there is nothing to inherit and Windows gives the
+         * grandchild a brand new, VISIBLE one.
+         *
+         * That is the terminal that flashes on every rebuild, and a new console
+         * window takes foreground: it minimises a fullscreen game. Measured,
+         * `detached: true` leaves the child with no console while
+         * `windowsHide: true` alone gives it its own CREATE_NO_WINDOW console —
+         * invisible, and inherited by the grandchild, which is exactly what is
+         * wanted.
+         *
+         * The cost is that a rebuild no longer survives dsh exiting mid-build.
+         * That is cheap: the repo simply stays marked dirty and the next write
+         * triggers it again. `unref()` still keeps it from holding dsh open,
+         * and `sync-run` clears `syncing` and releases the lock on its own way
+         * out either way.
+         */
+        const child = spawnFn(process.execPath, [g.syncRun, root], {
+          stdio: 'ignore',
+          windowsHide: true,
+        })
+        child.on?.('error', () => {})
+        child.unref?.()
+      } catch {
+        return 'spawn-failed'
+      }
+      return 'started'
+    },
+
+    /** Drop any pending debounce timers, so a disposed plugin fires nothing. */
+    dispose: () => {
+      for (const timer of timers.values()) clearTimer(timer)
+      timers.clear()
+    },
+  }
+
+  return api
+}