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

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

@@ -0,0 +1,436 @@
+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 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 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);
+    type('-l', sender.startsWith('codex') ? '/new' : '/clear');
+    sleep(ENTER_DELAY_MS);
+    type('Enter');
+    sleep(RESTART_CLEAR_MS);
+    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} in ${delay} seconds. 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.
@@ -119,6 +119,8 @@ et design sketch report <layer>/<name> --variant b --by <model id> "phone"
 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
 ```
 
 Variants are alternatives. A variant never stands for a state of another variant: a hidden or

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.

package/content/skills/handoff/SKILL.md

@@ -15,6 +15,10 @@ continue in a fresh session. Two modes:
 - **save** ("handoff", "wrap up") - write a handoff file.
 - **resume** ("continue from the handoff") - read one and continue the work.
 
+Text after the slug or the name is an instruction from the user, in both modes. In save mode it is
+for the session that resumes, so it must reach that session word for word. In resume mode it wins
+over the Next steps of the file where the two conflict.
+
 Name one invocation form to the user - your own - and never both. The skill is
 installed as `ethlete-handoff`, so under Claude Code the commands are
 `/ethlete-handoff` and `/ethlete-handoff resume [name]`; there is no `/handoff`.
@@ -89,7 +93,13 @@ noise, and it costs the next session the tokens to read it.
 
 Then give a prompt the user can copy into the fresh session, in a code block: the next task, the
 plan file or finding it lives in, and any rule of this session that the repo does not record. Keep
-it to a few lines. When no next task is known, say so instead.
+it to a few lines.
+
+An open item counts as the next task: a known gap, an open finding, or an unbuilt step in the plan,
+in the task, or in your own report of this session. "Everything waits for the user" is true only
+when every open item needs a decision of the user. Then name each decision; do not stop silently.
+In a `tmux` session, restart yourself with the next task as the prompt (see the next section) instead
+of handing the prompt to the user.
 
 Write `{%handoffDir%}/<slug>.md` where `<slug>` is a short kebab-case name for
 the task (use the user-provided slug if they gave one). If the file exists,
@@ -152,12 +162,48 @@ map, not a transcript.
 After writing, tell the user where it landed and that a fresh session should
 resume from it.
 
+## Clear and resume on your own
+
+Run inside a `tmux` session started with the agent-sessions `run` command or the shell functions from `shell-install` (`echo $TMUX` is not empty and
+the agent-sessions script `restart` finds the session)? Then you may clear and
+resume yourself after the save, instead of asking the user to. You decide. Do it only if every line
+is true:
+
+- No sub-agent, workflow or background command still runs. A background command from the old
+  session reports back into the new one, and a sub-agent answer has no reader after the clear.
+- No answer you wait for is open: a peer session, a mailbox reply, a CI run.
+- The tree is committed, or the handoff file names every uncommitted change.
+- The handoff file is saved and its Next steps are concrete.
+
+If one line is false, finish or collect that first. If you cannot, hand the prompt to the user as
+before. Then run, with the slug of the file you saved:
+
+```bash
+node <sessions-skill-dir>/agent-sessions.mjs restart <name> '<resume command> <slug> [<text after the slug>]'
+```
+
+If the user wrote text after the slug of the save command, append it to the prompt word for word.
+Escape each `'` in it as `'\''`. The restart drops anything you leave out, and the fresh session has
+no other way to see it.
+
+`<resume command>` is your own resume form from the top of this guide, with the name this repo
+installed the skill under: `/ethlete-handoff resume` under Claude Code, `ethlete-handoff resume`
+under Codex. A repo that ships its own copy can name it `handoff`, so check the skill directory
+name. A wrong name runs no skill, and the fresh session starts without the file.
+
+`<name>` is the sender name of your own session. Read it first with `tmux display-message -p -t "$TMUX_PANE" '#{session_name}'` and drop the `@<repo>` part: `claude-2@ethlete-sdk` gives `claude-2`. Never take the name from an example: a second Claude session is `claude-2`, not `claude`. The command refuses a session you do not run in. It returns at once. It
+types `/clear` (`/new` for a `codex` name) and the prompt into your pane a few seconds later, so
+end your turn after you run it and do not start another tool call. The `/clear` wipes the pane, so
+the user never sees text you write after the command. Before you run it, put the reason as the
+first line of the handoff file: `Restarted because: <one line>`. End the turn with no text.
+
 ## Resume mode
 
 1. List `{%handoffDir%}/`. Pick the file matching the given name, or the most
    recently modified one if no name was given. If the directory is empty, say so
    and stop.
-2. Read the file fully.
+2. Read the file fully. If its first line starts with `Restarted because:`, show that line to the
+   user first, then delete it from the file.
 3. Verify reality still matches: current branch, `git status`, last commit. If
    they diverge from the handoff (e.g. someone committed in between), say what
    changed and adapt - the repo is the truth, the handoff is the guide.

package/content/skills/sdk-update/SKILL.md

@@ -86,6 +86,13 @@ Every task carries a `kind`, and the kind decides who acts:
 3. Delete the task files you finished under `.ethlete/update`, and leave the ones you could not decide.
 4. Tell the user, per task: what you changed, and what still needs their decision.
 
+## Known traps
+
+- **Angular 22: `a?.b` gives `undefined`, not `null`.** Once the `$safeNavigationMigration` flag is
+  gone, a pipe that treats `null` and `undefined` differently breaks at runtime, with no type error. A
+  pipe that resets its state on `undefined` returns `null`, and the template then throws on a member
+  read. Pass `null` explicitly: `(x?.store ?? null) | suspense`.
+
 ## Rules
 
 - **Never invent a migration.** Only the tasks in `.ethlete/update` and the guides they link are real.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.27",
+  "version": "0.1.0-next.28",
   "repository": {
     "type": "git",
     "url": "https://github.com/ethlete-io/ethdk",

package/src/index.js

@@ -21,6 +21,7 @@ const cli_args_1 = require("./lib/cli-args");
 const config_1 = require("./lib/config");
 const git_flow_command_1 = require("./lib/git-flow-command");
 const load_content_1 = require("./lib/load-content");
+const sessions_command_1 = require("./lib/sessions-command");
 const migrate_1 = require("./lib/migrate");
 const output_style_command_1 = require("./lib/output-style-command");
 const package_runner_1 = require("./lib/package-runner");
@@ -40,6 +41,9 @@ const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into y
   ethlete-agents timetrack Ask the running Timetrack app about Jira - it holds this
                            machine's credentials, so no repo needs a token
                            (status, instance, issue, search, project, create, log)
+  ethlete-agents sessions  Run agents in tmux sessions of one checkout: message them, wake idle
+                           ones, restart one with a prompt, claim paths (run, up, down, restart,
+                           send, inbox, claim). The old name "mailbox" works too
   ethlete-agents migrate   Convert the repo to the AGENTS.md + .agents/skills layout:
                            CLAUDE.md content moves into AGENTS.md (CLAUDE.md becomes an
                            @AGENTS.md import), hand-written .claude/skills move to
@@ -112,6 +116,9 @@ const run = (argv) => {
     switch (command) {
         case 'git-flow':
             return (0, git_flow_command_1.gitFlowCommand)({ root, argv: argv.slice(1) });
+        case 'sessions':
+        case 'mailbox':
+            return (0, sessions_command_1.sessionsCommand)({ argv: argv.slice(1) });
         case 'output-style':
             return (0, output_style_command_1.outputStyleCommand)({ argv: argv.slice(1) });
         case 'timetrack':