@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/hub/lib/git.mjs

@@ -0,0 +1,93 @@
+// agents-hub lib/git.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Which branch a checkout is on, and whether it is a worktree of another repo, read from git's own files (no git
+// process): `<dir>/.git` is a directory for a main checkout, or a file `gitdir: <main>/.git/worktrees/<name>` for a
+// worktree. Cached by the HEAD file's mtime.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const cache = new Map();
+const readSmall = (file) => { try { return fs.readFileSync(file, 'utf8').slice(0, 4096).trim(); } catch { return null; } };
+
+/** { path, branch, sha, worktree, mainRepo } for a checkout directory, or null when it is not a git checkout. */
+export function gitInfo(dir) {
+  let gitDir = null;
+  let worktree = false;
+  try {
+    const st = fs.lstatSync(path.join(dir, '.git'));
+    if (st.isDirectory()) gitDir = path.join(dir, '.git');
+    else if (st.isFile()) {
+      const m = (readSmall(path.join(dir, '.git')) || '').match(/^gitdir:\s*(.+)$/m);
+      if (m) { gitDir = path.resolve(dir, m[1].trim()); worktree = true; }
+    }
+  } catch { return null; }
+  if (!gitDir) return null;
+  const headFile = path.join(gitDir, 'HEAD');
+  let mtime = 0;
+  try { mtime = fs.statSync(headFile).mtimeMs; } catch { return null; }
+  const hit = cache.get(dir);
+  if (hit && hit.mtime === mtime && hit.gitDir === gitDir) return hit.info;
+  const head = readSmall(headFile) || '';
+  const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+  const common = worktree ? readSmall(path.join(gitDir, 'commondir')) : null;
+  const mainGit = worktree ? path.resolve(gitDir, common || '../..') : gitDir;
+  const info = {
+    path: dir,
+    branch: ref ? ref[1] : null,
+    sha: ref ? null : (head.match(/^[0-9a-f]{7,40}$/) || [])[0]?.slice(0, 10) || null,
+    worktree,
+    mainRepo: worktree ? path.dirname(mainGit) : null,
+  };
+  if (cache.size > 500) cache.clear();
+  cache.set(dir, { mtime, gitDir, info });
+  return info;
+}
+
+function branchExists(mainGit, branch) {
+  if (fs.existsSync(path.join(mainGit, 'refs', 'heads', ...branch.split('/')))) return true;
+  return (readSmallBig(path.join(mainGit, 'packed-refs')) || '').includes(` refs/heads/${branch}\n`);
+}
+function readSmallBig(file) { try { return `${fs.readFileSync(file, 'utf8').slice(0, 2e6)}\n`; } catch { return null; } }
+
+/** Where a branch is checked out: the main checkout or one of its worktrees (from `.git/worktrees/<n>/{HEAD,gitdir}`). */
+function checkedOutAt(mainGit, branch) {
+  const want = `ref: refs/heads/${branch}`;
+  if (readSmall(path.join(mainGit, 'HEAD')) === want) return path.dirname(mainGit);
+  let names = [];
+  try { names = fs.readdirSync(path.join(mainGit, 'worktrees')); } catch { return null; }
+  for (const n of names) {
+    if (readSmall(path.join(mainGit, 'worktrees', n, 'HEAD')) !== want) continue;
+    const gitFile = readSmall(path.join(mainGit, 'worktrees', n, 'gitdir'));
+    if (gitFile) return path.dirname(gitFile);
+  }
+  return null;
+}
+
+/**
+ * A task's branch and worktree: the branch its KICKOFF named (else the one its channel's checkout is on), where that
+ * branch is checked out now, and whether the branch still exists.
+ */
+export function taskCheckout(checkout, planned) {
+  if (!checkout) return null;
+  const branch = (planned && planned.branch) || checkout.branch;
+  if (!branch) return { branch: null, sha: checkout.sha, worktreePath: checkout.path, isWorktree: checkout.worktree, mainRepo: checkout.mainRepo, channelCheckout: checkout.path, exists: null, here: true };
+  const mainGit = path.join(checkout.mainRepo || checkout.path, '.git');
+  const at = checkout.branch === branch ? checkout.path : checkedOutAt(mainGit, branch);
+  return {
+    branch,
+    worktreePath: at,
+    isWorktree: !!at && at !== (checkout.mainRepo || (checkout.worktree ? null : checkout.path)),
+    mainRepo: checkout.mainRepo || checkout.path,
+    channelCheckout: checkout.path,
+    channelBranch: checkout.branch,
+    exists: branchExists(mainGit, branch),
+    here: checkout.branch === branch,
+  };
+}
+
+/** The branch and worktree a KICKOFF post asked for ("Worktree <path>, branch <name>"). */
+export function plannedCheckout(text) {
+  const t = String(text || '');
+  const branch = (t.match(/\bbranch\s+`?([A-Za-z0-9._/-]+?)`?(?=[\s,.;)]|$)/i) || [])[1] || null;
+  const wt = (t.match(/\bworktree\s+`?([^\s,`]+)`?/i) || [])[1] || null;
+  return branch || wt ? { branch, worktree: wt ? wt.replace(/[).,]+$/, '') : null } : null;
+}

package/src/hub/lib/me.mjs

@@ -0,0 +1,123 @@
+// agents-hub lib/me.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Who "@you" is: the AgentPulse CLI's signed-in user. The CLI config holds no name, so the server asks the platform's
+// OIDC userinfo with the CLI's access token (as `agentpulse login` does) and keeps the answer in memory. The browser
+// only ever gets { name, handle, aliases }; the token goes only to the profile's own platform and is never logged.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { USER_ALIAS } from './channels.mjs';
+
+export const NOBODY = Object.freeze({ name: 'You', handle: null, aliases: Object.freeze([]) });
+/** Why the name is "You". Only these words are ever logged or kept, never an error message or a header. */
+export const REASONS = Object.freeze(['no-config', 'unauthorized', 'timeout', 'network', 'blank']);
+const TIMEOUT_MS = 3000;
+const FRESH_MS = 3600e3;
+const RETRY_MS = 5 * 60e3;
+const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+export const cliConfigPath = (env = process.env, home = os.homedir()) => path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'agentpulse', 'config.json');
+
+/** The CLI's active profile: its default, else its only one. */
+export function activeProfile(cfg) {
+  const profiles = (cfg && typeof cfg.profiles === 'object' && cfg.profiles) || {};
+  if (cfg && cfg.defaultProfile && profiles[cfg.defaultProfile]) return profiles[cfg.defaultProfile];
+  const names = Object.keys(profiles);
+  return names.length === 1 ? profiles[names[0]] : null;
+}
+
+/** The profile's platform origin, when the bearer may go there: https, or http on this machine. */
+export function platformOrigin(baseUrl) {
+  let u;
+  try { u = new URL(String(baseUrl)); } catch { return null; }
+  return u.protocol === 'https:' || (u.protocol === 'http:' && LOCAL.has(u.hostname)) ? u.origin : null;
+}
+
+const tidy = (s) => (typeof s === 'string' ? s.replace(/\s+/g, ' ').trim().slice(0, 60) : '');
+const localPart = (s) => tidy(s).split('@')[0];
+
+/**
+ * OIDC claims or a profile → { name, handle, aliases }: "First Last", else `name`, else the username; NOBODY when blank.
+ * Aliases are the handle and the name without spaces.
+ */
+export function identityOf(u) {
+  if (!u || typeof u !== 'object') return NOBODY;
+  const first = tidy(u.given_name || u.firstName || u.first_name);
+  const last = tidy(u.family_name || u.lastName || u.last_name);
+  const username = localPart(u.preferred_username || u.username || u.email);
+  const name = tidy([first, last].filter(Boolean).join(' ')) || tidy(u.name) || username;
+  if (!name) return NOBODY;
+  const handle = USER_ALIAS.test(username) ? username : null;
+  const aliases = [...new Set([handle, name.replace(/\s+/g, '')]
+    .filter((a) => a && USER_ALIAS.test(a) && !/^(you|user)$/i.test(a)).map((a) => a.toLowerCase()))];
+  return { name, handle, aliases };
+}
+
+/** The aliases no agent persona has: when the user's handle is also an agent's username, "@" it means the agent. */
+export const aliasesFor = (me, taken) => me.aliases.filter((a) => !taken.has(a.toLowerCase()));
+
+async function lookup(configPath, fetchImpl) {
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { return { reason: 'no-config' }; }
+  const profile = activeProfile(cfg);
+  if (!profile) return { reason: 'no-config' };
+  const own = identityOf(profile);
+  if (own !== NOBODY) return { me: own };
+  const origin = platformOrigin(profile.baseUrl);
+  if (!origin || typeof profile.accessToken !== 'string' || !profile.accessToken) return { reason: 'no-config' };
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  try {
+    const r = await fetchImpl(`${origin}/api/oauth/userinfo`, {
+      headers: { authorization: `Bearer ${profile.accessToken}`, accept: 'application/json' }, redirect: 'error', signal: ctl.signal,
+    });
+    if (r.status === 401 || r.status === 403) return { reason: 'unauthorized' };
+    if (!r.ok) return { reason: 'network' };
+    const got = identityOf(await r.json().catch(() => null));
+    return got === NOBODY ? { reason: 'blank' } : { me: got };
+  } catch {
+    return { reason: ctl.signal.aborted ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The CLI user, resolved in the background: `current()` never waits, and starts a lookup when the answer is stale (hourly,
+ * or every few minutes while it is still "You"). A failed lookup keeps the last good answer; `listen(fn)` hears changes,
+ * and `reason()` says why the name is "You".
+ */
+export function cliIdentity({ configPath = cliConfigPath(), fetchImpl = globalThis.fetch, now = Date.now, log = console.error } = {}) {
+  let me = NOBODY;
+  let why = null;
+  let checkedAt = -Infinity;
+  let running = null;
+  const listeners = new Set();
+  function refresh() {
+    if (running) return running;
+    checkedAt = now();
+    running = lookup(configPath, fetchImpl).then((got) => {
+      running = null;
+      if (got.reason) {
+        if (me === NOBODY && got.reason !== why) log(`@you shows "You": the CLI user could not be read (${got.reason})`);
+        why = got.reason;
+      } else {
+        why = null;
+        if (got.me.name !== me.name || got.me.aliases.join('|') !== me.aliases.join('|')) {
+          me = got.me;
+          for (const fn of listeners) fn(me);
+        }
+      }
+      return me;
+    });
+    return running;
+  }
+  return {
+    current() {
+      if (now() - checkedAt >= (me === NOBODY ? RETRY_MS : FRESH_MS)) refresh();
+      return me;
+    },
+    refresh,
+    reason: () => why,
+    listen(fn) { listeners.add(fn); },
+  };
+}

package/src/hub/lib/personas.mjs

@@ -0,0 +1,143 @@
+// agents-hub lib/personas.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Every agent gets a persona the first time the hub sees it: a first name, a surname, a username that is never reused,
+// and a seed for its illustrated face. The pairing is stored, so an agent keeps its identity for good.
+import fs from 'node:fs';
+import path from 'node:path';
+import { HUB } from './store.mjs';
+
+const FILE = path.join(HUB, 'state', 'personas.json');
+const RECENT_MS = 7 * 24 * 3600e3;
+const FIRST = [
+  'Maya', 'Arjun', 'Lena', 'Kofi', 'Sofia', 'Ravi', 'Noor', 'Mateo', 'Aiko', 'Elias', 'Priya', 'Tomas', 'Zara', 'Kenji', 'Amara', 'Luca',
+  'Ines', 'Dev', 'Hana', 'Omar', 'Clara', 'Jin', 'Asha', 'Felix', 'Leila', 'Nikhil', 'Mira', 'Diego', 'Yara', 'Sami', 'Ingrid', 'Tariq',
+  'Nora', 'Kai', 'Ananya', 'Bruno', 'Selin', 'Ade', 'Freya', 'Hugo', 'Meera', 'Rafael', 'Suki', 'Idris', 'Lina', 'Oskar', 'Tara', 'Malik',
+  'Esme', 'Rohan', 'Ayla', 'Theo', 'Kavya', 'Pablo', 'Rin', 'Yusuf', 'Alma', 'Ishaan', 'Greta', 'Emeka', 'Lea', 'Vikram', 'Saoirse', 'Ren',
+];
+const LAST = [
+  'Okafor', 'Sharma', 'Lindqvist', 'Mensah', 'Moreno', 'Iyer', 'Haddad', 'Silva', 'Tanaka', 'Novak', 'Reddy', 'Kowalski', 'Ahmed', 'Sato',
+  'Adeyemi', 'Rossi', 'Costa', 'Patel', 'Kim', 'Farouk', 'Weber', 'Chen', 'Nair', 'Fischer', 'Rahimi', 'Menon', 'Aydin', 'Garcia', 'Nkosi',
+  'Hassan', 'Berg', 'Qureshi', 'Larsen', 'Mori', 'Kapoor', 'Duarte', 'Yilmaz', 'Balogun', 'Olsen', 'Laurent', 'Pillai', 'Ortega', 'Ito',
+  'Abara', 'Vidal', 'Lund', 'Desai', 'Karimi', 'Brandt', 'Rao', 'Demir', 'Herrera', 'Watanabe', 'Eze', 'Nyberg', 'Joshi', 'Santos', 'Park',
+];
+
+/**
+ * A personality shapes how an agent talks to you in the hub: temperament, how it writes, and the emoji it reaches for.
+ * It is tone only. The role's duties are restated next to it every time, so a reviewer stays exacting and a coder
+ * stays precise, whatever its temperament.
+ */
+const TEMPERAMENT = ['warm and encouraging', 'dry and witty', 'calm and methodical', 'upbeat and energetic', 'thoughtful and curious',
+  'direct and no-nonsense', 'playful but sharp', 'quietly confident', 'friendly and plain-spoken', 'meticulous and a little wry'];
+const VOICE = ['writes short sentences and gets to the point', 'explains the why in one line', 'likes a quick checklist', 'asks one sharp question back when something is unclear',
+  'sums up first, then adds a light remark', 'speaks plainly, like a colleague at the next desk', 'leads with the answer and keeps the detail for when you ask'];
+const EMOJI_SETS = [['👍', '✅', '🚀'], ['🙂', '🙌', '✨'], ['👀', '🤔', '📝'], ['🔥', '💪', '🎉'], ['✅', '🧪', '🔍'], ['😄', '🎉', '☕'], ['👌', '🛠️', '📌'], ['🙏', '💡', '🌱']];
+const EMOJI_HABIT = ['rarely uses emoji', 'uses an emoji now and then', 'often answers with just an emoji when no words are needed'];
+const ROLE_DUTY = {
+  CODER: 'the coder: precise about what you built, tested and committed, and you never claim a check you did not run',
+  REVIEWER: 'the reviewer: exacting and honest; personality never softens a finding, a FAIL or a missing check',
+  ARCHITECT: 'the architect: you own the plan, the deploys and the evidence, and you keep every stream to its gates',
+  AUDITOR: 'the platform auditor: strict about alignment with the platform, and you flag drift plainly',
+  MANAGER: 'the hub manager: you coordinate across deliveries, deduplicate shared work and preserve every specialist role and gate',
+};
+
+function personalityFor(id) {
+  return {
+    temperament: TEMPERAMENT[hash(`temper:${id}`) % TEMPERAMENT.length],
+    voice: VOICE[hash(`voice:${id}`) % VOICE.length],
+    emoji: EMOJI_SETS[hash(`emoji:${id}`) % EMOJI_SETS.length],
+    habit: EMOJI_HABIT[hash(`habit:${id}`) % EMOJI_HABIT.length],
+  };
+}
+
+/** How an agent should sound when it answers you in the hub, with its role's duties restated so tone never changes the work. */
+export function voiceFor(id, role) {
+  let p = null;
+  try { p = (JSON.parse(fs.readFileSync(FILE, 'utf8')) || {})[id] || null; } catch { p = null; }
+  if (!p) return null;
+  const k = p.personality || personalityFor(id);
+  const r = String(role || p.role || '').toUpperCase().replace(/[^A-Z]/g, '');
+  const duty = ROLE_DUTY[r] || `the ${r ? r.toLowerCase() : 'agent'} on this task, doing that job exactly as before`;
+  return `In the hub you are ${p.name} (@${p.username}). Personality: ${k.temperament}; ${k.voice}; ${k.habit} (favourites: ${k.emoji.join(' ')}). `
+    + 'Answer like a human teammate with that personality: words, an emoji reaction, or both, whatever a person like you would send. '
+    + `It is tone only. You are still ${duty}. It changes nothing in your work or your standards. `
+    + 'Whatever the tone, keep the structure readable: a clear first sentence, short paragraphs, bullets, code blocks and tables where they help.';
+}
+
+let cache = null;
+let dirty = false;
+
+function hash(s) {
+  let x = 2166136261;
+  for (let i = 0; i < s.length; i++) { x ^= s.charCodeAt(i); x = Math.imul(x, 16777619); }
+  return x >>> 0;
+}
+const slug = (s) => s.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '');
+
+/** A username nobody has had: first.last, then first.last2, first.last3… */
+function uniqueUsername(first, last, all) {
+  const used = new Set(Object.values(all).map((p) => p.username).filter(Boolean));
+  const base = `${slug(first)}.${slug(last)}`;
+  if (!used.has(base)) return base;
+  let n = 2;
+  while (used.has(`${base}${n}`)) n++;
+  return `${base}${n}`;
+}
+
+/** Older personas had a first name only: give them a surname and a username, keeping name and face. */
+function upgrade(all) {
+  for (const [id, p] of Object.entries(all)) {
+    if (p && !p.personality) { p.personality = personalityFor(id); dirty = true; }
+    if (!p || p.username) continue;
+    const first = String(p.name || FIRST[hash(id) % FIRST.length]).split(' ')[0];
+    const last = LAST[hash(`last:${id}`) % LAST.length];
+    Object.assign(p, { first, last, name: `${first} ${last}`, username: uniqueUsername(first, last, all) });
+    dirty = true;
+  }
+}
+
+function load() {
+  if (cache) return cache;
+  try { cache = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { cache = {}; }
+  upgrade(cache);
+  return cache;
+}
+
+/** The persona of an agent id, creating it on first sight. First names are not reused among recent agents. */
+export function personaFor(id, { role = null, channel = null, now = Date.now() } = {}) {
+  const all = load();
+  if (all[id]) return all[id];
+  const recent = new Set(Object.values(all).filter((p) => now - p.createdAt < RECENT_MS).map((p) => p.first));
+  const start = hash(id) % FIRST.length;
+  let first = FIRST[start];
+  for (let i = 0; i < FIRST.length; i++) if (!recent.has(FIRST[(start + i) % FIRST.length])) { first = FIRST[(start + i) % FIRST.length]; break; }
+  const last = LAST[hash(`last:${id}`) % LAST.length];
+  all[id] = { first, last, name: `${first} ${last}`, username: uniqueUsername(first, last, all), seed: hash(`face:${id}`), role, channel, createdAt: now, personality: personalityFor(id) };
+  dirty = true;
+  return all[id];
+}
+
+/** Write new or upgraded personas to disk (once per pass). */
+export function savePersonas() {
+  if (!dirty || !cache) return;
+  fs.writeFileSync(FILE, JSON.stringify(cache, null, 2));
+  dirty = false;
+}
+
+let usernames = { mtime: null, set: new Set() };
+/** Every username an agent persona has had, re-read when the file changes (the collector writes it in its own thread). */
+export function personaUsernames() {
+  let mtime;
+  try { mtime = fs.statSync(FILE).mtimeMs; } catch { return new Set(); }
+  if (mtime !== usernames.mtime) {
+    let all = {};
+    try { all = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { /* half-written: keep the last set */ return usernames.set; }
+    usernames = { mtime, set: new Set(Object.values(all).map((p) => p && typeof p.username === 'string' && p.username.toLowerCase()).filter(Boolean)) };
+  }
+  return usernames.set;
+}
+
+/** Personas created since sinceMs, for "joined" lines in project channels. Read fresh: the collector writes them in its own thread. */
+export function personasSince(sinceMs) {
+  let all = {};
+  try { all = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { return []; }
+  return Object.entries(all).filter(([, p]) => p && p.createdAt >= sinceMs).map(([id, p]) => ({ id, ...p }));
+}

package/src/hub/lib/status.mjs

@@ -0,0 +1,147 @@
+// agents-hub lib/status.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// A status you set by hand on a delivery or an agent: stored once as the registry fact `status_override`, applied over
+// the derived status when the hub projects its rows, and recorded in the task channels as a USER post. Pure.
+
+export const USER_STATUSES = ['done', 'blocked', 'stopped', 'handed-over', 'working'];
+export const STATUS_LIMITS = Object.freeze({ id: 100, reason: 500, to: 120, key: 240 });
+/** The Board's step columns (channels.STEPS), and the ids a move names them by. */
+const STEP_NAMES = ['Research', 'Design', 'Mockup', 'Build', 'Review', 'Checks', 'Proof'];
+export const STEP_IDS = STEP_NAMES.map((name) => name.toLowerCase());
+const STREAM_KEY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+/** Done and Stopped hold until you change them; the others give way to the next agent header in the channel. */
+const STICKY = new Set(['done', 'stopped']);
+const HEADER_TYPE = { done: 'DONE', blocked: 'BLOCKER', stopped: 'STOPPED', 'handed-over': 'HANDED OVER', working: 'STATUS' };
+const LABEL = { done: 'Done', blocked: 'Blocked', stopped: 'Stopped', 'handed-over': 'Handed over', working: 'Working' };
+const DELIVERY_STATUS = { done: 'done', stopped: 'done', blocked: 'blocked', 'handed-over': 'on-track', working: 'on-track' };
+const AGENT_STATUS = { done: 'done', stopped: 'done', blocked: 'stuck', 'handed-over': 'waiting', working: 'working' };
+const LOCAL_ID = /^[^\0-\x1f\x7f]+$/;
+
+/** One line, no control or bidi characters: the reason goes into a channel header that editors also render. */
+const oneLine = (s) => s.replace(/[\0-\x1f\x7f-\x9f\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, ' ').replace(/\s+/g, ' ').trim();
+
+function text(v, name, max, required) {
+  if (v === undefined || v === null) return required ? { error: `${name} is required` } : { value: null };
+  if (typeof v !== 'string') return { error: `${name} must be text` };
+  const value = oneLine(v);
+  if (!value) return required ? { error: `${name} is required` } : { value: null };
+  if (value.length > max) return { error: `${name} must be at most ${max} characters` };
+  return { value };
+}
+
+/**
+ * A POST /api/status body → { target, status, reason, to }, or for a stream (a card moved to a step column)
+ * { target, step }; or { error }. The hub works out the rest of a move itself, so a move carries nothing else.
+ */
+export function statusRequest(body) {
+  const t = body && body.target;
+  if (!t || typeof t !== 'object' || !['delivery', 'agent', 'stream'].includes(t.kind)) return { error: 'target must be a delivery, an agent or a stream' };
+  if (t.kind === 'stream') {
+    if (typeof t.id !== 'string' || t.id.length > STATUS_LIMITS.key || !STREAM_KEY.test(t.id)) return { error: 'target id must be a <repo>/<channel> stream key' };
+    if (!STEP_IDS.includes(body.step)) return { error: `step must be one of ${STEP_IDS.join(', ')}` };
+    const extra = Object.keys(body).find((k) => !['target', 'step'].includes(k));
+    if (extra) return { error: `${extra} is not part of a move` };
+    return { target: { kind: 'stream', id: t.id }, step: body.step };
+  }
+  if (body.step !== undefined) return { error: 'step is only for a stream' };
+  if (typeof t.id !== 'string' || !t.id || t.id.length > STATUS_LIMITS.id || !LOCAL_ID.test(t.id)) return { error: 'invalid target id' };
+  if (!USER_STATUSES.includes(body.status)) return { error: `status must be one of ${USER_STATUSES.join(', ')}` };
+  const reason = text(body.reason, 'reason', STATUS_LIMITS.reason, body.status === 'blocked');
+  if (reason.error) return { error: reason.error };
+  if (body.status !== 'handed-over' && body.to !== undefined && body.to !== null) return { error: 'to is only for handed-over' };
+  const to = body.status === 'handed-over' ? text(body.to, 'to', STATUS_LIMITS.to, true) : { value: null };
+  if (to.error) return { error: to.error };
+  return { target: { kind: t.kind, id: t.id }, status: body.status, reason: reason.value, to: to.value };
+}
+
+export const overrideKey = (target) => `${target.kind}:${target.id}`;
+
+/** Header text without `#`: the parser reads "#12" in any header as a finding id that a closing word would close. */
+const headerSafe = (s) => oneLine(s.replace(/#/g, ''));
+
+/** The channel record of a status you set: one USER header, in the time format decisionPost writes. */
+const clock = (at) => [at.getHours(), at.getMinutes(), at.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+
+export function auditPost({ status, reason = null, to = null }, { at = new Date(), who = null } = {}) {
+  const hhmmss = clock(at);
+  const what = [to ? `to ${headerSafe(to)}` : null, reason ? headerSafe(reason) : null].filter(Boolean).join(': ');
+  return `\n## [USER] ${hhmmss} ${HEADER_TYPE[status]} — set from the Board${who ? ` for ${headerSafe(who)}` : ''}${what ? `: ${what}` : ''}\n`;
+}
+
+/** "Blocked, set by you: org down" — the words a row shows for a status you set. */
+export function overrideText(o) {
+  const by = !o.by || o.by === 'user' ? 'you' : o.by;
+  return `${LABEL[o.status]}${o.to ? ` to ${o.to}` : ''}, set by ${by}${o.reason ? `: ${o.reason}` : ''}`;
+}
+
+/**
+ * Whether an agent has posted a header that moves the work (channels.movesWork: not USER posts, so not the audit post,
+ * and not check-ins) since status `o` was set. Headers carry agents' clocks, not the hub's, so this goes by place in
+ * the channel: `o.seqs` holds the audit post's position in each stream it went to, `seqOf(key)` the newest moving
+ * header's. A status set before the hub recorded positions falls back to `agentAt`, the newest such header's time.
+ */
+export function movedSince(o, { agentAt = 0, seqOf = () => 0 } = {}) {
+  const seqs = Object.entries(o.seqs || {});
+  return seqs.length ? seqs.some(([key, seq]) => seqOf(key) > seq) : agentAt > o.at;
+}
+
+/** For movedSince: where the work under a delivery fact (its streams) or an agent-row fact (its own stream) last moved. */
+export function workMoved(kind, row) {
+  if (kind === 'delivery') {
+    const streams = row.streams || [];
+    const at = new Map(streams.map((s) => [s.key, s.agentSeq || 0]));
+    return { agentAt: Math.max(0, ...streams.map((s) => s.agentAt || 0)), seqOf: (key) => at.get(key) || 0 };
+  }
+  return { agentAt: row.movedAt || 0, seqOf: (key) => (key === row.streamKey ? row.movedSeq || 0 : 0) };
+}
+
+/** Whether a status you set still holds: Done and Stopped stick, the soft ones last until the work moves. */
+export const overrideHolds = (o, moved = {}) => !!o && USER_STATUSES.includes(o.status) && (STICKY.has(o.status) || !movedSince(o, moved));
+
+/**
+ * A delivery or agent row with the status you set over its derived one. An open ask stays in front: only Stopped, or
+ * Done on anything but a result waiting for your Accept, takes a delivery out of needs-you.
+ */
+export function withOverride(row, o, { kind, ...moved }) {
+  if (!overrideHolds(o, moved)) return row;
+  const override = { status: o.status, reason: o.reason || null, to: o.to || null, by: o.by || 'user', at: o.at };
+  const asking = kind === 'delivery' && row.status === 'needs-you';
+  if (asking && !(o.status === 'stopped' || (o.status === 'done' && !(row.ask && row.ask.kind === 'result')))) return { ...row, override };
+  if (kind === 'agent') {
+    return { ...row, status: AGENT_STATUS[o.status], waitingOn: o.status === 'handed-over' ? override.to : row.waitingOn, override };
+  }
+  return { ...row, status: DELIVERY_STATUS[o.status], reason: overrideText(override), override };
+}
+
+/** The channel record of a card you moved: a USER NOTE, which is chatter, so it never moves the derived step itself. */
+export const movePost = ({ step }, { at = new Date() } = {}) => `\n## [USER] ${clock(at)} NOTE — moved to ${STEP_NAMES[STEP_IDS.indexOf(step)]} from the Board\n`;
+
+/**
+ * Whether a step you moved a card to still holds on stream `s` (a streamView). It ends at the first header that moves
+ * the work, comes after the move's NOTE in the channel (`o.seq`, its position), and either leaves the derived step
+ * where it was not when you moved the card (`fromStep`) or implies on its own a step beyond yours (`stepSeq[i]`: the
+ * position of the newest such header implying step i or later). So commits in Build keep a move to Review, and the
+ * next findings end a move back to Build.
+ */
+export function stepHolds(o, s) {
+  if (!o || !STEP_IDS.includes(o.step) || !Number.isInteger(o.seq) || s.done) return false;
+  const mine = STEP_IDS.indexOf(o.step);
+  if ((s.agentSeq || 0) > o.seq && s.step !== o.fromStep) return false;
+  return !(((s.stepSeq || [])[mine + 1] || 0) > o.seq);
+}
+
+/** A stream row in the column you moved it to, with `override` saying who moved it and when. */
+export function withStep(s, o) {
+  if (!stepHolds(o, s)) return s;
+  const step = STEP_IDS.indexOf(o.step);
+  return { ...s, step, stepName: STEP_NAMES[step], override: { step: o.step, by: o.by || 'user', at: o.at } };
+}
+
+/** A delivery row with its streams' moves applied; its own step and counts follow them, as buildDeliveries counts. */
+export function withSteps(d, overrideOf) {
+  const streams = (d.streams || []).map((s) => withStep(s, overrideOf(s.key)));
+  if (streams.every((s, i) => s === d.streams[i])) return d;
+  const open = streams.filter((s) => !s.done);
+  const stepCounts = STEP_NAMES.map((_, i) => open.filter((s) => s.step === i).length);
+  const step = open.length ? stepCounts.lastIndexOf(Math.max(...stepCounts)) : d.step;
+  return { ...d, streams, stepCounts, step, stepName: step == null ? null : STEP_NAMES[step] };
+}

package/src/hub/lib/store.mjs

@@ -0,0 +1,106 @@
+// agents-hub lib/store.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// The hub's files. Everything is append-only JSONL or one small JSON file, so any sandboxed session can write it;
+// for the same reason everything read back is shape-checked before use.
+import fs from 'node:fs';
+import path from 'node:path';
+import { hubHome } from '../home.mjs';
+
+export const HUB = hubHome();
+const STATE = path.join(HUB, 'state');
+const EVENTS = path.join(STATE, 'events.jsonl');
+const REQUESTS = path.join(STATE, 'requests');
+const SETTINGS = path.join(STATE, 'settings.json');
+export const KEEPAWAKE_STATUS = path.join(STATE, 'keepawake-status.json');
+const EVENTS_TAIL_BYTES = 1024 * 1024;
+const NUDGE_CHOICES = [0, 5, 10, 15, 30];
+const KEEP_AWAKE_MODES = ['off', 'agents', 'always'];
+
+const DEFAULT_SETTINGS = { keepAwake: { mode: 'off' }, wake: { nudgeEveryMin: 0, macWakeAt: null } };
+
+fs.mkdirSync(REQUESTS, { recursive: true });
+
+const readJson = (f, fallback) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return fallback; } };
+const str = (v, max) => (typeof v === 'string' ? v.slice(0, max) : '');
+const isEvent = (e) => e && typeof e === 'object' && Number.isFinite(e.at) && typeof e.from === 'string' && typeof e.type === 'string';
+
+export function appendEvent(e) {
+  const event = { at: Date.now(), ...e };
+  fs.appendFileSync(EVENTS, JSON.stringify(event) + '\n');
+  return event;
+}
+
+/** Events since sinceMs, from the last megabyte of the log (older ones are history the views never show). */
+export function readEvents(sinceMs = 0) {
+  let text = '';
+  try {
+    const st = fs.statSync(EVENTS);
+    const len = Math.min(EVENTS_TAIL_BYTES, st.size);
+    const fd = fs.openSync(EVENTS, 'r');
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, st.size - len);
+    fs.closeSync(fd);
+    text = buf.toString('utf8');
+    if (len < st.size) text = text.slice(text.indexOf('\n') + 1);
+  } catch { return []; }
+  return text.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter((e) => isEvent(e) && e.at >= sinceMs)
+    .map((e) => ({ ...e, to: typeof e.to === 'string' ? e.to : '*', text: str(e.text, 500) }));
+}
+
+export function addRequest({ from, kind, title, files = [] }) {
+  const id = `r-${Date.now().toString(36)}`;
+  const req = { id, from: [String(from)], kind: String(kind), title: String(title), files, status: 'queued', at: Date.now() };
+  fs.writeFileSync(path.join(REQUESTS, `${id}.json`), JSON.stringify(req, null, 2));
+  appendEvent({ from: String(from), to: 'manager', type: 'REQUEST', text: `${kind}: ${title}`, ref: id });
+  return req;
+}
+
+export function readRequests() {
+  let files = [];
+  try { files = fs.readdirSync(REQUESTS).filter((f) => f.endsWith('.json')); } catch { return []; }
+  return files.map((f) => readJson(path.join(REQUESTS, f), null))
+    .filter((r) => r && typeof r === 'object' && Number.isFinite(r.at) && typeof r.title === 'string')
+    .map((r) => ({ id: str(r.id, 60), title: str(r.title, 200), kind: str(r.kind, 30), status: str(r.status, 20) || 'queued', at: r.at,
+      from: (Array.isArray(r.from) ? r.from : [r.from]).filter((x) => typeof x === 'string').slice(0, 10) }));
+}
+
+const ACCEPTED = path.join(STATE, 'accepted.json');
+
+/** Deliveries whose result you accepted, by delivery id → when. Kept in its own file so it never rolls off a log. */
+export function readAccepted() {
+  const a = readJson(ACCEPTED, {}) || {};
+  return new Map(Object.entries(a).filter(([k, v]) => typeof k === 'string' && Number.isFinite(v)));
+}
+
+export function acceptDelivery(id) {
+  const a = Object.fromEntries(readAccepted());
+  a[id] = Date.now();
+  fs.writeFileSync(ACCEPTED, JSON.stringify(a, null, 2));
+}
+
+export function readSettings() {
+  const s = readJson(SETTINGS, {}) || {};
+  return validSettings({ keepAwake: { ...DEFAULT_SETTINGS.keepAwake, ...(s.keepAwake || {}) }, wake: { ...DEFAULT_SETTINGS.wake, ...(s.wake || {}) } });
+}
+
+/** Only known keys and values survive: a nudge interval from the list, a keep-awake mode, a wake time as HH:MM. */
+export function validSettings(s) {
+  const mode = KEEP_AWAKE_MODES.includes(s.keepAwake && s.keepAwake.mode) ? s.keepAwake.mode : 'off';
+  const every = NUDGE_CHOICES.includes(Number(s.wake && s.wake.nudgeEveryMin)) ? Number(s.wake.nudgeEveryMin) : 0;
+  const at = s.wake && typeof s.wake.macWakeAt === 'string' && /^([01]\d|2[0-3]):[0-5]\d$/.test(s.wake.macWakeAt) ? s.wake.macWakeAt : null;
+  return { keepAwake: { mode }, wake: { nudgeEveryMin: every, macWakeAt: at } };
+}
+
+export function writeSettings(patch) {
+  const cur = readSettings();
+  const next = validSettings({ keepAwake: { ...cur.keepAwake, ...((patch && patch.keepAwake) || {}) }, wake: { ...cur.wake, ...((patch && patch.wake) || {}) } });
+  fs.writeFileSync(SETTINGS, JSON.stringify(next, null, 2));
+  return next;
+}
+
+/** What the keep-awake helper last reported; `installed` is false when it has not checked in for 90 s. */
+export function keepAwakeStatus() {
+  const s = readJson(KEEPAWAKE_STATUS, null);
+  if (!s || !Number.isFinite(s.heartbeat)) return { installed: false, running: false };
+  return { running: !!s.running, since: Number.isFinite(s.since) ? s.since : null, installed: Date.now() - s.heartbeat < 90e3 };
+}

package/src/hub/lib/titles.mjs

@@ -0,0 +1,29 @@
+// agents-hub lib/titles.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// The title Cursor gives each chat (the one in its chat list), read from Cursor's own store so a delivery is named
+// the way you already know it. Read-only; any failure just means no title, and the caller falls back to the prompt.
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+const DB = path.join(os.homedir(), 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+const SQLITE = '/usr/bin/sqlite3';
+const ID = /^[0-9a-f-]{36}$/;
+const TTL_MS = 60e3;
+const cache = new Map();
+
+/** Cursor's chat titles for these conversation ids, as a Map id → title (ids it has no title for are left out). */
+export function chatTitles(ids) {
+  const now = Date.now();
+  const want = [...new Set(ids)].filter((id) => ID.test(id) && !(cache.has(id) && now - cache.get(id).at < TTL_MS));
+  if (want.length) {
+    let rows = [];
+    try {
+      const sql = `SELECT substr(key, 14) AS id, json_extract(value, '$.name') AS name FROM cursorDiskKV WHERE key IN (${want.map((id) => `'composerData:${id}'`).join(',')});`;
+      const out = execFileSync(SQLITE, ['-readonly', '-json', `file:${DB}?mode=ro`, sql], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+      rows = out.trim() ? JSON.parse(out) : [];
+    } catch { rows = []; }
+    const got = new Map(rows.filter((r) => typeof r.name === 'string' && r.name.trim()).map((r) => [r.id, r.name.trim().slice(0, 80)]));
+    for (const id of want) cache.set(id, { at: now, name: got.get(id) || null });
+  }
+  return new Map(ids.map((id) => [id, cache.get(id) && cache.get(id).name]).filter(([, name]) => name));
+}