@davait/aipictury 1.9.2

package/ext/usage.js

@@ -0,0 +1,77 @@
+'use strict'
+// What the agent has used, turn by turn, kept for 30 days in ~/.aipictury/usage.jsonl — for a
+// /usage like Claude Code's: today or this week, by tool, helper, MCP server and skill, and
+// what is worth knowing (prompts re-read in full, contexts near their limit).
+// No VS Code here: the tests give their own clock and folder.
+const fs = require('fs')
+const path = require('path')
+const { home } = require('./sessions')
+
+const DAY = 86_400_000
+const KEEP = 30 * DAY
+const file = () => path.join(home(), 'usage.jsonl')
+const READ_TPS = 1000          // prompt tokens a second this GPU reads uncached (measured)
+
+// Told of every turn recorded (the account's daily totals follow it).
+const listeners = new Set()
+function onRecord(fn) { listeners.add(fn); return { dispose: () => listeners.delete(fn) } }
+
+/** One turn: { conversation, model, context, read, output, genSeconds, tools: [names] }. */
+function record(entry, now = Date.now()) {
+  for (const fn of listeners) { try { fn(entry, now) } catch { /* its own problem */ } }
+  try {
+    fs.mkdirSync(home(), { recursive: true })
+    fs.appendFileSync(file(), `${JSON.stringify({ t: now, ...entry })}\n`)
+    // Older than 30 days goes, now and then (about one write in fifty).
+    if (Math.random() < 0.02) prune(now)
+  } catch { /* usage is a convenience, never a failure */ }
+}
+
+function read() {
+  try {
+    return fs.readFileSync(file(), 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+  } catch { return [] }
+}
+
+function prune(now = Date.now()) {
+  const kept = read().filter((r) => now - r.t < KEEP)
+  const tmp = `${file()}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, kept.map((r) => JSON.stringify(r)).join('\n') + (kept.length ? '\n' : ''))
+  fs.renameSync(tmp, file())
+}
+
+/** Since when: 'today' (midnight) or 'week' (seven days back). */
+function since(range, now = Date.now()) {
+  if (range === 'week') return now - 7 * DAY
+  const d = new Date(now)
+  d.setHours(0, 0, 0, 0)
+  return d.getTime()
+}
+
+/** The turns of a range, summed and broken down. */
+function summary(range = 'today', { now = Date.now(), records = read(), window = 131_072 } = {}) {
+  const rows = records.filter((r) => r.t >= since(range, now))
+  const count = (key) => {
+    const out = {}
+    for (const r of rows) for (const name of r[key] || []) out[name] = (out[name] || 0) + 1
+    return Object.entries(out).sort((a, b) => b[1] - a[1])
+  }
+  const tools = count('tools')
+  const mcp = {}
+  for (const [name, n] of tools) if (name.startsWith('mcp__')) { const server = name.split('__')[1]; mcp[server] = (mcp[server] || 0) + n }
+  const missed = rows.filter((r) => (r.read || 0) > 20_000)
+  const full = rows.filter((r) => (r.context || 0) > 0.8 * window)
+  return {
+    range, turns: rows.length, conversations: new Set(rows.map((r) => r.conversation)).size,
+    context: rows.reduce((n, r) => n + (r.context || 0), 0), read: rows.reduce((n, r) => n + (r.read || 0), 0),
+    output: rows.reduce((n, r) => n + (r.output || 0), 0), genSeconds: rows.reduce((n, r) => n + (r.genSeconds || 0), 0),
+    tools: tools.filter(([n]) => !n.startsWith('mcp__')), mcp: Object.entries(mcp).sort((a, b) => b[1] - a[1]),
+    skills: count('skills'), helpers: count('helpers'), models: count('models'),
+    flags: [
+      ...(missed.length ? [`${missed.length} turn(s) re-read more than 20k prompt tokens (about ${Math.round(missed.reduce((n, r) => n + r.read, 0) / READ_TPS)} s of reading): the prompt cache was missed — a model switch, an edited earlier message, or another conversation in between.`] : []),
+      ...(full.length ? [`${full.length} turn(s) used over 80% of the context window: /compact, or start a new conversation for a new task.`] : []),
+    ],
+  }
+}
+
+module.exports = { record, read, prune, summary, file, onRecord }

package/ext/voice.js

@@ -0,0 +1,135 @@
+'use strict'
+// Dictation in the editor. VS Code gives its webviews no microphone (getUserMedia is refused),
+// so the recording is made here, in the extension host, by SoX or ffmpeg — whichever is
+// installed — from the system's default microphone, and written by the server's Whisper
+// (POST /api/transcribe). The first recording makes the system ask for the microphone, for VS
+// Code. AIPICTURY_FAKE_AUDIO (tests) plays a file in real time instead of the microphone, so
+// everything else — starting, stopping, the file, the upload — is the real path.
+// No VS Code here.
+const { spawn, spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const MAX_SECONDS = 300
+const EXTRA_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin']   // VS Code started from the Dock has a short PATH
+
+function which(name, env = process.env, platform = process.platform) {
+  const exts = platform === 'win32' ? ['.exe', ''] : ['']
+  const dirs = [...String(env.PATH || '').split(path.delimiter), ...(platform === 'win32' ? [] : EXTRA_DIRS)].filter(Boolean)
+  for (const dir of dirs) for (const ext of exts) {
+    const p = path.join(dir, name + ext)
+    try { fs.accessSync(p, fs.constants.X_OK); return p } catch { /* not here */ }
+  }
+  return null
+}
+
+/** Windows' first microphone, as ffmpeg's dshow names it. */
+function dshowMic(ffmpeg) {
+  const out = spawnSync(ffmpeg, ['-hide_banner', '-list_devices', 'true', '-f', 'dshow', '-i', 'dummy'], { encoding: 'utf8', timeout: 10_000 })
+  const m = /"([^"]+)"\s*\(audio\)/.exec(`${out.stderr}${out.stdout}`)
+  return m ? m[1] : null
+}
+
+/** How to record here: { tool, command, args(out) }, or null with nothing to record with. */
+function recorder({ env = process.env, platform = process.platform } = {}) {
+  const ffmpeg = which('ffmpeg', env, platform)
+  const pcm = ['-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le']
+  if (env.AIPICTURY_FAKE_AUDIO && ffmpeg) {
+    return { tool: 'ffmpeg (a file, for tests)', command: ffmpeg, args: (out) => ['-hide_banner', '-loglevel', 'error', '-y', '-re', '-i', env.AIPICTURY_FAKE_AUDIO, ...pcm, out] }
+  }
+  // SoX records from the default input on every system.
+  const rec = which('rec', env, platform)
+  if (rec && platform !== 'win32') return { tool: 'SoX', command: rec, args: (out) => ['-q', '-c', '1', '-r', '16000', '-b', '16', out] }
+  if (!ffmpeg) return null
+  let input
+  if (platform === 'darwin') input = ['-f', 'avfoundation', '-i', ':default']
+  else if (platform === 'linux') input = which('pactl', env, platform) ? ['-f', 'pulse', '-i', 'default'] : ['-f', 'alsa', '-i', 'default']
+  else if (platform === 'win32') { const mic = dshowMic(ffmpeg); if (!mic) return null; input = ['-f', 'dshow', '-i', `audio=${mic}`] } else return null
+  return { tool: 'ffmpeg', command: ffmpeg, args: (out) => ['-hide_banner', '-loglevel', 'error', '-y', ...input, ...pcm, out] }
+}
+
+function missing(platform = process.platform) {
+  const how = platform === 'darwin' ? 'brew install sox (or ffmpeg)' : platform === 'win32' ? 'winget install ffmpeg' : 'install sox or ffmpeg with your package manager'
+  return `Dictation records with SoX or ffmpeg, and neither is installed here — ${how}, then try again.`
+}
+
+/** Bytes of sound in a WAV file (its "data" chunk; when the recorder could not write the
+ *  chunk's size, what follows it). */
+function soundBytes(file) {
+  let buf
+  try { buf = fs.readFileSync(file) } catch { return 0 }
+  const at = buf.indexOf('data', 12, 'latin1')
+  if (at < 0 || at + 8 > buf.length) return 0
+  const declared = buf.readUInt32LE(at + 4)
+  const rest = buf.length - (at + 8)
+  return declared > 0 && declared <= rest ? declared : rest
+}
+const MIN_SOUND = 16_000 * 2 / 4                              // a quarter of a second at 16 kHz, 16-bit mono
+
+/** One recording: start() it, then stop() (resolves to the file) or cancel(). */
+class Recording {
+  constructor(how = recorder()) {
+    if (!how) throw new Error(missing())
+    this.how = how
+    this.file = path.join(os.tmpdir(), `aipictury-dictation-${process.pid}-${Date.now().toString(36)}.wav`)
+    this.started = 0
+    this.child = null
+    this.error = ''
+  }
+
+  start() {
+    this.child = spawn(this.how.command, this.how.args(this.file), { stdio: ['pipe', 'ignore', 'pipe'] })
+    this.child.stderr.on('data', (d) => { this.error = `${this.error}${d}`.slice(-2000) })
+    this.exited = new Promise((resolve) => {
+      this.child.on('error', (e) => { this.error = e.message; resolve(-1) })
+      this.child.on('exit', (code) => resolve(code))
+    })
+    this.started = Date.now()
+    this.limit = setTimeout(() => this.finish(), MAX_SECONDS * 1000)
+    return this
+  }
+
+  get seconds() { return this.started ? Math.floor((Date.now() - this.started) / 1000) : 0 }
+
+  /** Ends the recording cleanly (ffmpeg: "q"; SoX: an interrupt — both then close the file). */
+  finish() {
+    clearTimeout(this.limit)
+    if (!this.child || this.child.exitCode !== null) return
+    if (/ffmpeg/.test(this.how.tool)) { try { this.child.stdin.write('q') } catch { this.child.kill('SIGINT') } } else this.child.kill('SIGINT')
+    setTimeout(() => { if (this.child.exitCode === null) this.child.kill('SIGKILL') }, 5000).unref()
+  }
+
+  /** Stops and resolves to the recording's file; throws when nothing was recorded. */
+  async stop() {
+    this.finish()
+    await this.exited
+    if (soundBytes(this.file) < MIN_SOUND) {
+      this.discard()
+      const said = this.error.trim().split('\n').pop()
+      throw new Error(/not authori[sz]ed|permission|denied/i.test(said)
+        ? 'The microphone is not allowed for VS Code — allow it in the system\'s privacy settings (Microphone).'
+        : `nothing was recorded${said ? `: ${said}` : ''}`)
+    }
+    return this.file
+  }
+
+  cancel() { this.finish(); this.exited?.then(() => this.discard()) }
+
+  discard() { try { fs.rmSync(this.file, { force: true }) } catch { /* gone */ } }
+}
+
+/** The server writes it: { text, language, duration, seconds }. The file is removed after. */
+async function transcribe(server, file, { language = '', signal } = {}) {
+  try {
+    const form = new FormData()
+    form.append('audio', new Blob([fs.readFileSync(file)], { type: 'audio/wav' }), 'dictation.wav')
+    if (language) form.append('language', language)
+    const response = await fetch(`${server}/api/transcribe`, { method: 'POST', body: form, signal })
+    const data = await response.json().catch(() => ({}))
+    if (!response.ok) throw new Error(data.detail || `the server answered ${response.status}${response.status === 404 ? ' — it is older than dictation; update it' : ''}`)
+    return data
+  } finally { fs.rmSync(file, { force: true }) }
+}
+
+module.exports = { recorder, Recording, transcribe, missing, which, soundBytes, MAX_SECONDS }

package/ext/workbench.js

@@ -0,0 +1,162 @@
+'use strict'
+// The agent in VS Code's own furniture: the status bar entry, where a new conversation opens,
+// locking the editor group a tab opens in, reopening a closed agent tab, the
+// vscode://aipictury.aipictury/open link, and a system notification when VS Code is not in front.
+const vscode = require('vscode')
+const { execFile } = require('child_process')
+const log = require('./log')
+
+const config = () => vscode.workspace.getConfiguration('aipictury')
+
+// ---- the status bar ----
+
+let item = null
+const LOOK = {
+  idle: { text: '$(sparkle) AIPictury', tip: 'Open the AIPictury agent' },
+  working: { text: '$(sync~spin) AIPictury', tip: 'The agent is working — click to open it' },
+  waiting: { text: '$(bell-dot) AIPictury', tip: 'The agent is waiting for you' },
+  finished: { text: '$(check) AIPictury', tip: 'The agent has finished' },
+}
+
+function statusBar() {
+  if (!item) {
+    item = vscode.window.createStatusBarItem('aipictury.status', vscode.StatusBarAlignment.Right, 100)
+    item.name = 'AIPictury'
+    item.command = 'aipictury.focusInput'
+    setState('idle')
+    item.show()
+  }
+  return item
+}
+
+/** What the agent is doing, in the status bar: idle, working, waiting (for you) or finished. */
+function setState(state) {
+  if (!item) return
+  const look = LOOK[state] || LOOK.idle
+  item.text = look.text
+  item.tooltip = look.tip
+  item.backgroundColor = state === 'waiting' ? new vscode.ThemeColor('statusBarItem.warningBackground') : undefined
+}
+
+// ---- where a conversation opens ----
+
+/** The side bar or a new tab, as `preferredLocation` says. Returns the panel. */
+async function openPreferred(registry) {
+  if (config().get('preferredLocation', 'sidebar') === 'panel') return openTab(registry)
+  await vscode.commands.executeCommand('aipictury.agent.focus')
+  return registry.sidebar
+}
+
+/** A new agent tab; when it made a new editor group, that group is locked (`lockEditorGroups`),
+ *  so files opened while the tab is focused go to another group. */
+async function openTab(registry) {
+  const before = vscode.window.tabGroups.all.length
+  const panel = registry.openTab()
+  if (config().get('lockEditorGroups', true) && vscode.window.tabGroups.all.length > before) {
+    try { await vscode.commands.executeCommand('workbench.action.lockEditorGroup') } catch (error) { log.warn('could not lock the editor group', error) }
+  }
+  return panel
+}
+
+// ---- reopening a closed agent tab ----
+
+const closed = []            // conversations of agent tabs closed, newest last
+let lastClosedWasAgent = false
+
+/** Called when an agent tab closes, with its conversation. */
+function tabClosed(id) {
+  if (id) { closed.push(id); if (closed.length > 20) closed.shift() }
+}
+
+/** Every tab closed anywhere: was the last one an agent tab? */
+function watchTabs() {
+  return vscode.window.tabGroups.onDidChangeTabs((event) => {
+    for (const tab of event.closed) {
+      const input = tab.input
+      lastClosedWasAgent = !!input && input instanceof vscode.TabInputWebview && /aipictury\.agentTab/.test(input.viewType)
+    }
+  })
+}
+
+/** Cmd/Ctrl+Shift+T: the agent tab closed last, or VS Code's own Reopen Closed Editor. */
+async function reopenClosed(registry) {
+  if (lastClosedWasAgent && closed.length) {
+    const id = closed.pop()
+    const panel = await openTab(registry)
+    await panel.open(id, { focus: false })
+    lastClosedWasAgent = false
+    return panel
+  }
+  await vscode.commands.executeCommand('workbench.action.reopenClosedEditor')
+  return null
+}
+
+// ---- vscode://aipictury.aipictury/open?prompt=…&session=… ----
+
+function uriHandler(registry) {
+  return {
+    async handleUri(uri) {
+      const params = new URLSearchParams(uri.query)
+      // The browser back from signing in to an MCP server.
+      if (uri.path === '/oauth') {
+        if (!require('./mcpAuth').handleCallback(uri.query)) vscode.window.showWarningMessage('That sign-in link is not one AIPictury is waiting for.')
+        return
+      }
+      // vscode://aipictury.aipictury/plugin?marketplace=owner/repo&install=name@market — asked first.
+      if (uri.path === '/plugin') {
+        const install = params.get('install')
+        const market = params.get('marketplace')
+        const yes = 'Install'
+        const ok = await vscode.window.showWarningMessage(`Install the plugin ${install || ''}${market ? ` from ${market}` : ''}?`,
+          { modal: true, detail: 'A plugin can add commands, helper agents, hooks (commands that run on this machine) and MCP servers.' }, yes)
+        if (ok !== yes) return
+        const plugins = require('./plugins')
+        try {
+          if (market && !Object.keys(plugins.marketplaces()).some((n) => install?.endsWith(`@${n}`))) await plugins.addMarketplace(market)
+          if (install) await plugins.install(install, { level: 'user' })
+          vscode.window.showInformationMessage(`Installed ${install}.`)
+          for (const p of registry.all()) p.postCommands?.()
+        } catch (error) { vscode.window.showErrorMessage(`Could not install it: ${error.message}`) }
+        return
+      }
+      if (uri.path !== '/open') {
+        vscode.window.showWarningMessage(`AIPictury does not handle ${uri.path}`)
+        return
+      }
+      const session = params.get('session')
+      const prompt = params.get('prompt')
+      if (session) {
+        const open = registry.all().find((p) => p.id === session && p.host)
+        if (open) { open.host.reveal?.(); if (open.kind === 'sidebar') await vscode.commands.executeCommand('aipictury.agent.focus'); if (prompt) open.post({ type: 'draft', text: prompt }); return }
+      }
+      const panel = await openPreferred(registry)
+      if (session && !(await panel.open(session, { focus: false }))) panel.say?.('that conversation is not in this workspace — a new one is open instead')
+      // The prompt is filled in, never sent: the user sends it.
+      if (prompt) setTimeout(() => panel.post({ type: 'draft', text: prompt }), 300)
+    },
+  }
+}
+
+// ---- telling the user, when VS Code is not in front ----
+
+/** A system notification — only when VS Code is not the focused window, and `notifications` is on. */
+function notify(title, body) {
+  if (!config().get('notifications', true) || vscode.window.state.focused) return false
+  const text = String(body || '').slice(0, 200)
+  try {
+    if (process.platform === 'darwin') {
+      const esc = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+      execFile('osascript', ['-e', `display notification "${esc(text)}" with title "${esc(title)}"`], { timeout: 5000 }, () => {})
+    } else if (process.platform === 'linux') {
+      execFile('notify-send', [title, text], { timeout: 5000 }, () => {})
+    } else {
+      vscode.window.showInformationMessage(`${title}: ${text}`)
+    }
+    return true
+  } catch (error) {
+    log.warn('notification failed', error)
+    return false
+  }
+}
+
+module.exports = { statusBar, setState, openPreferred, openTab, tabClosed, watchTabs, reopenClosed, uriHandler, notify }

package/ext/workflow.js

@@ -0,0 +1,51 @@
+'use strict'
+// A workflow's steps: checked, then put in the order their dependencies give (each after the
+// steps it names). Pure: the agent runs the steps as helpers, one at a time — one GPU.
+const MAX_STEPS = 12
+
+/** [{ name, prompt, after?, subagent_type? }] (or its JSON) → the steps in running order. Throws on a bad plan. */
+function plan(given) {
+  let steps = given
+  if (typeof steps === 'string') { try { steps = JSON.parse(steps) } catch { steps = null } }
+  if (!Array.isArray(steps) || !steps.length) throw new Error('a workflow needs steps: [{ name, prompt, after? }]')
+  if (steps.length > MAX_STEPS) throw new Error(`at most ${MAX_STEPS} steps — group the work`)
+  const byName = new Map()
+  for (const [i, s] of steps.entries()) {
+    const name = String(s?.name || `step ${i + 1}`).trim()
+    if (!String(s?.prompt || '').trim()) throw new Error(`step ${name} has no prompt`)
+    if (byName.has(name)) throw new Error(`two steps are called ${name}`)
+    const after = Array.isArray(s.after) ? s.after : s.after ? [s.after] : []
+    byName.set(name, { ...s, name, prompt: String(s.prompt).trim(), after: after.map((a) => String(a).trim()) })
+  }
+  for (const s of byName.values()) {
+    for (const a of s.after) if (!byName.has(a)) throw new Error(`${s.name} comes after ${a}, which is not a step`)
+  }
+  const order = []
+  const state = new Map()
+  const visit = (s) => {
+    if (state.get(s.name) === 'done') return
+    if (state.get(s.name) === 'visiting') throw new Error(`the steps wait for each other in a loop (at ${s.name})`)
+    state.set(s.name, 'visiting')
+    for (const a of s.after) visit(byName.get(a))
+    state.set(s.name, 'done')
+    order.push(s)
+  }
+  for (const s of byName.values()) visit(s)
+  return order
+}
+
+/** What a step's helper is told: the goal, its step, and what the steps it depends on found. */
+function stepPrompt(step, goal, results) {
+  const earlier = step.after.map((a) => `## ${a}\n${results.get(a)}`).join('\n\n')
+  return `${goal ? `The overall goal: ${goal}\n\n` : ''}Your step: ${step.prompt}`
+    + (earlier ? `\n\nWhat the steps before yours found:\n\n${earlier}` : '')
+}
+
+/** The one report: every step that ran, in order. */
+function combine(order, results, { goal, stopped = false } = {}) {
+  const ran = order.filter((s) => results.has(s.name))
+  return `Workflow${goal ? ` — ${goal}` : ''}: ${ran.length} of ${order.length} steps done${stopped ? ' (stopped)' : ''}.\n\n`
+    + ran.map((s) => `## ${s.name}\n${results.get(s.name)}`).join('\n\n')
+}
+
+module.exports = { plan, stepPrompt, combine, MAX_STEPS }

package/ext/worktree.js

@@ -0,0 +1,83 @@
+'use strict'
+// Working in a git worktree, as Claude Code's enter/exit worktree: a checkout of its own, on a
+// branch of its own, inside the workspace at .aipictury/worktrees/<name> — so the agent (or a
+// helper) can change things without touching the user's checkout. The folder is kept out of
+// the main checkout's git status through .git/info/exclude (nothing in the repository changes).
+// No VS Code here: tests run it on a real repository. Asynchronous: a checkout of a large
+// repository takes a while, and a synchronous one would freeze the window's extension host.
+const fs = require('fs')
+const path = require('path')
+const { execFile } = require('child_process')
+
+const DIR = path.join('.aipictury', 'worktrees')
+
+function git(args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, encoding: 'utf8', timeout: 60_000, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(new Error(String(stderr || error.message).trim().split('\n').pop(), { cause: error }))
+      else resolve(stdout.trim())
+    })
+  })
+}
+
+/** The repository's top folder, or an error saying there is none. */
+async function top(root) {
+  try { return await git(['rev-parse', '--show-toplevel'], root) } catch { throw new Error('this workspace is not a git repository: a worktree needs one') }
+}
+
+/** Keeps .aipictury/worktrees/ out of the main checkout's status, without touching .gitignore. */
+async function exclude(repo) {
+  const file = path.join((await git(['rev-parse', '--git-common-dir'], repo)).replace(/^(?!\/)/, `${repo}/`), 'info', 'exclude')
+  const line = '/.aipictury/worktrees/'
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+  if (!text.split('\n').includes(line)) {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}${line}\n`)
+  }
+}
+
+/** Creates a worktree on a new branch from HEAD. Returns { name, path, relative, branch, base }. */
+async function enter(root, name) {
+  const repo = await top(root)
+  const clean = String(name || `wt-${Date.now().toString(36)}`).trim().replace(/[^\w.-]+/g, '-').slice(0, 40)
+  if (!clean) throw new Error('a worktree needs a name')
+  const relative = path.join(DIR, clean)
+  const where = path.join(repo, relative)
+  if (fs.existsSync(where)) throw new Error(`a worktree called ${clean} already exists`)
+  const branch = `aipictury/${clean}`
+  const base = await git(['rev-parse', 'HEAD'], repo)
+  await exclude(repo)
+  await git(['worktree', 'add', '-q', '-b', branch, where, 'HEAD'], repo)
+  return { name: clean, path: where, relative, branch, base }
+}
+
+/** What the worktree has that its base has not: commits, and uncommitted changes. */
+async function changes(wt) {
+  const commits = Number(await git(['rev-list', '--count', `${wt.base}..HEAD`], wt.path)) || 0
+  const dirty = (await git(['status', '--porcelain'], wt.path)).split('\n').filter(Boolean)
+  return { commits, dirty }
+}
+
+/** Leaves a worktree: kept (its folder and branch stay), or removed — refused when it holds
+ *  work that would be lost, unless `discard` says so. */
+async function exit(root, wt, { action = 'keep', discard = false } = {}) {
+  const repo = await top(root)
+  const what = await changes(wt)
+  if (action === 'keep') return { kept: true, ...what, path: wt.path, branch: wt.branch }
+  if ((what.commits || what.dirty.length) && !discard) {
+    throw new Error(`${wt.name} has ${what.commits} commit(s) and ${what.dirty.length} uncommitted change(s): keep it, or remove it with discard_changes: true`)
+  }
+  await git(['worktree', 'remove', '--force', wt.path], repo)
+  try { await git(['branch', '-D', wt.branch], repo) } catch { /* already gone */ }
+  return { kept: false, ...what }
+}
+
+/** A path from the model, while working in a worktree: relative to the worktree. */
+function inside(wt, given) {
+  const p = String(given ?? '.').trim() || '.'
+  if (!wt) return p
+  if (p === wt.relative || p.startsWith(`${wt.relative}/`) || path.isAbsolute(p)) return p
+  return path.join(wt.relative, p)
+}
+
+module.exports = { enter, exit, changes, inside, DIR }