diff --git a/docs/AGENT-CLAIM-PROTOCOL.md b/docs/AGENT-CLAIM-PROTOCOL.md index 8aadb85560..b0997bcbf4 100644 --- a/docs/AGENT-CLAIM-PROTOCOL.md +++ b/docs/AGENT-CLAIM-PROTOCOL.md @@ -65,6 +65,13 @@ before creating branches or editing files. In that mode, a pushed claim branch is the task lock, and a local heartbeat is the checkout/worktree traffic signal. +If agents do **not** share a machine, filesystem, worktree +directory, or local broadcast bus, read +[Remote-only / no shared filesystem mode](#remote-only--no-shared-filesystem-mode). +In that mode, pushed claim branches are the coordination +bus; host comments such as GitHub PR / issue comments are +useful adapters, not requirements. + ### 2. Check for an existing claim on the work you want Claim files live on pushed `claim/` branches (see @@ -372,6 +379,114 @@ claim lands, work commits can move to a separate working branch (`feat/`); the `claim/` branch stays as the lock until release. +### Remote-only / no shared filesystem mode + +This section applies when two or more agents are working from +different machines, cloud sandboxes, forks, browser sessions, +or vendor harnesses that cannot see each other's local files. +In that setting there is no shared `.git/agent-heartbeats/` +directory, no reliable local broadcast folder, and no local +worktree traffic signal. The protocol still works. + +The rule is: + +> **Remote git is the lock and the minimum message bus. +> Host comments are adapters. Local-only signals are optional +> convenience, never dependencies.** + +Operationally: + +1. **Assume no local signal exists.** Do not rely on + `.broadcasts/`, `.git/agent-heartbeats/`, terminal logs, + local worktree names, or a human courier to know what + remote agents are doing. Those can help on one machine, but + a remote agent following this document may never see them. +2. **Refresh remote refs before choosing work.** + ``` + git fetch --prune origin + git branch -r --list 'origin/claim/*' + git ls-remote --heads origin 'claim/*' + ``` + If you have a host adapter such as GitHub CLI, GitLab CLI, + Forgejo / Gitea, Jira, or Linear, also inspect its open + workflow surface. For Zeta today, that means GitHub PRs: + ``` + gh pr list --repo Lucent-Financial-Group/Zeta --state open + ``` + A project without GitHub still runs the protocol from the + first three git commands. +3. **Treat `origin/claim/` as the task lock.** If a + remote claim branch exists, read its claim file before + touching the same task: + ``` + git show origin/claim/:docs/claims/.md + ``` + If the existing claim covers your intended work, do not + duplicate it. Use the available remote surface to coordinate, + or pick a different slice. +4. **Use claim progress commits as remote heartbeats and the + git-only message bus.** In remote-only mode, a long-running + claim must signal progress through git, not local files. + Update the claim file's ETA or Notes and push: + ``` + git commit -am "progress: - " + git push + ``` + For active cross-agent work, prefer progress commits every + 30-60 minutes rather than waiting for the 24-hour stale + window. When no host comments exist, append short entries to + the claim file's Notes: + - `ask:` what input is needed; + - `offer:` what the agent can take next; + - `receipt:` what it has read or verified; + - `blocked:` what prevents the next move. + This is slower than a chatty host, but it is enough: every + remote peer can fetch and read the claim branch. +5. **Use host comments as a convenience adapter, not the core + protocol.** If the project has GitHub, GitLab, Forgejo / + Gitea, Jira, Linear, email patch review, or another review + host, mirror asks, offers, receipts, and blockers there too. + Keep the claim file as the ownership lock; keep host + discussion as a discoverability and notification layer. For + Zeta, GitHub PR / issue comments are the active host bus + because the factory currently lives on GitHub. +6. **Check changed paths before overlapping.** If another + claim may touch the same area, inspect its branch diff: + ``` + git diff --name-only origin/main...origin/claim/ + ``` + Overlapping paths are not automatically forbidden, but they + require an explicit remote signal before both agents write: + either a shared claim-file entry in git-only mode, or a host + comment when a host adapter exists. +7. **Forks still use the same lock.** If an agent cannot push + to `Lucent-Financial-Group/Zeta`, it cannot create the + authoritative `origin/claim/` lock. It should use + [report-back / write-via-maintainer mode](#report-back--write-via-maintainer-mode-no-claim-required) + or open a fork PR and comment that it is unable to hold a + first-class claim. A maintainer or write-capable agent can + then file the claim on its behalf. + +This gives remote agents two durable layers: + +- **Required git layer:** `origin/claim/` and + `docs/claims/.md`; task ownership, progress, + git-only asks, offers, receipts, and blockers. +- **Optional host layer:** GitHub / GitLab / Forgejo / Gitea + PRs or issues, Jira / Linear tickets, email patch threads, + Zeta's future native coordination host, or another review + host; notifications, review discussion, dashboards, and + richer comments. + +Remote-only mode is intentionally enough by itself. A local +broadcast bus, Reticulum mesh, Slack channel, or other +side-channel may be useful later, and Zeta uses GitHub as its +host adapter today, but those must remain adapters over this +protocol, not hidden prerequisites. The long-horizon target is +self-sufficiency: Zeta should eventually be able to host the +same coordination primitives itself while preserving this +git-native fallback path. + ### Shared machine / shared folder mode This section applies when two or more agents (or a human plus diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index e11f1564c5..2bac007646 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -164,6 +164,7 @@ are closed (status: closed in frontmatter)._ - [ ] **[B-0197](backlog/P2/B-0197-lean-prop-3-5-misattribution-cleanup-aaron-2026-05-05.md)** Lean DbspChainRule + chain-rule-proof-log -- correct Prop 3.5 misattribution to Theorem 3.3 (Aaron 2026-05-05) - [ ] **[B-0206](backlog/P2/B-0206-claude-code-env-mapping-skill-with-carved-sentences-references-ts-files-aaron-2026-05-05.md)** Claude Code environment-mapping skill with carved-sentences-in-behavior referencing existing capability-maps + our TS files - [ ] **[B-0208](backlog/P2/B-0208-launchd-forward-tick-reliability-merge-into-heartbeat-2026-05-06.md)** Launchd forward-tick reliability — merge forward logic into working heartbeat tick OR fix StartInterval for new services +- [ ] **[B-0209](backlog/P2/B-0209-remote-only-background-agent-test-matrix-and-model-scouting-2026-05-06.md)** Remote-only background agent test matrix — prove claim coordination without local broadcast ## P3 — convenience / deferred diff --git a/docs/backlog/P2/B-0209-remote-only-background-agent-test-matrix-and-model-scouting-2026-05-06.md b/docs/backlog/P2/B-0209-remote-only-background-agent-test-matrix-and-model-scouting-2026-05-06.md new file mode 100644 index 0000000000..1af41ac2de --- /dev/null +++ b/docs/backlog/P2/B-0209-remote-only-background-agent-test-matrix-and-model-scouting-2026-05-06.md @@ -0,0 +1,82 @@ +--- +id: B-0209 +priority: P2 +status: open +title: "Remote-only background agent test matrix — prove claim coordination without local broadcast" +created: 2026-05-06 +last_updated: 2026-05-06 +depends_on: + - B-0016 + - B-0068 + - B-0208 + - B-0202 +--- + +# B-0209 — Remote-only background agent test matrix + +## Problem + +The local broadcast bus is useful on the maintainer's Mac, but it is +a cheat if the claim protocol is supposed to onboard agents that do +not share a filesystem, heartbeat directory, terminal, or local +worktree. Zeta needs a repeatable way to prove that two or more +agents can coordinate using only remote git plus an optional host +adapter. + +## Desired outcome + +Create a small background-agent test matrix that deliberately denies +the agents access to local broadcast state while they coordinate +through `origin/claim/*`, claim progress commits, and optional host +comments. + +The test should answer: + +- Can two agents discover each other's claims using only remote refs? +- Can they avoid overlapping path sets without shared local files? +- Can asks, offers, receipts, and blockers move through claim-file + progress commits when no host comments exist? +- When a host adapter exists, do GitHub PR / issue comments improve + latency without becoming a required dependency? +- Which harnesses and models are reliable enough for background + work, and at what cost? + +## Candidate modes + +- **Git-only remote mode:** bare git remote plus pushed + `claim/` branches; no GitHub API, no broadcast folder. +- **GitHub-adapted mode:** Zeta's current production path; git + claims plus PR / issue comments and CI checks. +- **Local-model scout mode:** local models on the maintainer's + machine act as low-cost remote-only agents while denied broadcast + access. +- **Reticulum / mesh adapter mode:** transport experiment for + local or multi-host agent messages, kept as an adapter over the + git-native protocol. + +## Long arc + +GitHub is Zeta's current host adapter, not the final dependency. The +test matrix should preserve a git-only path, a GitHub-adapted path, +and a future Zeta-native host path. That keeps the near-term factory +practical while leaving the self-sufficiency route open. + +This composes with the longer hardware and microkernel backlog: + +- B-0016 carries the "no software dependencies / hardware bootstrap / + microkernel" arc. +- B-0068 carries the local-model, hardware-aware scouting lane. +- B-0202 carries the one-symbolic-IR-to-all-hardware kernel-layer + direction. + +The immediate task is modest: prove remote-only coordination without +local broadcast. The long-horizon target is stronger: Zeta eventually +hosts the coordination surface itself, down toward the kernel and +hardware substrate, without losing the remote-git fallback. + +## Notes + +This is a throughput and reliability project, not a replacement for +the claim protocol. The protocol must remain usable by a single +external agent that receives only +`docs/AGENT-CLAIM-PROTOCOL.md` and a task URL.