leos-agent 10.2.0 → 10.7.0

package/scripts/dispatch_log.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""dispatch_log: the append-only record of every subagent dispatch the guard saw.
+
+WHY A LOG AT ALL. dispatch_guard.py decides one call at a time and can never see
+a fan-out, so the signals that need a second dispatch to interpret -- was a block
+followed by a compliant re-dispatch, was a small brief one of five siblings --
+are recorded here and resolved at read time. Judgment that lives in the reader
+costs nothing on the hot path and can be revised without a Codex /hooks
+re-approval.
+
+NEVER PROMPT TEXT. This file sits in a home directory forever and would otherwise
+accumulate briefs about whatever Leo works on. Prompts and working directories
+are stored as truncated SHA-256, which is enough to notice the same brief
+re-dispatched after a block and useless to anyone reading the file. Raw text only
+under LEOS_AGENT_DISPATCH_LOG_PROMPTS=1, truncated, and documented as debug-only.
+
+The file is ${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}/dispatch.jsonl,
+beside routing.json and the handoffs -- data lives with the data, never inside
+the plugin, so an upgrade or an uninstall cannot take it.
+
+  dispatch_log.py report [--limit N] [--json]   what the guard has been seeing
+  dispatch_log.py path                          the log's path
+
+Exit codes: 0 ok, 2 on bad usage.
+"""
+import argparse
+import collections
+import hashlib
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+# Same data root and the same lock discipline as every other machine-local file.
+# _locked takes any path (it locks a sibling .lock), which is why a .jsonl can
+# use it even though state_file() would force a .json suffix.
+from state import _data_root, _locked  # noqa: E402
+
+LOG_NAME = "dispatch.jsonl"
+
+# One megabyte, one generation. ~230 bytes per record is roughly 4,500 dispatches
+# per file and 9,000 retained -- months of history, bounded at 2 MiB forever, with
+# no cron job and nothing to configure.
+MAX_BYTES = 1 << 20
+
+RECORD_VERSION = 1
+
+
+def path():
+    return os.path.join(_data_root(), LOG_NAME)
+
+
+def digest(text):
+    """A short, irreversible stand-in for text we refuse to store."""
+    if not text:
+        return None
+    return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:12]
+
+
+def _keep_prompts():
+    return os.environ.get("LEOS_AGENT_DISPATCH_LOG_PROMPTS") == "1"
+
+
+def record(dispatch, decision, reason, harness, session=None, cwd=None, trivial=0):
+    """The on-disk shape for one dispatch. Pure; writes nothing."""
+    entry = {
+        "v": RECORD_VERSION,
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "harness": harness,
+        "session": digest(session),
+        # Parallel dispatches from one assistant message land in the same
+        # two-second bucket, which is how `report` tells a fan-out from a
+        # sequence of lone spawns without the hot path ever reading the log.
+        "burst": "%s:%d" % (digest(session) or "-", int(time.time() // 2)),
+        "project": digest(cwd),
+        "decision": decision,
+        "reason": reason,
+    }
+    if dispatch is not None:
+        entry.update({
+            "tool": dispatch.tool,
+            "agent": dispatch.agent,
+            "model": dispatch.model,
+            "trivial": trivial,
+            "prompt_bytes": dispatch.prompt_bytes,
+            "prompt_lines": dispatch.prompt_lines,
+            "paths": dispatch.path_count,
+            "prompt": dispatch.prompt_hash,
+        })
+        if _keep_prompts():
+            entry["prompt_text"] = dispatch.prompt_head
+    return entry
+
+
+def append(entry):
+    """Append one record. Rotates at MAX_BYTES. Raises only on real I/O trouble.
+
+    Callers must treat a failure here as cosmetic: the guard's decision is made
+    before this is called and emitted after it, so a read-only home or a full
+    disk costs a log line, never a dispatch.
+    """
+    target = path()
+    with _locked(target):
+        try:
+            if os.path.getsize(target) > MAX_BYTES:
+                os.replace(target, target + ".1")
+        except OSError:
+            pass  # absent, or unstattable; either way there is nothing to rotate
+        # 0600 explicitly: open("a") yields 0644 under a default umask, which is
+        # the wrong mode for a file that indexes Leo's projects even in hashes.
+        fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a") as fh:
+            fh.write(json.dumps(entry, sort_keys=True) + "\n")
+
+
+def read(limit=None, target=None):
+    """Records, oldest first. Tolerates a truncated final line from a crash."""
+    out = []
+    for candidate in ((target,) if target else (path() + ".1", path())):
+        try:
+            with open(candidate, encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                    except ValueError:
+                        continue  # a half-written last line, or a foreign line
+                    if isinstance(entry, dict):
+                        out.append(entry)
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            sys.exit("dispatch_log: %s: %s" % (candidate, exc.strerror or exc))
+    return out[-limit:] if limit else out
+
+
+def summarise(entries):
+    """The read-time judgment: burst collapse, tiers, and block conversion."""
+    # Only dispatches that actually ran count toward a burst. A block and the
+    # re-dispatch it forced land in the same two-second bucket, and counting
+    # both would let every blocked retry pose as a fan-out of two.
+    bursts = collections.Counter(
+        e.get("burst") for e in entries if e.get("decision") not in ("block", "error")
+    )
+
+    tiers = collections.Counter()
+    for entry in entries:
+        agent = entry.get("agent") or ""
+        if agent.startswith("leo-"):
+            tiers[agent] += 1
+        elif entry.get("model"):
+            tiers["explicit model"] += 1
+        elif entry.get("decision") == "block":
+            tiers["blocked"] += 1
+        else:
+            tiers["inherited"] += 1
+
+    # A trivial-looking brief that was one of several in the same burst is a
+    # fan-out, which the policy wants. Only a lone small spawn is a finding --
+    # and only one that actually ran: a blocked dispatch spent nothing, so it
+    # cannot also be an over-delegation.
+    trivial = [
+        e for e in entries
+        if e.get("trivial", 0) >= 2
+        and e.get("decision") not in ("block", "error")
+        and bursts.get(e.get("burst"), 0) < 2
+    ]
+
+    # Did a block actually change anything? A blocked brief whose hash comes back
+    # naming a tier is the guard working; one that never returns was abandoned.
+    blocked = {e.get("prompt") for e in entries if e.get("decision") == "block"}
+    blocked.discard(None)
+    converted = {
+        e.get("prompt") for e in entries
+        if e.get("prompt") in blocked and e.get("decision") != "block"
+    }
+
+    return {
+        "records": len(entries),
+        "window": [entries[0].get("ts"), entries[-1].get("ts")] if entries else [],
+        "harnesses": dict(collections.Counter(e.get("harness") for e in entries)),
+        "decisions": dict(collections.Counter(e.get("decision") for e in entries)),
+        "tiers": dict(tiers),
+        "errors": sum(1 for e in entries if e.get("decision") == "error"),
+        "blocked": len(blocked),
+        "converted": len(converted),
+        "trivial_lone_spawns": len(trivial),
+        "agents": dict(collections.Counter(
+            "%s @ %s" % (e.get("agent") or "-", e.get("model") or "inherited")
+            for e in entries
+        )),
+    }
+
+
+def render(summary):
+    lines = []
+    # Errors lead. Conflating "the guard crashed" with "the guard allowed" is how
+    # a dead guard goes unnoticed for months, so a nonzero count is the headline.
+    if summary["errors"]:
+        lines.append("!! %d guard error(s) -- the guard failed open this many times" % summary["errors"])
+    if not summary["records"]:
+        lines.append("no dispatches recorded yet (%s)" % path())
+        return "\n".join(lines)
+
+    lines.append("%d dispatch(es)  %s .. %s" % (summary["records"], summary["window"][0], summary["window"][1]))
+    lines.append("  harnesses   " + ", ".join("%s %d" % kv for kv in sorted(summary["harnesses"].items())))
+    lines.append("  tiers       " + ", ".join("%s %d" % kv for kv in sorted(summary["tiers"].items())))
+    if summary["blocked"]:
+        lines.append("  blocks      %d, of which %d re-dispatched with a tier named" % (
+            summary["blocked"], summary["converted"]))
+    lines.append("  lone small spawns  %d  (fan-outs excluded)" % summary["trivial_lone_spawns"])
+    lines.append("  agent @ model:")
+    for name, count in sorted(summary["agents"].items(), key=lambda kv: (-kv[1], kv[0])):
+        lines.append("    %-44s %d" % (name, count))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="dispatch_log.py", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    report = sub.add_parser("report", help="what the guard has been seeing")
+    report.add_argument("--limit", type=int, default=None, help="only the most recent N records")
+    report.add_argument("--json", action="store_true", help="machine-readable summary")
+    sub.add_parser("path", help="the log file's path")
+
+    args = parser.parse_args(argv)
+    if args.command == "path":
+        print(path())
+        return 0
+
+    summary = summarise(read(limit=args.limit))
+    print(json.dumps(summary, indent=1, sort_keys=True) if args.json else render(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/ghreview.py

@@ -48,6 +48,11 @@ SNAP_MAX_DISTANCE = 10  # beyond this from the requested line, drop instead of s
 
 MARKER = "<!-- leos-agent:review-pr -->"
 
+# The reviewer's procedure caps a review at 15 comments; this is the script's
+# own backstop well above it, so a reviewer talked past its cap by a hostile
+# diff still cannot blanket a pull request.
+MAX_STAGE_COMMENTS = 50
+
 
 def _mark(body):
     """Tag a comment body as tool-created, so clear-pending can tell it apart
@@ -462,6 +467,13 @@ def cmd_stage(a):
     if not comments:
         print(json.dumps({"staged": 0, "note": "no comments provided; nothing created"}))
         return
+    if len(comments) > MAX_STAGE_COMMENTS:
+        print(
+            f"input error: {len(comments)} comments exceeds the cap of {MAX_STAGE_COMMENTS}; "
+            "a review this wide should be narrowed, not staged",
+            file=sys.stderr,
+        )
+        sys.exit(2)
 
     files = fetch_files(a.repo, a.pr)
     staged, snapped, dropped = validate_comments(comments, build_maps(files))

package/scripts/handoff.py

@@ -18,7 +18,8 @@ it. Files land at <root>/handoffs/<name>.md.
 
 Nothing is ever pruned automatically; `rm` is the only way a handoff goes away.
 `list` shows only handoffs written in or under the current directory unless
---all is passed. Exit codes: 0 ok, non-zero on error.
+--all is passed; when that leaves nothing it falls back to showing all of them
+rather than sending the caller away to re-run. Exit codes: 0 ok, non-zero on error.
 """
 import datetime as dt
 import os
@@ -32,8 +33,13 @@ SLUG = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
 
 
 def handoff_dir():
-    path = os.path.join(_data_root(), "handoffs")
-    os.makedirs(path, exist_ok=True)
+    # 0700 on creation, matching state.py: handoffs carry project context that
+    # is nobody else's business on a shared machine. The root is created first
+    # so it gets the mode too — makedirs applies mode to the leaf only.
+    root = _data_root()
+    os.makedirs(root, mode=0o700, exist_ok=True)
+    path = os.path.join(root, "handoffs")
+    os.makedirs(path, mode=0o700, exist_ok=True)
     return path
 
 
@@ -60,15 +66,17 @@ def frontmatter(path):
 
 
 def title_of(path):
+    """The first `# ` heading — after the frontmatter when there is one, from
+    the top of the file when there is not."""
     try:
         with open(path) as fh:
-            seen_open = False
-            for line in fh:
-                if line.strip() == "---":
-                    if seen_open:
+            first = fh.readline()
+            if first.strip() == "---":
+                for line in fh:
+                    if line.strip() == "---":
                         break
-                    seen_open = True
-                    continue
+            elif first.startswith("# "):
+                return first[2:].strip()
             for line in fh:
                 if line.startswith("# "):
                     return line[2:].strip()
@@ -128,6 +136,9 @@ def cmd_new(argv):
         suffix += 1
     print(name)
     print(file_for(name))
+    # The `created:` value, ready to copy verbatim — a model asked to invent
+    # "now" gets it wrong often enough to matter.
+    print(dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
 
 
 def cmd_path(argv):
@@ -145,20 +156,32 @@ def cmd_list(argv):
         except (IndexError, ValueError):
             sys.exit("handoff: --limit needs a number")
     here = os.path.realpath(os.getcwd())
-    rows = []
-    for name, path, meta, _ in entries():
-        cwd = os.path.realpath(meta.get("cwd", "")) if meta.get("cwd") else ""
-        if not show_all and cwd:
-            related = here == cwd or here.startswith(cwd + os.sep) or cwd.startswith(here + os.sep)
-            if not related:
-                continue
-        rows.append((name, age_of(meta.get("created", "")), meta.get("repo", meta.get("cwd", "?")), title_of(path)))
-        if len(rows) >= limit:
-            break
+
+    def collect(unfiltered):
+        rows = []
+        for name, path, meta, _ in entries():
+            cwd = os.path.realpath(meta.get("cwd", "")) if meta.get("cwd") else ""
+            if not unfiltered and cwd:
+                related = here == cwd or here.startswith(cwd + os.sep) or cwd.startswith(here + os.sep)
+                if not related:
+                    continue
+            rows.append((name, age_of(meta.get("created", "")), meta.get("repo", meta.get("cwd", "?")), title_of(path)))
+            if len(rows) >= limit:
+                break
+        return rows
+
+    rows = collect(show_all)
+    note = ""
+    if not rows and not show_all:
+        # Falling back beats printing "try --all": the caller is usually a model
+        # one round trip from giving up and searching the filesystem instead.
+        rows = collect(True)
+        note = "none written in or under this directory; showing all"
     if not rows:
-        scope = "" if show_all else " for this directory (try --all)"
-        print(f"no handoffs{scope}")
+        print("no handoffs")
         return
+    if note:
+        print(note)
     width = max(len(row[0]) for row in rows)
     for name, age, repo, title in rows:
         print(f"{name.ljust(width)}  {age.rjust(4)}  {repo}  {title}")

package/scripts/leo-install.py

@@ -23,7 +23,14 @@ import sys
 import tempfile
 from pathlib import Path
 
-HARNESSES = ("claude", "codex", "cursor", "hermes", "pi", "opencode")
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import routing  # noqa: E402  owns the harness list and the machine-local model config
+
+HARNESSES = routing.HARNESSES
+
+# The routing region inside the payload, replaced per harness at install time.
+ROUTING_OPEN = "<!-- leos-agent:routing -->"
+ROUTING_CLOSE = "<!-- /leos-agent:routing -->"
 
 OPEN_RE = re.compile(r"^<leos-agent\b[^>]*>[ \t]*$", re.MULTILINE)
 CLOSE_RE = re.compile(r"^</leos-agent>[ \t]*$", re.MULTILINE)
@@ -36,10 +43,18 @@ CODEX_SOFT_CAP = 28 * 1024
 # copies apart from a file the user happens to have put at the same path.
 PROVENANCE = "leos-agent"
 
+# Skill and command text refers to scripts as <plugin-root>/scripts/… and the
+# model resolves the root once. OpenCode copies live apart from the scripts,
+# and OpenCode sets no resolution env var, so their copies are installed with
+# the token already replaced by this machine's absolute plugin root. Installing
+# alternately from a checkout and a cache re-bakes the root each time — last
+# install wins, and --check reports a stale root as out of date.
+PLUGIN_ROOT_TOKEN = "<plugin-root>"
+
 # OpenCode plugins cannot register skills or commands from JS, so these are
 # copied to disk instead. check.py asserts every file they name carries
 # PROVENANCE, without which the installer would refuse to upgrade its own copy.
-OPENCODE_SKILLS = ("doctor", "review-pr", "handoff", "handon")
+OPENCODE_SKILLS = ("doctor", "review-pr", "handoff", "handon", "tune-routing")
 OPENCODE_COMMANDS = ("review-pr", "handoff", "handon")
 
 # Codex plugins cannot package custom agent definitions directly, so these are
@@ -100,19 +115,71 @@ def read_version(root):
 		sys.exit(f"leo-install: {manifest} has no version field")
 
 
-def payload_body(root):
-	"""The canonical payload: rules/preferences.md with its frontmatter stripped."""
+def render_routing(body, harness, config):
+	"""Replace the routing region with the stanza for this machine's config.
+
+	The payload ships with a default inside the region, so an un-rendered read of
+	rules/preferences.md -- Cursor's plugin-delivered rule, a human opening the
+	file -- still says something true. Rendering only ever narrows it to the one
+	harness being installed, which is why the installed payload is smaller than
+	the file on disk rather than larger.
+	"""
+	start = body.find(ROUTING_OPEN)
+	end = body.find(ROUTING_CLOSE)
+	if start < 0 or end < start:
+		sys.exit(f"leo-install: rules/preferences.md is missing its {ROUTING_OPEN} region")
+	return body[:start] + routing.stanza(harness, config) + body[end + len(ROUTING_CLOSE):]
+
+
+def payload_body(root, harness=None, config=None):
+	"""The canonical payload: rules/preferences.md with its frontmatter stripped.
+
+	With a harness, the routing region is rendered for it; without one the region
+	keeps its shipped default, markers and all.
+	"""
 	text = (root / "rules" / "preferences.md").read_text(encoding="utf-8")
 	body = re.sub(r"(?s)\A---\n.*?\n---\n", "", text, count=1).strip()
 	if not body:
 		sys.exit("leo-install: rules/preferences.md has no body below its frontmatter")
 	if OPEN_RE.search(body) or CLOSE_RE.search(body):
 		sys.exit("leo-install: rules/preferences.md contains a <leos-agent> marker; it must not")
+	if harness:
+		body = render_routing(body, harness, config if config is not None else routing.load())
 	return body
 
 
-def build_block(root):
-	return f'<leos-agent version="{read_version(root)}">\n{payload_body(root)}\n</leos-agent>\n'
+def build_block(root, harness=None, config=None):
+	return f'<leos-agent version="{read_version(root)}">\n{payload_body(root, harness, config)}\n</leos-agent>\n'
+
+
+def render_codex_agent(text, agent_name, config):
+	"""Substitute a Codex profile's model, leaving the shipped default when unset."""
+	entry = routing.profile(config, "codex", agent_name.split("-", 1)[1])
+	if not entry:
+		return text
+	text = re.sub(r'(?m)^model = ".*"$', f'model = "{entry["model"]}"', text, count=1)
+	if entry["effort"]:
+		text = re.sub(
+			r'(?m)^model_reasoning_effort = ".*"$',
+			f'model_reasoning_effort = "{entry["effort"]}"',
+			text,
+			count=1,
+		)
+	return text
+
+
+def cursor_routing_rule(harness, config):
+	"""Cursor reads its rules straight out of the plugin, so the per-machine half
+	has to arrive as its own always-applied rule file."""
+	return (
+		"---\n"
+		"description: leos-agent model routing for this machine.\n"
+		"alwaysApply: true\n"
+		"---\n"
+		"This supersedes the model-routing dispatch line in Leo's agent operating\n"
+		"preferences:\n\n"
+		f"{routing.stanza(harness, config)}\n"
+	)
 
 
 def scan_markers(text):
@@ -124,16 +191,19 @@ def scan_markers(text):
 	into a permanent "two blocks" error, so fenced regions are skipped.
 	"""
 	opens, closes = [], []
-	fence = None
+	fence = None  # (char, run length) of the currently open fence
 	offset = 0
 	for line in text.splitlines(keepends=True):
 		stripped = line.lstrip()
-		marker = stripped[:3]
-		if marker in ("```", "~~~"):
-			token = marker
+		run = re.match(r"(`{3,}|~{3,})", stripped)
+		if run:
+			token = run.group(1)
 			if fence is None:
-				fence = token
-			elif fence == token:
+				fence = (token[0], len(token))
+			# CommonMark: only a run of the same character at least as long as
+			# the opener closes a fence; a shorter run is fence content, so a
+			# ``` line inside a ```` example must not end the example.
+			elif fence[0] == token[0] and len(token) >= fence[1]:
 				fence = None
 		elif fence is None:
 			if OPEN_RE.match(line.rstrip("\n")):
@@ -283,11 +353,16 @@ def install_markdown(path, block, args, label, create=True):
 	return write_if_changed(path, inject(current, block), current, existed, crlf, args, label)
 
 
-def install_file_copy(src, dest, args, label, owned_parent=False):
-	"""Install a payload file the harness's plugin system cannot deliver itself."""
+def install_file_copy(src, dest, args, label, owned_parent=False, payload=None):
+	"""Install a payload file the harness's plugin system cannot deliver itself.
+
+	`payload` overrides the source text for files rendered from the machine's
+	routing config rather than copied verbatim.
+	"""
 	dest = dest.expanduser()
 	existed = dest.is_file()
-	payload = src.read_text(encoding="utf-8")
+	if payload is None:
+		payload = src.read_text(encoding="utf-8")
 	current = dest.read_text(encoding="utf-8") if existed else ""
 
 	# Never clobber or delete a same-named file this tool did not put there.
@@ -307,8 +382,27 @@ def install_file_copy(src, dest, args, label, owned_parent=False):
 	return write_if_changed(dest, payload, current, existed, False, args, label)
 
 
+def opencode_payload(src, root, rename_install=False):
+	"""An OpenCode copy's content: the plugin root baked in, optionally renamed.
+
+	OpenCode reads the copies out of ~/.config/opencode, far from the scripts
+	they invoke, and sets none of the resolution env vars — so the placeholder
+	is resolved here, at install time, where the root is known for certain.
+	The install skill is additionally renamed to match the leo-install/
+	directory it is copied into, keeping directory and frontmatter in
+	agreement whichever one OpenCode keys on.
+	"""
+	text = src.read_text(encoding="utf-8").replace(PLUGIN_ROOT_TOKEN, str(root))
+	if rename_install:
+		text = re.sub(r"(?m)^name:\s*install\s*$", "name: leo-install", text, count=1)
+	return text
+
+
 def run(harness, root, args):
-	block = build_block(root)
+	# Read once per run: rendering has to be a pure function of (version, config)
+	# or a second install would not come back "unchanged".
+	config = routing.load()
+	block = build_block(root, harness, config)
 	home = Path.home()
 	targets = []
 
@@ -328,22 +422,43 @@ def run(harness, root, args):
 						home / ".codex" / "agents" / f"{n}.toml",
 						args,
 						l,
+						payload=render_codex_agent(
+							(root / "payload" / "codex-agents" / f"{n}.toml").read_text(encoding="utf-8"),
+							n,
+							config,
+						),
 					),
 				)
 			)
 
 	elif harness == "cursor":
-		targets.append(
-			(
-				"cursor",
-				lambda: Result(
-					"cursor",
-					"skipped",
-					"Cursor has no on-disk global rules file; the plugin's alwaysApply rule delivers the payload natively",
-				),
-			)
+		# The payload itself arrives natively through the plugin's alwaysApply
+		# rule, which is the file in the plugin directory -- so there is nothing
+		# per-machine in it. Only the routing stanza needs installing, and only
+		# as its own rule -- and only when something is actually configured: an
+		# unconfigured rule would restate the payload's default, an always-loaded
+		# no-op that costs context on every turn.
+		label = "~/.cursor/rules/leos-agent-routing.mdc"
+		dest = home / ".cursor" / "rules" / "leos-agent-routing.mdc"
+		configured = bool(
+			routing.profile(config, "cursor", "runner") or routing.profile(config, "cursor", "executor")
 		)
 
+		def cursor_rule_target(l=label):
+			if args.uninstall or configured:
+				return install_file_copy(None, dest, args, l, payload=cursor_routing_rule(harness, config))
+			# Unconfigured install: write nothing, and take back a stale rule a
+			# previous config left behind -- but only one that is provably ours.
+			if not dest.is_file():
+				return Result(l, "skipped", "no routing configured for cursor")
+			if PROVENANCE not in dest.read_text(encoding="utf-8"):
+				return Result(l, "skipped", "no routing configured; leaving the unrelated file at this path")
+			if args.writes:
+				dest.unlink()
+			return Result(l, "removed", "no routing configured; stale rule removed")
+
+		targets.append((label, cursor_rule_target))
+
 	elif harness == "hermes":
 		# Never create SOUL.md: Hermes writes its own starter identity file on
 		# first run, and pre-empting that would fight the bootstrap.
@@ -374,6 +489,9 @@ def run(harness, root, args):
 					args,
 					skill_label,
 					owned_parent=True,
+					payload=opencode_payload(
+						root / "skills" / "install" / "SKILL.md", root, rename_install=True
+					),
 				),
 			)
 		)
@@ -394,6 +512,7 @@ def run(harness, root, args):
 							args,
 							l,
 							owned_parent=True,
+							payload=opencode_payload(s, root),
 						),
 					)
 				)
@@ -407,6 +526,7 @@ def run(harness, root, args):
 						args,
 						l,
 						owned_parent=True,
+						payload=opencode_payload(root / "skills" / n / "SKILL.md", root),
 					),
 				)
 			)
@@ -420,6 +540,7 @@ def run(harness, root, args):
 						cfg / "commands" / f"{n}.md",
 						args,
 						l,
+						payload=opencode_payload(root / "commands" / f"{n}.md", root),
 					),
 				)
 			)