Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Persistence train: combine commit-push staging with the skip-worktree filter, one CHANGELOG entry

garrytan68da83db4f12
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9a3b90cdb3..a37e5664c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**Persistence, sync and job fixes, most from community bug reports and each reproduced on master: sync timeouts stop cleanly, held and deleted files release, Postgres pools and deadline reads stop leaking or hanging, derived effects stop reporting false recoveries, and fix commands print what a retry needs.** `gbrain sync --timeout N` now stops as a partial run with exit 0 instead of being killed by its own watchdog, a held deleted file whose page was soft-deleted no longer stays `needs_human`, and `gbrain git commit-push` publishes a staged deletion under a wildcard-ignored folder. A Postgres pool that finishes opening after a reconnect is closed instead of leaking, a managed-sync preparation read gives up at its deadline instead of waiting on a saturated pool, and the sync cost check no longer scans every chunk when nothing has drifted. A `links` or `facts-backstop` effect that meets another write's publication in flight waits as `writer_busy` and retries within a second, instead of reporting `recovery_required` and waiting 30 s. A refused edit's fix command now prints the revision the retry needs, keyless init suggests an import that runs, cancelling a finished job changes nothing, and particle-1 on OpenRouter stops truncating.
+**Persistence, sync and job fixes, most from community bug reports and each reproduced on master: sync timeouts stop cleanly, held and deleted files release, Postgres pools and deadline reads stop leaking or hanging, derived effects stop reporting false recoveries, and fix commands print what a retry needs.** `gbrain sync --timeout N` now stops as a partial run with exit 0 instead of being killed by its own watchdog, a held deleted file whose page was soft-deleted no longer stays `needs_human`, and `gbrain git commit-push` publishes a staged deletion under a wildcard-ignored folder. A Postgres pool that finishes opening after a reconnect is closed instead of leaking, a managed-sync preparation read gives up at its deadline instead of waiting on a saturated pool, and the sync cost check no longer scans every chunk when nothing has drifted. A `links` or `facts-backstop` effect that meets another write's publication in flight waits as `writer_busy` and retries within a second, instead of reporting `recovery_required` and waiting 30 s. A refused edit's fix command now prints the revision the retry needs, keyless init suggests an import that runs, cancelling a finished job changes nothing, and particle-1 on OpenRouter stops truncating. gbrain's own receipt bookkeeping no longer caps writes by default (the cumulative id and receipt-byte caps become opt-in, and housekeeping keeps receipt storage in check), `gbrain repair file-drift` no longer offers to copy an untracked or gitignored file into an origin-twin page, and a `revision_backfill_pending` refusal names `gbrain apply-migrations --force-schema`, the command that resumes the backfill.
### Itemized changes
@@ -56,6 +56,45 @@ identifiers and attribution are available in the pre-removal Git revision
- `src/core/behavior-change-notice.ts`, `docs/guides/write-refusals.md`: the `refresh_replan_own_commits_8828` notice and the `refresh_source_changed` row now match the code (text only; the row's `since` is unchanged).
- Tests: `test/revision-fix-command-shows-revision.test.ts`, `test/init-keyless-import-hint.test.ts`, `test/worker-quiet-hours-skip-keeps-cancelled.test.ts`, `test/code-edges.test.ts`, `test/ai/recipe-openrouter.test.ts`, `test/minion-cancel-failed-parent.test.ts`, `test/minion-child-of-finished-parent.test.ts`, `test/minion-fail-parent-clears-lock.test.ts`, `test/write-receipt-remediation.test.ts`.
+#### Receipt bookkeeping no longer caps writes (#9021)
+
+**gbrain's own write bookkeeping no longer caps your writes.** Every accepted write leaves a receipt, and gbrain used to cap how many request ids and how many receipt bytes one writer and one brain could hold (2,000,000 / 8,000,000 ids, 16 GiB / 64 GiB). Near those caps, background writers paused at 80% and every write receipt carried a low-capacity warning; at the cap, `remember`, `put_page` and sync refused with `write_quota_exhausted` until someone on the brain host raised a number. Nothing about your data needed that: a cap only stopped writes. Both caps are now off unless the operator sets one. Receipt storage is kept in check by housekeeping instead: while receipts not yet compacted reserve more than `persistence.housekeeping.receipt_target_bytes` (default 8 GiB; the few KiB a compacted receipt keeps so its request id stays replayable never count, since nothing can shrink them), the compaction pass also compacts committed and cancelled receipts older than 7 days (except a subagent's own page writes, which a deferred synthesis postprocess still compares with the page), plus refusals that gbrain's own producers will write again from current content, and doctor `persistence_capacity` tells the brain host's operator. A refused write you made that `gbrain repair failed-writes` could still replay now keeps its intent at any age, until a later write resolves it or you drop it with `gbrain repair receipt-compaction --include-failures`; the retention pass used to drop it after 30 days. An explicit `persistence.receipt_retention_days` is left as set. On a brain that several hosts write to, these defaults hold once every one of them runs this version: an older gbrain still enforces its old caps and its 30-day retention, and the `gbrain config set persistence.limits.*` that its `write_quota_exhausted` refusal suggests would turn a cap on for every host, so upgrade the other hosts instead of raising it.
+
+- `src/core/persistence/model.ts`, `limits.ts`: `principal_lifetime_ids`, `brain_lifetime_ids`, `principal_terminal_bytes` and `brain_terminal_bytes` default to no cap; a value set with `gbrain config set` is enforced as before (refusal at the cap, background pause at its line). New key `persistence.housekeeping.receipt_target_bytes` (0 turns housekeeping and its warning off), measured by `readCompactableReceiptBytes`: terminal receipts not yet compacted that no recovery holds.
+- `src/core/persistence/compaction-pass.ts`: `housekeepReceipts` compacts up to 100 receipts older than 7 days per pass: settled page writes, and refused maintenance pages and managed sync, file import, reconcile and file repair page writes. Job receipts, a subagent's own page writes (`restrictedNamespace` authority), connector writes and every other refusal (a caller's write, conversation facts, atom members, connector items) keep their intent until the retention window while the brain is over the target and the retention is the default, with every exclusion of the retention pass; the pass record counts them as `early`. A housekeeping error is counted as `housekeeping_error` in the pass record and never skips the reservation sweep or the record.
+- `src/commands/doctor/checks/persistence-capacity.ts`: with no cap set, `ok` says so and `warn` fires above the target with the read-only `gbrain repair receipt-compaction --json` preview (actor `host_admin`); `details.housekeeping` reports target, stored bytes, the not-yet-compacted bytes the target counts and an explicit retention. The forecast, capacity notices, repair capacity rows and `persistence_request_growth` cover only caps that are set, so the `/metrics` `gbrain_write_capacity_*` gauges are exported only for a cap you set; an alert on them needs a cap.
+- `src/core/persistence/journal.ts`, `terminal-classify.ts`: the retention pass skips `UNRESOLVED_CALLER_REFUSAL_SQL` receipts (a writer-guard or `source_changed` refusal of a caller's `put_page`, `add_timeline_entry` or `remember` that no later request wrote, removed or repeated); `gbrain repair failed-writes` reads the same refusal predicates from there. A refusal with no recorded error code is not one of them and compacts at the retention as before.
+- `src/core/persistence/diagnostics.ts`: `gbrain sources writer status --json` lists only the limits that are set; an unset cap is left out instead of printing as `null`.
+- `src/core/persistence/reconcile-backup.ts`: the `--backups` listing leaves out `max_retained_count` while the brain id cap is unset (it serialized as `null`); the retained-backup bound is `brain_recovery_bytes`.
+- Docs: `docs/guides/repair.md` (refused writes keep their intent until resolved; no retention raise needed for a recovery), `docs/guides/concurrent-writes.md` (limits table, receipt housekeeping, growth model as sizing for a cap you set), `docs/guides/write-refusals.md`.
+- Tests: `test/persistence-opt-in-caps.test.ts` (counters at the old default caps admit background and interactive writes with no notice and no raise; a set cap still refuses; housekeeping above the target takes week-old settled page writes and refused maintenance and sync writes, and keeps a caller's refused write, a refused conversation-facts job, a committed job and young receipts; the retention pass keeps a 40-day-old replayable drift or guard refusal and compacts a resolved one and a non-replayable failure (red before: the drift refusal was compacted); a 40-day synthetic run never holds more than a week of uncompacted committed receipts; doctor's operator warning; compacted receipts alone above the target leave housekeeping idle and doctor ok, red before; the backup listing names no count bound while the id cap is unset, red before; a subagent's page write is kept from early compaction, a refusal with no error code still compacts at the retention, a housekeeping error still records the pass, and writer status prints no unset cap, each red before), `test/managed-synthesis-postprocess.test.ts` (an interrupted synthesis child output ten days old, with storage above the target and a maintenance drift on the page, is still verified and stamped by the next pass; red before: `revision_conflict`), `test/persistence-capacity.test.ts` (key count); the capacity forecast, notice and read-wave tests set the cap they exercise; the doctor goldens show the uncapped default and `details.housekeeping`.
+
+**A write that saved now says so when it carries a low-capacity warning, and the warning no longer asks the user to raise a write cap by tens of gigabytes.** When a cumulative write cap (receipt bytes or request ids) was at 80% or forecast to run out within 30 days, every write receipt's `write_capacity_low` notice ended with `actor: host_admin` and `next: tell_user_to_run: gbrain config set persistence.limits.principal_terminal_bytes <value>`. An agent that read only the end of a successful `remember` took that for a refusal and told its user the memory was not saved. The value was also oversized: it projected the last 24 hours for a whole year, so one bulk sync day could recommend several times the current cap. The notice now opens with "This write was saved and writes still work", its fix is the read-only `gbrain doctor --only persistence_capacity --json`, and the one-more-year value uses the 7-day mean rate. Days-to-exhaustion warnings still react to a bulk day. Doctor's finding keeps the `gbrain config set` command for the brain host's operator.
+
+- `src/core/persistence/capacity-snapshot.ts`: `write_capacity_low` says the write was saved and names doctor's read-only check (actor `agent`) as its fix, with no cap raise in the notice.
+- `src/core/persistence/capacity-forecast.ts`: `recommended_limit` (doctor `persistence_capacity`, the notice snapshot, `gbrain sync status` and `/metrics`) covers one more year at the 7-day mean gross and net rates instead of the larger of the mean and the last 24 hours.
+- `src/core/persistence/limits.ts`: `oneYearCapacity` (every `write_quota_exhausted`, `write_quota_insufficient` and background-pause refusal, and doctor's fallback) uses the scope's 7-day window over the forecast's window length while the scope admitted anything that week, and keeps the latest-1,000 sample for a scope idle all week; the compacted-size SQL moves to `receipt-bytes.ts` so both reads count the same net bytes.
+- Docs: `docs/guides/write-refusals.md` (`write_capacity_low` row), `docs/guides/concurrent-writes.md` (the notice, the mean-rate value, and returning a raised `persistence.receipt_retention_days` to the default before raising a cap), `docs/guides/repair.md` (unset the 90-day retention once a failed-writes recovery is done), `docs/architecture/key-files/core-persistence-capacity.md`.
+- Tests: `test/persistence-capacity-notices.test.ts` (the notice's fix and wording; a burst of 28 admissions in the last day over a 10-a-day week recommends the mean-rate value, ids exactly and receipt bytes under the mean-rate ceiling; after 1,000 admissions in one hour on a 100-a-week principal, a real `write_quota_exhausted` refusal names exactly the value doctor recommends, ids and receipt bytes, on PGLite and Postgres).
+
+#### Repair file-drift leaves an untracked or gitignored twin file alone (#9054)
+
+**`gbrain repair file-drift` no longer offers to adopt an untracked or gitignored file into an origin-twin page.** v0.60.629.0 taught the drift preview to read an origin twin with no recorded file against the file at its slug path, but only where sync admits that path. It didn't check that sync reads the file at all. Sync imports from the HEAD commit (and the working tree only with `sync.include_working_tree` or a detached HEAD, never an ignored file), so a slug-path file that Git doesn't track, or that `.gitignore` lists, is never imported or held. The preview still reported it as drift: it offered `--prefer file` to copy a possibly private, ignored file into the database, maintenance writes to the page were refused as drift, and doctor `maintenance_write_drift` counted it. Such a twin now stays `database_only`. An untracked file that sync does read from the working tree is still read as drift.
+
+- `src/core/persistence/drift-conflicts.ts`: `twinReading` reads `adopt` only when sync reads the slug-path file: committed at HEAD, or, when sync reads the working tree, not ignored by Git.
+- Tests: `test/repair-file-drift-origin-twin-gbra108.test.ts` (PGLite, managed source, real git): an untracked slug-path file and a gitignored one under `sync.include_working_tree` stay `database_only` with no sync hold, and an untracked file sync reads from the working tree still reads drift while sync holds it.
+
+#### The revision-backfill refusal names the command that resumes it (#9053)
+
+**A `revision_backfill_pending` refusal now names the command that actually resumes the backfill, and the write-refusal guide says what a webhook capture of such a page gets (follow-up to GST-2112).** The refusal's message, which is also the body of the 409 `POST /ingest` answers for a page the revision backfill has not reached and the error a dead `ingest_capture` job keeps, said `gbrain apply-migrations --yes`, which does not resume the backfill once the schema is current, and linked a section that does not cover it. It now says `gbrain apply-migrations --force-schema` on the brain host and links `docs/guides/write-refusals.md#revision-backfill`. Since #8940 that 409 stores and queues nothing, so the capture exists only with its sender, and an `ingest_capture` job already queued for such a page goes straight to `dead`; neither was written down. The guide's `revision_backfill_pending` row and a new upgrade notice row now say both, with the recovery: resume the backfill, send a capture that got the 409 again, and re-run a dead job with `gbrain jobs retry <id>`. The E2E runner also gives `test/e2e/source-retire-batched-postgres.test.ts` (60,000 pages) the 4x per-file budget: on a loaded CI runner it ran past the 180 s cap and was killed with a test in flight and no failed assertion.
+
+- `src/core/page-state/types.ts`: `RevisionBackfillPendingError`'s message names `gbrain apply-migrations --force-schema` and the `#revision-backfill` anchor, matching the error registry's fix.
+- `docs/guides/write-refusals.md`: the `revision_backfill_pending` row covers the 409 at `POST /ingest`, the `ingest_capture` job that goes straight to `dead`, and the resend and `gbrain jobs retry <job id>` recovery.
+- `src/core/behavior-change-notice.ts`: one row for the changed message and the recovery.
+- `scripts/run-e2e.sh`: `source-retire-batched-postgres.test.ts` joins the 4x per-file budget list. No assertion in that file changed.
+- Tests: `test/ingest-capture-keeps-readers.test.ts` checks that the 409 body and the job's refusal name `--force-schema` and the anchor.
+
+
## [0.60.657.0] - 2026-11-11
**A running `gbrain serve`, worker or autopilot no longer fails writes after another process changes a table's columns (GST-2260).** When `gbrain apply-migrations` or an upgrade in another process added, renamed or dropped a column, every pooled connection that had already prepared a `SELECT *` or `RETURNING *` on that table failed its next run with "cached plan must not change result type". Outside a transaction the driver quietly prepared the statement again, but inside one the error had already aborted the transaction, so the caller saw it. A `put_page` came back `internal_error`, or was accepted and then failed at publication, once for each statement on each pooled connection. Version 0.60.646.0 made the write paths re-run the transaction it aborted. Now the first such error also makes every connection in the process prepare its statements again before its next query, and an OAuth token grant whose client read meets it and a minion job's completion or failure record are re-run too. Pools that do not prepare statements (transaction-mode pooler URLs, `prepare: false`) and PGLite are unchanged.
diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.ts
index a4cc79e32d..af661a3979 100644
--- a/src/core/cli-flag-registry.generated.ts
+++ b/src/core/cli-flag-registry.generated.ts
@@ -52,18 +52,18 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'db-repair': ['--accept-pending', '--apply', '--apply-rewrites', '--as', '--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', '--claims', '--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', '--as', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--budget-ms', '--client', '--count', '--cursor', '--date', '--dated-since', '--days', '--detach', '--entities', '--expect', '--expected-revision', '--federated-read', '--filter', '--follow', '--format', '--from-index', '--full', '--fuzzy', '--group-by', '--held', '--help', '--http', '--id', '--include', '--include-ambiguous', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--no-pull', '--no-walk', '--of', '--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', '--absolute-git-dir', '--accept-all', '--accept-capabilities', '--accept-pending', '--access', '--access-policy', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt', '--adopt-columns', '--adopt-permissions', '--advertise', '--after', '--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', '--approval-out', '--approved', '--as', '--assign-corpus', '--attest-actor', '--attest-ops', '--attest-read', '--attest-sources', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--base', '--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', '--bundled', '--by-mention', '--cached', '--call-site', '--catalog', '--catch-up', '--channel', '--check', '--check-downgrade', '--check-only', '--claims', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--code', '--concurrency', '--confidence', '--config', '--confirm', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--credentials-file', '--cursor', '--cwd', '--dataset', '--day', '--db-url', '--deadline', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--email', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--env-file', '--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', '--filter', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-retry', '--force-schema', '--format', '--fresh', '--fresh-token', '--from', '--from-json', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--gbrain-bin', '--generation', '--get', '--get-all', '--get-regexp', '--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', '--ignore-missing', '--images', '--import', '--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-bare-repository', '--is-inside-work-tree', '--is-shallow-repository', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link', '--link-source', '--link-type', '--list', '--list-out', '--literal-pathspecs', '--local', '--local-env-vars', '--locks', '--log-noop', '--manifest', '--markdown', '--max-cost', '--max-cost-usd', '--max-facts', '--max-jobs', '--max-requests', '--max-rss', '--max-runtime', '--max-usd', '--max-waiting', '--may-act-for', '--mcp-only', '--member', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-assume-unchanged', '--no-autopilot-install', '--no-autostash', '--no-capture', '--no-confirm', '--no-cron', '--no-delegate', '--no-edit', '--no-embed', '--no-embed-cache', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-hooks', '--no-instructions', '--no-lanes', '--no-llm', '--no-migrate', '--no-optional-locks', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-skip-worktree', '--no-tags', '--no-verify', '--no-walk', '--non-interactive', '--now', '--of', '--older-than', '--once', '--only', '--operation', '--operations', '--others', '--out', '--output', '--oversized', '--overwrite', '--page', '--parallel', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--port', '--prefer', '--prefer-postgres', '--prefix', '--preload', '--preset', '--preview', '--principal', '--private-pages', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push-only', '--qm', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--readers', '--reason', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remote', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--reset-session', '--resolve', '--restart-only', '--restore-only', '--resume', '--retire', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--reverse', '--review-lower', '--revision', '--rollback-to-source', '--root', '--routing', '--rules', '--run', '--runtime', '--sample', '--save', '--scan-secrets', '--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', '--skill-loading', '--skills-dir', '--skills-index-only', '--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', '--squash', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--tags', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--trust', '--tsconfig-override', '--type', '--types', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset', '--unset-all', '--unsettle', '--unshallow', '--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', '--worktree', '--write-tree', '--yes'],
+ 'doctor': ['--abandon', '--abbrev-ref', '--absolute-git-dir', '--accept-all', '--accept-capabilities', '--accept-pending', '--access', '--access-policy', '--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', '--approval-out', '--approved', '--as', '--assign-corpus', '--attest-actor', '--attest-ops', '--attest-read', '--attest-sources', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--base', '--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', '--bundled', '--by-mention', '--cached', '--cacheinfo', '--call-site', '--catalog', '--catch-up', '--channel', '--check', '--check-downgrade', '--check-only', '--cherry-mark', '--claims', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--code', '--concurrency', '--confidence', '--config', '--confirm', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--credentials-file', '--cursor', '--cwd', '--dataset', '--day', '--db-url', '--deadline', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--email', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--env-file', '--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', '--filter', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-remove', '--force-retry', '--force-schema', '--force-with-lease', '--format', '--fresh', '--fresh-token', '--from', '--from-json', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--gbrain-bin', '--generation', '--get', '--get-all', '--get-regexp', '--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', '--ignore-missing', '--images', '--import', '--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-bare-repository', '--is-inside-work-tree', '--is-shallow-repository', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link', '--link-source', '--link-type', '--list', '--list-out', '--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', '--may-act-for', '--mcp-only', '--member', '--merge-base', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-assume-unchanged', '--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-optional-locks', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-skip-worktree', '--no-tags', '--no-verify', '--no-walk', '--no-write-fetch-head', '--non-interactive', '--not', '--now', '--of', '--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', '--prefix', '--preload', '--preset', '--preview', '--principal', '--private-pages', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push', '--push-only', '--qm', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--readers', '--reason', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remote', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--reset-session', '--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', '--routing', '--rules', '--run', '--runtime', '--sample', '--save', '--scan-secrets', '--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', '--skill-loading', '--skills-dir', '--skills-index-only', '--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', '--squash', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--tags', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--topo-order', '--trust', '--tsconfig-override', '--type', '--types', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset', '--unset-all', '--unsettle', '--unshallow', '--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', '--worktree', '--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', '--as', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--client', '--cursor', '--date', '--dated-since', '--days', '--entities', '--federated-read', '--follow', '--from-index', '--full', '--fuzzy', '--group-by', '--help', '--http', '--id', '--include', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--of', '--only', '--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'],
- 'embed': ['--accept-pending', '--all', '--as', '--background', '--batch-size', '--brain', '--break-lock', '--budget-ms', '--catch-up', '--client', '--db-url', '--dim', '--dry-run', '--embedding-dimensions', '--embedding-model', '--explain', '--facts', '--follow', '--force', '--gbrain-bin', '--group', '--harness', '--held', '--help', '--http', '--id', '--images', '--include-null-signature', '--json', '--legacy-lock', '--max-cost', '--max-cost-usd', '--max-facts', '--max-runtime', '--max-usd', '--no-accept-pending', '--no-autopilot-install', '--no-confirm', '--no-embed', '--no-embedding', '--no-hooks', '--only', '--oversized', '--pace', '--pace-max-concurrency', '--path', '--priority', '--probe', '--progress-interval', '--progress-json', '--quiet', '--replace', '--scopes', '--section', '--show-toplevel', '--slugs', '--source', '--stale', '--status', '--supabase', '--surface', '--timeout', '--timings', '--to', '--wait', '--yes'],
+ 'embed': ['--accept-pending', '--all', '--as', '--background', '--batch-size', '--brain', '--break-lock', '--budget-ms', '--catch-up', '--client', '--db-url', '--dim', '--dry-run', '--embedding-dimensions', '--embedding-model', '--explain', '--facts', '--follow', '--force', '--force-schema', '--gbrain-bin', '--group', '--harness', '--held', '--help', '--http', '--id', '--images', '--include-null-signature', '--json', '--legacy-lock', '--max-cost', '--max-cost-usd', '--max-facts', '--max-runtime', '--max-usd', '--no-accept-pending', '--no-autopilot-install', '--no-confirm', '--no-embed', '--no-embedding', '--no-hooks', '--only', '--oversized', '--pace', '--pace-max-concurrency', '--path', '--priority', '--probe', '--progress-interval', '--progress-json', '--quiet', '--replace', '--scopes', '--section', '--show-toplevel', '--slugs', '--source', '--stale', '--status', '--supabase', '--surface', '--timeout', '--timings', '--to', '--wait', '--yes'],
'embeddings': ['--accept-pending', '--as', '--background', '--brain', '--db-url', '--dim', '--dry-run', '--embedding-dimensions', '--embedding-model', '--explain', '--follow', '--force', '--help', '--json', '--no-accept-pending', '--no-embedding', '--path', '--probe', '--progress-interval', '--progress-json', '--quiet', '--source', '--stale', '--status', '--supabase', '--timeout', '--timings', '--to', '--wait', '--yes'],
'engine': ['--apply-rewrites', '--brain', '--break-lock', '--db-url', '--help', '--http', '--json', '--legacy-lock', '--path', '--prefer-postgres', '--probe', '--source', '--supabase', '--url', '--yes'],
'enrich': ['--accept-pending', '--access', '--add', '--all', '--allowed-operations', '--apply', '--as', '--asof', '--audit', '--background', '--body', '--bound-slug-prefixes', '--brain', '--client', '--concurrency', '--confirm-destructive', '--conflicts', '--cursor', '--date', '--dated-since', '--days', '--dry-run', '--embedding-dimensions', '--embedding-model', '--entities', '--expect', '--explain', '--federated-read', '--follow', '--force', '--from-index', '--full', '--fuzzy', '--group', '--group-by', '--help', '--http', '--id', '--include', '--include-deleted', '--input', '--json', '--kind', '--limit', '--max-cost', '--max-cost-usd', '--max-runtime', '--max-usd', '--min-context', '--model', '--multimodal', '--no-accept-pending', '--no-autopilot-install', '--no-confirm', '--non-interactive', '--of', '--only', '--order', '--output', '--page', '--params', '--path', '--phase', '--prefer', '--preview', '--progress-interval', '--progress-json', '--purge', '--quiet', '--rate', '--recent', '--reenrich-after', '--refresh-operations', '--resume', '--row', '--scopes', '--session', '--since', '--slug', '--slugs', '--source', '--source-id', '--sources', '--stale', '--status', '--surface', '--thin', '--thin-threshold', '--timeout', '--timings', '--to', '--trust', '--types', '--updated-after', '--url', '--wait', '--workers', '--yes'],
'errors': ['--brain', '--changed', '--help', '--json', '--source'],
'eval': ['--ab-relational', '--accept-pending', '--against', '--allow-incomplete-judgments', '--allow-mixed-run-config', '--allow-regression', '--as', '--asof', '--autocut', '--background', '--baseline', '--batch', '--brain', '--budget-usd', '--budget-usd-answer', '--budget-usd-retrieval', '--by-type', '--by-type-floor', '--by-type-floor-metric', '--call-plan', '--call-plan-gate', '--candidate', '--capture-pool', '--committed-baseline', '--compare', '--compare-limit', '--concurrent', '--config-a', '--config-b', '--corpus', '--cycles', '--days', '--decide', '--decide-calibration', '--decide-dataset', '--decide-force-on', '--decide-provider', '--decide-threshold', '--dedup-cosine', '--dedup-max-per-page', '--dedup-type-ratio', '--dimensions', '--distance-min', '--draws', '--embed-cache', '--embedder', '--embedding-dimensions', '--embedding-model', '--error-unmatch', '--eval-pool-depth', '--expand', '--expansion', '--expansion-replay', '--expansion-variant-budget', '--explain', '--fact-extractor', '--fact-keys', '--fact-keys-max-usd', '--fact-keys-model', '--fixtures', '--follow', '--force-rechunk', '--format', '--from-capture', '--from-db', '--gold', '--grounding-min', '--harness', '--help', '--include-abstention', '--include-holdout', '--input', '--json', '--judge', '--judge-concurrency', '--judge-model', '--justification', '--k', '--keyword-only', '--limit', '--llm', '--max-pair-chars', '--max-tokens', '--max-usd', '--mcp-only', '--md', '--metric', '--min-recall', '--mode', '--model', '--models', '--modes', '--name-only', '--no-accept-pending', '--no-cache', '--no-embed-cache', '--no-expand', '--no-llm', '--no-trajectory', '--older-than', '--op-expand', '--out', '--output', '--output-dir', '--parallel', '--parity-baseline', '--porcelain', '--progress-interval', '--progress-json', '--qrels', '--queries-file', '--query', '--question-ids', '--questions', '--quiet', '--reader-max-tokens', '--reader-mode', '--receipt-dir', '--record', '--refresh-cache', '--request-id', '--reranker', '--resume-from', '--retrieval-only', '--rrf-k', '--rubric-version', '--runs', '--sample', '--sampling', '--save', '--search-pin', '--seed', '--severity', '--short', '--show-toplevel', '--since', '--skip-replay', '--slot', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--slug-prefix', '--source', '--stale', '--status', '--strategy', '--suite', '--suites', '--supabase', '--synopsis-cache', '--synopsis-concurrency', '--synopsis-max-usd', '--task', '--threshold', '--threshold-expected-top1', '--threshold-first-relevant-hit', '--threshold-jaccard', '--threshold-latency-multiplier', '--threshold-recall-at-k', '--threshold-top1', '--time-scope', '--time-scope-pool', '--timeout', '--timings', '--tool', '--top-k', '--top-regressions', '--until', '--untracked-files', '--update-baseline', '--usefulness-min', '--vectors', '--verbose', '--verify', '--via-operation', '--wait', '--with-code-intel', '--yes'],
'export': ['--accept-pending', '--access-policy', '--as', '--background', '--body', '--brain', '--dir', '--explain', '--follow', '--help', '--json', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--repo', '--restore-only', '--slug-prefix', '--source', '--timeout', '--timings', '--type', '--wait'],
- 'extract': ['--accept-pending', '--admin-intent', '--after-slug', '--apply', '--apply-preview', '--as', '--background', '--backup-verified', '--body', '--brain', '--break-lock', '--by-mention', '--catch-up', '--checkpoint', '--client', '--concurrency', '--confirm', '--confirm-relocated-root', '--db-url', '--dir', '--dry-run', '--expected-epoch', '--expected-state', '--explain', '--follow', '--force', '--from-meetings', '--help', '--http', '--id', '--include-frontmatter', '--infer-dates', '--json', '--kind', '--legacy-lock', '--limit', '--manifest', '--ner', '--no-accept-pending', '--pack', '--page', '--path', '--progress-interval', '--progress-json', '--prune-orphans', '--quiet', '--rebuild', '--repair-attendance', '--retry-held', '--scopes', '--self-transfer', '--since', '--source', '--source-id', '--stale', '--timeout', '--timings', '--type', '--verbose', '--wait', '--workers', '--yes'],
+ 'extract': ['--accept-pending', '--admin-intent', '--after-slug', '--apply', '--apply-preview', '--as', '--background', '--backup-verified', '--body', '--brain', '--break-lock', '--by-mention', '--catch-up', '--checkpoint', '--client', '--concurrency', '--confirm', '--confirm-relocated-root', '--db-url', '--dir', '--dry-run', '--expected-epoch', '--expected-state', '--explain', '--follow', '--force', '--force-schema', '--from-meetings', '--help', '--http', '--id', '--include-frontmatter', '--infer-dates', '--json', '--kind', '--legacy-lock', '--limit', '--manifest', '--ner', '--no-accept-pending', '--pack', '--page', '--path', '--progress-interval', '--progress-json', '--prune-orphans', '--quiet', '--rebuild', '--repair-attendance', '--retry-held', '--scopes', '--self-transfer', '--since', '--source', '--source-id', '--stale', '--timeout', '--timings', '--type', '--verbose', '--wait', '--workers', '--yes'],
'extract-conversation-facts': ['--accept-pending', '--admin-intent', '--as', '--background', '--body', '--brain', '--concurrency', '--confirm-destructive', '--confirm-relocated-root', '--dim', '--dry-run', '--embedding-dimensions', '--embedding-model', '--expected-epoch', '--expected-state', '--explain', '--follow', '--force', '--grammar', '--help', '--input', '--json', '--limit', '--manifest', '--max-cost', '--max-cost-usd', '--max-runtime', '--no-accept-pending', '--no-autopilot-install', '--no-embedding', '--output', '--override-disabled', '--path', '--progress-interval', '--progress-json', '--quiet', '--rate', '--segment-limit', '--self-transfer', '--since', '--sleep', '--slug', '--slugs', '--source', '--source-id', '--stale', '--status', '--supabase', '--timeout', '--timings', '--to', '--types', '--url', '--wait', '--workers', '--yes'],
'facts': ['--admin-intent', '--after-id', '--all', '--brain', '--clear', '--conversation', '--dry-run', '--entity', '--examples', '--expected-state', '--force', '--help', '--include-private', '--json', '--limit', '--list', '--max-cost-usd', '--max-usd', '--no-conflict-queue', '--no-llm', '--path', '--reset', '--retry-model', '--since', '--slug', '--slugs', '--source', '--source-id'],
'features': ['--all', '--apply', '--auto', '--auto-fix', '--background', '--batch-size', '--brain', '--by-mention', '--catch-up', '--concurrency', '--dir', '--embedding-model', '--expect', '--explain', '--facts', '--force', '--from-meetings', '--held', '--help', '--images', '--include-frontmatter', '--include-null-signature', '--infer-dates', '--json', '--kind', '--max-cost', '--max-usd', '--ner', '--non-interactive', '--only', '--oversized', '--overwrite', '--pace', '--pace-max-concurrency', '--pack', '--page', '--path', '--priority', '--probe', '--prune-orphans', '--rebuild', '--refresh', '--repo', '--retry-held', '--save', '--since', '--slugs', '--source', '--source-id', '--stale', '--target', '--trust', '--type', '--verbose', '--workers', '--yes'],
@@ -73,12 +73,12 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'founder': ['--brain', '--help', '--json', '--mcp-only', '--request-id', '--since', '--source', '--until'],
'friction': ['--agent', '--base', '--brain', '--compare', '--help', '--hint', '--json', '--kind', '--message', '--no-redact', '--phase', '--run-id', '--severity', '--source', '--transcript-path', '--transcripts'],
'frontmatter': ['--allow-catch-all', '--batch', '--brain', '--cached', '--diff-filter', '--dry-run', '--exclude-standard', '--fix', '--force', '--full-name', '--get', '--git-common-dir', '--help', '--importable', '--include-ambiguous', '--include-catch-all', '--json', '--literal-pathspecs', '--local', '--name-only', '--no-verify', '--others', '--path', '--show-prefix', '--show-toplevel', '--source', '--stage', '--staged', '--stdin', '--type', '--uninstall'],
- 'git': ['--abbrev-ref', '--absolute-git-dir', '--add', '--allow-outside-source-root', '--autostash', '--base', '--brain', '--branch', '--cached', '--diff-filter', '--dry-run', '--enable', '--error-unmatch', '--exclude-standard', '--expect-remote', '--ff-only', '--file', '--force', '--get', '--get-all', '--get-regexp', '--git-common-dir', '--git-dir', '--git-path', '--hard', '--help', '--index-info', '--install', '--is-inside-work-tree', '--json', '--keep-checkout', '--local', '--local-env-vars', '--message', '--mode', '--name-only', '--name-status', '--no-assume-unchanged', '--no-autostash', '--no-cron', '--no-optional-locks', '--no-recurse-submodules', '--no-renames', '--no-skip-worktree', '--no-tags', '--no-verify', '--only', '--others', '--pat-file', '--path', '--path-format', '--pending', '--porcelain', '--pull', '--push-only', '--quiet', '--rebase', '--repo', '--require-clean', '--resolve', '--scan-secrets', '--short', '--show-toplevel', '--source', '--source-id', '--stdin', '--type', '--uninstall', '--unset', '--unset-all', '--untracked-files', '--verify', '--worktree', '--write-tree'],
+ 'git': ['--abbrev-ref', '--absolute-git-dir', '--add', '--aggressive', '--all', '--allow-outside-source-root', '--autostash', '--base', '--batch-check', '--brain', '--branch', '--cached', '--cacheinfo', '--cherry-mark', '--count', '--diff-filter', '--dry-run', '--enable', '--error-unmatch', '--exclude-standard', '--exit-code', '--expect-remote', '--ff-only', '--file', '--force', '--force-remove', '--force-with-lease', '--format', '--get', '--get-all', '--get-regexp', '--get-url', '--git-common-dir', '--git-dir', '--git-path', '--hard', '--help', '--index-info', '--install', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep-checkout', '--local', '--local-env-vars', '--max-count', '--merge-base', '--message', '--mode', '--name-only', '--name-status', '--no-assume-unchanged', '--no-autostash', '--no-commit-id', '--no-cron', '--no-gpg-sign', '--no-merges', '--no-optional-locks', '--no-recurse-submodules', '--no-renames', '--no-skip-worktree', '--no-tags', '--no-verify', '--no-write-fetch-head', '--not', '--only', '--others', '--parents', '--pat-file', '--path', '--path-format', '--pending', '--porcelain', '--pull', '--push', '--push-only', '--quiet', '--rebase', '--repo', '--require-clean', '--resolve', '--reverse', '--right-only', '--root', '--scan-secrets', '--short', '--show-toplevel', '--source', '--source-id', '--staged', '--stat', '--stdin', '--topo-order', '--type', '--uninstall', '--unset', '--unset-all', '--untracked-files', '--verify', '--worktree', '--write-tree'],
'google': ['--access', '--account', '--allow-create-db', '--allow-docker', '--brain', '--calendar-id', '--chat-model', '--client-id', '--client-json', '--client-secret', '--code', '--consent-state', '--content-root', '--db-only', '--embedding-dimensions', '--embedding-model', '--expansion-model', '--force', '--git', '--grant-types', '--help', '--history-days', '--http', '--issuer-url', '--json', '--key', '--kind', '--limit', '--local-postgres', '--mcp-only', '--mcp-url', '--migrate-only', '--model', '--no-browser', '--no-embed', '--no-embedding', '--no-git', '--no-probe', '--non-interactive', '--oauth-client-id', '--oauth-client-secret', '--paste', '--path', '--pglite', '--plan', '--port', '--prefer-postgres', '--probe', '--provenance', '--purge-client', '--query', '--reauth', '--retry-failed', '--schema-pack', '--scopes', '--search-mode', '--services', '--skip-embed-check', '--source', '--status', '--supabase', '--surface', '--sync-budget-ms', '--timeout-ms', '--to', '--token-command', '--url', '--version', '--via', '--yes'],
'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', '--catalog', '--count', '--diff-filter', '--dir', '--enable', '--end-of-options', '--env', '--gbrain-bin', '--get', '--harness', '--help', '--instructions', '--instructions-only', '--jq', '--json', '--limit', '--name-only', '--no-instructions', '--only', '--others', '--pat-file', '--path', '--porcelain', '--print', '--pure', '--quiet', '--remove', '--scope', '--seat', '--session', '--show-current', '--show-toplevel', '--since', '--source', '--source-ids', '--verify', '--workspace', '--yes'],
'import': ['--accept-pending', '--access-policy', '--admin-intent', '--allow-empty', '--allow-noncanonical-root', '--apply', '--as', '--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': ['--abandon', '--absolute-git-dir', '--accept-all', '--accept-capabilities', '--access', '--access-policy', '--acknowledge-managed', '--adopt', '--advertise', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--approval-out', '--approved', '--as', '--assign-corpus', '--attest-actor', '--attest-ops', '--attest-read', '--attest-sources', '--audit', '--auto', '--auto-additive', '--background', '--base', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--check-downgrade', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--code', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--decisions', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--email', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--filter', '--first-parent', '--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', '--list-out', '--local', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--may-act-for', '--mcp-only', '--mcp-url', '--member', '--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', '--of', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--prefix', '--preview', '--private-pages', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--qm', '--query', '--question', '--quiet', '--readers', '--reason', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remote', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retire', '--retry-failed', '--retry-parked', '--runtime', '--save', '--scan-secrets', '--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', '--squash', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--types', '--uninstall', '--unsettle', '--url', '--url-env', '--user', '--vacuum', '--verbose', '--version', '--wait', '--warn-only', '--watch', '--working-tree', '--workspace', '--yes'],
+ 'init': ['--abandon', '--absolute-git-dir', '--accept-all', '--accept-capabilities', '--access', '--access-policy', '--acknowledge-managed', '--adopt', '--advertise', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--approval-out', '--approved', '--as', '--assign-corpus', '--attest-actor', '--attest-ops', '--attest-read', '--attest-sources', '--audit', '--auto', '--auto-additive', '--background', '--base', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--check-downgrade', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--code', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--decisions', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--email', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--filter', '--first-parent', '--fix', '--force', '--force-retry', '--force-schema', '--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-failures', '--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', '--list-out', '--local', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--may-act-for', '--mcp-only', '--mcp-url', '--member', '--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', '--of', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--prefix', '--preview', '--private-pages', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--qm', '--query', '--question', '--quiet', '--readers', '--reason', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remote', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retire', '--retry-failed', '--retry-parked', '--runtime', '--save', '--scan-secrets', '--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', '--squash', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--types', '--uninstall', '--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', '--as', '--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', '--access-policy', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt-slug-path', '--aliases', '--all', '--all-sources', '--allow-empty', '--allow-shell-jobs', '--allowed-operations', '--apply', '--approval-out', '--approved', '--as', '--asof', '--assign-corpus', '--attest-actor', '--attest-ops', '--auto', '--background', '--backoff-delay', '--backoff-jitter', '--backoff-type', '--base', '--batch-size', '--body', '--bound-slug-prefixes', '--brain', '--break-lock', '--budget-ms', '--bundled', '--by-mention', '--cached', '--catalog', '--catch-up', '--channel', '--check', '--check-downgrade', '--check-only', '--clear', '--cli-path', '--client', '--close', '--cluster-errors', '--code', '--concurrency', '--confidence', '--confirm-destructive', '--confirm-relocated-root', '--cost-estimate', '--cursor', '--date', '--dated-since', '--days', '--decisions', '--delay', '--detach', '--detail', '--diff-filter', '--dir', '--drain', '--drain-timeout', '--dry-run', '--embedding-dimensions', '--embedding-model', '--empty', '--enable', '--entities', '--exclude', '--exclude-standard', '--expect', '--expect-catalog', '--expect-local', '--expect-upstream', '--expected-state', '--explain', '--facts', '--federated-read', '--ff-only', '--file', '--filter', '--filters', '--finished-since', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-retry', '--force-schema', '--format', '--fresh', '--from-index', '--from-json', '--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', '--include-ambiguous', '--include-content', '--include-deleted', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-null-signature', '--infer-dates', '--inject-bootstrap', '--inline', '--input', '--input-json', '--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', '--may-act-for', '--mcp-only', '--member', '--migration', '--min-context', '--missing-path', '--mode', '--model', '--multimodal', '--name', '--name-only', '--ner', '--nice', '--no-assume-unchanged', '--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-skip-worktree', '--no-verify', '--no-worker', '--non-interactive', '--now', '--of', '--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', '--qm', '--question', '--queue', '--queue-only', '--quiet', '--rate', '--reason', '--reason-scan-limit', '--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', '--routing', '--row', '--save', '--scope', '--scopes', '--section', '--segment-limit', '--segmented', '--select', '--self-transfer', '--serial', '--session', '--show-toplevel', '--side', '--sigkill-rescue', '--since', '--skill-loading', '--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', '--text', '--thin', '--thin-threshold', '--tier', '--timeout', '--timeout-ms', '--to', '--token', '--token-env', '--trust', '--type', '--types', '--uninstall', '--updated-after', '--url', '--user', '--vectors', '--verbose', '--verify', '--version', '--watch', '--wedge-rescue', '--workers', '--working-tree', '--yes'],
diff --git a/src/core/git/commit-push.ts b/src/core/git/commit-push.ts
index 5fbaa5d111..28fa476adc 100644
--- a/src/core/git/commit-push.ts
+++ b/src/core/git/commit-push.ts
@@ -587,7 +587,16 @@ function commitPaths(root: string, rel: string[], message: string, scope: Commit
const swept = stagedPaths(root).filter(p => !rel.includes(p) && rel.some(spec => covers(spec, p)));
if (swept.length) {
const list = `${swept.slice(0, 10).join(', ')}${swept.length > 10 ? ', ...' : ''}`;
- throw opError('commit_prestaged_paths', `${swept.length} file(s) under the named path(s) were already staged by another writer: ${list}.` // GST-2118: git add refuses a named skip-worktree file that is on disk; it is left to the skipped-path check, so the other paths still commit.
+ throw opError('commit_prestaged_paths', `${swept.length} file(s) under the named path(s) were already staged by another writer: ${list}.`,
+ 'Nothing was staged or committed. If they are yours, name each file explicitly; otherwise leave them to the writer that staged them, or unstage them with the user\'s agreement (git restore --staged -- <file>; the working tree keeps its bytes).',
+ { detail: JSON.stringify({ paths: swept }), fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
+ argv: ['git', '-C', root, 'restore', '--staged', '--', ...swept],
+ why: 'Another writer staged these files; committing them would publish whatever that writer had in progress, and unstaging them drops its staging.',
+ user_message: `Files already staged by another writer sit under the path you asked to commit (${list}). Commit only the files you name, or unstage those (their bytes stay on disk)?`,
+ docs: 'docs/guides/shared-checkout-git.md#outcomes' } });
+ }
+ const before = indexEntries(root, rel);
+ // GST-2118: git add refuses a named skip-worktree file that is on disk; it is left to the skipped-path check, so the other paths still commit.
const sparse = new Set(gitOk(root, ['ls-files', '-v', '-z', '--', ...literalPathspecs(rel)], 'ls-files -v').split('\0')
.filter(entry => /^[sS] /.test(entry) && rel.includes(entry.slice(2)) && existsSync(join(root, entry.slice(2)))).map(entry => entry.slice(2)));
const live = rel.filter(p => !sparse.has(p));
@@ -602,592 +611,877 @@ function commitPaths(root: string, rel: string[], message: string, scope: Commit
const matched = new Set(matching([...tracked, ...untracked, ...deleted]));
const unmatched = live.filter(spec => !matched.has(spec));
let landed: { committed: boolean; paths: string[]; listed: string[] };
-l for classic (unmanaged) brain
- * repos (#6530). Many writers (agents, crons, hooks, gbrain's own
- * write-through) commit to ONE checkout, so nothing here rebases, stashes or
- * resets the working tree:
- *
- * 1. two locks per checkout: the short commit lock (`git rev-parse --git-path
- * brain-commit.lock`, the same flock a bash `flock -x` takes) for local
- * index/HEAD changes only, and the publish lock (brain-publish.lock) for
- * the network push; a publisher takes the commit lock only to advance, and
- * an unattended publisher that finds the publish lock busy leaves a request
- * the holder honors after it releases (so no commit is stranded);
- * 2. commits carry only the caller's paths (`commit --only -- <paths>`);
- * 3. a rejected push is integrated IN MEMORY (`merge-tree --write-tree`, or a
- * 3-way `read-tree` into a temporary index on git < 2.38) into a merge
- * commit built with `commit-tree`; no working tree is touched;
- * 4. the shared checkout advances only by `merge --ff-only`, which refuses
- * (and changes nothing) when HEAD moved or a file it must change is dirty.
- *
- * Managed canonical worktrees are refused: the persistence owner is their
- * only writer. The one exception is a keep-checkout publish (`keepCheckout`,
- * `--push-only --keep-checkout`): it pushes HEAD, merging a moved remote in
- * memory, but never moves the checkout and skips its pre-push hook, so `gbrain sources
- * refresh` stays the only importer of remote files into a managed worktree
- * (#7010; the owner's Git effects publish this way). CLI-only; never exposed
- * over MCP (it pushes with host credentials).
- */
-import { appendFileSync, existsSync, lstatSync, mkdtempSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { scanRange } from './range-secret-scan.ts';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { execFileSync } from '../spawn.ts';
-import { gitChildEnv, literalPathspecs } from '../git-env.ts';
-import { GIT_ENV, GIT_ENV_AUTH, GIT_SSRF_SUBCOMMAND_FLAGS, durableSsrfFlags } from '../git-transport.ts';
-import { assertManagedFilesystemWrite, hasFilesystemPublication, managedFilesystemRootFor, type ManagedFilesystemRoot } from '../persistence/filesystem-guard.ts';
-import { acquireNativeLock, acquireNativeLockSync, type NativeLockSyncHandle } from '../persistence/native-lock.ts';
-import { recordCommit, recordIntent } from './commit-ledger.ts';
-import { OperationError, opError } from '../ops/contract.ts';
-import { shellQuote, type Action } from '../agent-output.ts';
-import { isSyncable } from '../sync.ts';
+ try {
+ for (const [mode, specs] of [['-u', matching(tracked)], ['-A', matching(untracked)], ['-A', unmatched]] as const) {
+ if (!specs.length) continue;
+ const add = withIndexRetry(root, ['add', mode, '--', ...literalPathspecs(specs)], 'git add');
+ if (add.code !== 0) throw opError('commit_paths_invalid', 'git add refused the given paths.', add.stderr.trim().slice(0, 300) || 'Check the paths exist or are tracked.');
+ }
+ const paths = withRenamePartners(root, rel);
+ const partners = paths.filter(p => !insideSourceRoots(p, scope.roots));
+ if (partners.length) throw outsideRootError(root, scope.roots, partners, 'A staged rename would commit');
+ // A file git did not index would fail `commit --only` for every path; it is left out here and reported as skipped.
+ const listed = gitOk(root, ['ls-files', '-v', '-z', '--', ...literalPathspecs(paths)], 'ls-files -v').split('\0').filter(Boolean);
+ const unindexed = new Set(unindexedFiles(root, paths, listed));
+ const staged = paths.filter(p => !unindexed.has(p) && !sparse.has(p));
+ if (!staged.length || git(root, ['diff', '--cached', '--quiet', '--', ...literalPathspecs(staged)]).code === 0) {
+ landed = { committed: false, paths, listed };
+ } else {
+ const env = { [COMMIT_VIA_ENV]: scope.lockPath, ...(scope.markHeld ? { [COMMIT_LOCK_ENV]: scope.lockPath } : {}) };
+ // #7759: literal per path, never git's global --literal-pathspecs: Git exports that to the commit's hooks, where a
+ // guard's glob pathspec ('*.json') then matches nothing and lets the commit through.
+ recordIntent(root, { writer: 'commit_push', head_before: git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).stdout.trim() || null, message });
+ const commit = withIndexRetry(root, ['commit', '--only', '-m', message, '--', ...literalPathspecs(staged)], 'git commit', env);
+ if (commit.code !== 0) {
+ throw opError('git_unavailable', `git commit failed in ${root}; the paths were unstaged again and keep their bytes.`,
+ `${commit.stderr.trim().slice(0, 300)} A missing git identity (user.name, user.email) or a refusing pre-commit hook are common causes.`);
+ }
+ landed = { committed: true, paths, listed };
+ }
+ } catch (e) {
+ try { restoreIndex(root, rel, before); } catch { /* the index lock outlasted the retries; the error below still stands */ }
+ throw e;
+ }
+ // GST-2116: after the try, so a failure from here on never restores the index under a commit that landed.
+ const sha = landed.committed ? gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD') : null;
+ if (sha) recordCommit(root, { sha, writer: 'commit_push' });
+ return { sha, skipped: unstagedPaths(root, landed.paths, landed.listed) };
+}
-export const COMMIT_LOCK_NAME = 'brain-commit.lock';
-/** Taken by pre-#6530 helpers and hooks; held too so they still exclude us during the mixed-version window. */
-export const LEGACY_PUSH_LOCK_NAME = 'gbrain-push.lock';
-export const COMMIT_LOCK_ENV = 'BRAIN_COMMIT_LOCK_HELD';
-export const PUBLISH_LOCK_NAME = 'brain-publish.lock';
-const PUBLISH_REQUEST_NAME = 'brain-publish.requested';
-const CONFLICT_STATE_NAME = 'brain-integrate-conflict.json';
-/** Write-through files gbrain wrote but could not commit (lock busy past the short budget, or a refused commit): one `<iso>\t<json path>` line each. */
-const PENDING_NAME = 'brain-writethrough-pending.log';
-/** Toplevel-relative source root(s) of this checkout, one value each (`gbrain sources harden` writes them); unset means the whole checkout. */
-export const SOURCE_ROOT_CONFIG = 'gbrain.sourceRoot';
-/** Set to the commit lock path on every commit gbrain makes under that lock; the opt-in commit guard admits only these. */
-export const COMMIT_VIA_ENV = 'GBRAIN_COMMIT_VIA';
-const MAX_PUSH_ATTEMPTS = 8;
-const sleeper = new Int32Array(new SharedArrayBuffer(4));
-const INDEX_LOCK_RETRIES = 5;
+// ── Pending write-through ───────────────────────────────────────────────────
-export type CheckoutState = 'advanced' | 'unchanged' | 'lagging';
+export interface PendingWriteThrough { path: string; since: string }
-export interface CommitPushResult {
- /**
- * `push_deferred`: an unattended publish found another publish running and left it a request to publish HEAD too.
- * `committed_local`: a managed canonical worktree, or a checkout with no Git remote (`no_remote`), where commit-push only commits the named paths and never pushes.
- */
- outcome: 'pushed' | 'nothing_to_commit' | 'pushed_checkout_lagging' | 'push_deferred' | 'committed_local';
- /** The commit now on the remote branch (the caller's commit or the merge built over it). */
- sha: string | null;
- committed: string | null;
- branch: string;
- remote: string;
- paths: string[];
- /** Remote commits merged in to publish. */
- integrated: number;
- /** `remote`: a push reported failure but every push destination already holds the commit (a lost acknowledgement or a concurrent pusher). */
- confirmed?: 'push' | 'remote';
- checkout: CheckoutState;
- lagging_reason?: string;
- /** Opt-in quarantine (git config gbrain.quarantine): the local versions of conflicting files, parked under a ref; the remote's version was published. */
- quarantined?: QuarantineEntry;
- /** The checkout has no Git remote: the paths were committed locally (or were already committed) and nothing was pushed. */
- no_remote?: true;
- /** Conflicted files where the remote held a version this checkout had already replaced: this checkout's version was published. */
- superseded_remote_paths?: string[];
- /** A managed canonical worktree: the named paths were committed (or had no change) and nothing was pushed. */
- managed?: true;
- /** Managed only: commits on the branch its upstream lacks as last fetched; null when no fetched upstream can be read. */
- unpublished?: number | null;
- /** Managed only: the branch's configured upstream (`origin/main`); null when it names none. */
- upstream?: string | null;
-}
+const PENDING_NOTED = new Set(['commit_lock_busy', 'git_index_locked', 'git_index_stale', 'git_unavailable', 'git_operation_in_progress']);
-export interface PullResult {
- status: 'up_to_date' | 'advanced' | 'ahead' | 'skipped_dirty' | 'lagging';
- from?: string;
- to?: string;
- merged?: boolean;
- /** Why the checkout could not advance (dirty must-change file, HEAD moved). */
- reason?: string;
+function readPendingFile(file: string, into: Map<string, string>): void {
+ let text: string;
+ try { text = readFileSync(file, 'utf8'); } catch { return; }
+ for (const line of text.split('\n')) {
+ const tab = line.indexOf('\t');
+ if (tab === -1) continue;
+ let path: unknown;
+ try { path = JSON.parse(line.slice(tab + 1)); } catch { continue; }
+ const since = line.slice(0, tab);
+ if (typeof path === 'string' && path && (!into.has(path) || since < into.get(path)!)) into.set(path, since);
+ }
}
-export interface CommitPushOptions {
- repo: string;
- /** Paths to commit, absolute or relative to `cwd`. Ignored with pushOnly. */
- paths?: string[];
- message?: string;
- pushOnly?: boolean;
- cwd?: string;
- lockWaitMs?: number;
- /** `--resolve`: blob choice per conflicted path for the in-memory merge. */
- resolutions?: Map<string, Resolution>;
- /**
- * `--expect-remote`: the remote commit the resolutions were chosen against (required with resolutions). Without
- * resolutions it binds the publish (#7686): HEAD is merged with that commit, pushed with a lease on it, and a remote that
- * moved anywhere else refuses, so a rewrite made after the caller checked the remote is never merged back.
- */
- expectRemote?: string;
- /** How long a foreground publish waits for another publish to finish. */
- publishWaitMs?: number;
- /** Unattended callers (the post-commit hook): publish, but advance the checkout only when it has no local edit. */
- advanceOnlyWhenClean?: boolean;
- /** Push-only: publish HEAD to this remote branch instead of the checked-out branch's upstream (the helper's `--push-only <branch>`). */
- branch?: string;
- /** Push-only: never advance the checkout and skip its pre-push hook (a managed canonical worktree; see the header). */
- keepCheckout?: boolean;
- /** Before pushing, scan what the commits the upstream lacks add (messages, added lines, merge resolutions) and refuse `publish_secret_found` on a finding: the gate for automatic publishes of commits gbrain did not write. */
- scanSecrets?: boolean;
- /** Commit the pending write-through files (`--pending`) instead of named paths. */
- pending?: boolean;
- /** Commit and publish files outside the configured source root(s): the user's explicit choice, or gbrain's own scaffolding at the checkout root. */
- allowOutsideSourceRoot?: boolean;
- /** `--base <path>=<blob>`: the blob (or `absent`) each named path had at HEAD when the writer read it; a moved one refuses `commit_base_moved`. */
- bases?: Map<string, string>;
+/** Write-through files gbrain wrote in this checkout but could not commit, oldest first. A path committed since stays listed until the next locked commit settles the ledger. */
+export function readPendingWriteThrough(repo: string): PendingWriteThrough[] {
+ try {
+ const file = absGitPath(checkoutRoot(repo), PENDING_NAME);
+ const entries = new Map<string, string>();
+ readPendingFile(file, entries);
+ readPendingFile(`${file}.settle`, entries);
+ return [...entries].map(([path, since]) => ({ path, since })).sort((a, b) => a.since.localeCompare(b.since));
+ } catch {
+ return [];
+ }
}
-export type Resolution = { kind: 'ours' } | { kind: 'theirs' } | { kind: 'file'; path: string };
+/** The pending ledger's files that still differ from HEAD (doctor's `dirty_age`); the others were committed since. */
+export function pendingWriteThroughStillDirty(repo: string): PendingWriteThrough[] {
+ const pending = readPendingWriteThrough(repo);
+ if (!pending.length) return [];
+ const dirty = dirtyPaths(checkoutRoot(repo), pending.map(e => e.path));
+ return pending.filter(e => dirty.has(e.path));
+}
-interface Ctx {
- root: string;
- branch: string;
- remote: string;
- mergeRef: string;
- trackingRef: string;
- keepCheckout?: boolean;
+/**
+ * Appends without the lock (O_APPEND), so a writer that could not get it still records its file. `root` is the checkout
+ * root and `paths` are relative to it (`scopePaths`). The derived write-through also records each file right after writing
+ * it (#8073), so a crash before its commit leaves the file for the next locked commit to sweep.
+ */
+export function notePending(root: string, paths: string[]): void {
+ try { appendFileSync(absGitPath(root, PENDING_NAME), paths.map(p => `${new Date().toISOString()}\t${JSON.stringify(p)}\n`).join('')); } catch { /* best-effort */ }
+}
+
+/** Which of `paths` differ from HEAD in the index or the working tree. */
+function dirtyPaths(root: string, paths: string[]): Set<string> {
+ const out = new Set<string>();
+ for (let i = 0; i < paths.length; i += 500) {
+ const specs = literalPathspecs(paths.slice(i, i + 500));
+ // GST-2118: status is blind to an assume-unchanged or skip-worktree entry, so a flagged edit is read from HEAD.
+ for (const { path } of flaggedChanges(root, git(root, ['ls-files', '-v', '-z', '--', ...specs]).stdout.split('\0').filter(Boolean))) out.add(path);
+ const entries = git(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...specs]).stdout.split('\0');
+ for (let j = 0; j < entries.length; j++) {
+ if (entries[j].length < 4) continue;
+ out.add(entries[j].slice(3));
+ if (/^[RC]/.test(entries[j])) j++;
+ }
+ }
+ return out;
}
-interface GitRun { code: number; stdout: string; stderr: string }
+/** Drop ledger entries whose file no longer differs from HEAD (the caller holds the commit lock). New lines appended meanwhile go to a fresh ledger file. */
+function settlePending(root: string): void {
+ try {
+ const file = absGitPath(root, PENDING_NAME);
+ const settle = `${file}.settle`;
+ const moved = `${file}.${process.pid}.tmp`;
+ if (existsSync(file)) renameSync(file, moved);
+ const entries = new Map<string, string>();
+ readPendingFile(settle, entries);
+ readPendingFile(moved, entries);
+ const dirty = (() => { try { return dirtyPaths(root, [...entries.keys()]); } catch { return null; } })();
+ const keep = [...entries].filter(([path]) => !dirty || dirty.has(path)).map(([path, since]) => `${since}\t${JSON.stringify(path)}\n`);
+ if (keep.length) { writeFileSync(`${settle}.tmp`, keep.join('')); renameSync(`${settle}.tmp`, settle); }
+ else rmSync(settle, { force: true });
+ rmSync(moved, { force: true });
+ } catch { /* best-effort: the ledger only feeds retries and doctor */ }
+}
-function git(root: string, args: string[], opts: { auth?: boolean; timeoutMs?: number; env?: NodeJS.ProcessEnv; input?: string; maxBuffer?: number } = {}): GitRun {
- const base = opts.auth ? { ...GIT_ENV_AUTH } : { ...GIT_ENV };
+/**
+ * Commit-only entry for gbrain's own write paths (write-through pages, facts
+ * fences, takes, timeline, lint fixes), always under the commit lock. A writer
+ * holding the lock past `lockWaitMs` makes this fail `commit_lock_busy` (the
+ * file write itself stands) and the file goes into the pending ledger, which
+ * the next locked write-through or `gbrain git commit-push --pending` commits and
+ * doctor's `dirty_age` reports. It never commits without the lock: that races
+ * other writers on the shared index. Paths must sit under `repo` (the source
+ * root). No marker is set, so the post-commit hook publishes. Returns the new
+ * commit, or null when the paths had no change. A named path git left out fails
+ * `commit_paths_skipped` after the rest is committed (GST-2116).
+ */
+export function commitPathsLocked(repo: string, rel: string[], message: string, opts: { lockWaitMs: number }): string | null {
+ const root = checkoutRoot(repo);
+ assertManagedFilesystemWrite(root);
+ assertNoOperationInProgress(root);
+ const paths = scopePaths(root, rel, root);
+ const own = relative(realpathSync(root), realpathSync(repo)).split('\\').join('/');
+ const roots = [own.startsWith('..') ? '' : own];
+ let lock: CommitLock;
+ try { lock = acquireCommitLock(root, opts.lockWaitMs); } catch (e) {
+ if (PENDING_NOTED.has((e as { code?: string }).code ?? '')) notePending(root, paths);
+ throw e;
+ }
try {
- const stdout = execFileSync('git', ['-C', root, ...args], {
- stdio: ['pipe', 'pipe', 'pipe'],
- input: opts.input ?? '',
- timeout: opts.timeoutMs ?? 60_000,
- ...(opts.maxBuffer ? { maxBuffer: opts.maxBuffer } : {}),
- env: gitChildEnv({ ...base, LC_ALL: 'C', LANGUAGE: 'C', ...opts.env }),
- }).toString();
- return { code: 0, stdout, stderr: '' };
+ const pending = [...dirtyPaths(root, readPendingWriteThrough(root).map(e => e.path).filter(p => !paths.includes(p) && insideSourceRoots(p, roots)))];
+ const scope = { roots, lockPath: lock.lockPath, markHeld: false };
+ let commit: ReturnType<typeof commitPaths>;
+ try {
+ commit = commitPaths(root, [...paths, ...pending], pending.length ? `${message} (+${pending.length} pending write-through file(s))` : message, scope);
+ } catch (e) {
+ if (!pending.length) throw e;
+ commit = commitPaths(root, paths, message, scope);
+ }
+ // GST-2118: a file git left out stays in the ledger, so doctor dirty_age reports it and --pending retries it loudly.
+ const ownSkipped = commit.skipped.filter(s => paths.includes(s.path));
+ if (ownSkipped.length) notePending(root, ownSkipped.map(s => s.path));
+ settlePending(root);
+ if (ownSkipped.length) {
+ const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
+ throw skippedPathsError(root, ownSkipped, { outcome: commit.sha ? 'committed_local' : 'nothing_to_commit', sha: commit.sha, committed: commit.sha, branch, remote: '', paths, integrated: 0, checkout: 'unchanged' });
+ }
+ return commit.sha;
} catch (e) {
- const err = e as { status?: number | null; stdout?: Buffer | string; stderr?: Buffer | string; message?: string };
- return {
- code: typeof err.status === 'number' ? err.status : -1,
- stdout: String(err.stdout ?? ''),
- stderr: String(err.stderr ?? err.message ?? ''),
- };
+ if (PENDING_NOTED.has((e as { code?: string }).code ?? '')) notePending(root, paths);
+ throw e;
+ } finally {
+ lock.release();
}
}
-function gitOk(root: string, args: string[], what: string, opts: Parameters<typeof git>[2] = {}): string {
- const r = git(root, args, opts);
- if (r.code !== 0) {
- throw opError('git_unavailable', `git ${what} failed in ${root}: ${r.stderr.trim().slice(0, 300) || `exit ${r.code}`}`,
- `Run git status in ${root}, fix what git reports, then rerun the same gbrain git commit-push command.`);
- }
- return r.stdout.trim();
-}
+// ── In-memory integrate ─────────────────────────────────────────────────────
-/**
- * Transport flags for this checkout's OWN configured remotes: no redirects, no
- * external helpers, no submodule fetch surface. The file protocol keeps git's
- * default (`user`): a bare repo on the same host is a supported brain topology
- * (the pre-#6530 helper pushed to it with plain git), and the URL is the
- * operator's own config, not remote-supplied input. GBRAIN_GIT_ALLOW_FILE_TRANSPORT
- * still forces `always` for tests.
- */
-function transportFlags(): string[] {
- return durableSsrfFlags().flatMap((flag, i, all) =>
- all[i - 1] === '-c' && flag.startsWith('protocol.file.allow=') && process.env.GBRAIN_GIT_ALLOW_FILE_TRANSPORT !== '1'
- ? ['protocol.file.allow=user'] : [flag]);
+interface MergeTree {
+ /** The merged tree; with conflicts, a placeholder every conflicted path must be resolved over. */
+ tree: string | null;
+ /** Raw repo-relative paths (NUL-delimited from git, never C-quoted). */
+ conflicts: string[];
+ /** Conflicts that are not one path's content (file/directory, renames): never resolvable by a blob choice. */
+ structural: string[];
}
-/** Remote operations: transport hardening on every call, credentials allowed, no prompt. */
-function remoteGit(root: string, sub: 'fetch' | 'push', args: string[], timeoutMs = 120_000): GitRun {
- return git(root, [...transportFlags(), sub, ...GIT_SSRF_SUBCOMMAND_FLAGS, ...args], { auth: true, timeoutMs });
+/** merge-tree conflict types a per-path blob choice fully resolves; anything else is structural. */
+const RESOLVABLE_CONFLICTS = new Set(['CONFLICT (contents)', 'CONFLICT (add/add)', 'CONFLICT (modify/delete)', 'CONFLICT (binary)']);
+
+const versions = new Map<string, [number, number]>();
+function cachedGitVersion(root: string): [number, number] {
+ let v = versions.get(root);
+ if (!v) { v = gitVersion(root); versions.set(root, v); }
+ return v;
}
-export function gitVersion(root: string): [number, number] {
- const m = /git version (\d+)\.(\d+)/.exec(gitOk(root, ['version'], 'version'));
- return m ? [Number(m[1]), Number(m[2])] : [0, 0];
+/** `--no-write-fetch-head` exists from git 2.29; older git just writes FETCH_HEAD. */
+function fetchFlags(root: string): string[] {
+ const [maj, min] = cachedGitVersion(root);
+ return ['--no-tags', ...(maj > 2 || (maj === 2 && min >= 29) ? ['--no-write-fetch-head'] : [])];
}
-function absGitPath(root: string, rel: string): string {
- const p = gitOk(root, ['rev-parse', '--git-path', rel], 'rev-parse --git-path');
- if (!p) throw opError('git_unavailable', `git rev-parse --git-path ${rel} printed nothing in ${root}.`, 'Check that git works in this checkout (git status).');
- return isAbsolute(p) ? p : resolve(root, p);
+/**
+ * merge-tree --write-tree on git >= 2.38; else (or with the GBRAIN_GIT_NO_MERGE_TREE=1 test seam) a 3-way read-tree
+ * that treats any same-path change on both sides as a conflict. `base` replaces the merge base (a replayed commit's
+ * parent); merge-tree takes it from git 2.40.
+ */
+function mergeTrees(root: string, ours: string, theirs: string, base?: string): MergeTree {
+ const [maj, min] = cachedGitVersion(root);
+ if ((maj > 2 || (maj === 2 && min >= (base ? 40 : 38))) && process.env.GBRAIN_GIT_NO_MERGE_TREE !== '1') {
+ const r = git(root, ['merge-tree', '--write-tree', '--name-only', '-z', ...(base ? [`--merge-base=${base}`] : []), ours, theirs]);
+ if (r.code !== 0 && r.code !== 1) throw opError('git_unavailable', 'git merge-tree failed.', r.stderr.trim().slice(0, 300));
+ const f = r.stdout.split('\0');
+ const tree = f[0] || null;
+ if (r.code === 0) return { tree, conflicts: [], structural: [] };
+ let i = 1;
+ const conflicts = new Set<string>();
+ while (i < f.length && f[i] !== '') conflicts.add(f[i++]);
+ i++;
+ const structural = new Set<string>();
+ while (i < f.length && f[i] !== '') {
+ const n = Number(f[i++]);
+ if (!Number.isInteger(n) || n < 1) break;
+ const paths = f.slice(i, i + n);
+ const type = f[i + n] ?? '';
+ i += n + 2;
+ if (type.startsWith('CONFLICT') && !RESOLVABLE_CONFLICTS.has(type)) for (const p of paths) structural.add(p);
+ }
+ return { tree, conflicts: [...conflicts], structural: [...conflicts].filter(p => structural.has(p)) };
+ }
+ const mergeBase = base ?? git(root, ['merge-base', ours, theirs]).stdout.trim();
+ if (!mergeBase) throw opError('integrate_conflict', 'The local and remote branches share no history.', 'Reconcile the branches by hand.');
+ const dir = mkdtempSync(join(tmpdir(), 'gbrain-integrate-'));
+ try {
+ const env = { GIT_INDEX_FILE: join(dir, 'index') };
+ const read = git(root, ['read-tree', '-m', '-i', '--aggressive', mergeBase, ours, theirs], { env });
+ if (read.code !== 0) throw opError('git_unavailable', 'git read-tree failed.', read.stderr.trim().slice(0, 300));
+ const unmerged = git(root, ['ls-files', '-u', '-z'], { env }).stdout.split('\0').filter(Boolean);
+ if (!unmerged.length) return { tree: gitOk(root, ['write-tree'], 'write-tree', { env }), conflicts: [], structural: [] };
+ const conflicts = [...new Set(unmerged.map(l => l.slice(l.indexOf('\t') + 1)))];
+ const structural: string[] = [];
+ for (const path of conflicts) {
+ gitOk(root, ['update-index', '--force-remove', '--', path], 'update-index', { env });
+ const mine = unmerged.find(l => l.slice(l.indexOf('\t') + 1) === path && l.split('\t')[0].split(' ')[2] === '2');
+ if (!mine) continue;
+ const [mode, sha] = mine.split('\t')[0].split(' ');
+ if (git(root, ['update-index', '--add', '--cacheinfo', `${mode},${sha},${path}`], { env }).code !== 0) structural.push(path);
+ }
+ return { tree: gitOk(root, ['write-tree'], 'write-tree', { env }), conflicts, structural };
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
}
-/** The checkout's toplevel; throws `commit_paths_invalid` outside a work tree. */
-/** The operator step that commits and pushes only `paths` (relative to `root`) with one -m per message paragraph: the fix text doctor and repair print instead of a bare git add/commit. */
-export function commitPushCommand(root: string, paths: readonly string[], messages: readonly string[]): string {
- return shellQuote(['gbrain', 'git', 'commit-push', '--path', root, ...messages.flatMap(m => ['-m', m]), '--', ...paths]);
+const treeOf = (root: string, commit: string) => gitOk(root, ['rev-parse', `${commit}^{tree}`], 'rev-parse tree');
+
+interface Integration extends MergeTree {
+ /** Local commits left out because an upstream commit already carries the same patch (`git patch-id`). */
+ skipped: string[];
}
-export function checkoutRoot(dir: string): string {
- const r = git(dir, ['rev-parse', '--show-toplevel']);
- if (r.code !== 0 || !r.stdout.trim()) {
- throw opError('commit_paths_invalid', `${dir} is not inside a git checkout.`,
- 'Run the command inside the brain checkout or pass --path <checkout>.');
+const MAX_REPLAY = 500;
+
+/**
+ * The tree a publish of `local` over `remote` should carry. A 3-way merge of the two tips
+ * counts a local commit whose patch already reached the remote (cherry-picked or rebased there) as a new
+ * change again: a remote that edited those lines since conflicts forever, and a remote that reverted it gets
+ * the change back silently. So when any local commit is patch-equivalent to an upstream one, the local
+ * commits are replayed in memory onto the remote tip instead, oldest first, leaving out the equivalent ones
+ * and the clean merges (their content is their parents'). A merge that carries its own resolution, a root
+ * commit, or more than MAX_REPLAY commits fall back to the tip merge.
+ */
+function integrate(root: string, local: string, remote: string): Integration {
+ const commits = git(root, ['rev-list', '--reverse', '--topo-order', '--cherry-mark', '--right-only', '--parents', `${remote}...${local}`])
+ .stdout.split('\n').filter(Boolean).map(line => {
+ const [head, ...parents] = line.split(' ');
+ return { sha: head.slice(1), equivalent: head.startsWith('='), parents };
+ });
+ const tipMerge = (): Integration => ({ ...mergeTrees(root, local, remote), skipped: [] });
+ if (!commits.some(c => c.equivalent) || commits.length > MAX_REPLAY) return tipMerge();
+ let acc = remote;
+ const conflicts = new Set<string>();
+ const structural = new Set<string>();
+ const skipped: string[] = [];
+ for (const c of commits) {
+ if (c.equivalent) { skipped.push(c.sha); continue; }
+ if (c.parents.length !== 1) {
+ if (c.parents.length !== 2) return tipMerge();
+ const own = mergeTrees(root, c.parents[0], c.parents[1]);
+ if (own.conflicts.length || own.tree !== treeOf(root, c.sha)) return tipMerge();
+ continue;
+ }
+ const step = mergeTrees(root, acc, c.sha, c.parents[0]);
+ for (const p of step.conflicts) conflicts.add(p);
+ for (const p of step.structural) structural.add(p);
+ acc = gitOk(root, ['commit-tree', '--no-gpg-sign', step.tree!, '-p', acc, '-m', 'gbrain: replay'], 'commit-tree');
+ recordCommit(root, { sha: acc, writer: 'replay', ref: null });
}
- return r.stdout.trim();
+ return { tree: treeOf(root, acc), conflicts: [...conflicts], structural: [...structural], skipped };
}
-function resolveCtx(root: string): Ctx {
- const sym = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
- if (sym.code !== 0) {
- throw opError('git_detached_head', `${root} is on a detached HEAD, so there is no branch to publish.`,
- 'Check out the branch the remote tracks (git switch <branch>), then rerun.');
- }
- const branch = sym.stdout.trim();
- if (git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).code !== 0) {
- throw opError('git_detached_head', `Branch ${branch} in ${root} has no commit yet.`,
- 'Make the first commit on this branch with git, then rerun.', { reason: 'unborn' });
- }
- const remote = git(root, ['config', '--get', `branch.${branch}.remote`]).stdout.trim() || 'origin';
- const mergeRef = git(root, ['config', '--get', `branch.${branch}.merge`]).stdout.trim() || `refs/heads/${branch}`;
- if (remote === '.' || git(root, ['remote', 'get-url', '--', remote]).code !== 0) {
- throw opError('git_unavailable', `Branch ${branch} in ${root} has no usable remote (${remote}); nothing was committed.`,
- `Add the remote (git remote add ${remote} <url>) or set the branch upstream, then rerun.`);
+interface TreeEntry { mode: string; type: string; sha: string }
+
+function treeEntry(root: string, commit: string, path: string): TreeEntry | null {
+ for (const line of git(root, ['ls-tree', '-z', commit, '--', ...literalPathspecs([path])]).stdout.split('\0')) {
+ const tab = line.indexOf('\t');
+ if (tab === -1 || line.slice(tab + 1) !== path) continue;
+ const [mode, type, sha] = line.slice(0, tab).split(' ');
+ return { mode, type, sha };
}
- const short = mergeRef.replace(/^refs\/heads\//, '');
- return { root, branch, remote, mergeRef, trackingRef: `refs/remotes/${remote}/${short}` };
+ return null;
}
-/** `--push-only <branch>`: publish to an explicit remote branch (validated as one exact ref, never a pattern). */
-function withBranch(ctx: Ctx, branch: string | undefined): Ctx {
- if (!branch) return ctx;
- const short = branch.replace(/^refs\/heads\//, '');
- if (!short || git(ctx.root, ['check-ref-format', `refs/heads/${short}`]).code !== 0) {
- throw opError('commit_paths_invalid', `${branch} is not a valid branch name.`, 'Pass one exact branch name, e.g. --branch main.', { detail: branch });
+/** One path's content conflict: a blob (or absent) on every side, no side has it as a directory or under a file. */
+function blobConflict(root: string, base: string, ours: string, theirs: string, path: string): boolean {
+ const sides = [base, ours, theirs].map(c => (c ? treeEntry(root, c, path) : null));
+ if (sides.every(e => !e) || sides.some(e => e && e.type !== 'blob')) return false;
+ const parts = path.split('/');
+ for (let k = 1; k < parts.length; k++) {
+ const prefix = parts.slice(0, k).join('/');
+ if ([ours, theirs].some(c => treeEntry(root, c, prefix)?.type === 'blob')) return false;
}
- return { ...ctx, mergeRef: `refs/heads/${short}`, trackingRef: `refs/remotes/${ctx.remote}/${short}` };
+ return true;
}
-/** The git-dir entries a rebase, merge, cherry-pick or revert leaves while it is in progress. */
-export const GIT_OPERATION_MARKERS = ['rebase-merge', 'rebase-apply', 'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'sequencer'] as const;
-
-/** Refuse while another git operation is mid-flight; never abort it for the user. */
-export function assertNoOperationInProgress(root: string): void {
- for (const marker of GIT_OPERATION_MARKERS) {
- if (existsSync(absGitPath(root, marker))) {
- throw opError('git_operation_in_progress', `A git ${marker.startsWith('rebase') ? 'rebase' : marker.toLowerCase().replace(/_head$/, '')} is in progress in ${root}.`,
- `Finish or abort it first. A stuck rebase may hold another writer's autostash: save it with git stash store <sha from .git/${marker}/autostash> before deleting anything. See docs/guides/shared-checkout-git.md#stuck-rebase.`,
- { detail: marker });
- }
- }
-}
-
-// ── Lock ────────────────────────────────────────────────────────────────────
-
-export interface CommitLock { release(): void; lockPath: string; reentrant: boolean }
+const MAX_SUPERSEDED_HISTORY = 200;
/**
- * Take this checkout's commit lock (and the legacy push lock). Re-entrant only
- * when BRAIN_COMMIT_LOCK_HELD names this exact lock AND the lock is really
- * held: a stale, spoofed or generic (`1`) marker cannot bypass a lock.
+ * Content conflicts where the remote's blob is one this checkout held at the same path and then replaced with
+ * another blob (a stale clone or writer brought an old copy back): the remote's version is history this side
+ * already moved past, so these resolve to ours. Reads the last MAX_SUPERSEDED_HISTORY commits of `ours` that touch
+ * the path. A blob ours never held there, a remote deletion, a structural conflict and a path the caller resolves
+ * explicitly stay conflicts.
*/
-export function acquireCommitLock(root: string, waitMs = defaultLockWaitMs()): CommitLock {
- const lockPath = absGitPath(root, COMMIT_LOCK_NAME);
- const legacyPath = absGitPath(root, LEGACY_PUSH_LOCK_NAME);
- const marker = process.env[COMMIT_LOCK_ENV];
- if (marker && marker !== '1' && resolve(marker) === lockPath) {
- const probe = acquireNativeLockSync(lockPath, { timeoutMs: 0 });
- if (!probe) return { release() {}, lockPath, reentrant: true };
- return withLegacy(root, probe, lockPath, legacyPath, waitMs);
+function supersededPaths(root: string, ours: string, theirs: string, merged: MergeTree, explicit?: Map<string, Resolution>): string[] {
+ const base = git(root, ['merge-base', ours, theirs]).stdout.trim();
+ return merged.conflicts.filter(path => {
+ if (explicit?.has(path) || merged.structural.includes(path) || path.includes('\n') || !blobConflict(root, base, ours, theirs, path)) return false;
+ const remote = treeEntry(root, theirs, path);
+ if (!remote) return false;
+ const commits = git(root, ['log', '--format=%H', '-n', String(MAX_SUPERSEDED_HISTORY), ours, '--', ...literalPathspecs([path])]).stdout.split('\n').filter(Boolean);
+ const blobs = git(root, ['cat-file', '--batch-check=%(objectname) %(objecttype)'], { input: commits.map(c => `${c}:${path}\n`).join('') })
+ .stdout.split('\n').slice(0, commits.length).map(line => (line.endsWith(' blob') ? line.split(' ')[0] : null));
+ const held = [treeEntry(root, ours, path)?.sha ?? null, ...blobs];
+ const at = held.indexOf(remote.sha);
+ return at > 0 && held.slice(0, at).some(sha => sha && sha !== remote.sha);
+ });
+}
+
+/** Apply `--resolve` choices on top of the merge's placeholder tree; structural conflicts are refused. */
+function resolvedTree(ctx: Ctx, ours: string, theirs: string, merged: MergeTree, resolutions: Map<string, Resolution>, cwd: string): string {
+ if (merged.conflicts.some(p => !resolutions.has(p))) throw conflictError(ctx, ours, theirs, merged);
+ const base = git(ctx.root, ['merge-base', ours, theirs]).stdout.trim();
+ const structural = merged.conflicts.filter(p => merged.structural.includes(p) || !blobConflict(ctx.root, base, ours, theirs, p));
+ if (structural.length) throw conflictError(ctx, ours, theirs, { ...merged, structural });
+ const dir = mkdtempSync(join(tmpdir(), 'gbrain-resolve-'));
+ try {
+ const env = { GIT_INDEX_FILE: join(dir, 'index') };
+ gitOk(ctx.root, ['read-tree', merged.tree!], 'read-tree', { env });
+ for (const path of merged.conflicts) {
+ const choice = resolutions.get(path)!;
+ if (choice.kind === 'file') {
+ const blob = gitOk(ctx.root, ['hash-object', '-w', '--', resolve(cwd, choice.path)], 'hash-object');
+ gitOk(ctx.root, ['update-index', '--add', '--cacheinfo', `${treeEntry(ctx.root, ours, path)?.mode ?? '100644'},${blob},${path}`], 'update-index', { env });
+ continue;
+ }
+ const entry = treeEntry(ctx.root, choice.kind === 'ours' ? ours : theirs, path);
+ if (entry) gitOk(ctx.root, ['update-index', '--add', '--cacheinfo', `${entry.mode},${entry.sha},${path}`], 'update-index', { env });
+ else gitOk(ctx.root, ['update-index', '--force-remove', '--', path], 'update-index', { env });
+ }
+ return gitOk(ctx.root, ['write-tree'], 'write-tree', { env });
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
}
- const handle = acquireNativeLockSync(lockPath, { timeoutMs: waitMs });
- if (!handle) throw lockBusy(lockPath, waitMs);
- return withLegacy(root, handle, lockPath, legacyPath, waitMs);
}
-function withLegacy(root: string, handle: NativeLockSyncHandle, lockPath: string, legacyPath: string, waitMs: number): CommitLock {
- let legacy: NativeLockSyncHandle | null;
- try { legacy = acquireNativeLockSync(legacyPath, { timeoutMs: waitMs }); }
- catch (e) { handle.release(); throw e; }
- if (!legacy) { handle.release(); throw lockBusy(legacyPath, waitMs, root); }
- return { lockPath, reentrant: false, release() { legacy!.release(); handle.release(); } };
+function shellWord(v: string): string {
+ return /^[A-Za-z0-9._\/@%+:-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`;
}
-/** The same locks for async callers (`gbrain sync`'s pull), without blocking the event loop while waiting. */
-export async function acquireCommitLockAsync(root: string, waitMs = defaultLockWaitMs(), signal?: AbortSignal): Promise<{ release(): Promise<void> }> {
- const lockPath = absGitPath(root, COMMIT_LOCK_NAME);
- const legacyPath = absGitPath(root, LEGACY_PUSH_LOCK_NAME);
- const handle = await acquireNativeLock(lockPath, { timeoutMs: waitMs, signal });
- if (!handle) throw lockBusy(lockPath, waitMs, root);
- let legacy;
- try { legacy = await acquireNativeLock(legacyPath, { timeoutMs: waitMs, signal }); }
- catch (e) { await handle.release(); throw e; }
- if (!legacy) { await handle.release(); throw lockBusy(legacyPath, waitMs, root); }
- return { async release() { await legacy.release(); await handle.release(); } };
+function conflictError(ctx: Ctx, ours: string, theirs: string, merged: MergeTree & { superseded?: string[] }, preface = ''): OperationError {
+ const paths = merged.conflicts;
+ const local = ours.slice(0, 12);
+ const remote = theirs.slice(0, 12);
+ const compare = `Compare the two versions (this machine's: git show ${local}:<path>; the remote's: git show ${remote}:<path>)`;
+ const fix = merged.structural.length
+ ? `${preface}The local commit ${local} stays local and the checkout is unchanged. ${merged.structural.map(shellWord).join(', ')} ${merged.structural.length === 1 ? 'is' : 'are'} a file/directory or rename conflict that a per-file choice cannot resolve. ${compare}, then move or remove the local path in a new commit (gbrain git commit-push -m "<msg>" -- <paths>) and rerun gbrain git commit-push --push-only. See docs/guides/shared-checkout-git.md#conflicts.`
+ : `${preface}The local commit ${local} stays local and the checkout is unchanged. ${compare}, then run gbrain git commit-push --push-only${ctx.keepCheckout ? ' --keep-checkout' : ''} --expect-remote ${remote} ${paths.map(p => `--resolve ${shellWord(p)}=ours|theirs`).join(' ')} (ours = this machine's version, theirs = the remote's, or =file:<path> with a merged copy). Until then every push from this checkout reports this conflict. See docs/guides/shared-checkout-git.md#conflicts.`;
+ return opError('integrate_conflict', `Local and remote commits both changed ${paths.length} file(s) on ${ctx.branch}; nothing was merged.`, fix,
+ { detail: JSON.stringify({ local: ours, remote: theirs, paths, structural: merged.structural, ...(merged.superseded?.length ? { superseded: merged.superseded } : {}) }),
+ fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
+ why: 'Choosing which version of a file wins discards the other side; ask the user before resolving.',
+ user_message: `Both this machine and the remote changed ${paths.join(', ')}. Which version should win, or should they be merged by hand?`,
+ ...(merged.structural.length ? {} : { argv: ['gbrain', 'git', 'commit-push', '--push-only', ...(ctx.keepCheckout ? ['--keep-checkout'] : []), '--path', ctx.root, '--expect-remote', theirs, ...paths.flatMap(p => ['--resolve', `${p}=<ours|theirs>`])] }),
+ docs: 'docs/guides/shared-checkout-git.md#conflicts' } });
}
-function defaultLockWaitMs(): number {
- const raw = process.env.GBRAIN_COMMIT_LOCK_WAIT_SECONDS ?? process.env.GBRAIN_PUSH_LOCK_WAIT_SECONDS;
- const secs = raw === undefined ? 60 : Number(raw);
- return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : 60_000;
+/** Honors the user's commit signing config, like the `git pull` it replaces. */
+function buildMerge(ctx: Ctx, ours: string, theirs: string, tree: string, skipped: string[] = [], extra: string[] = []): string {
+ const remote = `${ctx.remote}/${ctx.mergeRef.replace(/^refs\/heads\//, '')}`;
+ const note = skipped.length
+ ? ['-m', `Left out ${skipped.length} local commit(s) whose patch ${remote} already has: ${skipped.slice(0, 20).map(s => s.slice(0, 12)).join(' ')}${skipped.length > 20 ? ' ...' : ''}`] : [];
+ const sha = gitOk(ctx.root, ['commit-tree', tree, '-p', ours, '-p', theirs, '-m', `gbrain: merge ${remote} into ${ctx.branch}`, ...note, ...extra.flatMap(m => ['-m', m])], 'commit-tree');
+ recordCommit(ctx.root, { sha, writer: 'merge', ref: null });
+ return sha;
}
-function lockBusy(lockPath: string, waitMs: number, root?: string): OperationError {
- return opError('commit_lock_busy', `Another writer held this checkout's commit lock for ${Math.round(waitMs / 1000)}s.`,
- `Another commit or push is running in ${root ?? 'this checkout'} (lock ${lockPath}). Retry once it finishes; nothing was committed.`,
- { detail: lockPath, retryable: true });
+function fetchTracking(ctx: Ctx): string | null {
+ const r = remoteGit(ctx.root, 'fetch', [...fetchFlags(ctx.root), '--', ctx.remote, `+${ctx.mergeRef}:${ctx.trackingRef}`]);
+ if (r.code !== 0) return null;
+ return git(ctx.root, ['rev-parse', '--verify', '--quiet', ctx.trackingRef]).stdout.trim() || null;
}
-// ── Paths ───────────────────────────────────────────────────────────────────
+function isAncestor(root: string, a: string, b: string): boolean {
+ return git(root, ['merge-base', '--is-ancestor', a, b]).code === 0;
+}
-/** Repo-relative paths; refuses the root itself, `.git` and anything outside the checkout. */
-export function scopePaths(root: string, paths: string[], cwd: string): string[] {
- if (paths.length === 0) {
- throw opError('commit_paths_invalid', 'No paths to commit.',
- 'Pass the explicit file(s) you wrote; a repo-wide commit would sweep up other writers\' files.');
- }
- const out: string[] = [];
- for (const p of paths) {
- const abs = resolve(cwd, p);
- const rel = relative(root, abs);
- if (rel === '' || rel === '.' || rel.startsWith('..') || isAbsolute(rel)) {
- throw opError('commit_paths_invalid', `Path ${p} is ${rel === '' || rel === '.' ? 'the whole checkout' : 'outside the checkout'}.`,
- 'Pass the explicit file(s) you wrote inside the checkout; a repo-wide commit would sweep up other writers\' files.', { detail: p });
- }
- if (rel.split(/[\\/]/)[0] === '.git') {
- throw opError('commit_paths_invalid', `Path ${p} is inside .git.`, 'Pass files in the working tree.', { detail: p });
+/**
+ * #5138: true only when EVERY effective push destination (pushurl and
+ * pushInsteadOf expanded) has `sha` on the exact target branch. A URL that git
+ * would resolve as another remote alias fails closed, and remote evidence is
+ * read live (ls-remote), never from a stale tracking ref or the fetch repo.
+ */
+function remoteContains(ctx: Ctx, sha: string): boolean {
+ const branchRef = ctx.mergeRef;
+ if (git(ctx.root, ['check-ref-format', branchRef]).code !== 0) return false;
+ const urls = git(ctx.root, ['remote', 'get-url', '--push', '--all', '--', ctx.remote]).stdout.split('\n').map(u => u.trim()).filter(Boolean);
+ if (urls.length === 0) return false;
+ for (const url of urls) {
+ if (git(ctx.root, ['ls-remote', '--get-url', '--', url]).stdout.trim() !== url) return false;
+ const listed = git(ctx.root, [...transportFlags(), 'ls-remote', '--exit-code', '--', url, branchRef], { auth: true, timeoutMs: 60_000 });
+ if (listed.code !== 0) return false;
+ const tip = listed.stdout.split(/\s/)[0];
+ if (!/^[0-9a-f]{40,64}$/.test(tip)) return false;
+ if (git(ctx.root, ['cat-file', '-e', `${tip}^{commit}`]).code !== 0) {
+ const got = git(ctx.root, [...transportFlags(), 'fetch', '--quiet', ...fetchFlags(ctx.root), ...GIT_SSRF_SUBCOMMAND_FLAGS, '--', url, tip], { auth: true, timeoutMs: 120_000 });
+ if (got.code !== 0) return false;
}
- out.push(rel.split('\\').join('/'));
+ if (!isAncestor(ctx.root, sha, tip)) return false;
}
- return [...new Set(out)];
+ return true;
}
-/** The checkout's configured source roots (`gbrain.sourceRoot`, toplevel-relative); [''] (the whole checkout) when none is set. */
-export function configuredSourceRoots(root: string): string[] {
- const roots: string[] = [];
- for (const raw of git(root, ['config', '--get-all', SOURCE_ROOT_CONFIG]).stdout.split('\n').map(v => v.trim()).filter(Boolean)) {
- const rel = (isAbsolute(raw) ? relative(root, raw) : raw).split('\\').join('/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
- if (rel === '' || rel === '.') return [''];
- if (!rel.startsWith('..')) roots.push(rel);
- }
- return roots.length ? [...new Set(roots)] : [''];
-}
+interface Published { sha: string; integrated: number; confirmed: 'push' | 'remote'; quarantined?: QuarantineEntry; superseded?: string[] }
-const covers = (spec: string, path: string) => spec === '' || path === spec || path.startsWith(`${spec}/`);
-export const insideSourceRoots = (path: string, roots: string[]) => roots.some(r => covers(r, path));
+// ── Quarantine (opt-in) ─────────────────────────────────────────────────────
-function outsideRootError(root: string, roots: string[], paths: string[], what: string): OperationError {
- return opError('commit_outside_source_root', `${what} ${paths.slice(0, 10).join(', ')}${paths.length > 10 ? ', ...' : ''}, outside this brain's source root (${roots.join(', ')}).`,
- `Commit only files under the source root. Files elsewhere in ${root} belong to other projects or writers; commit those with their own tools. Nothing was staged or committed.`,
- { detail: JSON.stringify({ roots, paths }) });
-}
+const QUARANTINE_LEDGER_NAME = 'brain-quarantine.log';
+export const QUARANTINE_REF_PREFIX = 'refs/gbrain/quarantine/';
-// ── Commit ──────────────────────────────────────────────────────────────────
+export interface QuarantineEntry { ref: string; local: string; remote: string; paths: string[]; at: string }
-function indexLocked(r: GitRun): boolean {
- return /index\.lock': File exists|Unable to create '.*index\.lock'/.test(r.stderr);
-}
+const quarantineEnabled = (root: string) => git(root, ['config', '--type=bool', '--get', 'gbrain.quarantine']).stdout.trim() === 'true';
-/** Run an index-writing git command; a lockless git holding index.lock gets a bounded, jittered retry. */
-function withIndexRetry(root: string, args: string[], what: string, env?: NodeJS.ProcessEnv, input?: string): GitRun {
- for (let attempt = 0; ; attempt++) {
- const r = git(root, args, { env, timeoutMs: 120_000, input });
- if (r.code === 0 || !indexLocked(r)) return r;
- if (attempt >= INDEX_LOCK_RETRIES) {
- const lock = absGitPath(root, 'index.lock');
- let ageMs = 0;
- try { ageMs = Date.now() - statSync(lock).mtimeMs; } catch { /* gone */ }
- if (ageMs > 10 * 60_000) {
- throw opError('git_index_stale', `A Git index lock older than 10 minutes blocks ${root}: ${lock}.`,
- `If no git command is running in that checkout, remove ${lock}, then rerun. Nothing was committed.`, { detail: lock });
- }
- throw opError('git_index_locked', `Another git process kept ${root}'s index locked during ${what}.`,
- 'A git command that does not take the commit lock is running in this checkout. Retry shortly; nothing was committed.', { detail: lock, retryable: true });
- }
- Atomics.wait(sleeper, 0, 0, 100 * 2 ** attempt + Math.floor(Math.random() * 100));
- }
+/** Name the local commit under refs/gbrain/quarantine/ and note which files it parks; the ref keeps it even if history is later rewritten. */
+function parkLocalVersion(root: string, local: string, remote: string, paths: string[]): QuarantineEntry {
+ const at = new Date().toISOString();
+ const ref = `${QUARANTINE_REF_PREFIX}${at.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')}-${local.slice(0, 12)}`;
+ gitOk(root, ['update-ref', ref, local], 'update-ref quarantine');
+ const entry = { ref, local, remote, paths, at };
+ appendFileSync(absGitPath(root, QUARANTINE_LEDGER_NAME), `${JSON.stringify(entry)}\n`);
+ return entry;
}
-/** A staged rename (`git mv`) commits both sides: committing only the new name would publish a duplicate and leave the deletion staged for another writer's commit. */
-function withRenamePartners(root: string, rel: string[]): string[] {
- const fields = git(root, ['diff', '--cached', '-M', '--name-status', '-z']).stdout.split('\0');
- const out = new Set(rel);
- for (let i = 0; i < fields.length;) {
- const status = fields[i];
- if (!status) break;
- if (/^[RC]/.test(status)) {
- const [from, to] = [fields[i + 1], fields[i + 2]];
- if (status.startsWith('R') && (out.has(from) || out.has(to))) { out.add(from); out.add(to); }
- i += 3;
- } else i += 2;
+/** Parked local versions whose ref still exists (deleting the ref is how the user says they are done with it). */
+export function readQuarantine(repo: string): QuarantineEntry[] {
+ try {
+ const root = checkoutRoot(repo);
+ const p = absGitPath(root, QUARANTINE_LEDGER_NAME);
+ if (!existsSync(p)) return [];
+ const live = new Set(git(root, ['for-each-ref', '--format=%(refname)', QUARANTINE_REF_PREFIX]).stdout.split('\n').filter(Boolean));
+ return readFileSync(p, 'utf8').split('\n').flatMap(line => {
+ try { const e = JSON.parse(line) as QuarantineEntry; return live.has(e.ref) ? [e] : []; } catch { return []; }
+ });
+ } catch {
+ return [];
}
- return [...out];
-}
-
-/** Index entries that differ from HEAD, whoever staged them, with rename detection off so both sides of a rename are listed. */
-function stagedPaths(root: string): string[] {
- return git(root, ['diff', '--cached', '--no-renames', '--name-only', '-z']).stdout.split('\0').filter(Boolean);
}
-/** The index entries under `rel` as `ls-files -s` records, so a failed commit can put them back exactly. */
-function indexEntries(root: string, rel: string[]): string[] {
- return git(root, ['ls-files', '-s', '-z', '--', ...literalPathspecs(rel)]).stdout.split('\0').filter(Boolean);
+/**
+ * Push `start` (an immutable sha), merging remote commits in memory as needed.
+ * When the remote already holds the candidate, the published tip (which may be
+ * a merge built over it earlier) is returned so a lagging checkout catches up.
+ */
+function publish(ctx: Ctx, start: string, resolutions: Map<string, Resolution> | undefined, expectRemote: string | undefined, cwd: string): Published {
+ const bound = expectRemote && !resolutions?.size ? gitOk(ctx.root, ['rev-parse', '--verify', `${expectRemote}^{commit}`], 'rev-parse --expect-remote') : undefined;
+ let candidate = start;
+ let integrated = 0;
+ let lastError = '';
+ let stalled = 0;
+ let quarantined: QuarantineEntry | undefined;
+ const superseded = new Set<string>();
+ const notes = () => ({ ...(quarantined ? { quarantined } : {}), ...(superseded.size ? { superseded: [...superseded] } : {}) });
+ const onRemote = (): Published => {
+ const tip = fetchTracking(ctx);
+ return { sha: tip && isAncestor(ctx.root, candidate, tip) ? tip : candidate, integrated, confirmed: 'remote', ...notes() };
+ };
+ for (let attempt = 0; attempt < MAX_PUSH_ATTEMPTS; attempt++) {
+ if (attempt) Atomics.wait(sleeper, 0, 0, Math.min(2000, 50 * 2 ** attempt) + Math.floor(Math.random() * 100));
+ let remoteTip = bound && !isAncestor(ctx.root, bound, candidate) ? bound : null;
+ if (!remoteTip) {
+ const push = remoteGit(ctx.root, 'push', [...(ctx.keepCheckout ? ['--no-verify'] : []), ...(bound ? [`--force-with-lease=${ctx.mergeRef}:${bound}`] : []), '--', ctx.remote, `${candidate}:${ctx.mergeRef}`]);
+ if (push.code === 0) return { sha: candidate, integrated, confirmed: 'push', ...notes() };
+ lastError = push.stderr.trim();
+ if (remoteContains(ctx, candidate)) return onRemote();
+ remoteTip = fetchTracking(ctx);
+ if (!remoteTip) break;
+ if (bound && remoteTip !== bound) {
+ throw opError('push_unconfirmed', `The remote moved to ${remoteTip.slice(0, 12)} after --expect-remote ${bound.slice(0, 12)} was checked, so nothing was pushed: publishing now could merge back commits a rewrite removed.`,
+ 'Check the remote history first (gbrain sources refresh checks it for a force-push), then rerun.', { detail: candidate, retryable: true });
+ }
+ if (isAncestor(ctx.root, remoteTip, candidate)) {
+ if (++stalled > 1) break;
+ continue;
+ }
+ }
+ const raw = integrate(ctx.root, candidate, remoteTip);
+ const kept = supersededPaths(ctx.root, candidate, remoteTip, raw, resolutions);
+ const merged = kept.length
+ ? { ...raw, superseded: kept, conflicts: raw.conflicts.filter(p => !kept.includes(p)),
+ tree: resolvedTree(ctx, candidate, remoteTip, { ...raw, conflicts: kept }, new Map(kept.map(p => [p, { kind: 'ours' } as Resolution])), cwd) }
+ : raw;
+ let tree = merged.tree!;
+ let mergeNotes: string[] = kept.length
+ ? [`Kept this machine's version of ${kept.length} file(s) where the remote held a version this checkout had already replaced: ${kept.slice(0, 20).join(', ')}${kept.length > 20 ? ', ...' : ''}`] : [];
+ if (merged.conflicts.length && !resolutions?.size && !merged.structural.length && quarantineEnabled(ctx.root)) {
+ tree = resolvedTree(ctx, candidate, remoteTip, merged, new Map(merged.conflicts.map(p => [p, { kind: 'theirs' } as Resolution])), cwd);
+ quarantined = parkLocalVersion(ctx.root, candidate, remoteTip, merged.conflicts);
+ mergeNotes = [...mergeNotes, `Quarantined this machine's version of ${merged.conflicts.length} conflicting file(s) under ${quarantined.ref}: ${merged.conflicts.slice(0, 20).join(', ')}`];
+ } else if (merged.conflicts.length) {
+ if (!resolutions?.size) throw conflictError(ctx, candidate, remoteTip, merged);
+ if (!expectRemote || !remoteTip.startsWith(expectRemote.toLowerCase())) {
+ throw conflictError(ctx, candidate, remoteTip, merged,
+ `The remote moved to ${remoteTip.slice(0, 12)}${expectRemote ? ` after the choice was made against ${expectRemote.slice(0, 12)}` : ''}; review the remote's current version before choosing. `);
+ }
+ tree = resolvedTree(ctx, candidate, remoteTip, merged, resolutions, cwd);
+ }
+ integrated += Number(git(ctx.root, ['rev-list', '--count', `${candidate}..${remoteTip}`]).stdout.trim() || 0);
+ candidate = buildMerge(ctx, candidate, remoteTip, tree, merged.skipped, mergeNotes);
+ for (const p of kept) superseded.add(p);
+ }
+ if (remoteContains(ctx, candidate)) return onRemote();
+ throw opError('push_unconfirmed', `The commit is durable locally but no push to ${ctx.remote}/${ctx.mergeRef.replace(/^refs\/heads\//, '')} was confirmed.`,
+ `git push failed (network, credentials, branch protection, or a remote that kept moving): ${lastError.slice(0, 500) || 'no detail'}. Rerun gbrain git commit-push --push-only once the remote is reachable; never git pull --rebase in this checkout.`,
+ { detail: candidate, retryable: true });
+}
+
+/** Non-merge commits in `target` but not in `upstream` (at most 200) that change files outside `roots`; null when git cannot list them. */
+export function localCommitsOutsideRoots(root: string, target: string, upstream: string, roots: string[]): Array<{ sha: string; paths: string[] }> | null {
+ if (roots.includes('')) return [];
+ const local = git(root, ['rev-list', '--no-merges', '--max-count=200', target, '--not', upstream]);
+ if (local.code !== 0) return null;
+ const offending: Array<{ sha: string; paths: string[] }> = [];
+ for (const sha of local.stdout.split('\n').filter(Boolean)) {
+ const paths = git(root, ['diff-tree', '--no-commit-id', '--name-only', '--no-renames', '-r', '-z', '--root', sha]).stdout.split('\0').filter(p => p && !insideSourceRoots(p, roots));
+ if (paths.length) offending.push({ sha, paths });
+ }
+ return offending;
}
/**
- * Put the index under `rel` back to `before` after a commit that did not land:
- * `git add` already staged the paths, and an entry left staged in the shared
- * index is what the next writer's commit without paths sweeps up.
+ * Refuse to publish a local commit that changes files outside the configured source root(s). In a shared
+ * checkout a commit made without paths (a cron's `git add <dir>; git commit`) carries whatever any writer
+ * had staged; the source-root config is how a brain inside a larger repository says which files are its own.
+ * Merge commits are not judged (gbrain's in-memory merges bring remote files in). With no root configured
+ * the whole checkout is the root and nothing is refused.
*/
-function restoreIndex(root: string, rel: string[], before: string[]): void {
- const pathOf = (line: string) => line.slice(line.indexOf('\t') + 1);
- const kept = new Set(before.map(pathOf));
- const zero = '0'.repeat(git(root, ['rev-parse', 'HEAD']).stdout.trim().length || 40);
- const records = [...indexEntries(root, rel).map(pathOf).filter(p => !kept.has(p)).map(p => `0 ${zero}\t${p}`), ...before];
- if (records.length) withIndexRetry(root, ['update-index', '-z', '--index-info'], 'index restore', undefined, records.map(l => `${l}\0`).join(''));
+function assertLocalCommitsInsideRoots(ctx: Ctx, target: string, roots: string[]): void {
+ const offending = localCommitsOutsideRoots(ctx.root, target, ctx.trackingRef, roots) ?? [];
+ if (!offending.length) return;
+ const files = [...new Set(offending.flatMap(o => o.paths))];
+ const shas = offending.map(o => o.sha.slice(0, 12)).join(', ');
+ throw opError('commit_outside_source_root', `${offending.length} local commit(s) (${shas}) change ${files.length} file(s) outside this brain's source root (${roots.join(', ')}): ${files.slice(0, 10).join(', ')}${files.length > 10 ? ', ...' : ''}. Nothing was pushed.`,
+ `A commit made without gbrain git commit-push (for example a cron's git add plus git commit) can carry files other writers had staged. Show the user git show --stat ${offending[0].sha.slice(0, 12)}; if they want it published as is, rerun with --allow-outside-source-root. See docs/guides/shared-checkout-git.md#source-roots.`,
+ { detail: JSON.stringify({ roots, commits: offending }),
+ fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
+ argv: ['gbrain', 'git', 'commit-push', '--push-only', '--allow-outside-source-root', '--path', ctx.root],
+ why: 'These commits change files that are not the brain\'s; publishing them can overwrite other projects\' or writers\' work on the remote.',
+ user_message: `Local commit(s) ${shas} change files outside the brain's folder (${files.slice(0, 5).join(', ')}${files.length > 5 ? ', ...' : ''}). Publish them anyway?`,
+ docs: 'docs/guides/shared-checkout-git.md#source-roots' } });
+}
+
+/** The automatic-publish secret gate: scan what the commits in trackingRef..target add (the exact range this publish pushes, under its lock). */
+function assertNoSecretsInRange(ctx: Ctx, target: string): void {
+ const scan = scanRange(ctx.root, ctx.trackingRef, target);
+ if (scan.unreadable !== undefined) {
+ throw opError('publish_scan_unreadable', `The secret scan could not read the local commits ${ctx.trackingRef}..${target.slice(0, 12)} (${scan.unreadable}). No secret was reported. Nothing was pushed.`,
+ `The publish pushes only commits it has read in full. Check the checkout with git fsck in ${ctx.root} (a missing or corrupt object, a full disk, or a git too slow for the 300 s budget), fix what it reports, then retry. Never publish with a command that skips this scan.`,
+ { detail: JSON.stringify({ unreadable: scan.unreadable }), fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
+ argv: ['git', '-C', ctx.root, 'fsck'],
+ why: 'Read-only: names missing or corrupt objects in the unpublished commits, the usual reason the scan cannot read them.',
+ user_message: `The secret scan could not read the unpublished commits in ${ctx.root}, so nothing was pushed. Check the checkout with git fsck and fix what it reports?`,
+ docs: 'docs/guides/shared-checkout-git.md#publish_scan_unreadable' } });
+ }
+ if (!scan.findings.length && !scan.unscanned.length && !scan.gate_changes.length) return;
+ const named = [...scan.findings.map(f => `${f.path}:${f.line} (${f.pattern}, ${f.commit.slice(0, 7)})`), ...scan.unscanned.map(u => `${u.path} (too large to scan, ${u.commit.slice(0, 7)})`),
+ ...scan.gate_changes.map(g => `${g.path} (changes what the scan sees, ${g.commit.slice(0, 7)})`)];
+ throw opError('publish_secret_found',
+ `${named.length} item(s) in the local commits ${ctx.trackingRef}..${target.slice(0, 12)} look like secrets or could not be scanned: ${named.slice(0, 10).join(', ')}${named.length > 10 ? ', ...' : ''}. Nothing was pushed.`,
+ 'Remove the value from those commits (rewriting unpushed local commits is the user\'s call), or add a false positive\'s fingerprint to .gbrain-scan-allow, then retry. Never publish them with a command that skips this scan.',
+ { detail: JSON.stringify(scan),
+ fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
+ argv: ['git', '-C', ctx.root, 'log', '--stat', `${ctx.trackingRef}..${target}`],
+ why: 'Lists the unpublished commits the scan refused; read-only. A secret pushed to the remote stays in its history.',
+ user_message: `Unpublished commits in ${ctx.root} hold ${named.length || 'some'} item(s) that look like secrets or could not be scanned (${named.slice(0, 3).join(', ')}). Nothing was pushed. Remove them from those commits, or confirm a false positive so it can be allowlisted by fingerprint?`,
+ docs: 'docs/guides/shared-checkout-git.md#publish_secret_found' } });
+}
+
+/** Advance the shared checkout (caller holds the commit lock) with a real compare-and-swap: fast-forward only, hooks off, never autostash. */
+function advanceLocked(root: string, target: string, expectedHead: string): { checkout: CheckoutState; reason?: string } {
+ const head = git(root, ['rev-parse', 'HEAD']).stdout.trim();
+ if (head === target || isAncestor(root, target, head)) return { checkout: 'unchanged' };
+ if (head !== expectedHead) {
+ return { checkout: 'lagging', reason: isAncestor(root, expectedHead, head)
+ ? `a newer local commit (${head.slice(0, 12)}) landed during the push; publishing it advances the checkout`
+ : `HEAD moved to ${head.slice(0, 12)} during the push (a writer that did not take the commit lock)` };
+ }
+ if (!isAncestor(root, head, target)) return { checkout: 'lagging', reason: `HEAD ${head.slice(0, 12)} is not part of the published history (it was rewritten locally)` };
+ const r = withIndexRetry(root, ['-c', 'core.hooksPath=/dev/null', '-c', 'merge.autoStash=false', 'merge', '--ff-only', '--quiet', target], 'checkout advance');
+ if (r.code === 0) return { checkout: 'advanced' };
+ const dirty = [...r.stderr.matchAll(/^\t(.+)$/gm)].map(m => m[1]);
+ if (dirty.length) return { checkout: 'lagging', reason: `local edits in ${dirty.join(', ')} block the fast-forward` };
+ throw opError('git_unavailable', `git could not fast-forward ${root} to ${target.slice(0, 12)}.`,
+ `${r.stderr.trim().slice(0, 300) || `exit ${r.code}`}. Nothing in the working tree changed; run gbrain git commit-push --pull once git works in this checkout.`, { detail: target });
+}
+
+function advanceWithLock(root: string, target: string, expectedHead: string, onlyWhenClean: boolean, lockWaitMs?: number): { checkout: CheckoutState; reason?: string } {
+ let lock: CommitLock;
+ try { lock = acquireCommitLock(root, lockWaitMs); } catch (e) {
+ if ((e as { code?: string }).code !== 'commit_lock_busy') throw e;
+ return { checkout: 'lagging', reason: 'another writer held the commit lock; the next publish or --pull advances the checkout' };
+ }
+ try {
+ if (onlyWhenClean && git(root, ['status', '--porcelain']).stdout.trim()) {
+ return { checkout: 'lagging', reason: 'the checkout has local edits and this unattended run never moves files under them' };
+ }
+ return advanceLocked(root, target, expectedHead);
+ } finally {
+ lock.release();
+ }
}
-interface CommitScope { roots: string[]; lockPath: string; markHeld: boolean; bases?: ReadonlyMap<string, string> }
+// ── Conflict state (doctor / put_page read it) ──────────────────────────────
-/** A named path `git add -A` left out of the index while still exiting 0 (GST-2116). */
-export interface SkippedPath { path: string; reason: 'assume_unchanged' | 'skip_worktree' | 'not_staged' }
+export interface IntegrateConflictState { branch: string; at: string; local: string; remote: string; paths: string[] }
-/** The flagged index entries in `listed` (`ls-files -v`: lower case for assume-unchanged, S for skip-worktree) whose bytes on disk HEAD lacks. A skip-worktree entry absent from disk is a sparse checkout, not a change. */
-function flaggedChanges(root: string, listed: string[]): SkippedPath[] {
- const changed: SkippedPath[] = [];
- const flagged = listed.filter(entry => /^[a-zS] /.test(entry));
- const gitlinks = new Set(flagged.length
- ? gitOk(root, ['ls-files', '-s', '-z', '--', ...literalPathspecs(flagged.map(line => line.slice(2)))], 'ls-files -s')
- .split('\0').filter(entry => entry.startsWith('160000 ')).map(entry => entry.slice(entry.indexOf('\t') + 1))
- : []);
- for (const line of flagged) {
- const path = line.slice(2);
- if (gitlinks.has(path)) continue;
- const abs = join(root, path);
- const reason = /^[sS]/.test(line) ? 'skip_worktree' as const : 'assume_unchanged' as const;
- const stat = (() => { try { return lstatSync(abs); } catch { return null; } })();
- if (!stat && reason === 'skip_worktree') continue;
- const hashed = !stat ? null : stat.isSymbolicLink()
- ? git(root, ['hash-object', '--stdin'], { input: readlinkSync(abs) })
- : git(root, ['hash-object', '--', path]);
- // An entry git cannot hash (a missing required filter, an unreadable file, a directory now) counts as changed, so it is reported, never dropped.
- const disk = hashed && (hashed.code === 0 ? hashed.stdout.trim() : undefined);
- const committed = git(root, ['rev-parse', '--verify', '--quiet', `HEAD:${path}`]).stdout.trim() || null;
- if (disk !== committed) changed.push({ path, reason });
+/** The unresolved integrate_conflict recorded for this checkout, if any. */
+export function readIntegrateConflict(repo: string): IntegrateConflictState | null {
+ try {
+ const root = checkoutRoot(repo);
+ const p = absGitPath(root, CONFLICT_STATE_NAME);
+ return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) as IntegrateConflictState : null;
+ } catch {
+ return null;
}
- return changed;
}
-/**
- * GST-2116: the named paths whose bytes on disk HEAD still lacks once the commit step is done. `git add -A` stages
- * nothing and exits 0 for a modified entry flagged assume-unchanged or skip-worktree (`ls-files -v`: lower case, or S;
- * `commit --only` may still pick one up beside another path, so the check reads HEAD) and for a file inside an untracked
- * nested repository. A skip-worktree entry absent from disk is a sparse checkout, not a change, and a flagged gitlink
- * is left out (its commit lives in the nested repository, which hash-object cannot read). Ignored files under a named
- * directory are left out as git leaves them; a named ignored file is refused by `git add` itself.
- */
-function unstagedPaths(root: string, rel: string[], listed: string[]): SkippedPath[] {
- const skipped = new Map(flaggedChanges(root, listed).map(s => [s.path, s.reason]));
- for (const path of unindexedFiles(root, rel, listed)) if (!skipped.has(path)) skipped.set(path, 'not_staged');
- // Only a named directory can hide an unstaged change from the two checks above (a nested repository inside it).
- const dirs = rel.filter(path => { try { return lstatSync(join(root, path)).isDirectory(); } catch { return false; } });
- // Status lists nothing under a directory that sits inside an untracked nested repository.
- for (const path of dirs) {
- const parents = path.split('/').slice(0, -1).map((_, i, parts) => parts.slice(0, i + 1).join('/'));
- if (!skipped.has(path) && parents.some(parent => existsSync(join(root, parent, '.git')))) skipped.set(path, 'not_staged');
- }
- const status = dirs.length ? gitOk(root, ['--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', ...literalPathspecs(dirs)], 'status') : '';
- for (const entry of status.split('\0').filter(Boolean)) {
- const path = entry.slice(3);
- if ((entry[1] !== ' ' || entry.startsWith('??')) && !skipped.has(path)) skipped.set(path, 'not_staged');
- }
- return [...skipped].map(([path, reason]) => ({ path, reason })).sort((a, b) => a.path.localeCompare(b.path));
+function recordConflict(root: string, branch: string, e: unknown): void {
+ try {
+ const d = JSON.parse(String((e as { detail?: string }).detail ?? '{}'));
+ writeFileSync(absGitPath(root, CONFLICT_STATE_NAME), JSON.stringify({ branch, at: new Date().toISOString(), local: d.local, remote: d.remote, paths: d.paths ?? [] }));
+ } catch { /* best-effort */ }
}
+// ── Public entry points ─────────────────────────────────────────────────────
-/** Named paths that are files on disk yet absent from the index (`listed`: `ls-files -v` after `git add -A`), as a file inside a nested repository is. */
-function unindexedFiles(root: string, rel: string[], listed: string[]): string[] {
- const indexed = new Set(listed.map(line => line.slice(2)));
- return rel.filter(path => {
- if (indexed.has(path)) return false;
- try { return !lstatSync(join(root, path)).isDirectory(); } catch { return false; }
- });
+function defaultPublishWaitMs(): number {
+ const raw = process.env.GBRAIN_PUBLISH_LOCK_WAIT_SECONDS ?? process.env.GBRAIN_PUSH_LOCK_WAIT_SECONDS;
+ const secs = raw === undefined ? 300 : Number(raw);
+ return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : 300_000;
}
/**
- * GST-2116: a run that left a named path uncommitted fails, after committing (and, on a classic checkout, pushing) the
- * rest, so a write is never reported as saved when it is not. In a managed canonical worktree a skipped page is the
- * owner's to save (`writer_coordinator_required`); anything else is `commit_paths_skipped`.
+ * Q1: on a managed canonical worktree commit-push commits only the paths the caller names (pages written outside gbrain,
+ * which would otherwise land as bare commits), under the commit lock, and nothing more: no fetch, merge, push or checkout
+ * move, so the owner stays the only publisher. The commit reaches the remote on the owner's next Git publish, or with
+ * `gbrain git commit-push --push-only --keep-checkout`.
*/
-function skippedPathsError(root: string, skipped: SkippedPath[], result: CommitPushResult, managed?: ManagedFilesystemRoot, publish?: unknown): OperationError {
- const list = `${skipped.slice(0, 20).map(s => `${s.path} (${s.reason})`).join(', ')}${skipped.length > 20 ? ', ...' : ''}`;
- const pushed = !!result.committed && (result.outcome === 'pushed' || result.outcome === 'pushed_checkout_lagging');
- const done = result.committed
- ? `The other named paths were committed as ${result.committed.slice(0, 7)}${pushed ? ` and pushed to ${result.remote}/${result.branch}` : ', not pushed'}.`
- : 'Nothing was committed.';
- const failed = publish as { code?: string; message?: string; detail?: string } | undefined;
- const rest = `${done}${failed ? ` The push failed too (${failed.code ?? 'error'}): ${failed.message ?? String(publish)}` : ''}`;
- const detail = JSON.stringify({ skipped, committed: result.committed, ...(pushed ? { pushed: result.sha } : {}), branch: result.branch,
- ...(failed ? { publish: { code: failed.code ?? null, detail: failed.detail ?? null } } : {}) });
- const docs = 'docs/guides/shared-checkout-git.md#outcomes';
- const flagged = skipped.filter(s => s.reason !== 'not_staged');
- // One update-index call per flag: given both, git clears only the first.
- const clears = (['assume_unchanged', 'skip_worktree'] as const)
- .map(reason => ({ flag: reason === 'skip_worktree' ? '--no-skip-worktree' : '--no-assume-unchanged', paths: flagged.filter(s => s.reason === reason).map(s => s.path) }))
- .filter(c => c.paths.length)
- .map(c => ['git', '-C', root, 'update-index', c.flag, '--', ...c.paths]);
- const clearCommand = clears.map(argv => shellQuote(argv)).join(' && ');
- const flagNote = 'an assume-unchanged or skip-worktree flag; an editor, an indexer or a sparse checkout can leave one, and people also set skip-worktree on purpose to keep local edits out of commits, so clearing it commits those edits';
- const chain = (steps: string[][], last?: Action): Action | undefined => steps.reduceRight<Action | undefined>((then, argv) =>
- ({ argv, consent: [], actor: 'agent', requires_exclusive: false, why: 'Clears the flag so git sees the edit on disk; the file keeps its bytes.', ...(then ? { then } : {}) }), last);
- const pages = managed ? skipped.filter(s => isSyncable(s.path)) : [];
- if (managed && pages.length) {
- const source = managed.sourceId ? { argv: ['--source-id', managed.sourceId], mcp: { source_id: managed.sourceId } } : { argv: [], mcp: {} };
- const put: Action = { argv: ['gbrain', 'put', ...source.argv, '<slug>'],
- mcp: { tool: 'put_page', arguments: { slug: '<slug>', ...source.mcp, content: '<the page file>' } },
- inputs: [{ name: 'slug', how: `Each listed page path without its .md extension; pass the file's content on stdin: ${pages.slice(0, 5).map(s => s.path).join(', ')}` }],
- consent: [], actor: 'agent', requires_exclusive: false,
- why: 'put_page saves the page through the owner, which writes the file, commits only that path and pushes it.',
- verify: { argv: ['gbrain', 'sources', 'writer', 'status', managed.sourceId ?? '<source>', '--json'] } };
- return opError('writer_coordinator_required',
- `${root} is the managed canonical worktree${managed.sourceId ? ` of source ${managed.sourceId}` : ''}, and git did not commit ${skipped.length} named path(s): ${list}. ${rest}`,
- `${clears.length ? `First, with the user's agreement, clear the flags (${clearCommand}), since the owner's own Git step cannot see a flagged edit either. ` : ''}Then save those pages through gbrain (put_page, edit_page or capture; on the CLI, gbrain put${managed.sourceId ? ` --source-id ${managed.sourceId}` : ''} with the page slug and the page on stdin): the persistence owner commits and pushes them. Never commit page files around it.`,
- { docs, detail,
- why: 'The persistence owner is the only Git writer of pages in a managed worktree; a page file written there directly and left uncommitted is neither in Git nor in the database, so reporting success would lose the write silently.',
- fix: { ...(chain(clears, put) ?? put), ask_user: true,
- user_message: `These page files were written straight into the managed checkout and git did not commit them: ${pages.slice(0, 10).map(s => s.path).join(', ')}.${clears.length ? ` Git hides their edits (${flagNote}); clear the flags first.` : ''} Save each one through gbrain (put_page), which replaces the stored page with the file's content?` } });
+function commitManagedPaths(root: string, opts: CommitPushOptions, managed: ManagedFilesystemRoot): CommitPushResult {
+ const where = `${root} is the managed canonical worktree${managed.sourceId ? ` of source ${managed.sourceId}` : ''}`;
+ if (opts.pending || opts.branch || opts.resolutions || opts.expectRemote || opts.allowOutsideSourceRoot || opts.advanceOnlyWhenClean) {
+ throw opError('commit_paths_invalid', `${where}: commit-push there only commits the paths you name.`,
+ `Run gbrain git commit-push with only -m and the page paths after --; gbrain sources refresh${managed.sourceId ? ` ${managed.sourceId}` : ''} brings remote commits in.`);
+ }
+ const { result: committed, skipped } = commitPathsOnly(root, opts, where, configuredSourceRoots(root), 'Leave the checkout to its owner; gbrain sources writer status names its state.');
+ const counted = git(root, ['rev-list', '--count', '@{upstream}..HEAD']);
+ const upstream = git(root, ['for-each-ref', '--format=%(upstream:short)', `refs/heads/${committed.branch}`]).stdout.trim();
+ const result: CommitPushResult = { ...committed, managed: true, unpublished: counted.code === 0 ? Number(counted.stdout.trim()) : null, upstream: upstream || null };
+ if (skipped.length) throw skippedPathsError(root, skipped, result, managed);
+ return result;
+}
+
+/** A checkout with no Git remote at all: no remote is configured and the branch names none (a named but missing remote is refused by resolveCtx). A git command that fails is not proof of "no remote". */
+function hasNoRemote(root: string): boolean {
+ const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+ if (branch.code !== 0 || git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']).code !== 0) return false;
+ const remotes = git(root, ['remote']);
+ if (remotes.code !== 0 || remotes.stdout.trim()) return false;
+ return git(root, ['config', '--get', `branch.${branch.stdout.trim()}.remote`]).code === 1;
+}
+
+/** GBRA-133: with no remote there is nothing to publish to, so commit-push only commits the named paths, like a managed worktree. */
+function commitRemotelessPaths(root: string, opts: CommitPushOptions): CommitPushResult {
+ const where = `${root} has no Git remote, so there is nothing to publish to`;
+ if (opts.pushOnly || opts.pending || opts.branch || opts.resolutions || opts.expectRemote || opts.advanceOnlyWhenClean) {
+ throw opError('commit_paths_invalid', `${where}; commit-push there only commits the paths you name.`,
+ 'Run gbrain git commit-push -m <msg> -- <paths> to commit them locally, or add a remote (git remote add origin <url>) and set the branch upstream to publish.');
+ }
+ const { result: committed, skipped } = commitPathsOnly(root, opts, where, opts.allowOutsideSourceRoot ? [''] : configuredSourceRoots(root), 'Check out a branch (git switch <branch>), then rerun.');
+ const result: CommitPushResult = { ...committed, no_remote: true };
+ if (skipped.length) throw skippedPathsError(root, skipped, result);
+ return result;
+}
+
+/** Commit only the named paths under the commit lock and nothing more: no fetch, merge, push or checkout move. */
+function commitPathsOnly(root: string, opts: CommitPushOptions, where: string, roots: string[], detachedFix: string): { result: CommitPushResult; skipped: SkippedPath[] } {
+ if (!opts.message?.trim()) throw opError('commit_paths_invalid', 'A commit message is required.', 'Pass the commit message with -m.');
+ const rel = scopePaths(root, opts.paths ?? [], opts.cwd ?? process.cwd());
+ if (!rel.length) throw opError('commit_paths_invalid', `${where}: name the paths to commit.`, 'Pass -- <paths> after the message.');
+ const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).stdout.trim();
+ if (!branch) throw opError('git_detached_head', `${root} is on a detached HEAD, so there is no branch to commit to.`, detachedFix);
+ assertNoOperationInProgress(root);
+ const lock = acquireCommitLock(root, opts.lockWaitMs);
+ let commit: ReturnType<typeof commitPaths>;
+ try {
+ assertNoOperationInProgress(root);
+ commit = commitPaths(root, rel, opts.message.trim(), { roots, lockPath: lock.lockPath, markHeld: true, bases: scopeBases(root, opts, rel) });
+ } finally {
+ lock.release();
+ }
+ const committed = commit.sha;
+ const remote = git(root, ['config', '--get', `branch.${branch}.remote`]).stdout.trim();
+ return { result: { outcome: committed ? 'committed_local' : 'nothing_to_commit', sha: committed, committed, branch, remote, paths: rel, integrated: 0, checkout: 'unchanged' }, skipped: commit.skipped };
+}
+
+export function commitAndPush(opts: CommitPushOptions): CommitPushResult {
+ const root = checkoutRoot(opts.repo);
+ if (opts.keepCheckout && !opts.pushOnly) throw opError('commit_paths_invalid', 'keepCheckout publishes commits already on the branch; it commits nothing.', 'Use --push-only --keep-checkout.');
+ const managed = opts.keepCheckout || opts.pushOnly ? null : managedFilesystemRootFor(root);
+ if (managed && !hasFilesystemPublication(root)) return commitManagedPaths(root, opts, managed);
+ if (!opts.keepCheckout) assertManagedFilesystemWrite(root);
+ if (hasNoRemote(root)) return commitRemotelessPaths(root, opts);
+ const cwd = opts.cwd ?? process.cwd();
+ const roots = configuredSourceRoots(root);
+ const rel = opts.pushOnly ? [] : opts.pending
+ ? [...dirtyPaths(root, readPendingWriteThrough(root).map(e => e.path).filter(p => insideSourceRoots(p, roots)))]
+ : scopePaths(root, opts.paths ?? [], cwd);
+ if (!opts.pushOnly && !opts.message?.trim()) {
+ throw opError('commit_paths_invalid', 'A commit message is required.', 'Pass -m "<message>".');
+ }
+ const upstream = resolveCtx(root);
+ const ctx = { ...withBranch(upstream, opts.branch), ...(opts.keepCheckout ? { keepCheckout: true } : {}) };
+ const elsewhere = ctx.mergeRef !== upstream.mergeRef;
+ assertNoOperationInProgress(root);
+
+ let committed: string | null = null;
+ let skipped: SkippedPath[] = [];
+ if (!opts.pushOnly) {
+ const lock = acquireCommitLock(root, opts.lockWaitMs);
+ try {
+ assertNoOperationInProgress(root);
+ if (rel.length) ({ sha: committed, skipped } = commitPaths(root, rel, opts.message!.trim(), { roots: opts.allowOutsideSourceRoot ? [''] : roots, lockPath: lock.lockPath, markHeld: true, bases: scopeBases(root, opts, rel) }));
+ settlePending(root);
+ } finally {
+ lock.release();
+ }
}
- return opError('commit_paths_skipped', `git did not commit ${skipped.length} named path(s) in ${root}: ${list}. ${rest}`,
- flagged.length
- ? `Git hides edits to the assume_unchanged and skip_worktree paths from commits. With the user's agreement clear the flags (${clearCommand}), then rerun the same commit-push.`
- : 'Git did not stage the not_staged paths (a file inside a nested Git repository is the usual cause). Move them into the brain checkout proper, or commit them in their own repository, then rerun.',
- { docs, detail,
- why: 'git add stages nothing and still exits 0 for a modified file flagged assume-unchanged or skip-worktree, or a file inside a nested repository; reporting success would leave the write uncommitted with nothing in any log.',
- fix: flagged.length
- ? { ...chain(clears)!, ask_user: true,
- user_message: `Git is set to ignore edits to ${flagged.slice(0, 10).map(s => s.path).join(', ')} (${flagNote}), so they were not committed. Clear those flags and commit the edits?`,
- verify: { argv: ['git', '-C', root, 'ls-files', '-v', '--', ...flagged.map(s => s.path)] } }
- : { consent: [], actor: 'user', requires_exclusive: false,
- why: 'Git cannot commit a file that belongs to another repository, so only moving it or committing it there settles it.',
- user_message: `Git did not commit ${skipped.slice(0, 10).map(s => s.path).join(', ')} in ${root} (a file inside a nested Git repository is the usual cause). Where should they be committed?` } });
-}
-/** `--base` keyed by the repository-relative path it names; each must also be a committed path. */
-function scopeBases(root: string, opts: CommitPushOptions, rel: string[]): Map<string, string> | undefined {
- if (!opts.bases?.size) return undefined;
- const scoped = new Map<string, string>();
- for (const [path, blob] of opts.bases) {
- const [key] = scopePaths(root, [path], opts.cwd ?? process.cwd());
- if (!key || !rel.includes(key)) throw opError('commit_paths_invalid', `--base names ${path}, which is not one of the paths to commit.`, 'Name every --base path after -- as well.');
- scoped.set(key, blob);
+ const unattended = !!opts.advanceOnlyWhenClean;
+ const publishLockPath = absGitPath(root, PUBLISH_LOCK_NAME);
+ const requestPath = absGitPath(root, PUBLISH_REQUEST_NAME);
+ const waitMs = unattended ? 0 : opts.publishWaitMs ?? defaultPublishWaitMs();
+ let pub = acquireNativeLockSync(publishLockPath, { timeoutMs: waitMs });
+ if (!pub) {
+ writeFileSync(requestPath, `${process.pid}\n`);
+ pub = acquireNativeLockSync(publishLockPath, { timeoutMs: 0 });
}
- return scoped;
+ const unpublished: CommitPushResult = { outcome: 'committed_local', sha: null, committed, branch: ctx.branch, remote: ctx.remote, paths: rel, integrated: 0, checkout: 'unchanged' };
+ if (!pub) {
+ if (unattended) {
+ const deferred: CommitPushResult = { ...unpublished, outcome: 'push_deferred' };
+ if (skipped.length) throw skippedPathsError(root, skipped, deferred);
+ return deferred;
+ }
+ const busy = opError('push_unconfirmed', `${committed ? 'The commit is durable locally, but another' : 'Another'} publish held this checkout's push lock for ${Math.round(waitMs / 1000)}s.`,
+ `The running publish was asked to push HEAD too once it finishes. Rerun gbrain git commit-push --push-only to confirm; never git pull --rebase in this checkout.`,
+ { detail: committed ?? '', retryable: true });
+ if (skipped.length) throw skippedPathsError(root, skipped, unpublished, undefined, busy);
+ throw busy;
+ }
+
+ const cycle = (onlyWhenClean: boolean, start: string | null, resolutions?: Map<string, Resolution>, expectRemote?: string) => {
+ const requested = existsSync(requestPath);
+ rmSync(requestPath, { force: true });
+ try {
+ const head = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
+ const target = start && !isAncestor(root, start, head) ? start : head;
+ if (!opts.allowOutsideSourceRoot) assertLocalCommitsInsideRoots(ctx, target, roots);
+ if (opts.scanSecrets) assertNoSecretsInRange(ctx, target);
+ const published = publish(ctx, target, resolutions, expectRemote, cwd);
+ if (!elsewhere) rmSync(absGitPath(root, CONFLICT_STATE_NAME), { force: true });
+ const moved = published.sha === head || elsewhere || opts.keepCheckout ? { checkout: 'unchanged' as const } : advanceWithLock(root, published.sha, head, onlyWhenClean, opts.lockWaitMs);
+ return { published, moved };
+ } catch (e) {
+ if ((e as { code?: string }).code === 'integrate_conflict' && !elsewhere) recordConflict(root, ctx.branch, e);
+ if (requested) writeFileSync(requestPath, `${process.pid}\n`);
+ throw e;
+ }
+ };
+
+ let first: ReturnType<typeof cycle>;
+ try {
+ first = cycle(unattended, committed, opts.resolutions, opts.expectRemote);
+ } catch (e) {
+ if (skipped.length) throw skippedPathsError(root, skipped, unpublished, undefined, e);
+ throw e;
+ } finally {
+ pub.release();
+ }
+ // Publishers that found the push lock busy left a request; honor it after releasing (no commit is stranded).
+ for (let i = 0; i < 16 && existsSync(requestPath); i++) {
+ const again = acquireNativeLockSync(publishLockPath, { timeoutMs: 0 });
+ if (!again) break;
+ try { cycle(true, null); } catch { break; } finally { again.release(); }
+ }
+
+ const { published, moved } = first;
+ const result: CommitPushResult = {
+ outcome: moved.checkout === 'lagging' ? 'pushed_checkout_lagging' : committed || opts.pushOnly ? 'pushed' : 'nothing_to_commit',
+ sha: published.sha, committed, branch: ctx.branch, remote: ctx.remote, paths: rel,
+ integrated: published.integrated, confirmed: published.confirmed, checkout: moved.checkout, ...(moved.reason ? { lagging_reason: moved.reason } : {}),
+ ...(published.quarantined ? { quarantined: published.quarantined } : {}),
+ ...(published.superseded ? { superseded_remote_paths: published.superseded } : {}),
+ };
+ if (skipped.length) throw skippedPathsError(root, skipped, result);
+ return result;
}
/**
- * Stage and commit exactly `rel` (the caller holds the commit lock). Refused
- * before anything is staged: a path outside the source root(s), and a file
- * another writer already staged under a named directory (name it to claim
- * it). A commit git refuses leaves the index as it found it. `skipped` lists
- * the named paths git left out (GST-2116); the rest are still committed.
+ * Bring remote commits into the shared checkout without rebasing it: fetch
+ * outside the lock, then (under the commit lock) fast-forward, or merge
+ * diverged history in memory and fast-forward to the merge. Never pushes.
+ * `requireClean` keeps the unattended cron's conservative "any local edit →
+ * skip" rule.
*/
-function commitPaths(root: string, rel: string[], message: string, scope: CommitScope): { sha: string | null; skipped: SkippedPath[] } {
- const outside = rel.filter(p => !insideSourceRoots(p, scope.roots));
- if (outside.length) throw outsideRootError(root, scope.roots, outside, 'Refusing to commit');
- for (const [path, base] of scope.bases ?? []) {
- const head = git(root, ['rev-parse', '--verify', '-q', `HEAD:${path}`]).stdout.trim() || 'absent';
- if (head !== base) throw opError('commit_base_moved', `${path} changed at HEAD since the writer read it (base ${base}, HEAD ${head}).`,
- `Nothing was staged or committed. Read ${path} at HEAD again (git -C ${root} show HEAD:${path}), redo the change on it, and rerun with --base ${path}=${head}.`,
- { detail: JSON.stringify({ path, base, head }), docs: 'docs/guides/shared-checkout-git.md#base-check' });
+export function pullShared(repo: string, opts: { requireClean?: boolean; lockWaitMs?: number; fetchTimeoutMs?: number; remoteBranch?: string } = {}): PullResult {
+ const root = checkoutRoot(repo);
+ assertManagedFilesystemWrite(root);
+ const ctx = withBranch(resolveCtx(root), opts.remoteBranch);
+ if (opts.requireClean && git(root, ['status', '--porcelain']).stdout.trim()) return { status: 'skipped_dirty' };
+ assertNoOperationInProgress(root);
+ const fetched = remoteGit(root, 'fetch', [...fetchFlags(root), '--', ctx.remote, `+${ctx.mergeRef}:${ctx.trackingRef}`], opts.fetchTimeoutMs ?? 300_000);
+ if (fetched.code !== 0) {
+ throw opError('git_unavailable', `git fetch from ${ctx.remote} failed in ${root}.`, fetched.stderr.trim().slice(0, 300) || 'Check the remote and its credentials.');
}
- const swept = stagedPaths(root).filter(p => !rel.includes(p) && rel.some(spec => covers(spec, p)));
- if (swept.length) {
- const list = `${swept.slice(0, 10).join(', ')}${swept.length > 10 ? ', ...' : ''}`;
- throw opError('commit_prestaged_paths', `${swept.length} file(s) under the named path(s) were already staged by another writer: ${list}.`,
\ No newline at end of file
+ const remoteTip = gitOk(root, ['rev-parse', ctx.trackingRef], 'rev-parse tracking ref');
+ const lock = acquireCommitLock(root, opts.lockWaitMs);
+ try {
+ assertNoOperationInProgress(root);
+ if (opts.requireClean && git(root, ['status', '--porcelain']).stdout.trim()) return { status: 'skipped_dirty' };
+ const head = gitOk(root, ['rev-parse', 'HEAD'], 'rev-parse HEAD');
+ if (head === remoteTip || isAncestor(root, remoteTip, head)) return { status: head === remoteTip ? 'up_to_date' : 'ahead' };
+ let target = remoteTip;
+ let merged = false;
+ if (!isAncestor(root, head, remoteTip)) {
+ const tree = integrate(root, head, remoteTip);
+ if (tree.conflicts.length) throw conflictError(ctx, head, remoteTip, tree);
+ target = buildMerge(ctx, head, remoteTip, tree.tree!, tree.skipped);
+ merged = true;
+ }
+ const moved = advanceLocked(root, target, head);
+ if (moved.checkout === 'lagging') return { status: 'lagging', from: head, reason: moved.reason };
+ return { status: 'advanced', from: head, to: target, merged };
+ } finally {
+ lock.release();
+ }
+}
diff --git a/test/commit-push-ignored-deletion-7984.test.ts b/test/commit-push-ignored-deletion-7984.test.ts
index 6f53244a69..601e3e8d5e 100644
--- a/test/commit-push-ignored-deletion-7984.test.ts
+++ b/test/commit-push-ignored-deletion-7984.test.ts
@@ -70,4 +70,14 @@ describe('commit-push: tracked deletions under a wildcard ignore (#7984)', () =>
}
expect(remoteFiles(bare)).toEqual(['.gitignore', 'artifact/a.bin', 'artifact/b.bin', 'artifact/c.bin']);
});
+
+ test('a named skip-worktree file beside a tracked deletion: the deletion publishes and the flagged file is reported skipped (GST-2118)', async () => {
+ const { bare, repo } = ignoredCheckout();
+ rmSync(join(repo, 'artifact', 'a.bin'));
+ git(repo, 'update-index', '--skip-worktree', '--', 'artifact/b.bin');
+ writeFileSync(join(repo, 'artifact', 'b.bin'), 'edited\n');
+ await expect(publish(repo, ['artifact/a.bin', 'artifact/b.bin'])).rejects.toMatchObject({ code: 'commit_paths_skipped' });
+ expect(remoteFiles(bare)).toEqual(['.gitignore', 'artifact/b.bin', 'artifact/c.bin']);
+ expect(git(bare, 'show', 'main:artifact/b.bin')).toBe('b.bin');
+ });
});