@researai/deepscientist 1.5.15 → 1.5.17

package/docs/en/00_QUICK_START.md

@@ -13,7 +13,7 @@ You will do four things:
 
 The screenshots in this guide use the current live web UI at `deepscientist.cc:20999` as an example. Your local UI at `127.0.0.1:20999` should look the same or very close.
 
-Current platform support: DeepScientist fully supports Linux and macOS. Native Windows support is currently experimental; WSL2 remains the most battle-tested option when you need the closest Linux-like terminal behavior.
+Current platform support: DeepScientist fully supports Linux and macOS. Native Windows support is currently experimental (strongly recommend WSL2 when you want the closest Linux-like terminal behavior).
 
 ## Safety First: Isolate Before You Start
 
@@ -37,7 +37,7 @@ Prepare these first:
 
 - Node.js `>=18.18` and npm `>=9`; install them from the official download page: https://nodejs.org/en/download
 - one working Codex path:
-  - default OpenAI login path: `codex --login` (or `codex`)
+  - default OpenAI login path: `codex login` (or just `codex`)
   - provider-backed path: one working Codex profile such as `minimax`, `glm`, `ark`, or `bailian`
 - a model or API credential if your project needs external inference
 - GPU or server access if your experiments are compute-heavy
@@ -47,6 +47,7 @@ Prepare these first:
 
 If you are still choosing a coding plan or subscription, these are practical starting points:
 
+- If you just want one simple starting recommendation, start with GPT-5.4 using `xhigh` reasoning effort, or Gemini 3 Pro using `gemini-3-pro-preview`.
 - ChatGPT pricing: https://openai.com/chatgpt/pricing/
 - ChatGPT Plus help: https://help.openai.com/en/articles/6950777-what-is-chatgpt-plus%3F.eps
 - MiniMax Coding Plan: https://platform.minimaxi.com/docs/guides/pricing-codingplan
@@ -54,13 +55,15 @@ If you are still choosing a coding plan or subscription, these are practical sta
 - Alibaba Cloud Bailian Coding Plan: https://help.aliyun.com/zh/model-studio/coding-plan
 - Volcengine Ark Coding Plan: https://www.volcengine.com/docs/82379/1925115?lang=zh
 
+If you plan to use Qwen through Alibaba Bailian, use the Bailian **Coding Plan** endpoint only. The generic Bailian or DashScope Qwen API is not supported in the Codex-backed DeepScientist path.
+
 If you plan to use a provider-backed Codex profile instead of the default OpenAI login flow, read this next:
 
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
 
 ## 1. Install Node.js and DeepScientist
 
-DeepScientist fully supports Linux and macOS. Native Windows support is currently experimental, and WSL2 is still the most battle-tested option when you want Linux-like shell behavior.
+DeepScientist fully supports Linux and macOS. Native Windows support is currently experimental (strongly recommend WSL2 when you want the most reliable Linux-like shell behavior).
 
 Before installing DeepScientist itself, install Node.js from the official page:
 
@@ -85,6 +88,15 @@ DeepScientist depends on a working Codex CLI. It prefers the `codex` already ava
 npm install -g @openai/codex
 ```
 
+If you want the most reliable path, verify the command immediately:
+
+```bash
+which codex
+codex login
+```
+
+If `which codex` prints nothing, the issue is usually the npm global bin path rather than DeepScientist itself. Fix the shell PATH first, then rerun `npm install -g @openai/codex`.
+
 If you want local PDF compilation later, also run:
 
 ```bash
@@ -102,10 +114,10 @@ Choose one of these two paths.
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run:
+If you prefer the interactive first-run flow, run:
 
 ```bash
 codex
@@ -121,7 +133,7 @@ ds doctor
 
 ### 2.2 Provider-backed Codex profile path
 
-If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another provider-backed path, verify that profile first in a terminal:
+If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian Coding Plan, or another provider-backed path, verify that profile first in a terminal:
 
 ```bash
 codex --profile m27
@@ -148,18 +160,21 @@ ds --codex /absolute/path/to/codex --codex-profile m27
 
 `m27` is the MiniMax profile name used consistently in this repo. MiniMax's own page currently uses `m21`, but the profile name is only a local alias; if you created a different name, use that same name in all commands.
 
-DeepScientist blocks startup until Codex can pass a real hello probe. By default, the runner model in `~/DeepScientist/config/runners.yaml` is `gpt-5.4`. If your profile expects the model to come from the profile itself, use `model: inherit` in `runners.yaml`, or simply launch with `--codex-profile <name>` and let that session inherit the profile-defined model.
+DeepScientist blocks startup until Codex can pass a real hello probe. The current default runner model in `~/DeepScientist/config/runners.yaml` is `inherit`. If your existing config still pins an explicit model while your provider expects the model to come from the profile itself, change it to `model: inherit`, or simply launch with `--codex-profile <name>` and let that session inherit the profile-defined model.
 
 MiniMax note:
 
 - if the current `@openai/codex` latest does not work with MiniMax, install `npm install -g @openai/codex@0.57.0`
+- when DeepScientist detects a MiniMax profile on startup and the installed Codex CLI is not `0.57.0`, it now offers to reinstall `0.57.0` automatically in interactive terminal launches
 - create a MiniMax `Coding Plan Key` first
-- clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
+- for plain terminal `codex --profile <name>` checks, clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
 - use `https://api.minimaxi.com/v1`
 - the `codex-MiniMax-*` model names shown on MiniMax's current Codex CLI page did not pass reliably through Codex CLI in local testing with the provided key
-- the locally verified working model name is `MiniMax-M2.7`
+- the locally verified DeepScientist model names are `MiniMax-M2.7` and `MiniMax-M2.5`
+- for `m25`, use `MiniMax-M2.5`, not `codex-MiniMax-M2.5`
 - DeepScientist can auto-adapt MiniMax's profile-only `model_provider` / `model` config shape during probe and runtime
-- if you also want plain terminal `codex --profile <name>` to work directly, add `model_provider = "minimax"` and `model = "MiniMax-M2.7"` at the top level of `~/.codex/config.toml`
+- DeepScientist also strips conflicting `OPENAI_*` auth variables automatically for providers that set `requires_openai_auth = false`
+- if you also want plain terminal `codex --profile <name>` to work directly, add `model_provider = "minimax"` and the matching top-level model such as `MiniMax-M2.7` or `MiniMax-M2.5` to `~/.codex/config.toml`
 - DeepScientist automatically downgrades `xhigh` to `high` when it detects an older Codex CLI that does not support `xhigh`
 
 ## 3. Start the Local Runtime
@@ -192,6 +207,18 @@ ds --here
 
 This is equivalent to `ds --home "$PWD/DeepScientist"`.
 
+Important:  
+* if you start DeepScientist with `ds --here` or an explicit `--home <path>`, later management commands such as `ds --status` and `ds --stop` should use the same DeepScientist home  
+* using the same `DEEPSCIENTIST_HOME` or `DS_HOME` environment variable for those commands is also fine
+* otherwise, the CLI may fall back to the default `~/DeepScientist`, which can make a reachable daemon look like an unverified one  
+  
+For example, when using a non-default home, run:  
+
+```bash
+ds --status --home /path/to/DeepScientist  
+ds --stop --home /path/to/DeepScientist
+```
+
 If you want another port, run:
 
 ```bash
@@ -200,13 +227,14 @@ ds --port 21000
 
 This keeps everything the same, but serves the web UI on port `21000`.
 
-By default, the local web UI is:
+By default, DeepScientist starts without a local browser password gate.
 
-```text
-http://127.0.0.1:20999
-```
-
-If the browser does not open automatically, paste that address into your browser manually.
+- open the normal local URL manually if the browser does not open automatically, such as `http://127.0.0.1:20999`
+- if you want a generated local browser password for one launch, run `ds --auth true`
+- on authenticated launches, DeepScientist prints the generated password in the terminal
+- if the browser is not authenticated yet, DeepScientist shows a password modal before loading the landing page and workspace
+- after the first successful login, the browser keeps the local session and later visits usually do not need the password again
+- if you need to look up the password again for an authenticated launch, check the launch terminal or run `ds --status`
 
 ## 4. Open the Home Page
 
@@ -220,10 +248,18 @@ After 12 hours of running, the projects surface will often look more like this:
 
 The two main entry points are:
 
-- `Start Research`: create a new project and launch a new research run
+- `Start Research` or `Start Experiment`: begin a new project flow
 - `Open Project`: reopen an existing project
 
-For your first run, click `Start Research`.
+For your first run, click `Start Research` or `Start Experiment`.
+
+Important update:
+
+- the product now asks you to choose a start style first
+- `Copilot` creates a quieter project that waits for your first instruction
+- `Autonomous` creates the standard DeepScientist project and starts moving immediately
+
+If you are unsure which one to choose, read [20 Workspace Modes Guide](./20_WORKSPACE_MODES_GUIDE.md) first.
 
 ## 5. Create Your First Project With A Worked Example
 
@@ -236,7 +272,7 @@ The example task is:
 - study how to improve truth-preserving collaboration under mixed correct and incorrect social signals
 - use two local inference endpoints to keep throughput high
 
-Click `Start Research` to open the dialog.
+Click `Start Research` / `Start Experiment`, then choose `Autonomous Mode` to follow the flow below.
 
 ![Start Research dialog](../images/quickstart/01-start-research.png)
 
@@ -400,6 +436,12 @@ Check status:
 ds --status
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --status --home /path/to/DeepScientist
+```
+
 This shows whether the local runtime is up.
 
 Stop the daemon:
@@ -408,8 +450,47 @@ Stop the daemon:
 ds --stop
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --stop --home /path/to/DeepScientist
+```
+
 This stops the local DeepScientist daemon.
 
+Uninstall code and runtime, but keep local data:
+
+```bash
+ds uninstall
+```
+
+If you started DeepScientist with a non-default home, specify it explicitly:
+
+```bash
+ds uninstall --home /path/to/DeepScientist --yes
+```
+
+This removes launcher wrappers, local runtime code, and install-local code trees, but preserves:
+
+- `quests/`
+- `memory/`
+- `config/`
+- `logs/`
+- `plugins/`
+- `cache/`
+
+If you installed DeepScientist from npm and also want to remove the global npm package itself, run this after `ds uninstall`:
+
+```bash
+npm uninstall -g @researai/deepscientist
+```
+
+If you really want to delete local data too, remove the DeepScientist home manually after uninstall:
+
+```bash
+rm -rf /path/to/DeepScientist
+```
+
 Run diagnostics:
 
 ```bash

package/docs/en/01_SETTINGS_REFERENCE.md

@@ -52,6 +52,7 @@ daemon:
 ui:
   host: 0.0.0.0
   port: 20999
+  auth_enabled: false
   auto_open_browser: true
   default_mode: both
 logging:
@@ -165,6 +166,17 @@ acp:
 - UI label: `UI port`
 - Meaning: listening port for the local UI server.
 
+**`ui.auth_enabled`**
+
+- Type: `boolean`
+- Default: `false`
+- UI label: `Require local password`
+- Meaning: require a locally generated 16-character browser password for the web workspace and all `/api/*` routes.
+- Behavior:
+  - `true`: `ds` prints the generated password in the terminal, the browser prompts for the password if no valid local login exists, and successful login persists in the browser.
+  - `false`: disable the local password gate and keep the plain local URL behavior.
+- CLI override: `ds --auth true` or `ds --auth false`
+
 **`ui.auto_open_browser`**
 
 - Type: `boolean`
@@ -263,6 +275,7 @@ Palette selection is no longer exposed in `Settings` or `config.yaml`.
 - Default: `true`
 - UI label: `Sync project skills on create`
 - Meaning: mirror skills into project-local runner homes when a project is created.
+- Prompt note: this also seeds the managed quest-local prompt mirror under `.codex/prompts/`.
 
 **`skills.sync_quest_on_open`**
 
@@ -270,6 +283,26 @@ Palette selection is no longer exposed in `Settings` or `config.yaml`.
 - Default: `true`
 - UI label: `Sync project skills on open`
 - Meaning: refresh project-local skill mirrors when an existing project is opened.
+- Prompt note: this refreshes quest-local skill and prompt mirrors for quests discovered under the configured DeepScientist home.
+
+Managed prompt behavior:
+
+- DeepScientist now treats `.codex/prompts/` as a managed active prompt tree rather than as a permanent hand-edited override.
+- Before each real runner turn, it compares the active quest-local prompt tree against the current repository `src/prompts/` tree and automatically repairs drift.
+- If the active prompt tree differs, the previous tree is backed up under `.codex/prompt_versions/<backup_id>/` before the new active copy is written.
+- This run-time prompt sync happens against the actual quest root used for the turn, so it still works even when a quest lives outside the default `home/quests` path.
+- Runtime override: `ds daemon --prompt-version latest` uses the managed active tree, while `ds daemon --prompt-version <official_version>` runs that daemon session against the newest backup recorded for that formal DeepScientist version.
+- If you need one exact historical backup rather than the newest backup for that version, you may still pass the exact backup directory name from `.codex/prompt_versions/`.
+- The same override also exists for one-off CLI runs: `ds run --prompt-version <official_version> ...`.
+
+Managed auto-continue behavior:
+
+- `workspace_mode = copilot`
+  - after the current requested unit, DeepScientist normally parks and waits for the next user message or `/resume`
+- `workspace_mode = autonomous`
+  - if no real external long-running task exists yet, DeepScientist keeps using the next turns to prepare, launch, or durably route that real task
+  - once a real external long-running task exists, auto-continue becomes low-frequency monitoring, roughly every `240` seconds by default
+- Auto-continue prompts now also carry a compact resume spine: latest user message, latest assistant checkpoint, latest run summary, recent memory cues, and current `bash_exec` state
 
 ### Connector policy
 
@@ -432,7 +465,7 @@ claude:
 - `Test` behavior: checks whether the binary is on `PATH`.
 - Resolution order for `codex`: env override, explicit path, local `PATH`, then bundled fallback.
 - One-off note: you can temporarily override this with `ds --codex /absolute/path/to/codex`.
-- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex --login` (or `codex`) has completed successfully.
+- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex login` (or just `codex`) has completed successfully.
 - Repair note: if the bundled dependency is missing after `npm install -g @researai/deepscientist`, install Codex explicitly with `npm install -g @openai/codex`.
 
 **`config_dir`**

package/docs/en/02_START_RESEARCH_GUIDE.md

@@ -316,9 +316,16 @@ This is the main public knob for round depth.
 
 - `autonomous`
   - the agent should keep choosing ordinary routes on its own
+  - after one turn finishes, it should keep moving automatically: if no real long-running external task exists yet, keep preparing or launching it; once a real long-running external task exists, background monitoring should become low-frequency instead of sub-minute polling
 - `user_gated`
   - the agent may raise a blocking decision only when continuation truly depends on the user
 
+Practical note on workspace mode:
+
+- DeepScientist also distinguishes a user-directed `copilot` workspace mode from the default `autonomous` mode.
+- In `copilot`, completing the current requested unit should normally park and wait for the next user message or `/resume`.
+- In `autonomous`, the quest should not park just because no long-running task is active yet; it should keep pushing toward the next real long-running unit of work.
+
 ### Launch mode
 
 **`launch_mode`**

package/docs/en/05_TUI_GUIDE.md

@@ -58,6 +58,7 @@ ds --stop
 Meaning:
 
 - `ds`: start the daemon, print the local Web URL, try to open the browser, then exit.
+  If you launch with `ds --auth true`, DeepScientist also prints the generated local browser password for that launch.
 - `ds --tui`: start the daemon and enter the terminal workspace.
 - `ds --both`: open Web and TUI together.
 - `ds --status`: inspect daemon status.
@@ -71,6 +72,11 @@ When the TUI opens, the first useful signals are:
 - the local Web URL
 - which quests are available to switch to
 
+If local browser auth is enabled, treat that printed Web URL as the source of truth.
+
+- open the exact printed URL first
+- `Ctrl+O` reopens the Web workspace with the same local password token when TUI already has it
+
 If the welcome area says `request mode`, the current terminal session is not bound to a quest yet.
 
 The correct next move is not plain text. Do one of these first:

package/docs/en/06_RUNTIME_AND_CANVAS.md

@@ -246,9 +246,10 @@ The current authoritative runner path is Codex.
 
 The Codex runner:
 
-- prepares a quest-local `.codex/`
-- copies local auth/config if needed
-- injects DeepScientist built-in MCP servers into `.codex/config.toml`
+- prepares an isolated runtime home under `.ds/codex-home/`
+- inherits the configured Codex home semantics (`config.toml`, `auth.json`, `skills/`, `agents/`, `prompts/`)
+- overlays quest-local `.codex/skills/` and `.codex/prompts/` on top of that runtime copy
+- injects DeepScientist built-in MCP servers into `.ds/codex-home/config.toml`
 - runs `codex --search exec --json --cd <quest_root> --skip-git-repo-check --model <model> -`
 
 The injected built-in MCP namespaces are exactly:

package/docs/en/09_DOCTOR.md

@@ -15,7 +15,7 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    Default OpenAI path:
 
    ```bash
-   codex --login
+   codex login
    ```
 
    Provider-backed profile path:
@@ -55,10 +55,18 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 - whether required config files are valid
 - whether the current release is still using `codex` as the runnable runner
 - whether the Codex CLI can be found and passes a startup probe
+- whether a recent quest runtime failure already points to a known provider / protocol / retry problem
 - whether an optional local `pdflatex` runtime is available for paper PDF compilation
 - whether the web and TUI bundles exist
 - whether the configured web port is free or already running the correct daemon
 
+`ds doctor` now tries to render failed checks in a more operational form:
+
+- `Problem`: what failed
+- `Why`: why DeepScientist believes it failed
+- `Fix`: the concrete next steps to try
+- `Evidence`: the quest/run/request clues that matched the diagnosis
+
 ## Common fixes
 
 ### Codex is missing
@@ -80,10 +88,10 @@ npm install -g @openai/codex
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+If you prefer the interactive first-run flow, run `codex` and finish the setup there.
 
 Finish login once, then rerun `ds doctor`.
 
@@ -109,19 +117,25 @@ Also check:
 
 - the same shell still exports the provider API key
 - the profile points at the provider's Coding Plan endpoint, not the generic API endpoint
+- if you are using Qwen through Alibaba Bailian, use the Bailian Coding Plan endpoint only; the generic Bailian or DashScope Qwen API is not supported here
 - `~/DeepScientist/config/runners.yaml` uses `model: inherit` if the provider expects the model to come from the profile itself
 
 MiniMax-specific note:
 
 - if MiniMax fails on the current `@openai/codex` latest, install `npm install -g @openai/codex@0.57.0`
+- when DeepScientist detects a MiniMax profile on startup and the installed Codex CLI is not `0.57.0`, it now offers to reinstall `0.57.0` automatically in interactive terminal launches
 - create a MiniMax `Coding Plan Key` first
-- clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
+- for plain terminal `codex --profile <name>` checks, clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
 - use `https://api.minimaxi.com/v1`
 - the `codex-MiniMax-*` model names shown on MiniMax's current Codex CLI page did not pass reliably through Codex CLI in local testing with the provided key
-- the locally verified working model name is `MiniMax-M2.7`
+- the locally verified DeepScientist model names are `MiniMax-M2.7` and `MiniMax-M2.5`
+- for `m25`, use `MiniMax-M2.5`, not `codex-MiniMax-M2.5`
 - DeepScientist can auto-adapt MiniMax's profile-only `model_provider` / `model` config shape during probe and runtime
-- if you also want plain terminal `codex --profile <name>` to work directly, put `model_provider = "minimax"` and `model = "MiniMax-M2.7"` at the top level of `~/.codex/config.toml`
+- DeepScientist also strips conflicting `OPENAI_*` auth variables automatically for providers that set `requires_openai_auth = false`
+- if you also want plain terminal `codex --profile <name>` to work directly, put `model_provider = "minimax"` and the matching top-level model such as `MiniMax-M2.7` or `MiniMax-M2.5` in `~/.codex/config.toml`
 - DeepScientist automatically downgrades `xhigh` to `high` when it detects a Codex CLI older than `0.63.0`
+- if the provider returns `tool call result does not follow tool call (2013)`, treat it as a request-ordering/protocol error rather than a transient network failure
+- if the provider returns malformed tool-call argument errors such as `invalid function arguments json string` or `failed to parse tool call arguments`, fix the tool-call serialization path before retrying again
 
 ### The configured Codex model is unavailable
 
@@ -147,7 +161,7 @@ Normally `ds` will bootstrap a local `uv` automatically. If that bootstrap fails
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-On Windows PowerShell:
+On Windows PowerShell (still strongly recommend WSL2 for regular DeepScientist use):
 
 ```powershell
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
@@ -229,4 +243,7 @@ Set it back to disabled in:
 ## Notes
 
 - `ds docker` is kept as a compatibility alias, but the official command is `ds doctor`.
-- The normal browser URL is `http://127.0.0.1:20999`.
+- The default browser URL stays in the plain local form, for example `http://127.0.0.1:20999`.
+- When local browser auth is enabled, DeepScientist shows a password modal before loading the workspace.
+- You can view the current password in the launch terminal or through `ds --status`.
+- By default the password modal is disabled; use `ds --auth true` when you want the local browser password gate for one launch.

package/docs/en/14_PROMPT_SKILLS_AND_MCP_GUIDE.md

@@ -56,6 +56,14 @@ In practice:
 - `SKILL.md` files define stage-specific execution discipline
 - `mcp/server.py` defines the built-in tool surface
 
+Managed quest-local prompt mirror:
+
+- DeepScientist still reads prompt fragments from `quest_root/.codex/prompts/` first when they exist.
+- But that tree is now managed automatically rather than assumed to be a permanent manual fork.
+- Before each real runner turn, DeepScientist compares the active quest-local prompt tree against the repository `src/prompts/` tree and refreshes the active copy when the source changed or the local copy drifted.
+- Before that refresh, the previous active tree is backed up under `quest_root/.codex/prompt_versions/<backup_id>/`.
+- This means an old quest uses the latest prompt contracts by default, while historical prompt trees remain available for explicit replay.
+
 ## 3. How one turn prompt is assembled
 
 The current runtime assembles the turn prompt in roughly this order:
@@ -72,11 +80,12 @@ The current runtime assembles the turn prompt in roughly this order:
 10. research delivery policy
 11. paper and evidence snapshot
 12. retry recovery packet when this is a retry turn
-13. interaction style block
-14. priority memory for this turn
-15. recent conversation window
-16. current turn attachments
-17. current user message
+13. resume context spine when this is an auto-continue turn
+14. interaction style block
+15. priority memory for this turn
+16. recent conversation window
+17. current turn attachments
+18. current user message
 
 That order matters.
 
@@ -210,6 +219,16 @@ If `Start Research` behavior feels wrong, you usually need to inspect:
 - `src/deepscientist/prompts/builder.py`
 - the stage skill the quest is currently using
 
+It also carries the key mode split for continuation:
+
+- `workspace_mode = copilot`
+  - request-scoped help
+  - complete one useful unit, then normally park and wait for the next user message or `/resume`
+- `workspace_mode = autonomous`
+  - keep advancing without waiting for the user
+  - if no real long-running external task exists yet, keep using the next turns to prepare, launch, or durably decide that real unit of work
+  - once a real long-running external task exists, background auto-continue turns become low-frequency monitoring passes
+
 ### 4.8 Interaction style
 
 This block tells the model how to speak on this turn.
@@ -229,7 +248,27 @@ This is why DeepScientist can keep the same runtime but behave differently acros
 - writing stages
 - waiting-for-decision stages
 
-### 4.9 Priority memory
+It now also encodes the auto-continue cadence split:
+
+- autonomous preparation / launch work may continue quickly across turns
+- monitoring an already-running external task should switch to low-frequency checks, roughly every `240` seconds by default
+- copilot mode should usually stop after the current requested unit instead of auto-continuing
+
+### 4.9 Resume context spine
+
+On auto-continue turns, the prompt now injects a compact resume spine so the model does not restart from a vague stage label alone.
+
+It includes:
+
+- the latest durable user message
+- the latest assistant checkpoint
+- the latest run result summary
+- a few recent memory cues
+- current `bash_exec` state, including whether a long-running shell session is active
+
+This is the main reason auto-continue turns can stay grounded in the latest intent and latest checkpoint instead of drifting into generic stage narration.
+
+### 4.10 Priority memory
 
 DeepScientist does not inject memory randomly.
 
@@ -246,22 +285,33 @@ This means the prompt is stage-biased on purpose.
 
 The agent should not see the same memory bundle on every turn.
 
-## 5. What can be overridden locally
+## 5. Managed local prompt copies and historical versions
 
-Prompt fragments can be overridden per quest under:
+The active quest-local prompt tree lives under:
 
 - `.codex/prompts/system.md`
 - `.codex/prompts/contracts/shared_interaction.md`
 - `.codex/prompts/connectors/<connector>.md`
 
-This means:
+Repository defaults still live under `src/prompts/`.
+
+Important behavior change:
+
+- `.codex/prompts/` is no longer best understood as a permanent hand-maintained override tree.
+- On each real run, DeepScientist repairs the active quest-local copy back to the current repository prompt source when they differ.
+- Manual edits to the active copy are therefore treated as drift: they are backed up and then replaced on the next run.
+- Historical copies are preserved under `.codex/prompt_versions/<backup_id>/`.
+
+If you need to run a quest against an older prompt version intentionally, start the daemon or one-off run with the official DeepScientist version number:
+
+- `ds daemon --prompt-version <official_version>`
+- `ds run --prompt-version <official_version> ...`
 
-- repo defaults live under `src/prompts/`
-- quest-local prompt overrides live under `.codex/prompts/`
+DeepScientist resolves that to the newest backup recorded for that formal version. If you need one exact backup rather than “latest backup for version X”, you may still pass the exact backup directory name.
 
-Use quest-local prompt overrides only when the quest truly needs a different local contract.
+Use `latest` to stay on the managed active prompt tree.
 
-Do not fork the repo-level prompt unless the change should affect the product globally.
+If a prompt change should affect normal future behavior, change the repository prompt source instead of editing only one quest-local active copy.
 
 ## 6. How skills are structured