* fix(dolt): honor dolt.auto-commit=batch/off on the proxied-server write path (#4995)
In proxied-server mode every write minted a Dolt history commit whatever
dolt.auto-commit said. Two causes:
- cmd/bd/main.go never applied issueOpsContext(rootCtx) in the
proxiedServerMode branch of the root pre-run, so the context carried no
deferred-commit marker.
- internal/storage/uow/doltserver_tx.go: doltServerTx.Commit ignored
issueops.VersionCommitDeferred(ctx) and ran CALL DOLT_COMMIT('-Am', ?)
whenever a message was supplied.
Apply issueOpsContext to rootCtx in the proxied setup, and have
doltServerTx.Commit blank its message under a deferred context so the existing
plain-COMMIT branch persists the write to the working set without advancing
Dolt history. dolt.auto-commit=on is unchanged.
This commit alone strands batch/off writes in the working set; the explicit
flush point (`bd dolt commit`) follows in the later commits of this series.
(Originally recorded as "witness: salvage uncommitted work (ocb-ani)"; the
change itself is unmodified.)
* test(uow,cmd/bd): add regression tests for proxied dolt.auto-commit batch/off (#4995)
Add focused regression tests verifying that proxied dolt.auto-commit batch/off
defer Dolt version commits:
- cmd/bd: TestIssueOpsContextDefersByModeInProxiedServerMode verifies that
issueOpsContext defers version commits in proxied-server mode when
dolt.auto-commit is batch or off.
- internal/storage/uow: TestDoltServerTxCommitDefersDoltCommitUnderDeferredContext
and TestDoltServerTxRunTxWithDeferredContextSkipsDoltCommit verify that
doltServerTx.Commit blanks the commit message under a deferred context,
bypassing DOLT_COMMIT and status checks, and executing plain COMMIT to
persist writes into the working set without advancing Dolt history.
* fix(dolt): add the proxied flush point dolt.auto-commit=batch/off defers to (#4995)
The deferral half of this PR makes dolt.auto-commit=batch/off actually take
effect on the proxied-server write path. On its own that turns batch/off into
"never commit": proxied mode returns from the root pre-run before newDoltStore
runs, so getStore() is nil and `bd dolt commit` has no store to commit
through. Writes pile up in the sql-server working set where `dolt log`,
`dolt push` and backups never see them.
Add the missing half. cmd/bd/dolt_commit_proxied_server.go is the proxied dual
of `bd dolt commit`: it takes the uow.MaintenanceProvider route (RunNonTx) and
runs CALL DOLT_COMMIT('-Am', ?) on a pinned connection, gated on
issueops.HasPendingChanges. It deliberately does not go through
doltServerTx.Commit, which blanks its own message under the deferred context;
routing the flush through the deferral it exists to discharge would make the
flush a no-op. doltCommitCmd dispatches to it on usesProxiedServer(); the
message is built before the branch so both routes name the same default, and
the "Committed." / "Nothing to commit." contract is unchanged.
--dolt-auto-commit's help no longer claims proxied-server routes are
unaffected: it names the proxied flush point and keeps the SIGTERM/SIGHUP
flush marked embedded-only. docs/reference/configuration.md says the same.
`bd vc commit`'s proxied refusal now points at `bd dolt commit`.
Tests:
- cmd/bd/dolt_commit_proxied_integration_test.go: three batch writes leave
dolt_log unchanged and stay readable, `bd dolt commit` advances it by
exactly one, a second `bd dolt commit` reports "Nothing to commit." with
dolt_log unchanged, and one write under --dolt-auto-commit on advances it
by one. On the PR's original base it failed at the `bd dolt commit` step
with "no store available". On current main the front door refuses the
command before that code is reached, so this test is only green together
with the next commit, which moves `dolt commit` to supported in the proxy
capability registry.
- TestIssueOpsContextDefersByModeInProxiedServerMode renamed to
TestIssueOpsContextDefersByModePolicyTable and the proxiedServerMode
assignment dropped: issueOpsContext branches only on writesCommitNow(),
never on the storage mode, so the old name over-promised.
- doltserver_tx_test.go: "bd: update bd-4995" -> "bd: update GH#4995", which
no longer reads as a bead id.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(proxy): move `dolt commit` from refused to supported in the capability registry
Main's proxy capability registry (added by #6269, 24a9da6cc) declares
`dolt commit` direct-only: it has a "proxy.dolt_commit.unsupported" refusal
in proxyMaintenanceRefusals (cmd/bd/proxy_capability.go) and is classed
HistoryDirectOnly in historyCapabilityMatrix (cmd/bd/history_capability.go).
The front door therefore refuses `bd dolt commit` in proxied-server mode
before dispatch, so the proxied dual added earlier in this series is
unreachable, and dolt.auto-commit=batch/off has no way to flush.
the history/VC front-door contract, and neither the registry, its tests nor
the docs explain why `dolt commit` was listed. Nothing on main implemented
`dolt commit` for the proxied route at the time, which is consistent with the
entry being a statement of what existed rather than a design decision.
This flips a capability main had declared unsupported, deliberately: the
proxied route now has an implementation (runDoltCommitProxiedServer), and
batch/off need it as their flush point (GH#4995).
Declared the same way as the other proxied-supported command,
`dolt remote remove`: HistoryProxySupported in the history matrix, and no row
in proxyMaintenanceRefusals.
Tests follow: history_capability_test.go moves `dolt commit` from the
direct-only assertions and refusal contract to the proxy-supported ones
(including the nested front-door pass-through), and
history_remote_frontdoor_matrix_test.go drops the refusal row and adds a
`dolt commit` pass-through check to TestHistoryRemoteSupportedFrontDoorParity.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(proxy): exempt explicit commit points from the proxied deferral (#4995)
Maintainer review fixup for PR #6499, adopt-pr iterations 1-2.
Major (Contract & Interface Fidelity). The deferral is applied once, to
rootCtx, so it blanketed BOTH commit classes the direct route distinguishes by
which wrapper a verb picks: policy-honoring writes (transactHonoringAutoCommit,
per-verb issueOpsContext) and explicit commit points (transact, which passes
the caller's message whatever the policy says). Under dolt.auto-commit=batch a
proxied `bd batch -m "release batch"` therefore persisted the rows, discarded
the message and minted nothing, while the identical command and config on the
direct route committed it — and batch_proxied_server.go's own contract comment
rejects exactly that ("would persist these writes while silently bypassing
Dolt history"), as does batch.go's "the contract is the same on both backends".
issueops.WithImmediateVersionCommit clears the marker and cmd/bd's
explicitCommitPointContext applies it in the duals whose direct twin calls
transact. Scope is the intersection of the transact call sites with
proxyPermittedPaths: batch, mol bond/pour/squash, mol wisp create, and the
WISP half of mol burn (cook and migrate issues also call transact but are
refused in proxied mode, so they have no dual to exempt). The review sized the
radius at batch + 4 mol verbs; mol wisp create is the same class — its direct
twin reaches cloneSubgraph's transact through spawnMoleculeWithOptions — so it
is exempted with them.
Membership is per commit site, not per command (iteration 2). `bd mol burn` is
two classes on the direct route: wisps go through burnWisps -> transact, while
persistent molecules go through deleteBatch -> issueOpsContext ->
dolt/deleter.go, which returns before DOLT_COMMIT when the context defers.
Exempting the whole command minted one Dolt commit per persistent molecule
under batch/off — on a destructive verb, where the identical direct-route
command defers them all to `bd dolt commit`. runMolBurnProxiedServer now
applies the exemption to the wisp RunTxResult only, and the flag help,
configuration.md and the helper's own radius comment say so.
Minors:
- The flush passes '--author' like DoltStorage.CommitAll, so the one commit
batch mode keeps is attributed to the bd actor rather than the SQL session
user (without it dolt_log reads `root <root@localhost>`).
- runDoltCommitProxiedServer calls the shared runProxiedNonTx instead of
re-implementing its provider checks, so `bd --json dolt commit` keeps the
JSON error envelope; `dolt commit`'s RunE no longer re-wraps an
already-reported failure, and runProxiedNonTx's message gains the provider
%T the open-coded version had.
- The flag help and configuration.md drop two false claims: that the deferral
covers "every write" in proxied mode (the bd serve plane over the same
provider never touches rootCtx, so daemon writes still commit per write) and
that the SIGTERM/SIGHUP flush is "embedded-only" (flushBatchCommitOnShutdown
gates on an open store, which direct SQL-server mode has; only proxied mode
lacks one). Both surfaces now name the explicit-commit-point exemption.
- Both user-facing enumerations of that exemption are now derived from the
explicitCommitPointContext call sites rather than restated (iteration 2):
they had omitted mol wisp create, listed mol burn wholesale, and implied a
message-less `bd batch` defers when batch.go synthesizes a default message
and the dual exempts unconditionally, so every proxied batch commits.
- doltserver_tx.go's ephemeral-form comment names its second entry point —
RunTx/RunTxResult under a deferred context — where its
ONLY-dolt_ignored-state rationale stops applying.
Not done: regenerating docs/CLI_REFERENCE.md. Its --dolt-auto-commit drift is
base-preexisting, and the generated CLI docs are built from the release tag
pinned in docs/cli-docs.pin, not from this source, so touching them converts
the drift gate's inherited-drift warn-pass into a failure.
Tests. The uow blanking table gains the immediate-commit arm (tagless, so it
runs in every lane); the proxied integration test gains an explicit-batch-commit
step with a deferred plain create as its control, plus the flush attribution
assertions. Mutation-proved: reverting explicitCommitPointContext to a no-op
reds the new step (dolt_log 80 -> 80, no commit minted), and dropping
'--author' reds the attribution assertion with committer=root.
Iteration 2 adds the WIRING pin those left open — the mechanism was covered,
but deleting `ctx = explicitCommitPointContext(ctx)` from a dual was green in
every lane, which is why the mol burn over-application above was invisible.
dolt_autocommit_exemption_wiring_test.go is tagless and needs no server: a
uow.UnitOfWorkProvider that records the context RunTxResult hands NewUOW and
then refuses observes exactly the context each dual gives its transaction.
Mutation-proved per arm: neutering the exemption at batch/bond/squash reds
those three rows and only those; dropping it from the wisp RunTxResult reds
the wisp arm alone; and restoring the command-wide reassignment reds the
persistent arm alone, reproducing the defect this iteration fixes.
Validation: go build ./..., go vet (cgo and CGO_ENABLED=0), gofmt clean;
internal/storage/issueops; internal/storage/uow -run TestDoltServerTx; the
cmd/bd registry / history / policy / batch / mol / wisp / errors battery; and
the gated real-server lane BEADS_TEST_PROXIED_SERVER=1 green for both
TestProxiedServerBatchDefersThenDoltCommitAdvancesHeadOnce (41s) and
TestProxiedServerMolBurn (33s, all four subtests including the mixed
wisp+persistent burn this iteration changed).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
* test(proxy): harden history and remote front doors
* fix(proxy): preserve ready claim and compact refusal contracts
* fix(proxy): validate ready claim row caps preprovider
* fix(proxy): key capability front door on command paths
Review fixes for the proxied-server capability front door.
Blocking: validateProxyCapabilitiesBeforeProvider keyed on cobra's leaf
Name(), and `bd ready` and `bd mol ready --gated` share the leaf name
"ready". The max-rows refusal written for the former also refused the
latter for anyone with BEADS_MAX_ROWS exported — a proxy-supported
command that has no --max-rows flag to refuse. Every branch and both
policy tables now key on proxyCommandPath (the path below the root),
with an explicit "mol ready" row saying so. The compact refusal moves
from "compact" to "admin compact" for the same reason: root `bd compact`
is a different command with its own proxied route, and its message now
names `bd admin compact --dolt` rather than a `compact --dolt` that the
root command has no flag for.
Blocking: the allow path had no coverage, and it is the direction that
needs it — a refusal that stops firing degrades to the older late
failure, but one that fires too widely breaks a working command at the
front door where nothing catches it. Added a real-command-tree allow
table (a parentless cobra command has no path and matches no rule, which
is how a synthetic test tree reports success for a refusal that never
fired), a drift guard that every table key names a command that exists,
and an e2e allow matrix running the proxy-supported set against a live
managed-local proxied project, once clean and once under
BEADS_MAX_ROWS=5. `bd ready` under that cap is in the same table as the
control: it must still refuse.
Row cap resolved once on the proxied claim path, via resolveMaxRowsQuiet
rather than by hoisting the claim early-return above resolveMaxRows. The
duplicate line is the malformed-BEADS_MAX_ROWS advisory, which is a side
effect of resolving; the front door now resolves silently and the
command body stays the sole warner, so the message appears exactly where
it did before the front door existed. Hoisting would have moved the
`--max-rows -1` usage rejection back behind provider construction and
regressed TestReadyClaimValidatesMaxRowsBeforeProvider, which this PR
added.
Also folded in, all in-theme:
- ProxyOutcomeNA asserts clean (it states the command lacks the flag,
which is nothing to refuse), and a rule carrying neither code nor
message falls back to a generic one instead of rendering as a bare
"Error: " with exit 1.
- The list/--repo row said notApplicable(); list_proxied_server.go
refuses it. A policy table that contradicts the command is worse than
a missing row.
- preflight binds --json to &jsonOutput like every other command's local
--json. commandJSONFlagChanged suppresses the config-driven default
whenever a local --json is set, so an unbound flag left
`bd preflight --json` with jsonOutput=false.
- Deleted the proxied no-op in doctor.go. "doctor" is in the refusal
table now, so the front door returns exit 1 before RunE ever runs.
CHANGELOG records that flip (exit 0 with a stderr note becomes exit 1
with proxy.doctor.unsupported) and that --json refusals are strict
JSON on stdout.
- Deleted the dead tail block in validateProxyMaintenanceBeforeProvider:
it could only run for a space-free path, which the table lookup above
it had already handled.
- TestHistoryDirectOnlyRefusalContract iterates its own expectation
table, so all 13 declared rows are asserted rather than 11.
- HandleProxyCapabilityError(nil) returns nil. Every AssertProxy* allow
path returns nil and this wraps that return value directly, so the
natural way to add the next rule -- a bare
`return HandleProxyCapabilityError(AssertProxy...(...))` with no
preceding `if` -- would have rendered an allowed capability as
"Error: <nil>" with exit 1. Latent today: all five nil-capable call
sites are guarded by conditions whose rules resolve to refused().
- The third front-door branch, the skipsStoreInit route into
validateProxyMaintenanceBeforeProvider, keys on proxyCommandPath like
the other two, and "doctor" joins the path list in
TestProxyFrontDoorBranchesUseRealCommandPaths so the drift guard
covers all three. It returns unconditionally, so a future
`bd <parent> doctor` matching on the leaf name would have taken nil
back from the now path-keyed validator and returned early past
guardLegacyNoStoreCommand and getDoltAutoCommitMode.
* test: make direct and proxied history ordering fixtures deterministic
Assign distinct fixture timestamps and assert the expected newest-first sequence so same-second writes cannot make SQL/proxy parity flaky.
Agent: Codex (unknown model, unknown reasoning)
* test(proxy): expect scoped admin compact refusal
Agent: Codex (unknown model, unknown reasoning)
* fix(proxy): restore typed refusals and settle the ready --claim contract
Maintainer review fixes for #6293.
Major: `bd list --repo` under --proxied-server was the one live refusal this
PR converted from a typed ProxyCapabilityError to a bare errors.New. The
pre-provider gate covers `create` only, so runListProxiedServer is list's sole
enforcement point: --json got prose on stderr instead of
{"code":"proxy.repo.unsupported",...,"mutates":false} on stdout, while the PR
simultaneously added a "list"/ProxyCapRepo policy row that no non-test call
site could reach. The call site is typed again and keyed on the command path,
which makes that row the single source of the message. list.go's wrapper now
passes an already-rendered exitError through instead of re-wrapping it, so the
typed refusal no longer picks up a trailing "Error: exit code 1".
Major: the front door's new --claim early return contradicted ready.go, which
is untouched and still refuses any positive cap "including on --claim" -- so
the bypass never let a claim through. It only moved the refusal after provider
setup and, with max_rows.go downgraded to HandleErrorRespectJSON, stripped the
stable code: `bd ready --max-rows 5 --json` answered proxy.max_rows.unsupported
while `bd ready --claim --max-rows 5 --json` answered a bare {"error":...}. One
refusal, two shapes, selected by an unrelated flag. Settled toward the
documented contract, and toward the pre-existing
TestReadyRefusesMaxRowsUnderProxiedServerOnClaim which already pinned it:
--claim is not exempt. The early return is gone and
rejectResolvedMaxRowsUnderProxiedServer is typed again, so the front door and
its backstop in ready.go render identically. The claim path keeps what it
gained -- a malformed or negative value is still rejected before any provider
work, resolved quietly so the advisory still prints exactly once. The three
comments that disagreed about this contract now agree.
Also folded in, all in-theme:
- The create/show proxied fallbacks are typed again and marked as the dead
defensive paths they are. Same downgrade, shadowed by the gate rather than
live, so nothing failed when the contract left them.
- compact.go's dead fallback carries the gate's corrected wording
("bd admin compact --dolt"), and the table comment no longer asserts the
message did not change in the same hunk that changed it.
- The "mol ready" row's comment says what the row is -- a documentation pin.
Path keying is the guard it was crediting itself for.
- Tests: the strict-JSON shape (code/mutates/exit) of the list --repo refusal,
claim-and-bulk parity plus the backstop for the max-rows refusal, and
preflight's --json binding in both directions -- including the config half
end-to-end, since flag.Value.Set never sets Changed and the config default
only lands inside refreshBoundCommandConfig.
- CHANGELOG: #5859 sits in exactly one section again (it is not an ancestor of
v1.3.0), plus an [Unreleased] entry for this PR's own user-visible deltas,
including the bd preflight json-config change.
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* refactor(proxy): one capability registry, with a reason on every refusal
Proxied-server policy lived in three path tables (a maintenance refusal
map, a history classification map, a transform row list), each with its
own lookup and its own front-door validator, plus a flag matrix. Nothing
forced a new command to appear in any of them, so an unclassified
command sailed past the gate and died in the store factory with
`proxy server store should be uow provider`. That — not the table count
— was the root problem.
One table now (cmd/bd/capability_registry.go), and a test that fails
when a runnable command is missing from it. Adding a command is no
longer a place where policy can be forgotten: it is a build failure
until someone decides whether the proxied front door lets it through.
Every refusal carries a Reason: `design` where refusing is correct and
expected to stay (shared history, multi-repo routing, destructive admin,
storage-format surgery, strict --readonly), `unimplemented` where it is
a gap with a named owner. The reason renders in the refusal JSON,
additive to the frozen {code, error, mutates} contract, and is omitted
on refusals that report a runtime state rather than a policy so a
consumer keying on its presence is never told "" by mistake.
The registry also inventories the 57 untyped refusals commands raise
from their own RunE. Those rows are not enforced — converting them
changes observable output and belongs to the slice that owns each
family — but a source scan now keeps the inventory honest in both
directions.
The store-factory backstop is typed as `proxy.store.unrouted`, the
unreachable duplicate readonly refusal in main.go is gone (the proxied
branch above it already returns for the only config that reaches it),
and with it `backendSupportsStrictReadonly`, which had no other caller.
No outcome changes. Every code, message and exit status is identical,
which #6576's five-topology matrix proves: 90/90 cells unchanged
(HONORED 47, REFUSED_TYPED 24 = 4 design + 20 unimplemented, ERROR 12,
WRONG_ANSWER 4, DEGRADED 3), all five topologies exercised, no skips.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(proxy): `migrate hooks` is an unimplemented refusal, not a design one
The registry filed `migrate hooks` under "storage-format and workspace
surgery against a store other clients may be holding open". That rationale
does not describe it: migrate_hooks.go plans and applies GIT HOOK FILE
migration through doctor.PlanHookMigration, on the local filesystem, and
opens no store at all. Left as it was, proxied-local — the default topology
since 1.3.0 — loses the command permanently, because `design` tells every
later slice the refusal is semantic and settled.
It is not settled, but it is also not free to lift, and the difference is
structural rather than semantic. `migrate hooks` appears on none of main.go's
store-init skip lists, so permitting it makes the root pre-run open the
proxied provider before RunE runs. Measured with the row flipped to
permitted, not reasoned about: on a managed-local workspace
`bd migrate hooks --dry-run` started the proxy AND its dolt child — both
pidfiles present — to print a hook plan for five missing hooks, and on a
workspace with an unreadable sidecar it exited 1 with "failed to open uow
provider: corrupt proxied-server sidecar ..." where it had cleanly refused
before. Trading a typed refusal for a provider-open error is not a lift.
So: Reason=unimplemented with a Tracking item that names the actual work —
put the command on the store-init skip list first, then permit it — which is
S7's, not this slice's. No outcome changes; the row still refuses with the
same code, message and exit status. The registry header now says that
permitting a path costs a provider open, since that is the fact this row
turns on and the one the completeness test cannot see.
Also leaves S7 an explicit instruction on the rows next door. `migrate
issues`, `migrate-personal` and `admin cleanup`/`admin reset` claim `design`
on a topology-blind rationale — "a store other clients may be holding open",
"destructive against a possibly-shared store" — that describes external and
team-server workspaces and does not describe managed-local, which is 1:1 and
bd-owned. They are not reclassified here: the table cannot yet express
"refused, except on managed-local", and narrowing them is semantic work
nobody has done. The comments now say that is why, so the next reader does
not mistake conservatism for a considered verdict.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(ga-p9iuv.22): add shared tracker proxy storage seam
* fix(ga-p9iuv.22): preserve tracker storage capabilities safely
* test(ga-p9iuv.22): cover tracker adapter label semantics
* test(ga-p9iuv.22): harden tracker adapter contracts
* fix(ga-p9iuv.22): reject invalid proxied tracker stores
* feat(ga-p9iuv.1): route Linear and Jira front doors through proxy store
* test(ga-p9iuv.1): exercise tracker mutations through UOW store
* fix(ga-p9iuv.1): preserve proxied Linear endpoint config
* test(ga-p9iuv.1): cover proxied Linear endpoint and direct config
* feat(ga-p9iuv.19): add typed proxied capability matrix
* feat(proxy): enforce typed capability matrix before provider
* test(proxy): cover command capability rows and claim caps
* test(proxy): check capability rows across topologies
* fix(proxy): validate capabilities before workspace side effects
* fix(proxy): refuse ready claim max rows caps
* feat(proxy): add shared maintenance capability policy
* fix(proxy): key maintenance refusals by command path
* test(proxy): cover nested maintenance refusals
* fix(proxy): enumerate nested maintenance command paths
* fix(proxy): refine compact and nested maintenance policy
* test(proxy): prove maintenance refusals preserve files
* fix(proxy): cover admin and remote maintenance refusals
* fix(proxy): refuse doctor before store initialization
* test(proxy): define history capability command matrix
* fix(proxy): wire history capability refusals to front door
* fix(proxy): refuse top-level sync history path
* fix(proxy): preserve maintenance refusal codes
* feat(proxy): classify history as supported UOW API
* feat(proxy): classify transform capability paths
* test(proxy): harden transform capability matrix
* fix(proxy): drive transform validation from exact rows
* fix(proxy): drive transform matrix from normalized flags
* fix(proxy): bound external backend dials per attempt
* test(proxy): cover bounded blocked backend dial
* fix(proxy): make transform capability policy row-driven
* fix(proxy): make transform capability policy row-driven
* fix(proxy): classify formula swarm and merge-slot refusals
* test(proxy): enforce workflow refusal contract
* fix(proxy): classify Dolt remote history boundaries
* test(proxy): enforce history refusal contract
* test(proxy): cover canceled backend dial cleanup
* test(proxy): cover real TCP blackhole cancellation
* test(proxy): cover external transport lifecycle matrix
* test(proxy): assert stable dial failure diagnostics
* test(proxy): add outage reconnect acceptance matrix
* test(proxy): make unix outage bridge restartable
* test(proxy): bound outage subprocess cleanup
* test(proxy): cover upstream restart with retained endpoint bridge
* test(proxy): stabilize managed-local outage contract
* fix(proxy): retire managed proxy when backend exits
* test(proxy): accept managed child retirement restart
* test(proxy): cover workflow refusals at bd front door
* test(proxy): cover history VC front doors
* test(proxy): pass valid workflow refusal arguments
* test(proxy): assert text and json refusal contracts
* test(proxy): assert exact workflow refusal codes
* test(proxy): guard refusal issue-row stability
* fix(proxy): expose non-mutating capability refusals
* test(proxy): match stable refusal text
* test(proxy): compare refusal artifact snapshots
* test(proxy): assert exact refusal messages
* test(proxy): retain direct workflow behavior
* test(proxy): match nested refusal messages
* test(proxy): cover direct-only front-door refusals
* test(proxy): provide valid direct-only command args
* fix(migrate): repair missing proxied sidecar on reentry
* fix: checkpoint Dolt mode migrations for safe retry
* fix: harden migration journal topology and retries
* fix: fsync migration journal removal
* fix: fail on migration journal directory sync errors
* fix: reject external ownership in every migration phase
* fix: enforce canonical shared migration topology
* fix: enforce live migration topology
* test: add migration front-door and topology regressions
* fix: require physical Dolt roots for migration
* test: strengthen migration front-door contracts
* fix: reject missing or invalid Dolt migration roots
* fix: keep shared migration dry-runs side-effect free
* fix: require Dolt repository identity for migrations
* fix: validate Dolt repository identity metadata
* fix: require typed Dolt repo state identity
* test: expand migration front-door CRUD assertions
* test: make migration JSON dry-run front-door safe
* test: sanitize Dolt environment for migration front door
* test: use cgo binary for migration front door
* test: omit empty Dolt overrides in migration front door
* test: isolate migration front door from test mode
* test: isolate home for migration front door
* test: stop supervised Dolt before reverse migration
* fix: reject empty Dolt head refs
* test: harden migration topology invariants
* test: harden external and shared topology refusals
* test: snapshot migration refusal artifacts
* test: cover external migration refusal phases
* fix: refuse stale proxied sidecars during migration
* test: strengthen migration artifact and external front door checks
* feat: type external migration refusals
* test: assert external refusal starts no proxy
* fix: validate migration journal sidecar topology
* fix: make sidecar recovery phase aware
* fix: honor persisted shared topology during migration
* test: exercise external journal migration front door matrix
* test(tracker): add shared conformance harness
* test: harden external migration matrix fixtures
* test: preserve durable dolt gate lock in matrix
* test: preseed gate lock for refusal matrix
* test: cover malformed migration state front door
* fix: type malformed migration config refusals
* fix: type migration preflight state errors
* test: separate migration JSON stdout from warnings
* test: reach typed malformed journal refusal
* test: assert migration retry phase and idempotence
* test: cover shared migration checkpoint retries
* fix: make reverse migration idempotent without sidecar
* test: cover proxied to shared retries
* fix: derive shared topology from persisted YAML
* fix: validate shared migration no-op state
* fix: allow completed proxied shared no-op
* fix: validate forward proxied no-op sidecar
* test: reject bad already-proxied sidecars
* fix: reject stale proxy controls on no-op
* fix: fail closed on malformed migration workspace yaml
* test: pin migration yaml topology precedence
* Cover forward migration no-op ownership refusals (ga-p9iuv.26.5.2)
Agent-Signature: unknown-model/unknown-reasoning
* Strengthen migration retry sentinel coverage (ga-p9iuv.26.1)
Agent-Signature: unknown-model/unknown-reasoning
* Expand migration fault retry artifact coverage (ga-p9iuv.26.1)
Agent-Signature: unknown-model/unknown-reasoning
* Add reverse migration frontdoor fault matrix (ga-p9iuv.26.1.1)
Agent-Signature: unknown-model/unknown-reasoning
* test: cover shared migration frontdoor fault matrices
* test: strengthen direct migration matrix assertions
* test: preserve migration dependency edges
* test: assert exact migration dependency edges
* test: parse migration dependency edges from batch list
* test: fix shared migration matrix compile
* test: verify shared dependencies before shutdown
* test(proxy): cover history remote front-door topology matrix
* docs: define direct-local ownership handoff contract
* fix(ci): repair pre-review CI failures on proxy parity branch
Five PR-introduced failures across the docs, PR Core, and Proxied Dolt Cmd
lanes. Each fix is scoped to the evidenced defect.
- test/docsync: TestEveryDocsPageIsPublished flagged
docs/architecture/ownership-handoff-contract.md as unpublished. It is an
internal Beads/Gas City handoff contract with no Mintlify frontmatter and
no inbound links, so move it to engdocs/design/ beside its peers rather
than publishing it.
- cmd/bd: TestProxyWorkflowRefusalContractAndNoMutation asserted on
commandDidWrite, a process-wide atomic latch set by 71 non-test sites and
never reset, so it reported an earlier test's write. Baseline and restore
it around the assertion, matching the save/reset/restore idiom already
used in proxied_lookup_failure_test.go and readonly_policy_test.go.
- cmd/bd: the new pre-provider gate short-circuited compact.go's refusal
with new wording, breaking TestProxiedServerCompactDolt/non_dolt_mode_-
rejected in an unchanged test. Restore the long-standing message; the
proxy.compact.unsupported code is unchanged.
- internal/storage/dbproxy/proxy: the unix subtests bound sockets under
t.TempDir(), whose embedded test name overflows macOS's ~104-byte
sun_path limit ("bind: invalid argument"). Add unixSocketPath() to place
them in a short temp dir.
- cmd/bd: migration topology compared recorded and canonical Dolt roots
lexically, so macOS's /var -> /private/var symlink made equivalent paths
compare unequal. Add sameMigrationRoot(), mirroring the existing
resolveExistingPrefix idiom in cmd/bd/doctor/git.go.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(review): address blocker and major findings from adopt-pr review
Maintainer review fixup for the proxy parity branch, iterations 1-2.
Blockers and majors from the review synthesis and quality scorecard.
Blockers:
- cmd/bd/migrate_dolt_mode.go: resuming from migratePrepared rebuilt the
migration plan from the current argv instead of replaying the recorded
one. A resume that omitted or changed --idle-timeout wrote a sidecar the
target_configured check then rejected, and because that check runs only
after the phase advances past migratePrepared, the block never ran again
— the workspace stayed wedged in proxied-server mode with no in-tool
recovery. Replay j.Sidecar and warn when the supplied value is ignored.
- internal/tracker/store.go: NewStore double-wrapped already-adapted values.
directStore embeds the storage.Storage interface, so *directStore also
satisfies storage.Storage and was re-wrapped as
&directStore{Storage: &directStore{...}}; the inner value can never
satisfy storage.IssueLifecycleStore, which silently degraded
ApplyIssueUpdate to a bare UpdateIssue — no labels, no lifecycle
transaction. Match the tracker's own adapters by concrete type first.
Testing value.(Store) first, as the review suggested, does not work:
storage.Storage is a strict superset of Store, so a raw direct store
satisfies Store too and would be returned un-adapted, relocating the same
bug. The branch order is documented at the call site.
Majors:
- internal/tracker/store.go: directStore.ApplyIssueUpdate now calls
syncIssueLabels, which normalizes both label sets (trim, drop empty) and
restores the semantics the pull path had before this seam moved behind
ApplyIssueUpdate. The un-normalized local copy churned remove+add on
whitespace-only differences and let an empty label reach AddLabel; it is
deleted rather than left as a second, divergent implementation.
- Both regressions were invisible to the suite. Adds
TestNewEngineKeepsDirectStoreAdaptationIntact, TestNewStoreIsIdempotent,
TestDirectStoreApplyIssueUpdateNormalizesLabels, and
TestMigrateToProxiedServer_ResumeReplaysRecordedIdleTimeout (changed /
omitted / never subtests, each also asserting the reverse-migration escape
hatch still recovers). All four were verified to fail against the
pre-fix production code with the predicted symptoms.
Non-gating follow-ups from the scorecard, fixed while nearby:
- cmd/bd/proxy_capability.go: treat ProxyOutcomeNA as "this command has no
such flag" rather than a refusal, so an assert on an N/A row cannot return
a non-nil error carrying an empty message.
- cmd/bd/errors.go: emit the rule's real Mutates value in the JSON refusal
envelope instead of a hardcoded false.
- cmd/bd/main.go: the doctor pre-provider check returned unconditionally,
so a nil result (every doctor subcommand) skipped the legacy-store guard
and autocommit-mode resolution that other skipsStoreInit commands run.
Return only on a real refusal.
- internal/tracker/engine.go: type NewEngine's store parameter as Store so
the seam names its contract, and drop the now-dead applyPullIssueUpdate.
- CHANGELOG.md: record the proxied `bd ready --claim` row-cap refusal, which
was a behavior change shipped without a release note.
Iteration 2 -- gating major (uowStore/directStore external_ref divergence):
- internal/tracker/uow_store.go: GetIssueByExternalRef resolved through a
single merged search over both storage planes, which has no plane
preference: it is a UNION ALL ordered by content and terminating in
`id ASC`, so one external_ref present on both planes resolved to whichever
row's id sorted first. The direct backend is explicitly issues-first --
issueops.GetIssueByExternalRefInTx queries `issues` and falls through to
`wisps` only on sql.ErrNoRows, and says why ("so that pushed ephemeral
beads are found during pull dedup"). The consumer is the pull dedup, which
updates whatever row comes back, so the divergence was a silent write to
the wrong local bead under --proxied-server only. Query the issues plane
first via SkipWisps, then fall back.
The fallback is the merged search rather than the review's literal
Ephemeral=true: that filter contributes an `ephemeral = 1` predicate the
direct backend's `SELECT id FROM wisps WHERE external_ref = ?` does not
have, and wisp-plane rows legitimately carry ephemeral=0 (NoHistory beads;
see types.IssueFilter.EphemeralTier). Taking it literally would have traded
one divergence for a narrower one. Verified: implementing the prescription
fails the ephemeral_flag_clear subtest below.
- internal/tracker/uow_store_engine_test.go: the engine fake now models plane
routing (SkipWisps / Ephemeral / merged) instead of one flat map, so the
contract is expressible at all. Adds
TestUOWStoreGetIssueByExternalRefPrefersIssuePlane, whose wisp id sorts
first so "first merged hit" fails it, and
TestUOWStoreGetIssueByExternalRefFallsBackToWispPlane over both ephemeral
values. Verified to fail against the pre-fix uow_store.go.
- internal/tracker/conformance: the shared suite gains a Wisps plane and
external_ref_resolution_prefers_issue_plane, so this is a contract both
backends are held to rather than one adapter's unit test.
Iteration 2 -- non-gating follow-ups from the scorecard:
- cmd/bd/migrate_dolt_mode.go: scope the migratePrepared sidecar-equivalence
check in runMigrateFromProxiedServer to reverse journals. A forward journal
at that phase records the sidecar it is about to write, so a crash in the
pre-write window leaves none on disk -- the correct state -- and the
unscoped check refused the documented escape hatch by naming a missing
file, stranding the workspace. Tested against TargetMode's forward value so
the guard stays live for both reverse targets, "server" and
"shared-server". Adds
TestMigrateFromProxiedServer_ForwardJournalAtPreparedIsNotSidecarRefused,
verified to fail against the unscoped guard.
- cmd/bd/linear.go: buildLinearClientAPIOnly returned the OAuth client inline
and never reached the WithEndpoint block, so a configured
linear.api_endpoint was honored for an API key and ignored for OAuth. Hoist
the endpoint application after the branch, as Tracker.Init does, and add
the OAuth mirror of the existing endpoint test.
- cmd/bd/ready_max_rows_proxied_test.go: pin the proxied --max-rows refusal
on `bd ready --claim`. It lives in RunE above the dispatch and nothing
below it can enforce a cap, but the existing coverage all sits below it.
Covers both cap sources (--max-rows and BEADS_MAX_ROWS) and the negative
case that the refusal is conditioned on a live cap, not on --claim.
- engdocs/design/ownership-handoff-contract.md: trim the trailing blank line
at EOF flagged by `git diff --check`.
Iteration 3 -- non-gating residual on the iteration-2 fix:
- internal/tracker/uow_store.go: the issues-first fix above split one logical
lookup across two read transactions. uow.RunTxRead opens a fresh unit of
work per call, so calling s.SearchIssues twice left the wisp fallback's
premise -- "the issues plane is already known empty" -- without a shared
snapshot: a concurrent same-ref insert into the issues plane landing between
the two reads could let the merged fallback return the wisp, re-creating the
wrong-row write that ordering exists to prevent. The consumer is the pull
dedup loop, so it runs per imported issue. Both plane reads now share a
single RunTxRead, which is also the shape the direct backend uses (both
planes inside one withReadTx). Plane ordering is unchanged.
- internal/tracker/uow_store_engine_test.go: the engine fake counts the units
of work it hands out, and
TestUOWStoreGetIssueByExternalRefUsesOneReadTransaction pins that count at 1
across the two paths that actually perform both reads -- the wisp fallback
and the miss. An issues-plane hit short-circuits after one read and would
pass either way, so it is not a case. Verified to fail against the
two-transaction version with "opened 2, want 1".
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
bd doctor bypassed both write gates structurally, not deliberately. It
carries skipStoreAnnotation, so the root PersistentPreRunE returns before
reaching its freeze check and its read-only store policy; and doctor's
own RunE never called CheckReadonly, the chokepoint every other write
command calls first. Its fixers then opened stores directly — two of them
by shelling out to a child bd, which --readonly does not propagate to —
so `bd doctor --fix` and `--clean` mutated straight through both gates.
Worse, plain `bd doctor` wrote too. runDiagnostics re-implements the two
maintenance side effects doctor skipped with PersistentPreRunE
(trackBdVersion, autoMigrateOnVersionBump) but inherited none of that
hook's guards, so diagnosis alone rewrote .beads/.local_version and could
auto-apply a schema migration to a frozen store — the exact torn-upgrade
write a freeze exists to prevent.
Two chokepoints, both keyed on doctor's resolved target:
- checkDoctorMutationGate, one call early in RunE, triggered iff --fix or
--clean (the complete trigger set for all five mutating surfaces).
Read-only refuses with the standard message and exit 1; otherwise
migrationFreezeErrorFor(op, absPath) refuses with exit 14. No
doctor-side override: the freeze wins and the operator clears the
marker. Placed before the embedded-mode gate, so a refused run needs no
store and can never half-execute.
- The runDiagnostics maintenance block now mirrors main.go's guard on the
same two calls, probing with migrationFreezeActiveFor(beadsDir). Under
either gate doctor reports the version mismatch as a finding instead of
healing it.
Both take the target path because doctor is the one write-capable command
that operates on a directory named on the command line: keying on cwd
alone would let `bd doctor /frozen/repo --fix` walk an unrelated tree.
migrationFreezeActiveFor is the probe half of the existing
migrationFreezeErrorFor pair, added alongside it.
Every diagnosis mode still runs under both gates — diagnosing a frozen or
sandboxed workspace is the point.
Fixes#6028
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): vendor-neutral freeze marker discovery and exit code 14
The MIGRATION-FREEZE gate keyed on a gastown town root: findTownRoot walked
cwd ancestors for mayor/town.json and fell back to GT_TOWN_ROOT/GT_ROOT, and
the refusal told users to run `gt migrate thaw` — a CLI that does not ship
with bd. Key on the marker file itself instead: walk cwd to the filesystem
root looking for MIGRATION-FREEZE, with BD_MIGRATION_FREEZE_FILE as an
authoritative override (and therefore an opt-out). The on-disk contract is
unchanged, so a marker written at a town root — an ancestor of every rig cwd
— is still found with no configuration.
The refusal now names the marker's own path, so "remove that file" is always
actionable, and exits 14 (ExitMigrationFrozen) rather than 1 so scripts can
tell "someone is migrating, come back later" from a generic failure.
Fixes a real bug on the way: the root PersistentPreRunE called os.Exit(1)
from inside a function holding a live defer that closes the store and
releases the workspace gates. Both that call site and runImport now return
&exitError{ExitMigrationFrozen}; only CheckReadonly's void signature keeps
the documented flush-then-exit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migration): cover marker discovery, exit 14, and the returned refusal
The gate tests scaffolded a fake town root (mayor/town.json) in every
workspace; deleting that scaffolding is itself the vendor-neutrality proof at
setup level — the gate now keys on the marker file alone.
New coverage: an ancestor marker blocks a write in a nested workspace;
BD_MIGRATION_FREEZE_FILE is authoritative in both directions (existing file
freezes with no marker in the tree, missing file thaws despite one); the
refusal names the marker's real path and never prints a vendor-coupled
substring; bd import blocks too; an empty `touch`ed marker produces no
"(by )" artifact.
TestMigrationFreezeErrorReturnsInsteadOfExiting is the direct regression test
for the defer-skip bug — it calls the gate in the shape of the PersistentPreRunE
call site and asserts the caller's deferred cleanup ran. If the refusal ever
goes back to os.Exit, the test binary dies mid-run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(configuration): document the migration freeze marker and exit code 14
Operators had no user-facing description of the freeze gate at all — the only
recovery instruction bd printed pointed at a CLI that does not ship with it.
Add a Migration Freeze section covering the marker filename, the ancestor
walk, the optional tab-separated payload, the BD_MIGRATION_FREEZE_FILE
override, and the exit code scripts branch on.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): key the freeze on the target workspace, fail closed, cover the skip-store bypass
Review round on #6043. The gate had the right idea and the wrong anchor.
Target-workspace keying. Find walked the process working directory only, so
every invocation that names a workspace from outside it — BEADS_DIR=... bd
create, bd -C <dir> (which sets BEADS_DIR and never chdirs), a daemon or cron
with an unrelated cwd — walked the wrong ancestry and wrote straight through a
freeze. Find now takes the directories to cover and PersistentPreRunE passes
the resolved workspace; FindFrom walks a named tree without consulting cwd.
Skip-store bypass. init and bootstrap are in noDbCommands, so the root hook
returns before the gate and neither file calls CheckReadonly. bd init
--reinit-local destroyed and recreated the very database the marker protects,
exit 0, marker never read. Both now gate themselves, init at the one point
every destructive variant passes through (ahead of --proxied-server, which
reaches its writes without taking the init mutation gate at all).
Fail closed. A stat error on the marker or an ancestor read as "not frozen",
indistinguishable from the documented opt-out. Find now reports it and the
refusal says bd could not tell, rather than assuming an open workspace.
Marker hardening. Only a regular file is a marker (a directory named
MIGRATION-FREEZE no longer freezes a tree), the read is capped, markers found
by the walk in a world-writable sticky directory are ignored (/tmp: forgeable
by anyone, undeletable by the victim the refusal instructs), and the payload is
sanitized before it reaches a terminal. parse splits before trimming, so a
marker recording a reason but no operator keeps its fields instead of sliding
the timestamp into the operator slot.
One walk per invocation, hoisted into commandFreeze; PostRunE reads the same
answer and stands its own maintenance down, so a read run during a freeze no
longer leaves an auto-commit, tip metadata, backup, export or push in the
store being migrated.
Cobra no longer appends "Error: exit code 14" and a usage dump to the refusal
on the commands that set neither Silence flag.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): add the probe and targeted-gate entry points, with coverage
migrationFreezeActive is the silent probe for diagnosis paths that keep
running while frozen but must skip their own writes; migrationFreezeErrorFor
refuses against a workspace the command was handed rather than the one it was
launched in. Both are the surface the doctor-gate work (#6056) already calls,
under the names and signatures it expects, so that merge resolves errors.go to
this branch with its own callers untouched.
Covered by a test that pins both against the gate rather than leaving them as
uncalled code.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migration): stop the tip-freeze test leaking process globals
recordTipShown's no-freeze branch records a pending tip write in
commandDidWriteTipMetadata/commandTipIDsShown — the same globals
PersistentPostRunE reads to decide whether to apply one. Leaving them set
handed TestPersistentPostRunE_ClearsOnErrorPath a pending write and a nil
store, which it dereferenced: a panic that only appeared in a full-package run.
Restore all three globals, and assert on both of recordTipShown's branches
rather than on whichever one the resolved dolt auto-commit mode selects — the
immediate-write branch is not the one taken once an earlier test in the
package has turned auto-commit on.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migration): honor a symlinked freeze marker on the authoritative env path
The MIGRATION-FREEZE hardening keyed "is this a marker?" on os.Lstat +
IsRegular(), which is false for a symlink. A marker that is a symlink --
including one named by the authoritative BD_MIGRATION_FREEZE_FILE -- was
therefore read as "not frozen" and writes proceeded silently at exit 0:
a fail-open in the one gate that must never fail open (review Finding 1,
PR #6043).
statMarker now takes a `trusted` flag:
- On the operator-named BD_MIGRATION_FREEZE_FILE path it follows the link
with os.Stat and freezes when the target is a regular marker, so an
indirection like `current -> releases/N` works as intended.
- On the untrusted ancestor walk it still refuses to follow a symlink
(anything the walk passed through could otherwise redirect the gate),
but now emits a one-line stderr warning so the skip is visible instead
of a silent bypass.
Adds symlink coverage to freeze_test.go (env follows to a real marker,
dangling env symlink stays unfrozen, walk symlink is ignored with a
warning) and documents the regular-file requirement plus the env-path
symlink exception in the Migration Freeze reference.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(dc-6jaq): bd honors MIGRATION-FREEZE sentinel on write commands
Mirrors gt CLI's existing town-wide write-freeze gate (gastownhall/gastown
internal/cmd/root.go persistentPreRun + internal/migration/freeze.go on
branch feat/migrate-freeze-thaw) into bd, closing the residual gap noted in
dc-qcd2/B2: gt mail send/nudge/sling/assign already refuse writes under a
MIGRATION-FREEZE sentinel at the town root, and continuous bd writers
(mail-poller, daemon patrols) are stopped separately via the migration
playbook's plist-unload step — but a human typing 'bd create'/'bd update'
etc. mid-migration could still write directly to dolt, bypassing the
gt-layer gate entirely.
Adds internal/migration (IsFrozen/Read, read-only — the sentinel itself is
still created/removed by gt migrate freeze/thaw) and CheckMigrationFreeze
next to the existing CheckReadonly in cmd/bd/errors.go, wired into the 5
commands the story named: create, update, close, remember, import.
findTownRoot (doctor_gastown_guard.go) walks up from cwd for mayor/town.json
— the same primary marker gt's own workspace package checks — falling back
to GT_TOWN_ROOT/GT_ROOT, matching this codebase's existing orchestrator-
detection convention (formula.go, molecules.go, doltserver.go already use
GT_ROOT the same way).
Verified via clean-baseline diff against origin/main: one pre-existing,
unrelated test failure (TestUpdateStrayMetadataPositionalRefusedBeforeWrite/
TestUpdateSetMetadataRepeatedFlagStillWrites, "embedded Dolt requires a CGO
build" under CGO_ENABLED=0) reproduces identically with zero changes present
— confirmed environment-specific, not a regression from this change.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(dc-6jaq): address review — fold freeze check into CheckReadonly, gate before store-open side effects
bee-ghosttrack's review (PR #5826, 2026-08-20) found two structural gaps in
the original gate:
1. Only 5 of ~120 CheckReadonly call sites were gated (create, update,
close, remember, import) — a hand-picked list that rots. Sharpest
instance: `bd q` (quick.go), create's own documented shorthand, called
CheckReadonly directly and was never gated even though create was.
Fix: fold CheckMigrationFreeze into CheckReadonly itself, so every call
site inherits it automatically — one chokepoint, not a list to maintain.
`bd import` keeps its own explicit CheckMigrationFreeze call: runImport
never called CheckReadonly to begin with (a separate, pre-existing gap —
readonlyMode doesn't gate it either), so it can't inherit from
CheckReadonly.
2. The gate fired inside each write command's RunE, but PersistentPreRunE's
own store-touching side effects — autoMigrateOnVersionBump (a real schema
migration against the shared store) and maybeAutoImportJSONL — run
unconditionally for non-preview commands *before* any RunE. A frozen
`bd create` on a version-bumped binary could trigger both before ever
printing the refusal.
Fix: an early freeze check in the root PersistentPreRunE, placed right
after the read-only/preview classification (useReadOnly) is resolved and
before trackBdVersion/autoMigrateOnVersionBump/maybeAutoImportJSONL run.
Reuses useReadOnly rather than a second write-command list — mirrors the
existing isForcedMigrate/#4259 precedent for "must run before store open".
Also: parse("") no longer fabricates a time.Now() timestamp for an empty
sentinel file (nit); CHANGELOG entry added.
New tests: bd q and a second, previously-ungated write command (label add)
blocked during freeze; an ordering test forces a version-bump detection and
uses BD_DEBUG=1 to confirm autoMigrateOnVersionBump's body is never entered
while frozen (a companion test confirms it still runs normally without a
freeze). Verified via git stash that the four new tests fail against the
pre-fix commit — they catch what's described above, not passing vacuously.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(dc-6jaq): address round-2 review — skip maintenance writes while frozen, correct preview claim
Reviewer bee-ghosttrack re-verified a01f914b7 (build/vet/14 tests green,
MERGE-AFTER-FIXES) with two remaining asks:
1. The early freeze gate only covered write commands (`if !useReadOnly`),
but trackBdVersion/autoMigrateOnVersionBump ran regardless via
policy.runMaintenance — so a classified read (e.g. `bd list`) still
rewrote .local_version and could auto-migrate the frozen store.
Reproduced: freeze + seed a stale .local_version + `bd list` exits 0
but the auto-migrate debug line fires anyway. Fixed by gating both
calls on migration.IsFrozen(findTownRoot()) without blocking the read
itself, short-circuited behind policy.runMaintenance so the extra
filesystem walk isn't paid on the strict-readonly path where these
calls are already skipped.
2. CHANGELOG and a main.go comment claimed --dry-run/--inspect previews
are unaffected by a freeze. False: create's own CheckReadonly call
still runs the (non-preview-aware) freeze check at RunE, so
`create --dry-run` on a frozen town exits 1. Per reviewer's own
recommendation, corrected the claim rather than making the chokepoint
preview-aware — fail-closed already, and consistent with what strict
--readonly does to previews today.
Extended TestAutoMigrateSkippedDuringMigrationFreeze with a `list`
subtest covering both: exit 0 (not blocked) and no auto-migrate/write
side effect (maintenance skipped), plus a .local_version-unchanged
assertion on both subtests to make the skip observable beyond the debug
log line.
Verified: CGO_ENABLED=0 go build/vet clean; go test ./internal/migration/...
6/6; scripts/test.sh (CGO-built bd, canonical CI flags) on all 7 gate
tests in cmd/bd — 9/9 including both new list-case assertions — green.//
Out of scope per reviewer: bd doctor --fix bypassing readonly/freeze
(pre-existing, separate follow-up).
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Maintainer fixups for PR #4419 folded into one commit on top of the
contributor branch.
Security (blocker): metrics consent and endpoint are resolved from the
user-global config only (config.MetricsDisabledByUserConfig /
UserMetricsEndpoint). A project/BEADS_DIR config — highest viper precedence —
can no longer re-enable metrics or redirect the endpoint for a user who ran
`bd metrics off`.
First-run notice (major): the consent notice runs after the config-derived
json/quiet rebind and command classification, and is suppressed in
JSON/quiet/hook-json, BD_GIT_HOOK, hook/codex-hook/completion/shell-init/
version/prime, the metrics command, `init --stealth`, and the root
`bd --version` / `bd -V` probe, so it can never corrupt machine-readable or
hook/protocol output.
One cli_command event per invocation (major): delegating commands no longer
double-count. `bd ready --gated` and `bd mol wisp <proto>` record only their
own event by delegating to non-emitting cores (runMolReadyGatedCore /
runWispCreateCore), matching the existing runTodoListCore/runListCore pattern;
cardinality regression tests cover both aliases.
config get/show honor user-global metrics state (major): `bd config get
metrics.*` and `bd config show` report the user-global value (via
config.GetUserYamlConfig) that actually governs runtime behavior, with the
user-global path as the location, instead of a project value that has no
runtime effect.
Metrics cleanup on os.Exit paths (major): CheckReadonly and the reachable
pre-run gates (no-DB, fresh-clone, schema-skew, remote-migrate-gate, identity
mismatch) call the shared metrics.CloseAndFlush before exiting, so events
queued earlier in the run are still written and scheduled for upload instead
of stranded until the next clean exit. main()'s post-command tail uses the
same helper. `bd q` now creates its event before the readonly guard and labels
the readonly operation "q".
Telemetry coverage (major): recompute-blocked converted to RunE + HandleError
and emits a cli_command event; `metrics on/off/example` and `version` emit
cli_command events.
Consistency / minor cleanups: added SilenceUsage/SilenceErrors to the
ADO/GitHub/GitLab/Notion push/pull commands to match the jira/linear siblings
in the same file; corrected the inverted env-override "saved config" status
text; preserved 0600 when unsetting user-global config keys.
Pre-review CI repair (earlier in this commit): lint, stealth-init
cleanliness, proxied-server error handling, and regenerated CLI docs.
Tests: user-global opt-out vs project override at the config readers, runtime
resolvers, and `config get`; first-run notice suppression across
hook/protocol/json/quiet/stealth/root-version contexts; event cardinality for
the todo/ready-gated/wisp aliases; and CloseAndFlush persistence.
Original contributor commits preserved.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping
Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.
Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.
Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.
Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.
Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md
* fix: suppress deprecation notice when stderr is not a TTY
Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.
Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.
* fix: suppress gosec G304 false positive in hookWorkTreeRoot
The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.
This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.
* feat: add schema_version to all --json output (beads-5uh)
All bd commands that emit --json output now include a schema_version
field so consumers (Jawnt MCP, BeadsX, gt mail, sync scripts) can
detect format changes without silently breaking.
- Object output: schema_version injected as top-level field
- Array output: wrapped as {"schema_version": 1, "items": [...]}
- Error output: schema_version added to stderr JSON
Central implementation in outputJSON() via wrapWithSchemaVersion()
means all 272 call sites get the field automatically.
Includes:
- Unit tests for wrapping logic (object, struct, slice, nil, roundtrip)
- Updated protocol contract tests for new envelope format
- New schema_version presence test across list/ready/show
- docs/JSON_SCHEMA.md documenting the field contract per command
* feat: add ready/blocked JSON contract tests (beads-clt)
bd ready --json and bd blocked --json already return full issue objects
with dependency counts and blocked_by fields. Add protocol contract
tests to pin this behavior:
- TestJSONContract_ReadyOutputHasFullObjects: verifies dependency_count,
dependent_count fields on ready items
- TestJSONContract_BlockedOutputHasBlockedBy: verifies blocked_by and
blocked_by_count fields on blocked items
Update docs/JSON_SCHEMA.md with blocked output contract.
* feat: add bd ping lightweight health-check command (beads-8cc)
New minimal command that confirms bd can reach its database:
1. Resolves the .beads workspace
2. Opens the store (embedded or server)
3. Runs a trivial query (SearchIssues with Limit=1)
4. Reports timing breakdown
Supports --json for structured output with resolve_ms, store_ms,
query_ms, and total_ms fields. Exit 0 on success, 1 on failure.
Registered as read-only command (no auto-push, no file writes).
Includes protocol contract test for JSON output.
* feat: structured JSON errors on stderr when --json active (beads-06n)
All fatal error functions (FatalError, FatalErrorWithHint,
FatalErrorRespectJSON, FatalErrorWithHintRespectJSON) now emit
structured JSON with schema_version when --json is active:
{"schema_version": 1, "error": "message", "hint": "optional"}
Centralized via jsonStderrError() and jsonStdoutError() helpers.
Replaces ad-hoc json.MarshalIndent calls scattered across error
functions with a consistent, schema-versioned format.
Includes unit tests and updated protocol contract test verifying
schema_version presence in error JSON output.
* feat: enhance bd import with stdin, --dedup, --json (beads-c6i)
Enhance the existing bd import command for bulk JSONL ingest:
- Stdin support: bd import - reads JSONL from stdin for piped workflows
- --dedup flag: skips lines whose title matches an existing open issue
(case-insensitive) to prevent duplicate creation
- --json flag: structured output with created/skipped counts and IDs
Refactored import to use runImportFromReader() for unified file/stdin
handling. Added filterDuplicatesByTitle() for dedup logic. Updated
docs/JSON_SCHEMA.md with import output contract.
Backward compatible: existing bd import [file] and --dry-run work
exactly as before.
* fix: update tests for schema_version envelope in JSON output
Three test files expected raw JSON arrays or map[string]string, which
broke when schema_version (a number) was added to the output envelope:
- ado_test.go: parse envelope with items array instead of raw []json.RawMessage
- bootstrap_embedded_test.go: use map[string]interface{} for mixed types
- where_embedded_test.go: same map[string]interface{} fix
* fix: drop array envelope wrapping to fix 200+ test failures
The schema_version envelope was wrapping arrays as
{"schema_version": N, "items": [...]} which broke every integration
test that parses --json array output. Objects (show, create, ping)
still get schema_version injected. Arrays (list, ready, blocked)
now pass through unchanged for backwards compatibility.
Also fixes: gofmt on import.go, doc-flags reference to bd import,
uses importIssuesCore result to satisfy unparam lint.
* fix: update remaining tests for schema_version number field
config_embedded_test.go, kv_embedded_test.go, config_nodb_embedded_test.go,
and show_test.go all parsed JSON output into map[string]string but
schema_version is a number. Parse to map[string]interface{} and
skip/assert schema_version appropriately.
---------
Co-authored-by: kev <kglynn@pryoninc.com>
* fix(workspace): align resolved workspace messaging and config lookup
intent(workspace): pure worktrees and external BEADS_DIR setups should work without implying a local .beads directory is required
decision(config): derive config repo roots from FindBeadsDir-backed workspace resolution instead of a local-only .beads walk
constraint(workspace-detection): keep FindBeadsDir ordering and storage behavior unchanged while making bd where the primary diagnostic hint
learned(testing): shared-server env and global .beads ignore rules can distort CGO suites, so regression coverage now normalizes those test paths
* fix(bootstrap): align no-workspace JSON wording
intent(bootstrap): machine-readable no-workspace output should match the resolved-workspace guidance used elsewhere on this branch
decision(bootstrap-json): reuse the shared workspace error helpers through a dedicated payload builder so tests can lock the JSON contract
constraint(review-loop): keep the bootstrap CLI flow unchanged outside the no-workspace JSON branch while adding a focused regression test
* fix(where): allow no-workspace diagnostics without db (beads-9f74-5l1)
intent(where): no-workspace guidance should point to a command that actually runs when workspace resolution fails
decision(startup): treat top-level where as a no-db command so it reaches its own handler before database preflight
constraint(where-tests): subprocess mode can change the exact hint text, so the regression test locks the JSON contract and stable guidance fragments instead
* fix(bootstrap): restore bd where guidance for no-workspace output (beads-9f74-3c3)
intent(bootstrap): no-workspace bootstrap guidance should match the resolved-workspace diagnostics introduced on this branch
decision(no-workspace-hints): reuse the shared hint that mentions bd where instead of the bootstrap-specific fallback text
constraint(bootstrap-tests): cover both the payload helper and subprocess CLI path so wording regressions are caught before release
* fix(workspace): remove no-workspace .beads fallbacks (beads-9f74-gr1)
intent(workspace-resolution): finish the GH#3124 follow-up for runtime paths that still fabricated local .beads state
rejected(no-workspace-fallback): inventing ./ .beads paths outside an active workspace hid shared-worktree resolution and created stray files
decision(setup-recipes): keep built-in bd setup recipes usable without a workspace but require an active workspace for custom recipe state
constraint(worktree-support): completion and backup helpers still need to resolve shared main-repo workspaces from a git worktree
* fix(config): skip no-workspace store init for store-free commands
intent(config): review-fix-loop found no-workspace config commands should reach their own graceful paths instead of failing in PersistentPreRun
decision(config-preflight): detect store-free config subcommands before DB synthesis so config.yaml, git-backed, and diagnostic flows can run without an opened store
constraint(json-contract): keep bd config validate --json machine-readable on stdout once pre-run stops short-circuiting into low-level DB errors
learned(config-preflight): the parent config command not being in noDbCommands leaked store init into show, validate, drift, apply, and yaml-only config helpers
* fix(ci): restore init prefix normalization and formatting
intent(ci): clear the current PR failures instead of leaving the branch blocked behind known red checks
decision(init-prefix): normalize dotted prefixes before persisting issue_prefix so config, metadata.json, and Dolt database naming stay aligned for Julia-style repos
constraint(fmt-check): CI runs gofmt over the whole repo, so the existing spacing drift in internal/jira/tracker_test.go had to be cleaned up on this branch to get a green run
learned(ci): the latest main CI was already red on the same formatting file and the same embedded shard, so rebasing surfaced pre-existing blockers rather than introducing a new shard-only regression
- FatalError and FatalErrorWithHint now output structured JSON to stderr
when --json flag is active, preventing mixed text/JSON output
- bd restore validates issues.jsonl schema before importing, catching
incompatible export formats early (GH#2492)
- Add restoreResult.Errors and ErrorDetails fields for structured error reporting
- Add 6 JSON contract regression tests for list, show, create, close,
ready, and error output contracts
Co-Authored-By: matt wilkie <maphew@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Code health review found 30+ instances of error suppression using blank
identifier without explanation. Added comments to 82 files explaining WHY
each error is safely ignored (best-effort cleanup, advisory operations,
safe defaults, etc.) to improve code maintainability.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/polecats/jasper
Rig: beads
Role: polecats
- Add FatalErrorRespectJSON helper for JSON-aware error output
- Fix bd comments list returning null instead of [] for empty arrays
- Remove redundant local --json flags from show/update/close commands
that were shadowing the global persistent --json flag
- Update show command error handlers to use FatalErrorRespectJSON
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a --readonly flag that blocks all write operations, allowing workers
to read beads state without modifying it. Workers can use:
- bd show, bd list, bd ready (read operations)
Workers cannot use:
- bd create, bd update, bd close, bd sync, etc. (write operations)
The flag can be set via:
- --readonly flag on command line
- BD_READONLY=true environment variable
- readonly: true in config file
This enables swarm workers to see their assigned work from a static
snapshot of the beads database without accidentally modifying it.
Commands protected by readonly mode:
- create, update, close, delete, edit
- sync, import, reopen
- comment add, dep add/remove, label add/remove
- repair-deps, compact, migrate, migrate-hash-ids, migrate-issues
- rename-prefix, validate --fix-all, duplicates --auto-merge
- epic close-eligible, jira sync
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Create reusable error handling helpers to reduce boilerplate and
enforce consistency across the codebase:
- FatalError(format, args...): writes "Error: ..." to stderr and exits
- FatalErrorWithHint(message, hint): includes actionable suggestion
- WarnError(format, args...): writes "Warning: ..." to stderr
Prototyped in create.go to validate the approach - converted 13 error
patterns and 5 warning patterns. This reduces code from:
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
To simply:
FatalError("%v", err)
Also fixed countIssuesInJSONLFile reference after earlier refactoring.
See docs/ERROR_HANDLING.md for the three-pattern guideline.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>