@vibelord/lanes 1.0.0 → 1.0.1

package/payload/lanes/libexec/agent_state.py

@@ -0,0 +1,214 @@
+"""Agent-aware lane state from signals the harnesses already emit. Pure functions, no subprocesses.
+
+Measured 2026-10-03 on coder-dev-work: Claude Code writes ~/.claude/sessions/<pid>.json with
+status busy|idle|shell|waiting, waitingFor, name, sessionId and tmux "<session>:@<win>.%<pane>" (21/21
+live lanes matched); it never deletes them (669 files, 21 live), so liveness is /proc/<pid>. Codex sets the
+pane title "[ ! ] Action Required | <task> | <dir>" and rings BEL when it needs an approval, prefixes a
+braille spinner while working, and rings BEL on turn completion. Claude's title "✳ <name>" is static.
+
+The agent{} status vocabulary is fixed here and reused by statusd, the sidebar, the hook sidecar and the phone:
+working | needs_input | needs_approval | done | errored | shell | idle. It is a NEW key beside status.json's
+six-word `state`, never a replacement for it.
+
+Two stale-signal traps, both MEASURED 2026-10-04 on this host: (1) a Claude session file outlives its pid, and pids
+wrap (pid_max 4194304, live pids already ~2.3M), so a recycled pid would resurrect a dead session — every file
+carries `procStart` as a JSON STRING (669/669 files), equal to field 22 (starttime) of /proc/<pid>/stat, and a
+mismatch means the pid is someone else's; (2) tmux keeps a pane's title after Codex exits, so a bare shell can still
+read `<task> | <dir>` — spec §3 calls that state `shell` ("a harness that ended into a shell"), never idle/done.
+
+pane_current_command alone cannot tell (2) apart from a live harness: tmux reports the foreground process-group
+LEADER, and lanes launch harnesses non-interactively (`bash -c '<harness> …; exec bash -l'`) or through a wrapper
+script (`bash eval-claude`), where the harness shares its shell's pgid — MEASURED 2026-10-04: 21/21 live Claude
+panes and a live Codex pane report `bash` with a live harness child; Codex panes report `node` only where node IS
+the pane root. The stale panes are the ones whose shell has no child at all, so the liveness signal is
+`pane_has_child` (does pane_pid have any child process in the container's /proc). statusd computes it with
+child_liveness(): a per-pane read of /proc/<pid>/task/*/children (this kernel exposes it, CONFIG_PROC_CHILDREN —
+MEASURED 2026-10-04 on 6.8.0-106-generic), falling back to one child_parents() /proc walk only when that read
+fails; a pid whose liveness could not be determined gets no `pane_has_child` key (unknown never demotes).
+pane_current_command stays a secondary hint (a non-shell pane root such as node is the harness itself, child or not).
+"""
+import json
+import os
+from pathlib import Path
+
+SPINNER = set('⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠁⠂⠄⡀⢀⠠⠐⠈')
+ACTION = '[ ! ] Action Required'
+SHELL_TITLES = {'', 'work', 'bash', 'sh', 'zsh', 'fish'}
+STATUS_FROM_CLAUDE = {'busy': 'working', 'idle': 'needs_input', 'shell': 'shell', 'waiting': 'needs_input'}
+STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')
+SHELL_COMMANDS = {'bash', 'sh', 'dash', 'zsh', 'fish', 'ksh', 'tcsh', 'csh'}
+
+
+def pane_has_child(proc_root, pid):
+    """Does `pid` have any child process? Reads every /proc/<pid>/task/<tid>/children (a child is listed under
+    the thread that forked it, so all threads are read): any non-empty -> True, all empty -> False. Any read
+    failure — pid gone, no task dir, a thread exiting mid-read, or a kernel without CONFIG_PROC_CHILDREN — is
+    None (unknown), never False. Same race caveat as child_parents(): the kernel guarantees the file only for a
+    stopped task, so a child forked or reaped during the read may be missed; one tick later it is seen."""
+    task = Path(proc_root, str(pid), 'task')
+    try:
+        tids = os.listdir(task)
+    except OSError:
+        return None
+    if not tids:
+        return None
+    for tid in tids:
+        try:
+            if Path(task, tid, 'children').read_text().split():
+                return True
+        except OSError:
+            return None
+    return False
+
+
+def child_parents(proc_root):
+    """The set of pids that have at least one child process in `proc_root` (field 4, ppid, of every
+    /proc/<pid>/stat, parsed after the last ')' since comm may contain spaces and ')'), or None when nothing could
+    be read — `proc_root` unlistable, or zero stat files parsed — so "could not look" is never "no children".
+    O(processes) (MEASURED 2026-10-04: ~140-170 ms over ~3.2k host processes), so it is only child_liveness()'s
+    fallback when the per-pane children read fails. A pid that exited mid-walk is skipped."""
+    parents = set()
+    parsed = 0
+    try:
+        names = os.listdir(proc_root)
+    except OSError:
+        return None
+    for name in names:
+        if not name.isdigit():
+            continue
+        try:
+            parents.add(int(Path(proc_root, name, 'stat').read_text().rsplit(')', 1)[1].split()[1]))
+        except (OSError, IndexError, ValueError):
+            continue
+        parsed += 1
+    return parents if parsed else None
+
+
+def child_liveness(proc_root, pids):
+    """pid -> True | False | None for each pane pid, as statusd's `pane_has_child`. pane_has_child() per pid
+    first (O(threads of that pid)); for a pid it cannot answer, one lazily computed child_parents() walk per call;
+    None when both fail. statusd sets the row key only for a non-None value, so unknown never demotes."""
+    out = {}
+    parents = walked = None
+    for pid in pids:
+        pid = int(pid)
+        has = pane_has_child(proc_root, pid)
+        if has is None:
+            if not walked:
+                parents, walked = child_parents(proc_root), True
+            has = None if parents is None else pid in parents
+        out[pid] = has
+    return out
+
+
+def _harness_ended(pane_row):
+    """True only when the row says the pane's root process has NO child (`pane_has_child is False`) and the
+    foreground is a bare shell: the harness exited into that shell, whatever title it left behind. A live
+    wrapper-launched harness is a child of the shell (has_child True); a node pane root is the harness itself (not
+    a shell). An absent or None `pane_has_child` is unknown and never demotes — the title then decides, since the
+    shell-foreground hint alone misreads every `bash -c` / wrapper launch as ended."""
+    return pane_row.get('pane_has_child') is False and _shell_foreground(pane_row)
+
+
+def _shell_foreground(pane_row):
+    """True when tmux reports a bare shell as the pane's foreground command (login '-bash' and paths normalised).
+    An absent/empty column is unknown, never a shell: the title alone then decides, as before."""
+    cmd = str(pane_row.get('pane_current_command') or '').strip().lstrip('-').rsplit('/', 1)[-1]
+    return cmd in SHELL_COMMANDS
+
+
+def _same_process(proc_root, pid, proc_start):
+    """The session file's `procStart` must equal the live pid's starttime (field 22 of /proc/<pid>/stat), else
+    the pid was recycled by an unrelated process. Claude writes procStart as a JSON string; str() normalises the
+    string and int forms alike. Unreadable stat -> treated as dead."""
+    try:
+        stat = Path(proc_root, pid, 'stat').read_text()
+        return stat.rsplit(')', 1)[1].split()[19] == str(proc_start)
+    except (OSError, IndexError):
+        return False
+
+
+def parse_codex_title(title):
+    """A Codex pane title -> {'harness','status','name'}, or None for a shell / non-agent title."""
+    t = (title or '').strip()
+    head = t.split('|')[0]
+    if t in SHELL_TITLES or (': ' in head and head.startswith(('coder@', 'root@'))):
+        return None
+    if t.startswith(ACTION):
+        rest = [p.strip() for p in t[len(ACTION):].split('|') if p.strip()]
+        return {'harness': 'codex', 'status': 'needs_approval', 'name': rest[0] if rest else ''}
+    if t and t[0] in SPINNER:
+        return {'harness': 'codex', 'status': 'working', 'name': t[1:].split('|')[0].strip()}
+    if t.startswith('✳'):
+        return None   # Claude's static title: presence only; the session file carries the state
+    if '|' in t or len(t.split()) >= 2:
+        return {'harness': 'codex', 'status': 'idle', 'name': head.strip()}
+    return None
+
+
+def claude_sessions(sessions_dir, proc_root):
+    """pane key -> agent dict, live pids only. Several files can name one pane (a resumed session leaves the
+    old pid's file behind): the newest `statusUpdatedAt` among LIVE pids wins. A file whose `procStart` does not
+    match the pid's current starttime is a recycled pid and is skipped (no `procStart` -> existence only). `proc_root` is the container's
+    /proc as seen from the host (/proc/<container-pid>/root/proc), so liveness is checked in the container's pid
+    namespace. A malformed file is skipped, never raised: one bad file costs nobody else their agent."""
+    out = {}
+    try:
+        names = os.listdir(sessions_dir)
+    except OSError:
+        return out
+    for fn in names:
+        stem = fn[:-5] if fn.endswith('.json') else ''
+        if not stem.isdigit() or not os.path.exists(os.path.join(proc_root, stem)):
+            continue
+        try:
+            d = json.loads(Path(sessions_dir, fn).read_text())
+        except (OSError, ValueError):
+            continue
+        if not isinstance(d, dict):
+            continue
+        if d.get('procStart') is not None and not _same_process(proc_root, stem, d['procStart']):
+            continue
+        key = d.get('tmux')
+        if not isinstance(key, str) or not key:
+            continue
+        try:
+            since = int((d.get('statusUpdatedAt') or 0) // 1000)
+        except (TypeError, ValueError):
+            continue
+        status = STATUS_FROM_CLAUDE.get(d.get('status'), 'idle')
+        if d.get('status') == 'waiting' and 'permission' in str(d.get('waitingFor') or '').lower():
+            status = 'needs_approval'
+        entry = {'harness': 'claude', 'status': status, 'name': str(d.get('name') or ''),
+                 'session_id': str(d.get('sessionId') or ''), 'pid': int(stem),
+                 'since': since, 'source': 'claude-session-file'}
+        if key not in out or entry['since'] >= out[key]['since']:
+            out[key] = entry
+    return out
+
+
+def merge(pane_row, claude_by_pane, sidecar):
+    """Precedence: hook sidecar (event-driven, both harnesses) > Claude session file > Codex title > bell.
+    Any Codex title — idle, spinner or Action Required, bell or not — over a bare-shell pane whose shell has no
+    child process (`pane_has_child is False`, statusd's row key) publishes `shell`: the harness ended and tmux kept
+    its last title, so no ghost idle/done/working/needs_approval. Unknown liveness leaves the title in charge.
+    Returns None when nothing says an agent is here — the sidebar then draws a plain shell."""
+    if sidecar and sidecar.get('status') in STATUSES:
+        return dict(sidecar, source=sidecar.get('source') or 'hook')
+    key = f"{pane_row.get('session_name')}:{pane_row.get('window_id')}.{pane_row.get('pane_id')}"
+    if key in claude_by_pane:
+        return dict(claude_by_pane[key])
+    title = parse_codex_title(pane_row.get('pane_title'))
+    bell = pane_row.get('window_bell_flag') == '1'
+    if title:
+        if _harness_ended(pane_row):
+            title['status'] = 'shell'   # stale title on a childless shell: the harness ended, no ghost of any kind
+        elif title['status'] == 'idle' and bell:
+            title['status'] = 'done'
+        title['source'] = 'title'
+        try:
+            title['since'] = int(pane_row.get('window_activity') or 0)
+        except ValueError:
+            title['since'] = 0
+        return title
+    return None

package/payload/lanes/libexec/connection.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""A quiet connection screen with input custody until the viewer answers."""
+import argparse
+import errno
+import fcntl
+import os
+import pty
+import select
+import signal
+import sys
+import termios
+import time
+import tty
+
+RESET = b'\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l\x1b[?1016l\x1b[?2004l\x1b[<u\x1b[0m'
+
+
+def screen(title, frame):
+    title = ''.join(c for c in title if c.isprintable())[:100]
+    spinner = '|/-\\'[frame % 4]
+    os.write(1, b'\x1b[H\x1b[2J\x1b[?25l' + f'\n  {spinner} Syncing {title}…\n\n  Connecting to the workspace\n'.encode())
+
+
+def drain():
+    termios.tcflush(0, termios.TCIFLUSH)
+
+
+def wait_screen(title, seconds, preserve_screen=False):
+    saved = termios.tcgetattr(0)
+    handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGTERM, signal.SIGHUP)}
+    def stop(sig, _frame):
+        raise SystemExit(128 + sig)
+    for sig in handlers:
+        signal.signal(sig, stop)
+    try:
+        tty.setraw(0)
+        os.write(1, RESET)
+        drain()
+        end, frame = time.monotonic() + seconds, 0
+        while time.monotonic() < end:
+            if not preserve_screen:
+                screen(title, frame)
+            frame += 1
+            if select.select([0], [], [], min(.15, max(0, end - time.monotonic())))[0]:
+                if not os.read(0, 4096):
+                    break  # disconnected terminal
+    finally:
+        for sig, handler in handlers.items():
+            signal.signal(sig, handler)
+        drain()
+        termios.tcsetattr(0, termios.TCSANOW, saved)
+        os.write(1, RESET + b'\x1b[?25h')
+
+
+def connect(title, command):
+    if not os.isatty(0):
+        raise SystemExit('The workspace viewer needs a terminal')
+    saved = termios.tcgetattr(0)
+    error_fd = os.dup(2)
+    child = None
+    stopping = False
+    master = None
+
+    def stop(_sig, _frame):
+        nonlocal stopping
+        stopping = True
+        if child:
+            try:
+                os.killpg(child, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+
+    def resize(_sig=None, _frame=None):
+        if master is not None:
+            size = fcntl.ioctl(0, termios.TIOCGWINSZ, b'\0' * 8)
+            fcntl.ioctl(master, termios.TIOCSWINSZ, size)
+
+    old_handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGTERM, signal.SIGHUP, signal.SIGWINCH)}
+    try:
+        tty.setraw(0)
+        drain()
+        os.write(1, RESET)
+        screen(title, 0)
+        child, master = pty.fork()
+        if child == 0:
+            os.dup2(error_fd, 2)  # diagnostics belong in the view's error file
+            os.close(error_fd)
+            try:
+                os.execvp(command[0], command)
+            except OSError as error:
+                print(error, file=sys.stderr)
+                os._exit(127)
+        os.close(error_fd)
+        error_fd = -1
+        resize()
+        signal.signal(signal.SIGTERM, stop)
+        signal.signal(signal.SIGHUP, stop)
+        signal.signal(signal.SIGWINCH, resize)
+        connected, frame = False, 0
+        while not stopping:
+            ready, _, _ = select.select([0, master], [], [], .15)
+            # Consume old mouse/keyboard input BEFORE accepting the first output.
+            if 0 in ready:
+                data = os.read(0, 4096)
+                if not data:
+                    stop(None, None)
+                    break
+                if connected:
+                    os.write(master, data)
+            if master in ready:
+                try:
+                    data = os.read(master, 65536)
+                except OSError as error:
+                    if error.errno != errno.EIO:
+                        raise
+                    break
+                if not data:
+                    break
+                if not connected:
+                    drain()
+                    os.write(1, RESET + b'\x1b[?25h\x1b[H\x1b[2J')
+                    connected = True
+                os.write(1, data)
+            if not connected:
+                frame += 1
+                screen(title, frame)
+        if stopping:
+            # This kills only the attach client group, never the persistent lane.
+            deadline = time.monotonic() + 2
+            while time.monotonic() < deadline:
+                pid, status = os.waitpid(child, os.WNOHANG)
+                if pid:
+                    return -signal.SIGTERM
+                time.sleep(.05)
+            try:
+                os.killpg(child, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+        _, status = os.waitpid(child, 0)
+        return -signal.SIGTERM if stopping else os.waitstatus_to_exitcode(status)
+    finally:
+        for sig, handler in old_handlers.items():
+            signal.signal(sig, handler)
+        if master is not None:
+            os.close(master)
+        if error_fd >= 0:
+            os.close(error_fd)
+        drain()
+        termios.tcsetattr(0, termios.TCSANOW, saved)
+        os.write(1, RESET + b'\x1b[?25h')
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--title', default='workspace')
+    parser.add_argument('--wait', type=float)
+    parser.add_argument('--preserve-screen', action='store_true')
+    parser.add_argument('--retry', action='store_true')
+    parser.add_argument('command', nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+    command = args.command[1:] if args.command[:1] == ['--'] else args.command
+    if args.wait is not None:
+        wait_screen(args.title, args.wait, args.preserve_screen)
+        return 0
+    if not command:
+        parser.error('viewer command required')
+    delay = 1
+    while True:
+        started = time.monotonic()
+        code = connect(args.title, command)
+        if not args.retry or code < 0:
+            return max(0, code) if code < 0 else code
+        delay = 1 if time.monotonic() - started >= 30 else min(delay * 2, 15)
+        wait_screen(args.title, delay)
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/payload/lanes/libexec/cursor_sync.py

@@ -12,12 +12,22 @@ The repository's `.vscode/terminals.json` stays the source of truth for WHICH la
 
 Text is edited minimally (command strings replaced in place, the `lanes` block inserted before the final brace) so
 git diffs stay small. Dry-run by default: prints a unified diff. `--write` applies (with a timestamped backup).
+
+`--canonicalize` additionally replaces every tmux lane's `create` that cannot create the lane — null, attach-only
+(`attach-session` without `new`), or naming a script that is missing in the container — with
+`lanes_lib.canonical_recipe()` (the recorded binding + the repository folder + `bash -l`), which is also what gives a
+NEW lane its identity (LANE_ID, LANE_WS, the lanes/<ws>/<id> trace). `--identity` additionally gives a WORKING
+recipe of the plain shape `[exec] tmux -L <socket> new -ADs <session> [-c <dir>] <command…>` the same identity
+(`plain_tmux_new`: the command argv is kept, only the `-e` flags are added); any other working recipe is left
+alone and its lane carries no identity. The old value is kept as `createPrevious` in both cases. Identity reaches a
+tmux lane ONLY through these `-e` flags: `lane open` never exports it (DEF-1422, lanes/docs/ARCHITECTURE.md).
 Boards whose registry lives outside a repository are additionally PROJECTED into the file Cursor
 reads for that folder, named by `"cursor": "<path>"` on the repository entry of the workspace manifest.
 """
 import difflib
 import json
 import re
+import shlex
 import time
 from pathlib import Path
 
@@ -31,8 +41,103 @@ def _indent_of(text):
     return match.group(1) if match else '  '
 
 
-def normalized_text(text, lanes_by_name):
-    """Return the file text with uniform commands + the `lanes` block. Minimal textual edits when possible."""
+ATTACH_VERBS = {'attach-session'[:n] for n in range(1, 15)}             # tmux takes any unique prefix + `attach`
+NEW_VERBS = {'new-session'[:n] for n in range(3, 12)}
+TMUX_OPTION_ARGS = {'-L', '-S', '-f', '-T', '-c'}
+SCRIPT_SUFFIXES = ('.sh', '.bash', '.py', '.js', '.mjs', '.cjs', '.rb', '.pl')
+
+
+def _words(text, depth=3):
+    """Shell words of a recipe, with quoted command strings split again (`new … 'script.sh arg'`)."""
+    try:
+        words = shlex.split(text)
+    except ValueError:
+        return None
+    out = []
+    for word in words:
+        out.append(word)
+        if depth and any(c.isspace() for c in word):
+            out += _words(word, depth - 1) or []
+    return out
+
+
+def _tmux_verbs(words):
+    verbs = []
+    for i, word in enumerate(words):
+        if word == 'tmux' or word.endswith('/tmux'):
+            j = i + 1
+            while j < len(words) and words[j].startswith('-'):
+                j += 2 if words[j] in TMUX_OPTION_ARGS else 1
+            if j < len(words):
+                verbs.append(words[j])
+    return verbs
+
+
+def needs_canonical(create, folder, exists):
+    """Why `create` cannot create its lane (None when it can, or when that is not knowable).
+    `exists(container_path)` answers True / False / None (unknown — never counted as missing)."""
+    if not isinstance(create, str) or not create.strip():
+        return 'no create recipe'
+    recipe = create.replace('${workspaceFolder}', folder).replace('[workspaceFolder]', folder)
+    words = _words(recipe)
+    if words is None:
+        return None
+    verbs = _tmux_verbs(words)
+    if any(v in ATTACH_VERBS for v in verbs) and not any(v in NEW_VERBS for v in verbs):
+        return 'attach-only'
+    for word in words:
+        if word.startswith('/') and word.endswith(SCRIPT_SUFFIXES) and exists(word) is False:
+            return f'missing script {word}'
+    return None
+
+
+OPERATORS = set('();<>|&')
+UNSAFE_TO_REQUOTE = set('$`*?[{\\')
+
+
+def plain_tmux_new(create, folder, socket, session):
+    """`(folder, command)` of a WORKING recipe of exactly the shape `[exec] tmux -L <socket> new[-session] -A -D -s
+    <session> [-c <dir>] <command…>` — this lane's binding, no `-e`, no shell operators — else None. `--identity`
+    rewrites such a recipe to `canonical_recipe(…, folder, command)`: the command words are re-quoted one for one, so
+    tmux receives the same argv and the rewrite only ADDS the identity `-e` flags. Anything the re-quoting could change
+    (an expansion, a glob, a backslash, a leading `~`) or any other shape is left alone."""
+    if not isinstance(create, str):
+        return None
+    recipe = create.replace('${workspaceFolder}', folder).replace('[workspaceFolder]', folder)
+    try:
+        lexer = shlex.shlex(recipe, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        words = list(lexer)
+    except ValueError:
+        return None
+    if any(set(w) <= OPERATORS or set(w) & UNSAFE_TO_REQUOTE or w.startswith('~') for w in words):
+        return None
+    if words[:1] == ['exec']:
+        words = words[1:]
+    if words[:3] != ['tmux', '-L', socket] or len(words) < 4 or words[3] not in NEW_VERBS:
+        return None
+    i, flags, sess, cdir = 4, set(), None, None
+    while i < len(words) and words[i].startswith('-'):
+        letters = words[i][1:]
+        if letters == 'c' and i + 1 < len(words):
+            cdir, i = words[i + 1], i + 2
+        elif letters and set(letters) <= {'A', 'D'}:
+            flags, i = flags | set(letters), i + 1
+        elif letters.endswith('s') and set(letters[:-1]) <= {'A', 'D'} and i + 1 < len(words):
+            flags, sess, i = flags | set(letters[:-1]), words[i + 1], i + 2
+        else:
+            return None   # -e (already has an identity, or a partial one), -d, -n, -x, …: not the plain shape
+    command = words[i:]
+    cdir = cdir or folder
+    if sess != session or flags != {'A', 'D'} or not command or not cdir.startswith('/'):
+        return None
+    return cdir, ' '.join(shlex.quote(w) for w in command)
+
+
+def normalized_text(text, lanes_by_name, canonicalize=None):
+    """Return the file text with uniform commands + the `lanes` block. Minimal textual edits when possible.
+    `canonicalize` = {'ws': workspace id, 'exists': container path -> True/False/None, 'repair': bool (default True,
+    `--canonicalize`), 'identity': bool (default False, `--identity`)}."""
     data = json.loads(text)
     block = {'version': 1, 'terminals': {}}
     commands = {}
@@ -47,6 +152,25 @@ def normalized_text(text, lanes_by_name):
             entry['tmux'] = {'socketName': lane['tmux']['socket'], 'sessionName': lane['tmux']['session']}
         if create:
             entry['create'] = create
+        if 'createPrevious' in previous:
+            entry['createPrevious'] = previous['createPrevious']
+        if canonicalize and lane.get('holder') == 'tmux' and lane.get('tmux'):
+            folder = lane.get('folder') or L.CONTAINER_HOME
+            socket, session = lane['tmux']['socket'], lane['tmux']['session']
+            kept = plain_tmux_new(create, folder, socket, session) if canonicalize.get('identity') else None
+            if canonicalize.get('repair', True) and needs_canonical(create, folder, canonicalize['exists']):
+                entry.pop('create', None)
+                entry['create'] = L.canonical_recipe(lane['id'], canonicalize['ws'], socket, session, folder)
+                entry['createPrevious'] = create
+            elif kept:
+                try:
+                    recipe = L.canonical_recipe(lane['id'], canonicalize['ws'], socket, session, kept[0], cmd=kept[1])
+                except L.LanesError:
+                    recipe = None   # a trace the proxy would reject: no identity to give, the recipe stays
+                if recipe:
+                    entry.pop('create', None)
+                    entry['create'] = recipe
+                    entry['createPrevious'] = create
         block['terminals'][term['name']] = entry
         commands[term['name']] = ENTRY + lane['id']
     # Nothing to do: leave the file byte-identical (never reformat somebody else's JSON).
@@ -104,7 +228,7 @@ def projected_text(source_text, source_path):
     return json.dumps({**note, **data}, ensure_ascii=False, indent=2) + '\n'
 
 
-def plan(registry, only=()):
+def plan(registry, only=(), canonicalize=False, identity=False):
     """Yield (workspace id, host path, container path, old text, new text, note)."""
     catalog = L.read_site_json(L.workspaces_dir() / 'catalog.json')['workspaces']
     containers = registry['containers']
@@ -123,7 +247,14 @@ def plan(registry, only=()):
             lanes = {name[len(prefix):] if prefix and name.startswith(prefix) else name: lane for name, lane in lanes.items()}
             host_file = L.host_path(info, repo['registry'])
             old = host_file.read_text()
-            new = normalized_text(old, lanes)
+
+            def exists(container_path, info=info):
+                try:
+                    return L.host_path(info, container_path).exists()
+                except (L.LanesError, OSError):
+                    return None   # outside the home volume / container unknown: not knowable, never "missing"
+            mode = {'ws': item['id'], 'exists': exists, 'repair': canonicalize, 'identity': identity}
+            new = normalized_text(old, lanes, mode if canonicalize or identity else None)
             yield item['id'], host_file, repo['registry'], old, new, 'registry'
             if repo.get('cursor'):
                 target = L.host_path(info, repo['cursor'])
@@ -136,7 +267,8 @@ def run(args):
     only = [a for a in args if not a.startswith('--')]
     registry = L.load_registry()
     changed = 0
-    for workspace, host_file, container_path, old, new, note in plan(registry, only):
+    plans = plan(registry, only, '--canonicalize' in args, '--identity' in args)
+    for workspace, host_file, container_path, old, new, note in plans:
         if host_file is None:
             print(f'== {workspace}: {note}')
             continue
@@ -162,5 +294,6 @@ def run(args):
             L.atomic_write(host_file, new, mode=mode)
             print(f'   written (backup in {backup_dir})')
     if not write and changed:
-        print(f'\n{changed} file(s) would change. Apply with:  lanes cursor-sync <workspace> --write')
+        again = ''.join(f' {flag}' for flag in ('--canonicalize', '--identity') if flag in args)
+        print(f'\n{changed} file(s) would change. Apply with:  lanes cursor-sync <workspace>{again} --write')
     return 0