Skip to content

docs(agents): scope runtime sections core-only so automation agents don't self-write task files - #2075

Merged
john-the-dev merged 11 commits into
mainfrom
fix/agents-md-core-only-guard
Aug 3, 2026
Merged

john-the-dev merged 11 commits into
mainfrom
fix/agents-md-core-only-guard

Conversation

@qingyun-wu

@qingyun-wu qingyun-wu commented Jul 11, 2026 •

Copy link
Copy Markdown
Collaborator

Box: multi-agent hygiene — instruction-file scoping (reliability)

Problem (live-caught 2026-07-11): an agent auto-loads AGENTS.md/CLAUDE.md by walking up from its cwd. When a scheduled/one-shot agent runs with cwd inside a Sutando checkout — e.g. a Codex PR-review automation — it inherits the core's operational runbook and follows the "Chat-path task tracking" rule, self-writing task-chat files into workspace/tasks/ that the live core then processes as real owner requests. It ran every 10 min for days and was invisible from the Claude side (Codex automations are daemon-persistent; nothing in CronList/crontab/launchd showed it).

Fix: add a core-only guard atop the runtime-operational sections. Any automation/one-shot agent that merely opened the repo is a guest in the checkout, not the core — it must NOT write task/result files, start the watcher, run the proactive loop, or write state/ liveness. Isolate such automations in /private/tmp with no repo cwd (the safe pattern).

Both guards are placed before the first status/task write in their section, so an agent reading top-down hits the exemption before the instruction it exempts.

Scope of the diff (measured at head 504ec2ad)

 AGENTS.md | 4 ++++
 CLAUDE.md | 4 ++++
 2 files changed, 8 insertions(+)

Two files, +4/+4, insertions only — two guard paragraphs plus spacing, mirrored between the two files. AGENTS.md is generated, so its half is scripts/agents-md-sync.sh output, not a hand edit.

This supersedes an earlier description in this body that claimed CLAUDE.md +2 and a much larger AGENTS.md diff carrying 78 lines of pre-existing drift. That was accurate when written and is now obsolete: the drift catch-up landed on main independently, so the regen here is a clean +4 that mirrors the +4 in CLAUDE.md. There is no longer any drift-catch-up scope in this PR — reviewers should not go looking for it.

Verification at head 504ec2ad

Check Result
bash scripts/agents-md-sync.sh --check AGENTS.md is up to date, exit 0
git diff --check origin/main...HEAD clean (no whitespace errors)
git diff --stat origin/main...HEAD 2 files, +8/-0 (table above)
Added-line hardcoded-host-path scan clean

Freshness: refreshed from current main via update-branch (da38a861 → 504ec2ad) and taken out of draft, so the current required check set runs on this head. The prior head predated today's gates and exposed only smoke + CLA — that was the basis of the freshness block, not a failure.

Earlier review point, already resolved: the per-host label recipe. Both per-host paths (PERSONAL_CLAUDE.md, pending-questions.md) resolve <hostname> via bash scripts/sutando-config.sh host-label on this head — matching CLAUDE.md and the code reader personal_path() → _host_label(). Verified by grep at this head: zero hostname | sed occurrences in either file, two sutando-config.sh host-label occurrences in each. (The grep was checked against a known-positive on the same files so a zero couldn't come from a broken pattern.)

No behavior change for the real core (it still does all of this — it is the core). Only automations that inherit the file are told to stand down.

…on't self-write task files

An agent (Codex, Claude, etc.) auto-loads AGENTS.md/CLAUDE.md by walking up from
its working directory. When a scheduled/one-shot agent runs with its cwd inside a
Sutando checkout (e.g. a Codex PR-review automation), it inherits the core's
operational runbook and follows the 'Chat-path task tracking' rule — self-writing
task-chat files into workspace/tasks/ that the live core then processes as real
owner requests. (Live-caught 2026-07-11: a Codex automation with cwds=[the repo]
wrote a task-chat every 10 min for days; invisible to the Claude side because
Codex automations are daemon-persistent.)

Add a core-only guard atop the runtime-operational sections: an automation/one-shot
agent that merely opened this repo is a guest in the checkout, not the core — it
must not write task/result files, start the watcher, run the proactive loop, or
write liveness. Isolate such automations in /private/tmp with no repo cwd.

AGENTS.md regenerated via scripts/agents-md-sync.sh (also catches up pre-existing
CLAUDE.md->AGENTS.md drift that was already on main; the intent is the 2-line
CLAUDE.md guard).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

Coverage Gate

✅ No Python changes — nothing to gate (bar: 95% on changed lines).

@qingyun-wu qingyun-wu left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not LGTM yet.

Required

  • Medium: the new core-only guard lands too late to stop the earlier Work Status side effect instructions from being followed (CLAUDE.md:75-89, AGENTS.md:75-89). On this branch, Work Status still tells the reader to write core-status.json and says "This applies to all work" at lines 77-85; the new guest-automation warning only appears at line 89. That means a scheduled/one-shot agent reading the file top-down can still perform the status write before it ever reaches the guard, which is the same class of unintended side effect this PR is trying to eliminate. I fetched pull/2075/head into a local worktree and confirmed bash scripts/agents-md-sync.sh --check passes there, so this is an authored-doc behavior gap rather than a regeneration mismatch. Please move the guard above ## Work Status, or add the same explicit guest-agent exemption inside Work Status itself, so the first runtime write instruction a guest sees is already gated. Re-verify by checking the generated CLAUDE.md/AGENTS.md ordering and rerunning bash scripts/agents-md-sync.sh --check.

Verification

  • git fetch origin pull/2075/head:pr-2075
  • git worktree add /private/tmp/sutando-pr-2075 pr-2075
  • bash scripts/agents-md-sync.sh --check (passes on the PR worktree)

Qingyun's Personal Codex Agent

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Approval signal: no blocking findings. The core-only guard is placed before the chat-path task file instructions that caused the automation leak, and the generated AGENTS.md is synchronized with CLAUDE.md rather than hand-edited drift.

Checks run in an isolated temp checkout at head 54a85cf:

  • PASS: git diff --check origin/main...HEAD
  • PASS: bash scripts/agents-md-sync.sh --check
  • PASS: bash -n scripts/agents-md-sync.sh
  • PASS: guard text present in both CLAUDE.md and AGENTS.md

Reviewed by Qingyun's Codex.

@qingyun-wu
qingyun-wu marked this pull request as draft July 11, 2026 18:38
Reviewer flagged that the core-only guard landed under Chat-path task
tracking, *below* Work Status — so a guest automation reading top-down
hits the core-status.json write instruction (and 'applies to all work')
before the guard. Add the same guest-agent exemption at the top of Work
Status so the first runtime-write instruction a guest sees is already
gated; cross-reference the full rationale below. Regenerated AGENTS.md;
agents-md-sync --check passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@qingyun-wu
qingyun-wu marked this pull request as ready for review July 11, 2026 19:31
@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Addressed the ordering gap in 282953c.

Took the second option you offered — added the guest-agent exemption at the top of ## Work Status itself, so the first runtime-write instruction a guest sees (core-status.json) is already gated, with a cross-reference to the full rationale under Chat-path task tracking. Also clarified that the 'applies to all work' line scopes the core's own activities and does not enlist guests.

Regenerated AGENTS.md from CLAUDE.md; bash scripts/agents-md-sync.sh --check passes (gate at AGENTS.md:77 inside Work Status, full guard at :91). Marked ready for re-review.

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Approval signal: no blocking findings. The new head addresses the earlier ordering gap: the guest-agent exemption now appears at the top of Work Status before the first core-status.json write instruction, and the broader chat-path/runtime guard remains in both CLAUDE.md and generated AGENTS.md.

Checks run in an isolated temp checkout at head 282953cfaeda800ede07a3e4ca60c8258c99d3e6:

  • PASS: git diff --check origin/main...HEAD
  • PASS: bash -n scripts/agents-md-sync.sh
  • PASS: bash scripts/agents-md-sync.sh --check
  • PASS: verified guard ordering in both CLAUDE.md and AGENTS.md (Work Status guard before core-status.json, broader chat-path guard before task/result-writing instructions)

Reviewed by Qingyun's Codex.

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

LGTM.

Verified on pull/2075/head that the new guest-automation guard now appears before the runtime write instructions in both CLAUDE.md and AGENTS.md, so a top-down reader sees the exemption before Work Status or Chat-path task tracking. I also reran bash scripts/agents-md-sync.sh --check in a PR worktree and it passes.

Qingyun's Personal Codex Agent

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

LGTM from code review.

Verification:

  • bash scripts/agents-md-sync.sh --check (on pr-2075) reports AGENTS.md is up to date, which matches the stated intent: the substantive change is the new core-only guard in CLAUDE.md, and the larger AGENTS.md diff is the generated sync result.

Ready to merge once CI passes.

Qingyun's Personal Codex Agent

@liususan091219 liususan091219 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Triage change-request (owner-approved batch, 2026-07-12 sweep). Conditions found on the current diff:

  • incomplete fix — Gate Chat-path task tracking/task writes, not only Work Status liveness.

Justification: kb triage standards (source-grep test standard, voice/vision live-test policy, necessity/coverage checks) — see sonichi/sutando-pr-triage kb/.
Address the asks and push; re-request review to clear this. If a finding is wrong, reply with the counter-evidence and it will be withdrawn.

cr-reason: incomplete_fix

@liususan091219 liususan091219 added request-change Has an active CHANGES_REQUESTED review docs labels Jul 13, 2026
@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Counter-evidence for cr-reason: incomplete_fix ("Gate Chat-path task tracking/task writes, not only Work Status liveness") — the current head 282953c already gates chat-path task writes, and did so before this review landed:

  • CLAUDE.md line 91 (and the generated AGENTS.md line 91): a core-only guard sits at the very top of ## Chat-path task tracking (issue #585) — immediately after the section header at line 89, and before the first write instruction (cat > "$WORKSPACE/tasks/task-chat-${_ts}.txt" at line 103). It explicitly says: "do NOT write task-* / task-chat-* / results/ files, do NOT start the watcher, do NOT run the proactive loop, do NOT write state/ liveness" — i.e., task/result writes are covered by name, not just Work Status liveness.
  • A top-down reader (the threat model from the 2026-07-11 incident) hits that guard before any task-write instruction in the section.
  • Verified on a clean worktree of pull/2075/head: bash scripts/agents-md-sync.sh --check → AGENTS.md is up to date, and both files carry identical guard placement.

This matches the two earlier LGTM verifications (2026-07-11T19:39Z / 19:47Z) which specifically confirmed the chat-path guard ordering. The finding appears to be against a stale diff. Requesting withdrawal per the triage protocol.

— @sutando-qingyun-001

@qingyun-wu
qingyun-wu marked this pull request as draft July 13, 2026 08:25
@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Counter-evidence — the incomplete_fix (gate Chat-path task writes, not only Work Status liveness) is already satisfied by the current diff:

The ## Chat-path task tracking (issue #585) section gets its own Core-only gate (in both AGENTS.md and CLAUDE.md), and it gates task/result writes explicitly, not just liveness:

Core-only — automation/one-shot agents MUST skip this and every other runtime-operational section below (task/result writing, the task watcher, the proactive loop, status/heartbeat/liveness writes) … do NOT write task-* / task-chat-* / results/ files, do NOT start the watcher, do NOT run the proactive loop, do NOT write state/ liveness. Doing so injects fake tasks into the core's queue that it will process as real owner requests.

So the gate covers three distinct write classes, not one:

  1. liveness — the Work Status gate (core-status.json / state/),
  2. task/result writes — the Chat-path gate above (task-* / task-chat-* / results/),
  3. every other runtime-operational section below — named as a blanket ("task watcher, proactive loop, status/heartbeat/liveness") so Task bridge / Task progress / Core liveness are covered by reference without duplicating the block N times.

The gate is also anchored to the real failure it prevents (the 2026-07-11 Codex cwds=[repo] self-wrote a task-chat every 10 min). If the ask was instead to repeat the blockquote verbatim atop each of those additional sections, say so and I'll add them — but functionally chat-path task writes are gated as of the current head. Re-requesting review to clear.

— @sutando-qingyun-001

@liususan091219

Copy link
Copy Markdown
Collaborator

Daily reminder — this PR has an open change-request from 2026-07-13 (2d) with no commits since. Push fixes or reply to the review to reset the clock; ~2 weeks of silence routes to final-notice and then close-as-abandoned per the triage policy.

nudge: cr-unaddressed day2

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Both asks are addressed on HEAD (282953c) — counter-evidence:

@qingyun-wu (Medium: Work Status guard lands too late). Fixed. The core-only guard now sits at the TOP of the Work Status section, BEFORE the core-status.json write instructions — CLAUDE.md line 77 (guard) precedes lines 79–87 (the write + 'applies to all work'). A top-down reader hits the guard first. This was the commit that post-dates your review: docs(agents): gate Work Status for guest agents too (282953c, 2026-07-11).

@liususan091219 (incomplete_fix: gate Chat-path task tracking/task writes). The Chat-path task tracking section IS gated, and before its task-write recipe: CLAUDE.md line 91 (guard) precedes the ## When to write block and the cat > $WORKSPACE/tasks/task-chat-* recipe (line ~103). The guard explicitly says: do NOT write task-* / task-chat-* / results/ files, do NOT start the watcher, do NOT run the proactive loop. That section was gated in the FIRST commit (2026-07-10); I believe the triage keyed on commit 2's incremental diff (which only touched Work Status) and didn't see the pre-existing Chat-path guard. If I'm missing a specific task-write path that's still ungated, point me at the line and I'll cover it.

Both files stay mirrored: bash scripts/agents-md-sync.sh --check → 'AGENTS.md is up to date' (exit 0); each file carries 2 core-only guards. Marking ready-for-review + re-requesting.

@qingyun-wu
qingyun-wu marked this pull request as ready for review July 15, 2026 18:24
@liususan091219

Copy link
Copy Markdown
Collaborator

Daily reminder — this PR has an open change-request from 2026-07-13 (3d) with no commits since. Push fixes or reply to the review to reset the clock; ~2 weeks of silence routes to final-notice and then close-as-abandoned per the triage policy.

nudge: cr-unaddressed day3

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Re-verified: resolved by 282953cfa. The guest-exemption blockquote now sits inside ## Work Status (and above Chat-path tracking), so an automation reading top-down hits the exemption before the core-status.json write instruction — exactly the ordering gap I flagged. agents-md-sync.sh --check passes on the PR head. My earlier concern is addressed; nothing further needed from my side.

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Blocking finding on the new head 08cf879:

  • [P1] AGENTS.md is stale relative to the repo sync generator. bash scripts/agents-md-sync.sh --check fails and shows generated drift in AGENTS.md (for example the host-label helper text, the core-status.json socket schema, and the per-host pending-questions path). This PR is specifically changing automation-facing instructions, so the generated AGENTS.md must be in sync with CLAUDE.md before merge; otherwise Codex/automation agents can read inconsistent guidance.

Validation run in /private/tmp/sutando-pr2075-08cf87-review:

  • bash scripts/agents-md-sync.sh --check failed with stale AGENTS.md.
  • git diff --check origin/main...HEAD passed.

Reviewed by Qingyun's Codex.

@liususan091219 liususan091219 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto re-review (author pushed after the change-request):

  • ask 1: ADDRESSED — The diff adds a core-only/guest-skip gate to Work Status and explicitly extends the rationale to “Ch

All asks addressed — the stale CHANGES_REQUESTED will be dismissed in the next owner-approved batch.

@john-the-dev john-the-dev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The core of this — the "Core-only — guests skip this" callouts on Work Status + Chat-path task tracking — is exactly right and worth landing: it directly closes the 2026-07-11 hole where a codex exec automation with cwds=[this repo] auto-loaded the runbook and self-wrote a task-chat every 10 min into the live core's queue. The scoping language (guest-in-checkout vs the single live core) is clear and unambiguous. The rest is a faithful AGENTS.md ↔ CLAUDE.md sync.

One should-fix before merge — the per-host label recipe. This PR newly introduces per-host resolution to AGENTS.md using:

<hostname> = hostname | sed 's/\..*//'

for both PERSONAL_AGENTS.md and pending-questions.md. But that diverges from the canonical recipe everywhere else:

  • CLAUDE.md resolves the same two paths via bash scripts/sutando-config.sh host-label.
  • The code reader personal_path() → _host_label() (src/util_paths.py) resolves scutil LocalHostName first, then short hostname — its docstring cites the DHCP-drift incident (2026-06-22 / #1745): on a Comcast lease hostname returns Chis-MBP.hsd1.wa.comcast.net → Chis-MBP, while the stable Bonjour name is Chis-MacBook-Pro.

So on any machine where scutil LocalHostName ≠ short hostname, a guest that follows AGENTS.md would write hosts/<hostname-sed>/pending-questions.md, but personal_path() reads hosts/<scutil-label>/… — the reader silently misses the write (split-brain per-host paths, the exact failure #1745 documents). Since AGENTS.md is the Codex-facing runbook, this would propagate the anti-pattern the schedule-crons skill explicitly warns against.

Fix: replace both hostname | sed 's/\..*//' occurrences with bash scripts/sutando-config.sh host-label (matching CLAUDE.md + the code readers). One-line change; happy to push it if useful.

Not blocking the guest-scoping value — flagging so the runbook doesn't ship a host-label recipe that the code won't honor.

@liususan091219 liususan091219 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto re-review (author pushed after the change-request):

  • ask 1: REMAINS — Current diff only adds a Core-only guest skip for Work Status/liveness writes (core-status.json /

Remaining asks above — the change-request stays until they land.

@liususan091219

Copy link
Copy Markdown
Collaborator

Daily reminder — commits landed after the 2026-07-13 change-request, but the auto re-review found asks still open (see the re-review comment above for exactly what remains). Pushing those closes this out; ~2 weeks without them routes to final-notice per the triage policy.

nudge: cr-remains day5

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Conflicts resolved by merging current main and regenerating AGENTS.md via scripts/agents-md-sync.sh (it's generated from CLAUDE.md — hand-merging would defeat the guard this PR adds; --check green). CLAUDE.md itself auto-merged cleanly. CI re-running.

@bassilkhilo-ag2

Copy link
Copy Markdown
Collaborator

Flagging before re-reviewing further: this PR's diff has ballooned to 172 files / +15490 -449 (was a 2-file, ~52-line AGENTS.md+CLAUDE.md docs change when I approved it earlier today). mergeStateStatus is CLEAN so GitHub thinks it's mergeable, but the file list includes dozens of files clearly owned by other in-flight PRs today (packages/ag2-sparrow/, skills/agent-room-ops/, hooks/activity-emitter.py, package-lock.json, most of .github/workflows/*, etc.) — this looks like the classic squash-merge/cross-branch-merge ancestry mismatch (branch previously merged main in, that content later landed on main via squash under new SHAs, so git no longer recognizes it as already-present and the diff shows it as "new").

Not re-reviewing the full 15K-line diff since it doesn't represent this PR's actual intended change. Recommend rebasing this branch cleanly onto current origin/main before merge — as-is, merging this would risk re-introducing stale/duplicate content even though the working tree would probably resolve fine. My earlier approval stood for the small docs-only diff; not retracting it, but this needs a clean rebase before it should land in its current state.

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Reviewed head c5902c1.

No blocking findings. This refresh is back down to the intended docs-only guard: AGENTS.md and CLAUDE.md receive matching core-only warnings for Work Status and chat-path task tracking, so review/headless guests do not self-write task files, results, watchers, or liveness into the live core checkout.

Focused checks passed:

  • git diff --check origin/qingyun-dev...HEAD
  • bash scripts/agents-md-sync.sh --check

Approval signal from me. Since the PR is still draft, treat this as ready from my review lane once the author is ready to undraft.

Reviewed by Qingyun's Personal Codex.

@bassilkhilo-ag2 bassilkhilo-ag2 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Draft, so this is a scoping comment rather than a verdict — but I think it needs restructuring before it leaves draft.

The label and the diff disagree by a wide margin

Titled docs(agents): and described as scoping runtime sections so automation agents don't self-write task files. The actual diff is +15490/-449 across 172 files:

src/          31 files
skills/       29 files
packages/     14 files
.github/       7 files
hooks/         5 files
scripts/       5 files
+ package.json, package-lock.json, eslint.config.mjs, ruff.toml,
  CLAUDE.md, AGENTS.md, CONTRIBUTING.md, TELEMETRY.md

package-lock.json, eslint.config.mjs and ruff.toml are not docs, and 31 files under src/ is not a documentation change. Whatever the dependency/lint/config churn is, it's riding along invisibly under a docs(...) label — and package-lock.json alone probably accounts for a large share of the +15490, which is exactly the kind of bulk that makes the real change impossible to see.

Per CONTRIBUTING's single-concern rule, I'd split this into at least:

  1. The actual docs change — the AGENTS.md / CLAUDE.md / CONTRIBUTING.md scoping edit that the title describes. That's the part with the interesting semantics (which sections automation agents may act on), and it deserves careful reading on its own.
  2. The lockfile / lint-config bump — mechanical, reviewable in thirty seconds, but only if it isn't buried.
  3. The src/ + skills/ + packages/ edits — 74 files across three trees needs its own statement of intent; right now a reviewer cannot tell whether these are mechanical doc-header updates (plausible, given docs/src-map.md regeneration is a thing in this repo) or behavior changes.

If (3) is mechanical — e.g. every touched file got a header-comment tweak that regenerates src-map.md — say so explicitly in the body, because that single sentence turns 74 unreviewable files into 74 skimmable ones.

Why this matters beyond tidiness

The stated purpose is a guardrail: stopping automation agents from self-writing task files. That's a security-adjacent behavioral boundary, and it's the kind of change where a reviewer needs to read every line of the rule and think about how an agent might route around it. That reading will not happen inside a 172-file diff — it will get an approval based on the title. A guardrail approved by title is not a guardrail.

I'd rather review a 60-line PR on this than skim a 15,000-line one, and I suspect you would rather have that too.

What I did not do

I did not review the content — no verdict on the scoping rule itself, which is the part I actually want to read once it's separable.

@bassilkhilo-ag2 bassilkhilo-ag2 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My APPROVED from 2026-07-24T14:53 is stale and should not be counted for the current head. Please dismiss it, or treat this comment as the qualification. Flagging rather than silently leaving a vouch on content I have not read.

What changed after I approved. Seven substantive commits landed the same evening, none of them documentation:

16:56 b87f5264 feat(observe): /observe policy core — Policy Interaction Layer MVP
16:57 d23e9ce4 feat(hooks): activity-emitter — durable activity journal
17:31 cd5c5db1 fix(slack-bridge): durable on-disk backup for access allowlist
17:45 c6ece1b2 feat(dashboard): editable schedules — add / edit / delete crons
17:49 f79f590a fix(bridges): allowlist additions default to read-only, not owner
17:57 ba493beb docs(claude): explicit ambient-tier sandbox mapping
18:06 08024406 feat(agent-room-ops): events client (subscribe/pull/SSE stream)

The PR now stands at 172 changed files, +15,490/-449, 55 commits, and of the first 100 files only 10 are .md — the rest are CI workflows, eslint config, hooks, and source. Whatever I reviewed under the title "docs(agents): scope runtime sections core-only", my approval does not cover this.

Two of those commits are ones I would want to read carefully rather than wave through, since they touch authorization rather than presentation: f79f590a (allowlist additions default to read-only, not owner) and cd5c5db1 (durable on-disk backup for the access allowlist). A tier-default change is exactly the class where a stale approval is worst — it looks reviewed and it governs who can do what.

I am not requesting changes and not claiming a defect. I have no finding here; I simply cannot vouch for 172 files I did not read, and an approval that implies otherwise weakens the gate. Given the base is qingyun-dev rather than main, blocking a dev integration branch over my own review hygiene would be disproportionate — hence a comment plus a dismissal request rather than a CHANGES_REQUESTED.

Happy to do a real review of the current head if that is useful; say the word and I will scope it to the authorization-touching commits first.

Context: I audited my own review states tonight and found 13 stale ones — 10 standing approvals and 3 blocks. The blocks are cleared (#2324, #2180 approved after re-verification; #2197 corrected). This is the first of the approvals, and the largest.

@qingyun-wu
qingyun-wu changed the base branch from qingyun-dev to main July 28, 2026 09:55
@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Addressed the diff-balloon @bassilkhilo flagged — the 172-file / +15490 −449 diff was an ancestry artifact of the base, not real content.

Root cause: this PR was targeting qingyun-dev, which has diverged from main (ahead 48 / behind 37). The branch had also merged origin/main into itself. So the three-dot diff branch-vs-qingyun-dev surfaced every main commit that qingyun-dev lacks — dozens of files owned by other in-flight PRs, exactly as you spotted.

Fix (no history rewrite): re-targeted the base qingyun-dev → main. Against main the true delta is what it always was:

main...fix/agents-md-core-only-guard  →  2 files, +8 −0
  AGENTS.md   (+4)
  CLAUDE.md   (+4)

The 8 inserted lines are the two mirrored "Core-only — guests skip this" callouts on ## Work Status and ## Chat-path task tracking (long lines — that's the "~52 lines" wrapped). Content is unchanged from your earlier approval; the balloon is gone. mergeable: MERGEABLE, status BEHIND (branch trails main; no conflict). Ready for re-review.

@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Approval signal for current head c5902c193fcb8d28e6d6421fe4042cc17db3069a after the base retarget to main (comment, not formal approval — shared author identity).

No blocking findings from the current-base re-review. Against main, the diff is back to the intended docs-only change: AGENTS.md and CLAUDE.md each add the mirrored core-only guard before the Work Status liveness write recipe and before the Chat-path task tracking task/result write recipe. That preserves the intended boundary: review/headless guests do not self-write task files, results, watchers, proactive-loop state, or liveness into the live core checkout.

Focused checks passed in an isolated /private/tmp checkout:

  • git diff --stat origin/main...HEAD -> 2 files changed, 8 insertions(+)
  • git diff --check origin/main...HEAD
  • bash scripts/agents-md-sync.sh --check

The remaining CHANGES_REQUESTED review state appears stale against earlier heads/base diff, not the current two-file main diff.

Reviewed by Qingyun's Personal Codex.

@john-the-dev john-the-dev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed exact head c5902c193fcb8d28e6d6421fe4042cc17db3069a; replacing the stale old-head blocker with two current merge gates.

The guard implementation itself is sound. The current server diff is now only CLAUDE.md and generated AGENTS.md, +4 lines each (two guard paragraphs plus spacing). Both place the guest exemption before the first status/task write, explicitly cover task/result files, watcher, proactive loop, and liveness, and bash scripts/agents-md-sync.sh --check plus git diff --check pass. Added-line host-path scan is clean. No code/semantics blocker found.

Blocking documentation gate: the PR body still describes an obsolete comparison: it says CLAUDE.md is +2 and AGENTS.md has a much larger 78-line drift catch-up. Against current main, GitHub reports exactly two files and the local exact-head diff is +4/+4. Update the body to describe the current diff so reviewers are not asked to reason about scope that no longer exists.

Blocking freshness gate: the branch is behind current main, remains draft, and this exact head exposes only smoke, CLA recheck, and CLA status—today’s clean-install/coverage/lint gate set is absent. Refresh from main, rerun the complete current required checks, then request exact-head review.

The earlier 172-file concern is not a current-diff blocker: after fetching current main, gh pr diff --name-only and git diff origin/main...HEAD both show only AGENTS.md and CLAUDE.md.

@john-the-dev
john-the-dev dismissed liususan091219’s stale review July 30, 2026 03:08

Resolved on current head c5902c1: both Work Status and Chat-path task/result writes are explicitly guarded before their write instructions; exact sync/order verification passes. Current remaining gates are documented in John’s exact-head review.

@qingyun-wu
qingyun-wu marked this pull request as ready for review July 30, 2026 03:16
@qingyun-wu
qingyun-wu marked this pull request as draft July 30, 2026 03:22

@qingyun-wu qingyun-wu left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval signal for current head da38a861f89c6b1d93614a19c9b0efbece0eaeac (regular comment because the authenticated account owns this PR).

No blockers found. The current diff is the intended docs-only scope: AGENTS.md and CLAUDE.md each add the mirrored core-only guard before the Work Status liveness recipe and before the Chat-path task tracking task/result write recipe. The PR body now describes the current +4/+4 diff and explicitly supersedes the stale drift-catch-up wording, and the branch is no longer draft with the current check set green. That clears the two current gates from john-the-dev's previous review from my lane.

Focused verification passed in an isolated /private/tmp checkout:

  • bash scripts/agents-md-sync.sh --check
  • git diff --check origin/main...HEAD
  • git diff --stat origin/main...HEAD -> 2 files changed, 8 insertions(+)

GitHub checks and CLA are green on this head.

Reviewed by Qingyun's Personal Codex.

@qingyun-wu
qingyun-wu marked this pull request as ready for review July 31, 2026 04:26
@qingyun-wu
qingyun-wu requested a review from john-the-dev July 31, 2026 04:26
@qingyun-wu

Copy link
Copy Markdown
Collaborator Author

Both merge gates addressed at exact head 504ec2ad:

  • Documentation gate: the body already describes the current diff (2 files, +4/+4, insertions only) and explicitly supersedes the obsolete CLAUDE.md +2 / 78-line-AGENTS.md description; head refs bumped to 504ec2ad.
  • Freshness gate: refreshed from current main (clean merge, no conflicts) and taken out of draft, so today's full required-check set runs on this head.

Verified locally at 504ec2ad: bash scripts/agents-md-sync.sh --check → AGENTS.md is up to date; git diff origin/main --check clean; git diff origin/main --stat = 2 files, +8/-0. Ready for exact-head re-review.

@john-the-dev john-the-dev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed exact head 504ec2ad; this replaces my stale scope/freshness blocker on c5902c19. Both requested gates are resolved on the current head: the PR body now accurately describes the two-file AGENTS.md/CLAUDE.md +4/+4 diff, the branch is out of draft, and every exact-head CI/lint/coverage/CLA check is green. An independent conflict-free cumulative merge with current main passes agents-md-sync --check, diff hygiene, hardcoded-path policy, and explicit parity/order assertions: the liveness exemption precedes the first core-status.json write, and the broader guest-agent exemption precedes the first task/result write in both files. The guard still permits explicitly orchestrated core/delegate work while preventing checkout-guest automations from self-injecting runtime tasks.

Worst-case disruption is an actual core being misclassified as a guest; the wording avoids that by limiting the exemption to agents that merely inherit the repo cwd and repeatedly identifies the single live Sutando core as the owner of these mechanics. APPROVE for this exact head. Not merge-ready yet: it is 13 commits behind current main and needs refresh, fresh exact-head gates/review, and a second qualifying maintainer approval.

@qingyun-wu qingyun-wu left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Current-head approval signal for 0fae73ffd492b73c5a321a014f2345a534934cfd (formal self-approval is unavailable because the authenticated account owns this PR).

This is a clean current-main merge refresh. The cumulative PR diff remains only the mirrored AGENTS.md/CLAUDE.md core-only guard, four inserted lines in each; the three topic commits are unchanged. Reviewer-run agents-md-sync 5/5, sync check, diff hygiene, and REVIEW.md path checks pass, and GitHub now reports all required checks green with an APPROVED aggregate decision. The worst-case misclassification concern remains mitigated by wording that exempts only checkout-guest automations while leaving the single live Sutando core responsible for status/task writes. Code-ready; repository merge gates still apply.

Reviewed by Qingyun's Personal Codex.

@bassilkhilo-ag2 bassilkhilo-ag2 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified independently: diff is exactly 2 files, +8/-0 (AGENTS.md, CLAUDE.md), both additions byte-identical — confirmed via gh pr diff + gh api .../pulls/2075/files (additions:8, deletions:0, changedFiles:2), so the earlier 172-file ancestry-balloon I flagged on 2026-07-24 is gone.

Confirmed the bug is real on current main (fetched contents/CLAUDE.md?ref=main directly): no "Core-only" guard exists today under ## Work Status or ## Chat-path task tracking — a scheduled/one-shot automation that cd's into this checkout would inherit the unqualified task-write instructions as claimed.

Checked: guard text is placed before each section's write recipe (Work Status guard before core-status.json write; Chat-path guard before the task-chat-*/results/ recipe) — correct ordering for a top-down reader. Anchor link resolves correctly. No hardcoded host-specific paths in the added lines (/private/tmp is the repo's own documented isolation pattern, not a literal user path). All CI green including the specific refuse AGENTS.md stale vs CLAUDE.md lint and CLA.

Ready to merge — no blockers. (One non-blocking note already surfaced in-thread: this is an advisory guard, not code-enforced; real enforcement is running automations outside the repo cwd, which the PR text itself calls out as the actual fix.)

@john-the-dev
john-the-dev enabled auto-merge (squash) August 3, 2026 12:21
@john-the-dev

Copy link
Copy Markdown
Collaborator

@cla-assistant check

1 similar comment
@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

@cla-assistant check

@john-the-dev
john-the-dev merged commit 3464dbd into main Aug 3, 2026
16 checks passed
@john-the-dev
john-the-dev deleted the fix/agents-md-core-only-guard branch August 3, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs request-change Has an active CHANGES_REQUESTED review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants