Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: key-files notes for the CLI = gate (#7619)
garrytand18ce4941597
diff --git a/docs/architecture/key-files/commands-3.md b/docs/architecture/key-files/commands-3.mdindex fe2e1d17b7..918f4f6407 100644--- a/docs/architecture/key-files/commands-3.md+++ b/docs/architecture/key-files/commands-3.md@@ -13,7 +13,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/eval-export.ts` — streams `eval_candidates` rows as NDJSON to stdout with `schema_version: 1` prefix on every line. EPIPE-safe, progress heartbeats on stderr, stable id-desc tiebreaker so `--since` windows never dupe/miss rows. D2: `eval` declares `jsonSubcommands` {export, replay, gate: 'ndjson'}; under `--json` each row is a `writeNdjsonLine` and argv errors are one `{status:'error'}` envelope line (`invalid_params`, exit 2).-- `src/commands/eval-longmemeval.ts` + `src/eval/longmemeval/{harness,adapter,sanitize,extract,intent,reader,emit,capture,gateway-client,trajectory-route,decide-lane}.ts` — `gbrain eval longmemeval <dataset.jsonl>` runs the public [LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark against gbrain's hybrid retrieval and is the repo's receipt producer for the strict retrieval metric and, with `--judge`, for judged answer accuracy (both reproduction paths are in `docs/eval-bench.md`). One in-memory PGLite per run via `createBenchmarkBrain` + `withBenchmarkBrain`; between questions, `TRUNCATE` over runtime-enumerated `pg_tables` with the infrastructure tables (`sources`, `config`, `gbrain_cycle_locks`, `subagent_rate_leases`, and `decide_calibrations` for System One arms) preserved — which is why the run's pins, written once via `engine.setConfig`, hold for every question. `cli.ts` pre-dispatch bypass skips `connectEngine()`, so `~/.gbrain` is never opened. Embedded callers use `RunOpts.exitOnError: false` to throw rather than terminate the host and preflight resolved chat providers before embedding; standalone CLI exits remain unchanged. **Metric (metrics.ts):** recall joins on RAW dataset session ids through a per-question slug→raw map; `recall_all@k` (every gold session among the distinct sessions of the top-k CHUNK rows returned at `limit: k`) is the headline, `recall_any@k` the diagnostic, and the per-row `recall_hit` is a deprecated alias of `recall_any_hit`; `_abs` abstention questions are emitted with `abstention: true` but stay out of the recall denominators unless `--include-abstention`; a slug collision touching a gold id aborts that question with an error row. **Pins:** `--mode`, `--reranker on|off`, `--autocut on|off`, `--expansion` (OFF for every mode — the per-call setting wins over the bundle, so `--mode tokenmax` alone never expands), `--expansion-variant-budget legacy|(0,4]`, `--search-pin KEY=VALUE` (repeatable; any `search.*` key, written verbatim via `engine.setConfig`); precedence is explicit flag > `--search-pin` > injected `RunOpts.searchConfigSnapshot` > bundle, so a flag wins over a pin on the same key. The raw `--search-pin` map folds into `retrieval_config_hash` (only when non-empty, so pin-free runs keep their hash identity) while the knobs hash covers only the resolved mode knobs. The reranker gate keys on the RESOLVED pin (flag, `--search-pin`, snapshot or bundle), not only on an explicit `--reranker on`: a run that resolves to reranker on preflights `rerankerReadinessForEngine` and exits 2 with the fix when the reranker cannot run (a `balanced` run with no `VOYAGE_API_KEY` exits with the fix text — `--reranker off` or set the key — instead of quietly scoring un-reranked rows). **Gates (exit 1):** a run in which every question errored, a row that fell through un-reranked under a resolved reranker-on pin (`reranker_skipped_rows`), a row whose vector arm silently degraded to keyword-only on a non-`--keyword-only` run (`vector_degraded_rows`: `vector_enabled:false` / `embed_unavailable` / `embed_timeout`), an `--expansion` row that did not expand as configured (`expansion_failed_rows`), an `--expansion-replay` miss, and `--by-type-floor F` breaches — which gate on `recall_all` by default (`--by-type-floor-metric recall_any` selects the lenient rate). The run-end gates and `GBRAIN_LME_DEBUG=1` prints per-question wall time to stderr; `--record` run through ONE `finishRun` from both the main path and the no-op resume path. **Rows:** `retrieved[]` (every returned chunk row: `slug`, `chunk_id`, RAW `session_id`, `rank`, `score`, `rerank_score?`, `alias_hit?`), `retrieved_session_ids`, `distinct_sessions_in_top_k`, `gold_total`/`gold_found`, `search_meta` (`vector_enabled`, `expansion_applied`, `degraded`, derived `reranked` = some finite `rerank_score` and no skip stage, `autocut`), `retrieval_config_hash`, the reader pins on every answered row (`reader_model` = the requested id, `reader_model_snapshot` = the provider-reported id when it differs — a dated API snapshot — else null, `reader_prompt_sha`, `reader_max_tokens`; `--retrieval-only` rows carry `retrieval_only: true` instead so a judge backfill can refuse them), `expansion_variants` when expansion ran (`--expansion-replay FILE` serves them back and stamps `expansion_replayed`, so every cell differs only in its knobs), and with `--capture-pool` a `rerank_pool` — the exact pre-autocut `returnPool` `hybridSearch` hands to `applyAutocut` (via `HybridSearchOpts.onRerankPool`; unscored alias/exact-lookup injections included; `rrf_rank`, `pool_rank`, `est_tokens` per row; `autocut_kept_keys` when the returned rows are the kept set) for the offline autocut-floor replay. **Summary:** `--by-type` emits a `schema_version: 2` `by_type_summary` (per-type + aggregate `{total, all_hit, all_rate, any_hit, any_rate}`, `excluded_abstention`, `mean_distinct_sessions`, `legacy_rows`, `gold_missing_from_haystack`, `slug_collisions`, and `run_config`: every pin, embedder `model@dims`, dataset sha256 + question count, `knobs_hash` + `KNOBS_HASH_VERSION`, `retrieval_config_hash`, the embed-cache receipt, the degradation counters); resume-replace keeps exactly ONE summary at the tail (`emit.ts:emitByTypeSummary`: the summary is always the FINAL line — any prior `by_type_summary` is removed before the new one is appended, and the file rewrite is atomic, `<path>.summary.tmp` + rename, so a kill mid-write never truncates the paid rows — its `_meta.metric_glossary` is the ONE glossary block per response and names exactly the metrics carried, `recall_all@k`, `recall_any@k`, and `qa_accuracy` when the judge lane ran; a CR inside any emitted line throws rather than splitting a JSONL record). **Reader (reader.ts):** the selected reader system text is constant across questions — every per-question input (question, `Current Date: {question_date}` when the dataset row carries one, the trajectory block, the sanitized `<chat_session>` blocks) lives in the USER message — so `reader_prompt_sha` (sha256 of the selected system text) is a run-level pin, alongside mode, version, model and output budget. Notes-first/1024 is the reader default; direct/512 retains the original prompt (official cap 500). Disclosed deviations from the official `run_generation.py` prompt: an abstention instruction (say the information is not available / "I don't know" when the retrieved sessions lack it — without it the 30 `_abs` questions are answered and judged wrong by construction), the #4338 data-boundary framing + pattern stripping, and the configurable cap. `resolveReaderConfig`, `buildReaderRequest` and `readerConfigHash` are available through `gbrain/eval/longmemeval/reader` to companion evals; `generateAnswer` returns `{text, response_model, finish_reason}`, `response_model` being the provider-reported snapshot when it differs from the requested id (the harness's gateway client maps `ChatResult.responseModel ?? model` into the Anthropic-shaped `message.model`). **Judge lane (`--judge`):** implies `--by-type`; `--judge --retrieval-only` is a usage error. Preflight (`judge-lane.ts:judgePreflight`): no usable chat provider for the judge model → exit 1; `--max-usd` against an unpriced model → exit 2 (pass `--max-usd off`); estimate over the cap without `--yes` → exit 2. The estimate (`judge.ts:estimateJudgeRunUsd`) assumes the selected reader output cap per live hypothesis and the stored hypothesis for backfill rows; the `BudgetLedger` soft-stops at the cap and the remaining rows are stamped `judge_skipped: 'budget'`. Live rows are judged inline after each reader call. `--judge --resume-from FILE` is the judge-only backfill: `selectBackfillRows` picks every prior row with a hypothesis and no settled verdict (`judge_error` rows are re-judged, `--retrieval-only` rows are refused, rows absent from the dataset are left unjudged with a WARN); a same-file resume ALWAYS appends (`makeEmitter(outputPath, append)` has no atomic-rewrite mode — appending is the only write path) — judged backfill rows and retries land as newer duplicates the moment they finish, so a timeout or kill loses at most the in-flight question — and `compactJsonlByQuestionId` (emit.ts) rewrites the file atomically (`<path>.compact.tmp` + rename) to one row per question_id (last wins, first-seen order) before the summary is emitted; `readJsonlRows` / `loadResumeSet` read appended files last-wins and `--judge-concurrency N` parallelizes the backfill. Every judged row carries `judge_config_hash` — the judge pins (model, `JUDGE_PROMPT_VERSION`, max_tokens, temperature) plus the reader pins the row was produced under; a prior row hashes from its OWN recorded `reader_model` / `reader_prompt_sha` / `reader_max_tokens`, so a file answered by another reader is never relabelled as this run's, and rows already judged under a different hash are refused unless `--allow-mixed-run-config`. Run end: `qa_accuracy` (`qa-accuracy.ts`) is rebuilt from ALL rows (prior + new, last row per `question_id` wins) whenever the lane ran or any row carries a verdict; a run with `judge_errors > 0`, `skipped_budget > 0` or `unjudged > 0` (the `qa_accuracy.complete` predicate) prints a `FAIL … NOT publishable` line and exits 1 unless `--allow-incomplete-judgments` (WARN, exit 0) — the fix is `--judge --resume-from FILE` until all three are 0; a row whose judge call threw is stamped `judge_error: 'provider_error'` by the backfill, never silently left unjudged. Judge row fields: exactly one of `judge_correct` / `judge_error` (+ secret-redacted `judge_error_detail`) / `judge_skipped`, plus `judge_model`, `judge_model_snapshot`, `judge_raw` (first 200 chars), `judge_cost_usd`, `judge_attempts`, `judge_prompt_kind`, `judge_prompt_version`, `judge_config_hash`. `RunOpts.judgeClient` / `judgeBackoffMs` are the test seams. **Embed cache:** on by default at `~/.cache/gbrain-eval/longmemeval-embed.sqlite` (`--embed-cache FILE` / `--no-embed-cache`; never installed on `--keyword-only`), installed through the gateway embed-transport seam so every arm sees byte-identical vectors; the cache transaction wraps only the embed-producing section of a question (import + search), never a reader call. **Resume:** `--resume-from FILE` re-scores prior rows from `retrieved[]` + the dataset's gold (stored booleans are never trusted), refuses reader-mode/prompt/model/budget changes unconditionally (historical direct rows require `--reader-mode direct`), and refuses a different `retrieval_config_hash` unless `--allow-mixed-run-config`; error rows without a hypothesis are retried. `--question-ids FILE` restricts the run to a listed slice (unknown ids or an empty file exit 1); `--record` appends a secret-redacted `EvalRunRecord` (schema 3, suite `longmemeval`, params = `run_config`) via `persistRunRecord`. Flags live in ONE table, `LME_FLAGS`, that drives both `parseArgs` and `printHelp`, so the flag-registry scan sees every literal and help cannot drift from the parser. Sanitization parity: `harness.ts` reuses `INJECTION_PATTERNS` from `src/core/think/sanitize.ts`; retrieved chat content is wrapped in `<chat_session id="..." date="...">` and the answer-gen system prompt declares it UNTRUSTED. `RunOpts` seams — `client`, `extractorClient`/`extractorModel`, `engine`, `searchConfigSnapshot`, `expandFn`, `embedTransport`, `rerankerReadiness`, `recordDir` — let the full pipeline run hermetically without an API key. Trajectory routing (default on; `--no-trajectory` bypasses BOTH the extractor and the intent routing, the like-for-like retrieval setting): `extract.ts` runs the claim extractor (`RunOpts.extractorModel`, else the utility tier) over each haystack session into the benchmark brain's `facts` table (content-hash cache, per-question alias map, fail-open on every error path), `intent.ts` prefers the dataset's `question_type` before the SHARED regex set from `src/core/think/intent.ts`, temporal/knowledge_update questions splice a `findTrajectory` block into the reader prompt, and rows carry `intent`, `trajectory_points`, `entity_resolved`, `resolution_source`, `methodology_note` (`trajectoryMethodologyNote`: `extractor=haiku-preprocess-full-haystack-v1` for a Haiku extractor, else `extractor=<model id>-preprocess-full-haystack-v1` — "gbrain + extractor-preprocess", not "gbrain alone"). Incomplete reader output (`max_tokens`, empty or unknown finish) records its partial text only in `reader_partial_output`, clears the hypothesis, counts as a failed question and cannot be judged; `reader_finish_reason` is stamped on answered attempts. Pinned by `test/eval-longmemeval-reader-mode.slow.test.ts`, `test/longmemeval-reader.test.ts`, `test/longmemeval-metrics.test.ts`, `test/eval-longmemeval-mixedcase.slow.test.ts` (raw-id join, strict/any split, abstention, pins, gates over the placeholder fixture `test/fixtures/longmemeval-mixedcase.jsonl`), `test/eval-longmemeval-cli-smoke.test.ts`, `test/longmemeval-embed-cache.test.ts`, `test/longmemeval-judge.test.ts` + `test/eval-longmemeval-judge.slow.test.ts` (the judge lane, reader pins and `qa_accuracy` denominators), `test/eval-longmemeval.slow.test.ts`, `test/eval-longmemeval-e2e.slow.test.ts`, `test/eval-longmemeval-search-config.test.ts`, `test/longmemeval-extract.test.ts`, `test/longmemeval-intent.test.ts`, `test/longmemeval-trajectory-routing.test.ts`. **System One arms (`decide-lane.ts`, shared flags in `src/eval/decide-eval-flags.ts`):** `--decide <slot>=<mode>` and the `--decide-*` flags configure each benchmark brain so the slot acts, fold `run_config.decide` into `retrieval_config_hash`, stamp a per-row `decide` receipt and `run_config.decide_summary`, restrict to the `--decide-dataset` eval half, refuse trajectory routing (it reads `question_type`), and with `--decide answerable=on` let the S4 verdict `abstain` replace the reader call; `--eval-pool-depth N` (eval-only, `src/core/search/eval-pool-depth.ts`) lifts the per-arm cap to N and pins `top_n_in`; `--capture-pool` rows carry `pool_recall` at fused depths 30/50/100/300 (`capture.ts`). All-off rows are unchanged. Tests: `test/eval-longmemeval-decide.serial.test.ts`, `test/eval-pool-depth.test.ts`.+- `src/commands/eval-longmemeval.ts` + `src/eval/longmemeval/{harness,adapter,sanitize,extract,intent,reader,emit,capture,gateway-client,trajectory-route,decide-lane}.ts` — `gbrain eval longmemeval <dataset.jsonl>` runs the public [LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark against gbrain's hybrid retrieval and is the repo's receipt producer for the strict retrieval metric and, with `--judge`, for judged answer accuracy (both reproduction paths are in `docs/eval-bench.md`). One in-memory PGLite per run via `createBenchmarkBrain` + `withBenchmarkBrain`; between questions, `TRUNCATE` over runtime-enumerated `pg_tables` with the infrastructure tables (`sources`, `config`, `gbrain_cycle_locks`, `subagent_rate_leases`, and `decide_calibrations` for System One arms) preserved — which is why the run's pins, written once via `engine.setConfig`, hold for every question. `cli.ts` pre-dispatch bypass skips `connectEngine()`, so `~/.gbrain` is never opened. Embedded callers use `RunOpts.exitOnError: false` to throw rather than terminate the host and preflight resolved chat providers before embedding; standalone CLI exits remain unchanged. **Metric (metrics.ts):** recall joins on RAW dataset session ids through a per-question slug→raw map; `recall_all@k` (every gold session among the distinct sessions of the top-k CHUNK rows returned at `limit: k`) is the headline, `recall_any@k` the diagnostic, and the per-row `recall_hit` is a deprecated alias of `recall_any_hit`; `_abs` abstention questions are emitted with `abstention: true` but stay out of the recall denominators unless `--include-abstention`; a slug collision touching a gold id aborts that question with an error row. **Pins:** `--mode`, `--reranker on|off`, `--autocut on|off`, `--expansion` (OFF for every mode — the per-call setting wins over the bundle, so `--mode tokenmax` alone never expands), `--expansion-variant-budget legacy|(0,4]`, `--search-pin KEY=VALUE` (repeatable; any `search.*` key, written verbatim via `engine.setConfig`); precedence is explicit flag > `--search-pin` > injected `RunOpts.searchConfigSnapshot` > bundle, so a flag wins over a pin on the same key. The raw `--search-pin` map folds into `retrieval_config_hash` (only when non-empty, so pin-free runs keep their hash identity) while the knobs hash covers only the resolved mode knobs. The reranker gate keys on the RESOLVED pin (flag, `--search-pin`, snapshot or bundle), not only on an explicit `--reranker on`: a run that resolves to reranker on preflights `rerankerReadinessForEngine` and exits 2 with the fix when the reranker cannot run (a `balanced` run with no `VOYAGE_API_KEY` exits with the fix text — `--reranker off` or set the key — instead of quietly scoring un-reranked rows). **Gates (exit 1):** a run in which every question errored, a row that fell through un-reranked under a resolved reranker-on pin (`reranker_skipped_rows`), a row whose vector arm silently degraded to keyword-only on a non-`--keyword-only` run (`vector_degraded_rows`: `vector_enabled:false` / `embed_unavailable` / `embed_timeout`), an `--expansion` row that did not expand as configured (`expansion_failed_rows`), an `--expansion-replay` miss, and `--by-type-floor F` breaches — which gate on `recall_all` by default (`--by-type-floor-metric recall_any` selects the lenient rate). The run-end gates and `GBRAIN_LME_DEBUG=1` prints per-question wall time to stderr; `--record` run through ONE `finishRun` from both the main path and the no-op resume path. **Rows:** `retrieved[]` (every returned chunk row: `slug`, `chunk_id`, RAW `session_id`, `rank`, `score`, `rerank_score?`, `alias_hit?`), `retrieved_session_ids`, `distinct_sessions_in_top_k`, `gold_total`/`gold_found`, `search_meta` (`vector_enabled`, `expansion_applied`, `degraded`, derived `reranked` = some finite `rerank_score` and no skip stage, `autocut`), `retrieval_config_hash`, the reader pins on every answered row (`reader_model` = the requested id, `reader_model_snapshot` = the provider-reported id when it differs — a dated API snapshot — else null, `reader_prompt_sha`, `reader_max_tokens`; `--retrieval-only` rows carry `retrieval_only: true` instead so a judge backfill can refuse them), `expansion_variants` when expansion ran (`--expansion-replay FILE` serves them back and stamps `expansion_replayed`, so every cell differs only in its knobs), and with `--capture-pool` a `rerank_pool` — the exact pre-autocut `returnPool` `hybridSearch` hands to `applyAutocut` (via `HybridSearchOpts.onRerankPool`; unscored alias/exact-lookup injections included; `rrf_rank`, `pool_rank`, `est_tokens` per row; `autocut_kept_keys` when the returned rows are the kept set) for the offline autocut-floor replay. **Summary:** `--by-type` emits a `schema_version: 2` `by_type_summary` (per-type + aggregate `{total, all_hit, all_rate, any_hit, any_rate}`, `excluded_abstention`, `mean_distinct_sessions`, `legacy_rows`, `gold_missing_from_haystack`, `slug_collisions`, and `run_config`: every pin, embedder `model@dims`, dataset sha256 + question count, `knobs_hash` + `KNOBS_HASH_VERSION`, `retrieval_config_hash`, the embed-cache receipt, the degradation counters); resume-replace keeps exactly ONE summary at the tail (`emit.ts:emitByTypeSummary`: the summary is always the FINAL line — any prior `by_type_summary` is removed before the new one is appended, and the file rewrite is atomic, `<path>.summary.tmp` + rename, so a kill mid-write never truncates the paid rows — its `_meta.metric_glossary` is the ONE glossary block per response and names exactly the metrics carried, `recall_all@k`, `recall_any@k`, and `qa_accuracy` when the judge lane ran; a CR inside any emitted line throws rather than splitting a JSONL record). **Reader (reader.ts):** the selected reader system text is constant across questions — every per-question input (question, `Current Date: {question_date}` when the dataset row carries one, the trajectory block, the sanitized `<chat_session>` blocks) lives in the USER message — so `reader_prompt_sha` (sha256 of the selected system text) is a run-level pin, alongside mode, version, model and output budget. Notes-first/1024 is the reader default; direct/512 retains the original prompt (official cap 500). Disclosed deviations from the official `run_generation.py` prompt: an abstention instruction (say the information is not available / "I don't know" when the retrieved sessions lack it — without it the 30 `_abs` questions are answered and judged wrong by construction), the #4338 data-boundary framing + pattern stripping, and the configurable cap. `resolveReaderConfig`, `buildReaderRequest` and `readerConfigHash` are available through `gbrain/eval/longmemeval/reader` to companion evals; `generateAnswer` returns `{text, response_model, finish_reason}`, `response_model` being the provider-reported snapshot when it differs from the requested id (the harness's gateway client maps `ChatResult.responseModel ?? model` into the Anthropic-shaped `message.model`). **Judge lane (`--judge`):** implies `--by-type`; `--judge --retrieval-only` is a usage error. Preflight (`judge-lane.ts:judgePreflight`): no usable chat provider for the judge model → exit 1; `--max-usd` against an unpriced model → exit 2 (pass `--max-usd off`); estimate over the cap without `--yes` → exit 2. The estimate (`judge.ts:estimateJudgeRunUsd`) assumes the selected reader output cap per live hypothesis and the stored hypothesis for backfill rows; the `BudgetLedger` soft-stops at the cap and the remaining rows are stamped `judge_skipped: 'budget'`. Live rows are judged inline after each reader call. `--judge --resume-from FILE` is the judge-only backfill: `selectBackfillRows` picks every prior row with a hypothesis and no settled verdict (`judge_error` rows are re-judged, `--retrieval-only` rows are refused, rows absent from the dataset are left unjudged with a WARN); a same-file resume ALWAYS appends (`makeEmitter(outputPath, append)` has no atomic-rewrite mode — appending is the only write path) — judged backfill rows and retries land as newer duplicates the moment they finish, so a timeout or kill loses at most the in-flight question — and `compactJsonlByQuestionId` (emit.ts) rewrites the file atomically (`<path>.compact.tmp` + rename) to one row per question_id (last wins, first-seen order) before the summary is emitted; `readJsonlRows` / `loadResumeSet` read appended files last-wins and `--judge-concurrency N` parallelizes the backfill. Every judged row carries `judge_config_hash` — the judge pins (model, `JUDGE_PROMPT_VERSION`, max_tokens, temperature) plus the reader pins the row was produced under; a prior row hashes from its OWN recorded `reader_model` / `reader_prompt_sha` / `reader_max_tokens`, so a file answered by another reader is never relabelled as this run's, and rows already judged under a different hash are refused unless `--allow-mixed-run-config`. Run end: `qa_accuracy` (`qa-accuracy.ts`) is rebuilt from ALL rows (prior + new, last row per `question_id` wins) whenever the lane ran or any row carries a verdict; a run with `judge_errors > 0`, `skipped_budget > 0` or `unjudged > 0` (the `qa_accuracy.complete` predicate) prints a `FAIL … NOT publishable` line and exits 1 unless `--allow-incomplete-judgments` (WARN, exit 0) — the fix is `--judge --resume-from FILE` until all three are 0; a row whose judge call threw is stamped `judge_error: 'provider_error'` by the backfill, never silently left unjudged. Judge row fields: exactly one of `judge_correct` / `judge_error` (+ secret-redacted `judge_error_detail`) / `judge_skipped`, plus `judge_model`, `judge_model_snapshot`, `judge_raw` (first 200 chars), `judge_cost_usd`, `judge_attempts`, `judge_prompt_kind`, `judge_prompt_version`, `judge_config_hash`. `RunOpts.judgeClient` / `judgeBackoffMs` are the test seams. **Embed cache:** on by default at `~/.cache/gbrain-eval/longmemeval-embed.sqlite` (`--embed-cache FILE` / `--no-embed-cache`; never installed on `--keyword-only`), installed through the gateway embed-transport seam so every arm sees byte-identical vectors; the cache transaction wraps only the embed-producing section of a question (import + search), never a reader call. **Resume:** `--resume-from FILE` re-scores prior rows from `retrieved[]` + the dataset's gold (stored booleans are never trusted), refuses reader-mode/prompt/model/budget changes unconditionally (historical direct rows require `--reader-mode direct`), and refuses a different `retrieval_config_hash` unless `--allow-mixed-run-config`; error rows without a hypothesis are retried. `--question-ids FILE` restricts the run to a listed slice (unknown ids or an empty file exit 1); `--record` appends a secret-redacted `EvalRunRecord` (schema 3, suite `longmemeval`, params = `run_config`) via `persistRunRecord`. Flags live in ONE table, `LME_FLAGS`, that drives both `parseArgs` and `printHelp`, so the flag-registry scan sees every literal and help cannot drift from the parser; a switch written with a value (`--judge=true`) exits 1 like an unknown flag. Sanitization parity: `harness.ts` reuses `INJECTION_PATTERNS` from `src/core/think/sanitize.ts`; retrieved chat content is wrapped in `<chat_session id="..." date="...">` and the answer-gen system prompt declares it UNTRUSTED. `RunOpts` seams — `client`, `extractorClient`/`extractorModel`, `engine`, `searchConfigSnapshot`, `expandFn`, `embedTransport`, `rerankerReadiness`, `recordDir` — let the full pipeline run hermetically without an API key. Trajectory routing (default on; `--no-trajectory` bypasses BOTH the extractor and the intent routing, the like-for-like retrieval setting): `extract.ts` runs the claim extractor (`RunOpts.extractorModel`, else the utility tier) over each haystack session into the benchmark brain's `facts` table (content-hash cache, per-question alias map, fail-open on every error path), `intent.ts` prefers the dataset's `question_type` before the SHARED regex set from `src/core/think/intent.ts`, temporal/knowledge_update questions splice a `findTrajectory` block into the reader prompt, and rows carry `intent`, `trajectory_points`, `entity_resolved`, `resolution_source`, `methodology_note` (`trajectoryMethodologyNote`: `extractor=haiku-preprocess-full-haystack-v1` for a Haiku extractor, else `extractor=<model id>-preprocess-full-haystack-v1` — "gbrain + extractor-preprocess", not "gbrain alone"). Incomplete reader output (`max_tokens`, empty or unknown finish) records its partial text only in `reader_partial_output`, clears the hypothesis, counts as a failed question and cannot be judged; `reader_finish_reason` is stamped on answered attempts. Pinned by `test/eval-longmemeval-reader-mode.slow.test.ts`, `test/longmemeval-reader.test.ts`, `test/longmemeval-metrics.test.ts`, `test/eval-longmemeval-mixedcase.slow.test.ts` (raw-id join, strict/any split, abstention, pins, gates over the placeholder fixture `test/fixtures/longmemeval-mixedcase.jsonl`), `test/eval-longmemeval-cli-smoke.test.ts`, `test/longmemeval-embed-cache.test.ts`, `test/longmemeval-judge.test.ts` + `test/eval-longmemeval-judge.slow.test.ts` (the judge lane, reader pins and `qa_accuracy` denominators), `test/eval-longmemeval.slow.test.ts`, `test/eval-longmemeval-e2e.slow.test.ts`, `test/eval-longmemeval-search-config.test.ts`, `test/longmemeval-extract.test.ts`, `test/longmemeval-intent.test.ts`, `test/longmemeval-trajectory-routing.test.ts`. **System One arms (`decide-lane.ts`, shared flags in `src/eval/decide-eval-flags.ts`):** `--decide <slot>=<mode>` and the `--decide-*` flags configure each benchmark brain so the slot acts, fold `run_config.decide` into `retrieval_config_hash`, stamp a per-row `decide` receipt and `run_config.decide_summary`, restrict to the `--decide-dataset` eval half, refuse trajectory routing (it reads `question_type`), and with `--decide answerable=on` let the S4 verdict `abstain` replace the reader call; `--eval-pool-depth N` (eval-only, `src/core/search/eval-pool-depth.ts`) lifts the per-arm cap to N and pins `top_n_in`; `--capture-pool` rows carry `pool_recall` at fused depths 30/50/100/300 (`capture.ts`). All-off rows are unchanged. Tests: `test/eval-longmemeval-decide.serial.test.ts`, `test/eval-pool-depth.test.ts`.- `src/commands/eval-prune.ts` — explicit retention cleanup. Requires `--older-than DUR`. `--dry-run` reports would-delete count.diff --git a/docs/architecture/key-files/commands-6.md b/docs/architecture/key-files/commands-6.mdindex df69a1e357..e4d832f10c 100644--- a/docs/architecture/key-files/commands-6.md+++ b/docs/architecture/key-files/commands-6.md@@ -14,7 +14,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/upgrade.ts` — self-update CLI. It sets `GBRAIN_UPGRADE_OWNS_MIGRATIONS=1` for the install step, so package postinstall (`scripts/postinstall.ts`) skips `apply-migrations`; post-upgrade owns them. An install step that fails or times out after `gbrain --version` already reports a newer version counts as installed. The run ends with a `Binary:` line (installed version, or upgrade failed) and a `Migrations:` line: complete; running, with the lock holder's host and pid when post-upgrade exits 75; or failed, with the recovery command (`--force-retry <v>` for wedged versions). `runPostUpgrade()` enumerates migrations from the TS registry (`src/commands/migrations/index.ts`) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally. After schema apply it prints the one-shot auto_chronicle default-on `[AGENT]` notice (`core/chronicle/upgrade-notice.ts`). Before the swap of a bun-link, package or ClawHub install it refuses (exit 78, nothing changed) a target whose Bun floor is above the host's Bun or unreadable (`--no-bun-floor-check` overrides, manual only; `src/core/bun-floor.ts`); after the swap it runs `gbrain --help` as a smoke that passes the startup Bun check and, on failure, exits 1 with per-method recovery (#5855). Everything the post-swap tail needs is imported statically, so the old process never loads new-release modules into its cached graph (#6604; the supervisor step constant lives in the import-free leaf `src/commands/movement-step.ts`; guard: `test/upgrade-post-swap-imports.test.ts`). A tag-pinned reinstall hint (`bunReinstallCommand`, `reinstallHintLines`) probes `git ls-remote --exit-code --tags … refs/tags/v<x>` before `bun remove -g gbrain`, prints a restore line, and on Windows prints one step per line; `planPinnedReinstall` probes the tag itself (published / not published / unknown) and falls back to the newest published `v<x>` tag (`latestPublishedVersion`) when the requested one is missing (#6662, D24; `test/upgrade-release-tag-hint.test.ts`). A verified version equal to the running one after the install step is no swap (#6828): it prints `No newer version was installed`, skips `last_upgrade`, `JUST_UPGRADED`, the cache reset and the smoke, and on a tag pin with no newer published tag the hint moves the install off the pin with `to_version: latest`, never a cached unpublished version (#6718). With `GBRAIN_SWAP_RECEIPT` set it writes a `SwapReceipt` (`installed` / `not_installed` / `installed_broken`) for the autopilot channel (`test/autopilot-unpublished-target-6828.test.ts`). Tests: `upgrade-migration-outcome.test.ts`, `upgrade-no-autopilot.serial.test.ts`, `upgrade-bun-link-arc.serial.test.ts`. `post-upgrade --json` (D2, `json: 'document'`): human lines go to stderr and stdout is one report `{status, apply_migrations:{exit_code}, schema, warnings[]}`; it calls `applyMigrations()` and still ends on any status apply-migrations returns (a failure is one envelope leading with the report). GBRA-175: `--channel latest|stable` (default `self_upgrade.channel`): `resolveStableRelease` maps the commit `refs/tags/stable` peels to onto its `v<version>` tag through `git ls-remote`, and `installStableRelease` installs exactly that release (bun: remove then add `#v<version>`, restoring the previous release on failure; bun-link: fast-forward only; binary: `fetchReleaseByTag`), never downgrading. Before the swap `preflightHostRestart` refuses (`restart_refused`, exit 3) when a running process could not be restarted; after post-upgrade the new build runs `gbrain upgrade --restart-only` (`--no-restart` skips it). Tests: `upgrade-stable-channel.test.ts`. A global install pinned to a tag or commit (`bunGlobalExactTagPin(root, true)`) is replaced with the newest published release the same way instead of `bun update`, which keeps the pin. `parseChannelArg` and `resolveStableRelease` live in `src/core/stable-channel.ts` (re-exported).- `src/commands/upgrade-restart.ts` — GBRA-175: the host side of the upgrade restart. Real process sources (consumer heartbeat rows on Postgres, the supervisor PID file, the worker registry, `ps -U <uid> -ww -o pid=,ppid=,etime=,command=` with `/proc/<pid>/environ` GBRAIN_HOME matching on Linux; the install version above each entry point), the installed serve and autopilot services with the pid each manager runs (`hostServices`: `systemctl --user show -p MainPID`, `launchctl list`), `terminateIfUnchanged` (SIGTERM an MCP pid only while `ps` still shows the same server and start time), `restartRefusal` (ask_user + `--stop-mcp` when only MCP servers block, else the first manual step for the user), `preflightHostRestart` (pre-swap, every process stale) and `runHostRestart` (`gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]`: plan, run, verify for up to 180 s with the warm-socket probe `probeCliSocket`). Tests: `upgrade-restart.test.ts`.-- `src/core/upgrade-restart.ts` — GBRA-175: the pure half of the upgrade restart. `collectHostProcesses` (the process table is the authority: a heartbeat, PID-file or registry record whose pid `ps` does not show as gbrain is dropped; `gbrainEntry` skips wrappers such as tini, and a process's parent is its nearest gbrain ancestor), `planRestart` (a service restarts only processes under its manager's pid; `supervisorRestartArgv` keeps the launch options and PID file; anything else is a `ManualStep`), `runRestartSteps`, `restartProblems` (old pids gone, one build, roles and the supervised worker back, warm socket accepts) and `unverifiedBuilds`. A stale process whose `install_root` is another install than the one being upgraded gets a `replace_copy` step first when it is a Bun global copy (`bunGlobalCopyOf`: probe the tag, `bun remove -g` then `bun add -g` under its `BUN_INSTALL`, restore on failure), else a manual step from `copyFix`; after the restart `mismatchedBuilds` names any process back on another build, and the host's `mismatchFix` chains that replacement with `gbrain upgrade --restart-only`.+- `src/core/upgrade-restart.ts` — GBRA-175: the pure half of the upgrade restart. `collectHostProcesses` (the process table is the authority: a heartbeat, PID-file or registry record whose pid `ps` does not show as gbrain is dropped; `gbrainEntry` skips wrappers such as tini, and a process's parent is its nearest gbrain ancestor), `planRestart` (a service restarts only processes under its manager's pid; `supervisorRestartArgv` keeps the launch options and PID file, read from `--pid-file <path>`, and drops a `--flag=value` token that is neither a global flag nor `--job-isolation=`, because the supervisor that holds it ignored it and this build's `=` gate refuses it (#7619); anything else is a `ManualStep`), `runRestartSteps`, `restartProblems` (old pids gone, one build, roles and the supervised worker back, warm socket accepts) and `unverifiedBuilds`. A stale process whose `install_root` is another install than the one being upgraded gets a `replace_copy` step first when it is a Bun global copy (`bunGlobalCopyOf`: probe the tag, `bun remove -g` then `bun add -g` under its `BUN_INSTALL`, restore on failure), else a manual step from `copyFix`; after the restart `mismatchedBuilds` names any process back on another build, and the host's `mismatchFix` chains that replacement with `gbrain upgrade --restart-only`.- `src/commands/watch.ts` — `gbrain watch`: the push transport. Reads turns from stdin as they arrive (`user:`/`assistant:` prefixes; unprefixed = user turn), keeps a rolling in-process window (`--window-turns`, default 4), calls `volunteerContext` per turn, streams pointers to stdout (`--json` for JSONL with turn attribution), logs `channel: 'watch'` events with a per-session id. Session dedupe feeds already-pushed slugs back as priorContext so the core's slug-only suppression dedupes. Blocks in the stdin iteration (interactive alive until Ctrl-C/Ctrl-D; piped ends at EOF) — deliberately NOT in DAEMON_COMMANDS; SIGINT closes the stream so teardown flows through finishCliTeardown. Per-turn resolution failures are fail-open. Registered in CLI_ONLY + CLI_ONLY_SELF_HELP + THIN_CLIENT_REFUSED_COMMANDS (thin clients use the `volunteer_context` MCP op). Pinned by `test/watch-command.test.ts`.diff --git a/docs/architecture/key-files/entrypoints-and-docs.md b/docs/architecture/key-files/entrypoints-and-docs.mdindex c7aeaad728..b074d350f6 100644--- a/docs/architecture/key-files/entrypoints-and-docs.md+++ b/docs/architecture/key-files/entrypoints-and-docs.md@@ -122,7 +122,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGELSize ceiling (`src/cli/main.ts`): `scripts/module-size-limits.tsv` (per-change raise history: `git log -p` on that file). The ceiling covers `handleCliOnly`'s explicit ordered pipeline (`@cliPipelineStage` functions: thin-client guard, deferred-persistence routing, subcommand and help routes, read-only timeout path, sync watchdog and delegation, connectEngine terminator with degraded-serve recovery, teardown), thin-client routing and refusal, help and self-help text, strict flag parsing and process-exit teardown. Per-command dispatch (pre- and post-connect) lives in the command table (entry below), not in `src/cli/main.ts`.- `src/cli/remember-format.ts` — the `remember` human formatter (`formatRememberResult`: status, entity with `(inferred from mention)`, expiry, degraded dedup, a `note: private` line when the call passed `visibility: private` (#6606; read from the params, so it prints when the write ran on a serve owner too), `warnings` + `hint`), kept out of `src/cli.ts`; `--json` prints the raw envelope. Pinned by `test/remember-entity-inference.test.ts`.-- `src/cli/subcommands.ts` + `src/cli/router-help.ts` + `src/cli/strict-args.ts` — help never acts (#6114). `subcommands.ts` holds each router command's inventory (`ROUTERS`: pages, cache, integrity, hook, search, edge-proposals, schema, config, quarantine, core, loops; each router re-exports its list as `SUBCOMMANDS` and types its dispatch over it, so an unlisted subcommand fails typecheck) and the help grammar: `--help`/`-h` anywhere before `--` (a flag-value slot included) and a bare `help` only as the first token after a router command or one of its subcommands (`search help` stays a query). `cli.ts` decides `cliHelpRequested` once, before the update marker, backup nag and key warnings; on help it calls `printRouterHelp`, which loads only the router's `printUsage`, before any subcommand, thin-client route or engine. `strict-args.ts` is the per-subcommand table for destructive subcommands (pages purge-deleted, cache clear/prune, schema use/downgrade/init/remove-*, integrity auto/reset-progress, search modes --reset and its `--mode <mode>` preview, W4.13: `--source <mode>` is the deprecated alias, and the handler refuses a missing value or conflicting `--mode`/`--source` with exit 2 instead of resetting): an argument the handler would ignore refuses with `invalid_params` (exit 2) after help and before dispatch, with a read-only fix that itself parses under the table (`ask_user` for integrity reset-progress). `STRICT_SELF_HELP_SUBCOMMANDS` is the same table for a self-help command that prints its own per-subcommand help instead of a router inventory: `skillpack reference` (#5491) accepts `<name>` or `--all`, `--workspace`, `--since`, `--apply-clean-hunks`, `--dry-run` and `--json`, so a `--dry-run=true`, a typo or an unknown flag refuses before the apply instead of running it with the flag ignored (the `--harness` lane keeps its own parser; `src/commands/skillpack/reference.ts` re-checks on entry so an in-process caller gets the same refusal). The flag-registry generator skips `strict-args.ts` (its literals belong to the commands it lists). Pinned by `test/cli-help-grammar.test.ts` and the four-part subprocess gate `test/cli-help-no-side-effects*.serial.test.ts` (harness `test/helpers/cli-help-gate.ts`, child probe `test/helpers/cli-side-effect-probe.ts`): every self-help command's `--help`/`-h` and every router subcommand's `--help`/`-h`/`help` on a copy of a seeded PGLite brain, asserting exit 0 with usage, unchanged table rows and HOME/cwd files, and no fetch or spawn. `quarantine` (list, clear, scan) is a router since #6259. `core` and `loops` are routers since #6521: as SELF_HELP_WITHOUT_ENGINE entries their handlers answered help only as the first token, so `core list --help` ran `list` against the null engine (`internal_error: null is not an object`) and `loops show --help` exited 2; `transcripts` keeps its per-subcommand help (`recover --help` prints a dedicated usage) and its handler answers the flag for `status` itself. `test/cli-help-without-brain.test.ts` runs an explicit brainless table of these invocations next to the gate's router walk.+- `src/cli/subcommands.ts` + `src/cli/router-help.ts` + `src/cli/strict-args.ts` — help never acts (#6114). `subcommands.ts` holds each router command's inventory (`ROUTERS`: pages, cache, integrity, hook, search, edge-proposals, schema, config, quarantine, core, loops; each router re-exports its list as `SUBCOMMANDS` and types its dispatch over it, so an unlisted subcommand fails typecheck) and the help grammar: `--help`/`-h` anywhere before `--` (a flag-value slot included) and a bare `help` only as the first token after a router command or one of its subcommands (`search help` stays a query). `cli.ts` decides `cliHelpRequested` once, before the update marker, backup nag and key warnings; on help it calls `printRouterHelp`, which loads only the router's `printUsage`, before any subcommand, thin-client route or engine. `strict-args.ts` is the per-subcommand table for destructive subcommands (pages purge-deleted, cache clear/prune, schema use/downgrade/init/remove-*, integrity auto/reset-progress, search modes --reset and its `--mode <mode>` preview, W4.13: `--source <mode>` is the deprecated alias, and the handler refuses a missing value or conflicting `--mode`/`--source` with exit 2 instead of resetting): an argument the handler would ignore refuses with `invalid_params` (exit 2) after help and before dispatch, with a read-only fix that itself parses under the table (`ask_user` for integrity reset-progress). `STRICT_SELF_HELP_SUBCOMMANDS` is the same table for a self-help command that prints its own per-subcommand help instead of a router inventory: `skillpack reference` (#5491) accepts `<name>` or `--all`, `--workspace`, `--since`, `--apply-clean-hunks`, `--dry-run` and `--json`, so a `--dry-run=true`, a typo or an unknown flag refuses before the apply instead of running it with the flag ignored (the `--harness` lane keeps its own parser; `src/commands/skillpack/reference.ts` re-checks on entry so an in-process caller gets the same refusal). `strictSpecFor(command, subArgs)` is the one lookup of a subcommand's spec, shared by `strictArgsRefusal` and the CLI entry's `=` gate, which leaves a strict subcommand's argv to this table. The flag-registry generator skips `strict-args.ts` (its literals belong to the commands it lists). Pinned by `test/cli-help-grammar.test.ts` and the four-part subprocess gate `test/cli-help-no-side-effects*.serial.test.ts` (harness `test/helpers/cli-help-gate.ts`, child probe `test/helpers/cli-side-effect-probe.ts`): every self-help command's `--help`/`-h` and every router subcommand's `--help`/`-h`/`help` on a copy of a seeded PGLite brain, asserting exit 0 with usage, unchanged table rows and HOME/cwd files, and no fetch or spawn. `quarantine` (list, clear, scan) is a router since #6259. `core` and `loops` are routers since #6521: as SELF_HELP_WITHOUT_ENGINE entries their handlers answered help only as the first token, so `core list --help` ran `list` against the null engine (`internal_error: null is not an object`) and `loops show --help` exited 2; `transcripts` keeps its per-subcommand help (`recover --help` prints a dedicated usage) and its handler answers the flag for `status` itself. `test/cli-help-without-brain.test.ts` runs an explicit brainless table of these invocations next to the gate's router walk.- `src/cli/command-table.ts` + `src/cli/commands/<name>.ts` — one record per CLI-only command (`name`, `phase`, `thinClient`, `selfHelp`, `skipStartupHooks`, `load: () => import('<literal>')`, and the agent-contract fields `json`, `read_only`, `startup`, `end_of_options`, `help: () => import('./help/<name>.ts')` — see `src/cli/help/` in [agent contract](agent-contract.md)). A `selfHelp` record whose handler needs an engine answers `--help` brainless through `SELF_HELP_WITHOUT_ENGINE` in `src/cli.ts` (an explicit loader, or `true` to run the record's own module with a null engine). The records derive `CLI_ONLY`, `CLI_ONLY_SELF_HELP`, `THIN_CLIENT_REFUSED_COMMANDS` and `STARTUP_HOOK_SKIP_COMMANDS` (re-exported from `src/cli.ts`); `cliAliases`' collision check runs over the derived `CLI_ONLY`. Each module holds the body its switch case or plain branch had, moved verbatim, and receives dispatcher-owned pieces through `CliDispatchContext`. Master's membership inconsistencies are preserved (the dead second `auth` branch, the unreachable `capture --help` branch, the `connectors` and `recall` refuse hints that only `connectEngine`'s thin-client backstop reaches (the static extractor reports them as never reached), `watch` refused without a hint, `eval whoknows` shadowed by the refusal) and pinned by `test/fixtures/goldens/cli/membership-sets.json`. Contract: `test/cli-command-table.test.ts`; engine lifecycle per path: `test/cli-dispatch-lifecycle.serial.test.ts`. `json` / `jsonSubcommands` declare the D2 `--json` contract (record-wide / per subcommand).- `scripts/build-fence-format.ts` — #6188 renders the generated region of `docs/guides/fence-format.md` (between `BEGIN/END GENERATED fence-format`) from the fence constants: markers, the column tables and layouts from `schema.ts` (`COLUMNS`, `BASE_WIDTH`, `MIN_CELLS`, `CANONICAL_HEADER`, `ALLOWED`, `COLUMN_DEFAULTS`, `NAMED_COLUMNS`, `TOLERATED_TRAILING`, `HEADER_ALIASES`), holder outcomes computed with `isValidHolder`/`holderAlias`, the Tier 1 rule table from the synonym tables (bound to `FixClass` by `satisfies`), screen reasons grouped by tier and the gate table from `reasons.ts`. It parses both synthetic examples with the strict parsers and throws on any warning. `--check` exits 1 when the committed region is stale. Drift test: `test/fence-format-reference.test.ts` (the region, the examples, the reference's links, and one `fence-<reason>` row per reason in `write-refusals.md` with the reason table's tier and auto-retry and a link into the reference).@@ -130,7 +130,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `scripts/lib/cli-pipeline.ts` — flattens `handleCliOnly` (inlining `@cliPipelineStage` functions) and reads the command table by AST, for the W0 dispatch-shape extractor (`test/helpers/cli-dispatch-extract.ts`) and `scripts/generate-flag-registry.ts`.- `src/core/operation-manifest.generated.ts` + `scripts/build-operation-manifest.ts` (`bun run build:operation-manifest`, in `regen:all`) — every operation in `src/core/operations.ts` minus its handler, in registry order (`OperationMeta` in `src/core/ops/contract.ts`). `gbrain serve` (stdio initialize/tools/list, surface and publish-gate filtering, skill-resource permission checks) and the CLI dispatcher (`src/cli/op-manifest.ts`: command, alias, flag and help lookup plus the A1 fix-routing registration) read it, so neither loads the handler graph until an op runs. Freshness, equality with the live registry, and the absence of `operations.ts`/`dispatch.ts` from the serve and dispatcher import graphs are pinned by `test/operation-manifest.test.ts`. The same script writes `src/core/operation-loaders.generated.ts`: each op's defining module (`verbs.ts` or `ops/*.ts`) and export, as string-literal `import()`s. `src/core/operation-load.ts` holds the one finalize step (central `OP_AREAS` + the output-redaction wrapper, idempotent per op object) that `operations.ts` applies to the registry, and `loadOperation(name)`, which `runSharedOperation` uses to load and finalize only the op it runs; `test/cli-cold-start-graph.test.ts` pins that a lone load is the registry's object in the registry's state.-- `src/core/cli-flag-registry.generated.ts` (strict flag validation in `src/cli/main.ts`) + `scripts/generate-flag-registry.ts` — pre-dispatch, pre-engine unknown-flag rejection for every command: a flag no handler consults fails loud (`unknown flag --x for 'gbrain <cmd>'`, exit 1; `--json` invocations also get a structured `{status:'error', reason:'invalid_flag'}` on stdout) instead of being silently ignored while the un-asked-for real operation runs. `validateCommandFlags(command, subArgs)` runs after the `--help` short-circuit and before any dispatch or engine connect, in two lanes mirroring dispatch order (CLI_ONLY first — `think`/`salience`/`anomalies` are both ops AND CLI_ONLY members whose handlers parse flags the op contract doesn't declare): CLI_ONLY commands validate against the generated `CLI_FLAG_REGISTRY` (per-command legal sets derived from each command's source — its `src/cli/commands/` module and pipeline branches + imported modules + one level of relative imports + `EXTRA_FLAGS` + `DELEGATED_MODULES`, the modules a command hands its argv to through a nested handler (auth → `persistence-admin.ts` and `grants/cli.ts`), scanned at module depth without their imports so their safety-flag reads count as consumption; deliberately over-inclusive, help-text mentions count, but `//` and `/* */` comments are stripped at every depth before the scan — a helper's doc comment naming `--fresh` must not legalise it for a command that only imports one function from that helper; regenerate via `bun run build:flag-registry`); op commands validate via `findUnknownOpFlag`, which mirrors `parseOpArgs`'s traversal (non-boolean flags consume their value token; `--key=value` inline form recognized) plus the CLI-local flags consumed outside the op contract (`json`, `explain`, `help`, `source`, `dry-run`); the CLI_ONLY token scan is the exported `findUnknownFlag(args, legal)`. `parseOpArgs` also refuses to let a non-boolean flag swallow a token that is itself a known flag of the same command (op-contract param, a CLI-local, or the `--no-<boolean>` form): `gbrain put x --content --source default` fails with `--content requires a value, but '--source' is a flag; omit --content (or put it last) to read stdin` (exit 1, pre-write) instead of storing the literal `--source` as the page body. A value that merely starts with `--` but names no flag of this command stays a value; the shared `isKnownOpFlag` predicate (`src/core/op-flag-tokens.ts`) sits next to `isBooleanLiteral` so parser and validator cannot disagree. In `parseOpArgs`, `json`/`dry_run` are CLI-local booleans that never consume a value token, so a trailing `--dry-run` is a real rehearsal switch feeding `makeContext`'s `ctx.dryRun`. Uppercase flag spellings are treated as unknown (every handler is case-sensitive-lowercase, so they'd be silently ignored downstream — the exact class the validator kills). Exempt by contract: `call` (arbitrary `--param` interface), `config` (arbitrary set values), `jobs submit` (handler-defined payload params); everything after a literal `--` is passthrough and never validated. A command missing from the registry fails OPEN at runtime (never bricks a command); `test/cli-flag-validation.test.ts` pins registry freshness, per-command drift, and consumption evidence — a safety flag (`--dry-run`, `--yes`, `--force`) may only be advertised if the command's source actually reads it. The generator segments `handleCliOnly` into per-command text blocks with `segmentDispatchBlocks`: both `case 'X':` labels and every `if (command === 'X' …)` head — plain, compound (`&& args[0] === 'sub'`: the no-DB `eval <sub>` bypasses such as `eval longmemeval`, the `<cmd> --help` pre-engine branches, `agent register`) and multi-line — are markers, and ownership follows the `command === 'X'` head, never the condition's tail, so a compound block's flags land on its own command's row (the `eval` row is a union across eval subcommands, the registry's shape for every multi-subcommand command); a bare `command === 'X'` inside a non-`if` expression is deliberately not a marker. Only `import('./commands/*.ts')` inside a block counts as a command module (core helpers a block reaches for directly are not scanned — a flag the block consumes through one is already a literal in the block's own text), and `isValueOnlyImport` skips a destructured import whose bindings are all SCREAMING_CASE constants (a borrowed message string, not a handler). Pinned by `test/generate-flag-registry.test.ts` (acceptance AND rejection: `--frobnicate` is still refused) and `test/eval-longmemeval-cli-smoke.test.ts` (the documented `gbrain eval longmemeval … --retrieval-only --by-type --no-trajectory --keyword-only` invocation exits 0 as a subprocess).+- `src/core/cli-flag-registry.generated.ts` (strict flag validation in `src/cli/main.ts`) + `scripts/generate-flag-registry.ts` — pre-dispatch, pre-engine unknown-flag rejection for every command: a flag no handler consults fails loud (`unknown flag --x for 'gbrain <cmd>'`, exit 1; `--json` invocations also get a structured `{status:'error', reason:'invalid_flag'}` on stdout) instead of being silently ignored while the un-asked-for real operation runs. `validateCommandFlags(command, subArgs)` runs after the `--help` short-circuit and before any dispatch or engine connect, in two lanes mirroring dispatch order (CLI_ONLY first — `think`/`salience`/`anomalies` are both ops AND CLI_ONLY members whose handlers parse flags the op contract doesn't declare): CLI_ONLY commands validate against the generated `CLI_FLAG_REGISTRY` (per-command legal sets derived from each command's source — its `src/cli/commands/` module and pipeline branches + imported modules + one level of relative imports + `EXTRA_FLAGS` + `DELEGATED_MODULES`, the modules a command hands its argv to through a nested handler (auth → `persistence-admin.ts` and `grants/cli.ts`), scanned at module depth without their imports so their safety-flag reads count as consumption; deliberately over-inclusive, help-text mentions count, but `//` and `/* */` comments are stripped at every depth before the scan — a helper's doc comment naming `--fresh` must not legalise it for a command that only imports one function from that helper; regenerate via `bun run build:flag-registry`); op commands validate via `findUnknownOpFlag`, which mirrors `parseOpArgs`'s traversal (non-boolean flags consume their value token; `--key=value` inline form recognized) plus the CLI-local flags consumed outside the op contract (`json`, `explain`, `help`, `source`, `dry-run`); the CLI_ONLY token scan is the exported `findUnknownFlag(args, legal)`, defined in `src/cli/flag-equals.ts` and re-exported by `main.ts`; that module's `=` gate (`cliOnlyFlagArgs`, see [agent contract](agent-contract.md)) splits, keeps or refuses each `--flag=value` token before this scan runs. `parseOpArgs` also refuses to let a non-boolean flag swallow a token that is itself a known flag of the same command (op-contract param, a CLI-local, or the `--no-<boolean>` form): `gbrain put x --content --source default` fails with `--content requires a value, but '--source' is a flag; omit --content (or put it last) to read stdin` (exit 1, pre-write) instead of storing the literal `--source` as the page body. A value that merely starts with `--` but names no flag of this command stays a value; the shared `isKnownOpFlag` predicate (`src/core/op-flag-tokens.ts`) sits next to `isBooleanLiteral` so parser and validator cannot disagree. In `parseOpArgs`, `json`/`dry_run` are CLI-local booleans that never consume a value token, so a trailing `--dry-run` is a real rehearsal switch feeding `makeContext`'s `ctx.dryRun`. Uppercase flag spellings are treated as unknown (every handler is case-sensitive-lowercase, so they'd be silently ignored downstream — the exact class the validator kills). Exempt by contract: `call` (arbitrary `--param` interface), `config` (arbitrary set values), `jobs submit` (handler-defined payload params); everything after a literal `--` is passthrough and never validated. A command missing from the registry fails OPEN at runtime (never bricks a command); `test/cli-flag-validation.test.ts` pins registry freshness, per-command drift, and consumption evidence — a safety flag (`--dry-run`, `--yes`, `--force`) may only be advertised if the command's source actually reads it. The generator segments `handleCliOnly` into per-command text blocks with `segmentDispatchBlocks`: both `case 'X':` labels and every `if (command === 'X' …)` head — plain, compound (`&& args[0] === 'sub'`: the no-DB `eval <sub>` bypasses such as `eval longmemeval`, the `<cmd> --help` pre-engine branches, `agent register`) and multi-line — are markers, and ownership follows the `command === 'X'` head, never the condition's tail, so a compound block's flags land on its own command's row (the `eval` row is a union across eval subcommands, the registry's shape for every multi-subcommand command); a bare `command === 'X'` inside a non-`if` expression is deliberately not a marker. Only `import('./commands/*.ts')` inside a block counts as a command module (core helpers a block reaches for directly are not scanned — a flag the block consumes through one is already a literal in the block's own text), and `isValueOnlyImport` skips a destructured import whose bindings are all SCREAMING_CASE constants (a borrowed message string, not a handler). Pinned by `test/generate-flag-registry.test.ts` (acceptance AND rejection: `--frobnicate` is still refused) and `test/eval-longmemeval-cli-smoke.test.ts` (the documented `gbrain eval longmemeval … --retrieval-only --by-type --no-trajectory --keyword-only` invocation exits 0 as a subprocess).- `src/schema.sql` — Full Postgres + pgvector DDL: canonical for every table except the TS fragment tables, whose `BEGIN/END GENERATED` regions are rewritten from the fragment modules; `bun run build:schema` derives schema-embedded.generated.ts and the PGLite template from it (`docs/ENGINES.md#canonical-schema-sources`)diff --git a/docs/architecture/key-files/managed-sync-bookkeeping.md b/docs/architecture/key-files/managed-sync-bookkeeping.mdindex f630c4760a..b82cadb18f 100644--- a/docs/architecture/key-files/managed-sync-bookkeeping.md+++ b/docs/architecture/key-files/managed-sync-bookkeeping.md@@ -46,7 +46,7 @@ run, and the supersession of a checkpoint whose cursor another run replaced. The- `src/core/persistence/sync-ghosts.ts` — #6712 PR 2: `countSyncGhosts(engine, sourceId)`, the post-sync ghost count. It reuses `scanGhostSource` from `repair/ghost-pages.ts` (no second classifier) with a candidate bound of `SYNC_GHOST_CHECK_LIMIT` (50) stats, leaves out paths sync holds (a held file is the hold's to explain), and returns the count, samples and the `gbrain repair ghost-pages --source <id>` preview as its fix. Sync never deletes or tombstones a ghost; `commands/sync/perform.ts` prints one line and sets `SyncResult.ghostPages`. Test: `test/sync-exits-l4-6712.test.ts`. GBRA-133 2b.2: the count is answered from the last scan (op_checkpoints op `sync-ghost-report`, fingerprint the source id); an atomic claim on that row starts the next scan in the background at most once per `GBRAIN_SYNC_GHOST_INTERVAL_MS` (default 300000) per source, and only after a sync landed since the last claim (`sources.last_sync_at`), so a cancelled sync writes nothing. The sync never waits for the scan; a CLI exit waits within the background-work drain budget and an engine disconnect aborts it. `syncGhostDecisions` records each decision for tests.- `src/core/persistence/soak-counters.ts` — #6712 PR 2: the soak counters doctor `sync_soak_counters` reports (one `op_checkpoints` row per UTC day under op `sync-soak-counters`). Interventions: `sync_non_plain` (`nonPlainSyncFlags`, from `sync/run.ts`), `repair_apply` (`repair.ts`), `unblock_apply` (`sync/operator.ts`), `retry_held` (`sources-retry-held.ts`) and `needs_human` (`sweepNeedsHumanHolds`, run after each managed sync: stamps `needs_human_at` on a hold the fault table now calls `needs_human` and counts it once; the stamp survives same-code re-holds). Content decisions: `file_drift_apply` and `file_drift_hold`. `readSoakCounters` sums the last seven days. Counting never fails the command that counts. Test: `test/sync-exits-l4-6712.test.ts`.- `src/commands/doctor/checks/managed-sync-movement.ts` + `src/core/persistence/sync-movement.ts` — #6317 (B4, I2): the movement reader and its doctor check. `readManagedSyncMovement` snapshots, per active managed source, the newest `completed_at` of committed `managed_sync_*` receipts in the current source incarnation (the watermark: one probe of the partial index `persistence_requests_sync_watermark`, v223; a count would shrink under compaction), the head claim's `step_since`, the `managed-sync` cursor (`index/total`, `held`) and `sources.last_sync_at`/`last_commit`, and whether a drain or full consumer is live on the owner host. `data_moving` is false when an unfinished cursor has had neither a committed receipt nor a head step advance for longer than `persistence.preparation_ceiling_ms` while a consumer is live; with none live the state is `parked` (informational). `sources status --json` and `writer status --json` print `data_moving`, `not_moving_since` and `movement_state` beside `sync_running`, and `sources status` prints the writer-status command beside `data_moving: false`; doctor `managed_sync_not_moving` (warn, scored for `not_moving` only) uses the same rule and command as its fix, and fails on a parked cursor whose admitted queue has no consumer past the ceiling (#6552; fix: the resume sync); `serve` prints one `[gbrain notice]` when a source flips. A failed backlog read is `unknown`, never `nothing_pending` (doctor warns). `/health` stays liveness-only.-- `src/commands/sources-writer-movement.ts` — #6317 (I2): `gbrain sources writer movement [<source>] [--wait <dur>] [--warn-only] [--json]`, the deploy gate `gbrain upgrade` and `post-upgrade` end by printing (bare, so it inherits the default window; neither runs it, because neither restarts the resident processes). The printed step is `MOVEMENT_SUPERVISOR_STEP` from the import-free leaf `src/commands/movement-step.ts` (re-exported here), so upgrade loads it before the swap (#6604). Same source selection as `writer status` (`persistence-admin.ts`). It snapshots through `sync-movement.ts`, waits `max(300 s, preparation budget + 60 s)` (printed as the effective budget; `--wait <dur>` takes sync's duration syntax) and judges each source: `moved` (a new committed publication; a cursor advanced only by holds or a `last_sync_at` touched by an up-to-date check is not movement) and `current` exit 0; `held` exits 0 with a warning and the hold kind's route (`gbrain repair fences --source <id>`; `preparation_stalled` → writer status, then `gbrain sources retry-held <id>`); `within_allowance` (the head's step advanced inside the window) exits 0 with `retry_after_ms`; `not_moving` exits 1 with `managed_sync_not_moving` (`reason: movement_check`, `fix.argv` the writer-status command, `fix.verify` this command); `unknown` (backlog unreadable) exits 1 with `movement_unknown`; other read failures keep their code. `--warn-only` prints the same envelopes and exits 0. Flags are regenerated into `src/core/cli-flag-registry.generated.ts` with `bun run build:flag-registry`.+- `src/commands/sources-writer-movement.ts` — #6317 (I2): `gbrain sources writer movement [<source>] [--wait <dur>] [--warn-only] [--json]`, the deploy gate `gbrain upgrade` and `post-upgrade` end by printing (bare, so it inherits the default window; neither runs it, because neither restarts the resident processes). The printed step is `MOVEMENT_SUPERVISOR_STEP` from the import-free leaf `src/commands/movement-step.ts` (re-exported here), so upgrade loads it before the swap (#6604). Same source selection as `writer status` (`persistence-admin.ts`). It snapshots through `sync-movement.ts`, waits `max(300 s, preparation budget + 60 s)` (printed as the effective budget; `--wait <dur>` takes sync's duration syntax) and judges each source: `moved` (a new committed publication; a cursor advanced only by holds or a `last_sync_at` touched by an up-to-date check is not movement) and `current` exit 0; `held` exits 0 with a warning and the hold kind's route (`gbrain repair fences --source <id>`; `preparation_stalled` → writer status, then `gbrain sources retry-held <id>`); `within_allowance` (the head's step advanced inside the window) exits 0 with `retry_after_ms`; `not_moving` exits 1 with `managed_sync_not_moving` (`reason: movement_check`, `fix.argv` the writer-status command, `fix.verify` this command); `unknown` (backlog unreadable) exits 1 with `movement_unknown`; other read failures keep their code. `--warn-only` prints the same envelopes and exits 0. `parseMovementArgs` refuses `--json` or `--warn-only` written with a value (`invalid_params`), except `--json=true`, which it reads as `--json` (#7619). Flags are regenerated into `src/core/cli-flag-registry.generated.ts` with `bun run build:flag-registry`.- `src/core/serve-head-watcher.ts` + `src/core/persistence/sync-freshness.ts` + `src/commands/doctor/checks/managed-sync-latency.ts` — #6858 ask 6: on-commit sync and its latency metric. `startServeHeadWatcher` (two call sites: `installResidentTickers` in `src/commands/serve.ts`, stopped before `shutdownDelegatedSync`, and `runServeHttp` in `src/commands/serve-http.ts`, beside `startMovementWatch` and stopped on the same shutdown path) re-reads `sync.on_commit` every 30 s; while on it polls `git rev-parse HEAD` in each managed source checkout this host owns (`GBRAIN_SERVE_HEAD_POLL_MS`, default 3 s; an `fs.watch` on the git dir only nudges the poll), debounces 3 s (`GBRAIN_SERVE_HEAD_DEBOUNCE_MS`) and starts one managed sync through the unchanged `startDelegatedSync` with this host's `cli` registration. It never starts beside a running delegated sync or a held drain lease (the move stays pending and fires once after), skips a HEAD `sources.last_commit` already has, resumes a resumable stop up to `MAX_RESUMES`, and logs each distinct error once. `readSyncFreshness` samples committed `managed_sync_import` receipts of the last 24 h (not first syncs or working-tree entries): commit time is the git committer time of `intent.target`, searchable is `completed_at`, embedded is the page's newest `content_chunks.embedded_at` once every chunk has one, sampled only from a receipt no later committed write to the same page supersedes and only at or after its `completed_at`; p50/p95 in one aggregate over the `persistence_requests_sync_watermark` predicate. #7604: the supersede check reads the newest committed sequence per (source, slug) once, over the rows after the oldest sample (a materialized CTE), so the read stays linear in the samples after a killed pass leaves tens of thousands of receipts (a per-receipt subquery is quadratic and reaches the 300 s statement timeout). `gbrain sync status` (the `freshness` block) and `gbrain status` print it; doctor `managed_sync_latency` grades p95 against `sync.freshness_target_seconds` (default 300; fail over max(1 h, target)) only with `sync.on_commit` on or a target set. Tests: `test/serve-head-watcher.test.ts`, `test/serve-head-watcher-managed.serial.test.ts`, `test/serve-http-head-watcher.serial.test.ts`, `test/sync-freshness-6858.test.ts`. #7189: each `SourceFreshness` carries `behind` (`readGitBehind`, injectable `BehindReader`: `rev-list --count <last_commit>..HEAD` and the oldest of those commits' committer age; null without a checkout or a synced commit), printed by `formatSyncFreshness`.- `src/core/persistence/sync-status.ts` (status coherence) — GBRA-150: `state: blocked` means the source cannot advance (the drain outcome's meaning); a file hold that waits on a person while the source keeps syncing reads `synced` with reason `held_needs_human`, `needs_human` and `next` unchanged (`test/sync-status-blocked-definition.test.ts`); `detail` adds `landing` / `landing_read` (`landing-gaps.ts`). #7189: a `last_error` whose cursor failure row (`op_checkpoints` `managed-sync-failure`) is older than the source's newest committed managed-sync receipt carries `superseded` and sets neither `needs_human`, `state` nor `next` (`liveError`); `needs_human_from` names the hold or the error. #7243 (GBRA-133 PR 3a): every status carries `last_commit` (`sources.last_commit`) and `live` (the drain-lease holder still renewing it, from `readDrainLease`, read only when the source read's `gbrain_cycle_locks` probe finds a row, with `job_id` for a Minions sync job and `stalled` from `holderStalled`; #7596: a holder that stopped renewing the lease (`readDrainLease`, `drainLeaseLive`) is not `live`, and an open pass with no live holder reads `pass_interrupted` (`passStatusState`) with an `interrupted` block (pass, last row write, the dead holder), which `sync-blocked.ts` also lists for doctor `managed_sync_blocked`; test `test/sync-pass-interrupted-7596.test.ts`; `live_job_id` also takes a job holder of a pass); `supersedingAttempt` marks a `last_error` `superseded` (`by`, `age_seconds`) when evidence newer than the failure row passed its phase (`resume` < `discovery` < `freeze`/`admission` < `receipt`/`checkpoint`; evidence: the pass row's `started_at` (pin), a level read (`timings_ms` set or an `up_to_date` idle tick), an uncommitted managed import or delete admitted later, a later commit). The CLI (`sync/operator.ts` `holdsListing`) bounds the holds: `holds_summary` (`topCounts` by code and by state: `needs_human`, `actionable`, `held`) over every hold, then `PLAIN_STATUS_HOLDS` (20) rows needs-human first, or with `--detail` a page of the shared listing contract (`bounded-listing.ts`, kind `sync_status_holds:<source>:<state>`, `--limit`/`--cursor`/`--all`, `--hold-state`), `holds_page` only when a page left rows out or took a cursor, the rows last. Test: `test/sync-status-truthful-7243.test.ts` (both engines).- `src/core/persistence/resolve-paths.ts` — GBRA-150 `resolveSourcePaths`: what gbrain did with each file path of a source, by its own rules, so a landing check stops copying them. Per path: the sync slug (`resolveSlugForPath`), presence in the last synced commit and at HEAD (Git object reads), the skip reason (`unsyncableReason`, plus `typed_frontmatter` for a skipped metafile), the open hold, the live page by origin (`source_path`) and by slug (`slug_owner` when another file owns it, so a case-folded twin never reads as this file's page), a differing frontmatter `slug:`, chunk and embedding counts (`listEmbeddingStateRows` with its `slugs` filter), and one of `RESOLVE_PATH_STATES` with `searchable` (true / 'keyword' / false), `why` and an existing-command `fix`. Bounded: at most 200 paths, indexed lookups only, nothing written. Tests: `test/sources-resolve-path.test.ts`.diff --git a/docs/architecture/key-files/schema-mutation.md b/docs/architecture/key-files/schema-mutation.mdindex 90d1d1ae06..92f6d16d13 100644--- a/docs/architecture/key-files/schema-mutation.md+++ b/docs/architecture/key-files/schema-mutation.md@@ -32,7 +32,7 @@ Key files:- `src/core/schema-pack/sync.ts` — `runSyncCore(engine, opts)` chunked UPDATE in 1000-row batches per declared prefix. Concurrent writers never block on a single row >100ms. Write-side scoping via `ctx.sourceId` directly (NOT `sourceScopeOpts`, which inherits OAuth read federation). Idempotent on `--apply` re-run.- `src/commands/schema.ts` — schema CLI dispatch, including `lint [<pack>] [--with-db] [--json]`. Lint parses `--with-db` as a boolean rather than a pack name, accepts it before or after the optional pack, and rejects unknown flags, boolean values, and multiple pack positionals. The DB-backed lane resolves the active pack and runs DB-plane rules on the same connection; plain lint does not run those rules. `test/schema-cli-lint-with-db.test.ts` drives real isolated CLI subprocesses for implicit/explicit packs, JSON output, missing packs, global source flags, invalid arguments, and plain-lint separation. `withConnectedEngine` routes `loadConfig()` through the canonical `toEngineConfig()` helper and passes the complete result (`database_url` and `database_path`) to factory construction and connect, so PGLite schema commands open the configured brain. Lifecycle-grouped help text (Inspection / Activation / Authoring / Discovery+repair). Pinned by `test/schema-cli-database-path.serial.test.ts`. Help after any subcommand prints usage without running it, and `use`, `downgrade`, `init` and `remove-*` refuse arguments they would ignore (`src/cli/strict-args.ts`).- `src/commands/schema-active.ts` — `schema active [--source <id>] [--json]` (#6090). Resolves through `engineSchemaInput(engine, { remote: false, sourceId })`, the engine's own tier chain, so the per-source override (`schema_pack.source.<id>`) is honored and the output names the tier (`resolved_from`). An unregistered or archived source (`fetchSource`) refuses with `unknown_source` (fix `gbrain sources list --json`); a database that can't be read is a degraded read: stderr marker in text mode (exit 0), a `database_error` envelope carrying the file-plane answer and `degraded: true` under `--json` (nonzero). `schema.ts`'s `runActive` only parses flags and passes `withConnectedEngine`. Pinned by `test/schema-active-source.test.ts`.-- `src/commands/schema-add-type.ts` — `parseAddTypeArgs` for `schema add-type` (#6135). The type name is the first positional that is not a value-flag's value (`--primitive concept archive` names `archive`). A type needs `--prefix <dir/>` or an explicit `--no-prefix`; missing both, `--prefix` with `--no-prefix`, and `--no-prefix` with `--extractable`/`--expert` each refuse with `invalid_params` (exit 2) before the pack is touched. Each refusal's `fix.argv` is one complete corrected command with `<NAME>`/`<PRIMITIVE>`/`<PREFIX>` placeholders described in `inputs`; `NO_PREFIX_NOTE` is the success note (`note` under `--json`). Pinned by `test/schema-add-type-no-prefix.test.ts` (core mutator, batch path, CLI subprocess, and every refusal's fix parsing under the same parser). W4.10: `schemaPositionals(args, valueFlags)` (exported with `SCHEMA_PACK_VALUE_FLAGS`: `--pack`, `--source`, `--source-id`) gives every other pack-authoring subcommand in `schema.ts` (`remove-type`, `update-type`, `add|remove-alias`, `add|remove-prefix`, `add|remove-link-type`, `set-extractable`, `set-expert-routing`, `scaffold-extractable`) the same rule, with each subcommand's own value flags (`--inverse`, `--page-type`, `--target-type`, `--primitive`, `--dims`, ...); pinned by `test/schema-positionals-w410.test.ts`.+- `src/commands/schema-add-type.ts` — `parseAddTypeArgs` for `schema add-type` (#6135). The type name is the first positional that is not a value-flag's value (`--primitive concept archive` names `archive`). A type needs `--prefix <dir/>` or an explicit `--no-prefix`; missing both, `--prefix` with `--no-prefix`, and `--no-prefix` with `--extractable`/`--expert` each refuse with `invalid_params` (exit 2) before the pack is touched. Each refusal's `fix.argv` is one complete corrected command with `<NAME>`/`<PRIMITIVE>`/`<PREFIX>` placeholders described in `inputs`; `NO_PREFIX_NOTE` is the success note (`note` under `--json`). A switch written with a value (`--extractable=true`) refuses with `invalid_params`, except `--json=true`, which `runAddTypeCmd` reads as `--json` (#7619). Pinned by `test/schema-add-type-no-prefix.test.ts` (core mutator, batch path, CLI subprocess, and every refusal's fix parsing under the same parser). W4.10: `schemaPositionals(args, valueFlags)` (exported with `SCHEMA_PACK_VALUE_FLAGS`: `--pack`, `--source`, `--source-id`) gives every other pack-authoring subcommand in `schema.ts` (`remove-type`, `update-type`, `add|remove-alias`, `add|remove-prefix`, `add|remove-link-type`, `set-extractable`, `set-expert-routing`, `scaffold-extractable`) the same rule, with each subcommand's own value flags (`--inverse`, `--page-type`, `--target-type`, `--primitive`, `--dims`, ...); pinned by `test/schema-positionals-w410.test.ts`.- `skills/schema-author/SKILL.md` — Agent dispatcher for "evolve the schema pack." Triggers: 15+ phrasings incl. "add a page type", "my brain has untyped pages", "propose new types from my corpus", "backfill page types". Explicit Non-goals callout to `brain-taxonomist` (files one page) and `eiirp` (schema-check during iteration) so agents pick the right surface. 7-phase workflow: brain → assess → propose → apply → sync → verify → commit. Lists every gbrain schema CLI verb + every MCP op the skill uses. `brain_first: exempt` frontmatter. Required conformance sections: Contract, Anti-Patterns, Output Format.- `skills/conventions/schema-evolution.md` — Canonical convention: "when to add a type vs alias vs prefix." Decision tree: <20 pages → don't pack-codify; 20-100 → alias or narrow prefix on existing type; 100+ → first-class type. Don'ts section + "when to remove a type" + "when to commit the pack" all answered in one place.