v1.63.0.0 feat(gbrain): make repository indexing verifiable and fail-closed

[mamedov]

Summary

Make /sync-gbrain repository indexing fail closed and prove exactly which clean repository commit and immutable content plan were applied.

• Replace page-count and path-spelling heuristics with a strict schema-1 repository-index result and persisted verified receipt.
• Bind GREEN evidence to the canonical worktree root, full clean HEAD, expected bookmark, strategy auto, trusted .gbrain-source, final source registry state, and one preview/apply plan_digest.
• Add --verify-receipt to rebind persisted evidence to the live canonical root, attached source, and current clean HEAD without contacting GBrain.
• Stop memory, artifact, cleanup, reindex, and dream stages after any repository refusal, partial apply, or unverified postcondition.

Safety and deterministic behavior

• The wrapper requires GBrain 0.42.71.0 or newer.
• Missing sources use a safe two-call bootstrap: the first invocation registers only and exits with state_changed: registry_only; a later invocation syncs after registration is independently observable.
• Wrapper --dry-run is a true no-probe ORCHESTRATION PREVIEW — unvalidated: it performs no Git, engine, source, lock, path, or content probes and makes no writes.
• For an existing source, the wrapper validates a schema-1 dry_run / validated_index_plan, requires a full lowercase SHA-256 plan_digest, passes it through --expected-plan-digest, and accepts success only when apply echoes the same digest. plan_changed preserves validated observed/required digests and refuses before mutation.
• Preview evidence preserves the source's prior bookmark and last-successful strategy; only completed apply may advance them to the target HEAD and auto.
• Source state is read through three strict snapshots: before planning, after sync, and after wrapper-owned marker attachment.
• Every real attempt writes a fail-closed watermark and invalidates the prior receipt before the first GBrain probe. The new receipt is written while that watermark still blocks readers and becomes visible only after the watermark clears.
• Receipt verification refuses active wrapper locks and superseding attempt watermarks both before and after live Git/source rebinding.
• Canonical path ownership must remain unique; path drift is never repaired by remove/re-add.
• .gbrain-source is replaced by gstack through a same-directory exclusive temporary file and atomic rename, so a raced symlink is not followed.
• Affected evidence stores at most 100 canonical rows plus a SHA-256 digest over the complete operation/path/slug/rename-source tuple set.
• Corpus evidence has an exact schema, zero image operations, multimodal admission disabled, and search_ready is true if and only if embedding and extraction are both complete.

Review-driven hardening

• Added a real executable/package launcher for gstack-gbrain-sync; generated host skills now resolve the same runnable entry point.
• Global skill guidance uses GBrain repository search only after live receipt verification succeeds; a pin alone is never freshness proof.
• /setup-gbrain delegates repository writes to the safe wrapper instead of raw import/background embedding paths.
• Same-HEAD failed retries cannot resurrect an older GREEN receipt, and lock setup errors such as permission failures are no longer misclassified as contention.
• Recovery commands validate inputs, quote every argv value, and pair direct preview/apply through the exact returned plan_digest instead of telling operators to remove --dry-run.

Verification

Current reviewed commit: 63308e25115bc48cfb7de093aec257bf9094897a

• bun test test/gbrain-repository-index.test.ts test/gstack-gbrain-sync.test.ts test/gbrain-sync-skip.test.ts test/skill-e2e-memory-pipeline.test.ts test/host-config.test.ts test/gen-skill-docs.test.ts
  • 596 passed
  • 0 failed
  • 7,412 assertions
• Final generated/docs subset: 529 passed, 0 failed, 7,156 assertions.
• bun run build passed and regenerated every supported host artifact.
• Prettier check passed for all changed TypeScript sources and tests.
• git diff --check passed.
• Version classification: ALREADY_BUMPED (1.60.1.0 → 1.63.0.0).
• Public-repository redaction scan: 0 HIGH findings; MEDIUM matches were known public test fixtures and version-number false positives. The new launcher scanned with 0 findings.

Full-suite baseline caveat

An earlier full bun test run exited 1 solely because three pre-existing test/brain-cache-roundtrip.test.ts cases time out at the 5-second test limit when a usable local GBrain is installed. A focused reproduction produced 11 passed / 3 failed. The affected brain-cache implementation and test paths are unchanged from origin/main. Follow-up: https://3.basecamp.com/4058523/buckets/34718435/card_tables/cards/10141872751

Tracking

Basecamp card: https://3.basecamp.com/4058523/buckets/34718435/card_tables/cards/10135180500

Release status

No release, installation, merge, or deployment was performed. This PR prepares the v1.63.0.0 code, documentation, tests, and version metadata for review.

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[mamedov]

Superseded by the dependency-ordered split:

• fix(gbrain): bind source mutations to canonical identity #2436 — canonical source identity and mutation safety; this must land first.
• feat(gbrain): sync changed repository docs #2438 — docs-aware repository sync; this depends on fix(gbrain): bind source mutations to canonical identity #2436 and will be updated from the then-current main before fresh verification.

The split keeps the security-sensitive identity boundary independently reviewable and gives the docs-aware behavior its own tests and rollout boundary. Closing this combined PR in favor of those replacements.

[mamedov]

Scope clarification: the replacement PRs supersede this branch as the active implementation path, not every mechanism explored here. They intentionally do not carry forward the receipt, plan-digest, or --verify-receipt architecture. If that stronger evidence model is revisited, it should return as a separate proposal against current main; it is not being claimed as shipped by #2436 or #2438.