@ethlete/agent-rules 0.1.0-next.27 → 0.1.0-next.29

package/content/skills/agent-sessions/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: agent-sessions
+description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt, and claim paths so two agents do not overwrite each other. Read before you edit a shared file while another agent may be active, and when the user says "mailbox", "coordinate with the other agent", "claim a file", "hand off to the other agent", or "restart the session".
+kind: skill
+scope: both
+---
+
+# Agent sessions
+
+One script, {%resource:agent-sessions.mjs%}, does three jobs for the agents of one checkout:
+
+- **Sessions.** It runs each agent in a `tmux` session, and it can clear a session and start it with a prompt.
+- **Messages.** Agents send each other messages through an append-only JSON-lines file, the mailbox. A dispatcher wakes an idle agent.
+- **Claims.** An agent announces the paths it edits, so two agents do not overwrite each other.
+
+Below, `<skill-dir>` is the directory this file sits in, and `<name>` is your own sender name. Where
+the `ethlete-agents` package is a dependency, `npx ethlete-agents sessions <command>` runs the same
+script, so you do not need `<skill-dir>`. The older name `npx ethlete-agents mailbox` works too.
+
+```bash
+node <skill-dir>/agent-sessions.mjs run <name> <command...>
+node <skill-dir>/agent-sessions.mjs up <name>[=<command>]...
+node <skill-dir>/agent-sessions.mjs restart <name> [--after <seconds>] <prompt...>
+node <skill-dir>/agent-sessions.mjs down [<name>...]
+node <skill-dir>/agent-sessions.mjs shell-install [<agent>...] [--file <path>] [--remove] [--dry-run]
+node <skill-dir>/agent-sessions.mjs shell-init [<agent>...]
+node <skill-dir>/agent-sessions.mjs send <name> [--to <agent>] '<message>'
+node <skill-dir>/agent-sessions.mjs inbox <name> [--wait <seconds>]
+node <skill-dir>/agent-sessions.mjs read [--last <n>] [--all]
+node <skill-dir>/agent-sessions.mjs watch <name>
+node <skill-dir>/agent-sessions.mjs dispatch
+node <skill-dir>/agent-sessions.mjs claim <name> <path...> [--ttl <hours>] [--force]
+node <skill-dir>/agent-sessions.mjs release <name> [path...]
+node <skill-dir>/agent-sessions.mjs claims
+```
+
+## Quick start for a person
+
+Nothing runs until you start it, so a person who does not use this does nothing. To try it:
+
+1. Run `node <skill-dir>/agent-sessions.mjs shell-install`. It adds one function per agent to your shell file.
+2. Open a new terminal. In the repo, type `claude` or `codex` as usual. The function starts the agent in a `tmux` session and starts the dispatcher.
+3. Ask one agent to message the other. An idle agent wakes when a message carries `--to <agent>`.
+4. Run `node <skill-dir>/agent-sessions.mjs down` to stop the dispatcher. Run `shell-install --remove` to undo step 1.
+
+## Sessions
+
+`run <name> <command...>` starts the command in the `tmux` session `<name>@<repo>`, or attaches if it runs already. It also starts the dispatcher when none runs. Session names carry the repo name, so `codex` in two repos never collides. If that session has a terminal attached already, `run` starts `<name>-2`, then `<name>-3`, and so on. A detached session is attached again. So a second `claude` terminal gets its own agent.
+
+`up codex=codex gemini=gemini` starts a detached `tmux` session per agent, named like its sender name, and runs the command in it. It also starts a session named `mailbox-dispatch` that runs `dispatch`. A running session is left alone. Attach to a session with `tmux attach -t <name>`. Detach with `Ctrl-b`, then `d`. The session and its agent keep running. Use `down` to stop the dispatcher and the named sessions.
+
+`restart <name> <prompt...>` types the clear command (`/clear`, or `/new` for a `codex` name) and then the prompt into the session `<name>@<repo>`, no sooner than `--after` seconds (default 5). It waits until that session ended its turn and its prompt holds no typed text, and gives up after 30 minutes. The command returns at once, so end your turn after it. An agent uses it to clear itself and resume from its saved work state. It refuses any session other than the caller's own (from `$TMUX_PANE`), and the error names the caller's own sender name. Background commands of the old session still report into the new one.
+
+`shell-install` writes one shell function per agent into `~/.zshrc` or `~/.bashrc`, between two marker lines. A second run replaces the block, and `--remove` deletes it. Use `--file` for another startup file and `--dry-run` to preview. After a new terminal opens, typing `claude` or `codex` in a repo with this skill runs the agent through `run`. Elsewhere the function starts the plain command. Run `shell-install` only when the user asks: it changes a file the user owns. `shell-init` prints the same functions without writing a file.
+
+Choose a `<name>` that no other agent uses, for example `agent-a` or `agent-b`. Two sessions with one name look like one agent.
+
+## Messages
+
+The mailbox file is `.ethlete/mailbox.jsonl` in the git root. The first write also creates `.ethlete/.gitignore`, so the file stays out of git. Set `AGENT_MAILBOX` to use another path. For two Claude Code sessions, the `SendMessage` tool is the better channel. The mailbox is for agents that cannot reach each other directly.
+
+An idle agent cannot read the mailbox. One `dispatch` process outside every agent fixes this. It polls the mailbox for free. When a message carries `--to <agent>`, it waits a short grace period and then, if the agent has not read the message, types a wake-up line into the `tmux` session `<agent>@<repo>`, or a session named only `<agent>`. The agent then runs `inbox` and acts. A message without `--to` wakes nobody.
+
+If the prompt of the agent holds typed text, the dispatcher waits until that text is sent or cleared. It checks again every 2 seconds. An open menu, for example a permission dialog, also makes it wait. If the agent is in the middle of a turn, the wake-up line waits as its next prompt. An agent in a `tmux` session does not need the `--wait` loop, which costs a turn at every timeout. If you wait for an answer in a session without `tmux`, run `inbox <name> --wait 120`: it blocks until a message arrives or 120 seconds pass. If it prints "No new messages.", run it again. A background `--wait` ends after one message, so it is not a lasting watch.
+
+- `inbox` keeps one cursor per sender name, so it never repeats a message. The first call shows the last 20.
+- `read` shows the last 20 messages. Use `--all` for the full history.
+- `send` with no message reads it from standard input, so a long message needs no shell quoting.
+- `watch` is optional. It runs until you stop it. In Claude Code, start it with the `Monitor` tool, so a new message wakes the session. Without such a feature, rely on `inbox`.
+- Never rewrite or truncate the file. Only the script appends to it.
+- Keep credentials and personal data out of the mailbox.
+
+## Claims
+
+1. At the start of a task, run `claims` and `inbox`. They show what other agents hold and said.
+2. Before you edit a file, run `claim` with the exact paths. A directory path claims everything below it. `claim` also prints the messages you have not seen yet.
+3. If `claim` reports a conflict, do not edit. Run `send` to ask the holder for a handoff, then wait.
+4. After each larger step, run `inbox` again. Most agents cannot wake on new output, so you must pull messages yourself.
+5. When you finish, run `release`. A claim also expires after 4 hours, or after `--ttl` hours.
+
+A claim is advisory, not a lock. `--force` claims over another agent: use it only after the holder agreed. Silence is not approval. Acknowledge each handoff in words. No agent starts automatically. The user starts each one.

package/content/skills/agent-sessions/agent-sessions.mjs

@@ -0,0 +1,460 @@
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, watchFile, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const root = (() => {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+})();
+const mailbox = process.env.AGENT_MAILBOX ?? join(root, '.ethlete/mailbox.jsonl');
+const script = fileURLToPath(import.meta.url);
+const hasRootScript = (name) => {
+  try {
+    return Boolean(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).scripts?.[name]);
+  } catch {
+    return false;
+  }
+};
+const inboxCommand = (agent) => {
+  if (existsSync(join(root, 'node_modules/.bin/ethlete-agents'))) return `npx ethlete-agents sessions inbox ${agent}`;
+  if (hasRootScript('agents:sessions')) return `yarn agents:sessions inbox ${agent}`;
+  return `node ${script} inbox ${agent}`;
+};
+const DEFAULT_TTL_HOURS = 4;
+const DEFAULT_LAST = 20;
+const ENTER_DELAY_MS = 400;
+const WAKE_GRACE_MS = 1500;
+const DRAFT_RETRY_MS = 2000;
+const RESTART_AFTER_SECONDS = 5;
+const RESTART_CLEAR_MS = 2500;
+const RESTART_POLL_MS = 2000;
+const RESTART_WAIT_MS = 30 * 60 * 1000;
+const repoSlug = basename(root).replace(/[.:]/g, '-');
+const sessionFor = (agent) => `${agent}@${repoSlug}`;
+const DISPATCH_SESSION = process.env.AGENT_MAILBOX_DISPATCH_SESSION ?? `mailbox-dispatch@${repoSlug}`;
+
+const takeFlag = (args, name, hasValue) => {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const [flag, value] = args.splice(index, hasValue ? 2 : 1);
+  return hasValue ? value : flag;
+};
+
+const args = process.argv.slice(2);
+const last = takeFlag(args, '--last', true);
+const ttl = takeFlag(args, '--ttl', true);
+const all = takeFlag(args, '--all', false);
+const force = takeFlag(args, '--force', false);
+const waitSeconds = takeFlag(args, '--wait', true);
+const recipient = takeFlag(args, '--to', true);
+const rcFile = takeFlag(args, '--file', true);
+const remove = takeFlag(args, '--remove', false);
+const afterSeconds = takeFlag(args, '--after', true);
+const now = takeFlag(args, '--now', false);
+const dryRun = takeFlag(args, '--dry-run', false);
+const [command, sender, ...words] = args;
+
+const help = `Shared agent mailbox: ${mailbox}
+
+Send:    node ${script} send <name> [--to <agent>] '<message>'   (no message: read it from stdin)
+Inbox:   node ${script} inbox <name> [--wait <seconds>]   (only the messages you have not seen yet;
+                                                           --wait blocks until one arrives or the time ends)
+Read:    node ${script} read [--last <n>] [--all]     (default: the last ${DEFAULT_LAST} messages)
+Watch:   node ${script} watch <name>
+Claim:   node ${script} claim <name> <path...> [--ttl <hours>] [--force]
+Release: node ${script} release <name> [path...]      (no path: release every claim of <name>)
+Claims:  node ${script} claims
+Up:      node ${script} up <name>[=<command>]...      (start a tmux session per agent, plus one that runs dispatch)
+Run:     node ${script} run <name> <command...>       (start or attach the agent in its tmux session; starts dispatch)
+Install: node ${script} shell-install [<agent>...] [--file <path>] [--remove] [--dry-run]
+                                                      (write the shell functions into ~/.zshrc or ~/.bashrc)
+Shell:   node ${script} shell-init [<agent>...]       (print shell functions that wrap each agent with run; default: claude codex)
+Restart: node ${script} restart <name> [--after <seconds>] <prompt...>
+                                                      (type the clear command and then the prompt into the tmux session of <name>)
+Down:    node ${script} down [<name>...]              (stop dispatch; stop the named sessions too)
+Dispatch: node ${script} dispatch                      (wake the tmux session named <agent> for each message sent --to <agent>)
+
+Protocol: append one JSON object per line; never rewrite or truncate.
+Fields: timestamp (UTC), sender, message. A claim also has paths and expires.
+Pick a sender name no other agent uses. Claim the paths you edit before you edit them.
+A claim is advisory, not a lock: it expires after ${DEFAULT_TTL_HOURS} hours unless --ttl says otherwise.
+Silence is not approval. Acknowledge handoffs explicitly.
+Watch prints existing messages and then new messages from other senders every second.
+Keep credentials and personal data out of the mailbox. No agent is started automatically.
+`;
+
+const tmux = (...tmuxArgs) => spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
+const quote = (text) => `'${text.replaceAll("'", "'\\''")}'`;
+const sessionExists = (name) => tmux('has-session', '-t', `=${name}`).status === 0;
+const ONE_SHOT_FLAGS = new Set(['-p', '--print', '-v', '--version', '-h', '--help']);
+const runsInSession = (agentArgs) =>
+  Boolean(process.stdin.isTTY && process.stdout.isTTY) && !agentArgs.some((arg) => ONE_SHOT_FLAGS.has(arg));
+
+/**
+ * Reads the last prompt line (`❯` for Claude Code, `›` for Codex) of the pane. Dim text is the empty
+ * prompt's placeholder, so it does not count. A menu cursor (`❯ 1. Yes`) also counts, which keeps a
+ * wake-up line from answering a permission dialog.
+ */
+const SGR = `${String.fromCharCode(27)}\\[([0-9;]*)m`;
+const isBusy = (session) => /esc to inte/i.test(tmux('capture-pane', '-p', '-t', `=${session}:`).stdout ?? '');
+
+/** Waits until the agent ended its turn and nobody types in its prompt, twice in a row; `false` after the time limit. */
+const waitForQuiet = (session) => {
+  const end = Date.now() + RESTART_WAIT_MS;
+  let quiet = 0;
+  while (Date.now() < end) {
+    quiet = isBusy(session) || hasDraft(session) ? 0 : quiet + 1;
+    if (quiet === 2) return true;
+    sleep(RESTART_POLL_MS);
+  }
+  return false;
+};
+
+const hasDraft = (session) => {
+  const pane = tmux('capture-pane', '-p', '-e', '-t', `=${session}:`).stdout ?? '';
+  const prompt = pane
+    .split('\n')
+    .reverse()
+    .find((line) => /^\s*[❯›]/.test(line.replace(new RegExp(SGR, 'g'), '')));
+  if (!prompt) return false;
+  let dim = false;
+  const visible = prompt
+    .split(new RegExp(`(${SGR.replace('(', '(?:')})`))
+    .map((part) => {
+      const codes = part.match(new RegExp(`^${SGR}$`))?.[1].split(';');
+      if (!codes) return dim ? '' : part;
+      codes.forEach((code) => {
+        if (code === '2') dim = true;
+        if (code === '' || code === '0' || code === '22') dim = false;
+      });
+      return '';
+    })
+    .join('');
+  return visible.replace(/^\s*[❯›]/, '').trim().length > 0;
+};
+const isAttached = (name) => tmux('list-clients', '-t', `=${name}`).stdout.trim() !== '';
+const freeSessionFor = (agent) => {
+  for (let number = 1; ; number++) {
+    const session = sessionFor(number === 1 ? agent : `${agent}-${number}`);
+    if (!sessionExists(session) || !isAttached(session)) return session;
+  }
+};
+const startSession = (name, shellCommand, quiet = false) => {
+  if (sessionExists(name)) return quiet ? undefined : process.stdout.write(`Session ${name} already runs.\n`);
+  const result = tmux('new-session', '-d', '-s', name, '-c', root, ...(shellCommand ? [shellCommand] : []));
+  if (result.status !== 0) return process.stderr.write(`Could not start ${name}: ${result.stderr.trim()}\n`);
+  if (!quiet) process.stdout.write(`Started ${name}. Attach with: tmux attach -t ${name}\n`);
+};
+
+const IGNORED = ['mailbox.jsonl', 'mailbox.cursor.*'];
+
+const prepare = () => {
+  mkdirSync(dirname(mailbox), { recursive: true });
+  if (process.env.AGENT_MAILBOX) return;
+  const ignore = join(dirname(mailbox), '.gitignore');
+  const present = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  const missing = IGNORED.filter((line) => !present.split('\n').includes(line));
+  if (missing.length)
+    writeFileSync(ignore, `${present && !present.endsWith('\n') ? `${present}\n` : present}${missing.join('\n')}\n`);
+};
+
+const append = (entry) => {
+  prepare();
+  appendFileSync(mailbox, `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`, 'utf8');
+};
+
+const parse = (line) => {
+  if (!line.trim()) return undefined;
+  try {
+    return JSON.parse(line);
+  } catch {
+    process.stderr.write('Ignoring malformed mailbox line.\n');
+    return undefined;
+  }
+};
+
+const entries = () => (existsSync(mailbox) ? readFileSync(mailbox, 'utf8').split('\n').map(parse).filter(Boolean) : []);
+
+const show = (entry) => process.stdout.write(`[${entry.timestamp}] ${entry.sender}: ${entry.message}\n`);
+
+const inboxCursor = (reader) => join(dirname(mailbox), `mailbox.cursor.${reader}`);
+
+const unreadFor = (reader) => {
+  const cursor = inboxCursor(reader);
+  const history = entries();
+  const seen = existsSync(cursor) ? Number(readFileSync(cursor, 'utf8')) : history.length - DEFAULT_LAST;
+  return { count: history.length, unread: history.slice(Math.max(0, seen)).filter((entry) => entry.sender !== reader) };
+};
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+const showInbox = (reader, waitFor = 0) => {
+  const deadline = Date.now() + waitFor * 1000;
+  let { count, unread } = unreadFor(reader);
+  while (!unread.length && Date.now() < deadline) {
+    sleep(1000);
+    ({ count, unread } = unreadFor(reader));
+  }
+  if (!unread.length) process.stdout.write('No new messages.\n');
+  unread.forEach(show);
+  prepare();
+  writeFileSync(inboxCursor(reader), String(count));
+};
+
+const toRepoPath = (path) => relative(root, resolve(path)).split('\\').join('/');
+
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+
+const activeClaims = () => {
+  const now = Date.now();
+  const claims = [];
+  for (const entry of entries()) {
+    if (entry.type === 'claim') {
+      for (const path of entry.paths) claims.push({ sender: entry.sender, path, expires: entry.expires });
+    } else if (entry.type === 'release') {
+      for (let index = claims.length - 1; index >= 0; index--) {
+        const claim = claims[index];
+        const released = !entry.paths?.length || entry.paths.some((path) => overlaps(path, claim.path));
+        if (claim.sender === entry.sender && released) claims.splice(index, 1);
+      }
+    }
+  }
+  return claims.filter((claim) => Date.parse(claim.expires) > now);
+};
+
+if (command === 'send' && sender) {
+  const message = words.length ? words.join(' ') : process.stdin.isTTY ? '' : readFileSync(0, 'utf8').trim();
+  if (!message) {
+    process.stderr.write('No message given.\n');
+    process.exitCode = 1;
+  } else {
+    append({ sender, message, ...(recipient ? { to: recipient } : {}) });
+    process.stdout.write(`Sent as ${sender}.\n`);
+  }
+} else if (command === 'up') {
+  const withEnv = process.env.AGENT_MAILBOX ? `AGENT_MAILBOX=${quote(process.env.AGENT_MAILBOX)} ` : '';
+  startSession(DISPATCH_SESSION, `${withEnv}node ${quote(script)} dispatch`);
+  [sender, ...words].filter(Boolean).forEach((spec) => {
+    const [name, ...rest] = spec.split('=');
+    startSession(sessionFor(name), rest.join('=') || undefined);
+  });
+} else if (command === 'run' && sender && words.length && !runsInSession(words.slice(1))) {
+  const [program, ...programArgs] = words;
+  process.exitCode = spawnSync(program, programArgs, { stdio: 'inherit' }).status ?? 1;
+} else if (command === 'run' && sender && words.length) {
+  const withEnv = process.env.AGENT_MAILBOX ? `AGENT_MAILBOX=${quote(process.env.AGENT_MAILBOX)} ` : '';
+  if (!sessionExists(DISPATCH_SESSION))
+    startSession(DISPATCH_SESSION, `${withEnv}node ${quote(script)} dispatch`, true);
+  const session = freeSessionFor(sender);
+  const shellCommand = words.map(quote).join(' ');
+  if (process.env.TMUX) {
+    if (!sessionExists(session)) tmux('new-session', '-d', '-s', session, '-c', process.cwd(), shellCommand);
+    process.exitCode = spawnSync('tmux', ['switch-client', '-t', `=${session}`], { stdio: 'inherit' }).status ?? 1;
+  } else {
+    process.exitCode =
+      spawnSync('tmux', ['new-session', '-A', '-s', session, '-c', process.cwd(), shellCommand], { stdio: 'inherit' })
+        .status ?? 1;
+  }
+} else if (command === 'shell-init' || command === 'shell-install') {
+  const agents = [sender, ...words].filter(Boolean);
+  const functions = (agents.length ? agents : ['claude', 'codex'])
+    .map(
+      (agent) => `${agent}() {
+  local root script
+  root=$(git rev-parse --show-toplevel 2>/dev/null) && script="$root/.agents/skills/ethlete-agent-sessions/agent-sessions.mjs"
+  if [ -n "$script" ] && [ -f "$script" ] && command -v tmux >/dev/null; then
+    node "$script" run ${agent} ${agent} "$@"
+  else
+    command ${agent} "$@"
+  fi
+}
+`,
+    )
+    .join('');
+  if (command === 'shell-init') {
+    process.stdout.write(functions);
+  } else {
+    const shell = basename(process.env.SHELL ?? '');
+    const file = rcFile ?? (shell === 'zsh' ? '.zshrc' : shell === 'bash' ? '.bashrc' : undefined);
+    if (!file) {
+      process.stderr.write('Unknown shell. Pass --file <path> to the startup file.\n');
+      process.exitCode = 1;
+    } else {
+      const path = rcFile ? resolve(rcFile) : join(homedir(), file);
+      const present = existsSync(path) ? readFileSync(path, 'utf8') : '';
+      const start = '# >>> ethlete agent-sessions >>>';
+      const end = '# <<< ethlete agent-sessions <<<';
+      const without = ['agent-mailbox', 'agent-sessions']
+        .reduce(
+          (text, name) =>
+            text.replace(new RegExp(`\\n?# >>> ethlete ${name} >>>[\\s\\S]*?# <<< ethlete ${name} <<<\\n?`), '\n'),
+          present,
+        )
+        .replace(/\n+$/, '\n');
+      const block = `${start}\n${functions}${end}\n`;
+      const next = remove ? without : `${without}\n${block}`;
+      if (dryRun) {
+        process.stdout.write(`Would write ${path}:\n${remove ? '(block removed)\n' : block}`);
+      } else {
+        writeFileSync(path, next);
+        process.stdout.write(
+          `${remove ? 'Removed the block from' : 'Wrote the block to'} ${path}. Open a new terminal.\n`,
+        );
+      }
+    }
+  }
+} else if (command === 'restart' && sender && words.length) {
+  const session = [sessionFor(sender), sender].find(sessionExists);
+  const own = process.env.TMUX_PANE
+    ? tmux('display-message', '-p', '-t', process.env.TMUX_PANE, '#{session_name}').stdout.trim()
+    : null;
+  if (!session) {
+    process.stderr.write(`No tmux session for ${sender}.\n`);
+    process.exitCode = 1;
+  } else if (own && own !== session) {
+    process.stderr.write(
+      `Refused: ${session} is not your session. You run in ${own}, so pass ${own.replace(`@${repoSlug}`, '')}.\n`,
+    );
+    process.exitCode = 1;
+  } else if (now) {
+    const type = (...keys) => tmux('send-keys', '-t', `=${session}:`, ...keys);
+    sleep(Number(afterSeconds ?? RESTART_AFTER_SECONDS) * 1000);
+    if (!waitForQuiet(session)) {
+      process.exitCode = 1;
+    } else {
+      type('-l', sender.startsWith('codex') ? '/new' : '/clear');
+      sleep(ENTER_DELAY_MS);
+      type('Enter');
+      sleep(RESTART_CLEAR_MS);
+      if (waitForQuiet(session)) {
+        type('-l', words.join(' '));
+        sleep(ENTER_DELAY_MS);
+        type('Enter');
+      }
+    }
+  } else {
+    const delay = Number(afterSeconds ?? RESTART_AFTER_SECONDS);
+    spawn(process.execPath, [script, 'restart', sender, '--now', '--after', String(delay), ...words], {
+      detached: true,
+      stdio: 'ignore',
+    }).unref();
+    process.stdout.write(
+      `Restarting ${session} once its turn ended and its prompt is empty, ${delay} seconds at the earliest. End your turn now.\n`,
+    );
+  }
+} else if (command === 'down') {
+  [DISPATCH_SESSION, ...[sender, ...words].filter(Boolean).map(sessionFor)].forEach((name) => {
+    const result = tmux('kill-session', '-t', `=${name}`);
+    process.stdout.write(result.status === 0 ? `Stopped ${name}.\n` : `No session ${name}.\n`);
+  });
+} else if (command === 'dispatch') {
+  prepare();
+  appendFileSync(mailbox, '');
+  let seen = entries().length;
+  const due = {};
+  const waiting = new Set();
+  const wake = (agent) => {
+    if (!unreadFor(agent).unread.length) return;
+    const text = `New mailbox message for ${agent}. Run: ${inboxCommand(agent)}`;
+    const session = [sessionFor(agent), agent].find(sessionExists);
+    if (!session) return process.stderr.write(`No tmux session for ${agent}.\n`);
+    if (hasDraft(session)) {
+      if (!waiting.has(agent)) process.stdout.write(`Waiting for the typed text in ${session}.\n`);
+      waiting.add(agent);
+      due[agent] = Date.now() + DRAFT_RETRY_MS;
+      return;
+    }
+    waiting.delete(agent);
+    spawnSync('tmux', ['send-keys', '-t', `=${session}:`, '-l', text]);
+    sleep(ENTER_DELAY_MS);
+    spawnSync('tmux', ['send-keys', '-t', `=${session}:`, 'Enter']);
+    process.stdout.write(`Woke ${session}.\n`);
+  };
+  const poll = () => {
+    const history = entries();
+    const fresh = history.slice(seen);
+    seen = history.length;
+    fresh
+      .filter((entry) => entry.to && entry.to !== entry.sender)
+      .forEach((entry) => (due[entry.to] ??= Date.now() + WAKE_GRACE_MS));
+    Object.keys(due)
+      .filter((agent) => due[agent] <= Date.now())
+      .forEach((agent) => {
+        delete due[agent];
+        wake(agent);
+      });
+  };
+  process.stdout.write(`Dispatching for ${resolve(mailbox)}\n`);
+  setInterval(poll, 1000);
+} else if (command === 'inbox' && sender) {
+  showInbox(sender, Number(waitSeconds ?? 0));
+} else if (command === 'read') {
+  const history = entries();
+  (all ? history : history.slice(-Number(last ?? DEFAULT_LAST))).forEach(show);
+} else if (command === 'claims') {
+  const claims = activeClaims();
+  if (!claims.length) process.stdout.write('No active claims.\n');
+  claims.forEach((claim) => process.stdout.write(`${claim.path}  ${claim.sender}  until ${claim.expires}\n`));
+} else if (command === 'claim' && sender && words.length) {
+  showInbox(sender);
+  const paths = words.map(toRepoPath);
+  const conflicts = activeClaims().filter(
+    (claim) => claim.sender !== sender && paths.some((path) => overlaps(path, claim.path)),
+  );
+  if (conflicts.length && !force) {
+    conflicts.forEach((claim) =>
+      process.stderr.write(`Claimed by ${claim.sender}: ${claim.path} until ${claim.expires}\n`),
+    );
+    process.stderr.write('Ask for a handoff, or pass --force to claim anyway.\n');
+    process.exitCode = 2;
+  } else {
+    const hours = ttl === undefined ? DEFAULT_TTL_HOURS : Number(ttl);
+    const expires = new Date(Date.now() + hours * 3_600_000).toISOString();
+    append({ sender, type: 'claim', paths, expires, message: `claims ${paths.join(', ')}` });
+    process.stdout.write(`Claimed ${paths.join(', ')} as ${sender} until ${expires}.\n`);
+  }
+} else if (command === 'release' && sender) {
+  const paths = words.map(toRepoPath);
+  append({
+    sender,
+    type: 'release',
+    paths,
+    message: paths.length ? `releases ${paths.join(', ')}` : 'releases all claims',
+  });
+  process.stdout.write(`Released as ${sender}.\n`);
+} else if (command === 'watch' && sender) {
+  prepare();
+  appendFileSync(mailbox, '');
+  let consumed = 0;
+  let pending = '';
+  const update = () => {
+    const contents = readFileSync(mailbox, 'utf8');
+    if (contents.length < consumed) {
+      process.stderr.write('Mailbox was truncated; restarting read.\n');
+      consumed = 0;
+      pending = '';
+    }
+    pending += contents.slice(consumed);
+    consumed = contents.length;
+    const lines = pending.split('\n');
+    pending = lines.pop() ?? '';
+    lines
+      .map(parse)
+      .filter((entry) => entry && entry.sender !== sender)
+      .forEach(show);
+  };
+  process.stdout.write(`Watching ${resolve(mailbox)} as ${sender}\n`);
+  update();
+  watchFile(mailbox, { interval: 1000 }, update);
+} else {
+  process.stdout.write(help);
+  if (command && command !== '--help') process.exitCode = 1;
+}

package/content/skills/design-exploration/SKILL.md

@@ -45,7 +45,7 @@ finished while the user is still talking about it.
 check that a variant renders. In a repository with `et design`, take it with
 `et design shot <layer>/<name> --states [--variants]`: one contact sheet of every state, and
 every variant of the open sketch, with a label per cell; below each variant row, a diff row marks
-the pixels that differ from the merged state in red, or says "no pixel change" (with ", but the markup differs" when only the markup changed, e.g. both sides miss the same content). It prints the PNG path last. `--scale 2` enlarges a small part; `--crop x,y,w,h` cuts each cell to that CSS-pixel box, to judge hairlines. `--interaction hover` forces an interaction on every cell. `--state a,b` draws only those states, to compare them side by side. With `--variants`, `--diff-props` compares each variant with the merged part drawn with the variant's state props, so changed props do not paint the diff red. It draws
+the pixels that differ from the merged state in red, or says "no pixel change" (with ", but the markup differs" when only the markup changed, e.g. both sides miss the same content). It prints the PNG path last. `--scale 2` enlarges a small part; `--crop x,y,w,h` cuts each cell to that CSS-pixel box, to judge hairlines. `--interaction hover` forces an interaction on every cell. `--state a,b` draws only those states, to compare them side by side. With `--variants`, `--round r2` or `--variant i,j` draws only those variants next to the merged row, so the current round stays readable; it filters the picture, never the checks. With `--variants`, `--diff-props` compares each variant with the merged part drawn with the variant's state props, so changed props do not paint the diff red. It draws
 undimmed, whatever Studio shows. Do not write a scratch script for batch shots.
 
 If a second defect appears, add it to the open list and give it one line. Do not draw it.
@@ -115,12 +115,19 @@ answers. Variants are drawn at the same geometry, and one variant wins only agai
 
 ```bash
 et design sketch new <layer>/<name> --variants a,b --by <model id> [--like <layer>/<name>] [--variant-note a=<text>]… [--product <p>]   # each variant starts as a copy of the part
+et design sketch new <layer>/<name> <layer>/<name>… --variants a --by <model id>   # one change across several parts: one sketch, one ready, one merge
 et design sketch report <layer>/<name> --variant b --by <model id> "phone"         # tell Studio what you build now
 et design sketch report <layer>/<name> --variant b --by <model id> --done         # you stopped drawing b; Studio shows its frames
 et design sketch check [<layer>/<name>] [--fix]                                    # each variant laid over the product
 et design sketch ready <layer>/<name> --by <model id>                              # now the user can pick
+et design sketch reject <layer>/<name> --variant b [--reason <text>] --by <model id> # only when the user rejected b; no pick or merge until reopened
+et design sketch reopen <layer>/<name> --variant b [--reason <text>] --by <model id> # only when the user takes b back; the rejection stays in the history
 ```
 
+One change across several parts (an alias removal, a token rename) is one sketch with several targets: each
+variant holds every target, and `ready` compares them all. `ready` and `preview` also name every part a `shared/`
+edit reaches.
+
 Variants are alternatives. A variant never stands for a state of another variant: a hidden or
 collapsed mode of variant d is a further state of d, not a variant e. Before you draw a new control,
 look for a control that already does the job (an active rail button that toggles its panel), and
@@ -160,7 +167,9 @@ variant imports it as `@shared/<path>`, and a shared file may import `@system/..
 changed holds its own copy at `<variant>/shared/<path>`; `@shared/<path>` finds that copy first, and a merge
 of that variant takes it. On a merge, `shared/` moves into
 the target's folder as `shared/` with its imports made relative; when no part imports it, it is
-dropped. Only the target may import it: a merge refuses while another part of the picked variant
+dropped. With several targets, each takes only the files it imports, directly or through another
+shared file; a file nobody imports goes back to the target that held it, and the merge refuses one no
+target held. `sketch new` refuses targets whose `shared/` folders hold one path with different contents. Only the target may import it: a merge refuses while another part of the picked variant
 does, so move that code into the part. `sketch new` prints each file it puts in `shared/`, for example
 the `shared/` folder of a merged page: edit it there, as part of the sketch, not in a variant copy.
 

package/content/skills/e2e-triage/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: e2e-triage
+description: Work through a failed Playwright e2e run - read the failures file the @ethlete/cli failure reporter writes, group the failures by error, fix the largest group first, and re-run only the specs that failed. Read when an e2e run fails with more than a few tests, when an `e2e-failures.jsonl` file is present, or before you start a full e2e run after a change.
+kind: skill
+scope: consumer
+requires: ['@ethlete/cli']
+vars: [docsBaseUrl]
+---
+
+# Triage a failed e2e run
+
+Many failed tests rarely mean many bugs. In one real run, a single change in a shared pipe failed 61
+tests. After the fix, 158 of the first 159 retried tests passed. So find the shared cause first, and
+never fix failures one test at a time from the top of the log.
+
+## Before the run
+
+1. Check that `playwright.config.ts` lists `@ethlete/cli/playwright/failure-reporter` in `reporter`.
+   If not, add it next to the reporter that is there: `[['list'], ['@ethlete/cli/playwright/failure-reporter']]`.
+   The reporter writes one JSON line per failed attempt while the run goes on. The guide is
+   {%docsBaseUrl%}/cli/e2e.
+2. Run the specs of the files you changed first. Start the full suite only when they pass. A full
+   run takes long, and one broken shared file fails it everywhere.
+
+## Read the failures
+
+The file is `e2e-failures.jsonl` next to `playwright.config.ts`, unless `E2E_FAILURES_FILE` or the
+`outputFile` option of the reporter names another path. You can read it while the run goes on.
+
+Each line has `test`, `location`, `project`, `status`, `retry`, `seconds`, `error`, `detail` and `context`.
+`error` holds the first lines of the message. `detail` holds the first later line with a URL, for errors whose first lines do not name it, or `null`. `context` is the path of Playwright's
+`error-context.md`, which holds the page snapshot at the failure.
+
+Do not parse the console log of the run. It mixes the output of parallel workers, and it has no end
+line if the run stops.
+
+## Group, then fix the largest group
+
+1. Normalize the `error` text of each line. Remove line and column numbers, timeouts in ms, ids,
+   hashes and dates. Keep the matcher, the locator and the expected value.
+2. Group the lines by the normalized text. Count the distinct spec files per group, not only the lines.
+   A group that spans many spec files points at shared code: a component, a pipe, a fixture or a
+   test helper.
+3. Take the largest group. Read one `context` file of it, then the code the error points at. Find
+   one cause that explains the whole group.
+4. Fix that cause. Then re-run only the spec files of that group.
+
+A group whose errors are a connection refused (`ERR_CONNECTION_REFUSED`, `ECONNREFUSED`) on a local mock or
+`webServer` port is an infrastructure group, not a test verdict. Check that the server is still up,
+restart it, and re-run those tests before you read them as failures.
+
+Small groups that differ only in a locator often have the same cause. Check them after the large group
+is fixed, because a fix often clears them too.
+
+## Re-run only what failed
+
+Take the spec file from `location`, without the `:line`. Collect each file once, then run:
+
+```bash
+npx playwright test <file> <file> --project=<project> --no-deps
+```
+
+- Pass each file as its own argument. In zsh, an unquoted `$files` is one argument, and Playwright
+  then finds no tests.
+- `--no-deps` skips the setup projects. Leave it out if the failure is in a setup project, or if the
+  setup state is gone.
+- `--project` comes from the `project` field. Run one call per project.
+
+## Retries and flaky tests
+
+With `retries` on, a test that fails each attempt has one line per attempt (`retry` 0, 1, and so on).
+A test with a line for `retry` 0 and no line for the last retry passed on a later attempt: it is flaky.
+Report a flaky test, but fix the stable failures first.
+
+## Rules
+
+- Never skip a failed test, or mark it with `test.fail()` or `test.fixme()`, to make a run pass.
+- Never change an assertion to match the wrong value the app shows now. A failed e2e test is a
+  signal first. If you think the test is wrong, say why, and ask before you change it.
+- Report per group: the cause, the fix, the spec files you re-ran, and what still fails.