Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
56.0 KB
Raw Blame

Agent bootstrap cluster (the paste-in desktop-agent install)

Subsystem index.

Normative docs: docs/designs/AGENT_BOOTSTRAP_DESIGN.md (scope) + docs/designs/AGENT_BOOTSTRAP_PLAN.md (implementation, review-finding IDs inlined). User-facing contract: docs/guides/bootstrap.md. Runbook the paste block fetches: BOOTSTRAP_FOR_AGENTS.md (root; carries a version stamp CI pins to VERSION).

  • src/commands/bootstrap.ts — the gbrain bootstrap {status,interview,render,repo,hooks,verify,uninstall,attach,cloud-setup-script} dispatcher (plus the machine-level harness subcommand — see the core/bootstrap/harness.ts entry below). Engine-free everywhere except verify (which opens/closes its own engine — safe because verify runs with no live serve, before host registration). cloud-setup-script is a pure printer (prints templates/bootstrap/cloud-setup-script.sh for the cloud environment's setup step) and is dispatched entirely BEFORE workspace resolution, so it works from any cwd, including $HOME. Every other subcommand resolves --workspace (default: cwd) through resolveWorkspace, which refuses with BootstrapError('HOME_WORKSPACE') when the resolved path (realpath-compared, so a symlinked $HOME or cwd still matches) IS process.env.HOME (falling back to os.homedir() only when HOME is unset) — an unqualified run from a freshly-SSH'd shell must not silently stage a home-directory-scale git add -A over ~/.ssh/ and friends; the refusal is still appended to <home>/bootstrap/install.jsonl (keyed by the rejected candidate path) before returning. status, uninstall, and harness are exempt from this guard (HOME_WORKSPACE_GUARD_EXEMPT): status only reads and prints a report, uninstall removes exactly receipt.created_paths (each containment-checked) — never a git add/commit/push, never a workspace-wide scan — and harness operates only on home and never even receives a ws argument (runHarness, machine-level wiring), so the value resolveWorkspace returns for it is used only for LogCtx.ws bookkeeping. Exempting status/uninstall keeps the recovery path reachable for the guard's own victims: someone who bootstrapped into $HOME needs status to see what's there and uninstall to remove it, both run with --workspace pointing AT $HOME; the refusal message for the still-guarded subcommands names that recovery path. Known gap: a process already launched with HOME pointed away from the real account home is not caught (Bun's os.homedir() mirrors process-start HOME rather than doing an independent uid lookup, so it collapses to the same wrong value). Mutating subcommands run under the workspace bootstrap lock; render is gated on interview complete && confirmed and hard-refuses when the workspace origin is a PUBLIC remote (identity files must never land in a public repo — the same template-door gate status enforces; unverifiable visibility warns and proceeds, treating the origin as public); the provider key routes to the 0600 config sink and never touches interview state; every MUTATING subcommand appends a line to <home>/bootstrap/install.jsonl (the read-only status and cloud-setup-script do not log). hooks on Claude Code writes the committed carrier in a cloud sandbox (writeCommittedClaudeHooks) and the gitignored local file otherwise; uninstall tears down the durability wiring and removes this workspace's per-root push/debounce state, and its opencode teardown sweeps BOTH merged global filenames (under the opencode config-dir bootstrap lock) plus the project opencode.json, expectation-keyed on this workspace's source id (skipOtherSource) — a gbrain entry from a different workspace is skipped with a note, never silently deleted. Consent answers resolve FAIL-CLOSED: consentAnswer treats a hand-edited/unusable interview value (non-string, empty) as declined — loudly, with a re-record note — never falling through to a permissive bank default; hooks on Codex prints a corrective note when a persisted project MCP_SCOPE answer is found (raw state read, not the resolver — codex mcp add has no scope flag, registrations are always user-global) with safe clear instructions. GBRAIN_BOOTSTRAP_ABORT_AFTER is the deterministic kill-mid-phase test seam.
  • src/core/gbrain-bin.ts — resolveGbrainBin(): the absolute gbrain binary for harness registrations and hook commands (Bun.which('gbrain') when absolute, else this process's executable when it is the compiled binary, else null). A bare gbrain is never registered because GUI hosts inherit no PATH. Used by bootstrap and readiness's harness_wiring fix.
  • src/core/bootstrap/format.ts — agent.json manifest (format_version 1, provisional; initialized sentinel distinguishes a template clone from a bootstrapped workspace) + the machine-local install receipt (<home>/bootstrap/receipt.json) that proves THIS machine ran bootstrap; uninstall is keyed to the receipt, never the repo manifest. Atomic writes; readManifest never throws (typed states incl. conflict markers).
  • src/core/bootstrap/assets.ts — every template + the question bank embedded via Bun with { type: 'file' } imports (the chunkers/code.ts pattern) so the compiled binary renders with no repo checkout; DERIVED_TOKENS (GITHUB_REPO_URL, CORPUS_RETENTION_DAYS) is the non-bank half of the template token set the CI bijection guard checks.
  • templates/bootstrap/ — the ten {{TOKEN}} identity templates (AGENTS/CLAUDE/SOUL/USER/MEMORY/HEARTBEAT/ACCESS_POLICY/GITHUB/memory-README/gitignore), questions.json (12 asked / 6 required; consent keys; persist:false sink keys), and template-repo/ — the VENDORED deterministic render the release job diffs against before publishing the public template repo. Generic placeholder content only (privacy iron rule; CI-asserted).
  • src/core/bootstrap/interview.ts — interview state at <ws>/state/interview.json (committed; multi-device re-render source). Read-back confirm hash: --confirm must present the hash of the exact answer set shown to the human, and ANY later answer change clears the confirmation — the single-batch self-confirm attack is structurally impossible. Set-time enforcement: length caps, reject-lists, allowed-lists, control-char strip, {{ escaping. Conflict-markered files return agent-readable errors, not stack traces.
  • src/core/bootstrap/render.ts — token substitution with interview values treated as data (line-leading #/<!--/fence escaping), hard-fail on unresolved tokens, never-clobber + timestamped backups on --force, blank-line collapse, byte floors scaled to answered count. --minimal is the deterministic placeholder mode the template-repo generator uses (byte-identical across runs; leaves required tokens as literal fill-me markers; writes initialized:false). --only never writes agent.json. OpenClaw renders HEARTBEAT.md as SCHEDULES.md (render-host.ts, #7470).
  • src/core/bootstrap/lock.ts — the bootstrap-run mutex (atomic mkdir + pid liveness + age guard + ownership token; steal requires dead pid AND stale age) and the family's shared typed BootstrapError (GH_MISSING/GH_AUTH carry exit 2 = human action needed).
  • src/core/bootstrap/repo.ts / attach.ts / uninstall.ts — private-repo lifecycle. createPrivateRepo: gh gates, slugified name probe, gh repo create --private --source --push, privacy verified via gh api .private (rate-limit/5xx is VERIFY_UNAVAILABLE, distinct from not-private) before any push, idempotency keyed off the remote URL. A pre-existing origin is adopted (disposition 'adopted') when the authed gh user owns it, there's no recorded repo_url, and it is SAFE — empty or already carrying our history (assertAdoptableOrigin; a foreign-content repo is refused ORIGIN_NOT_EMPTY, never a silent no-op); this is the create-repo-first path. Org-owned origins and anything else are refused and pointed at attach. Repo-local git identity is set in both create and adopt paths before commit; repo_url is recorded only after a successful push. attachWorkspace (machine two): requires an initialized manifest, writes this machine's receipt, returns structured wiring steps. uninstallWorkspace: receipt-keyed, refuses under a live serve (read-only lock probe — never opens the engine), removes exactly receipt-recorded paths + marker-keyed host entries, keeps the brain unless --delete-brain AND bootstrap created it; never wholesale-deletes the gbrain home. All gh/git through an injectable ExecRunner seam.
  • src/core/bootstrap/hooks.ts + host-specs.ts — host wiring. host-specs.ts is the ONE module owning host-format assumptions (dated spec targets with verifiedAt + doc references: claude-code hooks/settings shapes incl. the 10,000-char hook-output cap and the five hook events; codex mcp-add argv, the streamable-HTTP url + http_headers = { Authorization = "Bearer <t>" } config shape (loads on codex-cli 0.147.x and 0.149.x; inline bearer_token is rejected at config load by >=0.149), codexConfigPath() honoring CODEX_HOME, claudeUserSettingsPath() honoring CLAUDE_CONFIG_DIR/$HOME explicitly — Bun's homedir() ignores a remapped HOME, which would point sandboxed writers at the operator's real settings; the shared resolution lives in the private claudeConfigBase() (CLAUDE_CONFIG_DIR-else-$HOME-else-homedir(), the directory playing the role of ~/.claude — NOT for claudeUserMcpConfigPath, whose default lives at the HOME level as ~/.claude.json), which also feeds claudeUserSkillsDir()/claudeProjectSkillsDir() (native SKILL.md discovery, the harness-bridge install targets; user scope attested, project scope provisional-from-docs) — and the opencode shapes: opencodeConfigDir/opencodeGlobalConfigPath (XDG-only resolution; the .jsonc name preferred for parity with opencode mcp add; OPENCODE_CONFIG/_CONFIG_DIR/_CONFIG_CONTENT deliberately NOT honored — observed INERT in opencode 1.18.18, honoring them would write registrations into a file opencode never reads), opencodeProjectConfigPath, opencodeGlobalSiblingPath (the OTHER member of the global filename pair — writers reconcile mcp.<name> across it because opencode merges both), and OPENCODE_HAS_HOOKS=false — 'gbrain does not wire opencode's plugin/event system yet', not 'opencode has no hooks'). The settings writers are path+marker parameterized: writeClaudeHooksAt/removeClaudeHooksAt take an explicit settings file and a marker VALUE (workspace installs stamp bootstrap-v1 in .claude/settings.local.json; harness installs stamp bootstrap-harness-v1 in user-scope settings or a --project dir — the two coexist and each removal strips only its own; refuseOnForeignGbrainMarker blocks same-file double-wiring), fail-closed on broken JSON (a settings file that doesn't parse THROWS with the path — a writer must never relocate or overwrite a config it can't read), mode-preserving realpath-resolved atomic writes (dotfile symlinks survive), and fixed-or-timestamped backups. addPermissionsAllowEntry/removePermissionsAllowEntry manage the harness lane's mcp__<name> headless pre-approval with set semantics and NO marker (ownership rides the harness receipt; foreign entries always survive); the add path fails CLOSED when an existing permissions key or permissions.allow carries a shape it doesn't understand (host security policy is never rewritten on a guess), while removal leaves shapes it can't read untouched and reports nothing-to-remove. registerClaudeMcp/registerCodexMcp build argv only (Claude Code takes --scope, project default; Codex has no scope flag — codex mcp add is always user-global; -e/--env GBRAIN_SOURCE so MCP writes land in the workspace source, and the serve argv from stdioServeArgv in src/core/mcp-registration.ts: --surface starter by default so a pre-existing mcp_surface: verbs config row can't narrow the registration, or the surface the caller passes — bootstrap hooks --surface, or an existing entry's form carried over on replacement, null meaning a bare serve). bootstrap hooks never narrows: a matching registration is kept, verifyMcpTargetsWorkspace returns the existing entry's surface (registeredSurface) and the mismatch re-add keeps it, and the opencode writer keeps the existing command's form unless --surface is given. The opencode workspace lane execs NOTHING — registration is the direct opencode-json.ts write with an INVERTED scope default (user-global; opencode spawns project-config servers with no trust prompt, so MCP_SCOPE=project is an explicit opt-in that writes the committed-candidate opencode.json with a PATH-resolved command and prints the sharing warning), verification is config parse-back + a best-effort opencode mcp list --pure probe — the probe spawns via a held Bun.spawn handle from a fresh EMPTY temp-dir cwd (never the invoking cwd: opencode merges a project opencode.json from cwd and spawns its servers with no trust prompt), is SKIPPED entirely for project scope (printed note; parse-back is authoritative) and on plugin-bearing configs (mcp list is a code-execution surface), and on timeout actually kills the child (SIGTERM → SIGKILL, bounded pipe drain, code 124 into the could-not-confirm branch; probeSpawn is the injectable seam). User-scope writes also reconcile the SIBLING global filename first (ours → removed with a note; foreign → refuse naming both files) so a merge-shadow registration can never survive. detectHarness probes OPENCODE/OPENCODE_PID (set in opencode's bash-tool children, observed 1.18.18). ClaudeHookEnv.GBRAIN_SEAT (#4618) renders GBRAIN_SEAT=<label> into local-carrier hook commands (never the committed carrier); writeClaudeHooksAt keeps the seat a prior install of the same marker rendered when the caller passes none, and '' clears it. parseSeatFlags validates --seat <label> / --no-seat for bootstrap hooks and bootstrap harness and returns a note where a seat cannot be rendered (codex, opencode, the cloud committed carrier). Pinned by test/bootstrap-seat.serial.test.ts. Harness-lane hook ownership does not rest on the marker alone: Claude Code can drop unknown keys when it rewrites settings.json, so parseClaudeHookCommand (the inverse of buildClaudeHookCommand: shellQuote-aware word split, env keys limited to the four the builder writes, each at most once, an absolute launcher, nothing after hook <sub>, and a re-render that must equal the input) feeds classifyHarnessHook(entry, event, identity) → marked / command (unmarked, exactly the harness hook for THAT event, launcher/source/seat inside a HarnessHookIdentity, no GBRAIN_HOME) / unowned (harness-looking under a wired event but edited or another install's; never deleted) / null. harnessHookIdentity(receipt, target, current) merges the running install with the receipt's recorded launcher/seat and source binding (seats constrain only when recorded). writeClaudeHooksAt({identity}) replaces owned unmarked entries like marked ones (one entry per event on re-run, seat carried from marked then owned entries) and notes harness_hook_unowned lookalikes; removeClaudeHooksAt(path, marker, {identity, dryRun}) returns unmarked (event + why, never command text) and unowned events; scanHarnessHookCarrier is the read-only per-event census (doctor, --status, the cross-HOME guard with identity 'any'); groupsCarryGbrainHook feeds hook_carrier_overlap. The workspace lane (bootstrap-v1) keys on the marker alone. Pinned by test/bootstrap-harness-hook-ownership.test.ts. hookEntryHash (sha256 over type, command, timeout; the marker excluded, so a dropped marker keeps the hash) backs the opt-in ownedEntryHashes option on both writers: with it a marker match alone never replaces or removes an entry, edited marked entries come back in preserved, and unmarked entries with an owned hash are still ours (gbrain setup); without it every existing caller keeps marker-keyed ownership.
  • src/core/bootstrap/harness-hooks.ts — the receipt-aware glue for harness hook entries without their marker: removeHarnessHooksTarget (one hooks target: owned marked + unmarked entries removed and listed by event; a surviving lookalike prints the harness_hook_unowned notice block with next: tell_user_to_run and throws so the target stays failed and --remove exits 1), previewHarnessRemoval (--remove --dry-run: every target's would-be action, nothing written, receipt untouched), harnessHooksPresent (the cross-HOME --project guard: marked, unmarked or edited-by-shape unowned entries, any install; W4.8) and harnessHookCarrierStatus (--status text line + hook_carriers JSON).
  • src/core/setup/capabilities.ts + src/core/setup/claude-code.ts — gbrain setup's data and Claude Code writer. capabilities.ts is the versioned harness × transport table (SETUP_CAPABILITY_TABLE_VERSION; per row setup, pull, push, read_events, capture_events, docs); push is native-pending or unsupported on every row until an observed injected event proves it. claude-code.ts owns entries by exact hash through the connection receipt .gbrain-connection-claude-code-<name>[-project-<hash>].json beside ~/.claude.json (connection: 'local-stdio', entry_hash/pending_entry_hash, hooks.{owned,pending,edited}, consent, gbrain_home; a receipt with client_id is a hosted one and is never adopted). The MCP entry ({type:'stdio', command, args, env}, user scope mcpServers or project scope projects[<dir>].mcpServers) is written directly; hooks go through writeClaudeHooksAt/removeClaudeHooksAt with marker GBRAIN_SETUP_MARKER_VALUE and ownedEntryHashes. applyClaudeSetup (under the config-dir bootstrap lock) writes the receipt prepared first, then the brain (beforeMcp), the MCP entry, the hooks and installed, each step recording its hash so a resume never duplicates; an unchanged install writes nothing. An owned event whose recorded hash vanished while a marked entry remains is edited: preserved, reported, and skipped by later runs. removeClaudeSetup deletes only hash-matched entries (adopted entries stay), keeps a removed receipt when an edited entry survives, and otherwise deletes the receipt. The codex row (table version 2) is supported with push: 'native-verified' and a push_evidence string (codex-cli 0.162.1, observed UserPromptSubmit injection into fresh native sessions, 3/3, with a --no-hooks control); entryHash is ownedEntryFingerprint from adopted-connections.ts.
  • src/core/setup/codex.ts — gbrain setup codex's writer. Owns three kinds of entry, each by ownedEntryFingerprint (sha256 over canonical JSON of the exact parsed entry) recorded per entry in $CODEX_HOME/.gbrain-connection-codex-<name>.json (setup_receipt_version: 2: the claude-code receipt fields plus hooks_path, gbrain_home_env and trust.{owned,pending,edited} keyed by event as {key, hash}; a client_id receipt is hosted and never adopted): the stdio [mcp_servers.<name>] table (command, args, inline env), one hooks.json group per wanted event (codexSetupHookGroup), and one [hooks.state."<hooks.json>:<event>:<index>:0"] trust table per group. applyCodexSetup (under the CODEX_HOME bootstrap lock) writes in a crash-recoverable order: receipt prepared (the consent record and pending fingerprints) → brain (beforeMcp) → MCP table → hooks.json groups (inert until trusted) → stale owned trust tables removed, wanted ones appended (activation last) → installed; each step records its fingerprints so a resume never duplicates. Compare-and-swap everywhere: a group whose recorded hash vanished while a this-install setup-lane group remains is edited (preserved, reported, never trusted by setup); a trust table at setup's key with a different value is preserved (conflict/edited); an identical pre-existing MCP table is mcp_adopted and kept on removal. removeCodexSetup runs trust → hooks → MCP → receipt and keeps a removed receipt when an edited entry survives. Both keep <file>.bak.<timestamp> of each existing config.toml or hooks.json they changed (also on a failed run) and name it in a note. GBRAIN_SETUP_ABORT_AFTER=receipt|mcp|hooks|trust is the crash seam. Pinned by the codex blocks of test/setup.test.ts.
  • src/core/setup/local-receipts.ts — read-only view of this install's live local-stdio setup receipts (.gbrain-connection-*.json beside ~/.claude.json and in CODEX_HOME; kept only when connection: 'local-stdio', a numeric setup_receipt_version, gbrain_home === configDir() and status prepared/installed). Engine-free, imports no harness writer. providerDeclineRecord() (a recorded providers: declined, opt-outs win) gates OpenAI model discovery and doctor's provider probe; claudeCodeSpawnsServe(cwd) (an installed claude-code receipt, user scope or a project receipt for exactly cwd) tells the SessionStart hook that Claude Code is starting a stdio serve.
  • src/core/bootstrap/plugin-lanes.ts — plugin-lane detection (*PluginProvidesName, *AnyRegistrationExists, re-exported by harness.ts; variants count as gbrain) plus enabledPluginLanes(name), read by plugin_lane_collision/harness_wiring. Config, not health. pluginHookYields: yield to no-hooks consent, another lane (Codex: trusted, enabled), a higher GBRAIN_PLUGIN.
  • src/core/bootstrap/codex-hooks.ts — the codex hooks.json writer (SessionEnd capture lane), built entirely on the dated CODEX_HOOKS_SPEC_TARGET (verified 2026-08-25 against pinned codex-cli 0.147.0, live + tag-source evidence; re-run the observation gate on codex version bumps). The three load-bearing facts: hooks.json is TOP-LEVEL deny-unknown-fields (ownership rides the legal description slot + a command-substring token, never a _gbrain key); user-layer hooks are TRUST-GATED and fail SILENTLY (the writer lands BOTH the hooks.json entry AND its [hooks.state."<path>:session_end:<g>:<h>"].trusted_hash config.toml entry — sha256 of the recursively-key-sorted compact canonical JSON of the normalized handler identity — inside a gbrain-managed marker block, backing config.toml up to .hooks.bak so it never clobbers the MCP writer's .bak rollback anchor); SessionEnd handlers are hard-killed at 3s (the command captures stdin to a mktemp file and detaches a nohup grandchild running the real gbrain hook session-end --harness codex — live-verified end-to-end). Deliberately NO GBRAIN_SOURCE in the command: hooks.json is user-global, so a baked source would stamp every codex session on the machine; session-end resolves everything from the payload. a fresh install APPENDS our group last while a re-run REPLACES it IN PLACE (a single well-formed install never shifts a foreign group's trust index; dropping DUPLICATE gbrain groups can shift foreign groups sitting after them — the writer prints a note naming the re-trust); the whole command is wrapped in a top-level sh -c '…' <bin> so a non-POSIX $SHELL (fish/csh) never parses the POSIX script; the foreign-trust-entry guard is a tolerant [hooks.state…] header match (not byte-exact); a golden known-answer hash vector pins the canonical recipe; removal also deletes the gbrain description when byte-identical to ours and NOTES the inherent index shift for foreign groups that sat after ours; unparseable hooks.json is never touched, on write or removal; the residual stale-trust-index case (user reorders their own groups) degrades to silent non-execution, which doctor's codex_hooks_never_fired rung names. Pinned by test/codex-hooks-writer.test.ts. codexHookTrustHash(eventName, command, timeout) is the generalized recipe (re-read against openai/codex rust-v0.162.1 hook_hash + version_for_toml; a known-answer vector from trust entries a live codex-cli 0.162.1 executed pins it in test/setup.test.ts). The setup lane (CODEX_SETUP_EVENTS SessionStart/UserPromptSubmit 15s, SessionEnd 3s) is hash-owned: codexSetupHookGroup renders env GBRAIN_HOOK_LANE=setup [GBRAIN_HOME=…] [GBRAIN_SOURCE=…] <bin> hook <sub> --harness codex (SessionEnd prefixes the detached capture command), codexHookCensus fingerprints every group and tags its lane, writeCodexSetupHooks replaces owned groups in place / appends / drops only owned groups (notes any index shift), and the token-owned bootstrap writer's isOurGroup skips groups carrying GBRAIN_HOOK_LANE=setup, so bootstrap never claims or strips setup's groups. writeCommittedClaudeHooks is the second, COMMITTED hook carrier: it writes marker-keyed entries into the workspace's checked-in .claude/settings.json using buildPortableClaudeHookCommand (PATH-resolved gbrain, fail-open when the binary is absent) so teammates cloning the repo inherit the hooks; committedHookEvents(ws) feeds the local writer's carriedEvents so the two carriers never double-wire an event, and removeClaudeHooks strips both.
  • src/core/bootstrap/codex-toml.ts — the ONE direct codex-config writer (codex mcp add cannot express an inline credential, and framework-spawned codex inherits no shell profile for the env-var lane). One [mcp_servers.<name>] table between full-line markers carrying url + http_headers = { Authorization = "Bearer <token>" } (NOT inline bearer_token, which codex-cli >=0.149 rejects at config load; parseCodexBlockBearer in harness.ts keeps a legacy bearer_token read fallback so existing tokens still recover); everything outside survives byte-for-byte. Foreign-server detection PARSES the config (Bun.TOML.parse, no dependency) with our block stripped — a header-only regex would false-negative inline-table/dotted/quoted spellings 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; 0600 tmp/target/.bak (the .bak carries the previous token on re-runs); CRLF preserved, missing trailing newline repaired. Also exports renderCodexHttpServerBlock({name, url, bearerToken}) — a MARKER-FREE, parse-validated [mcp_servers.<name>] TOML render for paste-into-config surfaces (gbrain agent register's codex block); rendering only, never writes a file. Pinned by test/codex-toml.test.ts. Also the hash-owned single-table helpers for gbrain setup codex: readCodexTomlTable, appendCodexTomlTable (EOF append, refuses an existing table, parse-verifies the result is exactly the old document plus the table) and removeCodexTomlTable (header through the line before the next header, keeping trailing comments/blank lines and a preceding # gbrain setup comment; unlocatable when the edit would change anything but that table, e.g. a re-rendered subtable). No markers: codex may rewrite config.toml and drop comments.
  • src/core/bootstrap/adopted-connections.ts + adopt-connection.ts — an operator-managed Codex PROJECT connection (<workspace>/.codex/config.toml [mcp_servers.<name>], streamable HTTP logged in with codex mcp login, or stdio) is not a bootstrap-owned registration, so the wire phase in status.ts reads it through adoptedConnectionState: detected (the table exists, nothing proves it works) is partial with the adopt hint, adopted is done, drifted (fingerprint changed, table gone, file unparsable) is partial with a re-adopt hint, none leaves the receipt/hook detectors' verdict (#4082). Evidence lives in the versioned, offline-readable sidecar <gbrain-home>/bootstrap/adopted-connections.json (version: 1, one row per workspace + harness + name; recordAdoptedConnection replaces, never appends twins), never in the install receipt, so uninstall does not tear down config bootstrap did not write. The fingerprint is sha256 over canonical JSON of transport, target (URL or command) and header NAMES; header values and tokens are never stored or printed, so a token rotation is not drift. adoptConnection backs gbrain bootstrap hooks --adopt --harness codex [--name <server>] (dispatch in src/commands/bootstrap.ts runHooks, before the harness writers): Codex only, refuses without a passing bootstrap verify run newer than the config file's mtime, writes nothing to the Codex config and fabricates no receipt registration. Pinned by test/bootstrap-adopted-connection.serial.test.ts. ownedEntryFingerprint(value) is the shared fingerprint (connectionFingerprint and gbrain setup's per-entry hashes both go through it).
  • src/core/bootstrap/serve-health.ts — serve /health probe + scopes version-skew floor, re-exported by harness.ts. probeServeHealth(mcpUrl, fetchFn, timeoutMs=3000) GETs <base>/health and returns {ok, version?, engine?, detail?}, never throws; fetchFn is an explicit argument (no ambient fetch, no engine, no config). isServeOlderThanScopes(v) compares against the PINNED SCOPES_MIN_SERVE_VERSION constant — a comparison against the moving CLI VERSION would false-flag every scope-aware serve on the next release. An older serve verifies scoped tokens as FULL ACCESS, so callers print the floor line unconditionally.
  • src/core/bootstrap/opencode-json.ts — the ONE direct opencode-config writer (workspace stdio lane, harness remote lane, connect --install). ALL edits ride jsonc-parser modify/applyEdits (comments/formatting/EOLs survive byte-for-byte outside the edited range — opencode's own mcp add preserves comments, and JSONC is its effective grammar for BOTH .json and .jsonc filenames, which MERGE when both exist). Ownership is a 4-state STRUCTURAL FINGERPRINT (opencodeEntryKind → ours-same-source | ours-other-source | foreign | absent; GBRAIN_SOURCE EQUALITY for local entries, receipt-url match or the {env:GBRAIN_REMOTE_TOKEN} interpolation for remote), never a marker key (a future strict-schema flip must not brick the host). 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 for inline-bearer targets; backups are UNIQUE per operation (<config>.bak-<hex>, returned in the result with writtenText, the exact rendered bytes) so overlapping runs can never clobber each other's snapshot, and a backup is chmod'd 0600 whenever the COPIED content carries an inline bearer (write AND remove paths); the ours-other-source refusal is caller-appropriate (url + --force wording on the remote/expect-url path, GBRAIN_SOURCE wording on the local path); removeOpencodeMcpEntry takes a caller expectation + optional skipOtherSource — the uninstall lane passes THIS workspace's source id so an ours-other-source match becomes a calm skip-with-note (another workspace's registration is never deleted; foreign still refuses); reconcileOpencodeSiblingGlobal clears a same-name gbrain entry from the OTHER global filename before a global write (foreign → refuse naming both files) — opencode merges both, so a leftover sibling entry is a shadow registration; the bun-run ownership lane is ANCHORED (an exact gbrain/gbrain-* path segment in some arg — a gbrainy-fork cli path is NOT ours, fail-closed); parseOpencodeEntryBearer recovers the harness --status token url-matched only; opencodeRemoteEntryExists is the stdio-lane ownership arbiter (codexBlockOwnsName analog). Callers hold acquireBootstrapLock (config-dir → opencode-dir ordering). Pinned by test/opencode-json.test.ts (incl. the fingerprint truth-table suite).
  • src/core/bootstrap/atomic-write.ts — the ONE atomic config-file writer for bootstrap host surfaces: symlink-target-resolving, mode-inheriting (freshMode for new files, forceMode for secret-bearing targets), random-suffix tmp + rename, tmp unlinked best-effort when write/chmod/rename throws (ENOSPC/EACCES never strand .tmp- litter), and the existsSync→realpathSync race falls back to fresh-path resolution instead of throwing raw ENOENT. hooks.ts (JSON), codex-toml.ts (TOML+EOL), and opencode-json.ts (JSONC) all swap through it; serialization and EOL policy stay caller-side.
  • src/core/bootstrap/harness.ts — gbrain bootstrap harness: machine-level wiring of framework-spawned Claude Code/Codex/opencode sessions to a RUNNING gbrain serve --http, no agent.json. The opencode target mirrors the codex posture: forced-wire on explicit --harness opencode (the JSONC writer needs no CLI), one managed mcp.<name> remote entry with the inline bearer header (0600) via opencode-json.ts, rotation across a url change recognized through the PRIOR receipt's url, failed-smoke rollback restoring the run's UNIQUE backup or removing a fresh entry — guarded by a content compare against the exact text this run wrote, so a NEWER registration that landed after the lock released is never clobbered (rollback skips with a note; the fresh mint is revoked either way), with the backup unlinked once consumed or once the smoke verifies — --remove classifying against the receipt url (not-ours skips with a note), and --status bearer recovery via parseOpencodeEntryBearer (url-matched). An explicit private posture (file-plane memory.visibility_posture) prints a pre-consent WARNING outside registrar mode: the wired HTTP sessions read world facts only, so they cannot read back what they save as private. Consent block in the honesty register (reach as fact, transcript capture its own numbered item + --no-capture, off-ramps in the same breath), then requireConsent via consentGate (effects persistent_install, plus credentials when it mints the token; --yes approves; the TTY prompt runs only when isInteractive(), and EOF/decline or no human at the terminal writes nothing and exits 3 with the consent payload, whose argv never repeats --token); /health probe with a loopback guard on --url (remote brains are gbrain connect's charter; --token makes it a pure registrar); mint-first rotation (previous token revoked BY ID only after every target confirms + the bearer smoke passes — clients are never dead mid-swap; revoke-by-name never happens); the smoke is canary-gated: a random same-format bearer must FAIL auth before the real token is sent, so a loopback impostor is caught whichever way it answers, and ANY failed smoke rolls back symmetrically — fresh registrations removed, replaced ones restored (an unrestorable replacement fails the target honestly), the freshly-added pre-approval stripped, and the fresh mint revoked immediately so nothing live stays pointed at an unverified endpoint; the permissions.allow pre-approval only lands after the MCP registration itself confirms; stale prior-target cleanup runs AFTER the smoke passes, so a run that failed to establish its replacement never unwires working prior wiring; write-ahead harness receipt (targets persist as pending at mint time and flip per-target, so a crash 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; GBRAIN_HOOK_LANE=harness on hook commands so gbrain hook yields to a workspace bootstrap install in the cwd (Claude Code merges settings scopes — same event must not fire twice); the hook GBRAIN_SOURCE, the receipt source_id, and the token grant bind to a validated --source (scalar write floor), else to the source HarnessDeps.resolveHookSource resolves through the SAME chain the serve's resolve-IPC binding runs (resolveSourceWithTier: env → dotfile → local_path → sources.default → sole populated non-default → seed default) with that source's federated read set as the grant, so the hooks' turn_context claim is never source_mismatch; a resolution landing on default/__all__ is the federated floor. Lookup failures are NOT papered over with default: a typo'd --source or stale env/dotfile throws SOURCE_UNRESOLVED before any mint or receipt; an explicit --source with an unopenable engine binds unverified with a warning; a live PGLite serve (engine cannot open) refuses with LIVE_SERVE when no token was supplied, printing (and in details.steps) stop / auth create + auth rescope --operations with the harness grant / restart / --token (#6661) and, on the --token lane without --source, wires the hooks UNPINNED with a warning (an unpinned hook resolves through the live serve's own binding; the receipt records the federated floor default plus source_pinned: false); any other lookup failure throws SOURCE_UNRESOLVED naming --source; Postgres degradation + serve-version-skew honesty lines (isServeOlderThanScopes pinned to SCOPES_MIN_SERVE_VERSION, the first scope-aware release, so later CLI bumps never re-trigger the warning); --status probes the live truth with host-config token recovery (redacted; the Claude Code lane recovers a bearer ONLY from a registration whose URL matches the receipt — never another install's credential; the codex fallback reads OUR managed block at the receipt-recorded path, its url key not yet compared — TODOS.md; the opencode fallback IS url-compared inside parseOpencodeEntryBearer) and honest verify: unavailable degrades, with a cron-honest exit contract: 0 only when serve + token + every target verify and the rotation has converged (honest degrades count), 1 on an unreachable serve, a failed token verify, failed/pending targets, unconverged rotations, or a half-removed receipt (zero targets, minted token awaiting deferred revoke — also a doctor FAIL); no receipt prints honestly and exits 0 in plain mode, 2 under --json; --json on apply emits ONLY the final JSON document on stdout (prose → stderr); --remove is engine-free-first and defers the token revoke with exact instructions under a live PGLite serve; it removes hook entries that lost their marker when their command is this install's (harness-hooks.ts), keeps the hooks target failed on an unowned lookalike, and --remove --dry-run previews without a lock or any write. Hooks targets record launcher and seat on the receipt (the ownership identity for later runs); the permission target carries mechanism: 'added' forward from a prior confirmed receipt target so a re-run never relabels its own mcp__<name> as pre-existing, and the failed-smoke rollback removes only an entry added this run. Locks on the gbrain HOME, plus the host config dir around codex/opencode writes, removals, rollbacks, and stale cleanup (stale prior-target cleanup nests the codex/opencode config-dir lock inside the held claude config-dir lock — same claude-first ordering as apply/remove, same-dir skip — so its read-modify-write can't interleave with a concurrent config-dir-locked writer); bootstrap uninstall holds the HOME lock across the whole teardown and 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. Pinned by test/bootstrap-harness.serial.test.ts + test/bootstrap-harness-lifecycle.serial.test.ts. The production mint (mintHarnessToken, exported) rotates each host's token from the token it replaces via carryLegacyGrant. --refresh-skills (src/core/bootstrap/harness-skills.ts, refreshHarnessSkills) re-joins each live shared-skills entry under its recorded credential so the receipt and native router adopt the server's current enrollment epoch, with no token rotation; localEnrollment reads the adapter receipt epoch for --status, and supersededEnrollments is doctor's read-only comparison against shared_skill_members (bootstrap_harness_health warn, code shared_skills_epoch_superseded). Pinned by test/harness-skills-epoch.test.ts. The Codex SessionEnd capture hook obeys the same recorded consent as the Claude lane (wireCodexCapture: hooks on, capture accepted, never registrar mode) and is a numbered consent item when wired. #6661 option B: harness-pending-verify.ts (a --token run on PGLite with no serve answering ends pending_verify, exit 13, re-run as fix; --status partial until it passes).
  • src/core/token-mint.ts — legacy-token mint/revoke for the harness lane: mintLegacyToken (scopes → the TEXT[] column; required takesHolders per-token allow-list, harness default ['world']; optional permissions.source_id federation array mirroring the stdio lane's localFederatedSourceIds grant, element 0 = write floor, [] stored as the explicit no-source grant; RETURNING id) and revokeLegacyTokenById (never touches same-name siblings). carryLegacyGrant + readActiveTokenPermissions are the harness rotation carry-over: takes holders and the source grant carry as stored (explicit empty lists included; an explicit --source wins), a stored operation snapshot narrows to the run's snapshot plus only skills-policy-added operations, newer operations are reported as withheld, and private_pages is never carried (readActiveTokenPrivatePages; the harness prints the rescope; pinned by test/harness-rotation-grants.test.ts). Exports TOKEN_ID_RE (shared with the auth revoke --id gate). Pinned by test/token-mint.test.ts. insertUnifiedToken (shared with auth create) births every token on the unified grant columns at revision 1 plus the permissions mirror; a brain whose schema predates the columns refuses with migrations_pending (fix: gbrain apply-migrations --yes) and nothing is written; carryLegacyGrant parses the prior grant from its JSONB through tokenGrantFromPermissions, so a drifted prior carries its JSON edit (the --adopt-permissions resolution).
  • src/commands/hook.ts — engine-free gbrain hook {session-start,user-prompt,stop,session-end,compact} (zero engine modules in the import graph; a hook must NEVER contend for the PGLite writer lock). session-start's context pack goes through src/core/context/session-start-pack.ts: when sessionStartAwaitsServe holds (source startup/resume, harness claude-code, claudeCodeSpawnsServe(cwd)), the hook's deadline widens from SESSION_START_DEADLINE_MS (1.5s) to SESSION_START_SERVE_WAIT_DEADLINE_MS (4s, under the 5s harness timeout) and requestSessionStartPack retries every 100ms, re-resolving socket and secret, until the serve Claude Code spawned alongside SessionStart answers (Cat 41 first push: Claude Code 2.1.285 starts MCP servers in parallel with SessionStart and a fresh serve binds ~2s later); a wait that runs out records heartbeat degraded/serve_not_ready. Pinned by test/hook-session-start-serve-wait.serial.test.ts. When GBRAIN_HOOK_LANE=harness (set on harness-mode hook commands), each event PARSES the cwd's workspace settings carriers — .claude/settings.local.json AND the committed .claude/settings.json — and yields silently only when a live bootstrap-v1 hook entry wires THAT event: the workspace install wins over user-scope harness wiring so the merged settings scopes can't fire the same event twice, unwired events still run, and a repo committing marker-lookalike strings in unrelated fields can't disable the machine-wide capture lane (fail-open — a read/parse hiccup means the event runs normally). user-prompt: stdin hook JSON → transcript-path confinement → last-4-turns window + cross-turn dedupe (the transcript's hook_additional_context attachments — the blocks WE previously injected — ride priorContextText, deduplicated and capped at PRIOR_CONTEXT_MAX_BYTES (32KB, so the advisory payload can never blow the IPC message cap; one oversized block is skipped without evicting smaller ones), so a page is volunteered once per session, not once per mention; structured extraction only, never raw-turn substring matching) → IPC turn_context (with a feedback-loop channel, --harness <claude-code|codex>, default claude-code) → hookSpecificOutput.additionalContext under an 800ms self-deadline; every path fails open (exit 0, empty stdout) with a typed reason in the heartbeat. Listed in cli.ts's STARTUP_HOOK_SKIP_COMMANDS (per-prompt invocations must never spawn a detached check-update child; membership is pinned by a source grep — the runtime path no-ops under NODE_ENV=test). session-start: file-plane digest (allowlisted MEMORY.md sections, push staleness, prior failures) + crashed-session recovery push gated on an initialized manifest. session-end: a transcript path or payload cwd carrying the claude-cli scratch fingerprint (isClaudeCliSelfTranscriptPath) is gbrain's own subprocess session — heartbeat segment: self_transcript, no parse, no corpus write; otherwise confined full-transcript parse → redacted corpus write (session-id filename dedup, retention prune via gcCorpusTurnFiles: an extracted .txt goes at corpus_retention_days, one with no .ingested sidecar only at CORPUS_UNINGESTED_RETENTION_FACTOR (3) times that, E-N1, pinned by test/corpus-retention-uningested.serial.test.ts; an assistant-only whole-file parse heartbeats degraded/no_user_turns, E-N4; the corpus scan runs highEntropy whenever the relay is on — the relay child derives its egress task line from the corpus text — and stays vendor-prefix-only otherwise) → parser-drift detection (bytes>0 && turns==0 is loud) → best-effort workspace push. session-start recovery + session-end pushes run in a DETACHED child so the hook returns immediately (a synchronous inline push would block harness startup on a dirty tree); the corpus write is atomic and clears the stale ingested/in-progress sidecars so a resumed session re-ingests its appended transcript. Heartbeat JSONL is counters/reasons only by construction; readHeartbeatTail feeds doctor. GBRAIN_HOOKS=0 kills all events. Session-end capture dispatches per harness through captureSpecFor(io.harness) (src/core/transcripts/capture-spec.ts): claude-code and codex each pin their OWN confinement root + parser; unknown/undefined/opencode resolve to the claude spec (golden-pinned). The codex lane confines to codexSessionsDir() + codexArchivedSessionsDir() (codex moves rollouts into the flat archived store), parses rollouts via parseCodexHookTranscript, and falls back to bounded id-matched discovery across both stores when the SessionEnd payload carries transcript_path: null or a path that no longer exists (missing_path; unreadable is reserved for EACCES/IO faults) — the fallback and prior-run relay failures are DEFERRED heartbeat reasons, applied after current-session reasons so they never mask one (first-degrade-wins). ONE gate covers the whole optional Memorable seam — memorableGateAllowed(cfg) in hook-heartbeat.ts: the config flag (integrations.memorable.enabled === true, file plane), the GBRAIN_MEMORABLE kill switch (any common negative spelling, trimmed; env can only ever disable), AND the gbrain-authored consent stamp (memorable-consent.json — see hook-heartbeat.ts). Off is the default: no tool-call collection, no receipt, no spawn. On, session-end runs the shared redactedToolCallsJson (span-filtered to the corpus window, highEntropy ALWAYS on — those args are the one artifact that leaves the machine) and recordAndRelayReceipt (receipt dedup by post-redaction content hash → CLI-side consent evidence → resolveMemorableBin → detached fire-and-forget memorable record spawn; both capture lanes trim memorable-relay.jsonl). Fail-closed egress guards: a scanner-import failure skips the receipt+relay entirely (memorable_relay_skipped_unscanned — parity with the openclaw lane), and a newest-mtime discovery GUESS (no session-id match) writes the local corpus but never relays (memorable_relay_skipped_newest_guess — the newest rollout can be a different, still-running session). A payload without session_id adopts the transcript's own id post-parse (never a shared unknown.txt corpus), and the gate answer is hoisted BEFORE the parse and collection is opt-in, so the default gate-off population never collects tool calls (collectToolCalls: memorableAllowed). Operator-facing doc: docs/memorable-agents.md (install is npm i -g memorable-cli; closed source, no source install, no embedding model to configure). spawnDetachedPush passes env: process.env explicitly so the detached push child inherits the parent's quarantined env view. tryExecAsync (the git wrapper behind resolveBootstrapWorkspaceRoot / repoPhaseComplete) also passes env: process.env so git sees the quarantined view, not Bun's startup snapshot; pinned by test/hook-push-spawn-env.test.ts. Seat identity (#4618): session-end (before any corpus write of the session), compact (before bankCompactSegment) and the stop hook's writeback bank (before bankWritebackTurn) record <sessionId>.seat.json through context/seat.ts — GBRAIN_SEAT when valid, else the hashed harness-home seat; seat_label_invalid, seat_conflict (first seat kept) and seat_write_failed are heartbeat reasons with a fixed hint (session-end applies them last, like the deferred reasons). gcCorpusArtifacts reaps a seat sidecar or session source record once no .txt of its session remains, after a 10-minute grace; session-end counts live sessions across the spool and the legacy top level (#6611). Pinned by test/session-seat-capture.serial.test.ts. HOOK_EVENTS is the router inventory from src/cli/subcommands.ts; hook <event> --help prints usage and never runs the event. user-prompt confines and parses transcript_path through captureSpecFor(io.harness), so --harness codex reads the rollout under CODEX_HOME/sessions (the Claude projects root otherwise), and skips the Claude-only pressure notice for codex. #5941: the pack and user-prompt arms ask for contextSourceId (session-start-pack.ts): GBRAIN_SOURCE, else the session's frozen source record, else the cwd's .gbrain-source walk; a serve bound elsewhere answers source_mismatch (the heartbeat reason).
  • src/core/transcripts/claude-code-jsonl.ts — the Claude Code transcript parser as a dated spec-target (tool_use/tool_result/thinking/image/sidechain/summary/compact-boundary shapes; placeholders for non-text content). recognizedOnly: whole file read, every line parsed, no conversation message, some session scaffolding (session-end: empty_session). Both the hook-tail and full-session parsers skip root isSidechain, isMeta, or isCompactSummary exactly true; nested markers and truthy non-booleans do not exclude a turn. User text with a non-empty string root origin.kind other than 'human' is excluded; missing, empty, or unstructured origins stay compatible, without guessing from message text. Assistant text and non-text placeholders remain eligible, while skipped metadata entries also contribute no collected tool calls. test/claude-code-jsonl-origin.test.ts uses synthetic fixtures, not new live-harness validation. genuineUserTurnIndexes separately records accepted user-role turns containing real text blocks (harness tags and paste blocks removed first), because Claude stores tool-result-only entries with role:'user'; archival consumers keep every placeholder while prompt-only consumers select by structure. Also extracts injectedContextBlocks — the hook_additional_context attachment lines a gbrain hook previously injected (verified live against claude CLI 2.1.224), plus a SessionStart hook_success attachment's content from the gbrain envelope on (session-start stdout, #7026; marker-filtered, so a foreign hook's blocks are excluded and another tool's output can't suppress volunteering — a same-user mislabeling guard, not an authenticity check), the user-prompt hook's cross-turn dedupe input; confineTranscriptPath (contained under ~/.claude/projects, .jsonl, lstat-rejects symlinks, byte cap; under WSL, a Windows drive-literal transcript_path — Claude Code on the Windows host invoking hooks via wsl.exe — is translated through src/core/wsl-paths.ts and then held to the SAME confinement, rooted Windows-side, so translation never widens what a hook may read). Fixtures: test/fixtures/conversation-formats/claude-code.jsonl (synthetic, privacy-guarded) + test/fixtures/hook-transcript.jsonl (real captured hook round-trip). parseTranscript additionally returns toolCalls, but collection is OPT-IN (collectToolCalls: true; the bare parse — every per-prompt lane — collects nothing, so tool INPUTS are never retained for users who never opted in): the tool name + input args for every tool_use block, oldest → newest, each joined to its tool_result outcome by tool_use_id and then stripped of that id so no transcript-internal identifier reaches a consumer; every STRING in a collected input is bounded to TOOL_CALL_VALUE_MAX_CHARS (32k) with an explicit …[N chars omitted] marker (capToolCallInput, shared with the codex lane — one receipt-size ceiling for every harness). It is a parallel extraction, never a change to the placeholder-only archival rendering, which is load-bearing for the token-budget-constrained ambient-recall path; existing callers that ignore the field see no behavior change.
  • src/core/transcripts/pasted-content.ts — #5812, the ONE Claude Code paste detector (<pasted_content id="…">…</pasted_content id="…">, tag shape from a real 2.1.287 transcript; depends on that harness format). stripPastedContent removes closed blocks and an unclosed tail only when the opening tag has the exact harness shape, scanning with indexOf (no lazy regex); stripPastedContentFromCorpus strips inside each [user] block of the toCorpusText rendering, never across the flattened corpus, so an unclosed paste ends with its turn. Consumers: the writeback gate (banked text), isGenuineUserText in the parser (classification only; turn, corpus, segment and ingest text keep the paste), and corpusTextForExtraction (corpus-segments.ts: a .wb- file is one turn, other corpus files per block) used by the sweep, the checkpoint harvest and dream extract_atoms. synthesize keeps pastes. Tests: test/transcripts-pasted-content.test.ts, test/facts/writeback-gate.test.ts, test/extract-atoms-pasted-content.test.ts.
  • src/core/transcripts/grok.ts — the Grok Build (grok CLI) transcript adapter: one session directory (~/.grok/sessions/<url-encoded-cwd>/<uuid>/chat_history.jsonl) = one session; GROK_HOME relocates the root. Turn selection is STRUCTURAL (mapGrokLine, exported so the dated SPEC_TARGET mapping is pinned): user turns are type:'user' text blocks WITHOUT synthetic_reason (injected system_reminder/task_completed rows are typed, i.e. intentionally text-free, as are tool_result-only user arrays); assistant turns need non-empty string content (tool-only rows — content ''/null WITH tool_calls — are typed); system/reasoning/tool_result/backend_tool_call rows are typed; unknown row types skip. A recognised HUMAN-turn row whose content this parser cannot decode (user content missing / non-string / non-array / an array holding non-block entries; assistant non-string content with no tool_calls) is malformed and counted as SKIPPED, never typed, so a file made only of such rows is never expectedEmpty — the ingest drift signal fires (bytesRead > 0, sessions 0, cleanScan=false, watermark frozen) and zeroSessionsReason names the malformed row count, instead of an upstream schema change silently advancing the watermark past whole conversations. chat_history.jsonl carries NO per-message timestamps: session times come from the sibling summary.json (created_at/last_active_at; a malformed summary is ignored, an unparseable date is never fabricated) and, because grok writes summary.json at session END, an in-progress session or partial rsync falls back to the log file's own mtime — a real filesystem time — with raw.timestamp_source stamped 'summary.json' vs 'file_mtime' so consumers can tell them apart (without the fallback the render refusal would freeze the --since-last watermark for the whole grok root). Every message carries the session bounds (last message = last_active_at, the rest = start). Session id: summary → UUID dir name → stableIdFromPath (a sha256 prefix of the log path, never the bare chat_history basename, which would collapse every such session onto one page). Sidecars (updates.jsonl, events.jsonl, rewind_points.jsonl, summary.json, prompt_history.jsonl) are not sessions — discover.ts's grok-sidecar filter is scoped to PROVEN grok trees and the head sniff rejects claude-family keys (grok detection runs after claude-code; an oversized system head still detects through the truncated-line sniff); a percent-encoded cwd segment that fails to decode yields cwd undefined with the session id intact.

Continue this subsystem · More entries.