@@ -20,3 +20,11 @@ paths-ignore:
   # (PWD here is the unix env var for present working directory, not a
   # password). Test exercises symlink/cwd resolution.
   - packages/opencode/test/cli/tui/thread.test.ts
+  # `learn` redaction and guard-rail tests: synthetic credentials (`hunter2`,
+  # AWS's documented `AKIAIOSFODNN7EXAMPLE`, fake JWT/basic-auth strings) that
+  # verify secrets are scrubbed before signals are stored or sent to a model.
+  - packages/opencode/test/altimate/learn/guardrail-corpus.test.ts
+  - packages/opencode/test/altimate/learn/review-redaction.test.ts
+  - packages/opencode/test/altimate/learn/digest.test.ts
+  - packages/opencode/test/altimate/learn/import-reviews.test.ts
+  - packages/opencode/test/altimate/learn/sensitive-data.test.ts
@@ -52,6 +52,11 @@ jobs:
               - 'bun.lock'
               - 'package.json'
               - 'tsconfig.json'
+              # altimate_change start — the Typecheck job runs `bun turbo typecheck`: turbo.json
+              # defines that task and bunfig.toml shapes the install it runs on.
+              - 'turbo.json'
+              - 'bunfig.toml'
+              # altimate_change end
             drivers:
               - 'packages/drivers/src/**'
               - 'packages/opencode/src/altimate/native/connections/**'
@@ -124,6 +129,47 @@ jobs:
         run: bun script/check-tracker-leaks.ts
   # altimate_change end
 
+  # altimate_change start — typecheck every workspace on PRs and on main.
+  # ---------------------------------------------------------------------------
+  # `bun turbo typecheck` ran only in release.yml and in the local pre-push hook,
+  # and the TypeScript job below runs tests, not the compiler. So nothing in CI
+  # caught two PRs that each passed on their own leaving main with a type error
+  # together; it surfaced as every developer's pre-push failing after they
+  # merged main, and would have failed the next release.
+  typecheck:
+    name: Typecheck
+    needs: changes
+    if: needs.changes.outputs.typescript == 'true' || github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2
+        with:
+          bun-version: "1.3.14"
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: bun install
+
+      # The same command as release.yml's gate and the pre-push hook, so all
+      # three agree on what "typechecks" means.
+      - name: Typecheck
+        run: bun turbo typecheck
+  # altimate_change end
+
   # Main TypeScript tests — excludes driver E2E tests (separate job) and
   # cloud credential tests (local-only).
   # ---------------------------------------------------------------------------
 
@@ -23,6 +23,9 @@ Each warehouse has a key (the connection name) and a config object:
 !!! tip
     Use `{env:...}` substitution for passwords and tokens so you never commit secrets to version control.
 
+!!! note "Where saved passwords go"
+    When the agent adds a connection for you, passwords, keys and tokens are kept in your OS credential store (macOS Keychain, Windows Credential Manager, or libsecret on Linux), never in `connections.json`. If no credential store is available, the credential is not saved: the connection works for that session only, and Altimate Code says so. In that case set an `ALTIMATE_CODE_CONN_<NAME>` environment variable to the connection's full config as JSON (not just the password); for a name containing `-`, set it with `env`, since a shell assignment cannot use that character. Removing a saved connection removes its credentials from the store, unless this project's connections file or an environment variable still defines a connection by that name. Saving a connection again under the same name drops the credentials it no longer uses once the new config is written. Credentials are stored by connection name, so a project file that defines a connection of the same name without its own password was using the saved connection's, and loses it when that one is removed. If the store refuses a removal, Altimate Code says which credentials remain.
+
 ## Snowflake
 
 ```json
@@ -50,6 +53,7 @@ Each warehouse has a key (the connection name) and a config object:
 | `database` | No | Database name |
 | `schema` | No | Schema name |
 | `role` | No | User role |
+| `client_session_keep_alive` | No | Keep the session alive while Altimate Code is running (default `true`). A connection Snowflake closes anyway is reopened automatically. `USE`, `ALTER SESSION` and `SET` settings are applied again to the reopened session. A single read-only query interrupted by the close is run again; a statement that changes data, or calls a sequence, is not, because it may already have run, and the error says so. Temporary tables and an open transaction cannot be restored: statements issued before the reopen report that instead of running. |
 
 ### Key-pair authentication
 
@@ -68,6 +72,26 @@ Each warehouse has a key (the connection name) and a config object:
 }
 ```
 
+### Browser single sign-on
+
+Set `"authenticator": "externalbrowser"` (and no password) to sign in through your identity provider.
+
+```json
+{
+  "snowflake-sso": {
+    "type": "snowflake",
+    "account": "xy12345.us-east-1",
+    "user": "jane.doe@example.com",
+    "authenticator": "externalbrowser",
+    "warehouse": "COMPUTE_WH"
+  }
+}
+```
+
+When a connection opens, Snowflake's sign-in page opens in your default browser, and Altimate Code shows **Waiting for sign-in** with a link to the same page in case no browser tab appeared. Snowflake waits up to two minutes for the sign-in. If it isn't completed in that time, the connection fails with a message saying so; complete the sign-in, then try again. If you'd rather not sign in through the browser, use [key-pair authentication](#key-pair-authentication).
+
+A connection that does not use the browser fails after two minutes without an answer from Snowflake, with a message pointing at network, VPN or proxy settings, instead of retrying silently.
+
 ## BigQuery
 
 ```json
 
@@ -245,13 +245,35 @@ Or manually compact in the TUI: leader + `Shift+C`.
 
 ## Debug Mode
 
-Run with full debug output:
+When something goes wrong that is hard to reproduce (a hang, Altimate Code closing unexpectedly, a connection that fails sometimes), turn on debug mode, reproduce the problem, then create a diagnostic report.
+
+**1. Turn on debug mode** for the session where you will reproduce the problem:
 
 ```bash
-altimate --print-logs --log-level DEBUG 2>debug.log
+# macOS / Linux
+ALTIMATE_DEBUG=1 altimate
+
+# Windows (PowerShell)
+$env:ALTIMATE_DEBUG = "1"; altimate
+```
+
+In debug mode the log records every tool call as it starts and ends, and while one is running, a line every 15 seconds naming what is still in progress. Lines are written as they happen, so if Altimate Code hangs or closes, the log still shows what it was doing.
+
+**2. Create the report** after the problem has happened:
+
+```bash
+altimate debug bundle
 ```
 
-Then share `debug.log` when reporting issues.
+This writes `altimate-debug-report-<time>.md` in the current folder (use `--output <path>` to choose another place). It lists the problems it detected first, then the evidence: version and install method, operating system and terminal, warehouse connections (names, types, sign-in method and which fields are set, never values), MCP servers, a summary of the log, and the last 300 log lines. It also checks that the Snowflake and Databricks warehouses, the Altimate API, the telemetry endpoint (when telemetry is on) and the model catalogue this installation uses are reachable over HTTPS. Add `--no-network` (or `--network=false`) and the command makes no network requests at all, telemetry included. It does not start your project (plugins, language servers), so it still works when that is what hangs. The file is created readable only by you, where the filesystem supports it.
+
+Passwords, keys, tokens and other secret settings (in `name=value`, JSON and connection-URL forms), email addresses, URL parameters, your home folder, your user name and your computer's name are removed. This is pattern-based and can miss a secret in an unusual format, so read the report before you send it. It stays on your machine until you send it to Altimate support yourself.
+
+To save the raw logs to a file instead:
+
+```bash
+altimate --print-logs --log-level DEBUG 2>debug.log
+```
 
 ## Getting Help
 
 
@@ -40,9 +40,11 @@ altimate --agent analyst
 | `import`    | Import session data            |
 | `session`   | Session management             |
 | `link`      | Link this project to an Altimate workspace (pilot, requires `ALTIMATE_WORKSPACE=1`) |
+| `workspace` | Show, refresh, sync or unlink this project's workspace from a shell (pilot, requires `ALTIMATE_WORKSPACE=1`) |
 | `trace`     | List and view session traces (recordings of agent sessions) |
 | `github`    | GitHub integration             |
 | `pr`        | Pull request tools             |
+| `debug`     | Troubleshooting tools -- `debug bundle` writes a diagnostic report to send to support; see [Debug Mode](../reference/troubleshooting.md#debug-mode) |
 | `upgrade`   | Upgrade to latest version      |
 | `uninstall` | Uninstall altimate             |
 
@@ -51,6 +53,11 @@ altimate --agent analyst
 Workspace features are off unless `ALTIMATE_WORKSPACE=1` is set. With it:
 
 - `altimate-code link` links the current project to a workspace (or creates one). The sidebar then names the workspace and shows how many memories are not yet synced and when skills last synced.
+- From a shell, script or CI job, without the TUI:
+    - `altimate-code link --workspace <name|id>` links to an existing workspace (an id is matched before a name), and `altimate-code link --create [name]` creates one (named after the repo by default) and links to it. Neither prompts. If the project is already linked to a different workspace they refuse unless `--yes` is passed. Running `--create` again when the project is already linked to a workspace of that name creates nothing, so it is safe in a devcontainer's setup command; if another workspace already has that name it refuses and names its id, unless `--allow-duplicate` is passed. Linking to the workspace the project is already linked to confirms that link on this machine, which a fresh clone needs before `workspace sync` sends its memory.
+    - `altimate-code workspace status [--json]` shows the linked workspace and, when known, how many saved memories have not reached it and when skills last synced.
+    - `altimate-code workspace refresh` pulls the workspace's skills (memory is loaded by the next session started in the project); `altimate-code workspace sync` sends memory the workspace has not received; `altimate-code workspace unlink [--yes]` detaches the project (`--yes` is required without a terminal).
+    - These commands accept `--directory`. Exit codes: `0` done, `1` failed (including when the workspace service could not be reached), `2` a request to change (not signed in, a re-link or unlink without `--yes` and no terminal to confirm on, or a `sync` to a link not yet confirmed on this machine), `3` the project is not linked. With `--json`, `ok` is `true` exactly when the exit code is `0`.
 - `/workspace` in the TUI opens a menu: **Refresh** pulls the workspace's skills and memory into this project, **Sync** re-sends local memory the workspace never received, **Open in browser** (when a web URL is available) shows the workspace on the web, **Switch workspace** relinks the project, **Unlink** detaches it. In a project that is not linked yet, it offers **Link to a workspace** instead.
 - `altimate-code skill publish <name>` uploads a project skill to the linked workspace; see [Skills](../configure/skills.md#cli-commands).
 - In an ordinary session the agent is told every turn which workspace the project is linked to — or that none is, or that the link could not be verified just now. In an extension-pinned session it is told the pinned workspace instead, and that it differs from the project's own link. Either way "which workspace am I in?" has an answer, and the agent is told not to confuse it with a Databricks workspace or an IDE workspace folder.
@@ -79,6 +86,7 @@ Configuration can be controlled via environment variables:
 | Variable                      | Description                  |
 | ----------------------------- | ---------------------------- |
 | `ALTIMATE_CLI_CONFIG`         | Path to custom config file   |
+| `ALTIMATE_DEBUG`              | `1` turns on debug mode: every tool call and a heartbeat for long ones are recorded in the log (see [Debug Mode](../reference/troubleshooting.md#debug-mode)) |
 | `ALTIMATE_CLI_CONFIG_DIR`     | Custom config directory      |
 | `ALTIMATE_CLI_CONFIG_CONTENT` | Inline config as JSON string |
 | `ALTIMATE_CLI_GIT_BASH_PATH`  | Path to Git Bash (Windows)   |
 
@@ -96,6 +96,7 @@ nav:
     - Memory Tools: data-engineering/tools/memory-tools.md
     - Custom Tools: configure/tools/custom.md
   - Skills: configure/skills.md
+  - Learn: configure/learn.md
   - Commands: configure/commands.md
   - Validators: data-engineering/validators.md
   - Trace: configure/trace.md
@@ -177,6 +178,7 @@ nav:
     - Memory Tools: data-engineering/tools/memory-tools.md
     - Custom Tools: configure/tools/custom.md
   - Skills: configure/skills.md
+  - Learn: configure/learn.md
   - Commands: configure/commands.md
   - Validators: data-engineering/validators.md
   - Trace: configure/trace.md
 
@@ -0,0 +1,91 @@
+# RSI research harness
+
+Research tooling only. Model-driven suites incur provider charges; the self-tests below do not.
+The learning loops, v1 delivery, bootstrap, and drift suites require the **`learn` features from
+PR #1405**. This harness-only branch does not supply them. Use a checkout containing those
+features through `ALTIMATE_CMD`; changing product code is outside this experiment.
+The verifier, fake backend, and local `none`/`gold`/`playbook` evaluation arms do not need `learn`.
+
+Prerequisites: Bun, Git, repository dependencies installed for the selected CLI, and Python
+3.10+ for the dbt environment (harness syntax supports 3.9+). The local checks used Python 3.11.
+For example, from the repository root:
+
+```bash
+python3.11 -m venv /tmp/rsi-dbt
+/tmp/rsi-dbt/bin/pip install dbt-core==1.12.5 dbt-duckdb==1.11.0
+export DBT_BIN=/tmp/rsi-dbt/bin/dbt
+export DBT_PYTHON=/tmp/rsi-dbt/bin/python
+```
+
+Pin package versions and record the CLI commit and model IDs alongside any reported results.
+The shared default CLI is this repository's `packages/opencode/src/index.ts`; baseline and fix
+comparison wrappers retain their historical `rsi-base` and `rsi` worktrees. An override is a
+shell-quoted command string, e.g. `ALTIMATE_CMD="bun run --conditions=browser '/path with spaces/src/index.ts'"`.
+Model-driven runs need provider authentication usable from the isolated homes. Account/org policies
+may block Claude, including Claude on Vertex; choose models your account can use. The harness checks
+requested model IDs before evaluation and treats timeouts, errors and incomplete turns as failed runs.
+
+## Running suites
+
+Free local checks (from the repository root):
+
+```bash
+experiments/rsi-workspace/demo/run_task.sh selftest
+python3 experiments/rsi-workspace/fake-backend/selftest.py
+python3 experiments/rsi-workspace/harness/selftest.py
+python3 experiments/rsi-workspace/harness/v1bench/selftest.py
+```
+
+Model-driven suites, from `experiments/rsi-workspace/harness/`:
+
+```bash
+bash run_all.sh my-ci-loop                 # train / validation gate / publish / heldout arms
+bash run_corrections.sh my-corrections     # simulated teammate corrections / publish / eval
+python3 eval.py --arm gold --runs 1 --run-id my-eval --out runs/my-eval/eval/gold.jsonl
+bash run_arms.sh my-ci-loop                # rerun final arms of an existing completed loop
+python3 publish_replace.py runs/my-ci-loop # recover publishing using supported publish/update
+bash budget/run_budget.sh                 # rule-budget arms
+bash budget/run_budget2.sh                # scope/conflict arms
+bash budget/run_drift.sh my-drift "${REFLECTOR_MODEL:-google-vertex/gemini-3.5-flash}"
+FIX_SRC_ROOT=/path/to/fix-checkout bash budget/run_drift_matrix.sh
+FIX_SRC_ROOT=/path/to/fix-checkout bash budget/run_drift_matrix2.sh
+bash v1bench/run_baselines.sh              # n50-short / all-50 / all-300 / all-1000
+bash v1bench/run_all_v1.sh                 # retrieval, vague task, topic, bootstrap, drift suites
+bash v1bench/run_fix_v1.sh                 # focused fix comparison (ALTIMATE_CMD selects checkout)
+```
+
+See [v1 suite plan](harness/v1bench/PLAN.md), [topic switch](harness/v1bench/topic_switch/README.md),
+[vague tasks](harness/v1bench/vague_tasks/README.md), [demo](demo/README.md), and
+[fake backend](fake-backend/README.md) for task definitions and additional switches.
+`fake-backend/demo.sh` runs the model-driven two-user workspace demo.
+IDs must be simple names (letters/digits plus `.`, `_`, `-`); empty, absolute and traversing IDs
+are rejected. Main loops require a fresh run ID. Recovery/evaluation replaces complete arm output;
+v1 resumes only outputs containing the exact unique expected task/run keys.
+
+## Environment
+
+| Variable | Default / meaning |
+|---|---|
+| `ALTIMATE_CMD` | Bun CLI in this repository; honors quoted paths |
+| `DBT_BIN`, `DBT_PYTHON` | `dbt` on PATH; Python beside dbt, or explicitly selected interpreter |
+| `AGENT_MODEL` | Shared Python drivers: `google-vertex-anthropic/claude-haiku-4-5@20251001`; v1 and budget drift shell drivers: `google-vertex/gemini-3.5-flash` |
+| `REFLECTOR_MODEL`, `REVIEWER_MODEL` | Shared default: `google-vertex-anthropic/claude-sonnet-4-6@default`; drift shell reviewer: `google-vertex/gemini-3.1-pro-preview`; independently overridable |
+| `BACKEND` | Historical default `saas`, requiring explicit opt-in; `fake` uses loopback and isolated test users |
+| `ALLOW_REAL_SAAS` | Unset; must equal `1` to permit real workspace access |
+| `WORKSPACE_ID` / `--workspace-id` | Required positive ID for SaaS; binding must resolve to it |
+| `SAAS_CREDS_DIR` | No default; explicit directory containing `home-a/.altimate/altimate.json` and `home-b/...` for SaaS |
+| `RUNS`, `PARALLEL`, `K`, `RUNS_VAL` | Wrapper sample count, concurrency, iterations and validation repetitions |
+| `AGENT_TIMEOUT`, `STAGGER_SECONDS` | Agent deadline (600s), startup spacing (3s) |
+| `BASELINE_FROM` | Corrections driver defaults to `runs/saas-v2/eval/none.jsonl`; set empty to evaluate anew; retain original logs when reusing |
+| `FIX_SRC_ROOT`, `STRONG_MODEL`, `WEAK_MODEL` | Drift matrix checkout (historical `rsi-fix` worktree by default), reflector choices |
+| `BUDGET_REAL_FILE` | Optional real-lesson source; defaults to `runs/corr-main/playbooks/final.md` |
+| `FAKE_DEBUG_TOKEN` | Standalone fake-server admin token; unset disables debug routes; harness generates its own |
+
+SaaS publishing can update an existing **owned** `team-playbook`. Only run it against an intended test
+workspace, with `BACKEND=saas ALLOW_REAL_SAAS=1 WORKSPACE_ID=... SAAS_CREDS_DIR=...` (Python entrypoints use
+`--backend saas --workspace-id ...`). No real SaaS or paid benchmark is needed for self-tests.
+
+Lesson pools/playbooks are deterministic: regenerate with `python3 harness/v1bench/pool.py` then
+`python3 harness/v1bench/make_playbooks.py` from this directory. Committed pools, playbooks, lesson IDs/order, and benchmark treatment defaults match `780168ab18`.
+Historical result Markdown predates these verifier and delivery fixes; it is retained as historical evidence,
+not rescored or claimed as current benchmark results.