leos-agent 10.2.0 → 10.6.0

package/README.md

@@ -1,28 +1,35 @@
 # leos-agent
 
-Leo's portable agent operating policy, version **10.2.0**, installable on Claude
+Leo's portable agent operating policy, version **10.6.0**, installable on Claude
 Code, Codex, Cursor, Hermes, Pi, and OpenCode through each harness's own plugin
 system.
 
 The policy it carries is short: **the main thread is an orchestrator.**
-Investigation, brainstorming, debugging, execution, testing, and mechanical work
-all run in briefed subagents, so the main thread never fills up with the files,
-retries, and logs that produced an answer — only the answer. Work runs at one of two
-named tiers: **standard**, the model you are already using, for thinking and
-judging; **economical**, the cheapest sufficient profile where the harness can
-select one. Narrow search, reading, testing, and mechanical work use the runner
-profile; well-specified implementation uses the executor profile.
+Investigation, brainstorming, debugging, and mechanical work all run in briefed
+subagents, so the main thread never fills up with the files, retries, and logs
+that produced an answer — only the answer. A single command you can filter at
+the shell stays inline. Work runs at one of two named tiers: **standard**, the
+model you are already using, for thinking and judging; **economical**, two
+named agent profiles — `leo-runner` for narrow search, reading, testing, and
+mechanical work, `leo-executor` for well-specified implementation — shipped as
+first-class agent definitions on both Claude Code (`agents/`, Haiku and Sonnet)
+and Codex (installed TOML profiles), so the cheaper model is baked into the
+agent type rather than chosen per dispatch. Every other harness inherits unless
+a machine-local [routing config](#per-machine-model-routing) names models for it.
 
 ## What it ships
 
-Beyond the preferences payload: a setup diagnostic, a session handoff pair, and
-three GitHub skills. The GitHub ones need `gh`, authenticated.
+Beyond the preferences payload: the two economical-tier agent definitions
+(`agents/` for Claude Code, `payload/codex-agents/` for Codex), a setup
+diagnostic, a routing tuner, a session handoff pair, and three GitHub skills.
+The GitHub ones need `gh`, authenticated.
 
 | Skill | What it does | Where |
 |---|---|---|
 | `review-pr` | Reviews a pull request and stages inline comments as a **pending** review — visible only to you until you submit or discard on GitHub. Never submits. Resolves the originating ticket (Linear, Jira, GitHub issue) from the PR's title, body, or branch when one is named, and adds a spec lens that checks the diff against it. | every skill-loading harness |
-| `watch-review` | Arms a watcher that streams new direct review requests into the session, one notification per pull request, for `review-pr` to handle. Polling is a shell script (`scripts/watch_review.py`), not a model loop: an idle tick is one `gh` call and zero tokens. | **Claude Code only** — built on its Monitor tool |
+| `watch-review` | Arms a watcher that streams direct review requests into the session for `review-pr` to handle, and re-streams one when its head moves. Never surfaces a pull request someone else has approved. Polling is a shell script (`scripts/watch_review.py`), not a model loop: an idle tick is one `gh` call and zero tokens. | **Claude Code only** — built on its Monitor tool |
 | `doctor` | Diagnoses this harness's setup, read-only: whether the `<leos-agent>` block is injected and current, what else is loaded into every session (global instruction file, memories, settings, skills), and whether a local checkout passes `scripts/check.py`. Run it with `/doctor`. | every skill-loading harness |
+| `tune-routing` | Picks the concrete models behind `leo-runner` and `leo-executor` on this machine, writes them to `~/.leos-agent-local/routing.json`, re-renders the install, and proves the choice with one live dispatch — model strings are never checked against a known-model list, so a typo surfaces at dispatch time and nowhere earlier. Run it with `/tune-routing`. | every skill-loading harness |
 | `handoff` | Writes this session's context — goal, what landed, what is next, key files, decisions, gotchas — to a markdown document under `~/.leos-agent-local/handoffs/`, so a later session can pick the work up. Pointers, not contents: it names files rather than pasting them. Run it with `/handoff`. | every skill-loading harness |
 | `handon` | Loads a handoff written earlier — in this harness or a different one — and resumes from it, reporting any drift first when the directory, branch, or HEAD has moved since. Loading never consumes a handoff. Run it with `/handon <name>`. | every skill-loading harness |
 | `attach-pr` | Attaches the current desktop session to an existing pull request so the app shows its PR card. Creates nothing and pushes nothing. | **Claude Code only** — it drives that app's card |
@@ -31,14 +38,80 @@ The Claude-only pair live in `skills-claude/` and `commands-claude/`, listed in
 `.claude-plugin/plugin.json` and nowhere else. Hermes receives the preferences
 payload but no skills — it has no skill loader.
 
-The watcher records each reviewed pull request under `~/.leos-agent-local/`
-(override with `$LEOS_AGENT_LOCAL_PATH`), so it never surfaces the same one
-twice; `watch_review.py forget <n>` puts one back in play.
-
-Handoffs live in the same place, under `handoffs/`. Nothing there is ever pruned
-automatically: `handoff.py list [--all]` shows what exists and `handoff.py rm
-<name>` is the only way one goes away. The directory is deliberately outside
-the plugin, so upgrading or reinstalling can never take state with it.
+The watcher records the **head commit** it reviewed each pull request at, under
+`~/.leos-agent-local/` (override with `$LEOS_AGENT_LOCAL_PATH`), so a pull
+request comes back when someone pushes to it and stays quiet otherwise;
+`watch_review.py forget <n>` puts one back in play at its current head. Two
+gates keep a continuous watch from being expensive: a pull request another user
+has already approved is never surfaced at all, and a new head must hold still
+for `--settle` seconds (default 120) before it is emitted, so a burst of pushes
+costs one review rather than one per commit.
+
+Handoffs live in the same place, at
+`~/.leos-agent-local/handoffs/<name>.md` — a fixed path that needs no plugin
+root, so `/handon` reads one with a single `cat` rather than going looking for
+it. Nothing there is ever pruned automatically: `handoff.py list [--all]` shows
+what exists and `handoff.py rm <name>` is the only way one goes away. The
+directory is deliberately outside the plugin, so upgrading or reinstalling can
+never take state with it.
+
+## Per-machine model routing
+
+The economical tier only ever had teeth on Claude Code and Codex, because those
+are the two harnesses whose model names the payload could hardcode. Everywhere
+else, every fan-out ran at the current model — the most expensive shape the
+policy has. Which models a harness offers varies by machine and by what an IT
+department allows, so the mapping is machine-local config rather than something
+the plugin can ship:
+
+```jsonc
+// ~/.leos-agent-local/routing.json  (override the directory with $LEOS_AGENT_LOCAL_PATH)
+{
+  "cursor":   {"runner": "grok-code-fast-1", "executor": "claude-sonnet-4.6"},
+  "opencode": {"runner": "anthropic/claude-haiku-4-5"},
+  "codex":    {"runner": {"model": "gpt-5.6-luna", "effort": "low"}}
+}
+```
+
+Keys are harness names; each holds `runner` and/or `executor`, independently —
+configuring only `runner` is the common case, since it is the fan-out that
+costs. A bare string is shorthand for `{"model": ...}`. Model strings are
+free-form and never checked against a known-model list: whatever the harness
+accepts goes in verbatim. A misspelled *key*, though, is a hard error, because a
+typo that silently left a harness on the expensive model is the one failure this
+is here to prevent.
+
+**Nothing reads it at run time.** `leo-install.py` renders the result into the
+`<leos-agent>` block it already writes, so a session pays nothing to know its own
+routing — no config read, no extra turn. It costs *less* than before: each
+machine now carries only its own harness's dispatch line instead of all of them,
+which took the installed payload from 4497 bytes to 4315–4344 depending on the
+harness. `scripts/measure_context.py` prints the per-harness figure and fails if
+an unconfigured harness ever grows past the old one.
+
+Edit the file — by hand, or with `routing.py set --harness <h> --runner
+<model>`, which [`/tune-routing`](#what-it-ships) drives end to end — then
+re-run the installer to re-render; `leo-install.py <harness> --check` reports
+"out of date" until you do, and `/doctor` surfaces it. Installing is
+idempotent: same config, same version, same bytes, so a second run reports
+`unchanged`.
+
+**The config is yours, never the installer's.** `leo-install.py` only ever reads
+it, and never creates, migrates, rewrites, or removes it, including under
+`--uninstall`; it lives outside the plugin so an upgrade cannot take it. The one
+thing that writes it is `routing.py set` / `unset`, run because you asked: it
+creates the file if it is missing, replaces the one role you named, validates
+the whole document before writing, and leaves every other harness's entry —
+including the bare-string shorthand — exactly as you wrote it. `routing.py show`
+prints what is configured; with no file at all, every harness uses its shipped
+default and behaviour is exactly what it was before this existed.
+
+Delivery differs by harness only in the last mile: Claude Code gets a `model:`
+override alongside `subagent_type:` (the plugin-owned `agents/*.md` are never
+rewritten), Codex gets the models substituted into its installed profile TOMLs,
+Cursor gets its own `~/.cursor/rules/leos-agent-routing.mdc` because its rules
+come straight out of the plugin directory, and the rest get the rendered line in
+their global instruction file.
 
 ## How it works
 
@@ -49,7 +122,7 @@ gets it through its global instruction file, written by
 [`scripts/leo-install.py`](scripts/leo-install.py) into a marker block:
 
 ```
-<leos-agent version="10.2.0">
+<leos-agent version="10.6.0">
 ...the payload...
 </leos-agent>
 ```
@@ -67,7 +140,7 @@ exactly the content it exists to protect.
 
 | Harness | Global file the installer writes |
 |---|---|
-| Claude Code | `~/.claude/CLAUDE.md` |
+| Claude Code | `~/.claude/CLAUDE.md` (the `leo-runner` / `leo-executor` agents need no installer step — the plugin's `agents/` directory delivers them) |
 | Codex | `~/.codex/AGENTS.md` (plus `~/.codex/agents/leo-runner.toml` and `leo-executor.toml`) |
 | Cursor | none — the plugin's always-apply rule delivers it |
 | Hermes | `~/.hermes/SOUL.md` (edited only if it already exists) |
@@ -118,7 +191,7 @@ that it is already installed and changes nothing.
 Run the installer's uninstall first, while the script is still on disk:
 
 ```bash
-python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py claude --uninstall
+python3 ~/.claude/plugins/cache/leos-agent/leos-agent/10.6.0/scripts/leo-install.py claude --uninstall
 ```
 
 ```bash
@@ -149,7 +222,7 @@ Then run the `install` skill in a Codex session (`$leos-agent`, then `install`),
 run the script directly:
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py codex
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.6.0/scripts/leo-install.py codex
 ```
 
 This writes `~/.codex/AGENTS.md` and installs two economical agents:
@@ -174,7 +247,7 @@ threads only. Re-adding an already-installed plugin is idempotent.
 **Uninstall**
 
 ```bash
-python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.2.0/scripts/leo-install.py codex --uninstall
+python3 ~/.codex/plugins/cache/leos-agent/leos-agent/10.6.0/scripts/leo-install.py codex --uninstall
 ```
 
 ```bash
@@ -290,8 +363,9 @@ Remove the `leos-agent` entry from `plugins.enabled`, and delete the clone if
 you made one. Your own `SOUL.md` content is left intact — only the block goes.
 
 **Note on model routing:** Hermes applies a single `delegation.model` to every
-child of a `delegate_task` call, so it cannot vary the model per spawn. The
-policy therefore routes all Hermes work to the current model.
+child of a `delegate_task` call, so it cannot vary the model per spawn. A
+routing config still renders a stanza for it, and the stanza says to inherit and
+say so where a per-spawn model is not available.
 
 ---
 
@@ -322,7 +396,7 @@ Pinned refs are reconciled, never silently advanced — to move to a new tag,
 install it explicitly:
 
 ```bash
-pi install git:github.com/foxhatleo/leos-agent@v10.2.0
+pi install git:github.com/foxhatleo/leos-agent@v10.6.0
 ```
 
 Re-run `/skill:install` afterwards.
@@ -361,7 +435,10 @@ python3 ~/.cache/opencode/packages/leos-agent@latest/node_modules/leos-agent/scr
 
 That writes `~/.config/opencode/AGENTS.md` and copies the skills and commands into
 `~/.config/opencode/skills/` and `~/.config/opencode/commands/`. From then on
-`/leo-install` works inside OpenCode.
+`/leo-install` works inside OpenCode. The copies are installed with the plugin
+root already resolved to an absolute path — OpenCode sets no resolution env var,
+and the copies live apart from the scripts they invoke — so re-run the installer
+after clearing or moving the package cache to point them at the new location.
 
 **Upgrade**
 
@@ -462,8 +539,10 @@ is the worked example: the main thread loads a 3.2 KB contract, the reviewer
 subagent reads `reference/procedure.md`, and the lens sub-subagents read
 `reference/lenses.md` that the reviewer itself never loads. Before the split the
 main thread and the reviewer each loaded the same 21 KB file, and every turn
-after that re-read it. Split a file out only when some run genuinely does not
-read it; moving prose around costs the same tokens.
+after that re-read it. `tune-routing` does the same with its per-harness model
+discovery, in `reference/harnesses.md`, which only a run that actually tunes
+ever loads. Split a file out only when some run genuinely does not read it;
+moving prose around costs the same tokens.
 
 **Invocation split.** A skill is either *user-invoked* — reached by typing its
 slash command, and carrying `disable-model-invocation: true` — or *deliberately
@@ -537,7 +616,7 @@ claude plugin uninstall leos-agent@leos-agent && claude plugin install leos-agen
 ```
 
 or replace the cachebuster suffix in the Codex manifest with one in the form
-`10.2.0+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
+`10.6.0+codex.local-YYYYMMDD-HHMMSS` and re-add. Either way, plugin changes only
 reach a **new** session or thread.
 
 `--check` exits non-zero when a file is out of date, and `--force` replaces a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leos-agent",
-  "version": "10.2.0",
+  "version": "10.6.0",
   "description": "Leo's portable agent operating policy: orchestrator main thread, subagent-first execution, cost-tiered model routing.",
   "type": "module",
   "main": "index.js",

package/rules/preferences.md

@@ -7,58 +7,63 @@ alwaysApply: true
 ## The main thread is an orchestrator
 
 Keep the main thread minimal: understand the request, decide the approach,
-dispatch subagents, integrate what they return, report to Leo. Bulk work belongs
-in subagents.
+dispatch subagents, integrate what they return, report to Leo.
 
-Delegate work whose byproducts you do not want to keep: many files read, long
-output, several attempts before it lands — investigation, code search,
-debugging, execution, test runs. Only the conclusion comes back; the rest dies
-with it.
+Delegate work that floods your context to reach one answer: many files read,
+several attempts before it lands, open-ended search — investigation, code
+search, debugging. Only the conclusion comes back.
 
-Keep it inline when delegating costs more than it saves. Your context is already
-cached; a subagent starts cold and pays a full cache write on its system prompt
-and brief before reading anything. That write, not a screenful of output, is the
-break-even — one known file or a one-line edit never clears it.
+A single command you can filter at the shell runs inline: a `grep` or `tail`
+pipe costs nothing, so noisy output is never the trigger. Test runs, linters,
+and builds are inline by default.
 
-Do not spawn a subagent to avoid thinking. If you are a subagent, this section
-does not apply — do the work yourself.
+Below that bar, delegating costs more than it saves. Your context is cached; a
+subagent starts cold and pays a full cache write on its system prompt and brief
+— roughly $3 at Opus prices, $1 at Sonnet. That write is the break-even;
+one known file or a one-line edit never clears it.
+
+Never delegate to avoid thinking. As a subagent, do not delegate at all — do
+the work yourself.
 
 ## Briefing a subagent
 
 Spawn with clean context: on Codex pass `fork_turns="none"`; elsewhere request
-a fresh child where supported. Report the gap if history inheritance cannot be
-prevented. Write the brief to stand alone:
+a fresh child. Write the brief to stand alone:
 
 - State the goal and what "done" looks like.
-- Name the files, paths, symbols, and commands it should start from.
+- Name the files, paths, symbols, and commands to start from.
 - Include settled decisions, so it does not relitigate them.
-- Where supported, grant only the skills and tools it needs; extra schemas cost
-  context and invite wandering.
+- Grant only the skills and tools it needs; extra schemas invite wandering.
+- Say it does the work itself and spawns nothing further; it sees only the
+  brief.
 - Say what to return: the finding, the diff, the verdict — not a transcript.
 
 Prefer several narrow subagents over one broad one, run independent ones
 concurrently, and ask for uncertainty explicitly.
 
-## Model routing
-
-Every brief names one of two tiers; there is no third.
+Cap the scope: a brief that could plausibly run past ~50 turns gets split. A
+subagent's own context grows turn over turn, so one broad brief re-creates the
+expensive-prefix problem inside the child — a single measured agent ran 231
+turns and took a third of a day's subagent spend.
 
-**Standard** is the model Leo is running now, inherited with no override.
+## Model routing
 
-**Economical** is min(current model, the cheapest sufficient profile): runner =
-Haiku on Claude Code or `gpt-5.6-luna`/low on Codex; executor = Sonnet or
-`gpt-5.6-terra`/medium. Elsewhere use the current model. Never upgrade a cheaper
-session; report when routing cannot be applied.
+Every subagent dispatch MUST name an explicit model or profile. The harness
+inherits the parent model when you say nothing, so a dispatch with no model and
+no stated reason for inheriting is a bug, not a default.
 
-Match the tier to the kind of work, not to the size of the request.
+- Reading, search, tests, logs, codemods, and every fan-out → **leo-runner**.
+- An approved plan or a well-specified code change → **leo-executor**.
+- Investigation, debugging, adjudication, orchestration → inherit the current
+  model, and say that inheriting is intended.
 
-**Thinking work runs standard** — investigation, debugging, adjudication, and
-orchestration. A weak diagnosis makes every later step wasteful.
+<!-- leos-agent:routing -->
+On Claude Code pass `subagent_type: "leo-runner"` or `"leo-executor"`; on Codex
+the installed profiles carry the models. Elsewhere use the current model.
+<!-- /leos-agent:routing -->
 
-**Doing work runs economical** — runner for tests, reading, search, logs,
-codemods, and every fan-out; executor for an approved plan or well-specified
-code change. On Codex these are `leo-runner` and `leo-executor`. Wide standard
-fan-out is the policy's most expensive shape.
+Never upgrade a cheaper session; report when routing cannot be applied. Wide
+inherited fan-out is the policy's most expensive shape.
 
 ## Caching
 

package/scripts/check.py

@@ -110,7 +110,9 @@ def main():
 	# 5. Skills and commands exist and carry the portable frontmatter subset.
 	skills = sorted((ROOT / "skills").glob("*/SKILL.md"))
 	check(len(skills) >= 1, "skills/: no SKILL.md found; the plugin must ship at least one skill")
-	for skill in skills:
+	# skills-claude/ ships through .claude-plugin/plugin.json on the same terms, so
+	# it is validated on the same terms -- an unguarded tree is where conventions rot.
+	for skill in skills + sorted((ROOT / "skills-claude").glob("*/SKILL.md")):
 		text = skill.read_text(encoding="utf-8")
 		check(text.startswith("---\n"), f"{skill.relative_to(ROOT)}: missing frontmatter")
 		fm = text.split("---", 2)[1] if text.count("---") >= 2 else ""
@@ -161,6 +163,80 @@ def main():
 		if path.is_file():
 			check(installer.PROVENANCE in path.read_text(encoding="utf-8"), f"{rel}: must contain {installer.PROVENANCE!r} so the installer recognises its own copy")
 
+	# 5a-agents. Claude Code auto-discovers agents/ at the plugin root. The set
+	# must stay in lockstep with the Codex profiles (same names, one policy), and
+	# each definition needs the frontmatter Claude reads — a missing model field
+	# would silently inherit the parent model, which is the failure this tier
+	# exists to prevent.
+	claude_agents = sorted((ROOT / "agents").glob("*.md"))
+	check(
+		sorted(p.stem for p in claude_agents) == sorted(installer.CODEX_AGENTS),
+		f"agents/: expected exactly the Claude twins of {installer.CODEX_AGENTS}, found {[p.stem for p in claude_agents]}",
+	)
+	for agent in claude_agents:
+		rel = agent.relative_to(ROOT)
+		text = agent.read_text(encoding="utf-8")
+		check(text.startswith("---\n"), f"{rel}: missing frontmatter")
+		fm = text.split("---", 2)[1] if text.count("---") >= 2 else ""
+		name_match = re.search(r"^name:\s*(\S+)", fm, re.MULTILINE)
+		check(name_match is not None and name_match.group(1) == agent.stem, f"{rel}: frontmatter name must be {agent.stem!r}")
+		check(re.search(r"^description:", fm, re.MULTILINE) is not None, f"{rel}: needs description")
+		check(re.search(r"^model:\s*\S", fm, re.MULTILINE) is not None, f"{rel}: needs an explicit model")
+		check(re.search(r"^tools:\s*\S", fm, re.MULTILINE) is not None, f"{rel}: needs an explicit tools allowlist")
+
+	# 5a-routing. The routing region is what makes the economical tier
+	# configurable per machine. Rendering must be total (every harness gets a
+	# stanza), deterministic (or a second install would not report "unchanged"),
+	# and cheaper than the multi-harness prose it replaced.
+	prefs_body = installer.payload_body(ROOT)
+	for marker in (installer.ROUTING_OPEN, installer.ROUTING_CLOSE):
+		check(prefs_body.count(marker) == 1, f"rules/preferences.md: expected exactly one {marker}")
+	check(
+		prefs_body.find(installer.ROUTING_OPEN) < prefs_body.find(installer.ROUTING_CLOSE),
+		"rules/preferences.md: the routing region's closer precedes its opener",
+	)
+	for harness in installer.HARNESSES:
+		rendered = installer.payload_body(ROOT, harness, {})
+		check(bool(installer.routing.stanza(harness, {}).strip()), f"routing: {harness} renders an empty stanza")
+		check(
+			installer.ROUTING_OPEN not in rendered and installer.ROUTING_CLOSE not in rendered,
+			f"routing: {harness}'s rendered payload still carries the region markers",
+		)
+		check(
+			rendered == installer.payload_body(ROOT, harness, {}),
+			f"routing: rendering {harness} twice is not byte-identical",
+		)
+		check(
+			len(rendered.encode("utf-8")) < len(prefs_body.encode("utf-8")),
+			f"routing: {harness}'s rendered payload is not smaller than the unrendered file",
+		)
+	# The rule is only ever installed when cursor routing is configured, so the
+	# provenance requirement is checked on a configured render.
+	configured_cursor = {"cursor": {"runner": {"model": "example-model", "effort": None}}}
+	check(
+		installer.PROVENANCE in installer.cursor_routing_rule("cursor", configured_cursor),
+		f"routing: the Cursor rule must contain {installer.PROVENANCE!r} so the installer recognises its own copy",
+	)
+
+	# 5c. Plugin-root references. Skill and command text points at plugin files
+	# through the <plugin-root> placeholder, and the OpenCode installer bakes the
+	# absolute root into its copies — so every referenced path must actually
+	# exist, or an install ships a command that can only fail.
+	for base in ("skills", "skills-claude", "commands", "commands-claude"):
+		for doc in sorted((ROOT / base).rglob("*.md")):
+			text = doc.read_text(encoding="utf-8")
+			for ref in sorted({r.rstrip(".") for r in re.findall(r"<plugin-root>/([\w./-]+)", text)}):
+				check((ROOT / ref).exists(), f"{doc.relative_to(ROOT)}: <plugin-root>/{ref} does not exist")
+
+	# The OpenCode copy of the install skill is renamed to leo-install by a
+	# targeted regex in the installer; if the source name ever changes, that
+	# regex would silently no-op and ship a dir/name mismatch.
+	install_fm = (ROOT / "skills" / "install" / "SKILL.md").read_text(encoding="utf-8").split("---", 2)[1]
+	check(
+		re.search(r"(?m)^name:\s*install\s*$", install_fm) is not None,
+		"skills/install/SKILL.md: frontmatter name must stay 'install' — leo-install.py's OpenCode rename keys on it",
+	)
+
 	# 5b. Invocation split: a skill is either user-invoked (and hidden from the
 	# model's always-loaded skill listing) or deliberately model-invocable. Claude
 	# reads the SKILL.md flag; Codex reads the sibling agents/openai.yaml policy.

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}")