Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

44.1 KB
Raw Blame
"""Delete, mkdir and move in a session workspace, on both backings, and what keeps them from coming back.

  * the hosted backing (CheckpointWorkspaceFiles): between turns the checkpoint tarball IS the
    workspace, so each change rewrites it, as `write` does
  * the self-hosted backing (RunnerWorkspaceFiles): the live directory through the runner, and then
    the checkpoint, because a sandbox that does not hold the last checkpoint is restored from it and
    a change made only live would be undone there
  * the durable copies: a delete leaves a tombstone, so the by-path read stops falling back to the
    agent's old capture and the restore stops re-applying the app's; a move carries the app's copy
    to the new name
  * the routes: the same ownership and busy rule as PUT, `..` and absolute paths refused, internal
    paths (.git, .harness) refused, and each backing's answer mapped to its failure
"""
import io
import json
import pathlib
import sys
import tarfile
import time

import pytest

sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
import app as A  # noqa: E402
import backing as B  # noqa: E402


def _tar(entries: dict) -> bytes:
    """name -> bytes (a file) or None (a directory entry)."""
    out = io.BytesIO()
    with tarfile.open(fileobj=out, mode="w:gz") as tf:
        for name, data in entries.items():
            info = tarfile.TarInfo(name)
            if data is None:
                info.type = tarfile.DIRTYPE
                tf.addfile(info)
            else:
                info.size = len(data)
                tf.addfile(info, io.BytesIO(data))
    return out.getvalue()


def _files(raw: bytes) -> dict:
    with tarfile.open(fileobj=io.BytesIO(raw), mode="r:gz") as tf:
        return {m.name: (tf.extractfile(m).read() if m.isfile() else None) for m in tf.getmembers()}


# ── the archive ────────────────────────────────────────────────────────────────────────────────
def test_delete_a_file_and_keep_the_rest():
    outcome, raw = B.tar_change(_tar({"./a.txt": b"a", "./b.txt": b"b"}), "delete", "a.txt")
    assert outcome == B.WS_OK and _files(raw) == {"./b.txt": b"b"}


def test_delete_a_directory_with_or_without_its_own_entry():
    for entries in ({"./d": None, "./d/x": b"x", "./dx": b"keep"}, {"d/x": b"x", "dx": b"keep"}):
        outcome, raw = B.tar_change(_tar(entries), "delete", "d")
        assert outcome == B.WS_OK
        assert [n for n in _files(raw)] == [n for n in entries if n.endswith("dx")]


def test_delete_nothing():
    assert B.tar_change(_tar({"a": b"a"}), "delete", "b") == (B.WS_NOT_FOUND, None)
    assert B.tar_change(None, "delete", "b") == (B.WS_NOT_FOUND, None)


def test_mkdir():
    outcome, raw = B.tar_change(_tar({"a": b"a"}), "mkdir", "d/e")
    assert outcome == B.WS_OK and _files(raw) == {"a": b"a", "d/e": None}
    assert B.tar_change(raw, "mkdir", "d/e") == (B.WS_UNCHANGED, None)  # already there
    assert B.tar_change(raw, "mkdir", "a") == (B.WS_EXISTS, None)      # a file is in the way
    outcome, raw = B.tar_change(None, "mkdir", "d")                     # no checkpoint yet
    assert outcome == B.WS_OK and _files(raw) == {"d": None}


def test_move_a_file_and_a_directory_keeping_the_bytes():
    raw = _tar({"./a.txt": b"A", "./d": None, "./d/x": b"X", "./d/y/z": b"Z"})
    outcome, raw = B.tar_change(raw, "move", "a.txt", "notes/a.txt")
    assert outcome == B.WS_OK
    outcome, raw = B.tar_change(raw, "move", "d", "e")
    assert outcome == B.WS_OK
    assert _files(raw) == {"./notes/a.txt": b"A", "./e": None, "./e/x": b"X", "./e/y/z": b"Z"}


def test_move_refusals():
    raw = _tar({"a": b"a", "b": b"b", "d/x": b"x"})
    assert B.tar_change(raw, "move", "a", "b") == (B.WS_EXISTS, None)
    assert B.tar_change(raw, "move", "d", "d/in") == (B.WS_BAD_PATH, None)
    assert B.tar_change(raw, "move", "nope", "c") == (B.WS_NOT_FOUND, None)


def test_the_nesting_base_s_files_are_found_one_level_down():
    raw = _tar({".harness/agent-subdir": b"workspace\n", "workspace/deck.json": b"{}"})
    outcome, raw = B.tar_change(raw, "move", "deck.json", "old/deck.json")
    assert outcome == B.WS_OK and "workspace/old/deck.json" in _files(raw)
    outcome, raw = B.tar_change(raw, "delete", "old")
    assert outcome == B.WS_OK and set(_files(raw)) == {".harness/agent-subdir"}


# ── the hosted backing ────────────────────────────────────────────────────────────────────────
class _Blob:
    def __init__(self, objects=None):
        self.objects = dict(objects or {})

    async def get(self, kb, key):
        return self.objects.get((kb, key))

    async def put(self, kb, key, data):
        self.objects[(kb, key)] = data
        return True

    async def delete(self, kb, key):
        return self.objects.pop((kb, key), None) is not None


def _hosted(entries):
    blob = _Blob({("kb", "sessions/s/workspace.tgz"): _tar(entries)})
    return blob, B.CheckpointWorkspaceFiles(blob, "kb", lambda sid: f"sessions/{sid}/workspace.tgz")


@pytest.mark.asyncio
async def test_hosted_delete_mkdir_move_rewrite_the_checkpoint():
    blob, ws = _hosted({"a.txt": b"a", "d/x": b"x"})
    assert await ws.delete("s", "a.txt") == B.WS_OK
    assert await ws.mkdir("s", "new") == B.WS_OK
    assert await ws.move("s", "d", "e") == B.WS_OK
    assert _files(blob.objects[("kb", "sessions/s/workspace.tgz")]) == {"new": None, "e/x": b"x"}
    assert await ws.read("s", "e/x") == b"x" and await ws.read("s", "d/x") is None


@pytest.mark.asyncio
async def test_hosted_refusals_change_nothing():
    blob, ws = _hosted({"a.txt": b"a"})
    before = dict(blob.objects)
    assert await ws.delete("s", "../a.txt") == B.WS_BAD_PATH
    assert await ws.move("s", "a.txt", "../../b") == B.WS_BAD_PATH
    assert await ws.delete("s", "missing") == B.WS_NOT_FOUND
    # normpath leaves "." and ".." as they are; a member named ".." is one tar refuses to unpack
    # ("Member name contains '..'", GNU tar), so every later restore of the session would fail
    assert await ws.write("s", "..", b"x") is False
    assert await ws.mkdir("s", "..") == B.WS_BAD_PATH and await ws.mkdir("s", ".") == B.WS_BAD_PATH
    assert blob.objects == before


# ── the self-hosted backing ───────────────────────────────────────────────────────────────────
class _Resp:
    def __init__(self, status, body=None):
        self.status_code, self._body = status, body or {}

    def json(self):
        return self._body


def _selfhosted(answer, entries=None):
    blob = _Blob({("ckpt", "sessions/s/workspace.tgz"): _tar(entries)} if entries is not None else {})
    ws = B.RunnerWorkspaceFiles("http://runner", "k", blob, "resp", "ckpt",
                                lambda sid: f"sessions/{sid}/workspace.tgz")
    calls = []

    class _Client:
        async def request(self, method, url, params=None, headers=None):
            calls.append((method, url, params))
            return answer

    ws._c = lambda: _Client()
    return blob, ws, calls


@pytest.mark.asyncio
async def test_selfhosted_changes_the_live_directory_and_then_the_checkpoint():
    blob, ws, calls = _selfhosted(_Resp(200, {"path": "d", "to": "e"}), {"d/x": b"x", "keep": b"k"})
    assert await ws.move("s", "d", "e") == B.WS_OK
    assert calls == [("POST", "http://runner/file/move", {"identifier": "s", "path": "d", "to": "e"})]
    assert _files(blob.objects[("ckpt", "sessions/s/workspace.tgz")]) == {"e/x": b"x", "keep": b"k"}


@pytest.mark.asyncio
async def test_selfhosted_changes_the_nesting_base_s_checkpoint_where_its_files_are():
    """nanobot: the runner answers the session-relative path (workspace/deck.json); the checkpoint is
    changed by the caller's path, which tar_change looks for one level down itself. Passing the
    runner's spelling looked for workspace/workspace/deck.json, found nothing, and changed nothing."""
    marker = {".harness/agent-subdir": b"workspace"}
    blob, ws, _calls = _selfhosted(_Resp(200, {"path": "workspace/deck.json"}),
                                   {**marker, "workspace/deck.json": b"{}", "deck.json.bak": b""})
    assert await ws.delete("s", "deck.json") == B.WS_OK
    assert set(_files(blob.objects[("ckpt", "sessions/s/workspace.tgz")])) == {".harness/agent-subdir", "deck.json.bak"}
    blob, ws, _calls = _selfhosted(_Resp(200, {"path": "workspace/a.md", "to": "workspace/b/a.md"}),
                                   {**marker, "workspace/a.md": b"A"})
    assert await ws.move("s", "a.md", "b/a.md") == B.WS_OK
    assert _files(blob.objects[("ckpt", "sessions/s/workspace.tgz")])["workspace/b/a.md"] == b"A"


@pytest.mark.asyncio
async def test_selfhosted_a_file_made_since_the_checkpoint_leaves_it_alone():
    blob, ws, _ = _selfhosted(_Resp(200, {"path": "new.txt"}), {"old.txt": b"o"})
    before = dict(blob.objects)
    assert await ws.delete("s", "new.txt") == B.WS_OK
    assert blob.objects == before


@pytest.mark.asyncio
async def test_selfhosted_with_no_checkpoint_yet():
    """A delete or a move has no archive to change while the session has no checkpoint (its turn ended
    without one). A folder does: the next turn's restore empties the live directory and the captures
    put back only files, so the archive is started with the folder, as the hosted backing starts one."""
    blob, ws, _ = _selfhosted(_Resp(200, {"path": "x"}))
    assert await ws.delete("s", "x") == B.WS_OK and blob.objects == {}
    blob, ws, _ = _selfhosted(_Resp(200, {"path": "a", "created": True}))
    assert await ws.mkdir("s", "a") == B.WS_OK
    assert _files(blob.objects[("ckpt", "sessions/s/workspace.tgz")]) == {"a": None}


@pytest.mark.asyncio
async def test_selfhosted_a_checkpoint_that_refuses_what_the_live_directory_allowed_is_the_answer():
    """The live directory took the change but the checkpoint has a FILE in the way: that live directory
    is a reaped one the runner made anew, which the next turn wipes and restores from the checkpoint.
    A 200 would be undone by that turn."""
    blob, ws, _ = _selfhosted(_Resp(200, {"path": "notes/x", "created": True}), {"notes": b"a file"})
    before = dict(blob.objects)
    assert await ws.mkdir("s", "notes/x") == B.WS_EXISTS
    assert blob.objects == before
    blob, ws, _ = _selfhosted(_Resp(200, {"path": "a", "to": "b"}), {"a": b"a", "b": b"b"})
    before = dict(blob.objects)
    assert await ws.move("s", "a", "b") == B.WS_EXISTS
    assert blob.objects == before


@pytest.mark.asyncio
@pytest.mark.parametrize("status,outcome", [(409, B.WS_EXISTS), (400, B.WS_BAD_PATH), (500, B.WS_FAILED)])
async def test_selfhosted_a_refusal_touches_no_checkpoint(status, outcome):
    blob, ws, _ = _selfhosted(_Resp(status), {"a": b"a"})
    before = dict(blob.objects)
    assert await ws.delete("s", "a") == outcome
    assert blob.objects == before


@pytest.mark.asyncio
async def test_selfhosted_a_reaped_live_directory_leaves_the_change_to_the_checkpoint():
    """The live directory is reaped after HR_WORKSPACE_TTL_HOURS; the checkpoint still holds the file,
    and the next turn restores from it. The runner's 404 is not the answer then."""
    blob, ws, _ = _selfhosted(_Resp(404), {"notes.md": b"n", "keep": b"k"})
    assert await ws.delete("s", "notes.md") == B.WS_OK
    assert _files(blob.objects[("ckpt", "sessions/s/workspace.tgz")]) == {"keep": b"k"}
    assert await ws.move("s", "keep", "kept") == B.WS_OK
    assert _files(blob.objects[("ckpt", "sessions/s/workspace.tgz")]) == {"kept": b"k"}
    assert await ws.delete("s", "nowhere") == B.WS_NOT_FOUND
    _blob, ws, _ = _selfhosted(_Resp(404))                        # no checkpoint either
    assert await ws.delete("s", "x") == B.WS_NOT_FOUND


@pytest.mark.asyncio
async def test_selfhosted_a_bad_path_never_reaches_the_runner():
    _blob, ws, calls = _selfhosted(_Resp(200))
    assert await ws.delete("s", "../x") == B.WS_BAD_PATH
    assert await ws.move("s", "a", "/../b") == B.WS_BAD_PATH
    assert calls == []


# ── the durable copies ────────────────────────────────────────────────────────────────────────
@pytest.fixture
def captures(monkeypatch):
    """The response blob store, in memory: containers/<sid>/<cfile> and its .meta."""
    store: dict[str, bytes] = {}

    async def _list(prefix, **_k):
        return {"items": [{"file_id": k} for k in sorted(store) if k.startswith(prefix)]}

    async def _get(fid, **_k):
        return store.get(fid)

    async def _put(fid, data, **_k):
        store[fid] = data
        return True

    async def _delete(fid, **_k):
        return store.pop(fid, None) is not None

    async def _bytes(sid, cid):
        data = store.get(f"containers/{sid}/{cid}")
        return (data, "application/octet-stream", cid) if data is not None else None

    monkeypatch.setattr(A, "_blob_list", _list)
    monkeypatch.setattr(A, "_blob_get", _get)
    monkeypatch.setattr(A, "_blob_put", _put)
    monkeypatch.setattr(A, "_blob_delete", _delete)
    monkeypatch.setattr(A, "_container_file_bytes", _bytes)

    class _StoreBlob:
        async def put(self, _kb, key, data):
            store[key] = data
            return True

    monkeypatch.setattr(A.BACKING, "blob", _StoreBlob(), raising=False)

    def add(cid, name, data, ts, app=False):
        store[f"containers/s/{cid}"] = data
        store[f"containers/s/{cid}.meta"] = json.dumps(
            {"filename": name, "written_at": ts, **({"source": "app"} if app else {})}).encode()
    store_add = add
    store_add.store = store
    return store_add


@pytest.mark.asyncio
async def test_a_tombstone_hides_older_captures_of_the_path_and_under_it(captures):
    captures("cfile_agent1", "report.md", b"old", 100.0)
    captures("cfile_agent2", "d/x.md", b"x", 100.0)
    captures("cfile_agent3", "dx.md", b"keep", 100.0)
    await A._put_tombstone("s", "report.md")
    await A._put_tombstone("s", "d")
    assert set(await A._cfile_by_name("s")) == {"dx.md"}


@pytest.mark.asyncio
async def test_a_capture_newer_than_the_tombstone_is_back(captures):
    await A._put_tombstone("s", "report.md")
    captures("cfile_later", "report.md", b"new", time.time() + 10)
    assert (await A._cfile_by_name("s"))["report.md"] == "cfile_later"


@pytest.mark.asyncio
async def test_the_tombstone_replaces_the_app_s_own_copy(captures):
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "sheet.json", b"rows")
    cid = B.app_capture_id("sheet.json")
    assert f"containers/s/{cid}" in captures.store
    await A._put_tombstone("s", "sheet.json")
    assert f"containers/s/{cid}" not in captures.store and f"containers/s/{cid}.meta" not in captures.store
    assert json.loads(captures.store[A._tomb_key("s", "sheet.json")])["filename"] == "sheet.json"


@pytest.mark.asyncio
async def test_a_restore_does_not_bring_back_what_the_app_deleted(captures, monkeypatch):
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "sheet.json", b"rows")
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "d/x.json", b"x")
    await A._put_tombstone("s", "sheet.json")
    await A._put_tombstone("s", "d")
    written = {}

    class _Ws:
        async def write(self, _sid, name, data):
            written[name] = data
            return True

    monkeypatch.setattr(A.BACKING, "workspace", _Ws(), raising=False)
    assert await A._reapply_app_writes("s") == 0 and written == {}


@pytest.mark.asyncio
async def test_a_removed_path_does_not_come_back_by_its_bare_name(captures, monkeypatch):
    """The read falls back to a capture named by the bare filename (captures from before paths
    were kept). After `notes/a.md` is deleted, a capture called `a.md` is some other file."""
    captures("cfile_legacy", "a.md", b"legacy", 50.0)

    class _Gone:
        async def read(self, *_a, **_k):
            return None

    async def _owned(*_a, **_k):
        return ("org", {})

    monkeypatch.setattr(A.BACKING, "workspace", _Gone(), raising=False)
    monkeypatch.setattr(A, "_owned_session", _owned)
    r = await A.read_session_file("s", "notes/a.md", request=None)
    assert r.body == b"legacy"                                    # before: the old fallback stands
    await A._put_tombstone("s", "notes/a.md")
    with pytest.raises(Exception) as e:
        await A.read_session_file("s", "notes/a.md", request=None)
    assert getattr(e.value, "status_code", None) == 404


@pytest.mark.asyncio
async def test_a_move_carries_the_app_s_copy_and_not_the_agent_s(captures):
    """The app's, because a restore re-applies it. Not the agent's: carried as the app's it would be
    re-applied on every restore, over whatever the agent later did with the file."""
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "d/sheet.json", b"typed since the checkpoint")
    captures("cfile_agent", "d/other.md", b"agent's", 100.0)
    await A._carry_captures("s", "d", "archive/d", await A._capture_state("s"))
    await A._put_tombstone("s", "d")
    by = await A._cfile_by_name("s")
    assert set(by) == {"archive/d/sheet.json"}
    assert captures.store[f"containers/s/{by['archive/d/sheet.json']}"] == b"typed since the checkpoint"


# ── the routes ────────────────────────────────────────────────────────────────────────────────
class _Fake:
    def __init__(self, outcome=B.WS_OK):
        self.outcome, self.calls = outcome, []

    async def delete(self, sid, path):
        self.calls.append(("delete", path))
        return self.outcome

    async def mkdir(self, sid, path):
        self.calls.append(("mkdir", path))
        return self.outcome

    async def write(self, sid, path, data):
        self.calls.append(("write", path))
        return self.outcome == B.WS_OK

    async def move(self, sid, path, to):
        self.calls.append(("move", path, to))
        return self.outcome


@pytest.fixture
def routes(monkeypatch, captures):
    state = {"v": {}}

    async def _owned(_r, _sid):
        return ("org", state["v"])

    async def _vget(_sid):
        return state["v"]

    fake = _Fake()
    monkeypatch.setattr(A, "_owned_session", _owned)
    monkeypatch.setattr(A, "_vertex_get", _vget)
    monkeypatch.setattr(A.BACKING, "workspace", fake, raising=False)
    monkeypatch.setattr(A, "_ws_changed", lambda sid: state.setdefault("changed", []).append(sid))
    state["fake"] = fake
    return state


@pytest.mark.asyncio
async def test_routes_do_the_change_and_answer(routes):
    assert await A.delete_session_file("s", "a.txt", request=None) == \
        {"session_id": "s", "path": "a.txt", "deleted": True}
    assert await A.mkdir_session_file("s", "d", request=None) == \
        {"session_id": "s", "path": "d", "dir": True, "created": True}
    assert await A.move_session_file("s", "d", A.WorkspaceMove(to="e"), request=None) == \
        {"session_id": "s", "path": "d", "to": "e", "moved": True}
    assert routes["fake"].calls == [("delete", "a.txt"), ("mkdir", "d"), ("move", "d", "e")]
    assert routes["changed"] == ["s", "s", "s"]


@pytest.mark.asyncio
@pytest.mark.parametrize("status", ["running", "starting"])
async def test_routes_refuse_while_a_turn_runs(routes, status):
    routes["v"] = {"turn_status": status}
    for call in (lambda: A.delete_session_file("s", "a", request=None),
                 lambda: A.mkdir_session_file("s", "a", request=None),
                 lambda: A.move_session_file("s", "a", A.WorkspaceMove(to="b"), request=None)):
        with pytest.raises(Exception) as e:
            await call()
        assert e.value.status_code == 409 and e.value.detail["code"] == "session_busy"
    assert routes["fake"].calls == []


@pytest.mark.asyncio
@pytest.mark.parametrize("path", ["../a", "a/../../b", ".git", ".git/config", ".harness/agent-subdir",
                                  "x/.git/HEAD", ".gitignore", "a\\b"])
async def test_routes_refuse_escapes_and_internal_paths(routes, path):
    for call in (lambda: A.delete_session_file("s", path, request=None),
                 lambda: A.mkdir_session_file("s", path, request=None),
                 lambda: A.move_session_file("s", path, A.WorkspaceMove(to="ok"), request=None),
                 lambda: A.move_session_file("s", "ok", A.WorkspaceMove(to=path), request=None)):
        with pytest.raises(Exception) as e:
            await call()
        assert e.value.status_code == 400 and e.value.detail["code"] == "invalid_input"
    assert routes["fake"].calls == []


@pytest.mark.asyncio
async def test_a_put_the_runner_refuses_says_which_paths_it_may_write(routes):
    """The runner refuses a PUT to the base's own machinery as it refuses delete, mkdir and move, and the
    backing answers that as a failed write: the answer names that rule beside the workspace rule, so a
    caller writing AGENTS.md on a base that keeps it is not told the path left the workspace."""
    routes["fake"].outcome = B.WS_BAD_PATH
    with pytest.raises(Exception) as e:
        await A.write_session_file("s", "AGENTS.md", A.WorkspaceWrite(content="x"), request=None)
    assert e.value.status_code == 400 and e.value.detail["code"] == "write_failed"
    assert "not one of the agent's own files" in e.value.detail["message"]
    assert routes["fake"].calls == [("write", "AGENTS.md")] and "changed" not in routes


@pytest.mark.asyncio
async def test_a_leading_slash_names_the_same_workspace_path(routes):
    """The PUT next door treats `/a.txt` as `a.txt` (_safe_member strips it); these do the same."""
    await A.delete_session_file("s", "/a.txt", request=None)
    assert routes["fake"].calls == [("delete", "a.txt")]


@pytest.mark.asyncio
async def test_move_into_itself_is_refused_before_the_backing(routes):
    with pytest.raises(Exception) as e:
        await A.move_session_file("s", "d", A.WorkspaceMove(to="d/in"), request=None)
    assert e.value.status_code == 400 and routes["fake"].calls == []


@pytest.mark.asyncio
@pytest.mark.parametrize("outcome,status,code", [(B.WS_NOT_FOUND, 404, "file_not_found"),
                                                 (B.WS_EXISTS, 409, "file_exists"),
                                                 (B.WS_BAD_PATH, 400, "invalid_input"),
                                                 (B.WS_FAILED, 502, "internal_error")])
async def test_routes_map_the_backing_s_answer(routes, outcome, status, code):
    routes["fake"].outcome = outcome
    with pytest.raises(Exception) as e:
        await A.delete_session_file("s", "a", request=None)
    assert e.value.status_code == status and e.value.detail["code"] == code
    assert "changed" not in routes                     # a refused change evicts nothing


def test_the_action_suffix_routes_a_path_with_slashes():
    from starlette.routing import Match

    def _match(method, path):
        scope = {"type": "http", "method": method, "path": path, "root_path": "", "query_string": b"",
                 "headers": []}
        for r in A.app.router.routes:
            m, child = r.matches(scope)
            if m == Match.FULL:
                return r.endpoint.__name__, child["path_params"]
        return None

    assert _match("POST", "/v1/sessions/s/files/notes/2026/a.md:move") == \
        ("move_session_file", {"sid": "s", "path": "notes/2026/a.md"})
    assert _match("POST", "/v1/sessions/s/files/a/b:mkdir") == \
        ("mkdir_session_file", {"sid": "s", "path": "a/b"})
    assert _match("DELETE", "/v1/sessions/s/files/a/b.txt") == \
        ("delete_session_file", {"sid": "s", "path": "a/b.txt"})
    # the routes beside them are untouched
    assert _match("GET", "/v1/sessions/s/files/a/b.txt")[0] == "read_session_file"
    assert _match("PUT", "/v1/sessions/s/files/a/b.txt")[0] == "write_session_file"


@pytest.mark.asyncio
async def test_a_capture_that_cannot_be_carried_does_not_stop_the_move(routes, monkeypatch):
    """The backing has already moved the file; the tombstone on the source must still land, or the
    next restore writes the app's old copy back under the old name."""
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "sheet.json", b"rows")

    async def _boom(*_a, **_k):
        raise RuntimeError("blob store flaked")

    monkeypatch.setattr(A, "_container_file_bytes", _boom)
    assert (await A.move_session_file("s", "sheet.json", A.WorkspaceMove(to="kept.json"), request=None))["moved"]
    assert "sheet.json" not in await A._cfile_by_name("s")


# ── what the review of #478 found ─────────────────────────────────────────────────────────────
_NANOBOT = {".harness/agent-subdir": b"workspace\n",
            ".git/info/exclude": b"# runner\nworkspace/.nanobot/\nworkspace/skills/\nworkspace/memory/\n"
                                 b"workspace/AGENTS.md\n",
            "workspace/AGENTS.md": b"doc", "workspace/skills/s/SKILL.md": b"skill",
            "workspace/memory/m.md": b"mem", "workspace/deck.json": b"{}"}


def test_the_nesting_base_s_own_directory_is_not_a_user_path():
    """DELETE …/files/workspace on nanobot would have removed the agent's whole working directory."""
    raw = _tar(_NANOBOT)
    assert B.tar_change(raw, "delete", "workspace") == (B.WS_NOT_FOUND, None)
    assert B.tar_change(raw, "move", "workspace", "w2") == (B.WS_NOT_FOUND, None)


@pytest.mark.parametrize("op,path,to", [("delete", "skills", ""), ("delete", "AGENTS.md", ""),
                                        ("delete", "memory/m.md", ""), ("move", "skills", "s2"),
                                        ("move", "deck.json", "skills/deck.json"),
                                        ("mkdir", "memory/new", "")])
def test_the_base_s_excluded_machinery_is_refused(op, path, to):
    assert B.tar_change(_tar(_NANOBOT), op, path, to) == (B.WS_BAD_PATH, None)


def test_a_flat_base_s_excluded_files_are_refused_too():
    """opensquilla seeds SOUL.md and memory/ at the session root and excludes them."""
    raw = _tar({".git/info/exclude": b"SOUL.md\nmemory/\n", "SOUL.md": b"s", "memory/x": b"x",
                "notes.md": b"n"})
    assert B.tar_change(raw, "delete", "SOUL.md") == (B.WS_BAD_PATH, None)
    assert B.tar_change(raw, "delete", "memory") == (B.WS_BAD_PATH, None)
    assert B.tar_change(raw, "delete", "notes.md")[0] == B.WS_OK


def test_a_file_written_at_the_root_between_turns_is_still_reachable_on_the_nesting_base():
    """An app's PUT lands at the session root until the next turn adopts it."""
    outcome, raw = B.tar_change(_tar({**_NANOBOT, "sheet.json": b"rows"}), "move", "sheet.json", "kept.json")
    assert outcome == B.WS_OK and _files(raw)["kept.json"] == b"rows"


@pytest.mark.parametrize("op,path,to", [("move", "a.md", "notes.txt/a.md"), ("mkdir", "notes.txt/sub", ""),
                                        ("move", "a.md", "notes.txt/deeper/a.md")])
def test_nothing_goes_under_a_file(op, path, to):
    """Such an archive holds `notes.txt` and `notes.txt/a.md`, and no restore can unpack it."""
    assert B.tar_change(_tar({"notes.txt": b"n", "a.md": b"a"}), op, path, to) == (B.WS_EXISTS, None)


def test_a_rewritten_archive_unpacks(tmp_path):
    _o, raw = B.tar_change(_tar({"./d": None, "./d/x": b"X", "./y": b"Y"}), "move", "d", "e/d")
    with tarfile.open(fileobj=io.BytesIO(raw), mode="r:gz") as tf:
        tf.extractall(tmp_path, filter="data")
    assert (tmp_path / "e" / "d" / "x").read_bytes() == b"X" and (tmp_path / "y").read_bytes() == b"Y"


@pytest.mark.asyncio
async def test_a_hosted_rewrite_records_the_new_checkpoint_sha():
    """A sandbox kept warm with the old workspace passes the hydrate probe on the old sha, and its next
    checkpoint writes the deleted files back. The new sha matches no sandbox."""
    import hashlib
    blob, ws = _hosted({"a.txt": b"a", "b.txt": b"b"})
    seen = []

    async def _rewritten(sid, sha):
        seen.append((sid, sha))
    ws.on_rewrite = _rewritten
    assert await ws.delete("s", "a.txt") == B.WS_OK
    assert await ws.write("s", "c.txt", b"c")
    assert await ws.delete("s", "missing") == B.WS_NOT_FOUND
    assert len(seen) == 2
    assert seen[-1] == ("s", hashlib.sha256(blob.objects[("kb", "sessions/s/workspace.tgz")]).hexdigest())


@pytest.mark.asyncio
async def test_two_changes_at_once_both_land():
    import asyncio

    class _Slow(_Blob):
        async def get(self, kb, key):
            await asyncio.sleep(0.01)
            return await super().get(kb, key)

    blob = _Slow({("kb", "sessions/s/workspace.tgz"): _tar({"a": b"a", "b": b"b", "c": b"c"})})
    ws = B.CheckpointWorkspaceFiles(blob, "kb", lambda sid: f"sessions/{sid}/workspace.tgz")
    assert await asyncio.gather(ws.delete("s", "a"), ws.delete("s", "b")) == [B.WS_OK, B.WS_OK]
    assert _files(blob.objects[("kb", "sessions/s/workspace.tgz")]) == {"c": b"c"}


@pytest.mark.asyncio
async def test_selfhosted_mkdir_says_when_the_directory_was_there():
    _blob, ws, _ = _selfhosted(_Resp(200, {"path": "d", "created": False}))
    assert await ws.mkdir("s", "d") == B.WS_UNCHANGED


@pytest.mark.asyncio
async def test_mkdir_route_answers_created(routes):
    routes["fake"].outcome = B.WS_UNCHANGED
    assert (await A.mkdir_session_file("s", "d", request=None))["created"] is False


@pytest.mark.asyncio
async def test_a_move_clash_names_the_destination(routes):
    routes["fake"].outcome = B.WS_EXISTS
    with pytest.raises(Exception) as e:
        await A.move_session_file("s", "a.md", A.WorkspaceMove(to="b.md"), request=None)
    assert e.value.status_code == 409 and e.value.detail["param"] == "to"
    assert "'b.md'" in e.value.detail["message"]


@pytest.mark.asyncio
async def test_a_tombstone_the_store_refused_is_reported_and_keeps_the_copy(routes, captures, monkeypatch):
    await B.put_app_capture(A.BACKING.blob, "kb", "s", "sheet.json", b"rows")
    cid = B.app_capture_id("sheet.json")

    async def _refuse(fid, data, **_k):
        return False
    monkeypatch.setattr(A, "_blob_put", _refuse)
    with pytest.raises(Exception) as e:
        await A.delete_session_file("s", "sheet.json", request=None)
    assert e.value.status_code == 502
    assert routes.get("changed") == ["s"]                    # the change itself was made
    assert f"containers/s/{cid}" in captures.store           # the copy was not dropped unrecorded
    assert "Repeat the delete" in e.value.detail["message"]


@pytest.mark.asyncio
async def test_a_delete_of_what_is_already_gone_still_records_it(routes, captures):
    """The repeat a refused tombstone asks for: the workspace answers 404, the removal is recorded."""
    captures("cfile_agent", "old.md", b"agent's", 100.0)
    routes["fake"].outcome = B.WS_NOT_FOUND
    assert (await A.delete_session_file("s", "old.md", request=None))["deleted"] is True
    assert "old.md" not in await A._cfile_by_name("s")


@pytest.mark.asyncio
async def test_the_gateway_records_a_rewritten_checkpoint_s_sha_on_the_session(monkeypatch):
    seen = []

    class _Graph:
        async def upsert(self, label, vid, props, *, raise_on_fail=False):
            seen.append((label, vid, props, raise_on_fail))
    monkeypatch.setattr(A.BACKING, "graph", _Graph(), raising=False)
    await A._checkpoint_rewritten("s", "abc")
    assert seen == [("HarnessSession", "s", {"ws_sha": "abc"}, True)]


@pytest.mark.asyncio
async def test_a_removed_directory_compacts_what_it_hides(captures):
    for name in ("d/a.json", "d/b.json", "keep.json"):
        await B.put_app_capture(A.BACKING.blob, "kb", "s", name, b"x")
    await A._put_tombstone("s", "d/old", await A._capture_state("s"))
    await A._put_tombstone("s", "d", await A._capture_state("s"))
    metas = {json.loads(v)["filename"] for k, v in captures.store.items() if k.endswith(".meta")}
    tombs = {json.loads(v)["filename"] for k, v in captures.store.items() if k.startswith("ws-removed/")}
    assert metas == {"keep.json"} and tombs == {"d"}


@pytest.mark.asyncio
async def test_every_tombstone_is_read_beside_the_capture_window(captures):
    """The captures stay a first page of 200 metas; the tombstones live apart and are read in full,
    so none can fall out of a window and let the file it hid come back."""
    for i in range(250):
        captures(f"cfile_{i:04d}", f"f{i}.md", b"x", 100.0)
    for i in range(30):
        await A._put_tombstone("s", f"gone{i}.md")
    await A._put_tombstone("s", "f0.md")
    caps, tombs = await A._capture_state("s")
    assert len(tombs) == 31 and "f0.md" not in caps and len(caps) == 199


@pytest.mark.asyncio
async def test_a_delete_of_a_path_that_never_existed_stores_nothing(routes, captures):
    routes["fake"].outcome = B.WS_NOT_FOUND
    for i in range(5):
        with pytest.raises(Exception):
            await A.delete_session_file("s", f"never{i}.md", request=None)
    assert not [k for k in captures.store if k.startswith("ws-removed/")]


@pytest.mark.asyncio
async def test_the_read_fallback_scans_the_captures_once(captures, monkeypatch):
    captures("cfile_legacy", "a.md", b"legacy", 50.0)
    calls = []
    real = A._capture_state

    async def _counted(sid):
        calls.append(sid)
        return await real(sid)

    class _Gone:
        async def read(self, *_a, **_k):
            return None

    async def _owned(*_a, **_k):
        return ("org", {})

    monkeypatch.setattr(A, "_capture_state", _counted)
    monkeypatch.setattr(A.BACKING, "workspace", _Gone(), raising=False)
    monkeypatch.setattr(A, "_owned_session", _owned)
    assert (await A.read_session_file("s", "notes/a.md", request=None)).body == b"legacy"
    assert calls == ["s"]


def test_a_hard_link_to_a_removed_file_keeps_its_bytes(tmp_path):
    """tar stores a second hard link as a pointer to the first member's name. Removing or renaming that
    member left a pointer to nothing, and an archive no restore can unpack."""
    out = io.BytesIO()
    with tarfile.open(fileobj=out, mode="w:gz") as tf:
        info = tarfile.TarInfo("./a.txt"); info.size = 1
        tf.addfile(info, io.BytesIO(b"A"))
        for n in ("./b.txt", "./c.txt"):
            ln = tarfile.TarInfo(n); ln.type, ln.linkname = tarfile.LNKTYPE, "./a.txt"
            tf.addfile(ln)
    outcome, raw = B.tar_change(out.getvalue(), "delete", "a.txt")
    assert outcome == B.WS_OK
    with tarfile.open(fileobj=io.BytesIO(raw), mode="r:gz") as tf:
        tf.extractall(tmp_path / "del", filter="data")
    assert (tmp_path / "del" / "b.txt").read_bytes() == b"A" and (tmp_path / "del" / "c.txt").read_bytes() == b"A"
    outcome, raw = B.tar_change(out.getvalue(), "move", "a.txt", "d/a.txt")
    with tarfile.open(fileobj=io.BytesIO(raw), mode="r:gz") as tf:
        tf.extractall(tmp_path / "mv", filter="data")
    assert (tmp_path / "mv" / "d" / "a.txt").read_bytes() == b"A" and (tmp_path / "mv" / "b.txt").read_bytes() == b"A"


def test_a_new_folder_on_the_nesting_base_goes_in_the_agent_s_directory():
    """Where the runner now makes it, so the live directory and the checkpoint agree."""
    outcome, raw = B.tar_change(_tar(_NANOBOT), "mkdir", "slides/old")
    assert outcome == B.WS_OK and "workspace/slides/old" in _files(raw)
    raw = _tar({**_NANOBOT, "workspace/notes": b"a file"})
    assert B.tar_change(raw, "mkdir", "notes/x") == (B.WS_EXISTS, None)


@pytest.mark.asyncio
async def test_a_sha_that_cannot_be_recorded_leaves_the_archive_as_it_was():
    """Rewriting under a sha that still matches the warm sandbox would be undone by its next checkpoint."""
    blob, ws = _hosted({"a.txt": b"a"})
    before = dict(blob.objects)

    async def _down(_sid, _sha):
        raise RuntimeError("graph store down")
    ws.on_rewrite = _down
    assert await ws.delete("s", "a.txt") == B.WS_FAILED
    assert not await ws.write("s", "b.txt", b"b")
    assert blob.objects == before


def test_a_delete_on_the_nesting_base_removes_every_copy():
    """A file at the root beside the agent's copy (an app's PUT from before writes went where the file
    is) would be adopted back next turn if only the agent's copy went."""
    outcome, raw = B.tar_change(_tar({**_NANOBOT, "notes.md": b"app", "workspace/notes.md": b"agent"}),
                                "delete", "notes.md")
    assert outcome == B.WS_OK and not {"notes.md", "workspace/notes.md"} & set(_files(raw))


@pytest.mark.asyncio
async def test_a_hosted_put_replaces_the_nesting_base_s_file_where_it_is():
    blob, ws = _hosted({**_NANOBOT})
    assert await ws.write("s", "deck.json", b'{"v":2}')
    files = _files(blob.objects[("kb", "sessions/s/workspace.tgz")])
    assert files["workspace/deck.json"] == b'{"v":2}' and "deck.json" not in files
    assert await ws.read("s", "deck.json") == b'{"v":2}'
    assert await ws.write("s", "new.json", b"n")                 # a new file: the root, adopted next turn
    assert _files(blob.objects[("kb", "sessions/s/workspace.tgz")])["new.json"] == b"n"
    assert await ws.read("s", "new.json") == b"n"


@pytest.mark.asyncio
async def test_a_put_waits_for_a_change_of_the_same_session(routes, monkeypatch):
    """Under the same lock as delete, mkdir and move: a PUT racing a delete of its path would have
    its fresh copy dropped by the delete's tombstone."""
    import asyncio
    order = []

    class _Ws(_Fake):
        async def delete(self, sid, path):
            order.append("delete start")
            await asyncio.sleep(0.02)
            order.append("delete end")
            return B.WS_OK

        async def write(self, sid, path, data):
            order.append("put")
            return True

    monkeypatch.setattr(A.BACKING, "workspace", _Ws(), raising=False)
    await asyncio.gather(A.delete_session_file("s", "n.md", request=None),
                         A.write_session_file("s", "n.md", A.WorkspaceWrite(content="x"), request=None))
    assert order == ["delete start", "delete end", "put"]


def test_a_move_on_the_nesting_base_leaves_no_copy_under_the_old_name():
    outcome, raw = B.tar_change(_tar({**_NANOBOT, "a.md": b"root", "workspace/a.md": b"agent"}),
                                "move", "a.md", "b.md")
    files = _files(raw)
    assert outcome == B.WS_OK and files["workspace/b.md"] == b"agent"
    assert "a.md" not in files and "workspace/a.md" not in files


@pytest.mark.asyncio
async def test_a_hosted_put_of_a_new_file_goes_into_a_folder_the_agent_has():
    """Adoption moves a root entry only when its name is free in the agent's directory, so a root
    notes/new.md beside workspace/notes/ would never reach the agent."""
    blob, ws = _hosted({**_NANOBOT, "workspace/notes/old.md": b"o"})
    assert await ws.write("s", "notes/new.md", b"n")
    files = _files(blob.objects[("kb", "sessions/s/workspace.tgz")])
    assert files["workspace/notes/new.md"] == b"n" and "notes/new.md" not in files


@pytest.mark.asyncio
async def test_a_refused_move_does_not_blame_one_side(routes):
    routes["fake"].outcome = B.WS_BAD_PATH
    with pytest.raises(Exception) as e:
        await A.move_session_file("s", "notes.md", A.WorkspaceMove(to="skills/notes.md"), request=None)
    assert e.value.status_code == 400 and e.value.detail["param"] is None


@pytest.mark.asyncio
async def test_a_put_refreshes_the_cached_listing(routes, monkeypatch):
    class _Ws(_Fake):
        async def write(self, sid, path, data):
            return True
    monkeypatch.setattr(A.BACKING, "workspace", _Ws(), raising=False)
    await A.write_session_file("s", "n.md", A.WorkspaceWrite(content="x"), request=None)
    assert routes["changed"] == ["s"]


# ── what the maintainer review of #478 found ──────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_a_file_with_no_capture_is_read_from_the_checkpoint(captures, monkeypatch):
    """A file the agent moved has no capture under its new name. Once the live directory is reaped
    the checkpoint holds it there, and the by-path read finds it instead of answering 404 until the
    next turn restores it."""
    class _Gone:
        async def read(self, *_a, **_k):
            return None

    async def _owned(*_a, **_k):
        return ("org", {})

    async def _bytes(sid, fid):
        if fid == A._wf_id("archive/report.md"):
            return b"moved", "text/markdown", "archive/report.md"
        data = captures.store.get(f"containers/{sid}/{fid}")
        return (data, "application/octet-stream", fid) if data is not None else None

    monkeypatch.setattr(A.BACKING, "workspace", _Gone(), raising=False)
    monkeypatch.setattr(A, "_owned_session", _owned)
    monkeypatch.setattr(A, "_container_file_bytes", _bytes)
    assert (await A.read_session_file("s", "archive/report.md", request=None)).body == b"moved"
    captures("cfile_agent", "notes.md", b"captured", 100.0)        # a capture still comes first
    assert (await A.read_session_file("s", "notes.md", request=None)).body == b"captured"
    with pytest.raises(Exception) as e:
        await A.read_session_file("s", "report.md", request=None)
    assert getattr(e.value, "status_code", None) == 404


@pytest.mark.asyncio
@pytest.mark.parametrize("call", ["delete", "mkdir", "move", "put"])
async def test_a_change_that_waited_behind_a_turn_s_restore_is_refused(routes, monkeypatch, call):
    """The route's busy check read the session before a turn was stamped running. The turn restores
    the workspace under the change lock, so the change waits, reads the session again, and stops
    rather than landing under the running turn."""
    import asyncio

    class _Ws(_Fake):
        async def write(self, sid, path, data):
            self.calls.append(("write", path))
            return True
    monkeypatch.setattr(A.BACKING, "workspace", _Ws(), raising=False)
    routes["fake"] = A.BACKING.workspace
    sid = f"busy-{call}"           # a lock of its own: one bound to another test's event loop is not
    run = {"delete": lambda: A.delete_session_file(sid, "a.txt", request=None),
           "mkdir": lambda: A.mkdir_session_file(sid, "d", request=None),
           "move": lambda: A.move_session_file(sid, "a.txt", A.WorkspaceMove(to="b.txt"), request=None),
           "put": lambda: A.write_session_file(sid, "a.txt", A.WorkspaceWrite(content="x"), request=None)}[call]
    lock = A._ws_change_lock(sid)
    await lock.acquire()                              # the turn's restore, in progress
    task = asyncio.create_task(run())
    for _ in range(5):
        await asyncio.sleep(0)
    routes["v"] = {"status": "running", "turn_status": "starting"}
    lock.release()
    with pytest.raises(Exception) as e:
        await task
    assert e.value.status_code == 409 and e.value.detail["code"] == "session_busy"
    assert routes["fake"].calls == []


@pytest.mark.asyncio
async def test_a_restore_waits_for_a_change_in_flight(monkeypatch):
    """A change that passed its busy check before the turn was stamped running finishes before the
    restore reads the workspace (the recycle route restores the same way a turn does)."""
    import asyncio
    order = []

    async def _hydrate(sid, rec, force=False):
        order.append("restore")
        rec["hydrated"] = True

    async def _vget(_sid):
        return {"status": "idle"}

    monkeypatch.setattr(A, "_hydrate", _hydrate)
    monkeypatch.setattr(A, "_vertex_get", _vget)
    lock = A._ws_change_lock("recycle-wait")
    await lock.acquire()                              # a change, in progress
    task = asyncio.create_task(A.recycle_session_sandbox("recycle-wait"))
    for _ in range(5):
        await asyncio.sleep(0)
    order.append("change done")
    lock.release()
    assert (await task)["hydrated"] is True
    assert order == ["change done", "restore"]


@pytest.mark.parametrize("extra,path,to", [({"app.json": b"the app's"}, "deck.json", "app.json"),
                                           ({"sheet.json": b"rows"}, "sheet.json", "deck.json")])
def test_a_move_onto_a_name_taken_on_the_other_side_is_refused(extra, path, to):
    """nanobot: a file an app put at the root waits there for adoption. Moving the agent's deck.json to
    app.json answered 200 on the candidate (0.35.0-rc.1), and the moved file then shadowed the app's
    app.json for good, since adoption never moves over a name the agent's directory has. The same the
    other way round."""
    raw = _tar({**_NANOBOT, **extra})
    assert B.tar_change(raw, "move", path, to) == (B.WS_EXISTS, None)