beads/docs/reference
ecuthiell ac1ec5dc4c
fix(init): bootstrap Git in the selected project directory (#6459)
* fix(worktree): scrub inherited Git routing state

Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.

Fixes #5531

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

* refactor(worktree): explain owned filtering and remove an unused shim

Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.

Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning

* fix(config): isolate identity and tracked-file Git probes from routing

Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.

Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning

* fix(config): share subprocess key identity for Git routing (saa-cgh.93)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(exec): match Windows environment key identity (#5618)

Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

* test(execenv): exercise every environment operation under both host rules

Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.

Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning

* test(execenv): exercise exported host policy wiring (saa-cgh.78)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(worktree): explain startup Git environment scope (saa-cgh.23)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(config): isolate role commands from Git routing (saa-cgh.99)

Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(env): exercise shared key helpers on native Windows (saa-cgh.78)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(config): explain role command routing policy (saa-cgh.99)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): isolate role configuration from inherited Git routing (saa-cgh.109.3)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): use the selected origin in contributor setup (saa-cgh.109.7)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): isolate Git writes in planning repositories (saa-cgh.109.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): retain inherited planning commit author (saa-cgh.109.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): align embedded role gates with selected Git context (saa-cgh.109.12)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): scope embedded artifact Git operations to selected directory (saa-cgh.109.15)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): cover selected optional artifacts and explain refused commits (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Honor role-probe cancellation and exercise actual fork planning (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): warn when automatic contributor role write fails (saa-cgh.109.3)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): cover successful nonquiet contributor role writes (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Assert the automatic contributor setup banner alongside warnings (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* test(init): read persisted role routing from the store (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Bind early embedded Git bootstrap to the selected project (saa-cgh.120.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* Create the owned separate-storage parent in the bootstrap fixture (saa-cgh.120.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init,gitenv,config): maintainer fixup for #6459

Review iteration 1, blocking:
- cmd/bd/init_stealth.go: scope the fork exclude writer the way this PR
  scoped the fork detector. detectForkSetup now scrubs inherited Git
  routing, but resolveGitExcludePath still ran `git rev-parse
  --git-common-dir` with no Dir and no Env, so with GIT_DIR inherited
  toward another repository bd detected the fork in the selected repo and
  then appended `.beads/`, `**/RECOVERY*.md` and `**/SESSION*.md` to the
  *inherited* repository's .git/info/exclude - automatically, with no
  prompt, in non-interactive mode. At base the two halves agreed (both saw
  the inherited repo, found no upstream, wrote nothing), so the PR is what
  creates the disagreement. Scrubbing the probe is the whole remedy: no
  cmd/bd caller chdirs, so `repoPath == ""` already means the selected
  project directory once inherited routing is gone. The new test asserts
  both halves - the selected repo is written, the inherited one is
  byte-unchanged - and reverting the scrub reds it while every existing
  exclude test stays green.
- cmd/bd/config.go: the new comment claimed "All role commands ignore
  inherited Git routing". Only bd config's own role paths were hardened -
  routing.DetectUserRole, `bd config show`, `bd doctor` and `bd hooks
  uninstall` still resolve beads.role through the inherited environment,
  and beads.RepoContext.Role pins GIT_DIR/GIT_WORK_TREE last-wins but still
  inherits GIT_CONFIG_*. So `bd config get beads.role` and `bd config show`
  can disagree in one shell, and `bd config unset beads.role` and `bd hooks
  uninstall` can target different repositories. Narrow the comment to the
  command set it covers; widening the boundary to the deciders is a
  separate, permissions-adjacent change. The same root cause is filed on
  #6460 and #6464, where it is broader - fix it once, on whichever merges
  first.

Review iteration 1, non-blocking:
- docs/reference/worktrees.md: the new prose claimed startup Git discovery
  probes for every bd command scrub inherited routing. Only internal/config's
  gitDirsForRepo does; internal/git's process-cached context does not. Narrow
  the sentence to config discovery and name both sides.
- internal/gitenv/routing.go: say in the contract comment why
  GIT_CEILING_DIRECTORIES is a routing key even though it narrows rather
  than redirects, and disclose that removing it widens the upward search.
  Pin the membership with a ceiling entry in the existing scrub table.
- cmd/bd/worktree_cmd.go: route the removal pass's key identity through
  execenv.KeyIdentityForOS instead of the last hand-rolled fold. ToUpper is
  the opposite direction from the shared primitive and provably
  non-equivalent: on Windows it collapsed GıT_OPTIONAL_LOCKS (U+0131) onto
  GIT_OPTIONAL_LOCKS and stripped an unrelated variable that
  gitenv.ScrubRoutingForOS, one line earlier, keeps.

Validation: go build ./..., go vet, CGO_ENABLED=0 vet and
GOOS=windows CGO_ENABLED=0 vet all clean; internal/gitenv green; cmd/bd
filtered run green except TestGetNotionConfigReadsDBPathWhenStoreUnset and
TestConfigValidateReadOnlyIsHermetic, which fail identically at the
unmodified head. All three new pins mutation-proved.

Review iteration 2, non-blocking:
- internal/config/worktree_config_test.go, cmd/bd/init_git_bootstrap_routing_test.go:
  finish the conditional half of iteration 1's GIT_CEILING_DIRECTORIES item.
  That item offered "drop the key" or "keep it and say so - and if kept, add
  a legitimate-ceiling case to the two cited tests". The docs arm was taken
  but only one of the two tests got a case, and the half left unpinned is the
  widening the new contract comment now promises. Both new cases set a
  *legitimate* ceiling - an operator fencing off an ancestor - and assert the
  scrub widens past it: startup config discovery still resolves the main
  repository's shared config, and `bd init`'s bootstrap probe still resolves
  the containing repository. Each carries a control that fails the test if the
  ceiling did not bite, so neither can pass vacuously. Dropping
  GIT_CEILING_DIRECTORIES from routingKeys reds both new pins while
  TestWorktreeFallbackConfigPathIgnoresInheritedGitRouting and
  TestSetupForkExcludeIgnoresInheritedGitRouting stay green, so they cover an
  arm the poisoned-routing pins do not.
  The review prescribed this assertion in the inverted direction ("a
  fenced-off ancestor does not suppress the fresh git init"). Measured
  against git 2.43.0: a ceiling at a repository root does fence off a probe
  run from a subdirectory, so scrubbing it makes the ancestor visible and the
  fresh `git init` is suppressed. The tests pin the measured direction.
- cmd/bd/init_stealth.go: the scrub makes resolveGitExcludePath's "not a git
  repository" newly reachable from `bd init --setup-exclude` exactly where the
  cause is interesting, but the probe's error was discarded. Thread git's own
  reason through, reusing firstNonEmptyLine from sync_git.go, which already
  exists for this failure shape. exec.ExitError.Error() is only "exit status
  128", so a bare %w would have added nothing readable. The "not a git
  repository" prefix is load-bearing - setupStealthMode matches it with
  strings.Contains to treat this as a skip - and is preserved. Rendered:
    Warning: failed to configure git exclude: not a git repository (inherited
    Git routing is ignored here): fatal: not a git repository (or any of the
    parent directories): .git

Validation (iteration 2): gofmt clean; go build ./...; go vet, CGO_ENABLED=0
go vet and GOOS=windows CGO_ENABLED=0 go vet clean on cmd/bd and
internal/config. Both new pins green and mutation-proved as described; the
nine existing cmd/bd exclude/routing/fold pins, the internal/config
worktree-fallback set, and the internal/gitenv and internal/execenv suites all
stay green. No production behavior change beyond the error text.

---------

Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Julian Knutsen <julian@example.com>
2026-09-27 13:16:05 -07:00
..
advanced.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
antivirus.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
configuration.md fix: honor dolt.auto-commit in proxied server mode (#6499) 2026-09-27 01:31:11 -07:00
events-journal.md fix(events): journal delete and cascade dep_remove rows carry the request actor; notice when reading a disabled journal (#5985) (#6061) 2026-08-29 04:14:23 -07:00
faq.md docs(troubleshooting): document the two native-Windows integration traps (#5838) 2026-08-20 05:41:39 -07:00
git-integration.md Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
index.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
json-schema.md fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
observability.md refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859) 2026-08-03 00:05:06 -07:00
protected-branches.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
troubleshooting.md Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
worktrees.md fix(init): bootstrap Git in the selected project directory (#6459) 2026-09-27 13:16:05 -07:00