From f967288066af59fc27f7971047c92f6cc4c92fed Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Wed, 5 Aug 2026 00:53:16 -0400
Subject: [PATCH 1/9] fix(harness): show candidate diff before approval

---
 static/harness.html                    |  8 ++++++--
 tests/test_harness_console_contract.py | 12 ++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/static/harness.html b/static/harness.html
index a4992ac0..f2da8417 100644
--- a/static/harness.html
+++ b/static/harness.html
@@ -423,8 +423,12 @@
     ['pull request', rec.pr_url || '—'],
     ['error', rec.error || '—'],
   ], ['field', 'value']));
-  if (rec.status === 'pending_decision')
-    sys('awaiting your decision — /agent approve ' + rec.run_id + '   or   /agent reject ' + rec.run_id);
+  if (rec.status === 'pending_decision' && rec.diff) {
+    sys('candidate diff\n' + rec.diff);
+    sys('diff shown above — /agent approve ' + rec.run_id + '   or   /agent reject ' + rec.run_id);
+  } else if (rec.status === 'pending_decision') {
+    sys('diff not loaded — inspect with /agent status ' + rec.run_id + ' before deciding');
+  }
   // Each escalation past approve is its own decision, so the console offers
   // the next one rather than performing it. Both are disarmed on a shipped
   // checkout (allow_git_write_tools / EXECUTION_ENABLED) — the prompt is the
diff --git a/tests/test_harness_console_contract.py b/tests/test_harness_console_contract.py
index 95a71e35..0cbc94b6 100644
--- a/tests/test_harness_console_contract.py
+++ b/tests/test_harness_console_contract.py
@@ -196,3 +196,15 @@ def test_session_id_is_url_encoded_on_every_interpolated_path():
         "static/harness.html interpolates a session id into a URL without "
         f"encodeURIComponent(): {sorted(set(interpolations))}"
     )
+
+
+def test_pending_agent_diff_is_shown_before_approval():
+    """The browser's human gate must display the backend-rendered diff first."""
+    html = _HARNESS_HTML.read_text(encoding="utf-8")
+    start = html.index("function showAgentRecord(rec)")
+    end = html.index("/* ── slash commands ── */", start)
+    body = html[start:end]
+
+    assert "'candidate diff\\n' + rec.diff" in body
+    assert body.index("rec.diff") < body.index("/agent approve ")
+    assert "diff not loaded — inspect with /agent status " in body

From f9402c3e5f90d3a65c086576a265329985551ced Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Wed, 5 Aug 2026 01:55:19 -0400
Subject: [PATCH 2/9] feat(harness): stage reviewed browser agent inputs

---
 docs/HARNESS_POWERSHELL.md             |  19 +++--
 harness/schemas.py                     |  30 ++++++-
 harness/server.py                      |   2 +
 static/harness.html                    | 106 ++++++++++++++++++++++---
 tests/test_harness_agent_routes.py     |  37 ++++++++-
 tests/test_harness_console_contract.py |  23 ++++++
 tests/test_ops_runner.py               |  42 +++++++++-
 utils/ops_runner.py                    |  36 +++++++--
 8 files changed, 264 insertions(+), 31 deletions(-)

diff --git a/docs/HARNESS_POWERSHELL.md b/docs/HARNESS_POWERSHELL.md
index 3291bd86..be39f146 100644
--- a/docs/HARNESS_POWERSHELL.md
+++ b/docs/HARNESS_POWERSHELL.md
@@ -83,9 +83,11 @@ Slash commands (type `/help` in the console):
 | `/model [use <name>]` | show / select the local model |
 | `/skills`, `/tools`, `/connectors` | merged registry views |
 | `/github` | agentic GitHub status (read-only subprocess) |
-| `/agent run\|confirm\|cancel` | stage, authorize, or discard a real-repo coding run |
+| `/agent run\|plan\|read\|confirm\|cancel` | stage, refine, authorize, or discard a real-repo coding run |
 | `/agent status\|approve\|reject <id>` | read a run record, or decide a pending one |
-| `/agent checks` | list the selectable verification profiles |
+| `/agent plan [clear]` | load or clear a reviewed local `.md` / `.txt` plan for the staged run |
+| `/agent read <repo-relative-path>` | declare an existing cloned-repo file for coder context (`clear` removes all) |
+| `/agent checks [profile ...]` | list or choose allow-listed verification profiles for the staged run |
 | `/harness` | harness optimizer runs |
 | `/tokens` | per-session token tally |
 | `/status` | server status |
@@ -112,15 +114,20 @@ worth knowing before you treat either as an off switch:
 
 1. `/agent run claude/<topic> <what the agent should do>` stages a proposal and
    prints it. Nothing is sent.
-2. `/agent confirm <reason>` authorizes it. This is the request that clones the
+2. Optionally, `/agent plan` opens the browser's native picker for a reviewed
+   local plan. The console retains only the selected text, never a server-side
+   path; reselect the file after editing it. `/agent read <repo-relative-path>`
+   declares existing clone content the coder may see, and `/agent checks pytest ruff`
+   replaces the default profile list. These values stay staged until confirmation.
+3. `/agent confirm <reason>` authorizes it. This is the request that clones the
    repo, asks the local model for a patch, and runs the selected verification
    profile against the result. **It blocks for up to 15 minutes** — the run
    record is written only when the run ends, so there is no intermediate
    progress to poll for, and the run id first exists in that response.
-3. On success the run stops *before committing* and reports
+4. On success the run stops *before committing* and reports
    `status: pending_decision`. `/agent approve <id>` is what actually commits;
    `/agent reject <id>` discards the clone. Neither pushes.
-4. Escalating past the local commit is two further, separate decisions —
+5. Escalating past the local commit is two further, separate decisions —
    deliberately not folded into approve, and each its own route:
    `/agent push <id>` puts the branch on origin, and
    `/agent publish <id> <why>` opens a draft PR. **Both refuse on a shipped
@@ -128,7 +135,7 @@ worth knowing before you treat either as an off switch:
    `false`) and publish needs `agentic/writer.py`'s `EXECUTION_ENABLED`, a
    hardcoded `False` no config file can flip. Arming either is the filed
    checklist in `docs/agentic/GITHUB_WRITE_ENABLEMENT.md`, not a toggle.
-5. `/agent discard <id>` reclaims the clone. It is the only step that frees
+6. `/agent discard <id>` reclaims the clone. It is the only step that frees
    disk: an approved run keeps its clone on purpose (push and publish still
    need it) and nothing reclaims it automatically, so a console session that
    only ever approves accumulates one full repository clone per run.
diff --git a/harness/schemas.py b/harness/schemas.py
index 01f54bb8..f09007bf 100644
--- a/harness/schemas.py
+++ b/harness/schemas.py
@@ -9,7 +9,7 @@
 
 from typing import Literal
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 from harness.agent_policy import BRANCH_NAME_RE, DEFAULT_CHECK_PROFILE
 
@@ -21,6 +21,12 @@
 _MAX_COMMIT_MESSAGE_LEN = 500
 _MAX_BRANCH_LEN = 88  # longest allowlisted prefix + '/' + topic (1+79)
 _MAX_CHECK_PROFILES = 8
+_MAX_READ_FILES = 8
+_MAX_READ_FILE_LEN = 1024
+# The agentic planner caps its generated body at 6,000 characters, then adds a
+# fixed truncation marker. Keep enough room for that legitimate reviewed output
+# without turning the browser request into an unbounded prompt transport.
+_MAX_PLAN_CHARS = 6_100
 _MAX_ITERATIONS_CEILING = 10
 
 
@@ -81,6 +87,13 @@ class AgentRunRequest(_ForbidModel):
         min_length=1,
         max_length=_MAX_CHECK_PROFILES,
     )
+    # Browser clients supply plan TEXT selected from their own filesystem, not
+    # a server-side path. The shim materializes that text briefly for the CLI's
+    # existing --plan-file scanner and deletes it on every exit path.
+    plan: str | None = Field(default=None, min_length=1, max_length=_MAX_PLAN_CHARS)
+    # This is a declared list, never a browse/read API: the CLI resolves each
+    # path only inside the fresh jailed clone before showing it to the coder.
+    read_files: list[str] = Field(default_factory=list, max_length=_MAX_READ_FILES)
     # ge=1 rather than gt=0 so 0 is a validation error, not a silently-dropped
     # value: run_agentic_op gates --max-iterations on truthiness, so 0 would
     # fall through to the CLI default of 3 rather than doing what it says.
@@ -101,6 +114,21 @@ def _one_target_only(self) -> AgentRunRequest:
             raise ValueError("pass at most one of pr / issue")
         return self
 
+    @field_validator("plan")
+    @classmethod
+    def _plan_is_not_blank(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise ValueError("plan must not be blank")
+        return value
+
+    @field_validator("read_files")
+    @classmethod
+    def _read_files_are_bounded_text(cls, values: list[str]) -> list[str]:
+        for path in values:
+            if not path or len(path) > _MAX_READ_FILE_LEN or "\x00" in path:
+                raise ValueError("read_files must contain non-empty bounded paths without NUL bytes")
+        return values
+
 
 class AgentDecisionRequest(_ForbidModel):
     """Approve (commit) or reject (discard) one pending run.
diff --git a/harness/server.py b/harness/server.py
index 2facf7f9..b3622c6d 100644
--- a/harness/server.py
+++ b/harness/server.py
@@ -724,6 +724,8 @@ def agent_run(req: AgentRunRequest) -> dict:
                 reason=req.reason,
                 confirm=req.confirm,
                 max_iterations=req.max_iterations,
+                plan=req.plan,
+                read_files=req.read_files,
                 pr=req.pr,
                 issue=req.issue,
             ),
diff --git a/static/harness.html b/static/harness.html
index f2da8417..067bfc90 100644
--- a/static/harness.html
+++ b/static/harness.html
@@ -197,6 +197,7 @@
       </div>
     </div>
   </div>
+  <input id="agentPlanFile" type="file" accept=".md,.txt,text/markdown,text/plain" hidden>
 
 <script>
 'use strict';
@@ -204,6 +205,9 @@
    through textContent or the table() builder (createElement + textContent). */
 const $ = id => document.getElementById(id);
 const stream = $('stream'), input = $('input'), sendBtn = $('send'), apiKeyInput = $('apiKey');
+const agentPlanInput = $('agentPlanFile');
+const MAX_AGENT_PLAN_CHARS = 6100;
+const MAX_AGENT_PLAN_BYTES = 25000;
 /* Substituted server-side into the meta tag at serve time (harness/server.py's
    console() route) -- the literal placeholder below never reaches a browser. */
 const csrfMeta = document.querySelector('meta[name="csrf-token"]');
@@ -366,9 +370,8 @@
   ['/tools', 'tool registry'],
   ['/connectors', 'connector catalog'],
   ['/github', 'agentic GitHub status'],
-  ['/agent run|confirm|cancel', 'stage and start a real-repo coding run'],
+  ['/agent run|plan|read|checks|confirm|cancel', 'stage and start a real-repo coding run'],
   ['/agent status|approve|reject <id>', 'inspect or decide a pending run'],
-  ['/agent checks', 'available verification profiles'],
   ['/harness', 'harness optimizer runs'],
   ['/tokens', 'token tally'],
   ['/status', 'server status'],
@@ -410,6 +413,47 @@
   }
   return r.parsed;
 }
+function showPendingAgentRun() {
+  if (!pendingAgentRun) return;
+  sys(table([
+    ['branch', pendingAgentRun.branch],
+    ['instruction', pendingAgentRun.instruction],
+    ['commit message', pendingAgentRun.commit_message],
+    ['plan', pendingAgentRun.plan ? 'loaded (' + pendingAgentRun.plan.length + ' chars)' : 'none'],
+    ['read files', pendingAgentRun.read_files.join(', ') || 'none'],
+    ['checks', pendingAgentRun.checks.join(', ')],
+  ], ['field', 'value']));
+}
+
+agentPlanInput.addEventListener('change', () => {
+  const file = agentPlanInput.files && agentPlanInput.files[0];
+  const stagedRun = pendingAgentRun;
+  agentPlanInput.value = '';
+  if (!file || !stagedRun) return;
+  if (file.size > MAX_AGENT_PLAN_BYTES) {
+    sys('plan file is too large; keep reviewed plans below ' + MAX_AGENT_PLAN_CHARS + ' characters');
+    return;
+  }
+  const reader = new FileReader();
+  reader.onerror = () => sys('could not read the selected plan file');
+  reader.onload = () => {
+    if (pendingAgentRun !== stagedRun) {
+      sys('staged run changed before the plan loaded; select it again for the current run');
+      return;
+    }
+    const plan = typeof reader.result === 'string' ? reader.result : '';
+    if (!plan.trim()) { sys('plan file is empty'); return; }
+    if (plan.length > MAX_AGENT_PLAN_CHARS) {
+      sys('plan is too long; keep reviewed plans below ' + MAX_AGENT_PLAN_CHARS + ' characters');
+      return;
+    }
+    pendingAgentRun.plan = plan;
+    sys('reviewed plan loaded; reselect it after any local edit.\n' + plan);
+    showPendingAgentRun();
+  };
+  reader.readAsText(file);
+});
+
 function showAgentRecord(rec) {
   sys(table([
     ['run id', rec.run_id],
@@ -537,7 +581,21 @@
         const sub = rest[0] || 'help';
         if (sub === 'checks') {
           const r = await api('/api/agent/checks');
-          sys(table(r.profiles.map(p => [p.name, p.description]), ['profile', 'what it runs']));
+          if (rest.length === 1) {
+            sys(table(r.profiles.map(p => [p.name, p.description]), ['profile', 'what it runs']));
+          } else if (!pendingAgentRun) {
+            sys('nothing staged — start with /agent run before selecting checks');
+          } else {
+            const requested = rest.slice(1).join(' ').split(/[\s,]+/).filter(Boolean);
+            const available = new Set(r.profiles.map(p => p.name));
+            const unknown = requested.filter(name => !available.has(name));
+            if (unknown.length) {
+              sys('unknown profile(s): ' + unknown.join(', ') + '; run /agent checks to list valid names');
+            } else {
+              pendingAgentRun.checks = requested;
+              showPendingAgentRun();
+            }
+          }
         } else if (sub === 'run') {
           const branch = rest[1] || '';
           const instruction = rest.slice(2).join(' ').trim();
@@ -550,14 +608,37 @@
             instruction: instruction,
             commit_message: instruction.slice(0, 72),
             checks: ['pytest'],
+            plan: null,
+            read_files: [],
           };
-          sys(table([
-            ['branch', pendingAgentRun.branch],
-            ['instruction', pendingAgentRun.instruction],
-            ['commit message', pendingAgentRun.commit_message],
-            ['checks', pendingAgentRun.checks.join(', ')],
-          ], ['field', 'value']));
-          sys('nothing has run yet. Authorize with:  /agent confirm <why you are doing this>');
+          showPendingAgentRun();
+          sys('nothing has run yet. Optionally use /agent plan, /agent read, or /agent checks <profile ...>; then authorize with:  /agent confirm <why you are doing this>');
+        } else if (sub === 'plan') {
+          if (!pendingAgentRun) { sys('nothing staged — start with /agent run'); break; }
+          if (rest[1] === 'clear' && rest.length === 2) {
+            pendingAgentRun.plan = null;
+            sys('staged plan cleared');
+            showPendingAgentRun();
+          } else if (rest.length > 1) {
+            sys('usage: /agent plan  (or /agent plan clear)');
+          } else {
+            agentPlanInput.click();
+          }
+        } else if (sub === 'read') {
+          if (!pendingAgentRun) { sys('nothing staged — start with /agent run'); break; }
+          const path = rest.slice(1).join(' ').trim();
+          if (path === 'clear') {
+            pendingAgentRun.read_files = [];
+            sys('declared read files cleared');
+          } else if (!path) {
+            sys('usage: /agent read <repo-relative-path>  (or /agent read clear)');
+          } else if (pendingAgentRun.read_files.includes(path)) {
+            sys('read path is already declared: ' + path);
+          } else {
+            pendingAgentRun.read_files.push(path);
+            sys('declared read path: ' + path);
+          }
+          showPendingAgentRun();
         } else if (sub === 'cancel') {
           pendingAgentRun = null;
           sys('staged run discarded');
@@ -607,6 +688,10 @@
         } else {
           sys(table([
             ['/agent run claude/<topic> <task>', 'stage a run (sends nothing)'],
+            ['/agent plan [clear]', 'load or clear a reviewed local plan for the staged run'],
+            ['/agent read <repo-relative-path>', 'declare an existing file for the staged coder context'],
+            ['/agent read clear', 'clear declared read paths'],
+            ['/agent checks [profile ...]', 'list or choose allow-listed verification profiles'],
             ['/agent confirm <reason>', 'authorize and start the staged run'],
             ['/agent cancel', 'discard the staged run'],
             ['/agent status <run id>', 'read a run record'],
@@ -615,7 +700,6 @@
             ['/agent push <run id>', 'push an approved branch to origin (disarmed by default)'],
             ['/agent publish <run id> <why>', 'open a draft PR for a pushed run (disarmed by default)'],
             ['/agent discard <run id>', 'reclaim the clone of a decided run from disk'],
-            ['/agent checks', 'list verification profiles'],
           ], ['command', 'action']));
         }
         break;
diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index 68037038..0cad5c6c 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -40,6 +40,7 @@
 )
 from harness.config import HarnessConfig
 from harness.ollama import HarnessChatClient
+from harness.schemas import _MAX_PLAN_CHARS as HARNESS_MAX_PLAN_CHARS
 from utils.ops_runner import OpsError, run_agentic_op
 
 _KEY = "harness-agent-test-key"
@@ -135,6 +136,20 @@ def test_duplicated_constants_match_their_agentic_originals():
     assert BRANCH_NAME_RE.pattern == producer_branch.pattern
 
 
+def test_harness_plan_limit_holds_a_truncated_agentic_plan():
+    """A plan emitted by the CLI must fit through the browser handoff path.
+
+    Harness cannot import agentic at runtime (I6), so the intentional duplicate
+    is checked here. ``generate_plan`` appends its fixed marker after the 6k
+    body limit, which is why equality would reject a valid generated plan.
+    """
+    from agentic.real_repo_loop import _MAX_PLAN_CHARS as agentic_plan_chars
+    from harness.schemas import _MAX_PLAN_CHARS as harness_plan_chars
+
+    marker = f"\n... [plan truncated at {agentic_plan_chars} chars]"
+    assert harness_plan_chars >= agentic_plan_chars + len(marker)
+
+
 def test_check_profile_argv_matches_the_executors_own_commands():
     """pytest/ruff are a verbatim copy of two of agentic.executor's defaults.
 
@@ -234,21 +249,39 @@ def test_checks_listing_is_open_and_lists_every_profile(cfg, calls):
 
 
 def test_run_forwards_the_resolved_profile_not_the_name(client, calls):
-    resp = client.post(_RUN, json=_VALID_BODY)
+    plan = "Review the parser change before testing it."
+    read_files = ["src/parser.py", "tests/test_parser.py"]
+    resp = client.post(_RUN, json={
+        **_VALID_BODY, "checks": ["pytest", "ruff"], "plan": plan, "read_files": read_files,
+    })
     assert resp.status_code == 200
     action, kwargs = calls[0]
     assert action == "real-repo-run"
-    assert kwargs["checks"] == [{"name": "pytest", "argv": resolve_check_profiles(["pytest"])[0]["argv"]}]
+    assert kwargs["checks"] == resolve_check_profiles(["pytest", "ruff"])
     assert kwargs["instruction"] == _VALID_BODY["instruction"]
     assert kwargs["branch"] == _VALID_BODY["branch"]
     assert kwargs["commit_message"] == _VALID_BODY["commit_message"]
     assert kwargs["reason"] == _VALID_BODY["reason"]
     assert kwargs["confirm"] is True
+    assert kwargs["plan"] == plan
+    assert kwargs["read_files"] == read_files
 
 
 def test_run_defaults_to_the_default_profile_when_checks_is_omitted(client, calls):
     client.post(_RUN, json=_VALID_BODY)
     assert [c["name"] for c in calls[0][1]["checks"]] == [DEFAULT_CHECK_PROFILE]
+    assert calls[0][1]["plan"] is None
+    assert calls[0][1]["read_files"] == []
+
+
+@pytest.mark.parametrize("body", [
+    {"plan": "x" * (HARNESS_MAX_PLAN_CHARS + 1)},
+    {"read_files": ["file.py"] * 9},
+    {"read_files": ["safe.py\x00not-safe.py"]},
+])
+def test_run_rejects_invalid_browser_plan_or_read_paths_before_the_shim(client, calls, body):
+    assert client.post(_RUN, json={**_VALID_BODY, **body}).status_code == 422
+    assert calls == []
 
 
 def test_confirm_is_not_defaulted_on(client, calls):
diff --git a/tests/test_harness_console_contract.py b/tests/test_harness_console_contract.py
index 0cbc94b6..9968be51 100644
--- a/tests/test_harness_console_contract.py
+++ b/tests/test_harness_console_contract.py
@@ -208,3 +208,26 @@ def test_pending_agent_diff_is_shown_before_approval():
     assert "'candidate diff\\n' + rec.diff" in body
     assert body.index("rec.diff") < body.index("/agent approve ")
     assert "diff not loaded — inspect with /agent status " in body
+
+
+def test_staged_agent_plan_read_paths_and_checks_reach_confirmation():
+    """The console must not silently drop the reviewed values it displays."""
+    from harness.schemas import _MAX_PLAN_CHARS
+
+    html = _HARNESS_HTML.read_text(encoding="utf-8")
+    helper_start = html.index("function showPendingAgentRun()")
+    helper_end = html.index("function showAgentRecord(rec)", helper_start)
+    helper = html[helper_start:helper_end]
+
+    assert "agentPlanInput.addEventListener('change'" in helper
+    assert f"const MAX_AGENT_PLAN_CHARS = {_MAX_PLAN_CHARS};" in html
+    assert "pendingAgentRun.plan = plan" in helper
+    assert "pendingAgentRun !== stagedRun" in helper
+
+    commands_start = html.index("case 'agent':")
+    commands_end = html.index("case 'harness':", commands_start)
+    commands = html[commands_start:commands_end]
+    assert "read_files: []" in commands
+    assert "pendingAgentRun.read_files.push(path)" in commands
+    assert "pendingAgentRun.checks = requested" in commands
+    assert "Object.assign({}, pendingAgentRun, { reason: why, confirm: true })" in commands
diff --git a/tests/test_ops_runner.py b/tests/test_ops_runner.py
index 5e34b4d0..eb91c682 100644
--- a/tests/test_ops_runner.py
+++ b/tests/test_ops_runner.py
@@ -335,15 +335,42 @@ def test_real_repo_run_requires_its_fields(kwargs, match) -> None:
         run_agentic_op("real-repo-run", **kwargs)
 
 
-def test_real_repo_run_argv_shape_and_checks_file_cleanup(monkeypatch: pytest.MonkeyPatch) -> None:
+@pytest.mark.parametrize(
+    ("optional", "match"),
+    [
+        ({"plan": "   "}, "plan"),
+        ({"read_files": ["safe.py\x00not-safe.py"]}, "read_files"),
+        ({"read_files": "safe.py"}, "read_files"),
+    ],
+)
+def test_real_repo_run_rejects_invalid_optional_browser_values(optional, match) -> None:
+    with pytest.raises(OpsError, match=match):
+        run_agentic_op(
+            "real-repo-run", instruction="x", checks=[{"name": "x", "argv": ["y"]}],
+            branch="agent/x", commit_message="m", reason="r", **optional,
+        )
+
+
+def test_real_repo_run_argv_shape_and_temp_file_cleanup(monkeypatch: pytest.MonkeyPatch) -> None:
     from pathlib import Path
 
-    runner, captured = _fake_run(returncode=0, stdout='{"status": "pending_decision"}')
+    captured: list[list[str]] = []
+    captured_plan: list[str] = []
+
+    def runner(argv, *, timeout_sec=None):
+        del timeout_sec
+        captured.append(argv)
+        plan_path = Path(argv[argv.index("--plan-file") + 1])
+        captured_plan.append(plan_path.read_text(encoding="utf-8"))
+        return subprocess.CompletedProcess(args=argv, returncode=0, stdout='{"status": "pending_decision"}', stderr="")
+
     monkeypatch.setattr(ops_runner, "_run", runner)
     checks = [{"name": "pytest", "argv": ["python", "-m", "pytest"]}]
+    plan = "Review this candidate before applying it."
     res = run_agentic_op(
         "real-repo-run", instruction="add a marker", checks=checks, branch="agent/topic",
         commit_message="add marker", reason="test run", confirm=True, max_iterations=5,
+        plan=plan, read_files=["src/marker.py", "tests/test_marker.py"],
     )
     argv = captured[0]
     assert "--repo" in argv  # default target when pr/issue omitted
@@ -356,7 +383,12 @@ def test_real_repo_run_argv_shape_and_checks_file_cleanup(monkeypatch: pytest.Mo
 
     assert "--checks-file" in argv
     checks_path = argv[argv.index("--checks-file") + 1]
+    plan_path = argv[argv.index("--plan-file") + 1]
     assert not Path(checks_path).exists()  # cleaned up after the run
+    assert captured_plan == [plan]
+    assert not Path(plan_path).exists()  # the reviewed plan is not retained by the shim
+    assert "--read-file=src/marker.py" in argv
+    assert "--read-file=tests/test_marker.py" in argv
     assert res.parsed == {"status": "pending_decision"}
 
 
@@ -472,7 +504,7 @@ def _boom(_path):
     assert ops_runner._real_repo_run_timeout_sec(1, 1) > 0  # noqa: SLF001
 
 
-def test_real_repo_run_checks_file_cleaned_up_when_run_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_real_repo_run_temp_files_are_cleaned_up_when_run_raises(monkeypatch: pytest.MonkeyPatch) -> None:
     from pathlib import Path
 
     captured_argv: list[list[str]] = []
@@ -485,11 +517,13 @@ def raising_run(argv, *, timeout_sec=None):
     with pytest.raises(subprocess.TimeoutExpired):
         run_agentic_op(
             "real-repo-run", instruction="x", checks=[{"name": "x", "argv": ["y"]}],
-            branch="agent/x", commit_message="m", reason="r",
+            branch="agent/x", commit_message="m", reason="r", plan="reviewed plan",
         )
     argv = captured_argv[0]
     checks_path = argv[argv.index("--checks-file") + 1]
+    plan_path = argv[argv.index("--plan-file") + 1]
     assert not Path(checks_path).exists()
+    assert not Path(plan_path).exists()
 
 
 def test_real_repo_run_status_requires_run_id() -> None:
diff --git a/utils/ops_runner.py b/utils/ops_runner.py
index 12346d02..a5dbed54 100644
--- a/utils/ops_runner.py
+++ b/utils/ops_runner.py
@@ -253,17 +253,17 @@ def _maybe_json(text: str) -> Any:
         return None
 
 
-def _write_body(body: str) -> str:
-    """Persist a skill body to a temp file so it is passed via --body-file, never argv."""
+def _write_body(body: str, *, prefix: str = "cyclaw_skill_") -> str:
+    """Persist caller-supplied text to a temporary file, never an argv value."""
     handle = tempfile.NamedTemporaryFile(
-        mode="w", suffix=".md", prefix="cyclaw_skill_", delete=False, encoding="utf-8"
+        mode="w", suffix=".md", prefix=prefix, delete=False, encoding="utf-8"
     )
     try:
         handle.write(body)
     except (OSError, UnicodeError):
         # The file already exists on disk; run_agentic_op only unlinks the name
         # we RETURN, so a write failure here (disk full, un-encodable body) would
-        # orphan a cyclaw_skill_*.md. Close first (Windows can't unlink an open
+        # orphan a cyclaw_*.md. Close first (Windows can't unlink an open
         # file), then remove it, before the exception propagates.
         handle.close()
         Path(handle.name).unlink(missing_ok=True)
@@ -329,6 +329,8 @@ def run_agentic_op(
     confirm: bool = False,
     instruction: str | None = None,
     checks: list[dict] | None = None,
+    plan: str | None = None,
+    read_files: list[str] | None = None,
     branch: str | None = None,
     commit_message: str | None = None,
     max_iterations: int | None = None,
@@ -353,7 +355,11 @@ def run_agentic_op(
     via ``--checks-file`` (never interpolated into argv, mirroring
     ``body``/``--body-file`` above) — never defaulted, since guessing a
     verification command for an arbitrary configured repo is exactly what
-    this whole path exists to avoid. ``real-repo-run-status``/
+    this whole path exists to avoid. An optional browser-supplied ``plan`` is
+    materialized into a temporary ``--plan-file`` so the CLI retains ownership
+    of plan scanning and hashing; ``read_files`` travel as repeatable
+    ``--read-file=<path>`` arguments and are resolved only inside the clone.
+    ``real-repo-run-status``/
     ``real-repo-run-decide`` require ``run_id``; ``decide`` additionally
     requires ``decision`` (``"approve"`` or ``"reject"``), validated here
     before the subprocess launch even though the CLI's own ``argparse``
@@ -379,8 +385,9 @@ def run_agentic_op(
     Validation raises happen before the subprocess launch. All ``proc`` usage
     lives INSIDE the try so there is no post-``finally`` reference to an unbound
     name: if ``_run`` raises (e.g. ``subprocess.TimeoutExpired``), the ``finally``
-    cleans up the temp body-file/checks-file and the exception propagates before
-    any result is read. Both are unlinked on every exit path (return or raise).
+    cleans up the temp body-file/checks-file/plan-file and the exception
+    propagates before any result is read. All are unlinked on every exit path
+    (return or raise).
     """
     if action not in _AGENTIC_ACTIONS:
         raise OpsError(f"Unknown agentic action: {action!r}")
@@ -397,6 +404,13 @@ def run_agentic_op(
             raise OpsError("real-repo-run requires both branch and commit_message")
         if not (reason and reason.strip()):
             raise OpsError("real-repo-run requires a non-empty reason")
+        if plan is not None and (not isinstance(plan, str) or not plan.strip()):
+            raise OpsError("real-repo-run plan must not be blank")
+        if read_files is not None and (
+            not isinstance(read_files, list)
+            or any(not isinstance(path, str) or not path or "\x00" in path for path in read_files)
+        ):
+            raise OpsError("real-repo-run read_files must contain non-empty paths without NUL bytes")
     if action in {
         "real-repo-run-status", "real-repo-run-decide", "real-repo-run-push", "real-repo-run-publish",
         "real-repo-run-discard",
@@ -413,6 +427,7 @@ def run_agentic_op(
     argv = [sys.executable, "-m", "agentic.cli", "--config", str(_CONFIG_PATH), action]
     body_file: str | None = None
     checks_file: str | None = None
+    plan_file: str | None = None
     try:
         if action == "context":
             if pr is not None:
@@ -453,6 +468,11 @@ def run_agentic_op(
                 f"--commit-message={commit_message}",
                 f"--reason={reason}",
             ]
+            if plan:
+                plan_file = _write_body(plan, prefix="cyclaw_plan_")
+                argv += ["--plan-file", plan_file]
+            for read_file in read_files or ():
+                argv.append(f"--read-file={read_file}")
             if max_iterations:
                 argv += ["--max-iterations", str(max_iterations)]
             if confirm:
@@ -491,6 +511,8 @@ def run_agentic_op(
             Path(body_file).unlink(missing_ok=True)
         if checks_file:
             Path(checks_file).unlink(missing_ok=True)
+        if plan_file:
+            Path(plan_file).unlink(missing_ok=True)
 
 
 def run_fsconnect_op(

From 5afcd148792c100349893be133950a1b78d6a142 Mon Sep 17 00:00:00 2001
From: Chris Grady <17553614+cgfixit@users.noreply.github.com>
Date: Wed, 5 Aug 2026 19:38:07 -0400
Subject: [PATCH 3/9] Update schemas.py

---
 harness/schemas.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/harness/schemas.py b/harness/schemas.py
index f09007bf..efc74568 100644
--- a/harness/schemas.py
+++ b/harness/schemas.py
@@ -117,17 +117,17 @@ def _one_target_only(self) -> AgentRunRequest:
     @field_validator("plan")
     @classmethod
     def _plan_is_not_blank(cls, value: str | None) -> str | None:
-        if value is not None and not value.strip():
+        if plan_text is not None and not value.strip():
             raise ValueError("plan must not be blank")
-        return value
+        return plan_text
 
     @field_validator("read_files")
     @classmethod
     def _read_files_are_bounded_text(cls, values: list[str]) -> list[str]:
-        for path in values:
+        for path in read_paths:
             if not path or len(path) > _MAX_READ_FILE_LEN or "\x00" in path:
                 raise ValueError("read_files must contain non-empty bounded paths without NUL bytes")
-        return values
+        return read_paths
 
 
 class AgentDecisionRequest(_ForbidModel):

From 5ed2c27f3d4f8f8c863bfc06d39947aad5e1a284 Mon Sep 17 00:00:00 2001
From: Chris Grady <17553614+cgfixit@users.noreply.github.com>
Date: Wed, 5 Aug 2026 19:40:27 -0400
Subject: [PATCH 4/9] Update test_harness_agent_routes.py

---
 tests/test_harness_agent_routes.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index 0cad5c6c..f539a369 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -137,7 +137,7 @@ def test_duplicated_constants_match_their_agentic_originals():
 
 
 def test_harness_plan_limit_holds_a_truncated_agentic_plan():
-    """A plan emitted by the CLI must fit through the browser handoff path.
+    # A plan emitted by the CLI must fit through the browser handoff path.
 
     Harness cannot import agentic at runtime (I6), so the intentional duplicate
     is checked here. ``generate_plan`` appends its fixed marker after the 6k

From 28cdc8435c51dbd0c1eb01873cfc0950813e29e8 Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Wed, 5 Aug 2026 23:52:40 +0000
Subject: [PATCH 5/9] fix(harness): jail-align read_files, cap staging, keep
 staged run on confirm fail

Codex P2s on #803: reject non-repo-relative read paths at the control plane
(utils.repo_paths, same rules as agentic canonical_repo_path), enforce the 8
path cap in the console before confirm, and preserve pendingAgentRun when
/agent confirm gets a 422 so plan/instruction/checks are not wiped.

Also rename plan/read validators (WPS110) and move plan/read ops_runner prose
out of the function docstring into comments (CLAUDE.md convention). Drift test
keeps utils and agentic path acceptance in lockstep without harness importing
agentic (I6).
---
 harness/schemas.py                     | 35 ++++++++++++++----
 static/harness.html                    | 49 ++++++++++++++++++++++----
 tests/test_harness_agent_routes.py     | 42 ++++++++++++++++++++++
 tests/test_harness_console_contract.py | 17 ++++++---
 tests/test_ops_runner.py               |  3 ++
 utils/ops_runner.py                    | 23 +++++++-----
 utils/repo_paths.py                    | 44 +++++++++++++++++++++++
 7 files changed, 186 insertions(+), 27 deletions(-)
 create mode 100644 utils/repo_paths.py

diff --git a/harness/schemas.py b/harness/schemas.py
index efc74568..6ffac37b 100644
--- a/harness/schemas.py
+++ b/harness/schemas.py
@@ -12,6 +12,7 @@
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 from harness.agent_policy import BRANCH_NAME_RE, DEFAULT_CHECK_PROFILE
+from utils.repo_paths import canonical_repo_relative_path
 
 _MAX_MESSAGE_LEN = 32768
 _MAX_TITLE_LEN = 200
@@ -116,18 +117,38 @@ def _one_target_only(self) -> AgentRunRequest:
 
     @field_validator("plan")
     @classmethod
-    def _plan_is_not_blank(cls, value: str | None) -> str | None:
-        if plan_text is not None and not value.strip():
+    def _plan_is_not_blank(cls, plan_text: str | None) -> str | None:
+        if plan_text is not None and not plan_text.strip():
             raise ValueError("plan must not be blank")
         return plan_text
 
     @field_validator("read_files")
     @classmethod
-    def _read_files_are_bounded_text(cls, values: list[str]) -> list[str]:
-        for path in read_paths:
-            if not path or len(path) > _MAX_READ_FILE_LEN or "\x00" in path:
-                raise ValueError("read_files must contain non-empty bounded paths without NUL bytes")
-        return read_paths
+    def _read_files_are_safe_repo_relative(cls, read_paths: list[str]) -> list[str]:
+        # Align with the clone jail (utils.repo_paths / agentic canonical_repo_path):
+        # reject absolutes, traversal, drive-qualified, flag-like, and overlong
+        # names here so /agent confirm never 422s after the console staged junk
+        # the jailed reader would only skip later.
+        if len(read_paths) > _MAX_READ_FILES:
+            raise ValueError(f"read_files allows at most {_MAX_READ_FILES} paths")
+        cleaned: list[str] = []
+        seen: set[str] = set()
+        for raw in read_paths:
+            if not isinstance(raw, str) or len(raw) > _MAX_READ_FILE_LEN:
+                raise ValueError(
+                    "read_files must contain non-empty bounded repo-relative paths "
+                    "without NUL bytes, traversal, or absolute/drive forms"
+                )
+            canonical = canonical_repo_relative_path(raw)
+            if canonical is None:
+                raise ValueError(
+                    "read_files must contain non-empty bounded repo-relative paths "
+                    "without NUL bytes, traversal, or absolute/drive forms"
+                )
+            if canonical not in seen:
+                seen.add(canonical)
+                cleaned.append(canonical)
+        return cleaned
 
 
 class AgentDecisionRequest(_ForbidModel):
diff --git a/static/harness.html b/static/harness.html
index 067bfc90..66eb5952 100644
--- a/static/harness.html
+++ b/static/harness.html
@@ -208,6 +208,26 @@
 const agentPlanInput = $('agentPlanFile');
 const MAX_AGENT_PLAN_CHARS = 6100;
 const MAX_AGENT_PLAN_BYTES = 25000;
+/* Mirrors harness.schemas._MAX_READ_FILES and the clone-jail path rules in
+   utils.repo_paths.canonical_repo_relative_path (keep in sync via console contract tests). */
+const MAX_AGENT_READ_FILES = 8;
+const MAX_AGENT_READ_FILE_LEN = 1024;
+function isSafeRepoRelativePath(raw) {
+  if (typeof raw !== 'string' || !raw || raw.length > MAX_AGENT_READ_FILE_LEN || raw.indexOf('\0') !== -1) return false;
+  const normalized = raw.replace(/\\/g, '/');
+  if (normalized.charAt(0) === '/' || normalized.charAt(0) === '-') return false;
+  if (/^[A-Za-z]:/.test(raw) || normalized.indexOf('://') !== -1) return false;
+  const parts = normalized.split('/').filter(part => part !== '' && part !== '.');
+  if (!parts.length) return false;
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '..' || parts[i].indexOf(':') !== -1) return false;
+  }
+  return true;
+}
+function canonicalRepoRelativePath(raw) {
+  if (!isSafeRepoRelativePath(raw)) return null;
+  return raw.replace(/\\/g, '/').split('/').filter(part => part !== '' && part !== '.').join('/');
+}
 /* Substituted server-side into the meta tag at serve time (harness/server.py's
    console() route) -- the literal placeholder below never reaches a browser. */
 const csrfMeta = document.querySelector('meta[name="csrf-token"]');
@@ -632,11 +652,18 @@
             sys('declared read files cleared');
           } else if (!path) {
             sys('usage: /agent read <repo-relative-path>  (or /agent read clear)');
-          } else if (pendingAgentRun.read_files.includes(path)) {
-            sys('read path is already declared: ' + path);
           } else {
-            pendingAgentRun.read_files.push(path);
-            sys('declared read path: ' + path);
+            const canonical = canonicalRepoRelativePath(path);
+            if (!canonical) {
+              sys('refused read path (must be repo-relative: no absolute, .., drive, or flag-like names): ' + path);
+            } else if (pendingAgentRun.read_files.includes(canonical)) {
+              sys('read path is already declared: ' + canonical);
+            } else if (pendingAgentRun.read_files.length >= MAX_AGENT_READ_FILES) {
+              sys('at most ' + MAX_AGENT_READ_FILES + ' read paths can be staged; drop one with /agent read clear or confirm with the current list');
+            } else {
+              pendingAgentRun.read_files.push(canonical);
+              sys('declared read path: ' + canonical);
+            }
           }
           showPendingAgentRun();
         } else if (sub === 'cancel') {
@@ -646,13 +673,23 @@
           if (!pendingAgentRun) { sys('nothing staged — start with /agent run'); break; }
           const why = rest.slice(1).join(' ').trim();
           if (!why) { sys('a reason is required: /agent confirm <why you are doing this>'); break; }
-          const body = Object.assign({}, pendingAgentRun, { reason: why, confirm: true });
-          pendingAgentRun = null;
+          /* Keep the staged proposal until the server accepts the run. Clearing
+             first made a 422 (e.g. over-cap read_files) destroy the instruction,
+             plan, checks, and paths with no recovery short of re-staging. */
+          const stagedRun = pendingAgentRun;
+          const body = Object.assign({}, stagedRun, { reason: why, confirm: true });
           sendBtn.disabled = true;
           sys('cloning, planning, patching and verifying — this blocks for up to 15 minutes…');
           try {
             const rec = agentRecord(await api('/api/agent/run', 'POST', body));
+            if (pendingAgentRun === stagedRun) pendingAgentRun = null;
             if (rec) showAgentRecord(rec);
+          } catch (err) {
+            if (pendingAgentRun === null || pendingAgentRun === stagedRun) {
+              pendingAgentRun = stagedRun;
+            }
+            sys('confirm failed — staged run kept. Fix the request or /agent cancel. (' + err.message + ')');
+            showPendingAgentRun();
           } finally {
             sendBtn.disabled = false;
           }
diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index f539a369..9fb26853 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -278,12 +278,54 @@ def test_run_defaults_to_the_default_profile_when_checks_is_omitted(client, call
     {"plan": "x" * (HARNESS_MAX_PLAN_CHARS + 1)},
     {"read_files": ["file.py"] * 9},
     {"read_files": ["safe.py\x00not-safe.py"]},
+    {"read_files": ["/etc/passwd"]},
+    {"read_files": ["../README.md"]},
+    {"read_files": ["C:\\Windows\\system32\\config"]},
+    {"read_files": ["-evil"]},
+    {"read_files": ["foo/../../etc/passwd"]},
 ])
 def test_run_rejects_invalid_browser_plan_or_read_paths_before_the_shim(client, calls, body):
     assert client.post(_RUN, json={**_VALID_BODY, **body}).status_code == 422
     assert calls == []
 
 
+def test_run_canonicalizes_safe_read_paths_before_the_shim(client, calls):
+    resp = client.post(_RUN, json={
+        **_VALID_BODY,
+        "read_files": ["./src/parser.py", "src//parser.py", "tests/test_parser.py"],
+    })
+    assert resp.status_code == 200
+    assert calls[0][1]["read_files"] == ["src/parser.py", "tests/test_parser.py"]
+
+
+def test_control_plane_path_rules_match_agentic_jail():
+    # I6: harness/utils must not import agentic at runtime; this test is the
+    # deliberate drift check so browser-accepted paths stay jail-acceptable.
+    from agentic.deepagent_github.repo_workspace import canonical_repo_path
+    from utils.repo_paths import canonical_repo_relative_path
+
+    samples = [
+        "src/a.py",
+        "./src/a.py",
+        "src//a.py",
+        r".\conftest.py",
+        "foo/bar/baz.py",
+        "/etc/passwd",
+        "../README.md",
+        "foo/../../etc/passwd",
+        "-flag",
+        "C:\\temp\\x",
+        "safe.py\x00no",
+        "",
+        "foo/bar:baz",
+        "a" * 2000,
+    ]
+    for sample in samples:
+        left = canonical_repo_relative_path(sample)
+        right = canonical_repo_path(sample)
+        assert left == right, (sample, left, right)
+
+
 def test_confirm_is_not_defaulted_on(client, calls):
     """Omitting confirm must reach the CLI's own refusal, not a silent True.
 
diff --git a/tests/test_harness_console_contract.py b/tests/test_harness_console_contract.py
index 9968be51..49b1b7df 100644
--- a/tests/test_harness_console_contract.py
+++ b/tests/test_harness_console_contract.py
@@ -199,7 +199,7 @@ def test_session_id_is_url_encoded_on_every_interpolated_path():
 
 
 def test_pending_agent_diff_is_shown_before_approval():
-    """The browser's human gate must display the backend-rendered diff first."""
+    # The browser human gate must display the backend-rendered diff first.
     html = _HARNESS_HTML.read_text(encoding="utf-8")
     start = html.index("function showAgentRecord(rec)")
     end = html.index("/* ── slash commands ── */", start)
@@ -211,8 +211,9 @@ def test_pending_agent_diff_is_shown_before_approval():
 
 
 def test_staged_agent_plan_read_paths_and_checks_reach_confirmation():
-    """The console must not silently drop the reviewed values it displays."""
-    from harness.schemas import _MAX_PLAN_CHARS
+    # Console must stage reviewed plan/read/checks, cap reads, and keep the
+    # staged run when confirm fails (422) instead of wiping operator state.
+    from harness.schemas import _MAX_PLAN_CHARS, _MAX_READ_FILES
 
     html = _HARNESS_HTML.read_text(encoding="utf-8")
     helper_start = html.index("function showPendingAgentRun()")
@@ -221,6 +222,9 @@ def test_staged_agent_plan_read_paths_and_checks_reach_confirmation():
 
     assert "agentPlanInput.addEventListener('change'" in helper
     assert f"const MAX_AGENT_PLAN_CHARS = {_MAX_PLAN_CHARS};" in html
+    assert f"const MAX_AGENT_READ_FILES = {_MAX_READ_FILES};" in html
+    assert "function isSafeRepoRelativePath(" in html
+    assert "function canonicalRepoRelativePath(" in html
     assert "pendingAgentRun.plan = plan" in helper
     assert "pendingAgentRun !== stagedRun" in helper
 
@@ -228,6 +232,9 @@ def test_staged_agent_plan_read_paths_and_checks_reach_confirmation():
     commands_end = html.index("case 'harness':", commands_start)
     commands = html[commands_start:commands_end]
     assert "read_files: []" in commands
-    assert "pendingAgentRun.read_files.push(path)" in commands
+    assert "pendingAgentRun.read_files.push(canonical)" in commands
+    assert "read_files.length >= MAX_AGENT_READ_FILES" in commands
     assert "pendingAgentRun.checks = requested" in commands
-    assert "Object.assign({}, pendingAgentRun, { reason: why, confirm: true })" in commands
+    assert "Object.assign({}, stagedRun, { reason: why, confirm: true })" in commands
+    assert "confirm failed — staged run kept" in commands
+    assert "pendingAgentRun = stagedRun" in commands
diff --git a/tests/test_ops_runner.py b/tests/test_ops_runner.py
index eb91c682..691f5086 100644
--- a/tests/test_ops_runner.py
+++ b/tests/test_ops_runner.py
@@ -341,6 +341,9 @@ def test_real_repo_run_requires_its_fields(kwargs, match) -> None:
         ({"plan": "   "}, "plan"),
         ({"read_files": ["safe.py\x00not-safe.py"]}, "read_files"),
         ({"read_files": "safe.py"}, "read_files"),
+        ({"read_files": ["/etc/passwd"]}, "read_files"),
+        ({"read_files": ["../secret"]}, "read_files"),
+        ({"read_files": ["-flag"]}, "read_files"),
     ],
 )
 def test_real_repo_run_rejects_invalid_optional_browser_values(optional, match) -> None:
diff --git a/utils/ops_runner.py b/utils/ops_runner.py
index a5dbed54..f909e670 100644
--- a/utils/ops_runner.py
+++ b/utils/ops_runner.py
@@ -39,6 +39,7 @@
 from typing import Any
 
 from utils.logger import _get_config, redact_sensitive
+from utils.repo_paths import canonical_repo_relative_path
 
 # Repo root = parent of utils/. The CLIs run as ``python -m sync.cli`` /
 # ``agentic.cli``; running with cwd=repo-root puts the ``sync`` / ``agentic``
@@ -355,10 +356,7 @@ def run_agentic_op(
     via ``--checks-file`` (never interpolated into argv, mirroring
     ``body``/``--body-file`` above) — never defaulted, since guessing a
     verification command for an arbitrary configured repo is exactly what
-    this whole path exists to avoid. An optional browser-supplied ``plan`` is
-    materialized into a temporary ``--plan-file`` so the CLI retains ownership
-    of plan scanning and hashing; ``read_files`` travel as repeatable
-    ``--read-file=<path>`` arguments and are resolved only inside the clone.
+    this whole path exists to avoid.
     ``real-repo-run-status``/
     ``real-repo-run-decide`` require ``run_id``; ``decide`` additionally
     requires ``decision`` (``"approve"`` or ``"reject"``), validated here
@@ -406,11 +404,18 @@ def run_agentic_op(
             raise OpsError("real-repo-run requires a non-empty reason")
         if plan is not None and (not isinstance(plan, str) or not plan.strip()):
             raise OpsError("real-repo-run plan must not be blank")
-        if read_files is not None and (
-            not isinstance(read_files, list)
-            or any(not isinstance(path, str) or not path or "\x00" in path for path in read_files)
-        ):
-            raise OpsError("real-repo-run read_files must contain non-empty paths without NUL bytes")
+        # Browser plan text is written to a temp --plan-file (CLI owns scan/hash);
+        # never treated as a server filesystem path. read_files are --read-file
+        # names only — resolved inside the fresh jailed clone, never the host.
+        if read_files is not None:
+            if not isinstance(read_files, list):
+                raise OpsError("real-repo-run read_files must be a list of repo-relative paths")
+            for path in read_files:
+                if not isinstance(path, str) or canonical_repo_relative_path(path) is None:
+                    raise OpsError(
+                        "real-repo-run read_files must contain non-empty repo-relative "
+                        "paths without NUL bytes, traversal, or absolute/drive forms"
+                    )
     if action in {
         "real-repo-run-status", "real-repo-run-decide", "real-repo-run-push", "real-repo-run-publish",
         "real-repo-run-discard",
diff --git a/utils/repo_paths.py b/utils/repo_paths.py
new file mode 100644
index 00000000..b3d4672b
--- /dev/null
+++ b/utils/repo_paths.py
@@ -0,0 +1,44 @@
+"""Repo-relative path safety — shared by harness and ops_runner.
+
+Why this module exists
+----------------------
+``agentic.deepagent_github.repo_workspace.canonical_repo_path`` is the jail's
+source of truth for "will this path write/read under the clone root." Harness
+and ``utils.ops_runner`` must not import ``agentic`` (I6 / isolation), but they
+must reject the same escapes *before* a browser-staged path is forwarded as
+``--read-file``.
+
+This module is a stdlib-only mirror of that acceptance rule. A drift test in
+``tests/test_harness_agent_routes.py`` asserts the two functions agree on a
+matrix of safe and hostile inputs so a future jail change cannot leave the
+control plane accepting what the clone will skip (or vice versa).
+"""
+
+from __future__ import annotations
+
+from pathlib import PureWindowsPath
+
+
+def canonical_repo_relative_path(target: str) -> str | None:
+    """Return ``target``'s canonical repo-relative form, or ``None`` if unsafe.
+
+    Same acceptance contract as ``agentic``'s ``canonical_repo_path``:
+
+    * empty / non-str / NUL → reject
+    * absolute (POSIX or Windows drive-qualified) → reject
+    * leading ``-`` (flag injection into argv) → reject
+    * ``..`` segment or ``:`` in a segment → reject
+    * empty / ``.`` segments dropped; remaining parts joined with ``/``
+
+    Returns ``None`` rather than a "cleaned" string for rejectable inputs so
+    ``/etc/passwd`` never becomes ``etc/passwd``.
+    """
+    if not isinstance(target, str) or not target or "\x00" in target:
+        return None
+    normalized = target.replace("\\", "/")
+    if normalized.startswith(("/", "-")) or PureWindowsPath(target).is_absolute():
+        return None
+    parts = tuple(part for part in normalized.split("/") if part not in {"", "."})
+    if not parts or any(part == ".." or ":" in part for part in parts):
+        return None
+    return "/".join(parts)

From 27279b86c9989b437d81c7fd119ea2388f2231d8 Mon Sep 17 00:00:00 2001
From: Chris Grady <17553614+cgfixit@users.noreply.github.com>
Date: Wed, 5 Aug 2026 20:02:55 -0400
Subject: [PATCH 6/9] Update test_harness_agent_routes.py

---
 tests/test_harness_agent_routes.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index 9fb26853..389f54a3 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -139,10 +139,11 @@ def test_duplicated_constants_match_their_agentic_originals():
 def test_harness_plan_limit_holds_a_truncated_agentic_plan():
     # A plan emitted by the CLI must fit through the browser handoff path.
 
-    Harness cannot import agentic at runtime (I6), so the intentional duplicate
-    is checked here. ``generate_plan`` appends its fixed marker after the 6k
-    body limit, which is why equality would reject a valid generated plan.
-    """
+    # Harness cannot import agentic at runtime (I6), so the intentional duplicate
+    # is checked here. ``generate_plan`` appends its fixed marker after the 6k
+    # body limit, which is why equality would reject a valid generated plan.
+    
+    #
     from agentic.real_repo_loop import _MAX_PLAN_CHARS as agentic_plan_chars
     from harness.schemas import _MAX_PLAN_CHARS as harness_plan_chars
 

From 84f0108a66cb6d2da63c80675fc4cec937f9d741 Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Thu, 6 Aug 2026 00:06:08 +0000
Subject: [PATCH 7/9] fix(lint): drop WPS231 on read_files validator via helper

---
 harness/schemas.py                 | 50 ++++++++++++++++--------------
 tests/test_harness_agent_routes.py |  2 --
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/harness/schemas.py b/harness/schemas.py
index 6ffac37b..c372df52 100644
--- a/harness/schemas.py
+++ b/harness/schemas.py
@@ -31,6 +31,30 @@
 _MAX_ITERATIONS_CEILING = 10
 
 
+def _canonicalize_read_paths(read_paths: list[str]) -> list[str]:
+    # Shared by AgentRunRequest: reject jail-unsafe names, dedupe canonical forms.
+    if len(read_paths) > _MAX_READ_FILES:
+        raise ValueError(f"read_files allows at most {_MAX_READ_FILES} paths")
+    cleaned: list[str] = []
+    seen: set[str] = set()
+    for raw in read_paths:
+        if not isinstance(raw, str) or len(raw) > _MAX_READ_FILE_LEN:
+            raise ValueError(
+                "read_files must contain non-empty bounded repo-relative paths "
+                "without NUL bytes, traversal, or absolute/drive forms"
+            )
+        canonical = canonical_repo_relative_path(raw)
+        if canonical is None:
+            raise ValueError(
+                "read_files must contain non-empty bounded repo-relative paths "
+                "without NUL bytes, traversal, or absolute/drive forms"
+            )
+        if canonical not in seen:
+            seen.add(canonical)
+            cleaned.append(canonical)
+    return cleaned
+
+
 class _ForbidModel(BaseModel, extra="forbid"):
     """Shared base: reject unexpected request fields."""
 
@@ -125,30 +149,8 @@ def _plan_is_not_blank(cls, plan_text: str | None) -> str | None:
     @field_validator("read_files")
     @classmethod
     def _read_files_are_safe_repo_relative(cls, read_paths: list[str]) -> list[str]:
-        # Align with the clone jail (utils.repo_paths / agentic canonical_repo_path):
-        # reject absolutes, traversal, drive-qualified, flag-like, and overlong
-        # names here so /agent confirm never 422s after the console staged junk
-        # the jailed reader would only skip later.
-        if len(read_paths) > _MAX_READ_FILES:
-            raise ValueError(f"read_files allows at most {_MAX_READ_FILES} paths")
-        cleaned: list[str] = []
-        seen: set[str] = set()
-        for raw in read_paths:
-            if not isinstance(raw, str) or len(raw) > _MAX_READ_FILE_LEN:
-                raise ValueError(
-                    "read_files must contain non-empty bounded repo-relative paths "
-                    "without NUL bytes, traversal, or absolute/drive forms"
-                )
-            canonical = canonical_repo_relative_path(raw)
-            if canonical is None:
-                raise ValueError(
-                    "read_files must contain non-empty bounded repo-relative paths "
-                    "without NUL bytes, traversal, or absolute/drive forms"
-                )
-            if canonical not in seen:
-                seen.add(canonical)
-                cleaned.append(canonical)
-        return cleaned
+        # Align with the clone jail so confirm never 422s on staged junk.
+        return _canonicalize_read_paths(read_paths)
 
 
 class AgentDecisionRequest(_ForbidModel):
diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index 389f54a3..61cf231c 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -142,8 +142,6 @@ def test_harness_plan_limit_holds_a_truncated_agentic_plan():
     # Harness cannot import agentic at runtime (I6), so the intentional duplicate
     # is checked here. ``generate_plan`` appends its fixed marker after the 6k
     # body limit, which is why equality would reject a valid generated plan.
-    
-    #
     from agentic.real_repo_loop import _MAX_PLAN_CHARS as agentic_plan_chars
     from harness.schemas import _MAX_PLAN_CHARS as harness_plan_chars
 

From 83f840c15e3a25404cdee5cab0d88262ac5ce4b4 Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Thu, 6 Aug 2026 00:13:43 +0000
Subject: [PATCH 8/9] fix(lint): split read path helper further for WPS231

---
 harness/schemas.py | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/harness/schemas.py b/harness/schemas.py
index c372df52..a2a94ad1 100644
--- a/harness/schemas.py
+++ b/harness/schemas.py
@@ -31,6 +31,22 @@
 _MAX_ITERATIONS_CEILING = 10
 
 
+_READ_PATH_ERR = (
+    "read_files must contain non-empty bounded repo-relative paths "
+    "without NUL bytes, traversal, or absolute/drive forms"
+)
+
+
+def _one_safe_read_path(raw: object) -> str:
+    # One entry → canonical form, or ValueError (jail-aligned).
+    if not isinstance(raw, str) or len(raw) > _MAX_READ_FILE_LEN:
+        raise ValueError(_READ_PATH_ERR)
+    canonical = canonical_repo_relative_path(raw)
+    if canonical is None:
+        raise ValueError(_READ_PATH_ERR)
+    return canonical
+
+
 def _canonicalize_read_paths(read_paths: list[str]) -> list[str]:
     # Shared by AgentRunRequest: reject jail-unsafe names, dedupe canonical forms.
     if len(read_paths) > _MAX_READ_FILES:
@@ -38,17 +54,7 @@ def _canonicalize_read_paths(read_paths: list[str]) -> list[str]:
     cleaned: list[str] = []
     seen: set[str] = set()
     for raw in read_paths:
-        if not isinstance(raw, str) or len(raw) > _MAX_READ_FILE_LEN:
-            raise ValueError(
-                "read_files must contain non-empty bounded repo-relative paths "
-                "without NUL bytes, traversal, or absolute/drive forms"
-            )
-        canonical = canonical_repo_relative_path(raw)
-        if canonical is None:
-            raise ValueError(
-                "read_files must contain non-empty bounded repo-relative paths "
-                "without NUL bytes, traversal, or absolute/drive forms"
-            )
+        canonical = _one_safe_read_path(raw)
         if canonical not in seen:
             seen.add(canonical)
             cleaned.append(canonical)

From 514abc8310bb237f796b91adf217bf2d00cb2ab8 Mon Sep 17 00:00:00 2001
From: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
Date: Thu, 6 Aug 2026 00:52:09 +0000
Subject: [PATCH 9/9] fix(harness): address codex review findings on browser
 agent parity

Fixes four issues flagged by chatgpt-codex-connector on PR #803:

- static/harness.html: /agent confirm unconditionally cleared the staged
  run after the request resolved, even when the server rejected it
  (agentRecord() returns null rather than throwing on ok=false or an
  unparsed response) -- losing the reviewed plan/read paths/checks with
  no recovery. Only clear the staged run once a real record confirms
  the server accepted it.
- static/harness.html: the Enter-key handler bypassed sendBtn's disabled
  state, so pressing Enter during the up-to-15-minute /agent confirm
  request launched a second concurrent clone/model/verification run for
  the same staged proposal. Guard onSend() on the existing in-flight
  signal.
- utils/repo_paths.py: canonical_repo_relative_path mirrored the WRITE
  jail's rules (canonical_repo_path) but harness's declared read_files
  actually flow through the stricter READ jail (ScopedRoots.read_bytes /
  split_components), which additionally rejects a trailing space or dot
  in a path component. A path like "README.md." validated here, got
  staged and confirmed, then silently vanished from the coder's context
  when agentic.real_repo_loop._render_existing_files caught the reader's
  AgenticError -- reject it up front instead.
- utils/ops_runner.py: converted run_agentic_op's multi-line docstring
  to a one-line summary + `#` comments per CLAUDE.md's Critical Python
  Coding Requirement (no multi-line docstrings outside a file's opening
  module docstring).

Added regression tests for the two path-validation fixes and verified
against the console contract test and the full targeted harness/ops_runner
suite (233 passed), ruff, invariant-guard (33/0), and a JS syntax check
of the embedded harness.html script.

Co-Authored-By: CyClaw Agent <cyclaw-agent@users.noreply.github.com>
---
 static/harness.html                | 15 ++++-
 tests/test_harness_agent_routes.py | 24 ++++++++
 utils/ops_runner.py                | 96 +++++++++++++++---------------
 utils/repo_paths.py                | 37 +++++++-----
 4 files changed, 107 insertions(+), 65 deletions(-)

diff --git a/static/harness.html b/static/harness.html
index 66eb5952..c1d7db27 100644
--- a/static/harness.html
+++ b/static/harness.html
@@ -682,8 +682,13 @@
           sys('cloning, planning, patching and verifying — this blocks for up to 15 minutes…');
           try {
             const rec = agentRecord(await api('/api/agent/run', 'POST', body));
-            if (pendingAgentRun === stagedRun) pendingAgentRun = null;
-            if (rec) showAgentRecord(rec);
+            /* agentRecord() returns null (not a throw) on ok=false or an
+               unparsed response, so only clear the staged run once a real
+               record confirms the server actually accepted it. */
+            if (rec) {
+              if (pendingAgentRun === stagedRun) pendingAgentRun = null;
+              showAgentRecord(rec);
+            }
           } catch (err) {
             if (pendingAgentRun === null || pendingAgentRun === stagedRun) {
               pendingAgentRun = stagedRun;
@@ -804,6 +809,12 @@
 }
 
 async function onSend() {
+  /* sendBtn.disabled is the console's existing in-flight signal (see
+     sendChat and /agent confirm above); the Enter-key handler below calls
+     onSend() directly and bypasses the button's own disabled state, so a
+     second Enter during a blocking /agent confirm launched a concurrent
+     clone/model/verification run for the same staged proposal. */
+  if (sendBtn.disabled) return;
   const text = input.value.trim();
   if (!text) return;
   input.value = '';
diff --git a/tests/test_harness_agent_routes.py b/tests/test_harness_agent_routes.py
index 61cf231c..be18ae76 100644
--- a/tests/test_harness_agent_routes.py
+++ b/tests/test_harness_agent_routes.py
@@ -282,6 +282,8 @@ def test_run_defaults_to_the_default_profile_when_checks_is_omitted(client, call
     {"read_files": ["C:\\Windows\\system32\\config"]},
     {"read_files": ["-evil"]},
     {"read_files": ["foo/../../etc/passwd"]},
+    {"read_files": ["README.md."]},
+    {"read_files": ["trailing space "]},
 ])
 def test_run_rejects_invalid_browser_plan_or_read_paths_before_the_shim(client, calls, body):
     assert client.post(_RUN, json={**_VALID_BODY, **body}).status_code == 422
@@ -325,6 +327,28 @@ def test_control_plane_path_rules_match_agentic_jail():
         assert left == right, (sample, left, right)
 
 
+def test_read_path_rules_reject_what_the_scoped_reader_jail_rejects():
+    # canonical_repo_path (compared above) is the WRITE jail's source of
+    # truth. harness's declared read_files instead flow through
+    # RepoWorkspaceTools.read_file -> ScopedRoots.read_bytes ->
+    # split_components, which additionally rejects a trailing space or dot
+    # in a path component (Windows silently strips them, so "README.md."
+    # and "README.md" would open the same file). Without this check here
+    # too, a declared path like "README.md." would validate at this layer,
+    # get staged and confirmed, and then
+    # agentic.real_repo_loop._render_existing_files would catch the
+    # reader's AgenticError and silently omit it -- the operator's
+    # confirmed run proceeding without the context they explicitly declared.
+    from agentic.fsconnect.pathsafe import FsPathError, split_components
+    from utils.repo_paths import canonical_repo_relative_path
+
+    samples = ["README.md.", "trailing space ", "dir./file.py", "a.b. /c"]
+    for sample in samples:
+        assert canonical_repo_relative_path(sample) is None, sample
+        with pytest.raises(FsPathError):
+            split_components(sample)
+
+
 def test_confirm_is_not_defaulted_on(client, calls):
     """Omitting confirm must reach the CLI's own refusal, not a silent True.
 
diff --git a/utils/ops_runner.py b/utils/ops_runner.py
index f909e670..bea08fc3 100644
--- a/utils/ops_runner.py
+++ b/utils/ops_runner.py
@@ -338,55 +338,53 @@ def run_agentic_op(
     run_id: str | None = None,
     decision: str | None = None,
 ) -> OpsResult:
-    """Invoke ``python -m agentic.cli <action>`` and normalize the result.
-
-    ``context`` takes an optional ``--pr`` / ``--issue`` selector (defaults to
-    ``--repo``). ``propose-skill`` / ``apply-skill`` require ``name`` + ``desc``;
-    ``apply-skill`` additionally requires a non-empty ``reason`` (the registry
-    governance gate) and only adds ``--confirm`` when the caller set it — calling
-    apply without confirm reaches the CLI's own refusal path (exit 4), which is
-    surfaced verbatim rather than masked.
-
-    ``real-repo-run`` requires ``instruction``/``checks``/``branch``/
-    ``commit_message``/``reason`` and takes the same optional ``--pr``/
-    ``--issue`` selector as ``context``. Like ``apply-skill``, ``confirm`` is
-    only forwarded when the caller set it — omitting it reaches the CLI's own
-    refusal path (exit 4), not a silent default. ``checks`` is a
-    JSON-serializable list of check dicts, written to a temp file and passed
-    via ``--checks-file`` (never interpolated into argv, mirroring
-    ``body``/``--body-file`` above) — never defaulted, since guessing a
-    verification command for an arbitrary configured repo is exactly what
-    this whole path exists to avoid.
-    ``real-repo-run-status``/
-    ``real-repo-run-decide`` require ``run_id``; ``decide`` additionally
-    requires ``decision`` (``"approve"`` or ``"reject"``), validated here
-    before the subprocess launch even though the CLI's own ``argparse``
-    ``choices=`` would also catch a bad value.
-
-    ``real-repo-run-push`` and ``real-repo-run-publish`` are the two escalation
-    steps past an approved run, each its own decision (see the CLI's own
-    docstrings for why they are separate subcommands rather than flags on
-    ``decide``). Both require ``run_id``; ``publish`` additionally requires a
-    non-empty ``reason`` and only appends ``--confirm`` when the caller set it,
-    reaching the CLI's own refusal path (exit 4) otherwise -- the same
-    "no anonymous mutations" shape as ``apply-skill``. Neither can succeed on a
-    shipped checkout: push needs ``allow_git_write_tools`` and publish needs
-    ``agentic/writer.py``'s ``EXECUTION_ENABLED``, a hardcoded ``False``.
-
-    ``real-repo-run-discard`` requires ``run_id`` and reclaims a decided run's
-    clone from disk. It is the ONLY reclamation path: an approved run's clone
-    is deliberately retained past its decision (push/publish need it), so
-    without this action a console-driven operator accumulates one full repo
-    clone per approved run with no way to free any of them. The CLI refuses a
-    still-``pending_decision`` run itself.
-
-    Validation raises happen before the subprocess launch. All ``proc`` usage
-    lives INSIDE the try so there is no post-``finally`` reference to an unbound
-    name: if ``_run`` raises (e.g. ``subprocess.TimeoutExpired``), the ``finally``
-    cleans up the temp body-file/checks-file/plan-file and the exception
-    propagates before any result is read. All are unlinked on every exit path
-    (return or raise).
-    """
+    """Invoke ``python -m agentic.cli <action>`` and normalize the result."""
+    # ``context`` takes an optional ``--pr`` / ``--issue`` selector (defaults to
+    # ``--repo``). ``propose-skill`` / ``apply-skill`` require ``name`` + ``desc``;
+    # ``apply-skill`` additionally requires a non-empty ``reason`` (the registry
+    # governance gate) and only adds ``--confirm`` when the caller set it —
+    # calling apply without confirm reaches the CLI's own refusal path (exit
+    # 4), which is surfaced verbatim rather than masked.
+    #
+    # ``real-repo-run`` requires ``instruction``/``checks``/``branch``/
+    # ``commit_message``/``reason`` and takes the same optional ``--pr``/
+    # ``--issue`` selector as ``context``. Like ``apply-skill``, ``confirm`` is
+    # only forwarded when the caller set it — omitting it reaches the CLI's own
+    # refusal path (exit 4), not a silent default. ``checks`` is a
+    # JSON-serializable list of check dicts, written to a temp file and passed
+    # via ``--checks-file`` (never interpolated into argv, mirroring
+    # ``body``/``--body-file`` above) — never defaulted, since guessing a
+    # verification command for an arbitrary configured repo is exactly what
+    # this whole path exists to avoid. ``real-repo-run-status``/
+    # ``real-repo-run-decide`` require ``run_id``; ``decide`` additionally
+    # requires ``decision`` (``"approve"`` or ``"reject"``), validated here
+    # before the subprocess launch even though the CLI's own ``argparse``
+    # ``choices=`` would also catch a bad value.
+    #
+    # ``real-repo-run-push`` and ``real-repo-run-publish`` are the two
+    # escalation steps past an approved run, each its own decision (see the
+    # CLI's own docstrings for why they are separate subcommands rather than
+    # flags on ``decide``). Both require ``run_id``; ``publish`` additionally
+    # requires a non-empty ``reason`` and only appends ``--confirm`` when the
+    # caller set it, reaching the CLI's own refusal path (exit 4) otherwise --
+    # the same "no anonymous mutations" shape as ``apply-skill``. Neither can
+    # succeed on a shipped checkout: push needs ``allow_git_write_tools`` and
+    # publish needs ``agentic/writer.py``'s ``EXECUTION_ENABLED``, a hardcoded
+    # ``False``.
+    #
+    # ``real-repo-run-discard`` requires ``run_id`` and reclaims a decided
+    # run's clone from disk. It is the ONLY reclamation path: an approved
+    # run's clone is deliberately retained past its decision (push/publish
+    # need it), so without this action a console-driven operator accumulates
+    # one full repo clone per approved run with no way to free any of them.
+    # The CLI refuses a still-``pending_decision`` run itself.
+    #
+    # Validation raises happen before the subprocess launch. All ``proc``
+    # usage lives INSIDE the try so there is no post-``finally`` reference to
+    # an unbound name: if ``_run`` raises (e.g. ``subprocess.TimeoutExpired``),
+    # the ``finally`` cleans up the temp body-file/checks-file/plan-file and
+    # the exception propagates before any result is read. All are unlinked on
+    # every exit path (return or raise).
     if action not in _AGENTIC_ACTIONS:
         raise OpsError(f"Unknown agentic action: {action!r}")
     if action in {"propose-skill", "apply-skill"} and (not name or not desc):
diff --git a/utils/repo_paths.py b/utils/repo_paths.py
index b3d4672b..2fe8a082 100644
--- a/utils/repo_paths.py
+++ b/utils/repo_paths.py
@@ -20,25 +20,34 @@
 
 
 def canonical_repo_relative_path(target: str) -> str | None:
-    """Return ``target``'s canonical repo-relative form, or ``None`` if unsafe.
-
-    Same acceptance contract as ``agentic``'s ``canonical_repo_path``:
-
-    * empty / non-str / NUL → reject
-    * absolute (POSIX or Windows drive-qualified) → reject
-    * leading ``-`` (flag injection into argv) → reject
-    * ``..`` segment or ``:`` in a segment → reject
-    * empty / ``.`` segments dropped; remaining parts joined with ``/``
-
-    Returns ``None`` rather than a "cleaned" string for rejectable inputs so
-    ``/etc/passwd`` never becomes ``etc/passwd``.
-    """
+    # Return target's canonical repo-relative form, or None if unsafe.
+    #
+    # Base contract matches agentic's canonical_repo_path (the write-path
+    # jail): empty/non-str/NUL, absolute (POSIX or Windows drive-qualified),
+    # leading "-" (flag injection into argv), a ".." segment, or ":" in a
+    # segment are all rejected; empty/"." segments are dropped and the rest
+    # joined with "/".
+    #
+    # PLUS one stricter rule the write jail does not need but the read jail
+    # does: a segment with a trailing space or dot is rejected outright,
+    # rather than accepted and silently reinterpreted. The actual read path
+    # for harness's declared read_files is RepoWorkspaceTools.read_file ->
+    # ScopedRoots.read_bytes -> split_components, which raises on exactly
+    # this (Windows silently strips trailing dots/spaces from a path
+    # component, so "README.md." and "README.md" would open the same file).
+    # Without this check, a path like "README.md." would validate here, get
+    # staged and confirmed, and then _render_existing_files would catch the
+    # reader's AgenticError and silently omit it -- the operator's confirmed
+    # run would proceed without context they explicitly declared.
+    #
+    # Returns None rather than a "cleaned" string for rejectable inputs so
+    # /etc/passwd never becomes etc/passwd.
     if not isinstance(target, str) or not target or "\x00" in target:
         return None
     normalized = target.replace("\\", "/")
     if normalized.startswith(("/", "-")) or PureWindowsPath(target).is_absolute():
         return None
     parts = tuple(part for part in normalized.split("/") if part not in {"", "."})
-    if not parts or any(part == ".." or ":" in part for part in parts):
+    if not parts or any(part == ".." or ":" in part or part != part.rstrip(" .") for part in parts):
         return None
     return "/".join(parts)