diff --git a/CHANGELOG.md b/CHANGELOG.md
index 91f558f813..79b76578f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.10] - 2026-11-07
+
+**Workspace rules are no longer read from the repository, and a session's title no longer sticks on its placeholder.** The workspace rules state (queued proposals, pending approvals, review notices, dismissed topics and the personal learning choice) moves out of the project folder to a private per-user file, so a branch, merge or pull cannot plant a proposal or an approval that a client would then send with the signed-in person's credential, and team rules reach a session only for the account that pulled them. A session whose first title request fails now retries on the next messages and records the provider's error. Also in this release: a project linked by its path can gain its git remote so team rules can sync, `learn status` says why rules are off, and `tool` commands deliver a large answer whole on a pipe.
+
+**Heads-up for support:**
+- **Workspace rules state moves to `$XDG_STATE_HOME/altimate-code/workspace-rules/<hash>.json`** (usually `~/.local/state/…`), keyed by the project folder's real path, so two clones or a moved folder keep separate state. Only projects linked to a workspace are affected. There is no migration from the in-project `.altimate-code/learn/workspace-rules/rules.json`, on purpose: that file is no longer read and can be deleted. Lost with it: proposals queued but never sent, review notices, dismissed topics, the personal learning choice (someone who turned learning off in `/rules` is back on the workspace setting until they set it again), and the record of which usage was already reported, so the first report after upgrading can count the last 30 days again. Until the first sync after upgrading (at session start, then every 5 minutes, or `altimate-code learn sync`) a session has no team rules. The in-project `approved.json` copy is still written for display and recurrence but is never used for delivery.
+- **Before the first sync, `learn status` distinguishes** not linked, linked by path only (rules need a git remote), not signed in, learning off, and linked but not yet synced, and the `learn sync` skip message says what to do.
+- **A path-linked project that now has a git remote gets it added to the link** when `altimate-code link` or the TUI link picker is run again and the same workspace is picked, or with `link --workspace <id>`, instead of stopping at "Already linked".
+- **A session keeps `New session - <time>` only while its title request keeps failing.** The title is retried on each of the first five user messages, always from the first message; a session titled on the first message makes no extra request, and one that already has more than five messages (for example resumed from an older version) is left as it is. Each failure writes `failed to generate title` to the log with the provider's error (`errorType`, `message`, `status`, `attempt`) and sends a `title_generation_failed` telemetry event (provider and model that were asked for, attempt, error class and type, HTTP status; no message text). The worst case for a session whose small model never answers is five attempts of up to three HTTP requests each. A `small_model` the provider cannot serve, or does not list, is a likely cause; the models page now describes it.
+- **`tool` commands write the whole answer before returning.** Read stdout while the command runs: a reader that stops taking output for 60 seconds makes the command exit 1 with a message on stderr, as does a write that fails (for example a full disk), where it used to exit 0 with the answer lost. A reader that closes early, such as `| head`, still exits 0.
+
+### Fixed
+
+- **Workspace rules state lives outside the project.** Proposals, approvals and notices found in the working tree are no longer trusted or acted on; the state is a private per-user file, and team rules come from it only for the account that pulled them. (#1669)
+- **A project linked by its path can gain its git remote**, and `learn status` says why workspace rules are off (not linked, linked by path only, not signed in, learning off, not yet synced) instead of "not linked". The learn docs say that rules need a git remote. (#1670)
+- **`tool` commands no longer lose a big answer on a pipe.** A slow reader used to receive only the first 64 KiB of a larger answer (for example 64 KiB of a 354 KB `tool run --json` result). `tool run` in JSON and text mode, `tool list --json`, `tool context` and `tool schema` now write the whole answer before returning. (#1687)
+- **A failed session title is retried on later turns and reported.** The log carries the provider's error instead of "No output generated", a failure before the request (a `small_model` the provider does not list) is reported too, and telemetry gets a `title_generation_failed` event. (#1688)
+
 ## [0.12.9] - 2026-11-04
 
 **Claude Code and other coding agents can call altimate-code's data tools directly.** `altimate-code mcp serve` and the new model-free `altimate-code tool` CLI run the same tools without a second model: reads by default, writes only with `--allow-write` (over MCP, `warehouse_add` can save a connection without it). In projects linked to a workspace, what people teach the agent can become a team rule: they confirm it on a card, the workspace owner reviews it, and approved rules reach every teammate's sessions. `dbt_lineage` and `impact_analysis` now return structured lineage, and column impact traces each downstream model's compiled SQL. Also in this release: `auth logout` removes the saved Altimate gateway key, the analyst stays read-only whatever config grants, and the home screen suggests the Claude Code and Codex plugins.
diff --git a/docs/docs/configure/models.md b/docs/docs/configure/models.md
index 3a845aba55..baebe3cb19 100644
--- a/docs/docs/configure/models.md
+++ b/docs/docs/configure/models.md
@@ -18,7 +18,7 @@ altimate supports models from all configured providers. Use the `model` and `sma
 
 The model format is `provider/model-name`.
 
-`small_model` handles the small background requests that are not part of the conversation, such as the session title and prompt enhancement. When it is not set, Altimate Code picks a cheap model from the same provider (Claude Haiku, Gemini Flash or GPT-5 nano when the provider lists one) and otherwise uses the chat model. A `small_model` the provider cannot serve, or does not list, fails only those requests: chat keeps working, while new sessions keep their `New session - <time>` placeholder title until a retry succeeds. Altimate Code retries the title on each of the first five messages of a session and reports every failure in telemetry.
+`small_model` handles the small background requests that are not part of the conversation, such as the session title and prompt enhancement. When it is not set, Altimate Code picks a cheap model from the same provider (Claude Haiku, Gemini Flash or GPT-5 nano when the provider lists one) and otherwise uses the chat model. A `small_model` the provider cannot serve, or does not list, fails only those requests: chat keeps working, while new sessions keep their `New session - <time>` placeholder title until a retry succeeds. Altimate Code retries the title on each of the first five messages of a session and reports every failure in telemetry. A failure shows up as a `failed to generate title` line in the log, with the provider's error, and as a `title_generation_failed` telemetry event naming the model that was asked for; correct or remove the `small_model` value to resolve it.
 
 ## Browsing Models
 
diff --git a/packages/opencode/src/cli/cmd/tool.ts b/packages/opencode/src/cli/cmd/tool.ts
index b2629c20cf..03c35712e1 100644
--- a/packages/opencode/src/cli/cmd/tool.ts
+++ b/packages/opencode/src/cli/cmd/tool.ts
@@ -303,18 +303,36 @@ const ToolDaemonCommand = cmd({
  */
 function writeAll(text: string) {
   const bytes = Buffer.from(text)
+  let progressAt = performance.now()
   for (let at = 0; at < bytes.length; ) {
+    let wrote = 0
     try {
-      at += writeSync(1, bytes, at)
+      wrote = writeSync(1, bytes, at)
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code
       if (code === "EPIPE") return // The reader left, so nobody is waiting for the rest.
       if (code !== "EAGAIN") throw error
-      Bun.sleepSync(2)
     }
+    if (wrote > 0) {
+      at += wrote
+      progressAt = performance.now()
+      continue
+    }
+    // Nothing was taken (EAGAIN, or a zero-byte write). A reader that stopped draining the pipe (a
+    // stopped pager, a wedged log shipper) would otherwise keep this process spinning forever; after
+    // a minute without progress on a monotonic clock, fail.
+    if (performance.now() - progressAt > WRITE_STALL_MS) {
+      throw new Error(
+        `stdout stopped accepting output for ${WRITE_STALL_MS / 1000} s; ${bytes.length - at} bytes of the answer were not written`,
+      )
+    }
+    Bun.sleepSync(2)
   }
 }
 
+/** How long `writeAll` waits for a reader that has stopped taking output before it gives up. */
+const WRITE_STALL_MS = 60_000
+
 export const ToolCommand = cmd({
   command: "tool",
   describe: "run altimate-code data tools directly, without a model",
diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
index cfd5fceb09..11a455551d 100644
--- a/packages/opencode/src/session/prompt.ts
+++ b/packages/opencode/src/session/prompt.ts
@@ -1254,12 +1254,13 @@ export namespace SessionPrompt {
 
       step++
       if (step === 1)
-        ensureTitle({
+        // altimate_change — fire-and-forget, but never an unhandled rejection
+        void ensureTitle({
           session,
           modelID: lastUser.model.modelID,
           providerID: lastUser.model.providerID,
           history: msgs,
-        })
+        }).catch((error) => log.error("failed to generate title", { error: String(error) }))
 
       const model = await Provider.getModel(lastUser.model.providerID, lastUser.model.modelID).catch((e) => {
         if (Provider.ModelNotFoundError.isInstance(e)) {
@@ -4948,7 +4949,17 @@ NOTE: At any point in time through this workflow you should feel free to ask the
     let text = ""
     let failure: unknown
     let model: Provider.Model | undefined
+    // The model the request is for, so a failed lookup is reported against the model that was asked
+    // for (the title agent's own, or `small_model`), not against the chat model.
+    let requested: { providerID: string; modelID: string } | undefined
     try {
+      requested = await iife(async () => {
+        if (agent.model) return { providerID: String(agent.model.providerID), modelID: String(agent.model.modelID) }
+        const small = (await Config.get()).small_model
+        if (!small) return undefined
+        const parsed = Provider.parseModel(small)
+        return { providerID: String(parsed.providerID), modelID: String(parsed.modelID) }
+      })
       model = await iife(async () => {
         // agent.model carries core ProviderV2.ID/ModelV2.ID brands; re-brand to fork ProviderID/ModelID (identity at runtime)
         if (agent.model)
@@ -5002,8 +5013,8 @@ NOTE: At any point in time through this workflow you should feel free to ask the
     if (failure !== undefined || !cleaned) {
       const err = failure ?? new Error(text.trim() ? "the model returned no title line" : "the model returned no text")
       const described = describeTitleError(err)
-      const providerID = model?.providerID ?? input.providerID
-      const modelID = model?.id ?? input.modelID
+      const providerID = model?.providerID ?? requested?.providerID ?? input.providerID
+      const modelID = model?.id ?? requested?.modelID ?? input.modelID
       // Name, message and status only: a provider error object can carry the request body.
       log.error("failed to generate title", {
         errorType: described.name,
diff --git a/packages/opencode/test/session/title-retry.test.ts b/packages/opencode/test/session/title-retry.test.ts
index b724abb6df..f0ce291cc4 100644
--- a/packages/opencode/test/session/title-retry.test.ts
+++ b/packages/opencode/test/session/title-retry.test.ts
@@ -275,7 +275,8 @@ it.live(
           failed = events
         }
         expect(failed).toHaveLength(1)
-        expect(failed[0]).toMatchObject({ provider_id: "test", model_id: "test-model", attempt: 1 })
+        // The report names the model that was asked for, not the chat model it fell back from.
+        expect(failed[0]).toMatchObject({ provider_id: "test", model_id: "does-not-exist", attempt: 1 })
         expect(failed[0].error_type).toBe("ProviderModelNotFoundError")
         expect(failed[0].http_status).toBeUndefined()
         const titleHits = (yield* llm.hits).filter((hit) => JSON.stringify(hit.body).includes(TITLE_MARKER))
@@ -335,3 +336,38 @@ it.live(
     ),
   { timeout: 60_000 },
 )
+
+it.live(
+  "a name the user gives the session while the title request runs is kept",
+  () =>
+    provideTmpdirServerLegacy(
+      Effect.fnUntraced(function* ({ llm }) {
+        const { events } = yield* recordTitleFailures
+        const prompt = yield* SessionPrompt.Service
+        const sessions = yield* Session.Service
+        const session = yield* sessions.create({
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        })
+
+        const gate = Promise.withResolvers<void>()
+        yield* llm.title(reply().wait(gate.promise).text("Generated title").stop())
+        yield* llm.text("first answer")
+        yield* prompt.prompt({
+          sessionID: session.id,
+          agent: "build",
+          parts: [{ type: "text", text: "first message" }],
+        })
+        yield* llm.wait(2)
+        // The user names the session while the title answer is still held.
+        yield* sessions.setTitle({ sessionID: session.id, title: "My own name" })
+        gate.resolve()
+
+        // The generated answer arrives and is discarded: only a placeholder is ever replaced.
+        for (let i = 0; i < 25; i++) yield* Effect.sleep("20 millis")
+        expect((yield* sessions.get(session.id)).title).toBe("My own name")
+        expect(events).toHaveLength(0)
+      }),
+      { git: true, config: providerCfg },
+    ),
+  { timeout: 60_000 },
+)
diff --git a/packages/opencode/test/skill/release-v0.12.10-adversarial.test.ts b/packages/opencode/test/skill/release-v0.12.10-adversarial.test.ts
new file mode 100644
index 0000000000..d62772624b
--- /dev/null
+++ b/packages/opencode/test/skill/release-v0.12.10-adversarial.test.ts
@@ -0,0 +1,289 @@
+/**
+ * Adversarial coverage for the v0.12.10 patch payload (v0.12.9..HEAD, 4 commits), on top of the
+ * suites each PR shipped with:
+ *
+ *   1. #1669 "workspace rules state lives outside the project": the state file moves to the person's
+ *      state directory, keyed by the project's real path (`altimate/rules/state-path.ts`,
+ *      `altimate/rules/store.ts`). `test/altimate/rules/*.test.ts` and `test/altimate/learn/*.test.ts`
+ *      cover pull, vouching and delivery.
+ *   2. #1670 "a project linked by path can gain its git remote": `addsRemoteToLink` and the
+ *      `learn status` rules line (`altimate/workspace/api-client.ts`, `cli/cmd/learn.ts`).
+ *      `test/cli/workspace-command.test.ts` and `test/altimate/plugin/workspace.test.ts` cover the flows.
+ *   3. #1687 "`tool` commands no longer lose a big answer on a pipe" (`cli/cmd/tool.ts`, `writeAll`).
+ *      `test/altimate/tool-cli/cli.test.ts` covers the delayed reader and the exit codes.
+ *   4. #1688 "retry a failed session title on later turns and report why it failed"
+ *      (`session/prompt.ts`, `altimate/telemetry/index.ts`). `test/session/title-retry.test.ts` covers
+ *      the retry, the cap, the unlisted small model and the in-flight guard through the prompt loop.
+ *
+ * This file adds the boundary classes those suites do not reach:
+ *
+ *   - The state path with hostile project roots: traversal segments, separators, unicode, very long
+ *     paths and a path that differs only in case or in a trailing slash must all land as one hashed file
+ *     name directly under the state directory, never anywhere else. A symlinked root resolves to the real
+ *     root's file. The prompt path's "may this project have rules" check keys on that file.
+ *   - `addsRemoteToLink` as a truth table, including empty-string remotes, and the `learn status` line
+ *     for every gate outcome with a reason that carries terminal control sequences.
+ *   - Source guards that pin the shapes the fixes depend on, so a later edit cannot quietly undo them:
+ *     no `console.log` answer path left in `tool.ts`, EPIPE and EAGAIN handled in `writeAll`; the title
+ *     attempt cap, the in-flight set, the placeholder re-check before `setTitle`, the identifier-only
+ *     `error_type`, and the telemetry event in the catalogue and the docs.
+ */
+import { afterAll, describe, expect, test } from "bun:test"
+import * as fs from "fs"
+import * as os from "os"
+import * as path from "path"
+import { addsRemoteToLink, ADDING_REMOTE_MESSAGE } from "../../src/altimate/workspace/api-client"
+import { rulesNotSyncedLine } from "../../src/cli/cmd/learn"
+
+// The state directory is redirected before any module that reads `Global.Path.state` loads, so this
+// file never touches the developer's real state directory.
+const stateHome = fs.mkdtempSync(path.join(os.tmpdir(), "release-v0.12.10-state-"))
+const previousStateHome = process.env.OPENCODE_TEST_STATE_HOME
+process.env.OPENCODE_TEST_STATE_HOME = stateHome
+afterAll(() => {
+  if (previousStateHome === undefined) delete process.env.OPENCODE_TEST_STATE_HOME
+  else process.env.OPENCODE_TEST_STATE_HOME = previousStateHome
+  fs.rmSync(stateHome, { recursive: true, force: true })
+})
+
+const { stateFileOf } = await import("../../src/altimate/rules/state-path")
+const { Global } = await import("../../src/global")
+
+const src = (rel: string) => fs.readFileSync(path.join(import.meta.dir, "../../", rel), "utf8")
+const HEX64 = /^[0-9a-f]{64}\.json$/
+
+// ---------------------------------------------------------------------------------------------
+// #1669 — the state file lives under the state directory whatever the project root looks like
+// ---------------------------------------------------------------------------------------------
+describe("workspace rules state path (#1669)", () => {
+  const stateDir = () => path.join(Global.Path.state, "workspace-rules")
+
+  test("every root hashes to one 64-hex file directly under <state>/workspace-rules", () => {
+    const roots = [
+      "/tmp/project",
+      "/tmp/project/../other",
+      "/tmp/pro ject with spaces",
+      "/tmp/ünïcödé/项目",
+      "/tmp/" + "x".repeat(4000),
+      "C:\\Users\\someone\\project",
+      "/tmp/project;rm -rf ~",
+      "/tmp/project\n/etc/passwd",
+      "",
+    ]
+    for (const root of roots) {
+      const file = stateFileOf(root)
+      expect(path.dirname(file)).toBe(stateDir())
+      expect(path.basename(file)).toMatch(HEX64)
+    }
+  })
+
+  test("the hash is deterministic and distinct for roots that differ only slightly", () => {
+    const a = stateFileOf("/tmp/project")
+    expect(stateFileOf("/tmp/project")).toBe(a)
+    expect(stateFileOf("/tmp/project/")).not.toBe(a)
+    expect(stateFileOf("/tmp/Project")).not.toBe(a)
+    expect(stateFileOf("/tmp/project2")).not.toBe(a)
+  })
+
+  test("the state directory follows OPENCODE_TEST_STATE_HOME at call time, not import time", () => {
+    const other = fs.mkdtempSync(path.join(os.tmpdir(), "release-v0.12.10-state2-"))
+    try {
+      process.env.OPENCODE_TEST_STATE_HOME = other
+      expect(path.dirname(stateFileOf("/tmp/project"))).toBe(path.join(other, "workspace-rules"))
+    } finally {
+      process.env.OPENCODE_TEST_STATE_HOME = stateHome
+      fs.rmSync(other, { recursive: true, force: true })
+    }
+  })
+
+  test.skipIf(process.platform === "win32")(
+    "RulesStore.stateFile resolves a symlinked root to the real root's file",
+    async () => {
+      const { RulesStore } = await import("../../src/altimate/rules/store")
+      const real = fs.mkdtempSync(path.join(os.tmpdir(), "release-v0.12.10-root-"))
+      const link = real + "-link"
+      fs.symlinkSync(real, link)
+      try {
+        const viaReal = await RulesStore.stateFile(real)
+        const viaLink = await RulesStore.stateFile(link)
+        expect(viaLink).toBe(viaReal)
+        expect(viaReal).toBe(stateFileOf(fs.realpathSync(real)))
+      } finally {
+        fs.rmSync(link, { force: true })
+        fs.rmSync(real, { recursive: true, force: true })
+      }
+    },
+  )
+
+  test("a root that no longer exists still gets a file name instead of throwing", async () => {
+    const { RulesStore } = await import("../../src/altimate/rules/store")
+    const gone = path.join(os.tmpdir(), "release-v0.12.10-does-not-exist-" + process.pid)
+    const file = await RulesStore.stateFile(gone)
+    expect(path.dirname(file)).toBe(stateDir())
+    expect(path.basename(file)).toMatch(HEX64)
+  })
+
+  test("the prompt path's rules check keys on the state file, not on anything inside the project", async () => {
+    const { mayHaveWorkspaceRules } = await import("../../src/session/prompt")
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "release-v0.12.10-proj-"))
+    try {
+      // A planted in-project rules.json (the 0.12.9 location) no longer counts.
+      const planted = path.join(root, ".altimate-code", "learn", "workspace-rules")
+      fs.mkdirSync(planted, { recursive: true })
+      fs.writeFileSync(path.join(planted, "rules.json"), JSON.stringify({ version: 1, outbox: [{ text: "planted" }] }))
+      expect(mayHaveWorkspaceRules(root, root)).toBe(false)
+      // The person's own state file does.
+      const file = stateFileOf(fs.realpathSync(root))
+      fs.mkdirSync(path.dirname(file), { recursive: true })
+      fs.writeFileSync(file, "{}")
+      expect(mayHaveWorkspaceRules(root, root)).toBe(true)
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  test("source guard: the old in-project rules.json path is not read anywhere in the rules code", () => {
+    for (const rel of [
+      "src/altimate/rules/store.ts",
+      "src/altimate/rules/sync.ts",
+      "src/altimate/learn/delivery.ts",
+      "src/session/prompt.ts",
+    ]) {
+      const text = src(rel)
+      expect(text).not.toMatch(/["'`]rules\.json["'`]/)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------------------------
+// #1670 — adding a remote to a path link, and the `learn status` rules line
+// ---------------------------------------------------------------------------------------------
+describe("addsRemoteToLink and the learn status line (#1670)", () => {
+  const lookup = (matchedBy: "path" | "remote", repo_remote: string | null | undefined) =>
+    ({
+      matchedBy,
+      binding: { repo_remote } as any,
+      datamate: { id: 1, name: "ws" } as any,
+    }) as any
+
+  test("true only for a path match, a project remote, and a link without one", () => {
+    expect(addsRemoteToLink({ repoRemote: "https://x/y.git" }, lookup("path", null))).toBe(true)
+    expect(addsRemoteToLink({ repoRemote: "https://x/y.git" }, lookup("path", undefined))).toBe(true)
+    expect(addsRemoteToLink({ repoRemote: "https://x/y.git" }, lookup("remote", null))).toBe(false)
+    expect(addsRemoteToLink({ repoRemote: "https://x/y.git" }, lookup("path", "https://x/y.git"))).toBe(false)
+    expect(addsRemoteToLink({ repoRemote: "https://x/y.git" }, lookup("path", "https://x/other.git"))).toBe(false)
+    expect(addsRemoteToLink({}, lookup("path", null))).toBe(false)
+    expect(addsRemoteToLink({ repoRemote: "" }, lookup("path", null))).toBe(false)
+    expect(addsRemoteToLink({ repoRemote: "" }, lookup("path", ""))).toBe(false)
+  })
+
+  test("the message shown when a remote is added is one printable line", () => {
+    expect(ADDING_REMOTE_MESSAGE).not.toMatch(/[\u0000-\u001F\u007F]/)
+    expect(ADDING_REMOTE_MESSAGE).toContain("git remote")
+  })
+
+  test("learn status explains every gate outcome and never prints control sequences", () => {
+    expect(rulesNotSyncedLine(undefined)).toContain("learn sync")
+    expect(rulesNotSyncedLine({ status: "ready" } as any)).toContain("not synced yet")
+    expect(rulesNotSyncedLine({ status: "skipped", code: "not_linked", reason: "x" } as any)).toContain(
+      "altimate-code link",
+    )
+    const hostile = {
+      status: "skipped",
+      code: "no_remote",
+      reason: "needs a remote\u001b]0;pwned\u0007\n\rrun rm -rf \u202e/",
+    } as any
+    const line = rulesNotSyncedLine(hostile)
+    expect(line.startsWith("Workspace rules: off")).toBe(true)
+    expect(line).not.toMatch(/[\u0000-\u001F\u007F-\u009F\u2028\u2029\u202e]/)
+    expect(line.split("\n")).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------------------------
+// #1687 — `tool` answers go through writeAll
+// ---------------------------------------------------------------------------------------------
+describe("tool command output (#1687)", () => {
+  const tool = src("src/cli/cmd/tool.ts")
+
+  test("no answer is written with console.log any more", () => {
+    // Answers (JSON documents, tool output, instructions) go through writeAll; console.log remains only
+    // for the one-line-per-tool listing and the daemon's status lines.
+    expect(tool).not.toMatch(/console\.log\(JSON\.stringify\(/)
+    expect(tool).not.toMatch(/console\.log\(result\.output\)/)
+    expect(tool).not.toMatch(/console\.log\(instructions\)/)
+    expect(tool).toMatch(/function writeAll\(/)
+    // Every command's answer goes through it: list, context (both modes), schema, run (both modes).
+    expect(tool.match(/writeAll\(/g)!.length).toBeGreaterThanOrEqual(7)
+  })
+
+  test("writeAll handles a departed reader and a full pipe, and lets other write errors propagate", () => {
+    const body = tool.slice(tool.indexOf("function writeAll("))
+    expect(body).toMatch(/code === "EPIPE"\) return/)
+    expect(body).toMatch(/code !== "EAGAIN"\) throw error/)
+    expect(body).toMatch(/writeSync\(1, bytes, at\)/)
+    // A reader that stops draining the pipe no longer hangs the command forever.
+    expect(body).toMatch(/performance\.now\(\) - progressAt > WRITE_STALL_MS/)
+    // A zero-byte write counts as no progress, not as success.
+    expect(body).toMatch(/if \(wrote > 0\)/)
+    expect(tool).toMatch(/const WRITE_STALL_MS = 60_000/)
+  })
+
+  test("the docs tell callers to read stdout while the command runs", () => {
+    expect(src("../../docs/docs/usage/tool.md")).toMatch(/read stdout while/i)
+  })
+})
+
+// ---------------------------------------------------------------------------------------------
+// #1688 — title retry: the shapes the behaviour depends on
+// ---------------------------------------------------------------------------------------------
+describe("session title retry (#1688)", () => {
+  const prompt = src("src/session/prompt.ts")
+  const title = prompt.slice(
+    prompt.indexOf("const TITLE_MAX_ATTEMPTS"),
+    prompt.indexOf("return Session.setTitle({ sessionID: input.session.id, title })"),
+  )
+
+  test("the retry is bounded, one request per session is in flight, and the lookup is inside the try", () => {
+    expect(title).toMatch(/const TITLE_MAX_ATTEMPTS = 5/)
+    expect(title).toMatch(/if \(attempt > TITLE_MAX_ATTEMPTS\) return/)
+    expect(title).toMatch(/if \(titleInFlight\.has\(input\.session\.id\)\) return/)
+    expect(title).toMatch(/finally \{\s*titleInFlight\.delete\(input\.session\.id\)/)
+    // The model lookup happens after `try {`, so a small_model the provider does not list is reported.
+    expect(title.indexOf("try {")).toBeLessThan(title.indexOf("Provider.getSmallModel(input.providerID)"))
+  })
+
+  test("a generated title only replaces the placeholder, and is left for a retry when the session cannot be read", () => {
+    expect(title).toMatch(/const current = await Session\.get\(input\.session\.id\)\.catch\(\(\) => undefined\)/)
+    expect(title).toMatch(/if \(!current \|\| !Session\.isDefaultTitle\(current\.title\)\) return/)
+  })
+
+  test("the failure report never carries the raw error object, and error_type is identifier-shaped", () => {
+    expect(title).not.toMatch(/log\.error\("failed to generate title", \{\s*error:/)
+    expect(prompt).toMatch(/\^\[A-Za-z0-9_\.:-\]\{1,64\}\$/)
+    expect(title).toMatch(/error_type: described\.name/)
+    expect(title).toMatch(/error_class: Telemetry\.classifyError\(described\.message\)/)
+    expect(title).not.toMatch(/error_message/)
+  })
+
+  test("the telemetry event is in the union, the completeness list and the public catalogue", () => {
+    const telemetry = src("src/altimate/telemetry/index.ts")
+    const event = telemetry.slice(telemetry.indexOf('type: "title_generation_failed"'))
+    expect(event).toMatch(/attempt: number/)
+    expect(event).toMatch(/error_type: string/)
+    expect(event).toMatch(/error_class: string/)
+    expect(event).toMatch(/http_status\?: number/)
+    expect(src("test/telemetry/telemetry.test.ts")).toContain('"title_generation_failed"')
+    const docs = src("../../docs/docs/reference/telemetry.md")
+    expect(docs).toMatch(/\| `title_generation_failed` \|.*No message text/)
+    expect(docs).toMatch(/retries stop after the fifth user message/)
+  })
+
+  test("the models page says what small_model drives and that compaction is not among them", () => {
+    const models = src("../../docs/docs/configure/models.md")
+    const paragraph = models.split("\n").find((line) => line.startsWith("`small_model` handles"))!
+    expect(paragraph).toContain("session title")
+    expect(paragraph).not.toContain("compaction")
+    expect(paragraph).toContain("first five messages")
+  })
+})