Grok OSS fork notes

Grok OSS (grok-oss) is an unofficial open-source fork of xai-org/grok-build (SpaceXAI’s Grok Build CLI/TUI), maintained by Surmount.

It is not affiliated with or endorsed by xAI / SpaceXAI. Trademarks and product names belonging to xAI remain theirs.

Why the fork exists: upstream publishes under Apache-2.0 but does not accept external pull requests. This repo accepts community PRs. If upstream ever opens to outside contributions, Surmount intends to open a PR and try to land the useful fork work there.

Vision

Pillar	Practice
Faithful	Absorb xAI monorepo exports after review; keep `xai-grok-*` paths for alignment
Complete history	Surmount `main` is the continuous product archive; xAI is a content feed
Open	Pull requests welcome here
Distinct	Product Grok OSS, binary `grok-oss`, clear unofficial labeling
Compatible	Config and sessions under `~/.grok` (shared with upstream if both installed)
Superset	Fork features sit on top of upstream behavior, never hollow out core agent logic

Git flow

Normal feature branches → pull request → main. Temporary tool branches (import/*, onto-xai/*) are not a second main; they land via PR.

On open PRs, catch up with main by merge, not rebase (no force-push while CI runs). Detail: docs/git-workflow.md.

Remotes

git remote add xai-org https://github.com/xai-org/grok-build.git   # once
# origin → SurmountSystems/grok-oss
# xai-org → xai-org/grok-build

Syncing with xAI

xAI publishes force-pushed snapshots (bot author, often orphan roots, sometimes short “Synced from monorepo” chains). GitHub may say histories are “entirely different.” Expected. Treat them as a tree feed, not shared ancestry.

Maintainer jobs (do not confuse them):

Job	Command	Result
Import: their tree into Surmount history	`grok-nix-helper import-upstream-export`	`import/*` review branch → PR to `main`
Stack on tip: our product commits on their tip	`grok-nix-helper put-history-on-xai`	`onto-xai/` (real cherry-pick*; no `MODE=overlay`)
Join `main` into onto: landable graph	`grok-nix-helper join-main-into-onto`	same tip; `main` becomes ancestor; tree kept (`-s ours`) → PR

When histories keep breaking: stack product on their tip, then join Surmount main (-s ours) so GitHub compare/PR works, then PR to main. Detect: grok-nix-helper detect-upstream-export or just upstream-detect. The helper prepares git state. A human TTY signs: git commit -S. Agents never GPG-sign and never git commit.

GitHub tracking and git-flow (pinned 2026-09-08): Plan Approve → new GitHub issue with the full plan text. Bug report → new issue on the appropriate origin, with screenshots. After the operator signs and pushes, open or update the PR that describes all the work. Collaborative work uses feat/ / fix/ / docs/ branches from main. Canonical: docs/github-tracking.md. Dual-pin AGENTS.md 1b/1c, CONTRIBUTING.md, docs/git-workflow.md, host ~/.grok/AGENTS.md.

Full process: docs/upstream-history.md Import log: docs/upstream-import-log.md Onto log: docs/upstream-onto-log.md

Never: reset Surmount main to xAI; GitHub “Sync fork” that drops Surmount commits; unsigned commits; bulk tree rewrites without review.

Hunter's razor (pinned 2026-09-01)

Never assume competence. Do not treat a solution as superior because it comes from SpaceX, from xAI / SpaceXAI, or from a newer upstream export. Never assume someone else has thought everything through.

A more recent upstream version may already solve a problem we have. We also solve problems we find. Given two solutions, the result must always be maximally meritocratic, even if that means synthesizing a better solution from both. That is how a senior engineer solves problems. We balance the constraints with the best knowledge we have.

This is not a license to ignore upstream. Evaluate both. Upstream can win. Our fix can win. A synthesis can win. This is process law for Grok OSS versus xAI / SpaceXAI upstream, not a slur.

Wasted human time (pinned 2026-09-01)

A dropped operator prompt is a product defect. Repeating because the harness lost the text is an engineering miss. The durability path is the prompt write-ahead log (prompt_wal.jsonl). /rebuild and session load must preserve that log the same way they preserve an unsent composer draft and pending_prompts.json, once that file exists in the tree. User-guide 04-slash-commands /rebuild must say that relaunch preserves the WAL once the file exists. Do not document that preservation as shipped while the file is absent.

Named tests are Surmount contracts: quote the owed outcome, keep the stronger assert, enroll them in doc/dev/upstream-regression-filters.md § Prompt write-ahead log, do not fit them to a wipe. Meritocratic with § Hunter's razor. Operator-verified known good (2026-09-02) for named tests that encode live send, rebuild-flush, interject, and plan-notes appends, because live session files contained those kinds. Queue enqueue stays a catalog contract and is not that known-good mark. Restore and skip tests stay contracts. Do not delete or weaken those tests in recon, onto, import, or join. This pin does not replace Hunter's razor, pasted-image tokens, lost-prompt integration tests, Operator/Agent speaker labels, or the /rebuild persist named-test list. Dual-pin: AGENTS.md § Wasted human time (hard constraint 24). Host pointer: ~/.grok/AGENTS.md § The operator's words are the spec.

What Grok OSS adds (divergence inventory)

Hierarchical: one complete sentence here, then a named fn plus crate, or a linked doc. This list is the defense inventory for the next upstream merge. A checkbox is not proof. Import restores FORK_PATHS (docs, scripts, packaging) only. Product seams inside xai-grok-* survive onto only by cherry-pick plus named cargo tests.

When you ship a restack-droppable seam: add the one-liner here with the exact fn name; enroll that filter in doc/dev/upstream-regression-filters.md; keep helper-green (substring grok on --version, theme file exists, schema without /spend ingest, serde without a /settings row, rank helpers without sampling_config hop keys) out of the land proof. Do not list a catalog identifier that has no matching fn.

Product

Chrome

Human chrome is green (accent_user: composer caret, human rails, OSC 12, success). Agent activity is magenta (accent_running / accent_model: active agent rails, tool spinner, lower-left still-running cue). Clear finished is quiet secondary, not neon green and not magenta. Default theme is DOGE. External role map: 0001_DOGE.md. User-guide 06-theming.

Packaging and build

Process

File-level infer-from-path verify

After ACP search_replace / apply_patch (and the other structured edit tools), the edit tool infers from the path. A .rs file is formatted and linted as that file. The format and lint argv must include the written path. That is not crate or project cargo, not just check, and not an AGENTS process slogan. Markdown, toml, and other non-.rs paths stay quiet. The command-running tool still rejects crate-wide cargo launches (cargo fmt --all, cargo fmt -p without a file list, cargo clippy -p ... --all-targets, --workspace). Kill switch if already in the plan: GROK_SKIP_EDIT_VERIFY=1.

File-level rustfmt-only may stay on this laptop (no rustc). File-level clippy that compiles belongs on the remote builder too (just cargo-remote / just check-remote). Agents must not run cargo test, cargo clippy, cargo build, or rustc on this laptop for grok-oss. Named filters: just test-remote (see the CI table). For now, cargo tests run on surmount-1, not on horizon; horizon must export GROK_SKIP_EDIT_VERIFY=1 before starting grok-oss so edit-tool verify does not invoke rustc or cargo here. GROK_SKIP_EDIT_VERIFY is still the kill switch, not a config.toml key and not the product default on other hosts. See Process Cargo tests run on surmount-1, not on horizon.

Quality cargo fmt --all -- --check (workspace-cargo-quality) is a hard miss. rustfmt Diff in is not a flake 502. File-level rustfmt on the written .rs is how a write stays on that gate (example: wrapping Result in MCP servers.rs so rustfmt does not emit Diff in). nix_retry does not retry that class.

This is product behavior. Process law (do not prove the slice by spawning crate-wide cargo through extra subagents; named cargo on the remote builder) lives in AGENTS.md hard constraints 3b, 3b-remote, and 3b-remote-named.

Named tests (fixture and argv only; they must not clippy this workspace). Module filter rust_edit_verify matches these fns:

rustfmt_argv_edition_2024_config_and_absolute_files
clippy_argv_lints_the_edited_file_not_crate_lib
clippy_argv_includes_bin_path_not_package_lib
clippy_argv_includes_integration_test_path_not_package_lib
clippy_argv_is_file_level_not_package_lib
several_rust_writes_run_file_level_clippy_per_file
clippy_driver_uses_temp_out_dir_not_the_workspace_root

ACP refuse rustc probe junk at the workspace root (same crate, compiler_probe_junk plus the write / search_replace / apply_patch / bash filters):

names_match_rmeta_long_type_a_out_rust_out
root_rmeta_is_junk_nested_target_is_not
rustc_oneshot_is_refused_version_and_tmp_out_dir_are_not
write_refuses_rmeta_at_workspace_root_and_does_not_create_the_file
write_refuses_a_out_at_workspace_root_and_does_not_create_the_file
write_refuses_rust_out_at_workspace_root_and_does_not_create_the_file
write_refuses_long_type_dump_at_workspace_root_and_does_not_create_the_file
search_replace_refuses_a_out_at_workspace_root_and_does_not_create_the_file
apply_patch_refuses_add_rmeta_at_workspace_root_and_does_not_create_the_file
rustc_oneshot_without_out_dir_is_refused_and_does_not_spawn_shell
rustc_stdin_rust_out_is_refused_and_does_not_spawn_shell
rustc_dash_o_a_out_at_workspace_root_is_refused_and_does_not_spawn_shell
redirect_rmeta_at_workspace_root_is_refused_and_does_not_spawn_shell

Workspace hygiene still says do not gitignore probe junk. That stands. The product fix is the tool refuse, not a mop and not .gitignore.

Command-tool reject (same crate, dangerous_cargo filter):

dangerous_cargo_fmt_all_is_refused_and_does_not_spawn_shell
dangerous_cargo_fmt_package_without_file_list_is_refused_and_does_not_spawn_shell
dangerous_cargo_clippy_all_targets_is_refused_and_does_not_spawn_shell
dangerous_cargo_clippy_package_all_targets_is_refused_and_does_not_spawn_shell
dangerous_cargo_clippy_workspace_is_refused_and_does_not_spawn_shell
dangerous_cargo_test_workspace_is_refused_and_does_not_spawn_shell
dangerous_cargo_nextest_run_without_package_or_filter_is_refused_and_does_not_spawn_shell
dangerous_cargo_test_package_lib_filter_is_not_refused

Catalog: doc/dev/upstream-regression-filters.md § File-level infer-from-path verify. Extra restack-droppable class, not one of the seven numbered land classes.

ACP per-path write lock

ACP search_replace, apply_patch, write, OpenCode edit, and hashline_edit (GrokBuildHashline:hashline_edit) take a per-path write lock automatically as part of the tool call. There is no lock argument on the tool schema. A successful write does not mention the lock.

When another agent already holds that path, the tool returns an error that names the holder and the file. It does not write. It does not overwrite silently. It does not wait inside the tool. It does not show a human steal, skip, or wait menu. Agents resolve the conflict by talking to each other: they can wait, hand off, or pick another path.

The lock is held through file-level infer-from-path verify on a written .rs file. GROK_SKIP_EDIT_VERIFY=1 still skips only that verify.

OpenCode edit (tool id "edit") acquires after directory, same-string, and bulk-edit checks, and before create or replace. The guard stays in run so rustfmt and clippy-driver on the same .rs path stay under the hold.

hashline_edit acquires on the joined path after resolve_model_path, before canonicalize or any write. Existing-file edits and new-file Write both take the lock. Same helper; no second table; no human menu.

Named tests (module filter per_path_write_lock):

two_agents_cannot_write_the_same_path_at_once
happy_path_first_writer_succeeds_silently
lock_releases_after_the_tool_call_so_a_later_call_can_write
search_replace_apply_patch_and_write_all_take_the_lock
held_path_error_names_holder_and_file_without_a_steal_skip_wait_menu
hashline_edit_refuses_when_another_agent_holds_the_path
hashline_edit_happy_path_does_not_mention_the_lock
sequential_writes_succeed_after_the_first_tool_call_returns_even_when_both_agents_were_assigned_the_same_write_paths
concurrent_in_flight_writes_on_the_same_path_still_conflict
spawn_write_paths_soft_assignment_does_not_block_a_sibling_and_the_reminder_is_observable
same_holder_can_write_a_path_they_reserved
sequential_search_replace_succeeds_after_the_first_tool_call_returns_when_both_agents_were_assigned_the_same_write_paths
search_replace_succeeds_when_a_sibling_only_has_a_soft_write_paths_assignment
soft_lock_reminder_is_observable_on_a_sibling_tool_call
spawn_write_paths_overlap_is_a_soft_assignment_not_a_spawn_error
cow_snapshot_read_is_ephemeral_many_readers_one_writer
read_file_uses_cow_snapshot_and_does_not_take_the_exclusive_write_lock
after_write_returns_held_is_empty_lock_must_be_released
reader_during_held_write_gets_published_pre_write_bytes_current_atomic_snapshot
two_live_agents_with_the_same_write_paths_spawn_without_error_l2_and_l3_may_be_assigned_the_same_file

Spawn write_paths on task / spawn_subagent is a soft assignment. Other nested agents get a reminder (L2 X is assigned these paths). Share is allowed. Spawn and later sequential edits do not fail for the child's lifetime. Exclusive is try_acquire_write for one search_replace / write / apply_patch call, then Drop. Two agents still cannot write the same file at the same instant. After write returns, held() is empty.

The path table is a reader-writer lock, not write-only. try_acquire_read is a CoW snapshot read: ephemeral, many concurrent readers, snapshot at a point in time. It does not take the exclusive write lock, does not block a writer, and is not blocked by a writer for the snapshot itself. read_file uses that CoW published snapshot (published_cow_snapshot) while a writer holds the path. Soft write_paths assignment stays a writer reminder.

cargo test -p xai-grok-tools --lib per_path_write_lock
cargo test -p xai-grok-tools --lib spawn_write_paths_overlap_is_a_soft_assignment_not_a_spawn_error
cargo test -p xai-grok-tools --lib soft_lock_reminder_is_observable_on_a_sibling_tool_call
cargo test -p xai-grok-tools --lib -- \
  after_write_returns_held_is_empty_lock_must_be_released \
  reader_during_held_write_gets_published_pre_write_bytes_current_atomic_snapshot \
  two_live_agents_with_the_same_write_paths_spawn_without_error_l2_and_l3_may_be_assigned_the_same_file

OpenCode edit fixture (not under that module filter):

opencode_edit_cannot_write_a_path_another_agent_already_holds

cargo test -p xai-grok-tools --lib opencode_edit_cannot_write_a_path_another_agent_already_holds

Skills (multi-source)

Skills are loaded from several places; the product on this branch owns the machinery. Full map: doc/dev/research/where-skills-come-from-2026-07-24.md, user-guide 08-skills.md.

Source	Role
Project `.agents/skills`, `.grok/skills`	Git-trackable on the branch (supported; may be empty). Not the home for `/polish` or `/subagent`.
`crates/codegen/xai-grok-bundle/skills/`	In-tree Grok OSS default skills (`polish`, `subagent`, `what`, `pull-remote-tree`). Installed into `~/.grok/bundled/skills/` on startup and after network extract. Live cache is not the source. When the operator asks to revise a skill in grok-oss, edit this tree. Named tests are the contract so skill maintenance and upgrades cannot drop it.
`~/.agents/skills` then `~/.grok/skills`	Host operator overlay (agents wins)
`[skills].paths` / server inject / plugins	Config and managed dirs
`~/.grok/bundled/skills`	Platform cache from network bundle sync plus installed Grok OSS defaults

Process pins that must survive recon (import / onto): document in FORK + AGENTS + product user-guide when product-facing; dual-pin host skills (~/.agents) when operator-only. Host skill git alone does not ride product history. Chat-only pins die at compaction.

User-guide fork pins (one line + link)

The shared guide under crates/codegen/xai-grok-pager/docs/user-guide/ is not in FORK_PATHS. Onto takes the xAI guide unless conflict resolve keeps Surmount pages. Do not paste those pages here.

Page	Fork pin	Cargo pin
`01-getting-started`	Binary is `grok-oss`. Bare interactive open is last session for this cwd, not Welcome.	Last-session sentences shipped in code; no dedicated `fn`.
`02-authentication`	SuperGrok is paid. Distinct meters. `/limits` and compact chip. Hop after included SuperGrok period limits are full. Fail-open: a client 100% / remaining 0 / $0 printout must not mark SuperGrok used up. Named `/limits` words and `limits_pins.json`. grok-oss limits is not xAI billing truth. Machine console API key for host surmount-1: console API credits / console team prepaid, install under that host grok home (`$GROK_HOME` or `~/.grok`), never commit the key, no guest git, GPG sign on the laptop, attach SSH + tmux as user grok, L0 is not `/dashboard`.	`user_guide_does_not_claim_automatic_host_hop_is_unshipped`, `user_guide_limits_names_fail_open_and_named_commands`, `user_guide_machine_console_api_key_for_surmount_1`. Zero `/limits` hits is a failed land in catalog prose; no cargo hit-count `fn`.
`03-keyboard-shortcuts`	Plan keys and Enter cue (send / queue / interject). Empty Enter never approves a plan. Nested L2/L3 overlay Esc dismisses the view and does not cancel.	Plan honesty `fn`s under Chrome. Overlay Esc: `l2_overlay_app_esc_dismisses_without_cancel_or_cancelling`.
`04-slash-commands`	`/running` (alias `/windows`) lists live grok-oss TUI windows. Not Agent Dashboard. L0 is Surmount GPUI and must not merge with `/dashboard` or `/running`. L0 action set remote host console API key is laptop-side for a machine console API key (never prints the key; no guest git). `/start` starts paused or interrupted work in this process; not `/resume`. `/unstick` resends the last parent prompt as if the network dropped it; orphans a hung in-flight prompt; WAL images resend as resource links, never data URLs; not `/resume`, not a second Operator line, not unwind. `/finish` writes a session post-mortem (work continues; leftover and next features stay first-class; not `/dream`, not `/recap`, not `/reports`). `/reports` writes a checkpoint while work continues (host overlay `~/.agents/skills/reports` plus pager slash). `/polish` is a polish pass as a default Grok OSS skill (in-tree `crates/codegen/xai-grok-bundle/skills/polish`, installed into `~/.grok/bundled/skills/polish`; not host overlay, not a pager builtin, not a project `.agents/skills/polish` pack; not `/finish`, not `/reports`). `/subagent` (and `/subagent this`) spawns one L2 coordinator as a default Grok OSS skill (in-tree `crates/codegen/xai-grok-bundle/skills/subagent`, installed into `~/.grok/bundled/skills/subagent`; not host overlay, not a pager builtin, not a project `.agents/skills/subagent` pack; L1 does not do the job). `/what` restates this session in four complete thoughts (Job, State, Operator, Next) when chat is unclear. Speaker labels are Operator not You or Human, and Agent not Me or Grok when Grok means the assistant. Never mix Grok Build version with grok-oss product version. Isolated Preview and plan chrome are grok-oss unless this process was launched as `grok` from downloads. Default Grok OSS skill at `crates/codegen/xai-grok-bundle/skills/what`, installed into `~/.grok/bundled/skills/what`. Not host overlay as the grok-oss source. Not repo `.agents/skills/what`. Follow Concise American Technical English (`0005_CATE.md`). `/compaction` aliases `/compact`. Named hold (`queue`/`later` or `/queue <slash>`) puts `/compaction`, `/plan`, `/reports`, `/finish` on the existing composer prompt queue without running them this turn. Immediate invoke stays. Present is not Approve. `/metadata` shows ULID, UUID, cwd, model, started, pid, plus last Chat Completions `system_fingerprint` and last language-models `{id, fingerprint, version, created}` for the current sampling model (serving-path config, not a SHA of the weights, not on the status bar). `/limits` named words: stay-supergrok, use-console, meter included or dollar-credits or console or combined, refresh. Fail-open printout must not mark SuperGrok used up. Once `prompt_wal.jsonl` exists in the tree, `/rebuild` must say relaunch preserves that WAL. Do not document that preservation as shipped while the file is absent.	`running_slash_lists_sibling_fixture_row`; L0 `surmount-coordinator-gui` `write_enqueue_creates_per_session_file`, `omits_prompt_text`, `keeps_pid_session_cwd`, `enqueue_drop_path_is_per_session_id`, `CoordinatorApp_selects_row`, `CoordinatorApp_omits_prompt_in_displayed_fields`, `CoordinatorApp_enqueue_writes_drop_file`, `set_remote_host_console_api_key_never_prints_the_key`, `set_remote_host_console_api_key_is_not_pager_dashboard`; `user_guide_machine_console_api_key_for_surmount_1`; `/start` cite `start_` tests; `/unstick` cite `unstick_` tests; `finish_empty_args_injects_postmortem_skill`; `finish_skill_copy_does_not_say_work_is_closed_forever`; `reports_empty_args_injects_reports_skill`; `what_empty_args_injects_what_skill`; `what_instruction_prefers_operator_and_agent_speaker_labels`; `what_skill_does_not_mix_grok_build_version_with_grok_oss`; `user_guide_what_does_not_mix_grok_build_version_with_grok_oss`; `what_registered_in_builtin_commands`; `queue_compaction_does_not_invoke_immediately`; `queue_plan_does_not_invoke_immediately`; `metadata_command_emits_show_session_metadata`; `show_session_metadata_includes_fingerprint_fields_from_stored_samples`; `user_guide_metadata_documents_serving_fingerprints`; `user_guide_limits_names_fail_open_and_named_commands`. No `user_guide_start` `fn`. Guide still documents `grok-oss rebuild`; that page is not cargo-proven for CLI rebuild.
`05-configuration`	`hide_header` is in-app only. Titles use `title.enabled`. `[subagents] allow_worktree` defaults false. `[ui] composer_multiline` defaults on; false makes the Operator box single-line.	Class 2 readers. Do not claim Token Economy `/settings` table rows as proven.
`06-theming`	Default theme is DOGE. Operator green / agent magenta roles.	Class 4 theme + rail `fn`s. `user_guide_operator_agent_speaker_labels_not_human_user_grok`.
`08-skills`	Product skills are not a Python runtime (allowlisted CLI stubs + office/docx/pptx/xlsx/pdf only). `/polish`, `/subagent`, `/what`, and `/pull-remote-tree` are default Grok OSS skills (in-tree `crates/codegen/xai-grok-bundle/skills/`, installed into `~/.grok/bundled/skills/`). Revising a skill in grok-oss edits that tree. Not repo `.agents/skills/what`.	`user_guide_skills_are_not_a_python_runtime`; `default_product_skills_include_polish_and_subagent`; `what_empty_args_injects_what_skill`; `what_instruction_prefers_operator_and_agent_speaker_labels`; `what_skill_does_not_mix_grok_build_version_with_grok_oss`; `user_guide_what_does_not_mix_grok_build_version_with_grok_oss`; `user_guide_operator_agent_speaker_labels_not_human_user_grok`
`16-subagents`	Worktree isolation off by default. Soft interject never cancels. Three-layer paragraph. Hierarchical fast path (L1-only). L1 Subagents list is L2-only plus a live L3 count. Live list is still-running only. already_exited still dismisses the paused Implementer overlay. Compacting `[↗]` still opens. L2 overlay is a mid-turn ask to that L2. L3 overlays stay unbothered. Esc on the nested view dismisses it and leaves the L2 running (not Cancelling). New reports under `~/.agents/reports/`. L1 AUTO compact uses catalog 500k. L2 nested 200k may compact. An L2 implement coordinator must spawn L3 for greps, reads, and product edits. L2 does not fill 200k implementing. `capability_mode` All is the full-tool escape. Ordinary L2 still AUTO compact at 95% of nested 200k. L3 never compact and must not compact-and-continue. Parent follow-up onto a running nested L2 is additive (not kill, not respawn). `resume_from` remains completed-continue. L3 overlays stay unbothered. Off is the SpaceXAI option (spawn, wait, resume after exit).	Three-layer / fast-path / L2-only guide text shipped in code; no dedicated user-guide `fn`. Cargo: `child_task_description_is_concise`, `l2_implement_coordinator_capability_none_strips_search_replace`, `l2_implement_coordinator_capability_none_strips_grep_and_read_file`, `l2_implement_coordinator_still_keeps_spawn_subagent`, `l3_at_max_depth_keeps_search_replace_and_grep_without_task`, `l2_capability_mode_all_keeps_edit_grep_read`, `l2_auto_compact_still_fires_at_95_percent_of_200k`, `live_subagent_list_shows_only_l2_and_reports_live_l3_count`, `kill_already_exited_dismisses_paused_implementer_overlay`, `restore_nested_occupancy_does_not_unfinish_or_revive_dead_host`, `running_count_matches_listed_live_l2_not_l3`, `click_tasks_open_on_compacting_row_opens_subagent`, `click_tasks_open_on_last_painted_row_opens_subagent`, `click_tasks_kill_on_compacting_row_emits_kill`, `open_subagent_fullscreen_sets_active_while_child_is_auto_compacting`, `l2_overlay_send_prompt_interjects_l2_not_l1`, `nested_reparent_stamps_l3_depth_and_immediate_parent`, `l2_overlay_esc_leaves_overlay_without_cancelling`, `l2_overlay_app_esc_dismisses_without_cancel_or_cancelling`, `l2_overlay_esc_does_not_fire_armed_parent_cancel`, `parent_cannot_talk_to_own_l2s_follow_up_enqueues_interject_on_running_l2_without_kill_or_respawn`, `parent_follow_up_does_not_inject_into_live_l3_unless_operator_targeted_that_specialist`, `resume_from_of_running_l2_still_fails_active`, `parent_follow_up_off_is_upstream_spawn_wait_resume_from_completed_only`, `parent_follow_up_onto_running_l2_with_live_l3_hits_l2_not_l3`, `parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_returns_queued_and_does_not_spawn`, `parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_and_resume_from_are_mutually_exclusive`, `parent_cannot_talk_to_own_l2s_follow_up_field_is_optional_and_distinct_from_resume_from`, `shell_child_follow_up_sends_session_command_interject_on_child_session`, `subagents_config_parent_follow_up_false_parses_and_omitted_defaults_true`, `resolve_subagents_copies_parent_follow_up`, `nested_spawner_can_resume_from_completed_reparented_child`, `l3_overlay_send_prompt_does_not_reach_l3_or_l1`.
`17-sessions`	Last-session on start vs `-c` / `--resume` vs `/start` vs leftover `canceled_turn_resume.json` drop after a successful primary-turn finish. Running grok-oss sessions vs disk `grok-oss sessions`. Resume examples use `grok-oss`.	`user_guide_resume_and_version_examples_use_grok_oss`; `/start` + marker-drop cite `start_*` and `session_load_drops_stale_cancel_resume_marker_when_primary_turn_finished_successfully`.
`19-plan-mode`	Present is not Approve. Idle footer is Approve / Comment / Revise / Exit. Clarify only after Comment. Empty Enter never approves. Copy/`y` is not a fifth idle CTA (title bar + hint). Approve files a GitHub issue with the plan text (`docs/github-tracking.md`). Selected CTA is marked. Enter submits the marked CTA. Click marks the CTA and runs it. First click on Approve still Approves. Letter keys type. Freeform questions, not the questionnaire modal. `/plan --soft` docks Isolated Preview and does not enter plan mode.	Extra class B `fn`s. Keep identifier `plan_approval_footer_paints_five_cta_vocabulary`. `user_guide_plan_soft_docks_isolated_preview`. Copy/`y` and selected-CTA Enter: `y_copies_the_plan_while_the_comment_overlay_is_open`, `plan_approval_pane_has_a_clickable_copy_control`, `plan_approval_cta_row_does_not_paint_copy`, `plan_approval_copy_button_click_copies_the_plan`, `selected_idle_cta_is_visually_marked`, `enter_submits_the_marked_idle_cta`, `enter_while_composing_a_comment_still_saves_the_comment`, `empty_enter_never_approves_even_when_approve_is_marked`, `click_selects_a_cta_and_first_click_approve_still_submits`, `second_click_on_already_selected_cta_still_submits`, `letter_key_types_and_is_not_the_only_submit`.
`22-permissions-and-safety`	Always-approve is tool permissions only, not plan Approve.	`exit_plan_mode_shows_overlay_even_in_yolo`
`23-dashboard`	Agent Dashboard is this pager. Running grok-oss sessions must not merge into `/dashboard`. L0 is Surmount GPUI, not this pager, and must not merge with either. Call L0 `grok-oss gui`. L0 action set remote host console API key is laptop-side, not this pager. Session todos stay in this TUI.	Cite `omits_prompt_text`, `set_remote_host_console_api_key_is_not_pager_dashboard`, `user_guide_machine_console_api_key_for_surmount_1`.
`24-monitoring-usage`	`/spend` ledger vs org metrics. Do not mash meters.	`user_guide_names_token_economy_spend_order`

Also: user_guide_operator_cli_examples_use_grok_oss (leftover grok login / grok sessions must not return).

Dogfood snapshot (2026-08-09)

This section is a dated operator handoff from 2026-08-09. It does not demote later shipped claims in Product, Chrome, or Land above. Source restore is not live TUI dogfood. This file does not claim a rebuilt interactive grok-oss. Do not start rebuild or quit from this inventory.

Read first (next task, recon, or dogfood):

Operator install gate: code can be green while old TUIs still run a deleted-inode binary. Checklist: .agents/reports/d0-dogfood-checklist-2026-08-09.md. Package status for that wave: .agents/reports/impl-remaining-plan-wave-2026-08-09.md.
Shipped in that wave (tree + reports; dogfood only after a later install the operator chooses): decisive plan Revise; same-batch plan.md write + exit_plan_mode; plan decision surface (empty Enter never approves; Plan ready. Side panel open); revise/clarify in-flight status; caret empty half text_primary; OAuth 403 bad-credentials path; rewind missing intermediate checkpoints; Ctrl+C dismisses rewind; status [pause]/[resume] + red [stop]; soft stop chord-only; composer Enter send/queue/interject cue; compact included SuperGrok period limits meter. Later Product / Chrome bullets and named fns supersede this snapshot when they disagree. Later Product bullets for /start and leftover canceled_turn_resume.json drop supersede this snapshot. Do not revive idle Clarify as current leftover.
Still not shipped (honesty leftovers, not a demotion of shipped chrome)
- Auto-resume after error terminal on rebuild/reopen: expected operator contract if the last terminal was an error (not only the cancel-resume marker). Document as shipped only when .agents/reports/impl-rebuild-auto-resume-after-error-2026-08-09.md (or equivalent) is green in tree. Distinct from continue interrupted turn (canceled_turn_resume.json). After any auto-resume, 403 bad-credentials may still need /login.
- Soft-stop button: not shipped; soft stop stays Ctrl+Shift+S only.
- Mid-sample freeze without cancel: not shipped (global pause cancels turns; soft stop only stops queue drain after the current turn). Do not invent a media-player freeze metaphor.
- CLI grok-oss rebuild: clap-wired (Command::Rebuild, rebuild_subcommand_parses). Compiles and signals live instances. Does not re-exec this process. TUI /rebuild still owns persist plus self re-exec.
- /economic-mode slash: pager queues the text only. No BuiltinAction. Economic cap at spawn / model switch / header is shipped.
- SuperGrok Heavy ranking optional label: not implemented. SuperGrok Heavy is a real distinct weekly pool. This file does not diagnose product usage of that pool.
Still open (residual, not this install alone)
- Included SuperGrok period flat % / server C4 debit: paste-ready ticket .agents/reports/c4-xai-ticket-paste-ready-2026-08-07.md; never invent included SuperGrok period used % on the client.
- Thoughtful todo tracking process (session board hygiene; not file-level edit verify): RESIDUAL.md Open.
Useful regression filters from that wave only (not a substitute for the seven-class land list):

cargo test -p xai-grok-pager --lib -- after_revise re_present_after_revise \
  paint_composer_box_cursor_grapheme_phases_keep_letter \
  left_through_letters_empty_phase_not_neon
cargo test -p xai-grok-shell --lib -- same_batch_plan_write_before_exit_plan_mode_returns_new_body \
  replay_skips_missing_intermediate_checkpoint
cargo test -p xai-grok-sampling-types --lib -- forbidden_bad_credentials
cargo test -p xai-grok-sampler --lib -- api_403_bad_credentials classify_forbidden
cargo test -p xai-grok-pager --lib -- work_control_chrome_matrix_pause_not_cancel_stop_not_pause \
  pause_button_click_dispatches_global_pause_not_cancel

# File-level infer-from-path verify (2026-08-15; extra class, not that wave)
cargo test -p xai-grok-tools --lib rust_edit_verify
cargo test -p xai-grok-tools --lib dangerous_cargo

Process law (plain English, no bad metaphors): host + project AGENTS.md § Prose + tone / hard constraint 4. Not re-dumped here.

What recon keeps / clobbers

Path	Import	Put-history	Join (`-s ours`)
Paths in `FORK_PATHS` (AGENTS, RESIDUAL, FORK, `docs/upstream-*`, `crates/codegen/grok-nix-helper`, `.grok/workflows`, `.agents/skills`, `doc/dev`, `flake.nix`, `flake/`, ...)	Restored from base; post-restore `assert-process-pins`	Via cherry-picks	Tip tree kept
Product commits after seed	N/A (tree = xAI + restore)	Cherry-picked onto tip	Tip tree kept
Paths not in `FORK_PATHS` and absent from xAI	Dropped	Only if stacked	Cannot backfill missing
Shared user-guide / crate seams	xAI base	Conflict resolve	Tip tree only
Host `~/.agents/skills`, `~/.grok/AGENTS.md`	Untouched	Untouched	Untouched
`rust-toolchain.toml`	Not in `FORK_PATHS`; import can take upstream's file	Only if stacked	Tip tree only

Assert: grok-nix-helper assert-process-pins or just upstream-assert-process-pins. That command proves files exist. It does not prove product contracts inside xai-grok-*. Detail: doc/dev/research/fork-paths-hardening-2026-07-24.md, doc/dev/research/skills-survive-upstream-recon-2026-07-24.md, docs/upstream-history.md.

Novel Surmount crates use the grok-* prefix (example: grok-rate-limit). Upstream crate paths stay xai-grok-* for mergeability.

How to defend a seam on the next merge

A restack-droppable seam is not defended by a FORK checkbox. Defense is four things that stay aligned:

FORK line: one complete sentence in this inventory with the named fn and crate (or an explicit “shipped in code, no named test” / “file pin only” label).
Named cargo test: a fn that goes red if the seam is deleted.
Catalog row: enroll the filter in doc/dev/upstream-regression-filters.md. Recon agents walk these classes. The process improver owns that catalog and the assert / git-recon wiring.
Cherry-pick: product seams inside xai-grok-* survive onto only via cherry-pick plus those tests.

Import restores docs and scripts only (FORK_PATHS). It does not restore crate tests. grok-nix-helper assert-process-pins proves files exist. It does not prove contracts. just check cannot fail a deleted catalog test. A chrome-only inventory is a failed land. Paint-only bubble copy is a failed land. Reintroducing non-excepted Python under product skills is a failed land.

Land checklist (after put-history / onto / import / join)

Do not claim "Surmount seams survived" until this list is done. just check is quality only. It cannot fail a deleted catalog test.

Named tests are contracts (pinned 2026-08-25)

A named cargo fn is intended product behavior. Do not reshape asserts to match code. Do not skip Nix-sandbox S3, MCP, or bwrap tests to go green. Hermeticity fixes keep that contract: PATH includes bash, $GROK_HOME is writable, TLS uses webpki roots when the OS store is empty, bwrap placeholders exist without dropping deny binds, and grok argv0 fixtures work on Nix coreutils (a multi-call binary). Land proof is those named fns below, not a skipped subset. After compact, standing Surmount law is the first section of the post-compaction <system-reminder>, not a buried AGENTS.md paragraph. Process: AGENTS.md hard constraint 15.

The operator's words are the spec (pinned 2026-09-01). A named cargo fn encodes the operator's named contract, not a weaker paraphrase of what they probably meant. Repeating the same prompt three times (tell, then after nonsense, then verbatim because the build still does not match) is a failed land of that contract, not a reason to hold the operator's hand. Observed red, then product so the same test passes. Do not fit the test to the code. Tests are Surmount contracts. Keep the stronger assert. Adjacent to § Hunter's razor; it does not replace it. Dual-pin: AGENTS.md § The operator's words are the spec (hard constraint 23).

Wasted human time (pinned 2026-09-01). A dropped operator prompt is a product defect. Repeating because the harness lost the text is an engineering miss. The durability path is prompt_wal.jsonl. Enroll named WAL tests in the catalog when they exist. Do not document /rebuild WAL preservation as shipped while that file is absent. Operator-verified known good (2026-09-02) for named tests that encode live send, rebuild-flush, interject, and plan-notes appends, because live session files contained those kinds. Catalog: doc/dev/upstream-regression-filters.md § Prompt write-ahead log. Queue enqueue is still a named contract; do not mark it known good from that date. Restore and skip tests stay contracts. Do not delete or weaken those tests in recon, onto, import, or join. Adjacent to this paragraph, Named tests are contracts, lost-prompt, and § Hunter's razor; it does not replace them. Dual-pin: AGENTS.md § Wasted human time (hard constraint 24).

Rules (not product class numbers):

FORK_PATHS restore is docs and scripts only. Product seams inside xai-grok-* survive onto only via cherry-pick plus cargo tests. grok-nix-helper assert-process-pins proves files exist. It does not prove contracts.
A chrome-only inventory is a failed land. Paint screenshots of rails and four idle plan CTAs do not prove hop keys, /spend ingest, unread config, first-token grok-oss, last-session, or skills-not-Python.
Paint-only bubble copy is a failed land. Click-to-copy tests must still exist.
Product skills reintroduced as a Python runtime is a failed land.
Catalog hook (process improver): recon agents walk these classes in doc/dev/upstream-regression-filters.md. A sibling name-existence check (not this file, not REQUIRED_FILES) may later fail if a required-land identifier has no matching fn. Path assert stays files-only.

Steps (procedure; do not mix these into the 1-7 product count):

Run just upstream-assert-process-pins (or grok-nix-helper assert-process-pins HEAD). Files and light sniffs only.
Run the named cargo filters for the seven product classes below, plus the extra proven restack-droppable classes. Use existing test names. Do not invent a filter that is not in the tree. Do not list an identifier that has no matching fn.
rg each required identifier for a matching fn. A named filter with no matching fn is a failed land.
Helper-green is a failed land. Forbidden as proof: a --version test that only checks stdout contains the substring grok; catalog-exists without paint; schema-exists without /spend ingest; serde hide_header without a /settings row and a runtime reader; rank helpers without sampling_config hop keys; bundle still has memory.py.
Dogfood screenshots (rails, four idle plan CTAs, compact included SuperGrok period limits meter, SIGUSR1 after a failed install) stay an operator check after those fns exist. They are not the only check. This inventory does not claim live TUI dogfood.

Seven product classes (must match the catalog; each proven by a named cargo fn):

CLI identity. The product command is grok-oss. grok-oss --version first token is grok-oss, not bare grok. Resume and relaunch hints are grok-oss --resume. Welcome / tutorial badges say Grok OSS.
Config is a surface, not a field. A toml field that deserializes is not shipped if /settings has no row and no runtime reader. Restack lost unread keys (hide_header, always-expand thinking, plan park, worktrees, ASCII scrub at launch, bubble copy) and leftover /settings rows plus DOGE in the theme picker.
Token Economy ledger /spend (extra SQL, not SuperGrok dollar credits). $GROK_HOME/grok_oss.db is the Token Economy ledger, not the session store. Schema v1 surviving is not enough. /spend must ingest usage.jsonl and write reconciliation_run (not DoubleEntryReport::default()).
DOGE / Surmount chrome. A theme file existing is not paint. Land must keep paint/render tests for human green rails plus box caret, magenta model / running agent, the compact included SuperGrok period limits meter, the titled composer frame (prompt_border_active white, yellow title only), and the four-CTA idle plan panel (Clarify only after Comment).
Dual-auth hop after included SuperGrok period limits are full. Rank helpers are not hop. sampling_config must fill console failover after those included limits are full, and must omit it while they still have room. Includes personal SuperGrok JWT as the paying identity while that login exists and personal included SuperGrok period limits have room (Team JWT omitted; that JWT settles Billing Credits). Operators switch SuperGrok identity with use-personal / use-business on $GROK_HOME/limits_pins.json. No new [auth] keys. Stock preferred_method = "api_key" still pins console. Also: any stored SuperGrok login with included remaining before SuperGrok dollar credits, sibling included before SuperGrok dollar credits, and the one-process hourly limits flock (HonorTtl at most once an hour per machine; ForceRefresh still fetches). Do not flatten remaining to zero from usage percent 100 plus missing SuperGrok Heavy. Never invent used-up included SuperGrok period limits. Fail-open: a client 100% / remaining 0 / SuperGrok dollar credits $0 printout must not mark SuperGrok used up or hop to console. Real SuperGrok HTTP 402 after that request failed can still leave SuperGrok. SuperGrok Heavy ranking optional label is not this class. SuperGrok is paid.
Last-session on start. Interactive grok-oss opens the remembered last session for this working directory. It does not land on Welcome first.
Product skills are not a Python runtime. Tool work is a named Rust function, an ACP tool, or a shipped CLI bin of that function. Skills must not generate arbitrary Python or Bash payloads and then exec them. A restack that installs non-excepted Python under product skills, that drops the Rust intercept for the allowlisted stub names memory.py / validate-plan.py / session_reader.py, or that drops the CLI bins grok-oss-implement-memory / grok-oss-plan-validate / grok-oss-session-reader, is a failed land. grok-oss intercepts those stub names and bins to Rust. Grok Build compatibility is those bins, not a second Python runtime. Office/docx/pptx/xlsx/pdf scripts and those three allowlisted stub names are the only exceptions. Host ~/.agents/skills is operator-owned and is not this class. User-guide 08-skills.md must keep that sentence. grok-oss sqlite session/work ids are ULIDs; UUID stays the Grok Build / ACP wire id.

After restack the required classes are all seven above: CLI branding, /settings plus unread config, Token Economy ledger /spend, DOGE/chrome paint, dual-auth hop after included SuperGrok period limits are full, last-session on start, and product skills are not a Python runtime.

Extra proven restack-droppable classes (named cargo tests exist; a land that drops them while keeping the seven is still a seam loss):

Official serving-path fingerprints (Surmount persist + /metadata; upstream Chat Completions system_fingerprint JSON). Named tests: show_session_metadata_includes_fingerprint_fields_from_stored_samples, parse_language_models_json_reads_id_fingerprint_version_created, record_completion_fingerprint_persists_a_flip, user_guide_metadata_documents_serving_fingerprints. Schema v7 tables must not drop /spend v1 (migrate_v6_file_to_v7_adds_serving_tables_without_dropping_spend).
Always-on bubble copy click + wrap (paint-only is a failed land).
Plan present ≠ Approve + modal-free typing (four-CTA idle paint is not honesty).
Lost-prompt integration tests are fork-owned contracts. Clickable Approve must not drop the Operator-box prompt. Empty Enter on Revise is not proof of mouse Approve. When those tests change, keep the stronger assert; synthesize if upstream and Surmount both have a piece; never fit the contract to a wipe. Named tests (plan_approve_lost_prompt): isolated_present_preview_click_approve_does_not_drop_human_box_prompt, isolated_present_preview_typed_after_present_click_approve_sends_human_box_prompt, isolated_present_prompt_focus_click_approve_does_not_drop_human_box_prompt, isolated_present_click_approve_dispatches_interject_with_prompt_text, isolated_present_preview_enter_is_human_turn_then_click_approve, isolated_preview_idle_non_empty_operator_paste_enter_approves_with_notes_not_plan_exit, isolated_preview_idle_leftover_slash_plus_notes_click_approve_is_approve_with_comment, isolated_preview_vanished_pane_notes_enter_approves_with_comment, isolated_preview_idle_leftover_slash_plus_notes_enter_approves_with_comment, isolated_preview_approve_with_plan_composer_notes_submits_with_approve_not_as_prompt, isolated_preview_stays_after_present_so_comment_then_approve_can_run, isolated_preview_comment_cta_then_notes_then_approve_submits_with_approve_not_as_prompt, view_plan_reopens_isolated_preview_from_current_disk_plan_md_after_panel_closed, isolated_preview_human_send_closes_leftover_present_after_mill_continues, isolated_preview_implement_closes_leftover_present_after_mill_continues, isolated_preview_rereads_current_disk_plan_md_when_mill_rewrote_it, isolated_preview_after_mill_completion_must_not_paint_leftover_present_or_tech_md, isolated_preview_second_plan_prompt_must_not_paint_stale_plan_as_live_present, user_guide_isolated_preview_rewrite_wait_on_second_plan_prompt.
/rebuild SHA-aware peer relaunch (fail-does-not-signal is not enough). Installed identity git SHA must match this workspace HEAD short SHA. TUI /rebuild starts from the session workspace. Named tests: rebuild_must_exec_workspace_binary_not_stale_cargo_bin, installed_identity_must_match_workspace_git_sha, tui_rebuild_starts_from_session_workspace_not_process_cwd.
/rebuild SIGUSR1s every other live grok-oss TUI PID (dedupe by PID; two windows on the same session both get a signal). SHA-aware fail-does-not-signal is not this list. Named tests: rebuild_signals_each_pid_after_composite_key, peer_pids_to_signal_excludes_self_dead_and_non_grok (xai-grok-update --lib).
/rebuild TUI persist like a network interrupt (fork-owned drafts, queue, plan notes, WAL, and nested ids in this TUI). Named tests: handle_rebuild_done_persists_unsent_composer_draft_and_session_load_restores_it, handle_rebuild_done_persists_pending_prompts_including_interject_and_session_load_restores_them, handle_rebuild_done_persists_plan_feedback_draft_and_plan_md, handle_rebuild_done_keeps_nested_subagents_for_resume, rebuild_and_relaunch_starts_while_nested_subagents_are_running, operator_ran_rebuild_and_the_grok_oss_process_did_not_restart, export_git_index_omits_unstaged_dirty_file, stash_keep_index_hides_unstaged_wip_from_compile_worktree. Unstaged WIP is not the compile source. Do not weaken to an upstream nested-cancel. Prompt WAL: prompt_wal_appends_on_enter_before_model_wait, prompt_wal_appends_on_mid_turn_interject, prompt_wal_appends_on_queue_enqueue, prompt_wal_appends_on_approve_notes, session_load_restores_wal_send_missing_from_prompt_history. After --resume / last-session restore, the operator prompt appears once (not composer plus queue #1), Enter is send unless a live sampler turn is running, and Waiting is a real sampler wait. Named tests: resume_restore_must_not_put_the_same_operator_prompt_in_composer_and_queue, resume_restore_must_not_arm_enter_interject_when_no_live_sampler_turn, resume_restore_must_not_show_waiting_when_nested_and_sampler_are_gone, resume_restore_must_not_rehydrate_unsent_draft_and_queue_with_the_same_string, post_rebuild_relaunch_chrome_includes_grok_oss_version_and_git_sha, restore_pending_prompts_from_disk_drops_human_turns_when_memory_queue_is_nonempty. Leader RelaunchForUpdate keeps nested ids on that leader the same way a TUI disconnect does, and keeps this process up while the parent turn is still busy (no five-second cap). Named tests: relaunch_drain_keeps_nested_ids_alive_after_grace_like_disconnect, relaunch_drain_keeps_parent_turn_until_idle_like_disconnect (xai-grok-shell --lib), rebuild_subcommand_parses (xai-grok-pager --lib). The prompt write-ahead log (prompt_wal.jsonl) is the durability path for a dropped operator prompt. Enroll named WAL tests in this extra class when they exist. Do not list a WAL fn that is not in the tree. Operator-verified known good (2026-09-02) for send, rebuild-flush, interject, and plan-notes append tests named in doc/dev/upstream-regression-filters.md § Prompt write-ahead log. Queue enqueue is not that mark. Restore tests stay contracts. Do not delete or weaken those tests in recon.
Interject Ctrl+Enter and Send now are fork-owned. Mid-turn Ctrl+Enter interjects when appropriate and otherwise inserts a newline. Queue [Send now] on a plain prompt row dispatches SendInterject via Action::Interject. A queued /goal row is GoalSet via SendPromptNow. Grok OSS 1.0.3 is not last-known-good. WAL known-good for send / rebuild-flush / interject / plan-notes appends is a separate contract and does not prove live Interject UI. Named tests: ctrl_enter_mid_turn_dispatches_send_interject, queue_send_now_click_dispatches_send_interject, empty_ctrl_enter_mid_turn_does_not_send, enter_while_other_work_is_live_must_still_clear_composer, queued_goal_send_now_is_goal_action_not_stuck_composer_string, header_timeout_is_named_cold_start_class_with_retry_path, limits_help_lists_named_words_and_hyphenated_aliases, interject_does_not_wait_minutes_or_block_paint, enter_soft_interject_must_not_leave_duplicate_prompt_in_composer, enter_on_pasted_15_lines_chip_sends_or_interjects_does_not_only_expand, l2_overlay_enter_interject_must_not_leave_duplicate_prompt_in_composer, enter_send_must_not_leave_duplicate_prompt_in_composer, enter_at_end_of_last_composer_line_must_submit_immediately_not_silent_newline, enter_at_end_of_last_composer_line_mid_turn_must_interject_immediately_not_silent_newline, arrow_keys_then_enter_must_submit_the_same_body_not_a_different_path. Keep prompt_wal_appends_on_mid_turn_interject.
TUI performance contracts are fork-owned. They are not last-known-good until typing, cancel, and interject stay responsive. Hang/cancel, Interject Send now, WAL, and queue-snapshot tests are in the tree. The live TUI may still be 1.0.3. Do not treat 1.0.3 as last-known-good. Persist: pending_prompts_queue_snapshot_skips_sync_all, pending_prompts::tests::write_without_fsync_still_roundtrips, plan_human_box_keystroke_burst_does_not_append_prompt_wal, main_composer_keystroke_burst_does_not_append_prompt_wal. Existing debounce stays a contract: plan_human_box_keystroke_burst_does_not_flush_unsent_draft_every_char, main_composer_keystroke_burst_does_not_flush_unsent_draft_every_char, keystroke_burst_does_not_flush_unsent_draft_every_char. Paint: idle_plan_overlay_does_not_demand_fast_ticks, plan_overlay_repeat_prepare_at_same_width_does_not_rebuild_markdown. Cancel and interject: cancel_does_not_wait_minutes, interject_does_not_wait_minutes_or_block_paint. Catalog: doc/dev/upstream-regression-filters.md § TUI performance. Do not delete or weaken image-token, lost-prompt, Operator/Agent, WAL append, or /rebuild persist tests.
Compact / summarize / turn HTTP image_url must be a base64 data URL or an http(s) URL. A local session asset path, a file:// handle, an [Image #N] token, or an empty value must not reach the API (invalid_image). Compact still strips user images to [image] so it does not re-inline the data URL crate. Leftover Image parts are converted or omitted on the request clone; stored chat_history.jsonl is not rewritten. An invalid_image retry must drop only non-API urls and keep valid data URL siblings. Named tests: compact_request_must_not_send_session_asset_path_or_image_token_as_image_url, repair_encodes_raw_session_asset_path_as_data_url, path_image_token_and_empty_are_not_api_image_urls, invalid_image_retry_drops_path_shaped_urls_and_keeps_valid_data_url. Catalog: doc/dev/upstream-regression-filters.md § Compact image_url. Do not delete or weaken image-token, lost-prompt, Operator/Agent, WAL append, or /rebuild persist tests.
Nucleo reuse-per-root.
Baked default is Grok 4.6 at medium reasoning effort (baked_default_is_grok_46_medium_fork_contract). Fork contract change.
Soft plan present is a real right-side pane (not a 75% centered overlay). Named tests: plan_soft_park_docks_right_not_centered_overlay, plan_soft_park_draw_right_pane_matches_side_panel_status, plan_row_click_does_not_enter_commenting, plan_loop_status_does_not_claim_side_panel_when_viewer_closed. Idle parked plan must not spin the 30fps loop, and same-width paints must not re-scan a 240k plan body (idle_plan_overlay_does_not_demand_fast_ticks, plan_overlay_repeat_prepare_at_same_width_does_not_rebuild_markdown).
Plan-review and Linux prompt screenshot paste (event_paste_plan_commenting_empty_defers_clipboard_image_probe, plan_feedback_ctrl_v_defers_clipboard_image_probe, agent_empty_bracketed_paste_defers_probe_for_clipboard_image, approve_or_revise_drains_plan_composer_images).
Live chrome names SuperGrok dollar credits, not a nickname (compact_status_supergrok_on_dollar_credits_shows_dollars_not_free_period_pct, format_supergrok_session_with_weekly_and_dollar_credits).
No two live same-description Subagent rows; unlimited retry is not a u32::MAX fraction (live_subagent_list_does_not_show_two_rows_with_the_same_description, task_spawn_rejects_or_replaces_second_live_same_description, format_activity_label_unlimited_retry_has_no_u32_max_fraction, implement_effort_two_does_not_spawn_two_review_rows_unless_operator_asked).
from_config no-prefetch usable catalog (from_config_without_prefetch_produces_usable_catalog). Empty models_cache.json miss is not cargo-proven.
Seeded custom model on session/load stays Chat Completions (keep_unverified_persisted_model_keeps_seeded_custom_slug, seeded_test_model_keeps_chat_completions_backend, poisoned_image_session_recovers_within_the_failing_turn).
Always-three-layer product prompt (child_task_description_is_concise, default_max_allows_l2_to_spawn_l3).
/goal parent coordinates (Surmount fork of the injected prompt vs upstream "Deliver everything yourself"): goal_instruction_parent_coordinates_and_l2_must_spawn_l3_for_tools (xai-grok-tools-api slash_commands.rs). Keep goal_instruction_carries_objective_and_contract_tokens. Live templates: goal_rules_templates_parent_coordinates_and_l2_must_spawn_l3_for_tools, goal_task_discipline_parent_spawns_l2_not_product_tools (xai-grok-shell).
Parent fire-and-return spawn (Surmount / grok-oss fork): a nested L2 that is a long builder must not occupy the parent as a blocking 10-minute get_command_or_subagent_output wait. Parent starts it, keeps working, completion is a notification. Parent can spawn a second L2 while the first is still running. Named fn: parent_spawn_subagent_second_l2_while_first_still_running_without_wait (xai-tool-types task.rs and xai-grok-tools task/backend_tests.rs).
Parent follow-up onto a running nested L2 (Surmount / grok-oss fork, GitHub #143): enqueue additive work on a live L2 without kill or respawn; do not inject a live L3 unless targeted; resume_from stays completed-only; off ([subagents] parent_follow_up = false) is SpaceXAI spawn / wait / resume_from after exit. No new [auth] key. Named fns: parent_cannot_talk_to_own_l2s_follow_up_enqueues_interject_on_running_l2_without_kill_or_respawn, parent_follow_up_does_not_inject_into_live_l3_unless_operator_targeted_that_specialist, resume_from_of_running_l2_still_fails_active, parent_follow_up_off_is_upstream_spawn_wait_resume_from_completed_only, parent_follow_up_onto_running_l2_with_live_l3_hits_l2_not_l3 (xai-grok-tools task/parent_follow_up_tests.rs). TaskTool::run: parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_returns_queued_and_does_not_spawn, parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_and_resume_from_are_mutually_exclusive (xai-grok-tools task/mod.rs). Schema: parent_cannot_talk_to_own_l2s_follow_up_field_is_optional_and_distinct_from_resume_from (xai-tool-types task.rs). Shell Interject: shell_child_follow_up_sends_session_command_interject_on_child_session (xai-grok-shell agent/subagent/tests/mod.rs). Config: subagents_config_parent_follow_up_false_parses_and_omitted_defaults_true, resolve_subagents_copies_parent_follow_up (xai-grok-shell config/tests.rs). KEEP parent_spawn_subagent_second_l2_while_first_still_running_without_wait, l2_overlay_send_prompt_interjects_l2_not_l1, l3_overlay_send_prompt_does_not_reach_l3_or_l1, nested_spawner_can_resume_from_completed_reparented_child.
Compact standing-law reminder (Surmount / grok-oss fork): after compact, standing Surmount law is the first <system-reminder> section, not a buried AGENTS.md paragraph and not /recap. Upstream parent turns often sit on a 10-minute poll wait. Surmount is fire-and-return for long builder L2s, and that wait/discovery law is injected here. Named fn: post_compact_reminder_includes_surmount_standing_law (xai-grok-shell compaction_context.rs section_surmount_standing_law_after_compact).
CoT death spiral (GitHub #133): DEST_ENCODER_SKIP_LOOP, StreamRepetitionGuard, Fatal RepetitiveGeneration, compact 8192 / 32768. Oh My Pi comparison: this tree has no Oh My Pi checkout; do not invent internals. Surmount vs SpaceXAI as in Product inventory. Named fns: dest_encoder_skip_loop_is_repetitive, dest_encoder_skip_single_sentence_four_times_is_repetitive, thought_line_loop_is_repetitive, chat_completions_stops_dest_encoder_skip_loop, chat_completions_stops_dest_encoder_skip_loop_in_thought, messages_stops_dest_encoder_skip_loop, responses_stops_dest_encoder_skip_loop, classify_repetitive_generation_is_fatal, compaction_reseed_of_unique_75k_history_must_not_leave_wasteful_75k_context, compact_summary_budget_is_8192_tokens_and_reseed_reserve_is_32768.
File-level infer-from-path verify after ACP structured edits (rustfmt_argv_edition_2024_config_and_absolute_files, clippy_argv_lints_the_edited_file_not_crate_lib, clippy_argv_is_file_level_not_package_lib, dangerous_cargo_clippy_package_all_targets_is_refused_and_does_not_spawn_shell). A restack that drops util/rust_edit_verify.rs or these tests is a failed land. Not one of the seven numbered classes.
ACP per-path write lock after structured edits (try_acquire_write, try_acquire_read, write_paths, CoW published / published_cow_snapshot, held(), share is allowed; two_agents_cannot_write_the_same_path_at_once, search_replace_apply_patch_and_write_all_take_the_lock, held_path_error_names_holder_and_file_without_a_steal_skip_wait_menu, opencode_edit_cannot_write_a_path_another_agent_already_holds, hashline_edit_refuses_when_another_agent_holds_the_path, hashline_edit_happy_path_does_not_mention_the_lock, sequential_writes_succeed_after_the_first_tool_call_returns_even_when_both_agents_were_assigned_the_same_write_paths, spawn_write_paths_overlap_is_a_soft_assignment_not_a_spawn_error, soft_lock_reminder_is_observable_on_a_sibling_tool_call, after_write_returns_held_is_empty_lock_must_be_released, reader_during_held_write_gets_published_pre_write_bytes_current_atomic_snapshot, two_live_agents_with_the_same_write_paths_spawn_without_error_l2_and_l3_may_be_assigned_the_same_file). A restack that drops per_path_write_lock.rs, the OpenCode edit lock acquire, the hashline_edit lock acquire, or these tests is a failed land. Not one of the seven numbered classes.
Pause / resume chips and Clear finished quiet paint.
User-guide cargo pins beyond skills + resume (user_guide_operator_cli_examples_use_grok_oss, user_guide_does_not_claim_automatic_host_hop_is_unshipped, user_guide_names_token_economy_spend_order, user_guide_limits_names_fail_open_and_named_commands).
L1 Subagents list is L2-only plus a live L3 count (live_subagent_list_shows_only_l2_and_reports_live_l3_count, l2_row_shows_live_l3_count_not_specialist_names).
Live Subagents list is still-running only; already_exited dismisses the paused Implementer overlay (finished, already_exited, Occupied skip, retain_still_running_nested_occupancy, listed_live_subagents; kill_already_exited_dismisses_paused_implementer_overlay, restore_nested_occupancy_does_not_unfinish_or_revive_dead_host, running_count_matches_listed_live_l2_not_l3, kill_already_completed_drops_live_list_responding_and_still_running_cue).
Compacting Subagents row [↗] still opens (open_subagent_fullscreen versus AutoCompactStarted auto-steal; click_tasks_open_on_compacting_row_opens_subagent, click_tasks_open_on_last_painted_row_opens_subagent, click_tasks_kill_on_compacting_row_emits_kill, open_subagent_fullscreen_sets_active_while_child_is_auto_compacting).
Ctrl+C two-stage, /model last Tab, Isolated Preview glass search, Isolated Preview screenshot paste (GNOME All Markup Copy is an image). Tests: isolated_preview_handle_input_ctrl_c_with_text_clears_and_stays, unique_model_slash_tab_switches_now_empty_composer_no_send, isolated_preview_search_query_plan_matches_plan_and_plan, isolated_preview_gnome_all_markup_copy_title_with_raster_is_image_chip.
Turbo planning (effective_reasoning_effort, live_plan_turn, model_effort_chrome_line, stamp_request_effort). Live exclusive /plan and Isolated Preview /plan --soft request xhigh while turbo planning is on (default on). Only the lower-right yellow model/effort line shows xhigh. Magenta model id stays the model id. No TURBO badge, banner, or toast. Stored session /effort is not mutated. Off is the upstream/SpaceXAI option: plan turns stay at session effort. Tests: session_medium_enter_plan_request_uses_xhigh_and_lower_right_shows_xhigh, exit_or_approve_plan_returns_session_medium_effort, turbo_planning_settings_off_plan_turn_stays_session_medium.
Soft process-rule reminders (settings list; spawn still succeeds): process_rule_reminder_configured_third_l2_still_spawns, process_rule_reminder_text_in_nested_spawn_prompt, process_rule_reminders_off_nested_spawn_has_no_extra_reminder_text. Off or empty list is the upstream option.
/start plus leftover cancel-resume marker drop (start_while_globally_paused_continues_interrupted_turn_once, start_on_idle_clean_session_does_not_invent_a_turn, start_with_cancel_resume_marker_continues_interrupted_turn, handle_rebuild_done_must_not_cancel_parent_so_session_load_adopts_like_disconnect, handle_rebuild_done_mid_turn_writes_cancel_resume_and_session_load_continues_the_turn, handle_rebuild_done_idle_completed_turn_does_not_write_cancel_resume_or_refire_last_prompt, session_load_drops_stale_cancel_resume_marker_when_primary_turn_finished_successfully).
/unstick shell skip-append, hung-task orphan, leader hung-RPC drop, and WAL image resource links (unstick_retry_does_not_append_second_user_query_when_last_turn_matches, unstick_retry_orphans_stuck_running_task_then_samples_again, unstick_leader_drops_hung_session_prompt_like_disconnected_client, unstick_resends_wal_images_as_resource_blocks_not_data_urls).
ForceRefresh on explicit /limits (management_meter_cache_policy_collect_force_background_honor_ttl, should_clear_management_meter_caches_force_with_key_only, limits_snapshot_mode_for_get_billing_explicit_is_force_refresh, limits_snapshot_force_refresh_leader_http_fetches_when_snapshot_is_younger_than_one_hour).
Footer / session sampling window vs catalog (context_chip_names_sampling_window_when_catalog_differs, context_chip_hover_percent_uses_sampling_window_when_catalog_differs, footer_chip_uses_session_sampling_window_when_economic_cache_is_off, refresh_context_used_does_not_copy_catalog_into_session_sampling, main_session_sampling_window_is_catalog_500k_even_when_economic_is_on, nested_session_sampling_window_stays_200k_when_catalog_is_500k).
Spawn-prompt fold plus last-answer caps (huge_spawn_prompt_becomes_pointer_with_description_and_report, parent_estimated_tokens_omit_huge_spawn_prompt, to_model_text_caps_huge_last_answer_for_parent_ingest, completed_subagent_task_output_is_capped_or_points_at_report, blocking_spawn_subagent_completed_to_prompt_format_is_capped).
Any stored SuperGrok included remaining before SuperGrok dollar credits; do not flatten remaining from usage percent 100 plus missing SuperGrok Heavy (sampling_config_hop_team_remaining_personal_exhausted_not_dollars_or_console, sampling_config_hop_personal_remaining_team_exhausted, sampling_config_hop_both_remaining_team_first_then_personal, sampling_config_hop_both_included_exhausted_dollar_credits_before_console, sampling_config_hop_missing_heavy_false_100_keeps_sibling_included, sampling_config_hop_dollar_credits_on_both_missing_heavy_keeps_team, prepare_sampler_for_turn_does_not_flatten_missing_heavy_100_off_sibling, prepare_sampler_for_turn_does_not_flatten_dollar_credits_on_both). Rank hop_* helpers are still not hop.

Not a cargo land class: rustc 1.98.0 (file pin only; rust-toolchain.toml not in FORK_PATHS). Stuck-retry pager chrome is not fully proven. Token Economy /settings table rows were not re-proven on 2026-08-15. CLI grok-oss rebuild is clap-wired (rebuild_subcommand_parses). /economic-mode is not a live BuiltinAction. SuperGrok Heavy ranking optional label is not implemented. Empty models_cache.json miss has no named test. Live hop / live Business remaining / live TUI dogfood are unknown.

Upstream regression filters

Process pins survive import via FORK_PATHS restore + assert-process-pins (path presence and light content sniffs). That gate does not prove product behavior inside shared xai-grok-* crates.

Product seams live inside those crates. They survive onto only through cherry-picks / conflict resolve and stay honest through named cargo tests. After recon, run the assert, then the seven-class land checklist, then the name-existence check. just check cannot fail a deleted catalog test. Deleting a red catalog test is not a restore. Paint is one of seven land classes, not the whole land.

Full filter catalog (why each exists + every residual Validate honesty block): doc/dev/upstream-regression-filters.md. Open residual still points at the same commands under RESIDUAL § Validate honesty (D0 can demote; the catalog is durable).

Operator cheat sheet (post-import / post-onto tip). rg each identifier for a matching fn first:

just upstream-assert-process-pins
grok-nix-helper assert-process-pins HEAD   # or onto tip

# 1. CLI identity (first token grok-oss; substring "grok" is not enough)
cargo test -p xai-grok-pager --lib -- product_version_line_uses_grok_oss_not_bare_grok \
  resume_session_command_uses_grok_oss user_guide_resume_and_version_examples_use_grok_oss \
  product_cli_name_is_grok_oss print_exit_resume_hint_writes_expected_lines \
  user_guide_operator_cli_examples_use_grok_oss welcome_badge_brands_grok_oss \
  hero_subtitle_brands_grok_oss tutorial_list_title_brands_grok_oss
cargo test -p xai-grok-pager-bin --test version_without_tty

# 2. Config is a surface (/settings rows + readers + DOGE picker; serde-only is not enough)
cargo test -p xai-grok-pager --test settings_e2e -- hide_header always_expand_thinking \
  scrub_ascii_punct allow_worktree bubble_copy_buttons plan_approval_park
cargo test -p xai-grok-pager --lib -- theme_choices_include_doge_and_default_is_doge \
  hide_header_zeroes always_expand_thinking ctrl_t_expand_is_default \
  ctrl_t_collapse_is_default \
  bubble_copy_buttons_on append_bubble_copy_button_paints \
  clicking_human_bubble_copy clicking_assistant_bubble_copy \
  clicking_wide_human_bubble_copy
cargo test -p xai-grok-pager-render --lib -- prime_applies_scrub_ascii_punct_from_ui \
  prime_applies_always_expand_thinking_from_ui
cargo test -p xai-grok-shell --lib -- resolve_subagents_copies_allow_worktree

# 3. Token Economy ledger /spend (schema-only is not enough; extra SQL, not SuperGrok dollar credits)
cargo test -p xai-grok-shell --lib -- spend_path_ingests_usage_jsonl_and_records_reconciliation
cargo test -p xai-grok-pager --lib -- show_spend_ingests_usage_jsonl_and_is_not_empty_default

# 4. DOGE / Surmount chrome (theme file existing is not paint)
cargo test -p xai-grok-pager-render --lib -- default_theme_is_doge resolve_from_config_no_config \
  doge_accent_user_is_pure_green doge_accent_system_is_pure_cyan \
  as_doge_human_green_named_ansi_is_rgb_0_255_0 osc12_named_ansi_green_is_doge_rgb_0_255_0
cargo test -p xai-grok-pager --lib -- user_prompt_block_accent user_prompt_entry_renderer_paints_green_rail \
  paint_composer_box_cursor_uses_human focused_composer_paints_human_green_box_caret \
  doge_human_box_caret_plate_is_rgb_0_255_0 paint_composer_box_cursor_named_ansi_green_becomes_doge_rgb \
  agent_message_block_accent info_line_model_name_uses_accent_model \
  status_bar_pushes_credits_compact_included_supergrok_period_limits \
  hit_credits_click_dispatches_show_limits \
  titled_doge_composer_frame_is_prompt_border_not_context_yellow \
  plan_approval_footer_paints_five_cta_vocabulary \
  auto_compact_completed_preserves_todo_board \
  todo_badge_names_tasks_not_only_fraction \
  status_header_todo_badge_names_tasks \
  nested_l2_overlay_todo_toggle_stays_findable \
  forked_session_status_header_paints_switcher_and_dashboard \
  forked_session_status_header_clicks_open_dashboard_and_cycle \
  load_session_restores_fork_family_from_disk

# 5. Dual-auth hop after included SuperGrok period limits are full (rank helpers are not hop)
cargo test -p xai-grok-shell --lib -- sampling_config_auto_use \
  sampling_config_hops_to_sibling_included_before_dollar_credits \
  afterburner_does_not_skip_mark_when_sibling_has_included_remaining \
  resolve_model_to_sampling_config_auto_use \
  align_after_billing_switches_sticky_personal_full_to_business_included \
  prepare_sampler_for_turn_aligns_to_ranked_included_primary \
  combined_included_remaining_sums_distinct_personal_and_business_pools \
  combined_included_remaining_does_not_double_count_unified_pool \
  combined_included_remaining_does_not_collapse_matching_percent_and_reset_into_one_pool \
  pick_prefers_business_included_before_personal_when_both_have_remaining \
  order_credentials_business_included_before_personal_when_both_have_room \
  limits_snapshot_second_process_within_the_hour_does_not_http \
  limits_snapshot_honor_ttl_fresh_within_hour_does_not_http \
  limits_snapshot_force_refresh_leader_http_fetches_when_snapshot_is_younger_than_one_hour \
  limits_snapshot_stale_file_lets_waiter_become_leader_and_fetch_once \
  limits_snapshot_never_writes_access_tokens \
  billing_handler_uses_snapshot_hub_instead_of_unconditional_sibling_http \
  personal_included_period_limits_reset_uses_personal_supergrok_not_leftover_business_credits \
  business_with_no_period_limits_payload_still_switchable_via_use_business \
  use_personal_switches_back_from_business_pin
cargo test -p xai-grok-pager --lib -- compact_meter_stays_included_while_sibling_pool_has_remaining \
  active_spend_driver_stays_included_while_any_distinct_pool_has_remaining \
  matching_percent_and_reset_does_not_collapse_combined_remaining_into_one_pool

# 6. Last-session on start
cargo test -p xai-grok-pager --lib -- materialize_new_auto_opens_last_session_when_one_exists \
  materialize_new_auto_stays_welcome_when_no_last_session \
  materialize_new_auto_does_not_open_last_when_headless \
  from_pager_args_opens_last_session_on_start

# 7. Product skills are not a Python runtime (non-excepted .py or dropped intercept is a failed land)
cargo test -p xai-grok-bundle --lib -- sanitize_rejects_non_excepted_skill_python \
  extract_archive_skips_non_excepted_skill_python \
  product_repo_skill_roots_have_no_non_excepted_python \
  default_product_skills_include_polish_and_subagent \
  default_product_skill_markdown_does_not_tell_agents_to_generate_python_or_bash
cargo test -p xai-grok-pager --lib -- user_guide_skills_are_not_a_python_runtime
cargo test -p xai-grok-tools --lib -- implement_memory_snapshot_intercept_does_not_spawn_shell \
  plan_validate_intercept_does_not_spawn_shell session_reader_list_intercept_does_not_spawn_shell \
  grok_oss_implement_memory_cli_bin_intercept_does_not_spawn_shell \
  generated_python_payload_is_not_skill_stub_intercept

# Extra: plan present != approve + modal-free typing
cargo test -p xai-grok-pager --lib -- exit_plan_mode_present_is_not_operator_approve \
  empty_enter_on_revise_prompt_does_not_approve \
  soft_park_empty_ctrl_c_abandons_plan_approval \
  exit_plan_mode_keeps_mid_compose_draft_and_a_types \
  exit_plan_mode_modal_park_does_not_steal_mid_compose_keys \
  exit_plan_mode_empty_present_printable_goes_to_composer \
  exit_plan_mode_shows_overlay_even_in_yolo
cargo test -p xai-grok-tools --lib -- exit_plan_mode_tool_result_does_not_claim_operator_approval

# Extra: pause / Clear finished (not paint-only)
cargo test -p xai-grok-pager --lib -- work_control_chrome_matrix_pause_not_cancel_stop_not_pause \
  pause_button_click_dispatches_global_pause_not_cancel \
  idle_with_subagents_paints_pause_and_stop_hits \
  global_paused_idle_paints_resume_not_stop \
  clear_finished_action_idle_is_quiet_not_neon_green_or_magenta \
  clear_finished_click_does_not_open_subagent

# Extra: /rebuild SHA-aware (fail-does-not-signal is not enough)
cargo test -p xai-grok-update --lib -- failed_install_must_not_replace_or_signal_peers \
  build_fail_does_not_signal_leaders parse_version_output_extracts_identity \
  peer_relaunch_accepts_same_semver_different_sha \
  peer_relaunch_declines_equal_identity_on_same_path \
  peer_relaunch_accepts_deleted_inode_even_when_identity_equal \
  operator_ran_rebuild_and_the_grok_oss_process_did_not_restart \
  rebuild_must_exec_workspace_binary_not_stale_cargo_bin \
  installed_identity_must_match_workspace_git_sha
cargo test -p xai-grok-pager --lib -- tui_rebuild_starts_from_session_workspace_not_process_cwd
cargo test -p xai-grok-shell --lib -- leader_is_older_than_same_semver_git_sha_identity

# Extra: /rebuild signals every live grok-oss PID (SHA-aware is not this list)
cargo test -p xai-grok-update --lib -- rebuild_signals_each_pid_after_composite_key \
  peer_pids_to_signal_excludes_self_dead_and_non_grok

# Extra: /rebuild TUI persist like a network interrupt (fork-owned)
# Leader drain is not that persist path.
cargo test -p xai-grok-pager --lib -- \
  handle_rebuild_done_must_not_cancel_parent_so_session_load_adopts_like_disconnect \
  handle_rebuild_done_persists_unsent_composer_draft_and_session_load_restores_it \
  handle_rebuild_done_persists_pending_prompts_including_interject_and_session_load_restores_them \
  handle_rebuild_done_persists_plan_feedback_draft_and_plan_md \
  handle_rebuild_done_keeps_nested_subagents_for_resume \
  rebuild_and_relaunch_starts_while_nested_subagents_are_running \
  operator_ran_rebuild_and_the_grok_oss_process_did_not_restart \
  post_rebuild_relaunch_chrome_includes_grok_oss_version_and_git_sha \
  tui_rebuild_starts_from_session_workspace_not_process_cwd \
  restore_pending_prompts_from_disk_drops_human_turns_when_memory_queue_is_nonempty \
  rebuild_subcommand_parses \
  prompt_wal_appends_on_enter_before_model_wait \
  prompt_wal_appends_on_mid_turn_interject \
  prompt_wal_appends_on_queue_enqueue \
  prompt_wal_appends_on_approve_notes \
  ctrl_enter_mid_turn_dispatches_send_interject \
  queue_send_now_click_dispatches_send_interject \
  empty_ctrl_enter_mid_turn_does_not_send \
  enter_soft_interject_must_not_leave_duplicate_prompt_in_composer \
  enter_on_pasted_15_lines_chip_sends_or_interjects_does_not_only_expand \
  l2_overlay_enter_interject_must_not_leave_duplicate_prompt_in_composer \
  enter_send_must_not_leave_duplicate_prompt_in_composer \
  enter_at_end_of_last_composer_line_must_submit_immediately_not_silent_newline \
  enter_at_end_of_last_composer_line_mid_turn_must_interject_immediately_not_silent_newline \
  arrow_keys_then_enter_must_submit_the_same_body_not_a_different_path \
  session_load_restores_wal_send_missing_from_prompt_history
cargo test -p xai-grok-update --lib -- export_git_index_omits_unstaged_dirty_file \
  stash_keep_index_hides_unstaged_wip_from_compile_worktree
cargo test -p xai-grok-shell --lib -- \
  relaunch_drain_keeps_nested_ids_alive_after_grace_like_disconnect \
  relaunch_drain_keeps_parent_turn_until_idle_like_disconnect

# Extra: from_config cold catalog (empty models_cache.json miss is NOT this filter)
cargo test -p xai-grok-shell --lib -- from_config_without_prefetch_produces_usable_catalog

# Extra: session/load keeps seeded custom model on Chat Completions (not last-session on start)
cargo test -p xai-grok-shell --lib -- keep_unverified_persisted_model_keeps_seeded_custom_slug \
  seeded_test_model_keeps_chat_completions_backend
cargo test -p xai-grok-shell --test test_image_strip_recovery -- \
  poisoned_image_session_recovers_within_the_failing_turn

# Extra: nucleo reuse-per-root
cargo test -p xai-grok-workspace --lib -- repeated_open_without_close_keeps_one_search_per_root \
  distinct_roots_each_keep_one_search get_results_does_not_keep_a_stale_search_alive

# Extra: always-three-layer product prompt
cargo test -p xai-grok-agent --lib -- child_task_description_is_concise
cargo test -p xai-grok-tools --lib -- default_max_allows_l2_to_spawn_l3

# Extra: file-level infer-from-path verify (not crate-wide cargo)
cargo test -p xai-grok-tools --lib rust_edit_verify
cargo test -p xai-grok-tools --lib compiler_probe_junk
cargo test -p xai-grok-tools --lib -- rustfmt_argv_edition_2024_config_and_absolute_files \
  clippy_argv_lints_the_edited_file_not_crate_lib \
  clippy_argv_is_file_level_not_package_lib \
  clippy_driver_uses_temp_out_dir_not_the_workspace_root \
  write_refuses_rmeta_at_workspace_root_and_does_not_create_the_file \
  rustc_oneshot_without_out_dir_is_refused_and_does_not_spawn_shell \
  dangerous_cargo_fmt_all_is_refused_and_does_not_spawn_shell \
  dangerous_cargo_clippy_package_all_targets_is_refused_and_does_not_spawn_shell \
  dangerous_cargo_test_package_lib_filter_is_not_refused

# Extra: ACP per-path write lock CoW + share is allowed (GitHub #129)
cargo test -p xai-grok-tools --lib -- \
  after_write_returns_held_is_empty_lock_must_be_released \
  reader_during_held_write_gets_published_pre_write_bytes_current_atomic_snapshot \
  two_live_agents_with_the_same_write_paths_spawn_without_error_l2_and_l3_may_be_assigned_the_same_file \
  spawn_write_paths_overlap_is_a_soft_assignment_not_a_spawn_error

# Extra: L1 Subagents list is L2-only plus a live L3 count
cargo test -p xai-grok-pager --lib -- \
  live_subagent_list_shows_only_l2_and_reports_live_l3_count \
  l2_row_shows_live_l3_count_not_specialist_names

# Extra: live Subagents list is still-running only; already_exited overlay closeout
cargo test -p xai-grok-pager --lib -- \
  kill_already_exited_dismisses_paused_implementer_overlay \
  restore_nested_occupancy_does_not_unfinish_or_revive_dead_host \
  running_count_matches_listed_live_l2_not_l3 \
  kill_already_completed_drops_live_list_responding_and_still_running_cue

# Extra: Compacting Subagents row open button still opens
cargo test -p xai-grok-pager --lib -- \
  click_tasks_open_on_compacting_row_opens_subagent \
  click_tasks_open_on_last_painted_row_opens_subagent \
  click_tasks_kill_on_compacting_row_emits_kill \
  open_subagent_fullscreen_sets_active_while_child_is_auto_compacting \
  nested_compact_chrome_does_not_steal_parent_fullscreen_overlay \
  nested_compact_chrome_must_not_steal_parent_tui_scroll

# Extra: Ctrl+C two-stage, /model last Tab, Isolated Preview glass search,
# Isolated Preview screenshot paste (GNOME All Markup Copy is an image)
cargo test -p xai-grok-pager --lib -- \
  isolated_preview_handle_input_ctrl_c_with_text_clears_and_stays \
  isolated_preview_handle_input_second_empty_ctrl_c_exits \
  isolated_preview_handle_input_running_turn_draft_ctrl_c_does_not_cancel_turn \
  leftover_isolated_preview_handle_input_ctrl_c_clears_then_exits \
  unique_model_slash_tab_switches_now_empty_composer_no_send \
  unique_model_slash_enter_switches_now_no_operator_model_chat \
  unique_m_slash_tab_switches_now \
  complete_typed_model_xhigh_tab_switches_now_with_effort \
  command_phase_unique_model_tab_still_completes \
  multi_row_model_tab_stays_complete_not_switch \
  isolated_preview_unique_model_tab_switches_now_does_not_rowwalk \
  plan_preview_title_bar_search_glass_immediately_left_of_copy \
  isolated_preview_search_query_plan_matches_plan_and_plan \
  isolated_preview_search_glass_clickable_next_to_copy_and_expand \
  isolated_preview_composer_slash_stays_slash_not_line_search \
  isolated_preview_handle_input_n_jumps_hits_after_search \
  isolated_preview_gnome_all_markup_copy_title_with_raster_is_image_chip \
  isolated_preview_search_open_paste_does_not_fill_search \
  mill_event_paste_gnome_all_markup_copy_title_with_raster_does_not_insert_title \
  gnome_all_markup_copy_title_still_probes \
  user_guide_ctrl_c_two_stage_clears_then_exits \
  user_guide_unique_model_tab_switches_now \
  user_guide_isolated_preview_search_glass \
  user_guide_gnome_all_markup_copy_is_image

# Extra: turbo planning (Surmount vs SpaceXAI; off = session effort)
cargo test -p xai-grok-pager --lib -- \
  session_medium_enter_plan_request_uses_xhigh_and_lower_right_shows_xhigh \
  exit_or_approve_plan_returns_session_medium_effort \
  turbo_planning_settings_off_plan_turn_stays_session_medium

# Extra: soft process-rule reminders (spawn still succeeds)
cargo test -p xai-grok-tools --lib -- \
  process_rule_reminder_configured_third_l2_still_spawns \
  process_rule_reminder_text_in_nested_spawn_prompt \
  process_rule_reminders_off_nested_spawn_has_no_extra_reminder_text

# Extra: Subagents list compact window counts and TECH.md (not billing meters)
cargo test -p xai-grok-pager --lib -- \
  subagents_list_omits_the_word_tokens \
  subagents_list_l2_row_is_present_plus_past_atomic_total_including_specialists \
  nested_compact_keeps_present_plus_past_without_double_counting_the_surviving_window \
  nested_specialist_windows_are_not_double_counted_in_the_total \
  l2_row_paints_present_plus_past_atomic_total_including_specialists \
  parent_context_chip_is_l1_window_and_does_not_add_nested_windows \
  format_live_subagents_list_row_uses_live_sample_not_tracker_high_water \
  subagents_list_truncation_does_not_split_compact_count \
  subagents_list_shows_measured_tokens_per_nested_l2 \
  format_subagents_list_description_shows_measured_tokens_suffix \
  format_subagent_label_shows_measured_tokens_suffix \
  tech_md_write_records_measured_tokens_on_spawn_usage_tick_and_l2_exit \
  subagents_list_layout_does_not_read_chat_history_jsonl \
  concurrent_nested_l2_usage_ticks_keep_atomic_u64_high_water

# Extra: /start + leftover cancel-resume marker drop
cargo test -p xai-grok-pager --lib -- \
  start_while_globally_paused_continues_interrupted_turn_once \
  start_on_idle_clean_session_does_not_invent_a_turn \
  start_with_cancel_resume_marker_continues_interrupted_turn \
  handle_rebuild_done_must_not_cancel_parent_so_session_load_adopts_like_disconnect \
  handle_rebuild_done_mid_turn_writes_cancel_resume_and_session_load_continues_the_turn \
  handle_rebuild_done_idle_completed_turn_does_not_write_cancel_resume_or_refire_last_prompt \
  session_load_drops_stale_cancel_resume_marker_when_primary_turn_finished_successfully

# Extra: /unstick shell skip-append, hung-task orphan, leader hung-RPC drop, WAL image resource links
cargo test -p xai-grok-shell --lib -- \
  unstick_retry_does_not_append_second_user_query_when_last_turn_matches \
  unstick_retry_orphans_stuck_running_task_then_samples_again \
  session_prompt_is_unstick_retry_reads_params_meta \
  take_in_flight_session_prompts_for_unstick_leaves_other_sessions \
  response_is_orphaned_for_unstick_while_client_connected
cargo test -p xai-grok-shell --test test_leader_stdio_integration -- \
  unstick_leader_drops_hung_session_prompt_like_disconnected_client
cargo test -p xai-grok-pager --lib -- \
  unstick_resends_wal_images_as_resource_blocks_not_data_urls \
  wal_image_resource_blocks_use_file_uri_not_data_url \
  wal_image_resource_blocks_drop_data_url_file_ids

# Extra: ForceRefresh on explicit /limits
cargo test -p xai-grok-pager --lib -- \
  management_meter_cache_policy_collect_force_background_honor_ttl \
  should_clear_management_meter_caches_force_with_key_only
cargo test -p xai-grok-shell --lib -- \
  limits_snapshot_mode_for_get_billing_explicit_is_force_refresh \
  limits_snapshot_force_refresh_leader_http_fetches_when_snapshot_is_younger_than_one_hour

# Extra: sampling window vs catalog (chip + session field + spawn seed)
cargo test -p xai-grok-pager --lib -- \
  context_chip_names_sampling_window_when_catalog_differs \
  context_chip_hover_percent_uses_sampling_window_when_catalog_differs \
  footer_chip_uses_session_sampling_window_when_economic_cache_is_off \
  refresh_context_used_does_not_copy_catalog_into_session_sampling
cargo test -p xai-grok-shell --lib -- \
  main_session_sampling_window_is_catalog_500k_even_when_economic_is_on \
  nested_session_sampling_window_stays_200k_when_catalog_is_500k

# Extra: parent fire-and-return spawn (no blocking 10-minute wait)
cargo test -p xai-tool-types --lib -- parent_spawn_subagent_second_l2_while_first_still_running_without_wait
cargo test -p xai-grok-tools --lib -- parent_spawn_subagent_second_l2_while_first_still_running_without_wait

# Extra: parent follow-up onto a running nested L2 (GitHub #143)
# KEEP fire-and-return spawn, overlay interject, nested_spawner_can_resume_from_completed_reparented_child
cargo test -p xai-tool-types --lib -- \
  parent_cannot_talk_to_own_l2s_follow_up_field_is_optional_and_distinct_from_resume_from
cargo test -p xai-grok-tools --lib -- \
  parent_cannot_talk_to_own_l2s_follow_up_enqueues_interject_on_running_l2_without_kill_or_respawn \
  parent_follow_up_does_not_inject_into_live_l3_unless_operator_targeted_that_specialist \
  resume_from_of_running_l2_still_fails_active \
  parent_follow_up_off_is_upstream_spawn_wait_resume_from_completed_only \
  parent_follow_up_onto_running_l2_with_live_l3_hits_l2_not_l3 \
  parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_returns_queued_and_does_not_spawn \
  parent_cannot_talk_to_own_l2s_task_tool_run_follow_up_and_resume_from_are_mutually_exclusive
cargo test -p xai-grok-shell --lib -- \
  shell_child_follow_up_sends_session_command_interject_on_child_session \
  subagents_config_parent_follow_up_false_parses_and_omitted_defaults_true \
  resolve_subagents_copies_parent_follow_up

# Extra: compact standing-law reminder (not AGENTS.md)
cargo test -p xai-grok-shell --lib -- post_compact_reminder_includes_surmount_standing_law

# Extra: CoT death spiral stop + compact not 75k (GitHub #133)
# Keywords: DEST_ENCODER_SKIP_LOOP, stream Fatal, compact 8192/32768.
# Surmount vs SpaceXAI. Oh My Pi is not in this tree.
cargo test -p xai-grok-sampler --lib -- dest_encoder_skip_loop_is_repetitive \
  dest_encoder_skip_single_sentence_four_times_is_repetitive \
  thought_line_loop_is_repetitive \
  chat_completions_stops_dest_encoder_skip_loop \
  chat_completions_stops_dest_encoder_skip_loop_in_thought \
  messages_stops_dest_encoder_skip_loop \
  responses_stops_dest_encoder_skip_loop \
  classify_repetitive_generation_is_fatal
cargo test -p xai-chat-state --lib -- \
  compaction_reseed_drops_dest_encoder_skip_loop_below_75_2k \
  compaction_reseed_of_unique_75k_history_must_not_leave_wasteful_75k_context \
  compact_summary_budget_is_8192_tokens_and_reseed_reserve_is_32768 \
  format_compact_summary_caps_unique_75k_body_to_compact_summary_budget \
  build_compacted_history_unique_75k_summary_stays_within_compact_summary_budget

# Extra: spawn-prompt fold + last-answer caps
cargo test -p xai-grok-sampling-types --lib -- fold_spawn_prompt
cargo test -p xai-chat-state --lib -- parent_estimated_tokens_omit_huge_spawn_prompt
cargo test -p xai-tool-types --lib -- to_model_text_caps_huge_last_answer_for_parent_ingest
cargo test -p xai-grok-tools --lib -- \
  completed_subagent_task_output_is_capped_or_points_at_report \
  blocking_spawn_subagent_completed_to_prompt_format_is_capped

# Extra: hop flatten / any stored included remaining (rank hop_* is not this)
cargo test -p xai-grok-shell --lib -- \
  sampling_config_hop_team_remaining_personal_exhausted_not_dollars_or_console \
  sampling_config_hop_personal_remaining_team_exhausted \
  sampling_config_hop_both_remaining_team_first_then_personal \
  sampling_config_hop_both_included_exhausted_dollar_credits_before_console \
  sampling_config_hop_missing_heavy_false_100_keeps_sibling_included \
  sampling_config_hop_dollar_credits_on_both_missing_heavy_keeps_team \
  prepare_sampler_for_turn_does_not_flatten_missing_heavy_100_off_sibling \
  prepare_sampler_for_turn_does_not_flatten_dollar_credits_on_both

# Extra: user-guide fork pins beyond class 1 resume + class 7 skills
cargo test -p xai-grok-pager --lib -- user_guide_does_not_claim_automatic_host_hop_is_unshipped \
  user_guide_names_token_economy_spend_order \
  user_guide_limits_names_fail_open_and_named_commands

# Neighbors that still have a matching fn (titles / stream retry emit / rebuild fail / /limits).
# Do NOT add retry_chrome_soft_reconnects_*, shell_collision, default_title_items_include_agents:
# those identifiers have no matching fn. Stuck-retry pager chrome is not fully proven.
cargo test -p xai-grok-pager --lib -- window_title_always_manages_non_empty_branded_osc \
  titles_on_session_name_osc_is_non_empty_branded window_title_osc_payload_never_empty_string \
  show_limits format_supergrok_session footer_names_live_principal \
  limits_json_lists_two_supergrok_principals_when_both_slots_exist \
  limits_json_honest_single_supergrok_session_cannot_see_team_plan
cargo test -p xai-grok-shell --lib -- stream_started_emits_retry_state_stream_resumed
cargo test -p xai-grok-sampler --lib -- wait_before_attempt_aborts_on_cancel \
  retry_footer_reason_uses_short_transport_label \
  retry_footer_backoff_hint_appends_next_try_in \
  stream_headers_timeout_defaults_to_120_secs_when_env_unset
cargo test -p xai-grok-sampler --test stream_headers_timeout

just check   # full gate before push/PR; does not replace missing catalog fn names

CI and local quality

CI is for checks only: never build a shippable release package in GitHub Actions (supply-chain boundary). Humans package from a trusted tree when ready.

Command	Role
`just check` or `just ci`	Full Nix local gate (flake-meta + prep + fmt/clippy/tests): run before push. Uses Nix on this machine or configured builders. This is not host cargo. The remote gate is `just check-remote`.
`just check-local`	Host cargo gate when the VPS is down. Runs `cargo fmt --all -- --check`, then workspace `cargo clippy --all-targets --locked` with `-D warnings`, then `cargo nextest run --workspace --locked`, then `cargo test --doc --workspace --locked`. Nextest compile and link, and doctest `--jobs`, cap at 4 (`CARGO_LINK_JOBS`). The recipe body does not run flake-meta, nix build, or the remote recipes. `just check` / `just ci` still use Nix. Remote remains `just check-remote`. Named test: grok-nix-helper `justfile_contracts` `just_check_local_is_cargo_only_and_does_not_nix`.
`just check-remote`	Optional. Realizes flake metadata and `.#workspace-cargo-quality` (the same full cargo gate as `just check` / `just test`: fmt, then workspace clippy `--all-targets` (members include cargo-mem-guard and grok-nix-helper), then workspace nextest execution, then doctests, as a Nix derivation) on this host's existing remote builder. rustc requires that builder's `surmount-remote` feature (and `big-parallel`) and must not run on the caller. This laptop never auto-detects `surmount-remote`; the host machines file must advertise it. `--option system-features` that omit `big-parallel` does not stop local nixbld (the daemon still advertises `big-parallel`). Force-remote nix also passes `--cores 64` so that rustc can use the builder's cores. Workspace cargo passes `--jobs` from those cores, capped at 32 (an OOM hedge; not 2 from the package sandbox, and not a full 64 rustc processes). `--jobs` is after the subcommand (`cargo check --jobs`). cargo 1.97 has no global `cargo --jobs`. Quality does not run `cargo clippy` (external dispatcher; a 1-token jobserver then ignores `--jobs`). Workspace lint is `cargo check` with `RUSTC_WORKSPACE_WRAPPER=clippy-driver` under GNU make `-j$CARGO_BUILD_JOBS` (after dropping Nix `MAKEFLAGS` / `CARGO_MAKEFLAGS` / `MFLAGS`). One clippy-driver is still one typeck thread; independent crates share that jobserver. That derivation uses the same cargo dev profile as local `just test-clippy`, not crane's default `--release` check (one rustc thread at opt-level 3; codegen-units does not parallelize `cargo check` / clippy). Nix jobs (machines-file `max-jobs`: how many derivations) are not cargo/rustc workers (jobs inside one derivation). Do not raise Nix max-jobs to fix a single busy rustc. Force-remote nix passes `--option max-jobs 0` on the caller so this laptop does not build: crates.io FODs, static.rust-lang.org toolchain tarballs (the builder instruction-set architecture, not extra cores), and crane vendor unpacks go to the remote builder. The VPS fetches those itself (`builders-use-substitutes`). Force-remote `nix build` uses `--store` with the machines-file ssh-ng URI and `--eval-store auto` so cargo-package, cargo-src, and toolchain store paths stay on the VPS. Default `nix build` realizes into the local store, then copies each remote output back over SSH (that is local store close, not a remote-builder miss). `--no-link` skips a local result symlink. `-L` logs still stream as text. This laptop must not substitute those NARs from cache.nixos.org either. Force-remote exports `NIX_SSHOPTS` with this account's known_hosts (host-key checks stay on) and copies that host key into the builders line so nix-daemon SSH can verify the builder. Missing builders, a missing known_hosts entry for the machines-file host, or SSH to Host surmount-1 exits 2 with no local cargo fallback. User SSH to Host surmount-1 alone is not enough. GitHub Actions must not use this recipe. Agents may run this recipe (pinned 2026-09-02; one live run at a time; do not restart at five minutes).
`just test-remote` / `just cargo-remote`	Named cargo on that same remote builder. `just test-remote -p xai-grok-pager --lib -- actions::defaults` realizes `.#workspace-cargo-named-test` (`nix build --impure`, `GROK_NIX_FORCE_REMOTE=1`, `surmount-remote`). Tests execute (`cargo test --locked` or `cargo nextest run --locked`); not compile-only `--no-run`. `just cargo-remote` takes kind `test`, `nextest`, `clippy`, `build`, or `check`, then the same filter argv. Reuses `workspaceCargoArtifacts`. Do not raise Nix max-jobs. GitHub Actions must not use these recipes. Agents must not run `cargo test` / `cargo clippy` / `cargo build` / rustc on this laptop for grok-oss. Agents must not run `just test-remote` / `just cargo-remote` unless the operator whitelist those in the same words. Agents may run `just check-remote` (pinned 2026-09-02; one live run at a time; do not restart at five minutes). The operator owns the VPS builder (pinned 2026-08-25). When a session is explicitly told to run one of those recipes as proof, it must start them as a background job with a long wait (timeout 0 or at least twenty minutes). A five-minute foreground wait that SIGKILLs a still-running VPS compile, then starts the same recipe again, is a failed wait policy (pinned 2026-08-28). Nested grok-oss agents inherit production bash wait policy (auto-background at the wait cap, ten-hour foreground ceiling).
`just test`	Quality suite without re-running full flake prep
`just build` / install	Optional release-style package (not CI)

GHA quality job: flake-meta → ci-prep → just test (see .github/workflows/ci.yml). There is no ci-quick or ci-host recipe.

The operator owns the VPS builder (pinned 2026-08-25; check-remote whitelist 2026-09-02). Agents do not invoke just test-remote, just cargo-remote, or force-remote nix build to nixbuilder / surmount-1 unless the operator also whitelist those in the same words. Agents may run just check-remote: one live run at a time; do not start a second on the same drv or leftover list; do not restart a live remote compile at five minutes. Competing nix on this laptop still means wait or skip. GitHub Actions still must not call check-remote. Dual-pin: AGENTS.md hard constraint 3b-remote-check.

just require_system does not need a prebuilt grok-nix-helper (pinned 2026-08-26). It is a justfile CI_SYSTEM/uname check, the same map as parse-time system :=. just check-remote / just require_remote_builder must not nix build .#grok-nix-helper. Preflight is justfile/uname/SSH (builders file, known_hosts, inject GROK_NIX_REMOTE_SYSTEM_FEATURES or live BatchMode). just nix_retry / just flake-meta / the just check-remote metadata step must not require grok_nix_helper_bin. The live nix_retry body is the justfile recipe (argv exec of "$@", fail-fast on quality/SSH, force-remote flags). Missing helper must not fail just check-remote. The operator can run that gate on a dirty tree without first realizing the helper and without GROK_NIX_HELPER set. Do not tell them to realize the package first. just check-remote exports GROK_NIX_FORCE_REMOTE=1 before require_remote_builder so later nix_retry is force-remote. grok_helper must not exec an empty path. Later recipes that still need the helper (cargo-remote / test-remote, recon) locate GROK_NIX_HELPER, PATH, result/bin, or crate target only.

Quality nextest compile/link jobs (pinned 2026-08-26). Workspace clippy/check stay at cargo jobs 32. cargo nextest run compile and link uses --build-jobs capped at 4 (CARGO_LINK_JOBS). Named just test-remote nextest and cargo test use that same cap. 32 parallel mold links of workspace test binaries were SIGKILL'd (ld returned 137, 128+9) under the builder nix-daemon 32GiB MemoryMax. Host MemAvailable is larger; cargo-mem-guard reads /proc/meminfo and would not restart. just nix_retry retries that linker SIGKILL as infra; a real rustc could not compile without ld returned 137 still fail-fasts. Do not drop --locked. Do not skip test_leader_death_repro. Raising nix-daemon MemoryMax is operator-owned on the VPS.

Quality order: cargo fmt, then clippy, then tests (pinned 2026-08-26). workspace-cargo-quality (just check-remote) and local just test run in this order. First cargo fmt --all -- --check. Then clippy on everything the gate compiles: workspace --all-targets (members include cargo-mem-guard and grok-nix-helper, so a helper E0106 fails here, not in a late cargo test). Quality clippy stays cargo check with RUSTC_WORKSPACE_WRAPPER=clippy-driver under the GNU make jobserver (not the cargo clippy dispatcher). Local just test-clippy uses cargo clippy --workspace --all-targets. Then workspace cargo nextest run, then cargo test --workspace --doc. Workspace nextest covers those member crate tests. Do not add a late cargo test --manifest-path. Do not allow-lint. --locked stays. just check-local uses that same cargo order on this host (fmt, then cargo clippy --workspace --all-targets --locked with -D warnings, then nextest, then doctest) and does not use Nix. Named-test (just test-remote / just cargo-remote) is one cargo kind plus a filter, not this full chain. Named tests in grok-nix-helper justfile_contracts: workspace_quality_fmt_then_clippy_then_nextest_and_helper_tests, workspace_quality_source_matches_just_test, just_test_clippy_lints_all_targets, just_check_local_is_cargo_only_and_does_not_nix.

just update (pinned 2026-08-27). Refresh locks without compiling: the one workspace Cargo.lock, then flake.lock. Does not run just check-remote. Quality still runs --locked after that. Named test: just_update_refreshes_workspace_and_flake_locks.

Quality cargo fmt --check is a hard miss. workspace-cargo-quality runs cargo fmt --all -- --check first. rustfmt Diff in is a quality fail, not a flake 502. File-level rustfmt on the written .rs is how agents keep that gate green. See § File-level infer-from-path verify.

PATH hermeticity (CI / low-mem): with CI_LOW_MEM=1, cargo-ci enters nix develop .#ci, then grok-nix-helper hermetic-path rebuilds PATH from /nix/store bins only (ci-tools + stdenv: rustc, nextest, mold, git, python3, coreutils, ...). Host desktop tools (pw-record / parec / arecord, ...) are not visible to quality tests, matches headless GHA. Interactive just dev / default shell keep impure host PATH. Audio recorders are intentionally not in ci-tools; python3 is (cgroup + mock LSP e2e spawn it under scrubbed PATH). Escape hatch: GROK_CI_ALLOW_HOST_PATH=1. Closest GHA repro: CI_LOW_MEM=1 CI_SYSTEM=x86_64-linux just ci.

Versioning and “am I up to date?”

Idea	Practice
Upstream owns the package version number	Keep lockstep with the upstream tree we track (`CARGO_PKG_VERSION`)
Our identity is the git revision	Binary shows upstream version + short git SHA (a git object id, not a download FOD hash)
No second release train	No Surmount stable/alpha channel mirroring SpaceXAI
No default xAI auto-update	Would advertise official `grok` builds

Illustrative only (not necessarily this checkout):

grok-oss <upstream-version> (<short-sha>)

grok-oss --version
grok-oss update --check          # vs github.com/SurmountSystems/grok-oss main
grok-oss update --check --json

SOURCE_REV at the repo root is a monorepo export pin (full upstream-side SHA recorded for the tree we absorbed), not a substitute for “what is HEAD.” That SHA is a git object id. It is not SHA-1 hashing of a tarball and not a Nix FOD pin. New download / FOD verify is SHA-256 or minisign. /rebuild checks the installed binary with --version, then compares that identity.

If behind: from a checkout run TUI /rebuild (wired, SHA-aware peer relaunch, persist plus self re-exec), or CLI grok-oss rebuild (same compile-and-signal core, no self re-exec). Named parse test: rebuild_subcommand_parses. Do not use the official curl https://x.ai/cli/install.sh path (that installs upstream grok).

Multi-session rate limits

Concurrent grok-oss processes share cooldowns under ~/.grok/rate_limits/ (grok-rate-limit). On HTTP 429-style limits, the strictest wait wins across processes. Before a sample, the sampler consults that store and waits if a cooldown is live, so many windows on one machine do not stampede one SuperGrok identity. Flock JSON is enough for that C1 case; do not add a daemon unless flock is proven racy. Filenames fingerprint the bearer (never the raw token). This path is not the exhausted-credit memo, not included SuperGrok period limits, not SuperGrok dollar credits, and not console team prepaid. A 100% client printout must not mark SuperGrok used up. Matching nextReset is not proof of a shared pool. Named test: peer_process_does_not_sample_during_shared_rate_limit_cooldown. Disable shared coordination with GROK_DISABLE_SHARED_RATE_LIMIT=1.

Product HTTP paths that wait before send and observe on 429 (403 only when a retry hint such as Retry-After is present):

Class	Provider key shape	Examples
Chat / inference	host + key fingerprint	sampler (xAI, SuperGrok proxy, OpenRouter, BYOK base URLs)
SuperGrok billing	proxy host + session fingerprint	`GET .../billing?format=credits`, auto-topup
Management API	management host + management-key fingerprint	prepaid, postpaid, usage series, key validation
Imagine image	host + fingerprint + `imagine`	`image_gen`, `image_edit`
Imagine video	host + fingerprint + `video`	`video_gen` start + poll
Voice STT	host + fingerprint + `voice`	streaming `wss://.../v1/stt`
Responses	host + fingerprint + `responses`	`web_search`
GitHub	logical `github`	OSS update compare

Waits prefer server headers (Retry-After, then x-ratelimit-reset) over hardcoded tier tables. Public docs (accessed 2026-08-03):

xAI rate limits (per-model RPS/TPM; Imagine image/video have separate RPS; Voice/Imagine tier increases via sales)
OpenRouter limits (honor Retry-After / X-RateLimit-* on 429)
GitHub REST rate limits (primary + secondary; Retry-After / x-ratelimit-reset)

Canonical repo

https://github.com/SurmountSystems/grok-oss

License

Apache License 2.0: LICENSE. Third-party: THIRD-PARTY-NOTICES.

FilesExpand file tree

FORK.md

Latest commit

History