dsh-graft-plugin 0.3.4 → 0.3.5

package/README.md

@@ -42,13 +42,20 @@ cd ~/.dsh/profiles/web && node -e "const p=require('./package.json');
               p.dsh.profile.bundles.includes('dsh-graft-plugin'))"
 ```
 
-Every tool here shells out to the `graft` CLI, so it needs `@nanonets/graft` on PATH:
+Every tool here shells out to the `graft` CLI, so it needs `@nanonets/graft`. **From 0.3.5 the plugin installs it for you** the first time it is needed — the chip, the Build button, `graft viz` and the tools all trigger the same one-at-a-time install:
+
+1. `npm install -g @nanonets/graft@latest`, run with a real node (never the Electron app binary) and npm's own `npm-cli.js`, no shell.
+2. If the global prefix refuses (elevation, read-only prefix) or the install lands off PATH, it retries into a prefix the plugin owns: `<DSH_HOME>/graft-cli` (default `~/.dsh/graft-cli`). No elevation needed, survives plugin upgrades, one directory to delete for a clean uninstall. A graft you installed yourself always wins over it.
+
+While that runs the chip says so; press Build again once it finishes. A failed attempt is not retried on every poll — the Build button forces a retry.
+
+The `postinstall` runs the same installer for package managers that execute lifecycle scripts. pnpm 10+ blocks those by default (and ignores them for tarball installs even when approved), which is exactly why the install also lives in the host half: it runs regardless of package-manager policy. To do it by hand instead:
 
 ```sh
 npm install -g @nanonets/graft
 ```
 
-A `postinstall` does this for you **when your package manager runs lifecycle scripts** — under pnpm 10+ they are blocked by default, so treat the command above as the required step there, not a fallback. If your global npm prefix needs elevation, the postinstall says so and prints the one command to run by hand.
+Opt out with `autoInstall: false` on the plugin's row, or `DSH_GRAFT_NO_AUTOINSTALL=1` per machine; pin what gets installed with `graftVersion` (default `latest`).
 
 Then index a repo once:
 
@@ -76,7 +83,7 @@ The dialog switches to the **Installed** confirmation, and the plugin appears un
 
 ![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 dialog notes that installed plugins **do not update automatically yet** — to upgrade, uninstall and install again. The graft CLI is installed automatically on first use from 0.3.5.
 
 ### The sidebar tab
 
@@ -165,6 +172,8 @@ All optional, all on the plugin's row in your profile's `cordis.patch.yml`:
     command: false           # drop /graft
     promptSection: false     # stop telling the model to use graft
     autoBuild: false         # stop rebuilding after edits (the card's Build button still works)
+    autoInstall: false       # never install graft automatically; report the npm command instead
+    graftVersion: '0.16.0'   # pin what the auto-install requests (default 'latest')
 ```
 
 ## Requirements
@@ -178,7 +187,7 @@ All optional, all on the plugin's row in your profile's `cordis.patch.yml`:
 | `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`). A bun global install (`bun add -g @nanonets/graft`) is detected too, via `$BUN_INSTALL` or `~/.bun`.
+- the `graft` CLI — installed automatically on first use (see Install), or by hand with `npm install -g @nanonets/graft`. A bun global install (`bun add -g @nanonets/graft`) is detected too, via `$BUN_INSTALL` or `~/.bun`, as is the plugin's own `<DSH_HOME>/graft-cli` prefix.
 
 The client bundle requires only `react`, which is why it survives the dsh `0.1.5-rc.2` client-package removals that broke several neighbouring plugins.
 
@@ -211,7 +220,7 @@ registering "dsh-graft-plugin" via __ModuleLoader__.load
 
 **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`.
+**`/graft` says the graft CLI is not on PATH.** On 0.3.5+ the plugin installs it on first use; if that failed (offline machine, refused prefix) the message carries npm's own output and the hand command: `npm install -g @nanonets/graft`. On older versions the postinstall was blocked or skipped (see Install).
 
 ## Licence
 

package/README.zh-CN.md

@@ -42,13 +42,20 @@ cd ~/.dsh/profiles/web && node -e "const p=require('./package.json');
               p.dsh.profile.bundles.includes('dsh-graft-plugin'))"
 ```
 
-这里的每个工具都要调用 `graft` CLI，所以 PATH 上必须有 `@nanonets/graft`：
+这里的每个工具都要调用 `graft` CLI，所以需要 `@nanonets/graft`。**从 0.3.5 起插件会替你装好**：chip、Build 按钮、`graft viz` 和各个工具在第一次需要时触发同一次安装（同一时刻只跑一个）：
+
+1. `npm install -g @nanonets/graft@latest`，用真正的 node（绝不是 Electron 应用二进制）和 npm 自己的 `npm-cli.js` 执行，不经过 shell。
+2. 若全局前缀拒绝（提权、只读前缀）或装到了 PATH 之外，则重试到插件自有的前缀：`<DSH_HOME>/graft-cli`（默认 `~/.dsh/graft-cli`）。不需要提权，插件升级后仍在，卸载时删一个目录即可。你自己装的 graft 永远优先于它。
+
+安装期间 chip 会说明；装完后再按一次 Build。失败的尝试不会在每次轮询时重试——Build 按钮会强制重试。
+
+`postinstall` 对愿意运行生命周期脚本的包管理器执行同一个安装器。pnpm 10+ 默认拦截这些脚本（tarball 安装即使批准也照样忽略），这正是安装逻辑同时放在 host 半边的原因：它不受包管理器策略影响。想手动装也可以：
 
 ```sh
 npm install -g @nanonets/graft
 ```
 
-`postinstall` 会在**你的包管理器愿意运行生命周期脚本时**替你装好——pnpm 10+ 默认拦截它们，所以在 pnpm 下请把上面这条命令当作必需步骤，而不是后备。若全局 npm 前缀需要提权，postinstall 会说明并打印那条需要手动执行的命令。
+在插件行上设 `autoInstall: false`、或按机器设 `DSH_GRAFT_NO_AUTOINSTALL=1` 可关闭自动安装；用 `graftVersion` 固定安装版本（默认 `latest`）。
 
 然后给仓库建一次索引：
 
@@ -76,7 +83,7 @@ graft build
 
 ![Installed 确认页与安装详情](assets/dsh-desktop-app-install-2.png)
 
-> 对话框也提示：已安装的插件**目前不会自动更新**——升级请先卸载再重装。graft CLI 的要求（`npm install -g @nanonets/graft`）不变。
+> 对话框也提示：已安装的插件**目前不会自动更新**——升级请先卸载再重装。graft CLI 从 0.3.5 起在首次使用时自动安装。
 
 ### 侧边栏标签页
 
@@ -165,6 +172,8 @@ dsh plugin --profile web add dsh-better-sidebar
     command: false           # 去掉 /graft
     promptSection: false     # 不再告诉模型使用 graft
     autoBuild: false         # 不再在编辑后重建（卡片上的 Build 按钮仍然可用）
+    autoInstall: false       # 不自动安装 graft，改为提示 npm 命令
+    graftVersion: '0.16.0'   # 固定自动安装的版本（默认 'latest'）
 ```
 
 ## 系统要求
@@ -178,7 +187,7 @@ dsh plugin --profile web add dsh-better-sidebar
 | `0.2.0-rc.2` | 需要插件 `0.2.1`+——更早的发行版无法激活（见故障排查） |
 
 - Node 22+
-- PATH 上的 `graft` CLI（`npm install -g @nanonets/graft`）。bun 的全局安装（`bun add -g @nanonets/graft`）也能被识别，经由 `$BUN_INSTALL` 或 `~/.bun`。
+- `graft` CLI——首次使用时自动安装（见安装），或手动 `npm install -g @nanonets/graft`。bun 的全局安装（`bun add -g @nanonets/graft`）也能被识别，经由 `$BUN_INSTALL` 或 `~/.bun`；插件自有的 `<DSH_HOME>/graft-cli` 前缀同样被识别。
 
 客户端 bundle 只依赖 `react`——这就是它能在 dsh `0.1.5-rc.2` 移除一批客户端包、弄坏了好几个相邻插件的情况下存活的原因。
 
@@ -211,7 +220,7 @@ registering "dsh-graft-plugin" via __ModuleLoader__.load
 
 **在 dsh 0.2 上插件加载失败，报 `strict codec has no create() factory`，dsh 还提议移除它。** dsh 0.2 要求每个 strict remote codec 都带一个 `create()` schema 工厂；`0.2.1` 之前的插件发行版只有 0.1 的 `schema` 键。升级到 `0.2.1` 或更新版本——它两种都带，0.1 和 0.2 上都能加载。
 
-**`/graft` 说 graft CLI 不在 PATH 上。** postinstall 被拦截或被跳过了（见安装）：`npm install -g @nanonets/graft`。
+**`/graft` 说 graft CLI 不在 PATH 上。** 0.3.5+ 会在首次使用时自动安装；若失败（离线机器、前缀被拒），消息里带 npm 自己的输出和手动命令：`npm install -g @nanonets/graft`。旧版本则是 postinstall 被拦截或被跳过（见安装）。
 
 ## 许可证
 

package/cordis.patch.yml

@@ -19,6 +19,10 @@
 #   command: false         drop the /graft command
 #   promptSection: false   stop telling the model to prefer graft
 #   autoBuild: false       stop rebuilding the index after edits
+#   autoInstall: false     never install graft automatically; report the one
+#                          `npm install -g @nanonets/graft` command instead
+#                          (DSH_GRAFT_NO_AUTOINSTALL=1 does the same per machine)
+#   graftVersion: '0.16.0' pin what the auto-install requests; default 'latest'
 - insert:
     - id: graft-status
       name: 'dsh-graft-plugin'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-graft-plugin",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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.",
   "icon": "assets/icon.png",
   "type": "module",
@@ -11,12 +11,14 @@
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
     "./graft-tools": "./src/graft-tools.js",
+    "./ensure-graft": "./src/ensure-graft.js",
     "./auto-sync": "./src/auto-sync.js",
     "./command": "./src/command.js"
   },
   "files": [
     "src/index.js",
     "src/graft-tools.js",
+    "src/ensure-graft.js",
     "src/auto-sync.js",
     "src/command.js",
     "src/client.js",
@@ -25,6 +27,7 @@
     "scripts/test-harness.mjs",
     "scripts/test-tools.mjs",
     "scripts/test-autosync.mjs",
+    "scripts/test-ensure.mjs",
     "scripts/test-command.mjs",
     "scripts/test-guidance.mjs",
     "README.md",
@@ -33,7 +36,7 @@
     "assets/icon.png"
   ],
   "scripts": {
-    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs && node scripts/test-guidance.mjs",
+    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-ensure.mjs && node scripts/test-command.mjs && node scripts/test-guidance.mjs",
     "test:live": "node scripts/test-tools.mjs",
     "postinstall": "node scripts/postinstall.mjs"
   },

package/scripts/postinstall.mjs

@@ -1,109 +1,84 @@
-/**
- * Put the graft CLI on the machine, and say what is still left to do.
- *
- * WHY A POSTINSTALL AT ALL
- *
- * This plugin is a front end. Every tool it registers shells out to `graft`,
- * and the chip reads an index `graft build` writes — so a correct install of
- * the plugin with no `graft` on PATH is a plugin that can do nothing, and says
- * so only at the first tool call. Installing it here turns that into one
- * install step instead of two.
- *
- * WHY IT NEVER FAILS THE INSTALL
- *
- * A global npm install is exactly the kind of thing that is refused: no write
- * permission on the prefix, an offline machine, a locked-down CI image, or
- * `--ignore-scripts` (which skips this file entirely and is a perfectly
- * reasonable thing for a careful user to do). None of those mean the PLUGIN
- * failed to install, so none of them exit non-zero. They print the one command
- * to run by hand and get out of the way.
- *
- * Set DSH_GRAFT_SKIP_POSTINSTALL=1 to skip it outright.
- */
-
-import { spawn } from 'node:child_process'
-import { delimiter, join } from 'node:path'
-import { existsSync } from 'node:fs'
-
-/** The package behind the `graft` command. The GitHub home is trailhq/Graft. */
-const PACKAGE = '@nanonets/graft'
-
-const BOLD = ''
-const DIM = ''
-const OFF = ''
-
-const say = (line = '') => process.stdout.write(`${line}\n`)
-
-/** Is `graft` already reachable? Checked before installing, so a re-install is a no-op. */
-function graftOnPath(env = process.env, exists = existsSync) {
-  const path = String(env.PATH ?? env.Path ?? '')
-  for (const dir of path.split(delimiter)) {
-    if (dir === '') continue
-    for (const name of ['graft.cmd', 'graft.exe', 'graft']) {
-      if (exists(join(dir, name))) return true
-    }
-  }
-  return false
-}
-
-/** Run a command to completion. Resolves with the exit code; never rejects. */
-function run(command, args) {
-  return new Promise((resolve) => {
-    let child
-    try {
-      // `shell: true` on Windows, because npm is a `.cmd` shim that cannot be
-      // exec'd directly. No argument here contains a space, so the unquoted
-      // argv join that makes `shell: true` dangerous cannot bite.
-      child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32' })
-    } catch {
-      resolve(null)
-      return
-    }
-    child.on('error', () => resolve(null))
-    child.on('close', (code) => resolve(code))
-  })
-}
-
-async function main() {
-  if (process.env.DSH_GRAFT_SKIP_POSTINSTALL === '1') return
-
-  say()
-  say(`${BOLD}dsh-graft-plugin${OFF}`)
-
-  if (graftOnPath()) {
-    say(`  ${DIM}graft is already on PATH - nothing to install.${OFF}`)
-  } else {
-    say(`  installing the graft CLI (${PACKAGE}) globally...`)
-    const code = await run('npm', ['install', '-g', PACKAGE])
-    if (code === 0) {
-      say(`  ${BOLD}done.${OFF} graft is on PATH.`)
-    } else {
-      say()
-      say(`  ${BOLD}graft was not installed${OFF} (npm exited ${code === null ? 'without running' : code}).`)
-      say('  This plugin needs it. Install it by hand:')
-      say()
-      say(`      npm install -g ${PACKAGE}`)
-      say()
-      say('  On a machine where the global prefix needs elevation, run that in an')
-      say('  administrator shell, or point npm at a writable prefix first.')
-    }
-  }
-
-  say()
-  say(`  ${BOLD}Next:${OFF}`)
-  say('    1. Index a repo:   cd <your repo> && graft build')
-  say('    2. The sidebar tab for `graft viz` needs dsh-better-sidebar mounted.')
-  say('       It ships as a dependency of this plugin, so it is already downloaded,')
-  say('       but dsh only mounts what the profile lists:')
-  say()
-  say('           dsh plugin --profile web add dsh-better-sidebar')
-  say()
-  say('       Skip it if you do not want the tab - the chip, the tools, the')
-  say('       /graft command and the auto-rebuild all work without it.')
-  say()
-}
-
-main().catch(() => {
-  // A postinstall that throws fails the install of a plugin that is, itself,
-  // perfectly fine. Never do that.
-})
+/**
+ * Put the graft CLI on the machine, and say what is still left to do.
+ *
+ * WHY A POSTINSTALL AT ALL
+ *
+ * This plugin is a front end. Every tool it registers shells out to `graft`,
+ * and the chip reads an index `graft build` writes — so a correct install of
+ * the plugin with no `graft` on PATH is a plugin that can do nothing, and says
+ * so only at the first tool call. Installing it here turns that into one
+ * install step instead of two, for the package managers that run this file.
+ *
+ * WHY IT IS NOT THE ONLY INSTALL PATH
+ *
+ * pnpm — which is what dsh profiles and the marketplace use — refuses
+ * lifecycle scripts of dependencies unless the profile approves them, and
+ * ignores them for `file:` tarball deps even WITH the approval. Measured on
+ * pnpm 11.28.5: ERR_PNPM_IGNORED_BUILDS, plugin installed, graft absent. So the
+ * host half runs the same ensureGraft() on first need; this file is the
+ * install-time convenience for plain npm, not the guarantee.
+ *
+ * WHY IT NEVER FAILS THE INSTALL
+ *
+ * A global npm install is exactly the kind of thing that is refused: no write
+ * permission on the prefix, an offline machine, a locked-down CI image, or
+ * `--ignore-scripts` (which skips this file entirely and is a perfectly
+ * reasonable thing for a careful user to do). None of those mean the PLUGIN
+ * failed to install, so none of them exit non-zero. ensureGraft already falls
+ * back to a user-writable prefix; whatever is left prints the one command to
+ * run by hand and gets out of the way.
+ *
+ * Set DSH_GRAFT_SKIP_POSTINSTALL=1 to skip it outright.
+ */
+
+import { ensureGraft, GRAFT_PACKAGE } from '../src/ensure-graft.js'
+
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const OFF = '\x1b[0m'
+
+const say = (line = '') => process.stdout.write(`${line}\n`)
+
+async function main() {
+  if (process.env.DSH_GRAFT_SKIP_POSTINSTALL === '1') return
+
+  say()
+  say(`${BOLD}dsh-graft-plugin${OFF}`)
+
+  const result = await ensureGraft({
+    spec: process.env.DSH_GRAFT_VERSION || undefined,
+    log: (message) => say(`  ${message}`),
+  })
+
+  if (result.ok && result.already) {
+    say(`  ${DIM}graft is already installed - nothing to do.${OFF}`)
+  } else if (result.ok) {
+    say(`  ${BOLD}done.${OFF} graft is installed (${result.installed}).`)
+  } else {
+    say()
+    say(`  ${BOLD}graft was not installed.${OFF} This plugin needs it.`)
+    for (const line of String(result.reason ?? '').split('\n')) say(`  ${line}`)
+    say()
+    say('  On a machine where the global prefix needs elevation, run that in an')
+    say('  administrator shell, or point npm at a writable prefix first.')
+    say(`  (dsh itself will retry automatically on first use: ${GRAFT_PACKAGE}.)`)
+  }
+
+  say()
+  say(`  ${BOLD}Next:${OFF}`)
+  say('    1. Index a repo:   cd <your repo> && graft build')
+  say('    2. The sidebar tab for `graft viz` needs dsh-better-sidebar mounted.')
+  say('       It ships as a dependency of this plugin, so it is already downloaded,')
+  say('       but dsh only mounts what the profile lists:')
+  say()
+  say('           dsh plugin --profile web add dsh-better-sidebar')
+  say()
+  say('       Skip it if you do not want the tab - the chip, the tools, the')
+  say('       /graft command and the auto-rebuild all work without it.')
+  say()
+}
+
+main().catch(() => {
+  // A postinstall that throws fails the install of a plugin that is, itself,
+  // perfectly fine. Never do that.
+})

package/scripts/test-ensure.mjs

@@ -0,0 +1,143 @@
+/**
+ * ensure-graft: the install that postinstall cannot guarantee.
+ *
+ * Every case here runs against a fake filesystem and a fake spawn, so the
+ * suite never touches the network or the machine's real npm prefix. The two
+ * real-install smoke tests live outside the suite (they need a contained
+ * npm_config_prefix) and are run by hand before a release.
+ */
+
+import { delimiter, join } from 'node:path'
+import {
+  GRAFT_PACKAGE,
+  cachedGraftCommand,
+  ensureGraft,
+  managedPrefix,
+  npmInvocation,
+  resetEnsureGraftState,
+  resetGraftCommandCache,
+  resolveGraftCommand,
+} from '../src/ensure-graft.js'
+import { createAutoSync } from '../src/auto-sync.js'
+
+let failures = 0
+const check = (l, ok, extra = '') => { console.log((ok ? 'PASS  ' : 'FAIL  ') + l + (extra ? '  -> ' + extra : '')); if (!ok) failures += 1 }
+
+const NODE_EXE = process.platform === 'win32' ? 'node.exe' : 'node'
+const cliIn = (dir) => join(dir, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+const nodeIn = (dir) => join(dir, NODE_EXE)
+const npmIn = (dir) => join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')
+const HOME = { DSH_HOME: join('C:', 'dsh-home') }
+
+/** A fake machine: which files exist, and what each spawned npm run does. */
+function world({ pathDirs = [], nodeDirs = [], managed = false, plan = () => ({ code: 0 }) } = {}) {
+  const set = new Set()
+  for (const d of pathDirs) set.add(cliIn(d))
+  for (const d of nodeDirs) { set.add(nodeIn(d)); set.add(npmIn(d)) }
+  if (managed) set.add(cliIn(managedPrefix(HOME)))
+  const spawns = []
+  const env = { ...HOME, PATH: pathDirs.join(delimiter) }
+  const exists = (p) => set.has(p)
+  const spawn = (command, args) => {
+    const step = plan(command, args, spawns.length)
+    spawns.push({ command, args })
+    for (const p of step.add ?? []) set.add(p)
+    return {
+      stdout: { on() {} },
+      stderr: { on() {} },
+      kill() {},
+      on(ev, cb) { if (ev === 'close') setImmediate(() => cb(step.code)) },
+    }
+  }
+  return { env, exists, spawn, spawns, set }
+}
+
+const deps = (w, over = {}) => ({ env: w.env, exists: w.exists, spawn: w.spawn, execPath: join('C:', 'app', 'DeepSeek Harness.exe'), electron: true, ...over })
+
+console.log('--- nothing to do when graft is already there ---')
+resetEnsureGraftState()
+let w = world({ pathDirs: [join('C:', 'npm')] })
+let r = await ensureGraft(deps(w))
+check('an existing install is reported, not reinstalled', r.ok === true && r.already === true && w.spawns.length === 0, JSON.stringify(r))
+
+console.log('--- opt-outs keep the old report-the-command behaviour ---')
+for (const over of [{ autoInstall: false }, {}]) {
+  resetEnsureGraftState()
+  w = world()
+  if (over.autoInstall === undefined) w.env.DSH_GRAFT_NO_AUTOINSTALL = '1'
+  r = await ensureGraft(deps(w, over))
+  check('no install, and the manual command is in the reason', r.ok === false && w.spawns.length === 0 && r.reason.includes(`npm install -g ${GRAFT_PACKAGE}`), JSON.stringify(r).slice(0, 120))
+}
+
+console.log('--- global install, with a real node and npm-cli.js (no shell) ---')
+resetEnsureGraftState()
+const nodeDir = join('C:', 'node')
+w = world({ nodeDirs: [nodeDir], plan: (cmd, args) => (args.includes('-g') ? { code: 0, add: [cliIn(nodeDir)] } : { code: 1 }) })
+w.env.PATH = nodeDir
+r = await ensureGraft(deps(w))
+check('global success is reported as global', r.ok === true && r.installed === 'global', JSON.stringify(r))
+check('spawned node + npm-cli.js, not the npm shim', w.spawns[0].command === nodeIn(nodeDir) && w.spawns[0].args[0] === npmIn(nodeDir), JSON.stringify(w.spawns[0]))
+check('asked for the package at the default spec', w.spawns[0].args.includes('-g') && w.spawns[0].args.includes(`${GRAFT_PACKAGE}@latest`), JSON.stringify(w.spawns[0].args))
+check('one npm run, no fallback needed', w.spawns.length === 1, String(w.spawns.length))
+
+console.log('--- a refused global prefix falls back to the managed prefix ---')
+resetEnsureGraftState()
+w = world({ nodeDirs: [nodeDir], plan: (cmd, args) => (args.includes('-g') ? { code: 1 } : { code: 0, add: [cliIn(managedPrefix(HOME))] }) })
+r = await ensureGraft(deps(w))
+check('the fallback reports managed', r.ok === true && r.installed === 'managed', JSON.stringify(r))
+check('and installed with --prefix under the dsh home', w.spawns[1].args.includes('--prefix') && w.spawns[1].args.includes(managedPrefix(HOME)), JSON.stringify(w.spawns[1].args))
+check('the resolver now finds the managed cli', resolveGraftCommand(w.env, w.exists).prefix[0] === cliIn(managedPrefix(HOME)))
+
+console.log('--- total failure: cooldown, then force ---')
+resetEnsureGraftState()
+w = world({ nodeDirs: [nodeDir], plan: () => ({ code: 1 }) })
+r = await ensureGraft(deps(w))
+check('failure carries npm output and the manual command', r.ok === false && r.reason.includes('by hand'), JSON.stringify(r).slice(0, 100))
+const after = w.spawns.length
+r = await ensureGraft(deps(w))
+check('a second poll inside the cooldown does not hammer npm', r.ok === false && w.spawns.length === after, String(w.spawns.length))
+r = await ensureGraft(deps(w, { force: true }))
+check('a pressed Build (force) retries anyway', w.spawns.length > after, String(w.spawns.length))
+
+console.log('--- one install at a time ---')
+resetEnsureGraftState()
+w = world({ nodeDirs: [nodeDir], plan: () => ({ code: 1 }) })
+const p1 = ensureGraft(deps(w))
+const p2 = ensureGraft(deps(w))
+check('concurrent callers share one attempt', p1 === p2)
+await p1
+check('and npm ran once per target, not once per caller', w.spawns.length === 2, String(w.spawns.length))
+
+console.log('--- resolution order and interpreter choice ---')
+resetEnsureGraftState()
+const own = join('C:', 'own')
+w = world({ pathDirs: [own], nodeDirs: [nodeDir], managed: true })
+check('the user\'s own PATH install wins over the managed one', resolveGraftCommand(w.env, w.exists).prefix[0] === cliIn(own))
+w = world({ nodeDirs: [nodeDir], managed: true })
+w.env.PATH = nodeDir
+const managedHow = resolveGraftCommand(w.env, w.exists, join('C:', 'app', 'x.exe'), true)
+check('a managed install on an Electron host runs with a real node', managedHow.command === nodeIn(nodeDir) && managedHow.shell === false, managedHow.command)
+const npmHow = npmInvocation(w.env, w.exists, join('C:', 'app', 'x.exe'), true)
+check('npm likewise avoids the Electron binary', npmHow.command === nodeIn(nodeDir) && npmHow.prefix[0] === npmIn(nodeDir), npmHow.command)
+check('the command cache is droppable after an install', (resetGraftCommandCache(), typeof cachedGraftCommand === 'function'))
+
+console.log('--- auto-sync picks up a graft installed mid-session ---')
+let now = 1_000_000
+let spawned = []
+const state = { stats: { dirty: true }, readStats: () => state.stats, patchStats: (_d, p) => Object.assign(state.stats, p), acquireLock: () => true }
+let available = null
+const sync = createAutoSync({
+  get graft() { return available },
+  resolveCli: () => (available ? 'C:/late/cli.js' : undefined),
+  resolveCommand: () => ({ command: 'C:/late/node.exe' }),
+  now: () => now,
+  spawn: (...a) => { spawned.push(a); return { on() {}, unref() {} } },
+})
+check('unavailable before the install', (await sync.syncIfDirty('C:/x')) === 'graft-unavailable')
+available = { state, syncRun: 'C:/late/sync-run.js' }
+now += 60_000
+check('and rebuilds after it, without a restart', (await sync.syncIfDirty('C:/x')) === 'started')
+check('with the live-resolved interpreter', spawned.at(-1)?.[0] === 'C:/late/node.exe', String(spawned.at(-1)?.[0]))
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/src/auto-sync.js

@@ -93,6 +93,10 @@ async function loadGraftState(cliPath) {
 /**
  * @param deps.cliPath - graft's `dist/cli.js`, from which its `claude/` dir is found.
  * @param deps.nodePath - the interpreter to run it with; defaults to execPath.
+ * @param deps.resolveCli - optional live re-resolve of graft's cli.js, so a
+ *   graft installed mid-session is picked up without a restart.
+ * @param deps.resolveCommand - optional live `{ command }` for the sync-run
+ *   spawn; wins over nodePath when present.
  * @param deps.minIntervalMs - floor between rebuilds of the same repo.
  */
 export function createAutoSync(deps = {}) {
@@ -150,9 +154,15 @@ export function createAutoSync(deps = {}) {
 
   let loaded
   const graft = async () => {
-    if (loaded === undefined) {
+    // A null result is NOT cached: graft can be installed mid-session by
+    // ensureGraft (the first Build on a fresh machine), and a permanently
+    // cached "unavailable" would keep auto-sync dead for the rest of that
+    // session. Re-resolving is cheap — loadGraftState returns before any
+    // import when there is no cli to load.
+    if (loaded === undefined || loaded === null) {
+      const cliPath = typeof deps.resolveCli === 'function' ? deps.resolveCli() : deps.cliPath
       try {
-        loaded = deps.graft !== undefined ? await deps.graft : await loadGraftState(deps.cliPath)
+        loaded = deps.graft !== undefined ? await deps.graft : await loadGraftState(cliPath)
       } catch {
         loaded = null // any loader failure counts as "graft unavailable"
       }
@@ -286,7 +296,8 @@ export function createAutoSync(deps = {}) {
          * and `sync-run` clears `syncing` and releases the lock on its own way
          * out either way.
          */
-        const child = spawnFn(nodePath, [g.syncRun, root], {
+        const how = typeof deps.resolveCommand === 'function' ? deps.resolveCommand() : { command: nodePath }
+        const child = spawnFn(how.command, [g.syncRun, root], {
           stdio: 'ignore',
           windowsHide: true,
         })

package/src/ensure-graft.js

@@ -0,0 +1,290 @@
+/**
+ * Find graft, and install it when it is not there.
+ *
+ * WHY THIS IS NOT ONLY A POSTINSTALL
+ *
+ * scripts/postinstall.mjs has always run `npm install -g @nanonets/graft`, and
+ * for a marketplace user it never runs at all. Measured with the pnpm dsh
+ * ships (11.28.5), installing this plugin's tarball into a fresh profile:
+ *
+ *     [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: dsh-graft-plugin@file:…
+ *
+ * pnpm refuses lifecycle scripts of dependencies unless the profile approves
+ * them, and even WITH the approval entry (`allowBuilds: dsh-graft-plugin: true`)
+ * a `file:` tarball dependency — exactly how the marketplace installs — is
+ * still ignored. So the plugin lands, graft does not, and the first Build says
+ * "no graft". A global prefix that needs elevation is the second way the
+ * postinstall loses, on machines where it does run.
+ *
+ * The one trigger that always runs is this plugin's own code inside the dsh
+ * host. So the install lives here: on first need, once at a time, with a
+ * user-writable fallback for the machines where `-g` is refused. postinstall
+ * calls the same function, so npm users keep the install-time convenience and
+ * gain the same fallback.
+ *
+ * NO dsh IMPORTS IN THIS FILE, DELIBERATELY
+ *
+ * postinstall runs under plain npm/pnpm node, where `@deepseek-ai/dsh-tools`
+ * does not exist. Everything here is node builtins, so both callers can use it.
+ *
+ * @module graft-status/ensure-graft
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync } from 'node:fs'
+import { delimiter, dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** The package behind the `graft` command. */
+export const GRAFT_PACKAGE = '@nanonets/graft'
+
+/** What a fresh install asks for. Overridable per profile (`graftVersion`). */
+export const DEFAULT_SPEC = 'latest'
+
+/** An install downloads and builds tree-sitter grammars; give it room. */
+const INSTALL_TIMEOUT_MS = 240_000
+
+/** After a failed attempt, do not hammer npm on every chip poll. */
+const FAIL_COOLDOWN_MS = 60_000
+
+/** Cap on npm output kept for the failure message. */
+const MAX_LOG = 2_000
+
+const NODE_EXE = process.platform === 'win32' ? 'node.exe' : 'node'
+
+const noop = () => {}
+
+/**
+ * Where the fallback install lives: a prefix this plugin owns, under the dsh
+ * home. Never needs elevation, survives plugin upgrades, and is one directory
+ * to delete for a clean uninstall. A graft the user installed themselves always
+ * wins over it — see the scan order in resolveGraftCommand.
+ */
+export function managedPrefix(env = process.env) {
+  const home = env.DSH_HOME ?? join(env.HOME ?? env.USERPROFILE ?? homedir(), '.dsh')
+  return join(home, 'graft-cli')
+}
+
+/**
+ * Which binary to run a graft/npm script with.
+ *
+ * The npm shim's own rule is the first choice — `%dp0%\node.exe`, the node that
+ * was installed beside the shims — so this agrees with what typing `graft` in a
+ * terminal would do. Only an Electron host needs the PATH search after it,
+ * because `graft` and its node need not share a prefix. A Node host keeps using
+ * its own execPath, unchanged.
+ *
+ * WHY NOT JUST process.execPath
+ *
+ * execPath is Node only when the host is Node. The dsh DESKTOP app is Electron
+ * (`DeepSeek Harness.exe`) running with ELECTRON_RUN_AS_NODE=1, so execPath is
+ * that app binary: the script still starts, and the breakage happens one layer
+ * in, inside graft's own argument parsing. The child keeps
+ * `process.versions.electron`, and commander 15 picks its `electron` argv
+ * convention from exactly that (`if (process.versions?.electron) from =
+ * 'electron'`). That branch then keys on `process.defaultApp`, which is
+ * undefined when the JS arrived as a script path rather than an app directory,
+ * and slices argv from 1 instead of 2 — so the cli.js path lands where the
+ * subcommand should be:
+ *
+ *     error: unknown command '<...>\@nanonets\graft\dist\cli.js'
+ *
+ * which is what the Build button and all five query tools returned in the
+ * desktop app before 0.3.4. A real node avoids the Electron binary altogether.
+ */
+function interpreterFor(installDir, dirs, exists, execPath, electron) {
+  const beside = join(installDir, NODE_EXE)
+  if (exists(beside)) return beside
+  if (!electron) return execPath
+  for (const dir of dirs) {
+    const candidate = join(dir, NODE_EXE)
+    if (exists(candidate)) return candidate
+  }
+  // Nothing better to hand: execPath at least runs the script, and graft's own
+  // stderr says what happened — the same answer as before this existed.
+  return execPath
+}
+
+const pathDirs = (env) => String(env.PATH ?? env.Path ?? '').split(delimiter).filter((dir) => dir !== '')
+
+/**
+ * How to invoke graft without a shell.
+ *
+ * `graft` on Windows is a `.cmd` shim, so a naive spawn cannot exec it and the
+ * obvious fix — `shell: true` — is a trap: Node joins argv into one command
+ * line WITHOUT quoting, so the first argument containing a space is silently
+ * split. That broke every call at once, because both the queries
+ * (`"punch animation"`) and the repo path (`B:\...\Street Yeet`) contain
+ * spaces.
+ *
+ * The shim's own body is `node <dir>/node_modules/@nanonets/graft/dist/cli.js`,
+ * so finding that file and running it with a real node needs no shell at all,
+ * and argv is passed through exactly as written.
+ *
+ * Scan order: the user's own PATH install, then a bun global install (only the
+ * shim is on PATH there), then this plugin's managed prefix. The bare-name
+ * fallback keeps a differently-installed graft working; it is only reached
+ * when no entry point can be found.
+ */
+export function resolveGraftCommand(
+  env = process.env,
+  exists = existsSync,
+  execPath = process.execPath,
+  electron = process.versions?.electron !== undefined,
+) {
+  const dirs = pathDirs(env)
+  for (const dir of dirs) {
+    const cli = join(dir, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+    if (exists(cli)) return { command: interpreterFor(dir, dirs, exists, execPath, electron), prefix: [cli], shell: false }
+  }
+  const bunRoot = env.BUN_INSTALL ?? join(env.HOME ?? env.USERPROFILE ?? '.', '.bun')
+  if (typeof bunRoot === 'string' && bunRoot !== '') {
+    const bunInstall = join(bunRoot, 'install', 'global')
+    const bunCli = join(bunInstall, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+    if (exists(bunCli)) return { command: interpreterFor(bunInstall, dirs, exists, execPath, electron), prefix: [bunCli], shell: false }
+  }
+  const managed = managedPrefix(env)
+  const managedCli = join(managed, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+  if (exists(managedCli)) return { command: interpreterFor(managed, dirs, exists, execPath, electron), prefix: [managedCli], shell: false }
+  return { command: 'graft', prefix: [], shell: process.platform === 'win32' }
+}
+
+/**
+ * The resolved command, cached for the process — and DROPPED after a successful
+ * install, because the cache would otherwise keep answering "not installed"
+ * for the rest of the session that installed it.
+ */
+let cachedCommand
+export const cachedGraftCommand = () => (cachedCommand ??= resolveGraftCommand())
+export const resetGraftCommandCache = () => { cachedCommand = undefined }
+
+/**
+ * How to invoke npm without a shell: the npm-cli.js beside the node we would
+ * run graft with. Falls back to the `npm` shim (shell on Windows) when that
+ * file is not there — a node from nvm or a standalone build still ships npm
+ * next to itself in every layout we have seen.
+ */
+export function npmInvocation(env = process.env, exists = existsSync, execPath = process.execPath, electron = process.versions?.electron !== undefined) {
+  const dirs = pathDirs(env)
+  let node = execPath
+  if (electron) {
+    for (const dir of dirs) {
+      const candidate = join(dir, NODE_EXE)
+      if (exists(candidate)) { node = candidate; break }
+    }
+  }
+  const npmCli = join(dirname(node), 'node_modules', 'npm', 'bin', 'npm-cli.js')
+  if (exists(npmCli)) return { command: node, prefix: [npmCli], shell: false }
+  return { command: 'npm', prefix: [], shell: process.platform === 'win32' }
+}
+
+/** Run to completion, capturing both streams. Never rejects; code null = never ran. */
+function runCapture(how, args, deps) {
+  const spawnFn = deps.spawn ?? spawn
+  const timeoutMs = deps.timeoutMs ?? INSTALL_TIMEOUT_MS
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawnFn(how.command, [...how.prefix, ...args], {
+        shell: how.shell,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    } catch {
+      resolve({ code: null, text: '' })
+      return
+    }
+    let out = ''
+    let settled = false
+    const finish = (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ code, text: out.length > MAX_LOG ? out.slice(-MAX_LOG) : out })
+    }
+    const timer = setTimeout(() => { child.kill(); finish(null) }, timeoutMs)
+    child.stdout?.on('data', (c) => { out += c.toString() })
+    child.stderr?.on('data', (c) => { out += c.toString() })
+    child.on('error', () => finish(null))
+    child.on('close', (code) => finish(code))
+  })
+}
+
+const manualHint = (spec) =>
+  'graft is not installed, and automatic installation is turned off.\n' +
+  `Install it once:  npm install -g ${GRAFT_PACKAGE}@${spec}\n` +
+  'Then press Build again.'
+
+/** Single-flight + cooldown state. Resettable so tests start clean. */
+let inflight
+let lastFailAt = -Infinity
+let lastReason = ''
+export function resetEnsureGraftState() {
+  inflight = undefined
+  lastFailAt = -Infinity
+  lastReason = ''
+}
+
+/**
+ * Make graft reachable, installing it if needed.
+ *
+ * Returns { ok, already? , installed?: 'global'|'managed', reason? }. Never
+ * throws: every caller is a chip poll, a button or a fire-and-forget hook, and
+ * a rejection in any of those is fatal to dsh rather than informative.
+ *
+ * @param deps.autoInstall - false (or DSH_GRAFT_NO_AUTOINSTALL=1) keeps the old
+ *   behaviour: report the one command to run by hand.
+ * @param deps.spec - version spec to install; defaults to DEFAULT_SPEC.
+ * @param deps.force - skip the failure cooldown (the Build button).
+ */
+export function ensureGraft(deps = {}) {
+  const env = deps.env ?? process.env
+  const exists = deps.exists ?? existsSync
+  const execPath = deps.execPath ?? process.execPath
+  const electron = deps.electron ?? process.versions?.electron !== undefined
+  const now = deps.now ?? (() => Date.now())
+  const log = deps.log ?? noop
+  const spec = typeof deps.spec === 'string' && deps.spec !== '' ? deps.spec : DEFAULT_SPEC
+  const autoInstall = deps.autoInstall !== false && env.DSH_GRAFT_NO_AUTOINSTALL !== '1'
+
+  if (resolveGraftCommand(env, exists, execPath, electron).prefix[0] !== undefined) {
+    return Promise.resolve({ ok: true, already: true })
+  }
+  if (!autoInstall) return Promise.resolve({ ok: false, reason: manualHint(spec) })
+  if (inflight !== undefined) return inflight
+  if (!deps.force && now() - lastFailAt < FAIL_COOLDOWN_MS) {
+    return Promise.resolve({ ok: false, reason: lastReason })
+  }
+
+  const attempt = (async () => {
+    const npm = npmInvocation(env, exists, execPath, electron)
+    const target = `${GRAFT_PACKAGE}@${spec}`
+    log(`graft is not installed — installing ${target} globally…`)
+    const global = await runCapture(npm, ['install', '-g', target], deps)
+    if (global.code === 0 && resolveGraftCommand(env, exists, execPath, electron).prefix[0] !== undefined) {
+      resetGraftCommandCache()
+      log('graft installed globally.')
+      return { ok: true, installed: 'global' }
+    }
+    // `-g` refused (elevation, read-only prefix) or landed off PATH. A prefix
+    // under the dsh home needs neither, so the install still succeeds there.
+    log(`global install did not land (npm exit ${global.code}) — using a user-writable prefix…`)
+    const prefix = managedPrefix(env)
+    try { mkdirSync(prefix, { recursive: true }) } catch { /* runCapture reports the real error */ }
+    const local = await runCapture(npm, ['install', '--prefix', prefix, target], deps)
+    if (local.code === 0 && resolveGraftCommand(env, exists, execPath, electron).prefix[0] !== undefined) {
+      resetGraftCommandCache()
+      log(`graft installed into ${prefix}.`)
+      return { ok: true, installed: 'managed', root: prefix }
+    }
+    lastFailAt = now()
+    lastReason =
+      'graft could not be installed automatically.\n\n' +
+      `${global.text}\n${local.text}\n\n`.trim() +
+      `\n\nInstall it by hand:  npm install -g ${target}`
+    return { ok: false, reason: lastReason }
+  })()
+
+  inflight = attempt.finally(() => { inflight = undefined })
+  return inflight
+}

package/src/graft-tools.js

@@ -40,8 +40,12 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { delimiter, join } from 'node:path'
+import { cachedGraftCommand, ensureGraft } from './ensure-graft.js'
+
+// Resolution and installation live in ensure-graft.js, which postinstall can
+// also import (it runs under plain npm node, where dsh-tools does not exist).
+// Re-exported here because every existing caller imports it from this module.
+export { resolveGraftCommand } from './ensure-graft.js'
 
 /**
  * Ceiling for one graft call.
@@ -57,90 +61,6 @@ const TIMEOUT_MS = 60_000
 /** Cap on returned text, so one broad query cannot swamp the context. */
 const MAX_CHARS = 60_000
 
-/**
- * How to invoke graft without a shell.
- *
- * `graft` on Windows is a `.cmd` shim, so a naive spawn cannot exec it and the
- * obvious fix — `shell: true` — is a trap: Node joins argv into one command
- * line WITHOUT quoting, so the first argument containing a space is silently
- * split. That broke every call here at once, because both the queries
- * (`"punch animation"`) and the repo path (`B:\...\Street Yeet`) contain
- * spaces.
- *
- * The shim's own body is `node <dir>/node_modules/@nanonets/graft/dist/cli.js`,
- * so finding that file on PATH and running it with the current Node needs no
- * shell at all, and argv is passed through exactly as written.
- *
- * The bare-name fallback keeps a differently-installed graft working; it is
- * only reached when the entry point cannot be found.
- *
- * WHY THE INTERPRETER IS NOT ALWAYS `process.execPath`
- *
- * execPath is Node only when the host is Node. The dsh DESKTOP app is Electron
- * (`DeepSeek Harness.exe`) running with ELECTRON_RUN_AS_NODE=1, so execPath is
- * that app binary: the script still starts, and the breakage happens one layer
- * in, inside graft's own argument parsing. The child keeps
- * `process.versions.electron`, and commander 15 picks its `electron` argv
- * convention from exactly that (`if (process.versions?.electron) from =
- * 'electron'`). That branch then keys on `process.defaultApp`, which is
- * undefined when the JS arrived as a script path rather than an app directory,
- * and slices argv from 1 instead of 2 — so the cli.js path lands where the
- * subcommand should be:
- *
- *     error: unknown command '<...>\@nanonets\graft\dist\cli.js'
- *
- * which is what the Build button and all five query tools used to return in the
- * desktop app. A real node avoids the Electron binary altogether.
- */
-const NODE_EXE = process.platform === 'win32' ? 'node.exe' : 'node'
-
-/**
- * Which binary to run graft's cli.js with.
- *
- * The npm shim's own rule is the first choice — `%dp0%\node.exe`, the node that
- * was installed beside the shims — so this agrees with what typing `graft` in a
- * terminal would do. Only an Electron host needs the PATH search after it,
- * because `graft` and its node need not share a prefix. A Node host keeps using
- * its own execPath, unchanged from before.
- */
-function interpreterFor(installDir, dirs, exists, execPath, electron) {
-  const beside = join(installDir, NODE_EXE)
-  if (exists(beside)) return beside
-  if (!electron) return execPath
-  for (const dir of dirs) {
-    const candidate = join(dir, NODE_EXE)
-    if (exists(candidate)) return candidate
-  }
-  // Nothing better to hand: execPath at least runs the script, and graft's own
-  // stderr says what happened — the same answer as before this existed.
-  return execPath
-}
-
-export function resolveGraftCommand(
-  env = process.env,
-  exists = existsSync,
-  execPath = process.execPath,
-  electron = process.versions?.electron !== undefined,
-) {
-  const dirs = String(env.PATH ?? env.Path ?? '').split(delimiter).filter((dir) => dir !== '')
-  for (const dir of dirs) {
-    const cli = join(dir, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
-    if (exists(cli)) return { command: interpreterFor(dir, dirs, exists, execPath, electron), prefix: [cli], shell: false }
-  }
-  // A bun global install puts only the shim on PATH; the package lives under
-  // $BUN_INSTALL/install/global. Missing it left prefix empty, which auto-sync
-  // used to turn into a fatal dirname(undefined).
-  const bunRoot = env.BUN_INSTALL ?? join(env.HOME ?? env.USERPROFILE ?? '.', '.bun')
-  if (typeof bunRoot === 'string' && bunRoot !== '') {
-    const bunInstall = join(bunRoot, 'install', 'global')
-    const bunCli = join(bunInstall, 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
-    if (exists(bunCli)) return { command: interpreterFor(bunInstall, dirs, exists, execPath, electron), prefix: [bunCli], shell: false }
-  }
-  return { command: 'graft', prefix: [], shell: process.platform === 'win32' }
-}
-
-let cachedCommand
-
 /**
  * Run one graft subcommand and return its stdout.
  *
@@ -151,7 +71,7 @@ let cachedCommand
  */
 export function runGraft(args, cwd, deps = {}) {
   const spawnFn = deps.spawn ?? spawn
-  const how = deps.command ?? (cachedCommand ??= resolveGraftCommand())
+  const how = deps.command ?? cachedGraftCommand()
   return new Promise((resolve) => {
     let child
     try {
@@ -236,6 +156,16 @@ function graftTool(spec, deps) {
     },
     execute: async (args, exec) => {
       const root = repoFor(exec, deps.fallbackCwd)
+      // A machine with no graft at all used to answer "no index" here, which
+      // reads as "your repo is not indexed" when the truth is "the CLI is not
+      // installed". Install it first (once, in the background elsewhere) so
+      // the next call works; while that runs, say what is happening. Only when
+      // the caller wired ensure deps: the offline test suites construct these
+      // tools without them and must never reach the network.
+      if (deps.ensure !== undefined && cachedGraftCommand().prefix[0] === undefined) {
+        const ensured = await ensureGraft(deps.ensure)
+        if (!ensured.ok) return { text: ensured.reason }
+      }
       const found = await deps.findRoot(root)
       if (found === undefined) {
         return {

package/src/index.js

@@ -49,6 +49,7 @@ import { dirname, join, resolve } from 'node:path'
 import { createAutoSync } from './auto-sync.js'
 import { createGraftCommand } from './command.js'
 import { graftTools, resolveGraftCommand, runGraft } from './graft-tools.js'
+import { ensureGraft } from './ensure-graft.js'
 
 export const name = 'graft-status'
 
@@ -567,10 +568,28 @@ export function apply(ctx, config = {}) {
   const autoSync = createAutoSync({
     cliPath: graftCommand.prefix[0],
     nodePath: graftCommand.command,
+    // graft may not exist yet at boot (fresh machine): re-resolve per use so
+    // the install ensureGraft performs mid-session is picked up without a
+    // restart, for both the state helpers and the sync-run interpreter.
+    resolveCli: () => resolveGraftCommand().prefix[0],
+    resolveCommand: () => resolveGraftCommand(),
     minIntervalMs: config.autoBuildMinIntervalMs,
     writeTools: config.autoBuildTools,
   })
 
+  /**
+   * The auto-install, shared by the chip, the Build button, viz and the tools.
+   * `autoInstall: false` on the row (or DSH_GRAFT_NO_AUTOINSTALL=1) restores the
+   * old report-the-command behaviour; `graftVersion` pins what gets installed.
+   */
+  const ensureDeps = {
+    autoInstall: config.autoInstall !== false,
+    spec: typeof config.graftVersion === 'string' && config.graftVersion !== '' ? config.graftVersion : undefined,
+    // ctx.get, not ctx.logger: property access on an undeclared service throws
+    // in cordis, and this plugin deliberately declares no injects.
+    log: (message) => { try { ctx.get?.('logger')?.info?.(`[graft] ${message}`) } catch { /* logging must never break the chip */ } },
+  }
+
   const vizDeps = {
     alive: vizAlive,
     wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -600,6 +619,13 @@ export function apply(ctx, config = {}) {
   liveOps = {
     status: async (sessionId) => {
       const from = cwdFor(sessionId)
+      // No graft at all is a different answer from "no index in this repo":
+      // kick the install off once (single-flight inside ensureGraft) and let
+      // the next poll read the real status.
+      if (resolveGraftCommand().prefix[0] === undefined) {
+        void ensureGraft(ensureDeps)
+        return { ok: false, reason: 'graft is not installed yet — installing it in the background. Press Build again in a moment.', from }
+      }
       let root
       try {
         root = await findGraftRoot(from, io.exists, io.readText)
@@ -627,6 +653,8 @@ export function apply(ctx, config = {}) {
 
     viz: async (sessionId) => {
       const from = cwdFor(sessionId)
+      const ensured = await ensureGraft(ensureDeps)
+      if (!ensured.ok) return { ok: false, reason: ensured.reason, from }
       const root = await findGraftRoot(from, io.exists, io.readText)
       if (root === undefined) return { ok: false, reason: 'no graft index above ' + from, from }
 
@@ -664,6 +692,9 @@ export function apply(ctx, config = {}) {
 
     build: async (sessionId) => {
       const from = cwdFor(sessionId)
+      // A pressed Build is an explicit request: skip the failure cooldown.
+      const ensured = await ensureGraft({ ...ensureDeps, force: true })
+      if (!ensured.ok) return { ok: false, reason: ensured.reason, from }
       let root
       try {
         root = await findGraftRoot(from, io.exists, io.readText)
@@ -709,6 +740,7 @@ export function apply(ctx, config = {}) {
   if (config.tools !== false) {
     const toolDeps = {
       fallbackCwd: fallbackFrom,
+      ensure: ensureDeps,
       findRoot: (start) => findGraftRoot(start, io.exists, io.readText),
       noteUse: (root) => pulses.note(root),
       recordSavings: (root, saved) => {