parallelclaw 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 Notable changes to parallelclaw (formerly memex-mvp). Older history lives in the git log.
 
+## 1.2.0 — delegate by talking + the laptop as executor
+
+Coordination, now from natural language. Two MCP tools so any MCP client (Claude
+Code, Cursor, OpenClaw) can delegate and check on work without touching the CLI:
+- **`parallelclaw_delegate`** `{prompt, to, kind, content}` — hand a task to
+  another of your agents. Fired when you say "tell Kimi to …", "delegate this to
+  the VPS agent", "have X do this while I'm away". `to:"any"` broadcasts.
+- **`parallelclaw_tasks`** `{filter: mine|inbox|results|all, status, limit}` —
+  status of what you delegated, your inbox, or completed answers.
+
+SERVER_INSTRUCTIONS gained an "AGENT COORDINATION" recipe so the agent recognizes
+the delegation intent and surfaces results from the SessionStart 📥 block.
+
+### Mac headless executor (Phase 2b) — the laptop runs delegated tasks too
+`lib/executor.js` + `task-executor install|uninstall|status` / `task-run-once`:
+a launchd timer drains the inbox while the Mac is awake, running each claimed
+safe-kind task through `claude -p` and writing the result back — closing any↔any
+auto-coordination both directions. Selective-auto: only SAFE_KINDS (research /
+content / test / general / review / summarize / analysis) auto-run, addressed-to-me
+only unless `--any`; the exec prompt forbids destructive actions and `claude -p`
+runs without `--dangerously-skip-permissions`. Honest limit: only while awake.
+The always-on cron-prompt flow stays the path for Linux/VPS nodes
+(`docs/design/executor-prompt.md`). Hands-off loop live-proven on the Mac↔Kimi mesh.
+
+## 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,12 @@ 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(),
+    // Phase 2b — Mac headless executor (run delegated inbox tasks via `claude -p`)
+    'task-run-once': async () => (await import('./lib/executor.js')).cmdTaskRunOnce(),
+    'task-executor': async () => (await import('./lib/executor.js')).cmdTaskExecutor(),
     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/executor.js

@@ -0,0 +1,238 @@
+/**
+ * Mac headless executor (Phase 2b).
+ *
+ * Lets THIS node (a laptop running Claude Code) be an executor too: while the
+ * Mac is awake, a launchd timer drains the ParallelClaw inbox by running each
+ * claimed task through `claude -p` (headless Claude Code) and writing the result
+ * back. The always-on nodes (Kimi/OpenClaw) use the cron-PROMPT instead
+ * (docs/design/executor-prompt.md); this is the code path for the laptop.
+ *
+ * Honest limit: launchd StartInterval only fires while the Mac is awake — a
+ * sleeping laptop simply doesn't run, and the task WAITS in the ledger. There is
+ * no cloud Claude Code, so "run it now while my laptop is closed" can't happen.
+ *
+ * Safety (selective-auto): only tasks whose `kind` is in SAFE_KINDS auto-run,
+ * and (by default) only those addressed to me — broadcasts ("any") are left for
+ * the always-on nodes unless --any is passed. The exec prompt forbids
+ * destructive/irreversible actions; `claude -p` runs WITHOUT
+ * --dangerously-skip-permissions, so risky tools are declined rather than
+ * silently performed.
+ */
+
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+import { writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { execFile, execSync } from 'node:child_process';
+
+import { getOrigin } from './config.js';
+import { listTasks, claimTask, updateTask } from './tasks.js';
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+const DATA = join(MEMEX_DIR, 'data');
+
+const EXEC_LABEL = 'com.parallelclaw.memex.executor';
+const EXEC_PLIST = join(HOME, 'Library', 'LaunchAgents', `${EXEC_LABEL}.plist`);
+const EXEC_OUT_LOG = join(DATA, 'executor.out.log');
+const EXEC_ERR_LOG = join(DATA, 'executor.err.log');
+
+// Auto-runnable task classes. Read/produce-text work is safe to run unattended;
+// anything that mutates another machine's state is intentionally absent and is
+// left in the inbox for explicit handling (one-tap approval = future v1 UI).
+export const SAFE_KINDS = ['research', 'content', 'test', 'general', 'review', 'summarize', 'analysis'];
+
+const DEFAULT_TIMEOUT_MS = 240000; // 4 min — matches the always-on cron budget
+
+function buildExecPrompt(env) {
+  return [
+    'You are an autonomous ParallelClaw executor running headlessly via `claude -p`.',
+    'A task was delegated to you by another of the user\'s agents. Do it, then print ONLY the',
+    'result/output (no preamble, no "I will…").',
+    '',
+    'SAFETY: do NOT perform destructive or irreversible actions — no deploys, no git push/',
+    'force-push, no deleting or overwriting files outside a scratch directory, no spending, no',
+    'outbound messages. If the task genuinely requires any of that, instead print exactly what',
+    'needs human approval and stop.',
+    '',
+    `TASK (kind: ${env.kind || 'general'}, from: ${env.from || '?'}):`,
+    env.prompt || '',
+    env.content ? `\nADDITIONAL CONTEXT:\n${env.content}` : '',
+  ].join('\n');
+}
+
+/** Default runner: headless `claude -p`. Returns stdout; rejects on error/timeout. */
+function claudeRunner(prompt, { timeoutMs = DEFAULT_TIMEOUT_MS, cwd } = {}) {
+  return new Promise((res, rej) => {
+    const bin = process.env.PARALLELCLAW_CLAUDE_BIN || 'claude';
+    execFile(bin, ['-p', prompt],
+      { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, encoding: 'utf8', cwd: cwd || DATA },
+      (err, stdout, stderr) => {
+        if (err) {
+          if (err.killed) return rej(new Error(`claude -p timed out after ${timeoutMs}ms`));
+          return rej(new Error(String(stderr || err.message).slice(0, 300)));
+        }
+        res(String(stdout || '').trim());
+      });
+  });
+}
+
+/**
+ * One drain pass over the inbox. opts:
+ *   db?            — shared connection (else opens its own writable handle)
+ *   runner?        — async (prompt, {timeoutMs}) => string (default: claude -p) — injectable for tests
+ *   allowKinds?    — auto-run allowlist (default SAFE_KINDS)
+ *   includeBroadcast? — also take to:'any' tasks (default false — leave for always-on nodes)
+ *   timeoutMs?, now?, log?
+ * Returns [{ id, status, skipped? }] for what it acted on.
+ */
+export async function runInboxOnce({
+  db = null, runner = null, allowKinds = SAFE_KINDS, includeBroadcast = false,
+  timeoutMs = DEFAULT_TIMEOUT_MS, now = Date.now(), log = () => {},
+} = {}) {
+  const me = getOrigin();
+  const exec = runner || claudeRunner;
+  const acted = [];
+  let inbox = listTasks({ inbox: true, db, limit: 50 });
+  inbox = inbox.filter((t) => t.to === me || (includeBroadcast && t.to === 'any'));
+  for (const t of inbox) {
+    if (!allowKinds.includes(t.kind)) {
+      log(`skip ${t.id}: kind '${t.kind}' not in auto-allowlist (left for one-tap)`);
+      acted.push({ id: t.id, status: 'skipped', reason: 'kind' });
+      continue;
+    }
+    const claimed = claimTask(t.id, { db, now });
+    if (!claimed) { log(`skip ${t.id}: not claimable (taken/raced)`); acted.push({ id: t.id, status: 'skipped', reason: 'claim' }); continue; }
+    try {
+      const out = await exec(buildExecPrompt(claimed), { timeoutMs });
+      const result = (out && String(out).trim()) || '(executor produced no output)';
+      updateTask(t.id, 'done', { result, db });
+      log(`done ${t.id}`);
+      acted.push({ id: t.id, status: 'done' });
+    } catch (e) {
+      updateTask(t.id, 'failed', { result: `executor error: ${e.message}`.slice(0, 500), db });
+      log(`failed ${t.id}: ${e.message}`);
+      acted.push({ id: t.id, status: 'failed' });
+    }
+  }
+  return acted;
+}
+
+// ── launchd (macOS) — run one drain pass every N min while awake ──────────────
+
+function resolveClaudeBin() {
+  try { return execSync('command -v claude', { encoding: 'utf8' }).trim() || 'claude'; }
+  catch (_) { return 'claude'; }
+}
+
+export function buildExecutorLaunchAgentPlist({ script, mins, nodePath, claudeBin, includeBroadcast }) {
+  const interval = Math.max(60, Math.floor(mins * 60));
+  const argv = [nodePath, script, 'task-run-once'];
+  if (includeBroadcast) argv.push('--any');
+  const argXml = argv.map((a) => `    <string>${a}</string>`).join('\n');
+  // launchd's PATH is minimal and excludes /opt/homebrew/bin where `claude`
+  // usually lives — bake an explicit PATH + the resolved claude path so the
+  // headless run finds it. (Same class of bug as the brew `timeout` PATH trap.)
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${EXEC_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key><string>${HOME}</string>
+    <key>MEMEX_DIR</key><string>${MEMEX_DIR}</string>
+    <key>PARALLELCLAW_CLAUDE_BIN</key><string>${claudeBin}</string>
+    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>StartInterval</key><integer>${interval}</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${EXEC_OUT_LOG}</string>
+  <key>StandardErrorPath</key><string>${EXEC_ERR_LOG}</string>
+  <key>WorkingDirectory</key><string>${resolve(script, '..')}</string>
+</dict>
+</plist>
+`;
+}
+
+export function installExecutor({ scriptPath, everyMinutes = 10, nodePath = process.execPath, includeBroadcast = false } = {}) {
+  if (platform() !== 'darwin') {
+    throw new Error('The headless executor service is macOS-only. On an always-on Linux node, use the cron-prompt in docs/design/executor-prompt.md instead.');
+  }
+  const script = resolve(scriptPath || process.argv[1]);
+  if (!existsSync(script)) throw new Error(`installExecutor: script not found at ${script}`);
+  const mins = Math.max(1, Math.floor(Number(everyMinutes) || 10));
+  const claudeBin = resolveClaudeBin();
+  mkdirSync(DATA, { recursive: true });
+  mkdirSync(join(HOME, 'Library', 'LaunchAgents'), { recursive: true });
+  const plist = buildExecutorLaunchAgentPlist({ script, mins, nodePath, claudeBin, includeBroadcast });
+  try { execSync(`launchctl unload ${JSON.stringify(EXEC_PLIST)}`, { stdio: 'ignore' }); } catch (_) {}
+  writeFileSync(EXEC_PLIST, plist);
+  execSync(`launchctl load ${JSON.stringify(EXEC_PLIST)}`, { stdio: 'inherit' });
+  return { platform: 'darwin', unitPath: EXEC_PLIST, everyMinutes: mins, claudeBin, includeBroadcast };
+}
+
+export function uninstallExecutor() {
+  if (platform() !== 'darwin') return { platform: platform(), unitPath: null };
+  try { execSync(`launchctl unload ${JSON.stringify(EXEC_PLIST)}`, { stdio: 'ignore' }); } catch (_) {}
+  if (existsSync(EXEC_PLIST)) unlinkSync(EXEC_PLIST);
+  return { platform: 'darwin', unitPath: EXEC_PLIST };
+}
+
+export function executorStatus() {
+  if (platform() !== 'darwin') return { installed: false, running: false, manager: 'none' };
+  const installed = existsSync(EXEC_PLIST);
+  let running = false, detail = '';
+  if (installed) {
+    try {
+      const out = execSync(`launchctl list 2>/dev/null | grep ${EXEC_LABEL} || true`, { encoding: 'utf8' });
+      running = out.trim().length > 0; detail = out.trim();
+    } catch (_) {}
+  }
+  return { installed, running, manager: 'launchd', unitPath: EXEC_PLIST, detail };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+export async function cmdTaskRunOnce() {
+  const argv = process.argv.slice(3);
+  const includeBroadcast = argv.includes('--any');
+  const acted = await runInboxOnce({ includeBroadcast, log: (m) => console.error(`[executor] ${m}`) });
+  const ran = acted.filter((a) => a.status === 'done' || a.status === 'failed');
+  if (!ran.length) { console.log('executor: nothing to run.'); process.exit(0); }
+  for (const r of ran) console.log(`${r.status === 'done' ? '✓' : '✗'} ${r.id} ${r.status}`);
+  process.exit(0);
+}
+
+export function cmdTaskExecutor() {
+  const sub = process.argv[3];
+  const argv = process.argv.slice(4);
+  const getOpt = (flag, def) => { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : def; };
+  try {
+    if (sub === 'install') {
+      const r = installExecutor({
+        everyMinutes: parseInt(getOpt('--every', '10'), 10) || 10,
+        includeBroadcast: argv.includes('--any'),
+      });
+      console.log(`✓ Mac executor installed (every ${r.everyMinutes}m while awake).`);
+      console.log(`  claude: ${r.claudeBin}   broadcast tasks: ${r.includeBroadcast ? 'yes' : 'no (addressed-only)'}`);
+      console.log(`  auto-runs kinds: ${SAFE_KINDS.join(', ')} — others wait in the inbox.`);
+      console.log(`  unit: ${r.unitPath}`);
+    } else if (sub === 'uninstall') {
+      uninstallExecutor(); console.log('✓ Mac executor uninstalled (tasks/data preserved).');
+    } else if (sub === 'status') {
+      const s = executorStatus();
+      console.log(`executor: installed=${s.installed} running=${s.running} (${s.manager})`);
+      if (s.detail) console.log(`  ${s.detail}`);
+    } else {
+      console.error('usage: task-executor <install|uninstall|status> [--every <min>] [--any]');
+      process.exit(2);
+    }
+  } catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+  process.exit(0);
+}

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.2.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",
@@ -31,7 +31,7 @@
     "sync": "node ingest.js",
     "ingest": "node ingest.js",
     "bot": "node bot/index.js",
-    "test": "node test/parser.test.js && node test/bot-inbox.test.js && node test/search-sort.test.js && node test/get-conversation-paging.test.js && node test/search-filters.test.js && node test/origin.test.js && node test/tasks.test.js && node test/store-document.test.js && node test/cli.test.js && node test/hook.test.js && node test/telegram-html.test.js && node test/telegram-decisions.test.js && node test/telegram-pending.test.js && node test/telegram-notify.test.js && node test/notify-click-action.test.js && node test/inbox-watcher.test.js && node test/e2e-inbox.test.js && node test/ingest-file.test.js && node test/openclaw-channel.test.js && node test/openclaw-channel-e2e.test.js && node test/wire-openclaw.test.js && node test/sync/server-bootstrap.test.js && node test/sync/push-pull-roundtrip.test.js && node test/sync/cli-end-to-end.test.js && node test/sync/adaptive-batch.test.js && node test/sync/service.test.js && node test/sync/skip-accounting.test.js && node test/sync/pair.test.js && node test/sync/join-token.test.js && node test/sync/tunnel-service.test.js && node test/sync/mcp-invite.test.js && node test/sync/skip-accounting.test.js",
+    "test": "node test/parser.test.js && node test/bot-inbox.test.js && node test/search-sort.test.js && node test/get-conversation-paging.test.js && node test/search-filters.test.js && node test/origin.test.js && node test/tasks.test.js && node test/executor.test.js && node test/store-document.test.js && node test/cli.test.js && node test/hook.test.js && node test/telegram-html.test.js && node test/telegram-decisions.test.js && node test/telegram-pending.test.js && node test/telegram-notify.test.js && node test/notify-click-action.test.js && node test/inbox-watcher.test.js && node test/e2e-inbox.test.js && node test/ingest-file.test.js && node test/openclaw-channel.test.js && node test/openclaw-channel-e2e.test.js && node test/wire-openclaw.test.js && node test/sync/server-bootstrap.test.js && node test/sync/push-pull-roundtrip.test.js && node test/sync/cli-end-to-end.test.js && node test/sync/adaptive-batch.test.js && node test/sync/service.test.js && node test/sync/skip-accounting.test.js && node test/sync/pair.test.js && node test/sync/join-token.test.js && node test/sync/tunnel-service.test.js && node test/sync/mcp-invite.test.js && node test/sync/skip-accounting.test.js",
     "prepublishOnly": "npm test"
   },
   "engines": {

package/server.js

@@ -44,6 +44,7 @@ import {
   KNOWN_SOURCES,
   CONFIG_PATH,
 } from './lib/config.js';
+import { createTask, listTasks, listTaskResults } from './lib/tasks.js';
 import {
   canonicalize as canonicalizeUrl,
   extractDomain,
@@ -1329,6 +1330,18 @@ This merges main + subagent messages in chronological order with a
   titles. Compare short_ids and date ranges before concluding duplicate.
 - Re-imports are idempotent (UNIQUE on msg_id, recount-on-upsert).
 
+══ AGENT COORDINATION (delegate tasks across your agents) ══
+
+ParallelClaw isn't only memory — your agents can hand tasks to each other over
+the same synced ledger. When the user says "tell Kimi to …", "ask the VPS agent
+to …", "delegate this to <agent>", or "have <agent> do X while I'm away":
+  → call parallelclaw_delegate({ prompt, to: "<agent>" })   (to:"any" = broadcast)
+The target agent claims it (atomic — never double-run) and runs it when
+available; the answer returns to you. To check delegated work or surface answers,
+call parallelclaw_tasks (filter: mine / inbox / results). Newly-finished results
+also appear automatically in this session's "📥 results from tasks you delegated"
+block. Don't shell out to raw SQL or the task-* CLI from here — use these tools.
+
 ══ CONVENTIONS ══
 
 - BE PROACTIVE. If past context would sharpen your answer, pull it
@@ -1985,6 +1998,43 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'parallelclaw_delegate',
+    description:
+      'Hand a task to ANOTHER of the user\'s agents (cross-tool, cross-machine) via the shared ParallelClaw ledger. ' +
+      'CALL THIS when the user says "tell Kimi to …", "ask the VPS agent to …", "delegate this to <agent>", ' +
+      '"have <agent> do X while I\'m away", or when an always-on agent should run bulk/long work. The task is ' +
+      'written to the synced ledger; the target agent claims and runs it when available, and the result returns ' +
+      'to you (your next session\'s 📥 block, or via parallelclaw_tasks filter:"results"). Set `to` to the target ' +
+      'node\'s origin label (e.g. "kimi", "vps1"); omit or "any" to broadcast to whichever always-on agent grabs ' +
+      'it first. Destructive cross-machine actions are NOT auto-run — state that in the prompt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'What the other agent should do — self-contained; it has no access to this conversation.' },
+        to: { type: 'string', default: 'any', description: 'Target agent origin label (e.g. "kimi", "vps1"), or "any" to broadcast.' },
+        kind: { type: 'string', default: 'general', description: 'Task class hint: research / code / content / test / …' },
+        content: { type: 'string', description: 'Optional extra context/material to carry with the task.' },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'parallelclaw_tasks',
+    description:
+      'Check the ParallelClaw task ledger. filter="mine" (default): tasks you delegated + their status/result; ' +
+      '"inbox": tasks waiting for THIS node to run; "results": completed answers to your delegations; "all": ' +
+      'everything. Use after parallelclaw_delegate to see whether the other agent finished, or to surface results.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filter: { type: 'string', enum: ['mine', 'inbox', 'results', 'all'], default: 'mine' },
+        status: { type: 'string', enum: ['submitted', 'working', 'done', 'failed'], description: 'Optional status filter.' },
+        limit: { type: 'integer', default: 20, minimum: 1, maximum: 100 },
+        format: { type: 'string', enum: ['markdown', 'json'], default: 'markdown' },
+      },
+    },
+  },
 ];
 
 // v0.11.11 experimental sync — expose the one-paste pairing tool ONLY when
@@ -3575,6 +3625,41 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       });
     }
 
+    if (name === 'parallelclaw_delegate') {
+      const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
+      if (!prompt) return textResult('parallelclaw_delegate: `prompt` is required (what should the other agent do?).');
+      const to = (typeof args.to === 'string' && args.to.trim()) ? args.to.trim().toLowerCase() : 'any';
+      const kind = (typeof args.kind === 'string' && args.kind.trim()) ? args.kind.trim() : 'general';
+      const content = typeof args.content === 'string' ? args.content : null;
+      const { id } = createTask({ prompt, to, kind, content });
+      return textResult(
+        `✓ Delegated task \`${id}\` → **${to}** (from ${getOrigin()}).\n` +
+        `Runs when ${to === 'any' ? 'an always-on agent' : to} is available; the result returns to you ` +
+        `(next session's 📥 block, or parallelclaw_tasks filter:"results").`
+      );
+    }
+
+    if (name === 'parallelclaw_tasks') {
+      const filter = ['mine', 'inbox', 'results', 'all'].includes(args.filter) ? args.filter : 'mine';
+      const limit = Math.min(100, Math.max(1, args.limit || 20));
+      const statusFilter = ['submitted', 'working', 'done', 'failed'].includes(args.status) ? args.status : null;
+      let rows;
+      if (filter === 'results') rows = listTaskResults({});
+      else if (filter === 'inbox') rows = listTasks({ inbox: true, limit });
+      else if (filter === 'mine') rows = listTasks({ mine: true, status: statusFilter, limit });
+      else rows = listTasks({ status: statusFilter, limit });
+      if (pickFormat(args) === 'json') return jsonResult({ filter, count: rows.length, tasks: rows });
+      if (!rows.length) return textResult(`No tasks (filter: ${filter}).`);
+      const icon = { submitted: '○', working: '◐', done: '✓', failed: '✗' };
+      const lines = [`ParallelClaw tasks (${filter}):`, ''];
+      for (const t of rows) {
+        lines.push(`${icon[t.status] || '?'} \`${t.id}\`  ${t.from} → ${t.to}  [${t.status}]`);
+        lines.push(`    ${String(t.prompt || '').slice(0, 90)}`);
+        if (t.result) lines.push(`    └ result: ${String(t.result).slice(0, 200)}`);
+      }
+      return textResult(lines.join('\n'));
+    }
+
     return textResult(`Unknown tool: ${name}`);
   } catch (err) {
     log('tool error:', name, err.message);