docs: document the week's user-facing changes (29 Sep – 6 Oct), with screenshots

[simple-agent-manager]

Summary

Documents the user-facing changes merged from 29 September to 6 October 2026 (PRs #2180–#2240) on the public docs site, written around what a person is trying to do, with Playwright screenshots of the real components rendered against mock data.

The previous weekly pass (#2179) covered #2136–#2177. For each PR since then I read the description and the code it changed, then checked what the docs said. The biggest change of the week — agents can now stop and ask the person in the chat — was documented only in operator terms (flag names, encryption, callback rules), and permission requests were not mentioned at all.

A user asks…	Before	Now
"My chat says Needs input. What do I do?"	Nothing explained the label	Chat Features → When the Agent Needs You: permission requests, questions, and links to open; who can answer; deadlines and what an unanswered request does; no push notification; typing doesn't answer a card; screenshots at desktop and phone width. Troubleshooting and Notifications point there
"How do I make the agent ask before it changes things — or stop asking?" (#2225)	A paragraph naming two of five modes	All five modes, where a mode can be set and which wins, when a change takes effect, why an agent may ask anyway (old saved "Manual", Amp/Gemini CLI), and a section on root devcontainers with a whoami check and the remoteUser fix
"How close am I to my Claude Max limit?" (#2238)	Said Settings → Credentials, which doesn't exist (it's Settings → Advanced); a source-file table; levels unexplained	Rewritten for users: where the chip is, what the levels mean, what to do near or past a limit, which credentials report; screenshot of the details dialog
"Agent connection rejected" / an MCP server's tools are missing (#2217)	One sentence under MCP "Scopes", naming a failure card that can never appear	Troubleshooting → The agent or a tool can't sign in, describing the strip, cards, and messages that actually appear, with recovery that differs for Chat and Task sessions; MCP → When a server needs sign-in
"SAM paused automatic check-ins…" (#2236) / "SAM detected a stalled agent turn" (#2232)	Undocumented	What happened, whether work is safe (stalled-turn failures do not save the workspace), and what to do
"Can I copy my own prompt?" (#2226) / "Why did my old chat jump to the top?" (#2228)	Undocumented	Message Actions; chat-list ordering
Self-hoster: "My users' agents stop whenever they need approval"	Only configuration rows	Self-Hosting → Let agents ask in chat, a Troubleshooting entry, and changelog steps keyed to releases
"What changed this week?"	—	Recent Product Changes: a 29 Sep – 6 Oct cycle (users, self-hosters, deep-dives)

Also: configuration's Worker Variables intro now says which variables a GitHub Environment variable can override (only those the deploy workflow passes through); agents and creating-workspaces no longer claim you pick a workspace profile in the composer (it's an agent-profile setting), and chat-features explains how a VM chat becomes a Chat (the profile's Task Mode). Quickstart notes sleeping tasks are back on Active Tasks (#2240) and that the dashboard can't show a waiting agent; configuration gets an Agent Requests in Chat section (the rows were buried in the snapshot table) with plain-language switches, seven undocumented limits (including the 4-hour maximum deadline, which makes session starts fail if exceeded), STALLED_TASK_CLASSIFIER_*, and RATE_LIMIT_CALLBACK_TOKEN_RENEWAL*; the API reference lists the agent-request routes and answer body; Self-Hosting explains recovering a project at the 10 GiB storage cap (#2215); collaboration and concepts mention who can answer and that an agent may stop to ask.

Critical notes for reviewers

• Self-hoster behaviour change the code PRs didn't spell out. Before v2026.10.01 the VM agent approved every permission request whatever the mode. From v2026.10.01 requests go to the chat, or — with the ACP_INTERACTION* switches off, the checked-in default — are refused. v2026.10.05 is the first release where Claude Code agents with no mode start in Bypass; fix(codex): upgrade runtime for Sol 6.1 #2234/fix: stop repeated agent check-ins with durable limits and Clef #2236/feat: surface credential usage limits; capture Codex and OpenCode #2238/fix(tasks): keep sleeping VM agents visible and reachable #2240 land in the release after it. The changelog gives three numbered steps.
• Product bugs found and filed as SAM ideas rather than papered over (code-verified, not reproduced live):
  • 01M47PYF4XAJ0GZZ8KJP3XBBKH — Archive likely fails on sleeping VM conversations since fix: stable task identity across sleep/wake cycles #2230: the close route accepts only in_progress/delegated, but slept VM tasks are now sleeping. Priority 8.
  • 01M47RANRASPRD6JVB4YAPAG6P — the stalled-turn classifier ignores pending cards, so a card left unanswered >1 h on work older than 4 h can fail the task without saving it. Docs tell users to answer within an hour there.
  • 01M47PYM16AJQ3ANQ4X2Z1QB9T — expired permission requests can show "Request cancelled — The agent cancelled this permission request".
  • 01M47PYS4NFYDHEDYAQ4ZF2WAQ — the "Tool connection needs sign-in" / "Sign-in flow unavailable" failure cards are unreachable (no producer of their codes).
  • 01M47PH42BYKGR0W90XFWPY1R5 — chats marked Needs input collapse into "Older" after 3 h.
  • 01M47V0101CAM43ZNZN4JHB4AK — the deploy doesn't forward several GitHub Environment variables to the Worker: newer runtime limits (STALLED_TASK_CLASSIFIER_*, TASK_RECONCILIATION_MAX_CHECKINS, RATE_LIMIT_CALLBACK_TOKEN_RENEWAL*, ceiling grace), the documented PREVIEW_BASE_DOMAIN/PREVIEW_URL_TTL_SECONDS (never forwarded since feat: add isolated interactive HTML artifact previews #1729), and MCP_ARCHIVED_TOOL_PAYLOAD_LIST_*. The docs now say how to check any variable.
  • 01M47V0GCMCZH5A51Z9FTJDKHM — the composer keeps task-mode/workspace-profile state with no UI, and TaskSubmitForm is used only by tests; docs that said you pick a workspace profile when starting a chat were corrected.
  • 01M47WCAGF4A18CC0DCHYFK6CP — a chat woken from sleep loses its start-time settings. Its agent requests are refused with no card (on hosted since 2026-10-03), and its profile's permission mode isn't re-applied, so a Manual profile wakes in Bypass. Overrides and the request contract are only sent on session start, and a wake restores instead. Priority 8. Docs describe the current behaviour.
  • Appended to existing ideas: 01M43B7Q8HC87N3AEW187Q6BMT (consider IS_SANDBOX=1, since Claude Code refuses Bypass as root) and 01M47RANRASPRD6JVB4YAPAG6P (the stalled-turn failure card reads a generic Failed).
• Screenshots (apps/www/public/images/docs/) come from a new spec, apps/web/tests/playwright/docs-screenshots-agent-requests.spec.ts, driving the real chat with mocks shaped like production (permission title = the tool call's title, Claude Code's own option labels, Claude's AskUserQuestion form, no tool-call ID for questions/links) and asserting on what rendered before each capture. It holds the chat socket open (an aborted socket shows a false "Reconnecting..." strip) and hides the completion dock only for card-only crops, after asserting it was there. Phone variants are served through <picture>. PNGs are palette-compressed (~4x smaller). I opened every image and checked the built site at 375 px and 1280 px (no horizontal overflow; phones get the narrow variants).
• Diff noise: moving the ACP_INTERACTION* rows out of the big configuration table re-pads ~75 untouched rows, a new row re-pads the Self-Hosting Step 6 variables table, and mcp-servers.md (Prettier-dirty on main) is now formatted. Whitespace only. One pre-existing phone overflow on the configuration page (a long variable name in an aside title) is fixed by moving the name into the body.

Validation

• pnpm lint: @simple-agent-manager/www lint clean; ESLint clean on the new Playwright spec
• pnpm typecheck: www Astro template check at its 5-error baseline; the new spec has no type errors under tsc --strict (the web tsconfig excludes tests)
• pnpm test: N/A, no unit tests change. The executable surface is the docs-screenshot spec: 7/7 captures pass at desktop and phone
• Additional validation run: pnpm --filter @simple-agent-manager/www build (230 pages) and pnpm check:links — 0 broken internal doc links (anchors included) across 31 doc pages; every touched page is Prettier-clean
• N/A: no sweep/cron/alarm candidate selection changes

Staging Verification (REQUIRED for all code changes — merge-blocking)

N/A: docs-only. No runtime code changed: the PR touches apps/www/ content and images, one Playwright docs-screenshot spec under apps/web/tests/playwright/ (ships nothing), and tasks/.

• Infrastructure verification completed: N/A, no infra changes

Staging Verification Evidence

No runtime code changed, so there is nothing to exercise on staging. The docs site was built locally, link-checked, and rendered at phone and desktop widths. Every screenshot was produced by driving the real production components against mocked API data, then opened and reviewed before embedding.

UI Compliance Checklist (Required for UI changes)

N/A: no UI changes. Nothing under apps/web/src/, packages/ui/, packages/terminal/, or packages/acp-client/ changed; the screenshots document existing surfaces.

• Mobile-first layout verified: N/A, no UI source changed. Phone captures (375 px) were reviewed for clipping and legibility, and the built docs pages were checked at 375 px.
• Accessibility checks completed: N/A, no UI source changed. Every new image has descriptive alt text.
• Shared UI components used or exception documented: N/A, no UI source changed.

UI Screenshot Evidence

N/A: no UI surfaces changed.

End-to-End Verification (Required for multi-component changes)

N/A: documentation-only change. Each behavioural claim was checked against code; the task file's review log lists the evidence: tasks/active/2026-10-06-docs-update-weekly-ux-changes.md.

Data Flow Trace

N/A: documentation-only change.

Untested Gaps

N/A: the executable surface of this PR is the docs-screenshot spec, which passes.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix. Product bugs found while documenting are filed as SAM ideas (listed above).

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human: N/A — reviews are still running, not failed

Reviewer	Status	Outcome
local-doc-reviewer, user journeys (round 1)	ADDRESSED	1 CRITICAL, 2 HIGH, 9 MEDIUM, 6 LOW groups. All verified against code, fixed in bd4dd1eed: release ranges from git tags (sign-in broken v2026.09.24–v2026.10.01), Settings → Agents saved the old always-ask mode, Chat/Task labels, typed messages don't answer cards, phone-width card screenshots, usage-limit actions, 10 GiB heading and example. Not changed: an unverified claim that a paused session keeps its machine running
local-doc-reviewer, code fact-check (round 1)	ADDRESSED	0 CRITICAL, 6 HIGH, 16 MEDIUM, ~10 LOW groups. Fixed in bd4dd1eed: the MCP sign-in failure cards are unreachable (idea filed), a missing credential is a strip not a card, the unsupported-model pause is immediate in any chat, stalled-turn failures skip work preservation, plan approval never offers "Yes, auto-accept edits", questions/links render at the end of the chat, Settings → Advanced, 30-day readings, configuration section and missing limits
local-doc-reviewer, user journeys (round 2)	ADDRESSED	1 CRITICAL, 5 MEDIUM, 7 LOW. Fixed in a302e053f: the stalled-turn/pending-card risk (idea 01M47RANRASPRD6JVB4YAPAG6P, docs caveat), self-hoster steps keyed to releases, card expiry vs request_human_input expiry, mode precedence, "asked about every command", Interrupt before resending, 10 GiB error text
local-doc-reviewer, code fact-check (round 2)	ADDRESSED	0 CRITICAL, 3 MEDIUM, 5 LOW. Fixed in 2944d493f: over-limit deadlines fail session starts, the dashboard shows nothing for a waiting agent, rejected-credential recovery differs for Chat (Sleep, then reply) and Task, Platform-credential limits, persisted local-callback message, root devcontainers refuse Bypass
local-doc-reviewer, user journeys (round 3)	ADDRESSED	1 HIGH, 3 MEDIUM, 11 LOW, each verified in code. Fixed in 5f991962a: a section on Claude Code refusing Bypass as root (whoami check, remoteUser fix), named in every self-hosted remedy; the 4-hour stalled-turn warning is its own bullet and says unpushed work is lost, plus a "SAM ended a stalled turn" heading and index entry; how a VM chat becomes a Chat (profile Task Mode), correcting stale "pick a workspace profile in the composer" claims; which Worker variables GitHub can override; a tested D1 query and a test check for operators; No override. Pushed back on: naming the next release tag (none exists yet) and "Sleep, then message" after a model change (restore path doesn't pass the new model; Fork offered instead)
local-doc-reviewer, code fact-check (round 3)	ADDRESSED	0 HIGH, 0 MEDIUM, 3 LOW, fixed in 5f991962a: Accept Edits with requests off, creator-only Review MCP connections, chip vs dialog reset times
local-doc-reviewer, user journeys (round 4)	ADDRESSED	3 MEDIUM, 6 LOW, fixed in 848fb0a47: the 4-hour advice now reads "on long-running VM work, answer within an hour" (a card raised at 3 h can be checked at 4 h); a Chat doesn't commit/push/open a PR, so keep Task Mode at Task for PR work; stale composer claim in concepts; the D1 query covers skills and shows owner emails; self-hoster steps reordered so requests are on before the update deploy; self-hosted date qualifier; Accept Edits approves only commands; Sleep is the moon button
local-doc-reviewer, code fact-check (round 4)	ADDRESSED	2 MEDIUM, 4 LOW, fixed in 848fb0a47: a woken chat doesn't re-apply its profile's mode or model (idea 01M47WCAGF4A18CC0DCHYFK6CP); the stalled-turn check is VM-only; Lightweight honours a devcontainer.json naming root; skills override Task Mode and permission mode; TASK_RECONCILIATION_MAX_CHECKINS must be added under [vars]; check sync-wrangler-config.ts, not the workflow
local-doc-reviewer, user journeys (round 5)	ADDRESSED	1 HIGH, 1 MEDIUM, 4 LOW, fixed in c16b779a9. HIGH: a chat woken from sleep can't ask, because the request settings are only sent at session start, so every request is refused with no card. Code-verified, added to idea 01M47WCAGF4A18CC0DCHYFK6CP (now priority 8), and documented with fork/new chat as the remedy. Also: Permission mode reordered (table first, sub-sections); skills decide Task Mode only on a VM; concepts and quickstart no longer promise a PR for every chat; self-hosting recommends turning requests on
local-doc-reviewer, code fact-check (round 5)	ADDRESSED	2 MEDIUM, 4 LOW, fixed in b6ab2b1d4: a woken chat keeps its model unless Agent Overrides or Settings → Agents set one; a GitHub Environment variable reaches the Worker only if the sync script reads it and the Sync steps pass it (the PREVIEW_* Step 6 rows never did, since #1729, now marked and filed); "usually" for wakes that start fresh; query owner wording; Instant + attachment + Task skill
local-doc-reviewer, user journeys (round 6)	ADDRESSED	2 HIGH, 3 MEDIUM, 4 LOW, fixed in 48433c851: a woken chat with a Manual/Plan Mode profile usually runs without asking (now stated plainly); troubleshooting gives the lasting fix (Bypass or Inherit in Agent Overrides / Settings → Agents, applied on the next wake) and what a fork keeps; a Current limitations box in chat features; a Chat or Task section; quickstart says Build and open PRs, then Cloud VM
local-doc-reviewer, code fact-check (round 6)	ADDRESSED	1 MEDIUM, 4 LOW, fixed in 63dbce2fa: a woken Task runs as a conversation, so SAM no longer commits/pushes/opens its PR (now in the woken-chat list and the reply-to-wake advice); SAM's own restores behave like wakes; moon icon wording; PR work needs a VM Task profile; idea Execute routes Instant through task submission; model wording narrowed to Claude Code
local-doc-reviewer, user journeys (round 7)	ADDRESSED	3 MEDIUM, 4 LOW, fixed in a8613c6d5: follow-ups after a Task has slept aren't pushed to its PR (docs say to ask the agent to push to its branch, not open a new PR); troubleshooting index entries for "agent set to ask made changes without asking" and "follow-up changes aren't in the PR"; an asking mode in Agent Overrides/Settings makes a woken chat refuse every request; fork-vs-files trade-off; a waiting card keeps the machine running; previous cycle's sign-in warning
local-doc-reviewer, code fact-check (round 7)	ADDRESSED	0 HIGH, 0 MEDIUM, 3 LOW, fixed in f71f14498: the fresh-start exception still doesn't push a Task; a woken Task has no Sleep button; the Amp/Gemini/root caveat covers both causes
local-doc-reviewer, user journeys (round 8)	ADDRESSED	1 MEDIUM, 1 LOW, fixed in 3f32289cb: the woken-chat fix now states the trade-off (Bypass in Agent Overrides/Settings also changes new chats; keep approvals via the profile), split into "keep this chat and its files" vs "get approvals back"; the requests-off remedy says how to keep the files
local-doc-reviewer, code fact-check (round 8)	ADDRESSED	4 LOW, fixed in 35add0575: a fresh-start wake still doesn't push a Task; a woken Task keeps its Task label; sign-in release range wording; "reliably" for new/forked chats
local-doc-reviewer, user journeys (round 9)	ADDRESSED	1 MEDIUM, 2 LOW, fixed in c54407db0: replies that wake a slept Task don't push to its PR (general note in troubleshooting, pointer in chat features); a repo's .claude/settings.json with disableBypassPermissionsMode: "disable" also blocks Bypass; Lightweight with Task Mode Default gives Chats (no PR)
local-doc-reviewer, code fact-check (round 9)	ADDRESSED	3 LOW: 2 fixed in 66b5d3b6e (the self-hosted "keep the files" path warns a Task stops getting pushes; "profile or skill"), 1 declined (rare degraded-snapshot edge readers can't detect)
local-doc-reviewer, user journeys (round 10)	PENDING	Running on c54407db0
local-doc-reviewer, code fact-check (round 10)	PENDING	Running on c54407db0

CodeRabbit Review Evidence (Required for agent-authored PRs)

• CodeRabbit requested after local review, staging if applicable, and CI gates passed
• Waited about 15 minutes, or up to about 45 minutes in total while a review CodeRabbit had started was still in progress
• Either CodeRabbit reviewed and no CodeRabbit feedback is unresolved, or it did not review and the observed outcome is recorded below

CodeRabbit Notes

Not requested yet: local review rounds are still running.

Exceptions (If any)

None.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

public-surface-change and docs-sync-change: this PR changes only the public documentation site (plus a docs-screenshot spec that ships nothing). No UI, API, or infrastructure behaviour changes, so ui-change and infra-change are deliberately unchecked.

External References

N/A: no external API was consulted. Every claim was verified against this repository's source, its release tags, and the pinned Claude ACP adapter installed in the workspace (@agentclientprotocol/claude-agent-acp@0.81.2, for option labels, the AskUserQuestion form, and mode availability). Load-bearing citations:

• apps/web/src/components/project-message-view/{AcpPermissionCard,AcpFormCard,AcpUrlCard,SessionStatusBanners}.tsx, useAcpPermissionPlacement.tsx, SessionMessageView.tsx (canAnswer = session.isMine)
• apps/api/src/durable-objects/interaction-store.ts (projectAttention, create-time switch checks, settle); apps/api/src/services/notification.ts; apps/api/src/durable-objects/project-data/attention-expiry.ts
• packages/vm-agent/internal/acp/{session_host_interactions,session_host_form,session_host_url,session_host_loopback_diagnosis,auth_failure}.go; packages/vm-agent/internal/server/{server,workspaces}.go
• packages/shared/src/constants/agent-settings.ts; apps/web/src/App.tsx (/settings/advanced); apps/api/src/services/credential-limit-events/
• apps/api/src/durable-objects/project-data/{reconciliation,reconciliation-loop,reconciliation-episode,session-reads}.ts; apps/api/src/scheduled/{stuck-tasks,stalled-task-classifier}.ts
• apps/api/wrangler.toml, scripts/deploy/sync-wrangler-config.ts, .github/workflows/deploy-reusable.yml

Codebase Impact Analysis

• apps/www/: docs pages (chat-features, agents, session-troubleshooting, mcp-servers, notifications, collaboration, quickstart, concepts, self-hosting, recent-product-changes, reference/configuration, reference/api) and seven new images.
• apps/web/tests/playwright/: one new docs-screenshot spec (not an *audit.spec.ts, so CI does not run it).
• tasks/: this task file.

No runtime code paths are affected.

Documentation & Specs

The listed apps/www/src/content/docs/docs/ pages; no specs.

Constitution & Risk Check

Principle XI: no code, so no hardcoded values introduced; documented defaults cite their configuration variables. Risk: docs drifting from code — mitigated by citing code for each claim and by repeated local review rounds that fact-check against code.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• coderabbit-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: raphaeltm/simple-agent-manager/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 47c53b88-5485-4206-a77d-22ef9541bbb0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
9.5% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud