* feat(security): verify build-provenance attestation before binary self-update installs
Before the downloaded binary is chmod'd, executed, or renamed over the live
path, compute its SHA-256 and verify it against the SLSA build-provenance
attestation from the GitHub REST API (origin-separated from the asset CDN):
the attested subject digest must match and the builder id must be this repo's
release workflow. Dependency-free (node:crypto + fetch + base64 + JSON — the
sigstore npm package does not bundle under bun build --compile). Fail-closed
with typed integrity_failed / integrity_unavailable reasons; gbrain upgrade
surfaces a dedicated message. Closes the D7a TODO.
Tests: unit suite over the deps.fetchIntegrity seam (tampered digest, wrong
builder, wrong asset name, missing attestation) + an opt-in compiled-binary
offline smoke test (GBRAIN_SELFUPDATE_COMPILE_SMOKE=1) proving the real verify
path survives bun build --compile.
* feat(release): build the admin UI fresh from source in the release job
Release binaries now embed an admin bundle built from admin/src at release
time (frozen-lockfile install, cache keyed on admin/bun.lock) instead of the
committed admin/dist bytes, so the shipped bundle is always traceable to
reviewed source.
* feat(ci,scripts): wave-security-scan + Semgrep graduates to blocking on net-new findings
scripts/wave-security-scan.sh (bun run wave-security-scan <base>..<head>) is
the repeatable mechanical sweep for community-PR waves: alarm-level checks
(obfuscation/eval in code, gitleaks with the repo allowlist stripped, committed
admin-bundle changes) plus informational context (new outbound URLs, spawns,
env reads, dependency changes). Range guards, --json, non-zero exit on alarms.
semgrep.yml: fetch-depth 0 + --baseline-commit <PR base> so a PR fails only on
findings it introduces; continue-on-error removed (the documented graduation
path). Scheduled runs stay full-tree report-only.
* docs(security): install-path trust model, wave security-review step, follow-up TODOs
SECURITY.md documents the self-update integrity check and the install-path
trust model (which paths verify provenance vs trust-on-first-use).
docs/RELEASING.md adds a security-review step to the community-PR wave process
(run wave-security-scan over the collector branch before shipping). CLAUDE.md
carries the pointer; llms bundle regenerated; two follow-up TODOs filed.
* fix(security): close adversarial-review findings in the self-update + wave-scan hardening
Pre-landing adversarial review (Codex + 2 Claude passes, cross-model consensus)
found real defects in the initial hardening; fixed here before merge:
- Downgrade-replay: verifyIntegrity accepted any historically-attested binary,
so an asset-swap adversary could serve an older, validly-attested vulnerable
build. Bind the staged binary to the release tag (--version must match) →
new typed reason version_mismatch, fail-closed before rename.
- Builder-id: pin to exact @refs/heads/master (EXPECTED_BUILDER_IDS), not a
prefix — a workflow_dispatch from an arbitrary branch mints a real attestation.
- parseAttestationBundle: reject non-SLSA predicateType; never-throws contract
restored (injected fetchAttestation that throws → integrity_unavailable, no
staged-file leak).
- upgrade.ts: drop "signed" from the user copy (we match digest/identity over
TLS; we don't verify the Sigstore signature chain — honest wording).
- wave-security-scan.sh: cd to the caller's repo TOP LEVEL (a subdir run scoped
the gate to a subtree); match shell `eval "$x"` / `source <(...)`, not just
`eval(`; is_comment no longer hides JS `#field`/`*gen()`; anchor the diff
header to `+++ b/` so a `++ x;` content line can't poison attribution; scan
admin/{package.json,bun.lock} + admin/src (release-reachable); require python3;
emit exit_code/gate in --json so a consumer can't read alarm:0 while exiting 1.
- semgrep.yml: baseline off `git merge-base "$BASE_SHA" HEAD`, not the raw
event base.sha (which goes stale when master advances mid-PR).
New contract pins in release-workflow.test.ts (attest step + admin-fresh-build
+ builder-id ref). Compile smoke wired as `bun run test:compile-smoke` + docs.
Two residuals filed (P1 upgrade exit-code/autopilot; P3 API rate-limit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.12.0 chore: version bump + CHANGELOG (supply-chain hardening: self-update integrity, fresh admin build, wave security scan)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: regenerate version-stamped artifacts for 0.46.12.0 (bootstrap tag, template repo, plugin tree)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump plugin manifests to 0.46.12.0 (five-file version lockstep)
VERSION/package.json moved to 0.46.12.0; the hand-maintained plugin manifests
(openclaw.plugin.json, .codex-plugin/plugin.json, .claude-plugin/plugin.json)
must track it — pinned by test/codex-plugin-manifest.test.ts +
test/openclaw-plugin-manifest.test.ts (unit suite, not verify).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: sync contributor + README docs for v0.46.12.0 supply-chain hardening
- CONTRIBUTING.md: correct the PR-side Semgrep description — it graduated from
advisory/non-blocking to blocking on findings new since the PR base
(pre-existing findings never block; scheduled runs stay report-only), matching
SECURITY.md's "Automated security scanning" section.
- README.md: expand the SECURITY.md doc-link description to surface the new
install-path trust model, self-update integrity, and automated scanning
content so it's discoverable from the entry point.
- llms-full.txt: regenerated (README is inlined in the bundle).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: fix codex-review doc drift (test-tier count, integrity version attribution)
Cross-model doc review (Codex, high effort) against origin/master...HEAD found:
- docs/TESTING.md: header said "Six test command tiers" but the table now lists
seven after this release added the test:compile-smoke row.
- TODOS.md: the self-update integrity work (verifyIntegrity) was attributed to
v0.46.11.0 in two places; it shipped in v0.46.12.0 (v0.46.11.0 was the
unrelated five-issue operational wave). Corrected both.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(security): drop 'signed' from self-update wording; note downgrade-replay guard
The updater matches the attestation's digest/identity over GitHub API TLS but
does not verify the Sigstore signature chain — align SECURITY.md with the honest
wording already in upgrade.ts. Also document the version-mismatch downgrade guard.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.12.1 chore: re-version supply-chain hardening 0.46.12.0 -> 0.46.12.1 (queue collision)
0.46.12.0 was claimed by concurrent ships; this PR takes the .1 micro slot.
Five-file version lockstep + CHANGELOG header + regenerated version-stamped
artifacts (bootstrap tag, template repo, plugin tree).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: stop fixture git commits inheriting global commit.gpgsign (#1696 flake)
Fixture tests that `git commit` in temp repos inherited the developer's global
commit.gpgsign; a signing gpg-agent OOMs under full-suite memory pressure
("gpg: signing failed: Cannot allocate memory") and fails a random fixture
commit. The unit + serial runners now inject GIT_CONFIG commit.gpgsign=false
(highest-precedence, whole process tree), and the two fixtures I own set it in
their repo config directly. Deterministic, machine-config-independent.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: parse wave-scan JSON from stdout only (CI runners lack gitleaks)
CI test-shard runners don't have gitleaks, so wave-security-scan.sh fail-closes
(exit 1) and prints its WARNING to stderr — by design. The fixture test's run()
helper concatenated stdout+stderr on the non-zero path, so split('\n').pop()
grabbed the stderr warning instead of the JSON line and JSON.parse failed
(green locally where gitleaks exists; red on CI). Parse the last JSON object
line from stdout only, and drop the implicit exit-0 assumption from the
markdown-prose case (its contract is obfuscation.total===0, not the exit code).
Verified both shapes: local with gitleaks (6 pass) and PATH-masked CI
reproduction (5 pass / 1 skip).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* cli: dispatch honesty sweep — hide shadowed cliHints, wire whoknows, drop dead code
Three ops (think, get_recent_salience, find_anomalies) carried non-hidden
cliHints whose names live in CLI_ONLY — dead cliOps entries that could never
dispatch (CLI_ONLY wins). Marked hidden with rationale comments, plus a new
shadow-guard invariant test so the class stays dead.
whoknows: the richer runWhoknows renderer (ranked table, per-factor explain,
thin-client routing) was unreachable behind find_experts' generic op dispatch.
Wired via CLI_ONLY + CLI_ONLY_SELF_HELP (the #2035/#3502 precedent); op hint
hidden. --json output shape unchanged (same results array).
Dead code: handleCliOnly's unreachable 'search' case ('search' is not in
CLI_ONLY; the :387 pre-dispatch and free-text op path are the live surfaces)
and printHelp's never-consumed cliNames. Flag registry regenerated (whoknows
entry).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* mcp: stdio tools/list honesty — subtract gate-off publish-gated ops on every agent-facing catalog
stdio dispatches remote:true, and publish-gate enforcement (assertPublishEnabled,
the advisor inline gate) exempts only ctx.remote === false — yet stdio's
ListTools advertised the 4 gated ops unconditionally and request_tools'
visibleOpsForCaller treated transport==='stdio' as gate-exempt. Both were the
listed-but-denied class the honest-catalog wave exists to kill, surviving on
the default transport.
Fix splits the two caller axes everywhere they were conflated: localOnly
visibility stays on the transport-LOCALITY axis (stdio IS the local pipe, D7 —
localOnly ops keep listing), publish gates are the owner-CONSENT axis keyed
strictly on remote === false. server.ts gains stdioVisibleTools (per-request,
uncached per publish-gates doctrine, fail-closed on resolver failure);
visibleOpsForCaller now gate-subtracts for stdio. Stale bypasses-gates
comments corrected. New test/mcp-stdio-gate-list.test.ts pins the builder;
request-tools tests updated to the truthful stdio catalog (+ gate-on case).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* core: extract takes write-through into src/core/takes-write.ts (md-canonical, fence-first)
Shared write core for the gbrain takes CLI and the upcoming takes_* MCP ops.
Markdown is canonical (the extract-takes contract): every mutation is md-first
with fence-derived row numbers, and the markdown write is REQUIRED — a missing
page file refuses ('mirror_unavailable') instead of creating DB-only rows the
next reconcile would clobber. The DB mirror for add/update/supersede is
addTakesBatch's (page_id,row_num) upsert of the affected fence rows — the same
primitive the extract pipeline uses, so mirror and reconcile can never
disagree; resolve mirrors via engine.resolveTake with md→DB self-healing on
drift. Row-targeting lookups read the PARSED FENCE (canonical) and carry the
holder-fence masking seam (fenced row presents as row_not_found) for the ops
that follow. Lock contention maps to a typed retryable error.
Deliberate behavior fix folded in (EV1 class): the old update/resolve
'DB-updated-but-markdown-missing → warn' paths were self-defeating — their own
reconcile hint (extract takes) would clobber the DB-only edit just written.
Both now refuse with the row/mirror error; supersede inherits kind/holder from
the fence row rather than the DB and mirrors both affected rows exactly as the
fence states them (#2663 test updated to the new contract, asserting the
mirrored old-row supersession pointer + inherited fields).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* core: extract search introspection builders into core/search (modes-report, tune-recommendations, graph-signals stats)
Behavior-preserving move so the upcoming search_modes / search_stats /
search_tune MCP ops render the same reports as the CLI: buildModesReport +
KNOB_DESCRIPTIONS → core/search/modes-report.ts, the tune recommendation
builder → core/search/tune-recommendations.ts (strictly read-only — the apply
lane stays in the command file per CDX-21), readGraphSignalsStats →
core/search/telemetry.ts. src/commands/search.ts keeps arg parsing, text
rendering, the modes reset lane, and the apply/revert lane; all JSON output
shapes unchanged.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* core: extract capture content helpers into src/core/capture-content.ts
Pure move of slug defaulting (inbox/YYYY-MM-DD-sha8 + type routing), the CV10
binary NUL guard, CV9 hash normalization, title derivation, the Life Chronicle
event block, and the BUG-1 frontmatter merge — shared with the upcoming
capture MCP op. capture.ts statically imports operations.ts, so operations-
layer code can never import capture.ts; the core module breaks that cycle.
capture.ts re-exports the public trio (detectBinaryNullByte, normalizeForHash,
mergeCaptureFrontmatter) and keeps its __testing seam, stdin reader, and the
FK-hint rewriter (CLI/thin-client-only concerns).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ops: get_job_stats — queue statistics + wedge signal over MCP
'gbrain jobs stats' was the one jobs verb with no MCP equivalent
(skills/minion-orchestrator documented the gap; every sibling verb has an op).
Admin scope for jobs-family consistency. Per-block scoping documented honestly
[EV10]: by_status/queue_health global, by_type windowed by since_hours, wedge
queue-scoped. The wedged-queue derivation moves to core/minions/queue.ts
(deriveWedgeSignal) shared by the CLI line, the doctor check, and the op, so
the three surfaces can never disagree (#1801). Adds the shared relation-
missing guard (withRelationGuard in ops/contract.ts [ENG-E2]) used by the
telemetry ops that follow: older brains get an actionable 'unavailable'
instead of a raw relation error. Renice/backpressure host diagnostics stay CLI.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ops: admin cluster — get_health migrations block + quarantine_list
get_health now returns migrations {pending, partial, wedged, skipped_future}
from the host migration ledger (closes TODOS:4063 — remote agents detect
wedged/outstanding host migrations without SSH). Composed at the OP layer
rather than the TODO's engine-method wording: the ledger is a filesystem
JSONL, engine-agnostic, so growing BrainEngine.getHealth would duplicate a
file read in both engines. New src/core/migration-ledger.ts owns the status
semantics (complete-wins, trailing-retry override, consecutive-partial wedge
cap) + compareVersions (canonical home; migrations/index re-exports), and a
version-strings-only MIGRATION_VERSIONS list [OV4/EV4] — pinned against the
real registry by test — so the ops layer never imports the migration
orchestrator. apply-migrations consumes the shared logic.
quarantine_list: read-only view of the content-quality gate (#1699) — the
shared collectQuarantineRows scan (pinned updated_desc order; bounded scans
set truncated and count is a LOWER BOUND [OV13]) behind both the CLI list and
the op. quarantine scan (bulk re-embed) and clear (the trust decision,
extraction_review class) stay CLI-only, recorded at the op.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ops: search cluster — search_stats, search_modes, search_tune, cache_stats
Read-only introspection ops sharing the extracted core builders with the CLI
(modes-report, tune-recommendations, telemetry, query-cache). search_modes is
read-scoped (resolved knob values so agents can budget their own calls);
search_stats/search_tune/cache_stats are admin-scoped operational telemetry
(the get_status_snapshot posture). search_tune has NO apply param — applying
recommendations stays CLI-only per CDX-21; the op returns paste-ready config
commands to relay to the user. All four ride the shared relation-missing
guard so older brains degrade with an actionable 'unavailable'. Tests pin the
dashboard shapes (glossary blocks per CDX-25), knob attribution, the
insufficient-data tune path, the no-config-mutation guarantee, quarantine
marker detection + the truncation lower-bound contract, and source scoping.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ops: takes write verbs — takes_add, takes_update, takes_resolve, takes_supersede
Agents could read the predictions ledger but never record, refine, resolve,
or supersede a take — the highest-demand gap in the CLI→MCP audit (gstack's
calibration write-back is gated on takes_add existing). Backed by the shared
md-canonical write-through core: fence-derived row numbers, markdown first,
DB mirrored with the reconcile primitive, and refusal (detail
takes_mirror_unavailable) when the host has no markdown repo [EV1].
Trust model, ungated by design (put_page precedent — argued at the cluster):
the holder WRITE fence reuses the read allow-list fail-closed (stdio default
['world']; [] deny-all; row-targeting verbs require the TARGET row's holder in
the list, and a fenced row presents as not_found, the same shape as a missing
row [CEO-F4] — existence-by-count via dense row numbers is documented as
accepted [OV10/EV3]). resolved_by is server-stamped mcp:<client> for remote
callers (clamped) and takes_scorecard gains an op-layer mcp_resolved count so
agent resolutions stay segregable from owner ground truth [OV8/EV5] (the
calibration curve stays a bare array — decorating it would break its shape).
Lock waits cap at 2s and contention maps to a retryable envelope [OV12].
Tests drive dispatchToolCall against a real engine + temp markdown repo:
fence round-trip incl. create-on-first-take, all four fence axes wired
through dispatch [CEO-F8], no-existence-leak shape equality, immutability of
resolved rows, supersession inherit/decay/pointer mirroring, server-stamp
spoof rejection, mirror-mandatory refusal, dry_run, and concurrent adds
landing sequential rows with no silent overwrite [ENG-E4/EV11].
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ops: capture over MCP — starter-surface membership + the FAQ retirement (D2A)
The documented ingestion entrypoint agents kept reaching for: three docs plus
the generated onboarding text carried 'unknown tool: capture → use put_page'.
The op is thin sugar that DELEGATES to put_page with the same ctx (inheriting
the slug fence, dedupe, unknown-type audit, write-through, remote auto-link
skip) after the guards agents had to hand-roll: stable content-derived default
slug (idempotent recapture), frontmatter merge, NUL/empty refusal. Remote
provenance stays the honest CV6 stamp mcp:put_page; results carry
channel:'capture'. No file param over MCP (host-side lane stays CLI).
Surface [EV8]: capture joins STARTER_OPS + ALWAYS_INCLUDED_STARTER_OPS as a
DIRECT literal — deliberately not via BRAIN_TOOL_ALLOWLIST (that would grant
every minion subagent a new write tool) — and the plugin README's op count is
now derived from STARTER_OPS.size instead of a hardcoded string [EV9].
[EV7] slug-bound clients get their zero-config path: the default slug nests
under the first bound prefix, and capture + the takes write verbs join
CLIENT_FENCED_WRITE_OPS (each enforces the slug fence internally — the
put_page/add_tag guarantee). FAQ retired across the 4 places with the
narrowed-token hedge [EV12]; LEARN_INSTRUCTION now teaches the capture/
put_page split and its pinned test verifies every named tool is a real op.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* cli: thin-client routing for the new ops — takes, search dashboards, jobs stats, cache stats, quarantine list
The thin-client CLI is the biggest legitimate remote caller of the new ops
[OV6]: takes was wholesale refused with a stale hint, and search stats on a
thin client fabricated a scratch PGLite. New engine-free routing module
(src/commands/thin-client-routing.ts, the salience/anomalies precedent) maps
routable subcommands onto their ops over callRemoteTool: takes list/search/
scorecard/calibration + add/update/resolve/supersede (closing the TODOS:3793
routable list for takes), search modes/stats/tune (read-only forms; --reset /
--apply / diagnose stay host-side per CDX-21), jobs stats via get_job_stats,
cache stats, quarantine list. whoknows needed nothing new — runWhoknows
already routes internally and commit 1 made it reachable. Unhandled
subcommands fall through to refuseThinClient, whose hints now name the
routed ops and the takes mirror-mandatory posture. Both module-size ceilings
raised consciously in the TSV (cli.ts +23 call sites; queue.ts +24 for the
shared wedge helper from the get_job_stats commit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: TODOS + skill truth-up for the gap-closure wave
Marks the get_health migration-introspection TODO done (with the op-layer-
composition rationale recorded at the closure), annotates the rotate_token
TODO with the D3A deferral sketch (self-rotation-only, one-shot secret, own
auth-plane pass — there is no CLI to mirror yet, so it was never a CLI→MCP
gap), and files the wave's three P3 follow-ups: the takes read/write holder
axis split, pack-aware takes-kind validation, and the mcp:capture provenance
channel label. minion-orchestrator now names get_job_stats (MCP, admin-scope
note) where it documented 'CLI; no MCP equivalent'.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ops): no raw pipes in op descriptions — they break the tool-catalog table cells
The takes_add/takes_resolve enum prose used ' | ' separators, which the
generated markdown catalog renders as extra table cells (caught by
test/tool-catalog.test.ts's starter-column pin). Slashes/commas instead.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* review: pre-landing hardening — fence-injection guards, row-inactive, EV7 slug, thin-client tests
Pre-landing review army (7 dimensions + adversarial) surfaced one CRITICAL
class and a set of correctness/coverage gaps; all folded here.
CRITICAL — takes-fence injection (remote write ops now accept free-text that
lands in the markdown-canonical fence): src/core/takes-write.ts gains
assertSafeCellText (rejects control chars incl. newlines + the 'gbrain:takes'
marker substring so no cell can mint rows or terminate the fence),
assertValidWeight ([0,1] — matches the DB clamp so md and DB can't diverge),
and assertValidSinceDate; applied across add/update/supersede/resolve. New
'invalid_input' TakesWriteError → invalid_params. Ops also validatePageSlug
after the client fence (defense-in-depth), and takes_resolve sanitizes the
server-stamped mcp:<clientId> so a hostile DCR name can't carry newlines/pipes
into the fence.
Correctness: row_inactive now guards update AND resolve (not just supersede —
a superseded row's mirror upsert would wipe its superseded_by pointer);
resolveTakeOnPage hoists the shared resolveArgs so the self-heal retry can't
diverge. EV7 capture bound-prefix slug nests the WHOLE default (fixes the
diary/event double-segment bug 3 specialists caught). BrainHealth.migrations
type truthed-up to the emitted shape. thin-client resolve gains the --outcome
back-compat lane; malformed routable subcommands print the host usage + exit 1
instead of a misleading host-bound refusal.
Maintainability: flag-registry generator excludes the pure-router module (was
bleeding takes/quarantine flags into the jobs allowlist + --rebuild into
takes); deriveWedgeSignal static-imported; TUNE_MIN_CALLS interpolated;
quarantine bounds named once; dead break removed.
Coverage: new test/thin-client-routing.test.ts (28 tests, all 14 routes +
malformed + host-bound fall-throughs); capture-op NUL fixture de-binaryized +
fenced-typed slug test; client-slug-fence extended to the 4 takes verbs;
get_health op-layer migrations + ledger_unreadable pins; takes-write
invalid_input/row_inactive/mirror-absent/foreign-scope tests; whoknows
CLI_ONLY reachability pin; CAPTURE_DESCRIPTION phrase pin; deriveWedgeSignal
env-isolated; e2e roundtrip capture assertion flipped to advertised.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* review: adversarial-pass P1 hardening for the remote takes write sink
Two independent adversarial passes (Codex + Claude) caught a data-loss class
the 7-dimension specialist army missed: the takes MCP write ops are
markdown-canonical and reused the CLI's naive whole-fence-rewrite + plain-fs
pattern, unsafe once reachable by untrusted remote callers.
F1 (CRITICAL — cross-holder data loss): every row-targeting write re-rendered
the WHOLE fence from parseTakesFence().takes, which SKIPS rows it can't parse
(dup row_num, pack-extended kind outside the closed fact|take|bet|hunch set) —
a world-fenced caller editing a world row silently deleted another holder's
unparseable row it can't even see. Now: assertFenceRoundTrips refuses the
write (fence_unparsed → invalid_params) when parseTakesFence reports skipped
rows, naming the reconcile fix. Regression test pins that the cross-holder row
survives on disk.
P1-1 (source isolation): the file path came from the global sync.repo_path,
ignoring the page's per-source local_path — a source-scoped token wrote to the
wrong tree / clobbered a same-slug file. resolveTakesFilePath now mirrors
write-through's topology (source local_path → its root; else host repo with
default-at-root / non-default under .sources/<id>/) via resolvePageFilePath.
P1-2: writes go through isWriteTargetContained (symlink/traversal escape →
refused) + atomicWriteFileSync (temp+rename), matching write-through's
hardening. P1-4/F4: a failed DB mirror is now non-fatal (md is canonical;
reconcile heals) — returns success with mirror_warning instead of throwing,
so a retry can't duplicate the durable row. F2: assertSafeCellText rejects a
wholly ~~strikethrough~~ claim (would parse as inactive). F3: resolvedValue
renders full-precision, not through the 2-decimal weight formatter.
Peripherals: readSearchStats + query-cache stats re-throw relation-missing
errors so withRelationGuard surfaces 'unavailable' on un-migrated brains
instead of a healthy-looking zero; capture normalizes a legacy prefix/* bound
prefix + validatePageSlug on caller slug + honest capture-mcp provenance for
remote callers; quarantine tie-breaker documented.
Pre-existing findings filed as P2 TODOs (publish-gate fail-open [test-pinned],
parser pack-kind widening, ledger malformed-line honesty, quarantine SQL
projection) rather than drive-by flipped.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.12.0 feat(mcp): CLI→MCP gap closure — 11 new ops, capture, thin-client routing, honesty fixes
Version bump + CHANGELOG for the gap-closure wave. Closes the CLI-vs-MCP
surface gap: agents can now record/resolve takes, capture notes, read queue +
retrieval + cache diagnostics, and triage quarantine over MCP; capture joins
the starter surface; thin-client installs route the new ops; the stdio tool
catalog stops listing gate-off ops it would deny. Full wave: 15 commits
(11 new ops + get_health migrations block, 3 core extractions, 5 catalog-
honesty fixes, plus two rounds of pre-landing + adversarial hardening for the
newly-remote-reachable takes write sink).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: restore graceful telemetry/cache empty-stats contract; regen flag registry
Ship-suite triage of 3 failures on the final tree:
- readSearchStats/query-cache stats(): the P2-7 adversarial fix rethrew
relation-missing so the op guard could surface 'unavailable', but that broke
the long-standing best-effort contract (pinned by search-telemetry.test.ts,
relied on by the CLI dashboard): a pre-telemetry-table brain shows '0
searches', not a crash. Reverted to graceful-empty; withRelationGuard stays
on the ops for OTHER unexpected relation errors. Over-reach to satisfy a P2.
- flag registry: the adversarial-fix agents edited command files the generator
scans (thin-client-routing/quarantine/takes/search) after the last regen —
regenerated so the freshness guard passes.
- (the third failure, VERSION-matches-package.json, was a mid-run torn read
from the version bump; clean on a consistent tree.)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: truth-up starter-surface count + capture-over-MCP for v0.46.12.0
capture joined STARTER_OPS this wave (26 → 27), so four hand-maintained
docs drifted against the auto-generated TOOL_CATALOG.md (already ~27):
INSTALL.md, mcp/DEPLOY.md, protocol/MEMORY_VERBS_v1.md, and the surface.ts
entry in KEY_FILES.md — updated the count and added capture to the two
composition enumerations. Also corrected the connect.ts KEY_FILES entry:
LEARN_INSTRUCTION now names capture (a starter-surface MCP op), and the
serve-stdio-roundtrip test now asserts capture IS advertised — both were
still described as "capture is CLI-only, not an MCP tool". Regenerated
llms-full.txt (MEMORY_VERBS is inlined).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.14.0 chore: re-bump wave version past in-flight 0.46.12/0.46.13 claims
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.12.2 chore: re-bump to the next free micro slot
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* refactor(ze): ze-switch becomes a truthful refusal/redirect shim
Every invocation now refuses or redirects; nothing mutates the brain.
The discovery surface was lying: --help printed the pre-deprecation
"switch onto ZeroEntropy" copy (and through the compiled binary never
even reached printHelp — the CLI_ONLY short-circuit answered with a
generic stub). A downstream agent read that copy and recommended
switching ONTO the provider that shuts down 2026-09-04.
- Wire ze-switch into CLI_ONLY_SELF_HELP + SELF_HELP_WITHOUT_ENGINE
(arg-order wrapper) so the truthful help is reachable engine-free;
membership pinned by test/cli-help-without-brain.serial.test.ts.
- ze-switch.ts is now a ~170-line shim: --help (exit 0, canonical
migration command + playbook pointer), --undo redirects (prints the
exact migrate command from ze_switch_previous_snapshot; status
'redirected' + undo_command in --json; exit 1), everything else
refuses (status 'refused', reason provider_sunset, migrate field;
exit 1). Retired flags stay parsed so old scripts reach the refusal
instead of a pre-dispatch unknown-flag error.
- The legacy undo/dry-run ACTIONS are retired: apply/undo wrote
DB-plane config the post-v0.37 file-plane-canonical embed pipeline
never reads, and undo emptied vectors with no verified re-embed.
Scripted `--undo --non-interactive --confirm-reembed` now prints
guidance instead of acting; `--dry-run --json` flips
status planned->refused and exit 0->1 (both noted for CHANGELOG).
- DELETE src/core/retrieval-upgrade-prompt.ts (zero test coverage,
sole importer was the dead interactive branch; removes the shipped
"Switch to ZeroEntropy (RECOMMENDED)" banner copy).
- Planner survives as a test vehicle (multimodal pins + env-gate
cases); stale state-diagram/resume-hint/1024d comments trued up.
- graph-embedding.ts width-consistency docblock no longer claims a
ze-switch --resume hint; KEY_FILES entries updated to current state.
- Flag registry regenerated; ze-switch-cli tests rewritten to the
shim contract (refusal matrix, redirect envelopes, corrupt-snapshot
degradation, exit codes, binary-reachable help assertions).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(providers,doctor): sunset-aware provider env + migration-first key hint
Two surfaces still funneled users toward a provider with an announced
shutdown:
- `gbrain providers env zeroentropyai` printed a clean signup funnel
(dashboard URL + "get an API key" hint) with no deprecation note.
runEnv now renders through the pure `formatEnvOutput` formatter:
recipes with `recipe.sunset` get the deprecation block + replacement
models + the canonical migration command INSTEAD of the funnel; key
STATUS still renders so existing users see what's configured. Living
providers are unchanged. Generic on recipe.sunset, so future sunsets
inherit the behavior.
- `gbrain providers explain`'s HUMAN embedding table printed sunsetting
providers as green-check cheap options (deprecation lived only in
cons/JSON). Rows now carry the DEPRECATED marker.
- doctor's ze_embedding_health missing-key hint said "get a key at
dashboard.zeroentropy.dev". Migration-first now: the fix is the
off-ramp; the key path survives as the secondary note for the
remaining hosted window.
One shared `sunsetMarker()` feeds list/explain/env so the three
renderings can't drift; `formatEnvOutput` guards a missing
`sunset.replacement` (no "undefined" prints). providers.ts joins the
canonical-migration-command consumer sweep; flag registry regenerated
(providers row picks up literals from the defaults.ts import).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(ze): de-market zeroentropy.md, neutralize historical imperatives
Docs and agent-readable skills still carried live encouragement toward a
provider with an announced shutdown:
- docs/ai-providers/zeroentropy.md: Setup section retitled "existing
brains and self-hosters only — do not onboard" (signup link gone),
price-comparison sell lines dropped (factual specs kept for
self-hosters), the opt-in-on-conservative recipe replaced with
voyage-first guidance, cost-anchor pitch deleted, banner updated to
the ze-switch shim contract.
- skills/migrations/v0.36.2.0.md + v0.35.0.0.md: banners strengthened
("Do not execute any command in this file"); the imperative playbook
sentences ("Recommend switching", the --force re-open tip, the era
opt-in recipes) neutralized to past-tense historical record — a
banner above contradictory instructions is instructions an agent can
follow past; frontmatter headline/feature_pitch prefixed HISTORICAL
(agent-skim metadata). Version references intact.
- docs/designs/2026_05_EVAL_PLAN.md: the smoke block's "All four MUST
exit 0" imperative scoped to the non-ZE commands; ZE lines annotated
historical.
- docs/guides/embedding-migration.md: schema transition attributed to
the survivor module, not the retired ze-switch.
- scripts/llms-config.ts: index description reframed from setup-funnel
to off-ramp.
skills.lock.json + llms bundles regenerated in the same commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(todos): truth up the v0.47 ZE-removal checklist
Annotate what the interim ZE cleanup wave completed early (prompt module
deleted, ze-switch is a shim, providers env/explain sunset-aware, doctor
copy migration-first) so the September wave doesn't re-plan it; refresh
the stale e2e.yml line refs (:168,:179 drifted to :239/:250/:377) and
note the cli-help-without-brain list entry that dies with the shim.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes (specialist findings, all informational)
- ze-switch --undo reranker fidelity (data-migration specialist): a
snapshot with reranking disabled but a model id still set now prints
--reranker off — enabled:false wins over the lingering model, matching
what the retired undo action restored. The old precedence would have
re-enabled a reranker the pre-switch brain had off.
- ze-switch snapshot hardening (security specialist): model ids must
match [A-Za-z0-9._:-]+ and dims must be a positive integer before they
interpolate into the printed return-path command / undo_command JSON
(the snapshot row is data-plane content); a throwing engine.getConfig
now degrades to the refusal instead of crashing; invalid shapes refuse.
- providers explain-row marker now renders through the shared
sunsetMarkerText primitive (maintainability + testing specialists) —
the docstring's "can't drift" claim is true again, and the row picks
up the replacement tail.
- Wording truth-up: retired flags are REGISTERED (registry-row literals),
not parsed — comment, help copy, and KEY_FILES entry no longer send a
maintainer hunting for parse logic.
- Coverage gaps closed: enabled:false+model precedence pin, no-model arm,
junk-dims + shell-metachar snapshot refusals, getConfig-throws case,
sunsetMarkerText unit, positive message/Replacement assertions,
keyless (ollama) + optional-env formatEnvOutput arms.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: red-team review fixes (guidance loop, dispatch refusal, flag-shape guard)
- A failed --undo no longer tells the user to run --undo (guidance loop
an agent following printed instructions would spin on); the three undo
failure states (missing / invalid / read-error) now word the refusal
truthfully instead of claiming "no switch recorded" for a brain whose
snapshot failed validation.
- cli.ts dispatch connects the engine ONLY for --undo: on an
unconfigured machine every other invocation now reaches the
provider_sunset refusal (with the --json envelope) instead of dying
with "No brain configured" — the exact old-script contract the shim
promises. Pinned end-to-end by a spawned-CLI empty-GBRAIN_HOME test.
- MODEL_ID_RE now requires provider:model shape with a leading
alphanumeric, so a snapshot value like "--force-sunset-target" can
never inject a flag into the printed return-path command.
- RETIRED_FLAGS exported + registry-row superset pin: the
refusal-instead-of-unknown-flag promise lives in the GENERATED row,
and a future help-copy trim would silently drop it without this test.
- Stale live-code comments swept: dims.ts OpenAI-dim note and
embedding-migration.ts header no longer describe the retired
ze-switch --undo action as a live path.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial review fixes (multi-brain fidelity, envelope truth, validation width)
Cross-model adversarial pass (Claude subagent + Codex adversarial + Codex
structured review). All findings informational-or-P1-on-CI, all fixed:
- Multi-brain fidelity (Codex P1): --brain is stripped pre-dispatch, so
`ze-switch --brain team-x --undo` printed a command targeting the
DEFAULT brain — a paid re-embed of the wrong corpus. Every rendered
command (undo redirect AND canonical refusal) now carries the explicit
brain selector; pinned by pure-builder tests.
- Ratchet truth (Codex structured P1): the red-team commit grew cli.ts
past the ceiling it had just set; ceiling now pinned at the exact
count so `bun run verify` is green again.
- Envelope truth (both models): `migrate` and `undo_command` are now
the LIVE commands with `migrate_preview`/`undo_preview` carrying
--dry-run — an agent executing the named field can no longer exit 0
on a preview and believe it migrated.
- Validation width (both models): MODEL_ID_RE now admits nested ids
(ollama:model:tag, openrouter:org/model) so legitimate snapshots stop
being reported as failed validation; string-"false" reranker state is
rejected (it would have re-enabled a paid reranker); injection guards
unchanged (leading-alnum, no whitespace).
- --undo on a brainless/unreachable machine now degrades through a null
engine to the truthful refusal envelope instead of connectEngine's
plain-text exit (spawn-pinned); --json=true spelling honored;
--markdown restored to the retired set (old scripts reached it);
redirect message carries a snapshot-recency caveat; deprecated explain
rows lead with ⚠ instead of a green check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.12.0)
Full version lockstep: VERSION, package.json, the three plugin
manifests, the bootstrap runbook stamp, bun.lock, and the regenerated
template + plugin trees.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.46.12.0
KEY_FILES.md: extend the zeroentropyai.ts recipe entry's sunset-metadata
consumer list with the shared sunsetMarker renderings, and add the missing
src/commands/providers.ts entry (discovery surface + the sunset-marker
primitive the v0.47 removal wave inherits).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: apply cross-model doc-review fixes for v0.46.12.0
Scope the CHANGELOG --brain claim to the JSON envelopes (the engine-free
--help renders the generic command); document the full refusal/redirect
envelope field sets in KEY_FILES.md; extend the ZE sunset-surface
inventory in embedding-providers.md and zeroentropy.md with the
providers env/explain and doctor surfaces this release shipped.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(gateway): give routed Claude 5 models output headroom
* chore(verify): raise gateway.ts ratchet 4116 -> 4117 for this fix
The thinking-model detector fix adds one line to src/core/ai/gateway.ts,
which sits exactly at its ratchet ceiling on current master (4116/4116).
check:module-size therefore fails on rebase even though every other
check passes.
Raising the ceiling by exactly the delta (+1), in the same commit as the
change, is the reviewer-visible path the guard documents. No peel is
warranted for a one-line regex fix.
verify: 54/54 green with this bump.
---------
Co-authored-by: gbrain-contrib <gbrain-contrib@example.com>
Co-authored-by: sina <sina@sinas-Mac-mini.local>
Co-authored-by: time-attack <time-attack@users.noreply.github.com>
The SELF_HELP_WITHOUT_ENGINE doc comment names
`test/cli-help-without-brain.test.ts` as the behavioural oracle for
membership in that map. That path has not existed since the file was renamed
to `.serial.test.ts`, so the one pointer that tells a contributor where to add
their pin resolves to nothing.
Comment only — no behaviour change. Repo-wide grep for the old path finds no
other reference.
Claude-Session: https://claude.ai/code/session_01SMJA4RCTXLgsXjPM4o1qcP
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
`lock-busy error message includes PID + hostname + age + --break-lock hint`
fails on any machine without an embedding key configured. The scenario shells
out to `gbrain sync --repo … --full --yes`, which refuses before it ever
reaches the lock check:
Embedding model "zeroentropyai:zembed-1" requires ZEROENTROPY_API_KEY.
Set it in your shell, or:
• Re-run with --no-embed to import-only and embed later once the key is set.
so the assertion on `pid <n>` matches the credential error instead of the
lock-busy message. Passing `--no-embed` — the remedy that error itself
suggests — lets the run reach the lock and assert what the test is named for.
The test is about lock recovery, not embedding, so it should not depend on
provider credentials being present.
Verified all four combinations against a scratch Postgres:
key present, before 7 pass / 0 fail
key present, after 7 pass / 0 fail
key absent, before 6 pass / 1 fail
key absent, after 7 pass / 0 fail
Noticed while running the DATABASE_URL-gated e2e suite on a developer machine;
CI presumably has a key in the environment, which is why this stays green
there.
Co-authored-by: Javan <javan@JavandeMac-mini.local>
* fix(backlinks): frontmatter-safe fixer — canonical body offset, validate, atomic write, page lock
The check-backlinks fixer could glue a generated timeline bullet above the
frontmatter fence (naive split on '## Timeline' matched inside YAML and as a
substring of longer headings; byte arithmetic then landed the insert at byte 0),
breaking YAML parsing for the whole page. The write was also a bare
writeFileSync: non-atomic, unvalidated, unlocked.
fixBacklinkGaps is now a safety pipeline per target file:
- pre-validate with parseMarkdown({validate:true}); fence/YAML-broken pages
(YAML_PARSE / MISSING_CLOSE / NULL_BYTES) are skipped and reported,
byte-identical. MISSING_OPEN is deliberately NOT a blocker: legacy pages
without frontmatter have no fence to corrupt and stay fixable.
- insertion anchors only on a real '## Timeline' heading line (CRLF-tolerant)
at/after the canonical frontmatter body offset (new markdown.ts
frontmatterBodyOffset, mirroring collectValidationErrors' fence semantics);
first heading wins deterministically; near-misses ('### Timeline',
'## Timeline (2026)') never match.
- post-validate the candidate, then write via new src/core/atomic-write.ts
(unique tmp sibling + fsync + mode preservation + on-disk re-validation
before the atomic rename). Migrating the older per-module atomic-write
copies is a filed follow-up.
- each file is wrapped in withPageLock + try/catch: one bad page or write
error isolates to a skip entry instead of killing the batch.
fixBacklinkGaps returns {fixed, skipped[]}; BacklinksResult carries the skip
report (additive), the CLI prints it, and the fix loop runs under a new
backlinks.fix progress phase. Dead sourceDir var removed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(sync): reject malformed filenames at import — classifier reason, delete-lane carve-outs, doctor discovery
Files literally named like markdown links polluted search because
slugifySegment STRIPS brackets instead of rejecting them, minting
plausible slugs for junk files. New SyncableReason 'malformed-path'
(brackets + ASCII control chars; parens deliberately legal) rejects such
filenames at every ingestion route: classifySync (incremental sync),
isCollectibleForWalker (bulk import, both FS-walk and git fast-path),
and a defense-in-depth check in importFromFile for direct callers.
The subtle halves (both caught by outside-voice review):
- Deletions and reconciles must still SEE malformed paths. manifest.deleted
is filtered by isSyncable, and the full-sync reconcile requires
isSyncable(source_path) — naively classifying junk as unsyncable would
have orphaned previously-ingested rows forever. Both lanes now carry an
explicit malformed-path carve-out, so deleting a junk file removes its
DB row, editing one sweeps its stale row, and a full sync reconciles
poison away even while the junk file still sits in the repo. Classifier
ordering (strategy before malformed-path) keeps the reconcile
strategy-safe; the #1433 metafile protection is untouched.
- Malformed skips are INFORMATIONAL, never failures. importFromFile marks
them skip_reason='malformed_path'; sync's failure classification keeps
them out of failedFiles and the failure ledger (they can never gate
bookmark advancement) and checkpoints them as done. Surfaced instead in
the dry-run listing, a summary count, SyncResult.malformedSkipped, and a
new doctor check (malformed_path_pages) that reports existing poisoned
rows with the reconcile fix hint.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(schema): warn on alias/undeclared explicit frontmatter types at ingest + lint
An explicit frontmatter type that is an ALIAS of a canonical pack type (or
undeclared entirely) is stored literally and never re-normalized, so agents
can silently file the same concept under different types and directories.
gbrain can't stop agent-side filing decisions; it can make every
non-canonical explicit type loud.
- src/core/schema-pack/type-usage.ts: classifyStoredType(type, pack) →
canonical | alias_of (with the canonical type + its path_prefixes[0]
filing directory) | undeclared; sanitizeTypeForDisplay (control-char
strip + length cap for terminal hygiene — type strings come from
frontmatter); renderTypeWarningSummary (once-per-type lines).
- importFromContent classifies at the typeExplicit site and returns an
advisory ImportResult.type_warning — the type is still stored as-is,
zero filing behavior change.
- gbrain sync + gbrain import aggregate warnings once per distinct type per
run (O(types), not O(files)) to stderr, and sync carries the counts on
SyncResult.type_warnings so worker-driven syncs surface them in job
results where daemon stderr is invisible.
- Two data-plane schema lint rules (stored_type_is_alias,
stored_type_undeclared) audit the EXISTING corpus via gbrain schema lint.
- Config off-switch schema.type_warnings (default on) registered in the
known-keys list; lint rules stay active regardless.
Acknowledged limit: this warns at ingest and audit — it cannot prevent
routing that happened in the agent's filing layer before import.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(scoping): close the unscoped-check/scoped-write bug class — writer, import, integrity + CI guard
engine.getPage without opts matches a slug in ANY source while putPage
defaults to 'default' — an existence check can succeed against source B
and the paired write then targets a different row (duplicates, clobbers,
spurious slug disambiguation; this class broke dream cycles for weeks).
Fixes:
- SlugRegistry + BrainWriter/WriteTxImpl thread a sourceId (default
'default') through every probe, read, write, addTimelineEntry, and the
validator pass (which previously hardcoded 'default' regardless of the
pages being validated).
- integrity auto uses one writer PER SOURCE, and its resume progress is
keyed by (source_id, slug) instead of slug alone — a resume no longer
skips same-slug pages in other sources (legacy slug-only progress
entries match the default source).
- import-file reads flip from any-source-when-unset to the canonical
{ sourceId: sourceId ?? 'default' } (mirrors the writes' schema
default). Caller audit: every importFromContent/importFromFile call
site either passes sourceId explicitly or is default-source-intentional
(brain-global synthesis artifacts, eval sandboxes) — none relied on the
any-source fallback.
- quarantine clear resolves the target source deterministically: new
--source-id flag; without it, an ambiguous multi-source slug errors
with the candidate list instead of acting on an arbitrary row.
- link-extraction's exact-probe steps reuse the resolver's source scope
(same posture as its basename index).
- Both engines' unscoped getPage gains a deterministic tiebreak:
ORDER BY (source_id = 'default') DESC, source_id ASC — default-first,
then stable alpha (plain LIMIT 1 returned an arbitrary row).
Guard: scripts/check-getpage-scoped-write.mjs (comment/string-aware span
scanner) fails the build when a file contains BOTH an unscoped or
ternary-undefined getPage AND a write-path call; opt-out marker
gbrain-allow-unscoped-getpage for documented read-only first-match sites.
Wired into verify CHECKS + guards-manifest + bad/good fixtures + unit
test; the grandfathered allowlist is empty.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): queue admission control — param-coalescing, waiting-TTL, quota + divergence alerting
The submit-side half of the queue-divergence incident (drain-side pool
starvation landed in v0.46.1.0): subagent intake ran ~25x drain with no
backpressure, no expiry, and stats that couldn't even express the
divergence. Admission-side only by design — claim fairness / lane
scheduling is a filed follow-up, not this wave.
New src/core/minions/admission.ts (per-name defaults tables, the
handler-timeouts.ts pattern; config under the new 'minions.' prefix;
GBRAIN_MINIONS_ADMISSION=0 kill-switch; fail-open to defaults with a
once-per-process warning):
- PARAM-COALESCING (default on for subagent): an identical parentless
submit — same (name, queue, payload hash) — returns the newest matching
WAITING row with coalesced:true instead of enqueuing a duplicate.
__owner_client_id is INCLUDED in the hash so owner lanes never cross;
parented submits never coalesce (aggregator bookkeeping); matches are
age-bounded to ttl/2 so a fresh submit can't coalesce onto a
nearly-expired row and silently die an hour later; waiting-only (a
running job never suppresses a re-run). Audited via the existing
backpressure JSONL.
- WAITING-TTL (default 48h for subagent): the worker's 4th maintenance
sweep cancels jobs still waiting past their TTL — through the canonical
cancel path (new cancelJobs(ids, {reason}) batch variant: one
transaction, descendant cancellation, child_done inbox messages,
aggregator-parent resolution — a raw UPDATE would wedge parents in
waiting-children), capped at 500/tick, oldest-first, with a reason
error_text every alerting surface keys on (the single-id cancel path
never wrote one). Warn-before-act: tick 1 counts + warns + sets
minions.ttl_notice_shown, sweeping starts tick 2; gbrain upgrade prints
the same one-shot notice on the interactive channel.
- NAME-GLOBAL QUOTA (config-only, NO shipped default per operator
decision): waiting count for a name across ALL queues (per-run private
fanout queues can't dodge it) at/over minions.quota_max_waiting.<name>
rejects with a typed QueueQuotaExceededError; approximate under
concurrency, documented as a backstop. Dream submitters
(synthesize/patterns) record the rejection as a phase skip — never a
phase crash.
Alerting: getStats by_type gains drained_completed/failed/dead/cancelled
(true outflow keyed on finished_at, split so TTL-cancel storms can't
masquerade as throughput), waiting_now, and oldest_waiting_minutes.
jobs stats gains Drained/Waiting columns, a --json document, a per-type
DIVERGENT-QUEUE scream (intake > GBRAIN_QUEUE_DIVERGENCE_RATIO x
completed with waiting > GBRAIN_QUEUE_DIVERGENCE_MIN_WAITING) carrying
the quota opt-in hint, and a 24h waiting-TTL cancellation report. doctor
checkQueueHealth screams the same divergence + TTL activity. The
advisor's stalled-jobs fix command now points at the real subcommand
(jobs stats; 'jobs status' never existed).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: five-issue fix-wave reference updates — KEY_FILES, TODOS, invariants, flag registry
- CLAUDE.md source-isolation invariant gains the unscoped-check/scoped-write
corollary + the new guard's opt-out marker (llms bundles regenerated in the
same commit per the CLAUDE.md-edit rule).
- KEY_FILES.md: current-state entries for src/core/atomic-write.ts,
src/core/minions/admission.ts, src/core/schema-pack/type-usage.ts, and
scripts/check-getpage-scoped-write.mjs.
- TODOS.md: six wave follow-ups (atomic-write migration + page-lock
unification, splitFrontmatter relocation, admission/stats indexes, getPage
type-boundary redesign, per-name claim fairness, per-queue divergence
scoping) and the existing --max-pending entry now notes param-coalescing as
the shipped payload-distinct dedupe primitive.
- docs/progress-events.md: new backlinks.fix phase (additive).
- Flag registry regenerated for quarantine --source-id; scrubbed a
prose-bleed '--refresh' token that page-lock.ts's comment would have
injected into check-backlinks' allowlist via the new import edge (the
known generator pitfall — flags in comments must be spelled dash-less).
- test/minions-admission.test.ts: env mutation moved onto withEnv (test
isolation guard).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): empty payloads never param-coalesce — no dedupe signal
Full-suite fallout (budget-tracker.test.ts): scaffolding jobs submitted with
literal {} data hashed identically and coalesced into one row, collapsing the
tests' owner/child fixtures. Two no-param submits are far more likely distinct
placeholder jobs than a runaway producer (which always carries a prompt), so
add() now skips coalescing when the payload has no keys beyond __param_hash.
Pinned in test/minions-admission.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial-review hardening — 15 confirmed findings across the wave
A 35-agent adversarial verification pass (5 dimension finders, 2 independent
skeptics per finding) confirmed 15 defects the suites missed; all fixed:
Queue (the serious ones):
- P0: waiting-TTL keyed on created_at cancelled jobs the SAME maintenance
tick had just requeued/retried/promoted (those paths bump updated_at, not
created_at) with a factually-false 'waited > Nh' reason. The sweep, the
notice counts, and the coalesce age-bound all key on updated_at now — a
state transition refreshes the TTL window; pure-waiting backlog semantics
unchanged.
- P1: the sweep's SELECT→cancel race could cancel a JUST-CLAIMED active job
(claimer and sweep both target the oldest waiting rows). cancelJobs gains
rootStatuses to re-check status atomically inside the cancel CTE; the TTL
sweep passes ['waiting'].
- P1: param-coalescing silently discarded a caller's idempotency_key
(returned a row the key was never registered against → a later same-key
submit ran the work twice). Producer-owned idempotency now disables
param-coalescing outright — it is the stronger contract.
- P2: a quota rejection mid-fanout left aggregators torn
(children_ids never written). The fanout now cancels the whole tree and
surfaces the quota message — all-or-nothing.
- P2: the quota error message no longer includes the live global waiting
count (it travels to remote MCP clients via submit_agent; counts stay on
the error object and in local jobs stats).
Scoping:
- P1: reindex-code iterated ALL sources' code pages but re-imported with the
CLI-level sourceId (undefined without a source flag) — under the new
default-scoped reads that duplicated every non-default-source code page
into 'default' and re-embedded it. fetchCodePages now SELECTs source_id
and each page re-imports into its OWN source.
- P2: importImageFile kept the variable-bound unscoped-read ternary the CI
guard's inline heuristic can't see; flipped to the canonical
sourceId-or-default read.
Malformed paths:
- P2: the FS-walk route only checked basenames, so a bracket-named DIRECTORY
of clean files passed the walker (and its rows were unsweepable on non-git
brains); descent now applies the malformed-segment check.
- P2: doctor's malformed_path_pages SQL prefilter was brackets-only; a
[[:cntrl:]] regex arm covers control-character-only paths.
- P2: junk filenames are control-character carriers by definition — every
place sync/import echoes one now routes through sanitizePathForDisplay
(control chars → U+FFFD, length-capped) so a crafted filename can't inject
terminal escapes.
Filesystem:
- P2: atomicWriteFileSync documented mode preservation but open(2)'s mode
arg is umask-masked; an explicit chmod on the tmp file now actually
preserves the target's mode across the rename (group-writable brain repos
no longer lose their group-write bit on a backlinks fix).
Test honesty:
- P1: the divergence test's seed screamed under BOTH the correct
(completed-based) and naive (cancellations-count-as-drain) metrics;
reseeded so only the correct metric fires.
- P2: the backlinks frontmatter-safety fixtures used quoted mid-line
'## Timeline' strings that the ^-anchored regex ignores even without the
bodyStart guard; replaced with line-start YAML-comment forms that
genuinely distinguish guard-on from guard-off.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: ship pre-landing review fixes — guard regex, sanitization, TTL grace window
Pre-landing review army (5 specialists + red team) findings, all applied:
- check-getpage-scoped-write guard: catch the EXPANDED ternary
(x ? { sourceId: x } : undefined) and {}/null false branches the
shorthand-only regex missed; the sharpened probe immediately found one
latent expanded-ternary site in operations.ts (safe pattern — write keys
on the returned row's source_id — now carrying the documented opt-out).
- Terminal hygiene: job names from the MCP-exposed submit surface are
control/ANSI-stripped before echoing into jobs-stats + doctor screams.
- Waiting-TTL warn-before-act: one ~30s tick between warn and sweep was a
courtesy log line, not a warning. runWaitingTtlTick (admission.ts, testable
per the lock-renewal-tick pattern) now stamps an ISO timestamp and holds a
1h grace window (GBRAIN_MINIONS_TTL_NOTICE_GRACE_MS seam) before the first
sweep; the upgrade banner stamps the same clock; legacy 'true' flags sweep
immediately. Worker + upgrade share countTtlExpiredWaiting.
- TTL_REASON_PREFIX constant shared by the sweep reason + both LIKE
consumers (jobs stats, doctor); patterns parameterized.
- isQueueQuotaExceededError code-based guard replaces error-name string
matching in agent fanout, cycle patterns, synthesize; submit_agent maps
quota rejections to a structured rate_limited OperationError.
- Empty-payload coalesce guard derives from PARAM_HASH_EXCLUDED_KEYS.
- Red team: stored_type_is_alias lint hint pointed at a non-existent
'schema unify' subcommand — now points at the real unify-types job;
reconcile prints a distinct count for malformed-path rows (their files
usually still exist on disk — rename to re-import) instead of lumping
them into 'source file was removed'.
- integrity: one-time note when legacy (pre-source_id) resume-ledger
entries force a partial re-scan.
Tests: atomic-write direct unit (verify-abort, umask/mode preservation);
cancelJobs reason/rootStatuses direct; idempotency-key-disables-coalesce;
runWaitingTtlTick notice→grace→sweep + legacy flag + kill-switch; walker
bracket-directory descent; sanitizePathForDisplay unit rows; backlinks
multi-gap batch; quarantine clear ambiguity exit-2 + source scoping;
doctor divergence/TTL/malformed_path_pages; engine-parity unscoped-getPage
ORDER BY (DATABASE_URL-gated). TODOS: requeue surface, dream-path quota
integration tests, coalesce concurrency e2e, canonical-json consolidation,
reconcile quarantine option, cross-source clobber audit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial cross-model review fixes — bracket scoping, quota lock, writer scope
Step-11 adversarial passes (Claude subagent + Codex exec + Codex structured
review). Cross-model high-confidence finding, fixed: blanket bracket
rejection over-captured — Next.js/Nuxt dynamic-route paths (app/[id]/…)
in code-strategy lanes stopped importing AND their indexed rows became
reconcile-deletable; bare-bracket markdown files imported by pre-gate
releases would be hard-deleted by a routine post-upgrade full sync while
their file sat on disk. Two-tier fix in core/sync.ts: ADMISSION rejects
control chars anywhere + brackets on markdown paths only
(hasMalformedPathSegment); the row-DELETING lanes (reconcile, modified-lane
cleanup) act only on the poison signature isPoisonedPath (`](` or control
chars). Walker now checks the RELATIVE path per file (basename checks
can't see bracket directories) and descends bracket dirs for code lanes.
Also fixed:
- Name-global quota: pg_advisory_xact_lock('minion_quota:'||name)
serializes check+insert — concurrent distinct-payload submits could each
observe capacity and overshoot without bound (quota is now exact, not a
backstop; lock cost applies only to quota'd names).
- cancelJobs stamps the reason on ROOT ids only — descendants carried a
factually false waiting_ttl_expired text and inflated the LIKE-prefix
stats the alerting surfaces count.
- synthesize: a mid-transcript quota rejection now rolls back that
transcript's fresh (non-coalesced) chunk submissions — previously the
skip report said 'skipped' while earlier chunks drained and wrote
partial pages.
- BrainWriter: putRawData + addLink (both directions) now carry the
writer's source scope — unscoped they defaulted to 'default'-source rows
(both Codex passes flagged this P1).
- page-lock: acquisition is O_EXCL ('wx') — the existsSync→write sequence
let two stale-reclaimers both 'acquire' and lose one side's writes.
- atomic-write: writeSync loops until all bytes land (legal short writes
could atomically install truncated content) + best-effort parent-dir
fsync after rename.
- Copy-pasteable command hints gate untrusted names/types through strict
token checks (safeConfigSegment/safeCliToken) — display sanitization
keeps shell metacharacters, so injected names could ride into pasteable
commands (jobs stats, doctor, schema lint hints).
- admission isOffValue: case-insensitive + trimmed + 'no' — 'FALSE'/'Off'
silently left the off-switch ON.
- Walker/import/sync surface malformed-filename exclusions on BOTH
collection routes (git + FS-walk), in directory imports, full-sync
dry runs, and the totalChanges===0 up_to_date early return (a commit
whose only changes are malformed files advances the anchor past them
forever — now reported + counted in SyncResult).
- submit_agent response carries coalesced:true so remote clients can
detect param-coalescing instead of silently receiving an existing job.
Rejected (by design, documented): default-on subagent param-coalescing
semantics (user-approved; per-call + config opt-outs, response flag makes
it detectable).
Tests: markdown-scoped bracket rows + code-strategy framework paths +
isPoisonedPath units (shape suite); bare-bracket row SURVIVES reconcile
(serial suite); walker dir-descent pin retained via relative-path check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: current-state reference updates for the review-fix batch
KEY_FILES: SyncableReason union gains 'malformed-path' with the two-tier
admission/destruction semantics; admission.ts entry reflects the grace-window
warn-gate, exact quota lock, root-only cancel reasons, and the shared
TTL/quota helpers; atomic-write entry reflects the full-write loop +
parent-dir fsync. llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: raise module-size ceilings for wave growth + refresh structural manifest
Nine ratcheted modules grew with the five-issue wave's feature code
(admission control in queue/worker/jobs, malformed-path lanes in
sync/import-file, divergence findings in doctor, ORDER BY in both engines,
quota rollback in synthesize) — conscious TSV raises per the ratchet's
documented growth path. structural-suites.tsv regenerated for the new
test files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.11.0 fix: five-issue operational wave — backlinks corruption, queue admission, junk paths, source scoping, type visibility
Version re-bumped from the user-pinned 0.46.10.0: master claimed that
version mid-ship (queue collision; natural next off master).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.46.11.0
Post-ship /document-release pass for the five-issue operational wave:
- queue-operations-runbook: new DIVERGENT QUEUE section (jobs stats
Drained/Waiting columns, divergence thresholds, admission remediations,
GBRAIN_MINIONS_ADMISSION kill-switch) + doctor divergent-queue and
waiting-TTL subcheck entries
- minions-deployment: "jobs sit in waiting forever" nuanced for the
waiting-TTL (48h default for subagent)
- schema-packs: schema lint data-plane rules documented behind --with-db
(per-source scoping exists at the rule layer, not yet CLI-threaded);
ingest-time type warnings + schema.type_warnings off-switch
- minion-orchestrator skill: coalesced-submit semantics (treat as success,
monitor the matched id, never resubmit), waiting-TTL, rate_limited quota
backoff + anti-pattern bullet
- KEY_FILES: lint-rules entry 12->14 rules / 2->4 DB-aware,
guards-manifest count 48->52
- schema-author skill + tutorial: DB-aware rule list and 14-rule surface
- TODOS: filed P3 for threading --source-id into schema lint --with-db
(+ jobs stats --json usage line, agent-run coalesce hint)
- regenerated skills.lock.json, plugin/ tree, llms bundles
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* refactor(migrate): move schema-transition + env-gate primitives into embedding-migration.ts
Pure move, no behavior change: runSchemaTransition, transitionDimPinnedColumn,
TEXT_EMBEDDING_DIM_PINNED_TABLES, detectEnvOverride, EnvOverrideWarning, and
formatEnvOverrideWarning now live in the v0.47-survivor module;
retrieval-upgrade-planner.ts re-imports/re-exports for back-compat so the ZE
removal wave can delete the planner wholesale.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(engines,embed,doctor): status surfaces key on the stored vector, not embedded_at
A schema rebuild NULLs every vector without touching embedded_at, so
getStats().embedded_count, getHealth().embed_coverage, and the per-slug embed
path all reported a dark column as embedded. Both engines now key those
surfaces on `embedding IS NOT NULL`; coverage excludes embed_skip chunks from
BOTH sides (vacuous 100% when zero eligible); getChunks exposes a cheap
embedding_is_null boolean (no vector egress) consumed by the per-slug filter;
runSchemaTransition clears embedded_at post-commit in yielding batches; the
doctor embeddings check gains a custom-active-column carve-out note. Pinned by
test/embedding-truth-predicates.serial.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migrate): DB-verified skip, shared CLI/op orchestrator, migration locks, env-gate honesty, nullable signature
The skip path could declare "Nothing to migrate" from env-poisoned config
without re-probing the database — the only exit-0 route with no verification.
Replaced by verifyMigrationComplete (column + dim-pinned widths, wide stale
census, NULL residue, chunkless pages, marker, un-merged file plane) that
falls through into the idempotent resume flow when work remains.
- One shared runEmbeddingMigrationFlow-style orchestrator (planMigrationFlow +
executeMigrationFlow) consumed by BOTH the CLI and the migrate_embeddings op.
- Global brain-wide migration DbLock, then all-source embed locks (sorted,
archived included), threaded into the drain via heldLocks so the migration
cannot lock_skip itself; 5-min heartbeat with lock-loss abort (refresh false
or 3 consecutive errors ⇒ clean resumable stop, never silent racing).
- env==target now proceeds with a loud notice (env-first deployments are
legitimate); env≠target keeps the refusal and also blocks the verified skip.
- Marker v2: started_at preserved across resumes, --retarget required to
abandon a different in-flight target (history recorded), completion
bookkeeping is one transaction (no lost-receipt crash window).
- schemaRebuildNeeded shared by plan + apply (absent column ⇒ honest rebuild
copy, not a silent DDL); per-column dim-pinned repair; HNSW skipped above
the 2000-dim pgvector cap (2048d targets work via exact scan); same-width
ze-switch resume/undo no longer drop vectors.
- currentEmbeddingSignature() returns null when the gateway is unconfigured —
callers skip stamping instead of writing a wrong signature.
- persistEmbeddingFileConfig writes through the file-only loader (never
persists env-sourced keys) and supports env-canonical no-file deployments.
- Plan render: brain/DB identity (redacted), page-signature census,
concurrent-writer warning, outstanding-work blockers.
Pinned by test/migrate-embeddings-hardening.serial.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(migrate): --reranker companion switch — embeddings + reranker are one flow
New --reranker auto|off|keep|<provider:model> (op param `reranker`), default
auto: when the RESOLVED reranker (through mode-bundle defaults, not just the
explicit DB key — the common ZE case the old warning missed) is sunset-exposed
or riding the outgoing provider, the migration switches it to the target
provider's default reranker in the same consented run. Cross-provider targets
with no reranker get an explicit ACTION line (exact commands) — a third
provider's paid service is never enabled silently. The switch is probed live
before the write; probe failure keeps the previous config and is reported as
switch_failed, never silent, never fatal. Config write + query-cache purge
land in ONE transaction (rank order changes with the reranker). A resolved
switch/disable executes as a config-only completion even on a converged brain
— the verified skip no longer swallows it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(migrate,doctor): read-only --status surface + completion smoke check + migration-state doctor check
- `gbrain migrate embeddings --status [--json]`: config planes (env presence,
file, DB — API keys as PRESENCE booleans only, never values), column +
dim-pinned widths, NULL/chunkless/facts censuses, signature census,
context-tier count, in-flight marker verbatim (corrupt markers render, never
throw) with the exact resume command, and the last completion record.
- Completion smoke check (honestly labeled: self-retrieval, not a recall
eval): query-side embedQuery + vector search on up to 3 recent pages, hit
identity by page_id, never throws, warn-don't-block; the content-free
outcome is stamped into the completion marker and --status READS it (no
API spend on a read-only surface). Plan + completion also surface the
per_chunk_synopsis tier-downgrade count (consent before, receipt after).
- New doctor check `embedding_migration_state` (both doctor surfaces) turns
the previously write-only state marker into an operator signal with resume
+ status commands; the embeddings check's env-agree note and the
active-column fix hint no longer prescribe a nonexistent flag.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(migrate): account for completion smoke-check query embeds in flow/boundary pins
The completed path now runs 3 self-retrieval query embeds through the same
transport the tests count; interrupted and skipped paths run none (asserted).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(surfaces): one canonical migration command via ai/defaults.ts renderer
renderCanonicalMigrationCommands({colDims}) is the single home for the
sunset-migration command; the gateway deprecation line, init warnings, the
upgrade ACTION REQUIRED banner, doctor provider_sunset, the ze-switch refusal,
and the advisor all consume it. Kills the stage-1 banner booby trap (an
unsubstituted <provider:model> placeholder recommended with this brain's
current width as --dim — invalid on Voyage) and the no---dim variants. The
Voyage line always carries --dim 1024; the keep-width OpenAI alternative and
the rebuild note render width-aware. Drift-guarded by
test/canonical-migration-command.test.ts (src sweep; docs sweep lands with the
docs wave).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(jobs,remediate): background embed payload parity + NULL-signature cohort in remediation
The embed --background payload builder now serializes catchUp,
includeNullSignature, batchSize, and priority, and the `embed` +
`embed-catch-up` handlers read them back — the documented recovery command no
longer silently degrades to a plain 30-minute stale pass. The remediation
context probes the NULL-signature cohort upstream (engine-holding caller,
fail-open) and the embed.stale step fires on missing + cohort, widens with
includeNullSignature when the cohort exists, and counts the cohort in its
cost estimate — a pure-cohort brain (vectors present, provenance unknown) is
no longer unreachable by doctor --remediate.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(migrate): guess-free ZE-sunset playbook + doc truth-up across every surface
- skills/migrations/v0.46.3.0.md rewritten: Step 0 env preflight (the exact
var class that caused mid-migration flailing, with the unset command), Step
0.5 quiesce, DB-verified Step 5 (--status, not the env-poisonable doctor
chain alone), the reranker handled in the same command with the plane
asymmetry explained, a Recovery section (exit codes, kill/resume, locks,
wrong---dim, retarget, deferred re-embed), and the pending-host-work
completion edit spelled out.
- skills/RESOLVER.md routes provider/embedding/reranker-switch asks to the
playbook; gbrain-upgrade's anti-pattern rule carves out the ACTION REQUIRED
banner (route to the playbook, don't run blind); v0.35.0.0 + v0.36.2.0
playbooks carry HISTORICAL — DO NOT FOLLOW banners.
- docs/ai-providers/zeroentropy.md body no longer teaches switching ONTO the
dying provider; INSTALL.md's off-ramp points at the playbook + guide (not
the doc scheduled for deletion); embedding-providers.md drops the phantom
retrieval-upgrade flag; README repair hint names migrate embeddings;
embedding-migrations.md leads with the supported command; the
embedding-migration guide's env-gate + reranker claims now match the code
and document --status/--reranker; UPGRADING_DOWNSTREAM_AGENTS +
INSTALL_FOR_AGENTS carry the sunset pointer; llms.txt playbook range
un-pinned; KEY_FILES entries updated to current truth; three follow-up
TODOs filed (facts backfill, tier-preserving re-embed, standalone reranker
cache purge).
- Drift guard extended: docs/skills sweep (voyage command always pairs
--dim 1024; phantom flag banned) + playbook content pins. llms bundles
regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(fix): full-gate green — getChunks pin allows the null-boolean, RESOLVER triggers declared, registry regen
The #2544 structural pin keeps forbidding vector egress but now pins the one
allowed reference — the (cc.embedding IS NULL) boolean; the ZE-sunset playbook
declares its RESOLVER trigger phrases in frontmatter (round-trip guard); the
flag registry + llms bundles regenerate over the final string surface.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migrate): ship-review fix wave — envelope parity, DRY helpers, 17 new pins
Review-army findings applied on top of the 8-commit wave:
- envFullyPinsTarget: dims-only env no longer counts as pinning the target
(env-canonical persistence + verify conjunct; the genuine #1421-class gap).
- readDimPinnedWidths schema-qualified (pg_namespace join, relkind 'r');
targetDim sink guards in both DDL builders; marker shape validation in
readMigrationState; verify_search reason_code enum; keyset-cursor
embedded_at clear; reconcilePageSignatures model conjunct.
- Op/CLI envelope parity: locked keeps its holder discriminator on the op
surface; CLI --json refusals normalize to {status:'refused', reason}.
- renderResumeCommand consumed at all four resume-command sites; magic 60
TTL -> EMBED_BACKFILL_LOCK_TTL_MIN; printRetargetRefusal +
renderApplySummary helpers; dead EMBEDDING_MODEL/_DIMENSIONS exports
removed; module headers rewritten to current behavior.
- Plan render: HNSW-cap note for >2000d targets, custom
search_embedding_column caveat, honest env-warning copy.
- TEXT_EMBEDDING_DIM_PINNED_TABLES documents the takes.embedding omission
(trigram search path, no vector consumer).
- 17 new pins across migrate-embeddings-hardening (10),
migrate-embeddings-op-contract (5, new file), embedding-truth-predicates
(2): locks, env-key-leak, dims-only env, independent pinned repair,
same-width resume/undo, corrupt markers, retarget history,
self_retrieval_miss privacy, heartbeat throw-reset, empty brain,
op flattening contract, nullable-signature honesty.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(fix): full-gate green — reconcile seed mirrors post-drain chunk.model, registry regen
The reconcile pin now seeds chunk.model with the target model (what the
drain actually stamps) and adds a foreign-model page proving the new
model conjunct refuses to stamp pages a non-locked writer embedded in a
different space. Flag registry regenerated: the DRY move of the
retarget-refusal strings out of command files drops the phantom
--force-sunset-target attribution from maintain/remote.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.9.0 feat(migrate): guess-free embedding + reranker migration — DB-verified skip, truthful coverage, one canonical command
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(fix): password-less DATABASE_URL canary in the env-leak pin
The key-absence assertion doesn't need userinfo in the URL, and a
credential-shaped literal rightly trips the pre-push scanner.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: post-ship documentation audit for v0.46.9.0
/document-release sweep — four stale-doc fixes the ship's doc commit missed
(all drift against the migration-hardening wave's final state):
- docs/ai-providers/zeroentropy.md: the Re-embed + Verify subsections under
the off-ramp were leftovers from the deleted switch-ONTO flow — Verify
told a correctly-migrated 1024d brain its dims were invalid ZE config,
and Re-embed named a phantom `gbrain embed --limit` flag. Both now
describe the off-ramp reality: the migration drains + DB-verifies itself;
`--status` is the verify surface.
- docs/integrations/embedding-providers.md: doctor-repair sentence still
named `gbrain retrieval-upgrade` (README's parallel sentence was already
fixed in-branch); the voyage-code-3 switch recipe still prescribed
reinit-pglite instead of the supported `gbrain migrate embeddings` path.
- docs/guides/embedding-migration.md: "Resume after a kill" now documents
the `--retarget` refusal/abandon flow (shipped flag, was playbook-only).
- TODOS.md: filed P3 — `gbrain config set embedding_model` refusal still
prescribes wipe-and-reinit; should render via
renderCanonicalMigrationCommands and join the drift-guard sweep.
llms bundles regenerated (byte-identical — linked, not inlined); build-llms
freshness, canonical-migration-command drift guard, and
check-key-files-current-state all green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(changelog): fix doctor-check attribution in the 0.46.9.0 entry
Cross-model doc review caught a misattribution: the env-agreement note and
the custom-embedding-column carve-out shipped in the pre-existing
embedding_env_override and embeddings coverage checks, not in the new
embedding_migration_state check. All three behaviors are real and shipped
in this release; only the attribution was wrong.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(fix): hermetic reranker probe pins — CI has no VOYAGE_API_KEY
The flow's mid-run persistEmbeddingFileConfig reconfigures the gateway
from file+env, and the file plane carries no voyage key — so the probe
died on the key check before reaching the stubbed wire on CI, while a
real key in the dev env masked it locally. The harness now clears
VOYAGE_API_KEY with the other keys and the two probe tests set a fake
one explicitly, so the stubbed wire is what gets exercised everywhere.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(release): bump the two plugin manifests master's v0.46.7.0 merge added
.claude-plugin/plugin.json + .codex-plugin/plugin.json are new
version-lockstep locations from the plugins wave; the merge brought them
in at master's version and the lockstep pin rightly failed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(release): regenerate the committed plugin/ tree against the branch's skill edits
Master's plugins wave drift-gates plugin/ (check:plugin-tree in verify);
the branch's gbrain-upgrade carve-out needed mirroring into the curated
tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(gates): raise size-ratchet ceilings for the wave's module growth + structural manifest regen
Nine ratcheted modules grew with the migration-hardening wave (truth
predicates, heartbeat, orchestrator surfaces) which landed before the
containment sprint pinned ceilings from master's tree. Raised to current
sizes — the conscious-decision path the guard prescribes; the peel
backlog stays with the containment sprint's targets. Structural test
manifest regenerated for the wave's new suites.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
The v0.46.9.1 landing (#4173) re-versioned VERSION, package.json,
openclaw.plugin.json, and every derived stamp, but missed the two plugin
manifests added to the lockstep by #4167 — .codex-plugin/plugin.json and
.claude-plugin/plugin.json still said 0.46.8.0, so the merge-drift-catcher
test (test/codex-plugin-manifest.test.ts) correctly failed on master.
Bump both to 0.46.9.1; no functional change.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* refactor(guards): glob-proof path-keyed guards + wire engine-parity into CI before the module peels
Peel prep, no behavior change:
- check-engine-dynamic-import / check-source-id-projection / check-fuzz-purity
now also cover src/core/{postgres,pglite}-engine/ module dirs, so peeled
engine code cannot silently leave their scan sets
- select-e2e gains the src/core/ops/ escape-hatch prefix; e2e-test-map gains
** entries for the engine and doctor module dirs
- test/e2e/engine-parity.test.ts (33 behavioral parity tests) was never wired
into e2e.yml — tier1 now runs it as its own invocation line (verified green
locally against a dedicated pgvector container)
- 12 doctor source-text guard files re-pointed at test/helpers/doctor-source.ts
(containment assertions read the concatenated doctor surface; positional
assertions read the specific file), so the doctor peel cannot move a pinned
string out of a guard's sight
- test/resolver.test.ts derives op names from the operations array instead of
regexing operations.ts source (prerequisite for the ops domain split)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(guards): module-size ratchet — committed per-file line ceilings
check:module-size (in verify) enforces scripts/module-size-limits.tsv:
growth over a ceiling fails; >50 lines of stale slack after a shrink fails;
a row for a deleted file fails; any UNLISTED src file over 1,500 lines fails.
migrate.ts gets policy=region-exempt: the append-only MIGRATIONS array grows
freely while the ~668 lines of runner logic around it are ratcheted. Seeded
with all 28 src files currently over 1,500 lines at their exact counts; peels
lower their ceilings in the same commit as each move. Guard self-test fixtures
exercise both the plain and region-exempt failure modes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(test): behavioral-vs-structural suite classification with a freshness-checked inventory
scripts/classify-tests.ts classifies test suites by INTENT (content-based,
suite-level): structural suites assert on repo source/doc text (wiring
guards, drift pins, doctor-source consumers); everything else is behavioral.
Detectors cover repo-anchored readFileSync/Bun.file readers, grep-style exec
scanners, and the doctor-source helpers; unattributable read-primitive files
land in a surfaced unknown bucket. The committed inventory
(scripts/structural-suites.tsv) is regenerate+diff freshness-checked in
verify (check:structural-manifest), and docs/TESTING.md's file taxonomy gains
the intent axis. CI's coverage report renders the two counts side by side so
the headline test count stops conflating shape guards with executed behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(ops): extract the operations foundation — contract types + security/scope layer
Pure move, byte-verbatim verified: ErrorCode/OperationError/verbError and the
ParamDef/Logger/AuthInfo/OperationContext/Operation contract types go to
src/core/ops/contract.ts; the slug-fence + validation + scope-resolution layer
goes to src/core/ops/context.ts (formerly file-private fence helpers are now
exported there for the domain modules). operations.ts re-exports its entire
previous surface, so all 21 consumers and the published gbrain/operations
export are unchanged. Domain modules (next commits) import only from
ops/contract + ops/context — acyclic, no TDZ risk. operations.ts 7,459→6,423;
ceiling ratcheted.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(ops): peel pages/search/takes/tags/links/timeline domains out of operations.ts
Six domain modules under src/core/ops/, each exporting its <domain>Operations
array, spread into the operations array at the exact original positions —
operations.map(o => o.name) is byte-identical before/after (114 names), so
the generated tool catalog and every array consumer are unchanged. Modules
import only from ops/contract + ops/context (acyclic). MANAGED_LINK_SOURCES
stays re-exported from operations.ts for its existing consumers.
operations.ts 6,423→4,675; ceiling ratcheted.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(ops): peel admin/skills-catalog/sync/raw-data/chunks/ingest-log/files/jobs/orphans/calibration/salience domains
Tranche 2 of the operations.ts peel: 39 ops moved verbatim into 11 domain
modules, spreads at exact original array positions — operations.map(o=>o.name)
byte-identical (114 names) and the generated tool catalog is unchanged, the
strongest whole-surface proof. Moved file ops carry no legacy getConnection
calls, so the guard allowlist needed no change. operations.ts 4,675→3,270;
ceiling ratcheted.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(ops): final tranche — operations.ts becomes a 312-line contract assembly
Tranche 3 moves the remaining ~35 ops (sources, facts/memory, insights,
code-intel, embedding-migration, image, schema-packs, skillopt, chronicle,
extraction, request-tools, transcripts) into 12 domain modules. operations.ts
now holds only the header, the re-export surface, the operations array
assembly (domain spreads + verbOperations), OP_AREAS + area stamping, and
operationsByName. Op-name order AND a name|scope|area|localOnly|mutating|verb|
param-count fingerprint are byte-identical before/after; the generated tool
catalog is unchanged. One documented seam: request-tools' visibleOpsForCaller
loads the assembled array via a handler-time dynamic import (the verbs.ts
house pattern) instead of a static cycle. operations.ts 3,270→312; ceiling
ratcheted. Contract mandate delivered: 7,459 → 312.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(doctor): peel the four tail clusters — schema-pack, remote report, bootstrap, skill checks
Pure moves into src/commands/doctor/: schema-pack-checks.ts (140),
report-remote.ts (433 — the run_doctor op's registry, dynamic import
unchanged via re-export), bootstrap-checks.ts (340), skill-checks.ts (408,
skillBrainFirstCheck re-export bundle-verified for the live-brain-first
script). One private check gained an export keyword as the minimal enabler
for the moved remote registry. Structural guards keep sight of moved code
through the doctor-source concat helper; the one positional guard that
pinned doctorReportRemote now reads doctor/report-remote.ts. doctor.ts
10,057→8,847; ceiling ratcheted.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(cli): flag-registry generator learns peeled façades — module dirs ride the façade's walk depth
The registry walks each command module + one level of relative imports. The
ops and doctor peels moved flag-bearing text into sibling module dirs, one
level deeper than the walk — a fresh regen would have silently dropped real
flags (doctor's git-plumbing set, ops-declared cliHints). facadeExpansion()
now treats a peeled façade's modules as part of the façade: their text scans
at the façade's own depth and their imports at dep depth — exactly the
pre-peel walk. The sync entry names only the modules peeled out of sync.ts,
so pre-existing sync-* siblings don't widen surfaces that never saw their
text. Proof: regen under the fixed generator is byte-identical to the
committed registry; the freshness test is green again (it was red for the
four preceding peel commits — this is the fix, not a regen-over-drift).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(doctor): peel the check-function library into doctor/checks/* bundles (containment C13)
Pure moves, zero behavior change. The ~61 exported standalone check
functions leave doctor.ts (8,847 -> 4,177 lines) for ten wave-grouped
bundle modules under src/commands/doctor/checks/. Every moved exported
symbol is re-exported from doctor.ts under its original name, so tests,
scripts, sync.ts's dynamic import, and report-remote.ts keep importing
from the facade unchanged. buildChecks/runDoctor import the moved checks
back through plain imports alongside the re-exports.
- core-health.ts (663): whoknows/pgvector/jsonb/volunteer/takes-grid/
orphans/provenance/source-config/scratch-probe cluster
- calibration.ts (664): v0.36.1.0 calibration + retrieval checks
- queue-jobs.ts (456): queue/wedged/fanout/batch-retry
- graph-embedding.ts (594): graph/brainstorm/ze/sunset/embedding-width
- routing-federation.ts (369): routing/federation/oauth/locks/phase-scope
- search-eval.ts (588): search-mode/eval-drift/env-override/subagent + probes
- extraction-sync.ts (949): extraction lag/backlog/health + checkSyncFreshness
- consolidation-cycle.ts (237): consolidation/pool-budget/cycle-freshness
- pglite-worker.ts (270): pglite datadir/worker OOM/pool reap
- verbs-reflex.ts (141): memory-verbs usage + retrieval reflex
Minimal enablers (C8-precedent license): per-bundle local aliases of the
core env-number resolvers (the shared warn-once memo lives in core, so
aliases can't fork behavior); pglite-worker.ts added to the grandfathered
getConnection allowlist (the call site moved verbatim); doctor.ts
module-size ratchet lowered 8847 -> 4177; dead facade imports pruned.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(sync): peel six pure-function clusters into src/core/sync-* modules
Pure moves (byte-identical spans; only deltas are 12 export keywords on
previously-private helpers plus 3 dynamic-import path rewrites): cost gate,
git plumbing, anchors/chunker-version, lock layer (performSync stays),
reconcile+deadlines, status report. sync.ts's public export surface is
byte-for-byte unchanged via re-export blocks at each cluster's original site;
type-only imports back into the new modules are erased at runtime (no load
cycle). The #132 nested-transaction positional guard still passes for its
original reason (the sole engine.transaction mention stays inside
performSyncInner's prelude — verified before/after). sync.ts 5,991→4,121;
ceiling ratcheted; flag registry stayed fresh through facadeExpansion without
regeneration.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(engines): peel facts/takes/code-edges/salience into narrow-deps modules, both engines in lockstep
Free-function extraction with per-group narrow deps interfaces (the sql/db
executor + named helpers — never an engine-shaped bag); class methods become
one-line delegates assembled through lazy per-group deps getters, so
pre-connection early-return behavior is unchanged. SQL text moved
byte-identical (line-multiset proof vs HEAD); BrainEngine conformance,
signatures, and published exports untouched; the pglite init preamble and
postgres session-timeout pins untouched. Behavioral proof: engine-parity 33/0
against live Postgres plus 63/0 across the group-specific e2e suites.
postgres-engine.ts 6,963→5,682; pglite-engine.ts 6,897→5,522; ceilings
ratcheted; the engine-live guards (dynamic-import, source-id projection,
jsonb, double-retry) all scan the new dirs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(coverage): measurement machinery — lcov merge, diff gate, baseline gate, lane wiring
merge-lcov.ts sweeps per-process lcov files (bun overwrites a reused
coverage-dir, so every lane/process gets its own), normalizes SF paths,
regenerates all records from parsed data (bun/JSC omits function names —
line records only for gating), and emits the canonical summary JSON with
lane-manifest degrade detection (a shard manifest with lcovCount != 1 trips
the xargs-batching tripwire) and an honest never-loaded file list instead of
fake all-files math. coverage-diff-gate.ts enforces >=80% on added/changed
gate-scoped lines (report-only until COVERAGE_GATE_ENFORCE=1; degraded merge
self-downgrades; [coverage-exempt: reason] trailer escape; exit contract
0 pass / 1 fail / 2 infra). coverage-baseline-gate.ts compares like-for-like
corpus sections against git show origin/master:scripts/coverage-baseline.json
with deletion defense; the committed baseline is provisional with null corpus
sections until seeded from real CI runs. Shell lanes (test-shard,
run-serial-tests, run-e2e) collect coverage only when COVERAGE_DIR is set —
argv-capture proof shows byte-identical exec lines when unset. Merge math
proven: 0 mismatches across 6,003 lines of two-lane hand-verification.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(ci): advisory coverage-report job — merged PR-corpus coverage on every run
The 13 PR-corpus lanes (10 shards + serial + 2 slow jobs) collect lcov behind
COVERAGE_DIR and upload per-lane artifacts (with lane manifests; the two
inline slow jobs write theirs in-workflow). coverage-report downloads,
merges (--manifest-expect over all 13 lanes), renders the summary +
behavioral/structural counts to the step summary, and runs the diff gate +
prCorpus baseline gate in report-only mode (COVERAGE_GATE_ENFORCE=0). The job
uses always()&&cache-miss — a failed shard still produces a (degraded)
report — and is deliberately NOT in test-status's required set or
cache-write's needs until the gate graduates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(ci): nightly coverage-full pipeline — the honest unit+serial+E2E merged number
Schedule-gated jobs in e2e.yml run every lane WITH coverage inside one
workflow (10 unit shards, serial, the 3 slow files, and the FULL e2e glob via
run-e2e.sh — all 185 files incl. engine-parity — against a pgvector service),
then coverage-full-report merges 13 lanes, compares against the fullCorpus
baseline, and uploads the 30-day trend artifact. No cross-workflow artifact
fetch anywhere (racy by construction). run-e2e.sh's per-file hard cap gains
the non-GBRAIN-prefixed E2E_FILE_TIMEOUT_SECS knob (nightly uses 300s to
absorb instrumentation overhead; default stays 180s).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: containment-sprint reference refresh — coverage lanes, ratchet + façade invariants, follow-up TODOs
CLAUDE.md gains three cross-cutting invariants (module-size ratchet, peeled
façades keep their surface, coverage measured honestly); TESTING.md gains the
Coverage lanes and gates section (two corpora, merge/degrade semantics, gate
contracts, bun caveats, local smoke command); KEY_FILES.md entries updated to
the façade+module reality; CONTRIBUTING.md tree and add-an-operation guide
point at the ops/ domain pattern; 8 follow-up TODOs filed (gate graduation
criteria, Wave 4a/4b, subprocess coverage, exemption shrinking, branch
coverage, evidence-gated engine dedup); llms bundles regenerated in the same
commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): re-point the two structural pins the peels moved out from under
check-engine-dynamic-import.test.ts derives the guard's default scan count
(3 façades + the peeled engine modules) instead of hardcoding 3, so adding an
engine module never breaks it. silent-drop-regression.test.ts scans the whole
ops surface (operations.ts façade + src/core/ops/*) for the v0.13 forbidden
pattern — strictly stronger than the old single-file pin, and the put_page
positive assertion follows the handler to its domain module.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(todos): file the master-inherited shard-1 SIGTERM self-kill flake (repro + starting points)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.47.0.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(guards): failing-side proof for every module-size ratchet rule
Rules 2-4 (stale ceiling, deleted-file row, unlisted-file cap) and the
unknown-policy arm now each have a red-side test through GBRAIN_GUARD_ROOT
temp trees, plus an accumulate-not-first-fail proof — closing the coverage
audit's P2 on the guard whose own thesis is that unfalsifiable guards rot.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test,ci): ship-stage review fixes — parity clock-skew, gate pipefail, guard modernization
- engine-parity's stale-page mark now stamps with each engine's own
updated_at_iso (the production #1768 pattern): the wall-clock stamp raced
the server's now() and failed deterministically on any Postgres whose
clock runs ahead of the test process (Docker VM skew) — reproduced on
clean master; PGLite shares the process clock so only real Postgres
drifted. First red caught by the newly CI-wired suite.
- coverage gate steps get shell: bash — the default GHA run shell has no
pipefail, so the tee-to-step-summary pipe would mask gate exit codes and
a graduated gate could never fail the job.
- check-operations-filter-bypass.sh now matches '../operations.ts'
specifiers and the dynamic-import house pattern; four pre-existing
blind-spot consumers and the request-tools seam are allowlisted with
rationales.
- doctor-source test helper had raw NUL bytes in its boundary marker
(git classified the 14-test-dependency helper as binary); now plain text.
- restored two security-rationale comments the ops peel dropped; removed a
dead execFileSync import the sync peel left; swept seven stale
file:line locators onto the peeled module paths; operations.ts ceiling
ratcheted to its exact 303.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ci): overwrite coverage artifacts on job re-runs
upload-artifact v4 hard-fails on a name conflict when a re-run attempt
uploads over a prior attempt's artifact — the always()-condition uploads on
REQUIRED lanes would redden a re-run of failed jobs, the exact
infra-flake-blocks-branch-protection class the advisory design excludes.
overwrite: true (supported by the pinned v4.6.2) on every coverage upload.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(coverage,guards): adversarial-review hardening — self-exemption governance, denominator gate, region + parser edges
- The diff gate's exemption list now resolves from origin/master (baseline-
gate governance): a PR's working-tree additions are inert until merged, so
no branch can self-exempt from the 80% gate at graduation. First-landing
and report-only fallbacks preserved; test seam for determinism.
- Baseline sections record neverLoadedCount and the gate treats an increase
as a regression — deleting the tests that load a module can no longer
raise the headline percentage ungated.
- check-module-size region-exempt hardened: spoof-named MIGRATIONS_* consts
no longer open the exempt region, and an unclosed region fails loudly
instead of exempting the file tail.
- classify-tests escapes binding names before RegExp and sorts by codepoint
(ICU-proof TSV); merge-lcov skips prior coverage-merged artifacts on job
re-runs (self-merge guard); check-skill-refs scans the ops module surface
(25 rotted warnings back to 0 real ones).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(todos): graduation PR inherits the adversarial acceptance items (degraded posture, re-seed cadence)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.47.0.0
Cross-reference sweep after the containment sprint's façade peels:
- eval-capture.md + eval-bench.md: capture surface moved to src/core/ops/search.ts
- conventions/calibration.md: the four calibration doctor checks live in
src/commands/doctor/checks/calibration.ts (+ skills.lock regen)
- FIX_WAVE_BASELINES.md: append the containment-sprint ledger row (post-peel
line counts, peeled-dir totals, guard + ratchet + coverage receipts)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: cross-model doc-review fixes for v0.47.0.0
Verified findings from the post-ship documentation review:
- CHANGELOG: parity suite is 34 tests at runtime (32 declared, one x3 loop);
e2e workflow runs on PRs + master pushes, not every push
- TESTING.md: guard registry count 45->48; COVERAGE_DIR is normalized (not
required-absolute); exemptions list resolves from origin/master (no
self-exemption); baseline gate's third rule (never-loaded count
non-increasing); optional flags (--base, --structural, --summary)
- CONTRIBUTING.md: drop duplicated stale "19+ guard checks" line;
operations is an array, not a map; dead intent.ts -> query-intent.ts
- KEY_FILES.md: operations array, not map
- eval-bench.md: dead intent.ts -> query-intent.ts
- FIX_WAVE_BASELINES.md: five of six giants peeled (not four); CI trigger
phrasing
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(cli): install cleanup signal handlers inside the import.meta.main seam
Installing process-cleanup's SIGTERM->exit(143) handler at module load
leaked it into any process that merely imports cli.ts. In a bun test
runner, test/run-child-entry.test.ts's synthetic process.emit('SIGTERM')
then killed the entire shard; run-unit-parallel.sh misread rc=143 as an
external kill, the serial rescue died identically, and `bun run test`
exited 1 with zero real failures. Minimal repro (pre-fix, exit 143):
bun test test/link-source-namespaced-regex.test.ts test/run-child-entry.test.ts
- cli.ts: move installCleanupSignalHandlers() inside import.meta.main
(entrypoints - real CLI, compiled binary, spawned CLIs in tests - still
install; imports no longer poison the importer).
- process-cleanup.ts: record attached listener refs; _resetForTests()
now detaches them (flags-only reset left a live exit(143) listener).
- run-child-entry.test.ts: strip foreign SIGTERM listeners around the
synthetic emit, restore in finally (defense-in-depth).
- autopilot.ts: refresh the stale "installed at cli.ts module load" comment.
* fix(test-harness): isolate GBRAIN_HOME by default; unify the preferences path convention
Unit tests ran against the operator's REAL ~/.gbrain: any config-honoring
code path silently changed behavior with whatever the live config.json
said (27 cycle/autopilot/dream tests flipped red the moment a sibling
workspace rewrote it, while the identical commit stayed green in CI),
and tests have historically clobbered the real config.
- test/helpers/gbrain-home-preload.ts (+bunfig preload): point GBRAIN_HOME
at per-run scratch when unset - same pattern as audit-dir-preload (#2823).
Respects the e2e wrapper's own GBRAIN_HOME.
- src/core/preferences.ts: gbrainDir() now delegates to config.ts's
gbrainPath(), so GBRAIN_HOME follows the ONE canonical convention
(parent dir, '.gbrain' appended). Its previous local resolver returned
GBRAIN_HOME directly - while claiming in its own comment to match
gbrainPath - splitting one logical home across two roots (config at
$GBRAIN_HOME/.gbrain/config.json, migration ledger at
$GBRAIN_HOME/migrations/).
- 7 test files updated to the canonical convention: subprocess spawns set
BOTH HOME and GBRAIN_HOME (HOME alone loses to the inherited preload
value; in-process HOME mutation loses to Bun's cached os.homedir()),
and the cycle file-lock test resolves via gbrainPath like production.
* fix(e2e): repair the 13 CI-uncovered files that rotted as master moved
CI's e2e workflow runs only 8 named files; `bun run test:e2e` runs all
~187, so the local-only lane rotted silently across v0.42-v0.46 waves.
Every failure diagnosed as test-rot/env/flake - zero product regressions.
- v0_29-mcp-dispatch-pglite: pass transport:'stdio' past the v0.45.13.0
dispatch-layer localOnly backstop so the in-handler remote gate is tested.
- type-unification-full-flow: withEnv-isolate the pack-upgrade check from
the machine's file-plane schema_pack (honored since v0.42.66.0).
- embedding-column-pglite: use __unconfigureGatewayForTests() (resetGateway
re-applies env config since PR #3557).
- extract-atoms-discovery-sql: sentinel type 'note' -> 'concept'
(unconditionally excluded) after PR #2615 widened extractable types.
- phantom-redirect: round-12 predicate accepts halfvec (migration v40 on
pgvector>=0.7) + idempotent-reconcile comment refresh (#2932).
- openclaw-plugin-load-real: bun build --outdir + --entry-naming (v0.45.0.0
pglite-embedded-assets emits 5 file-loader assets; --outfile refuses
multi-output); drop the retired `plugins inspect --runtime` flag
(OpenClaw 2026.4.x reports runtime state in plain --json).
- bootstrap-keyed-postgres: [G13] assertion is soft-delete-aware.
- pglite-cli-exit.serial: strip DATABASE_URL/pgbouncer vars from spawned-CLI
env so the corrupt-PGLite fixture isn't rerouted to healthy Postgres.
- bootstrap-harness-lifecycle.serial: scrub ambient DB URLs for the
IN-PROCESS runBootstrap path too.
- helpers.ts setupDB: reset leaked brain identity in `sources` (PR #3735's
ownership guard keys on sources.default.local_path; without the reset
every legacy-path sync classifies as first_sync forever). Deliberately
leaves chunker_version alone - NULLing it flips staleness semantics.
- ingestion-roundtrip: poll the async post-emit archive with waitFor.
- doctor-progress: detect the silent DB-fallback via the 'connection'
check + retry once on transient connect failure.
- serve-http-oauth: bind the scopes array as an explicit '{read}'::text[]
literal (sql.array under prepare:false serializes as the bare element).
- engine-parity: stamp with each row's own updated_at_iso (the #1768/D4
production convention) - a DB clock a few ms ahead of the client made
client-time stamps land before the row's insert time whenever the
seed->stamp gap was shorter than the skew.
* fix(review): review hardening + e2e timeout cap + v0.46.8.0 bump
Combined ship-stage commit (review army: 5 specialists + red team +
Claude adversarial + two Codex passes; every P1/P2 addressed):
REVIEW HARDENING
- preferences.ts: one-time copy-forward shim for the pre-unification
$GBRAIN_HOME-direct layout (atomic temp+linkSync, EEXIST = concurrent
winner; JSON-validated prefs; chmod 0600; copy-not-move for rollback;
once-per-process warnings). A valid-but-uncopyable legacy file is
READ IN PLACE, and ledger appends target the same resolved path so a
degraded copy can never split or shadow migration history — an
explicit minion_mode opt-out survives the upgrade; completed
migrations are never silently re-run. One-shot mixed-version
divergence documented as accepted.
- url-redact.ts: redactUrlsInText — greedy userinfo scrub (a raw '@' in
a password can't leak its tail) + libpq keyword/value form incl.
quoted passwords. cli.ts doctor fallback routes through
redactConnectionInfo AND the URL sweep; its label no longer
misdiagnoses a DB-backed-check throw as a connect failure.
- run-unit-parallel/shard/slow: strip ambient GBRAIN_HOME at the same
boundary that strips DATABASE_URL.
- process-cleanup.ts: docstring rewritten to the import.meta.main
contract.
- Regression pins: _resetForTests detach (all 7 attach points); cli.ts
import installs no signal handlers (spawn-based); preload
sets-when-unset/respects-preset; legacy copy-forward (4 cases);
doctor fallback stderr + credential redaction end-to-end;
redactUrlsInText units. Credential-shaped fixtures assembled at
runtime so source never carries a scannable span.
E2E TIMEOUT CAP
- run-e2e.sh: known-slow files get a 420s wedge backstop
(skills.test.ts runs the real ingest skill ~140s+ at 124 migrations;
the 180s cap false-killed it on quiet machines).
VERSION v0.46.8.0
- VERSION, package.json, CHANGELOG.md, openclaw.plugin.json,
BOOTSTRAP_FOR_AGENTS.md stamp, regenerated template stamp, bun.lock.
- KEY_FILES.md/TESTING.md updated; TODOS.md files the wave's 4
follow-ups (SIGCHLD seam, CI e2e coverage gap, runner kill-report
clarity, skills.test.ts host-repo commit leak found during the gate).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.46.8.0
- KEY_FILES.md: cli.ts entry now covers the doctor DB-fallback stderr
note + its two-redactor scrub (and drops a stale line-number cite);
new src/core/url-redact.ts entry (redactPgUrl / redactUrlsInText /
redactDeep, consumers, CI guard, test pin); redact-connection-info
consumer list gains the doctor fallback; run-e2e.sh entry documents
the per-file wedge-timeout override (180s default, skills.test.ts
420s, SIGTERM via gtimeout/timeout).
- docs/TESTING.md: preload section notes the unit/slow wrappers strip
an ambient GBRAIN_HOME (the preload respects pre-set values) and
documents GBRAIN_DEBUG_PRELOAD=1.
- CHANGELOG.md 0.46.8.0: adds the e2e timeout-cap bullet (the one
commit item the entry missed); narrows "no signal handlers" to
termination/cleanup handlers (SIGCHLD reaper still module-scope,
TODOS files the follow-up); tightens the doctor-redaction claim to
what the redactors guarantee.
- CONTRIBUTING.md: removes a stale orphaned duplicate line
contradicting the current guard-check count.
Cross-model doc review (codex, high effort) ran; concrete findings
applied, narrative findings deliberately skipped.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): claim the render backup-stamp dir atomically; harden two CI timing pins
Two one-shot CI failures on loaded runners (run 31928749495), exposed by
the merge's shard re-binpacking:
- render.ts: the forced-overwrite backup stamp has MILLISECOND
granularity, so two renders of the same workspace within one
millisecond collided on the exclusive `wx` backup write (EEXIST) — a
fast CI runner hit it on three back-to-back renders in one test. The
stamp dir is now claimed atomically per render call (non-recursive
mkdir, numeric suffix on EEXIST), lazily on the first backup. Pinned
by a 10-rapid-re-renders regression test asserting 10 distinct
backup dirs.
- db-lock-fencing: one loaded-CI run observed `aborted === true` with
`signal.reason === undefined` at the first post-abort read —
unreproduced across 50+ local + containerized Linux (bun 1.3.13)
runs, including the exact CI shard composition. The poll now awaits
the REASON (not just the aborted flag) within the same 5s deadline,
and a genuine miss reports the actual reason value for forensics.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* skills: delete deprecated install tombstone (frontmatterless SKILL.md breaks plugin skill scanners)
The skills/install/ dir was a deprecation pointer to the setup skill with no
YAML frontmatter — absent from skills/manifest.json and unreachable via the
resolver, but visible to any harness that scans skills/ for SKILL.md files.
Codex errors at session start on frontmatterless skills (the same class is
recorded for an external stray copy in TODOS.md), so it must not ship in the
plugin lanes. skills.lock.json regenerated by the commit gate.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* skills: portability, consent, and privacy sweep for the plugin lanes (10 skills, 50 fixes)
Prepares the sweep set (the 8 openclaw-excluded host-inversion skills plus
cold-start, signal-detector, eiirp, gbrain-upgrade) for publication to plugin
consumers who own their brain but are not gbrain-repo developers:
- setup: sanctioned global pinned install command; synthetic example names;
daemon-only prose generalized; repo-relative doc refs resolved; the invalid
discovery-loop bash fixed; PGLite-first framing restored
- cold-start: raw OAuth-token curl path deleted; ClawVisor phases labeled as
host-integration-only with offline (Takeout) equivalents leading
- signal-detector + eiirp: first-fire consent announcement + per-user off
switch; always-on reframed as a harness convention, not a runtime guarantee
- smoke-test: 'gbrain smoke-test' is the user entrypoint; container paths and
OpenClaw-service checks labeled conditional
- schema-author/schema-unify/skill-optimizer/frontmatter-guard/gbrain-upgrade:
repo-relative links, internal review-provenance citations, container paths,
and read-only-snapshot caveats cleaned
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* plugin-tree: curated skill tree for the codex/claude plugin lanes (generator + committed tree + drift gate)
One publication decision per lane, review-visible: lane set = (openclaw
bundle minus repo-dev exclusions) plus the 8 host-inversion additions —
skills/plugin-lanes.json is the curation record (a reason per entry),
scripts/generate-plugin-tree.ts emits the committed plugin/ tree (65 skills,
shared conventions/_*.md deps, generated README with the CLI-primary starter
note), and scripts/check-plugin-tree.sh byte-diffs tree-vs-generator (the
check-bootstrap-templates part-c posture). The starter_gaps snapshot pins
each bundled skill's beyond-starter MCP ops (computed from frontmatter
tools:, namespace-filtered) so a new gap is a conscious curation event —
every gap op has a first-class gbrain CLI path.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* serve: --source-guard fail-closed write routing for user-global plugin serves
A plugin-managed MCP server runs with the plugin snapshot as its cwd, so the
dotfile and local-path source-resolution tiers lose their meaning — an
ambient-tier resolution could silently route writes into whatever source it
fell through to (worst case: a registered source whose local_path contains
the snapshot dir). Under the flag, dispatch blocks write/admin ops with an
actionable source_binding_required envelope unless the winning tier proves
the binding deliberate (flag/env/dotfile/brain_default) or unambiguous
(sole_non_default; seed_default while 'default' is the sole source). Reads
pass on every tier; sole-source brains are a pure no-op; engine errors fail
closed. Both plugin manifests pass the flag; hand-run serves are untouched.
- src/core/source-resolver.ts: WRITE_SAFE_SOURCE_TIERS + sourceGuardBlocksWrite
- src/mcp/dispatch.ts: the gate (before validation, so a blocked caller
learns the routing rule, not the op's parameter shape); verb envelopes
carry protocol_version
- src/mcp/server.ts: resolveMcpStdioSourceScope now reports the winning tier
- src/commands/serve.ts: flag parse + seam type; flag registry regenerated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* codex-plugin,claude-plugin: lane manifests, shared launcher, manifest contract test
One repo, two plugin lanes:
- codex: .agents/plugins/marketplace.json (codex-native marketplace) +
.codex-plugin/plugin.json (skills → the curated plugin/ tree; mcpServers →
.codex-plugin/mcp.json, deliberately NOT a repo-root .mcp.json — a root
file would auto-offer a checkout-controlled launcher to every contributor's
session) + mcp.json serving --surface starter --source-guard with a
code-derived env_vars passthrough contract
- claude code: .claude-plugin/marketplace.json (content-equivalent so codex's
dual-format marketplace reading cannot fork the install) + plugin.json with
the inline env-OBJECT-shape MCP declaration via ${CLAUDE_PLUGIN_ROOT}
- .agents/gbrain-launcher (sh, 755, Unix-only): GBRAIN_BIN → PATH →
~/.bun/bin resolution with one stderr resolution line, GBRAIN_SURFACE
substitute-or-append override (serve argv only), actionable exit-127
recovery copy, no auto-install by design
test/codex-plugin-manifest.test.ts pins the whole contract: 4-manifest
version lockstep, exact MCP declarations, marketplace equivalence, launcher
statics + all seven resolver/override branches behaviorally (HOME pinned to
a tempdir in every case), curated-tree membership algebra, scanner guards,
env_vars ⊇ derived set, and a generator round-trip. Wired into the skills
commit gate alongside the openclaw manifest test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* bootstrap,doctor: plugin-lane coexistence — the plugin as a third owner of the gbrain MCP name
Detectors (src/core/bootstrap/harness.ts, all fail-open): codexPluginProvidesName
(line-anchored [plugins."<name>@<mkt>"] header + enabled=true — commented
lookalikes and next-table enabled keys never match), claudePluginProvidesName
(~/.claude/settings.json enabledPlugins, the shape verified on a live install),
and the doctor-side any-registration scans that DELIBERATELY count foreign/
manual entries (codexBlockOwnsName's managed-block scope is the wrong question
for coexistence).
runHooks: a healthy plugin-owned skip is a NEW state, not mcpSkipped (which
means host-failure and exits 2) — the MCP substep skips registration argv +
smoke (plugin MCP servers are invisible to mcp get/list), hooks and every
other phase proceed, exit 0, receipt records plugin ownership
('plugin-mcp' / 'hooks+plugin-mcp'). --mcp-even-if-plugin forces the
hand-wired registration (plugin enabled is a config signal, not health).
Harness lane: WARN (never refuse) when wiring the codex managed block next to
an enabled plugin — two same-name servers in different layers is host-defined
behavior; both off-ramps named.
Doctor: plugin_lane_collision (ops category, registered in doctor-categories)
— rows emitted ONLY when a gbrain plugin is enabled: warn on a real
double-registration, ok when the plugin is sole owner; runs before the
bootstrap-state gate (a manual mcp add + plugin needs no bootstrap to
collide).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(helpers): agent-harness oracle fixes for the plugin doors
- parseCodexJsonl retains mcp_tool_call items ({server, tool}, best-effort
field fallbacks) — e2e assertions no longer regex raw JSONL lines
- claudeHeadlessTurn / codexExecTurn spawn the RESOLVED binary path: the
hermetic child env can make a bare 'claude'/'codex' resolve differently
than the resolver the skip-gate consulted
- codexSupportsPlugins / claudeSupportsPlugins probes ('plugin --help'
exit 0) for the plugin-door skip-gates
- mcpToolsListProbe: deterministic MCP surface oracle — spawns a stdio MCP
server command, runs the initialize handshake, returns the advertised tool
names via a real tools/list (never an LLM-output assertion)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): codex + claude plugin doors — install, oracle, guard, coexistence, smoke
codex door (INSTALL verified GREEN against the real codex 0.147.0 in ~10s):
clean-tree staging via git archive HEAD (a dirty worktree never enters the
snapshot), marketplace add + plugin add, snapshot assertions (curated skills
present, repo-dev skills absent, NON-ROOT .codex-plugin/mcp.json honored,
launcher exec bit survives the copy), add-twice idempotency + exactly-one-row
dual-marketplace probe, deterministic tools/list surface oracle == the starter
surface through the SNAPSHOT launcher, cold-home fast-fail ('No brain
configured. Run: gbrain init'), --source-guard block/allow through the real
MCP pipe, hand-wired-next-to-plugin coexistence probe (succeeds — the doctor
warn scenario is real), marketplace-qualified removal. SMOKE (auth-gated):
plugin-provided server → seeded fact via mcp_tool_call evidence + the
recovery-loop probe (missing binary degrades, never bricks the session).
claude door: validate --strict (marketplace description added to pass),
marketplace add + install → enable entry in the exact claudePluginProvidesName
shape, uninstall clears it; SMOKE via claude -p with the plugin-launched
server. Harness: CodexTurnResult carries mcpToolCalls; extraEnv threads
GBRAIN_* through both turn helpers into plugin-launched servers.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci,dx: non-vacuous plugin-doors job + dx-explore codex-plugin-install scenario
heavy-tests.yml plugin-doors job (grok-door posture, EV11): PROVISIONS pinned
npm codex + claude binaries with version-output asserts (refuse on drift),
runs both INSTALL tiers, and refuses green unless the expected pass counts
executed — zero-pass/partial-pass never reports green. INSTALL tiers are
secretless by design; the auth-gated SMOKE tiers self-skip inside the suites
with the skip accounted for in the expected shape (integrity-metadata pinning
deliberately omitted: this job carries no secrets).
dx-explore codex-plugin-install: the plugin lane's first-run journey under a
real PTY — the two documented install commands up front, then an interactive
codex session answering a seeded brain question through the plugin-provided
MCP server; friction events recorded against docs/mcp/CODEX.md's plugin
section. Claude SMOKE oracle fixed to the observed plugin-namespaced tool
shape (mcp__plugin_gbrain_gbrain__*).
Both SMOKE doors verified GREEN live on this machine (codex attempt 1:
usedMcp=true gotFact=true; claude attempt 1 after the namespace fix).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* release: publish the slim codex-plugin dist branch on every release (EV4)
Force-publishes a history-less commit to the codex-plugin branch carrying
exactly the plugin artifacts (manifests + shared launcher + curated plugin/
tree) so 'codex plugin marketplace add garrytan/gbrain@codex-plugin' downloads
the plugin, not the dev repo. Gated on the same generator byte-diff as the
verify-time drift check; exec bit asserted before push; same force-advanced
trust model as latest-stable.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: plugin install paths, routing + surface guidance, tag-check Rule 4, five-way version lockstep
- docs/mcp/CODEX.md: plugin install headlined (@codex-plugin slim ref +
from-source form), prerequisites (binary + gbrain init, never the squatted
npm name), what ships (starter surface, host-inversion note), launcher
resolution + GBRAIN_BIN/GBRAIN_SURFACE, routing under the plugin lane
(dotfiles dead; source axis env/--source; brain axis env ONLY;
--source-guard semantics), one-owner-per-name + enabled≠healthy, both
upgrade halves, removal
- docs/mcp/CLAUDE_CODE.md: Option 0 plugin section (permissions.allow
pre-approval stays bootstrap-lane-only)
- README + INSTALL_FOR_AGENTS: plugin as the lightweight funnel next to the
bootstrap paste block; MCP table rows updated
- docs/guides/bootstrap.md degradation row + harness one-owner note;
BOOTSTRAP_FOR_AGENTS.md codex preflight covers the plugin-owned skip
- scripts/check-bootstrap-tag.sh Rule 4: marketplace refs in docs must pin
@latest-stable or @codex-plugin
- KEY_FILES entries for every new artifact; CLAUDE.md version-locations row
(five-file lockstep) + llms bundles regenerated; CHANGELOG under
[Unreleased]; TODOS: Windows launcher, keyless cold-home auto-init,
future harness lanes, post-release marketplace-upgrade probe
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(gates): flag-registry regen, serial-rename the source-guard test, register check-plugin-tree in the guards manifest
- cli-flag-registry regenerated (picks up --mcp-even-if-plugin and the other
new bootstrap flag literals added after the commit-3 regen)
- test/serve-source-guard.test.ts → .serial.test.ts (R1: it mutates
process.env.GBRAIN_SOURCE in its env-fallback cases)
- guards-manifest.tsv: check-plugin-tree.sh classified buildfresh/exempt
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes (1 critical + 13 hardening items from the specialist army)
- CRITICAL: claude plugin SMOKE door gains its missing auth skip-gate
(hasClaudeAuth) — an unauthed machine burned 2×230s live-turn attempts and
hard-failed instead of skipping
- source-guard probe: bounded LIMIT-1 existence query + memoized schema-shape
probe (a legacy pre-archived-column brain paid an exception per guarded
write); dispatch imports sourceGuardBlocksWrite statically (was a dynamic
import per call); serve warns loudly that --source-guard is stdio-only when
combined with --http (the --log-full-params posture precedent)
- generate-plugin-tree: canonical parseSkillFrontmatter replaces the
hand-rolled block-only parser (which silently missed inline tools: lists —
proven immediately by multi-word CLI entries surfacing), plus a
GBRAIN_PLUGIN_TREE_ROOT fixture seam; three negative-fixture tests prove
the curation gate can actually fail (short reason, addition-in-base, stale
starter_gaps)
- tests: parseCodexJsonl mcp_tool_call field-fallback unit cases; legacy-
schema fallback + memoization tests for the guard; dead var + unused import
dropped from the door tests
- check-bootstrap-tag: Rule 4 moved before the status block (no more
ok-then-FAIL transcripts); bare-form scope recorded as a deliberate
decision (Claude marketplaces have no ref-pin syntax)
- check-plugin-tree wired into bun run verify (the comment now tells the
truth); plugin-doors CI pins EXACT pass counts (grok-door posture);
release publish job checkout gets persist-credentials:false;
claudeUserMcpConfigPath() helper replaces the inline ~/.claude.json path;
dx-explore fails fast when the paid scenario's seed write fails
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.7.0)
Five-file lockstep (VERSION, package.json, openclaw.plugin.json, both plugin
manifests) + runbook stamp + template-repo regen + bun.lock + llms bundles.
User-pinned slot past the 0.46.2-0.46.6 in-flight queue.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial + red-team review fixes (2 critical + coexistence/guard hardening)
Cross-model review (Claude adversarial + Codex adversarial + red team) after
the merge surfaced two real criticals and a set of correctness/honesty gaps —
all fixed:
- CRITICAL (red team): the e2e source-guard block-probe seeded a sole-source
brain, which resolves to the unambiguous sole_non_default tier (WRITE_SAFE,
correctly NOT blocked) — a latent CI redliner. The guard DESIGN is right
(one real source can't be misrouted); the test now seeds a genuinely
ambiguous 2-source brain, and the CHANGELOG/CODEX.md wording drops the
"more than one source" overclaim for "multiple sources to choose from".
Re-verified live: INSTALL door green, block+unblock both assert.
- CRITICAL (Claude): the plugin-mcp receipt marker was write-only — uninstall
ran `mcp remove gbrain` for it, which would delete a user's later
hand-wired registration bootstrap never created. Uninstall now skips the
mcp-remove for plugin-owned receipts (hooks half still removed).
- launcher resolution prefers ~/.bun/bin over PATH (a hostile repo's
node_modules/.bin gbrain can't shadow the sanctioned install with all the
forwarded provider creds); GBRAIN_BIN stays the escape hatch.
- claudeAnyRegistrationExists scans projects.<path>.mcpServers (the LOCAL
scope `claude mcp add` defaults to) so doctor stops printing a false
"sole owner"; claudeUserMcpConfigPath honors CLAUDE_CONFIG_DIR.
- --source-guard: local_path now blocks only when another source exists (a
sole-source brain whose local_path contains the serve cwd is unambiguous);
the shape memo caches 'legacy' only on a genuine missing-column error (not
a transient blip); GBRAIN_SOURCE=__all__ writes get a sentinel-specific
block; a malformed GBRAIN_SOURCE no longer launders through as tier 'env'.
- claude manifest pins cwd=${CLAUDE_PLUGIN_ROOT} so the guard's
"cwd is meaningless" premise holds on both lanes.
- release publish job: GIT_ASKPASS instead of token-in-argv, ships LICENSE;
check-plugin-tree drops the now-permanent SKIP fail-open + guards mktemp;
mcpToolsListProbe races reads against the deadline (no silent-child hang);
env derivation covers transcription.ts (DEEPGRAM_API_KEY); removal-command
copy unified to gbrain@gbrain; plugin/ added to the version-lockstep
(CLAUDE.md + RELEASING); receipt-provenance edge filed as a P3 TODO.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: sync plugin docs to shipped behavior for v0.46.7.0
Post-ship /document-release cross-referenced every plugin doc against the
code and fixed eight drift points:
- starter surface is 26 ops, not "~20" (CODEX.md, plugin/README, generator
template + regenerated tree, derive-starter-ops comment)
- the plugin stdio serve binds the source axis from GBRAIN_SOURCE env, NOT a
--source flag (resolveMcpStdioSourceScope passes explicit=null) — dropped the
over-promised --source from CODEX.md, CHANGELOG, and both source-guard
dispatch envelopes
- --source-guard gates write AND admin ops (say "write/admin", not "write-only")
- Claude Code Remove section gains the Option 0 plugin uninstall command
- codex plugin remove is marketplace-qualified (gbrain@gbrain, not bare gbrain)
- BOOTSTRAP_FOR_AGENTS plugin-owned skip note now covers Codex AND Claude
- version-locations table: "six/trio" -> "seven files"; stale 0.46.1.0 example
- KEY_FILES: Claude manifest has no env block (command/args/cwd only)
CLAUDE.md edited -> llms bundle regenerated in the same commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci: silence intentional SC2016 in the codex-plugin publish job
actionlint (via shellcheck) flagged the single-quoted $GH_TOKEN in the
GIT_ASKPASS heredoc of publish-codex-plugin. The non-expansion is the
point — the askpass script must carry the literal variable so /bin/sh
expands it at git prompt time, never in the workflow shell. Add the same
shellcheck disable=SC2016 directive the publish-template job already
carries for its identical pattern. actionlint now green across all
workflows locally.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
runGather catches each retrieval stream's failure (hybrid pages,
takes-keyword, takes-vector, graph walk) and degrades fail-open, but
only wrote labeled stderr diagnostics — no typed code reached the
think result's warnings[]. For MCP/remote callers whose stderr goes to
server logs, diagnostics counts alone made pagesFromHybrid: 0
ambiguous (stream errored vs legitimately empty).
Follow the existing D6 code-only-on-the-wire idiom
(QUESTION_EMBED_FAILED / CALIBRATION_FETCH_FAILED /
TRAJECTORY_INJECTION_FAILED in src/core/think/index.ts): each catch
now also pushes a machine-stable code — GATHER_HYBRID_FAILED,
GATHER_TAKES_KEYWORD_FAILED, GATHER_TAKES_VECTOR_FAILED,
GATHER_GRAPH_FAILED — into a new ThinkGatherResult.warnings[], and
runThink folds them into ThinkResult.warnings (same fold pattern as
resolveCitations warnings). Stderr diagnostics, fail-open behavior,
and diagnostics counts are unchanged.
Claude-Session: https://claude.ai/code/session_01VQtBAN6mdxpH1ZnmBQxaVm
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
A brain whose only entity pages are soft-deleted has zero live entities, but
graph_coverage counted the deleted rows, so it never took its own
"No entity pages — graph_coverage not applicable" short-circuit and warned
about coverage on pages the rest of the system treats as gone.
The WARN was unclearable. doctor recommends `gbrain extract all`, but
buildGazetteer (src/core/by-mention.ts) already filters soft-deleted pages, so
`extract links --by-mention` answers "No linkable entity pages found" on the
same brain. The two disagreed about whether entity pages existed at all, and
the recommended command could never link pages that are deleted.
Adds `deleted_at IS NULL` to the entityCount query and the eligible CTE, which
is the filter buildGazetteer already applies. The linked_from and timeline
subqueries select from eligible, so they inherit it.
Not touched: links whose endpoints are soft-deleted still feed the numerator.
That is the page_links traversal #3754 is about, and belongs to that fix.
Related to #3754, where this surface was reported.
* minions: classify lock-renewal failure causes + starvation telemetry (#4145)
The incident's forensics cost ~8h because the eviction log lines could not
say WHY renewal failed. This commit makes every renewal fault self-explaining
without changing abort semantics:
- Named RenewalCallTimeoutError so cause classification (call-timeout vs
refused vs fenced-lost) is name-based, never message-sniffing.
- Tick lateness (now - lastTickFiredAt - intervalMs) as the primary
local-starvation signal — interval callbacks coalesce under a blocked
loop, so a missed-tick counter cannot measure starvation; lateness can.
overlap_skips counts tickInFlight re-entrancy skips only.
- Elapsed-time arithmetic now binds deps.now to performance.now()
(monotonic): wall-clock jumps can no longer distort the deadline math.
Date.now remains only in log/audit timestamps.
- loadSnapshot dep (raw loadavg[0] + cached core count), try/caught at
every call site — telemetry must never re-open the unhandledRejection
class this module exists to close.
- Worker-level event-loop-delay histogram (perf_hooks.monitorEventLoopDelay,
fail-open when the runtime lacks it), RESET on every successful renewal
so an eviction-time sample attributes to the exact window in which
renewal was failing; sampled into the abort + grace-evict log lines.
- Per-launch abortMeta stash so the grace-evict line (which fires 30s
after the abort) reports cause/lateness/load instead of just the Error
string that made healthy evictions read like orphan leaks.
- Audit events gain additive optional fields (cause, lateness_ms,
overlap_skips, load1, cores, via, deadline_deferred) behind a
back-compatible optional trailing ctx param; the 4-outcome contract and
pre-upgrade JSONL readback are unchanged (pinned by new tests).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* minions: inFlight generation-safety — lockToken-conditional deletes (#4145)
Force-evict and the handler's finally both deleted the inFlight entry by
bare job.id. When a force-evicted job is requeued and re-claimed by the
SAME worker while the old handler is still alive, the old execution's
late delete removed the NEW execution's entry — concurrency undercount
and lost tracking for the replacement run. Every claim mints a unique
lockToken and the entry already stores it, so the token is the
generation: both deletes now only remove the entry when it is still
their own.
Pre-existing bug surfaced by the #4145 outside-voice review (R2-1);
fixed in its own commit because the eviction path is exactly what this
wave modifies. Pinned by a deterministic same-worker reclaim test
(stale execution A's finally leaves execution B's entry intact).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* minions: stall-sweep reclaim grace (#4145)
handleStalled reclaimed on a bare lock_until < now(). When a CPU-starved
worker's event loop unblocks, its coalesced renewal tick and the stall
sweep fire in the same burst — if the sweep's UPDATE lands first it
steals the OWNER'S live job and discards its in-flight work. All three
sweep predicates now carry a reclaim grace (default 15s, env
GBRAIN_MINION_STALL_RECLAIM_GRACE_MS, 0 = exact legacy behavior).
The grace is a head-start for the owner's recovery renewal, not a
guarantee: it covers starvation bursts shorter than the grace; a healthy
second worker's sweep still wins beyond it. Cost: dead-worker recovery
becomes lock_until + grace + up to stalledInterval. This is the minion
analog of the cycle-lock steal grace, adapted because minion_jobs has no
last_refreshed_at column.
Existing stall tests move their synthetic lock_until offsets from 1s to
30s past (they pin stall mechanics on the production default path); new
tests pin within-grace hold, beyond-grace reclaim, grace=0 legacy, and
env resolution incl. warn-once fallback.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* minions: verify-before-evict + hard eviction deadline (#4145)
The root-cause fix. The only abort path was the throw branch's local
arithmetic: one timed-out renewal on a starvation-delayed tick past
lockDuration - safetyMargin evicted a healthy job — under load the
renewal UPDATE may even have LANDED server-side while the local race
timeout won. 2,571 subagent jobs submitted / 24 done in 24h.
New contract (ports the cycle-lock fencing doctrine to Minion job locks):
- Fenced-false is the only CERTAIN eviction signal; a throw is not
evidence of loss. When the NEXT tick would land past the soft deadline
(cadence-aware: sinceLastSuccess + intervalMs >= deadline — the bare
>= gate is unreachable under cadence quantization for long leases),
the tick runs ONE bounded VERIFY renewal. renewLock fences on
lock_token and deliberately ignores lock_until, so an
expired-but-unstolen lease revives: fenced-true → starved-but-ours,
keep working (the incident-saving path); fenced-false → certain loss,
abort (stall detector requeues, no attempt burned); verify unreachable
→ defer + reconnect-once, aborting only past the hardEvictMs backstop
(default 2×lease, env GBRAIN_LOCK_RENEWAL_HARD_EVICT_MS, floored to
the soft deadline) — a LOCAL decision under uncertainty that bounds
blind external side effects during a total outage.
- The verify is a synchronous, cancelled()-guarded, callTimeoutMs-bounded
call inside the tick's own flow — reconciled in-code with queue.ts's
no-background-retry rationale (both UPDATEs are same-token idempotent
lease extensions; a fenced row cannot gain two holders).
- Best-effort cancellation: the race timeout now aborts the in-flight
renewLock via AbortSignal threaded to executeRawDirect; both engines'
entry points gained an already-aborted preflight BEFORE dispatch/pool
acquisition. The fence stays the correctness authority.
- Relational knob validation: margin < lease/2, callTimeout <= cadence,
hardEvict >= soft deadline — clamped with warn-once; positive-integer
parsing alone could silently re-break the deadline math.
- Doctrine comments rewritten (tick header + worker grace-evict) — the
old abort-at-deadline prose actively misled.
Tests: incident replay (starved renewal times out, verify succeeds, job
survives — the exact #4145 shape), fenced-false via verify, deferral +
hard-backstop timelines, CDX-4 quantization pin (300s/60s verifies at
240s with lease left), first-tick verify at the 30s default,
mid-verify cancellation, reconnect-on-deferral, relational clamps, and
a DATABASE_URL-gated e2e pinning the DB-level foundations (expired-
but-unstolen revival, grace hold, post-reclaim fenced-false, and a
blocked-event-loop worker completing with zero stall bounces).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* minions: per-job lock_duration_ms end-to-end (#4145)
A single worker-global 30s lockDuration cannot serve both 2s shell jobs
and 173s-average LLM subagent jobs — the structural half of the #4145
incident. The lease is now a per-job column resolved through the same
three-layer model as timeout_ms (explicit submit → handler-type map →
worker default), claim-stamped so it survives worker restarts.
- Migration v129 + the 3 schema copies: nullable lock_duration_ms with
the positive CHECK added via the idempotent drop-then-add pattern (v7
precedent) — no fresh-vs-migrated asymmetry, no backfill (NULL = worker
default = pre-#4145 behavior; claim COALESCE owns all defaulting).
- HANDLER_DEFAULT_LOCK_DURATION_MS beside the timeout map (long LLM
handlers 300s, single-call LLM handlers 120s, shell deliberately absent
for fast dead-worker reclaim) under one rewritten header explaining why
lease and wall-clock budget are different quantities.
- Claim derives lock_until from COALESCE(row, map, worker default) and
stamps the resolved lease; the map binds as a RAW object (jsonb
double-encode rule). Wall-clock null-fallback becomes
COALESCE(lock_duration_ms, worker default) so an explicit lease on an
unmapped handler isn't killed at the old bound (NULL rows pinned to
exact legacy behavior).
- Worker consumes the effective per-job lease at all three launch sites;
renewal cadence clamps to min(lease/2, 60s) — a 300s lease renews 5x
per window instead of every 150s; ≤120s leases keep legacy /2 exactly.
Derived knob defaults cap at 15s call-timeout / 30s margin so long
leases don't inherit wedge-inducing values.
- Shared clampLockDurationMs [5s, 1h] used by queue.add, the new
gbrain jobs submit --lock-duration-ms flag, and the MCP submit_job
param (handler-side clamp; ParamDef has no min/max — wrong types are
rejected by the existing number validation). INSERT-only on idempotent
re-submit, matching the max_stalled footgun rule.
- jobs get shows the lease line alongside the timeout line.
Tests: migration v129 structure/idempotency/CHECK/pre-shape re-run;
claim-stamps-from-map + lock_until horizon; explicit-wins + clamp bounds;
idempotent-resubmit immutability; wall-clock NULL-row regression pin +
leased-row survival; lifetime max_stalled accumulation pin (the known
coverage gap); per-lease knob derivation caps.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(minions): lock-renewal knobs, eviction-forensics guide, verify-before-evict current-state (#4145)
- queue-operations-runbook.md gains the incident-reading section the
#4145 forensics lacked: how to read a gave_up/eviction line (cause,
lateness_ms, load1/cores, overlap_skips, deadline_deferred,
event-loop-delay), the was-the-DB-down-or-the-worker-starved decision
table, the full env-knob table (CALL_TIMEOUT / SAFETY_MARGIN /
HARD_EVICT / MAX_FAILURES / STALL_RECLAIM_GRACE) with relational-clamp
semantics and legacy escape hatches, and the honest zombie caveat
(eviction is cooperative until the kill/reap follow-up lands).
- minions-deployment.md's 'what can still bite' section rewritten for
verify-before-evict + per-type leases + reclaim grace; documents the
mixed-version-fleet degradation (old workers = legacy behavior, no
drain needed) and adds --lock-duration-ms to the per-job tuning list.
- KEY_FILES.md entries (lock-renewal-tick.ts ×2 duplicated entries,
worker.ts, queue.ts, handler-timeouts.ts) updated to current state.
- TODOS.md: filed the kill/reap-evicted-handler follow-up (P2), the
worker-level --lock-duration flag (P3), and the TODO-LR-2 note that
its doctor-check inputs now exist in the audit events.
- llms bundles regenerated (unchanged — these guides aren't inlined).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: scrub leaked GBRAIN_HOME from doctor-minions-check subprocess env
The test seeds $HOME/.gbrain/migrations fixtures and spawns gbrain doctor
with HOME overridden — but doctor resolves its home via resolveGbrainHome,
which prefers GBRAIN_HOME over HOME. Sibling test files in the same bun
process (preferences, friction, bootstrap-*, and several .serial files'
beforeEach hooks) set process.env.GBRAIN_HOME; a value captured by the
{...process.env} spread makes the fixture invisible, doctor finds nothing,
and the expected FAIL exit code never happens. Scrub GBRAIN_HOME exactly
like the DATABASE_URL variables already scrubbed two lines up.
Surfaced while triaging a non-blessed whole-suite invocation during the
#4145 wave (reproduced identically on master); the blessed sharded runner
can also co-schedule a GBRAIN_HOME-mutating file into this shard, so the
scrub closes a real flake vector, not just a synthetic one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): verify probe cleanup hard-deletes instead of leaving soft-delete tombstones
verify's end-of-run probe cleanup invoked the delete_page OP, which since
v0.26.5 is a SOFT delete — every verify run left two probe tombstone rows
in the user's brain (visible to include_deleted readers) until the 72h
purge. Cleanup now hard-deletes via engine.deletePage(slug, {sourceId}),
the same primitive sweepProbeLeftovers already uses on both engines, with
the warning-capture semantics preserved. Pinned by the (previously
failing) probe-residue assertion in the Postgres bootstrap-verify e2e.
Surfaced by the e2e fix wave: CI runs only 6 of 185 test/e2e files
(.github/workflows/e2e.yml), so the developer-lane files rot silently.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(search): deterministic relationalFanout path pick on equal-depth multi-seed ties
The fanout's representative-path pick ordered only by (depth, path
length); a node reachable at the same depth from multiple seeds had NO
tie-break, so the winner was plan/heap-order dependent — a fresh PGLite
and a lived-in Postgres heap could disagree, violating both engine parity
and the documented deterministic relational-retrieval contract. Appended
a lexicographic final tie-break to the array_agg ORDER BY in BOTH engines
(lockstep). The engine-parity e2e's multi-seed fanout case now passes on
real Postgres; its stale-page arm also moves off client wall-clock stamps
onto per-row updated_at_iso (the #1768 production semantics) so VM clock
drift can't skew the count.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): per-file outer-timeout override for LLM-bound Tier-2 files
run-e2e.sh's hard 180s-per-file gtimeout SIGKILLed skills.test.ts mid-run
(the ingest skill alone has been observed at ~131s of real provider
round-trips), producing a mystery failure with no assertion output. CI
runs the Tier-2 keyed files in their own job WITHOUT this wrapper, so the
cap only ever bit local runs. The cap is now GBRAIN_E2E_FILE_TIMEOUT
(default 180) with 4x for skills.test.ts + zeroentropy-live.test.ts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): un-rot the developer-lane files — 27 failures across 10 files, all green on both lanes
CI runs only 6 of the 185 test/e2e files; the rest run solely through the
developer-machine lane (bun run test:e2e / ci:local) and had rotted as src
moved deliberately underneath them. Every fix pins CURRENT intended
behavior with the causing commit cited in-file; no assertion was weakened
and several were strengthened. Root causes:
- sync.test.ts (13): the #2114 global-anchor ownership guard (636628fdb)
refuses anchor writes when the default source's local_path names another
repo; setupDB truncates config but not sources, so residue from earlier
files vetoed every bookmark write. The test now resets the default
source identity in beforeAll.
- v0_29-mcp-dispatch (2): the #4096 WP1/D7 locality backstop dispatches
localOnly ops only on transport 'stdio'; tests now dispatch with the
real stdio shape, plus a NEW fail-closed unknown_tool pin for unset
transport markers across both trust values.
- extract-atoms-discovery-sql (4): PR #2615 widened discovery to the
schema pack's extractable:true types ('note' included); tests re-pin
with 'person' as the non-extractable control + wider seed cleanup.
- pglite-cli-exit (1) + bootstrap-harness-lifecycle (1): the wrapper's
ambient DATABASE_URL leaked into subprocess/in-process env, silently
retargeting PGLite tests onto shared Postgres (#801 env-override
precedence); both files now scrub it at their boundaries.
- embedding-column-pglite (1): #3554 changed resetGateway() to restore
the test-preload baseline; the #3461 fallback test now uses
__unconfigureGatewayForTests() so the unconfigured path really fires.
- openclaw-plugin-load-real (1): the Retrieval Reflex import chain pulls
PGLite WASM assets into the bundle — bun build --outfile cannot emit
multi-output builds; switched to --outdir with entry naming + a
version-robust runtime inspection helper.
- phantom-redirect (1): halfvec migration (v40) + the #2932 idempotent
reconcile; the string-shape guard now accepts both legitimate vector
types.
- serve-http-oauth (1): sql.array() on a fresh connection races the
async typeArrayMap fetch and binds text instead of text[]; seed uses a
plain-array bind (the same untyped approach production pgArray() uses).
- type-unification-full-flow (1): checkPackUpgradeAvailable reads the
operator's real ~/.gbrain config; the test now isolates GBRAIN_HOME and
pins both the warn and ok arms hermetically.
Verified: full e2e lane 186/186 files, 1279/1279 tests on a pristine
pgvector container; the 14 previously-failing files re-verified green on
the residue-carrying locally-configured database as well.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): ship-review hardening — histogram lifecycle, cadence single-home, consumption re-clamp, DRY telemetry (#4145)
Fix-First batch from /ship's specialist + coverage reviews (21 findings,
all informational; the mechanical ones applied, the rest pinned by tests):
- The event-loop-delay histogram now disables in stop() and (re-)enables
in start() — each cycled worker instance previously leaked a ~50Hz
native sampling timer for process lifetime (embedding hosts and the
test suite cycle workers constantly).
- renewalIntervalFor()/RENEWAL_INTERVAL_CAP_MS: ONE home for the
min(lease/2, 60s) cadence formula, used by the worker's timer AND as
resolveLockRenewalKnobs' default intervalMs — previously the knob
default (lease/2 uncapped) diverged from production cadence for leases
over 120s, silently weakening the CDX-10 relational validation for
callers that omit intervalMs.
- Defense-in-depth re-clamp at consumption: launchJob clamps a row
lease through clampLockDurationMs — the exposed submit surfaces clamp,
but a writer bypassing add() could stamp a 1ms lease (renewal-storm
interval) or a ~25-day one (weeks-long dead-worker pin).
- formatAbortMeta(): one formatter for the classified abort telemetry;
the three log sites had already drifted (load1: vs load1_at_abort:).
- Knob docstrings updated to the capped defaults (min(lease/3, 15s) /
min(lease/6, 30s)); KEY_FILES dedup + stale-count scrub; dead test
binding removed; run-e2e.sh validates GBRAIN_E2E_FILE_TIMEOUT
digits-only before arithmetic/interpolation.
New pins: worker renews with the per-job lease (launchJob wiring, GAP-1);
claim precedence row-beats-map at the claim UPDATE; MCP submit_job
clamp round-trip incl. the 0→default boundary; jobs get lease lines
(all three states); bootstrap-verify tombstone-proof pages count on
PGLite; relationalFanout lexicographic WINNER (not just parity);
grace-env warn-once dedupe.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): adversarial-review hardening — claim-time clamp, grace cap, range CHECK, honest dry-run echo (#4145)
Two independent adversarial passes (Codex + Claude) converged on the same
lease-bounds gaps; this batch closes them:
- Claim SQL clamps the resolved row/map lease to [5s,1h] before deriving
lock_until, so a bypass-written out-of-range value can't produce a
pathological lease at claim time. The worker-default path ($2) passes
through untouched (tests pin a 1ms worker lease).
- Migration v130 + all 3 schema copies upgrade the CHECK to a full range
constraint (>= 5000 AND <= 3600000) — the DB bound now matches the
app-side clamp instead of only enforcing positivity.
- GBRAIN_MINION_STALL_RECLAIM_GRACE_MS is capped at 600s with a warn-once
(an absurd env value silently disabled stall reclaim fleet-wide).
- Hard-evict comparison recomputes elapsed AFTER the bounded verify, so
the backstop can't defer one extra cadence past its advertised bound;
the should_abort payload carries the recomputed value.
- Verify-failure telemetry re-samples loadavg at its own failure instead
of reusing a snapshot stale by the verify's duration; audit note that
the attempt counter advances by 2 per at-deadline tick.
- racedRenewLock/attemptReconnectOnce clear the losing race timer on the
win path (no stray late abort against a settled query).
- jobs submit --dry-run echoes the CLAMPED lease (annotated when it
differs from the raw input) instead of echoing a value add() won't store.
Tests: migrations-v130 range-CHECK rejection loop + bypass-clamp claim
test; grace-cap pin; dry-run echo cases. 301 pass / 0 fail targeted;
typecheck clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.6.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: document-release sweep for v0.46.6.0 — lease-bound enforcement, grace cap, e2e file timeout
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): stop run-child-entry SIGTERM test from broadcasting to leaked process listeners
The SIGTERM-semantics test fired a bare process.emit('SIGTERM') in the
shared bun test process. When an earlier file in the same shard had
installed process-cleanup.ts's signal handlers (module-global, never
uninstalled), the broadcast reached its handler, whose cleanup pass ends
in process.exit(143) — killing the entire shard mid-suite. The runner
then misclassified rc=143 as an external kill ("sibling workspace pkill /
memory jetsam") and queued a rescue pass that died the same way when it
reached the same test. Whether it fired depended on file interleaving;
under heavy host load the schedule made it deterministic (three
consecutive suite runs died at the ~3-minute mark with zero test
failures).
The test now snapshots the SIGTERM listener set before invoking
runChildJobEntry and fires ONLY the listener(s) the entry registered —
same wiring under test, no global broadcast.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: changelog entry for the unit-suite shard self-kill fix
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): best-effort tmpdir cleanup in run-child-entry afterAll — EFAULT rmSync flake reds the CI shard
CI shard 3 failed with an "(unnamed)" test: bun treats a throwing afterAll
as a failed test, and the hook's recursive rmSync EFAULT'd (bun 1.3.13,
ubuntu-24.04) immediately after the PGLite WASM engine teardown. All 8
real tests passed. Cleanup is now try/retry/warn — a tmpdir the OS reaps
anyway must never red the suite.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* perf(pglite): memoize snapshot loading — read the 42MB tar once per process, not per engine
tryLoadSnapshot re-read the snapshot tar and re-hashed all migration handler
sources on every engine construction (600+ per full suite, ~84MB transient
allocation each). The schema hash and the (versionLines, blob) pair are now
memoized per (path, process); missing/stale/torn paths memoize a terminal
null. The dims/model shape gate stays per-call so mid-process gateway
reconfiguration (the zembed/1280 class) still falls back to cold init —
pinned by new memo tests in snapshot-shape-guard.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* perf(test): pool the serial-test runner + wire the PGLite snapshot into every CI-facing runner
The serial lane ran 140 per-file bun processes strictly one-at-a-time (8.5
min in CI) — but the quarantine contract only requires per-PROCESS isolation.
run-serial-tests.sh now runs a pool (min(cpus,4), memory-adaptive, 120s
per-test budget, 300s SIGTERM-then-SIGKILL wall clock per file), keeps two
machine-global files on a sequential EXCLUSIVE lane (launchd/cron), treats a
missing exit sentinel as failure, and prints sorted per-file durations.
First full run: 140/140 in 145s at pool=4.
The snapshot fast-path (previously local-only) is now shared via
scripts/lib/test-env.sh (detect_cpus + mem detection + ensure_pglite_snapshot,
one implementation across the runner family) and wired into test-shard.sh
(+ --max-concurrency, mirroring the local runner), run-slow-tests.sh, and
run-e2e.sh's env-scrub keep-list. Serial lane also gains the #3485 ambient
DB-URL scrub its sibling lanes already had.
Guards: pool-behavior tests (fail → exit 1, full log; hang → timeout kill;
dry-run-list), EXCLUSIVE_FILES growth guard (≤3, justification comments),
missing-sentinel source pin, sandbox staging carries scripts/lib/.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(test): snapshot tar cache, one bun-cache saver, gitleaks tarball cache, shallow brainbench fetch
- PGLite snapshot (~42MB tar) cached across jobs keyed on schema inputs:
serial-tests saves, the 10-shard matrix + slow jobs restore-only; the
runner's own hash check stays authoritative (stale restores are rebuilt,
never trusted). Slow jobs export the snapshot env via the shared lib.
- Bun install cache: verify becomes the single saver (admin/bun.lock joins
its key); every other job restores with restore-keys so a bun.lock touch
no longer cold-installs all six jobs. All installs are --frozen-lockfile.
- gitleaks: the release tarball is cached; its published checksum is
fetched fresh and re-verified on every run, so a cache restore is never
trusted.
- brainbench: fetch-depth 1 + a depth-1 fetch of the master ref replaces
the full-history clone (the gate reads one file via git show).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(e2e,heavy,release,osv): parallel e2e tiers behind a spend gate, content-hash skip, cache/timeout hygiene
e2e.yml: tier2 no longer waits ~2min behind tier1 (separate DBs — never
shared state); it now gates on jsonb-parity (~40s), keeping a fast
broken-build spend gate in front of the job that burns real provider
tokens. New e2e-cache-check/e2e-cache-write (e2e-pass-<hash> namespace)
skip the whole suite on doc-only pushes; scheduled nightly runs are
exempt so the live-provider drift check always fires. e2e-status is the
stable aggregate name. Bun caches + --frozen-lockfile on all tiers.
heavy-tests: bun cache restores on all 4 jobs. release: timeout-minutes
on all 4 jobs (was 360-min default), bun caches, frozen installs.
osv-scanner: concurrency group cancels superseded PR scans.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(verify): bounded worker pool, longest-first ordering, chronicle gate, two revived guards
run-verify-parallel.sh fanned out 44 checks unbounded — two cp -R src +
bun build --compile builds, the admin vite build, tsc, and ~40 greps all
simultaneous on a 4-vCPU runner, feeding the 120s per-check timeout flake
class. The spawn loop is now a pool (default detect_cpus; escape hatch
GBRAIN_VERIFY_MAX_PARALLEL) with the heavy checks ordered first
(LPT-style makespan). 47 checks green in 38s locally.
New checks: check:eval-chronicle ($0 deterministic eval, exit-0-only-on-
perfect — first CLI-level CI gate for it), plus the two registered-but-
never-executed guards check:pagetype-exhaustive and check:pg-url-redaction
(the latter's marker now works inside block comments; its one legitimate
hit in the redactor's own docs carries the marker). A new registration⇒
execution coverage test closes the dead-guard class: every guards-manifest
row must be reachable from CHECKS or carry an explicit exemption reason.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(ci): collect evals/ tests into the matrix behind a keyless allowlist
evals/functional-area-resolver/harness-runner.test.ts (47 keyless tests)
was collected by NO runner — real tests that never executed anywhere.
test-shard.sh now finds test/ AND evals/; a new allowlist guard asserts
every collected evals file is keyless-verified (this repo's eval harnesses
are key-requiring by default, so unlisted growth would silently spend
tokens in CI). The isolation (R1-R4) and real-names lints extend their
scan roots to evals/ so everything CI executes carries the same hygiene bar.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* perf(test): shrink migrate dedup perf-gates to 200 rows; one engine for chunk-grain-fts
The two v8/v9 dedup gates inserted 1000 rows one-at-a-time each — ~15-25s
of row traffic per test that adds no discriminating power (the O(n²) shape
they guard is minutes-vs-sub-second at 200 rows; the full v7→current chain
replay they also pay is unchanged and still exercised).
chunk-grain-fts.test.ts booted three describe-scoped engines for 11 tests;
now one file-level engine + resetPgliteState per data-bearing describe
(the reset is required, not hygiene: the searchKeyword corpus would
pollute the searchKeywordChunks expectations).
The planned resetPgliteState pg_tables caching is deliberately NOT done:
the pre-agreed DDL check found 7 files that create/alter tables between
resets on a shared engine — a cached table list would skip truncating
mid-file tables and leak rows across tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(eval): hermetic CLI retrieval canary — deterministic embedder for eval gate, W1 mandate satisfied
gbrain eval gate gains an embedder option (deterministic) scoped to the
qrels correctness gate: query vectors come from a fixture-keyed basis
embedder (src/eval/deterministic-embed.ts, shared with the hermetic test)
through a new additive HybridSearchOpts.queryEmbedFn seam — the full RRF
pipeline (keyword/FTS, title, alias, relational arms + fusion) runs for
real with zero API keys. Bare hybridSearch is cache-free by construction
(lookup + writeback live only in hybridSearchCached), so deterministic
runs cannot poison query_cache. Behavior is unchanged when the seam is
absent. Flag registry regenerated.
scripts/run-eval-canary.ts seeds a throwaway PGLite brain from the qrels
corpus (expected pages visible to page-grain FTS via timeline — pages
FTS deliberately excludes compiled_truth) and spawns the real CLI:
check mode (CI, writes nothing) is wired as check:eval-canary in verify;
record mode appends the committed .gbrain-evals/eval-results.jsonl ledger.
Measured, deterministic across processes and keyless: recall@10 1.0000,
first_relevant 1.0000, expected_top1 0.8333 vs floors 0.70/0.60/0.50.
The FIX_WAVE_BASELINES W0 retrieval-canary mandate is now PASS (recorded
with honest scope: synthetic vectors gate the ranking pipeline; semantic
embedding regressions remain the keyed suites' job). Spike-first design
per the plan's OV2-1 respec.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(test): current-state TESTING.md for the pooled/pool-bounded runners; TODO ledger updates
TESTING.md: pooled serial lane (+EXCLUSIVE lane, knobs, timings), verify
worker pool + eval gates, snapshot-in-CI, evals/ collection, e2e cache-skip
+ e2e-status. ci-local.sh: stale "36 E2E files" comments (actual 181).
TODOS: deeper-speedup entry closed by this pass; test.concurrent P0
downgraded to P3 with stale-premise rationale; eval-gate baseline entry
narrowed to the sibling-repo regression half; 7 pass deferrals filed with
context (sleep-to-poll, e2e lanes, per-shape snapshots, persistent-engine
snapshot, engine-consolidation audit, verify double-spawn, image-decoders).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(ci): re-mine shard weights post-snapshot; p75 fallback; balance test asserts what CI runs
Weights re-mined from the branch's green Test run (31893516029): 1200/1212
files covered (was 663/1204 — 45% of the corpus rode a 30ms median fallback
while really averaging seconds), total mined suite time 986s vs 3185s
pre-snapshot. Rebalanced 10-shard totals: ~99s each.
sharding.ts missing-file fallback median → p75 (the distribution is
right-skewed and unweighted files skew heavy — new integration tests land
unweighted more often than pure-unit ones).
The balance regression test previously recomputed shard totals with the
same weights map + same fallback the partitioner used (max/min ≈ 1.0 by
construction) and asserted 4/6-shard splits while CI runs 10. It now:
asserts the 10-shard split with the shard count cross-checked against
test.yml's matrix (js-yaml parse, not a format-brittle regex), gates
weights coverage ≥70% of matrix-eligible files (the anti-rot forcing
function the regen cadence never had), and fails on weight keys naming
untracked files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): external-kill rescue pass for the serial pool; brain-repo-durability goes exclusive
Two contention classes surfaced by the first pooled CI runs:
1. Stray SIGTERM/SIGKILL from outside the runner (sibling-workspace process
cleanup, memory jetsam) killed 1-12s-old bun processes with exit 143 and
truncated logs — the exact class run-unit-parallel.sh already rescues.
The serial runner now queues exit 143/137 and missing-sentinel files for
ONE sequential rescue re-run: phantoms stay green with a rescue note,
real failures fail again and stay red. Pinned by a self-SIGTERM-once
fixture test.
2. brain-repo-durability.serial.test.ts: hardenBrainRepo's scaffolding
commit fires the just-installed post-commit hook (background push) which
races the synchronous push-probe on the same bare remote — "cannot lock
ref" lands in needs_attention. Near-deterministic on a contended 4-vCPU
runner, never observed locally. Moved to the sequential EXCLUSIVE lane
(third justified entry; growth guard capped at 3) until the probe learns
to retry ref-lock contention.
Also fixes a duplicated word in the runner's timeout header line.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(test): document the serial pool's external-kill rescue pass
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes
From the ship-stage specialist review (testing/maintainability/security/
performance):
- serial runner: exclusive-lane files keep their no-kill contract on rescue
re-runs; exit 137 at full duration is classified as our timeout's SIGKILL
escalation (real failure), not an external kill — no ~315s re-hang in rescue
- snapshot memo: tar read deferred until the first shape-MATCHING caller —
a process that only ever refuses (zembed/1280 class) now reads zero bytes
- e2e.yml: workflow_dispatch joins schedule in the cache-skip exemption (a
manual dispatch is an explicit ask for a live run)
- test.yml: verify job restores the snapshot cache like its siblings;
cache-key homes cross-referenced
- eval gate: the four embedder-flag validation exits are now asserted;
legacy-qrels parsing deduped into deterministic-embed.ts
- canary test: git-status invariance scoped to touchable paths; outer spawn
budget strictly above the inner CLI timeout
- doc/comment rot: TESTING.md exclusive-lane count, runner header, sharding
test comments, ci-local.sh sentence, CI_SHARDS in a test name
- TODOs: snapshot-tar digest verification (P3) + eval-ledger redaction (P2)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): serial pool re-emits a bun-format pass aggregate; ledger gets merge=union
The pooled runner's compressed per-file lines starved run-unit-parallel.sh's
headline counter (awk wants " N pass") — bun run test's pass=N banner
silently dropped the entire serial suite. The runner now emits one
aggregate " N pass" line in bun's own summary format. Failing files' logs
stream raw, so fail counting was never affected and stays single-counted.
.gbrain-evals/eval-results.jsonl (append-only tracked ledger) takes
merge=union so concurrent workspaces recording runs don't conflict.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.1.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.46.1.0
- eval-bench.md: document the hermetic --embedder deterministic correctness-gate
mode and the check:eval-canary CI gate (scripts/run-eval-canary.ts, --record)
- KEY_FILES.md: current-state updates — eval-gate hermetic mode +
deterministic-embed.ts + canary runner in the eval-loop entry, queryEmbedFn
seam in the hybrid.ts entry, per-process snapshot memoization + the shared
scripts/lib/test-env.sh helper in the snapshot entry, guard count 45→46
- TESTING.md: snapshot activation now via ensure_pglite_snapshot across five
runners (was two callers), honest per-file speedup figures (~3.5x), serial
runner output/knob semantics (GBRAIN_SERIAL_POOL=N width), CI shard
--max-concurrency bound, p75 missing-weight fallback
- CONTRIBUTING.md: drop the orphaned duplicate guard-checks line
- CHANGELOG.md (voice only): "every CI runner" -> "the CI test runners";
note the p75 fallback in the shard-rebalance clause
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: re-bump to v0.46.2.0 (0.46.1.0 claimed; user-pinned)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs(mcp): pin observed opencode CLI behavior (OPENCODE-CLI-PIN.md) + registration guide
Phase-0 hermetic observation of opencode-ai@1.18.18 (npm wrapper + platform
payload integrities pinned). Load-bearing observations: keyless anonymous
free tier answers headless runs AND drives MCP tool calls without --auto
(nonce SMOKE proven end-to-end against a real gbrain serve --surface verbs);
mcp list is the honest discriminator (spawns servers, exit 0 regardless —
parse the text); mcp add takes '-- command' (undocumented in --help) but
always writes user-global opencode.jsonc; project-defined local servers
spawn with NO trust gate (drives the user-global bootstrap default); JSONC
parses in .json-named files and both filenames merge; OPENCODE_CONFIG* env
vars observed inert (docs-contradiction, called out); OPENCODE=1 set in bash
children (detectHarness probe); AGENTS.md loads, CLAUDE.md not double-loaded.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): opencode-json managed config writer + opencode-2026-08 host spec
- src/core/bootstrap/opencode-json.ts: comment-preserving JSONC writer
(jsonc-parser surgical edits — opencode's own mcp add preserves comments,
the writer matches that bar). Ownership is a 4-state structural
fingerprint (ours-same-source | ours-other-source | foreign | absent)
keyed on GBRAIN_SOURCE EQUALITY ([FIX7] parity), never a marker key.
Distinct read-failure classes (ENOENT create / empty-as-{} / unreadable
refuse); foreign refusal on write AND remove; post-render validation
(our entry round-trips, every other key survives) keeps the original on
failure; 0600 + .bak-0600 only for inline-bearer entries; bearer
recovery helper for harness --status.
- host-specs.ts: TARGETS['opencode-2026-08'] (verified 2026-08-15 against
a hermetic opencode-ai@1.18.18) + opencodeConfigDir/GlobalConfigPath/
ProjectConfigPath (XDG-only — OPENCODE_CONFIG* observed INERT in
1.18.18, honoring them would be a silent no-op install) +
OPENCODE_HAS_HOOKS=false.
- atomic-write.ts: rule-of-three extraction of the symlink-resolving,
mode-inheriting atomic writer; codex-toml.ts + hooks.ts ported onto it
(behavior pinned by their existing suites).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): opencode workspace lane — hooks --harness opencode, scope-aware direct-writer registration, channels, templates
The Harness union widening is typecheck-SILENT at every existing
'claude-code ? A : B' ternary, so the hot sites now dispatch exhaustively
(HARNESSES satisfies anchor; exec-lane bin map returns null for opencode —
its registrations go through the JSONC writer whose fingerprint IS the
[FIX7] check, never through <host> mcp get).
Scope INVERSION for opencode: default user-global (opencode spawns
project-config-defined MCP servers with NO trust prompt — verified; a
committed project entry would auto-execute on every collaborator machine).
MCP_SCOPE=project is an explicit opt-in that writes the workspace
opencode.json with a PATH-resolved command (committed-candidate file: no
absolute machine paths, no fail-open analog exists) and prints the sharing
warning + enabled:false opt-out. detectHarness probes OPENCODE/OPENCODE_PID
(observed 1.18.18). Ownership: a remote-type mcp.gbrain in the global
config makes the stdio lane step aside (codexBlockOwnsName analog); foreign
entries refuse. Verification: writer post-render parse-back is
authoritative; best-effort 'opencode mcp list --pure' probe (skipped on
plugin-bearing configs — mcp list is a code-execution surface).
Atomic with this commit (each-commit-green): questions.json MCP_SCOPE +
SURFACE_PRIMARY copy, AGENTS/GITHUB template pull-protocol generalization,
BOOTSTRAP_FOR_AGENTS.md scope guidance + opencode wiring bullet,
status.ts interview/wire resume hints, check-bootstrap-templates.sh §(e)
pins (now 'Claude Code and opencode' + the 'NO trust prompt' spawn-gate
rationale pin), guard-test fixtures, the status-test hint pin, the vendored
template-repo regen, the offline docker opencode leg, and uninstall's
receipt-keyed opencode removal. Channels: 'opencode' joins
VOLUNTEER_CHANNELS + HARNESS_CHANNELS (reserved attribution slot, codex
precedent).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): opencode harness-mode target — managed remote entry with inline bearer, remove/status/rollback
HarnessSelector gains 'opencode' (forced-wire like codex: the JSONC writer
needs no opencode CLI). Wiring is one managed mcp.<name> remote entry with
the inline Authorization bearer in the user-global opencode config, 0600,
under the [X11] lock ordering (config-dir → opencode-dir). Ownership [C8]:
idempotent re-runs match on the serve url; rotation across a url change
recognizes the old entry via the PRIOR receipt's url; anything else under
the name refuses inside the writer. Failed-smoke rollback restores the .bak
or removes a fresh entry, and the fresh mint is revoked (impostor-guard
economics hold). --remove classifies against the receipt url and skips
not-ours entries with a note; --status recovers the bearer from the entry
(url-matched — a foreign entry's credential is never transmitted). Consent
copy: per-host numbered item, joined-list reach statement (a fourth harness
can no longer silently mislabel the ternary tree), opencode off-ramp.
Fixture hygiene: the harness serial fixture now injects opencodeConfig +
detectOpencode — the default path resolution reaches the operator's REAL
~/.config/opencode (the claudeUserSettingsPath lesson, caught live when the
registrar-mode test wrote a fixture token there; cleaned up).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(connect): --agent opencode — env-interpolated bearer, direct-writer --install
buildOpencodeMcpAddArgv pins the validated one-liner: the --header value
carries opencode's {env:GBRAIN_REMOTE_TOKEN} interpolation LITERALLY, so the
token never enters argv, the config file, or --json output. The print block
mirrors codexBlock (export line + one-liner + restart note). --install goes
through a new ConnectDeps.writeOpencodeRemoteEntry member (the existing
injectable seam, connect.ts:ConnectDeps) wrapping the JSONC writer in env
token mode — no opencode binary required, idempotent re-runs, foreign
same-name entries refuse with the writer's message (token-redacted), and
the D4 probe smoke-tests the credential end to end.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(claw-test): opencode runner — detection, pinned one-shot invoke, multi-provider env allowlist
OpencodeRunner (4th AgentRunner): detectBinary('OPENCODE_BIN','opencode');
argv pinned to 'run <brief> --format default' (explicit format so an
upstream default flip cannot silently change the transcript shape; NO
--auto — MCP tool calls fire in run mode without it, verified). Env
allowlist = BASE + an EXPLICIT multi-provider delta (XAI / Google / Gemini
/ OpenRouter keys — BASE carries only Anthropic+OpenAI, and a live-lane
operator on other providers would otherwise see a misleading auth failure)
+ XDG dirs + OPENCODE_CONFIG(_DIR) + OPENCODE_DISABLE_AUTOUPDATE;
OPENCODE_CONFIG_CONTENT (the inline config-shadow channel) deliberately
absent. Bare-semver version preamble (the SST-vs-claimant discriminator)
+ global-config mcp.gbrain contamination tripwire (JSONC-tolerant, checks
BOTH merged filenames). --list-agents pin moves to all four runners with
the openclaw<opencode ordering note.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(test): door-family extraction in agent-harness — shared resolver/childEnv/spawn core; grok+hermes ported; opencode first consumer
The 'P3 — Door-adapter extraction + CI-tail composite action' TODO armed
this at 'the NEXT door agent (4th)' — opencode is the 4th. Test-side only
(the composite CI-tail action stays deferred until the first green
grok-door AND opencode-door dispatches; workflow yaml can't be proven
locally).
- makeBinaryResolver: one shape (fail-closed $*_BIN > which > landing
spots + nvm/PATH sweeps); claude/codex/hermes/grok resolvers become
factory products with identical candidate lists.
- makeAgentChildEnv + GITHUB_STEP_META_KEYS: hermeticChildEnv + per-agent
overrides + key deletion + the step-metadata scrub + binDir prepend.
hermesChildEnv GAINS the GITHUB_* deletion via the factory (the filed P2
backport; truth-table extended).
- runOneShotSpawn: shared timeout/kill/kill-9-escalation/bounded-drain core;
hermesOneShotTurn gains the escalation + bounded drain (strictly safer,
nothing pinned the old unbounded wait); grokOneShotTurn is now a thin argv
builder over it.
- 5a-opencode family (first consumer): resolveOpencodeBinary (fail-closed
OPENCODE_BIN), hasOpencodeAuth (PAID-leg-only gate — the keyless free
tier carries the core SMOKE), opencodeChildEnv (HOME + BOTH XDG dirs,
anthropic re-admission, other-provider + OPENCODE_CONFIG* shadow-trio
deletes), seedOpencodeConfig (config half of the double autoupdate kill),
opencodeOneShotTurn, and parseOpencodeJsonl (event shapes pinned from the
live v1.18.18 observation — {type,part} with part.text / part.tool).
EV1 gate (local keyless grok-door): 4 pass / paid-skip in 20.5s BEFORE and
AFTER the port, against a hermetically npm-pinned @xai-official/grok@1.0.4.
The hermes door self-skips without a binary — its port is pinned by the
unit truth-tables (stated honestly, per the plan).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): opencode door — split-gated real-binary e2e on the extracted family (keyless SMOKE included)
The door goes a step beyond grok's split gating: opencode's anonymous free
tier drives MCP tool calls with zero credentials (observed, load-bearing),
so even the nonce SMOKE runs keyless. Tiers: T1 bare-semver version pin
(the SST-vs-claimant discriminator), T2 INSTALL via the documented
'mcp add … -- gbrain serve --surface verbs' shape + the honest 'mcp list'
discriminator (spawns servers; ✓/✗ text asserted — exit code is 0 even on
failure), T2b spawn-gate CANARY (a project-config decoy is spawn-attempted
with no trust prompt — if this ever gates, the bootstrap user-global
default rationale changed: re-observe), T3 writer parity (gbrain's
opencode-json.ts output handshakes through the real binary; cross-tool
preservation both ways incl. the autoupdate seed), T4 keyless SMOKE
(per-run nonce + STRUCTURAL gbrain_* tool_use proof via parseOpencodeJsonl,
list preflight before any turn, 2 attempts), and the paid T5 anthropic leg
(hasOpencodeAuth-gated; self-validating models-gate pins the model id
BEFORE any spend). Hermeticity: HOME + both XDG dirs per child, tmp cwds,
config/credential tripwire over the operator's real opencode state,
checkout guard, --pure on every probe (mcp list autoloads plugins), --pure
placed BEFORE the '--' separator (a trailing append lands inside the server
command — caught live). run-e2e.sh scrubs the OPENCODE_ prefix.
Verified live: 6/6 pass in 35.8s (keyless tier + paid anthropic leg)
against the hermetically pinned opencode-ai@1.18.18.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(heavy): opencode-door job (day-one full posture, keyless SMOKE) + canary leg + pin guards + hermes installer re-pin
opencode-door takes hermes-door's triggers (nightly + labels + dispatch;
cadence policy: nightly for the NEWEST door agent) with grok-door's
internals — keyless-first ordering, secretless npm provisioning with
wrapper AND per-platform integrity pre-checks, pass-count + paid sentinels,
mid-job version-drift tripwire, evidence scrub RE-KEYED to
ANTHROPIC_API_KEY + auth.json (not XAI/mcp_credentials), unconditional
credential removal. No dedicated dispatch input (any workflow_dispatch
already passes the non-PR arm — an input would be dead yaml). The keyless
tier includes the nonce SMOKE (free tier), so the core door needs NO
secret; the paid anthropic leg rides the secret hermes-door already
consumes. opencode-door-canary lands IN-WAVE (schedule-only,
continue-on-error, unpinned latest): opencode ships near-continuously — a
red canary is a pin-refresh signal, never a gate. real-agent-e2e adds the
opencode door file + env pins.
Guards: check-opencode-pin.sh (stamp↔workflow parity, job-block anchored so
the UNPINNED canary leg cannot satisfy it; fail-closed when the door exists
without the pin doc) and check-pin-doc-privacy.sh (placeholder discipline
for ALL docs/mcp/*-CLI-PIN.md — no operator home paths, no key-shaped
material outside sha512 pins, no non-example emails), both in bun run
verify + guards-manifest, both with fixture-tree bun tests.
Maintenance: hermes-door installer pin refreshed (upstream install.sh
drifted past the prior digest — last two nightlies red; reviewed: the
--commit payload-pin path is intact and the payload pins are unchanged).
docs/TESTING.md gains the opencode door entry + the door cadence policy.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: opencode across the install/testing/architecture surface
README client roster + remote-connect bullet (with the not-OpenClaw
disambiguation and the bootstrap-supported banner), INSTALL_FOR_AGENTS
'If you are opencode' block (routes bootstrap-capable readers to the
runbook; brain-only registration otherwise), docs/INSTALL per-client list,
MEMORY_VERBS register snippet, bootstrap guide (degradation-matrix row
naming the INVERTED scope default + rationale; harness-mode opencode
bullet; dx-explore scenario line), ambient-recall/push-context harness
mentions, and KEY_FILES current-state entries (opencode-json.ts,
atomic-write.ts, connect/harness/hooks/claw-test entry refreshes).
llms bundles regenerated (build:llms chaser).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* dx(explore): opencode-install TTY scenario — bootstrap paste block under the real interactive TUI
Unlike grok's brain-only prompt, opencode gets the FULL bootstrap paste
block (it is a bootstrap-supported harness) under a hermetic HOME + both
XDG dirs, the double autoupdate kill (config seed + env), BROWSER=false so
a first-run can never bounce the operator's browser, and auth.json
pre-registered for the secret scrub. Keyless posture INVERTS the grok
scenario: the anonymous free tier means a --keyless run should COMPLETE
the flow — a sign-in wall here is itself a pin-refresh signal, and the
generic early-stop in runInstallSession records it as friction if it ever
appears.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(todos): file opencode-wave follow-ups + retire fired triggers by title
Door-adapter extraction (test-side) and cadence policy: DONE — the 4th-door
trigger fired. CI-tail composite action re-filed with the sharpened trigger
(first GREEN grok-door AND opencode-door dispatches). hermesChildEnv
GITHUB_* backport: DONE via the shared factory. PIN-doc privacy guard:
DONE (check-pin-doc-privacy.sh in verify). New follow-ups: first-dispatch
watch, plugin/event-system wiring (ambient-recall lane), BrainBench
adapter (with hermes+grok), connect --oauth authorization-code lane,
OPENCODE_CONFIG* re-observation on bumps, opencode-install PTY promotion.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: coverage pins for the opencode channel widenings
Ship-audit additions: hook.ts --harness opencode flag-parse attribution
end-to-end, and 'opencode' membership in VOLUNTEER_CHANNELS +
isHarnessChannel (a regression here silently rebadges opencode deliveries
as claude-code).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): close two plan-audit gaps — ACCESS_POLICY opencode scope paragraph + doctor host:opencode pin
Plan-completion audit (ship Step 8) flagged both as PARTIAL: the
ACCESS_POLICY template's MCP-scope section didn't state opencode's
inverted default (user-global; project spawns with NO trust prompt),
and bootstrap_harness_health had no named pin proving an opencode
receipt flows through the host-generic filter. Template-repo regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes — review-army + red-team wave
Security: opencode error-path snippets render <paste-token-here> instead
of the live bearer; the harness opencode catch redacts like the claude
lane; test-harness child envs unconditionally drop GITHUB_TOKEN/ACTIONS_*.
Correctness: bootstrap-lock coverage for every shared-config writer
(hooks/connect/uninstall); uninstall + step-aside gate sweep BOTH global
opencode filenames (merged namespace); uninstall passes a sourceId
expectation and skips other-workspace entries; cross-kind fingerprint
matches classify ours-other-source instead of silently replacing;
dangling-symlink writes preserve the link; failed-smoke rollback restores
atomically; registration probe pins OPENCODE_DISABLE_AUTOUPDATE, a 20s
cap, ANSI-stripped exact-name matching. Guard: check-opencode-pin now
cross-checks per-platform integrities + every OPENCODE_VERSION copy.
Plus deny-path/uninstall/rollback/truth-table/symlink test coverage,
help-prose cosmetics, downgrade doc note, 3 P3 TODOs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial-review fix wave — cross-model (Claude + Codex) findings
P0: the registration probe no longer executes from the invoking cwd
(mkdtemp cwd for user scope; project scope skips the live probe —
parse-back is authoritative), so a cloned repo's committed opencode.json
can't gain code execution during bootstrap. Probe timeouts now kill the
child (SIGTERM→SIGKILL, bounded drain) instead of abandoning it over the
PGLite lock. Global writes reconcile mcp.<name> across BOTH merged
global filenames. Stale-target cleanup takes the target config-dir lock.
Backups are unique per operation; rollback is content-guarded and
remove-path backups tighten to 0600 when token-bearing. connect --force
now works on the opencode lane with url-appropriate refusal copy.
atomic-write cleans tmp litter and survives the exists/realpath race.
Bun-lane fingerprint is fail-closed on gbrain-less args. Scope answers
trim. bounded() clears its drain-cap timer. CI installs opencode from
byte-verified tarballs. Consent-semantics + hermetic-live-runner
follow-ups filed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: regen cli-flag-registry after review-fix waves
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.2.0 feat(opencode): full-parity client support — bootstrap, harness, connect, claw-test, e2e door
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: fold the post-review opencode fix-wave behaviors into KEY_FILES
Three current-state completions the fix agents didn't carry into the
per-file index: connect --agent opencode --install's --force semantics
(maps to the writer's allowReplaceOtherSource — ours-at-old-url
replaceable, foreign still refuses), removeOpencodeMcpEntry's
skipOtherSource option, and bootstrap uninstall's expectation-keyed
opencode sweep (both merged global filenames under the config-dir lock
plus the project file; other-workspace entries skipped with a note).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: cross-model doc-review fixes — opencode roster + probe/remote accuracy
Findings from the standard post-ship Codex doc review, verified against
the shipped code: the bootstrap guide's intro, install table, and door
inventory still described a two-client product (opencode added to all
three); INSTALL_FOR_AGENTS' grok section said the personal-agent path is
Claude Code/Codex only; OPENCODE.md called its recipe the bootstrap
"manual equivalent" (bootstrap additionally pins GBRAIN_SOURCE + full
surface), lacked the mcp-list trust caution the pin doc carries, and
never documented the connect --install / --force remote lane; the pin
doc's provisioning bullet now names the pack-verify-install posture the
CI job actually runs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.4.0 chore(release): re-bump 0.46.2.0 → 0.46.4.0 (version slots claimed by in-flight PRs)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(ai): Voyage reranker touchpoint + recipe sunset metadata + split-default constants
- Recipe.sunset (per-touchpoint replacement) on zeroentropyai; once-per-process
warn-on-use in the gateway for embedding + rerank, with a test reset seam
- Voyage reranker touchpoint: rerank-2.5/-lite at /rerank, request key via
top_param ('top_k'); response parser accepts both results[] (ZE/llama-server)
and data[] (Voyage REST, live-wire verified)
- EmbeddingTouchpoint.default_model (voyage-4 — array order is quality-sorted,
not recommendation-sorted); voyage-code-4 added incl. dims.ts membership
- Split-default: NEW_INSTALL_DEFAULT_* constants (voyage-4 @1024 + rerank-2.5);
the legacy configless runtime fallback stays zembed-1 @1280 until the
September removal so no existing brain changes behavior
- Voyage reranker + voyage-code-4 pricing rows (verified 2026-08-15)
* feat(init): new installs land on Voyage; sunset providers hidden from pick surfaces
- Auto-pick, multi-key canonical tiebreak, --embedding-model shorthand, and the
interactive picker (selection + displayed row) all resolve default_model
- Recipes with sunset metadata are excluded from auto-pick and the picker;
explicit --embedding-model still works with a loud warning
- Voyage-picked installs write search.reranker.model voyage:rerank-2.5 as
explicit per-brain config (never clobbers an existing choice)
- Keyless fresh installs size the embedding column at the new-install width
(1024) via an explicit init param; schema generators keep the legacy import
- gbrain providers flags sunsetting providers as DEPRECATED with the
replacement, regardless of key readiness
* feat(migrations): v0.47.0 detect-and-notify migration + shared ZE exposure detection
- src/core/ze-exposure.ts: exposure = effective-model resolution (env → file →
legacy fallback), never vector evidence; resolved-reranker + custom-column
axes; tri-state status (probe failure → unknown, never silently clear);
LIMIT-capped blast radius with a re-embed cost estimate; shared
renderZeActionRequired for the migration notice and the upgrade banner
- v0.47.0 registry migration: notice-only — no config writes, never invokes
migrate embeddings; unknown exposure completes with a loud advisory +
pending-host-work entry instead of wedging the migration chain
- skills/migrations/v0.47.0.0.md: agent playbook (key-detection ladder,
target-aware dims, reranker fix, custom-column honesty, wire-accurate
self-host path)
* feat(sweep): stop steering anyone at ZeroEntropy; stage-2 sunset banner; doctor fixes
- ze-switch forward + --resume refuse with the migrate-embeddings escape route
(--undo and --dry-run still work until the September removal)
- provider_sunset doctor fix-hint is target-aware on dimensions (voyage at its
valid 1024 step; OpenAI keep-width only when valid); reranker hints name the
provider's key generically
- Stage-2 upgrade banner (ze_sunset_notice_v2_shown) via detectZeExposure —
fires on exposed, on unknown (fail-safe), and on a ZE-resolved reranker
without a Voyage key; stage-1 banner's self-host copy made wire-accurate
- doctor.suppress_provider_sunset registered so the documented suppression
command works; advisor/queue/probe/preflight/ops copy stops recommending ZE
or refused commands; minion provider list derives from the recipe registry
* test(e2e): Voyage live wire suite + date guard on the ZeroEntropy live suite
- voyage-rerank-live: skip-gated real-key confirmation of the rerank wire
(top_k request, data[] response, ordered results) + a voyage-4 1024d embed
- zeroentropy-live auto-skips on/after 2026-09-04 so a slipped removal wave
cannot leave CI permanently red against a dead API
* docs: Voyage-first provider story; ZeroEntropy marked deprecated everywhere
Current-state sweep across README, install guides, provider matrix, migration
guide, retrieval architecture, KEY_FILES, and tutorials; September-removal
staged-deletion inventory filed in TODOS.md; llms bundles + CLI flag registry
regenerated.
* fix(ci): ci-local smoke count mirrors run-e2e's +1 phantom-redirect entry
run-e2e.sh deliberately appends test/phantom-redirect-engine-parity.test.ts
(Postgres arm needs the DATABASE_URL lane, #3485) to the test/e2e glob, but
the ci-local smoke check counted only the glob — the check fails on any tree
once the two counts drift. Pre-existing on master; surfaced here by adding a
new e2e file.
* fix: pre-landing review fixes
- providers explain matrix honors default_model + flags sunset providers as
deprecated (and never recommends one); no-key recommendation → the voyage
default
- ze-exposure: registry keys validated before rendering into the agent-directed
banner (text-injection hardening); width-honest OpenAI copy (a static 1280
was wrong for 640d/2560d brains — doctor prints the exact command);
dims interpolated from the NEW_INSTALL constant; cappedCount marked private
with a no-dynamic-SQL contract
- upgrade: drop the unreachable rerankerGate disjunct (reranker exposure is
already status=exposed) and correct the comment
- init: both --no-embedding hints stop recommending the refused
`config set embedding_model`; duplicated voyage-reranker-override blocks
extracted into one shared helper
- ze-switch refusal message interpolates the sunset/default constants
- v0.47.0 migration: version/skill literals hoisted to constants; redundant
dynamic import removed; pending-host-work append gains a torn-write newline
guard; a FAILED host-work write now returns partial (retries next run)
instead of complete
* test: coverage for the v0.47 surfaces the review flagged
- fresh-install e2e: voyage init writes the rerank-2.5 override; re-init never
clobbers an explicit reranker choice; explicit sunset-provider init proceeds
WITH the loud warning (D3 allow-explicit); keyless installs size at 1024
- picker units: sunset providers not offered; voyage pick resolves the
canonical voyage-4 (selection AND displayed row)
- sunset warn-on-use: embedding-touchpoint call site + migrate copy
- ze-switch: --dry-run --json planned envelope restored
- voyage live e2e header/test names corrected to the data[] wire truth
* chore: bump version and changelog (v0.47.0.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial review fixes — sunset-target gate, keyless recovery, file-plane keys
- migrate embeddings refuses a sunset TARGET (agent replaying an old runbook
would strand the brain onto the dying provider days before the shutdown);
--force-sunset-target is the loud self-hoster escape hatch, threaded through
planEmbeddingMigration but deliberately NOT exposed on the MCP op.
- The documented keyless recovery command (`init --force --embedding-model ...`)
now actually works: an explicit flag clears the seeded embedding_disabled
sentinel AND the persist block stops re-writing the stale sentinel inherited
via the ...existingFile spread (both engine paths).
- init provider readiness folds FILE-PLANE keys (buildGatewayConfig env) so a
config.json-keyed non-interactive install stops silently landing keyless;
fresh installs with only a sunset key get told which key was ignored and why.
- New-install reranker default generalized: voyage-keyed installs (any
embedding provider) get the voyage override; keyed non-voyage installs get
an explicit disable instead of inheriting the doomed legacy bundle default;
keyless installs get NO write so the recovery re-init still lands its
override; never-clobber checks both reranker config keys.
- doctor provider_sunset grows a custom-column arm (shared
detectZeCustomColumns helper) — no more ok while ZE-backed columns are live.
- ze-exposure: capped blast radius renders a cost FLOOR ("at least ~$X");
base-URL override surfaces a self-host note instead of claiming certain
death; gateway warn-on-use skips base-URL-overridden providers entirely.
- v0.47.0 migration: unreachable-brain fake engine now THROWS from getConfig
(returning null fabricated verified claims); detection crash still prints a
self-contained fallback ACTION REQUIRED banner.
- providers explain prices the CANONICAL model via lookupEmbeddingPrice
(recipe-wide hint tracks the flagship, wrong for voyage-4);
embed-preflight + advisor recommendation copy swept to effective-model-aware
non-refused commands.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: pin the adversarial-review fixes
- resolveMigrationTarget: sunset-target refusal + allowSunsetTarget escape.
- file-plane voyage_api_key → buildGatewayConfig fold → provider ready
(ambient-env-scrubbed).
- e2e keyless → keyed recovery round trip: embedding_disabled cleared, model
persisted, reranker override lands (keyless init left reranker config
virgin).
- e2e keyed non-voyage install: reranker explicitly disabled, no model
override written.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: document --force-sunset-target in the migration guide + playbook
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: credential-free unreachable-brain fixture (secret-scan guardrail false positive)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: document-release audit — align docs with final behavior; unbreak compat-fetch proximity pin
Post-ship /document-release pass over the final diff. Reranker-default copy
corrected everywhere to the generalized truth (voyage-KEYED installs get the
override on any provider; keyed non-voyage installs get an explicit disable;
keyless installs get no write); --force-sunset-target + doctor's target-aware
commands and custom-column arm documented; headless-install pattern replaced a
hard-refused `config set embedding_model` ENTRYPOINT with the sanctioned
re-init; README/integration guides updated to keyless-continue + file-plane
key detection truth. zeroentropy-compat-fetch's source-text proximity window
widened (the sunset warn-on-use hook landed between the pinned cast and
resolveEmbeddingProvider). llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: withEnv() for the file-plane fold test (test-isolation R1 gate)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.46.3.0 chore: re-version the wave 0.47.0.0 → 0.46.3.0 (natural next off master)
Master sits at 0.46.1.x; this wave takes the natural next slot instead of
leapfrogging. The rename cascades through the migration identity — a registry
migration numbered above the binary version would be skipped as future —
so v0_47_0 → v0_46_3 (MIGRATION_VERSION 0.46.3), the agent playbook moves to
skills/migrations/v0.46.3.0.md, and every code/doc/test reference follows.
The September removal target label shifts v0.48 → v0.47 to keep the
deprecation→removal pairing consecutive. Lockfile, templates, skills
manifest, and llms bundles regenerated; typecheck + full verify (44/44) +
migration/version-coupled suites (288 tests) green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(dream): scored triage-v1 cascade gates frontier synthesis (#4152)
Migration v129 widens dream_verdicts with score/content_type/segments/
entities/model/triage_version (legacy boolean rows = cache miss, re-judged
once). judgeSignificance emits an ordinal 0-1 salience score with
non-overlapping bands, three-window head/middle/tail sampling, and a
never-clamp out-of-range rule; degenerate verdicts are never cached.
runTriagePass (exported, shared with retriage) runs a bounded pool under a
dream.triage.max_ms wall-clock miss budget with (model, TRIAGE_VERSION)
cache validity; the gate score >= dream.triage.threshold is applied at read
time so retuning costs zero re-judging. Passing files carry a
verbatim-verified TRIAGE MAP block into the synthesis prompt;
dream.synthesize.max_turns defaults to 16 (config-restorable, pinned by a
regression test); an opt-in per-source daily cap fails open on count-query
errors and never stamps the cooldown when nothing was submitted; stranded
dream-inline-* rows self-heal behind a 1h liveness grace.
* feat(dream): retriage command — spend-gated re-score + backlog reconciliation (#4152)
gbrain dream retriage re-scores the corpus through the shared runTriagePass
and reconciles the queued synth-v2 backlog: below-threshold jobs cancel,
above-threshold jobs stranded in provably-dead dream-inline-* queues (older
than the 1h liveness grace) convert for resubmission (cancel releases the
idempotency slot), possibly-live queues are never touched, and legacy
dream:synth: keys are excluded at the SQL filter. Guardrails: upfront cost
estimate with a >$5 confirmation (--yes skips), --max-usd counts every paid
attempt including unreliable responses and spans --audit-rejects (frontier
second opinion on stride-sampled rejects), --cancel-unmatched refuses
truncated (--limit) or empty corpus scans, key-source vs payload source_id
mismatches are skipped, and statuses re-check immediately before each
cancel. dream/dream-retriage --help answer engine-free through the real CLI
(CLI_ONLY_SELF_HELP routing).
* chore: bump version and changelog (v0.46.2.0)
Docs: KEY_FILES synthesize/dream-retriage entries rewritten to current
state, cron-schedule triage-cascade section (threshold dial, retriage
recipe, mid-tier pairing guidance), six follow-up TODOs filed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(dream): close the structured-review P1/P2s — budget, liveness, preview honesty (#4152)
P1: --max-usd with --audit-rejects now refuses an unpriced synthesis model
(the audit's spend was un-estimable and silently un-metered), and an
un-estimable audit always triggers the confirmation gate. P2s: the daily
cap bounds NEW spend only — files whose idempotency keys already exist
coalesce/self-heal instead of stranding for the 24h window; a live
gbrain_cycle_locks row marks every dream-inline queue possibly-live
regardless of age (slow sequential children can outlive the 1h grace);
delayed retries in provably-dead queues convert for resubmit alongside
waiting ones; and --dry-run --cancel-unmatched counts its would-cancels
instead of understating the destructive preview.
* fix(dream): round-2 structured-review edges — audit-dollar gate, per-source lock scope, coalescible-key cap (#4152)
The spend confirmation now gates on the KNOWN estimate (a priced audit
confirms on its own dollars even when the triage model is unpriced); live
cycle locks suppress inline-queue conversions per-source (only the legacy
bare gbrain-cycle lock is global), so a busy source never indefinitely
blocks another source's cleanup; and the daily cap's existing-key credit
counts only coalescible rows (cancelled/dead keys get cleared on re-add and
would have minted fresh paid jobs past the cap).
* chore: regenerate flag registry (kill the --limit-truncated phantom from an error-string scan)
* fix(dream,models): round-3 structured-review — fail-loud stray retriage flags, dashboard shows the real triage route (#4152)
`gbrain dream --reconcile-queue` (retriage flag without the subcommand)
now exits 2 with a did-you-mean instead of silently running the full paid
maintenance cycle (the flag registry unions retriage flags into `dream`,
so the pre-dispatch validator alone can't catch it). `gbrain models` gains
the overrideKey seam so the triage row reports `models.dream.triage` as the
effective spending route (with the legacy verdict-model chain as fallback),
matching loadSynthConfig's actual resolution.
* docs: describe --max-usd honestly as an estimate-based soft stop (codex r4 P2)
* docs: update project documentation for v0.46.2.0
Sweep the remaining doc surface for #4152 triage-cascade drift:
- skills/maintain/SKILL.md: synthesize phase now describes the two-stage
cascade (scored triage gate, read-time threshold, triage map, max_turns
16) and points at `gbrain dream retriage` for re-scoring + backlog drain
- docs/architecture/system-of-record.md: dream_verdicts row is a scored
triage cache rebuildable via `dream retriage --force`, not a boolean
verdict cache
- skills/conventions/model-routing.md: utility-tier example is the dream
triage judge (prefers models.dream.triage)
- docs/operations/spend-controls.md: name `dream retriage --max-usd` as an
LLM-cost cap outside the embedding-spend posture scope
- skills/RESOLVER.md: add retriage trigger phrases to the dream-cycle row
- regenerate skills.lock.json + llms bundles
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: apply cross-model doc-review fixes for v0.46.2.0
Verified findings from the post-ship documentation review:
- docs/guides/cron-schedule.md: document the three missing triage knobs
(max_chars 24000/floor 1000, max_tokens 2048/floor 256, concurrency 4
clamped 1-16); qualify "every file scored" with the max_ms deferral;
audit-rejects uses the synthesis model, not "frontier"
- docs/architecture/KEY_FILES.md: add migration v129 to the migrate.ts
inventory; disambiguate the cap-hit dream_verdicts sentence (triage
verdict stays cached, cap site writes nothing new); add the degraded
field to details.triage
- skills/maintain/SKILL.md: --dry-run describes the scored triage (not a
Haiku boolean filter) and points at retriage --dry-run for zero-call
previews; qualify triage coverage with the max_ms budget; drop the
stale "8-phase" count (ALL_PHASES outgrew it)
- skills/conventions/model-routing.md: document the models.dream.triage
pre-read exception to the resolution chain
- docs/operations/spend-controls.md: retriage --max-usd is an
estimate-based soft stop, not a hard cap
- regenerate skills.lock.json + llms bundles
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ci): route dream exit codes through setCliExitVerdict; declare retriage triggers in maintain skill
Shard 4: raw process.exitCode writes in dream.ts/dream-retriage.ts are
zeroed by the flush-exit owned-verdict channel — route all nine sites
through setCliExitVerdict (doctor.ts pattern).
Shard 3: RESOLVER.md routes "retriage the backlog" / "re-score the
triage" to skills/maintain — declare both in the skill's frontmatter
triggers (round-trip pin) + regenerate skills.lock.json.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): cancel abandoned probe + lock-renewal queries instead of orphaning pool slots (#6)
Three hot paths raced a live query against a timer and abandoned the loser,
leaving the query holding a checked-out pool slot for its full server-side
duration. Under a saturated transaction-mode pooler those orphaned slots
starve lock renewal ('lock-renewal-failed' cascades) and the health probe.
- Health probe: pass the deadline AbortController's signal into
executeRaw('SELECT 1') so a hung probe is cancelled via postgres.js
.cancel() (runUnsafe already wires signal -> pending.cancel()).
- Minion lock renewal: LockRenewalDeps.renewLock widened with optional
{ signal }; runLockRenewalTick aborts a per-call controller when the
timeout wins the race; MinionQueue.renewLock forwards the signal to
executeRawDirect. Optional-param widening keeps the 14 existing hermetic
tests compiling untouched.
- Cycle drain renewal (synthesize.ts): the inline best-effort tick had no
per-call timeout and no re-entrancy guard, so a hung renewLock stacked a
fresh checked-out slot per interval firing. Extracted as exported
runDrainRenewalTick (per-call signal + timeout + swallow) behind a
tick-in-flight guard.
Tests: 2 new signal paths in worker-lock-renewal.test.ts, probe-signal
assertion in worker-supervised-db-probe.test.ts, new hermetic
minion-queue-renewlock-signal.test.ts + cycle-drain-renewal.test.ts.
scripts/check-worker-lock-renewal-shape.sh stays green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions,db): cancel timed-out wedge probes + db-lock refreshes (#6)
Same abandoned-racer class as the previous commit, in two more spots:
- probeQueueState raced probeQueueStateInner against its 1500ms budget but
the losing wedge/age queries kept running on the pool after the race
resolved — under pool exhaustion (the exact regime the probe exists to
detect) the orphaned query held a slot and made the exhaustion worse. The
timeout now aborts a per-probe signal threaded through queryWedgeSignals
and the oldest-waiting age query. Closes the filed TODOS entry.
- withRefreshingLock raced handle.refresh() against heartbeatTimeoutMs the
same way; DbLockHandle.refresh now accepts { signal } (Postgres forwards
to executeRawDirect; PGLite ignores it — no pool to starve), the timeout
aborts it, and a re-entrancy guard stops overlapping ticks (15s min
cadence vs 30s default timeout could stack two).
Tests: new hermetic queue-probe-cancellation.test.ts (signal threading,
timeout-aborts, fast-path-not-aborted, fail-open contract).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(db): explicit jittered max_lifetime on all four client pools (#6)
Makes the pool connection lifetime explicit at every postgres() call site
(db.ts module singleton, engine instance pool, ConnectionManager read +
direct pools) and adds GBRAIN_POOL_MAX_LIFETIME_S as an incident escape
hatch (N seconds; 0 disables recycling).
NOT a behavior change at default: postgres.js (verified against the pinned
3.4.9) already defaults max_lifetime to 60*(30+rand*30) — 30-60 min,
jittered per pool — and max_lifetime only recycles connections as they
return to the pool; it cannot reclaim a leaked checkout. Framed accordingly:
explicitness + operator knob, not a fix for the starvation class (that is
the cancellation work in the two prior commits).
Tests: hermetic resolver suite (env forms, 0-disables, jitter bounds,
warn-once on invalid values, per-call jitter variance).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): pool-state health-probe diagnostics — pool starved vs server unreachable (#6)
"[health] DB unreachable" sent operators chasing database capacity while the
real fault was client-side: the server sat at ~10% of max_connections. The
probe now names the failing layer:
- New src/core/minions/db-probe.ts (hermetic, injected-deps — the
lock-renewal-tick pattern): on read-pool probe failure, a 3s direct-lane
SELECT 1 disambiguates. Direct OK -> verdict 'pool_starved' ("server IS
reachable; the fault is in the transaction-pooler path — client pool
exhaustion or a pooler-layer fault", deliberately an honest disjunction).
Both fail -> 'server_unreachable'. No direct lane -> 'unknown'. Both
probes carry AbortSignals — a hung probe is cancelled, never abandoned.
- New src/core/pool-gauge.ts: approximate in-flight counters at the engine's
raw/direct/reserved/transaction seams, surfaced via a duck-typed
PostgresEngine.getPoolDiagnostics() (no BrainEngine churn, no PGLite
stub). Explicitly labeled a tracked SUBSET — template-path traffic is
untracked and no waiter/available figures are derived (that would be
invented telemetry). Counters use try/finally (runUnsafe throws
synchronously on a pre-aborted signal) and clamp at zero.
- worker.ts probe adapter emits the verdict in every failure line and on the
final unhealthy payload; exit semantics UNCHANGED (exiting on a starved
pool is correct recovery — it frees all client-held slots).
- jobs.ts: verdict-aware fatal text, plus a startup warning when a
Supabase-shaped engine is running single-pool (kill-switch collapse used
to be silent — renewal + probes + workload all sharing one pool is the
precondition for this incident class).
- Runbook: verdict interpretation table in queue-operations-runbook.md.
Tests: pool-gauge.test.ts (pure + engine seams incl. rejected-query and
sync-throw leak guards), db-probe.test.ts (full verdict matrix, signal
cancellation, fail-open diagnostics, no-waiter-wording pin).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(db): route withReservedConnection to the direct session pool when dual-pool is active (#6)
Long-hold reserved work — CREATE INDEX CONCURRENTLY (vector-index), non-
transactional migration DDL, and backfill BEGIN..COMMIT batches (the observed
353s COMMIT session) — previously reserved from the worker's shared READ
pool, pinning slots under the 5-min pooler statement_timeout. It now reserves
from the DIRECT session lane, whose 30-min statement_timeout and
maintenance_work_mem GUCs are the right fit, and stops competing with handler
workload.
Heartbeat protection: concurrent direct reserves are capped at
directPoolSize - 1 (default 2 of 3) via a per-process semaphore so
claim/renewLock always keep >= 1 direct slot; overflow falls back to the
read pool — exactly the pre-change behavior, so this commit is strictly
never-worse than master. (Deliberate rejection of queue-for-a-permit: that
would block migrations behind multi-minute index builds. Per-process is the
correct scope: each process owns its own direct pool, so a CLI migration
cannot starve a worker's heartbeats.) Never rerouted inside an open
transaction (same guard shape as executeRawDirect); kill-switch collapse
degrades to status quo. Callers unchanged.
Tests: postgres-engine-reserved-routing.test.ts — direct when active, read
when kill-switched/in-tx, semaphore cap + overflow + permit release on fn
throw and on reserve() failure.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): job-isolation protocol, child exit codes, shared job-context builder (#5)
Foundation for per-job process isolation (no behavior change yet):
- job-isolation.ts — the parent<->child protocol: atomic outcome-file codec
(tmp+rename; 32MiB decode cap that throws UnrecoverableError so oversize
results die LOUDLY on attempt 1 instead of retrying identically or being
silently truncated; decode errors report byte counts, never file content),
handler-error encode/reconstruct preserving the two instanceof branches
executeJob dispatches on (UnrecoverableError, RateLeaseUnavailableError),
child argv/env contract, child-CLI resolution (env override -> compiled
binary -> bun-dev fallback -> null for fail-fast), and killProcessGroup —
children run detached in their own process group because SIGKILL on a tini
pid alone kills tini and orphans the handler grandchild (tini cannot
forward SIGKILL), and Bun rejects negative pids in process.kill()
(oven-sh/bun#15791) so group signaling falls back to POSIX /bin/kill.
- worker-exit-codes.ts — reserved run-child codes 13 (usage/PGLite),
14 (not claimed / token mismatch), 15 (result-write failed). Result-file
presence, not the exit code, classifies the normal path: a reported
handler FAILURE is still exit 0.
- job-context.ts — MinionJobContext builder extracted verbatim from
executeJob so the child wires the exact same token-fenced DB callbacks;
worker.ts now calls it (behavioral no-op, full minions suite green).
Tests: job-isolation-protocol.test.ts — codec round-trip + all decode
failure paths, instanceof reconstruction, invocation resolution, and REAL
detached-process group-kill tests incl. the grandchild-death guarantee
(runs under bun test, so the Bun negative-pid fallback is exercised for
real, not mocked).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): hidden 'jobs run-child' single-job entrypoint (#5)
The child side of process isolation. `gbrain jobs run-child --job-id N`
(internal; spawned by the worker, absent from user help):
- re-reads the job row and validates status='active' + lock-token match
before running anything — a reclaimed/cancelled job exits 14 with the
handler never invoked (the DB stays ground truth; no payload
serialization across the boundary);
- registers the same handler surface as the worker via
registerBuiltinHandlers({quiet}) — which includes plugin discovery, so
plugin subagent jobs isolate identically — resolved through the new
MinionWorker.getHandler() accessor;
- builds the shared token-fenced MinionJobContext against the CHILD's own
engine, runs the handler, and writes ONE atomic outcome file: handler
failure is an encoded error outcome with exit 0 (a reported failure is a
successful report); only write-failure exits 15;
- runs NO worker machinery (no probe/stall/lock timers — the parent owns
liveness). Installs a SIGTERM handler (fires ctx.signal + shutdownSignal
so handlers get the drain window to finish and report) and a
parent-liveness watchdog polling process.kill(parentPid, 0) — a ppid
check is dead code under tini — that aborts the handler and hard-exits
after a grace so orphaned LLM-bound work stops burning spend;
- CLI layer owns engine.disconnect() + process.exit() (engine-ownership
invariant); PGLite exits 13 (isolation is Postgres-only, like jobs work).
Flag registry regenerated for the internal job-id flag.
Tests: run-child-entry.test.ts against real in-memory PGLite with a REAL
claim-minted token — success (incl. a fenced updateProgress landing),
handler-failure outcome, token-mismatch never-runs, missing job, missing
handler, and the parent-death watchdog aborting a live handler.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): process isolation — run claimed jobs in SIGKILL-able children (#5)
The parent-side seam. executeJob swaps ONE line — handler(context) vs
runJobInChild(...) — and every existing reporting branch (completeJob,
failJob dead/delayed, lease release, infra-abort no-burn) is reused verbatim
on the child's reconstructed outcome. Blast radius of a stuck or crashing
handler drops from N in-flight jobs to exactly one.
child-job-runner.ts:
- detached spawn (own process group) + tini wrap when available; stdio
['ignore','inherit','inherit'] so handler logs stream to the operator;
per-job lifecycle log lines (spawned / exited code+signal);
- per-job abort -> group SIGTERM now, group SIGKILL at +25s (inside the 30s
force-evict window, which stays as an untouched backstop) — force-eviction
is now a real kill, not an abandonment;
- worker shutdown -> same SIGTERM so the child's handlers get the drain
window to finish AND report; a child that reported before the kill
completes normally; one that couldn't throws ChildWorkerShutdownError,
which the worker RELEASES with no attempt burned — routine deploys must
not burn attempts (codex-2 #7);
- pre-exec spawn failure -> ChildSpawnInfraError, also released with no
attempt burned (one bad CLI path must not dead-letter a queue);
- child env contract: fenced lock token, outcome path, parent pid for the
orphan watchdog, GBRAIN_POOL_SIZE=3 + GBRAIN_DIRECT_POOL_SIZE=1 bounds
(children run no heartbeats; sockets die with the process — the point).
worker.ts: MinionWorkerOpts gains jobIsolation / childCliInvocation /
childTiniPath (defaults preserve inline behavior exactly); when isolated the
parent-side MinionJobContext is not built at all (the child builds its own).
Tests: child-job-runner.test.ts (real .mjs children: success + env contract,
error/lease outcome reconstruction, crash, SIGTERM-ignorer -> group SIGKILL,
pre-aborted, spawn ENOENT, both shutdown semantics);
worker-job-isolation.test.ts (real PGLite worker end-to-end: claim -> child
-> fenced completeJob with the REAL claim token, failJob on error outcome,
crash burns attempt, spawn failure releases with zero attempts burned).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(cli): --job-isolation flag, supervisor pass-through, e2e lane (#5)
The user-facing surface for per-job process isolation:
- jobs work --job-isolation <inline|process> (space or = form; env fallback
GBRAIN_JOB_ISOLATION; default inline — fully opt-in). With 'process' the
worker resolves the child CLI ONCE at startup (GBRAIN_JOB_CHILD_CLI ->
compiled binary -> bun-dev fallback) and REFUSES to start on an
unresolvable/nonexistent path — a bad path discovered per-job would stall
the queue one released claim at a time. detectTini() wraps children when
available. Startup banner names the mode + child CLI; combining with
--max-rss prints a note that the watchdog now covers the worker only.
- jobs supervisor --job-isolation passes through via buildWorkerArgs as a
CONDITIONAL push — inline/omitted keeps existing deployments' worker argv
byte-identical (pinned arrays in supervisor-build-worker-args.test.ts are
untouched; two new cases added).
- pool_starved fatal text now names the flag as a remedy (handler
connections die with each job's child).
- help text for work + supervisor + the jobs index; flag registry
regenerated.
- NEW test/e2e/job-isolation.test.ts, wired into e2e.yml tier1 EXPLICITLY —
the workflow runs only named files (no glob), so an unwired e2e file would
be silent coverage loss. Legs: concurrency-3 isolated drain through real
children against real Postgres (the child-pool topology), and the REAL
`jobs run-child` CLI entrypoint end-to-end (engine bootstrap, quiet
handler registry, token validation, outcome protocol). Follows the #4128
ambient-URL-guard conventions (explicit env in the e2e lane).
- serialization parity (codex-2 #8): a non-JSONB-serializable result fails
loudly in BOTH modes (inline completeJob serialization vs child exit 15) —
isolation never falsely completes a job inline mode would have failed.
Tests: jobs-isolation-flag.test.ts (parser matrix), extended
supervisor-build-worker-args + worker-job-isolation, cli-flag-validation
green via regen, jobs-subcommand-help.serial green (engine-free help path).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(minions,db): pool-starvation diagnostics + job isolation reference; file the follow-ups (#5, #6)
- KEY_FILES.md: entries for the six new modules (job-isolation,
child-job-runner, run-child, job-context, db-probe, pool-gauge) and
current-state updates for worker/queue/supervisor/jobs/db/db-lock/
lock-renewal-tick/synthesize.
- minions-deployment.md: a --job-isolation section modeled on --nice — how
the parent/child split works, preserved error semantics, orphan story, and
the sizing notes (pooler CLIENT connection math: concurrency 15 ~ 73;
--max-rss covers the worker only; spawn cost guidance; the lock token is a
fencing token, not a secret).
- TESTING.md: inventory entries for the 12 new unit files + the e2e lane
(which is wired EXPLICITLY into e2e.yml tier1 — no glob exists).
- TODOS.md: filed the 10 follow-ups, headlined by the P1-companion
nested-checkout audit (the strongest remaining #6 root-cause candidate —
this wave mitigates the starvation class and fixes the diagnostic; it does
not claim to close every leak path), plus per-handler isolation policy,
per-child RSS caps, the connection-budget clamp, autopilot pass-through,
connection-audit release events, the doctor connection_routing check, and
Sql-proxy checkout instrumentation.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: repoint the deadlineAtMs structural pin at the extracted job-context builder
The deadline-plumbing structural test grepped worker.ts for the literal
deadlineAtMs derivation, which moved verbatim into job-context.ts (the
builder shared by inline mode and 'jobs run-child'). The pin now checks the
derivation in job-context.ts AND that worker.ts calls buildJobContext — the
same contract, at its new home.
Full-suite triage note: an isolated A/B of the 22 files that failed in the
parallel full-suite run shows IDENTICAL results on this branch and on the
master base (290 pass / 5 fail — doctor-minions-check + unified-multimodal,
both env-dependent) — zero regression delta from this wave.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions,db): adversarial-review hardening — shutdown/attempt semantics, TOCTOU semaphore, gauge + parity gaps (#5, #6)
A 23-agent adversarial review (5 dimension finders + per-finding refuters)
over the wave's diff confirmed 12 defects; all fixed here:
- [P2] run-child conflated worker SIGTERM with the per-job abort: cooperative
handlers bailed mid-deploy, reported an error outcome, and the parent
BURNED an attempt per routine deploy — while signal-ignoring handlers got
the no-burn release (the exact inversion of the shutdown guarantee).
SIGTERM now fires ONLY shutdownSignal (inline signal-separation parity —
handlers finish + report inside the drain window), parent death still
aborts both, and the parent classifies an ERROR outcome that arrives
during shutdown as ChildWorkerShutdownError (released, not burned; a
genuinely-failing job coinciding with a deploy gets one free retry).
- [P2] the reserved-direct semaphore was a check-then-increment spanning
`await ddl()` — same-tick concurrent reserves could overshoot the cap and
starve the heartbeat slot it exists to protect. The permit is now taken in
the same synchronous frame as the check.
- [P3] RSS-watchdog drain (gracefulShutdown aborts BOTH signals, reason
'watchdog') was classified as a per-job abort and burned attempts on
innocent isolated jobs. Shutdown classification now wins unless the
per-job reason is job-targeted (timeout/cancel/lock-*).
- [P3] force-evict's failJob('dead') could race executeJob's own recording
in isolation mode (group SIGKILL at 25s + slow decode > 30s window) and
dead-letter a job with attempts remaining — skipped when isolated (the
inFlight eviction, which is what unblocks the worker, stays).
- [P3] child bootstrap exits were burned as handler crashes: exit 13 →
ChildSpawnInfraError (release), exit 14 → new ChildNotClaimedError
(release; the claim is provably owned elsewhere).
- [P3] missing handler in the child was 'generic' (retried to max_attempts)
vs inline's immediate dead-letter — now 'unrecoverable' (parity).
- [P3] result-shape parity: the {value: x} wrap now happens CHILD-side,
before JSON serialization, so Date/toJSON results can't flip the wrap
decision across the boundary.
- [P3] child env no longer raises a stricter user GBRAIN_POOL_SIZE (pooler
MaxClients tuning respected; explicit GBRAIN_JOB_CHILD_POOL_SIZE wins;
invalid values fall back instead of flowing to the 10-conn fallback).
- [P3] transaction() gauge used a chained .finally that a synchronous
begin() throw (nested tx on a clone) would skip — now try/finally.
- [P3 vacuity x3] new pins: db-lock heartbeat cancellation wiring +
re-entrancy, the synthesize drain-loop guard + tick call (the shape guard
only covers worker.ts), and GBRAIN_POOL_MAX_LIFETIME_S reaching a REAL
constructed pool (postgres() is lazy — no I/O).
New tests: error-outcome-during-shutdown, watchdog double-abort,
timeout-beats-shutdown precedence, bootstrap exit codes, pool-size env
matrix, SIGTERM-only-aborts-shutdown (in-process emit), child-side wrap.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions,db): pre-landing review fixes — specialist + red-team findings (#5, #6)
Ship's review army (5 specialists + red team over the full diff; 0 critical
from specialists, 3 confirmed critical from red team) — all findings fixed:
Red team (critical):
- reserved-direct cap: removed the Math.max(1, size-1) floor — at
direct_pool_size=1 it let a multi-minute reserve consume the ONLY direct
session and starve claim/renewLock heartbeats (the #6 class reintroduced).
cap = size - 1, direct routing only when cap >= 1; size<=1 uses the read
pool (true status quo). Pinned by a size=1 routing test.
- silent group-kill failure: the SIGKILL escalation now logs loudly when
delivery fails (distroless hosts without /bin/kill would otherwise void
the kill guarantee with zero diagnostics while the job duplicated
elsewhere), and skips the redundant signal when the child already exited.
- spawn-failure circuit breaker: a deterministically broken child CLI looped
claim/release forever, invisible to the stall detector (every settle
refreshes the progress clock). After 3 consecutive spawn/bootstrap
failures the worker emits unhealthy(child_spawn_failing) for a
process-manager restart; counter resets on any spawn that runs. Plus the
predicate-mismatch guard: jobIsolation 'process' without childCliInvocation
now throws at construction (it silently ran handlers inline while the
evict path believed it was isolated).
Specialists (informational, all applied):
- performance: parent-side outcome decode is async (a 32MiB-capped file must
not block the event loop running renewal ticks); /bin/kill by absolute
path (also the security finding).
- security: lease payloads are shape-validated before reconstruction
(corrupt outcome files degrade to generic); the child-CLI override is
canonicalized to an absolute path so the fail-fast check validates the
binary that actually spawns.
- data-migration: max_lifetime default is now a per-CONNECTION jitter
FUNCTION (matching the postgres.js built-in shape — a pre-evaluated number
synchronized every connection in a pool onto one recycle deadline);
reserved.release() throws no longer leak the gauge or the direct permit.
- testing: child harnesses use a readiness handshake instead of fixed 400ms
sleeps (CI-load flake); the orphan-watchdog test uses a real reaped pid
(a magic high pid is allocatable under Linux pid_max); new pins for the
dual-pool probe gating (probeDirect wired ONLY when isDualPoolActive),
the executeRawDirect/transaction gauge seams incl. the sync begin()-throw
leak guard, the ddl()-throw read-pool fallback, and the --job-isolation
help text.
- maintainability: abort-reason literals shared via types.ts (dead
'cancel'/'cancelled' entries dropped), DEFAULT_DIRECT_POOL_SIZE and
CHILD_READ_POOL_MAX named, redundant dynamic imports removed, unrefTimer
helper, getConnectionRouting shared accessor, docstring + fixture-header
corrections.
Deferred with TODOS entries: raceWithAbortTimeout DRY helper (5 sites), lazy
handler resolution in run-child, e2e-lane negative tests for the run-child
bootstrap guards + operator-flow messages, behavioral withRefreshingLock test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.1.0)
Issues #5 + #6 wave: pool-starvation cancellation + diagnostics, and opt-in
per-job process isolation. Version locations: VERSION, package.json,
CHANGELOG.md, openclaw.plugin.json, BOOTSTRAP_FOR_AGENTS.md stamp, and the
regenerated bootstrap template tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: passwordless fixture URLs in the pool-wiring tests
The pre-push credential guard (correctly) blocks any URL-with-password shape
in a pushed diff, including fake placeholders. The never-connected fixture
URLs don't need a password at construction time — drop it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: README Minions capability + KEY_FILES reserved-routing entry for v0.46.1.0
document-release sweep: the wave's docs covered the guides, TESTING, and the
new module entries but missed two spots — the README Job queue capability
paragraph (now names --job-isolation process and the probe verdicts, linking
both guides) and the KEY_FILES postgres-engine.ts entry (now carries the
withReservedConnection direct-lane routing invariants + getPoolDiagnostics
seam, pinned by test/postgres-engine-reserved-routing.test.ts). llms-full.txt
regenerated for the README edit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: cross-model doc-review precision fixes for v0.46.1.0
Codex review of the shipped docs vs the diff, each finding verified against
the code before applying:
- minions-deployment: group-SIGKILL platform caveat (Bun /bin/kill fallback),
lock-token fencing scoped to queue writes (handler side effects bounded by
the watchdog, not the token), connection math relabeled (pooler-lane vs
direct session-lane split), no-per-child-RSS-cap note, GBRAIN_JOB_CHILD_CLI
+ the 3-consecutive-spawn-failure breaker documented.
- queue-operations-runbook: verdict rides the TERMINAL probe line (not every
N/3 line), server_unreachable hedged (both-lanes-failed is the evidence),
pooler-layer fault added to the 0-in-flight reading, jobs cancel described
as cooperative inline vs real kill under isolation.
- KEY_FILES: run-child SIGTERM fires shutdownSignal ONLY (both only on
parent death); third no-burn child class (ChildNotClaimedError).
- TESTING: e2e concurrency leg uses the fixture (no child DB pools); only
the run-child leg boots real child pools.
- CHANGELOG: one wording precision fix (reserved holds leave a heartbeat
slot, not "always keep a free slot").
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): adapter seam — session contract, detection registry, claude lane with timestamps
Cathedral-4 commit 1: the TranscriptAdapter seam at src/core/transcripts/.
types.ts carries the session-granular AsyncGenerator contract (return value =
per-file diagnostics so a zero-yield file explains itself), format-specific
byte caps, and the ONE buildTranscriptSlug helper (per-provider dirs, id8
collision suffix). detect.ts owns the adapter registry, head-sample sniffing
(explicit format wins, symlinks lstat-rejected), and the injectable
HARNESS_ROOTS discovery surface. claude-code.ts wraps the SHIPPED parser;
claude-code-jsonl.ts gains the ADDITIVE parseClaudeSessionFile (full-file,
reject-over-cap, real per-message timestamps) — hook-lane parseTranscript
output is pinned byte-identical by the new regression test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): codex, openclaw, and hermes adapters — verified shapes, drift alarms, copy-then-read
Cathedral-4 commit 2. codex.ts: turn selection is STRUCTURAL — user turns
from event_msg user_message, assistant turns from response_item output_text;
response_item user/developer rows are injected preambles and never leak
(fixture-pinned). openclaw.ts: session header + message lines, real
timestamps, model_change/custom/compaction skipped, .checkpoint.*.jsonl
siblings rejected at detect. hermes.ts: copy-then-read (DB + wal/shm
sidecars to a temp dir) because readonly WAL opens need -shm write access
and lock against a live writer; schema verified against the installed
hermes-agent v0.20.0 SCHEMA_SQL, SPEC_TARGET provisional, multi-session
cardinality with tool-only sessions skipped. Detection matrix pins all four
formats. Codex + OpenClaw shapes verified against live local files
2026-08-14.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): chatgpt + claude.ai export adapters — mapping-tree walk, extracted-JSON v1
Cathedral-4 commit 3 (CP1). chatgpt-export.ts walks the mapping TREE via
current_node parent pointers (regenerated branches dropped by design;
orphaned parents terminate quietly; latest-leaf fallback when current_node
is absent) — the branched/orphaned/fallback cases are fixture-pinned.
claude-export.ts is the flat sibling (human maps to user, empty rows
skipped). Both take the EXTRACTED conversations.json only (unzip-first
errors; zip wrapper is a filed TODO), reject-not-truncate over the export
cap, and carry provisional SPEC_TARGETs pending a fresh real export sample.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): render pipeline — shared anchor pattern, anchor-escape, fail-closed redaction, part splitting
Cathedral-4 commit 4. render.ts renders sessions in the conversation-parser
imessage-slack builtin (regex IMPORTED, never re-declared — round-trip
pinned through parseConversation), with real UTC timestamps (missing ones
carry forward, zero-timestamp sessions REFUSED — provenance is never
fabricated). Anchor-shaped BODY lines are backslash-escaped so hostile
message content cannot forge speakers or timestamps on re-parse (P0).
Redaction is fail-closed for the page lane: secret-scan + user pattern file
(harvest-private-patterns convention; the slack-channel default is excluded
because it eats issue refs) + agent-imperative COUNTING stamped into
hash-covered transcript_import frontmatter (never content_flag). Long
sessions split at message boundaries (~300KB parts, 2-message overlap)
under the embed_skip threshold; part 1 keeps the base slug, ids are unique
per part.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(facts): batch slugs selector + the transcripts-ingest facts lane
Cathedral-4 commit 5. runExtractConversationFactsCore gains a slugs[] batch
selector (serial, same per-page advisory lock + durable-outcome gates as
enumeration) so a caller with a known page set invokes the core ONCE —
per-slug invocations multiply config resolution, checkpoint IO, and receipt
writes by page count. ingest-facts.ts wraps that single invocation in ONE
withBudgetTracker (opts.budgetTracker alone is not accounting — the gateway
reads AsyncLocalStorage) and pre-checks facts.extraction_enabled with a
notice instead of the core's throw.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): gbrain transcripts ingest — session-atomic import CLI, embed-OFF default, clean-scan watermark
Cathedral-4 commit 6. ingest.ts is the engine-facing core: detect → parse
(per-session) → since/limit filters → fail-closed redaction → render/split →
importFromContent per part (noEmbed unless the embed flag opts in) →
putRawData → stale-part reconciliation (deletes part>of leftovers).
Atomicity is the SESSION: failed sessions count and skip, integrity
failures (duplicate-lookup, read-back, raw-data miss) abort the whole run.
The command layer resolves ONE source id through the 6-tier chain, threads
activePack once, streams progress (phase transcripts.ingest, stderr), and
advances the since-last op-checkpoint watermark ONLY after a clean,
untruncated, non-dry scan (fingerprint binds source + pathspec + format +
adapter version). transcripts joins CLI_ONLY_SELF_HELP and
SELF_HELP_WITHOUT_ENGINE (engine-free help); flag registry regenerated.
Facts flag targets every touched slug including hash-skipped pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(transcripts): discovery mode, --all, and the status gap table
Cathedral-4 commit 7 (CP0 + CP2). No-arg ingest runs confined discovery
over the harness roots and shows what WOULD be imported (safe default);
the all flag imports the discovered set. The status subcommand derives its
imported side from ONE paginated pages walk (client-side transcript_import
filtering, distinct session ids) — durable truth that catches late-arriving
sessions no watermark can — and matches JSONL files by
session-id-in-basename; the hermes store reports at session granularity.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(transcripts): e2e PGLite suite + putRawData zero-row parity fix
Cathedral-4 commit 8. The e2e suite (R3/R4: engine in beforeAll, disconnect
in afterAll) pins: cross-harness round-trip (codex + openclaw into one
source, frontmatter + raw-data assertions), dry-run zero-writes, idempotent
re-runs with hash-skipped slugs still visible to the facts lane,
redaction-before-write, part splitting under the embed-skip threshold with
unique per-part ids, the dangerous split-then-shrink transition (stale
higher parts deleted), since/limit clean-scan semantics (limit truncation
freezes the watermark; the follow-up run converges), per-file error
taxonomy, and the drift signal.
PGLite putRawData now RETURNING-checks and throws on a missing page,
matching the Postgres engine — the run-level integrity abort was previously
false on the e2e backend (eng outside-voice finding 17).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(eval): write-back fidelity through the adapter path (in-repo pin)
Cathedral-4 commit 9. The BrainBench write-back suite renders normalized
turns directly and never exercises raw parsing/detection/redaction/import —
this deterministic e2e closes the bypass in-repo: raw codex + openclaw
fixture FILES enter via runTranscriptsIngest, the shipped extractor core
runs with the injected gold extractor (decision-15 seam, zero LLM), and the
planted facts are probed with provenance pointing at imported conversation
pages. Cross-harness continuity pinned: one source holds facts grounded in
both harnesses' sessions. Re-extraction dedup pinned via the
durable-outcome gate. The full BrainBench raw-fixture sidecar schema (+
corpus-hash coverage + baseline re-cut) lives in the sibling gbrain-evals
repo and is filed as a follow-up TODO.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(transcripts): conversation-archive native-importer update, KEY_FILES seam entry, progress phase, 8 follow-up TODOs
Cathedral-4 commit 10. conversation-archive now points at the native
importer for the six covered formats and states the native-vs-manual PII
delta (secrets + user patterns native; broad PII detection stays the human
pass — filed as a TODO). check-fixture-privacy scans the new
test/fixtures/transcripts dir with the same banned-token contract.
KEY_FILES gains the src/core/transcripts/ seam entry and the updated
transcripts-command entry; progress-events documents the transcripts.ingest
phase. TODOS: 8 follow-ups (OpenClaw/Codex go-forward capture, scheduled
re-import consent design, PII pass, more adapters, zip unwrapping,
BrainBench raw-fixture schema in the sibling repo, hermes verification) +
the TODOS flip-contract-adapters entry notes the codex parser unblock.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transcripts): review-army + red-team + cross-model fixes — identity hashing, watermark safety, redacted raw, healing re-runs
Cathedral-4 commit 11: 30+ findings from 5 specialists, a red team, and two
Codex passes (adversarial pass REPRODUCED the identity P0 against PGLite),
all folded.
Identity (P0): slug + dedup ids are now sha256 hashes (12-hex slug, 16-hex
harness-namespaced frontmatter id) — prefix identity let same-prefix session
ids silently overwrite a same-day page or dedup-skip a different-day one,
and every export fallback id collided.
Watermark safety: drift files, malformed lines, and page-import error
statuses all freeze the clean-scan watermark; unparseable timestamps are
skipped (never admitted to the compare); explicit --since values are
validated + Z-normalized and never advance the watermark (only full-coverage
runs attest); the --all fingerprint binds the resolved user-stated spec, not
the expanded file list; --limit counts NEW WORK only (hash-skipped re-scans
are free, so batched backfill converges instead of looping the imported
prefix).
Redaction: putRawData persists the REDACTED metadata copy (was the original
— the redacted copy was built and discarded); raw flatness is enforced
(nested values dropped); speaker labels are cleaned + anchor-stripped;
patterns compile once per run.
Healing re-runs: all-skipped sessions verify-and-heal raw_data instead of
assuming it; stale-part reconciliation is SQL-enumerated (walks past crash
holes) and runs on every pass. hermes.ts is text again (escaped NUL); the
sidecar-inclusive byte cap bounds the copy; codex detect is structural
(JSON.parse, not substring); claude-export detect gets the symmetric
mapping guard; directory expansion filters to importable extensions;
per-session heartbeats cover multi-session stores; status reads ONE
frontmatter-only query; empty slugs selector is a no-op, never full-corpus
enumeration; export-loader deduplicated (export-json.ts).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.46.0.0)
Cathedral 4 takes the MINOR per lineage (0.43/0.44/0.45 were cathedrals 1-3).
All six version locations move together: VERSION, package.json, CHANGELOG,
openclaw.plugin.json, the bootstrap runbook stamp, and the regenerated
template tree + llms bundles + lockfile.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transcripts): verification-pass residuals — raw refresh on skipped re-runs, resolved-slug follow, scoped all-lane watermark, content-derived fallback ids
Cathedral-4 commit 13: the Codex verification pass confirmed the review-wave
fixes hold and found four residuals in the new code, all folded. Skipped
re-runs now COMPARE the stored raw-data row instead of assuming existence
means freshness (a private pattern added after first import refreshes the
stored copy; healthy re-runs stay write-free). Raw-data writes and stale-part
reconciliation follow the slug importFromContent actually RESOLVED (identity
dedup can land part 1 on an existing page under a different slug — the old
code aborted every re-run on the nonexistent rendered slug). The all-lane
watermark fingerprint carries host + harness roots (DB-backed checkpoints are
shared across machines on one brain; a bare literal let machine B inherit
machine A's watermark). Export fallback session ids are content-derived,
never a bare per-file ordinal (two files' first id-less conversations
collided).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(transcripts): build the planted secret token at runtime
The redaction tests plant an AWS-shaped token to assert it never reaches a
page; as a committed literal it (correctly) trips the pre-push credential
guard, which scans the diff with the same pattern the runtime scanner uses.
Constructing it at test runtime keeps the regression coverage and keeps the
committed bytes credential-free.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.46.0.0
document-release pass over the cathedral-4 transcripts-import ship, verified
against the final diff (three code commits landed after the branch's docs
commit) plus a cross-model doc review:
- README: transcripts importer added to "How to get data in" (discovery /
all / status examples), with the redaction claim scoped to what the code
scrubs (bodies, titles, speakers, session metadata)
- KEY_FILES: current-state corrections — sha256 hash12/hash16 ids (stale
id8 claim), host-scoped all-lane watermark fingerprint, shared
export-json.ts loader + content-derived fallback ids, healed redacted
raw metadata on skipped re-runs, status = one executeRaw frontmatter
query, JSONL cap clarified (50MB import; 10MB is the hook tail reader)
- CHANGELOG (wording only): tool/thinking claim made precise (one-line
placeholders do land), facts backfill gated on the cycle phase being
enabled, format flag added to the flag list
- progress-events: per-session heartbeats documented alongside per-file
ticks
- conversation-archive skill: ~4K per-message body cap + placeholder
delta disclosed; IMPORT half covers both native and manual paths
- TODOS: "Native AI-chat export importer" marked Completed v0.46.0.0;
Perplexity cross-reference fixed
- cli.ts: top-level help now advertises the transcripts family, not just
recent (no dashed flags; registry regen = no diff)
- llms-full.txt + skills.lock.json regenerated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(transcripts): full-pipeline e2e for all six formats
Closes the coverage gap the ship left: codex and openclaw were the only
formats traveling parse -> redact -> render -> import -> page in e2e; the
other four stopped at adapter-level unit tests. Now every format lands as
real pages against PGLite: claude-code (placeholders + real anchor
timestamps from the shipped fixture), hermes (ONE store file -> MANY pages —
the multi-session ingest path, per-session raw_data, plus limit-truncation
convergence on a multi-session file), chatgpt export (per-thread pages under
the chatgpt directory with title slugs; abandoned branches never land), and
claude.ai export (title-slugged pages under the claude directory). Titles
are asserted on the page column, where import promotes them.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs(mcp): pin observed grok CLI behavior (GROK-CLI-PIN.md)
Phase-0 observation transcript against a real Grok Build v1.0.4 install
(pinned npm @xai-official/grok). Keyless scope complete: GROK_HOME seam,
lazy exit-0 mcp add, honest mcp doctor discriminator (7 verbs discovered),
saved TOML schema verbatim, trust-gated vendor fallback, volatile-path
inventory for the tripwire, keyless auth error. Paid probes marked
pending auth per plan D0. Machine-stable stamp block feeds
scripts/check-grok-pin.sh.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(claw-test): extract detectBinary/filterAllowlistEnv into agent-runner
Byte-identical detect()/env-filter bodies moved out of runners/hermes.ts and
runners/openclaw.ts (rule-of-three: the grok runner lands next). Behavior-
preserving: same reason strings, same ordering; existing runner tests green.
Adds direct unit pins for override precedence (PATH-shim depends on it), the
leak barrier, and the non-executable stat branch. openclaw.ts's prompt-file
comment respelled dash-free (flag-registry prose-bleed class).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(claw-test): grok runner — detection, pinned one-shot invoke, env allowlist
GrokRunner (xAI Grok Build CLI) as the third registered agent. Pinned argv
from docs/mcp/GROK-CLI-PIN.md observations: single-shot flag + plain output
format; permission flags deliberately absent pending the authed observation.
Env delta: GROK_HOME + XAI_API_KEY. Version preamble recorded as a stdout
transcript event (mis-bound community binary diagnosable from transcript);
loud warning when the operator's ~/.claude.json registers gbrain (the
trust-gated vendor-config contamination channel). Tests: detection contract
incl. the first through-runner shell-metacharacter pin, shim argv/env leak
barrier, three-way alphabetical list-agents pin. Flag registry regenerated
(argv-literal bleed is accepted over-inclusion; no SAFETY_FLAGS collision).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): grok door — split-gated real-binary e2e + harness helper family
install-real-grok.serial.test.ts: keyless tier (version-shape pin, documented
registration via a PATH-staged bin dir, saved-TOML asserts through
Bun.TOML.parse, mcp doctor handshake proving the seven-verb surface keyless,
vendor-fallback provenance guard, direct-TOML surface + config-preservation
pin) gated on opt-in + binary only; paid SMOKE additionally on XAI_API_KEY,
asserting a per-run nonce fact with web search disabled. mcp add is lazy
(exit-0-always, observed) — doctor is the honest discriminator. Bounded
tripwire over the operator's real ~/.grok config/credential files (volatile
paths excluded) + a checkout guard. Helpers: resolveGrokBinary (GROK_BIN
override honored), hasGrokAuth, grokChildEnv (explicit key re-admission +
GITHUB_ENV/PATH/OUTPUT/STATE scrub), seedGrokConfig (auto_update kill-switch),
stageGbrainBinDir (compiled copy, bun-run wrapper fallback), grokOneShotTurn;
seedBrainForAgent gains a nonce-fact override (hermes path unchanged).
run-e2e.sh scrubs GROK_* so the door structurally cannot fire under test:e2e.
Verified live: keyless tier 4 pass / 0 fail in 28.9s against Grok Build v1.0.4.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(heavy): grok-door job (keyless-first, npm-pinned) + check-grok-pin guard
grok-door provisions the pinned npm package (registry integrity pre-checked
against the GROK-CLI-PIN.md stamp — a re-published version becomes a loud
re-pin decision) in a secretless step, runs the KEYLESS door tier before the
secret precondition (missing XAI_API_KEY fails loudly but only after the free
compat coverage is banked), then a named bad-key preflight, the full paid run
with a paid-sentinel (a skipping paid tier can never read green while the key
is present), and a mid-job version-drift tripwire. Pre-secret gating posture:
real-agent-e2e label or the run_grok_door dispatch input ONLY — no schedule,
no generic heavy-tests label — so an absent secret cannot paint nightly runs
red; the secret-enable follow-up re-adds schedule + heavy-tests + a
latest-version canary leg. real-agent-e2e job gains the grok door file +
opt-in var. Backports to hermes-door in the same commit: unconditional
door.txt evidence copy (the zero-pass failure class now leaves a trace) and
persist-credentials: false on checkouts. New scripts/check-grok-pin.sh
(distribution_kind-aware, grok-door-block-anchored, SKIP-graceful) wired into
verify + check:all, with guard tests covering ok/skip/drift/exclusivity/dupes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(mcp): Grok Build install guide + surface wiring
docs/mcp/GROK.md (HERMES.md skeleton): surface-verbs register form matching
current CLAUDE_CODE.md guidance, direct-TOML block with the startup-timeout
gotcha, the trust-gated vendor-config fallback with honest precedence and the
doctor source field, doctor-as-the-real-probe verify (7 tools discovered),
headless auth + model pin + auto-update seed, cron pairing, troubleshooting
incl. wrong-grok-on-PATH (community CLI collision), grok/groq/ngrok
disambiguation, and the skills-placement note. Honest classification
everywhere: brain-only install; bootstrap does not support Grok yet.
Version-bounded phrasing on all three user surfaces (README bullet,
INSTALL_FOR_AGENTS block, GROK.md footer). MEMORY_VERBS registration
one-liner added. llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(dx): structural transcript redaction + PTY hot-loop bounds + settle audit trail
Behavior wave preceding the runInstallSession extraction (kept separate so
the extraction stays pure motion): saveTranscript gains an explicit redact
seam applied to EVERY artifact as one pass over the serialized string (a
secret split across frame boundaries can't survive frames.jsonl); dx-explore
builds the redaction map from PROVIDER_KEY_NAMES, redacts the live screen
mirror at every tick (the mirror outlives interrupted runs), redacts
events.jsonl, and hard-fails via an independent post-save grep that deletes
any leaking file (structural redaction is primary, the grep is the check).
mirrorSession strips a bounded raw tail instead of the full buffer
(quadratic on 25-minute sessions); waitForAny matches only output after the
paste (the pasted prompt contains verify-adjacent copy); settle notes a
quiet-but-dialog-shaped tail (note-only) and stops early at grok's observed
sign-in copy; main() guards ptySupported() so an unsupported Bun fails in
1s, not 25 minutes. Unit tests: redact bundle + purity/short-value skip.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(dx): extract the shared install-session tail (runInstallSession + stageBinDir)
The claude/codex install scenarios were ~65-line copy-paste twins; the grok
scenario would have been the third. The duplicated tail (launch → mirror →
settle → paste → race verify-copy vs exit → trailing quiet → save) moves into
runInstallSession(ctx, {argv, cwd, env, extraAllow, dropEnv, prompt, timeoutMs,
meta}); per-agent preparation (claude TUI seed, codex auth copy + git init)
stays bespoke in each scenario. Carries two behavior deltas that belong to the
preceding fix commit and are stated here honestly: the twins' mirror now
passes the redaction map, and the verify race is scoped to output after the
paste (since-mark).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* dx: grok-install TTY scenario — brain-only GROK.md prompt, sign-in-wall early-stop
scenarioGrokInstall drives REAL interactive grok through the GROK.md
brain-only install (deliberately NOT the bootstrap paste block — the docs
classify grok as brain-only) with its own success patterns (the doctor
handshake banner). Keyless posture verified live: intro animation → sign-in
screen at ~6s ('Approve in your browser to finish signing in' + device code,
copy pinned in GROK-CLI-PIN.md) → skip-splash Enter → early-stop at 16s with
the friction recorded and the full transcript bundle written, instead of
pasting into the sign-in wall for the 25-minute race. Hardening found by the
same run: settle + early-stop strip bounded raw tails (the post-paste spinner
made full-buffer ANSI stripping the hot loop); the textless-splash heuristic
counts 3-plus-letter word runs (the animation is U+2800 braille — glyph
enumeration misses it); XAI_API_KEY joins PROVIDER_KEY_NAMES so --keyless is
honest and the redaction map covers it; BROWSER kill-switch so a keyless run
never bounces the operator's browser; grok credential path pre-registered for
the scrub.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: conform detectBinary/filterAllowlistEnv pins to isolation rule R1 (withEnv)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(todos): file grok-wave follow-ups (secret-enable lane, connect, backports, registry unification)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: review-army wave — P1 paid-turn PATH seam + security/redaction/CI hardening
Findings from the ship pre-landing review (5 specialists + Claude adversarial
+ 2 Codex passes), all applied:
P1 (Codex structured review): grokOneShotTurn rebuilt its child env without
the staged bin dir, so the documented bare-gbrain MCP registration that
doctor had just validated could not resolve during the actual paid turn on a
clean runner — grokChildEnv gains a binDir PATH-prepend and the door threads
it through the SMOKE.
Security: the version preamble now runs execFileSync with the FILTERED env
(it ran a shell one-liner with the full parent env — ambient secrets exposed
to a possibly mis-bound binary, plus a quoting seam on which-resolved paths);
detectBinary's which goes through execFileSync (the extraction had introduced
shell interpolation of binName); the grok-door auth-preflight scrubs the
writable GITHUB_* step files and disables web search; grokChildEnv also
deletes GITHUB_STEP_SUMMARY/GITHUB_ACTION_PATH; the live-lane runner no
longer forwards ANTHROPIC/OPENAI keys to grok (foreign-provider filter, with
shim-test barrier); stageGbrainBinDir rejects shell-active repo paths;
per-platform npm payload integrities pinned (wrapper integrity covers only
the wrapper tarball) with the version-immutability assumption stated; docs
quote the env flag value for spaced homes.
Redaction: a secret straddling PTY frame records survived frames.jsonl as
joinable halves (each frame is its own JSON record — the contiguous value
never existed in the serialized string, and the covering test passed
vacuously; verified empirically in review). saveTranscript now coalesces
straddling frames before redaction, the test asserts on the JOINED data
stream, assertNoSecrets gains stripped-ANSI + joined-jsonl passes and never
deletes files that predate the run (a --dir at repo root could have deleted
a pre-existing .env), and the init/drive scenarios pass the redact map to
the live mirror.
Correctness/perf: resolveGrokBinary fails CLOSED on an invalid GROK_BIN
(fall-through could bind the colliding community binary despite the pin);
--keyless now actually drops provider keys in all three install scenarios;
waitForAny strips a bounded window (the verify race had re-introduced the
quadratic full-slice strip); raw-tail windows widened 32K→128K for SGR-dense
repaints; grok-door compiles gbrain ONCE via a GBRAIN_COMPILED_BIN
short-circuit (two bun test processes each paid the compile); bounded stream
drain + SIGKILL escalation on turn timeout; CI cleanup also removes the
preflight home and tmp door homes; the pin guard fails closed once the door
job exists, strips single-quoted env values, and asserts npm_version ==
grok_version; sign-in-wall early path defers cleanup to finally.
Tests: vendor-tripwire fire/silent pins, preamble-failure resilience,
fail-closed GROK_BIN truth table, coalesce unit + joined-frames assertion,
SAFETY_FLAGS collision guard, awaited withEnv call sites, foreign-key
barrier, guard fail-closed/quote/equality cases. All affected suites green;
keyless door 4-pass live re-verified; verify 44/44.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.17.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.45.17.0
docs/INSTALL.md: per-client MCP guide list now covers every client guide
in docs/mcp/ (adds HERMES.md, OPENCLAW.md, CLAUDE_COWORK.md alongside the
new GROK.md line — README's client roster and this list now agree).
docs/guides/bootstrap.md: tty-harness example CLI list includes grok,
which the grok-install DX scenario now drives.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* chore(test): delete dead cli-pty-runner PTY harness + self-test (T1)
launchPty had zero callers since v0.25.1; its documented consumer
(test/e2e/skill-smoke-openclaw.test.ts) was never written. The numbered-menu
parsers match Claude-style cursor menus, not gbrain's typed-number picker,
so nothing is folded forward. git history preserves the file.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(init): real-PTY serial test for the interactive init pickers (T2)
Drives bun run src/cli.ts init under a true pseudo-terminal via launchTty:
keyless provider choice, then a NON-default search mode (tokenmax vs the
keyless-env conservative recommendation) so the assertions cannot pass via
the pickers' 60s default fallback. Hermetic HOME+GBRAIN_HOME temp root,
Anthropic key dropped, prompt-liveness bounds, close() in finally, CI
fail-loud PTY guard. Serial lane so it runs in required CI.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: fix three false coverage comments pointing at deleted or wrong harnesses (T3)
Two files deferred interactive-picker coverage to each other in a circle via
the deleted cli-pty-runner; a third called a piped-stdin e2e file PTY-based.
All three now point at the real coverage: test/init-picker-pty.serial.test.ts
for TTY branches, init-fresh-pglite for non-TTY branches.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: truth-up TTY-testing docs after harness deletion (T4)
KEY_FILES entry now describes the surviving tty-harness + dx-explore layer
(deleted runner's entry removed); TESTING.md gains the four-tier TTY-testing
decision table incl. the serial-lane CI rule and the non-default-value
assertion rule; tty-harness header stops calling its unit suite
zero-subprocess (the live block spawns sh).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(test): drop stale shard-weight entry for deleted cli-pty-runner test (T5)
No re-mine: pre-deletion CI logs would resurrect the deleted key, and
neither serial nor e2e files receive sharded weights. tty-harness.test.ts
keeps the median fallback until the next routine mining run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(todos): PTY transcript capture via Bun terminal option; file e2e CI-lane gap (T6)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(todos): e2e CI-lane gap entry — match current e2e.yml named-file list
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes — EOF picker case, dropEnv hardening, wording truth-ups
Testing specialist: add the Ctrl-D EOF case at the provider prompt (the shared
readLineSafe branch the deleted harness's comments falsely claimed to cover).
Maintainability: drop ANTHROPIC_AUTH_TOKEN alongside the API key; derive the
liveness bound from a named READLINE_FALLBACK_MS; reword three named-file CI
claims to the glob-free phrasing; un-future the tty-harness consumer list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial-review fixes — ASCII-safe PTY menu match, live TESTING.md exemplar
Red team: a PTY chunk boundary inside the menu line's multibyte em-dash would
permanently corrupt the match buffer (per-chunk utf-8 decode); match the pure
ASCII prefix instead. Adversarial: TESTING.md's piped-stdin row cited a file
that runs in no CI lane; cite the fast-loop example and annotate the manual one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: codex adversarial fixes — fixed 20s liveness bound; file the EOF 60s init stall
The liveness budget is now a fixed interaction bound independent of the
fallback constant, so dead input cannot pass even if the production fallback
shortens. The confirmed post-EOF stall (mode picker burns its full 60s after
Ctrl-D because stdin never yields another line) is a pre-existing product
bug — filed in TODOS with the probe numbers; the EOF test's early close is
now documented as deliberate.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.19.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.45.19.0
- docs/TESTING.md: add per-file inventory entries for the new real-PTY
init-picker serial test and the tty-harness pure-helper suite
- docs/guides/bootstrap.md: note the tty-harness now also backs a
required-CI test (init pickers), while the DX layer stays an instrument
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Neither README.md nor docs/ mentions the claude-cli recipe (shipped in
v0.42.66.0, #3310) — the only description of how it routes gateway.chat()/
toolLoop() through the local `claude` CLI, what it strips from the
subprocess env, and how gbrain models doctor's fixed 5s probe timeout
interacts with a cold subprocess start lived in source comments. Adds
docs/ai-providers/claude-cli.md following the existing zeroentropy.md /
llama-server-reranker.md format. Documentation of existing shipped
behavior only — no README/CLAUDE.md/code changes.
Claude-Session: https://claude.ai/code/session_01SMJA4RCTXLgsXjPM4o1qcP
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
`src/core/cli-flag-registry.generated.ts` is a committed generated artifact
that upstream regenerates on most waves, so any branch that also regenerates
it conflicts on the whole body — repeatedly, since rebasing only resets the
clock until the next wave.
The header already says how to regenerate but not what to do when the file
conflicts, which is the moment a contributor is actually looking at it. Adds
that: take the base branch's copy wholesale, re-run the generator, and let the
freshness test catch a regeneration done against the wrong base.
Comment-only. No flag entries change; the regenerated artifact differs from
its committed form solely by the new header lines.
* fix(serve-http,pglite): UTC-instant spend day boundary + snapshot timezone parity
The admin spend query compared created_at against a NAIVE date_trunc result,
reinterpreted in each session's timezone — any non-UTC session shifted the day
boundary by its offset and underreported today's spend every evening. The
boundary is now a timestamptz instant (double AT TIME ZONE), pinned by a
session-timezone-adversarial regression test (Etc/GMT+12 / Etc/GMT-12 / UTC)
that is red on the old query at any wall-clock hour.
Root cause of the local-red/CI-green suite: dumpDataDir bakes the BUILD
process's TimeZone into the snapshot tar, so snapshot-restored engines ran
sessions in the build machine's zone while cold-init engines follow the
runtime (bun test pins TZ=UTC). Restored engines now re-pin the session to
the runtime zone (heals existing tarballs with no rebuild), the builder pins
TZ=UTC before any PGLite work, and a serial parity test asserts cold and
snapshot engines agree on their session UTC offset.
* chore: bump version and changelog (v0.45.18.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(test): name-floor guard for every destructive-SQL test + repo-wide coverage gate (#3485)
Moves assertSafeE2eDatabaseUrl to leaf module test/helpers/db-guard.ts
(re-exported from test/e2e/helpers.ts for existing call sites) and calls it
before connect() in all ten files that run destructive SQL against the
ambient URL — the eight from #3485, one newer offender
(bootstrap-keyed-postgres.serial), and the raw-postgres()-client OAuth suite
the original audit could not see.
test/db-guard-coverage.test.ts is the static gate that keeps the class
closed: walks every test file bun collects repo-wide (all naming patterns,
fixtures included), detects ambient-URL reads at the assignment site (any
binding name, both env vars, bracket notation), recognizes four connect
idioms, treats env-var deletes as scrubs not reads, refuses comment-only
guard mentions, and pins its own classifiers with positive controls so it
can never pass vacuously.
Patch for the ten files adopted from #3485 by @cheRoma (fork access blocked
a PR) — thank you.
* feat(test): refuse to start a test run while a database URL is ambient (#3485)
A bunfig [test] preload (registered first) hard-fails any bun test invocation
while DATABASE_URL or GBRAIN_DATABASE_URL is set, unless
GBRAIN_TEST_ALLOW_DATABASE_URL=1 — refusing with instructions, never silently
unsetting (a silent unset would turn DB-gated e2e tests into green skips).
Boundaries: run-e2e.sh and the e2e/heavy workflows opt in at their own
subprocess boundary (run-e2e.sh also keeps the opt-in vars past its hermetic
GBRAIN_* scrub and drops GBRAIN_DATABASE_URL, which has no name floor on
spawned-CLI paths); the unit/slow wrappers strip both vars instead — unit
tests need no database — which keeps `bun run test:full` with a DB URL
exported reaching its e2e leg. The phantom-redirect parity file rides the
e2e lane and CI's jsonb-parity job so its Postgres arm stays reachable.
Six subprocess tests spawn real bun test children against the actual
bunfig registration: refuses each var, refuses both, strict override value,
override allows, empty-string treated as unset, clean run.
* fix(tests-heavy): shared database name floor for the heavy shell lane (#3485)
The heavy lane runs schema drops, source-registry rewrites, migration
replays, and parallel syncs against whatever the environment names — outside
bun, where the preload guard cannot fire. tests/heavy/_db_floor.sh mirrors
test/helpers/db-guard.ts: sourced by run-heavy.sh and by every script
documented for direct invocation, it floors BOTH DATABASE_URL and
GBRAIN_DATABASE_URL (the CLI these scripts shell out to prefers the latter)
and strips query strings before extracting the name, so a
?host=/tmp/test-sockets parameter cannot smuggle a test-shaped segment past
the check.
* chore: bump version and changelog (v0.45.15.0)
TESTING.md documents the four guard layers and the cwd caveat; TODOS.md
files the disclosure-policy follow-up (P2).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.45.15.0
Cross-reference pass after the #3485 test-safety wave (Wave -1):
- docs/TESTING.md: complete the guard layers (heavy shell floor
tests/heavy/_db_floor.sh, schema-drift's accepted inline floor), note
the phantom-redirect Postgres arm riding the e2e lane in the file
taxonomy + E2E inventory.
- docs/architecture/KEY_FILES.md: scripts/run-e2e.sh entry updated to
current behavior (no-args list carries phantom-redirect parity; #3485
opt-in boundary, GBRAIN_DATABASE_URL drop, GBRAIN_E2E_ALLOW_DB
preserved through the env scrub).
- CONTRIBUTING.md: heads-up that bare `bun test` refuses to start with a
database URL ambient + the name floor for own-Postgres/Supabase e2e.
- tests/heavy/README.md: database name floor section (which scripts
source it, PGLite scripts unset instead, new-script rule).
- .env.testing.example: Supabase's default "postgres" database name
fails the floor — dedicated test DB or one-shot GBRAIN_E2E_ALLOW_DB.
- CHANGELOG.md v0.45.15.0: three accuracy-of-wording touches (headline
"silently", lane boundary phrasing, note the one accepted inline
floor) — no entries removed or regenerated.
Codex cross-model doc review ran; concrete gaps applied above. llms
bundles regenerated (no byte changes — touched docs are link-only).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test): keep the coverage gate's own scrub-pattern out of the R1 isolation lint's sight
The gate detects 'delete process.env.X' as a scrub-not-read; the R1 lint greps
the same token textually and flagged the gate's comment and classifier fixture
as env mutations. Comment reworded; fixture built by concatenation so the
classifier still receives the contiguous statement.
* chore: re-slot as v0.45.17.0 (re-land of reverted #4126)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(cycle,locks): fenced lock identity + steal-abort — the cycle lock is actually refreshed in production (W0 Tier-1 #1)
The 2026-08-14 audit (CONFIRMED by adversarial verification) found the cycle
DB lock was effectively never refreshed: lock.refresh() was reachable only
through buildYieldDuringPhase, three of five pass sites handed phases the raw
caller hook, and NO production caller (jobs.ts, autopilot.ts) sets
yieldDuringPhase at all — so with the 5-minute TTL against 35-minute subagent
waits, every long cycle lost its lock mid-run and a second cycle could start
against the same source.
Fixes, per the fix-wave plan (D5.10/D5.11/D5.6):
- db-lock: refresh() and release() predicates now require the acquisition
fence (id, holder_pid, acquired_at::text) captured at acquire time, so a
PID-reuse impostor or a stolen handle can never refresh or delete a
successor's row. refresh() returns true only while owned; a fenced miss is
distinguished from transient DB errors (which still throw and retry).
- cycle: runCycle owns a SERIALIZED background refresher (6x per TTL window,
GBRAIN_CYCLE_LOCK_REFRESH_MS escape hatch) for the cycle lock only — Minion
job-lock renewal stays on the phase-boundary hooks per the cycle.ts:618
decision. A detected steal aborts an internal controller; the combined
signal reaches every existing checkAborted() boundary, and the five long
phases (synthesize, extract_atoms, patterns, synthesize_concepts,
consolidate) race their awaits against it since their opts cannot carry a
signal yet. The three raw yieldDuringPhase pass sites are now wrapped.
- A steal returns a structured partial report (reason 'lock_stolen') instead
of throwing; completed phases' writes are durable, the freshness stamp is
skipped, and the fenced release leaves the successor's row intact.
- supervisor: a fenced refresh returning false is CERTAIN lock loss, not a
blip — exit LOCK_LOST immediately instead of resetting the failure counter.
- withRefreshingLock: stops its heartbeat and reports loudly when the fenced
refresh proves the lock gone.
Closes TODO-OPS-2 (refresh had no rows-affected check, so lock loss was
undetectable).
Tests: db-lock-fencing (fence round-trip, steal → refresh false, fenced
release no-op, refresher abort/serialization/transient-vs-steal, yield hook
steal reporting), cycle-lock-steal.serial (end-to-end mid-run steal →
partial/lock_stolen report, no further phases, successor row intact +
steal-free regression guard). All pre-existing lock suites green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): reset started_at on every automatic re-run path (W0 Tier-1 #7)
handleWallClockTimeouts anchors on now() - started_at, but only the manual
`jobs retry` path cleared started_at — its own docstring documented the bug.
The four automatic paths (failJob's delayed branch, handleStalled's requeue,
promoteDelayed, and releaseLeaseFullJob — the fourth site surfaced by
adversarial verification) preserved the FIRST claim's timestamp, so an
exponential-backoff job burned its wall-clock budget while parked in
'delayed' and could be dead-lettered before executing a single line of its
retry attempt.
All four paths now clear started_at; claim()'s COALESCE re-stamps per
attempt. Terminal failures (failed/dead) keep started_at for duration
accounting. Pinned end-to-end: a job whose first attempt ran an hour
survives the sweep on its fresh attempt, and the negative control proves the
sweep still kills genuinely overrunning attempts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(minions): shared killJobs tail — stall-death notifies parents; reapers use parents-first lock order (W0 Tier-1 #4)
handleStalled's dead-letter branch set status='dead' and emitted NOTHING: no
child_done inbox row, no aggregator unblock. A child that died via max-stall
stranded its parent in 'waiting-children' forever — the exact hang the v0.15
comment says was fixed for timeouts (resolveParent has no periodic caller;
the worker only logs counts). Meanwhile handleTimeouts and
handleWallClockTimeouts carried two verbatim copies of the ~45-line
notify-and-unblock block.
- One private killJobs(tx, rows, outcome, errorText) now owns the child_done
insert + waiting-children unblock; all three reapers route through it.
handleStalled's dead branch emits outcome 'dead' / 'max stalled count
exceeded' (distinct from 'timeout' so consumers can tell stall-death from
overrun).
- Deadlock safety (Codex eng-review D5.12): failJob locks the parent BEFORE
touching the child, while the reapers previously updated children first —
opposite lock order. All three reapers now discover candidates with a plain
read, lock parents in ascending-id order via lockParentsOrdered(), then
transition children under a re-checked FOR UPDATE SKIP LOCKED subselect in
the same transaction.
Pinned: stall-exhausted child → child_done(dead) + parent flips to waiting;
budget-remaining stall requeues without touching the parent; all three
reapers' outcome/error strings asserted through the shared tail (D5.5).
Full minions e2e suite green (187 tests).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embed): carry modality through every re-embed path — one shared field list (W0 Tier-1 #3)
CONFIRMED in the audit + adversarial verification: preserveCodeMetadata
(commands/embed.ts) rebuilt ChunkInputs without `modality`, and upsertChunks
overwrites that column from EXCLUDED — so every CLI re-embed path (embedPage,
embed --all, embed --stale, including the autopilot-reachable stale loop)
flipped image chunks to modality='text'. The image search arm filters
cc.modality='image', so image retrieval silently went to zero while keyword
search started returning raw OCR text. The minion twin in core/embed-stale.ts
carried modality correctly and its comment documented this exact hazard —
the two hand-copied field lists had diverged.
carryChunkMetadata (core/embed-stale.ts) is now the single carry list;
preserveCodeMetadata delegates to it, killing the divergence class at the
root (the full loop merge lands in W6). embedding_image stays deliberately
un-carried (COALESCEd by the upsert; getChunks returns pgvector strings).
Pinned: the carry preserves modality + all 8 code-metadata fields; an image
chunk round-trips the stale-merge intact; and the write-side contract test
documents WHY the carry is load-bearing (omission demonstrably resets to
'text').
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(import): throw typed ImportAbortError instead of process.exit — MCP server survives failed preflights (W0 Tier-1 #5)
runImport called process.exit(1) at five preflight/argv sites (deferred-setup
sentinel, missing embedding credentials, invalid --workers, missing dir,
unreadable dir). Correct for the CLI — but runImport is invoked IN-PROCESS by
the sync_brain MCP op (via performFullSync), the autopilot daemon, and the
minion sync handler, so a first/forced sync against a brain with unusable
embedding credentials terminated the stdio MCP server mid-tool-call with no
error envelope (verified reachable in adversarial review; daemon/worker paths
are partially shielded by noEmbed defaults, the MCP path was not).
The five sites now throw ImportAbortError (exitCode, alreadyReported) AFTER
printing their user-facing messages exactly as before; the CLI dispatch case
maps the error to process.exit(exitCode) — byte-identical CLI behavior. The
in-process callers get a normal error: the MCP op returns an error envelope,
the job handler fails the job, the daemon logs and continues.
Pinned: three abort classes throw typed (not exit), and the calling process
demonstrably survives.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(lint): single scan for --fix — true fixed count, half the work (W0 Tier-1 #14)
runLint ran its own full read+lint+fix loop for human output, then called
runLintCore a second time for the summary line. Every page was linted twice,
and because the first pass had already written the fixes, the second pass's
total_fixed counted against already-fixed content — `gbrain lint --fix`
printed "0 auto-fixed." after fixing N issues.
runLintCore now exposes per-page hooks (onPageScanned for the progress bar,
onPageIssues with the applied fix count); the CLI streams its human detail
from the same single pass that produces the canonical counts. Pinned: two
pages scan as exactly two ticks, total_fixed matches the page-level fix
count, the fix lands on disk, and a second run reports 0.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(cli): confirm prompts resolve on EOF and refuse non-TTY in-prompt (W0 Tier-1 #15)
Port-ledger note: since the audit, both destructive-command callers
(pglite-repair, reinit-pglite) gained caller-side non-TTY guards
('Non-TTY environment requires --yes'), so the original always-hangs case is
already blocked upstream. The residual: a TTY session whose stdin hits EOF
mid-prompt still parked forever — pglite-repair's readline had no 'close'
handler and reinit-pglite's raw data-listener had no 'end' path (and its
prompt wrote to stdout, polluting --json output).
Both prompts now: refuse non-TTY in-prompt (defense-in-depth, safe default
false), resolve(false) on EOF/close, prompt on stderr, and clean up their
listeners. Decline paths and --yes/-y escape hatches unchanged. No new test:
exercising EOF-mid-TTY needs a PTY harness — the W5 prompt canonicalization
(core/prompt.ts) picks that up when all seven prompt copies converge.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ci): guard self-test harness — a guard that cannot fail is not coverage (W0 Tier-1 #11)
The audit proved scripts/check-no-double-retry.sh had been PERMANENTLY GREEN
since it shipped: its `[^)]*` regex could not cross the `)` in `() =>`, so
the canonical banned shape `withRetry(() => engine.addLinksBatch(...))` was
invisible, and its multi-line fallback was gated on pcregrep — installed
neither locally nor in CI. check-jsonb-pattern.sh carried the same
nested-paren hole. Two more structural findings: package.json's `check:all`
was a second, stale, hand-synced guard registry (the exact disease this
fix-wave exists to cure), and three guards were reachable ONLY from it —
i.e. never run anywhere.
- Both regexes fixed; the no-double-retry multi-line pass now uses perl
(always present) instead of pcregrep (never present). Real tree verified
clean under the fixed patterns.
- scripts/guards-manifest.tsv is THE single guard registry: all 45 guards
classified (scanner / buildfresh / repostate, per Codex D5.14 — build and
freshness guards are exempt-with-reason, not fixture-tested).
- scripts/guard-self-test.sh runs every selftest=yes scanner against
known-bad (must fail) and known-good (must pass) fixture trees via the
GBRAIN_GUARD_ROOT seam, enforces manifest completeness for new guards, and
carries a runtime budget (D4.5) so guard sprawl surfaces here first.
Wired into `bun run verify`; adding a self-test = flip a manifest flag +
two fixture files.
- `check:all` deleted; its three orphaned guards (newlines, exports-count,
no-legacy-getconnection) verified green and wired into the real registry.
The bad fixtures are the exact shapes the old regexes missed — the harness
fails loudly on the pre-fix scripts.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test-infra): PGLite snapshot default-on for `bun run test` — idempotent, shard-safe, handler-aware (W0 Tier-1 #16)
500+ test files each cold-boot PGLite and replay all 126 migrations, but the
snapshot fixture that skips that was enabled ONLY inside scripts/ci-local.sh
— the everyday `bun run test` loop paid full cold-init on every file
(measured: 1.63s → 0.91s per PGLite-booting file with the fixture).
- run-unit-parallel.sh (the `bun run test` entrypoint) builds + exports the
snapshot BEFORE its shard fan-out. Opt out: GBRAIN_NO_SNAPSHOT=1.
- build-pglite-snapshot.ts is now idempotent: hash short-circuit exits in
~40ms when fresh, and REBUILDS stale snapshots — the old build-if-missing
guard left a stale-but-present snapshot permanently on the warn+slow path.
ci-local.sh now calls it unconditionally.
- Shard/workspace concurrency safety (Codex D5.8): atomic mkdir lock with
takeover-on-stale; tar written first, version file last, so a crash can
never leave a fresh-looking torn fixture.
- Hash soundness (Codex D5.13 / #4): 19+ migrations carry executable
`handler` code with empty sql — invisible to the sql-only hash, so editing
a handler reused a stale snapshot. The handler SOURCE now folds into the
hash via Function.prototype.toString.
Migration-replay coverage is unchanged: the replay canary tests clear
GBRAIN_PGLITE_SNAPSHOT themselves and migrate.test.ts exercises
runMigrations directly.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test-infra): snapshot bakes the pinned test embedding shape; loader refuses shape mismatches (W0 follow-through)
Turning the snapshot default-on exposed a latent poisoning class: the build
script ran with an UNCONFIGURED gateway, so initSchema fell back to the
shipped default (1280-d zembed columns) — while bunfig's preload pins every
`bun test` file to the legacy OpenAI 1536-d shape. The moment tests loaded
the fixture, every embedding write failed with "expected 1280 dimensions,
not 1536" (115 suite failures from one root cause).
- The pinned shape now lives ONCE in test/helpers/legacy-embedding-config.ts;
both the bunfig preload and the snapshot build script consume it (no
hand-copied twins — the exact disease this wave cures). The build also
isolates GBRAIN_HOME so ambient machine config can't leak in.
- The version file records dims= and model= alongside the schema hash; the
loader resolves its own would-be shape through the same gateway-or-default
fallback initSchema uses and REFUSES a shape-mismatched snapshot (falls
back to cold init with a rebuild hint). Pre-W0 hash-only version files
read as stale. A test that reconfigures the gateway to a different shape
now correctly bypasses the fixture instead of writing into wrong columns.
- The build's freshness short-circuit checks all three lines.
- Rephrased a guard comment that spelled a batch-call token literally —
check-system-of-record scans scripts/ comments (the prose-bleed class,
third occurrence this month).
put-page-provenance: 9 fail → 0 under the fixture, still 3x faster than
cold init.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(eval): fix-wave baseline metrics — measure the 10x claim (W0, D4.13)
Records the series' starting numbers: god-file line counts (the registry
waves' targets), guard census (47 guards / 3 self-tested / single registry),
and the measured snapshot speedup (1.63s → 0.91s per PGLite test file).
Each wave PR appends its row; the deltas are the receipt. The retrieval-
quality canary (eval gate on a non-production brain) is documented as the
mandatory pre-W1 step — W0 touches no search paths and the production brain
is single-writer-held by the live serve.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(cycle,ci): duck-type-tolerant signal combining + contract-test updates (W0 follow-through)
- anyAbortSignal no longer uses AbortSignal.any: CycleOpts.signal has always
been duck-typed in practice (test stubs pass { aborted: false } and flip
the flag; pre-W0 the raw object flowed straight into checkAborted).
AbortSignal.any threw ERR_INVALID_ARG_TYPE and broke the autopilot-cycle
handler suite. Manual fan-in: real signals propagate via listener,
listener-less stubs are polled at 50ms, and the RETURNED signal is a
genuine AbortSignal so phases can hand it to fetch/timers.
- cycle-abort.test.ts source-contract tests updated to the cycleSignal truth
(boundaries now check the combined external+steal signal) and additionally
pin that the combine folds BOTH sources.
- Restored the `typecheck` entry an errant edit dropped from
run-verify-parallel's CHECKS array (caught by its own contract test —
the registry pinning working as designed).
- De-flaked the refresher steal test: poll to a 5s deadline instead of a
fixed 120ms sleep (shard-load timer starvation).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes — 5 specialists + coverage audit findings (W0 ship pass)
Specialist review (testing/maintainability/security/performance/data-migration,
5 parallel fresh-context reviewers + ship coverage audit at 92%) on the W0
diff. Every accepted finding fixed in-line:
- db-lock: fence rendered as extract(epoch from acquired_at)::text — THREE
specialists independently flagged timestamptz::text as GUC-fragile (the
fence is captured on the acquire pool but compared on the direct pool; a
TimeZone/DateStyle divergence would turn every refresh into a false steal
and loop the supervisor through LOCK_LOST). Epoch text is session-invariant.
- cycle: anyAbortSignal returns {signal, dispose}; runCycle disposes in its
finally — the forward listener lives on the CALLER's signal and the
autopilot daemon reuses one shutdown signal across every tick, so
undisposed combines accumulated listeners + captured controllers for the
daemon's lifetime (MaxListenersExceededWarning within ~10 ticks). Stub
poll timers clear on dispose too. Helper moved out of the import block and
behaviorally tested (5 cases incl. the daemon-leak class).
- queue: retroactive stranded-parent sweep on every handleStalled tick — the
per-kill unblock was forward-only, so parents stranded by PRE-upgrade
stall-deaths (children already 'dead') never healed. Idempotent NOT-EXISTS
UPDATE; pinned with stranded-heals + live-child-stays tests.
- build-pglite-snapshot: the stale-lock takeover could NEVER acquire
(mkdirSync on an existing dir always throws), so one crashed builder left
every future rebuild waiting the full deadline then proceeding UNLOCKED
forever. Takeover now removes the stale dir first; lock timeout is
env-tunable; hermetic setup moved into main() (ESM hoisting made the
module-scope placement illusory) and the temp home is cleaned up.
- check-no-double-retry.sh: the perl multi-line pass exited 1 from clean
batches — under pipefail, xargs's 123 would override grep's verdict the
moment src/ outgrows one batch (a future silent miss of the exact class
this guard just got cured of; repro'd by the reviewer). Output-presence now
decides; multi-line bad fixture added so the pass self-tests.
- check-jsonb-pattern.sh: the widened greedy pattern false-positived a SAFE
::text::jsonb line followed by a paren-bearing ${expr()}::jsonb on the same
line (proven by repro); bracket-bounded [^}]* pattern can't span
interpolations — good fixture now pins the multi-interpolation shape.
- check-engine-dynamic-import.ts: also matches require() calls (the new
snapshot-loader require was invisible to the guard, its marker decorative);
4 pre-existing lazy requires in tryLoadSnapshot marked with their existing
justification.
- Coverage gaps closed: supervisor fenced-false → immediate LOCK_LOST test;
snapshot shape/hash guard tests (pre-W0 version files refused, dims/model
mismatch refused, handler-edit changes the hash); anyAbortSignal behavior
suite; steal-test window widened 200ms → 1.5s (shard-load starvation).
- lint: tree walked once (onPagesCollected sizes the progress bar; the CLI's
extra collectPages walk removed); stale docstrings corrected (hook fires
AFTER the fix attempt; carry list includes modality).
- Suite hygiene: 3 fresh-brain-premise tests opt out of the default-on
snapshot; the check:all contract test now pins the single CHECKS registry.
- TODOS.md: 6 fix-wave deferrals filed (each individually decided in review);
TODO-OPS-2 marked CLOSED by this wave.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: red-team findings — unfenced file-lock half, 5th started_at path, sync-phase steal coverage (W0 ship pass 2)
The post-specialist red team found what five specialists and the coverage
audit all missed — two of them critical:
- cycle (CRITICAL): the PGLite composite lock's FILE half was rewritten
unconditionally even when the fenced DB refresh reported a steal — the
losing holder clobbered the successor's file lock with its own pid on the
very tick it detected the loss, after which its pid-checked file release
DELETED the successor's only host-local protection mid-run (single-writer
violation). The file half now rewrites only while the DB fence says owned.
- queue (CRITICAL): fifth path of the started_at class — every
waiting-children→waiting parent unblock (killJobs, completeJob resolve,
failJob remove_dep/ignore, cancelJob, resolveParent, the new retroactive
sweep: 7 sites) preserved the parent's attempt-1 anchor, so an aggregator
whose children ran >5 minutes was wall-clock dead-lettered on re-claim —
orphaning the exact child_done results the W0 parent-unblock fix just
delivered. All 7 unblock sites now clear started_at; pinned by a
parked-parent-survives-the-sweep test.
- cycle: the sync phase — production's LONGEST await (resumable imports can
run hours) — was the one long phase outside steal coverage. Now raced like
the other five (sync checkpoints, holds its own per-source lock, and its
stall watchdog bounds the dangling import).
- build-pglite-snapshot: takeover verifies lock-dir mtime staleness before
rmdir (two exhausted waiters could steal each other's LIVE lock);
hermetic temp home created only past the short-circuit (was leaking one
dir per `bun run test`).
- Stale docs: jobs.ts import-handler comment claimed a process.exit that no
longer exists; CLAUDE.md's engine-dynamic-import exception list now names
the snapshot loader's require() cluster (build:llms regenerated in this
commit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.15.0)
W0 verified-bug hotfix wave of the code-smell fix-wave series. All six
version locations synced (VERSION, package.json, openclaw.plugin.json,
runbook stamp, template stamp, lockfile).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: update project documentation for v0.45.15.0
- docs/TESTING.md: tiers table now documents the default-on PGLite schema
snapshot for `bun run test` (GBRAIN_NO_SNAPSHOT opt-out); new "PGLite
schema snapshot" + "Guard registry and self-test" sections (build/loader
contract, GBRAIN_SNAPSHOT_LOCK_TIMEOUT_MS, guards-manifest.tsv,
GBRAIN_GUARD_ROOT); removed the deleted `check:all` tier; added the nine
new W0 test suites to the unit-test inventory.
- docs/architecture/KEY_FILES.md: current-state refresh for db-lock.ts
(fenced handles, boolean refresh, LockStolenError), cycle.ts (dedicated
serialized lock refresher, GBRAIN_CYCLE_LOCK_REFRESH_MS, steal-abort with
reason lock_stolen, composed DB+file lock semantics; dropped the closed
TODO-OPS-2 residual), minions/queue.ts (shared killJobs tail,
lockParentsOrdered, stranded-parent sweep, started_at resets),
supervisor.ts (fenced miss exits LOCK_LOST immediately), embed.ts
(carryChunkMetadata shared field list), import.ts (typed
ImportAbortError), lint.ts (single-pass --fix), pglite-repair.ts (EOF-safe
stderr confirm prompts), check-no-double-retry.sh (arrow-paren-crossing
pattern, perl fallback); new entries for guards-manifest.tsv +
guard-self-test.sh and build-pglite-snapshot.ts; swept stale check:all
references.
- CONTRIBUTING.md: verify check count refreshed; check:all replaced with the
guard-registry + self-test workflow.
llms bundles verified fresh (bun run build:llms — no byte changes;
test/build-llms.test.ts green). CHANGELOG/TODOS/VERSION already current from
the ship pass.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: cross-model doc-review fixes for v0.45.15.0 (Codex pass)
- CHANGELOG 0.45.15.0: the image-chunk recovery command is `gbrain backfill
modality` (flipped chunks are not stale, so an embed --stale re-run cannot
restore them — doctor names the same fix); upgrade note now also covers
jobs supervisor/worker restarts; the prompt-hang fix names its two commands
instead of implying all destructive prompts; guard self-test claim scoped
to self-tested scanners.
- KEY_FILES: cycle entry counts all 23 ALL_PHASES (was 9); raced-wait nuance
for the 5 long phases (in-flight work runs to its bounded timeout);
snapshot-lock last-resort unlocked path + version-file-not-tar gate scope;
guards manifest registers/classifies but does not schedule (CHECKS array
stays the execution list).
- TESTING.md: same snapshot-lock last-resort honesty.
- CONTRIBUTING.md: self-test scope (selftest=yes rows), stale ~85s inner-loop
figure and 19+ check count refreshed.
- FIX_WAVE_BASELINES.md: two W0 line counts refreshed per the doc's own
method (post-ship-pass HEAD).
llms bundle rebuilt (no byte changes); guards + build-llms test green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: re-bump to v0.45.16.0 (version queue collision with #4125)
The sibling jobs fix wave (PR #4125, open) claims v0.45.15.0; per the
user's call this PR advances past it. All six version locations re-synced.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: withEnv() for snapshot opt-out in embedding-dim fresh-brain case (test-isolation guard)
The W0 ship-pass fix used a manual save/delete/restore of
GBRAIN_PGLITE_SNAPSHOT, which check-test-isolation rule R1 flags on CI
(the local ship verify ran before this file gained the mutation).
withEnv() scopes the opt-out to the connect() call with identical
behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(cli): real help for jobs and its subcommands — never start a daemon on --help
`jobs` was in CLI_ONLY but not CLI_ONLY_SELF_HELP, so `gbrain jobs --help`
printed the generic one-line stub and the real help block (with the worker
entry point) was unreachable. Naively registering it would have been worse:
a help token after the subcommand fell through into the subcommand body, so
`jobs work --help` would have started a real worker daemon.
- Hoist the help block to JOBS_HELP; document watch, stats --cluster-errors,
smoke rescue flags; precise footer naming exactly the five subcommands
with dedicated help.
- JOBS_SUBCOMMAND_HELP (bootstrap.ts pattern) for work/supervisor/submit/
watch/prune, guarded at the top of runJobs BEFORE the thin-client refusal
and the switch. Only --help/-h; bare 'help' can be a job name.
- cli.ts: add jobs to CLI_ONLY_SELF_HELP + SELF_HELP_WITHOUT_ENGINE (help
answers engine-free); top-level JOBS section gains supervisor + watch.
- Regenerate the CLI flag registry (help text is harvested for flags).
- Tests: jobs-subcommand-help.serial (spawned CLI, engine-free env hygiene,
anti-stub + fast-exit-proves-no-daemon); jobs added to HELP_WITHOUT_BRAIN.
* fix(minions): claim-time timeout fallback + v128 backfill/duplicate-cleanup + jobs get budget surface
Pre-existing queued rows with timeout_ms = NULL fell to the minutes-scale
null-default wall-clock sweep (2 x lock-duration x max_stalled ~= 5 min at
defaults), so long handlers queued before submit-time stamping were
dead-lettered mid-progress — identical work succeeded or died purely on
insertion time, and the queue was effectively undrainable.
Three layers now apply the handler budget (explicit timeout_ms always wins):
- claim(): COALESCE timeout_ms from HANDLER_DEFAULT_TIMEOUT_MS (raw-object
jsonb bind; executeRawDirect preserved), deriving timeout_at from the
coalesced value. Durable invariant; also revives the worker abort timer,
deadlineAtMs budget clamping, inline-drain abort, and the handleTimeouts
first-killer for legacy rows. Names outside the map stay NULL (fail-open).
- migration v128 statement 1: one-shot backfill for non-terminal rows of the
8 long-lane handlers (values snapshotted at authoring time; never sync with
the live map). No timeout_at stamp for active rows — the 2x wall-clock
bound is the gentler sufficient repair.
- migration v128 statement 2: cancel all-but-newest ticker-keyed duplicate
waiting cycles per (name, queue, source) — prefix-guarded so manually
submitted cycles are never touched; rows preserved as cancelled for audit.
jobs get now prints the effective budget (1x deadline when claimed; 2x
wall-clock backstop) with a defensive Date|string deadline render;
timeout_at joins JOB_DATE_FIELDS for thin-client rehydration.
Tests: migrations-v128 (backfill matrix, cleanup scopes, manual/parented
exclusions, ledger + SQL-level rerun idempotency, empty-table no-op),
claim-fallback block in minions.test.ts, formatJobDetail render states,
rehydration field. PGLite snapshot rebuilt for the new migration.
* fix(autopilot,minions): maxPending single-flight dispatch guard + honest coalesce surfaces
The autopilot dispatch guards accumulated unbounded byte-identical cycles
once a job stalled in 'active': the slot idempotency key rotates every
baseInterval so it never dedups across ticks, and maxWaiting counts only
waiting rows. One observed brain held ~111 queued duplicates with zero
completions.
New INTERNAL submit option maxPending (single-flight):
- counts waiting rows PLUS live-lock active rows (lock_until > now()); an
expired-lock active belongs to a dead/blocked worker and never suppresses
dispatch, so fresh waiting rows keep feeding the waitingClaimable>0 wedge
detectors instead of starving them
- EXACT source scope via COALESCE(data->>'sourceId', data->>'source_id')
compared with IS NOT DISTINCT FROM (NULL matches only NULL) — a legacy
no-source dispatch can never coalesce into a per-source row; maxWaiting
keeps its intentional NULL-as-wildcard scope, now two-spelling aware
- same advisory-lock namespace as maxWaiting so both guards serialize;
maxPending checked first when both are supplied
- adopted at all three autopilot dispatch sites (legacy fallback,
per-source fan-out — safe there precisely because of the exact scope —
and global maintenance), replacing maxWaiting where present
Honest coalesce surfaces: all three add() coalesce paths (idempotency
fast-path, cap-hit, ON CONFLICT race fallback) stamp non-persisted
coalesced metadata; fanout splits FanoutResult.dispatched vs .coalesced,
emits dispatch_coalesced events, and the summary reports both. The
backpressure audit gains pending_count/max_pending, and jobs stats prints
a 24h Backpressure line (current + previous ISO-week audit files, queue
filtered) plus a suppressed-by hint naming the in-flight job — so
suppression is never silent even while waiting sits at 0.
Tests: maxPending block (live-lock vs expired-lock, exact NULL scope, both
spellings, both-guards interaction, race smoke), coalesce-metadata pins,
fanout opts + coalesce-event guards, audit reader (week boundary, queue
filter, malformed lines), and DB-gated e2e: issue reproduction (stalled
active suppresses cross-slot re-dispatch), full recovery loop with a real
claim + real sweeps, fan-out preservation under maxPending, and a real-PG
concurrent same-scope race pinning the advisory-lock guarantee.
* fix(minions,jobs): adversarial-review fixes — honest coalesce contract + hardened surfaces
Codex structured review (ship gate, P2s) + Codex adversarial challenge:
- dispatchGlobalMaintenance returns dispatched: false when the submission
coalesced — same honest-dispatch contract as dispatchPerSource.
- The jobs stats suppression hint is driven by the audit's latest
returned_job_id per name and scoped to THAT job's source, so on
multi-source brains source A's waiting row can't mask source B's wedge.
readRecentCoalesceCounts now returns {count, last_returned_job_id}.
- Backpressure audit writes are deferred to after the submission
transaction commits — filesystem I/O no longer runs while holding the
advisory lock + a pool connection (a hung audit volume degraded one
submission, not the whole scope's queue).
- The audit reader caps per-file reads at the last 4MB (tail slice,
partial first line dropped) so a caller-grown audit file can't OOM the
diagnostic that reads it.
- v128's duplicate cleanup additionally requires data.sourceId IS NULL:
the ticker only writes snake_case source_id, so camelCase rows are
by definition not ticker-provenance and are never swept.
- Supervisor help states the real --max-crashes semantics (soft degraded
threshold; hard stop at 10x N via GBRAIN_SUPERVISOR_HARD_STOP_CRASHES)
and the brain-scoped PID file default.
* chore: bump version and changelog (v0.45.15.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: brain-scoped supervisor pidfile default in minions-deployment example
The jobs.ts help text was corrected this wave to name the brain-scoped
default (~/.gbrain/supervisor-<brain-id>.pid); the deployment guide's
example output still showed the old un-scoped path.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: accuracy pass from cross-model doc review (v0.45.15.0)
- CHANGELOG: dead-worker (not wedged-worker) dispatch claim; scope the
truthful-dispatch bullet to autopilot cycle dispatch; jobs submit has no
--json flag (JSON is the default non-follow output); v128 manual-cycle
carve-out names the ticker-key heuristic honestly.
- KEY_FILES: handler-timeouts map is 8 handlers across 30/10/60-min tiers;
queue.ts subagent gate is capability-based (classifyCapabilities), not the
retired Anthropic pin; drop stale jobs.ts line-range refs; jobs submit
flag list is not the "full" MinionJobInput surface (maxPending internal).
- jobs.ts help: prune --older-than is days-only (no Nh forms); supervisor
exit code 4 (DB queue lock lost) documented.
- types.ts: coalesced JSDoc names the real JSON output path.
- minions-deployment: detach payload example matches the real fields.
- TODOS: bank handler-catalog + dispatch-event-schema doc gap (P3).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(cli,autopilot,jobs): red-team review fixes — prototype-safe help lookup + honest targeted dispatch + hint precision
Red-team pass on the final diff (4 informational findings, all fixed):
- Object.hasOwn guards on JOBS_SUBCOMMAND_HELP and bootstrap's
SUBCOMMAND_HELP: `jobs constructor --help` (or toString/valueOf/…)
printed Object.prototype functions instead of the full help.
- The targeted-plan dispatch loop now splits on job.coalesced and emits
dispatch_coalesced — the honest-dispatch contract this wave applies to
every other dispatch surface in the same file.
- jobs stats: the hint slice reuses the count-sorted entries (insertion
order could crowd out the highest-volume names past the cap), and the
target CTE re-checks name+queue so a shared cross-brain audit dir can
never name an unrelated job as the suppressor.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Reverts the six rebase-merged commits c439fad23..418dc1543:
DATABASE_URL preload guard, name floors, coverage gate, heavy-lane floor,
version bump, and docs. Restores master to v0.45.14.0 (dd99e40c2 state).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The gate detects 'delete process.env.X' as a scrub-not-read; the R1 lint greps
the same token textually and flagged the gate's comment and classifier fixture
as env mutations. Comment reworded; fixture built by concatenation so the
classifier still receives the contiguous statement.
Cross-reference pass after the #3485 test-safety wave (Wave -1):
- docs/TESTING.md: complete the guard layers (heavy shell floor
tests/heavy/_db_floor.sh, schema-drift's accepted inline floor), note
the phantom-redirect Postgres arm riding the e2e lane in the file
taxonomy + E2E inventory.
- docs/architecture/KEY_FILES.md: scripts/run-e2e.sh entry updated to
current behavior (no-args list carries phantom-redirect parity; #3485
opt-in boundary, GBRAIN_DATABASE_URL drop, GBRAIN_E2E_ALLOW_DB
preserved through the env scrub).
- CONTRIBUTING.md: heads-up that bare `bun test` refuses to start with a
database URL ambient + the name floor for own-Postgres/Supabase e2e.
- tests/heavy/README.md: database name floor section (which scripts
source it, PGLite scripts unset instead, new-script rule).
- .env.testing.example: Supabase's default "postgres" database name
fails the floor — dedicated test DB or one-shot GBRAIN_E2E_ALLOW_DB.
- CHANGELOG.md v0.45.15.0: three accuracy-of-wording touches (headline
"silently", lane boundary phrasing, note the one accepted inline
floor) — no entries removed or regenerated.
Codex cross-model doc review ran; concrete gaps applied above. llms
bundles regenerated (no byte changes — touched docs are link-only).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
TESTING.md documents the four guard layers and the cwd caveat; TODOS.md
files the disclosure-policy follow-up (P2).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The heavy lane runs schema drops, source-registry rewrites, migration
replays, and parallel syncs against whatever the environment names — outside
bun, where the preload guard cannot fire. tests/heavy/_db_floor.sh mirrors
test/helpers/db-guard.ts: sourced by run-heavy.sh and by every script
documented for direct invocation, it floors BOTH DATABASE_URL and
GBRAIN_DATABASE_URL (the CLI these scripts shell out to prefers the latter)
and strips query strings before extracting the name, so a
?host=/tmp/test-sockets parameter cannot smuggle a test-shaped segment past
the check.
A bunfig [test] preload (registered first) hard-fails any bun test invocation
while DATABASE_URL or GBRAIN_DATABASE_URL is set, unless
GBRAIN_TEST_ALLOW_DATABASE_URL=1 — refusing with instructions, never silently
unsetting (a silent unset would turn DB-gated e2e tests into green skips).
Boundaries: run-e2e.sh and the e2e/heavy workflows opt in at their own
subprocess boundary (run-e2e.sh also keeps the opt-in vars past its hermetic
GBRAIN_* scrub and drops GBRAIN_DATABASE_URL, which has no name floor on
spawned-CLI paths); the unit/slow wrappers strip both vars instead — unit
tests need no database — which keeps `bun run test:full` with a DB URL
exported reaching its e2e leg. The phantom-redirect parity file rides the
e2e lane and CI's jsonb-parity job so its Postgres arm stays reachable.
Six subprocess tests spawn real bun test children against the actual
bunfig registration: refuses each var, refuses both, strict override value,
override allows, empty-string treated as unset, clean run.
Moves assertSafeE2eDatabaseUrl to leaf module test/helpers/db-guard.ts
(re-exported from test/e2e/helpers.ts for existing call sites) and calls it
before connect() in all ten files that run destructive SQL against the
ambient URL — the eight from #3485, one newer offender
(bootstrap-keyed-postgres.serial), and the raw-postgres()-client OAuth suite
the original audit could not see.
test/db-guard-coverage.test.ts is the static gate that keeps the class
closed: walks every test file bun collects repo-wide (all naming patterns,
fixtures included), detects ambient-URL reads at the assignment site (any
binding name, both env vars, bracket notation), recognizes four connect
idioms, treats env-var deletes as scrubs not reads, refuses comment-only
guard mentions, and pins its own classifiers with positive controls so it
can never pass vacuously.
Patch for the ten files adopted from #3485 by @cheRoma (fork access blocked
a PR) — thank you.
* feat(bootstrap): harness-lane settings writers — marker/path params, permissions.allow, CODEX_HOME (#4043 step 1)
writeClaudeHooksAt/removeClaudeHooksAt with marker VALUE parameterization
(bootstrap-v1 and bootstrap-harness-v1 coexist; each removal strips only its
own), onBrokenJson relocate|abort policy (user-scope files must never be
relocated over a stray comment), refuseOnForeignGbrainMarker double-fire
guard, and addPermissionsAllowEntry/removePermissionsAllowEntry (set
semantics, no marker, foreign entries preserved). Atomic writes hardened:
realpath-resolved targets (dotfile symlinks survive), mode preservation,
random tmp suffix, timestamped backup strategy. codexConfigPath now honors
CODEX_HOME (config dir itself — pinned by the real-codex e2e convention).
Legacy wrappers keep byte-identical behavior; existing writer suite untouched
and green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): codex-toml managed block writer — the fired CX2-17 revisit (#4043 step 2)
One [mcp_servers.<name>] table with inline bearer_token between full-line
markers; everything outside survives byte-for-byte. Foreign-server detection
parses the config (Bun.TOML.parse, no new dependency) with our block
stripped, so inline-table/dotted/quoted spellings can't false-negative into
a codex-bricking duplicate table. Rewrites re-anchor at EOF; renders are
parse-validated with an ours-keys-exactly assert before rename; damaged
markers refuse. Secrets hygiene: 0600 tmp/target/.bak, group-readable
configs tightened with a note. CRLF preserved, missing trailing newline
repaired. TARGETS['codex-2026-08'] flipped to verified (codex-cli 0.147.0:
serde field scan; codex hooks existence recorded; CODEX_HOME resolution).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(auth): least-privilege legacy tokens — adopt the scopes TEXT[] column (#4043 step 3)
The dormant original-schema access_tokens.scopes column becomes THE scope
store: verifyAccessToken's legacy branch honors it (NULL = grandfathered
full access, so every existing token is byte-identical; a filtered-empty
array is deny, so typos fail closed), and a column is structurally immune
to the permissions-object-replacement wipe class. That class gets fixed at
its known site too: auth permissions set-takes-holders now MERGES into the
permissions JSONB instead of replacing it (a routine visibility edit would
have silently deleted the source_id federation grant and re-escalated).
New surface: gbrain auth create --scopes read,write (comma/whitespace,
mint-time validation); auth list shows id + scopes columns (grandfathered
rendered honestly); auth revoke --id <uuid> for precise revocation (names
are not unique — bulk revoke-by-name now says when it hit several). New
src/core/token-mint.ts (mintLegacyToken with federation source grant +
RETURNING id; revokeLegacyTokenById never touches same-name siblings) for
the harness rotation contract. The admin dashboard's agents endpoint stops
hardcoding full access for every legacy key and reads the real grant.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): harness receipt + mcp-registration core extraction (#4043 step 4)
HarnessReceipt is a machine-level sibling of receipt.json (the install
receipt is workspace-keyed; a harness-only box has no workspace) with the
same CX2-12 discipline: typed read states, newer-format refusal, broken-file
backup-aside, atomic 0600 writes. Write-ahead contract: targets persist as
pending at mint time and confirm as wiring lands, and token.previous_id
carries the prior token through the mint-first rotation, so a crash at any
step leaves a receipt --remove can consume.
The pure MCP-registration helpers (normalizeMcpUrl, argv builders,
redactToken, validateToken, shellQuote/cmdString) move from
src/commands/connect.ts to src/core/mcp-registration.ts — the harness lane
lives in core and core must not import from commands. connect.ts re-exports
(surface + tests unchanged). buildClaudeMcpAddArgv gains an optional scope
param (claude's default is local; harness must pass user); loopback helper
exported for the harness --url guard.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): `gbrain bootstrap harness` — wire framework-spawned sessions to a running serve (#4043 step 5)
The orchestrator (src/core/bootstrap/harness.ts): consent block in the
#4029 honesty register (reach stated as fact, transcript capture its own
numbered item, off-ramps in the same breath; non-TTY requires --yes),
/health probe with a loopback guard (remote brains are gbrain connect's
charter), mint-first rotation (previous token revoked BY ID only after
every target confirms and the smoke passes), write-ahead harness receipt
(crash at any step leaves consumable state), registration ownership checks
(--force to replace a foreign-url server; --remove skips what it no longer
owns), user-XOR-project hook scopes with the double-fire refusal, the
GBRAIN_HOOK_LANE=harness runtime defer guard in `gbrain hook` (workspace
bootstrap installs win), --no-capture context-only wiring, Postgres
degradation + version-skew honesty lines, --status with host-config token
recovery and honest degrades, and engine-free-first --remove that defers
the revoke under a live PGLite serve.
Dispatcher wiring: `bootstrap harness` subcommand (home-dir lock, own
install-log phase), uninstall runs harness removal FIRST (revoke needs the
DB alive; --delete-brain would destroy harness.json) and treats
NO_RECEIPT/HOME_GUARD/RECEIPT_MISMATCH as "no workspace install" once
harness wiring is cleared; runHooks' codex stdio lane defers to a
harness-managed server name (one owner per name); the stale "Codex has no
hook system" line now states the truth. Flag registry regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): harness doctor check + lifecycle e2e; CLAUDE_CONFIG_DIR-safe user-settings path (#4043 step 6)
Doctor gains bootstrap_harness_health inside the existing bootstrap check
group (no new status phase): skip when not a harness box / warn when the
serve is down (a normal transient) or the receipt is unreadable / fail when
targets are failed-or-pending or a rotation never converged — and a
harness-only box now opens the bootstrap check gate at all (it previously
got ZERO checks).
E2E lifecycle against a real `serve --http` on a hermetic PGLite brain:
pre-minted scoped token (the documented PGLite escape), real /health +
bearer smoke, both harness lanes wired, --status with token recovery from
the codex block, --remove leaving the codex config byte-identical, the
mint-under-live-serve refusal, and a live insufficient_scope refusal of an
admin op — least privilege proven end to end.
Root-cause fix the e2e caught: Bun's homedir() reads the password database
and ignores a remapped HOME, so claudeUserSettingsPath now resolves via
CLAUDE_CONFIG_DIR (Claude Code's own override) then $HOME explicitly —
without it, sandboxed runs write into the operator's REAL settings file
(the write-ahead receipt's remove path self-healed the one incident).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(bootstrap): v0.45.9.0 — local harness mode docs, scoped-token honesty pins, TODOS follow-ups (#4043 step 7)
docs/guides/bootstrap.md gains the "Local harness mode" section + the
missing Postgres row in the degradation matrix; DEPLOY.md/CODEX.md stop
claiming the token grandfather is unconditional and distinguish the connect
lane (token in env) from the harness lane (inline, 0600, consented);
KEY_FILES.md bootstrap cluster describes the parameterized writers,
codex-toml.ts, harness.ts, token-mint.ts, and mcp-registration.ts in
current-state voice; RESOLVER.md routes "wire this box's coding agents"
to bootstrap harness; setup skill points at it. Seven follow-ups filed in
TODOS.md (serve port record, http-transport scope asymmetry, unique token
names, codex hook lane, PGLite admin-lane minting, OpenClaw setup hook —
self-demoted: plugin installs run with lifecycle scripts disabled and the
manifest has no setup field — and federated-drift visibility). Doctor's
harness messages spell flags without leading dashes (the flag-registry
prose-bleed class; registry stays fresh). VERSION/package.json/CHANGELOG/
openclaw.plugin.json → 0.45.9.0 (0.45.8.0 is claimed by an open PR);
template stamp + runbook stamp refreshed; llms bundles rebuilt.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(doctor): categorize bootstrap_harness_health + de-flag harness message prose (#4043 triage)
The full-suite triage against a pristine-master baseline surfaced the two
in-branch failures: the doctor-categories drift guard (new check name not
in OPS_CHECK_NAMES) and the flag-registry freshness guard (doctor's harness
messages carried bare id/http flag tokens, which the generator harvests
into every importing command's allowlist — the known prose-bleed class;
messages now spell flags without leading dashes). Every other failing file
(18) fails identically on master with this environment — pre-existing,
not this wave's.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(hook): pin the harness-lane yield guard + honor the io.cwd seam (#4043 eng review E5)
The GBRAIN_HOOK_LANE=harness defer guard (workspace bootstrap installs win
over user-scope harness wiring — the C6 double-fire defense) was the one
new branch with no direct test. Two serial cases now pin it: lane +
bootstrap-v1 markers in the cwd → every event yields silently (exit 0, no
output, no heartbeat); lane without markers — including a harness-marker-
only settings file — runs normally and heartbeats. The guard now resolves
the cwd through the same io.cwd test seam the handlers use.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): harness convergence + rotation hardening — eng-review outside-voice X-batch (#4043)
Fifteen codex outside-voice findings, thirteen accepted and fixed, one
accepted as an advisory line, one kept as the settled PGLite deferral:
- X1: explicit --harness codex FORCES wiring (the TOML writer needs no
codex CLI — the exact no-CLI box the issue filed); detection heuristics
gate only the `all` default.
- X2: --source now reaches the mint as a scalar write-floor grant; it was
written to the receipt and hook env but never scoped the token.
- X3: re-runs converge — writeClaudeHooksAt strips our marker across ALL
events before wiring the requested subset (--no-capture now unwires
Stop/SessionEnd), and apply unwires prior-receipt targets the new plan
drops (changed --project sets no longer strand live wiring).
- X4: token.previous_ids is an array — a failed rotation accumulates every
unrevoked id and the next converge (or --remove) revokes them ALL; the
--token lane carries them too.
- X5: real rollback — the previous claude registration (url + bearer from
mcp get) is restored on add-failure or failed smoke, and the codex .bak
is restored on failed smoke, so "old clients keep working" is true in
the registration sense, not just the token sense.
- X6: the receipt guard + write-ahead write now precede the mint — a crash
or newer-format refusal can no longer strand an unrecorded live token.
- X7: consent copy tells the truth — supplied tokens are "written only
into the host registrations", and the reach paragraph matches the actual
harness/hook/capture selection.
- X8: a pre-existing permissions.allow entry is recorded as pre-existing
and never deleted by remove.
- X9: codex wiring prints the experimental_use_rmcp_client advisory.
- X10: an unknown-tool tool_error counts as verified (auth + dispatch
succeeded) — a --surface verbs serve is no longer declared broken by
smoke or --status.
- X11: user-scope writes run under a config-dir lock and fresh files are
created 0600.
- X12: --status is genuinely read-only (no home mkdir, no lock).
- X13: registrar mode (non-loopback --url + --token) wires MCP only —
hooks talk to the LOCAL brain and would split-brain the box; the http-
bearer warning is no longer discarded.
- X14: flag parsing fails closed (missing values, --url+--port,
--status+--remove all error instead of resolving by precedence).
12 new serial cases pin the batch; 463 wave tests green incl. the live e2e.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(harness): ship-review hardening — pre-landing review army + coverage/plan audits (#4043)
Review fixes (6 specialists + coverage + plan-completion audits at ship):
- Smoke-fail rollback symmetry: a FRESH claude registration is removed on a
failed smoke (previously only replacements were restored); an unrecoverable
replacement fails the target honestly instead of staying green.
- [X14] --project with a missing/flag-like value errors instead of silently
widening hook wiring to user scope; auth create --scopes/--takes-holders
missing values error instead of minting a grandfathered full-access token.
- normalizeTokenScopes fails CLOSED on representation drift: only never-written
NULL grandfathers; undecoded '{a,b}' array-literal strings parse; any other
non-null shape denies.
- set-takes-holders merge guards the left operand with jsonb_typeof so
historically damaged (scalar/array) permissions rows repair on edit instead
of compounding into a jsonb array; e2e updates pin the REAL auth.ts SQL
shape + the source_id-survives-merge regression.
- codexBlockOwnsName scopes the name check to INSIDE the managed block and
shares the writer's marker constants (parseCodexBlockBearer too).
- Refuse-rather-than-guess on unverifiable URLs: --remove and stale-target
cleanup skip claude registrations whose URL cannot be parsed.
- [X11] parity: codex config.toml writes/removes serialize under a lock on
the config's own dir; runUninstall takes the HOME lock around harness
removal (same key as runHarness).
- [D12] the harness-lane hook yield guard also honors the committed
.claude/settings.json carrier — checking only settings.local.json would
double-fire events owned by the committed carrier.
- token-mint uses isUndefinedColumnError (message-shaped variants included);
TOKEN_ID_RE shared with the auth revoke --id CLI gate.
- Stale 'Codex has no hook system' copy in the real-codex e2e + bootstrap
guide updated to the honest 'gbrain does not wire Codex hooks yet'.
- New tests: runUninstall harness-first composition (harness-only box +
abort-before-teardown), DATABASE_URL-gated mintLegacyToken Postgres parity,
renderTokenScopes, isServeOlderThanScopes matrix, codexBlockOwnsName,
fresh/unrecoverable smoke-fail rollback, committed-carrier yield.
- TODOS: smoke identity-verification hardening, lock.ts message polish,
auth-create/doctor dedupe follow-ups; docs: binary-downgrade scoping note.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(harness): adversarial-review hardening — codex + red-team convergence at ship (#4043)
Cross-model adversarial passes (Codex exec + red-team subagent) on top of the
review-army batch; three-reviewer convergence upgraded the loopback-impostor
class from TODO to fixed:
- CANARY before the smoke: a random same-format bearer must FAIL auth before
the real token is verified — an impostor squatting the loopback port cannot
distinguish the canary from the real token, so it is caught whichever way
it answers; on ANY failed smoke the fresh mint is revoked immediately
(nothing live is ever left with an unverified endpoint).
- Pre-approval integrity: the permissions.allow entry is gated on the MCP
registration actually landing (a failed/ownership-refused registration must
not bless a foreign server) and is rolled back with a failed smoke.
- --status recovers a bearer ONLY from a registration whose URL matches the
receipt ([C8] everywhere) — never transmits another install's credential.
- Half-removed receipts (zero targets, minted token awaiting deferred revoke)
FAIL doctor + exit 1 from --status instead of reading vacuously green;
--status also exits 1 on failed/pending targets and unconverged rotations.
- [X3] stale-target cleanup deferred until AFTER the smoke passes (mint-first
applies to removals too: a mint/lock failure no longer strands a box that
had working wiring); stale-remove exit codes checked, not assumed.
- oauth-provider's pre-v38 fallback SELECT keeps the ORIGINAL-schema scopes
column — a failed permissions projection no longer grandfathers scoped
tokens to full admin.
- Hook yield guard PARSES settings and requires a live bootstrap-v1 entry for
THIS event (both carriers) — a repo committing marker-lookalike strings can
no longer disable the machine-wide capture lane, and unwired events run.
- permissions writers fail closed on policy shapes they don't understand;
auth list renders through the SAME normalizer the verify path uses;
isServeOlderThanScopes pins the first scope-aware release (no cry-wolf on
the next CLI bump); harness receipts shape-validate before consumers
dereference; rollback bearers are validated before re-registration.
- [X11] lock parity on every remaining path: removeHarness host-removals,
stale cleanup, codex rollback; runUninstall holds the HOME lock across the
whole teardown (no mint window between harness removal and rm of
<home>/bootstrap); --project hook writes carry the [D12] committed-carrier
events; cross-home user-scope-vs-project double-fire refused where knowable.
- applyHarness --json emits ONLY the JSON document on stdout (prose → stderr).
- Registry prose-bleed swept (a comment's literal typo'd flag would have made
the typo VALID); TODOS updated: canary+fresh-revoke landed, identity
comparison + orphan-mint reconciliation filed as residuals.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(release): sync harness docs with the shipped adversarial-review behavior (v0.45.14.0)
/document-release drift pass against the final #4043 diff:
- KEY_FILES.md: drop the stale duplicate src/commands/hook.ts entry left by
the mid-wave append; the surviving entry now describes the per-event yield
guard that parses BOTH workspace settings carriers. harness.ts entry gains
the canary-gated smoke + symmetric rollback (fresh mint revoked on any
failed smoke), the registration-gated pre-approval, post-smoke stale
cleanup, the --status exit contract (incl. half-removed receipts), the
URL-matched bearer recovery, the SCOPES_MIN_SERVE_VERSION pin, apply
--json stdout-only discipline, and codex config-dir lock parity. hooks.ts
entry notes the permissions writers fail closed on policy shapes they
don't understand.
- docs/guides/bootstrap.md: the mint-first bullet states the failed-smoke
rollback + fresh-mint retirement guarantee; the --status bullet spells out
the cron exit contract and the install-level --json contract.
- README.md: the bootstrap guide link mentions local harness mode.
- CHANGELOG.md: restore the blank line before the 0.45.12.0 header
(formatting only; no entry content touched).
- llms bundles regenerated (bun run build:llms; freshness test green).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(release): cross-model doc-review fixes — honest scoping + two filed residuals (v0.45.14.0)
Independent doc-review pass (Claude subagent; codex session init failed on an
unrelated local MCP timeout) against the shipped #4043 diff. Verified 10
findings against the code; applied 8, filed 2:
- bootstrap.md + KEY_FILES.md: scope the --status bearer-recovery URL-match
claim to the Claude Code lane (the codex managed block is read at the
receipt-recorded path; its url key is not yet compared — filed in TODOS);
add the no-install exit-0/plain vs exit-2/--json distinction and the
unreachable-serve / failed-verify exit-1 trips; document the wider flag
surface + registrar mode (--url/--port/--force/--name/--no-hooks); state
that a supplied --token is never revoked by --remove or rotation.
- KEY_FILES.md: permissions-writer clause corrected — the add path fails
closed on alien policy shapes, removal leaves what it can't read untouched;
token-mint.ts entry gains the required takesHolders option and TOKEN_ID_RE.
- DEPLOY.md: revoke-by-name hits every same-name token; auth revoke --id +
the id/scopes columns in auth list are the precise path.
- RESOLVER.md: restore an "install gbrain into this agent workspace" trigger.
- CHANGELOG (factual drift only): damaged permissions rows are reset to a
clean object, not recovered; scope-display claim narrowed to the verify +
CLI display paths.
- TODOS.md: filed the codex-lane [C8] URL-match residual and the admin
dashboard scope-display normalizer residual.
- llms bundles regenerated; guards green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(harness): close the two doc-review residuals — codex-lane bearer ownership + dashboard scope honesty (#4043)
- parseCodexBlockBearer takes an expectedUrl: --status only recovers the
managed block's bearer when the block's url matches the receipt ([C8]
parity with the claude lane — two GBRAIN_HOMEs sharing the one user-global
codex config could otherwise hand install A install B's credential).
- The admin dashboard renders legacy-token scopes through the SAME
normalizeTokenScopes the verify path uses (NULL = grandfathered full
access; damaged/deny rows show what the serve actually enforces) instead
of raw array_to_string.
- Both TODOS residual entries removed (fixed, not filed).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(skills): regenerate skills.lock.json — RESOLVER.md + setup/SKILL.md edits from the #4043 wave
The wave's skill-routing updates (harness routing row in RESOLVER.md, the
harness pointer in setup/SKILL.md) landed without the manifest-lock chaser;
CI's check:skills-manifest caught the stale hashes. Full verify suite green
locally (39/39).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(writer): surface writer_lint findings in the put_page payload (T11/WP6)
put_page's writer_lint block grows from counts-only to an actionable
summary: errors-first top_findings (cap 5, per-finding fix hint, message
truncation), details_truncated, and a by_validator histogram. Contract per
amendment 28: lint ran with zero findings keeps the key present (zeroed);
a lint crash returns {status: 'lint_error'}, distinguishable from lint-off
(key absent).
validators/index.ts exports BUILTIN_VALIDATORS as the single registry
(ENG-12): registerBuiltinValidators, runPostWriteLint, and the new
FIX_HINTS map all derive from it. The payload plumbing lives in
post-write.ts (summarizeWriterLint + writerLintForPutPage) so every
outcome mapping is unit-testable without mocking the op handler.
New test pins the previously-unpinned payload shapes end-to-end on PGLite
plus FIX_HINTS completeness against the registry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP1 honest catalog — gate/scope/bound-aware tools/list + localOnly transport backstop
The advertised list is now exactly what the calling token can use: tools/list
filters per request by token scope, the bound-client fence predicate (shared
with dispatch via opAllowedForBoundClient so list and deny cannot drift), and
the publish gates (hidden while off; read failure hides the gated ops, never
fails the list). localOnly ops are confined to the stdio local pipe by a new
dispatch-layer backstop keyed on transport locality; the legacy bearer
transport also stops listing them. Denials carry the machine-readable
config_key detail grammar.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP2 _meta.retrieval channel + model-visible empty-result block + concept hint (E1)
search/query publish their already-computed retrieval meta (counts, vector
arm, cache, budget, degradation stages) through a per-key _meta side channel;
empty results additionally carry a second text content block so the model
sees the diagnosis in every harness while deployed thin-clients keep parsing
content[0] unchanged. The concept-shaped hint (TODOS P2) rides the same
channel on the search op. Producer isolation: a metaHook failure can no
longer drop handler-emitted keys. Convention doc: docs/protocol/MCP_META_CHANNELS.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(verbs): synthesize compose status + extractive fallback (WP2/T5, E2, ENG-10/19)
Stop dropping runThink's failure signal at the synthesize verb. runThink now
stamps a typed synthesis_status (ok | empty_answer | not_json | no_llm |
model_unusable | llm_error) and catches client.create() throws (429/timeout/
5xx/network) into llm_error instead of crashing the call — explicit-model
AIConfigError (#1698), BudgetExhausted, and AbortError stay hard throws.
Verb precedence (registry refinement): compose failure + non-empty gather ->
extractive fallback (synthesis_status: extractive_fallback; answer digests +
cites ONLY gathered pages via composeExtractiveFallback — empty gather NEVER
produces an answer, ENG-19); compose failure + empty gather -> typed
verbError('unavailable', 'retrieved 0 pages; compose failed: <code>'); no-LLM
stays the [c10] unavailable error regardless of gather. Every success response
now carries additive synthesis_status / pages_gathered / takes_gathered /
warnings; RESPONSE_SCHEMAS extended additively (protocol_version stays 1);
MEMORY_VERBS_v1.md gains the compose-status subsection (+ llms-full rebuild).
The think op inherits the new ThinkResult fields via its existing spread.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): T10 minions visibility — snapshot v2, submit-time queue probes, get_agent_job
WP5 of the MCP truthful-surface wave (amendments 16, 24-27, ENG-13/16/18/20):
- get_status_snapshot schema_version 1->2: additive queue (status counts +
per-queue depth + oldest_waiting_age_seconds, generalizing the doctor
oldest-age SQL past embed-backfill) and workers (supervisor liveness via
pidfile + DB-lock ladder, last_completed_at) sections, each fail-soft to
{error: 'unavailable'} without failing the snapshot. Thin-client
`gbrain status` renders the remote payload for workers/queue and degrades
gracefully against old (v1) servers.
- submit_job/submit_agent attach queue_state from a time-bounded (~1.5s),
fail-open probe (probeQueueState in supervisor.ts, reusing
queryWedgeSignals + supervisor DB-lock liveness + worker registry + the
autopilot pause marker). Warnings fire on dead lane, over-threshold depth
(GBRAIN_QUEUE_WAITING_THRESHOLD), and migration pause; a probe failure
degrades to {probe_failed: true} and never errors a paid submission.
- NEW get_agent_job op (scope 'agent', now a first-class Operation scope
union member; the `'agent' as any` cast on submit_agent is gone):
clientId required on every transport, fail-closed JSONB ownership WHERE,
uniform not_found for foreign/missing ids (ErrorCode comment widened),
trimmed view + claim-order queue_position for waiting jobs.
- computeQueueHealthCheck now returns structured details
{depth, oldest_age_seconds, worker_alive}; messages unchanged.
No migration DDL in this lane: the wedge index (queue, status, updated_at)
lands with the wave's single migration in another lane; new queries note
the index prefix they will ride.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(search): fail-loud retrieval core — degraded[] stamp, allSettled salvage, minKeep budget, short-TTL degraded cache (WP2/T3)
Lane B of the MCP consumer-feedback wave (amendments 5-8, D6, D14.2,
ENG-2/5/6/7/15, FOV-2):
- types.ts: HybridSearchMeta gains degraded[] (CLOSED exported stage
vocabulary DEGRADED_STAGES + enumerated DEGRADED_REASONS — raw
exception text never rides the wire, D6) and retrieved_count
(pre-budget hit count); token_budget gains truncated.
- hybrid.ts: Promise.all → Promise.allSettled on BOTH the embed fan-out
and the searchVector fan-out (ENG-15). Salvage semantics: variant
embed fails → original survives (expansion_partial); ORIGINAL fails
with variants ok → salvage variant lists, skip cosine re-score
(expansion_partial + rescore_skipped); all fail → keyword-only
(embed_unavailable/embed_timeout). Keyword-only-config and image/
unified branches stamp their degradation too (no silent bypass).
GBRAIN_SEARCH_SALVAGE=off (env-only, ENG-7) restores all-or-nothing
embeds + the strict budget wrapper.
- token-budget.ts: packToBudget UNCHANGED (frozen verb consumers);
enforceTokenBudget gains the minKeep:1 failsafe — first-result-
exceeds-budget keeps ONE result with chunk_text truncated on a COPY
(never mutating the shared SearchResult); sub-title-cost budgets keep
a title-only copy; dropped=N-1 + truncated reported (ENG-2/FOV-2).
- hybridSearchCached: both meta rebuilds become spread-carry (ENG-5) so
no inner key can silently drop again; hit path stamps cache 'hit'
(hit-with-offset included); rows lacking the degradation stamp emit
degraded:[{stage:'cache_prestamp'}] instead of claiming clean;
degraded-but-embeddable result sets cache with a short TTL (60s,
D14.2/ENG-6 — total embed outage stays uncacheable by construction).
- mode.ts: KNOBS_HASH_VERSION 15→16 (degradation-stamp epoch).
- telemetry.ts: empty_result rollup keyed by cause (vector_disabled /
budget_dropped_all / keyword_zero) riding reserved
(date,'empty_result',cause) rows — zero new DDL; surfaced via
readSearchStats.empty_results and diverted from call/intent/mode
aggregates.
- tests: token-budget minKeep flip + direct packToBudget strict-edge
pins (context_pack-shaped fixture); ENG-15 three-branch salvage suite
+ vector-arm + kill-switch; meta-key-parity (bare ⊆ cached, hit and
miss); cache_prestamp fixture; short-TTL + null-embedding-skip;
empty-cause telemetry suite; KNOBS_HASH_VERSION pins updated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP3 discovery — complete param schemas, strict/warn arg validation, one schema mapper
T6 — descriptors + strict/warn validation:
- Backfill descriptions on all 36 previously-undescribed params across 24
non-localOnly ops (search.query / query.query / resolve_slugs.partial
first), house style with inline examples where a name is guessably wrong.
- CI walker in test/mcp-tool-defs.test.ts fails on any non-localOnly op
param lacking a non-empty description (localOnly exempt).
- Extract normalizeOptionalParams + validateParams into
src/mcp/validate-params.ts (call order normalize→validate preserved, doc
comments verbatim; dispatch re-exports; server.ts second caller updated).
- New config key mcp.strict_params ('warn' default | 'reject'), resolved
dual-plane (DB > file > warn) once per dispatch. Unknown top-level keys
(allowlist: _meta, dry_run) warn-collect into _meta.warnings
[{code:'unknown_param', param, suggestion?}] + a model-visible second
content block in warn mode; reject mode returns invalid_params with the
did-you-mean in `suggestion` only — the raw unknown key never reaches
`message`, the one field persisted to mcp_request_log.error_message.
- Enum membership violations return invalid_params in BOTH modes, naming
the allowed values (never echoing the submitted value).
- unknown_tool did-you-mean via one shared envelope builder for all three
deny paths (hidden/nonexistent/localOnly-over-HTTP); candidates are the
caller-visible surface minus localOnly minus publish-gated ops, so hidden
names never leak and hidden-vs-nonexistent stays byte-identical (pinned).
- query op's plain "requires either query or image" throw is now
OperationError('invalid_params', ...).
- serve-http logs 'success_with_warnings' when a result carries non-empty
_meta.warnings (warn contents never logged) — amendment 13 observability.
T7 — one schema mapper:
- buildToolDefs(ops, {strictParams}): strict emission closes each schema
with additionalProperties:false and declares the _meta/dry_run
passthrough keys (D14.1, no clobber of real dry_run params); default
emission stays byte-identical (both states pinned).
- serve-http ListTools unified onto buildToolDefs with a per-request
dual-plane strict_params read (restart-free flip); stdio + legacy bearer
transports resolve once at startup from the file plane (flip needs a
restart there — deliberate, per plan).
- gbrain --tools-json rebuilt on buildToolDefs additively: legacy
name/description/parameters keys preserved verbatim, full JSON Schema
added under a new per-tool `schema` key.
Rider: test/file-upload-engine-context.test.ts now dispatches localOnly
file ops with transport:'stdio' — it pins engine ownership, and the WP1/D7
localOnly backstop (earlier commit on this branch) correctly denies its
old transport-less dispatch.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP4 starter surface, per-client ceiling-bounded unlock, request_tools
T8 — per-client surface persistence:
- Migration v127: oauth_clients.surface + surface_set_by (open value
space, amendment 18) + the ENG-10 wedge index
idx_minion_jobs_queue_status_updated (queue, status, updated_at);
mirrored in schema.sql / schema-embedded.ts / pglite-schema.ts and the
forward-reference bootstrap probe sets of BOTH engines (v121 mask
class), pinned by test/schema-bootstrap-coverage.test.ts.
- verifyAccessToken gains a NEW top degrade-ladder rung (drop the
surface columns first, keep the v85 fence column); missingOAuthColumn
probes BOTH new names (ENG-9). AuthInfo threads surface + surfaceSetBy.
- McpSurface widens to 'verbs' | 'starter' | 'full'. STARTER_OPS is
composed programmatically (spread of VERB_NAMES — seven verbs, ENG-1 —
+ the FOV-6b fallback daily set from BRAIN_TOOL_ALLOWLIST + the FOV-4
agent lane + whoami + request_tools) with a provenance note; the
production-histogram derivation corrects it later. Monotonicity
verbs ⊆ starter ⊆ full pinned; 'verbs' semantics untouched.
- D2 CEILING: serve-http resolves min(server --surface ceiling, client
row surface ?? mcp.default_surface_dcr ?? ceiling) PER REQUEST
(amendment 20); unknown row values ignored with warn-once per client.
GBRAIN_MCP_FORCE_SURFACE kill switch min()s in on top, NARROW-ONLY
(FOV-6a), pinned next to the D2 ceiling test.
- gbrain auth rescope-client --surface verbs|starter|full|clear
(surface_set_by='operator'; 'clear' nulls both) + the admin endpoint
mirror; EVERY surface mutation (CLI, admin, request_tools persist)
writes an mcp_request_log operation='surface_change' audit row with a
raw-object params payload via executeRawJsonb (ENG-8, amendment 32).
T9 — request_tools meta-op (contract-first):
- scope 'read' + mutating + agentCallable (FOV-4 scope carve-out in
serve-http list + call); listed on starter+full only (D4). No args →
area-grouped catalog of the ops VISIBLE to the caller (scope, fence,
localOnly-on-http, publish gates, ceiling — hidden names never leak);
{tools} → read-only descriptors for the visible subset (D5);
{surface} → self-persist within the ceiling, denied on operator lock
(detail 'locked_by=operator') or above the ceiling (detail
'ceiling=<surface>'), ~5/hour/client rate limit (D14.5),
pre-migration → {persisted:false, reason:'migration pending'}.
- D9 meta-op carve-out (BOUND_CLIENT_META_OPS) in opAllowedForBoundClient
so slug-bound clients keep discovery; persist self-enforces its guards.
- Operation.area populated for every non-localOnly op (names
non-contractual, amendment 22); tool-defs CI walker extended.
Integrator fixes (branch verify gate was red at HEAD): withEnv() for the
lane-B token-budget env tests, lane-F writer-lint comment reworded off
the R2 lint token, publish-gates.ts added to the operations-filter-bypass
allowlist with rationale.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(cli): T15 — empty results name their cause on both CLI surfaces
formatResult's empty branch renders the retrieval degradation (stages +
pre-trim count) captured from either path: the local engine via the
emitResponseMeta twin, or the thin-client envelope via _meta.retrieval.
unpackToolResult stays content[0]-only by contract (D8 skew guard, now
pinned) and extractResponseMeta lifts the envelope meta without erroring
on old servers.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(cli): fix generic on unpackToolResult pin (typecheck)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): T12 expansions — usage reader, advisor starter-fit, usage CLI, TOOL_CATALOG generator
The four T12 expansions over the truthful-surface wave's machinery
(amendments 22-23, 29-30, D12):
- src/core/mcp-usage.ts: the ONE shared reader over mcp_request_log.
Encodes the row-hygiene rules once (JSON-RPC method rows + ENG-8
surface_change audit rows dropped; legacy 'tools/call:<name>' prefix
stripped), windows on created_at (rides idx_mcp_log_time_agent), and
classifies automation-shaped clients behaviorally (>90% context_pack/
delta boundary calls — D12; the hook lane is stdio and never logs, so
there is no name convention to key on).
- E3: advisor collector `mcp-client-fit` — per-client starter fit
(full-surface client whose 30d distinct-op set fits STARTER_OPS gets
the exact `gbrain auth rescope-client <id> --surface starter` fix) +
set-level drift curation (top-used ops missing from STARTER_OPS;
starter members unused 90d). Remote output redacts client identifiers
to aggregate counts (amendment 29); dismiss/snooze rides the nag-state
engine with its own state file; >=10-call alert threshold.
- E4: `gbrain auth clients [--usage] [--days N] [--json]` — per-client
op-call counts, top ops, last-seen, joined with scopes + surface +
surface_set_by from oauth_clients; legacy bearer tokens listed
separately (no per-client surface row to rescope).
- scripts/derive-starter-ops.ts (amendment 23 + D12): proposes the
STARTER_OPS daily slice from production usage — per-client DISTINCT-op
sets ranked by client count, automation clients excluded, provenance
header, BRAIN_TOOL_ALLOWLIST cross-check. Prints only; never edits.
- E6: generated docs/TOOL_CATALOG.md (config-independent, deterministic;
one section per area; per-op scope/starter/gate columns; non-localOnly
only) via src/mcp/tool-catalog.ts + scripts/generate-tool-catalog.ts,
freshness-guarded by scripts/check-tool-catalog-fresh.sh wired into
`bun run verify` (the METRIC_GLOSSARY pattern).
Tests: test/mcp-usage.test.ts (hygiene incl. legacy prefix + exclusions,
windowing, automation classification), test/advisor-mcp-client-fit.test.ts
(local vs remote redaction, exclusions, drift, snooze lifecycle),
test/tool-catalog.test.ts (determinism, coverage, freshness + CI wiring).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(ops): T14 — surface runbook, honest-catalog metric, TODOS filings, docs pass + llms regen
Observability + operator tail of the truthful-surface wave (amendments
33-36, D10, D14.3, ENG-6/7/8/13):
- docs/operations/mcp-surface-runbook.md: the four operator moves with
exact commands + expected outcomes (publish-gate flip, surface rescope
with audit-row verification, strict-params warn→reject flip with the
named evidence criterion + schema-emission note, STARTER_OPS re-derive),
the incident levers (GBRAIN_MCP_FORCE_SURFACE narrow-only clamp,
GBRAIN_SEARCH_SALVAGE=off), the ENG-6 total-embed-outage expectations
(query cache uncacheable by construction; keyword-only degraded
results), the honest-catalog metric SQL, and a first-5-minutes
post-deploy checklist with a ~/.gbrain/smoke-tests.d drop-in snippet.
- Honest-catalog metric (amendment 33): op-level call-time denials the
tools/list filter should have prevented now log
status='denied_after_list' instead of 'error' — the inline scope deny
in serve-http, the publish-gate backstop (detail 'config_key=...'),
and the bound-client fence OP-level deny (new detail 'fence=op',
assign-after per ENG-11). Argument-level slug-fence denials carry no
marker and stay 'error' (D10 carve-out). Classifier
`isListLevelDenialEnvelope` exported from src/mcp/dispatch.ts; pinned
by test/denied-after-list.test.ts through real dispatch envelopes.
- Amendment 23 stopgap: the tools/list mcp_request_log row now records
the listed size as params.tool_count (raw object via executeRawJsonb).
- TODOS.md: eight filings — strict_params reject-flip (P1, named
zero-success_with_warnings/30d criterion + the pinned default=warn
test), mcp_request_log retention/pruning (now carries surface_change
audit + denied_after_list rows), describe_tools (OQ4), page_lint (OQ5),
named client tiers, per-client token budgets, full list-size telemetry,
get_job not_found alignment (ENG-13).
- Docs pass (current-state only): MEMORY_VERBS_v1.md surface modes gain
'starter' + the D2 ceiling semantics; thin-client.md documents the
full-surface posture (bootstrap pin; stdio has no client row);
KEY_FILES.md entries updated (surface.ts, dispatch.ts, tool-defs.ts,
serve-http.ts, advisor cluster) + new entries (validate-params.ts,
publish-gates.ts, tool-catalog.ts, surface-audit.ts, mcp-usage.ts,
MCP_META_CHANNELS.md). llms bundles regenerated (bun run build:llms).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): E5 truthful-catalog invariant — listed means callable, hidden means unknown
The wave's final guard (T13/E5, D10 carve-out, ENG-21 recipe, FOV-4/6c,
amendment 31): for each token class, tools/list then probe every listed
tool and assert no probe returns a LIST-LEVEL denial (publish-gate
config_key=..., bound-fence fence=op, scope insufficient_scope, or an
unknown envelope for an advertised name); invalid_params is acceptable.
Inversely, surface-hidden and localOnly ops return the no-leak
unknown-tool envelope, gate-hidden ops hit the fail-closed config_key
backstop, and fence-hidden ops hit fence=op.
Placement: test/truthful-catalog.e2e-lite.test.ts in the UNIT tree (not
test/e2e/, which runs only under run-e2e.sh on Postgres hosts) — the file
needs no DATABASE_URL, so the invariant runs in every CI unit pass.
Recipe (ENG-21): ONE PGLite engine + ONE real legacy-bearer HTTP server
reused across cells; the OAuth serve-http semantics run in-process through
the exact seams serve-http composes (filterOpsForSurface, hasScope +
agentCallable carve-out, opAllowedForBoundClient, disabledOpsForPublishGates,
dispatchToolCall). mcp.strict_params pinned 'reject' on the DB plane so no
garbage-arg probe can execute a write handler; required params probed with
wrong-typed values; request_tools probed with {surface:'garbage'} (never a
persist); exactly ONE warn-mode case probing a READ op (FOV-6c). Matrix:
scopes {read,write,admin,agent} x surfaces {verbs,starter,full} x gates
{on,off} x bound/unbound — full probe sweep on 3 extreme cells
(admin+full+gates-on, read+starter+gates-off, bound+write+full), list-set
equality + denial-class representative probes on the remaining 48 cells,
the FOV-4 agent-only row (exactly submit_agent/get_agent_job/request_tools),
verbs ⊆ starter ⊆ full monotonicity per token class, the amendment-20
persist→re-list flip (request_tools {surface} persist reflected by the next
per-request resolution, no restart), and a loud <3-minute wall-clock budget.
The full OAuth-server sweep (real HTTP + real tokens) remains the
Postgres-host assertion in test/e2e/serve-http-oauth.test.ts.
Rider fix the guard forced: the legacy bearer transport
(src/mcp/http-transport.ts) listed the four publish-gated ops
unconditionally (tool list built once at startup, no gate filter), so with
gates off — the default — they were listed-but-denied with the config_key
list-level denial: the exact catalog lie this wave exists to end. Its
tools/list now subtracts disabledOpsForPublishGates per request (dual-plane
read, restart-free flip, fail-closed on read failure), matching the OAuth
transport; the in-handler gates stay as the call-time backstop. Verified by
mutation: reverting the fix fails 3 of the new legacy-transport tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(cli): regenerate flag registry for the wave's new auth flags
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes
Ten review findings, all two-way doors:
1. health-indicators error rate no longer counts success_with_warnings /
surface_change rows as errors (denied_after_list stays counted).
2. visibleOpsForCaller treats the trusted local CLI (remote === false) like
stdio: localOnly + publish-gated ops stay visible to the operator who can
actually call them.
3. request_tools dry-run previews no longer consume the persist rate-limit
budget (denials still exercised; limiter meters actual writes only).
4. normalizeLoggedOperation re-runs the NON_OP_LOG_ROWS hygiene check on
legacy-prefix-stripped names ('tools/call:tools/list' no longer counts
as usage).
5. LLM_CALL_FAILED warnings carry a closed-vocabulary class (timeout |
rate_limited | network | provider_error) instead of raw provider text;
the raw message goes to stderr. MEMORY_VERBS doc + schema updated.
6. Publish-gate + strict-params config reads are issued concurrently
(tools/list RTT depth 3 -> 1).
7. resolveEffectiveSurface skips the default-surface config read when the
clamped ceiling is already 'verbs' (min() cannot go lower).
8. buildQueueDepths / doctor waitingByQueue comments now state the truth:
the wedge index gives no prefix access for a status-only WHERE; these
full-scan today.
9. Verb-count comments updated to the seven frozen verbs + starter tier.
10. ALWAYS_INCLUDED_STARTER_OPS exported from surface.ts and consumed by the
advisor starter-fit collector (which omitted the agent lane, producing a
perpetual bogus unused-starter finding) and derive-starter-ops.
Also extracts requestLogStatusForResult (src/mcp/dispatch.ts) as the one
request-log status decision serve-http persists — behavior identical, unit
pins land in the follow-up test commit. Behavior pins for fixes 2-5 and 10
ride here so every commit stays green (test/request-tools, test/mcp-usage,
test/think-extractive.serial, test/advisor-mcp-client-fit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: regression tests for request-log statuses and query invalid_params
Coverage-audit gaps + test hygiene from the pre-landing review:
- requestLogStatusForResult unit pins (all four statuses: success,
success_with_warnings, denied_after_list, error) in
test/denied-after-list.test.ts; row-level twins live in the Postgres-host
e2e (extension filed in TODOS.md).
- query op with neither `query` nor `image` returns the typed invalid_params
envelope, never internal_error (engine stub — the throw precedes any
search).
- writeSurfaceChangeAudit fail-open contract: a throwing engine resolves
false and never throws; the happy path binds the params object raw
(jsonb discipline).
- parseAuthClientsArgs: defaults, --days bounds (incl. >3650 rejection),
--usage/--json flags, unknown-flag rejection.
- E5 truthful-catalog wall-clock budget is enforced only under
GBRAIN_ENFORCE_E5_BUDGET=1 (warn otherwise — machine-load-dependent);
T0 moves from module load into beforeAll.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: file review-deferred TODOs
Six deferrals from the /ship pre-landing review, grouped by component under
a new truthful-surface-wave section: default-surface memoization on the
tools/call hot path (P2), Postgres-host e2e row-level request-log assertions
(P2), surfaceProjectionDegraded marker for drift-shaped brains (P3), partial
completed-jobs index if snapshot polling gets hot (P3), the master-owned
extract-atoms shard flake (P1, with failure signature), and the eight-item
hygiene dedupe batch as one P3 entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial review fixes — fail-closed surface resolution, usage hygiene, wire-safe warnings
Twelve fixes from the cross-model (Codex + Claude) adversarial ship review:
- resolveEffectiveSurface holds the last successfully read default surface
per process, so a transient config outage can't silently widen a
NULL-surface client to the ceiling; stale never-throws comment rewritten.
- readClientOpUsage counts only success/success_with_warnings rows — denial
and error traffic can no longer "use" its way into starter derivation or
advisor fit findings.
- think/index.ts pushes closed warning codes (QUESTION_EMBED_FAILED /
CALIBRATION_FETCH_FAILED / TRAJECTORY_INJECTION_FAILED) on the wire; raw
exception text goes to stderr only (D6).
- enforceTokenBudget's minKeep failsafe slices the title too, so used <=
budget holds unconditionally; the failsafe now stamps a distinct
budget_truncated stage (additive vocab) while budget_dropped_all is
reserved for genuinely-empty strict returns.
- advisor drift arm excludes localOnly ops from starter recommendations
(mirrors derive-starter-ops).
- legacy bearer transport routes tools/call statuses through
requestLogStatusForResult — denied_after_list / success_with_warnings
now feed the amendment-33 metric on both HTTP transports.
- request_tools rejects {surface, tools} together as invalid_params; a
race-lost persist (0-row UPDATE under a concurrent operator pin) refunds
its rate-limit token (new RateLimiter.refund, capped at limit).
- health-indicators error rate: surface_change is an OPERATION value, not a
status — audit rows now excluded from numerator AND denominator via the
operation column.
- expansion_failed carries reason 'timeout' when the expander timed out.
- resolveStrictParamsMode holds the last-known-good DB mode so a transient
config outage on a reject-mode server can't re-open the warn grace period
(+ reset seam for tests).
- get_agent_job caps error_text at 2000 chars (unbounded worker field).
Regression tests: usage status filter, denied_after_list on the legacy
transport (DB-plane-pinned gate), strict-mode last-known-good, both-params
reject, limiter refund semantics, title-slice used<=budget pin.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: file adversarial-review TODOs
Four review-deferred items from the ship-stage adversarial review: atomic
old-surface capture for the request_tools audit row (P2), persist rate-limit
durability across restarts/processes (P3), cancellation for timed-out
submit-time queue probes (P3), and a schema_version union doc for the
status snapshot JSON consumers (P3).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.12.0)
Truthful Surface wave — MCP consumer-feedback fixes. Version train:
VERSION + package.json + CHANGELOG + openclaw.plugin.json +
BOOTSTRAP_FOR_AGENTS.md stamp + regenerated bootstrap templates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: post-ship documentation sync for v0.45.12.0
Catch the drift the pre-landing (a8f502857) and adversarial (28bac59bc)
fix commits introduced after the wave's T14 docs pass:
- KEY_FILES.md: requestLogStatusForResult (both HTTP transports),
ALWAYS_INCLUDED_STARTER_OPS (surface + advisor + derive-starter-ops),
resolveEffectiveSurface / resolveStrictParamsMode last-known-good
fail-closed behavior, RateLimiter.refund, usage success-only status
filter + prefix-strip hygiene re-run, advisor drift-arm localOnly
exclusion, health-indicators error-rate audit-row exclusion.
- mcp-surface-runbook.md: --usage counts successful calls only;
request_tools persist rate-limit/dry-run semantics; strict-params
reject posture survives a transient config outage.
- INSTALL.md, mcp/DEPLOY.md, mcp/CLAUDE_CODE.md,
tutorials/connect-coding-agent.md: the verbs surface is seven verbs
(context_pack + delta), matching the code snippets in the same files;
surface enumerations now include starter.
- llms.txt / llms-full.txt regenerated (build:llms chaser).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: doc-review fixes — honest starter count/provenance, scoped _meta claim, DCR-default runbook move
Four gaps from the cross-model documentation review:
- Starter surface is ~26 ops (STARTER_OPS.size), not ~20 — harmonized
across CHANGELOG, MEMORY_VERBS_v1, KEY_FILES, INSTALL, DEPLOY,
CLAUDE_CODE, connect-coding-agent (the generated TOOL_CATALOG already
said ~26).
- CHANGELOG no longer claims the v1 starter set was usage-derived: it is
the reviewed brain-tool slice + agent lane, re-derivable via
scripts/derive-starter-ops.ts (matches the FOV-6b provenance comment).
- "every MCP response carries _meta.retrieval" scoped to query/search
(the only producers of the retrieval key).
- mcp-surface-runbook gains the mcp.default_surface_dcr operator move
(default for NULL-surface clients, ceiling-bounded, per-request).
- llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ci): add --timeout to the derive-starter-ops printed hint (bun-test guard)
The check-bun-test-timeout guard greps scripts/ for bare `bun test`
invocations and matched the console.log hint this wave's derivation script
prints. CI (GNU grep) enforces the \b word boundary the local BSD grep
silently drops, so the gate only fired on the runner. The hint now models
the convention it exists to teach.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(search): disclose telemetry coverage gap in search stats/tune
`gbrain search stats` / `gbrain search tune` read from an in-memory,
best-effort telemetry buffer that flushes on a 60s timer or 100-call
threshold (by design — see the module header in
src/core/search/telemetry.ts). Short-lived CLI invocations typically
exit before either trigger fires, so their search calls are silently
dropped; only long-lived processes (serve, MCP stdio/HTTP, jobs work)
are reliably counted. `search stats`/`search tune` printed totals and
"data-driven recommendations" with no hint of this scope, so a CLI-first
user could be tuned against a sample that never included their own
searches.
This is a display-only accuracy fix: no telemetry/flush behavior
changes. Adds a `coverage` disclosure (JSON, additive) and a one-line
human-readable caveat to both subcommands, backed by a single exported
note in telemetry.ts so the two callers stay in sync.
* fix(search): correct coverage wording after review + document KEY_FILES
Codex review of the coverage-disclosure commit found real issues, not
just nits:
- "long-lived processes only" overclaimed — a CLI run that itself
crosses the 100-call flush threshold before exiting IS captured.
Reworded to "coverage favors long-lived processes ... a lone
short-lived CLI search call is typically not recorded."
- The pre-existing "Run a few `gbrain query` calls and re-check"
advice on a 0-count `search stats`/`search tune` now directly
contradicts the new disclosure (a single CLI call is exactly what
tends not to survive the flush). Replaced with guidance that matches
the caveat (use `gbrain serve` / an MCP session for reliable counts).
- The human-readable caveats were hand-paraphrased at each call site,
which is how the above wording drifted in the first place. Added
`TELEMETRY_COVERAGE_CAVEAT` (short form, telemetry.ts) as the single
literal string every human-output call site now reuses.
- Test assertions were too loose to catch inaccurate wording (only
checked for the word "coverage" / a non-empty reason string).
Strengthened to pin the exact caveat string / key phrases.
- Added the KEY_FILES.md entry for this behavior per repo convention,
regenerated llms.txt/llms-full.txt (no diff — content already
matched).
* fix(search): address round-2 Codex nits (honest wording + wording pins)
- Soften "captures counts reliably over time" (best-effort telemetry can
still silently drop a flush) to "is more likely to record counts over
time (telemetry stays best-effort either way)".
- Add wording-accuracy pin tests that hardcode the expected substance
independently of the TELEMETRY_COVERAGE_NOTE/CAVEAT imports — importing
the same constant into both production code and its own test assertion
cannot catch an inaccurate edit to that constant (exactly how the
round-1 "long-lived processes only" / missing "jobs work" bug slipped
through). New tests assert gbrain serve / MCP / jobs work / short-lived
CLI / the typically-not-never hedge directly, for both the --json
reason string and the human caveat.
* chore(guards): allow the public Hermes platform name in tests
The banned entry targeted conflating the public NousResearch agent with
private deployment names. gbrain now documents and tests against the
public platform (README hero, claw-test runner, install door e2e), so
the public name is legal in tests; private fork names remain banned.
Drops the three now-inert allowlist entries.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(claw-test): hermes runner, live staging + success oracles, friction diff
HermesRunner (hermes -z one-shot, HERMES_BIN > which hermes, allowlist
env with HERMES_HOME + OPENROUTER_API_KEY delta). Live mode now stages
the scenario before the agent turn (fresh-install: brain + routing stub
+ init; upgrade: seed-first) and verifies outcomes after it: doctor
must parse and report healthy/warnings, scenario-declared query +
files_exist oracles are enforced for every kind, and upgrades use a
non-mutating schema-version probe that must reach LATEST_VERSION.
Missing upgrade seed dumps fail loudly in BOTH modes (a silent skip
false-greened the upgrade lane). Bare gbrain in live runs resolves
through a per-run PATH shim; when gbrain itself runs under the bun
runtime the harness synthesizes a launcher back into cli.ts instead of
handing children the bun binary.
gbrain friction diff --base/--compare: identity is (kind, phase,
digit-collapsed 80-char prefix); severity compares as a per-severity
distribution (integer proportion test) so redistribution and
delight-to-friction flips always surface; run start/end phase markers
carry agent + scenario for agent-name resolution.
Hardening from the adversarial gate: every harness child runs under a
wall-clock timeout with process-group kill + exit-fallback settle;
scenario names and declared brief/brain/seed paths are confined to the
scenario dir; child friction merges require a regular file, cap size,
and keep only valid JSONL lines; crashed runs stamp a non-zero end
marker; GBRAIN_* routing vars are scrubbed from child env; agent
stdin closes at spawn; argv agent/scenario values are charset-guarded.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(hermes): real-binary install door e2e + generic workspace compat
Door e2e registers this checkout's gbrain into a hermetic Hermes home
via the real CLI (single --env flag with multiple values, piped
confirm, enabled:true + mcp test as the success discriminators), the
direct-YAML surface, and a paid one-shot smoke turn proving MCP recall
of a seeded synthetic fact with a NO-GBRAIN-TOOL negative control.
Triple-gated (opt-in env + resolvable binary + non-empty anthropic key)
so it can never burn tokens by accident; anthropic-only auth because a
second visible provider key mis-routes hermes provider auto-detection.
Helpers copy exactly ONE provider key from the operator's env file,
never the whole file, and scrub all provider keys from child env.
workspace-generic-compat pins the documented any-repo-with-a-workspace
install flow (detection tier, scaffold additivity, resolver health) on
a generic fixture; the Hermes-behavior proof lives in the door test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci: label-gated hermes-door job + e2e hermeticity scrub
hermes-door provisions a pinned Hermes release: installer digest
verified before execution, payload tag+commit flags ASSERTED post-
install via rev-parse (an installer that ignores unknown flags can
never run unpinned upstream code next to secrets), secretless install
step, loud-fail preconditions, zero-pass-refuses-green, evidence
scrubbed three ways before upload, and unconditional credential
cleanup for self-hosted-runner safety. real-agent-e2e gains the door
file + opt-in env. run-e2e.sh scrubs HERMES_* alongside OPENCLAW_*;
e2e-test-map narrows claw-test core changes to their e2e suite.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: hermes + openclaw MCP guides, CLI pin notes, harness reference updates
Per-client docs for Hermes (observed-behavior guide incl. flag-order
and multi-key gotchas) and OpenClaw; HERMES-CLI-PIN records every
pinned CLI behavior + the CI pin posture. README MCP table rows,
INSTALL_FOR_AGENTS hermes block, TESTING/KEY_FILES current-state
rewrites (two runners, oracle semantics, diff identity), TODOS closure
(hermes runner done, friction diff shipped, follow-ups filed) and the
llms bundle regenerated in the same commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.10.0)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: release sync — verb-count drift, hermes link, discovery rows, harness knobs
Cross-referencing the diff against every .md surfaced drift beyond this
wave: the memory-verbs surface prose still said five verbs (the frozen
protocol grew context_pack + delta additively), docs/INSTALL.md linked
a wrong Hermes repo and missed the new HERMES/OPENCLAW per-client
guides, the door-suite doc pinned a tool COUNT that tracks the op
catalog, the friction protocol skill missed the diff subcommand, and
the claw-test KEY_FILES entry lacked the harness env knobs. Comment
counts in heavy-tests.yml corrected (three triggers; four door tests).
llms bundle regenerated in the same commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci: quote inner expansion in evidence-scrub path strip (shellcheck SC2295)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: re-bump to v0.45.12.0 (user-pinned past the contested 0.45.11.0 slot)
Two sibling PRs already claim 0.45.11.0; pinning one slot higher avoids
a second merge-race re-bump. All version locations move together:
VERSION, package.json, CHANGELOG entry header, openclaw.plugin.json,
bootstrap runbook stamp, regenerated template stamp, CLAUDE.md example
cell, llms bundle.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): TTY DX exploration harness + Krug onboarding fix wave
Add a real-PTY exploration harness and land 16 verified "Don't Make Me
Think" fixes on the paste-in install experience for Claude Code and Codex.
Harness:
- test/helpers/tty-harness.ts — spawns any CLI (gbrain/claude/codex) under a
real pseudo-terminal (Bun terminal: spawn), timestamps every output burst,
and turns silence windows into a measurable stall report. Hermetic; pure
helpers unit-tested in test/tty-harness.test.ts.
- scripts/dx-explore.ts — drives the fresh-user funnel (help / init / real
claude-install / real codex-install / manual drive mode), writing
transcripts to .context/dx-runs/ (gitignored).
Fixes (all adversarially verified against the code first):
- Keyless bare `gbrain init` completes in keyless mode instead of exit 1;
multi-key non-TTY auto-picks the canonical default; typo stays fail-loud.
- Provider picker probe-gates ollama (daemon-up != model-pulled) and offers
an explicit "continue keyless" option that is the bare-Enter default.
- Fresh-brain init prints one schema-setup line instead of ~240 migration
names (GBRAIN_MIGRATE_VERBOSE=1 restores detail).
- Init epilogue: memory-verbs funnel is last-on-screen; skills advisory
compacted for init; Mod Status trimmed.
- PGLite live-serve lock error names the fix (close the agent session).
- Mode-picker banner interpolates the applied mode; expansion-key gate is
Anthropic/OpenAI/Google, not OpenAI-only.
- Missing `claude` binary skips MCP but still installs hooks; honest copy.
- Foreign MCP-registration removal targets the conflicting scope and fails
loud if it does not land.
- Upgrade marker compares the running binary to latest and self-spawns via
execPath, so a current/newer binary no longer nags from a stale cache.
- interview --set/--skip after --confirm warns it voided the confirmation.
- init --help matches behavior; init --supabase fails loud on non-TTY.
- Provider capabilities attributed per provider across README / runbook /
questions bank / bootstrap.md.
- First-run tour: restart-first, prompt 3 true on day one, withheld on FAIL;
README gives Codex the same scripted magic moment.
- Empty-brain "0 takes" onboard nudge suppressed.
- Broken settings.local.json aborts the hooks write fail-closed instead of
silently dropping the user's permissions.
Regenerated cli-flag-registry.generated.ts and llms-full.txt.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): second DX polish wave — clean the success screen + honest copy (F17-F21)
Follow-up to the DX fix wave, closing the top-5 remaining gaps the scorecard
flagged (all human-facing polish, not survival):
F17 — machine markers no longer leak to humans:
- verify report drops the `[D3.6]` plan-tag from the first_run_tour detail.
- the raw `UPGRADE_AVAILABLE <cur> <latest>` marker line prints ONLY on a
non-TTY stderr (parsers still get it); an interactive human sees just the
"gbrain X -> Y available" sentence.
- per-migration "what changed" notices (v123/v124, incl. the #2704 ref) are
suppressed on a FRESH-install replay via a module quiet flag; upgrades still
narrate. (GBRAIN_MIGRATE_VERBOSE=1 restores them.)
F18 — one obvious next action on the init success screen: the memory-verbs
demo is the single "→ Do this next" hero, last on screen; import/migrate/doctor
collapse into one terse "More:" footer; the graph block only shows for a
non-empty brain.
F19 — README "moment it clicks" is now the genuine cross-session brain
round-trip (remember → restart → recall), explicitly distinguished from the
identity-file recall, on both the Codex and Claude Code paths.
F20 — the compact init skills advisory is human-voiced (no `[AGENT]`
stage-direction on the human-facing success screen; the mode-picker's
agent-directed block stays gated to the non-TTY channel).
F21 — time promise reconciled: headline is ~15 min (personal-agent path) /
~30 min (always-on OpenClaw/Hermes); the runbook's search-mode line no longer
claims "balanced" when keyless applies "conservative". README hooks copy says
"on by default, with an opt-out" to match the runbook.
Regenerated llms-full.txt.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): address two-model adversarial review of the DX wave
Fixes the regressions the 5-specialist + red-team + Claude/Codex adversarial
pass found in the F1–F21 changes, each with a test:
- Keyless upgrade hint pointed at `config set embedding_model`, which config.ts
hard-refuses as a schema-sizing no-op — now names the working re-init recipe
(`gbrain init --force --pglite --embedding-model <id>`), zero-key AND multi-key
paths.
- Multi-key TTY picker offered "continue keyless" but the caller aborted on it —
now honors keyless like the zero-key path.
- Detached update-refresh spawn used a `/gbrain$/` basename check that misfires
for a renamed/official-named compiled binary (`gbrain-darwin-arm64`) and
prepends the /$bunfs entrypoint — now detects dev-vs-compiled by the runtime
basename (bun|node) so the refresh always runs.
- `bootstrap status` reported the wire phase "done" on a hooks-only receipt
(host CLI missing at wire time) — now "partial" with a re-run hint, so a
resuming agent doesn't trust a false complete.
- Post-repair MCP mismatch re-verifies and aborts instead of blessing a
registration a racing writer may have re-claimed.
- probeOpenAICompat's abort timer now spans the body read (was cleared before
it), so a stalled `/v1/models` body can't hang init past the 1s cap.
- Centralized the 4-copy stale-cache upgrade predicate into
`pendingUpgradeVersion`; UPGRADE_AVAILABLE gains a GBRAIN_FORCE_UPGRADE_MARKER
override for PTY-based agent harnesses.
- Mode picker's expansion-key gate adds GEMINI_API_KEY; picker prompt is
article-aware ("an embedding" / "a chat"); dead `!brainEmpty` clause removed;
migrate.ts try/finally widened + stamp failures named in quiet mode.
- DX harness: credential copies scrubbed even on SIGINT/interrupt (+chmod 600),
child process TREE reaped on teardown, advisory made fail-open, KEY_MAP typed
as a literal union.
New tests: migrate quiet-replay, self-upgrade pending predicate + negative
cache cases, bootstrap 127/scoped-remove/broken-settings dispatch, interview
invalidation flag, verify tour-withheld-on-FAIL, init keyless/supabase/multi-key,
init-nudge branches, ai-probes model parsing. Regenerated flag registry +
template-repo.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.45.8.0 fix(bootstrap): onboarding DX polish wave (F17-F21) + review fixes
DX fix wave on the paste-in install/first-run experience for Claude Code and
Codex, driven by a new real-PTY exploration harness. Keyless init completes
instead of erroring, the migration wall collapses to one line, the success
screen leads with one action, and the "magic moment" copy points at the genuine
cross-session round-trip. Full detail in CHANGELOG.
Version trio + openclaw manifest + runbook stamp bumped to 0.45.8.0; CHANGELOG
release entry; TODOS onboarding-DX follow-ups filed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): OOBE hand-off — you own the brain, cold-start is skill #1
A working install now ends by making the two facts that matter actually land:
- `gbrain bootstrap verify` prints (and returns as `handoff` in --json) an
ownership block — the actual private-repo URL with what owning it means
(read it, `gbrain bootstrap attach` on machine two, delete it and the brain
is gone), or the local-only variant pointing at `gbrain bootstrap repo` —
followed by the ONE next action: run the cold-start skill (Gmail/calendar/
contacts via ClawVisor, an OAuth vault so the agent never holds raw tokens;
or offline archives), one consented phase at a time. Withheld on FAIL like
the tour; shape stays unconditional for machine consumers.
- cold-start ships in the downstream bundle (61 skills): its plugin exclusion
("host onboarding flow") predated the v0.45 personal-agent bootstrap and is
deliberately reversed — the paste-in audience is exactly who day-one
onboarding is for. It now LEADS the recommended set (ahead of book-mirror:
every flagship skill only becomes magical once the brain holds the user's
real life).
- New drift guard: every recommended slug must be scaffoldable from the
plugin bundle — recommended-but-unscaffoldable is a dead-end CTA and now
fails the suite.
- Runbook Hand off rewritten around the two must-land facts + the on-the-spot
cold-start offer; README's Codex and Claude Code paths carry the same two
follow-ups.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.45.10.0 feat(bootstrap): the OOBE hand-off release
Version trio + runbook stamp + template tree to 0.45.10.0; CHANGELOG entry;
llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(ci): stop memory-verbs-conformance leaking a fake-keyed gateway into shard-mates
The deterministic-embedder helper configures the MODULE-GLOBAL gateway with a
fake OpenAI key; the file's afterAll never reset it. The bunfig preload's
per-test restore only fires when the gateway is UNCONFIGURED, so the fake-keyed
config persisted for every later file in the shard process — turn-context's
corpus writes then embedded against real OpenAI and 401'd (CI shard-8 failure;
shard re-binning from this branch's new test files exposed it).
Fix both sides: conformance's afterAll now resetGateway()s back to the preload
baseline and nulls both test transports; turn-context's beforeAll does the same
defensively so it stays hermetic regardless of shard composition.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Wave-assembled from PR #3548 by @time-attack. Composition conflicts vs wave
item #3993 resolved: EmbedResult keeps both chunkless_pages_healed and the
PR's lock_skipped; KEY_FILES.md keeps the #3993 embed entry and takes this
PR's migrate-embeddings entry.
Co-Authored-By: Garry Tan <garrytan@gmail.com>
Wave-assembled from PR #3888 by @RerankerGuo. Conflict resolution: KEY_FILES.md
check-resolvable/skill-frontmatter/skill-trigger-index entries taken as the
PR's current-state prose; the PR's stale pre-fold 'doctor.ts extension' entry
dropped (master already folded it into the main doctor entry).
Co-Authored-By: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com>
Wave-assembled from PR #3936 by @dovstern. Conflict resolution: kept master's
resolveRepoRoot() block AND the PR's exported currentBranch in
src/core/brain-repo-durability.ts. Adaptation: the new serial test now writes
the simulated push log under $GBRAIN_HOME/.gbrain (CX2-8 parent-dir semantics
landed on master after the PR's base).
Co-Authored-By: Dov Stern <dovstern@users.noreply.github.com>
Wave-assembled from PR #3976 by @clement0909472. Rider: four toContain pins
(claude-fable-5, claude-opus-5, claude-opus-4-8, claude-sonnet-5) in
test/claude-cli-recipe.test.ts.
Co-Authored-By: Clément Barberousse <clement.barberousse.pro@gmail.com>
Wave-assembled from PR #3782 by @JonMcCutchen. Rider-check: verified the
non-default pageRoot join (repoPath/.sources/<sourceId>) matches how
pages.source_path is recorded (source-root-relative via importFile's
relative(dir, filePath)); no mismatch, no change needed.
Co-Authored-By: Jon McCutchen <jmmccutchen1@gmail.com>
Wave-assembled from PR #3762 by @awilhite. Rider: PGLite round-trip chunk-count
assertion in test/extract-atoms-chunk-embed.test.ts (verified fails without the
src change).
Co-Authored-By: Austin Wilhite <austinw80@gmail.com>
* fix(bootstrap): preview source_id + create brain/ eagerly in hooks phase
`bootstrap render`/`hooks` never told a human what source_id the
workspace expects until `verify` (the only engine-holding phase) ran.
A human who hand-registered a source before that point would guess an
"intuitive" name, hit an FK error on the first `verify` roundtrip (the
guessed id has no `sources` row), then hit `overlapping_path` on the
retry (their first guess still claims the same brain/ dir) — three
round trips to land the right id.
`hooks` is the last ENGINE-FREE phase before `verify`, and already
knows both the manifest's current source_id and the workspace path, so
it now:
- creates `<ws>/brain` eagerly (idempotent mkdir), removing the
manual-mkdir step before `git init && sources add`
- prints the exact `gbrain sources add <source_id> --path <brain>`
command
- previews the collision-fallback id verify would derive
(`workspace-<hash>`) — a pure function of the workspace's real
path, so it needs no DB lookup and is safe to preview engine-free
The collision-fallback derivation itself is unchanged; it is now
factored into an exported `deriveWorkspaceSourceId()` in verify.ts so
both call sites (the new hooks preview and the existing
`resolveSourceIdCollision`) share one formula instead of two copies
drifting apart.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016JNV9ABwb32DZEwvo7P4ay
* fix(bootstrap): --force the preview command; quote paths; fix runbook
Codex review round 2 caught three issues with the source_id preview
added in the prior commit:
- The printed `gbrain sources add <id> --path <brain>` command failed
immediately on a pristine bootstrap: the brain/ dir this phase just
created is empty (no git history), so `sources add --path` fail-fasts
as `not_a_git_repo` (#2707). Fixed by appending `--force` — the same
sanctioned opt-in `test/bootstrap-verify.serial.test.ts` already uses
to register a brand-new brain/ before any content exists
(`addSource(engine, { id: 'workspace', localPath: ..., force: true })`).
Safe here specifically because brainDir is the fixed
`<workspace>/brain` path this phase just created, not an arbitrary
user path.
- brainDir was interpolated unquoted; a workspace path containing a
space broke the printed command. Added a local
`shellQuoteForDisplay()` (mirroring the existing private `shellQuote`
already duplicated in hooks.ts / sources-ops.ts / connect.ts).
- The dispatcher test only pattern-matched the collision-fallback id's
shape (`workspace-[0-9a-f]{8}`) instead of pinning exact equality
with `deriveWorkspaceSourceId()`, so preview/verify drift could pass
silently. Now asserts exact equality, plus a new test for the space-
quoting fix.
Also corrects BOOTSTRAP_FOR_AGENTS.md's runbook step 5, which claimed
skill scaffolding "registers `brain/` as the workspace source" — no
code path does this automatically (confirmed by grep); the step now
points at the `hooks` phase's actual preview + --force command instead
of telling the installing agent there is "nothing to judge" on a step
that silently never ran.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016JNV9ABwb32DZEwvo7P4ay
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
`gbrain bootstrap <subcommand> --help` (a help token AFTER the subcommand
name, e.g. `gbrain bootstrap uninstall --help`) fell through into the
subcommand's own arg parsing instead of printing help, since none of the
mutating handlers (repo/hooks/verify/attach/uninstall/render/interview)
checked for --help/-h/help themselves. `uninstall --help` ran a real
uninstall; `repo --help` created a real private GitHub repo; etc.
Add a SUBCOMMAND_HELP usage map plus a pre-dispatch hasHelpToken() guard in
runBootstrap so a help token anywhere in the subcommand's args short-circuits
before any lock/runner/engine/handler call. Bare `help` (no dashes) is also
recognized, except for `interview` (its --set KEY value free-text answers
could legitimately be the literal word "help").
New test/bootstrap-subcommand-help.serial.test.ts arms fixtures so the real
operation would reach its side effect if the guard were removed (an
already-rendered workspace for render/hooks/attach, an operational verify
config, an isolated uninstall home with a real receipt-tracked file, a fresh
interview workspace) and asserts nothing mutates.
* fix(doctor): honor the recorded pid_file in supervisor_singleton check
`gbrain doctor`'s `supervisor_singleton` check (#1849) compares the local
pidfile holder against the queue-scoped DB lock holder. It read
`readSupervisorPid(DEFAULT_PID_FILE)` unconditionally, even though the
supervisor's own 'started' audit event already records the pid-file path
actually in use (`this.opts.pidFile`). A supervisor launched with a custom
`--pid-file` (e.g. a launchd-managed deployment) would then get a false
"singleton mismatch" warning against its own healthy, single instance,
because the pidfile doctor read was never the one the supervisor wrote.
- doctor.ts now prefers `lastStarted.pid_file` when present, falling back
to `DEFAULT_PID_FILE` for events that predate the field.
- supervisor.ts resolves `pid_file` to an absolute path at emit time (the
only cwd context in which a relative `--pid-file` is meaningful), so a
later reader running from a different cwd doesn't misresolve it. The
process's own internal pidfile guard/read/write paths are untouched.
The DB lock (`gbrain_cycle_locks`) remains the sole singleton authority per
#1849 — this only corrects which pidfile the diagnostic display reads.
Added test/doctor-supervisor-singleton-pidfile.test.ts covering the fixed
path, the still-mismatching absent-pidfile case, and a source-grep pin for
the compatibility fallback.
* docs(comments): correct pid_file fallback rationale and drop unsupported claims
The 'started' audit event has carried pid_file since the supervisor's
introduction, so the fallback comment no longer claims a predate case;
DEFAULT_PID_FILE is env-overridable (GBRAIN_SUPERVISOR_PID_FILE), so the
comments stop calling it HOME-derived; and the custom --pid-file scenario
is now described as an example rather than asserted as common.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126D3zLWL5RE3CVxnPANiiU
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
#1586 threaded the cycle's resolved source through the synthesize phase so
subagent-written pages land in that source's (source_id, slug) rows. The
patterns phase was not updated and kept the pre-#1586 shape: it stamped a
literal 'default' on every collected ref and compared the reverse-write path
against a literal 'default'.
On a per-source cycle that files the page against the wrong source. The row is
created under 'default' (the child had no source_id to scope its put_page
calls) while the reverse-write drops the file into the named source's checkout,
because source_id === 'default' selects the brainDir/<slug>.md branch and
brainDir IS that source's checkout. Row and file then disagree about which
source owns the page — what doctor reports as multi_source_drift.
Applies the same threading synthesize.ts already uses: PatternsPhaseOpts gains
sourceId, cycle.ts passes cycleSourceId at the patterns call site the way it
already does for synthesize, the child carries SubagentHandlerData.source_id,
and reverseWriteRefs takes the cycle source as its native source. Unset stays
'default', so unscoped callers are unchanged.
* fix(bootstrap): Gate 2 checks only the active gh account, not every registered one
createPrivateRepo's Gate 2 ran bare `gh auth status` and treated any
non-zero exit as "not authenticated". That command aggregates every
registered account across every host and exits 1 if even one of them
has auth issues — so a stale, unused, expired account (or one on an
unrelated GitHub Enterprise host) false-blocks `gbrain bootstrap repo`
even while the actual active account works fine.
Gate 2 now scopes the check with `--hostname github.com` (this flow is
already github.com-only end to end: parseGithubOwnerRepo, the
repo-create URL fallback, etc.) and, when the installed `gh` supports
it, `--active` as well (added in cli/cli v2.57.0 — confirmed present at
v2.57.0 and absent at v2.56.0 by diffing status.go across tags on
cli/cli). Support is detected from the `gh --version` output Gate 1
already captures, so an older `gh` falls back to the host-scoped bare
form instead of hard-failing on an unrecognized flag.
Verified `gh auth status --active`'s semantics directly against
cli/cli's pkg/cmd/auth/status/status.go: passing --active skips the
per-host loop over non-active accounts entirely (`if opts.Active {
continue }`), so only the active account's entry can affect the exit
code.
* fix(bootstrap): regenerate flag registry for the new gh --active/--hostname literals
The prior commit's Gate 2 change added the string literals `--active` and
`--hostname` inside src/core/bootstrap/repo.ts (both in the gh argv and in
comments). src/commands/bootstrap.ts statically imports repo.ts, and
scripts/generate-flag-registry.ts scans one level of relative imports from
each CLI_ONLY case block to build the committed, freshness-pinned
src/core/cli-flag-registry.generated.ts (#2185) — so the 'bootstrap' entry
was stale relative to a fresh `bun run build:flag-registry` run, failing
test/cli-flag-validation.test.ts's freshness guard in CI.
Regenerated via `bun run build:flag-registry`; the only change is 'bootstrap'
gaining '--active' and '--hostname' alongside its existing ~70 entries. This
is the generator's documented, deliberately over-inclusive behavior (accepting
an unused flag is the pre-#2185 status quo) — neither flag is
security-sensitive or read from user input; both are hardcoded in the `gh`
subprocess invocation, not accepted from `gbrain bootstrap`'s own CLI args.
Confirmed via `git fetch upstream && git log HEAD..upstream/master --oneline`
(0 commits) that this is not upstream drift — purely caused by this PR's own
diff.
Fixes#3962
Return the structured extraction result for --json callers while preserving the existing human summary. Add a behavior-level regression test that proves stdout is parseable JSON.
* fix(facts): make transcript pages facts-extraction eligible
`gbrain extract-conversation-facts`'s ALLOWED_TYPES allowlist omitted the
`transcript` page type, so gbrain's own nightly transcript-ingest pages
were silently skipped by both the CLI `--types` validation and the
`cycle.conversation_facts_backfill.types` config filter. Even with the
type allowed, the built-in conversation-parser had no pattern for the
`## User` / `## Assistant` markdown-heading turn shape that transcript
ingest writes into `compiled_truth`, so parsing would still yield 0
segments.
This PR makes an explicit decision: transcript pages ARE now
facts-extraction eligible. That is a real behavioral change (a new,
potentially large corpus starts flowing through the extraction +
segment-cost path), not a no-op bugfix — flagging it plainly rather than
padding out the change as narrower than it is.
Changes:
- `src/commands/extract-conversation-facts.ts`: add `'transcript'` to
`ALLOWED_TYPES` / `ALLOWED_TYPE_ALIASES` (the single source of truth
for this allowlist).
- `src/core/conversation-parser/builtins.ts`: add the `markdown-heading-turn`
builtin pattern recognizing heading-only `## User` / `## Assistant` /
`## Human` / `## System` lines as turn openers, with D5 continuation-line
body absorption. `quick_reject` is deliberately scoped to the role-prefix
(not a bare `#{2,3}` heading check) so a message body that happens to
paste unrelated markdown headings doesn't starve the D18 scorer's
anchor-candidate ratio.
- `src/commands/jobs.ts`, `src/commands/doctor.ts` (x2 checks),
`src/commands/sources.ts`: these each carried their own hand-copied
literal of the same allowed-types list (background-job type filter,
`conversation_facts_backlog` doctor check, `conversation_format_coverage`
doctor check, `facts_backfill_estimate`). Switched each to import
`ALLOWED_TYPES` from the command module instead of re-listing it, so this
class of drift (a type added in one place, silently excluded everywhere
else) can't recur.
- `docs/architecture/KEY_FILES.md`: updated the two stale mentions (pattern
count 17→18, allowlist list) to current-state per this repo's own
reference-doc convention.
Known limitation (not fixed here, scope-bounded intentionally): parsing is
context-free, same as every other multi-line builtin in this registry — a
message body that contains a literal `## User` line (e.g. someone pasting
a markdown transcript excerpt into their own message) would be read as a
turn boundary. This is a pre-existing property of the whole parser
(`applyPattern`'s per-line scan has no fence-awareness), not something
this PR introduces or could fix without a much larger, separate change to
the shared orchestrator affecting all 18 patterns. Flagging it here rather
than silently shipping the same limitation as the other 17 builtins.
Tests: 4 new tests (2 in test/extract-conversation-facts.test.ts, 2 in
test/conversation-parser/parse.test.ts) covering the allowlist, the new
pattern's positive match + continuation absorption, and that ordinary
`## Summary`-style headings are correctly rejected. Full targeted suite
(conversation-parser + facts-extraction + doctor backlog + build-llms
freshness): 263 pass / 0 fail. typecheck clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126D3zLWL5RE3CVxnPANiiU
* fix(facts): read the type allowlist from core, not the command module
CI caught this: the known-flags registry drifted for doctor, sources, and
repos. The obvious remedy the guard prints -- regenerate and commit -- would
have been a regression, so this takes the other route.
The generator walks one level of a command module's relative imports and
harvests every flag-shaped string it finds, help text included, and is
deliberately over-inclusive. Importing extract-conversation-facts.ts just to
read ALLOWED_TYPES therefore spliced that command's entire flag vocabulary
(--types, --sleep, --slug, --segment-limit, --override-disabled, ...) into
the allowlists of three commands that implement none of it: `gbrain doctor
--types foo` would have passed validation and been silently ignored. That is
the exact defect class #2185 exists to close.
(jobs.ts is unaffected: it already imported the command module on one line
for runExtractConversationFactsCore, so those flags were already in its
registry entry before this branch.)
ALLOWED_TYPES + ALLOWED_TYPE_ALIASES now live in
src/core/conversation-facts-types.ts, a constants-only module with no CLI
text to harvest. extract-conversation-facts.ts re-exports both so its
existing importers are unchanged.
Verified: registry regenerates to zero drift (was doctor/repos/sources),
cli-flag-validation 24 pass, typecheck clean, 287 pass across the touched
areas. Confirmed against a clean upstream/master worktree that the drift was
introduced by this branch and is not pre-existing.
* fix(conversation-parser): reduce to the parser pattern only
Withdraws the `transcript` allowlist half of this branch. The premise was
wrong: `transcript` is not an upstream page type. `ALL_PAGE_TYPES` does not
contain it, `gbrain-base.yaml` declares `conversation` for "long-running
chat/transcript pages" and marks it `extractable: true` precisely so
extract-conversation-facts walks it, and `gbrain-base-v2.yaml` lists
`transcript` as an alias of `source` (a media primitive). Pages typed
`transcript` are a convention of my own ingest pipeline, not something
upstream produces — the fix for that belongs on my side, by emitting
`conversation`.
That takes the four call-site de-duplications with it (they existed only to
keep the allowlist in sync), and with them the flag-registry drift: no
imports are added, so the registry regenerates to zero drift with no
constants module needed.
What remains is the half that stands on its own: a `conversation` page whose
body uses `## User` / `## Assistant` headings matches none of the 17 builtins
and parses to 0 segments. `markdown-heading-turn` is an 18th pattern in the
same shape as the iMessage/Circleback additions before it.
Verified: typecheck clean, 181 pass / 0 fail across the parser, extraction,
flag-registry and llms-freshness suites, registry drift zero.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(skills): company-brainify — close three sanitization-defeating defects
1. Scope truncation: the first structural grep used '>' and overwrote the
retrieval-discovered scope list; Phase 1 now writes retrieval paths to
/tmp/brainify-scope.txt explicitly and both greps append.
2. Facts reconciliation: the skill claimed 'gbrain sync' makes the DB stop
serving deleted Facts-fence rows. Sync's convergence contract covers page
import only — fact extraction is explicitly decoupled (src/commands/sync.ts
CONVERGENCE CONTRACT); the reconcile lives in the extract-facts sweep
(src/core/cycle/extract-facts.ts). The procedure now triggers the sweep and
verifies removal with 'gbrain recall --grep' before certifying.
3. Backup retention glob: the backup is created as
shared-brain-history-backup-<ts>.git but cleanup documented
brain-history-backup-<date>.git — a pattern that matches nothing, silently
retaining the pre-sanitization history mirror forever. Globs now agree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(skills): regenerate skills.lock.json after master fix-wave
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(skills): citation-graph-ingest — check-backlinks requires a subcommand
Bare 'gbrain check-backlinks' exits with a usage error; the CLI requires
'check' or 'fix' (src/commands/backlinks.ts runBacklinks). The hygiene step
now invokes 'check-backlinks check', matching every other invocation in the
skill pack.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(skills): regenerate skills.lock.json after master fix-wave
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
runServe()'s stdio path flips console-prefix's module-global
stdout→stderr redirect (#3844). bun test runs every file in one
process, so after sweep.test.ts's serve-wiring tests the flag stays
on and any later file pinning slog's stdout routing fails
(test/sync-all-parallel.test.ts, test/console-prefix.test.ts) —
shard-composition dependent, so it surfaces as a flake. Same reset
the donor harness (test/serve-stdio-lifecycle.test.ts) already
carries.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(core): execution-environment detection — local | cloud-sandbox | ephemeral-container
detectExecutionEnvironment() + isCredentialInjectingProxy() with injected
signals (CLAUDE_CODE_REMOTE, cse_ session-id prefix, proxy-injected token
placeholder, anthropic-egress proxy JWT, container markers). binaryOnPath
moves here as the canonical PATH probe. autopilot's detectInstallTarget
ephemeral branch now routes through the shared detector.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): repo-visibility ladder + per-turn Stop push + same-session failure banner
The durability lane. One repo-visibility verdict for every consumer (REST
first — never GraphQL, which sandbox proxies pin; authed ls-remote + an
attributed anonymous probe as the git-protocol fallback), replacing three
drifted probes. A 200 counts as public only with advertisement proof; a
401/404 counts as private-signal only with an auth challenge — fail-closed
in BOTH directions. Private verdicts cache 1h (private-only, per origin).
gbrain hook stop now spawns a debounced detached push per turn (per-root
state; cloud-sandbox defaults to every turn, elsewhere 5 min; a failing
status bypasses the debounce), closing the /exit and VM-reclaim gaps.
Push status is per workspace root, read through one shared reader by the
user-prompt banner (additionalContext + systemMessage — visible to the
human, not just the model), the SessionStart note, and doctor. Escape
hatches for self-hosted git: flag > env > file-plane config key.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): environment-aware install — honest cron skip, cloud repo-create guard, execution_env surfaces
installDurabilityCron probes for crontab before writing anything (containers
and cloud sandboxes ship without one — expected, reported as an honest skip
naming the event-driven pushes that still cover persistence). The repo phase
installs the container-friendly harden half (post-commit hook, no scheduler)
outside local machines. createPrivateRepo fails fast in cloud sandboxes with
the flow that works (create outside, open the session ON the repo, attach).
bootstrap verify gains a never-gating execution_env check; bootstrap status
--json carries execution_environment for installing agents to branch on.
Also fixes a live-PATH resolution class: binaryOnPath and the crontab execs
now pass the current env explicitly (Bun resolves against the startup
snapshot otherwise).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): lifecycle hygiene — uninstall teardown, doctor job liveness, .mcp.json out of the repo, honest persistence copy
uninstall now tears down the durability wiring it installed (launchd/cron
job, untracked post-commit hook, credential wiring — the committed helper
and AGENTS rules stay). doctor gains bootstrap_durability_job: presence +
LIVENESS (launchctl load-state, crontab line, pull-log freshness) — a plist
on disk with a dead job no longer reads as healthy. Rendered .gitignore now
covers .mcp.json (absolute machine paths must not land in the private
repo); verify warns on pre-fix installs that committed it; the never-built
state/mcp.json promise is gone from GITHUB.md. Persistence copy tells the
truth everywhere: event-driven pushes do the durability work, the 30-min
job is a multi-machine pull freshener. Post-commit hook install/removal is
worktree-safe (git-path resolution; the git marker is a FILE there) and the
cron wrapper's self-disable tests the repo dir, not its git marker. Two
follow-up TODOs filed (plugin hook distribution; Channels push lane).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(bootstrap): committed hook carrier for cloud + cloud-setup-script emitter + cloud runbook
Cloud sessions clone fresh and snapshot hook config at session start — the
gitignored settings.local.json never exists there, so hooks never fired in
cloud at all. Cloud installs now write the repo-COMMITTED .claude/settings.json
with PATH-resolved, fail-open commands (no machine paths; a host without the
binary no-ops); local installs keep settings.local.json; the writers enforce
that one event never fires from both carriers, and removal cleans both.
New: gbrain bootstrap cloud-setup-script prints the paste-ready environment
setup script (npm transport — bun fetching is proxy-incompatible in cloud;
never the unrelated npm-registry package). Runbook gains a NEVER FABRICATE
TOOLING hard rule, a cloud-sandbox section (expected degradations as facts to
relay, the attach-first flow), and failure-table rows for the proxy-403 and
missing-crontab signatures. Codex lane stated honestly: AGENTS.md Gate 2 now
has the pull-side push-health check. Guide documents the new knobs and the
cloud contract; llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(bootstrap): per-turn push e2e chain, cloud-sandbox sim, per-root status reader migration + registry regen
bootstrap-persistence e2e gains the Stop-hook chain (one stop banks the turn
to the real bare remote; the debounce holds across stops; debounce-0 lands
consecutive turns) and fixes a pre-existing post-#4024 break: repoPhaseComplete
required a github-parseable origin, so session-end pushes deferred FOREVER for
self-hosted/file-transport origins — non-github repo_urls now bind by exact
URL equality (redirect protection preserved). Degraded-modes e2e gains the
cloud-sandbox simulation (status reports the environment; repo creation
refuses with the attach flow). workspace-push tests read per-root status
through the shared reader. Flag registry regenerated (new git argv literals
from the git-path/ls-files calls — the accepted argv-bleed class).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(doctor): categorize bootstrap_durability_job (categories drift guard)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): adversarial-review hardening — fail-closed privacy, no push-storm, no exfil paths
Both Claude and Codex adversarial passes ran; 11 findings fixed (union):
- Non-github 401+WWW-Authenticate no longer reads as private (RFC 7235 makes
the header mandatory on every 401, so a middlebox 401s identically) — the
top exfil path both models flagged; now unverifiable/fail-closed, operator
confirms via the escape hatch. github.com still needs x-github-request-id.
- Escape hatches downgrade ONLY 'unverifiable' — a PROVEN-public origin still
refuses (hatches never authorize a public push).
- treeNeedsPush measures against origin/<branch> (the push's own ref), not
@{u}: a no-upstream branch no longer reports a committed-but-unpushed tree
as push_clean and silently strands it.
- [D20] failing-retry uses a fixed 60s floor, not min(debounce,60s) — cloud
debounce=0 no longer re-runs the network ladder every turn.
- Committed hook carrier: dedupe/suppress only on the EXACT portable-command
shape, not a 'gbrain hook' substring (blocks the suppress-local-run-evil
supply-chain vector); GBRAIN_HOME refused in the committed carrier.
- push-status reason sanitized (charset+length) at every surface (banner,
doctor, status blob) so remote git stderr can't inject via the remediation.
- Per-root state: ghost-root records (deleted workspaces) filtered so a dead
failing record can't re-fire the banner forever; uninstall removes them.
- statusReport support blob reads push status through the shared per-root
reader; visibility cache strips URL userinfo (no PAT persisted).
- anonProbe strips userinfo + redirect:manual + SSRF flags + --end-of-options
on ls-remote; cron self-disable uses git rev-parse (worktree-safe both
ways); cloud-setup-script fails loud on a broken update; durability liveness
won't certify a never-run crontab as live; config get/unset resolve the
dotted file-plane keys; .bak/.broken gitignored; typed config fields.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* v0.45.8.0 feat(bootstrap): first-class cloud-sandbox install + per-turn persistence + fail-closed privacy ladder
VERSION + package.json + CHANGELOG + TODOS + llms bundles.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: sync KEY_FILES + README for the cloud-DX wave (v0.45.8.0)
New KEY_FILES entries for execution-env.ts and repo-visibility.ts; updated the
bootstrap repo/hooks, workspace-push, brain-repo-durability, and hook.ts
entries to current behavior (ladder verification, committed cloud hook carrier,
per-root push status, crontab probe + liveness, per-turn stop push + banner).
README's Claude Code line now states per-turn + cloud persistence honestly.
llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): doc-review pass — attach records repo_url (enables cloud persistence), verify reads per-root push status, honest docs
Cross-model doc review (Codex) caught that the headline cloud-persistence
claim was hollow and two docs over-claimed:
- attach now records repo_url from the adopted origin, so the no-daemon push
gate (repoPhaseComplete) recognizes the repo phase as done — WITHOUT this,
the per-turn/session-end pushes deferred forever after an attach, which is
the ONLY install path in a cloud sandbox (repo is refused there). Privacy is
still enforced at push time by the ladder.
- bootstrap verify's push_probe reads the shared per-root reader [D8], not the
legacy single file — a fresh v0.45.8 install no longer reports 'no push
recorded' when per-root status exists.
- Docs corrected to match code: runbook stamp → 0.45.8.0; README states the
per-turn cadence honestly (debounced local, next-turn failure notice);
GITHUB.md qualifies auto-push as Claude Code (Codex is pull); KEY_FILES says
repo/status use REST (not the full ladder) and drops the stale --push;
bootstrap.md hooks-location covers both carriers; README verbs surface says
seven. llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(bootstrap): regenerate vendored template-repo tree + isolate env-mutating tests (verify gate)
The verify CI gate caught two things the piecemeal local runs missed:
- templates/bootstrap/template-repo/ is a GENERATED tree; the source-template
edits (AGENTS.md Gate 2, CLAUDE.md cloud note) plus the version stamp had
drifted. Regenerated from source (check:bootstrap-templates green).
- test/bootstrap-repo.test.ts + test/durability-cron.test.ts newly mutated
process.env in non-serial files; converted to withEnv() (check:test-isolation
green) — no .serial rename needed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(ambient-recall): pin a keyless gateway so delta/context_pack writes never fire a real embed
Root cause of the shard-2 CI red after the 0.45.9.0 re-bump: adding this
wave's test files reshuffled the weight-packed shards, moving
ambient-recall.test.ts next to a neighbor that leaks CI's dummy
OPENAI_API_KEY (sk-test-*) into the gateway singleton (the bunfig preload
configures with env:{...process.env}, and a present-but-invalid key turns
remember's keyless-degrade embed into a hard 401). The delta/context_pack
tests exercise cursor + budget logic, not embedding quality, so this pins a
keyless gateway (env:{}) in beforeAll — isAvailable('embedding') is false,
writeSingleFact degrades (degraded_dedup) with no HTTP call, and the file is
deterministic regardless of shard bin-packing. Verified: passes with
OPENAI_API_KEY=sk-test-* set (the CI condition). Master's own comment in
legacy-embedding-preload.ts already warns 'adding any test file reshuffles
the mines'; this makes the file immune.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-12 16:12:59 -07:00
961 changed files with 131676 additions and 24803 deletions
"description":"GBrain — a persistent knowledge brain for your coding agent: hybrid search, synthesis, and cross-session memory.",
"owner":{"name":"Garry Tan"},
"plugins":[
{
"name":"gbrain",
"source":"./",
"description":"Personal knowledge brain for your coding agent — hybrid search, synthesis, and durable cross-session memory, plus a curated brain-first skill set.",
"description":"Personal knowledge brain for your coding agent — hybrid search, synthesis, graph traversal, and durable cross-session memory over Postgres/PGLite with pgvector, plus a curated brain-first skill set.",
"description":"Personal knowledge brain for your coding agent — hybrid search, synthesis, graph traversal, and durable cross-session memory over Postgres/PGLite with pgvector, plus a curated brain-first skill set.",
"shortDescription":"Give your agent a persistent brain: search, synthesis, memory",
"longDescription":"GBrain wires a personal knowledge brain into every session: hybrid keyword+vector search, entity graph traversal, synthesis, and memory your agent writes itself — served on the starter MCP surface (the seven memory verbs plus the daily-driver brain ops). Bundles the curated brain-first skill set: setup (walks install + gbrain init), cold-start day-one brain filling, ingest, query, briefing, upgrade, and more. Requires the gbrain CLI (bun install -g github:garrytan/gbrain#latest-stable) and a brain (gbrain init); the bundled setup skill walks the rest. Unix (macOS/Linux) only.",
# shell: bash → pipefail, so tee can't mask the gate's exit code.
shell:bash
env:
COVERAGE_GATE_ENFORCE:'0'
run:bun scripts/coverage-baseline-gate.ts --summary "$RUNNER_TEMP/coverage-full-merged/summary.json" --corpus fullCorpus | tee -a "$GITHUB_STEP_SUMMARY"
if ! echo "$HERMES_INSTALL_SHA256 hermes-install.sh" | sha256sum -c -; then
echo "::error::hermes installer digest drift — re-pin deliberately: update HERMES_INSTALL_SHA256 + HERMES_VERSION in this workflow and docs/mcp/HERMES-CLI-PIN.md after reviewing upstream changes" >&2
exit 1
fi
for attempt in 1 2 3; do
if timeout 600 bash hermes-install.sh --skip-setup --non-interactive --branch "$HERMES_GIT_TAG" --commit "$HERMES_GIT_COMMIT"; then
# The branch/commit flags above are ASSERTED here, not trusted:
# a shell installer that silently ignores unknown flags would
# clone upstream main into a runner that later holds secrets.
# Verify the actual checkout before anything else runs it.
actual_commit=$(git -C "$HOME/.hermes/hermes-agent" rev-parse HEAD 2>/dev/null || echo "no-git-checkout")
if [ "$actual_commit" != "$HERMES_GIT_COMMIT" ]; then
echo "::error::hermes payload drift — installed checkout is $actual_commit, pinned $HERMES_GIT_COMMIT. Either the installer ignored its branch/commit flags or the layout moved from ~/.hermes/hermes-agent; re-pin deliberately (HERMES_GIT_TAG/HERMES_GIT_COMMIT + docs/mcp/HERMES-CLI-PIN.md) after reviewing upstream." >&2
exit 1
fi
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
exit 0
fi
echo "::warning::hermes install attempt $attempt failed or timed out; retrying in 10s" >&2
sleep 10
done
echo "::error::hermes install failed after 3 attempts" >&2
exit 1
- name:Preconditions (binary, secret, version pin)
echo "::error::grok npm integrity drift for $GROK_NPM_PACKAGE@$GROK_VERSION — registry serves '$served', pinned '$GROK_NPM_INTEGRITY'. Re-pin deliberately: update the stamps in docs/mcp/GROK-CLI-PIN.md + this workflow after reviewing upstream (see the pin doc's re-observation checklist)." >&2
exit 1
fi
# The platform sub-package is the binary that actually runs — pin it
# too (per-arch; ubuntu-latest is x64 today, arm64 pinned for a
if [ -z "$pass_count" ] || [ "$pass_count" -lt 4 ]; then
echo "::error::grok door keyless tier expected 4 passing tests, summary shows '${pass_count:-none}' — refusing to go green (see docs/mcp/GROK-CLI-PIN.md triage table)" >&2
exit 1
fi
- name:Preconditions (secret present)
env:
XAI_API_KEY:${{ secrets.XAI_API_KEY }}
run:|
if [ -z "$XAI_API_KEY" ]; then
echo "::error::XAI_API_KEY secret is empty — the keyless tier above already ran (its coverage is banked); the paid SMOKE needs the secret. Admin: create the XAI_API_KEY repo/environment secret (console.x.ai), then re-run. Fork PRs get no secrets from GitHub." >&2
exit 1
fi
# Named bad-key preflight: key-rot fails HERE, at a step named for it,
# instead of surfacing as a confusing SMOKE failure (GROK-CLI-PIN.md
echo "::error::grok auth preflight failed — the XAI_API_KEY secret is present but rejected (rotate it at console.x.ai; see GROK-CLI-PIN.md triage table). Output: ${out:0:300}" >&2
exit 1
}
echo "auth preflight ok"
- name:Run grok door tests (full — paid SMOKE included)
env:
XAI_API_KEY:${{ secrets.XAI_API_KEY }}
run:|
EXIT=0
bun test --timeout=600000 test/e2e/install-real-grok.serial.test.ts > door.txt 2>&1 || EXIT=$?
echo "::error::codex plugin door expected exactly 1 passing INSTALL test, summary shows '${pass_count:-none}' — refusing to go green (re-pin deliberately when tests are added)" >&2
exit 1
fi
- name:Claude plugin door (install tier — expected shape enforced)
run:|
EXIT=0
bun test --timeout=600000 test/e2e/claude-plugin-install-real.serial.test.ts -t 'VALIDATE' > claude-plugin-door.txt 2>&1 || EXIT=$?
echo "::error::claude plugin door expected exactly 1 passing INSTALL test, summary shows '${pass_count:-none}' — refusing to go green (re-pin deliberately when tests are added)" >&2
exit 1
fi
# opencode door e2e (SST opencode): PROVISIONS the real opencode binary via
# the pinned npm package (wrapper + per-platform payload integrities
# verified — both pins live in docs/mcp/OPENCODE-CLI-PIN.md, enforced
# against this file by scripts/check-opencode-pin.sh in `bun run verify`).
#
# DAY-ONE FULL POSTURE (a step past grok's pre-secret gating, deliberate):
if [ "$served" != "$OPENCODE_NPM_INTEGRITY" ]; then
echo "::error::opencode npm integrity drift for $OPENCODE_NPM_PACKAGE@$OPENCODE_VERSION — packed tarball integrity '$served', pinned '$OPENCODE_NPM_INTEGRITY'. Re-pin deliberately: update the stamps in docs/mcp/OPENCODE-CLI-PIN.md + this workflow after reviewing upstream (see the pin doc's re-observation checklist)." >&2
if [ -z "$pass_count" ] || [ "$pass_count" -lt 5 ]; then
echo "::error::opencode door keyless tier expected 5 passing tests, summary shows '${pass_count:-none}' — refusing to go green (see docs/mcp/OPENCODE-CLI-PIN.md triage table)" >&2
echo "::error::ANTHROPIC_API_KEY secret is empty — the keyless tier above already ran (its coverage, including the SMOKE, is banked); the paid anthropic leg needs the secret hermes-door already consumes. Fork PRs get no secrets from GitHub." >&2
exit 1
fi
# Full run (paid anthropic leg included). The T5 models-gate inside the
# suite is the named bad-pin tripwire: it validates the pinned model id
# against the AUTHED `opencode models` list BEFORE any spend.
- name:Run opencode door tests (full — paid anthropic leg included)
`gbrain-allow-unscoped-getpage` for read-only first-match sites).
- **JSONB: never `JSON.stringify` into a `::jsonb` cast.** postgres.js double-encodes it (a jsonb
string scalar); PGLite hides the bug. This bites BOTH spellings — the template form
(`${JSON.stringify(x)}::jsonb`) AND the positional form (`executeRaw(\`…$N::jsonb\`, [JSON.stringify(x)])`,
@@ -70,7 +75,11 @@ Per-file detail is in `docs/architecture/KEY_FILES.md`.
- **Engine-live paths avoid runtime dynamic `import()` for helper dependencies.** In
`src/core/pglite-engine.ts`, `src/core/postgres-engine.ts`, and
`src/core/migrate.ts`, dependencies previously reached through runtime dynamic
imports use static top-level imports. The only current dynamic-`import()` exceptions
imports use static top-level imports. Besides the snapshot loader's lazy
`require()` cluster in `pglite-engine.ts:tryLoadSnapshot` (fs/crypto/
migrate/pglite-schema + one gateway shape lookup — lazy so production
builds without the test-fixture path don't eager-load; the guard now
matches `require()` calls too), the only dynamic-`import()` exceptions
are the four `ai/gateway.ts` lookups in both engines'
`initSchema()` and `_upsertChunksOnce()` methods; each remains lazy inside a
local `try/catch` because the gateway has a large provider/config closure and,
@@ -101,6 +110,26 @@ Per-file detail is in `docs/architecture/KEY_FILES.md`.
(fail-closed vs warn-only vs null), not its own numbers. Pinned by `test/model-pricing.test.ts`
(drift guard asserts each view equals canonical). Embeddings price separately in
`embedding-pricing.ts` (different unit).
- **Module-size ratchet.** `scripts/module-size-limits.tsv` pins per-file line ceilings
(`check:module-size` in verify): growth over a ceiling, >50 lines of stale slack after a
shrink, a row for a deleted file, and any UNLISTED src file over 1,500 lines all fail.
Raise a ceiling only via a reviewer-visible TSV edit in the same commit; lower it in the
same commit as any peel. migrate.ts is `region-exempt` (the MIGRATIONS array grows freely;
the runner logic around it is ratcheted).
- **Peeled façades keep their surface.** operations.ts (`src/core/ops/*`), doctor.ts
(`src/commands/doctor/*`), sync.ts (`src/core/sync-*`), and both engines
(`src/core/{postgres,pglite}-engine/*`) are façades re-exporting everything they always
exported — import sites and published package exports never chase the peel. New code goes
in the module dirs, not back into the façades. Engine modules take narrow explicit deps
(never an engine-shaped bag); doctor source-text guards read `test/helpers/doctor-source.ts`,
and the flag-registry generator's `facadeExpansion` keeps peeled flag text in each command's
scan surface.
- **Coverage is measured, honestly.** CI merges per-lane lcov (`scripts/merge-lcov.ts`) into
a PR-corpus report on every run (advisory until the diff gate graduates via
`COVERAGE_GATE_ENFORCE`) and a nightly fullCorpus number incl. the full e2e glob. bun
facts: unique `--coverage-dir` per process (reuse overwrites lcov.info), line records only
(JSC omits function names), no subprocess coverage (cli.ts is exempt as a documented
undercount), never-loaded files are a count+list, never fake all-files math.
## Reference map (load on demand)
@@ -481,7 +510,7 @@ ms, max waiters) for `--json`; a one-line summary prints to stderr.
## Version locations (single source of truth: `VERSION` file)
Every release advances the version in **six files at once**. Keep these in
Every release advances the version in **seven files at once**. Keep these in
sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
package.json drift), but the canonical list lives here so future runs and
the auto-update agent know where to look.
@@ -497,7 +526,7 @@ four numeric segments are required first. Historical 3-segment versions
(`0.31.3`, `0.22.1`) remain valid in `git log` and migration filenames
(`skills/migrations/v0.21.0.md`); do NOT rewrite them. Going forward only.
**Required (every release must update all six):**
**Required (every release must update all seven):**
| File | What lives there | Format |
|---|---|---|
@@ -506,12 +535,19 @@ four numeric segments are required first. Historical 3-segment versions
| `CHANGELOG.md` | Top entry header `## [0.31.4.1] - YYYY-MM-DD` plus the "To take advantage of v0.31.4.1" block. | Standard Keep-a-Changelog header. |
| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z.W" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z.W` references in TODO bodies. |
| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z.W (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z.W (#NNN, contributed by @user)` references. |
| `openclaw.plugin.json` | OpenClaw plugin manifest (v0.45.6.0, #4033). Hand-maintained; `test/openclaw-plugin-manifest.test.ts` fails the suite if it drifts from `package.json`. Merges from master auto-resolve it to master's version — re-bump it with the trio. | `"version": "0.45.8.0"` |
| `openclaw.plugin.json` | OpenClaw plugin manifest (v0.45.6.0, #4033). Hand-maintained; `test/openclaw-plugin-manifest.test.ts` fails the suite if it drifts from `package.json`. Merges from master auto-resolve it to master's version — re-bump it with the trio. | `"version": "0.45.12.0"` |
| `.codex-plugin/plugin.json` + `.claude-plugin/plugin.json` | Codex + Claude Code plugin manifests. Hand-maintained; `test/codex-plugin-manifest.test.ts` fails the suite when either drifts from `package.json` (the bump is now a FIVE-file lockstep: VERSION, package.json, openclaw.plugin.json, and both plugin manifests). Merges from master auto-resolve them to master's version — re-bump with the version set. | `"version": "0.46.7.0"` |
| `BOOTSTRAP_FOR_AGENTS.md` | Runbook stamp on line 1. `scripts/check-bootstrap-tag.sh` (in `bun run verify` + CI) fails when it drifts from `VERSION`; refresh it in the same commit as the bump. | `<!-- gbrain-runbook-stamp: X.Y.Z.W -->` |
| `templates/bootstrap/template-repo/` | Vendored template tree with an embedded version stamp. Auto-derived, but NOT by `bun install`: run `bun run scripts/generate-template-repo.ts --out templates/bootstrap/template-repo` after the bump; `scripts/check-bootstrap-templates.sh` fails CI on drift. | `<!-- gbrain-template-stamp: X.Y.Z.W -->` in generated files. |
**Auto-derived (no manual edit; refreshed by their own commands):**
- `plugin/` — the committed codex/claude plugin skill tree embeds a
`gbrain-plugin-tree-stamp: X.Y.Z.W` in its generated README, so every
version bump drifts it. Regenerate after the bump: `bun run
scripts/generate-plugin-tree.ts --out plugin` (guarded by
`scripts/check-plugin-tree.sh` in `bun run verify`; the release
`publish-codex-plugin` job also drift-gates it before publishing).
- `bun.lock` — root-package version is auto-pinned from `package.json`. After
bumping `package.json`, run `bun install` to refresh the lockfile.
@@ -15,7 +15,7 @@ The point of building a 150K-page brain is to use it as a strategic moat. To nev
It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
> **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
> **~15 minutes to a working personal agent** on the recommended Codex / Claude Code path (mostly a short interview); ~30 minutes for the always-on OpenClaw / Hermes setup. Database ready in 2 seconds either way (PGLite, no server).
> **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
@@ -79,7 +79,7 @@ GBrain is designed to be installed and operated by an AI agent. **New to GBrain?
### For Codex — the recommended first step
Turn Codex into your persistent personal agent. Works in the **ChatGPT desktop app** (open Codex on a folder) and in the **Codex CLI** (`codex` in a terminal) — same install, same result. Open Codex in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, which bootstrap creates and privacy-verifies for you. Then paste:
Turn Codex into your persistent personal agent. (Just want the brain + skills without the full agent? `codex plugin marketplace add garrytan/gbrain@codex-plugin` then `codex plugin add gbrain@gbrain` — see [docs/mcp/CODEX.md](docs/mcp/CODEX.md). The paste block below builds the whole agent.) Works in the **ChatGPT desktop app** (open Codex on a folder) and in the **Codex CLI** (`codex` in a terminal) — same install, same result. Open Codex in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, which bootstrap creates and privacy-verifies for you. Then paste:
```
Read and follow every step of:
@@ -90,7 +90,9 @@ answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Codex will ask for command approvals during the install — approving them is the sandbox working as intended. What you get, in about 15 minutes: a short interview (6 required questions) → your agent's identity (SOUL.md, USER.md, MEMORY.md) rendered from your own answers, never invented → a local PGLite brain (2 seconds, no server, no Docker) → MCP wired so every session can search and write memory → a **private** GitHub repo, created and privacy-verified, as your agent's durable body. Works with **zero API keys** — keyword search plus memory your agent writes itself; one optional key (OpenAI, Anthropic, or Voyage) upgrades to semantic search and automatic fact extraction. Codex reads brain context through its tools each turn (pull-based).
Codex will ask for command approvals during the install — approving them is the sandbox working as intended. What you get, in about 15 minutes: a short interview (6 required questions) → your agent's identity (SOUL.md, USER.md, MEMORY.md) rendered from your own answers, never invented → a local PGLite brain (2 seconds, no server, no Docker) → MCP wired so every session can search and write memory → a **private** GitHub repo, created and privacy-verified, as your agent's durable body. Works with **zero API keys** — keyword search plus memory your agent writes itself; one optional key upgrades capabilities (OpenAI: semantic search + automatic fact extraction; Voyage: semantic search; Anthropic: fact extraction). Codex reads brain context through its tools each turn (pull-based). The click moment: tell it one small thing to remember, restart Codex, then ask for it back — the answer comes from the brain, not from this chat's context (which the restart cleared). That cross-session round-trip is the whole product; "what's my name / my top jobs?" is answered from your identity files, which is nice but not the same trick.
Two things worth understanding once it's running: **you own the brain** — every memory is a markdown file in that private repo (read it, clone it to a second machine, delete it and the brain is gone) — and **the first skill to run is `cold-start`**: say "fill my brain" and your agent imports your Gmail, calendar, and contacts (via [ClawVisor](https://clawvisor.com), an OAuth vault so the agent never holds raw tokens) or offline archives like Google Takeout, one consented step at a time. An empty brain is a database; a filled one is a memory.
> **Prefer to make the repo yourself?** Create a new **empty** private repo **under your own GitHub account** (no README/.gitignore/license), clone it, open the clone in Codex, and paste the same block — bootstrap detects your empty repo and adopts it instead of creating one. The repo must be empty and personal-account-owned; org-owned repos are refused (create one under your account, or let bootstrap make it).
@@ -107,7 +109,7 @@ answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Everything from the Codex path applies — interview, identity from your own answers, local brain, private repo, keyless mode — plus Claude Code gets **per-turn context hooks**: your brain loads automatically into every prompt, and your work persists to your private repo on a per-turn cadence (debounced ~5 min locally, every turn in a cloud sandbox — this covers the `/exit` case the harness never fires a session-end hook on), with a notice on your next turn if a push ever fails. This works in a **Claude Code cloud session** too, not just on your laptop: verification falls back to pure git protocol when the sandbox blocks the GitHub API, and `gbrain bootstrap cloud-setup-script` prints the environment setup recipe. Restart the session after install and ask "what did I tell you my top jobs were?" — that's the moment it clicks. Full contract, security posture, cloud sandboxes, and uninstall: [docs/guides/bootstrap.md](docs/guides/bootstrap.md).
Everything from the Codex path applies — interview, identity from your own answers, local brain, private repo, keyless mode — plus Claude Code gets **per-turn context hooks** (on by default, with an opt-out): your brain loads automatically into every prompt, and your work persists to your private repo on a per-turn cadence (debounced ~5 min locally, every turn in a cloud sandbox — this covers the `/exit` case the harness never fires a session-end hook on), with a notice on your next turn if a push ever fails. This works in a **Claude Code cloud session** too, not just on your laptop: verification falls back to pure git protocol when the sandbox blocks the GitHub API, and `gbrain bootstrap cloud-setup-script` prints the environment setup recipe. The click moment: tell it one small thing to remember, restart the session, then ask for it back — a fresh session has no chat context, so the answer can only come from the brain. That cross-session round-trip is the whole product ("what's my name?" is answered from your identity files — nice, but not the same trick). Same two follow-ups as the Codex path: you own the brain (markdown in your private repo), and `cold-start` is the first skill to run — "fill my brain" imports your email, calendar, and contacts (ClawVisor) or offline archives, one consented step at a time. Full contract, security posture, cloud sandboxes, and uninstall: [docs/guides/bootstrap.md](docs/guides/bootstrap.md).
> **Prefer to make the repo yourself?** Create a new **empty** private repo **under your own GitHub account** (no README/.gitignore/license), clone it, open the clone in Claude Code (CLI or the desktop app's open-a-repo flow), and paste the same block — bootstrap adopts your empty repo instead of creating one. The repo must be empty and personal-account-owned; org-owned repos are refused.
@@ -167,9 +169,13 @@ Postgres-at-scale, Supabase, and thin-client setup paths live in [`docs/INSTALL.
GBrain exposes nearly all of its 100+ operations as MCP tools (stdio and HTTP; a handful of local-only ops stay CLI-side) — or exactly the seven memory verbs with `--surface verbs`. The specific snippet depends on which client you use:
- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — local: one command,`claude mcp add gbrain -- gbrain serve` (zero server, zero tunnel). Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).
- **[Codex](docs/mcp/CODEX.md)** — `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`). Codex reads the bearer from `$GBRAIN_REMOTE_TOKEN` at runtime, so the token never lands in Codex config.
- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — plugin: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain` (MCP + skills). Or local one-liner:`claude mcp add gbrain -- gbrain serve` (zero server, zero tunnel). Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).
- **[Codex](docs/mcp/CODEX.md)** — plugin (recommended): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain` installs the MCP server AND the curated skill set. Or connect-only:`gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`); Codex reads the bearer from `$GBRAIN_REMOTE_TOKEN` at runtime, so the token never lands in Codex config.
- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve"]}` to your MCP config.
- **[Hermes](docs/mcp/HERMES.md)** — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve`. Keep `--args` last, and verify with `hermes mcp test gbrain` (the add exits 0 even on failure).
- **[Grok Build](docs/mcp/GROK.md)** — `grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- gbrain serve --surface verbs`. The add is lazy (exit 0 without connecting) — verify with `grok mcp doctor gbrain`, which spawns the server and reports `7 tools discovered`. Verified against Grok Build v1.0.4.
- **[opencode](docs/mcp/OPENCODE.md)** (opencode.ai / SST — not OpenClaw) — `opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- gbrain serve --surface verbs`, or let `gbrain bootstrap hooks --harness opencode` write the config for you (opencode is a bootstrap-supported harness — it reads AGENTS.md natively). The add is lazy — verify with `opencode mcp list`, which spawns the server (`✓ gbrain connected`). Remote: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]` — the config stores only the `{env:GBRAIN_REMOTE_TOKEN}` interpolation. Verified against opencode v1.18.18.
- **[OpenClaw](docs/mcp/OPENCLAW.md)** — the ClawHub bundle plugin registers gbrain automatically (`openclaw.plugin.json` ships in this repo), or add `{"command": "gbrain", "args": ["serve"]}` to `~/.openclaw/config.json`'s `mcpServers`.
- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.
- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.
- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — `gbrain connect https://your-host/mcp --agent perplexity --oauth --register` mints a least-privilege OAuth client and prints the Issuer/Client ID/Secret to paste into Settings → Connectors (OAuth is the right path for a cloud connector; a bearer token also works for local use). Pro subscription required.
@@ -230,6 +236,21 @@ curl -X POST https://your-brain/ingest \
For mobile capture, the inbox folder source picks up anything dropped into
`~/.gbrain/inbox/` from iOS Shortcuts / AirDrop / Drafts / Finder.
Your other agents' histories import in one command. `gbrain transcripts ingest`
gbrain transcripts status # found vs imported, per harness
```
Third-party skillpacks can ship custom ingestion sources (Granola, Linear,
voice, OCR) against the versioned `IngestionSource` contract at
`gbrain/ingestion`. See [`docs/skillpack-anatomy.md`](docs/skillpack-anatomy.md).
@@ -287,11 +308,11 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec
## Capabilities
**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). The install picker default-applies `tokenmax` (it recommends `conservative` for Haiku-class subagent tiers or keyless setups); a brain with `search.mode` unset resolves to `balanced` at query time. The ZeroEntropy reranker is on in `balanced` and `tokenmax`, off in `conservative`. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns. Vector retrieval pools the best chunk per page, so a page surfaces on its strongest evidence instead of losing to a neighbor on one weak chunk. Queries that match a page's title phrase or a declared free-text alias (`gbrain reindex --aliases` backfills existing pages) get boosted to the page they name. Every result carries an `evidence` tag (why it matched) and a `create_safety` hint (`exists` / `probable` / `unknown`) so an agent decides whether a page already exists instead of guessing from a raw score. `gbrain search diagnose "<query>" --target <slug>` traces which retrieval layer surfaces (or misses) a page.
**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). The install picker default-applies `tokenmax` (it recommends `conservative` for Haiku-class subagent tiers or keyless setups); a brain with `search.mode` unset resolves to `balanced` at query time. The cross-encoder reranker is on in `balanced` and `tokenmax`, off in `conservative` — new installs get Voyage `rerank-2.5`; brains that never set `search.reranker.model` still fall back to the deprecated ZeroEntropy `zerank-2` (hosted API ends 2026-09-04) until the September cutover. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns. Vector retrieval pools the best chunk per page, so a page surfaces on its strongest evidence instead of losing to a neighbor on one weak chunk. Queries that match a page's title phrase or a declared free-text alias (`gbrain reindex --aliases` backfills existing pages) get boosted to the page they name. Every result carries an `evidence` tag (why it matched) and a `create_safety` hint (`exists` / `probable` / `unknown`) so an agent decides whether a page already exists instead of guessing from a raw score. `gbrain search diagnose "<query>" --target <slug>` traces which retrieval layer surfaces (or misses) a page.
**Self-wiring knowledge graph.** Every `put_page` extracts entity refs from markdown/wikilinks/typed-link syntax and writes edges with zero LLM calls. Typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, …). Multi-hop traversal via `gbrain graph-query`. The graph is what produces the +31.4 P@5 lift over vector-only RAG. **Obsidian-style vaults:** bare `[[note-name]]` wikilinks that point across folders — you wrote `[[struktura]]` but the page lives at `projects/struktura.md` — resolve by basename once you opt in with `gbrain config set link_resolution.global_basename true`. Off by default; `gbrain doctor` tells you how many edges you'd gain before you flip it. See [migrating an Obsidian vault](INSTALL_FOR_AGENTS.md#step-45-wire-the-knowledge-graph).
**Job queue (Minions).** BullMQ-shaped, Postgres-native job queue. Durable subagents (LLM tool loops that survive crashes via two-phase pending→done persistence), shell jobs with audit, child jobs with cascading timeouts, rate leases for outbound providers, attachments via S3/Supabase storage. Replaces "spawn subagent as fire-and-forget Promise" with something that recovers from anything.
**Job queue (Minions).** BullMQ-shaped, Postgres-native job queue. Durable subagents (LLM tool loops that survive crashes via two-phase pending→done persistence), shell jobs with audit, child jobs with cascading timeouts, rate leases for outbound providers, attachments via S3/Supabase storage. Opt-in per-job process isolation (`gbrain jobs work --job-isolation process`) runs each claimed job in its own SIGKILL-able child process, so a stuck handler dies for real and a crash takes one job instead of the whole worker; when the worker's DB health probe fails, it names the failing layer (`pool_starved` vs `server_unreachable`) instead of a blanket "DB unreachable". Sizing and rollout guidance in [`docs/guides/minions-deployment.md`](docs/guides/minions-deployment.md); probe-verdict triage in [`docs/guides/queue-operations-runbook.md`](docs/guides/queue-operations-runbook.md). Replaces "spawn subagent as fire-and-forget Promise" with something that recovers from anything.
**Non-English brains (FTS language config).** The Postgres full-text search tokenizer is configurable via `GBRAIN_FTS_LANGUAGE`. Defaults to `english`. Set it to any text-search configuration that exists in your Postgres instance:
@@ -325,8 +346,8 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
- **Email + calendar**: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md).
- **Embedding providers**: a dozen providers covered — OpenAI (default fallback), OpenRouter, Voyage, ZeroEntropy (default), Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy. Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md).
- **Rerankers**: ZeroEntropy`zerank-2` hosted (the default; on in `balanced` and `tokenmax` modes) plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp — runs Qwen3-Reranker or self-hosted ZeroEntropy weights against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).
- **Embedding providers**: a dozen providers covered — Voyage (default: `voyage-4` @ 1024d), OpenAI, OpenRouter, Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy, plus ZeroEntropy (deprecated — hosted API ends 2026-09-04). Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md).
- **Rerankers**: Voyage`rerank-2.5` hosted (the new-install default; reranking is on in `balanced` and `tokenmax` modes, same `VOYAGE_API_KEY` as embeddings), ZeroEntropy `zerank-2` (deprecated — hosted API ends 2026-09-04; still the fallback for brains that never set `search.reranker.model`), plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp — runs Qwen3-Reranker or self-hosted zerank weights against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).
- **MCP clients**: every major MCP client is supported. [`docs/mcp/`](docs/mcp/) per-client setup.
@@ -344,7 +365,7 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
**PGLite crashes at startup with `RuntimeError: Aborted()` (often right after a macOS upgrade)?** Not a macOS incompatibility — the OS-upgrade reboot killed gbrain mid-write and tore the data dir's WAL. gbrain now repairs this automatically on the next command (data preserved, backup kept); if auto-repair is disabled or skipped, run `gbrain pglite-repair --dry-run` to diagnose and `gbrain pglite-repair --yes` to repair in place. Full recovery ladder (repair → rebuild → engine switch) in [`docs/ENGINES.md` — Troubleshooting: startup abort](docs/ENGINES.md#troubleshooting-startup-abort-runtimeerror-aborted) and [`docs/INSTALL.md`](docs/INSTALL.md#pglite-crashes-on-macos-26x-tahoe).
**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment: set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain migrate embeddings` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys: set `VOYAGE_API_KEY` (or `OPENAI_API_KEY` / another provider key) in the environment — or in `~/.gbrain/config.json`, which init also reads — before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker (non-TTY auto-picks the Voyage default when its key is present). With no keys at all, init continues keyless (keyword-only search) with a loud notice; add a key later and re-run `gbrain init --force --embedding-model voyage:voyage-4` to enable embeddings, or pass `--no-embedding` up front to make keyless explicit. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
**Hourly cron sync keeps timing out on a federated brain?** Switch your
cron to a per-source loop with shell `timeout(1)` doing the OS-level kill
@@ -462,7 +483,7 @@ the page PK, soft-delete-filtered, source-safe) and completes in seconds.
## Docs
- [`docs/INSTALL.md`](docs/INSTALL.md) — every install path, end to end
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — the persistent-personal-agent bootstrap contract (interview, identity files, hooks, private repo, security posture, uninstall), plus local harness mode (`gbrain bootstrap harness`) for wiring framework-spawned Claude Code/Codex sessions to a running serve
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — why schemas matter: 7 killer use cases, the structural argument for typed page kinds, the agent-co-curates pattern (v0.40.7.0)
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5-minute walkthrough: fork the bundled pack, add a custom type, backfill existing pages, prove the wiring via `gbrain whoknows`
- [`docs/architecture/`](docs/architecture/) — system design, topologies, retrieval theory
@@ -474,7 +495,7 @@ the page PK, soft-delete-filtered, source-safe) and completes in seconds.
- [`AGENTS.md`](AGENTS.md) — entry point for non-Claude agents
- [`CLAUDE.md`](CLAUDE.md) — entry point for Claude Code (deep operating context)
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor guide, test discipline, eval-capture mode
Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that ships as the default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that shipped as the default from v0.36 through v0.46. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
@@ -26,7 +26,7 @@ Your agent now reads `skills/RESOLVER.md` once per request, routes intent to the
Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference <name>` diffs your local copy vs the bundle. The legacy `skillpack install` managed-block model was retired in v0.36.0.0; if you're upgrading from an older release, run `gbrain skillpack migrate-fence` once to strip the legacy fence and keep your existing skill rows.
To upgrade later: `gbrain upgrade` runs schema migrations + post-upgrade prompts (chunker bumps, the v0.36.2.0 ZeroEntropy switch). Always TTY-only; non-TTY upgrades skip prompts with informational stderr lines.
For shared / large / multi-machine deployments (a team or company brain with multiple users hitting one server over HTTP MCP with OAuth scoping per user), follow the dedicated walkthrough: **[Tutorial: set up GBrain as your company brain](tutorials/company-brain.md)**.
API keys live in `~/.gbrain/config.json` (file plane) or env vars (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ZEROENTROPY_API_KEY`, `VOYAGE_API_KEY`, `ANTHROPIC_API_KEY`). Set via CLI:
API keys live in `~/.gbrain/config.json` (file plane) or env vars (`VOYAGE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`). Set them via env or by editing `~/.gbrain/config.json` directly — do NOT use `gbrain config set` for API keys (that writes the DB plane, which the embedding pipeline never reads):
exportOPENAI_API_KEY=sk-... # alternative embeddings; also used for chat models
exportANTHROPIC_API_KEY=sk-ant-... # optional, improves search via query expansion
```
`ZEROENTROPY_API_KEY` is still honored but deprecated — the ZeroEntropy hosted API shuts down 2026-09-04. Off-ramp: the agent playbook at [`skills/migrations/v0.46.3.0.md`](../skills/migrations/v0.46.3.0.md) (one command migrates embeddings + reranker) with the full reference in [`docs/guides/embedding-migration.md`](guides/embedding-migration.md).
Common follow-ups:
```bash
@@ -71,7 +73,7 @@ claude mcp add gbrain -- gbrain serve --surface verbs # Claude Code
The agent spawns `gbrain serve` as a stdio subprocess against your local brain. `--surface verbs` gives the agent the five-verb memory protocol (`recall`, `remember`, `entity`, `synthesize`, `forget` — [MEMORY_VERBS v1](protocol/MEMORY_VERBS_v1.md)) instead of the full tool catalog; drop the flag (default `full`) for every operation. Full walkthrough (both this local path and connecting to a remote brain), plus the brain-first protocol to paste into `CLAUDE.md` / `AGENTS.md`: **[Give your coding agent a memory](tutorials/connect-coding-agent.md)**.
The agent spawns `gbrain serve` as a stdio subprocess against your local brain. `--surface verbs` gives the agent the seven-verb memory protocol (`recall`, `remember`, `entity`, `synthesize`, `forget`, `context_pack`, `delta` — [MEMORY_VERBS v1](protocol/MEMORY_VERBS_v1.md)) instead of the full tool catalog;`--surface starter` adds the daily-driver set on top of the verbs (~27 ops total); drop the flag (default `full`) for every operation. Full walkthrough (both this local path and connecting to a remote brain), plus the brain-first protocol to paste into `CLAUDE.md` / `AGENTS.md`: **[Give your coding agent a memory](tutorials/connect-coding-agent.md)**.
## 3. MCP server (any MCP client)
@@ -99,6 +101,11 @@ Per-client setup guides live in [`docs/mcp/`](mcp/):
- [`docs/mcp/OPENCLAW.md`](mcp/OPENCLAW.md) — OpenClaw (bundle plugin or stdio)
- [`docs/mcp/CLAUDE_COWORK.md`](mcp/CLAUDE_COWORK.md) — Claude Cowork (team plan)
- [`docs/mcp/DEPLOY.md`](mcp/DEPLOY.md) — production deploy patterns
The HTTP server ships with an admin SPA at `/admin`, an SSE activity feed at `/admin/events`, DCR-style client registration, scope-gated `read`/`write`/`admin` access, and rate limiting.
@@ -11,13 +11,79 @@ Seven test command tiers, each with a clear scope:
| Command | What it runs | Wallclock | When to use |
|---|---|---|---|
| `bun run test` | Parallel unit-test fast loop. Sharded fan-out via `scripts/run-unit-parallel.sh` (default 4 shards — CPU-detected, clamped to a max of 8; 4 matches CI's fan-out and avoids PGLite WASM-init contention), then a serial pass over `*.serial.test.ts`. Excludes `*.slow.test.ts` and `test/e2e/*`. No pre-checks, no typecheck. Memory-safe by default: total concurrency (shards × intra-shard files) is capped to available memory at `GBRAIN_TEST_MEM_PER_FILE_MB` (default 1536 — a PGLite WASM instance) per concurrent file, and two phantom-failure classes are automatically re-run serially (the rescue pass): failures carrying the WASM out-of-memory signature, and shards killed externally (SIGTERM/SIGKILL well before the shard timeout — sibling workspaces' process cleanup, memory jetsam). Phantoms pass serially and the run goes green with an `oom_rescued` note; real failures fail again serially and stay red. Knobs: `GBRAIN_TEST_NO_MEM_ADAPT=1`, `GBRAIN_TEST_NO_OOM_FALLBACK=1`, `GBRAIN_TEST_MAX_CONCURRENCY` (intra-shard, default 4), `GBRAIN_TEST_SHARD_TIMEOUT` / `GBRAIN_TEST_SHARD_KILL_AFTER`, plus `--shards N` / `--max-concurrency N` / `--dry-run` script args. | a few minutes on a Mac dev box | Inner edit loop. Default. |
| `bun run verify` | CI's authoritative pre-test gate set, fanned out in parallel by `scripts/run-verify-parallel.sh`: the full`check:*` battery (privacy, jsonb, progress, source-id, test-isolation, wasm, …) plus `bun run typecheck`. The `CHECKS` array in that script is the single source of truth — CI literally calls `bun run verify` in a dedicated job. | ~16s (parallel; typecheck dominates) | Before pushing; before `/ship`. |
| `bun run test` | Parallel unit-test fast loop. Sharded fan-out via `scripts/run-unit-parallel.sh` (default 4 shards — CPU-detected, clamped to a max of 8; 4 matches CI's fan-out and avoids PGLite WASM-init contention), then a serial pass over `*.serial.test.ts`. Excludes `*.slow.test.ts` and `test/e2e/*`. No pre-checks, no typecheck. Builds/refreshes the PGLite schema snapshot BEFORE the shard fan-out and exports `GBRAIN_PGLITE_SNAPSHOT` so PGLite-booting files restore a baked schema instead of replaying every migration (~3.5x per booting file; see "PGLite schema snapshot" below). Opt out: `GBRAIN_NO_SNAPSHOT=1`. Memory-safe by default: total concurrency (shards × intra-shard files) is capped to available memory at `GBRAIN_TEST_MEM_PER_FILE_MB` (default 1536 — a PGLite WASM instance) per concurrent file, and two phantom-failure classes are automatically re-run serially (the rescue pass): failures carrying the WASM out-of-memory signature, and shards killed externally (SIGTERM/SIGKILL well before the shard timeout — sibling workspaces' process cleanup, memory jetsam). Phantoms pass serially and the run goes green with an `oom_rescued` note; real failures fail again serially and stay red. Knobs: `GBRAIN_TEST_NO_MEM_ADAPT=1`, `GBRAIN_TEST_NO_OOM_FALLBACK=1`, `GBRAIN_TEST_MAX_CONCURRENCY` (intra-shard, default 4), `GBRAIN_TEST_SHARD_TIMEOUT` / `GBRAIN_TEST_SHARD_KILL_AFTER`, plus `--shards N` / `--max-concurrency N` / `--dry-run` script args. | a few minutes on a Mac dev box | Inner edit loop. Default. |
| `bun run verify` | CI's authoritative pre-test gate set, fanned out by `scripts/run-verify-parallel.sh` through a bounded worker pool (default`detect_cpus`; override `GBRAIN_VERIFY_MAX_PARALLEL`) with the heavy checks ordered first (typecheck, the two compile-embed checks, admin build, fuzz bundles, guard self-tests, the PGLite-booting eval checks, whole-tree greps). The battery includes the deterministic `check:eval-chronicle` and `check:eval-canary` eval gates. The `CHECKS` array in that script is the single source of truth — CI literally calls `bun run verify` in a dedicated job. | ~40s (pool-bounded; longest check dominates) | Before pushing; before `/ship`. |
| `bun run test:full` | `verify && bun run test && bun run test:slow && [smart e2e]`. The local equivalent of "everything CI runs." Smart e2e: runs e2e only when `DATABASE_URL` is set; else loud skip notice to stderr. | ~3-5min depending on slow + e2e | Pre-merge sanity, before opening a PR. |
| `bun run test:slow` | Just the `*.slow.test.ts` set (intentional cold-path correctness checks). | seconds-to-minutes | When touching slow-path code. |
| `bun run test:serial` | Just the `*.serial.test.ts` set (cross-file-contention quarantine; one bun process per file for true module-registry isolation). | ~1s per quarantined file | Debugging a specific quarantined file. |
| `bun run test:serial` | Just the `*.serial.test.ts` set (cross-file-contention quarantine; one bun process per file for true module-registry isolation), run through a POOL of concurrent per-file processes — the isolation is per-process, not per-machine. Pool defaults to `min(detect_cpus, 4)` then memory-adapts (same doctrine as the parallel runner); a small growth-guarded set of files (machine-global state or contention-critical timing — see the justified `EXCLUSIVE_FILES` list in `scripts/run-serial-tests.sh`, capped at 3 by `test/scripts/serial-files.test.ts`) runs on a sequential EXCLUSIVE lane after the pool. Per-test timeout 120s (pooled contention headroom); each pooled file is wall-clock-killed at 300s (`timeout -k`, exit-hang containment). Externally-killed files (exit 143/137 or a missing exit sentinel — sibling-workspace cleanup, memory jetsam) get ONE sequential rescue re-run, mirroring the parallel runner's doctrine: phantoms stay green with a rescue note, real failures stay red. Prints per-file PASS lines plus a top-10 slowest-files list. Knobs: `GBRAIN_SERIAL_POOL=N` (explicit pool width — bypasses the memory clamp; `1` restores fully-sequential), `GBRAIN_SERIAL_FILE_TIMEOUT`. | ~2.5min for all ~140 files at pool=4 (was ~8.5min sequential) | Debugging quarantined files; CI's serial-tests job. |
| `bun run test:e2e` | Real Postgres E2E. Requires Docker + `DATABASE_URL`. Sequential. | ~5-10min | Pre-ship; nightly. |
| `bun run check:all` | The historical pre-check scripts (chained sequentially in package.json). Overlaps `verify` heavily but is NOT a superset — `verify`'s `CHECKS` array in `scripts/run-verify-parallel.sh` is the authoritative gate; `check:all` keeps a few local-only extras (trailing-newline, exports-count, no-legacy-getconnection). | ~10s | Local-only sweep for the extras. |
| `bun run test:compile-smoke` | Self-update integrity verify under a REAL `bun build --compile` binary, offline (sets `GBRAIN_SELFUPDATE_COMPILE_SMOKE=1`). The unit suite mocks the network seams; this proves the dependency-free crypto/base64/JSON verifypath survives compilation — the failure mode `sigstore-js` would have hit. | ~5s (one compile) | When touching `src/core/binary-self-update.ts`; pre-ship on self-update changes. |
There is no `check:all` script anymore — it was a second, hand-synced guard
registry that drifted from `verify` (three checks were reachable ONLY from it,
i.e. never ran anywhere). The `CHECKS` array in `scripts/run-verify-parallel.sh`
is the single execution list, and it now includes the former `check:all`-only
on an atomic `mkdir` lock (`test/fixtures/.pglite-snapshot.lock`) with
staleness-verified takeover of a crashed builder; the tar is written first
and the version file last, so a crash can never leave a fresh-looking torn
fixture. `GBRAIN_SNAPSHOT_LOCK_TIMEOUT_MS` (default 120000) bounds the
waiter; an exhausted waiter facing a still-live lock proceeds unlocked as a
last resort (the loader gate below validates the version file, not the tar
bytes).
- **Never authoritative.** The loader (`tryLoadSnapshot` in
`src/core/pglite-engine.ts`) verifies the schema hash AND the embedding
shape the snapshot was baked with (`dims=` / `model=` lines in the version
file) against what this process would create; any mismatch — including a
version file without shape lines — warns once and falls through to normal
cold init. A wrong fixture can never poison the suite.
- **Opt out.** `GBRAIN_NO_SNAPSHOT=1` skips the build + env export for a run;
the migration-replay canary tests clear the env themselves regardless.
Pinned by `test/snapshot-shape-guard.test.ts` (hash + shape refusal matrix,
handler-source hash sensitivity).
### Guard registry and self-test
`scripts/guards-manifest.tsv` is THE single registry of `scripts/check-*`
guards (currently 48), each classified `scanner` (greps/parses repo sources —
must eventually carry fixtures), `buildfresh`, or `repostate` (build/freshness
guards are exempt-with-reason, not fixture-tested).
`scripts/guard-self-test.sh` (`bun run check:guard-self-test`, wired into
`bun run verify`) proves every `selftest=yes` scanner CAN fail: it runs each
one against known-bad (must exit non-zero) and known-good (must pass) fixture
trees under `test/fixtures/guards/<guard>/{bad,good}/` via the
`GBRAIN_GUARD_ROOT` env seam, and enforces manifest completeness — a new
`scripts/check-*` script that isn't registered in the manifest fails the
build. A guard whose pattern rots into a permanently-green no-op now fails CI
instead of masquerading as coverage.
### Shell dispatch and Windows
@@ -47,11 +113,119 @@ there even though they pass on Linux and macOS.
### CI vs local: intentionally divergent file sets
- **CI matrix** (`.github/workflows/test.yml`) runs `scripts/test-shard.sh` across 10 matrix shards partitioned by weight-aware LPT bin-packing (`scripts/sharding.ts`) and INCLUDES `*.slow.test.ts` (the two outlier slow files run as dedicated jobs alongside the matrix). CI EXCLUDES `*.serial.test.ts` from the shards and runs them in a dedicated job via `bun run test:serial`, one bun process per file — keeping serial files out of the shard processes is what preserves the `mock.module` quarantine (a top-level mock in one file leaks into every other file sharing its process). `bun run verify` gets its own job too, as does the BrainBench memory-conformance gate (`brainbench` job → `scripts/ci-brainbench-gate.sh`, hermetic in-memory PGLite, ~15s), which compares HEAD's fresh run against master's committed baseline (`evals/brainbench/baselines/main.json`) — the `test-status` aggregate checks its result explicitly. CI is the ground truth for "did everything pass."
- **CI matrix** (`.github/workflows/test.yml`) runs `scripts/test-shard.sh` across 10 matrix shards partitioned by weight-aware LPT bin-packing (`scripts/sharding.ts`; files with no mined weight fall back to the p75 file weight so a new unweighted file can't silently unbalance a shard) and INCLUDES `*.slow.test.ts` (the two outlier slow files run as dedicated jobs alongside the matrix) plus `evals/**/*.test.ts` (keyless-allowlist-gated — `test/scripts/evals-collection.test.ts`). Each shard's bun process is bounded by `--max-concurrency` (`GBRAIN_TEST_MAX_CONCURRENCY`, default 4). Every bun-test job — matrix shards, serial-tests, verify, the slow/eval jobs — activates the PGLite schema snapshot (built in-runner via `scripts/lib/test-env.sh`; the brainbench gate brings its own in-memory PGLite and skips it; the ~42MB tar is also cached across jobs via actions/cache, with the runner's own hash check staying authoritative). CI EXCLUDES `*.serial.test.ts` from the shards and runs them in the pooled `serial-tests` job via `bun run test:serial` — one bun process per file preserves the `mock.module` quarantine; the pool runs those processes concurrently. `bun run verify` gets its own job too, as does the BrainBench memory-conformance gate (`brainbench` job → `scripts/ci-brainbench-gate.sh`, hermetic in-memory PGLite, ~15s), which compares HEAD's fresh run against master's committed baseline (`evals/brainbench/baselines/main.json`) — the `test-status` aggregate checks its result explicitly. E2E (`.github/workflows/e2e.yml`) mirrors the content-hash skip in its own `e2e-pass-<hash>` namespace (scheduled nightly runs are exempt and always run), runs tier1 and tier2 in parallel with the jsonb-parity job in front of tier2 as the token-spend gate, and aggregates through `e2e-status`. CI is the ground truth for "did everything pass."
- **Local fast loop** (`scripts/run-unit-shard.sh` via the parallel wrapper) uses round-robin-by-index sharding and EXCLUDES `*.slow.test.ts` AND `*.serial.test.ts`. Local trades coverage for inner-loop speed; CI catches what local skips.
This divergence is intentional. Don't try to make them equal — the two scripts deliberately solve different problems. The regression test at `test/scripts/run-unit-shard.test.ts` pins what the local fast loop should and shouldn't include; `test/scripts/run-unit-parallel.test.ts` pins the wrapper's memory-adaptive concurrency and the OOM/external-kill serial rescue pass.
### Coverage lanes and gates
Line coverage is opt-in via `COVERAGE_DIR`: when set, the shell lanes
scripts/structural-suites.tsv` adds the behavioral-vs-structural split to the
rendered summary (both CI lanes pass it); `classify-tests.ts --summary` prints
counts only.
### Failure-first logging
When `bun run test` finds any failure, the wrapper:
@@ -72,11 +246,40 @@ Triage rule: a `warn-pass` EXIT-HANG line in `.context/test-summary.txt` is NOT
-`*.test.ts` → fast loop (parallel up-to-4-shard fan-out, memory-adaptive).
-`*.slow.test.ts` → run via `bun run test:slow` only (intentional cold-path tests; would dominate the fast loop's wallclock).
-`*.serial.test.ts` → run via `bun run test:serial` after the parallel pass completes; one bun process per file (`--max-concurrency=1` within a shared process is not enough — the module registry still leaks `mock.module`). Quarantine for tests that share file-wide state and race when run alongside other files in the same `bun test` process. Several dozen files, discovered by the `*.serial.test.ts` glob — no list to maintain. Typical residents: `mock.module(...)` users (top-level mocks leak across files in a shard process, e.g. `test/embed.serial.test.ts`), env-coupled files (e.g. `test/brain-registry.serial.test.ts`), and process-lifecycle suites that assert on `process.exitCode` (e.g. `test/pglite-engine-disconnect.serial.test.ts`). **Do not put the parallelism back on a serial file unless you've fixed the contention root cause** (it just re-introduces the flake).
-`test/e2e/*.test.ts` → real-Postgres E2E. Skipped when `DATABASE_URL` is unset.
-`*.serial.test.ts` → run via `bun run test:serial` after the parallel pass completes; one bun process per file (`--max-concurrency=1` within a shared process is not enough — the module registry still leaks `mock.module`), with those per-file processes POOLED (per-process isolation never required one-at-a-time execution). Files touching machine-global state (launchd/cron) live on the sequential `EXCLUSIVE_FILES` lane inside `scripts/run-serial-tests.sh` — growth-guarded to ≤3 entries with justification comments. Quarantine for tests that share file-wide state and race when run alongside other files in the same `bun test` process. Several dozen files, discovered by the `*.serial.test.ts` glob — no list to maintain. Typical residents: `mock.module(...)` users (top-level mocks leak across files in a shard process, e.g. `test/embed.serial.test.ts`), env-coupled files (e.g. `test/brain-registry.serial.test.ts`), and process-lifecycle suites that assert on `process.exitCode` (e.g. `test/pglite-engine-disconnect.serial.test.ts`). **Do not put the parallelism back on a serial file unless you've fixed the contention root cause** (it just re-introduces the flake).
-`test/e2e/*.test.ts` → real-Postgres E2E. Skipped when `DATABASE_URL` is unset. One out-of-directory file rides this lane: `test/phantom-redirect-engine-parity.test.ts` (lives in `test/` for its PGLite arm, but its Postgres arm is only reachable through a DATABASE_URL-bearing lane — the unit wrappers strip the URL per #3485, so `run-e2e.sh`'s no-args list and CI's parity job carry it). `run-e2e.sh` wraps each file in a hard outer timeout (default 180s; `GBRAIN_E2E_FILE_TIMEOUT=<seconds>` overrides) because a synchronously-blocking PGLite WASM call can outlive bun's timer-based `--timeout`; LLM-bound Tier-2 files (`skills.test.ts`, `zeroentropy-live.test.ts`) automatically get 4× the cap since real provider round-trips legitimately run past 180s.
-`tests/heavy/*.sh` → ops-shape shell scripts. Cost minutes per run; NOT in default `bun test`. Run via `bun run test:heavy` or scheduled nightly via `.github/workflows/heavy-tests.yml`. Examples: pg_upgrade matrix (boot legacy brain → walk to head), RSS budget gate (measure peak worker RSS vs committed baseline), read-latency-under-sync (p50/p95/p99 under concurrent writer load), sync lock regression (N concurrent syncs assert 1 winner + N-1 lock-busy + zero leaked `gbrain_cycle_locks` rows). See `tests/heavy/README.md` for when to add a script here vs `*.slow.test.ts`. Files prefixed with `_` (e.g. `tests/heavy/_build_legacy_fixtures.sh`) are helpers/libs invoked by sibling tests — the runner skips them.
-`test/fuzz/*.test.ts` → property-based fuzz harness. Pure-validator targets in `pure-validators.test.ts` are guarded by `scripts/check-fuzz-purity.sh` (in `bun run verify`), which `bun build --target=bun` bundles each target and greps the resulting bundle for banned transitive imports (`node:fs`, `node:child_process`, engine modules). Anything that fails the guard moves to `mixed-validators.test.ts` (still property-tested, but no purity guarantee) or `filesystem-validators.test.ts` (fs-backed, uses temp dirs). Fuzz tests run in the default `bun test` loop because they're fast (~3s for ~12 properties × 1000 runs each).
The taxonomy above is LANE-based (where a test runs). A second, orthogonal axis is INTENT:
- **Behavioral** tests execute product code and assert on behavior — the default.
- **Structural** (source-shape) suites read repo source/doc TEXT and assert on its shape (wiring guards, drift pins, `doctorSource()` consumers). They are real invariants but execute no product paths, so they inflate the headline test count without adding line coverage. The committed inventory is `scripts/structural-suites.tsv`, generated by `scripts/classify-tests.ts` (suite-level, content-based detectors: repo-anchored `readFileSync`/`Bun.file` readers, grep-style exec scanners, the doctor-source helpers) and freshness-checked in `bun run verify` (`check:structural-manifest` — regenerate with `bun scripts/classify-tests.ts` when suites change shape). The inventory is approximate by design; fix misclassifications in the classifier's detector list, never by hand-editing the TSV. CI's coverage report renders behavioral vs structural counts side by side.
Guards that pin doctor source text read it through `test/helpers/doctor-source.ts` (`doctorSource()` = the façade + every `src/commands/doctor/**` module, for containment assertions; `doctorFileSource(rel)` = one named file, for positional/ordering assertions) so peeling doctor.ts into modules can't silently move a pinned string out of a guard's sight.
### TTY and interactive-CLI testing
Four escalating tools; reach for the cheapest one that answers the question:
| Question | Tool | Example |
|---|---|---|
| Does the TTY/non-TTY branch logic pick right? | Inject `isTTY` into the pure function — no subprocess | `test/init-provider-picker.test.ts`, `test/jobs-watch-mode.test.ts` |
| Does the real CLI behave right when stdin is NOT a terminal? | Spawn the CLI with piped/ignored stdio | `test/cli-stdin-hang.test.ts` (fast loop); `test/e2e/init-fresh-pglite.test.ts` (manual `test:e2e` lane — see the TODOS e2e CI-lane entry) |
| Does the real CLI render menus and read typed input under a REAL terminal? | `launchTty` from `test/helpers/tty-harness.ts` in a `*.serial.test.ts` file | `test/init-picker-pty.serial.test.ts` |
| How does the install FEEL (stalls, copy, silence windows)? | `scripts/dx-explore.ts` — instrument, not a test; nothing asserts | transcripts under `.context/dx-runs/` (see `docs/guides/bootstrap.md`) |
Real-PTY test rules: put the file in the serial lane (`*.serial.test.ts` — that
lane runs in required CI; a new `test/e2e/*` file does NOT, since unit shards
exclude the directory and the e2e workflow runs only explicitly named files,
no glob);
assert NON-default picker values (bare Enter and each prompt's 60s
`readLineSafe` timeout both resolve to the default, so a defaults-asserting
test passes with dead input); always `await session.close()` in a `finally`
(only `close()` clears the harness wall timer); and point `HOME` plus
`GBRAIN_HOME` at a temp root with pass-through auth keys stripped via
`dropEnv` so picker state is machine-independent.
### Skills-manifest freshness guard
`skills/skills.lock.json` is a committed sha256 inventory of every bundled file under
@@ -90,7 +293,7 @@ Any change under `skills/` must regenerate it: `bun run scripts/generate-skills-
**This section is the canonical home of the test-isolation discipline** — CONTRIBUTING.md and other docs link here rather than restating the rules.
The cross-file flake class is enforced statically by `scripts/check-test-isolation.sh`, wired into `bun run verify` and `bun run check:all`. Rules (non-serial unit files only; `*.serial.test.ts` and `test/e2e/*` are skipped):
The cross-file flake class is enforced statically by `scripts/check-test-isolation.sh`, wired into `bun run verify`. Rules (non-serial unit files only; `*.serial.test.ts` and `test/e2e/*` are skipped):
| Rule | What it bans | Fix |
|---|---|---|
@@ -161,6 +364,54 @@ The quarantine has grown to dozens of files — treat it as debt: every addition
`bun test` runs all tests without a database. E2E tests skip gracefully when `DATABASE_URL` is not set.
-`test/watch-command.test.ts` — `gbrain watch` push transport (#2095): streaming loop, rolling window, session dedupe, `--json` JSONL shape, `channel: 'watch'` event logging, clean EOF return. Hermetic PGLite + injected line/write deps (no subprocess, no real stdin).
-`test/watch-sigint.serial.test.ts` — `gbrain watch` SIGINT lifecycle against a real spawned CLI subprocess with a tmpdir brain. SERIAL: parallel unit shards flake on concurrent subprocess spawns (same rationale as `apply-migrations-pglite-spawn.serial.test.ts`).
-`test/init-picker-pty.serial.test.ts` — the interactive `gbrain init` pickers (embedding-provider + search-mode) driven under a REAL pseudo-terminal via `launchTty`: typed input lands (a NON-default mode choice verified by a follow-up non-TTY config read — bare Enter and the `readLineSafe` timeout both resolve to defaults, so a defaults-asserting test would pass with dead input), prompt-to-acknowledgement gaps bounded well under the fallback window, plus the Ctrl-D/EOF keyless fallback. On CI, missing PTY support fails loud instead of skipping. Hermetic: HOME + GBRAIN_HOME at a temp root, pass-through auth keys stripped via `dropEnv`; `session.close()` in `finally`. Serial: PTY spawn + full PGLite bootstrap, and the serial lane is what runs in required CI.
-`test/tty-harness.test.ts` — the real-PTY harness's pure helpers (`stripAnsi`, `computeStalls`, `renderStallsReport`, `parseDriveCommand`, `buildClaudeTuiSeed`) with zero subprocesses; the file's live-PTY smokes are `describe.skipIf(!ptySupported())`-gated.
-`test/autopilot-launchd-lifecycle.serial.test.ts` — autopilot lifecycle behavior, not generated-string assertions: the full install → self-disable → status → reinstall → uninstall arc with `launchctl` replaced by an argv recorder and the generated wrapper executed by a REAL bash against a genuinely deleted repo (every platform), plus a darwin-only fail-SKIP describe against the real launchd under a per-run unique label (`GBRAIN_AUTOPILOT_LABEL`) so it can never collide with — or tear down — a real install on the host. Serial: spawns subprocesses and pins HOME/GBRAIN_HOME for the whole file.
-`test/autopilot-fanout.test.ts` — Autopilot fan-out and #4046 policy regression: targeted idempotency keys reopen per dispatch interval while stable doctor/remediate keys remain unchanged; the 60-minute full-cycle floor wins with a remaining small plan, and an all-fresh restart check advances the process-local clock without masking failed stale-source submissions.
-`test/agent-scheduler-contract.serial.test.ts` — the documented external agent-scheduler shell chain (`gbrain sync --repo X && gbrain embed --stale`, live-sync.md / INSTALL_FOR_AGENTS.md Step 7) driven end-to-end through a real `/bin/sh` against a keyless PGLite brain: the `&&` short-circuit IS the contract (argv arrays can't exercise it), the keyless bare stale embed exits 0, and the pull-failure case that must break the chain does. Anti-vacuity: the fixture commits a real page and every read-back asserts pages >= 1. Serial: real spawned CLI + tmpdir HOME.
-`test/cli-format-volunteer.test.ts` — `formatResult`'s `volunteer_context` human rendering: pointer lines with confidence/arm/rationale, the empty-result message, the approximate stats summary.
-`test/config.test.ts` — config redaction.
@@ -221,6 +475,18 @@ Unit tests and what they cover:
-`test/minion-queue-renewlock-signal.test.ts` — `renewLock` forwards its optional AbortSignal to `executeRawDirect` (stub-engine capture); legacy 3-arg calls unchanged; token-fence miss returns false.
-`test/cycle-drain-renewal.test.ts` — `runDrainRenewalTick` (cycle drain): per-call signal aborted on timeout (slot released), onLost once on a lost fence, throws swallowed, hung renewal resolves at the deadline.
-`test/queue-probe-cancellation.test.ts` — `probeQueueState`/`queryWedgeSignals` signal threading: the 1500ms budget CANCELS the losing probe query; fast-path signals never abort; throw still collapses to `{probe_failed: true}`.
-`test/pool-gauge.test.ts` — `CheckoutGauge` pure semantics + the PostgresEngine seams with fake pools: counted while in flight, released on resolve, on REJECTED queries, and on the SYNCHRONOUS pre-aborted-signal throw (leak guards); `getPoolDiagnostics` fail-open.
-`test/postgres-engine-reserved-routing.test.ts` — `withReservedConnection` routing: direct pool when dual-pool active, read pool when kill-switched/in-tx, semaphore cap (directPoolSize−1) with read-pool overflow, permit released on fn throw and reserve failure.
-`test/job-isolation-protocol.test.ts` — outcome-file codec round-trip + every decode failure path (missing/malformed/oversize→UnrecoverableError; byte counts, never content), handler-error instanceof reconstruction, child-CLI invocation resolution, and REAL detached-process `killProcessGroup` tests incl. the grandchild-death guarantee (exercises the Bun negative-pid `/bin/kill` fallback for real under `bun test`).
-`test/run-child-entry.test.ts` — `runChildJobEntry` on real in-memory PGLite with a REAL claim-minted token: success (fenced updateProgress lands), handler-failure outcome (exit 0), token-mismatch never runs the handler (exit 14), missing job/handler, parent-death watchdog aborts a live handler.
-`test/child-job-runner.test.ts` — `runJobInChild` against real .mjs children: success + full env contract (incl. `GBRAIN_DIRECT_POOL_SIZE=1`), error/lease outcome reconstruction, crash, SIGTERM-ignorer → group SIGKILL at the injected grace, pre-aborted signal, spawn ENOENT → `ChildSpawnInfraError`, worker-shutdown drain (report-during-drain completes; non-reporting kill → `ChildWorkerShutdownError`).
-`test/worker-job-isolation.test.ts` — full parent path on PGLite with the `fake-run-child.mjs` fixture: claim → child → fenced completeJob (real token over env), error outcome → failJob, crash burns the attempt, spawn failure RELEASES with zero attempts burned, and the codex-2 #8 serialization-parity pin (unreportable results fail in BOTH modes, never falsely complete).
-`test/extract-fs.test.ts` — `gbrain extract --source fs`: first-run inserts + second-run reports zero, dry-run dedups candidates across files, second-run perf regression guard for the N+1 dedup bug.
@@ -263,10 +529,19 @@ Unit tests and what they cover:
-`test/longmemeval-sanitize.test.ts` — sanitization parity pinning that `INJECTION_PATTERNS` from `src/core/think/sanitize.ts` is the single source of truth (adding a pattern there must cover both `<take>` framing and `<chat_session>` framing, no per-surface regex drift).
-`test/openai-compat-multimodal.test.ts` — gateway's openai-compatible multimodal path: happy-path single + multi-input embedding, unauthenticated proxy mode, dimension-mismatch guard (throws `AIConfigError` with model id + observed + expected pre-storage), default-dim fallback when recipe declares `default_dims`, HTTP 401 / 400 / malformed-JSON / non-array error paths, regression that the existing Voyage `/multimodalembeddings` recipe still routes through its dedicated path. Hermetic via the `__setEmbedTransportForTests` seam.
-`test/serve-stdio-lifecycle.test.ts` — `MCP_STDIO=1` env guard: stdin EOF does NOT trigger shutdown when the env is set, SIGTERM still does (guard scope is correct), unset env preserves the CLI lifecycle. Exercises the `ServeOptions.mcpStdio?: boolean` test seam directly so tests don't mutate `process.env`.
-`test/db-lock-fencing.test.ts` — fenced lock identity: a `DbLockHandle` carries its acquisition fence, `refresh()` returns true while owned and false after a steal (0-row fenced UPDATE), a stolen-from handle's `release()` is a fenced no-op that leaves the successor's row intact, and `startCycleLockRefresher` aborts its controller with `LockStolenError` on a fenced miss while serializing ticks (a slow refresh never overlaps the next).
-`test/cycle-lock-steal.serial.test.ts` — runCycle steal-abort arc end-to-end: a mid-run steal produces a structured partial report (`reason: 'lock_stolen'`), runs no further phases, and never touches the successor's lock row; a steal-free cycle completes and releases normally.
-`test/cycle-any-abort-signal.test.ts` — `anyAbortSignal` combining: pre-aborted inputs, late aborts propagating their reason, duck-typed signal stubs (no `addEventListener`) observed via poll, and `dispose()` detaching the caller-signal listener + clearing the poll timer (the daemon leak class).
-`test/queue-stall-parent-unblock.test.ts` — the shared `killJobs` tail: a stall-exhausted child lands `child_done(dead)` in its parent's inbox and unblocks the parent, a requeued child doesn't touch the parent, all three reapers route through the tail with their own outcome, and the idempotent stranded-parent sweep self-heals parents whose children were already dead (without unblocking parents that still have a live child).
-`test/queue-started-at-retry.test.ts` — every automatic re-run path clears `started_at` (failJob delayed branch, stall requeue, lease release, promoteDelayed, parent re-claim) so a retried job's wall-clock budget measures execution, not backoff wait; end-to-end survival of the wall-clock sweep on a fresh attempt.
-`test/embed-modality-preserved.test.ts` — `carryChunkMetadata` carries modality + all code-metadata fields through re-embed merges (an image chunk stays image), plus the write-side contract that omitting modality resets it to text (why the shared list is load-bearing).
-`test/import-abort-error.test.ts` — `runImport` preflight/argv failures throw typed `ImportAbortError` instead of exiting the process; the calling process survives the abort.
-`test/lint-fix-single-pass.test.ts` — `gbrain lint --fix` walks the tree once and `total_fixed` reports the fixes THIS run applied.
-`test/snapshot-shape-guard.test.ts` — PGLite snapshot loader refusal matrix: shape-less version files, dims/model mismatches, and stale schema hashes are all refused; matching hash + shape loads; a migration-handler edit changes the hash.
### E2E test inventory
E2E tests live in `test/e2e/` and run against real Postgres+pgvector (require `DATABASE_URL`), except where noted as PGLite in-memory (no `DATABASE_URL` needed).
E2E tests live in `test/e2e/` and run against real Postgres+pgvector (require `DATABASE_URL`), except where noted as PGLite in-memory (no `DATABASE_URL` needed). One file outside the directory also rides the e2e lane: `test/phantom-redirect-engine-parity.test.ts` (Postgres arm; see the file taxonomy above).
-`bun run test:e2e` runs Tier 1 (mechanical, all operations, no API keys). Includes dedicated cases for the postgres-engine `addLinksBatch` / `addTimelineEntriesBatch` bind path — postgres-js's JSONB bind (`jsonb_to_recordset(($1::jsonb)->'rows')`) differs from PGLite's and gets its own coverage.
-`test/e2e/search-quality.test.ts` — search quality against PGLite (no API keys, in-memory).
@@ -278,10 +553,18 @@ E2E tests live in `test/e2e/` and run against real Postgres+pgvector (require `D
-`test/e2e/sync.test.ts` — `--skip-failed` failure-loop test alongside happy-path tests: broken file → `performSync` returns `blocked_by_failures` with grouped breakdown → `performSync({skipFailed: true})` advances bookmark and returns `AcknowledgeResult` with code summary → second broken file → second cycle. Saves and restores the user's real `~/.gbrain/sync-failures.jsonl` so the test is hermetic. Asserts bookmark gating, JSONL state, dedup across paths, summary aggregation, and the literal doctor-rendering string format.
-`test/e2e/upgrade.test.ts` — check-update against real GitHub API (network required).
-`test/e2e/minions-shell-pglite.test.ts` — PGLite `--follow` inline shell-job path (in-memory, no `DATABASE_URL` required) — the path the minion-orchestrator skill documents for dev use.
-`test/e2e/job-isolation.test.ts` — process isolation on real Postgres (DATABASE_URL-gated, wired EXPLICITLY into `.github/workflows/e2e.yml` tier1 — the workflow runs only named files): a concurrency-3 isolated drain through real child processes (the `fake-run-child.mjs` fixture — real spawns, no child DB pools), and the REAL `jobs run-child` CLI entrypoint end-to-end (engine bootstrap incl. the child's own pools, quiet handler registry, token validation, outcome protocol).
-`test/e2e/pglite-cli-exit.serial.test.ts` — real spawned-CLI exit behavior on PGLite (in-memory, no `DATABASE_URL`): read commands (`search`/`get`/`query`) exit 0 promptly; CLI_ONLY `capture` exits clean and frees the single-writer lock; the `#2084` describes pin every swept disconnect site — a failed op exits 1 with the error on stderr, and the dashboard, read-only-timeout, doctor, and `dream --dry-run` paths all exit with no force-exit banner.
-`test/e2e/pgbouncer-teardown.test.ts` — PgBouncer TRANSACTION-mode teardown (#2084 / the #1972→#2015→#2084 class). Pins the bug CLASS, not timings: a CLI op against a txn-mode pooled URL exits 0 with intact stdout and does NOT ride the 10s hard-deadline backstop (the `engine.disconnect() did not return` banner is the smoking gun — pre-#2084 it printed on 100% of query-shaped ops). Gated by `GBRAIN_PGBOUNCER_URL` + `GBRAIN_PGBOUNCER_DIRECT_URL` (NOT `DATABASE_URL`) — set automatically by `bun run ci:local`'s `pgbouncer` compose service; skips gracefully elsewhere. Uses a DEDICATED `gbrain_pgbouncer` database so it never races the `gbrain_test` TRUNCATE fixtures.
-`test/e2e/volunteer-context-postgres.test.ts` — `volunteer_context` on REAL Postgres (#2095; engine parity beyond the hermetic PGLite unit suite): resolution arms through the actual op handler, the fire-and-forget volunteer-event sink landing rows, the stats join, and the RLS pin that `context_volunteer_events` has ROW LEVEL SECURITY enabled (keeps the v35 auto-RLS event trigger honest for migration-created tables). `DATABASE_URL`-gated.
-`test/e2e/openclaw-reference-compat.test.ts` — `check-resolvable` + `skillpack install` against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the OpenClaw deployment shape.
-`test/e2e/openclaw-reference-compat.test.ts` — `check-resolvable` + skillpack install-model against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the OpenClaw deployment shape.
-`test/e2e/workspace-generic-compat.test.ts` — always-on (PGLite, no binary): pins the INSTALL_FOR_AGENTS.md "any repo with a workspace" contract against `test/fixtures/generic-agents-workspace/` (Hermes is the motivating consumer): `cwd_walk_up` detection, the `GBRAIN_SKILLS_DIR` override, `check-resolvable` on a root AGENTS.md, and scaffold additivity + refuse-overwrite. The real Hermes-behavior proof is the door suite below.
-`test/e2e/install-real-hermes.serial.test.ts` — the hermes "door": real `hermes` binary + real `hermes mcp add` handshake (full-catalog tool discovery; the count tracks the op catalog, so the test asserts discovery happened, not a number) + a paid `hermes -z` recall turn against a seeded brain. Triple-gated: `GBRAIN_REAL_HERMES_E2E=1` (explicit opt-in — run-e2e.sh scrubs GBRAIN_*, so it can never fire under `bun run test:e2e`) + resolvable binary + non-empty ANTHROPIC key (anthropic-pinned on purpose: a second provider key flips hermes provider-auto into a mis-routed 401). Hermetic HOME + HERMES_HOME with a tripwire on the operator's real config; evidence copies to `GBRAIN_E2E_EVIDENCE_DIR` for CI upload. Venue: heavy-tests.yml (`real-agent-e2e` + `hermes-door` jobs).
-`test/e2e/install-real-grok.serial.test.ts` — the grok "door" (xAI Grok Build; every asserted shape observed against the pin in `docs/mcp/GROK-CLI-PIN.md`). SPLIT-GATED, a deliberate divergence from the hermes door: grok's `mcp add/list/doctor` run keyless, so the compat tier (version-shape pin, documented-shape `grok mcp add gbrain -- gbrain serve --surface verbs` via a PATH-staged bin dir, saved-TOML asserts via `Bun.TOML.parse`, `mcp doctor` handshake proving the seven-verb surface, vendor-fallback provenance guard, direct-TOML surface) needs only `GBRAIN_REAL_GROK_E2E=1` + a resolvable binary; the paid SMOKE additionally needs a non-empty `XAI_API_KEY` and asserts a PER-RUN NONCE fact (grok has fs/shell tools — the committed fact is greppable, so recall of it proves nothing) with web search disabled. `mcp add` is lazy (exit 0 always) — `mcp doctor <name> --json` is the honest discriminator (exit 0/1 observed). Hermetic HOME + GROK_HOME + tmp cwd on every spawn (grok reads vendor MCP configs for trusted folders and loads `.envrc` from cwd); bounded tripwire over the operator's real `~/.grok` config/credential files (volatile paths excluded — grok rewrites logs/sessions/bin/docs every run) + a checkout guard that no `.grok/`/`.mcp.json` appeared in the repo root. Venue: heavy-tests.yml (`real-agent-e2e` + `grok-door` jobs); run directly via `GBRAIN_REAL_GROK_E2E=1 bun test test/e2e/install-real-grok.serial.test.ts`.
-`test/e2e/install-real-opencode.serial.test.ts` — the opencode "door" (SST opencode; every asserted shape observed against the pin in `docs/mcp/OPENCODE-CLI-PIN.md`). SPLIT-GATED a step past the grok door: opencode's anonymous FREE TIER drives MCP tool calls keyless, so even the nonce SMOKE runs in the keyless tier — T1 bare-semver version pin (the SST-vs-claimant discriminator), T2 documented-shape `opencode mcp add gbrain --env … -- gbrain serve --surface verbs` + the honest `opencode mcp list` discriminator (it SPAWNS every server; `✓/✗` text is the assertion surface — exit code is 0 even on failure, and `mcp debug` is OAuth-only), T2b spawn-gate CANARY (a project-config decoy is spawn-attempted with NO trust prompt — if this ever gates, the bootstrap user-global scope default's rationale changed: re-observe), T3 writer parity (gbrain's `opencode-json.ts` output handshakes through the real binary; cross-tool preservation both ways), T4 keyless SMOKE (per-run nonce + STRUCTURAL `gbrain_*` tool_use proof via `parseOpencodeJsonl`, `--format json`). The paid T5 anthropic leg additionally needs a non-empty `ANTHROPIC_API_KEY` and self-validates the pinned model id against the authed `opencode models` list BEFORE any spend. Hermetic HOME + both XDG dirs + tmp cwd on every spawn; `--pure` on every probe (`mcp list` autoloads plugins — a code-execution surface); bounded tripwire over the operator's real opencode configs/auth.json + a repo-root checkout guard. Venue: heavy-tests.yml (`real-agent-e2e` + `opencode-door` jobs, plus the schedule-only `opencode-door-canary` latest-version leg — continue-on-error, a pin-refresh signal, never a gate); run directly via `GBRAIN_REAL_OPENCODE_E2E=1 bun test test/e2e/install-real-opencode.serial.test.ts`.
**Door cadence policy** (adopted with the 4th door agent): the NEWEST door agent runs at nightly/schedule cadence (currently opencode, whose canary leg also tracks `latest`); a door drops to label-only (`real-agent-e2e`) after 2 stable monthly cycles with unchanged pins. Rationale: churn concentrates in the newest integration; steady-state doors pay for themselves on demand, not nightly.
-`test/helpers/tty-harness.ts` + `test/tty-harness.test.ts` — the DX real-PTY harness (`Bun.spawn({terminal:})`): pure text/timing helpers unit-tested with zero subprocesses, plus three live PTY smokes against `sh` guarded by `describe.skipIf(!ptySupported())`. The harness itself is a dev instrument surface — its consumer `scripts/dx-explore.ts` never runs in CI (transcripts land in gitignored `.context/dx-runs/`); see `docs/guides/bootstrap.md` for the scenario runbook.
-`test/e2e/search-swamp.test.ts` — reproduces the source-swamp case. Seeds a curated `originals/talks/article-outline-fat-code` page against two `<fork>/chat/` pages stuffed with the same multi-word phrase. Asserts the article wins keyword AND vector ranking, that `detail=high` lets the chat swamp re-surface, and that `source_id` passes through the two-stage CTE intact. PGLite in-memory.
-`test/e2e/search-exclude.test.ts` — `test/` + `archive/` pages hidden by default, `include_slug_prefixes` opts back in, caller-supplied `exclude_slug_prefixes` adds to defaults. Both keyword and vector search paths.
-`test/e2e/engine-parity.test.ts` — Postgres ↔ PGLite top-result and result-set parity for `searchKeyword` + `searchVector` (Postgres ranks pages then picks best chunk while PGLite returns chunks directly, so the source-boost behavior needs parity coverage). Skips without `DATABASE_URL`.
@@ -296,6 +579,7 @@ E2E tests live in `test/e2e/` and run against real Postgres+pgvector (require `D
-`test/e2e/think-source-isolation-pglite.test.ts` — PGLite in-memory suite pinning the `think` gather stage's source scope: seeds three sources with cross-source links and embedded takes, then asserts `runGather` under a federated `sourceIds` grant (and under a scalar `sourceId`) keeps every stream — hybrid retrieval, takes keyword + vector (`searchTakes`/`searchTakesVector`), and the `traversePaths` graph walk — inside the grant while still reaching authorized neighboring sources. No `DATABASE_URL` needed.
-`test/e2e/skill-brain-first.test.ts` — doctor reports `skill_brain_first` check with structured issues; `--fix --dry-run` previews insertion without writing; `--fix` applies the canonical Convention callout idempotently; `brain_first: exempt` frontmatter resolves the warn; `brain_first_typo` surfaces a paste-ready hint; audit JSONL records `detected` / `resolved` / `fixed` transitions; stable brain emits 0 audit lines/run.
- Tier 2 (`test/e2e/skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI.
-`test/e2e/claw-test.test.ts` also covers live mode token-free via shim agents (`OPENCLAW_BIN=<sh script>`): the success-oracle break path (a do-nothing agent now FAILS), the E0 child-friction merge surviving tempdir cleanup, and the upgrade staging + schema-version-probe regression.
- If `.env.testing` doesn't exist in this directory, check sibling worktrees: `find ../ -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
- **Run E2E tests without asking permission.** When you want to verify behavior, there's a relevant E2E test, or you're shipping anything covered by an E2E suite — spin up the test DB, run the tests, tear down. Don't ask, don't propose it, don't defer. The lifecycle is short (~2-30s startup, sub-minute tests, instant teardown) and the gate value is high. Skipping with "DATABASE_URL unset" is silent regression, not caution.
<!-- Regenerate: bun run scripts/generate-tool-catalog.ts -->
<!-- Freshness-guarded by scripts/check-tool-catalog-fresh.sh (bun run verify). -->
Every non-localOnly operation on the MCP surface: 115 tools across 22 areas. **Starter** marks membership in the ~27-op `starter` surface (`src/mcp/surface.ts`); **Gate** names the config key that must be true before remote callers see/call the op (`gbrain config set <key> true`). What a given token actually sees is further filtered per request by scope, bound-client fence, publish gates, and the per-client surface — see `docs/operations/mcp-surface-runbook.md`. Area names are non-contractual groupings.
## admin
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `get_health` | Brain health dashboard (embed coverage, stale pages, orphans). | admin | | |
| `run_skillopt` | Run SkillOpt against a single skill. | admin | | |
## advisor
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `advisor` | Ranked, read-only "what to do next" for this brain: version drift, pending migrations, schema-pack issues, stalled jobs, usage-shape gaps, and setup smells. | read | | `mcp.publish_advisor` |
## chronicle
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `chronicle_day` | Life Chronicle: events + timeline entries on a given day (or its ISO week when week=true), ordered chronologically; each row backlinks to its depth page. | read | | |
| `chronicle_last_seen` | Life Chronicle: when an entity was last seen — its own timeline rows OR an event's `who`. | read | | |
| `chronicle_on_this_day` | Life Chronicle: events from the same calendar day in PRIOR years ("on this day"). | read | | |
| `chronicle_since` | Life Chronicle: events + timeline entries on or after a date, optionally filtered by event kind. | read | | |
| `volunteer_chronicle` | Life Chronicle agent-orientation: the recent timeline (last N days) + the current validity-resolved ontology for the named entities, in one zero-LLM payload, so an agent orients before acting. | read | | |
## code
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `code_blast` | BEFORE editing any function, run code_blast with the symbol name to surface every transitive caller grouped by depth (direct → 2-hop → 3-hop). | read | | |
| `code_callees` | When tracing how a function flows to its dependencies (DB calls, HTTP calls, file I/O), run code_callees from the entry point. | read | | |
| `code_callers` | BEFORE editing any function, run code_callers with the symbol name to find every caller (the people who'd be affected by your change). | read | | |
| `code_def` | Where is this symbol defined? | read | | |
| `code_flow` | When tracing how a request flows through the codebase from entry point to side effect (DB write, HTTP call, file I/O), run code_flow from the entry point. | read | | |
| `code_refs` | Find every reference to a symbol across the codebase (every file, every line). | read | | |
## discovery
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `request_tools` | Discover this brain's tool catalog and optionally unlock a wider tool surface for your client. | read | yes | |
## entities
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `extract_entities` | Extract entity names (people, companies) from text and create/update their brain stub pages. | write | | |
| `extraction_pending` | List unverified auto-extracted entity stubs awaiting owner review (the quarantine lane from extract_entities). | read | | |
| `find_anomalies` | Returns statistical anomalies in recent page activity, grouped by cohort (tag or type). | read | yes | |
| `find_contradictions` | v0.32.6 — return suspected-contradiction findings from the most recent `gbrain eval suspected-contradictions` probe run, optionally filtered by slug and/or severity. | read | | |
| `find_experts` | Answers 'who in my brain knows about <topic>'. | read | | |
| `find_trajectory` | v0.35.4 — return the chronological claim trajectory for an entity (typed metric values over time, plus auto-detected regressions and narrative drift). | read | | |
| `get_calibration_profile` | Read the active calibration profile for a holder. | read | | |
| `get_recent_salience` | Returns pages recently touched and ranked by emotional + activity salience (deterministic 0..1 emotional_weight + take density + recency decay). | read | yes | |
| `volunteer_context` | Push-based context: volunteer brain pages relevant to a rolling conversation window WITHOUT being asked. | read | | |
## jobs
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `cancel_job` | Cancel a waiting, active, or delayed job | admin | | |
| `get_agent_job` | Poll an agent job submitted via submit_agent. | agent | yes | |
| `get_job` | Get job status and details by ID | admin | | |
| `get_job_progress` | Get structured progress for a running job | admin | | |
| `list_jobs` | List jobs with optional filters | admin | | |
| `pause_job` | Pause a waiting, active, or delayed job | admin | | |
| `replay_job` | Replay a completed/failed/dead job, optionally with modified data | admin | | |
| `resume_job` | Resume a paused job back to waiting | admin | | |
| `retry_job` | Re-queue a failed or dead job for retry | admin | | |
| `send_job_message` | Send a sidechannel message to a running job's inbox | admin | | |
| `submit_agent` | Submit an LLM agent job that the worker dispatches via the gateway-native tool loop. | agent | yes | |
| `submit_job` | Submit a background job to the Minions queue. | admin | | |
## links
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `add_link` | Create link between pages | write | | |
| `find_orphans` | Find pages with no inbound wikilinks. | read | | |
| `get_backlinks` | List incoming links to a page | read | yes | |
| `get_links` | List outgoing links from a page | read | | |
| `list_link_sources` | List distinct link_source provenances in the brain with edge counts (e.g. | read | yes | |
| `remove_link` | Remove link between pages | write | | |
| `traverse_graph` | Traverse link graph from a page. | read | yes | |
## memory
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `extract_facts` | v0.31: extract personal-knowledge facts (events, preferences, commitments, beliefs) from a conversation turn into the per-source hot memory. | write | | |
| `remember` | MEMORY VERB (v1): save one fact to durable agent memory — the protocol write verb. | write | yes | |
| `synthesize` | [EXPENSIVE / SLOW — makes LLM calls, seconds-to-minutes latency, costs money] MEMORY VERB (v1): answer a broad question using cross-page LLM reasoning with citations and gap analysis. | read | yes | |
## ontology
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `ontology_conflicts` | Life Chronicle: dimensions with ≥2 distinct current values from ≥2 provenances (genuine disagreement, not temporal supersession). | read | | |
| `ontology_dimensions` | Life Chronicle meta-ontology: which dimensions the brain tracks across entities, with entity + observation counts. | read | | |
| `ontology_get` | Life Chronicle: the current resolved per-entity ontology (dimension → value) at `asof` (default now), with provenance + confidence + validity. | read | | |
| `ontology_propose` | Life Chronicle: record one ontology observation (entity has dimension=value), sourced + confidence-weighted + bi-temporal. | write | | |
## pages
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `capture` | Capture a quick note into the brain — the "just remember this" write. | write | yes | |
| `search_modes` | Read-only search-mode dashboard: active mode, per-knob resolved value with attribution (mode default vs config override), and the three frozen bundles. | read | | |
| `search_stats` | Search observability over a window: cache hit rate, intent/mode mix, budget drops, rank-1 score drift, graph-signals failure counts. | admin | | |
| `search_tune` | Read-only tuning recommendations derived from the last 7 days of search telemetry: what should change, why, and the paste-ready config command per recommendation — relay them to the user. | admin | | |
## skills
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `get_skill` | Fetch one skill's full instructions by name. | read | | `mcp.publish_skills` |
| `list_brain_skillpack` | List brain-resident skillpacks this brain ships (per-source). | read | | `mcp.publish_skills` |
| `list_skills` | List the skills this agent's brain publishes. | read | | `mcp.publish_skills` |
## sources
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `sources_add` | Register a new source. | sources_admin | | |
| `sources_list` | List registered sources with page counts and remote_url. | read | | |
| `remove_tag` | Remove tag from page | write | | |
## takes
| Tool | Description | Scope | Starter | Gate |
|---|---|---|---|---|
| `takes_add` | Record a take (typed claim) on a page: fact / take / bet / hunch, with a holder (who holds the belief: world, people/<slug>, companies/<slug>, or brain), weight 0..1, and optional source/since date. | write | | |
| `takes_calibration` | Calibration curve: resolved correct/incorrect bets binned by stated weight; observed vs predicted per bucket. | read | | |
| `takes_list` | List takes (typed/weighted/attributed claims) filtered by holder/kind/active/etc. | read | | |
| `takes_resolve` | Resolve a take: quality correct / incorrect / partial / unresolvable, with optional evidence text and measured value/unit. | write | | |
| `takes_search` | Keyword search across takes (pg_trgm similarity over claim text) | read | | |
| `takes_supersede` | Supersede a take with a replacement claim: the old row is struck through (kept for archaeology), the replacement appends at the next fence row number. | write | | |
| `takes_update` | Update a take's mutable fields (weight, source, since date). | write | | |
> that `gbrain upgrade` / `gbrain post-upgrade` route through), plus
> `CHANGELOG.md` for what each release changed. Use this file only to catch a
> long-diverged fork up through the versions it covers; for anything after
> v0.36.5.0, walk the migration files and CHANGELOG instead.
> v0.36.5.0, walk the migration files and CHANGELOG instead. Time-critical example: the ZeroEntropy shutdown (2026-09-04) — every fork still embedding or reranking through `zeroentropyai:*` must run `skills/migrations/v0.46.3.0.md` before that date.
GBrain ships skills in `skills/`. Downstream agents (custom OpenClaw deployments,
agent forks of any kind) often **copy** these skill files into their own workspace and
touch or inspect its contents), and pipes the rendered prompt to it on
stdin:
- `--tools ''` disables every built-in tool (Bash/Read/WebSearch/…) — the
subprocess must behave like a raw LLM, not a full agent.
- `--strict-mcp-config` skips loading the user's MCP servers. Without it,
every call would boot the user's configured MCP servers — including
gbrain's own MCP, which would recurse and contend for the PGLite
single-writer lock.
- The subprocess env is a copy of gbrain's own process env with exactly
three keys deleted before spawn: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
`ANTHROPIC_BASE_URL`. Everything else in gbrain's environment is inherited
as-is. The recipe's source comment states the intent (stop an
`ANTHROPIC_API_KEY` present in gbrain's own env from being picked up by the
subprocess), scoped to those three variables specifically — the doc does
not claim this rules out every other way `claude` could end up billing
through a non-subscription path (e.g. other env-based auth switches the CLI
itself may support); that is between the installed `claude` binary and its
own configuration, not something this recipe's code inspects.
- Beyond that env-scrub, auth resolution is entirely up to the installed
`claude` binary — the recipe does not manage or forward credentials
itself. Whatever `claude` is already logged in / authenticated with on
this machine is what it authenticates with here too (see the `claude` CLI's
own docs for how it stores and resolves that).
`--bare` (which would skip loading the user-level `~/.claude/CLAUDE.md`
entirely) is not among the flags passed, because it also forces
`ANTHROPIC_API_KEY` auth (per the recipe's source comment). One effect of
not passing it: the user-level `~/.claude/CLAUDE.md` still loads and gets
cached tokens on every call.
The adapter does not use `claude`'s own agentic tool-calling — it injects a
fenced instruction block into the system prompt teaching the model a
`<use_tools>[{id,name,input}, ...]</use_tools>` JSON emission format
(`buildToolUseInstructions`), then parses that block back out of the plain
text response into ai-sdk tool-call parts (`extractToolCalls`). This
protocol-over-text approach is what lets `supports_subagent_loop: true`
work through the `--print`, no-built-in-tools subprocess shape described
above.
## Constraints
| Area | Behavior |
|---|---|
| Embedding | Not supported — `gateway.embed()` throws for `claude-cli` models. Pair with another provider for embeddings. |
| Streaming | Not implemented. `doStream()` throws. `gateway.toolLoop()` (the main caller) is non-streaming already, so this is not a practical limitation for subagent dispatch, but any caller that expects a streaming chat surface cannot use `claude-cli`. |
| Tool use | JSON emission via a system-prompt-injected protocol, not the CLI's native tool-call mechanism. Parallel tool calls in one turn round-trip correctly. |
| Multimodal | Not supported over the subprocess path. File/image message parts are rendered as a `[file <mediaType>]` text stub, not sent as actual content. |
| Prompt caching | The recipe declares `supports_prompt_cache: false`. The CLI manages its own caching internally but does not expose it through gbrain's `cache_control` control plane, so from the gateway's point of view this model does not support prompt caching. |
| Usage / token counts | Reported `usage.input_tokens` / `usage.output_tokens` are read straight from the CLI's `--output-format json` envelope (`result.usage?.input_tokens` / `output_tokens`); gbrain does not independently count tokens for this path. |
| Cost figures | The recipe declares `cost_per_1m_input_usd: 3.0` / `cost_per_1m_output_usd: 15.0` — the same Sonnet-class figures the `anthropic` recipe declares (`price_last_verified: 2026-06-17`) — purely so gbrain's budget ledger has a number to attribute per call. Neither the recipe nor the adapter code checks what you're actually billed; treat these as the ledger's nominal per-call number, not a verified charge. |
| User-level CLAUDE.md | `~/.claude/CLAUDE.md` still loads on every call (see above) — only the working directory changes (see "What actually happens on a call" for exactly what that directory is and isn't). |
## Known doctor caveat: cold-start subprocess vs the fixed 5s probe timeout
`gbrain models doctor`'s chat reachability probe (`probeModel` in
`src/commands/models.ts`) wraps every chat call in a fixed 5-second
`AbortController` timeout, independent of any per-recipe timeout the recipe
itself declares (`claude-cli` does not declare a `default_timeout_ms`).
Spawning the `claude` binary and letting it start up is generally fast, but
is not instantaneous — a slow first invocation (cold process cache, slow
disk, contended machine) can outrun that 5-second window.
When that happens, the probe's `AbortController` fires, the subprocess is
killed (`child.kill('SIGTERM')`), and the adapter's abort handler rejects
with a fixed message (`claude-cli adapter aborted`). `classifyError` in
`src/commands/models.ts` only maps a message to `status: network` if it
adapter aborted` matches none of those, so it falls through to
`status: unknown` — the classifier's catch-all — instead of `status:
network`, which is what a plain slow/unreachable HTTP provider would map
to on the same probe timeout. So a `status: unknown` result on a
`claude-cli:` model is not necessarily a broken configuration on its own;
a cold subprocess start outrunning the fixed 5s window is one thing that
can produce it (the same class of first-call cold-start the embedding
reachability probe's own code comment already calls out for local
embedders), and re-running the probe is a reasonable first thing to try.
`status: unknown` on its own doesn't distinguish that from any other
unclassified failure, so if a re-run keeps producing it, treat it as an
unclassified error worth investigating rather than assuming cold-start.
## Troubleshooting
| Symptom | Where it comes from | Try |
|---|---|---|
| `claude-cli spawn failed: ...` / stdin write failure | `spawn()`'s `error` event or a failed `stdin.write` — commonly means the `claude` binary was not found on `PATH` | Install Claude Code, or set `GBRAIN_CLAUDE_CLI_BIN` to the binary's path |
| `claude-cli exited <code>: ...` | Non-zero exit from the `claude` subprocess itself; the message is whatever the CLI wrote to stderr/stdout | Run `claude` interactively with the same model to see the underlying CLI error directly (e.g. not logged in, model unavailable) |
| `claude-cli output not JSON: ...` | `JSON.parse(stdout)` threw (stdout wasn't valid JSON at all) | Confirm the installed `claude` CLI version still supports `--print --output-format json`; this adapter's JSON handling was verified against CLI 2.1.145 |
| `claude-cli JSON event array had no "result" event` | stdout parsed as a JSON array (the `"verbose": true` event-stream shape in `~/.claude/settings.json`) but none of the events had `type: "result"` | Check `~/.claude/settings.json` for `"verbose": true`; the adapter tolerates the array shape but still needs a `result` event in it |
| `gbrain models doctor` reports `chat` as `status: unknown` for a `claude-cli:` model | See "Known doctor caveat" above — `classifyError` falls through to `unknown` for the adapter's abort message | Re-run the probe; if it persists, treat it as an unclassified failure and investigate directly (e.g. run the same model via `gbrain models doctor --json` or call `claude` by hand) |
| A call bills through the Anthropic API instead of the local session | The adapter deletes `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` from the subprocess env — this covers gbrain's own env leaking into the call. It does not inspect any other auth/billing switch the installed `claude` CLI itself may support | If billing looks wrong, check the `claude` CLI's own auth/billing configuration on this machine, not just gbrain's env |
@@ -44,13 +44,13 @@ Three regexes, zero LLM tokens, single SQL `addLinksBatch` call with `INSERT ...
Heuristic link-type inference (`attended`, `works_at`, `invested_in`, `founded`, `advises`) fires from surrounding sentence context — also LLM-free. Power users who want richer types add them via the typed-link blockquote convention.
## ZeroEntropy as reranker: 60% top-1 reshuffle
## Cross-encoder reranker: 60% top-1 reshuffle
ZeroEntropy's`zerank-2`is the default reranker (on for the `balanced` and `tokenmax` modebundles, off for `conservative`). On a real-corpus benchmark across 20 queries, zerank-2 reshuffles **60% of top-1 results** after the hybrid + RRF + graph stack. That's the headline number.
The reranker is on for the `balanced` and `tokenmax` mode bundles, off for `conservative`. New installs with a Voyage key get`rerank-2.5`written as explicit `search.reranker.model` config (the recommended reranker; same `VOYAGE_API_KEY` as embeddings — keyed installs without one get reranking explicitly disabled instead); brains that never set the key still fall back to the legacy ZeroEntropy `zerank-2` mode-bundle default, which is deprecated (the hosted API ends 2026-09-04 — switch with `gbrain config set search.reranker.model voyage:rerank-2.5`) and remains the fallback only until the September cutover. On a real-corpus benchmark across 20 queries, zerank-2 reshuffles **60% of top-1 results** after the hybrid + RRF + graph stack. That's the headline number.
The mechanical reason: hybrid ranking is locally optimal per strategy but globally suboptimal. A cross-encoder reranker reads the query + each candidate document jointly, with full attention. It catches the cases where the vector + keyword + graph signals all agreed on a document that's semantically related but topically wrong.
The cost: +150ms p50 latency, ~$0.025/M tokens. Disabled with `gbrain config set search.reranker.enabled false`. For agent loops that do downstream LLM work after retrieval, the latency is invisible.
The cost: +150ms p50 latency, ~$0.025–0.05/M tokens depending on the reranker. Disabled with `gbrain config set search.reranker.enabled false`. For agent loops that do downstream LLM work after retrieval, the latency is invisible.
| Local brain (PGLite) | `~/.gbrain/` (never in the repo) | while a session's MCP serve is open |
| MCP registration (`gbrain serve`) | Claude Code: project scope by default; Codex: user-global (no scope flag) | spawned by your harness per session |
| MCP registration (`gbrain serve`) | Claude Code: project scope by default; Codex: user-global (no scope flag); opencode: user-global by default (project scope is an explicit opt-in — see the degradation matrix) | spawned by your harness per session |
| Hooks (Claude Code, ON by default) | local installs: `.claude/settings.local.json` (gitignored); cloud sandboxes: the COMMITTED `.claude/settings.json` (PATH-resolved, fail-open commands) | each prompt; fail-open; `--no-hooks` opts out at install, `GBRAIN_HOOKS=0` disables at runtime |
| Per-turn persistence | Stop hook → debounced, detached scan-gated push (per workspace; 5 min default, every turn in cloud sandboxes) | after each assistant turn; `GBRAIN_STOP_PUSH=0` disables; `GBRAIN_STOP_PUSH_DEBOUNCE_MIN` / config `hooks.stop_push_debounce_min` tune it |
| Session persistence | SessionEnd hook → scan-gated commit+push | at session end (note: the harness never fires SessionEnd on `/exit` — the per-turn push is what covers that) |
@@ -100,9 +100,11 @@ With zero API keys, everything works: the agent authors memory explicitly throug
the brain's write tools (`put_page`, timeline entries, `## Facts` fences — your
harness's model is the LLM, already paid for), and search runs keyword-only
(BM25). `bootstrap verify` prints the capability report honestly. One optional key
(OpenAI, Anthropic, or Voyage) unlocks semantic search and automatic fact
extraction; the key goes to the 0600 config file, never into the repo or the
interview answers. API spend is metered separately from your subscription and is
upgrades capabilities per provider — OpenAI unlocks semantic search and
| Codex (no hook system, no MCP scope flag) | pull protocol + MCP tools | per-turn push (stated plainly; not oversold) + the ability to confine MCP reach to one folder (`codex mcp add` is always user-global) |
| Codex (no wired hooks, no MCP scope flag) | pull protocol + MCP tools | per-turn push (stated plainly; not oversold — codex 0.147+ ships a hook system, but gbrain does not wire it yet) + the ability to confine MCP reach to one folder (`codex mcp add` is always user-global) |
| opencode (no wired hooks; scope INVERTED: user-global by default) | pull protocol (opencode reads AGENTS.md natively) + MCP tools; project scope available as an explicit opt-in | per-turn push (opencode ships a plugin/event system, but gbrain does not wire it yet). The project-scope default is deliberately NOT offered: opencode spawns project-config servers with no trust prompt, so a committed entry would auto-execute on every collaborator machine |
| Bootstrap at all (plugin-only install) | MCP tools (`starter` surface, `--source-guard`) + the curated skill set via the codex/claude plugin (docs/mcp/CODEX.md) | identity files, hooks/push protocol, the private-repo body — the plugin is the lightweight lane; bootstrap is the full agent |
| Second simultaneous session | first session unaffected | second session's brain tools fail politely (one live serve per brain — v1 contract) |
| Postgres brain (incl. harness mode) | MCP tools every session + pull protocol | per-turn hook injection (`no_pglite_path`: the hook IPC socket is PGLite-only today; hooks stay pre-wired and light up when the engine-uniform listener lands) |
## Local harness mode (`gbrain bootstrap harness`, #4043)
The workspace install above is built for a human's laptop. A box run by an
agent framework (your OpenClaw, or anything that shells out to `claude -p` /
codex exec) already hosts a brain and a running `gbrain serve --http` — and
those framework-spawned sessions get zero brain access by default. Harness
mode wires them in one command, with no `agent.json` and no interview:
gbrain bootstrap harness --yes
- Mints a **least-privilege** bearer token (scopes `read+write`, stored in the
`access_tokens.scopes` column; reads span the brain's federated sources).
Re-runs rotate mint-first: the previous token is revoked by id only after
the new one is wired and smoke-tested, so clients are never dead mid-swap.
The smoke sends a deliberately invalid credential first — an endpoint that
accepts anything is not this brain's serve — and a failed smoke rolls the
wiring back (fresh registrations removed, replaced ones restored, the
headless pre-approval stripped) and retires the fresh mint immediately, so
nothing live is ever left pointed at an unverified endpoint. Prior wiring
is only cleaned up after the replacement verifies.
- Claude Code: user-scope HTTP MCP registration, `mcp__gbrain` pre-approved in
- **divergent queue** — A type's 24h intake structurally exceeds its 24h
completions while a real backlog waits (same thresholds as the
`jobs stats` scream, so the two surfaces agree). The finding names the
type and prints the exact `minions.quota_max_waiting.<name>` command to
cap admission. See "The backlog grows structurally" above.
- **waiting-TTL cancellations** — The admission sweep cancelled queued work
that expired unclaimed in the last 24h. That's operating as designed, but
it means the divergence is being shredded, not worked — intake still
exceeds drain. Tune with `gbrain config set
minions.ttl_waiting_hours.<name> <hours|0>`.
## Lock-renewal: reading an eviction, and the knobs
Since v0.46 lock renewal is **verify-before-evict**: a thrown or timed-out
renewal is never treated as loss. At the deadline the worker runs one fenced
re-check against the database — the only CERTAIN loss signal is that fenced
miss. Every renewal fault also writes a JSONL audit event
(`~/.gbrain/audit/lock-renewal-*.jsonl`) carrying the fields that answer the
first incident question — *was the database down, or was the worker starved?*
How to read a `gave_up` / eviction line:
| Field | Reading |
|---|---|
| `cause` | `call-timeout` = our own timer fired (starved loop, slow pool, or slow DB); `refused` = the driver threw (SQLSTATE in `error_code`); `fenced-lost` = certain reclaim, not an infrastructure fault. |
| `lateness_ms` | How late the renewal tick fired vs its own cadence. Tens of seconds = the WORKER was starved (the #4145 shape); ~0 with `refused` = the database was actually unreachable. |
| `load1` / `cores` | Raw loadavg at event time, with core count for normalization. |
| `overlap_skips` | Ticks skipped because a prior renewal call was still in flight. |
| `deadline_deferred` | The soft deadline passed but the fenced verify was unreachable — the job was KEPT and retried (the fence is the backstop). |
| `event_loop_delay …` (log line) | p99/max event-loop delay since the last successful renewal — the direct starvation measurement. |
A `Job N did not exit within 30s of abort` line after an infrastructure
abort is NOT an orphan leak: the handler is cooperatively cancelling. The
line carries the same cause/lateness/load fields. Caveat: eviction is
cooperative — an abort-IGNORING handler keeps running past every bound and
can duplicate external side effects until it exits; the worker only frees
the slot.
Env knobs (incident escape hatches; all validated, warn-once on bad values;
defaults derive from the per-job lease):
| Env var | Default | What it does |
|---|---|---|
| `GBRAIN_LOCK_RENEWAL_CALL_TIMEOUT_MS` | `min(lease/3, 15s)` | Per-call budget for each renewal attempt (raced + best-effort cancelled). |
| `GBRAIN_LOCK_RENEWAL_SAFETY_MARGIN_MS` | `min(lease/6, 30s)` | Headroom before lease expiry; the fenced verify fires when the NEXT tick would land past `lease - margin`. |
| `GBRAIN_LOCK_RENEWAL_HARD_EVICT_MS` | `2 × lease` | Hard local backstop when even the verify is unreachable (total outage). Floored to the soft deadline. Setting it TO the soft deadline approximates the legacy abort-at-deadline behavior. |
| `GBRAIN_LOCK_RENEWAL_MAX_FAILURES` | 3 | Audit-event labeling only — never gates eviction. |
| `GBRAIN_MINION_STALL_RECLAIM_GRACE_MS` | 15000 | Stall-sweep reclaim grace: a lease that lapsed within this window is not reclaimed (starved-owner head start). `0` restores the legacy `lock_until < now()` predicate. Capped at 600000 (10 min, warn-once + clamp) — an oversized value would otherwise disable stalled-job recovery fleet-wide. |
Cross-knob invariants are enforced with warn-once clamps (margin < lease/2,
call timeout ≤ renewal cadence, hard evict ≥ soft deadline) — a
misconfigured knob can degrade cadence but cannot silently re-break the
deadline math.
Per-job lease: `gbrain jobs submit --lock-duration-ms N` (clamped
[5 s, 1 h] — enforced at submit, re-applied to the resolved lease at
claim, and backed by a database range constraint; `--dry-run` echoes the
clamped value that will actually be stored); long LLM handlers default to 300 s via
`HANDLER_DEFAULT_LOCK_DURATION_MS` in `src/core/minions/handler-timeouts.ts`.
Renewal cadence is `min(lease/2, 60 s)`. Trade-off: a genuinely dead
worker's long-lease job requeues after lease + grace + one sweep interval.
## Self-check: is a worker even running?
@@ -107,6 +222,29 @@ claiming. Start one:
GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 4
```
## Reading the DB-probe verdicts (pool starved vs server unreachable)
When the worker's health probe fails repeatedly, the terminal
`[health] DB probe failed N consecutive times (verdict: ...)` line — and the
`unhealthy` payload the supervisor sees — carries a verdict that names the
failing LAYER (the intermediate `(N/3)` lines log only the failure detail).
Read it before touching anything — the historical failure mode here was
hours spent evaluating a database instance upgrade while the server sat at
10% of max_connections.
| Verdict | What it means | What to do |
|---|---|---|
| `pool_starved` | The read-pool probe failed but the DIRECT-lane probe succeeded — the database server is reachable; the fault is in the transaction-pooler path (client pool exhaustion or a pooler-layer fault; the probe deliberately does not distinguish the two). | Look at client-side load: long-running handler queries holding slots, `GBRAIN_POOL_SIZE` too small for the workload, or a pooler-layer incident. Do NOT resize the database. The worker exit is correct recovery — it frees every client-held slot. |
| `server_unreachable` | Both the pooler lane and the direct lane failed. | Check connectivity/capacity first: network, DNS, the database itself. Both-lanes-failed is the evidence — credential/config errors or a saturated direct lane can also land here, so glance at the probe detail text before concluding the server is down. |
| `unknown` | The read probe failed and no direct lane exists to disambiguate (single-pool mode: non-Supabase, kill switch active, or no derivable direct URL). | Check the startup log for the single-pool warning; consider `GBRAIN_DIRECT_DATABASE_URL` so future incidents self-diagnose. |
The `gbrain-tracked in flight` counts in the message are a tracked SUBSET
(raw/direct/reserved/transaction seams only) — most template-path queries are
untracked, so `0 in flight` next to a `pool_starved` verdict means the
saturation lives in that untracked traffic or at the pooler layer itself,
not that the pool is idle. The verdict, not the counts, is the
GBrain ships with 16 embedding-provider recipes covering OpenAI, ZeroEntropy, Voyage, OpenRouter (single key, many hosted models), the major hosted alternatives, three local options, and a universal escape hatch (LiteLLM proxy). Run `gbrain providers list` to see the live registry; `gbrain providers explain --json` emits a machine-readable matrix for agents.
GBrain ships with 16 embedding-provider recipes covering Voyage (the default), OpenAI, OpenRouter (single key, many hosted models), the major hosted alternatives, three local options, a universal escape hatch (LiteLLM proxy), and the deprecated ZeroEntropy recipe (hosted API shuts down 2026-09-04). Run `gbrain providers list` to see the live registry; `gbrain providers explain --json` emits a machine-readable matrix for agents.
This page is the human-readable counterpart: capability per provider, env-var setup, dimensions, cost, and known constraints.
gbrain init --pglite --model voyage # use a non-default provider
```
## Init resolves your provider from env keys
## Init resolves your provider from your keys
As of v0.37, `gbrain init --pglite` auto-detects which provider to use from your env vars. With `OPENAI_API_KEY` set, you get OpenAI. With `ZEROENTROPY_API_KEY` set, you get ZeroEntropy. If multiple provider keys are set, init fires an interactive picker. If no provider keys areset in a non-TTY context (CI, Docker build), init exits 1 with a paste-ready setup hint. Explicit flags (`--embedding-model`, `--no-embedding`) always win over env detection.
`gbrain init --pglite` auto-detects which provider to use from your provider keys — env vars or the file plane (`~/.gbrain/config.json` fields like `voyage_api_key`; env wins when both are set). With `VOYAGE_API_KEY` set, you get Voyage (`voyage:voyage-4` @ 1024d). With `OPENAI_API_KEY` set, you get OpenAI. Whenever a Voyage key is present — even if a different embedding provider is picked — init also writes `search.reranker.model voyage:rerank-2.5` as explicit config (one key covers both); keyed installs without a Voyage key get `search.reranker.enabled false` written instead. If multiple provider keys are set, init fires an interactive picker (non-TTY auto-picks the Voyage default when its key is present). ZeroEntropy is deprecated and excluded from both auto-pick and the picker — explicit `--embedding-model zeroentropyai:*` still works, with a loud warning. With no provider keys at all, init continues keyless (keyword-only search) with a loud notice; recover later with `gbrain init --force --embedding-model voyage:voyage-4`. Explicit flags (`--embedding-model`, `--no-embedding`) always win over key detection.
The resolved provider + dimensions get persisted to `~/.gbrain/config.json` atomically, so subsequent runs are deterministic across releases.
@@ -23,10 +23,10 @@ The resolved provider + dimensions get persisted to `~/.gbrain/config.json` atom
| `zeroentropyai` — **DEPRECATED** (hosted API **shuts down 2026-09-04**; replacement `voyage:voyage-4`— see note below) | `ZEROENTROPY_API_KEY` | 2560 (Matryoshka to 1280/640/320/...) | 0.05 | no | no |
| `google` | `GOOGLE_GENERATIVE_AI_API_KEY` | 768 | 0.025 | no | no |
| `azure-openai` | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` | 1536 | 0.13 | no | no |
| `minimax` | `MINIMAX_API_KEY` | 1536 | 0.07 | no | no |
@@ -42,9 +42,11 @@ The resolved provider + dimensions get persisted to `~/.gbrain/config.json` atom
**Note on local providers.** Ollama and llama-server have no required API key, so they don't show up in env-detection auto-pick. Pick them explicitly with `--embedding-model ollama:<model>` to avoid silently routing to a daemon that may not be running.
**Note on the ZeroEntropy hosted API.** ZeroEntropy announced (2026-07-24) that its hosted endpoints shut down on **2026-09-04**, and the recipe is deprecated: init auto-pick and the interactive picker exclude it (explicit `--embedding-model zeroentropyai:*` still works, with a loud warning), every ZE embed/rerank call prints a once-per-process deprecation warning, and `gbrain providers` annotates it DEPRECATED (`providers env zeroentropyai` prints the deprecation notice + migration command instead of the signup funnel, `providers explain` leads the row with ⚠ regardless of key readiness, and `gbrain doctor`'s ZE missing-key hint is migration-first). A brain still embedding through the hosted API loses semantic retrieval entirely on that date — query embedding uses the same endpoint, so existing vectors become unqueryable, not just new content. The off-ramp: `gbrain migrate embeddings --to voyage:voyage-4 --dim 1024 --dry-run` (cost preview), then `--yes`. 1280 is not a valid Voyage width (valid: 256/512/1024/2048), so a 1280d brain gets a one-time schema/HNSW rebuild to 1024; the OpenAI alternative keeps the width (flexible dims): `--to openai:text-embedding-3-small --dim 1280`. See [the migration guide](../guides/embedding-migration.md). Self-hosting the Apache-2.0 zembed-1 weights keeps every existing vector with zero re-embed, but the endpoint must speak ZeroEntropy's wire dialect — a generic OpenAI-compatible llama-server/Ollama will NOT work without a compat proxy (details in [`docs/ai-providers/zeroentropy.md`](../ai-providers/zeroentropy.md)). `gbrain doctor` (check `provider_sunset`) flags affected brains — including ZE-backed custom embedding columns — and prints target-aware paste-ready commands (Voyage at 1024; OpenAI keep-width when the brain's actual width is valid there); accepted the risk? `gbrain config set doctor.suppress_provider_sunset true` silences it.
## If first import fails
If `gbrain import` fails with `expected N dimensions, not M`, run `gbrain doctor`. The output will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. **You should not need to delete `~/.gbrain`.** The bug-class that historically forced `rm -rf` recoveries is closed as of v0.37.
If `gbrain import` fails with `expected N dimensions, not M`, run `gbrain doctor`. The output will print the exact `gbrain config set ...` or `gbrain migrate embeddings` command to repair the mismatch. **You should not need to delete `~/.gbrain`.** The bug-class that historically forced `rm -rf` recoveries is closed as of v0.37.
The doctor distinguishes two repair paths:
@@ -53,17 +55,20 @@ The doctor distinguishes two repair paths:
(the full playbook is `skills/migrations/v0.46.3.0.md`).
## Decision tree
- **Cost-sensitive, English-only**: Ollama (free, local) or Voyage (paid, best quality per dollar).
- **Quality-first**: Voyage `voyage-4-large` (1024-2048 dims, ~3-4× more dense tokens than OpenAI tiktoken).
- **Code-heavy brain (gstack per-worktree, source repos)**: Voyage `voyage-code-3` (1024 default; supports 256/512/1024/2048). Tuned on programming languages. Voyage publishes head-to-head numbers showing it outperforms their general flagships on code retrieval ([voyageai.com/blog](https://voyageai.com/blog)). For gstack's per-worktree pglite-backed code brain, this is the right default — see Topology 3 in `docs/architecture/topologies.md`.
- **Reranking pair**: ZeroEntropy `zerank-2` is the hosted default in `tokenmax` mode (see [`docs/ai-providers/zeroentropy.md`](../ai-providers/zeroentropy.md)). Voyage `rerank-2.5` pairs cleanly with Voyage embeddings.
- **Code-heavy brain (gstack per-worktree, source repos)**: Voyage `voyage-code-3` (1024 default; supports 256/512/1024/2048), or the newer `voyage-code-4` (hosted, flexible dims, $0.12/M). Tuned on programming languages. Voyage publishes head-to-head numbers showing it outperforms their general flagships on code retrieval ([voyageai.com/blog](https://voyageai.com/blog)). For gstack's per-worktree pglite-backed code brain, this is the right default — see Topology 3 in `docs/architecture/topologies.md`.
- **Reranking pair**: Voyage `rerank-2.5` ($0.05/M; `rerank-2.5-lite` at $0.02/M for cost-sensitive setups) is the new-install default and rides the same `VOYAGE_API_KEY` as embeddings. ZeroEntropy `zerank-2` remains the fallback only for brains that never set `search.reranker.model` — deprecated, hosted API ends 2026-09-04 (see [`docs/ai-providers/zeroentropy.md`](../ai-providers/zeroentropy.md)).
- **Local reranking (no API spend)**: `llama-server-reranker` recipe (v0.40.6.1) — point gbrain at your own `llama-server --reranking` instance running Qwen3-Reranker or self-hosted ZeroEntropy weights. Same `gateway.rerank()` seam, $0 per call. Walkthrough in [`docs/ai-providers/llama-server-reranker.md`](../ai-providers/llama-server-reranker.md).
- **One key for many hosted models**: OpenRouter. Set `OPENROUTER_API_KEY` and use `openrouter:<provider>/<model>` for chat against GPT-5.2, Claude 4.x, Gemini 3, DeepSeek, and dozens more without juggling per-provider keys. Embedding catalog includes OpenAI, Google, Qwen, BGE-M3.
- **Enterprise compliance**: Azure OpenAI (data residency + private endpoints) or self-hosted via llama-server / Ollama.
@@ -75,15 +80,17 @@ The doctor distinguishes two repair paths:
### OpenAI
Default. Set `OPENAI_API_KEY`. Models: `text-embedding-3-large` (3072 max, 1536 default), `text-embedding-3-small` (1536). Matryoshka via the `dimensions` field — gbrain pins it from `embedding_dimensions` config so existing 1536-dim brains stay aligned across SDK upgrades.
The main alternative to the Voyage default (its flexible-dim `text-embedding-3` models can keep an existing column width during a provider migration). Set `OPENAI_API_KEY`. Models: `text-embedding-3-large` (3072 max, 1536 default), `text-embedding-3-small` (1536). Matryoshka via the `dimensions` field — gbrain pins it from `embedding_dimensions` config so existing 1536-dim brains stay aligned across SDK upgrades.
Optional `OPENAI_BASE_URL` — point the native OpenAI provider at an OpenAI-compatible gateway. A bare host is normalized to carry the `/v1` suffix automatically (so `https://gw.example.com` and `https://gw.example.com/v1` both work); when unset, the SDK's default endpoint is untouched. `ANTHROPIC_BASE_URL` gets the same normalization for Anthropic chat/expansion calls.
### Voyage AI
Best-in-class quality on the Voyage 4 family (Jan 2026 release). Set `VOYAGE_API_KEY`. Models: `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-4-nano`, `voyage-3.5`, `voyage-code-3` (code-tuned), `voyage-finance-2`, `voyage-law-2`, `voyage-multimodal-3` (text + image).
**The default provider** — new installs get `voyage-4` @ 1024d ($0.06/M) plus the `rerank-2.5` reranker on the same key. Best-in-class quality on the Voyage 4 family (Jan 2026 release). Set `VOYAGE_API_KEY`. Models: `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-4-nano`, `voyage-code-4` (code-tuned, hosted, flexible dims, $0.12/M), `voyage-3.5`, `voyage-code-3`, `voyage-finance-2`, `voyage-law-2`, `voyage-multimodal-3` (text + image).
Voyage 4 family shares an embedding space across all variants, so you can index with `voyage-4-large` and query with`voyage-4-lite` without reindexing. Dims: 256, 512, 1024, 2048. **2048 exceeds pgvector's HNSW cap of 2000** — those brains fall back to exact vector scans (still correct, just slower).
Voyage 4 family shares an embedding space across all variants, so you can index with `voyage-4` and later point the query model at `voyage-4-large` or`voyage-4-lite` without reindexing. Dims: 256, 512, 1024, 2048. **2048 exceeds pgvector's HNSW cap of 2000** — those brains fall back to exact vector scans (still correct, just slower).
Voyage also serves the hosted rerankers `rerank-2.5` ($0.05/M) and `rerank-2.5-lite` ($0.02/M) at `POST /v1/rerank` (prices verified 2026-08-15) — the new-install reranker default, configured via `gbrain config set search.reranker.model voyage:rerank-2.5`.
**For brains that index source code** (gstack's per-worktree pglite-backed code brain — see Topology 3 in `docs/architecture/topologies.md`), prefer `voyage-code-3` over `voyage-4-large`. Voyage tunes it on programming languages and publishes head-to-head numbers vs their general flagships on code retrieval. Configure at install time:
@@ -91,7 +98,7 @@ Voyage 4 family shares an embedding space across all variants, so you can index
To switch an existing brain, use`gbrain reinit-pglite --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024` (PGLite) or follow `docs/embedding-migrations.md` (Postgres). `gbrain config set embedding_model` is refused — the schema column has to resize.
To switch an existing brain, run`gbrain migrate embeddings --to voyage:voyage-code-3 --dim 1024` (works on both engines; resumable, cost-previewed with `--dry-run` — see [`docs/guides/embedding-migration.md`](../guides/embedding-migration.md)). `gbrain config set embedding_model` is refused — the schema column has to resize, and the migration command is the path that does that safely.
`gbrain reindex --code` will print a recommendation when run against a brain whose configured embedding model isn't code-tuned; suppress with `GBRAIN_NO_CODE_MODEL_NUDGE=1` if you've intentionally chosen another model (single-vendor procurement, compliance, etc.).
- **Keyless one-shot: exit 1**, message (verbatim, both stdout and stderr):
`Not signed in. To authenticate without a browser, run:\n grok login --device-code\n\nAlternatively, set the XAI_API_KEY environment variable or run `grok login` on a machine with a browser.`
→ `hasGrokAuth()` = non-empty `XAI_API_KEY`; the TTY scenario's keyless early-stop
matcher is `Not signed in`.
- Cost/toolset flags that EXIST (observed in --help): `--always-approve`,
| installer digest drift (fallback path) | `sha256sum -c` fails on install.sh | Diff the new installer, re-pin `installer_sha256` after review |
| version drift mid-run | `grok --version` re-check ≠ pinned | Auto-update engaged — verify `[cli] auto_update = false` seeding; re-pin if a deliberate bump |
| blank XAI_API_KEY secret | named precondition/paid-sentinel failure | Admin adds/rotates the repo Actions secret (console.x.ai origin); keyless tier still ran |
| invalid/expired key | bad-key preflight fails (pin its message after first authed run) | Rotate the secret; no code change |
| tripwire fired | manifest mismatch on config/credential files only | True isolation breach — stop, inspect which file changed; volatile-path drift alone must NOT fire (bug in exclusions if it does) |
| real door regression | doctor checks or recall assert fail with pins intact | Bisect against the pinned version; file upstream if grok-side |
Re-observation checklist on a version bump: re-run the npm/installer pin captures
(§Pin), the help-surface diff (`--help`, `mcp --help`, `mcp add --help`), and the
mcp add → saved-TOML → doctor sequence (§add/§probes). The one-shot/auth/model
sections only need re-observation if their assertions start failing.
## Keyless TUI behavior (observed via the dx-explore PTY instrument)
Under a real PTY with no credentials, interactive `grok` plays a Braille-
pattern intro animation (U+2800-range glyphs) for a few seconds, then settles
(~6s) onto a SIGN-IN screen: "Approve in your browser to finish signing in"
plus a device code (and a ctrl+c hint). There is no unattended path past it.
Two hazards for PTY automation, both observed: the animation frames carry
zero word-like text (3+-letter runs) — a text-presence heuristic must count
letter runs, not enumerate glyphs; and pasting into the sign-in screen leaves
a persistent full-screen spinner redrawing at ~5 frames/sec, which starves
quiet-based settling and makes full-buffer ANSI stripping the hot loop
(strip bounded raw tails instead). Headless keyless is the clean
`Not signed in` error above. The `grok-install` dx scenario early-stops at
the sign-in copy (or a persistently textless screen) with the friction
recorded — that IS the keyless measurement.
## Supported-version policy
gbrain's grok integration is verified against **Grok Build v1.0.4** (this pin). The
canary CI leg (enabled with the secret) tracks latest and is continue-on-error; the
pinned lane is the deterministic gate. **Pending auth** (requires `XAI_API_KEY`):
paid one-shot smoke, authed model list + per-turn cost pins, credential-file
inventory after login (feeds evidence exclusions + TTY secretPaths), AUTHED
first-run TUI dialog copy (the keyless TUI + headless copies are pinned above).
config — the door seeds BOTH; version stayed pinned across every observed
run. `opencode upgrade` is the manual updater.
- Rules files: project `AGENTS.md` is loaded; a sibling `CLAUDE.md` is NOT
double-loaded (nonce test: only the AGENTS.md nonce surfaced) — AGENTS.md
wins per level, exactly as documented. gbrain's rendered pull-protocol
contract works unchanged.
- `.well-known/opencode` remote config: never observed to fire in any CLI run
(docs list it atop the lookup order). No kill needed today; re-observe on
version bump.
## Auth (only needed for PAID providers)
- Anonymous free tier needs nothing on disk; `auth.json` is only created by
`opencode auth login` at `<XDG_DATA_HOME>/opencode/auth.json`
(`opencode providers`, alias `auth`, prints the path).
- The optional paid door leg gates on `ANTHROPIC_API_KEY` (env-only) and
self-validates the model id against the authed `opencode models` output
before spending.
## When the door goes red (triage)
| Failure class | Signature | Remediation |
|---|---|---|
| npm pin drift | install step: version/integrity mismatch | Re-pin deliberately: bump `npm_version`+`npm_integrity` (+ platform stamps), run the re-observation checklist, update workflow env pins (check-opencode-pin.sh enforces the pair) |
| canary leg red, pinned leg green | latest-version leg fails install/asserts | Upstream changed shape — schedule a pin refresh; pinned lane still gates |
| version drift mid-run | `opencode --version` re-check ≠ pinned | Auto-update engaged — verify BOTH kills (env + config seed); re-pin if deliberate |
| `✗ gbrain failed` in `mcp list` | `Executable not found in $PATH` / spawn error | Staged bin dir missing from PATH, or abs path wrong — registration bug, not opencode drift |
| free-tier drift | keyless SMOKE stops answering / new auth wall | Re-observe keyless posture; if the free tier is gated, flip the SMOKE to the ANTHROPIC leg and re-pin this section |
| paid leg: model id unknown | models-gate assert fails before any spend | Update the pinned anthropic model id from the authed `opencode models` output |
| tripwire fired | manifest mismatch on `opencode.json(c)`/`auth.json` only | True isolation breach — stop and inspect; volatile-path drift alone must NOT fire |
| real door regression | handshake or nonce assert fails, pins intact | Bisect against the pinned version; file upstream if opencode-side |
Re-observation checklist on a version bump: npm pin captures (§Pin), help-surface
diff (`--help`, `run --help`, `mcp --help`, `mcp add --help`), the
`gbrain init --pglite` in a non-TTY context (Docker `RUN`, CI step, postinstall hook) exits 1 when no embedding-provider API key is present in the environment. This is a deliberate fail-loud — the alternative is a silent-broken state where init succeeds with a default that doesn't match any real key.
`gbrain init --pglite` in a non-TTY context (Docker `RUN`, CI step, postinstall hook) with no embedding-provider API key continues **keyless** (keyword-only search) with a loud notice — a first-class supported end state, not an error (Pattern 3 below). Init reads keys from the environment or from `~/.gbrain/config.json` (env wins). Two fail-louds remain: a near-miss env var name (e.g. `OPENAPI_API_KEY`) exits 1 with the corrected spelling instead of being silently ignored, and multiple keys with no canonical candidate exit 1 asking for an explicit `--embedding-model`.
Three patterns work for headless installs. Pick whichever fits your image lifecycle.
@@ -13,23 +13,25 @@ If your CI / Docker pipeline can inject the API key as a build-time env var, set
FROM oven/bun:1 AS builder
# Inject key at build via --build-arg or `--env` from CI.
ARG OPENAI_API_KEY
ENV OPENAI_API_KEY=$OPENAI_API_KEY
ARG VOYAGE_API_KEY
ENV VOYAGE_API_KEY=$VOYAGE_API_KEY
RUN bun install -g github:garrytan/gbrain#latest-stable
RUN gbrain init --pglite # auto-picks OpenAI, persists config
RUN gbrain init --pglite # auto-picks the Voyage default (voyage-4 @ 1024d), persists config
```
```yaml
# GitHub Actions equivalent
- name: Initialize gbrain
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
run: |
bun install -g github:garrytan/gbrain#latest-stable
gbrain init --pglite
```
Any provider key works the same way (`OPENAI_API_KEY` → OpenAI, etc.); see [the provider matrix](../integrations/embedding-providers.md).
Init writes `~/.gbrain/config.json` with the resolved `embedding_model` + `embedding_dimensions`. Subsequent runs (in the same image / runner) read from that config and don't re-resolve.
## Pattern 2: Provider key only at runtime (deferred-setup)
@@ -44,19 +46,20 @@ RUN bun install -g github:garrytan/gbrain#latest-stable
# width, but no embed callsite will actually run until runtime config.
RUN gbrain init --pglite --no-embedding
# At container start (entrypoint), provide the real provider:
# At container start (entrypoint), the runtime env now carries the key —
# re-init resolves the provider from it (or pin one explicitly with
# --embedding-model <provider>:<model>):
ENTRYPOINT ["/bin/sh", "-c", "\
gbrain config set embedding_model openai:text-embedding-3-large \
&& gbrain init --force --pglite \
gbrain init --force --pglite \
&& exec gbrain serve"]
```
The `gbrain init --no-embedding` opt-in writes `embedding_disabled: true` to config. Every embed callsite (`gbrain import`, `gbrain embed`, the `runEmbedCore` library entry point) checks this and refuses cleanly with a `gbrain config set embedding_model <id>` hint rather than proceeding with a silent default.
The `gbrain init --no-embedding` opt-in writes `embedding_disabled: true` to config. Every embed callsite (`gbrain import`, `gbrain embed`, the `runEmbedCore` library entry point) checks this and refuses cleanly with a re-init hint (`gbrain init --force --embedding-model voyage:voyage-4`) rather than proceeding with a silent default. (`gbrain config set embedding_model` is refused by design — it's a file-plane schema-sizing field the DB-plane command can't affect.)
The runtime `gbrain init --force` re-runs the init flow against the now-populated env, which:
- Removes `embedding_disabled` from config.
- Resolves the provider via env detection.
- Removes `embedding_disabled` from config (an explicit `--embedding-model` flag also clears it).
- Resolves the provider via key detection (env vars or `~/.gbrain/config.json`).
- Re-templates the PGLite schema if dim differs from the build-time default.
## Pattern 3: No key, ever (keyless mode)
@@ -73,15 +76,16 @@ RUN gbrain init --pglite --no-embedding # keyless install — done; no runtime
Since every embedding cost gate is structurally moot with no key, none of `docs/operations/spend-controls.md` applies until you add one.
## What WON'T work
## What changed from older releases
```dockerfile
# Don't do this — silent default leaves you with vector(1280) ZE column
# and 1536d OpenAI provider at runtime, mismatched.
RUN gbrain init --pglite
# On older gbrain releases this persisted a silent provider default that
# mismatched the runtime key (a legacy-width column with a different-width
# provider at runtime).
RUN gbrain init --pglite # no keys in the build env
```
If an older image used this pattern, `gbrain doctor` will surface the mismatch on first run after upgrade and print a paste-ready repair command — `gbrain init --force --pglite --embedding-model <model> --embedding-dimensions <dims>` for brains with no embeddings yet, `gbrain migrate embeddings --to <model> --dim <dims>` for non-empty brains.
It now continues keyless — the same end state as Pattern 3 — and recovery is Pattern 2's runtime `gbrain init --force`. If an older image shipped the mismatched shape, `gbrain doctor` will surface the mismatch on first run after upgrade and print a paste-ready repair command — `gbrain init --force --pglite --embedding-model <model> --embedding-dimensions <dims>` for brains with no embeddings yet, `gbrain migrate embeddings --to <model> --dim <dims>` for non-empty brains.
| `gated` (default) | Every cost gate enforces its limit as documented below. |
| `tokenmax` | Every embedding-spend gate in the table below prints its estimate and **proceeds** — informational only. Spend is still recorded to the ledger; posture removes the *ceiling*, not the *accounting*. (Commands with their own LLM cost caps outside this doc's embedding scope — e.g. `extract-conversation-facts --max-cost-usd` — don't resolve posture; their per-call flags govern.) |
| `tokenmax` | Every embedding-spend gate in the table below prints its estimate and **proceeds** — informational only. Spend is still recorded to the ledger; posture removes the *ceiling*, not the *accounting*. (Commands with their own LLM cost caps outside this doc's embedding scope — e.g. `extract-conversation-facts --max-cost-usd`, `dream retriage --max-usd` (an estimate-based soft stop) — don't resolve posture; their per-call flags govern.) |
`spend.posture` is deliberately separate from `search.mode=tokenmax` (which governs
retrieval payload size, not embedding spend). When a gate fires and
@@ -204,7 +204,7 @@ gbrain schema add-alias researcher person
Read [`skills/conventions/schema-evolution.md`](../skills/conventions/schema-evolution.md) for the decision tree on when to add types vs aliases vs prefixes. The short version: <20 pages → don't pack-codify; 20-100 → alias on existing type; 100+ → first-class type.
**Lint your pack before shipping.** The 11-rule lint surface (with the optional `--with-db` flag for DB-aware checks) catches dangling references, prefix collisions, and dead-corpus warnings:
**Lint your pack before shipping.** The 14-rule lint surface (with the optional `--with-db` flag for DB-aware checks, including the stored-type alias/undeclared rules) catches dangling references, prefix collisions, and dead-corpus warnings:
@@ -493,9 +493,9 @@ OAuth source scoping only guards the HTTP MCP path. If the brain's Postgres and
## Part 13: Cost and speed expectations
Real numbers from the published benchmark, running the default stack (GBrain with ZeroEntropy for embedding + reranker):
Real numbers from the published benchmark. The benchmark ran the then-default ZeroEntropy stack (now deprecated — its hosted API ends 2026-09-04); the current default is Voyage `voyage-4` + `rerank-2.5`, in the same price and latency class:
- **Embedding cost:** $0.05 per million tokens. For comparison, GBrain configured with OpenAI is $0.13 (2.6× more expensive), Voyage is $0.18 (3.6× more).
- **Embedding cost:** the current default (`voyage:voyage-4`) is $0.06 per million tokens; the benchmark's ZeroEntropy stack was $0.05. For comparison, GBrain configured with OpenAI is $0.13.
- **Ingest speed:** about 22 seconds for a small test corpus of 164 pages on the host machine. For a 10K-page corpus, expect about 20 minutes the first time, then most syncs are incremental and finish in seconds.
- **Query latency:** about 122 ms median for a `gbrain search`. For comparison, the same query through GBrain with OpenAI takes about 282 ms.
- **Synthesized-answer latency:** a few seconds, dominated by the Anthropic API.
@@ -503,7 +503,7 @@ Real numbers from the published benchmark, running the default stack (GBrain wit
Full methodology and per-run receipt JSONs live in [the gbrain-evals repo](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-05-23-v0.40.6.0-snapshot.md).
For a 25-person company at sustained use, expect about $35 a month in embeddings (ZeroEntropy at $0.05/million tokens), $50 a month in Anthropic calls for the synthesized-answer queries, plus your hosting bill. Under $100 a month for the AI side at most companies your size.
For a 25-person company at sustained use, expect about $40 a month in embeddings (the default `voyage-4` at $0.06/million tokens), $50 a month in Anthropic calls for the synthesized-answer queries, plus your hosting bill. Under $100 a month for the AI side at most companies your size.
---
@@ -515,7 +515,7 @@ Check `gbrain auth list` on the host and confirm their client has `--source` set
### "Sync is slow and feels stuck"
The first sync embeds every page, which takes time. Check `gbrain sources status` for the live page count. If it's climbing you're not stuck, you're just embedding. If you've got a 10K-page corpus and ZeroEntropy is being throttled, the per-source parallel sync looks like progress on three sources at once rather than one source moving fast.
The first sync embeds every page, which takes time. Check `gbrain sources status` for the live page count. If it's climbing you're not stuck, you're just embedding. If you've got a 10K-page corpus and your embedding provider is throttling you, the per-source parallel sync looks like progress on three sources at once rather than one source moving fast.
instead of the full operation catalog, so the agent sees a tight, stable surface
instead of a 110-tool wall. Drop the flag (or pass `--surface full`) for every
instead of a 110-tool wall. `--surface starter` sits between: the verbs plus the
daily-driver set (core page/search/graph ops + capture). Drop the flag (or pass `--surface full`) for every
operation. The default when the flag is omitted is `full`, so existing wire-ups
are unchanged.
@@ -192,12 +193,12 @@ about people, companies, decisions, projects, or past context:
tokens → `search` (cheap hybrid, no expansion). Concept, landscape, or
"all the X that do Y" questions → `query` FIRST — it recovers synonym
phrasings `search` misses, and a populated `search` result set is not proof
of coverage. On the five-verb surface the same split is `recall` (retrieve)
of coverage. On the verbs surface the same split is `recall` (retrieve)
vs `synthesize` (reasoned answer). Check the brain BEFORE answering from
memory or asking me. Never ask "who is X?" or "what did we decide about Y?"
before checking — the brain probably already knows.
2. **Write back.** When I make a decision, mention a new person/company, or land
on an idea worth keeping, write it to the brain: `remember` on the five-verb
on an idea worth keeping, write it to the brain: `remember` on the verbs
surface (one fact, with provenance), or `put_page` on the full surface
(entity pages under people/, companies/; decisions under decisions/ or
notes/). One insight, one page, linked.
@@ -222,7 +223,7 @@ hundreds of linked pages and patterns you didn't know were there.
**3. Briefing from your brain (not from the internet).** *"What do I need to know
before my 2pm with the Acme team?"* pulls your meeting history, the people,
what's still open, what the brain doesn't know yet. The agent does your prep
because it read your context. (`query` — `synthesize` on the five-verb surface —
because it read your context. (`query` — `synthesize` on the verbs surface —
gives you the synthesized answer with citations; this is the example on the
[README](../../README.md).)
@@ -243,7 +244,7 @@ habits to build. Your agent stops being amnesiac.
| Agent "can't reach the brain" (Path A) | `gbrain serve --http` bound to loopback | Restart with `--bind 0.0.0.0` |
| `list_skills` returns nothing / errors | Skill publishing OFF on the host | `gbrain config set mcp.publish_skills true` |
| Token rejected on first call | Wrong/expired token | Re-mint with `gbrain auth create`; `--install` smoke-tests it for you |
| `unknown tool: capture` | `capture` is CLI-only, not an MCP tool | Use `put_page` over MCP; `capture` only on the CLI |
| `unknown tool: capture` | Your surface predates v0.47 or your token's surface was narrowed | Upgrade the host (capture is on starter + full now); on narrowed tokens use `put_page`, or `remember` on the verbs surface |
| Empty results (Path B) | Brain has nothing in it yet | `gbrain import ~/notes/` or `gbrain capture "..."` |
@@ -106,8 +106,7 @@ In the AlphaClaw UI (Providers tab):
- **OpenAI API Key.** Required for embeddings if you use the OpenAI provider.
- **Anthropic API Key.** Required for Claude (the main model the agent talks through).
- **Perplexity API Key.** Optional, for web search.
- **Voyage API Key.**Optional, alternative to OpenAI for embeddings.
- **ZeroEntropy API Key.** Recommended. GBrain ships with ZeroEntropy as the default embedder + reranker because it's about 2× faster than OpenAI and about 2.6× cheaper.
- **Voyage API Key.**Recommended. GBrain ships with Voyage as the default embedder + reranker (`voyage-4` + `rerank-2.5`) — one key covers both, at about half OpenAI's embedding price.
You can use the same keys across multiple agents.
@@ -236,7 +235,7 @@ Brains share through git. My main agent can populate another agent's brain by pu
|-----------|-------------|
| Render Pro (minimum viable) | about $85 |
| Supabase (small) | free to $25 |
| OpenAI API (embeddings) | $5 to $20 (much less if you use ZeroEntropy as the default) |
| OpenAI API (embeddings) | $5 to $20 (about half that on the default Voyage stack) |
| Anthropic API (Claude) | $50 to $500 (usage dependent) |
| **Total minimum** | **about $100 to $150 a month** |
`gbrain-allow-unscoped-getpage` for read-only first-match sites).
- **JSONB: never `JSON.stringify` into a `::jsonb` cast.** postgres.js double-encodes it (a jsonb
string scalar); PGLite hides the bug. This bites BOTH spellings — the template form
(`${JSON.stringify(x)}::jsonb`) AND the positional form (`executeRaw(\`…$N::jsonb\`, [JSON.stringify(x)])`,
@@ -225,7 +230,11 @@ Per-file detail is in `docs/architecture/KEY_FILES.md`.
- **Engine-live paths avoid runtime dynamic `import()` for helper dependencies.** In
`src/core/pglite-engine.ts`, `src/core/postgres-engine.ts`, and
`src/core/migrate.ts`, dependencies previously reached through runtime dynamic
imports use static top-level imports. The only current dynamic-`import()` exceptions
imports use static top-level imports. Besides the snapshot loader's lazy
`require()` cluster in `pglite-engine.ts:tryLoadSnapshot` (fs/crypto/
migrate/pglite-schema + one gateway shape lookup — lazy so production
builds without the test-fixture path don't eager-load; the guard now
matches `require()` calls too), the only dynamic-`import()` exceptions
are the four `ai/gateway.ts` lookups in both engines'
`initSchema()` and `_upsertChunksOnce()` methods; each remains lazy inside a
local `try/catch` because the gateway has a large provider/config closure and,
@@ -256,6 +265,26 @@ Per-file detail is in `docs/architecture/KEY_FILES.md`.
(fail-closed vs warn-only vs null), not its own numbers. Pinned by `test/model-pricing.test.ts`
(drift guard asserts each view equals canonical). Embeddings price separately in
`embedding-pricing.ts` (different unit).
- **Module-size ratchet.** `scripts/module-size-limits.tsv` pins per-file line ceilings
(`check:module-size` in verify): growth over a ceiling, >50 lines of stale slack after a
shrink, a row for a deleted file, and any UNLISTED src file over 1,500 lines all fail.
Raise a ceiling only via a reviewer-visible TSV edit in the same commit; lower it in the
same commit as any peel. migrate.ts is `region-exempt` (the MIGRATIONS array grows freely;
the runner logic around it is ratcheted).
- **Peeled façades keep their surface.** operations.ts (`src/core/ops/*`), doctor.ts
(`src/commands/doctor/*`), sync.ts (`src/core/sync-*`), and both engines
(`src/core/{postgres,pglite}-engine/*`) are façades re-exporting everything they always
exported — import sites and published package exports never chase the peel. New code goes
in the module dirs, not back into the façades. Engine modules take narrow explicit deps
(never an engine-shaped bag); doctor source-text guards read `test/helpers/doctor-source.ts`,
and the flag-registry generator's `facadeExpansion` keeps peeled flag text in each command's
scan surface.
- **Coverage is measured, honestly.** CI merges per-lane lcov (`scripts/merge-lcov.ts`) into
a PR-corpus report on every run (advisory until the diff gate graduates via
`COVERAGE_GATE_ENFORCE`) and a nightly fullCorpus number incl. the full e2e glob. bun
facts: unique `--coverage-dir` per process (reuse overwrites lcov.info), line records only
(JSC omits function names), no subprocess coverage (cli.ts is exempt as a documented
undercount), never-loaded files are a count+list, never fake all-files math.
## Reference map (load on demand)
@@ -636,7 +665,7 @@ ms, max waiters) for `--json`; a one-line summary prints to stderr.
## Version locations (single source of truth: `VERSION` file)
Every release advances the version in **six files at once**. Keep these in
Every release advances the version in **seven files at once**. Keep these in
sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
package.json drift), but the canonical list lives here so future runs and
the auto-update agent know where to look.
@@ -652,7 +681,7 @@ four numeric segments are required first. Historical 3-segment versions
(`0.31.3`, `0.22.1`) remain valid in `git log` and migration filenames
(`skills/migrations/v0.21.0.md`); do NOT rewrite them. Going forward only.
**Required (every release must update all six):**
**Required (every release must update all seven):**
| File | What lives there | Format |
|---|---|---|
@@ -661,12 +690,19 @@ four numeric segments are required first. Historical 3-segment versions
| `CHANGELOG.md` | Top entry header `## [0.31.4.1] - YYYY-MM-DD` plus the "To take advantage of v0.31.4.1" block. | Standard Keep-a-Changelog header. |
| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z.W" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z.W` references in TODO bodies. |
| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z.W (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z.W (#NNN, contributed by @user)` references. |
| `openclaw.plugin.json` | OpenClaw plugin manifest (v0.45.6.0, #4033). Hand-maintained; `test/openclaw-plugin-manifest.test.ts` fails the suite if it drifts from `package.json`. Merges from master auto-resolve it to master's version — re-bump it with the trio. | `"version": "0.45.8.0"` |
| `openclaw.plugin.json` | OpenClaw plugin manifest (v0.45.6.0, #4033). Hand-maintained; `test/openclaw-plugin-manifest.test.ts` fails the suite if it drifts from `package.json`. Merges from master auto-resolve it to master's version — re-bump it with the trio. | `"version": "0.45.12.0"` |
| `.codex-plugin/plugin.json` + `.claude-plugin/plugin.json` | Codex + Claude Code plugin manifests. Hand-maintained; `test/codex-plugin-manifest.test.ts` fails the suite when either drifts from `package.json` (the bump is now a FIVE-file lockstep: VERSION, package.json, openclaw.plugin.json, and both plugin manifests). Merges from master auto-resolve them to master's version — re-bump with the version set. | `"version": "0.46.7.0"` |
| `BOOTSTRAP_FOR_AGENTS.md` | Runbook stamp on line 1. `scripts/check-bootstrap-tag.sh` (in `bun run verify` + CI) fails when it drifts from `VERSION`; refresh it in the same commit as the bump. | `<!-- gbrain-runbook-stamp: X.Y.Z.W -->` |
| `templates/bootstrap/template-repo/` | Vendored template tree with an embedded version stamp. Auto-derived, but NOT by `bun install`: run `bun run scripts/generate-template-repo.ts --out templates/bootstrap/template-repo` after the bump; `scripts/check-bootstrap-templates.sh` fails CI on drift. | `<!-- gbrain-template-stamp: X.Y.Z.W -->` in generated files. |
**Auto-derived (no manual edit; refreshed by their own commands):**
- `plugin/` — the committed codex/claude plugin skill tree embeds a
`gbrain-plugin-tree-stamp: X.Y.Z.W` in its generated README, so every
version bump drifts it. Regenerate after the bump: `bun run
scripts/generate-plugin-tree.ts --out plugin` (guarded by
`scripts/check-plugin-tree.sh` in `bun run verify`; the release
`publish-codex-plugin` job also drift-gates it before publishing).
- `bun.lock` — root-package version is auto-pinned from `package.json`. After
bumping `package.json`, run `bun install` to refresh the lockfile.
The add is lazy (exit 0 without connecting) — verify with `opencode mcp list`,
which spawns the server and must show `✓ gbrain connected` (the exit code is 0
even on failure; read the output). Restart opencode afterwards — it reads
config at session start. Verified against opencode v1.18.18. Full reference:
[docs/mcp/OPENCODE.md](docs/mcp/OPENCODE.md).
Whether you scaffolded or not, read `skills/RESOLVER.md` (in your workspace, or the
bundled copy at `~/gbrain/skills/RESOLVER.md` when running from the cloned repo). It's
the skill dispatcher — tells you which skill to read for any task. Save this to your
@@ -1510,11 +1601,13 @@ wins; fix the row.
|---------|-------|
| "Set up GBrain", first boot | `skills/setup/SKILL.md` |
| "Now what?", "fill my brain", "cold start", "bootstrap my data", "import my data", "what should I import first" | `skills/cold-start/SKILL.md` |
| "Install gbrain into this agent/harness", "agent workspace bootstrap", "gbrain bootstrap", "wire gbrain hooks", "set up the maintenance sweep" | Run `gbrain bootstrap` (paste-in harness install: hooks + sweep + config). See `docs/guides/bootstrap.md` |
| "agent workspace bootstrap", "install gbrain into this agent workspace", "gbrain bootstrap", "paste-in install", "set up the maintenance sweep" | Run `gbrain bootstrap` (paste-in workspace install: interview + identity files + hooks + sweep). See `docs/guides/bootstrap.md` |
| "wire this box's coding agents to the brain", "framework-spawned sessions need brain access", "wire gbrain hooks without a workspace", "hook Claude Code/Codex to the running serve" | Run `gbrain bootstrap harness --yes` (machine-level wiring to a running `serve --http`: scoped token + user-scope MCP + headless pre-approval + hooks; no agent.json). See the "Local harness mode" section of `docs/guides/bootstrap.md` |
| "Migrate from Obsidian/Notion/Logseq" | `skills/migrate/SKILL.md` |
| "Switch embedding provider" / "migrate my embeddings" / "switch reranker" / "ZeroEntropy" / "provider_sunset" / "search stopped working after a provider shutdown" | `skills/migrations/v0.46.3.0.md` |
| Brain health check, maintenance run | `skills/maintain/SKILL.md` |
| "Run dream", "process today's session", "synthesize my conversations", "consolidate yesterday's conversations", "what patterns did you see", "did the dream cycle run" | `skills/maintain/SKILL.md` (dream cycle section) |
| "Run dream", "process today's session", "synthesize my conversations", "consolidate yesterday's conversations", "what patterns did you see", "did the dream cycle run", "retriage the backlog", "re-score the triage" | `skills/maintain/SKILL.md` (dream cycle section) |
| "Brain health", "what features am I missing", "brain score" | Run `gbrain features --json` |
| "Set up autopilot", "run brain maintenance", "keep brain updated" | Run `gbrain autopilot --install --repo ~/brain` |
| "Upgrade gbrain", "update gbrain", "gbrain update available", `UPGRADE_AVAILABLE`, "is gbrain up to date" | `skills/gbrain-upgrade/SKILL.md` |
@@ -1596,7 +1689,7 @@ The point of building a 150K-page brain is to use it as a strategic moat. To nev
It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
> **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
> **~15 minutes to a working personal agent** on the recommended Codex / Claude Code path (mostly a short interview); ~30 minutes for the always-on OpenClaw / Hermes setup. Database ready in 2 seconds either way (PGLite, no server).
> **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
@@ -1660,7 +1753,7 @@ GBrain is designed to be installed and operated by an AI agent. **New to GBrain?
### For Codex — the recommended first step
Turn Codex into your persistent personal agent. Works in the **ChatGPT desktop app** (open Codex on a folder) and in the **Codex CLI** (`codex` in a terminal) — same install, same result. Open Codex in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, which bootstrap creates and privacy-verifies for you. Then paste:
Turn Codex into your persistent personal agent. (Just want the brain + skills without the full agent? `codex plugin marketplace add garrytan/gbrain@codex-plugin` then `codex plugin add gbrain@gbrain` — see [docs/mcp/CODEX.md](docs/mcp/CODEX.md). The paste block below builds the whole agent.) Works in the **ChatGPT desktop app** (open Codex on a folder) and in the **Codex CLI** (`codex` in a terminal) — same install, same result. Open Codex in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, which bootstrap creates and privacy-verifies for you. Then paste:
```
Read and follow every step of:
@@ -1671,7 +1764,9 @@ answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Codex will ask for command approvals during the install — approving them is the sandbox working as intended. What you get, in about 15 minutes: a short interview (6 required questions) → your agent's identity (SOUL.md, USER.md, MEMORY.md) rendered from your own answers, never invented → a local PGLite brain (2 seconds, no server, no Docker) → MCP wired so every session can search and write memory → a **private** GitHub repo, created and privacy-verified, as your agent's durable body. Works with **zero API keys** — keyword search plus memory your agent writes itself; one optional key (OpenAI, Anthropic, or Voyage) upgrades to semantic search and automatic fact extraction. Codex reads brain context through its tools each turn (pull-based).
Codex will ask for command approvals during the install — approving them is the sandbox working as intended. What you get, in about 15 minutes: a short interview (6 required questions) → your agent's identity (SOUL.md, USER.md, MEMORY.md) rendered from your own answers, never invented → a local PGLite brain (2 seconds, no server, no Docker) → MCP wired so every session can search and write memory → a **private** GitHub repo, created and privacy-verified, as your agent's durable body. Works with **zero API keys** — keyword search plus memory your agent writes itself; one optional key upgrades capabilities (OpenAI: semantic search + automatic fact extraction; Voyage: semantic search; Anthropic: fact extraction). Codex reads brain context through its tools each turn (pull-based). The click moment: tell it one small thing to remember, restart Codex, then ask for it back — the answer comes from the brain, not from this chat's context (which the restart cleared). That cross-session round-trip is the whole product; "what's my name / my top jobs?" is answered from your identity files, which is nice but not the same trick.
Two things worth understanding once it's running: **you own the brain** — every memory is a markdown file in that private repo (read it, clone it to a second machine, delete it and the brain is gone) — and **the first skill to run is `cold-start`**: say "fill my brain" and your agent imports your Gmail, calendar, and contacts (via [ClawVisor](https://clawvisor.com), an OAuth vault so the agent never holds raw tokens) or offline archives like Google Takeout, one consented step at a time. An empty brain is a database; a filled one is a memory.
> **Prefer to make the repo yourself?** Create a new **empty** private repo **under your own GitHub account** (no README/.gitignore/license), clone it, open the clone in Codex, and paste the same block — bootstrap detects your empty repo and adopts it instead of creating one. The repo must be empty and personal-account-owned; org-owned repos are refused (create one under your account, or let bootstrap make it).
@@ -1688,7 +1783,7 @@ answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Everything from the Codex path applies — interview, identity from your own answers, local brain, private repo, keyless mode — plus Claude Code gets **per-turn context hooks**: your brain loads automatically into every prompt, and your work persists to your private repo on a per-turn cadence (debounced ~5 min locally, every turn in a cloud sandbox — this covers the `/exit` case the harness never fires a session-end hook on), with a notice on your next turn if a push ever fails. This works in a **Claude Code cloud session** too, not just on your laptop: verification falls back to pure git protocol when the sandbox blocks the GitHub API, and `gbrain bootstrap cloud-setup-script` prints the environment setup recipe. Restart the session after install and ask "what did I tell you my top jobs were?" — that's the moment it clicks. Full contract, security posture, cloud sandboxes, and uninstall: [docs/guides/bootstrap.md](docs/guides/bootstrap.md).
Everything from the Codex path applies — interview, identity from your own answers, local brain, private repo, keyless mode — plus Claude Code gets **per-turn context hooks** (on by default, with an opt-out): your brain loads automatically into every prompt, and your work persists to your private repo on a per-turn cadence (debounced ~5 min locally, every turn in a cloud sandbox — this covers the `/exit` case the harness never fires a session-end hook on), with a notice on your next turn if a push ever fails. This works in a **Claude Code cloud session** too, not just on your laptop: verification falls back to pure git protocol when the sandbox blocks the GitHub API, and `gbrain bootstrap cloud-setup-script` prints the environment setup recipe. The click moment: tell it one small thing to remember, restart the session, then ask for it back — a fresh session has no chat context, so the answer can only come from the brain. That cross-session round-trip is the whole product ("what's my name?" is answered from your identity files — nice, but not the same trick). Same two follow-ups as the Codex path: you own the brain (markdown in your private repo), and `cold-start` is the first skill to run — "fill my brain" imports your email, calendar, and contacts (ClawVisor) or offline archives, one consented step at a time. Full contract, security posture, cloud sandboxes, and uninstall: [docs/guides/bootstrap.md](docs/guides/bootstrap.md).
> **Prefer to make the repo yourself?** Create a new **empty** private repo **under your own GitHub account** (no README/.gitignore/license), clone it, open the clone in Claude Code (CLI or the desktop app's open-a-repo flow), and paste the same block — bootstrap adopts your empty repo instead of creating one. The repo must be empty and personal-account-owned; org-owned repos are refused.
@@ -1748,9 +1843,13 @@ Postgres-at-scale, Supabase, and thin-client setup paths live in [`docs/INSTALL.
GBrain exposes nearly all of its 100+ operations as MCP tools (stdio and HTTP; a handful of local-only ops stay CLI-side) — or exactly the seven memory verbs with `--surface verbs`. The specific snippet depends on which client you use:
- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — local: one command, `claude mcp add gbrain -- gbrain serve` (zero server, zero tunnel). Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).
- **[Codex](docs/mcp/CODEX.md)** — `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`). Codex reads the bearer from `$GBRAIN_REMOTE_TOKEN` at runtime, so the token never lands in Codex config.
- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — plugin: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain` (MCP + skills). Or local one-liner: `claude mcp add gbrain -- gbrain serve` (zero server, zero tunnel). Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).
- **[Codex](docs/mcp/CODEX.md)** — plugin (recommended): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain` installs the MCP server AND the curated skill set. Or connect-only: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`); Codex reads the bearer from `$GBRAIN_REMOTE_TOKEN` at runtime, so the token never lands in Codex config.
- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve"]}` to your MCP config.
- **[Hermes](docs/mcp/HERMES.md)** — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve`. Keep `--args` last, and verify with `hermes mcp test gbrain` (the add exits 0 even on failure).
- **[Grok Build](docs/mcp/GROK.md)** — `grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- gbrain serve --surface verbs`. The add is lazy (exit 0 without connecting) — verify with `grok mcp doctor gbrain`, which spawns the server and reports `7 tools discovered`. Verified against Grok Build v1.0.4.
- **[opencode](docs/mcp/OPENCODE.md)** (opencode.ai / SST — not OpenClaw) — `opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- gbrain serve --surface verbs`, or let `gbrain bootstrap hooks --harness opencode` write the config for you (opencode is a bootstrap-supported harness — it reads AGENTS.md natively). The add is lazy — verify with `opencode mcp list`, which spawns the server (`✓ gbrain connected`). Remote: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]` — the config stores only the `{env:GBRAIN_REMOTE_TOKEN}` interpolation. Verified against opencode v1.18.18.
- **[OpenClaw](docs/mcp/OPENCLAW.md)** — the ClawHub bundle plugin registers gbrain automatically (`openclaw.plugin.json` ships in this repo), or add `{"command": "gbrain", "args": ["serve"]}` to `~/.openclaw/config.json`'s `mcpServers`.
- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.
- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.
- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — `gbrain connect https://your-host/mcp --agent perplexity --oauth --register` mints a least-privilege OAuth client and prints the Issuer/Client ID/Secret to paste into Settings → Connectors (OAuth is the right path for a cloud connector; a bearer token also works for local use). Pro subscription required.
@@ -1811,6 +1910,21 @@ curl -X POST https://your-brain/ingest \
For mobile capture, the inbox folder source picks up anything dropped into
`~/.gbrain/inbox/` from iOS Shortcuts / AirDrop / Drafts / Finder.
Your other agents' histories import in one command. `gbrain transcripts ingest`
gbrain transcripts status # found vs imported, per harness
```
Third-party skillpacks can ship custom ingestion sources (Granola, Linear,
voice, OCR) against the versioned `IngestionSource` contract at
`gbrain/ingestion`. See [`docs/skillpack-anatomy.md`](docs/skillpack-anatomy.md).
@@ -1868,11 +1982,11 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec
## Capabilities
**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). The install picker default-applies `tokenmax` (it recommends `conservative` for Haiku-class subagent tiers or keyless setups); a brain with `search.mode` unset resolves to `balanced` at query time. The ZeroEntropy reranker is on in `balanced` and `tokenmax`, off in `conservative`. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns. Vector retrieval pools the best chunk per page, so a page surfaces on its strongest evidence instead of losing to a neighbor on one weak chunk. Queries that match a page's title phrase or a declared free-text alias (`gbrain reindex --aliases` backfills existing pages) get boosted to the page they name. Every result carries an `evidence` tag (why it matched) and a `create_safety` hint (`exists` / `probable` / `unknown`) so an agent decides whether a page already exists instead of guessing from a raw score. `gbrain search diagnose "<query>" --target <slug>` traces which retrieval layer surfaces (or misses) a page.
**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). The install picker default-applies `tokenmax` (it recommends `conservative` for Haiku-class subagent tiers or keyless setups); a brain with `search.mode` unset resolves to `balanced` at query time. The cross-encoder reranker is on in `balanced` and `tokenmax`, off in `conservative` — new installs get Voyage `rerank-2.5`; brains that never set `search.reranker.model` still fall back to the deprecated ZeroEntropy `zerank-2` (hosted API ends 2026-09-04) until the September cutover. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns. Vector retrieval pools the best chunk per page, so a page surfaces on its strongest evidence instead of losing to a neighbor on one weak chunk. Queries that match a page's title phrase or a declared free-text alias (`gbrain reindex --aliases` backfills existing pages) get boosted to the page they name. Every result carries an `evidence` tag (why it matched) and a `create_safety` hint (`exists` / `probable` / `unknown`) so an agent decides whether a page already exists instead of guessing from a raw score. `gbrain search diagnose "<query>" --target <slug>` traces which retrieval layer surfaces (or misses) a page.
**Self-wiring knowledge graph.** Every `put_page` extracts entity refs from markdown/wikilinks/typed-link syntax and writes edges with zero LLM calls. Typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, …). Multi-hop traversal via `gbrain graph-query`. The graph is what produces the +31.4 P@5 lift over vector-only RAG. **Obsidian-style vaults:** bare `[[note-name]]` wikilinks that point across folders — you wrote `[[struktura]]` but the page lives at `projects/struktura.md` — resolve by basename once you opt in with `gbrain config set link_resolution.global_basename true`. Off by default; `gbrain doctor` tells you how many edges you'd gain before you flip it. See [migrating an Obsidian vault](INSTALL_FOR_AGENTS.md#step-45-wire-the-knowledge-graph).
**Job queue (Minions).** BullMQ-shaped, Postgres-native job queue. Durable subagents (LLM tool loops that survive crashes via two-phase pending→done persistence), shell jobs with audit, child jobs with cascading timeouts, rate leases for outbound providers, attachments via S3/Supabase storage. Replaces "spawn subagent as fire-and-forget Promise" with something that recovers from anything.
**Job queue (Minions).** BullMQ-shaped, Postgres-native job queue. Durable subagents (LLM tool loops that survive crashes via two-phase pending→done persistence), shell jobs with audit, child jobs with cascading timeouts, rate leases for outbound providers, attachments via S3/Supabase storage. Opt-in per-job process isolation (`gbrain jobs work --job-isolation process`) runs each claimed job in its own SIGKILL-able child process, so a stuck handler dies for real and a crash takes one job instead of the whole worker; when the worker's DB health probe fails, it names the failing layer (`pool_starved` vs `server_unreachable`) instead of a blanket "DB unreachable". Sizing and rollout guidance in [`docs/guides/minions-deployment.md`](docs/guides/minions-deployment.md); probe-verdict triage in [`docs/guides/queue-operations-runbook.md`](docs/guides/queue-operations-runbook.md). Replaces "spawn subagent as fire-and-forget Promise" with something that recovers from anything.
**Non-English brains (FTS language config).** The Postgres full-text search tokenizer is configurable via `GBRAIN_FTS_LANGUAGE`. Defaults to `english`. Set it to any text-search configuration that exists in your Postgres instance:
@@ -1906,8 +2020,8 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
- **Email + calendar**: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md).
- **Embedding providers**: a dozen providers covered — OpenAI (default fallback), OpenRouter, Voyage, ZeroEntropy (default), Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy. Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md).
- **Rerankers**: ZeroEntropy `zerank-2` hosted (the default; on in `balanced` and `tokenmax` modes) plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp — runs Qwen3-Reranker or self-hosted ZeroEntropy weights against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).
- **Embedding providers**: a dozen providers covered — Voyage (default: `voyage-4` @ 1024d), OpenAI, OpenRouter, Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy, plus ZeroEntropy (deprecated — hosted API ends 2026-09-04). Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md).
- **Rerankers**: Voyage `rerank-2.5` hosted (the new-install default; reranking is on in `balanced` and `tokenmax` modes, same `VOYAGE_API_KEY` as embeddings), ZeroEntropy `zerank-2` (deprecated — hosted API ends 2026-09-04; still the fallback for brains that never set `search.reranker.model`), plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp — runs Qwen3-Reranker or self-hosted zerank weights against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).
- **MCP clients**: every major MCP client is supported. [`docs/mcp/`](docs/mcp/) per-client setup.
@@ -1925,7 +2039,7 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
**PGLite crashes at startup with `RuntimeError: Aborted()` (often right after a macOS upgrade)?** Not a macOS incompatibility — the OS-upgrade reboot killed gbrain mid-write and tore the data dir's WAL. gbrain now repairs this automatically on the next command (data preserved, backup kept); if auto-repair is disabled or skipped, run `gbrain pglite-repair --dry-run` to diagnose and `gbrain pglite-repair --yes` to repair in place. Full recovery ladder (repair → rebuild → engine switch) in [`docs/ENGINES.md` — Troubleshooting: startup abort](docs/ENGINES.md#troubleshooting-startup-abort-runtimeerror-aborted) and [`docs/INSTALL.md`](docs/INSTALL.md#pglite-crashes-on-macos-26x-tahoe).
**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment: set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain migrate embeddings` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys: set `VOYAGE_API_KEY` (or `OPENAI_API_KEY` / another provider key) in the environment — or in `~/.gbrain/config.json`, which init also reads — before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker (non-TTY auto-picks the Voyage default when its key is present). With no keys at all, init continues keyless (keyword-only search) with a loud notice; add a key later and re-run `gbrain init --force --embedding-model voyage:voyage-4` to enable embeddings, or pass `--no-embedding` up front to make keyless explicit. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
**Hourly cron sync keeps timing out on a federated brain?** Switch your
cron to a per-source loop with shell `timeout(1)` doing the OS-level kill
@@ -2043,7 +2157,7 @@ the page PK, soft-delete-filtered, source-safe) and completes in seconds.
## Docs
- [`docs/INSTALL.md`](docs/INSTALL.md) — every install path, end to end
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — the persistent-personal-agent bootstrap contract (interview, identity files, hooks, private repo, security posture, uninstall), plus local harness mode (`gbrain bootstrap harness`) for wiring framework-spawned Claude Code/Codex sessions to a running serve
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — why schemas matter: 7 killer use cases, the structural argument for typed page kinds, the agent-co-curates pattern (v0.40.7.0)
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5-minute walkthrough: fork the bundled pack, add a custom type, backfill existing pages, prove the wiring via `gbrain whoknows`
- [`docs/architecture/`](docs/architecture/) — system design, topologies, retrieval theory
@@ -2055,7 +2169,7 @@ the page PK, soft-delete-filtered, source-safe) and completes in seconds.
- [`AGENTS.md`](AGENTS.md) — entry point for non-Claude agents
- [`CLAUDE.md`](CLAUDE.md) — entry point for Claude Code (deep operating context)
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor guide, test discipline, eval-capture mode
Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that ships as the default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that shipped as the default from v0.36 through v0.46. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
---
@@ -2831,7 +2945,7 @@ gbrain schema add-alias researcher person
Read [`skills/conventions/schema-evolution.md`](../skills/conventions/schema-evolution.md) for the decision tree on when to add types vs aliases vs prefixes. The short version: <20 pages → don't pack-codify; 20-100 → alias on existing type; 100+ → first-class type.
**Lint your pack before shipping.** The 11-rule lint surface (with the optional `--with-db` flag for DB-aware checks) catches dangling references, prefix collisions, and dead-corpus warnings:
**Lint your pack before shipping.** The 14-rule lint surface (with the optional `--with-db` flag for DB-aware checks, including the stored-type alias/undeclared rules) catches dangling references, prefix collisions, and dead-corpus warnings:
```bash
gbrain schema lint --with-db
@@ -3185,6 +3299,49 @@ it nightly and Phase 4 below (plus most of Phase 2's hygiene checks) is
covered. The pseudocode that follows is the harness-side variant for agents
that also do LLM-driven entity sweeps and memory consolidation on top.
### Synthesis cost control: the triage cascade
The synthesize phase is a two-stage cascade: a cheap scored triage
(utility-tier model, one call per new transcript) gates the expensive
per-transcript synthesis subagents. The dials:
- `dream.triage.threshold` (default 0.5) — the gate. Scores are cached, so
retuning it re-gates instantly with **zero** new LLM calls. Raise it if too
much routine content synthesizes; lower it if real signal is being skipped.
- `models.dream.triage` — the triage model (default: utility tier / Haiku).
- [docs/UPGRADING_DOWNSTREAM_AGENTS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/UPGRADING_DOWNSTREAM_AGENTS.md): Patches for downstream agent skill forks. One section per release.
"description":"Canonical (machine-readable) brain filing rules. The .md companion is the human explainer; this JSON is what `gbrain check-resolvable` audits against. Keep both in sync.",
"description":"Generative ideas the user might build, write, or expand later. Stub-shaped pages that mature over time. voice-note-ingest, archive-crawler, and similar capture-flavored skills file here when content is something to potentially act on."
"description":"Web-research output: what is NEW vs already-known about a topic, citation-checked claims, freshness deltas. perplexity-research and academic-verify file here."
},
{
"kind":"original",
"directory":"originals/",
"examples":["the user's own theses","frameworks the user generated","novel observations the user expressed"],
"description":"Pages where the user is the primary author of the idea — original thinking, not summarizations of someone else's work. voice-note-ingest, archive-crawler, signal-detector route content here when the user is the originator."
"description":"Voice-note transcript holders, especially when the content is a random thought that doesn't cleanly fit originals/, concepts/, or another subject directory. voice-note-ingest is the primary writer."
},
{
"kind":"openclaw",
"directory":"openclaw/",
"examples":["agent-state notes"],
"description":"Notes about the host OpenClaw agent itself, not the underlying entities."
},
{
"kind":"synthesis-output",
"directory":"media/books/",
"examples":["personalized book mirrors","two-column chapter analyses"],
"description":"Sanctioned exception to 'file by primary subject' for sui generis synthesized output that is one-of-one to a single book and a specific reader. Format-prefixed under media/<format>/ is allowed for synthesis output only, never for raw ingest. See _brain-filing-rules.md."
},
{
"kind":"synthesis-output",
"directory":"media/articles/",
"examples":["personalized article reads","long-form content tailored to reader"],
"description":"Same sanctioned exception as media/books/. One-of-one synthesis output of an article personalized for the reader. Distinct from raw article ingest, which goes to the article's primary-subject directory."
"description":"Date-keyed pages for events, calendar entries, or daily notes. Calendar imports land at daily/calendar/YYYY-MM-DD.md with attendees cross-linked to people/. Use when the primary subject is the date itself, not a person or topic."
"description":"Format-prefixed parent for media-by-source-format ingest. Subdirectories like media/x/{handle}/ hold X/Twitter archives, media/audio/ holds podcast/voice captures. The format-prefix lives only when the content is sui generis to the source format AND lacks a clean primary-subject directory. Prefer subject-by-subject filing; fall through to media/ only when the source format IS the unifying frame."
"description":"Imported chat exports (ChatGPT, Claude, etc.) where the conversation itself is the artifact. Cross-link concepts and people from the conversation; the conversation page is the source-of-truth for the dialog. Distinct from voice-notes/ (which holds raw voice capture)."
}
],
"sources_dir":{
"directory":"sources/",
"purpose":"ONLY for raw data: bulk imports, API dumps, periodic captures. A page with a clear primary subject (person, company, concept) does NOT belong here.",
"not_for":["articles about a person","analyses of a company","reusable frameworks"]
},
"notes":[
"The PRIMARY SUBJECT of the content determines the directory, not the format or source skill.",
"When in doubt: what would you search for to find this page again?",
"Cross-link from related directories via back-links — do not duplicate content."
],
"dream_synthesize_paths":{
"description":"Single source of truth for the v0.23 dream-cycle synthesize/patterns trusted-workspace allow-list. The cycle's synthesize phase reads this list and threads it as `allowed_slug_prefixes` to every subagent it dispatches; put_page enforces it server-side. Editing this list is the ONLY way to add a new directory the synthesis subagent may write to.",
The `synthesize` and `patterns` phases of `gbrain dream` write to a
**fixed allow-list** of paths sourced from `_brain-filing-rules.json`'s
`dream_synthesize_paths.globs` array. Editing that JSON is the ONLY way
to add a new directory the synthesis subagent may write to:
| Output type | Slug pattern | What goes here |
|-------------|--------------|----------------|
| Reflection | `wiki/personal/reflections/YYYY-MM-DD-<topic>-<hash[:6]>` | Self-knowledge, emotional processing, pattern recognition. Verbatim quotes from the user, with analysis. |
| Original idea | `wiki/originals/ideas/YYYY-MM-DD-<idea>-<hash[:6]>` | New frames, theses, mental models, "conceptive ideologist" outputs. Capture the user's exact phrasing — that's the artifact. |
| People enrichment | `wiki/people/<existing-slug>` | Timeline entries appended to existing people pages from session mentions. Stub pages for new substantive people. |
| Pattern | `wiki/personal/patterns/<theme>` | Cross-session theme detected across ≥3 reflections. Highest-leverage output: a pattern can span 25 years if reflections reference dated content. |
| Cycle summary | `dream-cycle-summaries/YYYY-MM-DD` | Index of every page produced by one dream cycle. Auto-written deterministically by the orchestrator. |
**Iron Law for synthesize output:**
1. Quote the user verbatim. Do not paraphrase memorable phrasings.
2. Cross-reference compulsively: every new page MUST link to existing brain content.
3. Slug discipline: lowercase alphanumeric and hyphens only, slash-separated. NO underscores, NO file extensions.
4. Edited transcripts produce NEW slugs (content-hash suffix changes) — never silently overwrite a prior reflection.
## Takes attribution (v0.32+)
When writing a `<!--- gbrain:takes:begin -->` fence, the **holder** column says
WHO BELIEVES the claim, not who it's ABOUT. Cross-modal eval over 100K
production takes scored attribution at 6.5/10 — holder/subject confusion was
the #1 error. These six rules are the contract. Long form with worked
examples lives in `docs/takes-vs-facts.md`.
1. **Holder ≠ subject.** The test: did this person SAY or CLEARLY IMPLY this?
- YES → `holder = people/<slug>`
- NO, it's your analysis OF them → `holder = brain`
- Example: "Garry has a hero/rescuer pattern" → `holder=brain` (analysis ABOUT Garry, not stated BY Garry)
2. **Atomic claims.** Split compound rows into separate rows. One claim per row.
3. **Amplification ≠ endorsement.** A retweet-only signal caps at `weight 0.55`.
The user shared something; they didn't necessarily endorse every clause.
> Cross-cutting rule shared by skills the claw-test harness exercises (setup,
> brain-ops, query, ingest, smoke-test, migrations). Reference via
> `> **Convention:** see [skills/_friction-protocol.md](_friction-protocol.md).`
When you encounter friction running gbrain — anything confusing, missing, surprising, or wrong — log it via `gbrain friction log` so maintainers can see it without you writing a bug report. Friction reports drive the claw-test feedback loop (the harness collects, renders, and re-runs).
## When to log
Log friction when any of these happens:
- A command failed with a non-actionable error message
- A doc said one thing and the tool did another
- You couldn't find the next step
- A setup command needed a manual workaround
- A flag exists but isn't documented in `--help`
- A success condition was unclear (you couldn't tell if the command worked)
Log delight (positive signal) when:
- Something worked on the first try and the docs were exactly right
- An error message handed you the fix
- A flag you guessed at turned out to exist with the obvious name
## How to log
```
gbrain friction log \
--severity {confused|error|blocker|nit} \
--phase <which-phase-or-command> \
--message "<one-line-what-happened>" \
[--hint "<one-line-what-could-be-better>"]
```
For delight, add `--kind delight` and pick any severity.
The CLI auto-fills `ts`, `cwd`, `gbrain_version`, and resolves `run_id` from `$GBRAIN_FRICTION_RUN_ID` (set by the harness) or falls back to `standalone.jsonl`. So you can call this anywhere — inside a harness run, manually during normal use, or from a scripted test.
## Severity guide
| severity | meaning |
|------------|---------|
| `blocker` | Couldn't proceed at all. Hard stop. |
| `nit` | Polish opportunity. Cosmetic or low-impact. |
Be specific: "doctor says `schema_version=0` and points at apply-migrations, but apply-migrations exits 0 with no output" beats "doctor was confusing."
description: Verify a research claim or academic citation by tracing it through publication → methodology → raw data → independent replication. Routes through perplexity-research for the actual web lookup, then formats results as a citation-checked brain page. Use when a book/article/conversation cites a study and you want to confirm the claim is real, replicated, and accurately characterized.
triggers:
- "verify this academic claim"
- "check this study"
- "academic verify"
- "validate citation"
- "is this study real"
- "Retraction Watch"
mutating: true
writes_pages: true
writes_to:
- concepts/
---
# academic-verify — Trace Claims to Source Data
> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
> citation rules; every verdict cites the source data, not just the
> author's claim about the source data.
>
> **Convention:** see [conventions/brain-first.md](../conventions/brain-first.md)
> for the lookup chain. This skill enforces brain-first by checking
> existing brain pages before issuing a fresh web search.
## What this is
A claim-verification flow for academic / research statements. When a
book, article, or speaker cites a study or quotes a number, this skill
traces the claim through:
```
claim → publication → methodology section → raw data source → independent verification
```
At each step, it answers:
- **Where does this number come from?** (Self-generated? Survey? Government data?)
- **What's the baseline?** (Reduction from what? Over what time period?)
- **Is the raw data available?** (Public? Proprietary? "Available on request"?)
- **Has anyone independently verified it?** (Replication study? Government audit?)
- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:` (when applicable).
- Conventions referenced (`quality.md`, `brain-first.md`, `_brain-filing-rules.md`) are followed.
- Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this section exists for the conformance test.
## Output Format
The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
description: Universal archivist for personal file archives (Dropbox/B2/Gmail-takeout/local-mount/hard-drive-dump). Filters for high-value content (the user's own writing, ideas, relationships) and surfaces it interactively. REFUSES TO RUN without an explicit gbrain.yml `archive-crawler.scan_paths:` allow-list.
triggers:
- "crawl my archive"
- "find gold in my archive"
- "archive crawler"
- "scan my dropbox for"
- "mine my old files for"
mutating: true
writes_pages: true
writes_to:
- originals/
- personal/
- ideas/
---
# archive-crawler — The Universal Archivist
> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
> citation rules, exact-phrasing requirements when capturing the user's
> reactions, and back-link enforcement.
>
> **Convention:** see [_brain-filing-rules.md](../_brain-filing-rules.md) —
> this skill is **schema-generic**: it reads the user's filing rules from
> the rules JSON instead of hardcoding any specific era / archive layout.
## Safety gate (REQUIRED, no exceptions)
archive-crawler refuses to run unless `archive-crawler.scan_paths:` is
explicitly set in `gbrain.yml`. This is a deliberate safety fence against
the agent over-scoping a scan and ingesting sensitive content (tax PDFs,
medical records, credentials).
```yaml
# gbrain.yml — the allow-list is mandatory
archive-crawler:
scan_paths:
- ~/Documents/writing/
- ~/Dropbox/Archive/
- /mnt/backup/old-letters/
# Optional deny-list inside the allow-list:
# deny_paths:
# - ~/Documents/finances/
# - ~/Documents/medical/
```
If `scan_paths` is empty or missing, the skill exits with:
```
archive-crawler: refusing to run. No `archive-crawler.scan_paths:` allow-list
in gbrain.yml. Add explicit paths the agent is permitted to scan, then re-run.
This is a safety fence — the agent will not infer what's safe to read.
```
This contract is enforced by `src/core/storage-config.ts` (mirrors the
`db_tracked` / `db_only` allow-list pattern from v0.22.11 storage tiering).
## What this is
Generic engine for exploring any tree of personal content within an
explicit allow-list. Works on local mounts, Dropbox API targets,
Backblaze B2, Gmail takeouts (`.mbox`), and similar archives. Filters
for "gold" (the user's own writing, ideas, relationships) and surfaces
it interactively for review. Skips noise (system files, configs, binary
blobs).
## Concepts
### Source
A source is any tree of files to explore. Sources have:
- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:` (when applicable).
- Conventions referenced (`quality.md`, `brain-first.md`, `_brain-filing-rules.md`) are followed.
- Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this section exists for the conformance test.
## Output Format
The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
description: Transform raw article text dumps in the brain into structured pages with executive summary, verbatim quotes, key insights, why-it-matters, and cross-references. Replaces walls-of-text with quotable, actionable brain pages.
triggers:
- "enrich this article"
- "enrich the article"
- "enriching the article"
- "enrich brain pages"
- "batch enrich"
- "enrich pass"
- "make brain pages useful"
mutating: true
writes_pages: true
writes_to:
- media/articles/
---
# article-enrichment — From Raw Dumps to Useful Brain Pages
> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
> citation rules, verbatim-quote requirements, and back-link enforcement.
>
> **Convention:** see [_brain-filing-rules.md](../_brain-filing-rules.md) for
> filing rules. Article pages live under `media/articles/` for raw ingest;
> personalized one-of-one synthesis output uses the sanctioned
- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:` (when applicable).
- Conventions referenced (`quality.md`, `brain-first.md`, `_brain-filing-rules.md`) are followed.
- Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this section exists for the conformance test.
## Output Format
The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
{"intent":"This article page is a wall of raw text — please enrich this article with quotes and insights","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
{"intent":"Run a batch enrich pass on the unstructured articles in my brain","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
{"intent":"Make brain pages useful by enriching the article dumps","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
{"intent":"Please enrich brain pages that have raw content but no executive summary","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
{"intent":"Enrich this article so it has verbatim quotes, key insights, and a why-it-matters section","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
description: Take any book (EPUB/PDF), produce a personalized chapter-by-chapter analysis. Each chapter is preserved in detail (The Chapter) and mirrored back to the reader's actual life (The Mirror) using brain context. The mirror observes and resonates — a friend pointing out parallels, NOT a consultant rearranging the reader's life, NOT a therapist assigning homework. The reader decides what to do about it. Layout is a top-aligned HTML table or stacked sections, never a bare markdown pipe table (pipe tables center-misalign uneven columns). Output is a single brain page at media/books/<slug>-personalized.md plus an optional PDF via brain-pdf.
triggers:
- "personalized version of this book"
- "mirror this book"
- "two-column book analysis"
- "apply this book to my life"
- "how does this book apply to me"
mutating: true
writes_pages: true
writes_to:
- media/books/
upstream: book-mirror@fc834ee
---
# book-mirror — Personalized Chapter-by-Chapter Book Analysis
> **Convention:** see [_brain-filing-rules.md](../_brain-filing-rules.md) for the
> sanctioned `media/<format>/<slug>` exception this skill files under.
>
> **Convention:** see [conventions/quality.md](../conventions/quality.md) for
> citation rules, back-link enforcement, and output quality bars.
>
> **Convention:** see [conventions/brain-first.md](../conventions/brain-first.md)
> for the lookup chain (brain → search → external) the context-gathering
> phase follows.
## What this does
Given a book (EPUB or PDF), produce a brain page where every chapter is
summarized in detail on one side ("The Chapter") and mirrored back to the
reader's actual life on the other ("The Mirror"), using their own words,
situations, people, and patterns from the brain. Output is a brain page at
`media/books/<slug>-personalized.md`.
This is NOT a generic book summary. The mirror is the value: it makes the
book read like a smart friend who happens to know the reader's life deeply
is pointing things out in the margins. The mirror's job is recognition —
"that's exactly me" — and then getting out of the way. If the user wants a
flat summary instead, route them to a different skill.
## Trust contract (read this before running)
book-mirror runs as a CLI command (`gbrain book-mirror`), NOT as a pure
markdown skill that the agent dispatches via tools. The CLI is the trusted
runtime; the skill is the orchestration prose around it.
What this means for the agent:
- The CLI submits N read-only subagent jobs (one per chapter). Each subagent
has `allowed_tools: ['get_page', 'search']` only. They CANNOT call
put_page or any mutating op. They produce markdown analysis via their
final message.
- The CLI reads each child's `job.result`, assembles the final
page, and writes it via a single operator-trust `put_page`.
- This means untrusted EPUB/PDF content cannot prompt-inject any
`people/*` page. The trust narrowing happens at the tool allowlist,
not at the slug-prefix layer.
## The pipeline
```
1. ACQUIRE → User has the EPUB/PDF locally (manual; book-acquisition is
not currently shipped — see "Acquiring the book" below).
2. EXTRACT → Pull chapter text from EPUB/PDF into one .txt per chapter.
3. CONTEXT → Gather everything the brain knows about the reader.
4. ANALYZE → `gbrain book-mirror` fans out N read-only subagents.
5. ASSEMBLE → CLI reads each child result and writes one put_page.
6. PDF → Optional: render via skills/brain-pdf for delivery.
```
## 1. Acquiring the book
book-acquisition (legal-grey-area downloader) was deliberately not shipped
in this skill wave. The user drops the EPUB/PDF manually. Common paths the
user might use:
```bash
# User-supplied path
ls path/to/book.epub
ls path/to/book.pdf
# Or already in the brain repo (recommended for tracking)
ls $BRAIN_DIR/media/books/
```
Resolve `$BRAIN_DIR` from the gbrain config (`gbrain config get sync.repo_path`)
or accept it from the user.
## 2. Text extraction
Goal: one `.txt` file per chapter under a temp directory. The agent has
shell + python access; the CLI is downstream of this and takes the
- [ ] Optional: PDF rendered via brain-pdf and delivered.
## Related skills
- `skills/brain-pdf/SKILL.md` — render the personalized page to PDF.
- `skills/strategic-reading/SKILL.md` — read a book through a specific
problem-lens instead of personalizing to the whole reader.
- `skills/article-enrichment/SKILL.md` — same shape applied to articles
rather than books.
- `skills/cross-modal-review/SKILL.md` — the manual second-model quality
gate; `gbrain eval cross-modal` is the scripted sibling surface.
## Contract
This skill guarantees:
- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:` (when applicable).
- Conventions referenced (`quality.md`, `brain-first.md`, `_brain-filing-rules.md`) are followed.
- Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this section exists for the conformance test.
## Output Format
The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
## Anti-Patterns
The full anti-pattern list is in the body sections above; this header exists for the conformance test if the body uses a different casing.
A card hit means the page exists — STOP, link, don't clone. On a miss (or
for concept-shaped nouns), fall through to `gbrain query "<name>" --limit 3`.
If the brain also keeps an explicit index of named initiatives (e.g. a page
under `concepts/`), read it before concluding anything is new.
2. **Expand through aliases before searching.** Named pages should carry an
`aliases:` frontmatter list (generic label + chosen name + any nickname +
signature phrase). Search EACH alias and the generic label, not just the
phrase the user happened to say.
3. **A vector score is a floor for prose, NEVER a gate for named things.**
If there is ANY plausible named match, open and read the candidate page
(`gbrain get <slug>`) before concluding it doesn't exist. A named page can
be the right answer at a score that would be a clear miss for prose.
4. **When a NEW named thing appears, bake its aliases in the same write.**
Create the page with the full `aliases:` list so every future synonym
resolves through `gbrain entity`. One frontmatter list covers all future
phrasings — O(1), not a per-instance reminder.
### Why a gate and not a memory note
A memory reminder ("query the real name, not the generic phrase") is a
per-instance sticky note: it only works if it happens to be in hot context
that turn, doesn't generalize to the next named entity, and rots. This skill
loads when an ingest-shaped task routes here. Process rules belong in the
triggered gate, not in hot memory.
## Dedup Gate (runs SECOND)
Before writing ANY new page (for named things, the resolution gate above runs
first and takes precedence):
1. **Extract the core claim** — 1-2 sentences capturing what's novel about the
new content.
2. **Search for it:**
```bash
gbrain search "<core claim>" --limit 5
```
3. **OPEN AND READ the top hit** (`gbrain get <slug>`). Never band on the
score alone. Donor systems publish cosine cutoffs for this step — do NOT
port them: `gbrain search` returns fused hybrid rank scores, not cosine
similarity, and no numeric threshold maps across. The band comes from
reading, not from the number.
4. **Assign a band:**
| Band | Meaning | Action |
|---|---|---|
| **clear-dup** | The top hit already states the same insight about the same subject | STOP. Link to the existing page (`gbrain link` / `gbrain timeline-add`) instead of writing. |
| **plausible-dup** | Same territory; possibly a new angle | Read both fully. Same insight → link, don't write. Genuinely new angle → write WITH a cross-link to the existing page. |
| **clear** | Nothing in the top results covers the claim | Write normally through the delegated enrichment skills. |
### Decision tree
```
New content to write
├─ Named thing? → Named-Entity Resolution Gate first
│ (entity card → alias-expanded search → READ the candidate)
├─ Extract core claim (1-2 sentences)
├─ gbrain search "<core claim>" --limit 5
└─ OPEN AND READ the top hit (gbrain get <slug>)
├─ clear-dup → STOP. Link to existing. Report "duplicate".
├─ plausible-dup → Read both. Same insight?
│ ├─ yes → STOP. Link to existing. Report "duplicate".
│ └─ no → Write with cross-link. Report "new angle".
└─ clear → Write via enrichment skills. Report "unique".
```
### When to skip dedup
- **Operational/state files** — time-series records, not knowledge.
- **Meeting transcripts** — each meeting is unique by definition (entities
INSIDE it still go through the named-entity gate via the delegated skills).
- **Timeline entries on existing pages** — back-links are additive, not
duplicative.
- **Media files** — dedup by filename/hash, not semantic similarity.
## Verification
After the batch, verify the gate's output holds:
```bash
gbrain check-backlinks check # mentioned entities link back (fix with: check-backlinks fix)
gbrain backlinks <new-slug> # each new page has inbound links
gbrain search "<core claim>" --limit 3 # the insight has exactly ONE home
```
If `check-backlinks check` reports gaps on pages the gate just admitted, the
enrichment delegation was skipped — route back through
[enrich](../enrich/SKILL.md) before declaring the ingest done.
## Contract
This skill guarantees:
- No new page enters the brain through this skill's flows without the
named-entity resolution check and the dedup check running first.
- Every "duplicate" verdict names the matched slug and produces a link or
timeline entry instead of a clone.
- New named-entity pages carry an `aliases:` frontmatter list in the same
write that creates them.
- Dedup bands are assigned by READING the top hit, never by score alone; no
numeric similarity thresholds are used against gbrain's fused scores.
- Enrichment is delegated to shipped skills (ingest, enrich, signal-detector,
concept-synthesis) — never restated or reimplemented inline.
- Batches end with a `gbrain check-backlinks check` verification pass.
- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:`.
- Privacy contract preserved: no real names, no fork-specific filesystem path
literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this
section exists for the conformance test.
## Output Format
One decision line per item checked, then the verification result:
{"intent":"run concept synthesis to dedupe the stubs that piled up in the brain over the last few months","expected_skill":"concept-synthesis","ambiguous_with":["brain-ingest-gate"]}
> states the one-line principle ("every brain page reference in output should
> use a clickable link format appropriate to the deployment"). This skill is
> that line's full expansion.
This is a reporting convention the harness routes brain-page delivery
messages through — a standing rule to apply when composing such messages,
not a mechanical guarantee enforced by tooling.
## The rule (same message)
If you commit and push a brain page, the link goes in the SAME message that
reports the work. Every time. No "let me commit and push" without the link
landing in that same reply once the push succeeds. The user should never
have to ask "give me the link" or "where is the page."
This applies to:
- Any message reporting a created or edited brain page
- Bulk reports ("5 pages created" — every page gets its own link line)
- Referencing a brain page in normal conversation
- Relaying subagent results that mention brain paths (rewrite first — see below)
The most common link bug is committing a brain page and forcing the user to
go find it. The link is a deliverable, not a follow-up.
## Scope split: in-message vs in-page (the inversion)
The two output surfaces take OPPOSITE link forms:
| Surface | Link form | Why |
|---|---|---|
| Chat message to the user | Absolute, verified URL (or the fallback chain below) | Repo-relative paths aren't clickable in chat surfaces |
| Inside a brain page body | RELATIVE markdown link: `[Alice Example](../people/alice-example.md)` | gbrain's link extraction builds the links/backlinks graph — which powers relational retrieval — from filesystem-relative links. An absolute URL between two brain pages is invisible to that graph |
**Never write absolute URLs for page-to-page references inside a brain
page.** Absolute URLs in a page body are for genuinely external targets
only. Frontmatter `related:` / `people:` keys stay bare relative paths
(machine-parsed, not rendered prose). After a link-heavy write,
`gbrain check-backlinks check` audits the graph and `gbrain sync --no-pull`
makes the pages searchable.
## Deriving the path mechanically
The repo-relative path a hosted git remote serves is relative to the **git
repo root** (`git rev-parse --show-toplevel`), NOT your current working
directory. When the repo root sits above your working directory, hand-
stripping your cwd prefix silently drops the intermediate directory segment
and every link you build 404s. Never hand-strip a prefix. Derive:
```bash
# From anywhere inside the repo, prints the EXACT path the remote serves:
cd "$(dirname <file>)" && git ls-files --full-name "$(basename <file>)"
> Fall back to the classic ops when the verbs aren't on the surface. Contract:
> `docs/protocol/MEMORY_VERBS_v1.md`.
## Contract
This skill guarantees:
- Brain is checked BEFORE any external API call (brain-first lookup)
- Every inbound signal triggers the READ → ENRICH → WRITE loop
- Every outbound response checks brain for relevant context
- Source attribution on every fact written (inline `[Source: ...]` citations)
- User's direct statements are highest-authority data
- Back-links maintained on every brain write (Iron Law)
## Iron Law: Back-Linking (MANDATORY)
Every mention of a person or company with a brain page MUST create a back-link
FROM that entity's page TO the page mentioning them. An unlinked mention is a
broken brain. See `skills/conventions/quality.md` for format.
## Phases
### Phase 1: Brain-First Lookup (MANDATORY)
Before using ANY external API to research a person, company, or topic:
1. `gbrain entity "<name>"` (v0.43+) — ONE known person/company/project → full card (description, aliases, open threads, recent events, edges, backlink/fact counts). Zero LLM calls, sub-100ms. This one call replaces steps 2–6 for known-entity lookups; near-misses return suggestions.
2. `gbrain search "name"` — exact-token lookup for existing pages (cheap hybrid, no expansion)
3. `gbrain query "natural question about name"` — concept/landscape questions go here FIRST (expansion recovers synonym phrasings; a nonzero `search` count is not proof of completeness)
4. `gbrain get <slug>` — if you know the slug, read the full page
5. Check backlinks: who references this entity?
6. Check timeline: recent events involving this entity
The brain almost always has something. External APIs fill gaps, not start from scratch.
**⚠️ NEVER scope/count a corpus with shallow `ls` — query gbrain or `find`.** Federated sources often carry MULTIPLE coexisting directory conventions — a flat legacy layer AND a date-nested `meetings/YYYY/MM/` layer. A non-recursive `ls dir/*.md` sees only one and undercounts massively. Real example: a shallow `ls` of one source's `meetings/` counted 132 files, almost all the user's, and concluded that WAS the corpus — missing thousands of transcripts nested under `meetings/YYYY/MM/`. To count/scope a brain corpus:
- **Best:**`gbrain sources list` (shows per-source indexed page counts) + `gbrain query`. gbrain indexes ALL federated sources correctly; trust its index, not the filesystem.
- **If you must hit the FS:**`find <dir> -name '*.md' | wc -l`, never `ls *.md`. Then map the layout: `find <dir> -name '*.md' | sed -E 's#(.*/)[^/]+$#\1#' | sort | uniq -c`.
- The bug is never "gbrain can't see the source" — it's almost always a shallow FS glob. Verify against `gbrain sources list` before believing a low count.
### Phase 1.5: Analytical Queries (gbrain think)
For questions that need synthesis, temporal grounding, or analytical answers —
not just "find the page" but "answer the question":
1. Use `gbrain think "<question>"` — multi-hop synthesis across pages + takes +
the graph. Temporal questions route through trajectory analysis; everything
else gets an LLM-synthesized, cited answer with conflict + gap analysis.
Returns a grounded answer, not just a list of matching pages.
2. Best for: "when did acme-example last raise", "what was the ARR in March",
"what changed since Q1", "who is alice-example's cofounder and what are they
working on", "summarize our relationship with acme-example".
3. Falls back gracefully to standard retrieval when no timeline facts match.
4. Cost: LLM calls per question — this is the expensive path. Use `query` for
simple page lookups where you just need the slug or a quick context check.
### Phase 2: On Every Inbound Signal (READ → ENRICH → WRITE)
Every message, meeting, email, or conversation that references a person or company:
- The `put_page` MCP response includes `auto_links: { created, removed, errors }`
so the agent can verify outcomes.
- To disable: `gbrain config set auto_link false`. Default is on.
- Timeline entries with specific dates still need explicit `gbrain timeline-add`
(or batch via `gbrain extract timeline --source db`).
### Phase 3: On Every Outbound Response (READ → PULL → RESPOND)
Before answering any question about a person, company, or topic:
1. **Check the brain** — read relevant pages
2. **Pull context** — use compiled truth + recent timeline
3. **Respond with context** — the brain makes every answer better
Don't answer from general knowledge when a brain page exists.
### Phase 4: Ambient Enrichment
This is not a special mode. This is the default. Everything the user says is an
ingest event.
- Person mentioned → check brain, create/enrich if needed (spawn background)
- Company mentioned → same
- Link shared → ingest it (delegate to idea-ingest)
- Data shared → delegate to appropriate skill
**Rules:**
- Never interrupt the conversation to do enrichment
- Spawn sub-agents for anything that would slow down the response
- Never announce "I'm enriching the brain" — just do it silently
## Output Format
No separate output. Brain-ops is an always-on behavior layer, not a report generator.
The output is updated brain pages and enriched responses.
## Cross-source citation format (v0.18.0+)
When a brain has multiple sources (wiki, gstack, yc-media, etc.), every
citation MUST include the source id: `[source-id:slug]`. Example:
> You told me about the retry budget approach — see
> [wiki:topics/resilience] and [gstack:plans/retry-policy] for where
> this came from.
Rules:
- The key is `sources.id` (immutable), never `sources.name` (mutable display).
- Single-source brains still write `[default:slug]` OR may omit the prefix
for backward compat.
- Every page payload returned by `search`, `query`, `get_page`, `list_pages`
carries `source_id` — always use it when citing, never guess.
If a search result has `source_id: "gstack"` and `slug: "plans/foo"`,
the citation is `[gstack:plans/foo]`. That's the whole rule.
## Anti-Patterns
- Answering questions about people/companies without checking the brain first
- Using external APIs before checking the brain
- Writing facts without inline `[Source: ...]` citations
- Blocking the response to do enrichment
- Overwriting user's direct statements with lower-authority sources
- Creating brain pages for non-notable entities
- Creating duplicate pages for the same entity — always check first before creating: `gbrain entity "<name>"` (catches aliases + near-misses), then `query` with name variants
- `get_backlinks` — check who references an entity
- `sync_brain` — sync changes to the index
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
