Skip to content

fix: observe status without implicit cache refresh or builds - #202

Open
Yehonal wants to merge 19 commits into
mainfrom
pr/read-effects-policy
Open

Yehonal wants to merge 19 commits into
mainfrom
pr/read-effects-policy

Conversation

@Yehonal

@Yehonal Yehonal commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Joseph · project thread

status previously fetched sources and tags, persisted version indexes and snapshot leases, and could prune existing snapshots or recursively replace an incomplete checkout. It now observes existing local state and caches; only explicit --refresh permits cache changes. --offline wins. Missing evidence is reported without repair. Registry/version/member caches share the central observation scope, cache writers refuse in that scope, and Git status disables optional index writes. Unqualified executable adapters/source drivers and direct remote transports refuse before invocation; cached composite reports remain usable.

Consumer behavior change: expired member-report and package-version caches no longer refresh automatically during status reads. The default fleet-diagnostics wrapper is therefore an observation consumer: after TTL expiry it shows STALE evidence (or a degraded status from stale package metadata) until an explicit refresh succeeds. Repeating the default read does not renew freshness. The operator or caller needing current evidence now owns the refresh: invoke agentwheel status with the same workspace/fleet/profile selectors and --refresh, or explicitly request the diagnostics caller's existing --refresh option. No new background refresher or schedule is installed. The fleet-control consumer follow-up remains Joseph's separate decision; fleet-control is unchanged here.

Incomplete-checkout errors now name the exact preserved directory and its cache parent, instruct the operator to move that directory to a new backup location outside the cache without overwriting a backup, confirm the original path is absent, then repeat the same scoped refresh. A fixture exercises that manual move and successful reclone while preserving the sentinel. No automatic repair or deletion is added. Snapshot path derivation is shared by observation and materialization; import ordering and conservative notifier suppression are covered by the review follow-up.

This PR is stacked on PR #201 at 71101a9b4f92ffad1ee817fe50842506dba202e1 and reuses its effects harness. PR #201 must merge first. The base remains main; until that prerequisite lands, the diff also includes the baseline. I2 is now an ordinary regression test; I5 remains an expected failure and is outside this fix.

Test-first evidence on the unchanged main product code reproduced cold/warm status fetches and leases, global pruning after a newer synthetic source commit, and sentinel loss when .git was missing. The same snapshot invariant then passes with the fix. A separately isolated legacy launcher probe recorded one implicit build on status with a dummy builder. The new generic scripts/agentwheel-local.mjs source launcher refuses missing/stale builds and never builds implicitly. It is not installed by this PR; no existing wrapper or runtime launcher is replaced.

The synthetic fixture snapshots HOME, workspace, cache, Git metadata and temp, with a child-process/network observer. Only its exact trace file is excluded. Cases cover cold/warm/offline/refused status reads, cached-source usefulness, a synthetic diagnostics protocol consumer, launcher admission, and bounded explicit refresh. Diagnostics is a consumer of status --json; no private diagnostics source or configuration is copied here. This is an application-boundary trace, not a kernel sandbox. Other read/preview verbs and observer-versus-refresh concurrency remain separate qualification work; see docs/read-effects.md.

Validation is intentionally lean: typecheck, build, and affected test files run sequentially with one worker and a memory gate. The complete reconciled matrix and smoke checks run only in CI. No merge, install, runtime-home changes, repository settings changes, or release are included. Stop here for independent review before subsequent batches.

Qualification on 667d6d23ca50ab3d9b842ff622811603944ad627: local typecheck, build, and the four affected test files passed sequentially with the RAM gate. CI passed: 1,250 registered and executed tests, 1,250 passed, zero failed or skipped; both CLI smoke checks and the catalogue contract passed. No merge is performed.

@Yehonal Yehonal self-assigned this Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant