agentbox-app 0.1.7 → 0.1.11

package/main/sign-in-files.mjs

@@ -0,0 +1,39 @@
+// THE FILES A LOGIN WRITES, SO THE APP CAN SEE ONE LAND.
+//
+// A signed-out account used to sit out a fixed half hour, and nothing but a
+// session surviving on it could bring it back, which no session could do while
+// it sat out. So typing /login fixed nothing a person could see: their agents
+// stayed "Queued" until the half hour ran out on its own, and a /login and any
+// "continue" replies in between did nothing.
+//
+// A login rewrites these. Only their modification times are read, never their
+// contents: what is in them is her credentials and is none of our business.
+// A moved time is a reason to TRY again, not proof; the try is the proof.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where one account's login is written.
+ *  - Claude Code, its default login: `~/.claude.json` (where the CLI keeps the
+ *    account it is signed in as) and the same files inside `~/.claude`.
+ *  - Claude Code, a CLAUDE_CONFIG_DIR: those files inside that folder.
+ *  - Codex: `auth.json` inside its CODEX_HOME.
+ */
+export function signInFiles({ engine = 'claude', folder = null, home }) {
+  if (engine === 'codex') return folder ? [path.join(folder, 'auth.json')] : [];
+  if (!folder) {
+    const dir = path.join(home, '.claude');
+    return [path.join(home, '.claude.json'), path.join(dir, '.claude.json'), path.join(dir, '.credentials.json')];
+  }
+  return [path.join(folder, '.claude.json'), path.join(folder, '.credentials.json')];
+}
+
+/** The newest modification time among them, or 0 when none can be read. */
+export function signInStamp(files, stat = fs.statSync) {
+  let newest = 0;
+  for (const f of files ?? []) {
+    try { newest = Math.max(newest, stat(f).mtimeMs); } catch {}
+  }
+  return newest;
+}

package/main/source-updater.mjs

@@ -0,0 +1,298 @@
+// A COPY RUN FROM SOURCE KEEPS ITSELF CURRENT TOO (w-7a39dace23, 2026-10-01).
+//
+// Teammates run the team build from a git checkout (docs/team/PLAN.md), and
+// main/updater.mjs cannot help them: electron-updater reads published releases
+// and does nothing at all unpackaged. Their updates are pushes to main, several
+// a day, so this watches the branch instead of a release feed.
+//
+// WHAT IT DOES. A few seconds after launch, and then every half hour, it runs
+// `git fetch` and asks whether the branch's upstream is ahead of the code this
+// process booted from. If it is, the state goes to `ready` and the sidebar
+// shows the "New version ready" card (renderer/src/components/SidebarUpdate.tsx),
+// which names what changed when pointed at.
+// Pressing Restart fast-forwards the folder, reinstalls packages only when
+// package.json or the lockfile changed, rebuilds the screens, and relaunches.
+// Nothing happens until that button is pressed.
+//
+// IT NEVER TOUCHES WORK SOMEBODY HAS NOT PUSHED. Four cases get no offer at
+// all, each stated in `error` so Settings can say why: a folder that is not a
+// checkout, a branch that follows nothing, tracked files with edits in them,
+// and a branch with commits of its own. The founder's own app runs from a
+// local branch with no upstream, so it is untouched by this. Untracked files
+// (zero.config.json, cloud/team.config.json) do not count as edits: they are
+// ignored or new, and a fast-forward cannot overwrite them without failing.
+//
+// "AHEAD OF WHAT IS RUNNING", NOT "AHEAD OF THE FOLDER". The code in memory is
+// what booted, so the folder brought up to date by hand without a restart is
+// still an update waiting, and the row says so.
+//
+// IF THE BUILD FAILS IT DOES NOT RESTART. The row comes back with what went
+// wrong, and pressing Restart again retries from where it stopped. Restarting
+// onto screens that did not build would be the one outcome worse than waiting.
+
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { describe } from './updater.mjs';
+
+const FIRST_CHECK_MS = 20_000;
+const EVERY_MS = 30 * 60 * 1000;
+const FETCH_MS = 60_000;
+const INSTALL_MS = 10 * 60 * 1000;
+const BUILD_MS = 5 * 60 * 1000;
+// How many change titles the row lists. The rest are counted, not named.
+const LISTED = 5;
+
+const SAY = {
+  notRepo: 'This folder is not a git checkout, so it does not update itself.',
+  noUpstream: 'This copy\'s branch does not follow a branch on GitHub, so it does not update itself.',
+  dirty: 'This folder has changes of your own in it, so it does not update itself.',
+  diverged: 'This copy has commits of its own, so it does not update itself.',
+  offline: 'Could not reach GitHub.',
+};
+
+// A FILE THE BUILD WRITES IS NOT AN EDIT OF HERS (2026-10-02). `npm run build`
+// rewrites shared/*.generated.mjs with the version and date of the Claude Code
+// on this Mac, and the restart below runs that build. Counted as her changes,
+// they made every update after the first say "changes of your own" for good
+// (tests/a-build-does-not-stop-the-next-update.test.mjs).
+const isBuildOutput = (file) => /^shared\/[^/]+\.generated\.[cm]?[jt]s$/.test(file);
+// The status code is one or two letters and `gitIn` trims the output, which
+// takes the leading space off the first line, so it is matched, not sliced.
+const changedPaths = (porcelain) => String(porcelain ?? '').split('\n').filter(Boolean).map((l) => l.replace(/^[ MADRCUT?!]{1,2} /, '').replace(/^"|"$/g, ''));
+const theirEdits = (porcelain) => changedPaths(porcelain).filter((f) => !isBuildOutput(f));
+
+function gitIn(appDir) {
+  return (args, { timeout = 30_000 } = {}) => new Promise((resolve) => {
+    execFile('git', args, {
+      cwd: appDir,
+      timeout,
+      // Never a password prompt from a background check. The repository is
+      // public; anything that asks for credentials is a failure to report.
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      maxBuffer: 4 * 1024 * 1024,
+    }, (err, stdout, stderr) => {
+      resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, out: String(stdout).trim(), err: String(stderr).trim() });
+    });
+  });
+}
+
+function collect(bin, args, { cwd, timeout }) {
+  return new Promise((resolve) => {
+    let out = '';
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: 1, out: String(e?.message ?? e) });
+      return;
+    }
+    const keep = (b) => { out = (out + b).slice(-64 * 1024); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => { keep('\nerror: timed out'); child.kill('SIGTERM'); }, timeout);
+    child.on('error', (e) => { keep(`\nerror: ${e.message}`); });
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code: code ?? 1, out }); });
+  });
+}
+
+// WHICH npm. Started with `npm start`, the process carries npm's own path in
+// its environment, so that one is used and nvm or a version manager never
+// matters. Started any other way, her login shell is asked, the way
+// main/claude-bin.mjs finds Claude Code. The arguments are fixed strings from
+// this file, never anything read from disk.
+export function defaultNpm(appDir, env = process.env) {
+  return (args) => {
+    const timeout = args[0] === 'install' ? INSTALL_MS : BUILD_MS;
+    const node = env.npm_node_execpath;
+    const cli = env.npm_execpath;
+    if (node && cli && fs.existsSync(node) && fs.existsSync(cli)) {
+      return collect(node, [cli, ...args], { cwd: appDir, timeout });
+    }
+    const shell = env.SHELL || '/bin/zsh';
+    return collect(shell, ['-lic', `npm ${args.join(' ')}`], { cwd: appDir, timeout });
+  };
+}
+
+// The line of a failed build worth showing a person: the first that says
+// error, else the last thing it printed.
+export function failureLine(out) {
+  const lines = String(out ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const named = lines.find((l) => /error/i.test(l));
+  const line = named ?? lines[lines.length - 1] ?? 'it stopped without saying why';
+  return line.length > 160 ? `${line.slice(0, 157)}…` : line;
+}
+
+export function createSourceUpdater({
+  appDir,
+  app = null,
+  log = console,
+  onChanged = () => {},
+  npm = defaultNpm(appDir),
+  relaunch = () => { app?.relaunch(); app?.quit(); },
+} = {}) {
+  const git = gitIn(appDir);
+  // The commit this process booted from. Read once, now, because it is the
+  // code in memory and nothing on disk can change that.
+  let bootHead = null;
+  try {
+    bootHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { /* not a checkout; check() says so */ }
+
+  let state = {
+    phase: 'idle',
+    source: true,
+    currentVersion: bootHead ? bootHead.slice(0, 7) : null,
+    newVersion: null,
+    percent: null,
+    error: null,
+    checkedAt: null,
+    readyAt: null,
+    changes: [],
+    behind: null,
+  };
+  let timer = null;
+  let stopped = false;
+  let pending = Promise.resolve();
+
+  const set = (next) => {
+    state = { ...state, ...next };
+    try { onChanged(describe(state)); } catch {}
+  };
+
+  // Everything that has to be true before an update is offered or applied.
+  // Returns the upstream commit, or the sentence saying why not.
+  async function preconditions() {
+    if (!bootHead) return { why: SAY.notRepo };
+    const upstream = await git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+    if (upstream.code !== 0) return { why: SAY.noUpstream };
+    const dirty = await git(['status', '--porcelain', '--untracked-files=no']);
+    if (dirty.code !== 0 || theirEdits(dirty.out).length) return { why: SAY.dirty };
+    const ahead = await git(['merge-base', '--is-ancestor', 'HEAD', '@{u}']);
+    if (ahead.code !== 0) return { why: SAY.diverged };
+    const up = await git(['rev-parse', '@{u}']);
+    if (up.code !== 0 || !up.out) return { why: SAY.noUpstream };
+    return { up: up.out };
+  }
+
+  async function check() {
+    if (stopped) return describe(state);
+    if (state.phase === 'checking' || state.phase === 'installing') return describe(state);
+    if (!bootHead) {
+      set({ phase: 'unsupported', error: SAY.notRepo, checkedAt: Date.now() });
+      return describe(state);
+    }
+    const was = state;
+    set({ phase: 'checking' });
+    // A failed fetch is not the end of the check: what was fetched before is
+    // still on disk, and an update already found stays offered on a plane.
+    const fetched = await git(['fetch', '--quiet'], { timeout: FETCH_MS });
+    if (fetched.code !== 0) log.warn?.('[source-updater] fetch failed:', fetched.err.split('\n')[0]);
+    const ok = await preconditions();
+    if (ok.why) {
+      set({ phase: 'unsupported', error: ok.why, newVersion: null, changes: [], behind: null, readyAt: null, checkedAt: Date.now() });
+      return describe(state);
+    }
+    if (ok.up === bootHead) {
+      set(fetched.code === 0
+        ? { phase: 'current', error: null, newVersion: null, changes: [], behind: null, readyAt: null, checkedAt: Date.now() }
+        : { phase: 'error', error: SAY.offline, checkedAt: Date.now() });
+      return describe(state);
+    }
+    const range = `${bootHead}..${ok.up}`;
+    const titles = await git(['log', '--no-merges', '--format=%s', `-n${LISTED}`, range]);
+    const count = await git(['rev-list', '--no-merges', '--count', range]);
+    const newVersion = ok.up.slice(0, 7);
+    set({
+      phase: 'ready',
+      newVersion,
+      changes: titles.code === 0 && titles.out ? titles.out.split('\n') : [],
+      behind: count.code === 0 ? Number(count.out) || 0 : null,
+      // Stamped when THIS version was first seen, so a recheck does not make
+      // old news young again, and a newer push does.
+      readyAt: was.phase === 'ready' && was.newVersion === newVersion && was.readyAt ? was.readyAt : Date.now(),
+      // A failed earlier restart keeps saying so until the next press.
+      error: was.phase === 'ready' && was.newVersion === newVersion ? was.error : null,
+      checkedAt: Date.now(),
+    });
+    return describe(state);
+  }
+
+  async function apply() {
+    const ok = await preconditions();
+    if (ok.why) {
+      set({ phase: 'unsupported', error: ok.why, newVersion: null, changes: [], behind: null, readyAt: null });
+      return;
+    }
+    const head = await git(['rev-parse', 'HEAD']);
+    // What the last build stamped goes back first, so the fast-forward can
+    // never trip on it. The build below writes it again.
+    const stamped = await git(['status', '--porcelain', '--untracked-files=no']);
+    const buildOutput = stamped.code === 0 ? changedPaths(stamped.out).filter(isBuildOutput) : [];
+    if (buildOutput.length) await git(['checkout', '--', ...buildOutput]);
+    if (head.out !== ok.up) {
+      const merged = await git(['merge', '--ff-only', '--quiet', '@{u}']);
+      if (merged.code !== 0) {
+        set({ phase: 'ready', error: `Could not bring the new code in: ${failureLine(merged.err || merged.out)}` });
+        return;
+      }
+    }
+    // Packages changed when either file's object id moved. Compared by id
+    // rather than by asking git for a diff, which this process does in exactly
+    // one file (tests/the-old-git-diff-screen-stays-gone.test.mjs).
+    let depsMoved = false;
+    for (const file of ['package.json', 'package-lock.json']) {
+      const was = await git(['rev-parse', '--verify', '--quiet', `${bootHead}:${file}`]);
+      const now = await git(['rev-parse', '--verify', '--quiet', `HEAD:${file}`]);
+      if (was.out !== now.out) depsMoved = true;
+    }
+    if (depsMoved) {
+      const installed = await npm(['install', '--no-audit', '--no-fund']);
+      if (installed.code !== 0) {
+        set({ phase: 'ready', error: `The new packages would not install: ${failureLine(installed.out)}` });
+        return;
+      }
+    }
+    const built = await npm(['run', 'build']);
+    if (built.code !== 0) {
+      set({ phase: 'ready', error: `The new code would not build: ${failureLine(built.out)}` });
+      return;
+    }
+    log.info?.('[source-updater] built', state.newVersion, '- relaunching');
+    relaunch();
+  }
+
+  // THE BUTTON. Returns at once; the work takes about a minute and the row
+  // says "Updating" while it runs.
+  function install() {
+    if (stopped || state.phase !== 'ready') return false;
+    set({ phase: 'installing', error: null });
+    pending = apply().catch((e) => {
+      set({ phase: 'ready', error: `The update stopped: ${failureLine(e?.message ?? e)}` });
+    });
+    return true;
+  }
+
+  function start() {
+    if (stopped || timer) return;
+    const tick = () => { void check(); };
+    setTimeout(tick, FIRST_CHECK_MS).unref?.();
+    timer = setInterval(tick, EVERY_MS);
+    timer.unref?.();
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) clearInterval(timer);
+    timer = null;
+  }
+
+  return {
+    start,
+    stop,
+    check: () => check(),
+    install,
+    state: () => describe(state),
+    // For tests: resolves when a started install has finished, either way.
+    settled: () => pending,
+  };
+}

package/main/store/home.mjs

@@ -88,8 +88,8 @@ export function appHome(homeDir = os.homedir()) {
 }
 
 // Claude Code's own encoding, checked against a real folder on her Mac:
-// `/Users/you/Zero/accounts/b482f.../agentbox` becomes
-// `-Users-you-Zero-accounts-b482f...-agentbox`. Every character that is not
+// `/Users/you/Zero/accounts/00000.../agentbox` becomes
+// `-Users-you-Zero-accounts-00000...-agentbox`. Every character that is not
 // a letter or a digit becomes a dash, which is readable at a glance and safe on
 // every filesystem.
 export function encodeProjectPath(dir) {
@@ -303,6 +303,51 @@ export function machineryPath(projectDir, rel, home = appHome()) {
   return target;
 }
 
+/**
+ * RECORDS A COPY WROTE UNDER THE WRONG HOME, CARRIED TO ITS OWN.
+ *
+ * The headless door (main/serve.mjs) used to open the store without pointing
+ * the app's home at `storeRoot`, so it wrote its ledgers under whatever home it
+ * inherited: `~/.agentbox` for `npx agentbox-app`, and on the test Mac
+ * 2026-10-01 the founder's own store, because the copies were started from an
+ * agent session. Its workers were handed `storeRoot`, found nothing there, and
+ * answered "no work item" to every store call. Pointing the home at `storeRoot`
+ * fixes the next write; this is what keeps the rows already written from
+ * vanishing on the first boot after the fix.
+ *
+ * ONLY WHAT IS PROVABLY THIS STORE'S MOVES. A machinery directory names the
+ * product it belongs to in `.origin`; one is carried only when that product is
+ * inside `storeRoot`. Everything else under `fromHome` is somebody else's
+ * store and is not touched. Each record goes through `foldStray`, so a ledger
+ * is appended rather than overwritten and nothing is ever destroyed; the old
+ * directory is removed only once nothing but its marker is left in it.
+ *
+ * Returns the product folders whose records were carried.
+ */
+export function carryMisplacedMachinery(fromHome, storeRoot, toHome = storeRoot) {
+  if (!fromHome || !storeRoot) return [];
+  const from = path.resolve(fromHome);
+  if (from === path.resolve(toHome)) return [];
+  const inside = path.resolve(storeRoot) + path.sep;
+  let names = [];
+  try { names = fs.readdirSync(path.join(from, 'projects')); } catch { return []; }
+  const carried = [];
+  for (const name of names) {
+    const dir = path.join(from, 'projects', name);
+    const origin = readOrigin(dir);
+    if (!origin || !path.resolve(origin).startsWith(inside)) continue;
+    const target = ensureMachineryDir(origin, toHome);
+    for (const rel of MACHINERY) foldStray(path.join(dir, rel), path.join(target, rel), rel);
+    let left = [];
+    try { left = fs.readdirSync(dir); } catch { /* gone already */ }
+    if (left.length === 1 && left[0] === ORIGIN) {
+      try { fs.rmSync(path.join(dir, ORIGIN)); fs.rmdirSync(dir); } catch { /* best effort */ }
+    }
+    carried.push(origin);
+  }
+  return carried;
+}
+
 /**
  * EVERY RECORD OF OURS FOR ONE PROJECT, GONE.
  *

package/main/store/work-items.mjs

@@ -18,7 +18,7 @@ import crypto from 'node:crypto';
 import { machineryPath } from './home.mjs';
 import { withProjectLock } from './project-lock.mjs';
 import {
-  foldWorkItems, buildLine, buildClaimLine, buildHeartbeatLine, buildReleaseLine,
+  foldWorkItems, normalizeLine, buildLine, buildClaimLine, buildHeartbeatLine, buildReleaseLine,
   isClaimable, sortForPull, matchesFilter, isWorkItemId, MAX_LINE_BYTES, LEASE_MS,
 } from '../../shared/work-items.mjs';
 
@@ -47,7 +47,29 @@ function ledgerPath(projectDir) {
 // and the result is two corrupted records rather than one. A short write means
 // the guarantee did not hold, so it throws rather than leaving a half line for
 // the fold to skip and the founder to never hear about.
+// WHO IS WRITING, on a Mac someone has signed in on (the team version).
+//
+// Main sets it on sign-in. The store's MCP server is another process, so it
+// reads AGENTBOX_PERSON_ID, which the supervisor hands it. With neither, no line
+// is stamped and the single-person app writes exactly what it always wrote.
+let lineAuthor = null;
+export function setLineAuthor(personId) {
+  lineAuthor = typeof personId === 'string' && personId ? personId : null;
+}
+function currentAuthor() {
+  return lineAuthor ?? (process.env.AGENTBOX_PERSON_ID || null);
+}
+const newLineUid = () => `l-${crypto.randomBytes(8).toString('hex')}`;
+
 function appendLine(file, obj) {
+  const author = currentAuthor();
+  // `by` and `uid` are added here, the one place every line passes, so no
+  // writer can forget them. A line that already carries them keeps its own.
+  const line = author ? { ...obj, by: obj.by ?? author, uid: obj.uid ?? newLineUid() } : obj;
+  return writeLine(file, line);
+}
+
+function writeLine(file, obj) {
   const buf = Buffer.from(JSON.stringify(obj) + '\n', 'utf8');
   if (buf.length > MAX_LINE_BYTES) throw new Error(`work item line too large (${buf.length} bytes, max ${MAX_LINE_BYTES})`);
   fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -136,7 +158,7 @@ function foldedLedger(file) {
   // Time zero, so the lease pass inside the fold expires nothing: a lease is
   // only ever lapsed against the clock of the call asking, and that is `aged`.
   const items = stamp === 'absent' ? new Map() : foldWorkItems(readLines(file), 0);
-  // One entry per ledger, so on her Mac this is 33 of them. The cap is for the
+  // One entry per ledger, so a real store has a few dozen. The cap is for the
   // long-lived MCP server, which walks temporary project dirs that never come
   // back; a Map iterates in insertion order, so the oldest key goes first.
   if (folded.size >= MAX_FOLDS_HELD) folded.delete(folded.keys().next().value);
@@ -167,6 +189,48 @@ export function readWorkItems(projectDir, now = Date.now()) {
   return out;
 }
 
+/**
+ * THE FINISHED THREADS THE 8 MB READ CUT OFF, read only when somebody asks.
+ *
+ * `readLines` keeps a ledger's trailing 8 MB, so a thread whose lines all came
+ * before that is in no fold, and one whose first lines did is folded without
+ * them (a blank title, the wrong `createdAt`). Measured 2026-10-07
+ * (w-fda2165ec6): 155 finished threads gone and 21 blank on one 12.8 MB
+ * ledger. Her call was that these load as she scrolls rather than up front, so
+ * the snapshot keeps its window and this reads the whole file, once per
+ * change of the file, for the Done and All tabs' next page.
+ *
+ * Finished threads only: this is history, and it is where the tabs that ask
+ * for it go. A ledger that fits in the window has nothing to give.
+ */
+const wholeFolds = new Map();
+export function readOlderWorkItems(projectDir, now = Date.now()) {
+  const file = ledgerPath(projectDir);
+  let size;
+  try { size = fs.statSync(file).size; } catch { return []; }
+  if (size <= MAX_LEDGER_BYTES) return [];
+  const stamp = ledgerStamp(file);
+  let whole = wholeFolds.get(file);
+  if (!whole || whole.stamp !== stamp) {
+    let lines;
+    try { lines = fs.readFileSync(file, 'utf8').split('\n').filter((l) => l && Buffer.byteLength(l, 'utf8') <= MAX_LINE_BYTES); } catch { return []; }
+    // Few ledgers are ever this big; hold the latest fold of each, no more.
+    if (wholeFolds.size >= 8) wholeFolds.delete(wholeFolds.keys().next().value);
+    whole = { stamp, items: foldWorkItems(lines, 0) };
+    wholeFolds.set(file, whole);
+  }
+  const windowed = foldedLedger(file);
+  const out = [];
+  for (const item of whole.items.values()) {
+    if (item.status !== 'done') continue;
+    const seen = windowed.get(item.id);
+    // In the window whole: the snapshot already has it right.
+    if (seen && seen.createdAt === item.createdAt) continue;
+    out.push(aged(item, now));
+  }
+  return out;
+}
+
 /** One work item, or null. */
 export function readWorkItem(projectDir, id, now = Date.now()) {
   if (!isWorkItemId(id)) return null;
@@ -261,10 +325,10 @@ export async function claimWorkItem(projectDir, { id = null, filter = null, hold
       // A LIVE CLAIM OF YOUR OWN IS NOT SOMEBODY ELSE'S. The holder was never
       // compared here, so a session asking for the row it already holds was
       // told "held by another worker" and handed back its own name, and the
-      // only way through was to sit out its own five minute lease. Measured
-      // on, 2026-09-21: she replied at 20:26:52, the session was refused by
-      // its own claim, waited out the lease, and the answer she was waiting
-      // for sat in a parked file. Re-claiming what you hold is a renewal.
+      // only way through was to sit out its own five minute lease: after a
+      // reply, the session was refused by its own claim, waited out the lease,
+      // and the answer the user was waiting for sat in a parked file.
+      // Re-claiming what you hold is a renewal.
       if (item.claim && !item.claimExpired && item.claim.holder !== holder) {
         return { claimed: false, reason: 'held by another worker', heldBy: item.claim.holder };
       }
@@ -295,5 +359,85 @@ export function releaseWorkItem(projectDir, id, { epoch, now = Date.now() } = {}
   return readWorkItem(projectDir, id, now);
 }
 
+// Release only the uninterrupted claim acquired by this run. A tool server
+// may outlive its turn, so process lifetime is not run lifetime. The first
+// claim after the spawn snapshot identifies the holder; same-holder renewals
+// are allowed, but a release or another holder ends this run's ownership.
+export function releaseRunClaim(projectDir, id, { afterEpoch, startedAt, now = Date.now() } = {}) {
+  if (!Number.isFinite(afterEpoch) || !Number.isFinite(startedAt)) return null;
+  const lines = readLines(ledgerPath(projectDir)).map(normalizeLine).filter(line => line?.id === id);
+  const item = foldWorkItems(lines, now).get(id);
+  if (!item?.claim) return item;
+  const claims = lines.filter(line => line.claim && !line.heartbeat && line.epoch > afterEpoch);
+  const first = claims[0];
+  if (!first || first.epoch !== afterEpoch + 1 || first.ts < startedAt) return item;
+  if (claims.some(line => line.claim.holder !== first.claim.holder)) return item;
+  if (lines.some(line => line.release && line.epoch >= first.epoch)) return item;
+  if (item.claim.holder !== first.claim.holder) return item;
+  // A concurrent new claim fences this append out through its newer epoch.
+  return releaseWorkItem(projectDir, id, { epoch: item.epoch, now });
+}
+
+/* ------------------------------ the team sync ----------------------------- */
+// A TEAMMATE'S LINES, PULLED FROM THE CLOUD, ENTER THE LEDGER HERE AND ONLY
+// HERE, which keeps this file the one write path even with several writers on
+// several Macs. Each line goes in verbatim, still its author's, and a line
+// whose uid the ledger already holds is skipped, so pulling the same page twice
+// stores it once. A line with no uid or no writer is refused: nothing could tell
+// it apart on the next pull. So is one too big to write, which used to throw
+// and leave the pull cursor in front of it forever (review, 2026-10-01): a bad
+// line is skipped and the pull moves past it. Returns how many were appended.
+export function appendForeignLines(projectDir, lines) {
+  const file = ledgerPath(projectDir);
+  const have = new Set();
+  for (const text of readLines(file)) {
+    const uid = /"uid":"([^"]+)"/.exec(text)?.[1];
+    if (uid) have.add(uid);
+  }
+  let added = 0;
+  for (const raw of Array.isArray(lines) ? lines : []) {
+    const line = normalizeLine(raw);
+    if (!line || !line.uid || !line.by || have.has(line.uid)) continue;
+    if (Buffer.byteLength(JSON.stringify(raw) + '\n', 'utf8') > MAX_LINE_BYTES) continue;
+    writeLine(file, raw);
+    have.add(line.uid);
+    added += 1;
+  }
+  return added;
+}
+
+// Every line after a byte offset, as written, and where the file ends. The
+// ledger only grows, so an offset is a cursor: sync keeps the one it pushed to
+// and asks from there next time.
+export function readLinesFrom(projectDir, offset = 0) {
+  const file = ledgerPath(projectDir);
+  let size;
+  try { size = fs.statSync(file).size; } catch (err) {
+    if (err.code === 'ENOENT') return { lines: [], end: 0 };
+    throw err;
+  }
+  const start = Math.max(0, Math.min(Number(offset) || 0, size));
+  if (start >= size) return { lines: [], end: size };
+  const fd = fs.openSync(file, 'r');
+  let text;
+  try {
+    const buf = Buffer.allocUnsafe(size - start);
+    const read = fs.readSync(fd, buf, 0, size - start, start);
+    text = buf.toString('utf8', 0, read);
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Stop at the last whole line: a line still being written is read next time.
+  const lastNewline = text.lastIndexOf('\n');
+  if (lastNewline < 0) return { lines: [], end: start };
+  const whole = text.slice(0, lastNewline + 1);
+  const lines = [];
+  for (const piece of whole.split('\n')) {
+    if (!piece || Buffer.byteLength(piece, 'utf8') > MAX_LINE_BYTES) continue;
+    try { lines.push(JSON.parse(piece)); } catch { /* a torn line reads as nothing, as in the fold */ }
+  }
+  return { lines, end: start + Buffer.byteLength(whole, 'utf8') };
+}
+
 export { LEASE_MS };
 export const _internals = { appendLine, readLines, ledgerPath, forgetFolds: () => folded.clear() };