drydock-cli 2.6.146__tar.gz → 2.6.147__tar.gz

drydock_cli-2.6.147/.auto_release.lock

@@ -0,0 +1 @@
+2652274

drydock_cli-2.6.147/OVERNIGHT_PROGRESS.md

@@ -0,0 +1,159 @@
+# Overnight Progress — 2026-04-20 → 2026-04-21
+
+Drop-in status doc so a fresh Claude session (after disconnect) can
+resume without relearning the last 24 hours. **Read this first, then
+`git log --oneline -20` + `TaskList` for full picture.**
+
+## What landed today (in order)
+
+| Commit | What | Where it lives |
+|---|---|---|
+| 3cb957e | pexpect-buffer trim, banner detect, ESC+/clear, force-reset, checkpoint filter | scripts/ |
+| f363ae1 | `DRYDOCK_AUTO_CONTINUE_DISABLE` env gate for agent_loop auto-Continue | drydock/core/agent_loop.py |
+| 2e0431e | Admiral actuator via SIGUSR1 — watcher asks harness to recycle TUI | scripts/stress_watcher.py + stress_shakedown.py |
+| 5c76801 | Wipe cwd down to fixtures on fresh stress start | scripts/stress_shakedown.py |
+| aafa090 | **should_break_loop dead-code fix** — user turns actually end on text responses | drydock/core/agent_loop.py:876 |
+| 1508c1b | SessionWatcher reads drydock's configured save_dir (was hardcoded ~/.drydock) | scripts/shakedown_interactive.py |
+| c77c2e0 | Hourly stress_babysitter cron | scripts/stress_babysitter.sh + crontab |
+| 0ae9d07 | Karpathy-autoresearch scaffold | research/ (kernel.py, experimenter.py, config_base.toml, mini_*) |
+| 11cfe89 | Todo loop fix (#10) + Check 0 empty-result detector + realuser prompts + raw-md detector | drydock/core/tools/builtins/todo.py, agent_loop.py, scripts/ |
+| fd7a160 | v2.6.145 release | PyPI + GitHub |
+| aad7ac6 | Admiral sees raw-markdown leakage; DEPLOYMENT.md baseline | scripts/stress_watcher.py, DEPLOYMENT.md, README.md |
+| 553926a | v2.6.146 release | PyPI + GitHub |
+
+## Long-running processes (DO NOT KILL without checking)
+
+| PID | Process | Notes |
+|---|---|---|
+| 2625579 | stress_shakedown (v10 restart #1) | auto-restarted by babysitter at 02:00 UTC after original died. Resuming from step 866. |
+| child of 2625579 | drydock TUI | Recycled periodically by admiral actuator |
+| 2366908 or newer | stress_watcher (v10) | Paired with current stress PID |
+| 2251231 | admiral_probe on :8878 | Read-only dashboard endpoint |
+| 1230765 | llm_balancer on :8001 | DO NOT KILL — proxies to vLLM, shared |
+| cron | stress_babysitter.sh hourly | Auto-restarts stress if PID dies |
+
+**v10 progress summary** (as of ~03:00 UTC 2026-04-21):
+- Original run: reached idx 972/1658 (59%) with done=866, skip=105, recycle=72 — died at ~21:00 UTC
+- Restart #1: resumed from step 866, currently at idx ~921, done=50, skip=5, recycle=3
+- Net cumulative: ~920/1658, acceptance rate still ~95%
+- Babysitter fired once (telegram sent), admiral actuator firing per run
+
+## Meta-Harness integration — in progress
+
+User approved the scope at ~03:00 local and asked for overnight build.
+See `research/domain_spec.md` for the full design (just written).
+
+**Approved mutation surface:**
+- `drydock/core/prompts/gemma4.md` (system prompt)
+- `drydock/core/prompts/cli.md` (alternate prompt)
+- admiral knob TOML (existing 7 numerics in `config_base.toml`)
+- `scripts/stress_shakedown.py` threshold constants
+  (MAX_CONSECUTIVE_SKIPS_BEFORE_RESET, SESSION_RESET_EVERY, retry windows)
+- `drydock/admiral/detectors.py` thresholds + patterns
+
+**Approved frozen:**
+- `drydock/core/agent_loop.py` (just stabilized, too risky)
+- Tool implementations
+- Provider config
+- Core stress harness flow (pexpect loop, session tracking)
+
+**Approved budget:**
+- Per candidate: 20-min mini-stress (50 prompts) as search-set, 5-min kernel as held-out smoke
+- Per 24 hr: up to ~30 candidates
+- Full 1658-prompt stress is quarterly regression only
+
+**Remaining overnight tasks:**
+1. [in progress] Expand `config_base.toml` mutation surface (tasks #16)
+2. [pending] Trace capture in `kernel.py` — save per-run artifacts to `research/traces/<exp_id>/` (task #17)
+3. [pending] `research/proposer.py` — Opus-backed proposer (task #18)
+4. [pending] `--proposer opus` flag in `experimenter.py` (task #19)
+5. [pending] Commit + let auto_release ship (task #20)
+
+**NOT running the experimenter overnight** — it would share vLLM with
+v10 stress and starve both. Scaffolded ready-to-launch.
+
+## Known issues to investigate (user-reported, not yet fixed)
+
+### 2026-04-21 03:xx user reports drydock crash with 15+ API errors
+
+User's quote:
+```
+✓ Read 0 line from prepare.py (truncated)
+✓ Read 66 lines from prepare.py
+✓ Read 66 lines from prepare.py
+✓ Read 630 lines from train.py
+✓ Read 19 lines from AGENTS.md
+
+[6 consecutive API errors (round 1/3). Compacting and retrying. Last error: API error
+from vllm (model: gemma4): LLM backend error [vllm]
+status: 400 Bad Request
+...]
+
+[Stopping: 15+ API errors. The model cannot process this request.]
+```
+
+Plus drydock self-diagnoses: "You've written prepare.py 4 times this session.
+If the file is oscillating Fix this before moving to the next file."
+
+**This is the production version of the exact wedge pattern the stress
+harness fixes.** Production drydock hits 400s, auto-compacts 2-3 times,
+then gives up at 15+ errors. It DOES have recovery — the compaction
+fires — but 15 errors in a row means compaction isn't finding enough
+context to shrink.
+
+**Root cause hypothesis:**
+- User's session accumulated large read_file results (train.py 630 lines
+  is substantial), plus prepare.py written 4 times = 4 copies of the file
+  content in history.
+- Auto-compact at 120000 tokens doesn't fire because the issue isn't
+  raw token count, it's a single turn's payload exceeding vLLM's 131K
+  context limit.
+- Compaction per-attempt only truncates old tool results; doesn't
+  dedupe repeat writes to the same file.
+
+**Fix hypothesis (for tomorrow's session):**
+- `_prune_duplicate_writes` already exists in `drydock/core/agent_loop.py`
+  but only fires when the hard-block trips on a write_file call. Extend
+  it to fire on ANY `write_file` call where the target already has ≥3
+  prior write_file entries in history.
+- Lower emergency-compact aggressiveness: when a 400 arrives, drop
+  middle-of-history message runs even if recent, not just oldest
+  truncation. The "keep first user + last 5" fallback is already there
+  (lines 834-846 of agent_loop.py).
+- Consider: hard-cap read_file results at 32KB per call regardless of
+  `max_read_bytes` config when the session has had >50k tokens of
+  tool results already.
+
+**NOT fixing overnight** — this is in `agent_loop.py` which is marked
+frozen for the meta-harness integration AND just got stabilized
+yesterday. Investigate + propose fix in morning session.
+
+## Auto-release state
+
+**Paused flag:** NOT set. Auto-release cron fires at 0/6/12/18 UTC.
+Next fire: 06:00 UTC (~03:00 local). Any commits before then ship in
+v2.6.147.
+
+**Version:** local == v2.6.146 (tagged fd7a160, aad7ac6 shipped).
+
+## Monitoring for connection loss
+
+If this Claude session disconnects:
+
+1. **v10 stress continues** — babysitter cron handles restarts. Check
+   `/tmp/stress_babysitter.log` and `~/.drydock/logs/admiral_history.log`.
+2. **Meta-harness files** are committed incrementally. `git log --oneline`
+   shows progress. Any staged-but-uncommitted changes are lost, but the
+   `domain_spec.md` alone is enough to resume.
+3. **No orphan processes** — all long-running jobs are daemonized via
+   `nohup + disown`, they survive my death.
+
+## For the next session (morning handoff)
+
+- Read `research/domain_spec.md` for the full design.
+- `git log --oneline fd7a160..HEAD` for commits since v2.6.145.
+- Check v10 state: `tail /tmp/stress_babysitter.log`.
+- Check meta-harness progress: `ls research/`, look for `proposer.py`
+  and `traces/` — if both exist, the overnight build finished.
+- **Priority for morning:** investigate the prepare.py-loop / 400-error
+  wedge the user reported. Hypothesized fixes above.

{drydock_cli-2.6.146 → drydock_cli-2.6.147}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.6.146
+Version: 2.6.147
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

{drydock_cli-2.6.146 → drydock_cli-2.6.147}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "drydock-cli"
-version = "2.6.146"
+version = "2.6.147"
 description = "Local-first CLI coding agent — tested with Gemma 4 26B via vLLM"
 readme = "README.md"
 requires-python = ">=3.12"

drydock_cli-2.6.147/research/config_base.toml

@@ -0,0 +1,209 @@
+# Baseline for the research experimenter.
+#
+# The knob array defines which admiral tunables the experimenter is
+# allowed to mutate. Bounds mirror drydock/admiral/tuning.py::KNOB_BOUNDS
+# exactly — if that file changes, mirror the change here. The kernel
+# validates bounds before writing admiral_tuning.json, so malformed
+# mutations fail fast rather than silently hitting admiral's clip.
+#
+# The experimenter NEVER edits this file. It writes to
+# research/config_best.toml on improvement. Swap this file's values
+# manually when you want to re-seed the search from a new baseline.
+#
+# FROZEN (NOT mutable — verified by experimenter before apply):
+#   - drydock/core/agent_loop.py (just stabilized 2026-04-19; untouchable)
+#   - Tool implementations (drydock/core/tools/)
+#   - Provider config
+#   - Core stress harness flow (scripts/stress_shakedown.py::run main loop)
+#
+# MUTABLE surface (what the Opus proposer may change):
+#   - Admiral knobs (the [[knob]] array below)
+#   - Env flags (the [env_flags] section below)
+#   - Stress harness thresholds (the [harness_thresholds] section below)
+#   - Admiral detector thresholds (the [admiral_detectors] section below)
+#   - System prompts (the [prompts] section below — paths to override files)
+#
+# The experimenter writes prompt overrides to:
+#     research/candidates/<exp_id>/prompts/<name>.md
+# and the kernel mounts them under the isolated HOME's prompt dir.
+
+[target]
+# admiral_tuning.json keys off (model, task). The kernel writes an entry
+# under this tuple when spawning drydock. Pick values that match what
+# admiral will classify stress-harness runs as.
+model = "mistral-vibe-cli-latest"
+task  = "unknown"
+
+# -----------------------------------------------------------------
+# Admiral knobs — bounded numeric tunables that affect agent_loop.
+# -----------------------------------------------------------------
+
+[[knob]]
+name    = "per_prompt_budget_sec"
+default = 300
+min     = 300
+max     = 3600
+mutable = true
+why     = "Hard ceiling on a single user turn. Too low wastes work; too high lets loops run wild."
+
+[[knob]]
+name    = "hard_stop_tool_calls"
+default = 100
+min     = 30
+max     = 250
+mutable = true
+why     = "HARD_STOP_CALLS in agent_loop. Cap on tool-call depth per user turn."
+
+[[knob]]
+name    = "wrap_up_warn_at"
+default = 40
+min     = 10
+max     = 100
+mutable = true
+why     = "First progressive nudge. Earlier = tighter turns, may lose quality."
+
+[[knob]]
+name    = "stop_now_warn_at"
+default = 60
+min     = 20
+max     = 150
+mutable = true
+why     = "Second progressive nudge. Gemma often ignores the wrap-up; this is the harder prod."
+
+[[knob]]
+name    = "temperature"
+default = 0.3
+min     = 0.0
+max     = 0.9
+mutable = true
+why     = "Sampling temperature. Lower = more deterministic; higher = more exploration."
+
+[[knob]]
+name    = "loop_detector_window"
+default = 3
+min     = 2
+max     = 6
+mutable = true
+why     = "How many consecutive identical tool calls trigger the loop advisor."
+
+[[knob]]
+name    = "struggle_threshold"
+default = 20
+min     = 10
+max     = 40
+mutable = true
+why     = "Reads-without-a-write before admiral fires the struggle directive."
+
+# -----------------------------------------------------------------
+# Environment flags — binary toggles the kernel sets in the TUI env.
+# -----------------------------------------------------------------
+
+[env_flags]
+DRYDOCK_AUTO_CONTINUE_DISABLE = "1"  # options: "0", "1"
+
+# -----------------------------------------------------------------
+# System prompt overrides. When `source_path` is set, the kernel
+# copies that file into the isolated HOME's prompt dir. When the
+# proposer mutates a prompt it writes to
+#     research/candidates/<exp_id>/prompts/<name>.md
+# and points the corresponding source_path here.
+# -----------------------------------------------------------------
+
+[prompts.gemma4]
+# Leave source_path empty to use the production gemma4.md shipped in
+# the installed drydock package. Opus proposer may replace this with
+# a candidate-local path.
+source_path = ""
+mutable = true
+why     = "Single highest-leverage mutable target. Governs how Gemma 4 interprets every turn."
+
+[prompts.cli]
+source_path = ""
+mutable = true
+why     = "Alternate non-Gemma system prompt. Rarely the right target but available for cross-model experiments."
+
+# -----------------------------------------------------------------
+# Stress harness threshold constants. These are hardcoded in
+# scripts/stress_shakedown.py today. The kernel reads them from here
+# via env overrides (DRYDOCK_STRESS_*) and the harness respects the
+# overrides if set, falling back to the source defaults otherwise.
+# -----------------------------------------------------------------
+
+[[harness_threshold]]
+name    = "MAX_CONSECUTIVE_SKIPS_BEFORE_RESET"
+default = 2
+min     = 1
+max     = 5
+mutable = true
+why     = "Force ESC+/clear after N consecutive SKIPs. Lower = aggressive recycling; higher = tolerant of transient wedges."
+
+[[harness_threshold]]
+name    = "SESSION_RESET_EVERY"
+default = 15
+min     = 5
+max     = 50
+mutable = true
+why     = "Periodic /clear cadence in prompts. Tight cadence bounds context but costs reset overhead every N prompts."
+
+[[harness_threshold]]
+name    = "SEND_PROMPT_RETRY_COUNT"
+default = 3
+min     = 1
+max     = 6
+mutable = true
+why     = "How many times send_prompt_and_confirm re-types before marking SKIP. Each retry is ~120s."
+
+[[harness_threshold]]
+name    = "SEND_PROMPT_WAIT_PER_RETRY_SEC"
+default = 120
+min     = 30
+max     = 300
+mutable = true
+why     = "Seconds to wait for user-msg confirmation before retyping. Tighter = faster SKIP, may miss slow prompts."
+
+# -----------------------------------------------------------------
+# Admiral detector thresholds. Currently hardcoded in
+# drydock/core/agent_loop.py and drydock/admiral/detectors.py.
+# Surface as env vars (DRYDOCK_ADMIRAL_*) that the detectors check
+# at init.
+# -----------------------------------------------------------------
+
+[[admiral_detector]]
+name    = "REPEAT_WARNING_THRESHOLD"
+default = 4
+min     = 2
+max     = 8
+mutable = true
+why     = "Consecutive identical tool calls before a WARNING. Lower = early nudge; higher = tolerant of legit repetition."
+
+[[admiral_detector]]
+name    = "REPEAT_FORCE_STOP_THRESHOLD"
+default = 8
+min     = 4
+max     = 20
+mutable = true
+why     = "Consecutive identical tool calls before FORCE_STOP. Must be >= REPEAT_WARNING_THRESHOLD."
+
+[[admiral_detector]]
+name    = "EMPTY_RESULT_THRESHOLD"
+default = 3
+min     = 2
+max     = 6
+mutable = true
+why     = "Check 0 (empty-result loop). Fire FORCE_STOP after N identical-call + empty-result in a row."
+
+[[admiral_detector]]
+name    = "SAME_TOOL_NAME_REPEAT_LIMIT_BASH"
+default = 5
+min     = 3
+max     = 10
+mutable = true
+why     = "Same-tool repetition limit for bash. Different from read/grep which need more headroom."
+
+[[admiral_detector]]
+name    = "SAME_TOOL_NAME_REPEAT_LIMIT_READ"
+default = 7
+min     = 4
+max     = 12
+mutable = true
+why     = "Same-tool repetition limit for read_file + grep. Investigation tools legitimately repeat more."

drydock_cli-2.6.147/research/domain_spec.md

@@ -0,0 +1,265 @@
+# Domain Spec: drydock stress harness
+
+Produced per stanford-iris-lab/meta-harness ONBOARDING.md template.
+First-cut spec; refine as the proposer exposes failure modes the
+current evaluation set doesn't distinguish.
+
+## Domain Summary
+
+**What the user is trying to improve:** drydock's acceptance rate,
+throughput, and user-visible reliability on stress workloads. Stable
+measurable symptoms from today's feedback session include todo-loops,
+text-only turns that don't close, unrendered markdown blobs, and
+skip-clusters on heavy prompts.
+
+**Unit of evaluation:** one stress run of 50 prompts against a
+pre-bootstrapped `tool_agent` package, hard-capped at 20 minutes. The
+kernel-5min variant (25 prompts, 5 min cap) is the held-out smoke
+test — fast signal, higher variance.
+
+**Fixed components:**
+- Base model: Gemma 4 26B-A4B-it-AWQ-4bit (served by vLLM on
+  `localhost:8000/v1`, `tool-call-parser gemma4`,
+  `enable-auto-tool-choice`, temperature 0.2, thinking high).
+- drydock core: `drydock/core/agent_loop.py` (stabilized 2026-04-19
+  after dead-code `should_break_loop` fix), tool implementations,
+  provider layer, `_check_tool_call_repetition` flow.
+- Stress infrastructure: `research/kernel.py`, `research/mini_prd.md`,
+  `research/mini_prompts.txt`, `scripts/stress_shakedown.py`'s
+  core loop (pexpect spawn / send / confirm / idle-wait).
+
+**Allowed to change (mutation surface):**
+- `drydock/core/prompts/gemma4.md` (Gemma-tuned system prompt —
+  currently the single highest-leverage mutable target).
+- `drydock/core/prompts/cli.md` (alternate prompt).
+- `research/config_best.toml` admiral knobs (7 bounded numerics:
+  per_prompt_budget_sec, hard_stop_tool_calls, wrap_up_warn_at,
+  stop_now_warn_at, temperature, loop_detector_window,
+  struggle_threshold).
+- `scripts/stress_shakedown.py` threshold constants
+  (MAX_CONSECUTIVE_SKIPS_BEFORE_RESET, SESSION_RESET_EVERY,
+  retry windows). NOT the main pexpect loop.
+- `drydock/admiral/detectors.py` thresholds + patterns (Check 0
+  empty-result match list, consecutive-empty-read escalation).
+
+**Budget:**
+- Per candidate: ~20 min (mini-stress 50 prompts) for search-set
+  evaluation; 5 min kernel for held-out smoke.
+- Per 24 hr: up to ~30 candidates. Overnight ceiling prevents
+  vLLM starvation when v10-class long stress runs are active.
+- Full 1658-prompt stress used only for quarterly regression. Not
+  a per-candidate metric.
+
+## Harness and Search Plan
+
+**Candidate harness interface:** A candidate is expressed as a
+`research/candidates/<exp_id>/` directory holding:
+- a `config.toml` (admiral knobs in the format
+  `research/config_base.toml` already defines),
+- optional `gemma4.md` / `cli.md` override files,
+- optional `stress_shakedown.patch` (unified diff against the
+  frozen main branch's `scripts/stress_shakedown.py` — applied
+  only to the kernel's isolated copy, never to source).
+
+The kernel spawns drydock with `HOME=<tmpdir>/home/` so admiral
+tuning + config isolation Just Works. Prompt overrides mount over
+`$HOME/.drydock/prompts/`.
+
+Interface compliance test: a candidate passes the interface check
+iff `kernel.py --config <candidate>/config.toml --validate-only`
+loads clean.
+
+**Useful helpers that should exist from the start:**
+- `research/proposer.py` — Opus/Claude API client that reads source +
+  recent traces + results.tsv, proposes mutations.
+- `research/kernel.py` — already in place; needs trace capture
+  extension (this task).
+- `research/experimenter.py` — already in place; needs `--proposer
+  opus` mode (this task).
+- `research/query_traces.py` — small CLI for inspecting prior
+  candidates ("show best by metric", "diff candidate A vs B",
+  "show failures with >N timeouts").
+
+**First search loop:**
+1. Warm-start: seed `config_best.toml` with current production
+   config (admiral knobs that `~/.drydock/config.toml` + admiral
+   defaults use).
+2. Run 5 random-search candidates to sanity-check the kernel
+   produces stable metrics.
+3. Switch experimenter to `--proposer opus`. First pass: contrast
+   top-3 vs bottom-3 results, propose one diff per round.
+4. Continue until random ceiling is clearly exceeded.
+
+## Evaluation Plan
+
+**Search set:** `scripts/stress_prompts_tool_agent_2000.txt` head-50
+and `scripts/stress_prompts_realuser.txt` head-50. Combined into a
+fixed `research/search_prompts_50.txt` to keep comparability.
+
+**Held-out test:** Tail-50 prompts from each file, never shown to
+the proposer during search. Only used for final validation of the
+promoted winner before shipping to `~/.drydock/config.toml` or
+`gemma4.md`. `research/holdout_prompts_50.txt`.
+
+**Primary metric:**
+```
+effective_rate = done_per_minute with cliff at >50% skip+timeout rate
+```
+(already defined in `kernel.py::run_kernel`). Higher is better.
+
+**Secondary metrics:**
+- `recycles_per_100_prompts` — how often admiral had to force-recycle
+  the TUI. Lower is better.
+- `rss_peak_mb` — pexpect buffer health proxy.
+- `raw_markdown_hits` — from the rec-check diagnostic; non-zero
+  means TUI rendering leaked.
+- `avg_assistant_ratio` — `assistant_msgs / user_msgs` in session
+  log. Healthy range 1.5–3.5; high ratios indicate Continue-loops
+  or multi-turn runaway.
+
+**Noise:** moderate. vLLM latency varies by GPU load, Gemma 4
+sampling has temperature-variance. **Replicate winners N=3 times**
+before promoting — see ONBOARDING.md's "how noisy" question. Single
+sample gates an experiment into a "short-list"; a median-of-3 gate
+is required to overwrite `config_best.toml`.
+
+**Per-candidate runtime:** 20 min mini-stress, hard-capped. Plus
+~10 s experimenter overhead. ~20.5 min/candidate round-trip.
+
+**Leakage / contamination risks:**
+- Prompts in the search set will be seen by the proposer via
+  traces. Prompts in the held-out set will NOT. Proposer context
+  filter enforces this.
+- The mini_prd.md package bootstrap happens once; repeated runs
+  against the same pre-built package are fine because admiral
+  knobs + prompts don't depend on file contents.
+- `drydock/admiral/persistence.py` caches tuning across runs; the
+  kernel's isolated HOME already addresses this (each run writes
+  its own `admiral_tuning.json`).
+
+## Baselines
+
+**Obvious hand-written baselines:**
+1. **Current production config:** `~/.drydock/config.toml` as checked
+   into `DEPLOYMENT.md` (2026-04-20). System prompt `ralph`, temp 0.2,
+   thinking high, per_prompt_budget_sec 300, hard_stop 100,
+   wrap_up_warn_at 40, stop_now_warn_at 60.
+2. **`research/config_base.toml` defaults:** the explicit mutation
+   surface's defaults. Matches production within a point or two.
+3. **"Continue-loop disabled":** flip `DRYDOCK_AUTO_CONTINUE_DISABLE=1`
+   for comparison. Known to help text-only prompts.
+4. **"Lower temperature":** temperature 0.1. Gemma 4's tool-call
+   reliability improves at low temp; hypothesis worth baselining.
+
+**Strongest current harness:** Production config + 2026-04-20 fixes
+(aafa090 should_break_loop, 11cfe89 empty-result detector, todo tool
+escalation). This is the beat-target.
+
+**Reusable helper functions available from the start:**
+- `research/kernel.py::run_kernel` — isolated-HOME stress runner.
+- `research/kernel.py::_looks_empty` (Check 0 in admiral) — empty-
+  pattern matcher.
+- `scripts/stress_shakedown.py::_count_raw_markdown_leakage` — TUI
+  rendering health check.
+- `drydock/admiral/persistence.py::TUNING_PATH` — admiral knob
+  store (isolated per kernel via HOME override).
+
+## Experience and Logging
+
+**Offline warm-start experience:**
+- `~/.vibe/logs/session/session_*/messages.jsonl` — every real
+  drydock session from 2026-03 onward. ~9300 sessions. Used by the
+  proposer to ground "what failure modes actually occur" context.
+- `~/.drydock/logs/admiral_history.log` — admiral intervention
+  history. Long-form trace of every stress-alert + stress-action.
+- `/tmp/stress_2000_v10*.log` — recent stress harness logs with
+  ~800 prompts of first-run progress + hourly babysitter restart
+  data.
+- `CLAUDE.md` — this project's design-decision log; proposer
+  should read it before proposing anything destabilizing. Already
+  describes why `agent_loop.py` is frozen, why thinking is
+  adaptive, why non-streaming for Gemma 4, etc.
+
+**Encoded references for proposer context:**
+- `DEPLOYMENT.md` — known-working config baseline.
+- `research/domain_spec.md` — this file.
+- `drydock/core/agent_loop.py` (read-only) — the proposer must know
+  the loop structure to avoid proposing mutations that would trip
+  invariants.
+
+**Per-candidate online experience:**
+- `research/traces/<exp_id>/messages.jsonl` — session log
+  copy at run end.
+- `research/traces/<exp_id>/tui.log` — pexpect PTY output.
+- `research/traces/<exp_id>/rec_check.jsonl` — extracted rec-check
+  lines + raw_md counts.
+- `research/traces/<exp_id>/summary.json` — metric, counts, config
+  hash, git commit, elapsed, note.
+
+**Metadata preserved:**
+- Full mutation diff from `config_best.toml`.
+- Git commit of drydock tree at kernel-invoke time.
+- Wall-clock start/end timestamps.
+- vLLM reachability ping before and after.
+
+**Directory structure:**
+```
+research/
+├── README.md
+├── domain_spec.md          ← this file
+├── config_base.toml        ← frozen baseline + mutation surface
+├── config_best.toml        ← current best, experimenter-managed
+├── results.tsv             ← append-only experiment log
+├── kernel.py               ← fixed 5-min runner
+├── experimenter.py         ← search orchestrator
+├── proposer.py             ← NEW: Opus-backed proposer
+├── query_traces.py         ← NEW: trace inspection CLI
+├── mini_prd.md
+├── mini_prompts.txt
+├── search_prompts_50.txt   ← NEW: search-set
+├── holdout_prompts_50.txt  ← NEW: held-out
+├── candidates/             ← NEW: promoted variants archive
+│   └── <exp_id>/
+│       ├── config.toml
+│       ├── gemma4.md        (if mutated)
+│       └── summary.json
+├── staged/                 ← in-flight variants (experimenter writes)
+└── traces/                 ← per-run artifacts
+    └── <exp_id>/
+        ├── messages.jsonl
+        ├── tui.log
+        ├── rec_check.jsonl
+        └── summary.json
+```
+
+**Query CLI (`query_traces.py`) — planned commands:**
+- `best` — show top-5 candidates by metric
+- `diff <exp_id_a> <exp_id_b>` — show config + mutation diff
+- `failures --min-timeouts 3` — list runs with >N timeouts
+- `context --top 3 --bottom 3` — produce proposer context bundle
+
+## Open Questions and Unknowns
+
+- **Opus API budget.** We haven't measured per-proposal token cost.
+  Estimate: ~40k input (source + traces) + ~2k output. At Opus
+  pricing that's ~$0.75/proposal. 30 candidates/day → ~$22.50/day.
+  Should we cap at $10/day? (Easy to add.)
+- **Replication strategy for the cliff.** Current metric has a binary
+  cliff at 50% failure. Replicating a near-cliff candidate 3 times
+  can produce high variance. May need a continuous-decay penalty
+  instead of a hard cliff. Revisit after first 20 candidates.
+- **Held-out leakage via the proposer's own context.** If the
+  proposer reads `CLAUDE.md` and `CLAUDE.md` indirectly describes
+  the held-out prompts (it currently doesn't, but future edits
+  might), leakage risk emerges. Policy: held-out prompts never
+  appear in any file the proposer reads.
+- **Unfreezing `scripts/stress_shakedown.py` fully.** Currently only
+  threshold constants are mutable. If the proposer argues for a
+  deeper change (e.g., a new recovery primitive), do we allow it?
+  Default: no; require human review + manual merge. `unknown` for
+  now.
+- **What happens to `config_best.toml` if the proposer proposes a
+  diff that doesn't apply cleanly.** Default: drop the proposal,
+  log rejection, don't penalize the proposer's "score." `unknown`
+  whether we want to feed rejection back to the proposer as a
+  learning signal.