Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/architecture/decisions/execution-and-concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,3 +64,4 @@ never rewritten or deleted. The detail doc describes the current design.
- 2026-11-20: Antigravity eligible structured turns use agy `--output-format json --json-schema` behind a cached capability probe and an `auto|off` operator switch. A renderable `SUCCESS` `structured_output` outranks the response file and stdout marker. The schema is loose and admits `agent_unavailable`, and the protocol validators stay authoritative. Turns whose contract needs content outside the JSON object, footer and signature keep the response-file channel. Repeated no-payload reviewer format failures fall back to the next chain model before the seat becomes unavailable; capacity, quota and provider-definitive behaviour is unchanged (#2029).
- 2026-11-20: A non-`SUCCESS` agy envelope's decoded error is a typed provider diagnostic on `AgentResult` and is classified as the terminal frame in every failure phase. A fallback response that fails validation after such an envelope is classified as a provider failure, with no repair and no format-failure fallback (#2029).
- 2026-11-20: The agy structured-output schema avoids non-string enums, which Gemini rejects with INVALID_ARGUMENT; `schema_version` is a plain integer validated by the protocol parsers. A structured attempt whose provider diagnostics (non-`SUCCESS` envelope, stdout outside the envelope, or the silent attempt's own agy log) show a schema-naming INVALID_ARGUMENT is replayed once per turn without schema flags, with a warning, a dedicated attempt slot, no retry, no format-failure count and no repair. Model prose is never evidence (#2039).
- 2026-11-20: `run-tests` refuses a request before reservation or launch when a registered worktree link or private environment of the broker checkout is no longer intact, naming it in a no-test `cancelled` frame; the pre-check is fail-open and never poisons the checkout. Coder prompts name the coder checkout's registered links as shared operator infrastructure. An uncitable receipt for a citable launcher family names the rejected argument through a static explainer that shares the recognizer's argument walk; the allow-list and persisted reasons are unchanged (#2036).
6 changes: 4 additions & 2 deletions docs/architecture/execution-and-concurrency.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Concurrent default-dir invocations on one repository are supported.
Each run with an omitted `--<agent>-dir` gets its own detached `git worktree`
under `<scratch>/OWNER-REPO/<agent>/runs/<run-token>`, backed by one shared
clone per repo/agent (the *store*, `<scratch>/OWNER-REPO/<agent>/repo`) that
owns the object store. Explicit `--<agent>-dir` paths are untouched. Optional `--worktree-link PATH` (repeatable, off by default) symlinks (never copies) an untracked repository-relative path such as `.venv` from the shared store into each per-run worktree. The path must exist in the store (otherwise the run fails, naming the shared clone and suggesting `--worktree-setup` or creating the path there) and its parent directories must be tracked. Explicit `--<agent>-dir` checkouts ignore it. The link is exempted from checkout verification, sync cleaning and test-evidence attribution by agent-loop's in-process registry only (no git ignore state is written); a removed, retargeted, staged or committed link is refused. Linked state is shared and mutable across concurrent runs. Keep every link ignored with a root-anchored pattern without a trailing slash (`/.venv`, `/node_modules`) in `.gitignore` or the store's `.git/info/exclude` (shared by every worktree); a dir-only `.venv/` or `node_modules/` rule does not match a symlink. agent-loop warns, and never writes ignore state, when a created link is not ignored. `.venv/bin/python` works through the link; bare `python` reaches the linked venv only if the agent environment activates it. Parallel
owns the object store. Explicit `--<agent>-dir` paths are untouched. Optional `--worktree-link PATH` (repeatable, off by default) symlinks (never copies) an untracked repository-relative path such as `.venv` from the shared store into each per-run worktree. The path must exist in the store and its parent directories must be tracked. Explicit `--<agent>-dir` checkouts ignore it. The link is exempted from checkout verification, sync cleaning and test-evidence attribution by agent-loop's in-process registry only (no git ignore state is written); a removed, retargeted, staged or committed link is refused. Linked state is shared and mutable across concurrent runs. Keep every link ignored with a root-anchored pattern without a trailing slash (`/.venv`, `/node_modules`) in `.gitignore` or the store's `.git/info/exclude` (shared by every worktree); a dir-only `.venv/` or `node_modules/` rule does not match a symlink. agent-loop warns, and never writes ignore state, when a created link is not ignored. Parallel
reviewers within one invocation are supported; the orchestrator verifies
distinct reviewer workdirs. Coder and reviewer turns are separate lifecycle
stages even when they use the same CLI.
Expand Down Expand Up @@ -208,7 +208,9 @@ client (including `--fixture` runs) prints that advisory, or the remedy selected
after a launch failure or a pre-collection failure. The variable is excluded
from evidence environment identity, and nothing reads it for classification,
outcome, evidence or exit code. A replaced-link refusal names the link source
in the shared clone. When an issue run stops (a checkout refusal or a terminal
in the shared clone. Before reservation or launch the broker refuses, naming
it, a registered link or private environment that is not intact (fail-open,
never poisons). Coder prompts name the checkout's own links as off limits (#2036). When an issue run stops (a checkout refusal or a terminal
no-PR result) while the implementing coder's per-run worktree is poisoned and its branch
has a remote-tracking ref, the stop's message gains a `managed-pr --head`
resume and the manual worktree-removal command; the exception type, exit code
Expand Down
28 changes: 28 additions & 0 deletions docs/local_agent_loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -1998,6 +1998,16 @@ fallback. Every no-test refusal (`overlap-rejected`, `worker-budget-busy`,
again after the receipt line as `agent-loop: no test ran (<outcome>):
<reason>`; a lock held by another request of the same broker is named with
its command, phase and age.
In a per-run worktree with `--worktree-link` paths, the broker checks every
registered link (and every private environment rebuilt under
`--worktree-setup-pr-local`) before it reserves or launches anything (#2036).
A replaced, moved, retargeted or removed link is refused with
`` agent-loop: no test ran (cancelled): agent-loop: worktree link `<name>` was replaced, moved or retargeted; it is shared operator infrastructure. Restore it or report the problem; nothing was run (not evidence) ``.
The pre-check never poisons the checkout and does not change the checkout
guard; a lookup error falls through to the existing snapshot and guard.
Coder prompts for such a checkout name its registered links as shared
operator infrastructure that must not be replaced, moved, copied over or
deleted.
A receipt whose inner command started but whose suite start was never verified
(`suite_start=unknown`) can never be cited, so `run-tests` says so right after
the receipt line (#1659). The broker persists why the suite start stayed
Expand All @@ -2007,6 +2017,24 @@ It never changes admission, citability or a disqualifier. For a launcher the
inner-probe recognizer does not accept (for example `python scripts/x.py`,
reason `unrecognized-launcher`) it prints
`agent-loop: this receipt is not citable evidence: unrecognized test launcher, so suite start was not verified (suite_start=unknown). Citable runners: <runners>. Wrap the check in a pytest test to make it citable; you may still report it in tests_run.`
When the launcher family is citable but one of its arguments or its context is
rejected (#2036), the notice names the cause instead of calling the launcher
unrecognized, for example
`` agent-loop: this receipt is not citable evidence: `playwright test` is a citable runner, but `-g` is a short alias, which the citable allow-list does not accept; spell it `--grep=pat` (value options are citable only in `--name=value` form). Suite start was not verified (suite_start=unknown); you may still report it in tests_run. ``
The static explainer covers `playwright test` (including `npx` and a local
`node_modules/.bin/playwright`), `node --test` and package scripts that
resolve to them. It names short aliases and detached values (`-g pat`,
`--grep pat`, `-j 4`, `-x`) with their citable `--name=value` spelling,
code-loading options (`--config`/`-c`, including a scratch config outside the
checkout, `--tsconfig`, custom reporters: never citable), zero-test and
interactive options, the `--` separator, unknown options, a non-empty
`NODE_OPTIONS`/`PW_TEST_REPORTER`, a missing local Playwright binary for
`npx playwright`, and a package script with a `pre`/`post` hook or shell
syntax. A rejected argument appended with `npm run <script> -- ...` is named as
appended, with the advice to cite the unfiltered `npm run <script>` run and
report the filtered run in tests_run. Unknown or unresolvable commands keep
the generic text above. The explainer is advisory only: the allow-list, the
persisted reason and citability are unchanged.
For a recognized launcher whose bootstrap probe could not verify it (reason
`probe-unavailable`, for example unavailable probe containment) it prints
`agent-loop: this receipt is not citable evidence: the test launcher is recognized, but its bootstrap probe could not verify it in this run, so suite start was not verified (suite_start=unknown). Rerunning the same command may make it citable; you may still report it in tests_run.`
Expand Down
41 changes: 41 additions & 0 deletions src/coding_review_agent_loop/checkout_verification.py
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,47 @@ def link_intact(root: Path, link: bytes | str, target: bytes | str) -> bool:
return descriptor == ("symlink", os.fsencode(target))


def replaced_worktree_link(root: Path) -> tuple[str, str] | None:
"""``(name, kind)`` of the first registered entry of ``root`` that is no longer intact (#2036).

``kind`` is ``"link"`` for a shared --worktree-link and ``"private"`` for a
rebuilt private environment. This is an advisory pre-check for
``agent-loop run-tests``: a lookup error returns None so the request falls
through to the snapshot and checkout guard, which still cover it. It
never poisons the checkout.
"""
try:
requested = Path(os.path.abspath(os.fspath(root)))
canonical = requested.resolve(strict=True)
registration = lookup_worktree_links(requested, canonical)
if registration is None:
return None
for link, target in sorted(registration.links.items()):
if not link_intact(canonical, link, target):
return os.fsdecode(link), "link"
for name, (_digest, identity) in sorted(registration.private.items()):
if not private_path_intact(canonical, name, identity):
return os.fsdecode(name), "private"
except (OSError, AgentLoopError):
return None
return None


def replaced_worktree_link_refusal(name: str, kind: str) -> str:
"""The run-tests refusal text naming a replaced link (#2036)."""
if kind == "private":
return (
f"agent-loop: private dependency environment `{name}` was removed or replaced; "
"agent-loop builds it from the committed --worktree-setup-key files. Restore it or "
"report the problem; nothing was run (not evidence)"
)
return (
f"agent-loop: worktree link `{name}` was replaced, moved or retargeted; it is shared "
"operator infrastructure. Restore it or report the problem; nothing was run (not "
"evidence)"
)


def _deferred_paths(path: Path) -> tuple[str, ...]:
registration = link_registration(path)
return registration.deferred if registration is not None else ()
Expand Down
20 changes: 18 additions & 2 deletions src/coding_review_agent_loop/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -2420,6 +2420,22 @@ def _uncitable_receipt_unrecognized_message() -> str:
)


def _uncitable_launcher_message(raw_inner: Sequence[str]) -> str:
"""The specific argument-rejection notice, else the generic unrecognized text (#2036)."""
try:
from .test_runtime import explain_uncitable_launcher

explanation = explain_uncitable_launcher(list(raw_inner), cwd=Path.cwd(), environment=os.environ)
except Exception: # advisory only; never fail run-tests
explanation = None
if not explanation:
return _uncitable_receipt_unrecognized_message()
return (
f"agent-loop: this receipt is not citable evidence: {explanation}. Suite start was not "
"verified (suite_start=unknown); you may still report it in tests_run."
)


def _announce_uncitable_receipt(result, raw_inner: Sequence[str]) -> None:
"""Say next to the receipt line when it can never be cited (#1659).

Expand All @@ -2446,7 +2462,7 @@ def _announce_uncitable_receipt(result, raw_inner: Sequence[str]) -> None:

reason = coerce_suite_start_reason(getattr(result, "suite_start_reason", None), "unknown")
if reason == SUITE_START_REASON_UNRECOGNIZED:
print(_uncitable_receipt_unrecognized_message(), file=sys.stderr, flush=True)
print(_uncitable_launcher_message(raw_inner), file=sys.stderr, flush=True)
return
if reason == SUITE_START_REASON_PROBE_UNAVAILABLE:
print(UNCITABLE_RECEIPT_PROBE_UNAVAILABLE_MESSAGE, file=sys.stderr, flush=True)
Expand All @@ -2456,7 +2472,7 @@ def _announce_uncitable_receipt(result, raw_inner: Sequence[str]) -> None:
probe = recognized_inner_probe(list(raw_inner), cwd=Path.cwd(), environment=os.environ)
except Exception: # advisory only; a malformed package.json must not fail run-tests
probe = ()
message = UNCITABLE_RECEIPT_GENERIC_MESSAGE if probe is not None else _uncitable_receipt_unrecognized_message()
message = UNCITABLE_RECEIPT_GENERIC_MESSAGE if probe is not None else _uncitable_launcher_message(raw_inner)
print(message, file=sys.stderr, flush=True)


Expand Down
20 changes: 18 additions & 2 deletions src/coding_review_agent_loop/local_test_evidence.py
Original file line number Diff line number Diff line change
Expand Up @@ -3392,12 +3392,16 @@ def capture_tracked_tree_snapshot(
if registration is not None:
for link_b, target_b in sorted(registration.links.items()):
if not _cv.link_intact(canonical_root, link_b, target_b):
raise AgentLoopError("registered worktree link was removed or retargeted")
raise AgentLoopError(
f"registered worktree link was removed or retargeted: {os.fsdecode(link_b)}"
)
link_names.add(os.fsdecode(link_b))
# Validate every private environment before exempting it (#1652).
for name_b, (_env_digest, identity) in sorted(registration.private.items()):
if not _cv.private_path_intact(canonical_root, name_b, identity):
raise AgentLoopError("registered private environment was removed or replaced")
raise AgentLoopError(
f"registered private environment was removed or replaced: {os.fsdecode(name_b)}"
)
private_names.add(os.fsdecode(name_b))
top = _run_git(canonical_root, ("rev-parse", "--show-toplevel"), timeout=timeout_seconds, cancel=cancel)
git_root = Path(top.decode("utf-8", errors="strict").strip()).resolve(strict=True)
Expand Down Expand Up @@ -4610,6 +4614,18 @@ def _handle(self, connection: socket.socket) -> None:
_drain_acks(connection, BROKER_SEND_CANCEL_POLL_SECONDS)
return
validated = rebuilt
# Issue #2036: a replaced worktree link is refused before
# anything is reserved or launched; nothing is poisoned.
from . import checkout_verification as _cv

replaced = _cv.replaced_worktree_link(self.root)
if replaced is not None:
sender.send(
_legacy_refusal_frame(_cv.replaced_worktree_link_refusal(*replaced)),
grace=terminal, cancellable=False,
)
_drain_acks(connection, BROKER_SEND_CANCEL_POLL_SECONDS)
return
nonce = str(validated["nonce"])
digest = hashlib.sha256(json.dumps(validated, sort_keys=True, default=str).encode()).hexdigest()
with self._journal_lock:
Expand Down
33 changes: 32 additions & 1 deletion src/coding_review_agent_loop/prompt_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -1101,6 +1101,7 @@ def _coder_workdir_guidance(
"and confirm the path is the assigned checkout."
f"{dangerous_warning}\n"
f"{_pr_local_environment_guidance(config, workdir) if implementation else ''}"
f"{_worktree_link_guidance(config, workdir) if implementation else ''}"
f"{_sandboxed_permission_guidance(config, implementation=implementation, agent=active_agent)}"
)

Expand All @@ -1118,14 +1119,44 @@ def _pr_local_environment_guidance(config: AgentLoopConfig, workdir: Path) -> st
"file, commit it and keep tracked files committed; agent-loop rebuilds "
f"{links} from the committed keys after the turn. Installs during the turn only affect "
"this worktree, and test evidence from before the rebuild does not count for the rebuilt "
"environment. Do not delete or replace those paths yourself.\n"
"environment. Do not delete, replace, move or copy over those paths yourself.\n"
)
note = take_rebuild_note(workdir)
if note:
text += f"Note: {note}\n"
return text


def _worktree_link_guidance(config: AgentLoopConfig, workdir: Path) -> str:
"""Name the coder checkout's shared ``--worktree-link`` paths as off limits (#2036).

The names come only from this checkout's own link registration, never from
``config.worktree_links`` alone: the configured links stay set whenever any
role uses a default worktree, while an explicit coder directory has no
links. Under --worktree-setup-pr-local the configured links are already
named by the private-environment note, so they are left out here.
"""
from .checkout_verification import registered_links

names = [os.fsdecode(name) for name in registered_links(workdir)]
if getattr(config, "worktree_setup_pr_local", False):
covered = set(config.worktree_links)
names = [name for name in names if name not in covered]
if not names:
return ""
links = ", ".join(f"`{name}`" for name in names)
return (
f"Shared worktree links: {links} in this checkout "
f"{'is a link' if len(names) == 1 else 'are links'} (--worktree-link) to the operator's "
"dependency store, shared across runs. They are shared operator infrastructure: do not "
"replace, move, copy over or delete them, not even to make a test receipt citable. "
"`agent-loop run-tests` refuses to run while one is replaced, and the run's checkout "
"guard treats a changed link as an untrustworthy checkout. If a dependency seems to "
"block citable evidence, report that in tests_run or the PR instead of changing the "
"link.\n"
)


def _sandboxed_permission_guidance(
config: AgentLoopConfig, *, implementation: bool, agent: AgentName
) -> str:
Expand Down
5 changes: 3 additions & 2 deletions src/coding_review_agent_loop/protocol_risk.py
Original file line number Diff line number Diff line change
Expand Up @@ -2547,8 +2547,9 @@ def _known_launch_integrity_passes(observation: object) -> bool:


SUITE_START_UNRECOGNIZED_DIAGNOSTIC = (
"Suite start was never verified (suite_start=unknown): the test launcher is not "
"recognized, so this receipt cannot be cited. Citable runners: "
"Suite start was never verified (suite_start=unknown): the launcher or one of its "
"arguments is not on the citable allow-list (the run-tests receipt line names the "
"rejected argument), so this receipt cannot be cited. Citable runners: "
f"{CITABLE_TEST_RUNNERS_SUMMARY}. Wrap the check in a pytest test to make it citable."
)
SUITE_START_PROBE_UNAVAILABLE_DIAGNOSTIC = (
Expand Down
Loading