agentbox-app 0.1.7 → 0.1.12

package/main/store/home.mjs

@@ -15,7 +15,10 @@
 // and repeat rules all sat in it.
 //
 // So this is the same convention, one name over: a dot-folder in her home
-// named after this app.
+// named after this app. On Linux a fresh install does not get that dot-folder,
+// and it does not get a visible folder of the app's name in $HOME. Application
+// data belongs in $XDG_DATA_HOME (see defaultStoreRoot). An existing dot-folder
+// is still read, so a store already on disk is not orphaned.
 //
 // WHAT MOVES AND WHAT DOES NOT, because the line is not "everything of ours".
 // The app's own RECORDS move: the work item ledger, session traces, run
@@ -37,7 +40,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { WAS, envNames, nameSlug, readEnv } from '../../shared/product-name.mjs';
+import { Name, WAS, envNames, nameSlug, readEnv } from '../../shared/product-name.mjs';
 
 const isDir = (dir) => { try { return fs.statSync(dir).isDirectory(); } catch { return false; } };
 
@@ -61,6 +64,25 @@ export function storeRootEnv(storeRoot) {
   return env;
 }
 
+// Where a config that names no store keeps the inbox.
+//
+// macOS, and anything that is not Linux: a folder of the app's name in the
+// home directory. That is the folder this app has used since 2026-09-22.
+// Linux: $XDG_DATA_HOME/<slug>, or ~/.local/share/<slug> when the variable is
+// unset, blank, or not an absolute path. A visible directory in $HOME is not
+// where an application writes. Measured 2026-10-07: a config that named no
+// store created one.
+//
+// The home and the environment are arguments so a test can ask about another
+// machine. A caller that passes a stand-in home must pass an environment that
+// belongs to it. This function does not decide that; it uses the env it is given.
+export function defaultStoreRoot({ home = os.homedir(), platform = process.platform, env = process.env } = {}) {
+  if (platform !== 'linux') return path.join(home, Name);
+  const given = typeof env?.XDG_DATA_HOME === 'string' ? env.XDG_DATA_HOME.trim() : '';
+  const base = given && path.isAbsolute(given) ? given : path.join(home, '.local', 'share');
+  return path.join(base, nameSlug);
+}
+
 // One env var, for tests and for anyone who keeps their home somewhere else.
 // Read at call time rather than captured, because a test sets it per case.
 //
@@ -74,9 +96,10 @@ export function storeRootEnv(storeRoot) {
 // store goes missing on the release that renames the app.
 // `homeDir` is injected so a test can ask what this answers on a machine with
 // an old dot-folder on it, without one having to exist on the machine running
-// the test. Production never passes it.
-export function appHome(homeDir = os.homedir()) {
-  const override = readEnv('HOME');
+// the test. `platform` and `env` are the same kind of injection: this suite
+// runs on a Mac and still has to answer a Linux home. Production passes neither.
+export function appHome(homeDir = os.homedir(), { platform = process.platform, env } = {}) {
+  const override = readEnv('HOME', env);
   if (override) return override;
   const here = path.join(homeDir, `.${nameSlug}`);
   if (isDir(here)) return here;
@@ -84,12 +107,21 @@ export function appHome(homeDir = os.homedir()) {
     const older = path.join(homeDir, `.${was.toLowerCase()}`);
     if (isDir(older)) return older;
   }
+  // A fresh Linux directory has nothing of ours on disk yet. The answer has to
+  // be the same path loadConfig opens, or the desktop and this lookup write two
+  // stores. The machine's own XDG_DATA_HOME is an absolute path in the real
+  // home; applying it to a stand-in home writes that stand-in's store there.
+  // A caller that passes `env` is asking about that environment, not this one.
+  if (platform === 'linux') {
+    const real = env === undefined && path.resolve(homeDir) === path.resolve(os.homedir());
+    return defaultStoreRoot({ home: homeDir, platform: 'linux', env: real ? process.env : (env ?? {}) });
+  }
   return here;
 }
 
 // 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 +335,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/project.mjs

@@ -4,34 +4,30 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import crypto from 'node:crypto';
 import { SCHEMA_VERSION, validateCreation, creationText, TEXT_CREATION_KINDS } from '../../shared/contracts.mjs';
 import { assertInside, assertCreationDir, deniesGitOrEnvPath } from './paths.mjs';
 import { migrateIndex } from './migrate.mjs';
 import { withProjectLockSync } from './project-lock.mjs';
-import { Name, readEnv } from '../../shared/product-name.mjs';
-
-// The machine-wide root: ASTRAL_HOME, else the folder named below. This is
-// where device-local files live (settings.json, ui-state.json, usage.json,
-// .runtime-pids, ...) and where a founder's PRE-account projects sit until they
-// are migrated into an account space. It is NEVER account-scoped: those files
-// stay global (Phase 1).
+import { readEnv } from '../../shared/product-name.mjs';
+import { defaultStoreRoot } from './home.mjs';
+
+// The machine-wide root: the store-home variable, else the same default
+// loadConfig uses when a config names no store. This is where device-local
+// files live (settings.json, ui-state.json, usage.json, .runtime-pids, ...)
+// and where a founder's PRE-account projects sit until they are migrated into
+// an account space. It is NEVER account-scoped: those files stay global
+// (Phase 1).
 //
-// THE FALLBACK IS THE APP'S OWN NAME NOW, where it used to be an older
-// product's folder.
+// THE FALLBACK IS defaultStoreRoot. On macOS that is a folder of the app's
+// name. On Linux it is the XDG data directory. A visible folder in $HOME was
+// the fallback until 2026-10-07, and a config that named no store created one.
 //
-// NOTHING WAS DELETED AND NOTHING MOVED. That folder is still on disk exactly
-// as it was. What changed is that this app stops reaching for it by default.
 // Her live store is named in zero.config.json and handed to every worker as
-// the app's own home variable, so this line was never the path she runs on; it
-// was only ever
-// the answer for an install carrying no config at all.
-//
-// An older product's HOME env var used to sit between these two. It is gone:
-// nothing sets it any more now that the store server carries the app's own name.
+// the app's own home variable, so this line is only ever the answer for an
+// install carrying no config and no store-home variable.
 export function legacyRoot() {
-  return readEnv('HOME') || path.join(os.homedir(), Name);
+  return readEnv('HOME') || defaultStoreRoot();
 }
 
 // The account currently signed in, if any. Set once at boot and re-resolved on

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() };