@phenx-inc/ctlsurf 0.17.3 → 0.17.4

package/README.md

@@ -38,7 +38,7 @@ Node.js 18+. A ctlsurf account (free tier works).
 
 **Live work map.** Open **Work map** in the titlebar (Ctrl+Shift+M), choose **Clef-Flash · local** or **Rules · lightweight**, and turn the map on. One chronological thread combines stated choices, hypotheses, readable thinking, actions, and results. Choice cards show the selected excerpt and its stated reason; following actions remain underneath in the same thread. Collapsible groups keep the semantic topics while preserving event order when Clef updates their placement. Expanding a thinking card loads the complete readable source block on demand and highlights the selected choice and reason. Full source text stays out of live map snapshots. Scrolling up pauses following; **Follow latest** returns to the newest activity. Closing the pane hides it; its On/Off switch controls collection for all local tabs.
 
-Work map is currently limited to the **desktop app on Apple Silicon Macs with an available Metal GPU**. npm installation performs a lightweight hardware check, without downloading or loading a model. Desktop startup checks the hardware again and verifies that Electron can access the Apple GPU. The option stays disabled during detection and on unsupported machines, including when saved preferences previously enabled it. GPU detection never blocks installation or other app features. The terminal/headless version does not start map collection or inference. HTTP and Cloudflare providers are not enabled in this release.
+Work map is currently limited to the **desktop app on Apple Silicon Macs with an available Metal GPU**. npm installation performs a lightweight hardware check, without downloading or loading a model. The first desktop launch on a capable Mac offers to download the Clef-Flash model; it asks once, and the choice is remembered. Desktop startup checks the hardware again and verifies that Electron can access the Apple GPU. The option stays disabled during detection and on unsupported machines, including when saved preferences previously enabled it. GPU detection never blocks installation or other app features. The terminal/headless version does not start map collection or inference. HTTP and Cloudflare providers are not enabled in this release.
 
 Claude Code's readable `thinking` blocks and Codex's public reasoning summaries (response items, completed reasoning items, and legacy `agent_reasoning` events) feed the same pipeline. Candidate segments come from the complete readable block before the source preview is shortened; Clef selects the important choice and a supporting reason, rather than only a type label. Public agent updates can also state decisions and are labelled as updates. The recent stated reasoning informs placement of following actions. Encrypted, redacted, or omitted reasoning is never treated as readable thinking. The panel reports when summaries are unavailable, rather than inferring private decisions from tool output. Some models/sessions omit readable summaries entirely. [Claude thinking format](https://platform.claude.com/docs/en/build-with-claude/thinking), [Codex reasoning summaries](https://learn.chatgpt.com/docs/app-server).
 
@@ -46,13 +46,13 @@ Clef-Flash suggests branch placement and activity types. Titles come from transc
 
 The local engine uses one shared, offline Python/MLX worker on Apple Silicon. It processes at most two events per request, caps input at 2,048 tokens, limits the pending queue to 24 events per tab, applies MLX allocation/cache limits, and unloads after 60 seconds idle or when mapping is turned off. A watchdog unloads a process exceeding 16 GiB RSS. These are resource guards, not a guarantee against system-wide memory pressure. Requests that fail leave the transcript-based map available and surface an error with a Retry control.
 
-This checkout automatically reuses the local pilot's downloaded Clef-Flash runtime. On another Mac, install `uv` and prepare only Clef-Flash (approximately 11 GB of model weights):
+This checkout automatically reuses the local pilot's downloaded Clef-Flash runtime. On another Mac, install `uv` (`brew install uv`) and accept the first-launch prompt, or download at any time (approximately 10.7 GB of model weights plus a ~0.6 GB Python/MLX runtime, in `~/.ctlsurf/clef-flash`):
 
 ```sh
-python3 scripts/prepare-work-map.py
+ctlsurf workmap
 ```
 
-The script prints the Python executable and model folder for **Local model setup**. These paths can also be supplied with `CTLSURF_CLEF_PYTHON` and `CTLSURF_CLEF_MODEL` before launch. Selecting an engine or opening the pane does not download model files. Rules needs no model or Python installation.
+It shows download progress, then saves the paths and turns the map on. The runtime lives outside the npm package, so updating ctlsurf does not download it again. From a checkout, `python3 scripts/prepare-work-map.py` does the same download and prints the Python executable and model folder for **Local model setup**. These paths can also be supplied with `CTLSURF_CLEF_PYTHON` and `CTLSURF_CLEF_MODEL` before launch. Selecting an engine or opening the pane does not download model files. Rules needs no model or Python installation.
 
 Validation: `npm run test:workmap`, `npm run test:workmap:ui`. To also load the pilot's actual weights for one offline decision-extraction inference and unload check: `node scripts/test-work-map.cjs --real-clef`. Optional `--replay-claude /path/session.jsonl` and `--replay-codex /path/rollout.jsonl` replay local files and print only diagnostic counts, never transcript text.
 

package/bin/ctlsurf-worker.js

@@ -5,6 +5,7 @@
  *
  * Subcommands:
  *   ctlsurf setup      — configure MCP for all detected coding agents
+ *   ctlsurf workmap    — download the local Work map model (Apple Silicon)
  *   ctlsurf update     — update to latest version
  *   ctlsurf doctor     — check all dependencies
  *   ctlsurf version    — print version
@@ -14,7 +15,7 @@
  *   ctlsurf --desktop  — Electron GUI mode
  */
 
-const { execFileSync, execSync } = require('child_process')
+const { execFileSync, execSync, spawn } = require('child_process')
 const path = require('path')
 const fs = require('fs')
 const os = require('os')
@@ -23,6 +24,11 @@ const ROOT = path.resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const subcommand = args[0]
 
+const ui = require(path.join(ROOT, 'scripts', 'setup-ui.cjs'))
+const wm = require(path.join(ROOT, 'scripts', 'work-map-setup.cjs'))
+const { detectCapability } = require(path.join(ROOT, 'scripts', 'check-work-map-gpu.cjs'))
+const WORK_MAP_PLATFORM = process.platform === 'darwin' && process.arch === 'arm64'
+
 // ─── Colors ───────────────────────────────────────
 
 const G = '\x1b[32m'
@@ -123,6 +129,18 @@ if (subcommand === 'setup') {
   process.exit(0)
 }
 
+if (subcommand === 'workmap') {
+  process.stdout.write(ui.banner(getPkgVersion()))
+  const box = new ui.Steps('work map setup', ['Apple GPU check', 'Work map model']).start()
+  workMapSetup(box, 0, { explicit: true })
+    .finally(() => box.finish())
+    .then(ok => { console.log(''); process.exit(ok ? 0 : 1) }, (err) => {
+      console.error(`\n${Y}!${R} Work map setup failed: ${err.message}\n`)
+      process.exit(1)
+    })
+  return
+}
+
 if (subcommand === 'update') {
   console.log(`\n${B}  ctlsurf update${R}\n`)
 
@@ -202,6 +220,16 @@ if (subcommand === 'doctor') {
     console.log(`    ${D}Install: cd ${ROOT} && npm install${R}`)
   }
 
+  if (WORK_MAP_PLATFORM) {
+    const found = wm.findModel(normalizeSettings(readSettings(settingsPathForMode('desktop'))).workMap)
+    if (found) {
+      console.log(`  ${G}✓${R} Work map model ${D}(Clef-Flash · ${tildify(found.modelPath)})${R}`)
+    } else {
+      console.log(`  ${D}-${R} Work map model ${D}(optional, not installed)${R}`)
+      console.log(`    ${D}Install: ctlsurf workmap${R}`)
+    }
+  }
+
   // Build status
   const headlessBuilt = fs.existsSync(path.join(ROOT, 'out/headless/index.mjs'))
   const desktopBuilt = fs.existsSync(path.join(ROOT, 'out/main/index.js'))
@@ -235,15 +263,28 @@ function detectMode(argv) {
 }
 
 const mode = detectMode(args)
+// Read before checkApiKey records this version as seen.
+const state = launchState(mode)
+const setupWanted = mode === 'desktop' && desktopSetupWanted(state)
+
+if (process.stdout.isTTY && !args.includes('--skip-setup') && (setupWanted || state.versionChanged)) {
+  process.stdout.write(ui.banner(getPkgVersion()))
+}
 
 // Validate the ctlsurf API key before launching — on install/update or when
 // the stored key is missing/rejected. A check failure never blocks launch.
 checkApiKey(mode).catch(() => {}).then(() => launch(mode))
 
-function launch(launchMode) {
+async function launch(launchMode) {
   ensurePtyHelperExecutable()
-  if (launchMode === 'desktop') runDesktop()
-  else runTerminal()
+  if (launchMode === 'desktop') {
+    if (setupWanted) {
+      await desktopSetup(state).catch(err => console.error(`${Y}!${R} Setup step failed: ${err.message}`))
+    }
+    runDesktop()
+  } else {
+    runTerminal()
+  }
 }
 
 // node-pty runs spawn-helper from whichever native dir it loaded (build/Release,
@@ -272,24 +313,14 @@ function ensurePtyHelperExecutable() {
 function runDesktop() {
   let electronPath
   try {
+    // Bust require cache (electron's index.js reads path.txt at require time)
+    delete require.cache[require.resolve('electron')]
     electronPath = require('electron')
   } catch {
-    // Electron not installed (devDependency, or wiped by `npm update`).
-    // Auto-install silently so npm-installed users don't have to think about it.
-    if (!installElectron()) {
-      // Install failed — fall back to terminal mode
-      console.error(`\n${Y}!${R} Falling back to terminal mode.\n`)
-      runTerminal()
-      process.exit(0)
-    }
-    try {
-      // Bust require cache (electron's index.js reads path.txt at require time)
-      delete require.cache[require.resolve('electron')]
-      electronPath = require('electron')
-    } catch (err) {
-      console.error(`\n${Y}!${R} Electron resolution failed after install: ${err.message}\n`)
-      process.exit(1)
-    }
+    // desktopSetup already tried to install it and reported why it failed.
+    console.error(`\n${Y}!${R} Electron is unavailable — falling back to terminal mode.\n`)
+    runTerminal()
+    process.exit(0)
   }
 
   // Rebrand Electron.app → ctlsurf.app (idempotent; sentinel file inside
@@ -316,42 +347,210 @@ function runDesktop() {
   }
 }
 
-function installElectron() {
-  console.log(`\n${B}  ctlsurf${R}  ${D}— first-run setup${R}\n`)
-  console.log(`  ${D}Installing Electron (one-time, ~100 MB)...${R}`)
+// ─── First-run setup ──────────────────────────────
+
+function launchState(m) {
+  const s = normalizeSettings(readSettings(settingsPathForMode(m)))
+  return { firstRun: !s.lastVersion, versionChanged: s.lastVersion !== getPkgVersion() }
+}
+
+// Electron missing always needs setup. Otherwise show the box once per
+// install/update, or once on Apple Silicon until the Work map choice is made.
+function desktopSetupWanted(launch) {
+  if (!electronResolves()) return true
+  if (!process.stdout.isTTY || args.includes('--skip-setup')) return false
+  if (launch.versionChanged) return true
+  return WORK_MAP_PLATFORM && !normalizeSettings(readSettings(settingsPathForMode('desktop'))).workMapSetup
+}
+
+async function desktopSetup(launch) {
+  const title = launch.firstRun ? 'first-run setup' : launch.versionChanged ? `updated to v${getPkgVersion()}` : 'setup'
+  const box = new ui.Steps(title, ['node-pty native addon', 'Electron runtime', 'Apple GPU check', 'Work map model']).start()
   try {
-    execSync('npm install electron --no-save --silent', {
-      cwd: ROOT,
-      stdio: ['ignore', 'ignore', 'inherit']
-    })
-  } catch (err) {
-    console.error(`\n${Y}!${R} Electron install failed: ${err.message}`)
-    console.error(`  Try manually: cd ${ROOT} && npm install electron\n`)
-    return false
+    box.set(0, { state: 'run' })
+    try {
+      require(path.join(ROOT, 'node_modules', 'node-pty'))
+      box.set(0, { state: 'done' })
+    } catch {
+      box.set(0, { state: 'fail', note: 'failed to load', detail: 'terminal tabs need it — run: ctlsurf doctor' })
+    }
+    await electronStep(box, 1)
+    await workMapSetup(box, 2, { explicit: false })
+  } finally {
+    box.finish()
   }
+  console.log(`\n  ${D}launching ctlsurf…${R}\n`)
+}
 
-  // electron's postinstall can exit 0 with a half-extracted binary (its
-  // extract-zip stalls on Node >= 26), and npm won't re-run it for a package
-  // that's already present — so unzip it ourselves with the system tool.
+async function electronStep(box, i) {
   if (!electronResolves()) {
-    console.log(`  ${D}Electron binary incomplete — extracting with system unzip...${R}`)
+    // Electron not installed (devDependency, or wiped by `npm update`).
+    const started = Date.now()
+    box.set(i, { state: 'run', progress: null, note: '0s', detail: 'one-time download, ~100 MB' })
+    const tick = setInterval(() => box.set(i, { note: ui.formatDuration(Date.now() - started) }), 1000)
     try {
-      execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'extract-electron.js')], {
-        stdio: ['ignore', 'ignore', 'inherit']
-      })
+      await runQuiet('npm install electron --no-save --silent', [], { cwd: ROOT, shell: true })
+      // electron's postinstall can exit 0 with a half-extracted binary (its
+      // extract-zip stalls on Node >= 26), and npm won't re-run it for a package
+      // that's already present — so unzip it ourselves with the system tool.
+      if (!electronResolves()) {
+        box.set(i, { detail: 'binary incomplete — extracting with system unzip' })
+        await runQuiet(process.execPath, [path.join(ROOT, 'scripts', 'extract-electron.js')])
+      }
     } catch (err) {
-      console.error(`\n${Y}!${R} Electron extract failed: ${err.message}`)
-      console.error(`  Try manually: cd ${ROOT} && node scripts/extract-electron.js\n`)
-      return false
+      box.set(i, { state: 'fail', progress: undefined, note: 'install failed', detail: `${err.message} · try: cd ${ROOT} && npm install electron` })
+      return
+    } finally {
+      clearInterval(tick)
     }
     if (!electronResolves()) {
-      console.error(`\n${Y}!${R} Electron binary still missing after extract.\n`)
+      box.set(i, { state: 'fail', progress: undefined, note: 'binary missing', detail: `try: cd ${ROOT} && node scripts/extract-electron.js` })
+      return
+    }
+  }
+
+  // Rebrand Electron.app → ctlsurf.app now, quietly; runDesktop's call is then a no-op.
+  const quiet = process.env.CTLSURF_QUIET
+  process.env.CTLSURF_QUIET = '1'
+  try {
+    require(path.join(ROOT, 'scripts', 'rebrand-electron.js')).rebrand()
+  } catch { /* runDesktop retries and reports */ } finally {
+    if (quiet === undefined) delete process.env.CTLSURF_QUIET
+    else process.env.CTLSURF_QUIET = quiet
+  }
+  let version = ''
+  try { version = require(path.join(ROOT, 'node_modules', 'electron', 'package.json')).version } catch { /* unknown */ }
+  box.set(i, { state: 'done', progress: undefined, note: version, detail: '' })
+}
+
+// Fills the GPU row at i and the model row at i + 1. Resolves true when the model is ready.
+async function workMapSetup(box, i, { explicit }) {
+  const settingsPath = settingsPathForMode('desktop')
+  const update = (patch) => {
+    const s = normalizeSettings(readSettings(settingsPath))
+    writeSettings(settingsPath, { ...s, ...(typeof patch === 'function' ? patch(s) : patch) })
+  }
+  const adopt = (paths, enable) => update(s => ({
+    workMapSetup: 'ready',
+    workMap: { ...s.workMap, ...paths, ...(enable ? { enabled: true, engine: 'clef-flash' } : {}) },
+  }))
+  const later = 'install any time: ctlsurf workmap'
+  const step = i + 1
+
+  if (!WORK_MAP_PLATFORM) {
+    box.set(i, { state: 'skip', note: 'Apple Silicon Macs only' })
+    box.set(step, { state: 'skip', note: 'not available on this machine' })
+    return false
+  }
+  box.set(i, { state: 'run' })
+  const capability = await detectCapability({ desktop: true })
+  if (capability.state !== 'available') {
+    box.set(i, { state: 'skip', note: 'no Metal GPU', detail: capability.reason })
+    box.set(step, { state: 'skip', note: 'not available on this Mac' })
+    update({ workMapSetup: 'unavailable' })
+    return false
+  }
+  box.set(i, { state: 'done', label: `${capability.gpuName} · Metal` })
+
+  const settings = normalizeSettings(readSettings(settingsPath))
+  const found = wm.findModel(settings.workMap)
+  if (found) {
+    // Already on disk (survives npm updates). Turn the map on only if it was never configured.
+    const enable = explicit || !settings.workMap
+    adopt(found, enable)
+    const on = enable || !!settings.workMap?.enabled
+    box.set(step, { state: 'done', note: `Clef-Flash · ${on ? 'on' : 'ready'}` })
+    return true
+  }
+  if (!explicit && settings.workMapSetup === 'declined') {
+    box.set(step, { state: 'skip', note: 'skipped', detail: later })
+    return false
+  }
+  const uv = wm.findUv()
+  if (!uv) {
+    box.set(step, { state: 'warn', note: 'needs uv', detail: 'brew install uv, then: ctlsurf workmap' })
+    update({ workMapSetup: 'deferred' })
+    return false
+  }
+  const free = wm.freeBytes()
+  if (free !== null && free < wm.DISK_NEEDED) {
+    box.set(step, { state: 'warn', note: 'not enough disk', detail: `needs ~${ui.formatBytes(wm.DISK_NEEDED)} free, ${ui.formatBytes(free)} available` })
+    update({ workMapSetup: 'deferred' })
+    return false
+  }
+
+  if (!explicit) {
+    if (!process.stdin.isTTY || args.includes('--skip-setup')) {
+      box.set(step, { state: 'skip', note: 'not installed', detail: later })
+      update({ workMapSetup: 'deferred' })
+      return false
+    }
+    box.set(step, { state: 'ask', note: `Clef-Flash · ${ui.formatBytes(wm.MODEL_BYTES)}` })
+    const yes = await box.confirm([
+      `${B}Work map${R} draws a live map of your agent's choices and actions`,
+      `with Clef-Flash, a local model on your Mac's GPU. Nothing is uploaded.`,
+      `${D}~${ui.formatBytes(wm.MODEL_BYTES)} model + ~0.6 GB runtime → ${tildify(wm.DEFAULT_DIR)}`
+        + `${free !== null ? ` · ${ui.formatBytes(free)} free` : ''}${R}`,
+    ], 'Download it now?')
+    if (!yes) {
+      update({ workMapSetup: 'declined' })
+      box.set(step, { state: 'skip', note: 'skipped', detail: later })
       return false
     }
   }
 
-  console.log(`  ${G}✓${R} Electron installed.\n`)
-  return true
+  const phases = { env: 'Python 3.12 env', deps: 'MLX runtime', model: 'model weights' }
+  const gb = (n) => (n / 1e9).toFixed(1)
+  const samples = []
+  box.set(step, { state: 'run', progress: null, note: 'starting', detail: '' })
+  try {
+    const paths = await wm.prepareModel({
+      uv,
+      onPhase: (name) => box.set(step, { progress: name === 'model' ? 0 : null, note: phases[name] || name, detail: '' }),
+      onBytes: (bytes) => {
+        // Rate over the last ~5 s of samples
+        const now = Date.now()
+        samples.push([now, bytes])
+        while (samples.length > 2 && now - samples[0][0] > 5000) samples.shift()
+        const [t0, b0] = samples[0]
+        const rate = now > t0 ? (bytes - b0) / ((now - t0) / 1000) : 0
+        const left = rate > 0 ? ` · ~${ui.formatDuration((wm.MODEL_BYTES - bytes) / rate * 1000)} left` : ''
+        box.set(step, {
+          progress: bytes / wm.MODEL_BYTES,
+          note: `${gb(Math.min(bytes, wm.MODEL_BYTES))}/${gb(wm.MODEL_BYTES)} GB`,
+          detail: rate > 0 ? `${ui.formatBytes(rate)}/s${left}` : 'connecting…',
+        })
+      },
+    })
+    adopt(paths, true)
+    box.set(step, { state: 'done', progress: undefined, note: 'Clef-Flash · on', detail: '' })
+    return true
+  } catch (err) {
+    update({ workMapSetup: 'deferred' })
+    box.set(step, {
+      state: 'fail', progress: undefined, note: 'download failed',
+      detail: `${err.message.slice(0, 80)} · log: ${tildify(path.join(wm.DEFAULT_DIR, 'prepare.log'))}`,
+    })
+    return false
+  }
+}
+
+function runQuiet(command, argv = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, argv, { ...options, stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    child.stderr.on('data', (chunk) => { stderr = (stderr + chunk).slice(-2000) })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(stderr.trim().split('\n').pop() || `exit code ${code}`))
+    })
+  })
+}
+
+function tildify(p) {
+  const home = os.homedir()
+  return p.startsWith(home + path.sep) ? '~' + p.slice(home.length) : p
 }
 
 function electronResolves() {

package/out/headless/index.mjs

@@ -17381,7 +17381,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@phenx-inc/ctlsurf",
-      version: "0.17.3",
+      version: "0.17.4",
       description: "Agent-agnostic terminal and desktop app for ctlsurf \u2014 run Claude Code, Codex, or any coding agent with live session logging and remote control",
       main: "out/main/index.js",
       bin: {