dsh-graft-plugin 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Adithyan Raj
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Adithya N Raj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -48,11 +48,32 @@ cd <your repo>
 graft build
 ```
 
+### In the desktop app
+
+The desktop dsh installs plugins from its own **Plugins** settings — no CLI, no profile directory:
+
+1. Open **Plugins** (settings, left sidebar) and click **Add plugin**.
+2. Paste the GitHub repository address into the field (the package name `dsh-graft-plugin` works too):
+
+   ```
+   https://github.com/adithyanraj03/dsh-graft-plugin
+   ```
+
+3. Click **Install**.
+
+![The Add plugin dialog with the repository address](assets/dsh-desktop-app-install.png)
+
+The dialog switches to the **Installed** confirmation, and the plugin appears under **Installed** at the bottom of the settings page:
+
+![The Installed confirmation with the install details](assets/dsh-desktop-app-install-2.png)
+
+> The dialog notes that installed plugins **do not update automatically yet** — to upgrade, uninstall and install again. The graft CLI requirement (`npm install -g @nanonets/graft`) is the same.
+
 ### The sidebar tab
 
 On dsh `0.1.5` and later the button opens the graph in **dsh's own right sidebar** — a tab titled Graft, also listed on the sidebar's guide page as "The graft graph for this workspace" — and a second click focuses the tab that is already open. No install needed for that path: the registration is soft, so an older dsh without the right sidebar falls through to `dsh-better-sidebar` when it is mounted, and to a browser tab when neither is there.
 
-If your profile still runs `dsh-better-sidebar`, that path is tried **first** and behaves exactly as before. It ships as a dependency of this plugin (0.18.x), so it is already downloaded — but dsh only mounts what the profile lists:
+If your profile still runs `dsh-better-sidebar`, that path is tried **first** and behaves exactly as before. From 0.3.0 it is an **optional peer dependency** — dsh no longer downloads it for you, so add it yourself when you want it (on dsh `0.1.5-rc.2` or later it cannot mount anyway, so most profiles should skip this):
 
 ```sh
 dsh plugin --profile web add dsh-better-sidebar
@@ -133,8 +154,11 @@ All optional, all on the plugin's row in your profile's `cordis.patch.yml`:
 
 | dsh | status |
 |---|---|
+| `0.2.1-rc.2` | test suites pass against the `0.2.1-rc.2` packages — chip, tools, `/graft`, auto-rebuild and the model-facing guidance; the dual-shape codecs load on both 0.1 and 0.2 hosts |
+| `0.1.7-rc.2` | tested on a live profile (0.3.0) — chip, tools, `/graft`, auto-rebuild and the model-facing guidance all verified |
 | `0.1.2-rc.1` – `0.1.0-rc.7` | tested, full feature set — the `graft viz` tab via `dsh-better-sidebar` |
 | `0.1.5-rc.2` / `0.1.5` | tested — chip, tools, `/graft` and auto-rebuild all work; on `0.1.5` the `graft viz` button opens the graph in the built-in right sidebar |
+| `0.2.0-rc.2` | needs plugin `0.2.1`+ — earlier releases fail to activate (see Troubleshooting) |
 
 - Node 22+
 - the `graft` CLI on PATH (`npm install -g @nanonets/graft`)
@@ -168,6 +192,8 @@ registering "dsh-graft-plugin" via __ModuleLoader__.load
 
 **No chip appears and dsh started without errors.** The plugin is in the profile's `package.json` `dependencies` but not in `dsh.profile.bundles` — which happens under pnpm 10+ when the `add` ends non-zero on `ERR_PNPM_IGNORED_BUILDS`; dsh skips the bundle row in that case and starts up looking healthy. Fix: `pnpm approve-builds` in the profile directory (tick `dsh-graft-plugin`), then re-run `dsh plugin --profile web add dsh-graft-plugin`. If `pnpm approve-builds` reports nothing awaiting approval, check `pnpm-workspace.yaml` for an unanswered `dsh-graft-plugin` entry (pnpm's approval placeholder) and set its value to `true` first.
 
+**On dsh 0.2 the plugin fails to load with `strict codec has no create() factory`, and dsh offers to remove it.** dsh 0.2 requires every strict remote codec to carry a `create()` schema factory; plugin releases before `0.2.1` only had the 0.1 `schema` key. Update to `0.2.1` or later, which carries both and so loads on 0.1 and 0.2.
+
 **`/graft` says the graft CLI is not on PATH.** The postinstall was blocked or skipped (see Install): `npm install -g @nanonets/graft`.
 
 ## Licence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-graft-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shows which graft index a dsh session is serving and whether it still matches the code, and gives the model graft_ask, graft_grep, graft_callers, graft_skeleton and graft_map as native tools.",
   "type": "module",
   "main": "src/index.js",
@@ -25,12 +25,13 @@
     "scripts/test-tools.mjs",
     "scripts/test-autosync.mjs",
     "scripts/test-command.mjs",
+    "scripts/test-guidance.mjs",
     "README.md",
     "LICENSE",
     "screenshots.json"
   ],
   "scripts": {
-    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs",
+    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs && node scripts/test-guidance.mjs",
     "test:live": "node scripts/test-tools.mjs",
     "postinstall": "node scripts/postinstall.mjs"
   },
@@ -45,15 +46,19 @@
       ]
     }
   },
-  "dependencies": {
-    "dsh-better-sidebar": "^0.18.0"
-  },
   "peerDependencies": {
-    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.6"
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.6",
+    "dsh-better-sidebar": ">=0.18.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1"
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2"
   },
   "keywords": [
     "dsh-plugin",

package/scripts/test-autosync.mjs

@@ -1,4 +1,5 @@
-import { savedTokensIn } from '../src/graft-tools.js'
+import { join } from 'node:path'
+import { resolveGraftCommand, savedTokensIn } from '../src/graft-tools.js'
 import { createAutoSync } from '../src/auto-sync.js'
 import { totalSaved } from '../src/index.js'
 
@@ -76,6 +77,17 @@ console.log('\n--- graft missing is not an error ---')
 const none = createAutoSync({ graft: null, now: () => now, spawn: () => { throw new Error('should not spawn') } })
 check('no graft, no rebuild, no throw', (await none.syncIfDirty('C:/x')) === 'graft-unavailable')
 
+console.log('\n--- a manual Build forces a rebuild, like the popup button ---')
+// The popup's Build must not go through syncIfDirty's gates: a repo whose
+// stats already read clean (plain `graft build` never patches stats.json, so
+// `dirty` is whatever the last sync-run left) would answer 'clean' and spawn
+// nothing — the exact "button press changes nothing" shipped once.
+state.lock = true
+now += 60_000
+check('a forced rebuild skips the clean gate', (await sync.rebuild('C:/y')) === 'started')
+check('and it spawned graft\'s sync-run for that root', spawned.some((a) => a[1][1] === 'C:/y'), JSON.stringify(spawned.at(-1)))
+check('it set syncing so the chip can show it', state.stats.syncing === true)
+
 console.log('\n--- mid-turn rebuild: a long turn must not sit on a stale graph ---')
 // The turn boundary alone left a graph dirty for 36 minutes of one agentic
 // turn while the model kept querying it. A write now also arms a debounce.
@@ -106,6 +118,11 @@ check('a second write replaces the timer, not adds one', pendingTimers.size ===
 const fire = [...pendingTimers.values()][0]
 pendingTimers.clear()
 await fire()
+// The timer callback fires syncIfDirty without awaiting it (fire-and-forget
+// by design — a throw inside a timer must never surface), so flush before
+// asserting the spawn landed. This needed one more hop once syncIfDirty
+// started delegating to rebuild().
+await new Promise((resolve) => setTimeout(resolve, 0))
 check('the quiet period rebuilds without waiting for the turn', fired.length === 1, String(fired.length))
 
 const off = createAutoSync({ graft: { state, syncRun: 'x' }, now: () => now, spawn: () => ({ on() {}, unref() {} }), debounceMs: 0, setTimeout: () => { throw new Error('should not arm') } })
@@ -113,5 +130,53 @@ let armed = true
 try { await off.markDirty('C:/y') } catch { armed = false }
 check('debounceMs 0 restores turn-end-only', armed === true)
 
+console.log('\n--- a graft cli we cannot locate must never crash dsh ---')
+// THE ORIGINAL FATALITY: graft installed as a bare shim (bun global) left
+// `cliPath` undefined, `dirname(undefined)` in loadGraftState escaped the
+// `void`-ed markDirty as an unhandled rejection, and dsh died on the FIRST
+// successful edit in an indexed repo. These checks pin the guarantee: no
+// input, no throw, no rejection, no spawn.
+const noCli = createAutoSync({ now: () => now, spawn: (...a) => { spawned.push(a); return { on() {}, unref() {} } }, debounceMs: 0 })
+let crashed = false
+const spawnedBefore = spawned.length
+try { await noCli.markDirty('C:/no-cli') } catch { crashed = true }
+check('markDirty resolves without a cli', crashed === false)
+check('and never spawns a rebuild', spawned.length === spawnedBefore, String(spawned.length - spawnedBefore))
+check('syncIfDirty reports graft unavailable', (await noCli.syncIfDirty('C:/no-cli')) === 'graft-unavailable')
+
+// Even a loader that REJECTS is swallowed — graft() awaits the injected stub
+// inside its own try, so no input shape can turn into an unhandled rejection.
+const throwing = createAutoSync({ graft: Promise.reject(new Error('boom')), now: () => now, spawn: () => ({ on() {}, unref() {} }), debounceMs: 0 })
+crashed = false
+try { await throwing.markDirty('C:/throwing') } catch { crashed = true }
+check('a rejecting graft loader is swallowed', crashed === false)
+check('and sync stays unavailable, not fatal', (await throwing.syncIfDirty('C:/throwing')) === 'graft-unavailable')
+
+console.log('\n--- resolveGraftCommand finds graft however it was installed ---')
+const fakeExists = (set) => (p) => set.has(p)
+const bunCli = join('/home/x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+// A bun global install: only the shim is on PATH, the package lives under
+// $BUN_INSTALL/install/global. The PATH-only scan returned prefix: [] here,
+// which is what fed undefined into loadGraftState above.
+const viaBunInstall = resolveGraftCommand(
+  { PATH: '/home/x/.bun/bin', BUN_INSTALL: '/home/x/.bun', HOME: '/home/x' },
+  fakeExists(new Set([bunCli])),
+)
+check('a bun global install resolves to its dist cli', viaBunInstall.prefix[0] === bunCli && viaBunInstall.shell === false, viaBunInstall.prefix[0])
+const viaHome = resolveGraftCommand(
+  { PATH: '', HOME: '/home/x' },
+  fakeExists(new Set([bunCli])),
+)
+check('or via HOME/.bun when BUN_INSTALL is unset', viaHome.prefix[0] === bunCli, viaHome.prefix[0])
+const viaUserprofile = resolveGraftCommand(
+  { PATH: '', USERPROFILE: 'C:\\Users\\x' },
+  // The fixture path is built with the same join() the source uses, so this
+  // checks WHERE the lookup happens, not how a host renders separators.
+  fakeExists(new Set([join('C:\\Users\\x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')])),
+)
+check('or via USERPROFILE/.bun on Windows', viaUserprofile.prefix[0] === join('C:\\Users\\x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js'), viaUserprofile.prefix[0])
+const bare = resolveGraftCommand({ PATH: '', HOME: '/home/x' }, fakeExists(new Set()))
+check('nothing installed falls back to the bare command', bare.command === 'graft' && bare.prefix.length === 0)
+
 console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
 process.exit(failures === 0 ? 0 : 1)

package/scripts/test-guidance.mjs

@@ -0,0 +1,160 @@
+/**
+ * The standing instruction must reach the model on CURRENT dsh.
+ *
+ * dsh `0.1.7-rc.2` removed the `agent/session-start` event the guidance used to
+ * ride: the listener stayed registered and the suite stayed green, while no
+ * agent ever fired it, so `graft-status:usage` silently vanished from every
+ * prompt. This suite runs `apply()` against a REAL Cordis context and drives
+ * the event dsh actually emits now (`agent/created`, the same seam dsh's own
+ * file-reference plugin uses), so an upstream rename fails here instead of
+ * disappearing into a prompt nobody diffs.
+ *
+ * Cordis resolves injects asynchronously, so every check after a trigger
+ * waits a tick first — the assertions test what a live session would see,
+ * not what a synchronous read-back would flatter.
+ *
+ * Run:  node scripts/test-guidance.mjs      (part of `npm test`)
+ */
+import { readFile } from 'node:fs/promises'
+import { Context, Service } from '@deepseek-ai/cordis'
+
+import { apply } from '../src/index.js'
+
+let failures = 0
+const check = (label, ok, extra = '') => {
+  console.log((ok ? 'PASS  ' : 'FAIL  ') + label + (extra ? '  -> ' + extra : ''))
+  if (!ok) failures += 1
+}
+/** Let pending Cordis inject fibers and disposals settle. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+/** The whole prompt section this plugin registers, as the tests see it. */
+const SECTION_NAME = 'graft-status:usage'
+const GUIDANCE_ORDER = 950
+
+/**
+ * A prompt-registry stand-in that behaves like the real `systemPrompt`
+ * service where it matters. It is a Cordis Service, so the traceable-context
+ * overlay applies, and `section()` creates its undo effect on the CALLER's
+ * context — the same ownership `SystemPrompt.section()` gets through
+ * `ScopedLayers`, and the reason an agent's section can die with the agent.
+ */
+function fakePromptRegistry(sections, removed) {
+  return class FakePromptRegistry extends Service {
+    constructor(ctx) {
+      super(ctx, 'systemPrompt')
+    }
+
+    section(section) {
+      sections.push(section)
+      return this.ctx.effect(() => () => {
+        removed.push(section.name)
+      }, `fake.section(${section.name})`)
+    }
+  }
+}
+
+/** Mount the stand-in on a context as the `systemPrompt` service. */
+function providePromptRegistry(ctx, sections, removed) {
+  ctx.plugin(fakePromptRegistry(sections, removed))
+}
+
+console.log('--- apply() against a real Cordis context ---')
+const root = new Context()
+const registeredTools = []
+const sections = []
+const removed = []
+root.plugin(fakePromptRegistry(sections, removed))
+root.reflect.provide('tools', {
+  register(tool) {
+    registeredTools.push(tool)
+    return () => {}
+  },
+})
+
+let threw
+try {
+  await apply(root, {})
+} catch (error) {
+  threw = error
+}
+check('apply() mounts without throwing', threw === undefined, threw ? String(threw) : '')
+check('the five graft tools register', registeredTools.length === 5, registeredTools.map((t) => t.name).join(', '))
+
+console.log('\n--- the guidance rides agent/created, not the removed agent/session-start ---')
+check(
+  'the source never names the removed event',
+  !(await readFile(new URL('../src/index.js', import.meta.url), 'utf8')).includes('agent/session-start'),
+)
+check('no guidance before any agent exists', sections.length === 0, JSON.stringify(sections))
+
+console.log('\n--- an agent with the prompt registry gets the section ---')
+const agent = { ctx: new Context() }
+providePromptRegistry(agent.ctx, sections, removed)
+root.emit('agent/created', { agent })
+await settle()
+check('the section registered on the agent scope', sections.length === 1, JSON.stringify(sections[0]?.name))
+check('under its own name', sections[0]?.name === SECTION_NAME, sections[0]?.name)
+check('at the documented order', sections[0]?.order === GUIDANCE_ORDER, String(sections[0]?.order))
+check('with the graft guidance text', /graft_ask/.test(sections[0]?.text ?? ''), (sections[0]?.text ?? '').split('\n')[0])
+
+console.log('\n--- a second announce does not duplicate it ---')
+root.emit('agent/created', { agent })
+await settle()
+check('the section registered exactly once', sections.length === 1, String(sections.length))
+
+console.log('\n--- agent disposal takes the section down ---')
+root.emit('agent/disposed', { agent })
+await settle()
+check('the section was disposed with the agent', removed.length === 1, JSON.stringify(removed))
+
+console.log('\n--- an agent WITHOUT the prompt registry only loses the sentence ---')
+const bare = { ctx: new Context() }
+let bareThrew
+try {
+  root.emit('agent/created', { agent: bare })
+  await settle()
+} catch (error) {
+  bareThrew = error
+}
+check('a registry-less agent is survived, not crashed', bareThrew === undefined, bareThrew ? String(bareThrew) : '')
+check('and it adds no section', sections.length === 1, String(sections.length))
+
+console.log('\n--- agents that already exist when the row mounts are briefed too ---')
+const lateRoot = new Context()
+lateRoot.reflect.provide('tools', { register: () => () => {} })
+providePromptRegistry(lateRoot, sections, removed)
+lateRoot.reflect.provide('agents', { list: () => [agent, bare] })
+const before = sections.length
+let lateThrew
+try {
+  await apply(lateRoot, {})
+  await settle()
+} catch (error) {
+  lateThrew = error
+}
+check('apply() with an agents service does not throw', lateThrew === undefined, lateThrew ? String(lateThrew) : '')
+check('pre-existing agents got the section at mount', sections.length === before + 1, `${sections.length - before} added`)
+check('and the registry-less one stayed silent', sections.every((s) => s.name === SECTION_NAME))
+
+console.log('\n--- promptSection: false registers nothing ---')
+const quietRoot = new Context()
+quietRoot.reflect.provide('tools', { register: () => () => {} })
+providePromptRegistry(quietRoot, sections, removed)
+quietRoot.reflect.provide('agents', { list: () => [agent] })
+await apply(quietRoot, { promptSection: false })
+quietRoot.emit('agent/created', { agent })
+await settle()
+check('no guidance section from a suppressed row', sections.length === before + 1, `${sections.length - before - 1} added`)
+
+console.log('\n--- teardown ---')
+for (const ctx of [root, agent.ctx, lateRoot, quietRoot]) {
+  try {
+    await ctx.fiber?.dispose?.()
+  } catch {
+    // A test context holds only fake services; nothing here may block exit.
+  }
+}
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-harness.mjs

@@ -14,7 +14,8 @@
 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'
+import { computeStatus, countWiring, createToolPulse, findGraftRoot, freshnessOf } from '../src/index.js'
+import { graftTools } from '../src/graft-tools.js'
 
 let failures = 0
 const check = (label, ok, extra = '') => {
@@ -113,6 +114,44 @@ 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--- git worktrees are their own graft root ---')
+// A linked worktree's .git is a FILE pointing at its admin dir, whose
+// commondir names the shared .git. The one that matters is NESTED inside the
+// main checkout: without the boundary, resolution walked straight past it and
+// the tools answered from the main checkout's graph — wrong paths for this
+// branch's files.
+await mkdir(join(REPO, '.git'), { recursive: true })
+const wt = join(REPO, 'wt')
+const gitDir = join(fixture, 'main.git', 'worktrees', 'wt')
+await mkdir(join(wt, 'src'), { recursive: true })
+await mkdir(gitDir, { recursive: true })
+await writeFile(join(wt, '.git'), `gitdir: ${gitDir}\n`, 'utf8')
+await writeFile(join(gitDir, 'commondir'), '../..\n', 'utf8')
+
+const fromWt = await findGraftRoot(join(wt, 'src'), exists)
+check('a nested worktree never answers from the main graph above it', fromWt === undefined, String(fromWt))
+
+const mainAgain = await findGraftRoot(REPO, exists)
+check('the main checkout itself still resolves', samePath(mainAgain, REPO), String(mainAgain))
+
+const mainStatus = await computeStatus(REPO, io)
+check('a main checkout is not reported as a worktree', mainStatus.worktreeOf === undefined, String(mainStatus.worktreeOf))
+
+// Once the worktree has its own index (graft seeds it from main on build),
+// resolution stays inside the worktree and the status names its repo.
+await mkdir(join(wt, 'graft', '.cache'), { recursive: true })
+await writeFile(join(wt, 'graft', 'INDEX.md'), '# graft repo map\n')
+await writeFile(
+  join(wt, 'graft', '.cache', 'stats.json'),
+  JSON.stringify({ nodeCount: 12, edgeCount: 7, dirty: false, staleCount: 0, syncedAt: '2026-09-11T09:00:00.000Z' }),
+)
+const wtIndexed = await findGraftRoot(join(wt, 'src'), exists)
+check('a worktree with its own index resolves to itself', samePath(wtIndexed, wt), String(wtIndexed))
+
+const wtStatus = await computeStatus(wt, io)
+check('status names the main checkout the worktree belongs to', samePath(wtStatus.worktreeOf, fixture), String(wtStatus.worktreeOf))
+check('and still serves the worktree graph', wtStatus.nodeCount === 12, String(wtStatus.nodeCount))
+
 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))
@@ -199,6 +238,53 @@ const cannotSpawn = await startViz('C:/x', 4400, {
 })
 check('an unspawnable graft is a reason, not a throw', cannotSpawn.ok === false && /not on PATH/.test(cannotSpawn.reason))
 
+/* ========================================================================== *
+ * Tool-use pulses: any graft_* call must reach the chip's dot
+ * ========================================================================== */
+
+console.log('\n--- tool use is recorded against its repo ---')
+const pulse = createToolPulse()
+check('an unused repo has no pulse', pulse.get(REPO) === undefined)
+pulse.note(REPO)
+const first = pulse.get(REPO)
+pulse.note(REPO)
+const second = pulse.get(REPO)
+check('repeated uses count up per root', first.count === 1 && second.count === 2, JSON.stringify(first) + ' vs ' + JSON.stringify(second))
+check('the pulse carries when it last happened', typeof first.at === 'number' && second.at >= first.at)
+check('another repo pulses independently', pulse.get(OTHER) === undefined)
+pulse.note('')
+check('an empty root is ignored', pulse.get('') === undefined)
+
+console.log('\n--- every graft tool announces its own use ---')
+const pulsed = []
+const spawnedArgv = []
+const fakeSpawn = (command, argv) => {
+  spawnedArgv.push([command, argv])
+  return {
+    stdout: { on() {} },
+    stderr: { on() {} },
+    on(event, fn) { if (event === 'close') fn() },
+    kill() {},
+  }
+}
+const pulseTools = graftTools({
+  fallbackCwd: BARE,
+  // BARE has no index: the no-graph branch. Everything else resolves to REPO.
+  findRoot: async (start) => (start === BARE ? undefined : REPO),
+  noteUse: (root) => pulsed.push(root),
+  command: { command: 'graft-fake', prefix: [], shell: false },
+  spawn: fakeSpawn,
+})
+const ask = pulseTools.find((t) => t.name === 'graft_ask')
+const answered = await ask.execute({ query: 'anything' }, { agent: { session: { header: { cwd: OTHER } } } })
+check('the call still answers', typeof answered.text === 'string' && answered.text !== '', answered.text.slice(0, 60))
+check('rooted at the session repo, not the process cwd', samePath(spawnedArgv[0]?.[1]?.at(-1), REPO), String(spawnedArgv[0]?.[1]?.at(-1)))
+check('one call, one pulse, for the right root', pulsed.length === 1 && samePath(pulsed[0], REPO), JSON.stringify(pulsed))
+
+const noGraph = await ask.execute({ query: 'anything' }, { agent: { session: { header: { cwd: BARE } } } })
+check('a workspace with no graph explains itself', /No graft index/.test(noGraph.text))
+check('and does not pulse — there is no green dot to light', pulsed.length === 1, JSON.stringify(pulsed))
+
 /* ========================================================================== *
  * The new-tab handle (a source-level guard)
  * ========================================================================== */
@@ -255,6 +341,138 @@ check('the type and its body register under the same id', clientSource.includes(
 check('that dependency is soft too', clientSource.includes('ctx.inject(["sidebarRightTabs", "slots"]') && !/const inject = [[]/.test('') && clientSource.indexOf('const inject = ["slots", "remote"]') !== -1)
 check('the body reads the session from either host', clientSource.includes('props?.sessionId ?? props?.scope?.sessionId'))
 check('the browser tab survives only as the last resort', clientSource.includes('neither sidebar'))
+// The viz panel bar shows which checkout a worktree graph belongs to.
+check('the viz panel names the worktree when the graph serves one', clientSource.includes('"worktree of " + wt') && clientSource.includes('status.worktreeOf'))
+
+console.log('\n--- the dot flickers blue while a graft tool runs ---')
+// The pulse rides the status poll, so it must bypass the five-second status
+// cache: a blink that waited out `cacheMs` would land after the call ended.
+const indexSource = await readFile(new URL('../src/index.js', import.meta.url), 'utf8')
+check('the status payload carries the pulse', /toolUse: pulses\.get\(root\)/.test(indexSource))
+check('on the cache-hit path too', (indexSource.match(/toolUse: pulses\.get\(root\)/g) ?? []).length === 2)
+check('the flicker style exists and sits on the dot', clientSource.includes('.gs-chip.gs-live .gs-dot{color:#8b5cf6}'))
+check('the client counts incoming pulses', clientSource.includes('toolUse?.count'))
+check('a fresh pulse blinks, on and off, not solid', /for \(const ms of \[0, 175, 350, 525, 700, 875, 1050, 1225, 1400, 1575, 1750, 1925\]\)/.test(clientSource))
+// Toggles alternate on/off, so an ODD number of marks ends ON — which shipped
+// once as a dot stuck purple after every blink. An even count ends off.
+const marks = clientSource.match(/for \(const ms of \[((?:\d+)(?:, \d+)*)\]\)/)?.[1]?.split(', ').map(Number) ?? []
+check('the blink ends off, back at the resting colour', marks.length > 0 && marks.length % 2 === 0, JSON.stringify(marks))
+check('polling speeds up while graft tools are active', clientSource.includes('settled && !recent ? 4000 : 2000'))
+check('a pulse keeps the fast poll for a tail, not just the blink', clientSource.includes('window.setTimeout(() => setRecent(false), 20000)'))
+check('the flicker timers are cleaned up on unmount', clientSource.includes('for (const t of flickTimers.current) window.clearTimeout(t)'))
+
+console.log('\n--- the chip label truncates, the popup builds ---')
+// A long workspace name must collapse to an ellipsis in the trailing-row
+// chip, not stretch the composer. The popup keeps the full path.
+check(
+  'the chip label carries its own ellipsis rule',
+  clientSource.includes('.gs-chip .gs-label{overflow:hidden;text-overflow:ellipsis'),
+)
+check('and the chip renders the label under that class', clientSource.includes('h("span", { className: "gs-label" }'))
+// The popup's Build button calls a `build` remote method — the same plain
+// offline `graft build` the bare /graft runs — with a busy state while it
+// is in flight, then a status re-read so the card shows the fresh graph.
+check('the client declares a build descriptor', clientSource.includes('descriptor("build", ["sessionId"])'))
+check('the host serves a build method', indexSource.includes('markRemoteMethod(GraftStatusRemote.prototype, \'build\')'))
+// The button rebuilds through the SAME sync-run.js the automatic hooks run —
+// never a bare `graft build`, which writes the graph but NOT stats.json, so
+// the pill kept reading the old `dirty` flag and never flipped to IN SYNC.
+// That shipped once as a press that changed nothing.
+check('the build goes through the shared rebuild engine', /build[\s\S]{0,600}autoSync\.rebuild\(root\)/.test(indexSource))
+check('a finished build drops the stale cache', /build[\s\S]*?cache\.delete\(root\)/.test(indexSource))
+check('the popup has a Build button', clientSource.includes('"Build"'))
+check('it disables while the build runs', clientSource.includes('disabled: building'))
+// The rebuild button sits IN the header row, right of the status pill — not
+// in a footer row of its own.
+check('no footer row survives the move', !clientSource.includes('gs-pop-buildrow'))
+check(
+  'one header group, rendered in both heads',
+  (clientSource.match(/headGroup\(h\(/g) ?? []).length === 2,
+  String((clientSource.match(/headGroup\(h\(/g) ?? []).length),
+)
+// Pill and Build travel as one group pinned right: a wrapper carries the
+// row's only auto margin, so the flex gap is the only thing between the
+// pair and nothing can split them — either apart or across the header.
+check('the header pills travel in one right-pinned group', clientSource.includes('.gs-pop-group{margin-left:auto'))
+check('the pill no longer spaces itself away from the button', !clientSource.includes('.gs-pill{margin-left:auto'))
+// The card itself is click-through (pointer-events:none), which was fine
+// while it was pure text — but any button inside it is dead unless it
+// re-enables events on itself. That shipped once as a button that could
+// never be pressed; this guard is the reason it will not ship again.
+check('the Build button re-enables pointer events on itself', clientSource.includes('.gs-build{') && /\.gs-build\{[^}]*pointer-events:auto/.test(clientSource))
+// The button holds Building… until OBSERVED freshness flips to synced, not
+// until the build promise lands: a build that exits while stats.json still
+// reads dirty (plain `graft build` never patches it) must not re-enable the
+// button against a pill that still says STALE. That shipped once as a press
+// that changed nothing; this guard is the reason it will not ship again.
+check('the button waits for observed sync, not the promise', clientSource.includes('waitForSynced'))
+check('with a bounded wait, not forever', clientSource.includes('SYNC_WAIT_MS'))
+check('the seat hands the waiter to the card', clientSource.includes('onSynced: waitForSynced'))
+check('a build that never reports sync re-enables with an error', clientSource.includes('did not report in sync'))
+
+console.log('\n--- Build in a workspace with no index confirms first ---')
+// The prompt is dsh's own themed Modal, not the browser's ugly box: the card
+// requires the primitives package permission-presets already proves a client
+// bundle can require. Guarded — if the package is ever absent the prompt
+// falls back to window.confirm, so the gate can never go missing silently.
+check('the card prefers dsh\'s own Modal', clientSource.includes('Primitives.Modal') && clientSource.includes('dsh-client-ui-primitives'))
+check('the Modal carries the confirm copy', clientSource.includes('Build graft index?'))
+check('its footer holds both accept and decline', clientSource.includes('Build index') && clientSource.includes('"Cancel"'))
+// Guarded require: if primitives is ever unresolvable the gate falls back to
+// the ugly box rather than going missing silently. The fallback is the ONLY
+// window.confirm in the file.
+check('only the fallback uses the browser box', (clientSource.match(/window\.confirm\(/g) ?? []).length === 1)
+// The modal accept must START the build while the modal is still open: it may
+// only close the modal after the build promise is underway. Closing first
+// (unmounting the card's modal subtree in the same tick) shipped once as an
+// accept that dismissed the dialog and built nothing.
+check('the accept starts the build while the modal is open', /startBuild[\s\S]{0,300}setConfirming\(false\)/.test(clientSource))
+check('the modal never closes before the build promise exists', !/setConfirming\(false\)[\s\S]{0,60}Promise\.resolve\(runBuild/.test(clientSource))
+// The confirm modal portals to document.body — OUTSIDE the card's wrap — so
+// the seat's capture-phase click-away closer would unmount the card (modal
+// included) before the accept's own click dispatches. That shipped once as an
+// accept that hid the dialog and built nothing; the closer must let modal
+// clicks through.
+check('the click-away closer lets modal clicks through', /closest\(['"]\[role="dialog"\]/.test(clientSource))
+check('the accept runs the plain offline initialise', /runGraft\(\['build', from\], from/.test(indexSource))
+check('a failed initialise reports graft\'s own message', /produced no index/.test(indexSource))
+check('a fresh initialise resolves as initialising', /initialising: true/.test(indexSource))
+
+// The remote descriptors must survive dsh 0.2's typert codec validation, which
+// runs inside `ctx.remote.$mount`: a strict codec needs a typeSymbol and a
+// `create()` factory returning a schema with `parse`. The 0.1 shape (`schema`
+// only) threw "strict codec has no create() factory", rejected apply(), and
+// took the whole plugin down. The client may only use strict codecs for
+// parameters. The descriptor block is lifted out of client.js and evaluated,
+// so this tests the shipped objects, not a copy.
+console.log('\nremote descriptors (dsh 0.2 codec contract)')
+const descriptorBlock = /function identity\(value\) \{[\s\S]*?\r?\n    const CONTRIBUTION = \{[\s\S]*?\r?\n    \};/.exec(clientSource)?.[0]
+check('descriptor block found in client.js', descriptorBlock !== undefined)
+const CONTRIBUTION = descriptorBlock ? new Function(`${descriptorBlock}; return CONTRIBUTION;`)() : { descriptors: [] }
+function codecProblem(codec, { parameter }) {
+  if (!codec || typeof codec !== 'object') return 'missing codec'
+  if (codec.mode === 'src-json') return parameter ? 'client parameters must be strict' : undefined
+  if (codec.mode !== 'strict') return `unknown mode ${codec.mode}`
+  if (typeof codec.typeSymbol !== 'string' || codec.typeSymbol === '') return 'empty typeSymbol'
+  if (typeof codec.create !== 'function') return 'strict codec has no create() factory'
+  const schema = codec.create()
+  if (typeof schema?.parse !== 'function') return 'create() returned no parse()'
+  if (codec.create() !== schema) return 'create() is not memoized'
+  // dsh 0.1 read `schema` directly; keep it so older hosts still load.
+  if (typeof codec.schema?.parse !== 'function') return 'no 0.1 schema fallback'
+  return undefined
+}
+check('declares the status, viz and build descriptors', CONTRIBUTION.descriptors.map((d) => d.method).join() === 'status,viz,build')
+for (const d of CONTRIBUTION.descriptors) {
+  for (const p of d.parameters) {
+    const problem = codecProblem(p.codec, { parameter: true })
+    check(`${d.id} parameter ${p.name} codec is valid`, problem === undefined, problem)
+  }
+  const problem = codecProblem(d.result, { parameter: false })
+  check(`${d.id} result codec is valid`, problem === undefined, problem)
+  const sample = { ok: true, value: { root: '/r', nodeCount: 1 } }
+  check(`${d.id} result decodes as a pass-through`, d.result.create().parse(sample) === sample)
+}
 
 await rm(fixture, { recursive: true, force: true })