@ethlete/agent-rules 0.1.0-next.32 → 0.1.0-next.33

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.33
+
+### Minor Changes
+
+- `agent-sessions restart --process` starts the agent as a new process in its tmux pane, so a plugin, settings or `PATH` change takes effect.
+
+### Patch Changes
+
+- The builder Stop hook now blocks a turn that ends with more than one line of chat text. `restart --process` keeps the session's role. Resuming a role handoff loads its role skill.
+- The builder Stop hook now counts the final message of the turn from `last_assistant_message`. Claude Code calls the hook before that message reaches the transcript.
+- `agent-sessions restart` treats a pane that shows "Waiting for" background agents as busy, and the skill says to mail the grill session when a self-restart is denied.
+- `agent-sessions restart` accepts the paired builder or grill/docs session as target and logs each peer restart to `restart.log`.
+- `agent-sessions restart` no longer hangs when the background-agent panel is open, and it tells the caller and `--notify` agents when it waits or gives up.
+- `agent-sessions restart --process` keeps the tmux session of the agent, does not send the first prompt of `run` again, and answers the background work dialog of Claude Code with "exit and stop tasks".
+- `agent-sessions restart --process` no longer passes a stored prompt twice, and `run` switches only the client of the calling tmux session.
+- The design exploration skill documents `et design sketch covers` (ADR 0222).
+- `et design sketch covers` on a multi-target sketch takes the part, `<layer>/<name>:<state>[@x,y,w,h]`, and refuses a bare state; compare matches a covered DIFF against that part.
+- The `background-design-commands` hook matches long design commands only at command position, so a heredoc, an unquoted `echo` or a `git commit` message that names `design check` no longer gets denied.
+- The builder Stop hook now parses each Bash command into its simple commands. A heredoc body or a quoted string that names `agent-sessions.mjs send` or `git commit` no longer counts as a report or a commit.
+- The builder Stop hook also blocks a stop one time when the turn ran `git commit` or `git push` and sent no report with `SendMessage` or `agent-sessions send`.
+- The design-exploration skill now describes build-ready, a current check record from `design check`, instead of the removed `design go` and `design accept` commands.
+- The git-safety hook now allows a pathless `git commit` that concludes a merge, no longer denies commands that only mention `git commit` in a grep pattern or heredoc, and drops the obsolete `go.json` rule.
+- Fix `agent-sessions restart` never restarting an idle session whose own chat text said "Waiting for": only the spinner line and the footer count as busy.
+
 ## 0.1.0-next.32
 
 ### Minor Changes

package/content/hooks/background-design-commands.py

@@ -7,8 +7,9 @@ they block the whole session, so a Bash call that runs one without `run_in_backg
 is denied and the agent repeats it in the background.
 
 Matches the `yarn design ...`, `node dist/libs/cli/src/index.js design ...` and
-`npx nx ... studio:e2e` forms. Quoted text is ignored, so a commit message that mentions a
-command does not trip the hook.
+`npx nx ... studio:e2e` forms at command position only. Quoted text, heredoc bodies and
+arguments of other commands (`echo`, `git commit`, `grep`) are ignored, so free text that
+mentions a command does not trip the hook.
 
 Can be disabled per machine via a gitignored ethlete-agents.config.local.json at the repo
 root: {"disableHooks": true} or {"disableHooks": ["background-design-commands"]}.
@@ -25,16 +26,51 @@ HOOK_NAME = "background-design-commands"
 LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
 
 LONG_COMMANDS = (
-    ("design check", re.compile(r"(?:^|[\s;&|])design\s+check(?=\s|$|[;&|])")),
-    ("design compare", re.compile(r"(?:^|[\s;&|])design\s+compare(?=\s|$|[;&|])")),
-    ("design ready", re.compile(r"(?:^|[\s;&|])design\s+ready(?=\s|$|[;&|])")),
-    ("design sketch ready", re.compile(r"(?:^|[\s;&|])design\s+sketch\s+ready(?=\s|$|[;&|])")),
-    ("design harness", re.compile(r"(?:^|[\s;&|])design\s+harness(?=\s|$|[;&|])")),
-    ("studio:e2e", re.compile(r"studio:e2e(?=\s|$|[;&|:])")),
+    ("design check", re.compile(r"\bdesign\s+check(?=\s|$)")),
+    ("design compare", re.compile(r"\bdesign\s+compare(?=\s|$)")),
+    ("design ready", re.compile(r"\bdesign\s+ready(?=\s|$)")),
+    ("design sketch ready", re.compile(r"\bdesign\s+sketch\s+ready(?=\s|$)")),
+    ("design harness", re.compile(r"\bdesign\s+harness(?=\s|$)")),
+    ("studio:e2e", re.compile(r"studio:e2e(?=\s|$|:)")),
     ("--visible-change", re.compile(r"(?:^|\s)--visible-change(?=\s|=|$)")),
 )
 
+LAUNCHERS = frozenset(
+    ("yarn", "npx", "pnpm", "pnpx", "npm", "node", "nx", "bun", "bunx", "et", "ethlete-agents", "bash", "sh", "zsh", "time", "env", "nohup", "timeout", "sudo", "exec", "xargs")
+)
+
 QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
+HEREDOC = re.compile(r"<<-?\s*(?:\"(\w+)\"|'(\w+)'|\\?(\w+))")
+SEPARATORS = re.compile(r"&&|\|\||[;&|\n(){}`]")
+ASSIGNMENT = re.compile(r"^[A-Za-z_]\w*=")
+
+
+def without_heredoc_bodies(command):
+    lines = command.split("\n")
+    kept = []
+    delimiter = None
+    for line in lines:
+        if delimiter is not None:
+            if line.strip() == delimiter:
+                delimiter = None
+            continue
+        kept.append(line)
+        match = HEREDOC.search(line)
+        if match:
+            delimiter = match.group(1) or match.group(2) or match.group(3)
+    return "\n".join(kept)
+
+
+def command_segments(command):
+    """The shell string split into simple commands, with heredoc bodies and quoted text removed."""
+    text = QUOTED.sub(" ", without_heredoc_bodies(command))
+    text = text.replace("$(", ";")
+    return [segment.strip() for segment in SEPARATORS.split(text) if segment.strip()]
+
+
+def at_command_position(segment):
+    words = [word for word in segment.split() if not ASSIGNMENT.match(word)]
+    return bool(words) and os.path.basename(words[0]) in LAUNCHERS
 
 
 def agent_name(argv):
@@ -76,11 +112,13 @@ def disabled_locally(config):
 
 
 def long_command_in(command):
-    """The name of the first long command the shell string runs, or None."""
-    unquoted = QUOTED.sub(" ", command)
-    for name, pattern in LONG_COMMANDS:
-        if pattern.search(unquoted):
-            return name
+    """The name of the first long command the shell string runs at a command position, or None."""
+    for segment in command_segments(command):
+        if not at_command_position(segment):
+            continue
+        for name, pattern in LONG_COMMANDS:
+            if pattern.search(segment):
+                return name
     return None
 
 

package/content/hooks/builder-chat-words.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
-"""Stop hook: logs how many chat words a builder session wrote in the turn that just ended.
+"""Stop hook: logs the chat text of a builder turn and blocks a turn that ends with more than one line.
 
 Only runs in a session started with `--role builder` (ETHLETE_AGENT_ROLE=builder). Appends one
-JSON line to .claude/builder-chat-words.jsonl: timestamp, session_id, words. It never blocks,
-never prints and always exits 0.
+JSON line to .claude/builder-chat-words.jsonl: timestamp, session_id, words, lines, committed, reported, blocked.
+It blocks the stop once (not again while stop_hook_active is set) when the turn's text blocks and
+last_assistant_message hold more than one non-empty line, or when the turn ran `git commit` or `git push` and sent
+no report (no SendMessage, no `agent-sessions send`). It always exits 0.
 """
 
 import json
@@ -12,6 +14,16 @@ import sys
 from datetime import datetime, timezone
 
 LOG_FILE = os.path.join(".claude", "builder-chat-words.jsonl")
+BLOCK_REASON = (
+    "builder: no chat text. Send the report with SendMessage to the grill session; "
+    "end the turn with at most one line."
+)
+REPORT_REASON = (
+    "builder: this turn committed or pushed and sent no report. Send it to the grill session with SendMessage "
+    "or `agent-sessions.mjs send`, then end the turn."
+)
+SEPARATORS = ";&|()\n"
+GIT_OPTIONS_WITH_VALUE = {"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path"}
 
 
 def is_prompt(entry):
@@ -25,8 +37,9 @@ def is_prompt(entry):
     )
 
 
-def count_words(path):
-    words = 0
+def turn_entries(path):
+    texts = []
+    tools = []
     with open(path, encoding="utf-8") as handle:
         for line in handle:
             try:
@@ -36,16 +49,181 @@ def count_words(path):
             if not isinstance(entry, dict):
                 continue
             if is_prompt(entry):
-                words = 0
+                texts = []
+                tools = []
             elif entry.get("type") == "assistant":
                 content = (entry.get("message") or {}).get("content")
                 if isinstance(content, str):
-                    words += len(content.split())
+                    texts.append(content)
                 elif isinstance(content, list):
                     for block in content:
-                        if isinstance(block, dict) and block.get("type") == "text":
-                            words += len(str(block.get("text", "")).split())
-    return words
+                        if not isinstance(block, dict):
+                            continue
+                        if block.get("type") == "text":
+                            texts.append(str(block.get("text", "")))
+                        elif block.get("type") == "tool_use":
+                            tools.append(block)
+    return texts, tools
+
+
+def bash_commands(tools):
+    for tool in tools:
+        if tool.get("name") == "Bash":
+            command = (tool.get("input") or {}).get("command")
+            if isinstance(command, str):
+                yield command
+
+
+def read_heredoc_delimiter(command, index):
+    strip_tabs = command.startswith("-", index)
+    if strip_tabs:
+        index += 1
+    while index < len(command) and command[index] in " \t":
+        index += 1
+    delimiter = []
+    while index < len(command) and command[index] not in " \t" + SEPARATORS + "<>":
+        char = command[index]
+        if char in "'\"":
+            end = command.find(char, index + 1)
+            end = len(command) if end == -1 else end
+            delimiter.append(command[index + 1 : end])
+            index = end + 1
+        else:
+            if char != "\\":
+                delimiter.append(char)
+            index += 1
+    return "".join(delimiter), strip_tabs, index
+
+
+def skip_heredoc_bodies(command, index, heredocs):
+    for delimiter, strip_tabs in heredocs:
+        while index < len(command):
+            end = command.find("\n", index)
+            end = len(command) if end == -1 else end
+            row = command[index:end]
+            index = end + 1
+            if (row.lstrip("\t") if strip_tabs else row) == delimiter:
+                break
+    return index
+
+
+def simple_commands(command):
+    commands = [[]]
+    word = None
+    heredocs = []
+    index = 0
+
+    def end_word():
+        nonlocal word
+        if word is not None:
+            commands[-1].append(word)
+            word = None
+
+    def end_command():
+        end_word()
+        if commands[-1]:
+            commands.append([])
+
+    while index < len(command):
+        char = command[index]
+        if char == "\\":
+            if command.startswith("\n", index + 1):
+                index += 2
+                continue
+            word = (word or "") + command[index + 1 : index + 2]
+            index += 2
+        elif char == "'":
+            end = command.find("'", index + 1)
+            end = len(command) if end == -1 else end
+            word = (word or "") + command[index + 1 : end]
+            index = end + 1
+        elif char == '"':
+            index += 1
+            chars = []
+            while index < len(command) and command[index] != '"':
+                if command[index] == "\\" and index + 1 < len(command):
+                    index += 1
+                chars.append(command[index])
+                index += 1
+            word = (word or "") + "".join(chars)
+            index += 1
+        elif char == "#" and word is None:
+            end = command.find("\n", index)
+            index = len(command) if end == -1 else end
+        elif command.startswith("<<<", index):
+            end_word()
+            index += 3
+        elif command.startswith("<<", index):
+            end_word()
+            delimiter, strip_tabs, index = read_heredoc_delimiter(command, index + 2)
+            heredocs.append((delimiter, strip_tabs))
+        elif char == "\n":
+            end_command()
+            index = skip_heredoc_bodies(command, index + 1, heredocs)
+            heredocs = []
+        elif char in SEPARATORS:
+            end_command()
+            index += 1
+        elif char in " \t":
+            end_word()
+            index += 1
+        else:
+            word = (word or "") + char
+            index += 1
+    end_command()
+    return [words for words in commands if words]
+
+
+def command_words(words):
+    index = 0
+    while index < len(words) and "=" in words[index] and not words[index].startswith("-"):
+        index += 1
+    return words[index:]
+
+
+def is_git_commit(words):
+    words = command_words(words)
+    if not words or os.path.basename(words[0]) != "git":
+        return False
+    index = 1
+    while index < len(words) and words[index].startswith("-"):
+        index += 2 if words[index] in GIT_OPTIONS_WITH_VALUE else 1
+    return index < len(words) and words[index] in ("commit", "push")
+
+
+def is_report_send(words):
+    words = command_words(words)
+    if len(words) < 3:
+        return False
+    if words[0] == "yarn":
+        return words[1:3] == ["agents:sessions", "send"]
+    if os.path.basename(words[0]) != "node":
+        return False
+    scripts = [word for word in words[1:] if not word.startswith("-")]
+    return len(scripts) >= 2 and os.path.basename(scripts[0]) == "agent-sessions.mjs" and scripts[1] == "send"
+
+
+def bash_simple_commands(tools):
+    for command in bash_commands(tools):
+        yield from simple_commands(command)
+
+
+def has_commit(tools):
+    return any(is_git_commit(words) for words in bash_simple_commands(tools))
+
+
+def has_report(tools):
+    return any(tool.get("name") == "SendMessage" for tool in tools) or any(
+        is_report_send(words) for words in bash_simple_commands(tools)
+    )
+
+
+def with_final(texts, final):
+    if not isinstance(final, str) or not final.strip():
+        return texts
+    if texts and texts[-1].strip() == final.strip():
+        return texts
+    return [*texts, final]
 
 
 def main():
@@ -53,18 +231,35 @@ def main():
         return
     payload = json.load(sys.stdin)
     path = payload.get("transcript_path")
-    if not path or not os.path.isfile(path):
+    final = payload.get("last_assistant_message")
+    has_transcript = bool(path) and os.path.isfile(path)
+    if not has_transcript and not isinstance(final, str):
         return
     root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
     log = os.path.join(root, LOG_FILE)
     os.makedirs(os.path.dirname(log), exist_ok=True)
+    # Claude Code calls the Stop hook before the final text block reaches the transcript.
+    texts, tools = turn_entries(path) if has_transcript else ([], [])
+    texts = with_final(texts, final)
+    lines = sum(1 for text in texts for row in text.splitlines() if row.strip())
+    committed = has_commit(tools)
+    reported = has_report(tools)
+    unreported = committed and not reported
+    blocked = (lines > 1 or unreported) and not payload.get("stop_hook_active")
     record = {
         "timestamp": datetime.now(timezone.utc).isoformat(),
         "session_id": payload.get("session_id"),
-        "words": count_words(path),
+        "words": sum(len(text.split()) for text in texts),
+        "lines": lines,
+        "committed": committed,
+        "reported": reported,
+        "blocked": blocked,
     }
     with open(log, "a", encoding="utf-8") as handle:
         handle.write(json.dumps(record) + "\n")
+    if blocked:
+        reason = REPORT_REASON if unreported else BLOCK_REASON
+        print(json.dumps({"decision": "block", "reason": reason}))
 
 
 try:

package/content/hooks/git-safety.py

@@ -6,13 +6,12 @@ Denies, for a Bash call:
 - every `git stash` that writes (bare, `push`, `save`, `pop`, `apply`, `drop`, `clear`, `branch`,
   `create`, `store`); `git stash list` and `git stash show` stay allowed
 - `git commit --amend`
-- `git commit` without a ` -- <paths>` pathspec
-- any `git add` or `git commit` whose paths name an `.ethlete/**/go.json` (a go is granted
-  in Studio, never committed by an agent)
+- `git commit` without a ` -- <paths>` pathspec, except the commit that concludes a merge: while
+  `MERGE_HEAD` exists and every staged path changed between HEAD and MERGE_HEAD or is conflicted
 
 `git commit-tree` and `git update-index` stay allowed, so a merge commit built on a temporary
-GIT_INDEX_FILE works. Commit messages (`-m`, `--message`) and other quoted text are ignored for
-the command checks, so a message that mentions `git stash` does not trip the hook.
+GIT_INDEX_FILE works. Only real command positions count: commit messages (`-m`, `--message`), quoted text and heredoc
+bodies are ignored, so a grep pattern or message that mentions `git stash` does not trip the hook.
 
 Can be disabled per machine via a gitignored ethlete-agents.config.local.json at the repo
 root: {"disableHooks": true} or {"disableHooks": ["git-safety"]}.
@@ -23,6 +22,7 @@ Fail-safe: any error exits 0 with no output.
 import json
 import os
 import re
+import subprocess
 import sys
 
 HOOK_NAME = "git-safety"
@@ -31,10 +31,11 @@ LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
 MESSAGE_ARG = re.compile(
     r"""(?:^|(?<=\s))(?:-[a-zA-Z]*m|--message)(?:=|\s*)(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s;&|]*)"""
 )
-SEGMENT_SPLIT = re.compile(r"[;&|\n]+")
+SEGMENT_SPLIT = re.compile(r"[;&|\n()`]+")
+HEREDOC = re.compile(r"<<-?[ \t]*(['\"]?)(\w+)\1([^\n]*)\n(?:.*?\n)?[ \t]*\2[ \t]*(?=\n|$)", re.DOTALL)
+QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
 GLOBAL_OPTS_WITH_VALUE = ("-C", "-c", "--git-dir", "--work-tree", "--namespace")
 ADD_ALL = ("-A", "--all", ".")
-GO_JSON = re.compile(r"(?:^|/)go\.json$")
 
 def agent_name(argv):
     for index, arg in enumerate(argv):
@@ -76,8 +77,8 @@ def disabled_locally(config):
 
 def git_calls_in(command):
     """Yield (subcommand, args) for every command-position git call in the shell string."""
-    stripped = MESSAGE_ARG.sub(" ", command)
-    unquoted = stripped.replace('"', " ").replace("'", " ")
+    stripped = MESSAGE_ARG.sub(" ", HEREDOC.sub(r"<<\3", command))
+    unquoted = QUOTED.sub(lambda m: re.sub(r"[\s;&|(`]", "_", m.group(0)[1:-1]), stripped)
     for segment in SEGMENT_SPLIT.split(unquoted):
         words = segment.split()
         index = 0
@@ -85,11 +86,14 @@ def git_calls_in(command):
             index += 1
         if index < len(words) and (words[index] == "git" or words[index].endswith("/git")):
             rest = words[index + 1 :]
+            directory = None
             while rest and rest[0].startswith("-"):
+                if rest[0] == "-C" and len(rest) > 1:
+                    directory = rest[1]
                 skip = 2 if rest[0] in GLOBAL_OPTS_WITH_VALUE else 1
                 rest = rest[skip:]
             if rest:
-                yield rest[0], rest[1:]
+                yield rest[0], rest[1:], directory
 
 
 STASH_READS = ("list", "show")
@@ -100,9 +104,33 @@ def stash_subcommand_of(args):
     return args[0] if args and not args[0].startswith("-") else "push"
 
 
-def violation_in(command):
+def git_lines(cwd, *args):
+    result = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, timeout=10, check=True)
+    return {line for line in result.stdout.splitlines() if line}
+
+
+def concludes_merge(cwd):
+    """True while MERGE_HEAD exists and every staged path belongs to the merge. Any error is False."""
+    try:
+        merge_head = git_lines(cwd, "rev-parse", "--git-path", "MERGE_HEAD")
+        if not merge_head or not os.path.isfile(os.path.join(cwd, next(iter(merge_head)))):
+            return False
+        staged = git_lines(cwd, "diff", "--cached", "--name-only")
+        merge_paths = git_lines(cwd, "diff", "--name-only", "HEAD", "MERGE_HEAD") | git_lines(
+            cwd, "diff", "--name-only", "--diff-filter=U"
+        )
+        return staged <= merge_paths
+    except Exception:
+        return False
+
+
+def stages_everything(args):
+    return any(arg == "--all" or re.fullmatch(r"-[a-zA-Z]*a[a-zA-Z]*", arg) for arg in args if arg != "--")
+
+
+def violation_in(command, cwd=None):
     """(rule, allowed form) for the first forbidden git call, or None."""
-    for sub, args in git_calls_in(command):
+    for sub, args, directory in git_calls_in(command):
         if sub == "add":
             if any(arg in ADD_ALL for arg in args):
                 return (
@@ -120,16 +148,14 @@ def violation_in(command):
                     "`git commit --amend` rewrites a commit another session may have built on",
                     "make a new commit: `git commit -m \"...\" -- <paths>`",
                 )
-            if "--" not in args:
+            if "--" not in args and not (
+                not stages_everything(args)
+                and concludes_merge(os.path.join(cwd or os.getcwd(), directory) if directory else cwd or os.getcwd())
+            ):
                 return (
                     "`git commit` without a pathspec commits everything staged, including other sessions' work",
                     "name the paths: `git commit -m \"...\" -- <paths>`",
                 )
-        if sub in ("add", "commit") and any(GO_JSON.search(arg) for arg in args):
-            return (
-                "an agent never stages or commits a `go.json`; a go is granted in Studio",
-                "leave `go.json` out of the paths",
-            )
     return None
 
 
@@ -155,7 +181,8 @@ def main():
     if disabled_locally(load_local_config(repo_root(data))):
         return
 
-    found = violation_in(command)
+    cwd = data.get("cwd")
+    found = violation_in(command, cwd if isinstance(cwd, str) and cwd else None)
 
     if not found:
         return

package/content/mods/plugins/e2e-progress/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e2e-progress",
-  "version": "0.1.0-next.32",
+  "version": "0.1.0-next.33",
   "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane",
   "types": "./types/index.d.ts"
 }

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

@@ -20,7 +20,7 @@ script, so you do not need `<skill-dir>`. The older name `npx ethlete-agents mai
 ```bash
 node <skill-dir>/agent-sessions.mjs run <name> <command...> [--role builder] [--dry-run]
 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 restart <name> [--after <seconds>] [--notify <agent,...>] [--process] [--role builder|none] <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>...]
@@ -49,7 +49,9 @@ Nothing runs until you start it, so a person who does not use this does nothing.
 
 `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. After the clear, a new turn does not hold the prompt back: a message can wake the fresh session, and Claude Code queues input typed during a turn. Only typed text in its prompt holds the prompt back. After 60 seconds of typed text, it saves the prompt to `.ethlete/restart.prompt.<session>.txt` and logs why in `.ethlete/restart.log`. 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.
+`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. After the clear, a new turn does not hold the prompt back: a message can wake the fresh session, and Claude Code queues input typed during a turn. Only typed text in its prompt holds the prompt back. The prompt is the text between the two rules of the input box, so the background-agent panel below the footer does not count as typed text. When the focus sits in that panel, it presses Up until the prompt has the focus and clears the line with C-u before it types. After 2 minutes of typed text, and when it gives up, it sends one mailbox line to `<name>` and to each `--notify` agent. After 60 seconds of typed text, it saves the prompt to `.ethlete/restart.prompt.<session>.txt` and logs why in `.ethlete/restart.log`. 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 paired session (the builder session, started with `run --role builder`, and any session that is not one), and the error names the caller's own sender name. A restart of the paired session is logged to `restart.log` as `peer restart: <caller> restarted <target>`. Background commands of the old session still report into the new one. A pane counts as busy only when "esc to interrupt" or "Waiting for" shows in the spinner line right above the input box or in the footer below it (a turn that waits on background agents is busy). A chat line that starts with `●` or `⎿` never counts, so an agent that ends its turn with its own "Waiting for ..." text is idle. If the permission system denies your own `restart` (the command never runs), send one mailbox line to the grill/docs session, for example `send <you> --to <grill> 'restart denied, please /clear my pane and type: <prompt>'`. That session drives your pane: it types into it only when the pane is idle by the rule above.
+
+`restart --process` ends the agent process instead of clearing it: it types `/exit` (`/quit` for a `codex` name) and starts the agent command again in the same tmux pane, through a login shell, with the prompt as its first message. A `/clear` keeps the old process, so it never picks up a change to an installed plugin, a settings file, an MCP server or `PATH`; after such a change use `--process`. The agent command is the one `run` started, without its prompt, and the pane's start command for an older session. It starts with `command`, so the shell function of the same name does not start a new session. If the exit opens the background work dialog, the restart selects "exit and stop tasks" and writes the stopped jobs to `restart.log` and to a mailbox notice. The new process keeps the role: the session's own role, else `builder` from a prompt that resumes a `builder-*` handoff, else the one `--role` names. A builder process gets `ETHLETE_AGENT_ROLE=builder` and, for `claude`, the builder system prompt once. A session with no role next to another agent session in the repo, none of them a builder, is refused unless the prompt resumes a `builder-*` or `doc-agent-*` handoff or `--role` is passed (`--role none` restarts it without a role).
 
 `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.
 
@@ -78,6 +80,6 @@ If the prompt of the agent holds typed text, the dispatcher waits until that tex
 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.
 
-In this repo commit with `yarn commit -m "..." -- <paths>`: it runs the related specs first in a throwaway worktree of HEAD plus those paths, before it takes `.git/index.lock`, and the pre-commit hook then skips them for that exact tree (a plain `git commit` still runs them in the hook).
+In this repo commit with `yarn commit -m "..." -- <paths>`: it adds untracked paths and waits for `.git/index.lock`. Specs, lint and typecheck run in CI, not in the hook.
 
 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

@@ -36,8 +36,10 @@ 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 RESTART_WAIT_MS = Number(process.env.AGENT_RESTART_WAIT_MS ?? 30 * 60 * 1000);
+const RESTART_DRAFT_NOTICE_MS = Number(process.env.AGENT_RESTART_DRAFT_NOTICE_MS ?? 2 * 60 * 1000);
 const RESTART_CLEAR_WAIT_MS = Number(process.env.AGENT_RESTART_CLEAR_WAIT_MS ?? 60 * 1000);
+const RESTART_EXIT_WAIT_MS = Number(process.env.AGENT_RESTART_EXIT_WAIT_MS ?? 30 * 1000);
 const repoSlug = basename(root).replace(/[.:]/g, '-');
 const sessionFor = (agent) => `${agent}@${repoSlug}`;
 const DISPATCH_SESSION = process.env.AGENT_MAILBOX_DISPATCH_SESSION ?? `mailbox-dispatch@${repoSlug}`;
@@ -62,6 +64,8 @@ const afterSeconds = takeFlag(args, '--after', true);
 const now = takeFlag(args, '--now', false);
 const dryRun = takeFlag(args, '--dry-run', false);
 const role = takeFlag(args, '--role', true);
+const notify = takeFlag(args, '--notify', true);
+const newProcess = takeFlag(args, '--process', false);
 const [command, sender, ...words] = args;
 
 const help = `Shared agent mailbox: ${mailbox}
@@ -81,8 +85,12 @@ Run:     node ${script} run <name> <command...> [--role builder] [--dry-run]
 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>)
+Restart: node ${script} restart <name> [--after <seconds>] [--notify <agent,...>] [--process] [--role builder|none] <prompt...>
+                                                      (type the clear command and then the prompt into the tmux session of <name>;
+                                                       a long wait on a draft and a give-up go to <name> and each --notify agent;
+                                                       --process ends the agent and starts it again in the same pane with the prompt;
+                                                       it keeps the role, else takes it from a builder-* handoff name, and refuses
+                                                       a session with no role while another agent session runs in the repo)
 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>)
 
@@ -102,9 +110,75 @@ const BUILDER_PROMPT =
 const withRole = (words) =>
   role === 'builder' && basename(words[0]) === 'claude' ? [...words, '--append-system-prompt', BUILDER_PROMPT] : words;
 const sessionExists = (name) => tmux('has-session', '-t', `=${name}`).status === 0;
+const ROLE_OPTION = '@ethlete_role';
+const COMMAND_OPTION = '@ethlete_command';
+const agentCommandOf = (session) =>
+  tmux('show-options', '-v', '-t', `=${session}:`, COMMAND_OPTION).stdout.trim() ||
+  tmux('display-message', '-p', '-t', `=${session}:`, '#{pane_start_command}')
+    .stdout.trim()
+    .replace(/^"(.*)"$/, '$1');
+const roleOf = (session) => tmux('show-options', '-v', '-t', `=${session}:`, ROLE_OPTION).stdout.trim() || null;
+const arePaired = (a, b) => (roleOf(a) === 'builder') !== (roleOf(b) === 'builder');
 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));
+const TEXT_VALUE_FLAGS = new Set(['--append-system-prompt', '--system-prompt']);
+const withoutPrompt = (words) => {
+  const separator = words.indexOf('--');
+  if (separator > 0) return words.slice(0, separator);
+  const [previous, last] = words.slice(-2);
+  const isPrompt =
+    words.length > 1 &&
+    !last.startsWith('-') &&
+    (!previous.startsWith('-') || (/\s/.test(last) && !TEXT_VALUE_FLAGS.has(previous)));
+  return isPrompt ? words.slice(0, -1) : words;
+};
+const SHELL_WORD = /(?:'[^']*'|\\.|[^\s'\\])+/g;
+const ENV_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const unquoteWord = (word) => word.replace(/'([^']*)'|\\(.)/g, (_, quoted, escaped) => quoted ?? escaped);
+const commandWithoutPrompt = (command) => {
+  const tokens = [...command.matchAll(SHELL_WORD)];
+  const program = tokens.findIndex(([word]) => !ENV_WORD.test(word));
+  if (program < 0) return command;
+  const words = tokens.slice(program).map(([word]) => unquoteWord(word));
+  const kept = withoutPrompt(words).length;
+  return kept === words.length ? command : command.slice(0, tokens[program + kept].index).trimEnd();
+};
+const HANDOFF_ROLE = /^\/handoff\s+resume\s+(builder|doc-agent)-/;
+const handoffRoleOf = (prompt) => prompt.match(HANDOFF_ROLE)?.[1] ?? null;
+const restartRoleOf = (session, prompt) => {
+  if (role === 'none') return null;
+  const found = role ?? roleOf(session) ?? handoffRoleOf(prompt);
+  return found === 'doc-agent' ? null : found;
+};
+const hasUnknownRole = (session, prompt) => {
+  if (role !== undefined || roleOf(session) || handoffRoleOf(prompt)) return false;
+  const peers = tmux('list-sessions', '-F', '#{session_name}')
+    .stdout.split('\n')
+    .filter((name) => name.endsWith(`@${repoSlug}`) && name !== session && name !== DISPATCH_SESSION);
+  return peers.length > 0 && !peers.some((name) => roleOf(name) === 'builder');
+};
+const commandWithRole = (command, agentRole) => {
+  const tokens = [...command.matchAll(SHELL_WORD)].map(([word]) => word);
+  const program = tokens.findIndex((word) => !ENV_WORD.test(word));
+  const env = program < 0 ? tokens : tokens.slice(0, program);
+  const words = tokens.slice(env.length).map(unquoteWord);
+  const kept = words.filter(
+    (word, index) =>
+      !(word === '--append-system-prompt' && words[index + 1] === BUILDER_PROMPT) &&
+      !(word === BUILDER_PROMPT && words[index - 1] === '--append-system-prompt'),
+  );
+  const rule =
+    agentRole === 'builder' && basename(kept[0] ?? '') === 'claude' ? ['--append-system-prompt', BUILDER_PROMPT] : [];
+  return [
+    ...env.filter((word) => !word.startsWith('ETHLETE_AGENT_ROLE=')),
+    `ETHLETE_AGENT_ROLE=${agentRole}`,
+    ...[...kept, ...rule].map(quote),
+  ].join(' ');
+};
+const bypassingShellFunction = (base) => base.replace(/^((?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*)/, '$1command ');
+const EXIT_DIALOG_JOBS = /will stop when you exit/i;
+const EXIT_AND_STOP = /exit and stop/i;
 
 /**
  * Reads the last prompt line (`❯` for Claude Code, `›` for Codex) of the pane. Dim text is the empty
@@ -112,14 +186,31 @@ const runsInSession = (agentArgs) =>
  * wake-up line from answering a permission dialog.
  */
 const SGR = `${String.fromCharCode(27)}\\[([0-9;]*)m`;
-const busyLine = (session) =>
-  (tmux('capture-pane', '-p', '-t', `=${session}:`).stdout ?? '')
-    .split('\n')
-    .find((line) => /esc to inte/i.test(line)) ?? null;
+const BUSY_TEXT = /esc to interrupt|Waiting for/i;
+const isTranscript = (line) => /^\s*[●⎿]/.test(line);
+/**
+ * The line that shows a running turn: the spinner line right above the input box, or a footer line below it.
+ * A transcript line (`●`, `⎿`) never counts, since an agent can end its turn with its own "Waiting for ..." text.
+ */
+const busyLineOf = (lines) => {
+  const bottom = lastRuleIndex(lines);
+  const top = lines.slice(0, bottom).findLastIndex(isRule);
+  if (bottom === -1 || top === -1) return lines.find((line) => BUSY_TEXT.test(line) && !isTranscript(line)) ?? null;
+  const spinner = lines.slice(0, top).findLast((line) => line.trim() !== '') ?? '';
+  return [spinner, ...lines.slice(bottom + 1)].find((line) => BUSY_TEXT.test(line) && !isTranscript(line)) ?? null;
+};
+const busyLine = (session) => busyLineOf((tmux('capture-pane', '-p', '-t', `=${session}:`).stdout ?? '').split('\n'));
 const restartLog = (message) => {
   mkdirSync(dirname(mailbox), { recursive: true });
   appendFileSync(join(dirname(mailbox), 'restart.log'), `${new Date().toISOString()} ${message}\n`);
 };
+const restartNotice = (message) => {
+  restartLog(message);
+  [sender, ...(notify ?? '').split(',')]
+    .map((agent) => agent.trim())
+    .filter(Boolean)
+    .forEach((to) => append({ sender: 'restart', to, message }));
+};
 
 /**
  * Waits until the agent ended its turn and nobody types in its prompt, twice in a row; `false` after the time limit.
@@ -130,12 +221,19 @@ const waitForQuiet = (session, limitMs = RESTART_WAIT_MS, allowBusy = false) =>
   const end = Date.now() + limitMs;
   let quiet = 0;
   let reason = '';
+  let draftSince = null;
+  let told = false;
   while (Date.now() < end) {
     const busy = allowBusy ? null : busyLine(session);
     const draft = busy === null ? draftLine(session) : null;
     const next = busy !== null ? `busy: ${busy.trim()}` : draft !== null ? `draft: ${draft}` : '';
     if (next !== reason) restartLog(`${session} ${next ? `waits, ${next}` : 'is quiet'}`);
     reason = next;
+    draftSince = draft === null ? null : (draftSince ?? Date.now());
+    if (!told && draftSince !== null && Date.now() - draftSince >= RESTART_DRAFT_NOTICE_MS) {
+      told = true;
+      restartNotice(`restart of ${session} waits ${Math.round((Date.now() - draftSince) / 1000)}s, draft: ${draft}`);
+    }
     quiet = next ? 0 : quiet + 1;
     if (quiet === 2) return true;
     sleep(RESTART_POLL_MS);
@@ -145,15 +243,29 @@ const waitForQuiet = (session, limitMs = RESTART_WAIT_MS, allowBusy = false) =>
 
 /** The IDE context chip (`[⧉ In file.ts]`, `[⧉ 3 lines selected]`) shares the prompt line and survives `/clear`. */
 const IDE_CHIP = /\[⧉ [^\]]*\]/g;
-const draftLine = (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 null;
+const plain = (line) => line.replace(new RegExp(SGR, 'g'), '');
+const isRule = (line) => /^─{10,}$/.test(plain(line).trim());
+const isPromptMark = (line) => /^\s*[❯›]/.test(plain(line));
+/** A row of the background-agent panel below the footer (`❯ ⏺ main`, `  ◯ general-purpose …`). */
+const isPanelRow = (line) => /^\s*❯?\s*[⏺◯]/.test(plain(line));
+const paneLines = (session) => (tmux('capture-pane', '-p', '-e', '-t', `=${session}:`).stdout ?? '').split('\n');
+const lastRuleIndex = (lines) => lines.findLastIndex(isRule);
+/**
+ * The prompt is the text between the last two rules of the input box. A `❯` line below the last rule that is not a
+ * panel row is a menu (`❯ 1. Yes`) and wins, which keeps a wake-up line from answering a permission dialog.
+ */
+const promptLines = (lines) => {
+  const below = lastRuleIndex(lines);
+  const menu = lines.slice(below + 1).findLast((line) => isPromptMark(line) && !isPanelRow(line));
+  if (menu) return [menu];
+  const above = lines.slice(0, below).findLastIndex(isRule);
+  if (below !== -1 && above !== -1) return lines.slice(above + 1, below);
+  const prompt = lines.findLast((line) => isPromptMark(line) && !isPanelRow(line));
+  return prompt ? [prompt] : [];
+};
+const withoutDim = (line) => {
   let dim = false;
-  const visible = prompt
+  return line
     .split(new RegExp(`(${SGR.replace('(', '(?:')})`))
     .map((part) => {
       const codes = part.match(new RegExp(`^${SGR}$`))?.[1].split(';');
@@ -165,12 +277,35 @@ const draftLine = (session) => {
       return '';
     })
     .join('');
-  const text = visible
+};
+const draftLine = (session) => {
+  const text = promptLines(paneLines(session))
+    .map(withoutDim)
+    .join('\n')
     .replace(/^\s*[❯›]/, '')
     .replace(IDE_CHIP, '')
     .trim();
   return text.length > 0 ? text : null;
 };
+const panelFocused = (lines) => lines.slice(lastRuleIndex(lines) + 1).some((line) => /^\s*❯\s*[⏺◯]/.test(plain(line)));
+const PANEL_UP_LIMIT = 10;
+/**
+ * Keys typed while the focus sits in the background-agent panel go into the panel. Up moves the focus back to the
+ * prompt, and an Up too many recalls history, so C-u clears the line after. `false` if the focus did not leave.
+ */
+const leavePanel = (session) => {
+  if (!panelFocused(paneLines(session))) return true;
+  for (let press = 0; press < PANEL_UP_LIMIT; press++) {
+    tmux('send-keys', '-t', `=${session}:`, 'Up');
+    sleep(ENTER_DELAY_MS);
+    if (!panelFocused(paneLines(session))) {
+      tmux('send-keys', '-t', `=${session}:`, 'C-u');
+      sleep(ENTER_DELAY_MS);
+      return true;
+    }
+  }
+  return false;
+};
 const hasDraft = (session) => draftLine(session) !== null;
 const isAttached = (name) => tmux('list-clients', '-t', `=${name}`).stdout.trim() !== '';
 const freeSessionFor = (agent) => {
@@ -295,14 +430,38 @@ if (command === 'send' && sender) {
   if (!sessionExists(DISPATCH_SESSION))
     startSession(DISPATCH_SESSION, `${withEnv}node ${quote(script)} dispatch`, true);
   const session = freeSessionFor(sender);
-  const shellCommand = `${role ? `ETHLETE_AGENT_ROLE=${role} ` : ''}${withRole(words).map(quote).join(' ')}`;
+  const roleEnv = role ? `ETHLETE_AGENT_ROLE=${role} ` : '';
+  const shellCommand = `${roleEnv}${withRole(words).map(quote).join(' ')}`;
+  const baseCommand = `${roleEnv}${withRole(withoutPrompt(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;
+    if (!sessionExists(session)) {
+      tmux('new-session', '-d', '-s', session, '-c', process.cwd(), shellCommand);
+      tmux('set-option', '-t', `=${session}:`, COMMAND_OPTION, baseCommand);
+      if (role) tmux('set-option', '-t', `=${session}:`, ROLE_OPTION, role);
+    }
+    const callerSession = tmux(
+      'display-message',
+      '-p',
+      '-t',
+      process.env.TMUX_PANE ?? '',
+      '#{session_id}',
+    ).stdout.trim();
+    const [callerClient] = callerSession
+      ? tmux('list-clients', '-t', callerSession, '-F', '#{client_tty}').stdout.split('\n').filter(Boolean)
+      : [];
+    process.exitCode = callerClient
+      ? (spawnSync('tmux', ['switch-client', '-c', callerClient, '-t', `=${session}`], { stdio: 'inherit' }).status ??
+        1)
+      : 0;
   } else {
-    process.exitCode =
-      spawnSync('tmux', ['new-session', '-A', '-s', session, '-c', process.cwd(), shellCommand], { stdio: 'inherit' })
-        .status ?? 1;
+    const created = sessionExists(session)
+      ? []
+      : ['new-session', '-d', '-s', session, '-c', process.cwd(), shellCommand];
+    if (created.length && tmux(...created).status === 0) {
+      tmux('set-option', '-t', `=${session}:`, COMMAND_OPTION, baseCommand);
+      if (role) tmux('set-option', '-t', `=${session}:`, ROLE_OPTION, role);
+    }
+    process.exitCode = spawnSync('tmux', ['attach-session', '-t', `=${session}`], { stdio: 'inherit' }).status ?? 1;
   }
 } else if (command === 'shell-init' || command === 'shell-install') {
   const agents = [sender, ...words].filter(Boolean);
@@ -360,30 +519,96 @@ if (command === 'send' && sender) {
   if (!session) {
     process.stderr.write(`No tmux session for ${sender}.\n`);
     process.exitCode = 1;
-  } else if (own && own !== session) {
+  } else if (own && own !== session && !arePaired(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 (role !== undefined && role !== 'builder' && role !== 'none') {
+    process.stderr.write(`Unknown role ${role}. Pass --role builder or --role none.\n`);
+    process.exitCode = 1;
+  } else if (newProcess && hasUnknownRole(session, words.join(' '))) {
+    process.stderr.write(
+      `Refused: ${session} has no role and another agent session runs in this repo, so the new process could lose the builder rule. Resume a builder-* or doc-agent-* handoff, or pass --role builder or --role none.\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)) {
+      restartNotice(`restart of ${session} gave up after ${RESTART_WAIT_MS / 1000}s, reason in restart.log`);
       process.exitCode = 1;
+    } else if (!leavePanel(session)) {
+      restartNotice(
+        `restart of ${session} gave up, the focus did not leave the agent panel after ${PANEL_UP_LIMIT} Up`,
+      );
+      process.exitCode = 1;
+    } else if (newProcess) {
+      const pane = `=${session}:`;
+      const restartRole = restartRoleOf(session, words.join(' '));
+      const stored = commandWithoutPrompt(agentCommandOf(session));
+      const base = restartRole ? commandWithRole(stored, restartRole) : stored;
+      if (restartRole) tmux('set-option', '-t', pane, ROLE_OPTION, restartRole);
+      tmux('set-option', '-p', '-t', pane, 'remain-on-exit', 'on');
+      type('-l', sender.startsWith('codex') ? '/quit' : '/exit');
+      sleep(ENTER_DELAY_MS);
+      type('Enter');
+      const end = Date.now() + RESTART_EXIT_WAIT_MS;
+      const dead = () => tmux('display-message', '-p', '-t', pane, '#{pane_dead}').stdout.trim() === '1';
+      const answerExitDialog = () => {
+        const lines = (tmux('capture-pane', '-p', '-t', pane).stdout ?? '').split('\n');
+        const start = lines.findIndex((line) => EXIT_DIALOG_JOBS.test(line));
+        const stop = lines.findIndex((line, index) => index > start && EXIT_AND_STOP.test(line));
+        if (start < 0 || stop < 0) return false;
+        const selected = lines.findIndex((line, index) => index > start && line.trim().startsWith('❯'));
+        const jobs = lines
+          .slice(start + 1, stop)
+          .map((line) => line.trim())
+          .filter(Boolean);
+        restartNotice(
+          `restart of ${session} stopped its background work, start it again: ${jobs.join('; ') || '(none listed)'}`,
+        );
+        const between = (from, to) => lines.slice(from, to).filter((line) => line.trim()).length;
+        const [key, steps] = selected > stop ? ['Up', between(stop, selected)] : ['Down', between(selected, stop)];
+        for (let step = 0; selected >= 0 && step < steps; step++) type(key);
+        type('Enter');
+        return true;
+      };
+      let answered = false;
+      while (!dead() && Date.now() < end) {
+        if (!answered) answered = answerExitDialog();
+        sleep(RESTART_POLL_MS / 4);
+      }
+      if (!dead()) restartLog(`${session} did not exit ${RESTART_EXIT_WAIT_MS / 1000}s after the exit command, killed`);
+      const shell = process.env.SHELL || 'sh';
+      tmux(
+        'respawn-pane',
+        '-k',
+        '-t',
+        pane,
+        '-c',
+        root,
+        shell,
+        '-lic',
+        `${bypassingShellFunction(base)} ${quote(words.join(' '))}`,
+      );
+      tmux('set-option', '-p', '-t', pane, 'remain-on-exit', 'off');
+      tmux('set-option', '-t', pane, COMMAND_OPTION, base);
+      restartLog(`${session} started a new process: ${base}`);
     } else {
       type('-l', sender.startsWith('codex') ? '/new' : '/clear');
       sleep(ENTER_DELAY_MS);
       type('Enter');
       sleep(RESTART_CLEAR_MS);
-      if (waitForQuiet(session, RESTART_CLEAR_WAIT_MS, true)) {
+      if (waitForQuiet(session, RESTART_CLEAR_WAIT_MS, true) && leavePanel(session)) {
         type('-l', words.join(' '));
         sleep(ENTER_DELAY_MS);
         type('Enter');
       } else {
         const saved = join(dirname(mailbox), `restart.prompt.${session}.txt`);
         writeFileSync(saved, `${words.join(' ')}\n`);
-        restartLog(
-          `${session} prompt not empty ${RESTART_CLEAR_WAIT_MS / 1000}s after the clear, prompt not typed, saved to ${saved}`,
+        restartNotice(
+          `restart of ${session} gave up: prompt not empty ${RESTART_CLEAR_WAIT_MS / 1000}s after the clear, prompt not typed, saved to ${saved}`,
         );
         tmux(
           'display-message',
@@ -395,13 +620,20 @@ if (command === 'send' && sender) {
       }
     }
   } else {
+    if (own && own !== session) restartLog(`peer restart: ${own} restarted ${session}`);
     const delay = Number(afterSeconds ?? RESTART_AFTER_SECONDS);
-    spawn(process.execPath, [script, 'restart', sender, '--now', '--after', String(delay), ...words], {
-      detached: true,
-      stdio: 'ignore',
-    }).unref();
+    const forward = notify ? ['--notify', notify] : [];
+    const mode = [...(newProcess ? ['--process'] : []), ...(role ? ['--role', role] : [])];
+    spawn(
+      process.execPath,
+      [script, 'restart', sender, '--now', '--after', String(delay), ...forward, ...mode, ...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`,
+      `${newProcess ? 'Starting a new process in' : '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') {
@@ -427,6 +659,7 @@ if (command === 'send' && sender) {
       return;
     }
     waiting.delete(agent);
+    if (!leavePanel(session)) return process.stderr.write(`The focus of ${session} stays in the agent panel.\n`);
     spawnSync('tmux', ['send-keys', '-t', `=${session}:`, '-l', text]);
     sleep(ENTER_DELAY_MS);
     spawnSync('tmux', ['send-keys', '-t', `=${session}:`, 'Enter']);

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

@@ -92,8 +92,8 @@ product. They take no picks and no new variants.
 - Mark a sketch `ready` only when no change to it waits on anything; otherwise `sketch hold`.
 - Every write command takes `--by <model id>`. **Never guess your id**: use the one your prompt names, or ask
   the coordinator or the user before you write.
-- Run `et design accept` only after the user approved a direct edit. Remove a part only with
-  `et design part remove`, never `git rm`.
+- A direct edit of a merged part is never accepted by hand: `design check` opens an old/new edit sketch and the
+  user picks in Studio. Remove a part only with `et design part remove`, never `git rm`.
 - Studio takes no new calls: never run `et design new`. New work goes to a product.
 - Share code between variants in the sketch's `shared/` folder only; no shared parameter or branch for one
   variant. An asset is one file in `<product>/assets/`, never inlined.

package/content/skills/design-exploration/reference-products-and-sketches.md

@@ -51,6 +51,19 @@ et design sketch reject <layer>/<name> --variant b [--reason <text>] --by <model
 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
 ```
 
+When the app shows UI the design does not draw, open the sketch at once with the built look as variant a, and
+name the compare DIFFs it explains:
+
+```bash
+et design sketch covers <layer>/<name> <state> <state>@<x>,<y>,<w>,<h>… --by <model id>   # no state clears them
+```
+
+While the sketch is open, `compare` lists each covered DIFF with the sketch name and passes it. A bare state
+covers its whole DIFF; `@x,y,w,h` covers only differing pixels inside that box of the state's picture (the
+diff PNG compare writes), and never a size change. A sketch with several targets needs the part in front,
+`<layer>/<name>:<state>[@x,y,w,h]`, and refuses a bare state (exit 2); a one-target sketch takes both forms. Any other DIFF on the part still fails. After the pick the
+cover ends, and the part must compare green again.
+
 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.
@@ -161,8 +174,7 @@ several variants at once; with `--round` they all start the new round. A new rou
 variant and mark the sketch `ready` again. `sketch new --round <title> --note <text>` names
 round 1 and sets its note; `--round` without `--note` fails. `sketch ready` refuses while the running round has no note; set it with `sketch round`.
 `sketch ready` also shoots every state of every variant and of the product's part: when not one pixel differs
-in any of them, it merges the sketch itself and logs it as an `auto` entry in the product's `accepted.json`
-("No visible change in any state: merged automatically."). Any difference or failed shot leaves it `ready`.
+in any of them, it merges the sketch itself. Any difference or failed shot leaves it `ready`.
 A problem the product already had before the merge does not block it (the check prints it as a note); only a problem the merge adds does.
 Run `sketch ready` again on a `ready` sketch to repeat the check and the auto merge.
 
@@ -194,6 +206,6 @@ in the product since the sketch was created, the merge refuses: bring each varia
 current shape. The user's reason is optional: with one, the merge sets the note from it; without
 one, the part keeps the `note` the picked variant file holds, so write that note while you draw.
 
-After the user approves a direct edit of a merged part (no sketch), run `et design accept <layer>/<name> --product <p> --by <model id> --note <why>` so `design check` stops warning `changed outside a sketch`. Never accept an edit the user did not approve.
+A part is build-ready when `design check` writes a current check record with no blockers (`ready.json`, tool-written, committed); Studio shows "Baubereit", "Nicht baubereit (n)" or "Wird geprüft". A direct edit of a merged part outside a sketch opens an old/new edit sketch that the user picks in Studio; there is no go and no accept command. `design check` warns `LEFTOVER-FILE` for a leftover gate file of the old go and accept flow and names the file to delete.
 
 To drop a merged part the user no longer wants (folded back into its host, say), run `et design part remove <layer>/<name> --product <p> --by <model id>`: it deletes the folder, its `merged.json` entry and its tsconfig path, and resolves its comments. It refuses while another part imports it or an open sketch targets it. Never `git rm` a part by hand.

package/content/skills/handoff/SKILL.md

@@ -196,6 +196,10 @@ before. Then run, with the slug of the file you saved:
 node <sessions-skill-dir>/agent-sessions.mjs restart <name> '<resume command> <slug> [<text after the slug>]'
 ```
 
+Add `--process` after `restart` when the session changed a plugin, a settings file, an MCP server or `PATH`.
+A plain restart keeps the old process, so the change reaches only a new one.
+Before `--process`, write the command line of each background job of the session into the handoff file. The exit stops these jobs, so the new process starts them again.
+
 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.
@@ -227,8 +231,11 @@ first line of the handoff file: `Restarted because: <one line>`. End the turn wi
    the constraints and the dead ends, so do not re-read the plan files it summarises, and do
    not survey the directory. Open a source file when you are going to edit it, and load a
    focused guidance file only when the work needs one.
-5. Continue with the **Next steps** section. Don't redo work listed under
+5. If the handoff name starts with a role prefix (`builder-`, `doc-agent-`) and a skill
+   of that name exists (`builder-agent`, `doc-agent`), load that skill now. Do it yourself;
+   do not wait for a line in the handoff that asks for it.
+6. Continue with the **Next steps** section. Don't redo work listed under
    _Done_; don't re-open questions under _Decisions_.
-6. When every next step is complete, decide whether the handoff can be removed. Delete it
+7. When every next step is complete, decide whether the handoff can be removed. Delete it
    only if this workflow created it and the save workflow or user authorized cleanup.
    Otherwise report that it is no longer needed and let the user decide.

package/package.json

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