Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
feat(persistence): settle-effects --retire settles a former-binding Git effect nothing current owes, on evidence (#7985)
garrytane05e4d025e83
diff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.mdindex aa3856ad2f..98e8690fd5 100644--- a/docs/architecture/key-files/core-persistence-capacity.md+++ b/docs/architecture/key-files/core-persistence-capacity.md@@ -22,4 +22,4 @@ What a managed publish costs in statements and round trips, and how it is measur- `addCodeReferenceLinks` in `src/core/engine-sql/links.ts` (#6712 L6) — a page's doc↔impl code-reference edges (`documents` from the page, `documented_by` back) in one set-based statement: endpoints resolve in the page's source under `FOR KEY SHARE`, a missing endpoint drops its edge, a repeated edge keeps its last context, and a re-import updates context and origin field in place. `import-file.ts` and `page-body/streamed-import.ts` call it once per page inside a savepoint (a failure leaves the page import intact), where each reference used to cost two sequential `addLink` statements.- `src/core/postgres-engine/pool-stats.ts` — #6317 (C1, G1): `driverPoolStats(sql)` reads the vendored postgres.js driver's `sql.pool` getter (`vendor/postgres`, patch regenerated) for real `{checked_out, max, waiters}`; `enginePoolStats(engine)` labels the source (`driver` or `tracked_subset` from `pool-gauge.ts`). Filled into the heartbeat row, `writer status` running claims and `getPoolDiagnostics()`.- `src/core/persistence/maintenance-wait.ts` — how long a maintenance publisher waits for its accepted write to commit before the receipt reports `write_pending` (#5854). `MAINTENANCE_WRITE_WAIT_MS` is 30 s; `MaintenanceWriteWait` is one budget per job: each wait is capped by the job's remaining deadline (zero at or past it), and once one publish is still pending after its wait (`observe`) every later publish in that job waits zero and is deferred like it. A pending write keeps its request identity and commits later; it is never reported as committed. A `MaintenanceWriteWait` with no deadline also sets the replay window of a subagent tool write whose job has none (`minions/tool-write-identity.ts`). `__setMaintenanceWriteWaitForTests` replaces the base wait, those tool writes included. Tests: `test/maintenance-write-wait.test.ts`, `test/e2e/maintenance-write-wait.test.ts`.-- `src/core/persistence/effect-settle.ts` — `gbrain sources writer settle-effects <source> (--request-id|--parked-code) [--unsettle] [--dry-run|--apply --expect <plan_hash>]` (`writer_settle_effects`, an administration extension) (#7423, #7378): records `data.settled` (and appends to `data.settlements`) on a failed Git effect no retry can move, never touching its failure, parked targets, request or bytes. It settles only on an exact-target proof re-checked under row locks at apply: each target declared `db_only` in the current binding's gbrain.yml (`sourceDbOnlyDir`), or, for an effect `guardEffectSource` refuses `source_changed` because the source moved to a new worktree (same incarnation, this host owning the active binding), a later committed and pushed Git effect of the current worktree whose `expected_hash` equals the canonical file now and a blob at the already-fetched `@{upstream}` equal to it (no fetch). Withdrawal effects, claims, open recovery records, revoked writers, replaced sources and unknown targets refuse; an effect of the current binding that is not db_only refuses `retry_instead`. The plan hash is doctor --remediate's `computePlanHash` over the brain, source, selector, owner epoch and each proof (`preview_changed` otherwise). Readers that skip settled rows: doctor `parked_effects`, `rearmWithheldTargets`, `readParkedGroups`, `readGitPushHolds`, `retryParkedPushes`/`--parked-code`, `retryIndexLockParks`, `sync status`, `failedEffectHistory`; `retryParkedEffects` reports a settled effect as `action: settled`. `retryParkedPushes` also reaches a push that failed without parked targets (#7378, `failedCodes`). #7985: an effect outside its source's current binding (`CURRENT_BINDING_SQL` in `parked-groups.ts`, the guard's own test) gets its own `readParkedGroups` group (`former_binding`: `binding_changed` or `source_replaced`, recorded and current worktree, up to five request ids, the settle preview as `command`), doctor's per-effect command for it is `settle-effects --request-id`, `retryParkedEffects` rethrows the guard's `source_changed` naming both bindings with that preview as `fix`, and the bulk retries' `former_worktree` lists its worktree and requests (`test/orphan-effect-diagnostics-7985.test.ts`). Tests: `test/persistence-effect-settle.test.ts` (scenarios in `test/helpers/effect-settle-scenarios.ts`) + the Postgres arm in `test/e2e/w5-persistence-postgres.test.ts`.+- `src/core/persistence/effect-settle.ts` — `gbrain sources writer settle-effects <source> (--request-id|--parked-code) [--unsettle] [--dry-run|--apply --expect <plan_hash>]` (`writer_settle_effects`, an administration extension) (#7423, #7378): records `data.settled` (and appends to `data.settlements`) on a failed Git effect no retry can move, never touching its failure, parked targets, request or bytes. It settles only on an exact-target proof re-checked under row locks at apply: each target declared `db_only` in the current binding's gbrain.yml (`sourceDbOnlyDir`), or, for an effect `guardEffectSource` refuses `source_changed` because the source moved to a new worktree (same incarnation, this host owning the active binding), a later committed and pushed Git effect of the current worktree whose `expected_hash` equals the canonical file now and a blob at the already-fetched `@{upstream}` equal to it (no fetch). Withdrawal effects, claims, open recovery records, revoked writers, replaced sources and unknown targets refuse; an effect of the current binding that is not db_only refuses `retry_instead`. The plan hash is doctor --remediate's `computePlanHash` over the brain, source, selector, owner epoch and each proof (`preview_changed` otherwise). Readers that skip settled rows: doctor `parked_effects`, `rearmWithheldTargets`, `readParkedGroups`, `readGitPushHolds`, `retryParkedPushes`/`--parked-code`, `retryIndexLockParks`, `sync status`, `failedEffectHistory`; `retryParkedEffects` reports a settled effect as `action: settled`. `retryParkedPushes` also reaches a push that failed without parked targets (#7378, `failedCodes`). #7985: an effect outside its source's current binding (`CURRENT_BINDING_SQL` in `parked-groups.ts`, the guard's own test) gets its own `readParkedGroups` group (`former_binding`: `binding_changed` or `source_replaced`, recorded and current worktree, up to five request ids, the settle preview as `command`), doctor's per-effect command for it is `settle-effects --request-id`, `retryParkedEffects` rethrows the guard's `source_changed` naming both bindings with that preview as `fix`, and the bulk retries' `former_worktree` lists its worktree and requests. `--retire` (`retiredTarget`) settles such an effect as `former_binding_retired` only on evidence: a replaced source (authority not re-checked), or each target's page absent, deleted, replaced (`page_id`) or at another revision than `effect.revision`; else `page_not_moved`, and a current-binding effect `not_former_binding`; its plan operation is `writer_retire_effects` and its fix `actor: user` (`test/orphan-effect-diagnostics-7985.test.ts`). Tests: `test/persistence-effect-settle.test.ts` (scenarios in `test/helpers/effect-settle-scenarios.ts`) + the Postgres arm in `test/e2e/w5-persistence-postgres.test.ts`.diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 8abef4fef3..8b5b135f6d 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -849,15 +849,30 @@ Disposition, with the user:Preview again, show the user the proof, and run the printed `apply_command`only after they agree. The settlement keeps the failure, request and bytes,and `--unsettle` reverses it.-2. `reason: source_replaced` (the source was archived, removed or re-created- after the effect): it owes nothing to the current source, and neither retry- nor settle runs it (settle refuses `source_replaced`). There is no- supported command that retires it yet; leave it parked and tell the user- what it is.+2. The page has since moved on (a later write committed a new revision), was+ deleted, or another page took its slug: nothing current owes the old+ bytes, so add `--retire` to the preview. Each target is listed with its+ evidence (`moved`, `deleted`, `replaced` or `absent`, with the owed and+ current revision). A page still at the owed revision is refused+ `page_not_moved`: write it through gbrain first. An effect of the current+ binding is refused `not_former_binding`.+3. `reason: source_replaced` (the source was archived, removed or re-created+ after the effect): it owes nothing to the current source, so retry never+ runs it and plain settle refuses `source_replaced`. Preview+ `settle-effects <source> --request-id <id> --retire --dry-run` (the group's+ command); the source being replaced is the evidence.++A retirement is a settlement with proof `former_binding_retired`: preview+first, bound to the plan hash (a settle plan never applies as a retirement),+asked of the user (`actor: user`), recorded in `data.settled` and+`data.settlements`, never requeued or replayed against the current binding,+idempotent (a second preview lists nothing) and reversed by `--unsettle`. The+exact retry keeps refusing the effect `source_changed`.These do not apply to it: `gbrain repair stuck-recovery` resolves recoveryrecords blocked on unexpected file bytes, and a parked Git effect without a-recovery record gives it nothing to resolve; cancelling the request returns a committed request unchanged; receipt+recovery record gives it nothing to resolve; cancelling the request returns a+committed request unchanged; receiptcompaction skips requests with uncommitted effects. A `write-request` read thatreturns `not_found` under another writer identity is a visibility limit, notproof the request is gone: writer status and the settle preview read thediff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex bf5290fa9c..07aff53406 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -215,7 +215,12 @@ with its refusal: `retry_instead` (current binding: retry it),`remote_ref_missing` or `remote_ref_stale` (fetch in the checkout, then previewagain), `content_changed`, `content_missing`, `unknown_target`, `withdrawal_effect`(never settled), `recovery_open`, `claimed`, `authority_changed`, `source_replaced` and-`owner_unavailable`. A settlement is recorded on the effect (`data.settled`, every+`owner_unavailable`. `--retire` (#7985) settles an effect of a former binding+that nothing current owes, on evidence instead of a remote proof: its source was+replaced, or each target's page moved to a later revision, was deleted or lost+its slug to another page (proof `former_binding_retired`; refusals+`page_not_moved` and `not_former_binding`; the apply asks the user,+[disposition](repair.md#former-binding-effects)). A settlement is recorded on the effect (`data.settled`, everysettle and unsettle appended to `data.settlements`); its failure, request, intentand target bytes are kept. Doctor `parked_effects`, writer status, the bulk retriesand `sync status` skip settled effects. `--unsettle` with the same selectordiff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex b1aa5ec146..7626dd58d5 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: linksrc/core/search/evidence-delivery.ts 1755 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned)src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)-src/core/behavior-change-notice.ts 1573 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +1 #7973 plain_directory_sync_7973 row; +1 #7988 managed_marker_own_directory_7988 row; +1 #7985 former_binding_parked_group_7985 row+src/core/behavior-change-notice.ts 1574 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +1 #7973 plain_directory_sync_7973 row; +1 #7988 managed_marker_own_directory_7988 row; +1 #7985 former_binding_parked_group_7985 row; +1 #7985 settle_effects_retire_7985 rowdiff --git a/src/commands/persistence-admin.ts b/src/commands/persistence-admin.tsindex 0ae079d4c9..fe7af7f7d6 100644--- a/src/commands/persistence-admin.ts+++ b/src/commands/persistence-admin.ts@@ -22,7 +22,7 @@ export const WRITER_HELP = `Usage:gbrain sources writer retry-effects <source> --request-id <uuid> [--admin-intent writer_retry_effects --expected-state <admin_state>] [--dry-run] [--json]gbrain sources writer retry-effects <source> --parked-pushes [--dry-run] [--json]gbrain sources writer retry-effects <source> --parked-code <code> [--dry-run] [--json]- gbrain sources writer settle-effects <source> --request-id <uuid>|--parked-code <code> [--unsettle] [--dry-run | --apply --expect <plan_hash>] [--json]+ gbrain sources writer settle-effects <source> --request-id <uuid>|--parked-code <code> [--unsettle | --retire] [--dry-run | --apply --expect <plan_hash>] [--json]gbrain sources writer git-durability <source> --enable|--disable [--pat-file <path>] [administration options] [--dry-run] [--json]gbrain sources writer claim <source> --path <directory> [administration options] [--dry-run] [--json]gbrain sources writer activate --confirm-quiesced [--cleanup-dead-local-locks] [--shared-skills] [administration options] [--dry-run] [--json]@@ -111,6 +111,9 @@ former canonical worktree and the fetched remote branch holds the current byteseffect wrote (nothing is fetched). The failure, request and target bytes are kept; doctor andretries skip settled effects. Preview first; --apply needs the preview's --expect <plan_hash>.--unsettle (previewed and plan-bound the same way) reverses a settlement; both stay in history.+--retire settles an effect of a former binding that nothing current owes: its source was replaced,+or each target's page is gone, deleted or past the revision the effect owed; a page still at that+revision is refused (write it through gbrain, then preview again). Ask the user first.lock sets an opt-in, brain-level writer admin lock (config key persistence.writer_admin_lock)and unlock clears it; both are local-only, idempotent and print the resulting state.While locked, writer claim, activate and transfer (prepare, accept and cancel) are refused with@@ -152,7 +155,7 @@ export function adminHostConfig<T extends GBrainConfig>(config: T | null | undeftype Group = 'writer' | 'local-writer';const GROUP_ARGV: Record<Group, string[]> = { writer: ['gbrain', 'sources', 'writer'], 'local-writer': ['gbrain', 'auth', 'local-writer'] };-const BARE_FLAGS = ['--json', '--dry-run', '--replace', '--probe', '--confirm-quiesced', '--self-transfer', '--confirm-relocated-root', '--cleanup-dead-local-locks', '--shared-skills', '--enable', '--disable', '--parked-pushes', '--apply', '--unsettle'];+const BARE_FLAGS = ['--json', '--dry-run', '--replace', '--probe', '--confirm-quiesced', '--self-transfer', '--confirm-relocated-root', '--cleanup-dead-local-locks', '--shared-skills', '--enable', '--disable', '--parked-pushes', '--apply', '--unsettle', '--retire'];/** A CLI usage refusal: the exact usage in the suggestion, the group's help as the read-only fix. */function invalid(group: Group, message: string, suggestion: string) {return opError('invalid_params', message, suggestion, {diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex c4c18c60c8..c86dda493c 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1374,6 +1374,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.514.0', id: 'redaction_marker_not_credential_7997', text: 'The transcript `labeled_credential` detector no longer reads an importer redaction marker (`login **<REDACTED:user-pattern>**`) as a typed user/password pair, so a correctly redacted page clears `gbrain transcripts audit-secrets`; a password written beside a marker is still found. The audit detector version moves to 3, so `gbrain doctor` asks for a fresh audit once.' },{ since: '0.60.516.0', id: 'plain_directory_sync_7973', text: '`gbrain sync` on a plain directory registered with `gbrain sources add --path <dir> --force` (no Git checkout at or above it) now imports its files into the source the way `gbrain import` does; it used to fail with a raw `git rev-parse` internal_error. There are no commits to diff, so a file removed from the directory keeps its page.' },{ since: '0.60.516.0', id: 'former_binding_parked_group_7985', text: 'Doctor `parked_effects` and `gbrain sources writer status` now list parked Git effects recorded under a former canonical binding in their own parked group (`former_binding`: reason, recorded and current worktree, request ids), whose `command` is the `settle-effects` preview instead of the bulk retry that never selects them; doctor\'s per-effect command for them is `settle-effects --request-id`, the exact retry\'s `source_changed` refusal names both bindings with that preview as its fix, and the bulk retries\' `former_worktree` lists the worktree and requests. A tool reading one parked group per source and code can now see two.' },+ { since: '0.60.516.0', id: 'settle_effects_retire_7985', text: '`gbrain sources writer settle-effects --retire` settles a parked Git effect of a former binding that nothing current owes, on evidence: its source was archived, removed or re-created, or each target\'s page moved to a later revision, was deleted or lost its slug to another page. It is previewed, bound to its plan hash, applied only after the user agrees, never retried, and `--unsettle` reverses it. The parked group for a replaced source now names that preview, and plain settle\'s `source_replaced` refusal points to it.' },{ since: '0.60.516.0', id: 'managed_marker_own_directory_7988', text: 'Managed persistence now marks a root that no Git checkout tracks (a connector clone or plain directory under a dotfiles home) in its own directory instead of in the enclosing repository, so legacy writers elsewhere in that repository are no longer refused, and the autopilot HEAD probe no longer reads the enclosing repository\'s HEAD for it. A marker an older release already wrote there stays until `gbrain sources writer deactivate` removes it (preview with `--dry-run --json`; activate again afterwards), and a write it refuses now says so.' },];diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.tsindex 0b5446fa05..ad9427db46 100644--- a/src/core/cli-flag-registry.generated.ts+++ b/src/core/cli-flag-registry.generated.ts@@ -19,7 +19,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'anomalies': ['--all', '--brain', '--help', '--json', '--lookback-days', '--mcp-only', '--request-id', '--sigma', '--since', '--source'],'append': ['--brain', '--expect-tail', '--expected-revision', '--file', '--force', '--help', '--json', '--region', '--request-id', '--separator', '--source'],'apply-migrations': ['--accept-reviewed-inventory', '--acknowledge-no-backup', '--apply', '--apply-rewrites', '--backup-confirmed', '--brain', '--break-lock', '--confirm-quiesced', '--content-root', '--dry-run', '--export-db-only', '--export-source', '--force', '--force-all', '--force-orchestrator', '--force-retry', '--force-schema', '--help', '--host-dir', '--http', '--install', '--json', '--legacy-lock', '--list', '--locks', '--migrate-only', '--migration', '--mode', '--no-autopilot-install', '--non-interactive', '--only', '--path', '--prefer-postgres', '--probe', '--repo', '--require-db', '--skip-verify', '--source', '--statement-timeout', '--uninstall', '--url', '--yes'],- 'auth': ['--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--all-new', '--allowed-operations', '--apply', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--budget-usd-per-day', '--category', '--cleanup-dead-local-locks', '--client', '--code', '--confirm-quiesced', '--confirm-relocated-root', '--days', '--delegated-namespace', '--delegated-slug-prefixes', '--disable', '--dry-run', '--enable', '--enable-dcr-insecure', '--expect', '--expected-epoch', '--expected-state', '--federated-read', '--fix', '--force', '--grant-types', '--group-by', '--help', '--id', '--if-version', '--json', '--limit', '--manifest', '--max-concurrent', '--migrate-legacy', '--min-trust', '--no-pull', '--operation', '--operations', '--origin', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--probe', '--profile', '--read-sources', '--redirect-uri', '--refresh-operations', '--repair', '--replace', '--request-id', '--reset-default', '--scopes', '--self-transfer', '--shared-skills', '--since', '--slug-prefixes', '--source', '--source-ids', '--sources', '--state', '--surface', '--takes-holders', '--token', '--token-endpoint-auth-method', '--token-ttl', '--unsettle', '--usage', '--wait', '--warn-only', '--yes'],+ 'auth': ['--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--all-new', '--allowed-operations', '--apply', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--budget-usd-per-day', '--category', '--cleanup-dead-local-locks', '--client', '--code', '--confirm-quiesced', '--confirm-relocated-root', '--days', '--delegated-namespace', '--delegated-slug-prefixes', '--disable', '--dry-run', '--enable', '--enable-dcr-insecure', '--expect', '--expected-epoch', '--expected-state', '--federated-read', '--fix', '--force', '--grant-types', '--group-by', '--help', '--id', '--if-version', '--json', '--limit', '--manifest', '--max-concurrent', '--migrate-legacy', '--min-trust', '--no-pull', '--operation', '--operations', '--origin', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--probe', '--profile', '--read-sources', '--redirect-uri', '--refresh-operations', '--repair', '--replace', '--request-id', '--reset-default', '--retire', '--scopes', '--self-transfer', '--shared-skills', '--since', '--slug-prefixes', '--source', '--source-ids', '--sources', '--state', '--surface', '--takes-holders', '--token', '--token-endpoint-auth-method', '--token-ttl', '--unsettle', '--usage', '--wait', '--warn-only', '--yes'],'autopilot': ['--apply', '--batch', '--brain', '--channel', '--check', '--dimensions', '--dir', '--drain', '--dry-run', '--embedding-dimensions', '--embedding-model', '--exit-code', '--expect', '--explain', '--ff-only', '--force', '--force-retry', '--from-pages', '--help', '--inject-bootstrap', '--inline', '--install', '--interval', '--is-ancestor', '--json', '--markdown', '--max-cost', '--max-rss', '--max-runtime', '--max-usd', '--migrate-only', '--model', '--no-autopilot-install', '--no-bun-floor-check', '--no-embed', '--no-embed-cache', '--no-inject', '--no-restart', '--no-worker', '--non-interactive', '--now', '--once', '--only', '--output', '--params', '--pause', '--phase', '--quiet', '--reader-mode', '--reason', '--refresh-cache', '--refs', '--remediation-plan', '--repo', '--restart-only', '--resume', '--retry-global', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--source', '--stale', '--status', '--stop-mcp', '--swap-only', '--tags', '--target', '--trust', '--uninstall', '--user', '--verify', '--version', '--yes'],'backfill': ['--batch-size', '--brain', '--concurrency', '--dry-run', '--fresh', '--help', '--json', '--keep-index', '--list', '--max-errors', '--max-rows', '--resume', '--source'],'backup': ['--accept-pending', '--background', '--brain', '--confirm-authority-reviewed', '--confirm-backup-compatible', '--confirm-quiesced', '--dir', '--explain', '--follow', '--full', '--help', '--into', '--json', '--mode', '--no-accept-pending', '--output', '--path', '--progress-interval', '--progress-json', '--purge-mirror', '--quiet', '--restore-only', '--source', '--timeout', '--timings', '--wait'],@@ -50,7 +50,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'db-repair': ['--accept-pending', '--apply', '--apply-rewrites', '--background', '--brain', '--break-lock', '--db-url', '--dry-run', '--explain', '--filter', '--follow', '--force', '--force-retry', '--format', '--help', '--http', '--json', '--legacy-lock', '--locks', '--name', '--no-accept-pending', '--path', '--prefer-postgres', '--probe', '--progress-interval', '--progress-json', '--quiet', '--remediate', '--restart', '--skip-verify', '--source', '--statement-timeout', '--supabase', '--timeout', '--timings', '--undo-last-rewrite', '--url', '--version', '--wait', '--yes'],'decide': ['--accept-all', '--all', '--all-from', '--apply', '--brain', '--call-site', '--dataset', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--expect', '--from', '--help', '--include-withdrawals', '--input', '--items-out', '--json', '--kind', '--limit', '--max-cost', '--max-usd', '--min', '--non-interactive', '--out', '--provenance', '--provider', '--query', '--rate', '--reason', '--reason-family', '--recommended', '--remove', '--shadow', '--since', '--slot', '--source', '--status', '--suite', '--target', '--threshold', '--trust', '--undo', '--uri-prefix', '--version', '--what-if-threshold', '--yes'],'diag': ['--access', '--add', '--all', '--allowed-operations', '--apply', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--budget-ms', '--client', '--count', '--cursor', '--date', '--dated-since', '--days', '--detach', '--entities', '--expect', '--expected-revision', '--federated-read', '--format', '--from-index', '--full', '--fuzzy', '--group-by', '--held', '--help', '--http', '--id', '--include-ambiguous', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--no-pull', '--no-walk', '--only', '--page', '--params', '--path', '--phase', '--prefer', '--preview', '--purge', '--query', '--recent', '--refresh-operations', '--replace', '--restart-only', '--reverse', '--row', '--scopes', '--session', '--side', '--since', '--slug', '--slugs', '--source', '--source-id', '--sources', '--stale', '--state', '--surface', '--to', '--updated-after', '--url', '--yes'],- 'doctor': ['--abandon', '--abbrev-ref', '--accept-capabilities', '--accept-pending', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt', '--adopt-columns', '--adopt-permissions', '--advertise', '--after', '--aggressive', '--aliases', '--all', '--all-drifted', '--all-from', '--allow-old-serve', '--allow-outside-source-root', '--allow-shell-jobs', '--allow-unverified-remote', '--allowed-operations', '--applied', '--apply', '--apply-rewrites', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--batch', '--batch-check', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--cached', '--cacheinfo', '--call-site', '--catch-up', '--channel', '--check', '--cherry-mark', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--concurrency', '--confidence', '--confirm', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--cursor', '--dataset', '--day', '--db-url', '--deadline', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--error-unmatch', '--exclude', '--exclude-standard', '--exit-code', '--expand', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-remove', '--force-retry', '--force-schema', '--format', '--fresh', '--fresh-token', '--from', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--generation', '--get', '--get-all', '--get-url', '--git-common-dir', '--git-dir', '--git-path', '--grammar', '--group', '--group-by', '--hard', '--hard-deadline', '--harness', '--held', '--help', '--hold-state', '--holds', '--home', '--http', '--id', '--if-version', '--ignore-env-override', '--images', '--include-ambiguous', '--include-cross-entity', '--include-deleted', '--include-failures', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-pseudo', '--include-repairs', '--include-withdrawals', '--index-audit', '--index-info', '--infer-dates', '--init', '--input', '--install', '--instructions', '--instructions-only', '--is-ancestor', '--is-inside-work-tree', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link', '--link-source', '--link-type', '--list', '--literal-pathspecs', '--local', '--local-env-vars', '--locks', '--log-noop', '--manifest', '--markdown', '--max-cost', '--max-cost-usd', '--max-count', '--max-facts', '--max-jobs', '--max-requests', '--max-rss', '--max-runtime', '--max-usd', '--max-waiting', '--mcp-only', '--merge-base', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-autopilot-install', '--no-autostash', '--no-capture', '--no-commit-id', '--no-confirm', '--no-cron', '--no-delegate', '--no-edit', '--no-embed', '--no-embed-cache', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-gpg-sign', '--no-hooks', '--no-instructions', '--no-lanes', '--no-llm', '--no-merges', '--no-migrate', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-tags', '--no-verify', '--no-walk', '--no-write-fetch-head', '--non-interactive', '--not', '--now', '--older-than', '--once', '--only', '--operation', '--operations', '--others', '--out', '--output', '--oversized', '--overwrite', '--page', '--parallel', '--params', '--parents', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--port', '--prefer', '--prefer-postgres', '--preset', '--preview', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push', '--push-only', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--resolve', '--restart-only', '--restore-only', '--resume', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--reverse', '--review-lower', '--revision', '--right-only', '--rollback-to-source', '--root', '--run', '--runtime', '--sample', '--save', '--scope', '--scopes', '--search-mode', '--seat', '--section', '--segmented', '--select', '--self-transfer', '--semantic', '--session', '--session-id', '--set', '--set-upstream-to', '--shadow', '--shared-skills', '--short', '--show-current', '--show-object-format', '--show-prefix', '--show-token', '--show-toplevel', '--side', '--since', '--since-last-run', '--skills-dir', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--skip-verify', '--slot', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--slugs', '--source', '--source-id', '--source-ids', '--sources', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--topo-order', '--trust', '--type', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset-all', '--untracked-files', '--url', '--url-env', '--user', '--vacuum', '--vectors', '--verbose', '--verify', '--version', '--wait', '--wait-drain', '--warn-only', '--watch', '--what-if-threshold', '--window', '--workers', '--working-tree', '--workspace', '--write-tree', '--yes'],+ 'doctor': ['--abandon', '--abbrev-ref', '--accept-capabilities', '--accept-pending', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt', '--adopt-columns', '--adopt-permissions', '--advertise', '--after', '--aggressive', '--aliases', '--all', '--all-drifted', '--all-from', '--allow-old-serve', '--allow-outside-source-root', '--allow-shell-jobs', '--allow-unverified-remote', '--allowed-operations', '--applied', '--apply', '--apply-rewrites', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--batch', '--batch-check', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--cached', '--cacheinfo', '--call-site', '--catch-up', '--channel', '--check', '--cherry-mark', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--concurrency', '--confidence', '--confirm', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--cursor', '--dataset', '--day', '--db-url', '--deadline', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--error-unmatch', '--exclude', '--exclude-standard', '--exit-code', '--expand', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-remove', '--force-retry', '--force-schema', '--format', '--fresh', '--fresh-token', '--from', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--generation', '--get', '--get-all', '--get-url', '--git-common-dir', '--git-dir', '--git-path', '--grammar', '--group', '--group-by', '--hard', '--hard-deadline', '--harness', '--held', '--help', '--hold-state', '--holds', '--home', '--http', '--id', '--if-version', '--ignore-env-override', '--images', '--include-ambiguous', '--include-cross-entity', '--include-deleted', '--include-failures', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-pseudo', '--include-repairs', '--include-withdrawals', '--index-audit', '--index-info', '--infer-dates', '--init', '--input', '--install', '--instructions', '--instructions-only', '--is-ancestor', '--is-inside-work-tree', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link', '--link-source', '--link-type', '--list', '--literal-pathspecs', '--local', '--local-env-vars', '--locks', '--log-noop', '--manifest', '--markdown', '--max-cost', '--max-cost-usd', '--max-count', '--max-facts', '--max-jobs', '--max-requests', '--max-rss', '--max-runtime', '--max-usd', '--max-waiting', '--mcp-only', '--merge-base', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-autopilot-install', '--no-autostash', '--no-capture', '--no-commit-id', '--no-confirm', '--no-cron', '--no-delegate', '--no-edit', '--no-embed', '--no-embed-cache', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-gpg-sign', '--no-hooks', '--no-instructions', '--no-lanes', '--no-llm', '--no-merges', '--no-migrate', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-tags', '--no-verify', '--no-walk', '--no-write-fetch-head', '--non-interactive', '--not', '--now', '--older-than', '--once', '--only', '--operation', '--operations', '--others', '--out', '--output', '--oversized', '--overwrite', '--page', '--parallel', '--params', '--parents', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--port', '--prefer', '--prefer-postgres', '--preset', '--preview', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push', '--push-only', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--resolve', '--restart-only', '--restore-only', '--resume', '--retire', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--reverse', '--review-lower', '--revision', '--right-only', '--rollback-to-source', '--root', '--run', '--runtime', '--sample', '--save', '--scope', '--scopes', '--search-mode', '--seat', '--section', '--segmented', '--select', '--self-transfer', '--semantic', '--session', '--session-id', '--set', '--set-upstream-to', '--shadow', '--shared-skills', '--short', '--show-current', '--show-object-format', '--show-prefix', '--show-token', '--show-toplevel', '--side', '--since', '--since-last-run', '--skills-dir', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--skip-verify', '--slot', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--slugs', '--source', '--source-id', '--source-ids', '--sources', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--topo-order', '--trust', '--type', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset-all', '--unsettle', '--untracked-files', '--url', '--url-env', '--user', '--vacuum', '--vectors', '--verbose', '--verify', '--version', '--wait', '--wait-drain', '--warn-only', '--watch', '--what-if-threshold', '--window', '--workers', '--working-tree', '--workspace', '--write-tree', '--yes'],'dream': ['--audit-rejects', '--brain', '--cancel-unmatched', '--date', '--dir', '--drain', '--dry-run', '--eval-run', '--force', '--from', '--help', '--input', '--install', '--json', '--limit', '--list', '--max-usd', '--once', '--phase', '--probe', '--pull', '--reconcile-queue', '--since', '--source', '--source-id', '--threshold', '--to', '--unsafe-bypass-dream-guard', '--window', '--yes'],'edge-proposals': ['--access', '--add', '--all', '--all-applied', '--all-held', '--allowed-operations', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--client', '--cursor', '--date', '--dated-since', '--days', '--entities', '--federated-read', '--from-index', '--full', '--fuzzy', '--group-by', '--help', '--http', '--id', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--page', '--params', '--path', '--phase', '--prefer', '--purge', '--recent', '--refresh-operations', '--row', '--scopes', '--session', '--since', '--slugs', '--source', '--sources', '--stale', '--status', '--surface', '--to', '--updated-after', '--url', '--yes'],'edges-backfill': ['--all-sources', '--brain', '--concurrency', '--help', '--json', '--max-chunks', '--source', '--workers'],@@ -76,7 +76,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'graph-query': ['--brain', '--depth', '--direction', '--help', '--hop', '--include-foreign', '--json', '--mcp-only', '--request-id', '--source', '--type'],'hook': ['--allow-unverified-remote', '--auto', '--batch-check', '--brain', '--branch', '--cached', '--count', '--diff-filter', '--enable', '--end-of-options', '--env', '--gbrain-bin', '--get', '--harness', '--help', '--instructions', '--instructions-only', '--jq', '--json', '--limit', '--name-only', '--no-instructions', '--others', '--pat-file', '--path', '--porcelain', '--pure', '--quiet', '--remove', '--seat', '--session', '--show-current', '--show-toplevel', '--since', '--source', '--source-ids', '--workspace', '--yes'],'import': ['--accept-pending', '--admin-intent', '--allow-empty', '--allow-noncanonical-root', '--apply', '--background', '--batch-check', '--brain', '--cached', '--confirm-relocated-root', '--diff-filter', '--dim', '--embedding-dimensions', '--embedding-model', '--empty', '--exclude', '--exclude-standard', '--expected-epoch', '--expected-state', '--explain', '--follow', '--force', '--force-rechunk', '--format', '--fresh', '--help', '--include-gitignored', '--is-shallow-repository', '--json', '--literal-pathspecs', '--log-noop', '--manifest', '--name-only', '--no-accept-pending', '--no-embed', '--no-embedding', '--no-gpg-sign', '--no-pull', '--no-renames', '--no-verify', '--only', '--others', '--path', '--probe', '--progress-interval', '--progress-json', '--quiet', '--self-transfer', '--show-toplevel', '--skip-failed', '--slugs', '--source', '--source-id', '--stale', '--status', '--supabase', '--timeout', '--timings', '--to', '--url', '--verify', '--wait', '--workers'],- 'init': ['--accept-capabilities', '--access', '--acknowledge-managed', '--adopt', '--advertise', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--background', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--fix', '--force', '--force-retry', '--format', '--fresh-token', '--from', '--from-meetings', '--full', '--git', '--grammar', '--grant-types', '--group-by', '--harness', '--held', '--help', '--hold-state', '--holds', '--http', '--id', '--images', '--include-ambiguous', '--include-cross-entity', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--infer-dates', '--input', '--install', '--instructions-only', '--issuer-url', '--job-isolation', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--legacy-lock', '--limit', '--link', '--list', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--mcp-only', '--mcp-url', '--migrate-only', '--migration', '--min-n', '--mode', '--model', '--no-autopilot-install', '--no-autostash', '--no-delegate', '--no-embed', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-git', '--no-hooks', '--no-instructions', '--no-lanes', '--no-llm', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--non-interactive', '--oauth-client-id', '--oauth-client-secret', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--preview', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--query', '--question', '--quiet', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retry-failed', '--retry-parked', '--runtime', '--save', '--schema-pack', '--scope', '--scopes', '--search-mode', '--section', '--segmented', '--self-transfer', '--semantic', '--session', '--session-id', '--shared-skills', '--show-toplevel', '--side', '--since', '--since-last-run', '--skip', '--skip-embed-check', '--skip-failed', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--url', '--url-env', '--user', '--vacuum', '--verbose', '--version', '--wait', '--warn-only', '--watch', '--working-tree', '--workspace', '--yes'],+ 'init': ['--accept-capabilities', '--access', '--acknowledge-managed', '--adopt', '--advertise', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--background', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--fix', '--force', '--force-retry', '--format', '--fresh-token', '--from', '--from-meetings', '--full', '--git', '--grammar', '--grant-types', '--group-by', '--harness', '--held', '--help', '--hold-state', '--holds', '--http', '--id', '--images', '--include-ambiguous', '--include-cross-entity', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--infer-dates', '--input', '--install', '--instructions-only', '--issuer-url', '--job-isolation', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--legacy-lock', '--limit', '--link', '--list', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--mcp-only', '--mcp-url', '--migrate-only', '--migration', '--min-n', '--mode', '--model', '--no-autopilot-install', '--no-autostash', '--no-delegate', '--no-embed', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-git', '--no-hooks', '--no-instructions', '--no-lanes', '--no-llm', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--non-interactive', '--oauth-client-id', '--oauth-client-secret', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--preview', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--query', '--question', '--quiet', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retire', '--retry-failed', '--retry-parked', '--runtime', '--save', '--schema-pack', '--scope', '--scopes', '--search-mode', '--section', '--segmented', '--self-transfer', '--semantic', '--session', '--session-id', '--shared-skills', '--show-toplevel', '--side', '--since', '--since-last-run', '--skip', '--skip-embed-check', '--skip-failed', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--unsettle', '--url', '--url-env', '--user', '--vacuum', '--verbose', '--version', '--wait', '--warn-only', '--watch', '--working-tree', '--workspace', '--yes'],'integrations': ['--auto', '--brain', '--dry-run', '--help', '--json', '--overwrite', '--refresh', '--source', '--target'],'integrity': ['--accept-pending', '--auto', '--backend', '--background', '--body', '--brain', '--check', '--confidence', '--cost', '--dry-run', '--explain', '--follow', '--fresh', '--help', '--json', '--limit', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--review-lower', '--skip-bare-tweet', '--skip-urls', '--source', '--timeout', '--timings', '--type', '--wait'],'jobs': ['--abbrev-ref', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt-slug-path', '--aliases', '--all', '--all-sources', '--allow-empty', '--allow-shell-jobs', '--allowed-operations', '--apply', '--asof', '--assign-corpus', '--auto', '--background', '--backoff-delay', '--backoff-jitter', '--backoff-type', '--batch-size', '--body', '--bound-slug-prefixes', '--brain', '--break-lock', '--budget-ms', '--by-mention', '--cached', '--catch-up', '--channel', '--check', '--clear', '--cli-path', '--client', '--close', '--cluster-errors', '--concurrency', '--confidence', '--confirm-destructive', '--confirm-relocated-root', '--cost-estimate', '--cursor', '--date', '--dated-since', '--days', '--delay', '--detach', '--detail', '--diff-filter', '--dir', '--drain', '--drain-timeout', '--dry-run', '--embedding-dimensions', '--embedding-model', '--empty', '--enable', '--entities', '--exclude', '--exclude-standard', '--expect', '--expect-local', '--expect-upstream', '--expected-state', '--explain', '--facts', '--federated-read', '--ff-only', '--file', '--filters', '--finished-since', '--fix', '--follow', '--force', '--force-break-lock', '--force-retry', '--format', '--fresh', '--from-index', '--from-meetings', '--full', '--full-history', '--fuzzy', '--git', '--grammar', '--grammar-diagnostics', '--group', '--group-by', '--hard-deadline', '--health-interval', '--held', '--help', '--hold-state', '--http', '--id', '--idempotency-key', '--ids', '--images', '--include-ambiguous', '--include-deleted', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-null-signature', '--infer-dates', '--inject-bootstrap', '--inline', '--input', '--install', '--interval', '--is-ancestor', '--is-shallow-repository', '--job-id', '--job-isolation', '--json', '--keep', '--kind', '--lanes', '--legacy-lock', '--limit', '--list', '--local', '--lock-duration-ms', '--log-noop', '--markdown', '--max-age', '--max-attempts', '--max-cost', '--max-cost-usd', '--max-crashes', '--max-rss', '--max-sources', '--max-stalled', '--max-usd', '--max-waiting', '--mcp-only', '--migration', '--min-context', '--missing-path', '--mode', '--model', '--multimodal', '--name', '--name-only', '--ner', '--nice', '--no-auto-embed', '--no-autopilot-install', '--no-bulk', '--no-confirm', '--no-delegate', '--no-embed', '--no-embedding', '--no-extract', '--no-gpg-sign', '--no-hard-deadline', '--no-inject', '--no-lanes', '--no-llm', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--no-worker', '--non-interactive', '--now', '--older-than', '--once', '--only', '--order', '--others', '--output', '--override-disabled', '--oversized', '--pace', '--pace-max-concurrency', '--pack', '--page', '--parallel', '--params', '--parked-code', '--pat-file', '--path', '--pause', '--pglite', '--phase', '--pid-file', '--plan', '--port', '--prefer', '--preview', '--priority', '--probe', '--prune-orphans', '--pull', '--purge', '--question', '--queue', '--queue-only', '--quiet', '--rate', '--reason', '--rebuild', '--recent', '--record', '--redact-paths', '--redact-secrets', '--reenrich-after', '--refresh-ms', '--refresh-operations', '--remediate', '--repo', '--request-id', '--reset-checkpoint', '--restart-only', '--resume', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--review-lower', '--row', '--save', '--scope', '--scopes', '--section', '--segment-limit', '--segmented', '--select', '--self-transfer', '--serial', '--session', '--show-toplevel', '--side', '--sigkill-rescue', '--since', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--sleep', '--slug', '--slugs', '--source', '--source-guard', '--source-id', '--sources', '--src-subpath', '--staged', '--stale', '--state', '--statement-timeout', '--status', '--stop-mcp', '--strategy', '--suites', '--surface', '--swap-only', '--target', '--thin', '--thin-threshold', '--tier', '--timeout', '--timeout-ms', '--to', '--token', '--trust', '--type', '--types', '--uninstall', '--updated-after', '--url', '--user', '--vectors', '--verbose', '--verify', '--version', '--watch', '--wedge-rescue', '--workers', '--working-tree', '--yes'],@@ -113,7 +113,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'repair': ['--accept-pending', '--acknowledge-managed', '--after', '--all', '--all-drifted', '--apply', '--background', '--brain', '--break-lock', '--class', '--client', '--close', '--cursor', '--day', '--diff', '--expect', '--explain', '--ff-only', '--follow', '--force', '--force-break-lock', '--from', '--full', '--full-history', '--generation', '--held', '--help', '--id', '--include-ambiguous', '--include-cross-entity', '--include-failures', '--include-repairs', '--json', '--keep', '--key', '--kind', '--limit', '--max-cost', '--max-cost-usd', '--max-usd', '--mode', '--no-accept-pending', '--no-delegate', '--no-embed', '--no-llm', '--older-than', '--only', '--prefer', '--probe', '--progress-interval', '--progress-json', '--provenance', '--quiet', '--remediate', '--remediation-plan', '--request', '--request-id', '--reset-checkpoint', '--retry-failed', '--run', '--scopes', '--side', '--since', '--skip', '--skip-failed', '--slug', '--slugs', '--source', '--stale', '--state', '--timeout', '--timings', '--url', '--wait', '--yes'],'repair-jsonb': ['--accept-pending', '--background', '--brain', '--dry-run', '--explain', '--follow', '--help', '--json', '--no-accept-pending', '--probe', '--progress-interval', '--progress-json', '--quiet', '--source', '--supabase', '--timeout', '--timings', '--url', '--wait'],'report': ['--brain', '--content', '--dir', '--help', '--json', '--source', '--title', '--type'],- 'repos': ['--abandon', '--abbrev-ref', '--abort', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--audit', '--auto-additive', '--autostash', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--force', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--limit', '--local', '--local-env-vars', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--message', '--migrate-legacy', '--migration', '--min-trust', '--name', '--name-only', '--no-autostash', '--no-cron', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-harden', '--no-lanes', '--no-pull', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--preview', '--probe', '--profile', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--rebase', '--redirect-uri', '--refresh-operations', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retry-failed', '--sample', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--takes-holders', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--unindexed', '--unset-all', '--unsettle', '--untracked-files', '--url', '--usage', '--verify', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],+ 'repos': ['--abandon', '--abbrev-ref', '--abort', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--audit', '--auto-additive', '--autostash', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--force', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--limit', '--local', '--local-env-vars', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--message', '--migrate-legacy', '--migration', '--min-trust', '--name', '--name-only', '--no-autostash', '--no-cron', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-harden', '--no-lanes', '--no-pull', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--preview', '--probe', '--profile', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--rebase', '--redirect-uri', '--refresh-operations', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retire', '--retry-failed', '--sample', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--takes-holders', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--unindexed', '--unset-all', '--unsettle', '--untracked-files', '--url', '--usage', '--verify', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],'resolvers': ['--backend', '--brain', '--cost', '--help', '--json', '--source'],'retrieval-upgrade': ['--accept-pending', '--all', '--background', '--batch-size', '--brain', '--catch-up', '--dim', '--dry-run', '--embedding-dimensions', '--embedding-model', '--explain', '--facts', '--follow', '--force', '--held', '--help', '--ignore-env-override', '--images', '--include-null-signature', '--json', '--max-cost-usd', '--max-usd', '--no-accept-pending', '--no-embed', '--non-interactive', '--only', '--oversized', '--pace', '--pace-max-concurrency', '--plan', '--priority', '--progress-interval', '--progress-json', '--quiet', '--replace', '--reranker', '--retarget', '--slugs', '--source', '--stale', '--status', '--timeout', '--timings', '--to', '--wait', '--yes'],'routing-eval': ['--brain', '--help', '--json', '--llm', '--skills-dir', '--source'],@@ -127,7 +127,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'skillpack': ['--all', '--apply-clean-hunks', '--author', '--auto', '--brain', '--dest', '--dry-run', '--env', '--exit-code', '--fast', '--fix', '--force-unlock', '--format', '--from', '--full', '--harness', '--help', '--homepage', '--json', '--license', '--list', '--minimal', '--name-only', '--no-cache', '--no-lint', '--note', '--out', '--overwrite-local', '--persona', '--probe', '--pure', '--push', '--quick', '--quiet', '--refresh', '--repo', '--schema-pack', '--scope', '--short', '--since', '--skill', '--skills', '--skills-dir', '--skip-doctor', '--source', '--strict', '--stub', '--supabase', '--target', '--tier', '--trust', '--url', '--verify', '--version', '--workspace', '--yes'],'skillpack-check': ['--accept-pending', '--background', '--brain', '--explain', '--fast', '--follow', '--help', '--json', '--list', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--source', '--strict', '--timeout', '--timings', '--wait', '--yes'],'smoke-test': ['--brain', '--help', '--json', '--source'],- 'sources': ['--abandon', '--abbrev-ref', '--abort', '--accept-pending', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--audit', '--auto-additive', '--autostash', '--background', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--db-url', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--explain', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--follow', '--force', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--legacy-lock', '--limit', '--local', '--local-env-vars', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--message', '--migrate-legacy', '--migration', '--min-trust', '--name', '--name-only', '--no-accept-pending', '--no-autostash', '--no-cron', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-harden', '--no-lanes', '--no-pull', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--preview', '--probe', '--profile', '--progress-interval', '--progress-json', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--rebase', '--redirect-uri', '--refresh-operations', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retry-failed', '--sample', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--takes-holders', '--timeout', '--timings', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--unindexed', '--unset-all', '--unsettle', '--untracked-files', '--url', '--usage', '--verify', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],+ 'sources': ['--abandon', '--abbrev-ref', '--abort', '--accept-pending', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--audit', '--auto-additive', '--autostash', '--background', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--db-url', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--explain', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--follow', '--force', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--legacy-lock', '--limit', '--local', '--local-env-vars', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--message', '--migrate-legacy', '--migration', '--min-trust', '--name', '--name-only', '--no-accept-pending', '--no-autostash', '--no-cron', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-harden', '--no-lanes', '--no-pull', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--preview', '--probe', '--profile', '--progress-interval', '--progress-json', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--rebase', '--redirect-uri', '--refresh-operations', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retire', '--retry-failed', '--sample', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--takes-holders', '--timeout', '--timings', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--unindexed', '--unset-all', '--unsettle', '--untracked-files', '--url', '--usage', '--verify', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],'status': ['--abbrev-ref', '--acknowledge-managed', '--all', '--allow-empty', '--apply', '--body', '--brain', '--break-lock', '--cached', '--check', '--concurrency', '--confirm-destructive', '--count', '--cursor', '--deadline-ms', '--delete', '--detail', '--diff-filter', '--empty', '--enable', '--exclude', '--exclude-standard', '--fast', '--filters', '--fix', '--force-break-lock', '--format', '--full', '--full-history', '--funnel', '--hard-deadline', '--help', '--hold-state', '--include-gitignored', '--include-hidden', '--install', '--interval', '--is-ancestor', '--is-shallow-repository', '--json', '--lanes', '--limit', '--max-age', '--max-sources', '--mcp-only', '--missing-path', '--name-only', '--no-auto-embed', '--no-bulk', '--no-delegate', '--no-embed', '--no-extract', '--no-gpg-sign', '--no-hard-deadline', '--no-lanes', '--no-llm', '--no-pull', '--no-renames', '--no-repair', '--no-schema-pack', '--no-verify', '--no-walk', '--others', '--parallel', '--path', '--prefer', '--preview', '--priority', '--quiet', '--redact-paths', '--repo', '--request-id', '--reset-checkpoint', '--retry-failed', '--retry-held', '--reverse', '--section', '--serial', '--show-toplevel', '--skip-failed', '--slugs', '--source', '--source-id', '--src-subpath', '--stale', '--status', '--strategy', '--timeout', '--url', '--verify', '--watch', '--workers', '--working-tree', '--yes'],'storage': ['--brain', '--help', '--json', '--plan', '--repo', '--restore-only', '--source', '--to'],'sweep': ['--accept-pending', '--apply', '--assign-corpus', '--background', '--batch-limit', '--brain', '--budget-ms', '--delete-brain', '--explain', '--follow', '--help', '--home', '--json', '--no-accept-pending', '--no-delegate', '--once', '--only', '--progress-interval', '--progress-json', '--quiet', '--retry-failed', '--session', '--source', '--source-id', '--stale', '--timeout', '--timings', '--wait'],diff --git a/src/core/persistence/administration.ts b/src/core/persistence/administration.tsindex ac23522617..5eb8a37080 100644--- a/src/core/persistence/administration.ts+++ b/src/core/persistence/administration.ts@@ -221,8 +221,8 @@ export async function runPersistenceAdministration(engine: BrainEngine, operatioreturn (await import('./effect-retry.ts')).retryRequestEffects(engine, source(params.source_id), params.request_id, params.dry_run === true, config, embeddingRetryPolicy, ownerHost);}if (operation === 'writer_settle_effects') {- keys(params, ['source_id', 'request_id', 'parked_code', 'unsettle', 'apply', 'expect', 'dry_run']);- bool(params, 'unsettle'); bool(params, 'apply');+ keys(params, ['source_id', 'request_id', 'parked_code', 'unsettle', 'retire', 'apply', 'expect', 'dry_run']);+ bool(params, 'unsettle'); bool(params, 'retire'); bool(params, 'apply');if (params.apply === true && params.dry_run === true) throw invalid('settle-effects takes --dry-run or --apply, not both.','Preview with --dry-run, then run the apply_command it prints (--apply --expect <plan_hash>) after the user agrees.');if (params.parked_code !== undefined && (typeof params.parked_code !== 'string' || !/^[a-z][a-z0-9_]*$/.test(params.parked_code))) throw invalid('Invalid --parked-code value.',@@ -233,7 +233,7 @@ export async function runPersistenceAdministration(engine: BrainEngine, operatioconst requestId = params.request_id === undefined ? undefined : uuid(params.request_id, 'A valid original write request UUID is required.','Pass --request-id with the request id doctor parked_effects or gbrain sources writer status lists for the effect.');return (await import('./effect-settle.ts')).settleEffects(engine, { sourceId, requestId, parkedCode: params.parked_code as string | undefined,- unsettle: params.unsettle === true, apply: params.apply === true, expect: params.expect as string | undefined });+ unsettle: params.unsettle === true, retire: params.retire === true, apply: params.apply === true, expect: params.expect as string | undefined });}if (operation === 'source_add' || operation === 'source_lifecycle') {const { managedPersistenceEnabled } = await import('./ownership.ts');diff --git a/src/core/persistence/effect-model.ts b/src/core/persistence/effect-model.tsindex e673e8c8e5..2adade7ea5 100644--- a/src/core/persistence/effect-model.ts+++ b/src/core/persistence/effect-model.ts@@ -38,8 +38,12 @@ export interface ParkedTarget { slug?: string; error_code: string; rule?: string/** #7423 / #7378: a settled target: under a declared db_only dir (`declared`), or its current bytes proved on the fetched remote (effect-settle.ts). */export type SettledTarget = { slug: string; declared: string }| { slug: string; path: string; remote_ref: string; remote_commit: string; blob: string; receipt_request_id: string };+/** #7985: a target of a retired former-binding effect: its page is gone, deleted, replaced or past the revision the effect owed, or its source was replaced. */+export type RetiredTarget = { slug: string; page: 'source_replaced' | 'absent' | 'deleted' | 'replaced' | 'moved'; owed_revision: string | null; current_revision?: string };export type SettlementProof = { kind: 'db_only'; worktree_id: string; targets: SettledTarget[] }- | { kind: 'superseded_remote'; former_worktree_id: string; worktree_id: string; targets: SettledTarget[] };+ | { kind: 'superseded_remote'; former_worktree_id: string; worktree_id: string; targets: SettledTarget[] }+ | { kind: 'former_binding_retired'; reason: 'source_replaced' | 'page_moved'; former_worktree_id: string | null; former_incarnation: string;+ worktree_id: string; source_incarnation: string | null; targets: RetiredTarget[] };/** The disposition `gbrain sources writer settle-effects` records on a Git effect whose retry can never succeed. */export interface EffectSettlement { reason: SettlementProof['kind']; at: string; host_id: string; plan_hash: string; proof: SettlementProof }/** `page_body_segmented`: a segmented page an older binary's mirror or Git scan passed by; this one mirrors and commits it. */diff --git a/src/core/persistence/effect-settle.ts b/src/core/persistence/effect-settle.tsindex 67fa958a12..0c6886c115 100644--- a/src/core/persistence/effect-settle.ts+++ b/src/core/persistence/effect-settle.ts@@ -14,6 +14,11 @@* current worktree committed and pushed the bytes the canonical file holds now, and the already-fetched remote-tracking* ref of the checkout's branch holds exactly those bytes at that path. Nothing is fetched: a missing ref, or a ref* that lacks bytes a push reported, refuses.+ * - `former_binding_retired` (#7985, only with `--retire`): the binding guard refuses the effect as `source_changed`+ * and nothing current owes its bytes: the source was archived, removed or re-created after it (`source_replaced`; the+ * original writer is not re-checked, its source is gone), or each target's page is gone, deleted, replaced by another+ * page or at a later revision than the one the effect owed (`page_moved`; a revision changes only when a write commits). A page still at that revision refuses `page_not_moved`+ * (write it through gbrain, then preview again); an effect of the current binding refuses `not_former_binding`.* Unknown targets, a withdrawal or other non-Git effect, a claimed effect, an open recovery record, a revoked original* writer, a replaced source and a binding this host does not own are refused. An effect of the current binding that is* not db_only is refused as `retry_instead`: `retry-effects` can still run it.@@ -38,10 +43,10 @@ import { persistenceFileHash } from './coordinator.ts';import { sourceDbOnlyDir } from './source-storage.ts';import { declarePersistenceProtocol } from './protocol.ts';import { GIT_PUSH_CODES } from './git-push-holds.ts';-import type { EffectSettlement, ParkedTarget, PersistenceEffect, SettlementProof, SettledTarget } from './effect-model.ts';+import type { EffectSettlement, ParkedTarget, PersistenceEffect, RetiredTarget, SettlementProof, SettledTarget } from './effect-model.ts';import type { WriteRequest } from './model.ts';-export interface SettleEffectsInput { sourceId: string; requestId?: string; parkedCode?: string; unsettle?: boolean; apply?: boolean; expect?: string }+export interface SettleEffectsInput { sourceId: string; requestId?: string; parkedCode?: string; unsettle?: boolean; retire?: boolean; apply?: boolean; expect?: string }type Refusal = { code: string; message: string };type Row = PersistenceEffect & { request: WriteRequest };interface Entry {@@ -88,8 +93,19 @@ async function remoteProof(tx: BrainEngine, effect: PersistenceEffect, binding:return { slug, path, remote_ref: ref, remote_commit: commit, blob: fileBlob, receipt_request_id: receipt.request_id };}+/** #7985: why nothing current owes this former-binding effect's target any more, or the refusal when its page still sits at the owed revision. */+async function retiredTarget(tx: BrainEngine, effect: PersistenceEffect, slug: string): Promise<RetiredTarget | Refusal> {+ const owed = effect.data.slug === slug ? effect.revision : null;+ const snapshot = await tx.readPageSnapshot(slug, { sourceId: effect.source_id, includeDeleted: true });+ if (!snapshot || snapshot.sourceIncarnation !== effect.source_incarnation) return { slug, page: 'absent', owed_revision: owed };+ if (snapshot.page.deleted_at) return { slug, page: 'deleted', owed_revision: owed, current_revision: snapshot.revision };+ if (owed !== null && effect.data.page_id !== undefined && String(snapshot.page.id) !== String(effect.data.page_id)) return { slug, page: 'replaced', owed_revision: owed, current_revision: snapshot.revision };+ if (owed !== null && snapshot.revision !== owed) return { slug, page: 'moved', owed_revision: owed, current_revision: snapshot.revision };+ return { code: 'page_not_moved', message: `Page ${slug} is still at the revision this effect owes (or the effect records no revision for it), so its bytes are still owed to Git and it is not retired. Write the page through gbrain (its Git effect commits and pushes it), then preview again.` };+}+/** The exact-target proof for one effect, or why it cannot settle. */-async function settleProof(tx: BrainEngine, row: Row, hostId: string, binding: WorktreeBinding | null): Promise<SettlementProof | Refusal> {+async function settleProof(tx: BrainEngine, row: Row, hostId: string, binding: WorktreeBinding | null, retire = false): Promise<SettlementProof | Refusal> {const { request, ...effect } = row;if (effect.kind === 'withdrawal-mirror') return { code: 'withdrawal_effect', message: 'A withdrawal effect is never settled: its file may still hold the withdrawn text.' };if (effect.kind !== 'git') return { code: 'not_git_effect', message: `Only Git effects settle; this ${effect.kind} effect keeps its own retry.` };@@ -103,13 +119,29 @@ async function settleProof(tx: BrainEngine, row: Row, hostId: string, binding: Wif (!(error instanceof OperationError)) throw error;if (error.code !== 'source_changed') return { code: error.code, message: error.message };const [source] = await tx.executeRaw<{ incarnation: string; archived: boolean }>('SELECT incarnation,archived FROM sources WHERE id=$1', [effect.source_id]);- if (!source || source.archived || source.incarnation !== effect.source_incarnation || binding.source_incarnation !== effect.source_incarnation || binding.worktree_id === effect.worktree_id) {- return { code: 'source_replaced', message: `Source ${effect.source_id} was archived, removed or re-created after this effect was recorded, so it owes nothing to the current source.` };+ const replaced = !source || source.archived || source.incarnation !== effect.source_incarnation;+ if (retire && replaced) return { kind: 'former_binding_retired', reason: 'source_replaced', former_worktree_id: effect.worktree_id, former_incarnation: effect.source_incarnation,+ worktree_id: binding.worktree_id, source_incarnation: source?.incarnation ?? null,+ targets: effectTargets(effect).map(target => ({ slug: target.slug ?? '(whole effect)', page: 'source_replaced', owed_revision: effect.data.slug === target.slug ? effect.revision : null })) };+ if (replaced || binding.source_incarnation !== effect.source_incarnation || binding.worktree_id === effect.worktree_id) {+ return { code: 'source_replaced', message: `Source ${effect.source_id} was archived, removed or re-created after this effect was recorded, so it owes nothing to the current source.${replaced ? ' Preview recording that with --retire.' : ''}` };}former = true;}+ if (retire && !former) return { code: 'not_former_binding', message: `This effect belongs to source ${effect.source_id}'s current binding, so it is never retired: retry-effects runs it, or settle-effects without --retire settles a target declared db_only.` };const denied = await storedAuthorityRefusal(tx, request, effect.source_id);if (denied) return { code: 'authority_changed', message: `The original writer is no longer authorized (${denied.message}).` };+ if (retire) {+ const retired: RetiredTarget[] = [];+ for (const target of effectTargets(effect)) {+ if (!target.slug) return { code: 'unknown_target', message: 'A parked entry names no page, so its exact target is unknown.' };+ const evidence = await retiredTarget(tx, effect, target.slug);+ if ('code' in evidence) return evidence;+ retired.push(evidence);+ }+ return { kind: 'former_binding_retired', reason: 'page_moved', former_worktree_id: effect.worktree_id, former_incarnation: effect.source_incarnation,+ worktree_id: binding.worktree_id, source_incarnation: binding.source_incarnation, targets: retired };+ }const sourceRoot = join(binding.local_path, binding.relative_path);const targets: SettledTarget[] = [];for (const target of effectTargets(effect)) {@@ -129,16 +161,19 @@ async function settleProof(tx: BrainEngine, row: Row, hostId: string, binding: W}export async function settleEffects(engine: BrainEngine, input: SettleEffectsInput): Promise<Record<string, unknown> & { plan_hash: string; effects: Entry[] }> {- const { sourceId, requestId, parkedCode, unsettle = false, apply = false } = input;+ const { sourceId, requestId, parkedCode, unsettle = false, retire = false, apply = false } = input;if ((requestId === undefined) === (parkedCode === undefined)) throw opError('invalid_params', 'settle-effects selects with exactly one of --request-id or --parked-code.',`Preview with gbrain sources writer settle-effects ${sourceId} and one parked code doctor parked_effects names (--parked-code), or name one request with --request-id.`, { fix: statusFix(sourceId) });+ if (retire && unsettle) throw opError('invalid_params', 'settle-effects takes --retire or --unsettle, not both.',+ 'A retired effect is un-settled like any other: preview --unsettle with the same selector, without --retire.', { fix: statusFix(sourceId) });if (apply && !input.expect) throw opError('invalid_params', 'settle-effects --apply needs --expect <plan_hash> from its preview.','Run the preview (--dry-run), show the user the plan, and run the apply_command it prints after they agree.', { fix: statusFix(sourceId) });const hostId = existingLocalHostId();if (!hostId) throw opError('permission_denied', 'Settling effects requires the registered local CLI host.',`This machine has no registered gbrain host identity, so it cannot settle effects of source ${sourceId}; nothing changed. Run it on the brain host that owns ${sourceId}.`, { fix: statusFix(sourceId) });const selector = requestId !== undefined ? ['--request-id', requestId] : ['--parked-code', parkedCode!];- const mode = unsettle ? 'unsettle' : 'settle';+ const mode = unsettle ? 'unsettle' : retire ? 'retire' : 'settle';+ const modeFlags = unsettle ? ['--unsettle'] : retire ? ['--retire'] : [];return engine.transaction(async tx => {await declarePersistenceProtocol(tx);await tx.executeRaw("SELECT set_config('synchronous_commit','on',true),set_config('lock_timeout','2s',true),set_config('statement_timeout','10s',true)");@@ -154,7 +189,7 @@ export async function settleEffects(engine: BrainEngine, input: SettleEffectsInpconst entry = { effect_id: String(row.id), request_id: (row as Row & { public_request_id: string }).public_request_id, kind: row.kind, error_code: row.error_code,worktree_id: row.worktree_id, targets: effectTargets(row) };if (unsettle) { effects.push({ ...entry, action: 'would_unsettle', settled: row.data.settled }); continue; }- const proof = await settleProof(tx, row, hostId, binding);+ const proof = await settleProof(tx, row, hostId, binding, retire);effects.push('code' in proof ? { ...entry, action: 'refused', refusal: proof } : { ...entry, action: 'would_settle', proof });}const actionable = effects.filter(effect => effect.action !== 'refused');@@ -165,7 +200,7 @@ export async function settleEffects(engine: BrainEngine, input: SettleEffectsInpif (apply) {if (input.expect !== planHash) throw opError('preview_changed', `The settle plan changed since its preview (--expect ${input.expect}, current plan ${planHash}); nothing was changed.`,'Preview again, show the user the new plan, and run its apply_command only if they approve it.',- { fix: readFix('Shows the current settle plan and its plan_hash, read-only.', { argv: ['gbrain', 'sources', 'writer', 'settle-effects', sourceId, ...selector, ...(unsettle ? ['--unsettle'] : []), '--dry-run', '--json'] }) });+ { fix: readFix('Shows the current settle plan and its plan_hash, read-only.', { argv: ['gbrain', 'sources', 'writer', 'settle-effects', sourceId, ...selector, ...modeFlags, '--dry-run', '--json'] }) });const at = new Date().toISOString();for (const effect of actionable) {if (unsettle) {@@ -181,18 +216,20 @@ export async function settleEffects(engine: BrainEngine, input: SettleEffectsInpeffect.action = 'settled';}}- const applyCommand = ['gbrain', 'sources', 'writer', 'settle-effects', sourceId, ...selector, ...(unsettle ? ['--unsettle'] : []), '--apply', '--expect', planHash];+ const applyCommand = ['gbrain', 'sources', 'writer', 'settle-effects', sourceId, ...selector, ...modeFlags, '--apply', '--expect', planHash];const preview = !apply && actionable.length > 0;return { action: 'writer_settle_effects', source_id: sourceId, mode, dry_run: !apply, plan_hash: planHash, settleable: actionable.length,refused: effects.length - actionable.length, effects,- ...(preview ? { apply_command: applyCommand, fix: { ask_user: true, argv: applyCommand, consent: [], actor: 'agent', requires_exclusive: false,+ ...(preview ? { apply_command: applyCommand, fix: { ask_user: true, argv: applyCommand, consent: [], actor: retire ? 'user' : 'agent', requires_exclusive: false,why: unsettle ? 'Removes the settled disposition so the effects are held and reported again; the settlement stays in their history.'- : 'Records a settled disposition on each listed effect (its failure, request and target bytes are kept), so doctor and retries stop reporting it.',+ : retire ? 'Records that nothing current owes these former-binding effects a Git backup (their source was replaced, or their page moved on or was deleted); failure, request and bytes are kept and nothing is retried.'+ : 'Records a settled disposition on each listed effect (its failure, request and target bytes are kept), so doctor and retries stop reporting it.',user_message: unsettle ? `Un-settle ${actionable.length} effect(s) of source ${sourceId}, so doctor reports them again?`- : `Settle ${actionable.length} Git effect(s) of source ${sourceId} whose retry can never succeed? Each has the proof shown; their failures stay in history and --unsettle reverses it.`,+ : retire ? `Retire ${actionable.length} Git effect(s) of source ${sourceId} recorded under a former binding? The evidence shown says nothing current owes their Git backup: the old write stays committed in the database and in history, no Git backup of those old bytes will be made, and --unsettle reverses it.`+ : `Settle ${actionable.length} Git effect(s) of source ${sourceId} whose retry can never succeed? Each has the proof shown; their failures stay in history and --unsettle reverses it.`,verify: { argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] } } satisfies Action } : {}),next: preview ? 'Show the user each proof; run apply_command (bound to this plan_hash) only after they agree.'- : apply ? `${actionable.length} effect(s) ${unsettle ? 'un-settled' : 'settled'}; doctor parked_effects and writer status reflect it now.`+ : apply ? `${actionable.length} effect(s) ${unsettle ? 'un-settled' : retire ? 'retired' : 'settled'}; doctor parked_effects and writer status reflect it now.`: effects.length ? 'No listed effect can settle; each refusal names its cause.' : `No ${unsettle ? 'settled' : 'unsettled parked or failed'} effect matches this selector.` };});}diff --git a/src/core/persistence/parked-groups.ts b/src/core/persistence/parked-groups.tsindex 007f2ff89b..a2b2646bda 100644--- a/src/core/persistence/parked-groups.ts+++ b/src/core/persistence/parked-groups.ts@@ -22,7 +22,7 @@ export const CURRENT_BINDING_SQL = `(e.worktree_id IS NULL OR EXISTS (SELECT 1 F* group names the .gitignore rule and says the rule has to change first: a retry while it stands parks again. Other groups* also name the settle preview (#7423, #7378) for targets a retry can never move; settled effects are not counted.* #7985: effects of a former binding form their own group (`former_binding`) naming their recorded worktree, the current- * one, up to five request ids and the settle preview, never the bulk retry that cannot select them.+ * one, up to five request ids and the settle preview (`--retire` for a replaced source), never the bulk retry that cannot select them.*/export async function readParkedGroups(engine: Pick<BrainEngine, 'executeRaw'>, sourceIds?: string[]): Promise<ParkedGroup[]> {const rows = await engine.executeRaw<{ source_id: string; code: string; former: FormerBinding['reason'] | null; effects: number; targets: number;@@ -41,11 +41,11 @@ export async function readParkedGroups(engine: Pick<BrainEngine, 'executeRaw'>,FROM parked GROUP BY source_id, code, former ORDER BY source_id, code, former NULLS FIRST`, [sourceIds ?? null]);return rows.map(({ rule, former, worktree_ids, current_worktree_id, requests, ...row }) => {if (former) {- const command = ['gbrain', 'sources', 'writer', 'settle-effects', row.source_id, '--parked-code', row.code, '--dry-run'];+ const command = ['gbrain', 'sources', 'writer', 'settle-effects', row.source_id, '--parked-code', row.code, ...(former === 'source_replaced' ? ['--retire'] : []), '--dry-run'];const recorded = `${row.effects} parked Git effect(s) of source ${row.source_id} (requests ${requests.join(', ')}) were recorded under worktree ${worktree_ids.join(', ')}`;const next = former === 'binding_changed'- ? `${recorded}, a former canonical binding: the source is now bound to ${current_worktree_id ?? 'no worktree'}. retry-effects refuses them (source_changed) and the bulk retry selects none of them, so its zero is not a clearance. Preview settling them on proof: ${command.join(' ')}; an effect it refuses stays parked and its refusal names what is missing. Never claim or transfer the source to force them through.`- : `${recorded}, under an earlier incarnation of the source (archived, removed or re-created since), so they owe nothing to the current source: neither retry-effects nor settle-effects runs them (settle refuses source_replaced). They stay parked as history; never re-create, claim or transfer the source to force them through.`;+ ? `${recorded}, a former canonical binding: the source is now bound to ${current_worktree_id ?? 'no worktree'}. retry-effects refuses them (source_changed) and the bulk retry selects none of them, so its zero is not a clearance. Preview settling them on proof: ${command.join(' ')}; an effect it refuses stays parked and its refusal names what is missing. One whose page has since moved on or been deleted can be retired instead (the same preview with --retire; ask the user before applying). Never claim or transfer the source to force them through.`+ : `${recorded}, under an earlier incarnation of the source (archived, removed or re-created since), so they owe nothing to the current source and retry never runs them. Preview recording that: ${command.join(' ')}, and apply it only after the user agrees; never re-create, claim or transfer the source to force them through.`;return { ...row, command, next, former_binding: { reason: former, worktree_ids, current_worktree_id, requests } };}const push = (GIT_PUSH_CODES as readonly string[]).includes(row.code);diff --git a/test/orphan-effect-diagnostics-7985.test.ts b/test/orphan-effect-diagnostics-7985.test.tsindex 222b4c8489..09eea659ce 100644--- a/test/orphan-effect-diagnostics-7985.test.ts+++ b/test/orphan-effect-diagnostics-7985.test.ts@@ -4,6 +4,9 @@* the parked groups (doctor \`parked_effects\`, \`sources writer status\`) give such effects their own group naming the* recorded worktree, the current one, the requests and the settle preview; doctor's per-effect command is that preview;* the exact retry refusal names both bindings and the settle preview; the bulk retry names the effects it leaves out.+ * \`settle-effects --retire\` records that nothing current owes such an effect, only on evidence: its source was replaced,+ * or each target's page is gone, deleted, replaced or past the revision the effect owed. It is preview-first, plan-bound,+ * idempotent and reversible, never requeues, and the exact retry still refuses the effect.* PGLite always; Postgres too when DATABASE_URL is set.*/import { describe, expect, test } from 'bun:test';@@ -23,6 +26,7 @@ import { getWorktreeBinding } from '../src/core/persistence/ownership.ts';import { runManagedSourceLifecycle } from '../src/core/persistence/source-lifecycle.ts';import { isPhysicalRootMetadata } from '../src/core/persistence/physical-root.ts';import { checkParkedEffects } from '../src/commands/doctor/checks/parked-effects.ts';+import { parsePersistenceAdminArgs } from '../src/commands/persistence-admin.ts';import { managedBrain } from './helpers/managed-brain.ts';import { durableGitRepo } from './helpers/git-publication.ts';@@ -44,6 +48,17 @@ async function park(engine: BrainEngine, slug: string) {return effect!;}+async function moveToNewWorktree(engine: BrainEngine, root: string) {+ const old = (await getWorktreeBinding(engine, 'default'))!;+ const moved = join(dirname(root), 'moved');+ cpSync(root, moved, { recursive: true, filter: path => !isPhysicalRootMetadata(basename(path)) });+ await runManagedSourceLifecycle(engine, { operation: 'rebind', sourceId: 'default', path: moved });+ return { old, current: (await getWorktreeBinding(engine, 'default'))! };+}+type History = { state: string; error_code: string | null; parked: unknown; worktree_id: string; settled: unknown; request_state: string };+const history = async (engine: BrainEngine, id: number) => (await engine.executeRaw<History>(`SELECT e.state,e.error_code,e.data->'parked' AS parked,+ e.worktree_id::text AS worktree_id,e.data->'settled' AS settled,r.state AS request_state FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id WHERE e.id=$1`, [id]))[0]!;+describe.each(backends.map(url => [url ? 'postgres' : 'pglite', url] as const))('#7985 effects of a former binding (%s)', (_name, url) => {test('the diagnostics name a former-binding effect, its recorded binding and the settle preview, apart from the current binding', () => managedBrain(async ({ engine, ctx, root }) => {await put(ctx, 'aa/page', 'Parked under the old binding.');@@ -96,7 +111,77 @@ describe.each(backends.map(url => [url ? 'postgres' : 'pglite', url] as const))(await sql(engine, 'UPDATE persistence_effects SET source_incarnation=$2::uuid WHERE id=$1', [orphan.id, randomUUID()]);const replaced = (await readParkedGroups(engine, ['default']))[1]!;- expect(replaced).toMatchObject({ command: settleCode, former_binding: { reason: 'source_replaced', requests: [orphan.request_id] } });+ expect(replaced).toMatchObject({ command: [...settleCode.slice(0, -1), '--retire', '--dry-run'], former_binding: { reason: 'source_replaced', requests: [orphan.request_id] } });expect(replaced.next).toContain('earlier incarnation of the source');}, { databaseUrl: url, setup: ({ root }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); } }), 240_000);++ test('--retire settles a former-binding effect only when its page moved on, was deleted or its source was replaced, and the exact retry still refuses it', () => managedBrain(async ({ engine, ctx, root }) => {+ await put(ctx, 'aa/page', 'Parked under the old binding.');+ const moved = await park(engine, 'aa/page');+ await put(ctx, 'cc/page', 'Parked under the old binding.');+ const deleted = await park(engine, 'cc/page');+ await put(ctx, 'dd/page', 'Parked under the old binding, still current.');+ const owed = await park(engine, 'dd/page');+ const { old, current } = await moveToNewWorktree(engine, root);+ await put(ctx, 'bb/page', 'Parked under the current binding.');+ const live = await park(engine, 'bb/page');+ const retire = (apply?: string) => settleEffects(engine, { sourceId: 'default', parkedCode: 'git_unavailable', retire: true, ...(apply ? { apply: true, expect: apply } : {}) });+ const outcome = async () => Object.fromEntries(((await retire()).effects as Array<{ request_id: string; action: string; refusal?: { code: string } }>)+ .map(entry => [{ [moved.request_id]: 'aa', [deleted.request_id]: 'cc', [owed.request_id]: 'dd', [live.request_id]: 'bb' }[entry.request_id], entry.refusal?.code ?? entry.action]));+ expect(await outcome()).toEqual({ aa: 'page_not_moved', cc: 'page_not_moved', dd: 'page_not_moved', bb: 'not_former_binding' });++ await put(ctx, 'aa/page', 'Second version, through the current binding.');+ const snapshot = await engine.readPageSnapshot('cc/page', { sourceId: 'default' });+ await submitPageMutation(ctx, { operation: 'delete_page', params: { slug: 'cc/page', expected_revision: snapshot!.revision, request_id: randomUUID() } });+ await disposePersistenceConsumer(engine);+ expect(await outcome()).toEqual({ aa: 'would_settle', cc: 'would_settle', dd: 'page_not_moved', bb: 'not_former_binding' });++ const before = await Promise.all([moved, deleted, owed, live].map(effect => history(engine, effect.id)));+ const preview = await retire();+ expect(preview).toMatchObject({ mode: 'retire', dry_run: true, settleable: 2, refused: 2,+ apply_command: ['gbrain', 'sources', 'writer', 'settle-effects', 'default', '--parked-code', 'git_unavailable', '--retire', '--apply', '--expect', preview.plan_hash],+ fix: { ask_user: true, actor: 'user' } });+ const proofs = Object.fromEntries((preview.effects as Array<{ request_id: string; proof?: Record<string, unknown> }>).filter(entry => entry.proof).map(entry => [entry.request_id, entry.proof]));+ expect(proofs[moved.request_id]).toMatchObject({ kind: 'former_binding_retired', reason: 'page_moved', former_worktree_id: old.worktree_id, worktree_id: current.worktree_id,+ targets: [{ slug: 'aa/page', page: 'moved', owed_revision: expect.any(String), current_revision: expect.any(String) }] });+ expect(proofs[deleted.request_id]).toMatchObject({ reason: 'page_moved', targets: [{ slug: 'cc/page', page: 'deleted' }] });+ expect(await Promise.all([moved, deleted, owed, live].map(effect => history(engine, effect.id)))).toEqual(before);++ const plain = await settleEffects(engine, { sourceId: 'default', parkedCode: 'git_unavailable' });+ await expect(retire(plain.plan_hash)).rejects.toMatchObject({ code: 'preview_changed' });+ await expect(retire('ph_000000000000000000000000')).rejects.toMatchObject({ code: 'preview_changed' });+ expect((await history(engine, moved.id)).settled).toBeNull();++ expect(await retire(preview.plan_hash)).toMatchObject({ dry_run: false, settleable: 2 });+ for (const [index, effect] of [moved, deleted].entries()) {+ const { settled, ...after } = await history(engine, effect.id);+ const { settled: was, ...kept } = before[index]!;+ expect(was).toBeNull();+ expect(after).toEqual(kept);+ expect(settled).toMatchObject({ reason: 'former_binding_retired', plan_hash: preview.plan_hash, proof: { kind: 'former_binding_retired' } });+ }+ expect(await Promise.all([owed, live].map(effect => history(engine, effect.id)))).toEqual(before.slice(2));+ await expect(retire(preview.plan_hash)).rejects.toMatchObject({ code: 'preview_changed' });+ expect(await outcome()).toEqual({ dd: 'page_not_moved', bb: 'not_former_binding' });+ expect((await readParkedGroups(engine, ['default'])).map(group => [group.effects, group.former_binding?.requests ?? null]))+ .toEqual([[1, null], [1, [owed.request_id]]]);+ await expect(retryParkedEffects(engine, 'default', moved.request_id, true)).rejects.toMatchObject({ code: 'source_changed' });++ const undo = await settleEffects(engine, { sourceId: 'default', requestId: moved.request_id, unsettle: true });+ expect(await settleEffects(engine, { sourceId: 'default', requestId: moved.request_id, unsettle: true, apply: true, expect: undo.plan_hash }))+ .toMatchObject({ effects: [{ action: 'unsettled' }] });+ expect((await history(engine, moved.id)).settled).toBeNull();++ await sql(engine, 'UPDATE persistence_effects SET source_incarnation=$2::uuid WHERE id=$1', [owed.id, randomUUID()]);+ expect(await settleEffects(engine, { sourceId: 'default', requestId: owed.request_id })).toMatchObject({ settleable: 0,+ effects: [{ action: 'refused', refusal: { code: 'source_replaced', message: expect.stringContaining('--retire') } }] });+ expect(await settleEffects(engine, { sourceId: 'default', requestId: owed.request_id, retire: true })).toMatchObject({ settleable: 1,+ effects: [{ action: 'would_settle', proof: { kind: 'former_binding_retired', reason: 'source_replaced', targets: [{ slug: 'dd/page', page: 'source_replaced' }] } }] });+ await expect(settleEffects(engine, { sourceId: 'default', requestId: owed.request_id, retire: true, unsettle: true })).rejects.toMatchObject({ code: 'invalid_params' });+ }, { databaseUrl: url, setup: ({ root }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); } }), 300_000);+});++test('settle-effects --retire parses to the writer_settle_effects retire flag', () => {+ expect(parsePersistenceAdminArgs('writer', ['settle-effects', 'source-a', '--parked-code', 'git_unavailable', '--retire', '--dry-run', '--json'])).toEqual({+ operation: 'writer_settle_effects', json: true, brain: undefined, params: { source_id: 'source-a', parked_code: 'git_unavailable', retire: true, dry_run: true } });});