agentbox-app 0.1.6

package/main/store/migrate.mjs

@@ -0,0 +1,40 @@
+import { SCHEMA_VERSION } from '../../shared/contracts.mjs';
+
+// One-time index.json v1 -> v2: artifacts[] becomes creations[]. Pure and
+// idempotent; readIndex decides whether to write the result back (it writes
+// only when the returned object differs from what was read).
+export function migrateIndex(idx) {
+  const src = idx ?? {};
+  const shaped = (src.schemaVersion === SCHEMA_VERSION && Array.isArray(src.creations))
+    ? src
+    : (() => {
+        const { artifacts, ...rest } = src;
+        return {
+          ...rest,
+          schemaVersion: SCHEMA_VERSION,
+          creations: Array.isArray(src.creations) ? src.creations : (artifacts ?? []),
+          runs: src.runs ?? [], reports: src.reports ?? [],
+          updatedAt: src.updatedAt ?? null,
+        };
+      })();
+  // Lazy cleanups ride the read path:
+  // - Database/deploy summary docs written before 2026-07-11 carried a phantom
+  //   kind 'doc' that was never in CREATION_KINDS; they are markdown.
+  // - One creation represents the whole application (her call, 2026-07-11):
+  //   legacy standalone database viewers (kind 'database') and the sibling
+  //   database/deployment receipt docs tombstone away. Their files stay on
+  //   disk untouched; the live views are the app creation's Data/People
+  //   panes, and receipts now land INSIDE the app creation as DATABASE.md /
+  //   DEPLOYMENT.md the next time provisioning or deploy runs.
+  const phantom = (c) => c?.kind === 'doc';
+  const standalone = (c) => !c?.deleted && (c?.kind === 'database' || c?.meta?.databaseFor != null || c?.meta?.deploymentFor != null);
+  if (!shaped.creations.some((c) => phantom(c) || standalone(c))) return shaped;
+  return {
+    ...shaped,
+    creations: shaped.creations.map((c) => {
+      let next = phantom(c) ? { ...c, kind: 'markdown' } : c;
+      if (standalone(next)) next = { ...next, deleted: true };
+      return next;
+    }),
+  };
+}

package/main/store/paths.mjs

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The .git / .env deny-list, shared by EVERY creation-file access point: the
+// agent tools (main/agent/tools.mjs), the folder-backed materialize walk
+// (main/creations/materialize.mjs, which re-exports these), the creation-file://
+// protocol (main/index.mjs), and the single-file store SINK
+// (readCreationContent/saveCreation in main/store/project.mjs). It lives HERE,
+// the lowest-level path module both store/ and creations/ already import, so
+// there is exactly ONE copy of the rules and no import cycle (store must not
+// import up into creations/). A trailing-segment match on a DIRECTORY named
+// e.g. .env.local blocks everything nested under it, not just a file literally
+// named that.
+export const GIT_PATH_RE = /(^|\/)\.git(\/|$)/;
+export const ENV_PATH_RE = /(^|\/)\.env[^/]*(\/|$)/;
+
+// Deny checks run on a normalized form: backslashes folded to forward slashes
+// (assertInside treats both as separators) and lowercased, so a case-
+// insensitive filesystem (the default on macOS/Windows) can never let
+// `.Git/config` alias the real `.git` past a case-sensitive regex.
+export function normalizeForDenyCheck(rel) {
+  return String(rel).replace(/\\/g, '/').toLowerCase();
+}
+
+// True iff `rel` names a .git or .env path in ANY segment. null/undefined -> false.
+// The single canonical predicate; other modules re-export it rather than
+// duplicating the regexes.
+export function deniesGitOrEnvPath(rel) {
+  if (rel == null) return false;
+  const norm = normalizeForDenyCheck(rel);
+  return GIT_PATH_RE.test(norm) || ENV_PATH_RE.test(norm);
+}
+
+// Containment: resolve rel against root; realpath the nearest EXISTING
+// ancestor so a symlinked directory cannot smuggle the path outside; reject
+// a symlink as the final component (lstat). Throws on any violation, returns
+// the absolute (real-ancestor-based) path on success.
+export function assertInside(root, rel) {
+  if (typeof rel !== 'string' || !rel) throw new Error('empty path');
+  if (path.isAbsolute(rel)) throw new Error(`absolute path rejected: ${rel}`);
+  if (rel.split(/[\\/]/).some((seg) => seg === '..')) throw new Error(`dot-dot rejected: ${rel}`);
+  const realRoot = fs.realpathSync(root);
+  const target = path.resolve(realRoot, rel);
+  // nearest existing ancestor, realpathed, must stay inside
+  let probe = target;
+  while (!fs.existsSync(probe)) probe = path.dirname(probe);
+  const realProbe = fs.realpathSync(probe);
+  if (realProbe !== realRoot && !realProbe.startsWith(realRoot + path.sep)) {
+    throw new Error(`path escapes project: ${rel}`);
+  }
+  try {
+    if (fs.lstatSync(target).isSymbolicLink()) throw new Error(`symlink rejected: ${rel}`);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  return target;
+}
+
+// Same check as a boolean, for canUseTool-style callers.
+export function isInside(root, rel) {
+  try { assertInside(root, rel); return true; } catch { return false; }
+}
+
+// A folder-backed creation's `dir` must be a real, non-empty subdirectory of
+// creations/ (creations/<slug>), NEVER the creations root itself
+// (dir: "creations", "creations/", "creations/.", ...) or some other project
+// subtree (a run directory, the project root, ...). plain assertInside alone
+// is not enough here: it only proves `dir` does not escape the PROJECT, not
+// that it is a legitimate creation root, and every consumer that trusts
+// envelope.dir as a creation root (read/write/list/delete a file inside it)
+// must reject a bad one itself, not rely on validation having already run
+// once when the envelope was first cataloged. A stale or externally-supplied
+// envelope (e.g. merged in from a sync peer, or written before this check
+// existed) must never grant access outside its own creation folder.
+export function assertCreationDir(root, dir) {
+  const rel = String(dir ?? '').replace(/\\/g, '/');
+  const segments = rel.split('/').filter(Boolean);
+  if (segments[0] !== 'creations' || segments.length < 2 || segments[1] === '.' || segments[1] === '..') {
+    throw new Error(`unsafe creation dir (must be a real subdirectory of creations/): ${dir}`);
+  }
+  return assertInside(root, rel);
+}

package/main/store/pending-writes.mjs

@@ -0,0 +1,122 @@
+// A write the ledger refused, kept on disk until somebody delivers it.
+//
+// The claim fence is right and stays: a worker whose lease has lapsed must not
+// stamp over whoever picked the row up next. What was wrong is what happened
+// after the refusal, which was nothing. The write was thrown away, the session
+// usually ended on that call, and neither the founder nor the agent ever learned
+// a message had existed. Measured across 3,191 worker transcripts on this
+// machine between 2 and 24 August 2026: 233 writes refused for a lapsed claim,
+// 50 of them never landed on the row by any route, carrying 101,606 characters
+// of finished notes and results. Half were the session's closing message.
+//
+// So a refused write is parked here instead, and the next session to claim that
+// row is handed it. Parking is deliberately NOT delivery: writing it onto the
+// row behind the fence would be the overwrite the fence exists to stop. The
+// message waits for someone who legitimately holds the claim to decide what of
+// it is still true.
+//
+// One file per refused write, in the app's own home, because a home survives a
+// reboot and /tmp does not. It used to be the product's own folder, which
+// survives one just as well and is also the worker's working directory
+// (main/store/home.mjs).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineryPath } from './home.mjs';
+import { isWorkItemId } from '../../shared/work-items.mjs';
+
+const DIR = 'pending-writes';
+// Delivered messages move here rather than being deleted: the next session
+// after that one should not be handed a message already carried, and nothing
+// about this should ever be the reason something becomes unrecoverable.
+const COLLECTED = 'collected';
+
+// A holder id reaches us from an MCP client and ends up in a filename.
+function safeHolder(holder) {
+  return String(holder ?? 'unknown').replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 40) || 'unknown';
+}
+
+// In the app's home beside the ledger, not in the product folder. The reason
+// the header gives still holds — this must survive a reboot and /tmp does not —
+// and `~/.astral` survives one exactly as well (main/store/home.mjs).
+function itemDir(projectDir, id) {
+  if (!isWorkItemId(id)) throw new Error(`invalid work item id: ${id}`);
+  return machineryPath(projectDir, path.join(DIR, id));
+}
+
+/**
+ * Keep a refused write. Returns where it went, so the caller can say so in the
+ * error it raises: an agent that is told its message survived and where can
+ * re-claim and re-send, which is the whole difference between a lost night and
+ * a retry.
+ */
+export function parkPendingWrite(projectDir, id, patch, { holder, epoch = null, reason = '', now = Date.now() } = {}) {
+  const dir = itemDir(projectDir, id);
+  fs.mkdirSync(dir, { recursive: true });
+  const name = `${now}-${safeHolder(holder)}.json`;
+  const file = path.join(dir, name);
+  const record = {
+    item: id,
+    ts: now,
+    writtenAt: new Date(now).toISOString(),
+    holder: holder ?? null,
+    epoch,
+    refusedBecause: reason,
+    patch: patch ?? {},
+  };
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 1)}\n`, 'utf8');
+  return { ...record, file, relPath: path.join(DIR, id, name) };
+}
+
+/** Every write still waiting on this row, oldest first. */
+export function readPendingWrites(projectDir, id) {
+  let dir;
+  try { dir = itemDir(projectDir, id); } catch { return []; }
+  let names = [];
+  try {
+    names = fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.json'))
+      .map((e) => e.name);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const name of names.sort()) {
+    let record = null;
+    try { record = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')); } catch { continue; }
+    if (!record || typeof record !== 'object') continue;
+    out.push({ ...record, file: path.join(dir, name), relPath: path.join(DIR, id, name) });
+  }
+  return out.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+}
+
+/**
+ * Mark everything waiting on this row as delivered, by the session that was
+ * handed it. Called when that session actually writes to the row: it has been
+ * given the message and has now spoken, so a third session must not be handed
+ * the same words again. The files move rather than vanish.
+ */
+export function collectPendingWrites(projectDir, id, { by = null, now = Date.now() } = {}) {
+  const waiting = readPendingWrites(projectDir, id);
+  if (!waiting.length) return [];
+  const dir = itemDir(projectDir, id);
+  const done = path.join(dir, COLLECTED);
+  fs.mkdirSync(done, { recursive: true });
+  const moved = [];
+  for (const record of waiting) {
+    const target = path.join(done, path.basename(record.file));
+    try {
+      fs.writeFileSync(record.file, `${JSON.stringify({ ...stripPaths(record), collectedBy: by, collectedAt: new Date(now).toISOString() }, null, 1)}\n`, 'utf8');
+      fs.renameSync(record.file, target);
+      moved.push(target);
+    } catch { /* a message we cannot move is left where it is, which is safe */ }
+  }
+  return moved;
+}
+
+function stripPaths({ file, relPath, ...rest }) {
+  return rest;
+}
+
+export const _internals = { DIR, COLLECTED, itemDir };

package/main/store/project-lock.mjs

@@ -0,0 +1,200 @@
+// A cross-process advisory lock, one per project.
+//
+// Why this exists: main/store/write-queue.mjs serializes catalog writes inside
+// ONE process, which was the whole world when the only writer was the app's
+// main process. It is not the world any more. Stateless wake-ups mean a dozen
+// MCP server children can be live at once, each against the same store, and
+// an in-process promise chain says nothing about any of them. readIndex ->
+// mutate -> atomicWriteJson across two processes is a lost update: both read
+// revision N, both write, one document silently vanishes from the catalog.
+// atomicWriteJson is atomic per write (tmp + rename); it is not a
+// compare-and-swap, and nothing in the store ever pretended otherwise.
+//
+// The mechanism is the oldest one there is: create a file with O_EXCL, which
+// the kernel guarantees will succeed for exactly one caller.
+//
+// THE HARD PART IS NOT TAKING THE LOCK, IT IS BREAKING A STALE ONE. A holder
+// can die without releasing (crash, SIGKILL, a laptop lid), so a lock nobody
+// holds must eventually be breakable or the store wedges silently, which is the
+// expensive failure. But the obvious test, "is the holder's pid alive", is a
+// HINT AND NOT PROOF: pids get recycled, so an unrelated process inheriting a
+// dead holder's number would keep a lock alive forever, and the wedge is
+// permanent and invisible. So:
+//
+//   - a random token, not the pid, is what identifies a holder
+//   - a conservative timeout is the real arbiter of staleness
+//   - the pid check is used only in the direction it is sound: a pid that is
+//     GONE proves the holder is gone (that lock can be broken early). A pid
+//     that is alive proves nothing and buys no extra time.
+//   - critical sections stay tiny (read, mutate, rename, release) so the window
+//     in which a wrongly-broken lock could matter is measured in milliseconds
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// How long a lock may be held before another process may break it. Far longer
+// than any legitimate critical section here (all of which are a read, a JSON
+// mutate, and a rename) and far shorter than a founder would tolerate a wedge.
+export const STALE_MS = 30_000;
+// Total time to wait for a contended lock before giving up. A dozen writers
+// queueing on sub-millisecond sections never comes close to this.
+const ACQUIRE_TIMEOUT_MS = 15_000;
+// Backoff between attempts: fast at first (the common case is microseconds of
+// contention), then easing off so a genuinely stuck lock is not spun on.
+const BACKOFF_MS = [1, 2, 5, 10, 20, 50, 100, 200];
+
+const lockPath = (projectDir) => path.join(projectDir, '.lock');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Is this pid gone? Signal 0 checks existence without delivering anything.
+// Only the FALSE answer here is trustworthy (see the header): a live pid may be
+// a recycled number, but a missing one is definitely not our holder.
+function pidGone(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try { process.kill(pid, 0); return false; } catch (err) { return err.code === 'ESRCH'; }
+}
+
+function readHolder(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Try once. Returns the token on success, null if someone else holds it.
+function tryAcquire(file, label) {
+  const token = crypto.randomBytes(12).toString('hex');
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const fd = fs.openSync(file, 'wx'); // O_CREAT | O_EXCL: exactly one winner
+    try {
+      fs.writeSync(fd, JSON.stringify({ token, pid: process.pid, at: Date.now(), label }));
+    } finally {
+      fs.closeSync(fd);
+    }
+    return token;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    return null;
+  }
+}
+
+// Break a lock that is provably or presumptively abandoned. The token check is
+// what makes this safe against the race with a legitimate holder releasing at
+// the same moment: we only unlink the exact holder we decided was stale, so a
+// fresh lock taken in between survives.
+function breakIfStale(file, now = Date.now()) {
+  const held = readHolder(file);
+  if (!held) {
+    // Unreadable or truncated: a torn write from a holder that died mid-create.
+    // Age it out rather than trusting a file we cannot parse.
+    try {
+      const age = now - fs.statSync(file).mtimeMs;
+      if (age > STALE_MS) fs.unlinkSync(file);
+    } catch { /* already gone; someone else won the break */ }
+    return;
+  }
+  const expired = !Number.isFinite(held.at) || (now - held.at) > STALE_MS;
+  const dead = pidGone(held.pid);
+  if (!expired && !dead) return;
+
+  // Re-read immediately before unlinking and confirm it is still the same
+  // holder. Without this, breaking a stale lock could delete a brand new one
+  // taken microseconds earlier by a healthy process.
+  const still = readHolder(file);
+  if (still?.token !== held.token) return;
+  try { fs.unlinkSync(file); } catch { /* someone else broke it first */ }
+}
+
+function release(file, token) {
+  const held = readHolder(file);
+  // Only ever release OUR lock. If the token differs, ours was already broken
+  // as stale and someone else legitimately holds it now; unlinking would evict
+  // an innocent holder.
+  if (held && held.token !== token) return false;
+  try { fs.unlinkSync(file); return true; } catch { return false; }
+}
+
+/**
+ * Run `fn` holding the project's lock. Cross-process safe.
+ *
+ * Keep the body SHORT: a read, a mutate, a rename. Never await network, never
+ * spawn, never call another locked helper (the lock is not reentrant, and a
+ * nested acquire would deadlock against itself until the stale timeout).
+ */
+export async function withProjectLock(projectDir, fn, { label = '', timeoutMs = ACQUIRE_TIMEOUT_MS } = {}) {
+  const file = lockPath(projectDir);
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+
+  for (;;) {
+    const token = tryAcquire(file, label);
+    if (token) {
+      try {
+        return await fn();
+      } finally {
+        release(file, token);
+      }
+    }
+
+    breakIfStale(file);
+    if (Date.now() >= deadline) {
+      const held = readHolder(file);
+      throw new Error(
+        `could not lock ${projectDir} within ${timeoutMs}ms` +
+        (held ? ` (held by pid ${held.pid}${held.label ? ` for ${held.label}` : ''} since ${new Date(held.at).toISOString()})` : ''),
+      );
+    }
+    await sleep(BACKOFF_MS[Math.min(attempt++, BACKOFF_MS.length - 1)]);
+  }
+}
+
+// A real blocking sleep, for the synchronous variant below. Atomics.wait on a
+// buffer nobody will ever notify parks the thread for the duration instead of
+// spinning the CPU, which a busy loop would do.
+const PARK = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+  Atomics.wait(PARK, 0, 0, ms);
+}
+
+/**
+ * The synchronous twin, for callers that cannot become async.
+ *
+ * This exists for exactly one reason: index.json's read-modify-write lives in
+ * updateIndex, which is synchronous and is called from roughly thirty places
+ * across the app. Making it async would ripple through all of them for no
+ * benefit, and a half-migrated version of that ripple is a worse risk than a
+ * blocking wait measured in milliseconds.
+ *
+ * It blocks the event loop while waiting, so the same rule as the async version
+ * applies with more force: KEEP THE BODY SHORT. Read, mutate, rename. Never do
+ * IO that can hang here.
+ */
+export function withProjectLockSync(projectDir, fn, { label = '', timeoutMs = ACQUIRE_TIMEOUT_MS } = {}) {
+  const file = lockPath(projectDir);
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+
+  for (;;) {
+    const token = tryAcquire(file, label);
+    if (token) {
+      try {
+        return fn();
+      } finally {
+        release(file, token);
+      }
+    }
+
+    breakIfStale(file);
+    if (Date.now() >= deadline) {
+      const held = readHolder(file);
+      throw new Error(
+        `could not lock ${projectDir} within ${timeoutMs}ms` +
+        (held ? ` (held by pid ${held.pid}${held.label ? ` for ${held.label}` : ''} since ${new Date(held.at).toISOString()})` : ''),
+      );
+    }
+    sleepSync(BACKOFF_MS[Math.min(attempt++, BACKOFF_MS.length - 1)]);
+  }
+}
+
+// Exported for tests and for a diagnostic surface; not part of normal use.
+export const _internals = { lockPath, readHolder, breakIfStale, tryAcquire, release, pidGone };