@leftoff/cli 0.8.7 → 0.8.8

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "leftoff",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Leftoff (formerly Checkpoints): WTF was I working on? Tracks every Claude Code session on this machine, writes a 3-line checkpoint when one goes quiet, and adds /cp (checkpoint now), /cp-name and a /leftoff pane. Talks to the local Leftoff daemon on 127.0.0.1:7429 and falls back to writing markdown in ~/checkpoints.",
   "author": {
     "name": "Joel"

package/mod/hooks/core.js

@@ -298,7 +298,8 @@ const CP_ORDER = ['id', 'session_id', 'session_title', 'created_at', 'trigger',
 export function resumeCommand(session) {
   const id = session.id || session.sessionId
   const cwd = resumeDir(session)
-  return (cwd ? 'cd ' + shArg(cwd) + ' && ' : '') + (isCodex(session) ? codexInvocation(id) : claudeInvocation(session, ['--resume', id]))
+  const wt = resumeWorktreeName(session)
+  return (cwd ? 'cd ' + shArg(cwd) + ' && ' : '') + (isCodex(session) ? codexInvocation(id) : claudeInvocation(session, [...(wt ? ['--worktree', wt] : []), '--resume', id]))
 }
 
 // 0.8.0: a Codex session (its rollout under ~/.codex/sessions) resumes with `codex resume <id>`.
@@ -308,9 +309,24 @@ export function codexInvocation(id) { return 'codex resume ' + shArg(id) }
 // 0.7.1: where to run `claude --resume`: the session's folder, or, inside a git
 // worktree, that worktree's own top folder (Claude Code declines to re-enter a
 // `git worktree add` worktree from one of its subfolders; code.claude.com/docs/en/worktrees).
+//
+// 0.8.8: a worktree Claude Code made (<repo>/.claude/worktrees/<name>, from
+// `claude --worktree` or EnterWorktree) is resumed the way Claude Code itself
+// prints on exit: from the main checkout, `claude --worktree <name> --resume <id>`.
+// On exit Claude Code moves the session back to where it was launched and
+// clears its worktree binding, so --worktree is what puts it back in there.
+// Not when the worktree is gone (folderGone): --worktree would make a new one.
+export function resumeWorktreeName(session) {
+  const wt = session && session.repo && session.repo.worktree
+  const root = session && session.repo && session.repo.root
+  if (!wt || !root || typeof wt !== 'string' || session.folderGone || isCodex(session)) return null
+  const c = claudeWorktreeOf(wt)
+  return c && trimSlash(c.root) === trimSlash(root) && trimSlash(c.path) === trimSlash(wt) ? c.name : null
+}
 export function resumeDir(session) {
   const cwd = session && session.cwd
   const wt = session && session.repo && session.repo.worktree
+  if (resumeWorktreeName(session)) return session.repo.root
   if (cwd && wt && typeof wt === 'string' && (cwd === wt || String(cwd).startsWith(wt.replace(/\/+$/, '') + '/'))) return wt
   return cwd || null
 }
@@ -821,9 +837,14 @@ export function applyEvent(s, ev) {
   // replayed older events (a Codex rollout read again) don't.
   if (s.parked && ms(at) > ms(s.parked.at) && unparks(s, ev, d)) delete s.parked
   switch (ev.type) {
-    case 'session.parked':
+    case 'session.parked': {
+      const prevLock = s.parked && s.parked.worktreeLock // parked again: the lock it already holds stays on record
       s.parked = { at, note: d.note ? clip(String(d.note).replace(/\s+/g, ' ').trim(), 300) || null : null, checkpoint: d.checkpoint ? String(d.checkpoint) : null, by: d.by ? String(d.by) : null }
+      // 0.8.8: the worktree /cp-park (or Park) locked, so it can be unlocked later
+      if (d.worktreeLock && typeof d.worktreeLock === 'object' && typeof d.worktreeLock.path === 'string' && typeof d.worktreeLock.reason === 'string') s.parked.worktreeLock = { path: d.worktreeLock.path, root: typeof d.worktreeLock.root === 'string' ? d.worktreeLock.root : null, reason: d.worktreeLock.reason }
+      else if (prevLock) s.parked.worktreeLock = prevLock
       break
+    }
     case 'session.unparked':
       delete s.parked
       break
@@ -912,6 +933,137 @@ export function parseParkArgs(args) {
   return { note: note ? clip(note, 300) : null }
 }
 
+// ------------------------------------------------------------ parked worktrees (0.8.8)
+// Claude Code removes a session's worktree when the session exits and the
+// worktree has no changes (code.claude.com/docs/en/worktrees, "Clean up
+// worktrees"), and /cp-park exits. So in a linked git worktree, park first
+// locks it (`git worktree lock --reason …`). Claude Code's exit cleanup keeps a
+// worktree locked with a reason it didn't write, and its stale-lock sweep only
+// releases its own "claude agent|session … (pid N)" locks, so the reason must
+// never start with "claude ". Resume, Done with it, or the session coming back
+// unlocks it. Only a lock with this exact session's reason is ever unlocked.
+// run(argv) -> { code | exitCode, stdout, stderr }: $.process.run in the mod,
+// execFile in the daemon, a fake in tests. Nothing here deletes anything.
+export const PARK_LOCK_PREFIX = 'leftoff: parked session '
+export function parkLockReason(sessionId) {
+  return PARK_LOCK_PREFIX + String(sessionId || '') + ' (resume it, or press Done with it on the board, to unlock)'
+}
+// a lock reason -> the session id Leftoff parked, or null for any other lock
+export function parkLockSession(reason) {
+  const m = /^leftoff: parked session ([A-Za-z0-9-]{4,80})(?: |$)/.exec(String(reason == null ? '' : reason))
+  return m ? m[1] : null
+}
+
+// `git worktree list --porcelain` -> [{ path, branch, bare, detached, locked: null | reason ('' when none given) }]
+export function parseWorktreeList(text) {
+  const out = []
+  let cur = null
+  for (const raw of String(text || '').split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (line.startsWith('worktree ')) { cur = { path: line.slice(9), branch: null, bare: false, detached: false, locked: null }; out.push(cur); continue }
+    if (!cur) continue
+    if (line.startsWith('branch ')) cur.branch = line.slice(7).replace(/^refs\/heads\//, '')
+    else if (line === 'bare') cur.bare = true
+    else if (line === 'detached') cur.detached = true
+    else if (line === 'locked') cur.locked = ''
+    else if (line.startsWith('locked ')) cur.locked = line.slice(7)
+  }
+  return out
+}
+
+const runCode = (r) => (r == null ? null : r.code != null ? r.code : r.exitCode != null ? r.exitCode : null)
+const trimSlash = (p) => String(p || '').replace(/\/+$/, '') || '/'
+const firstLine = (s) => String(s || '').trim().split('\n')[0].slice(0, 200)
+// a path inside Claude Code's own worktrees folder: <repo>/.claude/worktrees/<name>[/…]
+export function claudeWorktreeOf(dir) {
+  const m = /^(.*)\/\.claude\/worktrees\/([^/]+)(?:\/.*)?$/.exec(trimSlash(dir))
+  return m ? { root: m[1] || '/', name: m[2], path: m[1] + '/.claude/worktrees/' + m[2] } : null
+}
+
+// Is dir in a linked git worktree? -> { kind: 'worktree', top, root, gitDir, commonDir }
+// | { kind: 'none' } (not in git, or the main checkout) | { kind: 'unknown', why }
+export async function worktreeAt(run, dir) {
+  if (!dir) return { kind: 'unknown', why: 'no folder on record' }
+  let r
+  try { r = await run(['git', '-C', dir, 'rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir', '--show-toplevel']) } catch (e) { return { kind: 'unknown', why: 'git didn’t run (' + firstLine(e && e.message) + ')' } }
+  if (runCode(r) !== 0) {
+    if (/not a git repository/i.test(String(r && r.stderr))) return claudeWorktreeOf(dir) ? { kind: 'unknown', why: 'git doesn’t see a repository there' } : { kind: 'none' }
+    return { kind: 'unknown', why: 'git: ' + (firstLine(r && r.stderr) || 'exit ' + runCode(r)) }
+  }
+  const [gitDir, commonDir, top] = String(r.stdout || '').trim().split('\n').map((x) => trimSlash(x.trim()))
+  if (!gitDir || !commonDir || !top) return { kind: 'unknown', why: 'git gave no answer' }
+  if (gitDir === commonDir) return { kind: 'none' } // the main checkout (or a submodule, its own repo)
+  return { kind: 'worktree', top, gitDir, commonDir, root: /\/\.git$/.test(commonDir) ? commonDir.slice(0, -5) || '/' : commonDir }
+}
+
+function findEntry(list, path, reason) {
+  const p = trimSlash(path)
+  return list.find((e) => trimSlash(e.path) === p) || (reason ? list.find((e) => e.locked === reason) : null) || null
+}
+
+// /cp-park (and Park on the board): lock the worktree dir is in, then read it
+// back. -> { worktree: null } (not a worktree: nothing to protect)
+//  | { worktree, root, locked: true, reason } (locked and checked)
+//  | { worktree, root?, locked: false, why } (not protected: don't exit for them)
+export async function lockForPark(run, dir, sessionId) {
+  const w = await worktreeAt(run, dir)
+  if (w.kind === 'none') return { worktree: null }
+  if (w.kind === 'unknown') { const g = claudeWorktreeOf(dir); return { worktree: g ? g.path : null, locked: false, why: w.why, unsure: true } }
+  const reason = parkLockReason(sessionId)
+  let lockErr = ''
+  try { const r = await run(['git', '-C', w.top, 'worktree', 'lock', '--reason', reason, w.top]); if (runCode(r) !== 0) lockErr = firstLine(r && r.stderr) || 'exit ' + runCode(r) } catch (e) { lockErr = firstLine(e && e.message) }
+  let list = null
+  try { const l = await run(['git', '-C', w.top, 'worktree', 'list', '--porcelain']); if (runCode(l) === 0) list = parseWorktreeList(l.stdout) } catch {}
+  const base = { worktree: w.top, root: w.root }
+  if (!list) return { ...base, locked: false, why: 'couldn’t read the lock back' + (lockErr ? ' (' + lockErr + ')' : '') }
+  const e = findEntry(list, w.top, reason)
+  if (e && e.locked === reason) return { ...base, locked: true, reason }
+  if (e && e.locked != null) return { ...base, locked: false, why: 'it’s already locked' + (e.locked ? ' (“' + clip(e.locked, 80) + '”)' : ''), foreign: true }
+  return { ...base, locked: false, why: lockErr || 'the lock didn’t take' }
+}
+
+// Is the lock still there, with our reason? (checked again right before /exit)
+export async function parkLockHeld(run, path, reason) {
+  try {
+    const l = await run(['git', '-C', path, 'worktree', 'list', '--porcelain'])
+    if (runCode(l) !== 0) return false
+    const e = findEntry(parseWorktreeList(l.stdout), path, reason)
+    return !!(e && e.locked === reason)
+  } catch { return false }
+}
+
+// Unlock what Leftoff locked for this session: every worktree of the repo at
+// dir whose lock reason is this session's park reason. Any other lock (yours,
+// Claude Code's) is left alone. -> { unlocked: [path], failed: [{ path, why }], error? }
+export async function unlockParkLocks(run, dir, sessionId) {
+  const out = { unlocked: [], failed: [] }
+  if (!dir || !sessionId) return out
+  let list
+  try {
+    const l = await run(['git', '-C', dir, 'worktree', 'list', '--porcelain'])
+    if (runCode(l) !== 0) return { ...out, error: firstLine(l && l.stderr) || 'git worktree list failed' }
+    list = parseWorktreeList(l.stdout)
+  } catch (e) { return { ...out, error: firstLine(e && e.message) } }
+  for (const e of list) {
+    if (e.locked == null || parkLockSession(e.locked) !== String(sessionId)) continue
+    try {
+      const r = await run(['git', '-C', dir, 'worktree', 'unlock', e.path])
+      if (runCode(r) === 0) out.unlocked.push(e.path)
+      else out.failed.push({ path: e.path, why: firstLine(r && r.stderr) || 'exit ' + runCode(r) })
+    } catch (err) { out.failed.push({ path: e.path, why: firstLine(err && err.message) }) }
+  }
+  return out
+}
+
+// What /cp-park says about the worktree. res: lockForPark's answer.
+export function parkWorktreeText(res) {
+  if (!res || !res.worktree && !res.unsure) return ''
+  if (!res.worktree && !res.locked) return ' Leftoff couldn’t tell whether this is a worktree session (' + (res.why || 'no answer') + '), so it didn’t close it. If it is one, lock it first (`git worktree lock <worktree>`) or choose Keep if Claude Code asks: on /exit, Claude Code removes a worktree that has no changes.'
+  if (res.locked) return ' This is a worktree session, so Leftoff locked the worktree first: Claude Code will say it kept it (“could not be removed”). Resume or Done with it unlocks it.'
+  const where = res.worktree ? ' ' + shArg(res.worktree) : ''
+  return ' This is a worktree session and Leftoff couldn’t lock it (' + (res.why || 'no answer') + '), so it didn’t close the session: on /exit, Claude Code removes a worktree that has no changes. To keep it, run `git worktree lock' + (where || ' <worktree>') + '` first, or choose Keep if Claude Code asks.'
+}
+
 // The question Claude ended its turn on, if it ended on one: the last paragraph
 // of the answer when its last sentence ends with "?" (markdown and closing
 // quotes ignored). Code blocks don't count. -> string or null

package/mod/hooks/register.js

@@ -19,7 +19,7 @@ import {
   shortId, formatTabTitle, parseTabTitle, detectTerminal, parseProcLine, trailingQuestion,
   parseCheckpointArgs, SUMMARY_LENGTHS, parseBulletList, parseCatchupArgs,
   listHintFrom, extractChecklists, parseTodoArgs, parseDoneArgs, detectBackend, parseParkArgs,
-  boardLinkLines, isNonInteractive,
+  boardLinkLines, isNonInteractive, lockForPark, parkLockHeld, unlockParkLocks, parkWorktreeText,
 } from './core.js'
 
 const PANE_ID = 'checkpoints'
@@ -28,7 +28,7 @@ const END_TIMEOUT_MS = 1000
 const MODEL_TIMEOUT_MS = 20000
 
 // Module state. $.state is not used: the pane redraws with $.ui.invalidate.
-const MOD_VERSION = '0.8.7' // keep in step with .claude-plugin/plugin.json
+const MOD_VERSION = '0.8.8' // keep in step with .claude-plugin/plugin.json
 
 const st = {
   internal: false,
@@ -278,17 +278,45 @@ async function boardLinks($) {
 // only runs once Claude is done with the turn). If that's refused, it says to
 // type /exit. Nothing is ever killed.
 const PARK_FALLBACK = 'Parked. Type /exit when you\'re ready, and it\'ll stay on your board.'
+const PARK_LOCK_LOST = 'Parked, but not closed: the worktree lock Leftoff took is gone, and on /exit Claude Code removes a worktree that has no changes. Lock it again (git worktree lock), or choose Keep if Claude Code asks.'
+// 0.8.8: argv -> { exitCode, stdout, stderr } for the worktree helpers in core.js
+async function gitFor($, argv) { return $.process.run(argv, { timeoutMs: 5000 }) }
 async function parkCommand($, args) {
   if (st.internal || !st.sessionId) return { text: 'Leftoff: not in a tracked session.' }
   const a = parseParkArgs(args)
+  // 0.8.8: in a git worktree, lock it first: Claude Code's exit removes a worktree
+  // with no changes, and parking means coming back. No lock, no automatic /exit.
+  let cwd = null
+  try { cwd = await $.session.cwd() } catch {}
+  cwd = cwd || (st.record && st.record.cwd) || null
+  const run = (argv) => gitFor($, argv)
+  const wt = cwd ? await lockForPark(run, cwd, st.sessionId).catch((e) => ({ worktree: null, locked: false, unsure: true, why: String(e && e.message) })) : { worktree: null, locked: false, unsure: true, why: 'no folder on record' }
   const cp = await makeCheckpoint($, 'park', a.note, null, { next: a.note })
-  if (!cp) return { text: 'Leftoff: a checkpoint is already being made. Try /cp-park again in a moment.' }
-  await sendOrSpool($, 'session.parked', { note: a.note, checkpoint: cp.id || null, by: 'command' })
-  // After this command returns, not inside it: the built-in /exit.
+  if (!cp) {
+    if (wt.locked) await unlockParkLocks(run, wt.root || wt.worktree, st.sessionId).catch(() => null) // not parked after all
+    return { text: 'Leftoff: a checkpoint is already being made. Try /cp-park again in a moment.' }
+  }
+  const worktreeLock = wt.locked ? { path: wt.worktree, root: wt.root || null, reason: wt.reason } : null
+  await sendOrSpool($, 'session.parked', { note: a.note, checkpoint: cp.id || null, by: 'command', ...(worktreeLock ? { worktreeLock } : {}) })
+  const head = 'Parked' + (a.note ? ': ' + clip(a.note, 120) : '') + '.'
+  if (wt.worktree || wt.unsure) {
+    if (!wt.locked) return { text: head + parkWorktreeText(wt) }
+  }
+  // After this command returns, not inside it: the built-in /exit (in a worktree, only while our lock still holds).
   $.clock.after(400, async () => {
+    if (worktreeLock && !(await parkLockHeld(run, worktreeLock.path, worktreeLock.reason))) { try { $.ui.toast(PARK_LOCK_LOST, { timeoutMs: 12000 }) } catch {} return }
     try { await $.command.run({ command: 'exit' }) } catch { try { $.ui.toast(PARK_FALLBACK, { timeoutMs: 8000 }) } catch {} }
   })
-  return { text: 'Parked' + (a.note ? ': ' + clip(a.note, 120) : '') + '. Closing this session; it stays on your board under Parked.' }
+  return { text: head + ' Closing this session; it stays on your board under Parked.' + parkWorktreeText(wt) }
+}
+
+// 0.8.8: this session is back (claude --resume, or --worktree <name> --resume):
+// unlock any worktree Leftoff locked when it was parked. Only its own lock.
+async function unlockOwnParkLocks($, cwd) {
+  if (st.internal || !st.sessionId || !cwd) return
+  try {
+    await unlockParkLocks((argv) => gitFor($, argv), cwd, st.sessionId)
+  } catch {}
 }
 
 // ------------------------------------------------------------ lists (v0.5.1)
@@ -901,6 +929,7 @@ export function register(on, options) {
       st.backend = await readBackend($, model)
       st.hello = { cwd, repo, model, backend: st.backend, surface, proc: st.proc ? { ...st.proc, source: 'mod' } : null, term: st.term }
       await sendOrSpool($, 'session.opened', st.hello)
+      if (repo) await unlockOwnParkLocks($, cwd) // 0.8.8
       if (st.heartbeat) st.heartbeat.cancel()
       st.heartbeat = $.clock.every(60000, () => { heartbeat($).catch(() => {}); startReplyLoop($) })
       st.ready = true
@@ -923,6 +952,7 @@ export function register(on, options) {
         st.lastCheckpoint = null
         st.titleSoon = false
         st.daemonTitle = null
+        if (e.source === 'resume' && e.cwd) await unlockOwnParkLocks($, e.cwd) // 0.8.8: /resume of a parked worktree session
       }
       if (!st.sessionId) st.sessionId = e.session_id
       await sendOrSpool($, 'session.started', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftoff/cli",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Leftoff: WTF was I working on? Tracks every Claude Code session, writes a 3-line checkpoint when one goes quiet, and gives you a daily digest and a board, on your Mac and (optionally) your phone.",
   "keywords": [
     "claude",

package/ui/app.js

@@ -3339,7 +3339,7 @@ document.addEventListener('click', async (ev) => {
     if (action === 'resume-open') { const ok = await resumeOpen(btn, btn.dataset.id || id); if (ok && btn.closest('.parked-card')) await render(); return ok }
     if (action === 'unpark') {
       btn.disabled = true
-      try { const r = await api('POST', '/v1/sessions/' + encodeURIComponent(btn.dataset.id || id) + '/park', { done: true }); toast(r.session && r.session.status === 'ended' ? 'Done with it · moved to Closed' : 'No longer parked') } catch (e) { toast(e.message, 5000); btn.disabled = false; return }
+      try { const r = await api('POST', '/v1/sessions/' + encodeURIComponent(btn.dataset.id || id) + '/park', { done: true }); toast((r.session && r.session.status === 'ended' ? 'Done with it · moved to Closed' : 'No longer parked') + (r.worktreeUnlocked ? ' · its worktree is unlocked (still there)' : '')) } catch (e) { toast(e.message, 5000); btn.disabled = false; return }
       return render()
     }
     if (action === 'closed-more') { closedUi.limit += CLOSED_PAGE; btn.disabled = true; try { await closedFetch(state.boardFilter || { repos: [] }, state.boardSpace); closedRepaint() } catch (e) { toast(e.message, 5000) } return }