kira-glasses-bridge 2.14.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.14.0",
+  "version": "2.19.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "start": "node src/cli.mjs run"
+    "start": "node src/cli.mjs run",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",

package/src/agents/answers.mjs

@@ -0,0 +1,43 @@
+// Questions a running job asks a person (an approval, a question for them), waiting for the first
+// answer from any device, keyed `${jobId}:${requestId}`. A wait ends at its answer, after three
+// minutes, or when the job is stopped.
+const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
+const waits = new Map()
+
+/** Wait for the answer to one of a job's requests. */
+export function awaitAnswer(jobId, request, signal) {
+  return new Promise((resolve, reject) => {
+    const key = `${jobId}:${request.id}`
+    const end = () => {
+      clearTimeout(timer)
+      waits.delete(key)
+    }
+    const timer = setTimeout(() => {
+      end()
+      reject(new Error('No answer within 3 minutes'))
+    }, ANSWER_TIMEOUT_MS)
+    timer.unref?.()
+    waits.set(key, answered => {
+      end()
+      resolve(answered)
+    })
+    const stopped = () => {
+      end()
+      reject(new Error('The job was stopped'))
+    }
+    signal?.addEventListener('abort', stopped, { once: true })
+  })
+}
+
+/** An answer arrived: true if a request was waiting for it. */
+export function answer(jobId, requestId, answered) {
+  const resolve = waits.get(`${jobId}:${requestId}`)
+  if (!resolve) return false
+  resolve(answered)
+  return true
+}
+
+/** A job ended: whatever it was still asking is dropped. */
+export function forgetJob(jobId) {
+  for (const key of [...waits.keys()]) if (key.startsWith(`${jobId}:`)) waits.delete(key)
+}

package/src/agents/claude.mjs

@@ -5,6 +5,7 @@ import { homedir } from 'node:os'
 import { relative, resolve, sep } from 'node:path'
 import { PERMISSION_OPTIONS, PLAN_OPTIONS, requestId } from './protocol.mjs'
 import { decide, ruleFor } from './policy.mjs'
+import { policyFor, sdkOptionsFor } from './settings.mjs'
 
 const TEXT_CAP = 4000
 const DIFF_CAP = 6000
@@ -23,6 +24,9 @@ const inside = (cwd, p) => {
   return !!rel && !rel.startsWith('..') && !rel.startsWith(sep)
 }
 
+/** Kira's MCP server as Claude Code connects to it: Streamable HTTP, the token as the bearer. */
+const kiraServer = ({ url, token }) => ({ type: 'http', url, headers: { Authorization: `Bearer ${token}` } })
+
 /** Claude's tool call as a protocol action. */
 export function describeAction(name, input, cwd) {
   const i = input ?? {}
@@ -133,12 +137,14 @@ function applyAnswer(name, input, request, answer, suggestions) {
 /** "Always allow" answers, kept for the rest of the process per session: sessionId -> Set of rules. */
 const sessionRules = new Map()
 
-export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io) {
+export async function run({ prompt, sessionId, cwd, policy, persona, settings, abort }, io) {
   let session = sessionId ?? null
   let text = ''
   let error = null
   const rulesFor = () => (session && sessionRules.get(session)) || new Set()
-  const judge = (toolName, input) => decide(policy, toolName, input ?? {}, cwd, rulesFor())
+  // The composer's mode: "Ask" makes the policy ask for edits and commands (settings.mjs).
+  const ruled = policyFor(policy, settings)
+  const judge = (toolName, input) => decide(ruled, toolName, input ?? {}, cwd, rulesFor())
 
   // Pre-tool hook: the policy is authoritative. It forces the prompt for what
   // it does not allow (so a permissive local config cannot bypass the person)
@@ -191,38 +197,62 @@ export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io
     return applyAnswer(toolName, input, request, resolved.answer, suggestions)
   }
 
+  // Background work (subagents, `run_in_background` shell commands, monitors)
+  // started by the model would outlive the turn: this is a one-shot run, so the
+  // moment the main thread stops the result is released, the process ends and
+  // that work is killed, never having reported. Claude's parting words ("the
+  // agents are still running; I'll compile the report when they finish") then
+  // became the job's final report, and Kira told the user it was still going.
+  // With this set, the tool has no background option: subagents run inline and
+  // their findings are in the answer.
+  // Kira has its own Gmail/Calendar/Drive tools; keep the user's claude.ai connectors out of the
+  // sessions it runs, so there's one pathway for acting on their accounts (Kira's).
+  const env = { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1', ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
+  /** Background tasks the model still managed to start (an older CLI ignoring the flag): tool_use id -> description. */
+  const orphans = new Map()
+
   try {
     const q = query({
       prompt,
       options: {
         cwd,
+        env,
         ...(sessionId ? { resume: sessionId } : {}),
-        permissionMode: 'default',
+        // The model, effort and permission mode the person chose in the composer (plan mode: plan first).
+        ...sdkOptionsFor(settings),
         ...(abort ? { abortController: abort } : {}),
         // A team member's soul, skills and conventions ride on top of Claude Code's own prompt; its preset says which tools it does without.
         ...(persona?.systemPrompt ? { systemPrompt: { type: 'preset', preset: 'claude_code', append: persona.systemPrompt } } : {}),
         ...(persona?.disallowedTools?.length ? { disallowedTools: persona.disallowedTools } : {}),
-        // Kira has its own Gmail/Calendar/Drive tools; keep the user's claude.ai connectors out of
-        // the sessions it runs, so there's one pathway for acting on their accounts (Kira's).
-        env: { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: 'false' },
+        // Claude as the person's Kira: her tools come from her own MCP server, with a token the API
+        // made for this conversation. Claude Code loads them as it needs them (no tool ceiling).
+        ...(persona?.kiraTools ? { mcpServers: { kira: kiraServer(persona.kiraTools) } } : {}),
         canUseTool,
         hooks: { PreToolUse: [{ hooks: [preToolUse] }] },
         ...(process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}),
       },
     })
     for await (const m of q) {
+      // Messages from inside a subagent carry the id of the Subtask call that started it.
+      const nested = !!m.parent_tool_use_id
       if (m.type === 'system' && m.subtype === 'init') {
         session = m.session_id ?? session
         io.emit({ kind: 'session', sessionId: session, model: m.model ?? null })
+      } else if (m.type === 'system' && m.subtype === 'task_started') {
+        if (m.is_backgrounded && m.tool_use_id) orphans.set(m.tool_use_id, m.description ?? m.subagent_type ?? 'task')
+      } else if (m.type === 'system' && m.subtype === 'task_notification') {
+        if (m.tool_use_id) orphans.delete(m.tool_use_id)
       } else if (m.type === 'assistant') {
         for (const b of m.message?.content ?? []) {
-          if (b.type === 'text' && b.text?.trim()) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
+          // A subagent's narration is for its parent, not the user; its actions still show what is going on while the Subtask runs.
+          if (b.type === 'text' && b.text?.trim() && !nested) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
           else if (b.type === 'tool_use') io.emit({ kind: 'action', id: b.id, tool: b.name, ...describeAction(b.name, b.input, cwd) })
         }
       } else if (m.type === 'user') {
         for (const b of m.message?.content ?? []) {
           if (b?.type === 'tool_result') {
             const t = typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.map(c => (c.type === 'text' ? c.text : '')).join('\n') : ''
+            if (/^Async agent launched successfully/.test(t.trim()) && !orphans.has(b.tool_use_id)) orphans.set(b.tool_use_id, 'subagent')
             io.emit({ kind: 'action_result', id: b.tool_use_id, ok: !b.is_error, preview: short(t.trim(), 240) })
           }
         }
@@ -230,6 +260,11 @@ export async function run({ prompt, sessionId, cwd, policy, persona, abort }, io
         session = m.session_id ?? session
         if (m.subtype === 'success') text = String(m.result ?? '')
         else error = `Claude stopped: ${m.subtype}${Array.isArray(m.errors) && m.errors.length ? ` (${m.errors.join('; ').slice(0, 300)})` : ''}`
+        // Work left running in the background dies with this process; say so rather than let "still running" stand as the outcome.
+        if (orphans.size) {
+          const note = `${orphans.size} background ${orphans.size === 1 ? 'task was' : 'tasks were'} still running when Claude ended its turn (${[...orphans.values()].slice(0, 5).join(', ')}); they were stopped with the session and their findings are not in this report. Send a follow-up to have that work done inline.`
+          text = text ? `${text}\n\n(${note})` : `(${note})`
+        }
         const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd }
         io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: session, stats })
         return { ok: !error, text, error, sessionId: session, stats }

package/src/agents/policy.mjs

@@ -7,9 +7,29 @@
 // and every piece has to be safe for the whole command to be safe.
 import { relative, resolve, sep } from 'node:path'
 
-export const READ_ONLY = new Set(['Read', 'Glob', 'Grep', 'LS', 'TodoWrite', 'TodoRead', 'NotebookRead', 'Skill'])
+/**
+ * Tools that only look, or that are Claude Code's own housekeeping (ToolSearch loads the definitions
+ * of tools it has but hasn't used yet; the MCP resource tools read what a server offers).
+ */
+export const READ_ONLY = new Set([
+  'Read',
+  'Glob',
+  'Grep',
+  'LS',
+  'TodoWrite',
+  'TodoRead',
+  'NotebookRead',
+  'Skill',
+  'ToolSearch',
+  'ListMcpResourcesTool',
+  'ReadMcpResourceTool',
+])
+/** A subagent: older Claude Code calls the tool Task, newer Agent. */
+const DELEGATE = new Set(['Task', 'Agent'])
 export const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
 export const WEB = new Set(['WebFetch', 'WebSearch'])
+/** Claude Code's name for the tools of Kira's MCP server (mcp__<server>__<tool>). */
+export const KIRA_TOOLS = 'mcp__kira__'
 
 /** Read-only commands: looking, listing, testing, type-checking, building. Nothing that writes, sends or installs. */
 const SAFE_CMD = /^(?:ls|ll|pwd|cat|head|tail|wc|echo|printf|which|type|env|printenv|date|whoami|id|uname|tree|find|fd|grep|rg|ag|awk|cut|tr|sort|uniq|diff|comm|stat|file|du|df|basename|dirname|realpath|readlink|jq|yq|xxd|hexdump|strings|test|\[|true|false|sleep|md5|shasum|sha256sum|md5sum|column|nl|less|more|open -n --args|sed -n|sed -E -n|sed -n -E|git (?:status|diff|log|show|branch|rev-parse|remote|ls-files|ls-tree|blame|describe|stash list|tag|config --get|config -l|cat-file|grep|shortlog|count-objects|reflog)|node (?:-v|--version|-e|-p|--eval|--print)|npm (?:-v|--version|ls|list|view|outdated|why|test|run (?:test|lint|typecheck|check|build|format:check))|pnpm (?:-v|--version|ls|list|why|outdated|test|typecheck|lint|build|run (?:test|lint|typecheck|check|build))|yarn (?:-v|--version|list|test|lint|typecheck|build)|npx (?:tsc|eslint|prettier --check|jest|vitest|playwright test)|tsc|eslint|prettier --check|jest|vitest|cargo (?:check|test|build|fmt --check|clippy|tree|metadata)|go (?:test|build|vet|version|list|env)|python3? (?:-V|--version|-m pytest|-c)|pytest|ruby -v|make (?:test|check|lint|build)|mvn (?:test|compile)|gradle (?:test|build)|swift (?:build|test)|xcodebuild -list|brew (?:list|info|--version)|docker (?:ps|images|version)|gh (?:pr (?:list|view|status|checks)|issue (?:list|view)|run (?:list|view)|repo view|api)|heroku (?:logs|ps|releases|config(?::get)?|apps|info))(?:\s|$)/
@@ -80,6 +100,9 @@ export function decide(policy, toolName, input, cwd, sessionRules = new Set()) {
   if (matchesRule(p.askRules ?? [], toolName, command)) return { decision: 'ask', reason: 'your policy always asks for this' }
   if (matchesRule([...(p.allowRules ?? []), ...sessionRules], toolName, command)) return { decision: 'allow', reason: 'allowed by your policy' }
   if (READ_ONLY.has(toolName)) return { decision: 'allow', reason: 'read-only' }
+  // Kira's own tools (her MCP server, attached when Claude is the person's Kira): her server asks
+  // for itself when something needs their yes (approvals), so the Mac doesn't ask a second time.
+  if (toolName.startsWith(KIRA_TOOLS)) return { decision: 'allow', reason: 'Kira’s own tool' }
   if (EDITS.has(toolName)) {
     const file = input?.file_path ?? input?.notebook_path
     if (insideFolder(cwd, file)) return { decision: p.edits === 'ask' ? 'ask' : 'allow', reason: 'edit inside the project' }
@@ -91,7 +114,7 @@ export function decide(policy, toolName, input, cwd, sessionRules = new Set()) {
     return { decision: 'ask', reason: 'shell command' }
   }
   if (WEB.has(toolName)) return { decision: p.web === 'ask' ? 'ask' : 'allow', reason: 'web' }
-  if (toolName === 'Task') return { decision: p.delegate === 'ask' ? 'ask' : 'allow', reason: 'subagent' }
+  if (DELEGATE.has(toolName)) return { decision: p.delegate === 'ask' ? 'ask' : 'allow', reason: 'subagent' }
   if (toolName === 'ExitPlanMode') return { decision: p.plan === 'allow' ? 'allow' : 'ask', reason: 'plan approval' }
   return { decision: 'ask', reason: 'unfamiliar tool' }
 }

package/src/agents/settings.mjs

@@ -0,0 +1,23 @@
+// How a job runs, as the person chose it in Kira's composer (genui run-settings.ts): the model,
+// the effort, and the permission mode. Pure: the Agent SDK's options and the policy it judges by.
+//
+//   { model?: string, effort?: 'low'|'medium'|'high', mode?: 'auto'|'ask'|'plan' }
+
+const EFFORTS = new Set(['low', 'medium', 'high'])
+const MODEL = /^claude-[a-z0-9-]{1,60}$/
+
+/** The SDK's query options for these settings (left out when unset, so Claude Code's defaults stand). */
+export function sdkOptionsFor(settings) {
+  const s = settings ?? {}
+  return {
+    permissionMode: s.mode === 'plan' ? 'plan' : 'default',
+    ...(typeof s.model === 'string' && MODEL.test(s.model) ? { model: s.model } : {}),
+    ...(EFFORTS.has(s.effort) ? { effort: s.effort } : {}),
+  }
+}
+
+/** The person's policy for this job: "Ask" asks before every edit and every command. */
+export function policyFor(policy, settings) {
+  const p = policy ?? {}
+  return settings?.mode === 'ask' ? { ...p, edits: 'ask', shell: 'ask' } : p
+}

package/src/claude-designs.mjs

@@ -155,14 +155,16 @@ async function designsOf(s) {
 }
 
 /**
- * Scan every session changed since `since` (ISO time; all of them when omitted). Returns the
- * designs without their HTML, plus the HTML of those whose hash isn't in `known` (hashes the API
- * already holds), so a rescan sends only what changed.
+ * Scan every session changed since `since` (ISO time; all of them when omitted), or only the
+ * sessions named in `sessions` (a Claude job just finished in one). Returns the designs without
+ * their HTML, plus the HTML of those whose hash isn't in `known` (hashes the API already holds),
+ * so a rescan sends only what changed.
  */
-export async function scanDesigns({ since, known = [] } = {}) {
+export async function scanDesigns({ since, known = [], sessions: only } = {}) {
   const after = since ? Date.parse(since) || 0 : 0
   const have = new Set(known)
-  const sessions = (await sdkListSessions()).filter(s => s.lastModified > after)
+  const pick = Array.isArray(only) && only.length ? new Set(only) : null
+  const sessions = (await sdkListSessions()).filter(s => (pick ? pick.has(s.sessionId) : s.lastModified > after))
   const designs = []
   let failed = 0
   for (const s of sessions) {

package/src/git-tools.mjs

@@ -0,0 +1,51 @@
+// The bridge's git tools: worktrees for task attempts, what's in a folder's repository, and its
+// branches and worktrees (what Kira offers after @). Spread into index.mjs's tool table.
+import { resolveCwd } from './claude-run.mjs'
+import { snapshot } from './git.mjs'
+import { gitRefs } from './refs.mjs'
+import {
+  listOutputs,
+  prepareWorktree,
+  pushWorktree,
+  removeWorktree,
+  repoOfFolder,
+  stageFiles,
+  uploadOutputs,
+  worktreeStatus,
+} from './worktrees.mjs'
+
+export const gitTools = {
+  /** A worktree for one task attempt, off the project's checkout of the repo. */
+  prepare_worktree: args => prepareWorktree(args),
+  worktree_status: args => worktreeStatus(args),
+  push_worktree: args => pushWorktree(args),
+  remove_worktree: args => removeWorktree(args),
+  /** A task's reference files, downloaded into the worktree's .kira/files for the agent. */
+  stage_files: args => stageFiles(args),
+  /** What a designer or researcher produced under its output folder, and sending it to Kira's storage. */
+  list_outputs: args => listOutputs(args),
+  upload_outputs: args => uploadOutputs(args),
+
+  /** Which GitHub repo a folder's origin points at (project link enrichment). */
+  async repo_of_folder(args) {
+    return { repo: await repoOfFolder(args.path) }
+  },
+
+  /** Read-only git facts for a folder: repo, branch, head, dirty files. */
+  async git_status(args) {
+    const s = await snapshot(resolveCwd(args.path ?? args.cwd))
+    if (!s) return { error: 'not a git repository' }
+    const head = s.head?.slice(0, 7) ?? null
+    return {
+      cwd: s.cwd,
+      repo: s.repo,
+      branch: s.branch,
+      head,
+      dirty: s.dirty.slice(0, 50),
+      dirty_count: s.dirty.length,
+    }
+  },
+
+  /** A folder's branches (newest first) and where each is checked out: here, or in a worktree. */
+  git_refs: args => gitRefs(resolveCwd(args.path ?? args.cwd)),
+}

package/src/git.mjs

@@ -10,7 +10,7 @@ import { randomUUID } from 'node:crypto'
 const DIFF_CAP = 400 * 1024 // bytes of unified diff kept per change
 const COMMIT_CAP = 20
 
-function git(cwd, args, { ok = [0], env = {} } = {}) {
+export function git(cwd, args, { ok = [0], env = {} } = {}) {
   return new Promise(resolve => {
     execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', ...env } }, (err, stdout) => {
       if (err && !ok.includes(err.code)) return resolve(null)

package/src/index.mjs

@@ -8,18 +8,17 @@ import { snapshot, changesSince, display, setupProjectFolder } from './git.mjs'
 import { resolveCwd, folderExists } from './claude-run.mjs'
 import { agentById, AGENTS } from './agents/index.mjs'
 import { normalizeAnswer } from './agents/protocol.mjs'
+import { answer, awaitAnswer, forgetJob } from './agents/answers.mjs'
 import { openApp, installedApps } from './apps.mjs'
 import { listFiles, readUserFile, createFolder, writeUserFile, trashPath, resolveUserPath } from './files.mjs'
 import { initTerminals, terminalCall, terminalMessage, terminalsOffline } from './terminals.mjs'
-import { prepareWorktree, worktreeStatus, pushWorktree, removeWorktree, repoOfFolder, stageFiles, listOutputs, uploadOutputs } from './worktrees.mjs'
+import { gitTools } from './git-tools.mjs'
 
 import { createRequire } from 'node:module'
 const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
 
 let URL_ = ''
 let TOKEN = ''
-/** Requests waiting on a person: `${jobId}:${requestId}` -> resolve({ answer, by }). */
-const answerWaits = new Map()
 /** Running jobs, by id, so a person can stop one. */
 const running = new Map()
 /**
@@ -35,7 +34,6 @@ function sendLive(obj) {
   if (outbox.length >= OUTBOX_MAX) outbox.shift()
   outbox.push(obj)
 }
-const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
 
 /**
  * How the host hears from the bridge. The CLI passes nothing (logs to stdout, exits when the
@@ -45,6 +43,7 @@ const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
  *   openTerminal({ cwd, command })   open_terminal in the app's own terminal (a Kira tab), not
  *                           Terminal.app; resolves to what to report, or null to fall back
  *   terminals               the app's shells, for remote devices (terminals.mjs)
+ *   browser({ op, … })      Kira in the app's browser dock: open, read, click, type (browser-kira.mjs)
  */
 let hooks = {}
 let stopped = false
@@ -112,7 +111,7 @@ const tools = {
     return listProjects(args.max)
   },
   async scan_claude_designs(args) {
-    return scanDesigns({ since: args.since, known: Array.isArray(args.known) ? args.known : [] })
+    return scanDesigns({ since: args.since, known: Array.isArray(args.known) ? args.known : [], sessions: args.sessions })
   },
   async list_claude_sessions(args) {
     return listSessions(args.max)
@@ -142,40 +141,30 @@ const tools = {
       return { error: `The folder ${display(dir)} does not exist on this Mac. Link the project's real folder in the portal, or clone its repository there first (setup_project_folder); never guess a path.` }
     }
     log(`${agent.id} job=${jobId.slice(0, 8)}${args.persona?.name ? ` as ${args.persona.name}` : ''} session=${args.session_id ?? 'new'} in ${display(dir)}: ${prompt.slice(0, 80)}`)
-    const before = await snapshot(dir).catch(() => null)
     let seq = 0
     const io = {
       emit: event => sendLive({ type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
-      ask: (request, signal) =>
-        new Promise((resolve, reject) => {
-          const key = `${jobId}:${request.id}`
-          const timer = setTimeout(() => {
-            answerWaits.delete(key)
-            reject(new Error('No answer within 3 minutes'))
-          }, ANSWER_TIMEOUT_MS)
-          answerWaits.set(key, resolved => {
-            clearTimeout(timer)
-            resolve(resolved)
-          })
-          signal?.addEventListener('abort', () => {
-            clearTimeout(timer)
-            answerWaits.delete(key)
-            reject(new Error('The job was stopped'))
-          }, { once: true })
-        }),
+      ask: (request, signal) => awaitAnswer(jobId, request, signal),
     }
     const abort = new AbortController()
     running.set(jobId, abort)
-    void agent.run({ prompt, sessionId: args.session_id, cwd: dir, policy: args.policy ?? {}, persona: args.persona ?? null, abort }, io).then(async outcome => {
+    // Started is said at once. The git snapshot (what changed, reported at the end) is taken first but
+    // in the background: in a big repository it takes longer than the API waits for this answer.
+    const before = snapshot(dir).catch(() => null)
+    const persona = args.persona ?? null
+    const settings = args.settings ?? null
+    const job = { prompt, sessionId: args.session_id, cwd: dir, policy: args.policy ?? {}, persona, settings, abort }
+    void before.then(() => agent.run(job, io)).then(async outcome => {
       running.delete(jobId)
-      for (const key of [...answerWaits.keys()]) if (key.startsWith(`${jobId}:`)) answerWaits.delete(key)
+      forgetJob(jobId)
       let change = null
-      if (before) change = await changesSince(before).catch(err => (log(`git after job failed: ${err.message}`), null))
+      const was = await before
+      if (was) change = await changesSince(was).catch(err => (log(`git after job failed: ${err.message}`), null))
       log(`job ${jobId.slice(0, 8)} ${outcome.ok ? 'done' : 'error'}${change ? ` · ${change.stats.files} files +${change.stats.adds} -${change.stats.dels}, ${change.commits.length} commits` : ''}`)
       const result = { session_id: outcome.sessionId, result: outcome.text ?? '', stats: outcome.stats, cwd: display(dir), change, agent: agent.id }
       sendLive({ type: 'job', jobId, status: outcome.ok ? 'done' : 'error', result, error: outcome.error })
     })
-    return { started: true, agent: agent.id, cwd: display(dir), git: before ? { repo: before.repo, branch: before.branch, head: before.head?.slice(0, 7) ?? null } : null }
+    return { started: true, agent: agent.id, cwd: display(dir) }
   },
   /** Stop a running job: the agent is cut off; whatever it committed stays. */
   stop_job(args) {
@@ -198,6 +187,12 @@ const tools = {
   /** This Mac's shells for a browser elsewhere (only inside the Mac app, only when switched on there). */
   terminal: args => terminalCall(args),
 
+  /** Kira in the Mac app's browser dock: open a page, read it, click and type in it. */
+  async browser(args) {
+    if (!hooks.browser) return { error: 'the browser needs the Kira Mac app (this bridge has none)', reason: 'unavailable' }
+    return hooks.browser(args)
+  },
+
   /** Open a terminal on this Mac in a folder and run a command there (used to hand a Claude session
    *  to the person): a Kira tab when the bridge runs inside the Mac app, else Terminal.app. */
   async open_terminal(args) {
@@ -216,34 +211,7 @@ end tell`
     return new Promise(resolve => execFile('osascript', ['-e', script], err => resolve(err ? { error: err.message } : { opened: true, cwd: display(dir), command })))
   },
 
-  /** A worktree for one task attempt, off the project's checkout of the repo. */
-  prepare_worktree(args) {
-    return prepareWorktree(args)
-  },
-  worktree_status(args) {
-    return worktreeStatus(args)
-  },
-  push_worktree(args) {
-    return pushWorktree(args)
-  },
-  remove_worktree(args) {
-    return removeWorktree(args)
-  },
-  /** A task's reference files, downloaded into the worktree's .kira/files for the agent. */
-  stage_files(args) {
-    return stageFiles(args)
-  },
-  /** What a designer or researcher produced under its output folder, and sending it to Kira's storage. */
-  list_outputs(args) {
-    return listOutputs(args)
-  },
-  upload_outputs(args) {
-    return uploadOutputs(args)
-  },
-  /** Which GitHub repo a folder's origin points at (project link enrichment). */
-  async repo_of_folder(args) {
-    return { repo: await repoOfFolder(args.path) }
-  },
+  ...gitTools,
 
   /** Which Claude account Claude Code on this Mac is signed in to (`claude auth status --json`). */
   async claude_account() {
@@ -261,12 +229,7 @@ end tell`
     )
   },
 
-  /** Read-only git facts for a folder: repo, branch, head, dirty files. */
-  async git_status(args) {
-    const s = await snapshot(resolveCwd(args.path ?? args.cwd))
-    if (!s) return { error: 'not a git repository' }
-    return { cwd: s.cwd, repo: s.repo, branch: s.branch, head: s.head?.slice(0, 7) ?? null, dirty: s.dirty.slice(0, 50), dirty_count: s.dirty.length }
-  },
+
 }
 
 /**
@@ -322,11 +285,8 @@ function connect() {
       return log(`registered as bridge ${msg.bridgeId} (${Object.keys(tools).length} tools)`)
     }
     if (msg.type === 'job.answer') {
-      const key = `${msg.jobId}:${msg.requestId}`
-      const resolve = answerWaits.get(key)
-      if (resolve) {
-        answerWaits.delete(key)
-        resolve({ answer: normalizeAnswer(msg.answer), by: msg.by ?? 'portal' })
+      const by = msg.by ?? 'portal'
+      if (answer(msg.jobId, msg.requestId, { answer: normalizeAnswer(msg.answer), by })) {
         log(`request ${msg.requestId} for job ${String(msg.jobId).slice(0, 8)} answered by ${msg.by ?? 'portal'}`)
       }
       return

package/src/refs.mjs

@@ -0,0 +1,60 @@
+// A folder's branches and worktrees, read from git: what Kira offers after @ ("@branch main"), so
+// a message can point Claude at a place to work. Read-only; the parsers are pure and tested.
+import { display, git } from './git.mjs'
+
+const BRANCH_FORMAT = '%(refname:short)%09%(HEAD)%09%(committerdate:iso-strict)%09%(contents:subject)'
+const MAX_BRANCHES = 60
+
+/** `git branch --format=…` lines: name, whether it's checked out here, when it last moved, its last commit. */
+export function parseBranches(out) {
+  return String(out ?? '')
+    .split('\n')
+    .filter(Boolean)
+    .map(line => {
+      const [name = '', head = '', at = '', subject = ''] = line.split('\t')
+      return { name, current: head.trim() === '*', at: at || null, subject }
+    })
+    .filter(b => b.name && !b.name.startsWith('('))
+}
+
+/** `git worktree list --porcelain`: each worktree's path, branch (null when detached) and head. */
+export function parseWorktrees(out) {
+  return String(out ?? '')
+    .split('\n\n')
+    .map(block => {
+      const field = key =>
+        block
+          .split('\n')
+          .find(l => l.startsWith(`${key} `))
+          ?.slice(key.length + 1) ?? null
+      const branch = field('branch')
+      return {
+        path: field('worktree'),
+        branch: branch ? branch.replace(/^refs\/heads\//, '') : null,
+        head: field('HEAD'),
+      }
+    })
+    .filter(w => w.path)
+}
+
+/** Branches newest first, each with the worktree it's checked out in (if any). */
+export function joinRefs(branches, worktrees, main) {
+  const where = new Map(worktrees.filter(w => w.branch).map(w => [w.branch, w.path]))
+  return [...branches]
+    .sort((a, b) => (b.current ? 1 : 0) - (a.current ? 1 : 0) || String(b.at).localeCompare(String(a.at)))
+    .slice(0, MAX_BRANCHES)
+    .map(b => {
+      const path = where.get(b.name) ?? null
+      return { ...b, worktree: path && path !== main ? display(path) : null, here: path === main }
+    })
+}
+
+export async function gitRefs(dir) {
+  const main = (await git(dir, ['rev-parse', '--show-toplevel']))?.trim()
+  if (!main) return { error: 'not a git repository' }
+  const [branches, worktrees] = await Promise.all([
+    git(main, ['branch', `--format=${BRANCH_FORMAT}`, '--sort=-committerdate']),
+    git(main, ['worktree', 'list', '--porcelain']),
+  ])
+  return { cwd: display(main), branches: joinRefs(parseBranches(branches), parseWorktrees(worktrees), main) }
+}