parallelclaw 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 Notable changes to parallelclaw (formerly memex-mvp). Older history lives in the git log.
 
+## 1.1.0 — agent coordination: hardened task ledger + executor + result-routing
+
+The first release where the **coordination layer works end-to-end**: one of your
+agents delegates a task, an always-on agent runs it, and the answer comes back to
+where you asked — riding the existing sync mesh, no new transport.
+
+### Added
+- **`task-claim <id>`** — atomically claim a submitted task for execution (exit 0
+  claimed / 3 not-claimable / 1 error; `--json`). The always-on executor uses it
+  so two pollers never double-run one task. See `docs/design/executor-prompt.md`
+  for the ready-to-paste cron-prompt.
+- **`task-results [--ack] [--json] [--all]`** — results of tasks you delegated,
+  to deliver to your surface. The SessionStart hook now injects a "📥 N results
+  from tasks you delegated" block automatically (Claude Code requester); a
+  Telegram requester's cron DMs them and acks after sending.
+
+### Changed / fixed (ledger correctness — required before unattended execution)
+- **Skew-proof status (#1):** current task state is decided by a monotonic
+  per-task `seq` (then lifecycle-rank → ts → rowid), not wall-clock ts. Clock
+  skew across nodes can no longer regress a `done` back to `working`.
+- **Claim/lock (#3):** optimistic claim resolves concurrent take attempts to one
+  deterministic winner once synced.
+- **#2** a `to:'any'` task lands in every node's inbox (first to claim wins).
+  **#4** unique per-event `msg_id` (no same-ms silent drop). **#5** lifecycle
+  guard (no un-completing a terminal, no regress to submitted). **#6** `done`/
+  `failed` must carry a result.
+
+Deferred: #7 `listTasks` scan-bound + index (perf), #8 excluding `agent-task`
+rows from default search/overview. NL delegate tool (2c) and the Mac headless
+`claude -p` runner (2b) are the next slices.
+
 ## 1.0.0 — rebrand: memex → ParallelClaw
 
 The product is renamed **ParallelClaw** and repositioned from "AI memory" to a

package/ingest.js

@@ -156,7 +156,9 @@ if (subcommand && subcommand !== '--help' && subcommand.startsWith('-') === fals
     // Foreman tracer (v0) — agent-to-agent task ledger (tasks = agent-task messages)
     'task-delegate': async () => (await import('./lib/tasks.js')).cmdTaskDelegate(),
     'task-list':     async () => (await import('./lib/tasks.js')).cmdTaskList(),
+    'task-claim':    async () => (await import('./lib/tasks.js')).cmdTaskClaim(),
     'task-update':   async () => (await import('./lib/tasks.js')).cmdTaskUpdate(),
+    'task-results':  async () => (await import('./lib/tasks.js')).cmdTaskResults(),
     serve: cmdServe, // explicit foreground; same as no-arg
     // All scan / export modes fall through to module-level logic at EOF.
     // cmdServe is a no-op marker so the dispatch doesn't error.

package/lib/cli/index.js

@@ -799,6 +799,14 @@ async function cmdContext(args) {
     pendingTg = listPending();
   } catch (_) { /* ignore */ }
 
+  // Result-routing (Phase 2d): answers to tasks THIS node delegated that are now
+  // terminal and not yet surfaced here — "answer where you asked".
+  let taskResults = [];
+  try {
+    const { listTaskResults } = await import('../tasks.js');
+    taskResults = listTaskResults({ undeliveredOnly: true });
+  } catch (_) { /* ignore */ }
+
   if (opts.json) {
     console.log(JSON.stringify({
       pwd, project, freshness_days: freshnessDays,
@@ -806,6 +814,7 @@ async function cmdContext(args) {
       fuzzy_matches: filteredFuzzy.length,
       conversations: all,
       token_budget: tokenBudget,
+      task_results: taskResults,
       telegram_pending: pendingTg.map((e) => ({
         chat_title: e.chat_title,
         chat_type: e.chat_type,
@@ -846,7 +855,21 @@ async function cmdContext(args) {
     lines.push('');
   }
 
-  if (all.length === 0 && pendingTg.length === 0) {
+  if (taskResults.length > 0) {
+    lines.push(`### 📥 ${taskResults.length} result${taskResults.length === 1 ? '' : 's'} from tasks you delegated`);
+    lines.push('');
+    for (const t of taskResults.slice(0, 10)) {
+      const icon = t.status === 'done' ? '✓' : '✗';
+      lines.push(`- ${icon} **${t.id}** → ${t.to} _(${t.status})_ — ${String(t.prompt || '').slice(0, 70)}`);
+      lines.push(`  - result: ${String(t.result || '').slice(0, 220)}`);
+    }
+    if (taskResults.length > 10) lines.push(`- _… and ${taskResults.length - 10} more (run \`memex-sync task-results\`)_`);
+    lines.push('');
+    lines.push(`**INSTRUCTION FOR THE AGENT:** these are answers to tasks you handed to another of your agents. Surface them to the user briefly, then continue.`);
+    lines.push('');
+  }
+
+  if (all.length === 0 && pendingTg.length === 0 && taskResults.length === 0) {
     lines.push(`_No recent activity in memex for this project (last ${freshnessDays} days)._`);
     lines.push('');
     lines.push(`Path searched: \`${pwd}\``);
@@ -895,6 +918,11 @@ async function cmdContext(args) {
     out += '\n\n_[context truncated — exceeds token budget]_\n';
   }
 
+  // Mark surfaced results delivered so they don't re-show every session. Skip on
+  // --no-ack (preview/testing) — json/help paths returned earlier and never ack.
+  if (taskResults.length > 0 && !(opts.noAck || opts['no-ack'])) {
+    try { const { markResultsDelivered } = await import('../tasks.js'); markResultsDelivered(taskResults.map((t) => t.id)); } catch (_) { /* re-show next time */ }
+  }
   process.stdout.write(out);
 }
 

package/lib/tasks.js

@@ -24,13 +24,31 @@
  */
 
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import Database from 'better-sqlite3';
 
 import { getOrigin } from './config.js';
 
 const SOURCE = 'agent-task';
 const STATUSES = ['submitted', 'working', 'done', 'failed'];
+const TERMINAL = new Set(['done', 'failed']);
+
+// Pick the CURRENT event of a task WITHOUT trusting wall-clock ts — clock skew
+// across nodes regressed state on the live mesh (a 'done' on a fast clock could
+// sort before a later 'working'). Order by the monotonic per-task `seq`, then a
+// lifecycle rank (terminal wins a seq-tie, so a concurrent 'working' can never
+// un-complete a 'done'), then ts, then rowid — a total, deterministic order
+// every node computes identically once synced.
+const STATUS_RANK = { submitted: 0, working: 1, failed: 2, done: 3 };
+function cmpEvent(a, b) {
+  const sa = a.seq ?? 0, sb = b.seq ?? 0;
+  if (sa !== sb) return sa - sb;
+  const ra = STATUS_RANK[a.status] ?? -1, rb = STATUS_RANK[b.status] ?? -1;
+  if (ra !== rb) return ra - rb;
+  if ((a.ts || 0) !== (b.ts || 0)) return (a.ts || 0) - (b.ts || 0);
+  return (a.rowid || 0) - (b.rowid || 0);
+}
 
 function dbPath() {
   const dir = process.env.MEMEX_DIR || join(homedir(), '.memex');
@@ -45,9 +63,12 @@ function openDb() {
 }
 
 /** Append one event row for a task. Returns the row's msg_id. */
-function writeEvent(db, { taskId, status, envelope, text, origin, now }) {
+function writeEvent(db, { taskId, status, seq, envelope, text, origin, now }) {
   const ts = Math.floor(now / 1000);
-  const msgId = `${taskId}.${status}.${now}`;
+  // `seq` makes the id unique per event (fixes the same-status-same-ms silent
+  // INSERT-OR-IGNORE drop); `origin` disambiguates concurrent cross-node writes
+  // at the same seq. Computed once at write time → stable across sync.
+  const msgId = `${taskId}.${seq}.${status}.${origin}.${now}`;
   db.prepare(
     `INSERT OR IGNORE INTO messages
        (source, conversation_id, msg_id, role, sender, text, ts, metadata, origin)
@@ -70,9 +91,9 @@ export function createTask({ prompt, to = 'any', kind = 'general', content = nul
   const id = `t${now.toString(36)}${Math.random().toString(36).slice(2, 6)}`;
   try {
     writeEvent(db, {
-      taskId: id, status: 'submitted', origin: from, now,
+      taskId: id, status: 'submitted', seq: 1, origin: from, now,
       text: String(prompt),
-      envelope: { task_id: id, status: 'submitted', from, to, kind,
+      envelope: { task_id: id, status: 'submitted', seq: 1, from, to, kind,
                   prompt: String(prompt), content: content || null, result: null },
     });
   } finally { if (ownDb) db.close(); }
@@ -91,26 +112,65 @@ export function updateTask(id, status, { result = null, db = null, now = Date.no
   try {
     const prev = latestEvent(db, id);
     if (!prev) throw new Error(`updateTask: no task "${id}"`);
-    const env = { ...prev.envelope, status, result: result ?? prev.envelope.result ?? null };
+    const prevStatus = prev.envelope.status;
+    // #5 lifecycle guard: never un-complete a terminal task, never regress to submitted.
+    if (TERMINAL.has(prevStatus)) throw new Error(`updateTask: task "${id}" is already ${prevStatus} (terminal) — refusing to set ${status}`);
+    if (status === 'submitted') throw new Error(`updateTask: cannot move task "${id}" back to submitted`);
+    // #6 a terminal state must say why/what — no silent empty done/failed.
+    const carried = result ?? prev.envelope.result ?? null;
+    if (TERMINAL.has(status) && !(carried && String(carried).trim())) {
+      throw new Error(`updateTask: '${status}' requires a result — pass { result: "<output or reason>" }`);
+    }
+    const seq = (prev.envelope.seq ?? 0) + 1;
+    const env = { ...prev.envelope, status, seq, result: carried };
     writeEvent(db, {
-      taskId: id, status, origin: getOrigin(), now,
-      text: status === 'done' || status === 'failed' ? (result || '') : (env.prompt || ''),
+      taskId: id, status, seq, origin: getOrigin(), now,
+      text: TERMINAL.has(status) ? (result || carried || '') : (env.prompt || ''),
       envelope: env,
     });
     return env;
   } finally { if (ownDb) db.close(); }
 }
 
-/** Latest event for one task id, or null. Returns { envelope, ts, origin }. */
+/**
+ * Atomically CLAIM a submitted task for execution — prevents double-execution
+ * when several executors/cron-ticks poll the same inbox (#3). Optimistic: write
+ * a 'working' event stamped with my origin, then re-read — I hold the claim only
+ * if the current event is MY working (cmpEvent picks one deterministic winner
+ * across nodes once synced). Returns the working envelope on success, or null if
+ * the task wasn't claimable (already taken / terminal) or another node won.
+ * opts: { db?, now? }.
+ */
+export function claimTask(id, { db = null, now = Date.now() } = {}) {
+  const ownDb = !db;
+  db = db || openDb();
+  try {
+    const me = getOrigin();
+    const prev = latestEvent(db, id);
+    if (!prev) throw new Error(`claimTask: no task "${id}"`);
+    if (prev.envelope.status !== 'submitted') return null; // already working/terminal — not claimable
+    const seq = (prev.envelope.seq ?? 0) + 1;
+    const env = { ...prev.envelope, status: 'working', seq, result: prev.envelope.result ?? null };
+    writeEvent(db, { taskId: id, status: 'working', seq, origin: me, now, text: env.prompt || '', envelope: env });
+    const after = latestEvent(db, id);
+    if (after && after.envelope.status === 'working' && after.origin === me) return after.envelope;
+    return null; // another executor's working won the race
+  } finally { if (ownDb) db.close(); }
+}
+
+/** Current event for one task id, or null. Returns { envelope, ts, origin }. */
 function latestEvent(db, id) {
   const rows = db.prepare(
-    `SELECT metadata, ts, origin FROM messages
-      WHERE source = ? AND conversation_id = ? ORDER BY ts DESC, id DESC LIMIT 1`
+    `SELECT id AS rowid, metadata, ts, origin FROM messages
+      WHERE source = ? AND conversation_id = ? ORDER BY ts ASC, id ASC`
   ).all(SOURCE, `task-${id}`);
-  if (!rows.length) return null;
-  let envelope = {};
-  try { envelope = JSON.parse(rows[0].metadata || '{}'); } catch (_) {}
-  return { envelope, ts: rows[0].ts, origin: rows[0].origin };
+  let best = null;
+  for (const r of rows) {
+    let env; try { env = JSON.parse(r.metadata || '{}'); } catch (_) { continue; }
+    const cand = { envelope: env, ts: r.ts, origin: r.origin, status: env.status, seq: env.seq, rowid: r.rowid };
+    if (!best || cmpEvent(cand, best) > 0) best = cand;
+  }
+  return best ? { envelope: best.envelope, ts: best.ts, origin: best.origin } : null;
 }
 
 /**
@@ -128,17 +188,20 @@ export function listTasks({ forOrigin = null, status = null, mine = false, inbox
     // All events; reduce to latest per task in JS (low volume; robust to
     // cross-node id ordering — we key on logical ts, not local rowid).
     const rows = db.prepare(
-      `SELECT conversation_id, metadata, ts FROM messages
+      `SELECT id AS rowid, conversation_id, metadata, ts FROM messages
         WHERE source = ? ORDER BY ts ASC, id ASC`
     ).all(SOURCE);
     const latest = new Map();
     for (const r of rows) {
       let env; try { env = JSON.parse(r.metadata || '{}'); } catch (_) { continue; }
       if (!env.task_id) continue;
-      latest.set(env.task_id, { ...env, ts: r.ts }); // later rows overwrite → latest wins
+      const cand = { ...env, ts: r.ts, rowid: r.rowid };
+      const cur = latest.get(env.task_id);
+      if (!cur || cmpEvent(cand, cur) > 0) latest.set(env.task_id, cand); // skew-proof: seq, not rowid
     }
     let out = [...latest.values()];
-    if (inbox) out = out.filter((t) => (t.to === me) && t.status === 'submitted');
+    // #2 'any' is a broadcast: it lands in EVERY node's inbox (claim resolves the winner).
+    if (inbox) out = out.filter((t) => (t.to === me || t.to === 'any') && t.status === 'submitted');
     if (mine) out = out.filter((t) => t.from === me);
     if (forOrigin) out = out.filter((t) => t.to === forOrigin || t.from === forOrigin);
     if (status) out = out.filter((t) => t.status === status);
@@ -150,6 +213,48 @@ export function listTasks({ forOrigin = null, status = null, mine = false, inbox
   } finally { if (ownDb) db.close(); }
 }
 
+// ── Result-routing (Phase 2d) ────────────────────────────────────────────────
+// "Answer where you asked": a requester surfaces the results of tasks IT
+// delegated once they're terminal. "Delivered" is per-node UX state (which
+// results this surface already showed) — kept LOCAL in a small JSON file, NOT
+// in the synced ledger (delivery is surface-specific, not task state).
+
+function seenPath() {
+  const dir = process.env.MEMEX_DIR || join(homedir(), '.memex');
+  return join(dir, 'task-results-seen.json');
+}
+function readDelivered() {
+  try { return new Set(JSON.parse(readFileSync(seenPath(), 'utf-8')).delivered || []); }
+  catch (_) { return new Set(); }
+}
+/** Mark task ids as delivered to this node's surface (idempotent). */
+export function markResultsDelivered(ids = []) {
+  if (!ids || !ids.length) return;
+  const set = readDelivered();
+  for (const id of ids) set.add(id);
+  try {
+    const p = seenPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ delivered: [...set] }));
+  } catch (_) { /* best-effort; re-show next time rather than crash */ }
+}
+
+/**
+ * Results to route back to a requester surface: tasks THIS origin delegated
+ * (from === forOrigin) that are now terminal (done/failed), newest-first.
+ * undeliveredOnly drops ids already shown on this node. opts: { forOrigin, undeliveredOnly, db? }.
+ */
+export function listTaskResults({ forOrigin = null, undeliveredOnly = false, db = null } = {}) {
+  const ownDb = !db;
+  db = db || openDb();
+  try {
+    const me = forOrigin || getOrigin();
+    let out = listTasks({ db, limit: 1000 }).filter((t) => t.from === me && TERMINAL.has(t.status));
+    if (undeliveredOnly) { const seen = readDelivered(); out = out.filter((t) => !seen.has(t.id)); }
+    return out;
+  } finally { if (ownDb) db.close(); }
+}
+
 // ── CLI ──────────────────────────────────────────────────────────────────────
 
 function parseFlags(argv) {
@@ -194,6 +299,32 @@ export function cmdTaskUpdate() {
   process.exit(0);
 }
 
+export function cmdTaskClaim() {
+  const args = parseFlags(process.argv.slice(3));
+  const id = (args._ || [])[0];
+  if (!id) {
+    console.error('usage: task-claim <id> [--json]   (atomically take a submitted task for execution)');
+    process.exit(2);
+  }
+  let env;
+  try { env = claimTask(id); }
+  catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+  if (!env) {
+    // exit 3 = "not claimable" (already taken / terminal / lost the race) — the
+    // executor loop should treat this as "skip", NOT an error.
+    if ('--json' in args) console.log(JSON.stringify({ claimed: false, id }));
+    else console.log(`· task ${id} not claimable (already taken or terminal) — skip`);
+    process.exit(3);
+  }
+  if ('--json' in args) { console.log(JSON.stringify({ claimed: true, id, ...env })); process.exit(0); }
+  console.log(`✓ claimed ${id} → working (by ${getOrigin()})`);
+  console.log(`  from ${env.from}  ·  kind: ${env.kind || 'general'}`);
+  console.log(`  prompt: ${env.prompt || ''}`);
+  if (env.content) console.log(`  content: ${env.content}`);
+  console.log(`  on finish: task-update ${id} done --result "<output>"   (or: failed --result "<why>")`);
+  process.exit(0);
+}
+
 export function cmdTaskList() {
   const args = parseFlags(process.argv.slice(3));
   const tasks = listTasks({
@@ -213,3 +344,28 @@ export function cmdTaskList() {
   }
   process.exit(0);
 }
+
+// task-results [--ack] [--json] [--all]
+// Results of tasks I delegated, to deliver to my surface (Phase 2d). The
+// requester surface calls this: Claude Code via the SessionStart hook (auto),
+// an OpenClaw/Telegram requester via a cron-prompt that DMs them. --ack marks
+// them delivered so they don't re-show; --all ignores the delivered set.
+export function cmdTaskResults() {
+  const args = parseFlags(process.argv.slice(3));
+  const results = listTaskResults({ undeliveredOnly: !('--all' in args) });
+  if ('--json' in args) {
+    console.log(JSON.stringify(results));
+    if ('--ack' in args) markResultsDelivered(results.map((r) => r.id));
+    process.exit(0);
+  }
+  if (!results.length) { console.log('No new task results.'); process.exit(0); }
+  console.log(`📥 ${results.length} result(s) from tasks you delegated:`);
+  for (const t of results) {
+    const icon = t.status === 'done' ? '✓' : '✗';
+    console.log(`${icon} ${t.id} → ${t.to}  [${t.status}]`);
+    console.log(`    task:   ${String(t.prompt || '').slice(0, 80)}`);
+    console.log(`    result: ${String(t.result || '').slice(0, 200)}`);
+  }
+  if ('--ack' in args) { markResultsDelivered(results.map((r) => r.id)); console.log(`(${results.length} marked delivered)`); }
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parallelclaw",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Local-first personal AI ops layer. Shared verbatim memory across your agents (Claude Code, Cursor, OpenClaw, Hermes, Obsidian, Telegram) in one SQLite + FTS5 corpus — plus a coordination layer where any of your agents can delegate tasks to any other. Searchable from any MCP-compatible client.",
   "type": "module",
   "main": "server.js",