dsh-thoughtdag 0.5.4 → 0.5.6

package/lib/index.js

@@ -293,7 +293,11 @@ function decompressZstdToText(raw) {
  *  `session.jsonl.zstd`, while session format V3 (0.1.5-rc.2 and later) uses
  *  `session.v3.jsonl.zstd`. Probe the known names, newest first, so a listing
  *  keeps working across both. */
-const SESSION_LOG_NAMES = ['session.v3.jsonl.zstd', 'session.jsonl.zstd']
+// `session.jsonl.zstd` (≤ 0.1.4), `session.v3.jsonl.zstd` (0.1.5), `session.v4.jsonl.zstd` (the 0.2
+// desktop) …: the session directory is listed and the highest version wins, so the next format
+// version is found before this file learns its name (the 0.2 desktop's own sessions were invisible
+// while only v3 was probed)
+const SESSION_LOG_RE = /^session(?:\.v(\d+))?\.jsonl\.zstd?$/
 async function findSessionFiles(dshHome) {
   const root = join(dshHome, 'sessions')
   const out = []
@@ -305,13 +309,13 @@ async function findSessionFiles(dshHome) {
     try { sessions = await readdir(join(root, ws.name), { withFileTypes: true }) } catch { continue }
     for (const s of sessions) {
       if (!s.isDirectory()) continue
-      let log
+      let names
+      try { names = await readdir(join(root, ws.name, s.name)) } catch { continue }
+      const best = names.map(n => ({ n, m: SESSION_LOG_RE.exec(n) })).filter(x => x.m !== null).sort((a, b) => Number(b.m[1] ?? 0) - Number(a.m[1] ?? 0))[0]
+      if (best === undefined) continue
+      const log = join(root, ws.name, s.name, best.n)
       let st
-      for (const name of SESSION_LOG_NAMES) {
-        const candidate = join(root, ws.name, s.name, name)
-        try { st = await stat(candidate); log = candidate; break } catch { /* try the next format */ }
-      }
-      if (log === undefined || st === undefined) continue
+      try { st = await stat(log) } catch { continue }
       out.push({ dir: ws.name, sessionDir: s.name, log, size: st.size, mtime: st.mtimeMs })
     }
   }
@@ -534,7 +538,7 @@ async function visionIdsOf(ctx, providerId, catalogModels) {
   return out
 }
 
-async function modelsPayload(ctx) {
+async function modelsPayload(ctx, ownProviders = []) {
   const cat = await ctx.sessionController.modelCatalog()
   // the harness itself, as an entry: the agent loop with tools, not a bare model
   // the harness's agent loop with tools, once per model it can run on —
@@ -549,15 +553,137 @@ async function modelsPayload(ctx) {
     }
   }
   models.push(...agents)
+  // the person's own interfaces follow, under their own names; a harness id wins a collision
+  const own = ownModelEntries(ownProviders, new Set(models.map(m => m.id)))
+  models.push(...own)
   const def = cat.default ? `${cat.default.provider}/${cat.default.model}` : null
   return {
     models,
     default: def && models.some(m => m.id === def) ? def : (models[0]?.id ?? null),
-    capabilities: { webSearch: false, searchEngine: 'none', scholarSearch: false, vision: models.some(m => m.vision) },
+    capabilities: { webSearch: ownProviders.some(p => isOpenRouterURL(p.baseURL)), searchEngine: 'none', scholarSearch: false, vision: models.some(m => m.vision) },
     harness: { routableProviders: cat.routableProviders ?? [], failures: (cat.failures ?? []).map(f => ({ provider: f.id, message: f.message })) },
   }
 }
 
+// ── the person's own interfaces ────────────────────────────────────────
+// The canvas keeps API interfaces in the browser (the same list the desktop
+// app has) and sends them along with every call and with a registration
+// at boot (POST /runtime-providers). Here they are spoken to directly over
+// the OpenAI-compatible protocol, so a key added inside the harness works
+// the way it does in the app; the harness's own models are untouched.
+const OWN_PROVIDER_CAP = 12
+const OWN_MODEL_CAP = 60
+const isOpenRouterURL = (u) => /openrouter\.ai/i.test(String(u ?? ''))
+
+/** The providers a request or a registration carries, sanitised. */
+function ownProvidersOf(list) {
+  const out = []
+  for (const p of (Array.isArray(list) ? list : []).slice(0, OWN_PROVIDER_CAP)) {
+    const baseURL = String(p?.baseURL ?? '').trim().replace(/\/+$/, '')
+    if (!/^https?:\/\//i.test(baseURL)) continue
+    const name = String(p?.name || 'Custom').slice(0, 40)
+    const models = (Array.isArray(p?.models) ? p.models : [])
+      .map(m => (typeof m === 'string' ? { id: m } : m))
+      .filter(m => m && typeof m.id === 'string' && m.id)
+      .slice(0, OWN_MODEL_CAP)
+      .map(m => ({ id: m.id, ...(typeof m.vision === 'boolean' ? { vision: m.vision } : {}) }))
+    if (models.length === 0) continue
+    out.push({ name, baseURL, apiKey: typeof p?.apiKey === 'string' ? p.apiKey : '', models })
+  }
+  return out
+}
+
+/** Model entries for the picker: the model's short id and its interface's name, like the app shows them. */
+function ownModelEntries(providers, taken) {
+  const entries = []
+  for (const p of providers) {
+    for (const m of p.models) {
+      if (taken.has(m.id)) continue
+      taken.add(m.id)
+      const shortId = m.id.includes('/') ? m.id.split('/').slice(1).join('/') : m.id
+      entries.push({ id: m.id, name: `${shortId} (${p.name})`, provider: p.name, vision: m.vision })
+    }
+  }
+  return entries
+}
+
+/** The interface a requested model belongs to, from the request's own list first, then the registered list. */
+function ownTargetOf(requested, fromBody, registered) {
+  if (typeof requested !== 'string' || !requested) return null
+  for (const p of [...fromBody, ...registered]) if (p.models.some(m => m.id === requested)) return { provider: p, model: requested }
+  return null
+}
+
+/** The canvas's { role, content } messages and images as OpenAI-compatible messages. */
+function ownMessagesOf(body) {
+  const messages = []
+  for (const m of Array.isArray(body?.messages) ? body.messages : []) {
+    if (!m || typeof m.content !== 'string') continue
+    messages.push({ role: m.role === 'system' ? 'system' : m.role === 'assistant' ? 'assistant' : 'user', content: m.content })
+  }
+  if (messages.length === 0) throw new HttpError(400, 'messages: nothing to send')
+  const images = Array.isArray(body?.images) ? body.images.filter(i => i && typeof i.data === 'string' && IMAGE_MEDIA.has(i.mimeType)) : []
+  if (images.length > 0) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role !== 'user') continue
+      messages[i] = { role: 'user', content: [{ type: 'text', text: messages[i].content }, ...images.map(img => ({ type: 'image_url', image_url: { url: `data:${img.mimeType};base64,${img.data}` } }))] }
+      break
+    }
+  }
+  return messages
+}
+
+/** One chat-completions request to the interface; the response as fetched (the caller reads it). */
+async function ownRequest(target, body, stream) {
+  const { provider, model } = target
+  // OpenRouter searches through its `:online` variant and takes a reasoning switch; a fast call never thinks out loud
+  const openrouter = isOpenRouterURL(provider.baseURL)
+  const id = openrouter && body?.webSearch && !model.endsWith(':online') ? `${model}:online` : model
+  const payload = { model: id, messages: ownMessagesOf(body), stream, ...(openrouter ? { reasoning: { enabled: !body?.fast } } : {}) }
+  const headers = { 'content-type': 'application/json', ...(provider.apiKey ? { authorization: `Bearer ${provider.apiKey}` } : {}), ...(openrouter ? { 'HTTP-Referer': 'https://github.com/chenxiachan/thoughtdag', 'X-Title': 'ThoughtDAG' } : {}) }
+  const res = await fetch(`${provider.baseURL}/chat/completions`, { method: 'POST', headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(10 * 60 * 1000) })
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    let detail = text.slice(0, 300)
+    try { const j = JSON.parse(text); detail = j?.error?.message ?? j?.message ?? detail } catch { /* not json */ }
+    throw new HttpError(res.status === 401 || res.status === 403 ? 401 : 502, `${provider.name}: HTTP ${res.status}${detail ? ' · ' + detail : ''}`)
+  }
+  return res
+}
+
+/** Stream one answer from the interface as the canvas's frames: { text }, { reasoning }, [DONE]. */
+async function ownStream(res, target, body, isClosed) {
+  const upstream = await ownRequest(target, body, true)
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const chunk of upstream.body) {
+    if (isClosed()) break
+    buffer += decoder.decode(chunk, { stream: true })
+    let nl
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim(); buffer = buffer.slice(nl + 1)
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]') return
+      let parsed
+      try { parsed = JSON.parse(data) } catch { continue }
+      if (parsed?.error) { res.write(`data: ${JSON.stringify({ error: parsed.error.message ?? String(parsed.error) })}\n\n`); return }
+      const delta = parsed?.choices?.[0]?.delta ?? {}
+      const reasoning = delta.reasoning_content ?? delta.reasoning
+      if (typeof reasoning === 'string' && reasoning) res.write(`data: ${JSON.stringify({ reasoning })}\n\n`)
+      if (typeof delta.content === 'string' && delta.content) res.write(`data: ${JSON.stringify({ text: delta.content })}\n\n`)
+    }
+  }
+}
+
+/** One whole answer from the interface (the canvas's background calls). */
+async function ownCall(target, body) {
+  const upstream = await ownRequest(target, body, false)
+  const j = await upstream.json()
+  const c = j?.choices?.[0]?.message?.content
+  return typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => (typeof x?.text === 'string' ? x.text : '')).join('') : ''
+}
+
 const IMAGE_MEDIA = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
 
 /** The SPA's { role, content } messages as harness Messages; system lines
@@ -834,7 +960,7 @@ async function visionModel(ctx) {
 
 /** Resolve the requested model against the catalog, falling back to its default. */
 async function targetOf(ctx, requested) {
-  const payload = await modelsPayload(ctx)
+  const payload = await modelsPayload(ctx)  // the harness's own; the person's interfaces are resolved before this is asked
   const id = requested && payload.models.some(m => m.id === requested) ? requested : payload.default
   const t = splitModelId(id)
   if (!t) throw new HttpError(503, 'no model is routable in this harness')
@@ -943,6 +1069,8 @@ export async function apply(ctx, config) {
     : '/thoughtdag'
   const trustedHosts = new Set(['localhost', '127.0.0.1', ...[...(config?.trustedHosts ?? [])].map(h => String(h).trim().toLowerCase()).filter(Boolean)])
 
+  // the interfaces the canvas registered (memory only: a restart forgets them, the canvas registers again at boot)
+  let registeredProviders = []
   const api = async (req, res) => {
     try {
       const hostname = (typeof req.headers.host === 'string' ? req.headers.host : '').replace(/:\d+$/, '').toLowerCase()
@@ -1010,6 +1138,7 @@ export async function apply(ctx, config) {
           const cwd = url.searchParams.get('cwd') ?? undefined
           return sendJson(res, 200, await whyLib.findJson(phrase, { scope, limit, ...(cwd ? { cwd } : {}) }))
         }
+        if (path === '/why/turns') return sendJson(res, 200, await whyLib.turnsJson({ offset: Number(url.searchParams.get('offset') ?? 0) || 0, ...(url.searchParams.get('limit') === null ? {} : { limit: Number(url.searchParams.get('limit')) || 0 }), head: Number(url.searchParams.get('head') ?? 300) || 300 }))
         if (path === '/why/recall') {
           try { return sendJson(res, 200, await whyLib.recallJson(url.searchParams.get('session') ?? '', Number(url.searchParams.get('turn') ?? 0))) }
           catch (e) { return sendJson(res, 404, { error: e instanceof Error ? e.message : String(e) }) }
@@ -1089,7 +1218,34 @@ export async function apply(ctx, config) {
         if (await agentsHttp().handle(req, res, path, body)) return
       }
       // ── model connection (the SPA's proxy protocol, on the harness's providers) ──
-      if (path === '/models' && req.method === 'GET') return sendJson(res, 200, await modelsPayload(ctx))
+      if (path === '/models' && req.method === 'GET') return sendJson(res, 200, await modelsPayload(ctx, registeredProviders))
+      // the canvas registers its browser-stored interfaces at boot (and after a change): the list answers with them in it
+      // the interface dialog asks an endpoint what it serves (the /models protocol standard), through this host
+      if (path === '/probe-models' && req.method === 'POST') {
+        const body = await readJson(req, MAX_WRITE_BODY_BYTES)
+        const baseURL = String(body?.baseURL ?? '').trim().replace(/\/+$/, '')
+        if (!/^https?:\/\//i.test(baseURL)) return sendJson(res, 400, { error: 'baseURL required' })
+        try {
+          const r = await fetch(`${baseURL}/models`, { headers: body?.apiKey ? { authorization: `Bearer ${body.apiKey}` } : {}, signal: AbortSignal.timeout(15000) })
+          if (!r.ok) return sendJson(res, r.status, { error: `endpoint answered HTTP ${r.status}` })
+          const j = await r.json()
+          const list = Array.isArray(j?.data) ? j.data : Array.isArray(j?.models) ? j.models : []
+          const models = list.map(m => ({
+            id: typeof (m?.id ?? m?.name) === 'string' ? (m.id ?? m.name).replace(/^models\//, '') : '',
+            ...(typeof m?.created === 'number' ? { created: m.created } : {}),
+            ...(Array.isArray(m?.architecture?.input_modalities) ? { vision: m.architecture.input_modalities.includes('image') } : {}),
+            ...(typeof m?.context_length === 'number' ? { contextLength: m.context_length } : {}),
+          })).filter(m => m.id)
+          return sendJson(res, 200, { models })
+        } catch (error) {
+          return sendJson(res, 502, { error: 'could not reach the endpoint: ' + (error instanceof Error ? error.message : String(error)) })
+        }
+      }
+      if (path === '/runtime-providers' && req.method === 'POST') {
+        const body = await readJson(req, MAX_CALL_BODY_BYTES)
+        registeredProviders = ownProvidersOf(body?.providers)
+        return sendJson(res, 200, await modelsPayload(ctx, registeredProviders))
+      }
       const approvalRoute = /^\/approvals\/([^/]+)$/.exec(path)
       if (approvalRoute !== null && req.method === 'POST') {
         const id = decodeURIComponent(approvalRoute[1])
@@ -1119,6 +1275,22 @@ export async function apply(ctx, config) {
           res.end()
           return
         }
+        // the person's own interface, when the model is one of theirs
+        const own = ownTargetOf(body?.model, ownProvidersOf(body?.providers), registeredProviders)
+        if (own) {
+          if (path === '/claude') return sendJson(res, 200, { text: await ownCall(own, body), model: own.model })
+          res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' })
+          let closed = false
+          req.on('close', () => { closed = true })
+          try {
+            await ownStream(res, own, body, () => closed)
+            if (!closed) res.write('data: [DONE]\n\n')
+          } catch (error) {
+            if (!closed) res.write(`data: ${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n\n`)
+          }
+          res.end()
+          return
+        }
         const target = await targetOf(ctx, body?.model)
         const options = await callOf(ctx, body, target)
         if (path === '/claude') {

package/lib/runtime/agents/README.md

@@ -3,7 +3,7 @@
 One file per runtime (CommonJS, `.cjs`, so it loads the same under any package type): `pi.cjs` over `pi --mode rpc`, `codex.cjs` over `codex app-server`, `claude.cjs` over `claude -p` with stream-json both ways. Each exports a factory returning the same surface:
 
 - `available()` → where the binary is, or null
-- `models()` → `{ installed, models: [{ provider, id, name, reasoning, vision, efforts, defaultEffort }], default }` — `efforts` are the effort levels the CLI accepts for that model, in its own words, read from the CLI (empty when it has none); `defaultEffort` its own default when it says
+- `models()` → `{ installed, models: [{ provider, id, name, reasoning, vision, efforts, defaultEffort }], default }`; when the CLI is nowhere, `{ installed: false, searched: [dirs] }` names every directory the lookup walked (see `where.cjs`: the process PATH, then the login shell's PATH, then the usual homes and Node version managers), and the next ask looks again — `efforts` are the effort levels the CLI accepts for that model, in its own words, read from the CLI (empty when it has none); `defaultEffort` its own default when it says
 - `run(request, onEvent)` → run id at once; events follow, tagged with it. The request names the runtime, an absolute `cwd`, one `prompt`, optional `images`, a `model` from that runtime's own list, a session to continue (`sessionPath`, plus `forkEntryId` to branch it), and optionally `effort`: one of the levels the runtime itself listed for that model, in its own words (Codex from `model/list`, Claude Code and Pi from their `--help`), which it passes on as is (`--effort`, the turn's `effort`, `set_thinking_level`). A word the runtime did not list is dropped: the CLI's own setting stands.
 - `abort(runId)`, `answer(runId, requestId, { confirmed } | { value } | { cancelled: true })`, `shutdown()`
 

package/lib/runtime/agents/claude.cjs

@@ -16,19 +16,13 @@ const { randomUUID } = require('node:crypto');
 const { snapshotDir, diffSnapshots } = require('./fs-diff.cjs');
 
 const fsp = fs.promises;
-const CANDIDATE_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), '.claude', 'local'), path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.bun', 'bin')];
+const { locate, childEnv: envWith } = require('./where.cjs');
+const EXTRA_HOMES = [path.join(os.homedir(), '.claude', 'local')];   // the CLI's own install location, on top of the usual ones
 
-async function executable(p) { try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; } }
-async function findClaude() {
-  const names = process.platform === 'win32' ? ['claude.cmd', 'claude.exe', 'claude'] : ['claude'];
-  const dirs = [...(process.env.PATH || '').split(path.delimiter), ...CANDIDATE_DIRS].filter(Boolean);
-  for (const d of dirs) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return p; }
-  return null;
-}
-function childEnv() {
-  const seen = new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean));
-  return { ...process.env, PATH: [...seen, ...CANDIDATE_DIRS.filter((d) => !seen.has(d))].join(path.delimiter) };
-}
+/** The claude binary and the directories walked to find it (see where.cjs). */
+let located = null;
+const findClaude = () => (located ??= locate('claude', EXTRA_HOMES));
+const childEnv = () => envWith(EXTRA_HOMES);
 
 /** Claude Code has no model list; its aliases resolve to the newest model
  *  of each family inside the CLI, so they never go stale. The CLI's own
@@ -114,14 +108,19 @@ function createClaudeRuntime({ log } = {}) {
   const say = log || (() => {});
   const runs = new Map();     // runId → state
   let binPromise = null;
-  const bin = () => { if (!binPromise) binPromise = findClaude(); return binPromise; };
+  const bin = () => {
+    if (!binPromise) binPromise = findClaude().then((r) => { if (!r.path) { located = null; binPromise = null; } return r.path; });
+    return binPromise;
+  };
+  /** Where the lookup walked, for the picker's "not found" note. */
+  const searched = async () => (await findClaude()).searched;
 
   return {
     available: () => bin(),
 
     async models() {
       const b = await bin();
-      if (!b) return { installed: false, models: [], default: null };
+      if (!b) return { installed: false, models: [], default: null, searched: await searched() };
       const [efforts, defaultEffort] = await Promise.all([effortsOf(b), configuredEffort()]);
       return { installed: true, models: MODELS.map((m) => ({ ...m, efforts, defaultEffort })), default: 'claude/claude-code/opus' };
     },

package/lib/runtime/agents/codex.cjs

@@ -17,19 +17,13 @@ const { snapshotDir, diffSnapshots } = require('./fs-diff.cjs');
 
 const fsp = fs.promises;
 const RESPONSE_MS = 30 * 1000;
-const CANDIDATE_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', path.join(os.homedir(), '.bun', 'bin'), path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.local', 'bin')];
+const { locate, childEnv: envWith } = require('./where.cjs');
+const EXTRA_HOMES = [path.join(os.homedir(), '.codex', 'bin')];
 
-async function executable(p) { try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; } }
-async function findCodex() {
-  const names = process.platform === 'win32' ? ['codex.cmd', 'codex.exe', 'codex'] : ['codex'];
-  const dirs = [...(process.env.PATH || '').split(path.delimiter), ...CANDIDATE_DIRS].filter(Boolean);
-  for (const d of dirs) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return p; }
-  return null;
-}
-function childEnv() {
-  const seen = new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean));
-  return { ...process.env, PATH: [...seen, ...CANDIDATE_DIRS.filter((d) => !seen.has(d))].join(path.delimiter) };
-}
+/** The codex binary and the directories walked to find it (see where.cjs). */
+let located = null;
+const findCodex = () => (located ??= locate('codex', EXTRA_HOMES));
+const childEnv = () => envWith(EXTRA_HOMES);
 
 /** The guard file the canvas writes per working directory, as Codex policy. */
 async function policyFor(cwd) {
@@ -58,7 +52,12 @@ function createCodexRuntime({ log } = {}) {
   const byThread = new Map(); // threadId → runId
   const serverAsks = new Map(); // question id → { rpcId, respond(answer) }
   let binPromise = null;
-  const bin = () => { if (!binPromise) binPromise = findCodex(); return binPromise; };
+  const bin = () => {
+    if (!binPromise) binPromise = findCodex().then((r) => { if (!r.path) { located = null; binPromise = null; } return r.path; });
+    return binPromise;
+  };
+  /** Where the lookup walked, for the picker's "not found" note. */
+  const searched = async () => (await findCodex()).searched;
 
   const write = (obj) => { try { proc.stdin.write(JSON.stringify(obj) + '\n'); return true; } catch { return false; } };
   const send = (method, params, timeoutMs = RESPONSE_MS) => new Promise((resolve, reject) => {
@@ -283,7 +282,7 @@ function createCodexRuntime({ log } = {}) {
 
     async models() {
       const b = await bin();
-      if (!b) return { installed: false, models: [], default: null };
+      if (!b) return { installed: false, models: [], default: null, searched: await searched() };
       await ensureServer();
       const r = await send('model/list', {});
       noteEfforts(r);

package/lib/runtime/agents/pi.cjs

@@ -23,32 +23,14 @@ const fsp = fs.promises;
 const GUARD = path.join(__dirname, 'pi-guard.mjs');
 const IDLE_MS = Number(process.env.TD_AGENT_IDLE_MS) || 10 * 60 * 1000; // a Pi process (session or catalog) retires after this long without a listener
 const RESPONSE_MS = 30 * 1000;
-const CANDIDATE_DIRS = [
-  '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin',
-  path.join(os.homedir(), '.bun', 'bin'), path.join(os.homedir(), '.npm-global', 'bin'),
-  path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), '.pi', 'bin'),
-];
+const { locate, childEnv: envWith } = require('./where.cjs');
+const EXTRA_HOMES = [path.join(os.homedir(), '.pi', 'bin')];   // pi's own home, on top of the usual ones (see where.cjs)
 
-async function executable(p) {
-  try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; }
-}
-
-/** The pi binary: PATH first (a terminal launch), then the usual homes
- *  (a Finder launch carries almost no PATH). */
-async function findPi() {
-  const names = process.platform === 'win32' ? ['pi.cmd', 'pi.exe', 'pi'] : ['pi'];
-  const dirs = [...(process.env.PATH || '').split(path.delimiter), ...CANDIDATE_DIRS].filter(Boolean);
-  for (const d of dirs) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return p; }
-  return null;
-}
-
-/** PATH for the child: the shell's plus the usual homes, so Pi's own bash
- *  tool finds git, node and friends even under a Finder launch. */
-function childEnv() {
-  const seen = new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean));
-  const extra = CANDIDATE_DIRS.filter((d) => !seen.has(d));
-  return { ...process.env, PATH: [...seen, ...extra].join(path.delimiter) };
-}
+/** The pi binary and the directories walked to find it (PATH, the login shell's PATH, the usual homes). */
+let located = null;
+const findPi = () => (located ??= locate('pi', EXTRA_HOMES));
+/** PATH for the child: the shell's plus the usual homes, so Pi's own bash tool finds git, node and friends even under a Finder launch. */
+const childEnv = () => envWith(EXTRA_HOMES);
 
 class PiProcess {
   constructor(bin, cwd, opts) {
@@ -191,7 +173,12 @@ function createPiRuntime({ log } = {}) {
   const runs = new Map();      // runId → { proc, abort() }
   let binPromise = null;
 
-  const bin = () => { if (!binPromise) binPromise = findPi(); return binPromise; };
+  const bin = () => {
+    if (!binPromise) binPromise = findPi().then((r) => { if (!r.path) { located = null; binPromise = null; } return r.path; });
+    return binPromise;
+  };
+  /** Where the lookup walked, for the picker's "not found" note. */
+  const searched = async () => (await findPi()).searched;
   // Pi's thinking levels in its own words, from its own `--help`
   // (`--thinking <level>  Set thinking level: off, minimal, …`); read once
   let levelsPromise = null;
@@ -228,7 +215,7 @@ function createPiRuntime({ log } = {}) {
      *  sessionless process in the home directory. */
     async models() {
       const b = await bin();
-      if (!b) return { installed: false, models: [], default: null };
+      if (!b) return { installed: false, models: [], default: null, searched: await searched() };
       const key = '\0catalog';
       let p = procs.get(key);
       if (!p || p.dead) { p = new PiProcess(b, os.homedir(), { log: say, noSession: true, onExit: (d) => { if (procs.get(key) === d) procs.delete(key); } }); procs.set(key, p); }

package/lib/runtime/agents/where.cjs

@@ -0,0 +1,99 @@
+// Where a CLI lives when the process that launched us had no PATH to speak of.
+//
+// An app opened from the Finder, the Dock or a Start menu inherits a bare PATH
+// (/usr/bin:/bin on macOS), while the person's CLIs sit wherever their Node
+// version manager put them (nvm, fnm, volta, pnpm, asdf, mise …). A lookup
+// therefore walks three lists in order: the process PATH, the PATH a login
+// shell would give a terminal (asked once, with a timeout), and the usual
+// homes, version managers included. Every lookup returns what it searched,
+// so the picker can say where it looked when a runtime is missing.
+'use strict';
+
+const { execFile } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const fsp = fs.promises;
+const home = os.homedir();
+const isWin = process.platform === 'win32';
+const LOGIN_SHELL_MS = 4000;
+
+/** The login shell's PATH (zsh, bash and fish read their rc files there). Asked once; empty on Windows or when the shell is silent. */
+let loginPathPromise = null;
+function loginPath() {
+  if (loginPathPromise) return loginPathPromise;
+  loginPathPromise = new Promise((resolve) => {
+    if (isWin) return resolve([]);
+    const shell = process.env.SHELL || '/bin/zsh';
+    const args = /fish$/.test(shell) ? ['-l', '-c', 'string join : $PATH'] : ['-ilc', 'printf "%s" "$PATH"'];
+    execFile(shell, args, { timeout: LOGIN_SHELL_MS, env: { ...process.env, TERM: 'dumb' }, maxBuffer: 1 << 16 }, (err, stdout) => {
+      if (err) return resolve([]);
+      // rc files may print greetings; PATH itself has no newline, so the last line is ours
+      const line = String(stdout || '').split('\n').map((s) => s.trim()).filter(Boolean).pop() || '';
+      resolve(line.split(path.delimiter).map((d) => d.trim()).filter(Boolean));
+    });
+  });
+  return loginPathPromise;
+}
+
+const numeric = (v) => String(v).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+const newestFirst = (a, b) => { const x = numeric(a), y = numeric(b); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return (y[i] || 0) - (x[i] || 0); return 0; };
+const versionsUnder = (dir, ...sub) => { try { return fs.readdirSync(dir).sort(newestFirst).map((v) => path.join(dir, v, ...sub)); } catch { return []; } };
+
+/** Where package managers and Node version managers put global binaries. Newest Node first, so a lookup lands on the version the person uses. */
+function managerDirs() {
+  const dirs = [];
+  dirs.push(...versionsUnder(path.join(process.env.NVM_DIR || path.join(home, '.nvm'), 'versions', 'node'), 'bin'));
+  for (const base of [process.env.FNM_DIR, path.join(home, '.fnm'), path.join(home, '.local', 'share', 'fnm'), path.join(home, 'Library', 'Application Support', 'fnm')].filter(Boolean)) {
+    dirs.push(path.join(base, 'aliases', 'default', 'bin'));
+    dirs.push(...versionsUnder(path.join(base, 'node-versions'), 'installation', 'bin'));
+  }
+  dirs.push(
+    path.join(home, '.volta', 'bin'), path.join(process.env.N_PREFIX || path.join(home, 'n'), 'bin'), path.join(home, '.nodenv', 'shims'),
+    path.join(home, '.asdf', 'shims'), path.join(home, '.local', 'share', 'mise', 'shims'), path.join(home, '.proto', 'shims'),
+    path.join(home, 'Library', 'pnpm'), path.join(home, '.local', 'share', 'pnpm'), path.join(home, '.yarn', 'bin'), path.join(home, '.config', 'yarn', 'global', 'node_modules', '.bin'),
+    path.join(home, '.deno', 'bin'), path.join(home, '.cargo', 'bin'), path.join(home, 'bin'),
+  );
+  if (isWin) {
+    const { APPDATA, LOCALAPPDATA, ProgramFiles } = process.env;
+    if (APPDATA) dirs.push(path.join(APPDATA, 'npm'));
+    if (LOCALAPPDATA) dirs.push(path.join(LOCALAPPDATA, 'pnpm'), path.join(LOCALAPPDATA, 'Volta', 'bin'), path.join(LOCALAPPDATA, 'Programs', 'nvm'));
+    if (ProgramFiles) dirs.push(path.join(ProgramFiles, 'nodejs'));
+  }
+  return dirs;
+}
+
+const COMMON_HOMES = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', path.join(home, '.bun', 'bin'), path.join(home, '.npm-global', 'bin'), path.join(home, '.local', 'bin')];
+
+/** Every directory a lookup walks, in order and without repeats. Sync when the login shell has not answered yet. */
+function dirsSync(extraHomes, login) {
+  const seen = new Set(); const out = [];
+  const add = (d) => { if (d && !seen.has(d)) { seen.add(d); out.push(d); } };
+  (process.env.PATH || '').split(path.delimiter).forEach(add);
+  login.forEach(add);
+  [...COMMON_HOMES, ...extraHomes, ...managerDirs()].forEach(add);
+  return out;
+}
+let loginSeen = [];
+async function searchDirs(extraHomes = []) {
+  loginSeen = await loginPath();
+  return dirsSync(extraHomes, loginSeen);
+}
+
+async function executable(p) { try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; } }
+
+/** The first executable called `name` (Windows tries .cmd and .exe too): `{ path, searched }`, path null when nowhere. */
+async function locate(name, extraHomes = []) {
+  const names = isWin ? [`${name}.cmd`, `${name}.exe`, name] : [name];
+  const searched = await searchDirs(extraHomes);
+  for (const d of searched) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return { path: p, searched }; }
+  return { path: null, searched };
+}
+
+/** The process environment with PATH widened the same way, so a CLI's own tools (git, node, bash) resolve under a Finder launch too. */
+function childEnv(extraHomes = []) {
+  return { ...process.env, PATH: dirsSync(extraHomes, loginSeen).join(path.delimiter) };
+}
+
+module.exports = { locate, childEnv, searchDirs, loginPath };