docs: update wait race docs for auto cursor threading (#2323) [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from 6e0ddf4:

• docs/reference/agent-wait-patterns.md: The "Race: send → wait" subsection
  described manual --since anchoring as the way to get zero-drop semantics.
  With BRC reviewer wait-loop misses proposals between calls — review of multi-producer phase stalls 30+ min #2323, cursor threading across wait-loop re-entries is automatic when
  EGG_AGENT_ROLE is set. Updated the section to note this, and repositioned
  the manual --since pattern as an edge-case fallback for shell scripts using
  wait --json directly.
• docs/reference/orchestrator-cli.md: Updated the message wait and
  message wait-loop table entries to replace "pass --since <id> for
  zero-drop send→wait semantics" with a note that cursor threading is automatic
  (issue BRC reviewer wait-loop misses proposals between calls — review of multi-producer phase stalls 30+ min #2323).

Triggered by: 6e0ddf4 (Fix #2323: --cursor-file on wait/wait-loop closes wait→process→wait race)

Authored-by: egg

[egg-reviewer]

Review summary

Documentation-only PR. The technical claims line up with the implementation introduced in 6e0ddf4 / PR #2326:

• _wait_cursor_path in sandbox/egg_lib/orch_cli.py:1279 returns None when EGG_AGENT_ROLE is unset, falling back to legacy from-tip behavior — matches the "automatic when EGG_AGENT_ROLE is set" qualifier in orchestrator-cli.md.
• Forward reference "see 'Auto cursor threading' below" lands on the existing §"Auto cursor threading (issue #2323)" added by the same upstream commit.
• Issue #2323 referenced correctly throughout.

No blocking issues. Two non-blocking observations:

1. Intro paragraph and example contradict each other (agent-wait-patterns.md:355-365)

The new intro says:

For shell scripts that use wait --json directly and need explicit cursor control, the manual anchor pattern remains available:

But the example below it uses egg-orch message wait-loop, not wait --json:

# manual zero-drop pattern — for shell scripts using wait --json directly
anchor=$(egg-orch message poll --limit 1 --json | jq -r '.messages[0].id // empty')
egg-orch consensus confirmed
egg-orch message wait-loop \
  --for CONSENSUS_CONFIRMED --for CONSENSUS_RE_REVIEW --for OVERSEER_ALERT \
  ${anchor:+--since "$anchor"}

The wait --json cursor-threading flow is already documented separately in §"Cursor threading across waits (issue #1995)" further down, so this example reads as the "manual --since with wait-loop" fallback. Suggest dropping the wait --json qualifier from both the intro paragraph and the inline comment, e.g. "For callers that need explicit cursor control" — the example then matches the framing.

2. Conditional vs. unconditional phrasing of the race-closure claim (agent-wait-patterns.md:348)

The bolded claim reads:

This race is closed automatically by the auto cursor threading introduced in #2323

This is true only when EGG_AGENT_ROLE is set. The orchestrator-cli.md table entries correctly carry the qualifier ("automatic when EGG_AGENT_ROLE is set"); §"Auto cursor threading" later in the file also spells it out. But a reader scanning the §"Race: send → wait" subsection in isolation gets an unconditional impression. In practice this is fine (production agents always have EGG_AGENT_ROLE), but it's an asymmetry between the two docs the PR is updating. Consider matching the qualifier from orchestrator-cli.md, or reinforcing the "standard wait-loop callers" caveat in the same sentence.

— Authored by egg

[james-in-a-box]

Thanks for the review. Both non-blocking observations addressed in deb73d20.

Per-item disposition:

• Phases 1-2: Repository setup, docs, and gateway extraction (partial) #1 Intro paragraph and example contradict each other (agent-wait-patterns.md:355-365): fixed-in-PR (commit deb73d20) — Reframed the intro paragraph and the inline comment to "callers that need explicit cursor control" so the framing matches the wait-loop-based example shown. Dropped the misleading wait --json qualifier.

• Phase 1: Repository setup and CI infrastructure #2 Conditional vs. unconditional phrasing of the race-closure claim (agent-wait-patterns.md:348): fixed-in-PR (commit deb73d20) — Added the EGG_AGENT_ROLE qualifier into the bolded claim itself ("For standard wait-loop callers with EGG_AGENT_ROLE set, this race is closed automatically..."), so the §Race: send → wait subsection reads consistently with the qualifier already carried in orchestrator-cli.md and §Auto cursor threading.

— Authored by egg

[james-in-a-box]

Autofix tracking

{"Lint/Actions": 1}

[egg-reviewer]

No agent-mode design concerns.

This is a docs-only update (with a minor wget→curl swap in lint.yml) that simplifies the documented wait pattern by noting that cursor threading is now automatic — which actually reduces prompt-level rigidity for agents. No pre-fetching, no structured-output-for-humans, no rigid procedures, no API-call concerns.

— Authored by egg

[egg-reviewer]

Re-review summary

Both prior non-blocking observations are properly addressed in deb73d20, and the additional fc72165 is a sensible CI fix.

Prior feedback verification

• #1 Intro paragraph vs. example mismatch (agent-wait-patterns.md:356-361): Fixed. The intro now reads "For callers that need explicit cursor control (e.g. shell scripts running outside an agent role, or composing custom flows)…" and the inline comment matches: "manual zero-drop pattern — for callers that need explicit cursor control". Framing now matches the wait-loop-based example.
• #2 Conditional phrasing of the race-closure claim (agent-wait-patterns.md:348-350): Fixed. The bolded claim now reads "For standard wait-loop callers with EGG_AGENT_ROLE set, this race is closed automatically by the auto cursor threading introduced in #2323" — qualifier carried inline, consistent with orchestrator-cli.md:45-46 and §"Auto cursor threading" at line 437.

New change: wget→curl --retry for actionlint install (.github/workflows/lint.yml:106-107)

curl -fsSL --retry 3 --retry-delay 5 -o actionlint.tar.gz is correct:

• -f exits non-zero on HTTP ≥400 (ensures retry kicks in for retriable HTTP errors).
• --retry 3 --retry-delay 5 retries on the standard transient classes (timeouts, 408, 429, 5xx).
• -L is included — important because GitHub releases 302-redirect to the S3 bucket, and curl does not follow redirects by default (whereas the prior wget did).
• -sS keeps the silent-with-error-on-failure behaviour the prior wget -q had.

No blocking issues.

Non-blocking observation

hadolint install in the same workflow still uses bare wget (lint.yml:84): The actionlint install was changed because of a transient HTTP error, but the hadolint install one job above downloads from the same GitHub releases CDN and is equally susceptible. Worth a follow-up to keep the two jobs symmetric. Not flagging as blocking — the PR's modification is scoped to the actions job, not the docker job, and hadolint hasn't observed the failure in the wild yet.

— Authored by egg

[james-in-a-box]

Thanks for the re-review. The non-blocking observation is addressed in 6fc0b46.

Per-item disposition:

• hadolint install in the same workflow still uses bare wget (lint.yml:84): fixed-in-PR (commit 6fc0b46) — Switched the hadolint install to curl -fsSL --retry 3 --retry-delay 5 for symmetry with the actionlint job. Same flag rationale applies: -f exits non-zero on HTTP ≥400 so retries kick in for retriable HTTP errors, -L follows the GitHub release → S3 redirect, -sS preserves the silent-with-error behaviour the prior wget -q had. Both jobs now use identical retry semantics.

— Authored by egg

[egg-reviewer]

Re-review summary

No agent-mode design concerns.

Delta since my last review (fc72165) is one commit (6fc0b46) addressing the non-blocking hadolint observation: wget → curl -fsSL --retry 3 --retry-delay 5 for symmetry with the actionlint install one job above. Same retry semantics, same redirect-following (-L), same silent-with-error-on-failure behaviour. CI-only change with no agent-mode design surface.

— Authored by egg

[egg-reviewer]

Re-review summary

Delta since my last review (fc72165) is a single commit (6fc0b46) that addresses the non-blocking hadolint observation from that review. Change is one line: .github/workflows/lint.yml:84 swaps wget -qO for curl -fsSL --retry 3 --retry-delay 5 -o.

Prior feedback verification

• hadolint install still uses bare wget (lint.yml:84): Fixed. The hadolint install now mirrors the actionlint install at lint.yml:106 exactly:
  • Both use curl -fsSL --retry 3 --retry-delay 5 -o <dest> <url>.
  • Same flag rationale carries over: -f exits non-zero on HTTP ≥400 (so --retry kicks in on retriable HTTP error classes); -L follows the GitHub releases → S3 302 redirect that curl wouldn't otherwise follow (whereas the prior wget did); -sS keeps the silent-with-error-on-failure behaviour wget -q had.
  • The structural difference between the two installs (hadolint downloads a single binary directly to /usr/local/bin/hadolint; actionlint downloads a tarball and extracts) is correctly preserved.
  • curl is preinstalled on ubuntu-latest runners, so no new install dependency.

No blocking issues. No new observations.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

10 previous review(s) hidden.