copper-pilot-cli 0.1.10__tar.gz → 1.0.0__tar.gz

{copper_pilot_cli-0.1.10 → copper_pilot_cli-1.0.0}/HISTORY.md

@@ -5,6 +5,317 @@ Changelog
 (unreleased)
 ------------
 
+Fix
+~~~
+- Do not count echoed request fields toward the stream byte budget.
+  [AdityaNG, Claude Opus 5.5]
+
+  The hosted service echoes the request `query` (and, in the final frame,
+  `context`) in every chat_response. A live probe showed the echo is ~97% of
+  each frame. A validate arch.review prompt is ~76 KB, so a long review on a
+  large board crossed the 64 MiB client budget after ~815 frames (2601 s)
+  although the hosted output itself was ~4.4 MB, and the check ERRORed with
+  "Chat exceeded the client stream byte budget."
+
+  The budget now counts frame bytes minus the echoed request fields the
+  client never reads, and the error names the counted size and frame count.
+- Stop cutting long hosted answers at the 16 KB status limit. [AdityaNG,
+  Claude Opus 5.5]
+
+  Every hosted response frame went through sanitize_status, which caps
+  status lines at 16 KB. The hosted side can send a whole answer as one
+  response frame, so a validate review longer than 16 KB lost the end of
+  its findings JSON. The reviewer then found no json block, sent a repair
+  turn into the already huge thread, and the server refused it ("This
+  conversation is too large to continue"), so arch.review ERRORed. Chat
+  and ACP answers over 16 KB were cut the same way.
+
+  Response text now gets a 1 MiB bound; status and reasoning lines keep
+  16 KB. A validate check that fails with a hosted failed final also
+  records the hosted turn id, as chat does.
+- Surface stalled or failed hosted turns instead of hanging. [AdityaNG,
+  Claude Opus 5.5]
+
+  Three ways a long ACP turn could hang or hide its cause:
+
+  - idle_frame_timeout was None, so a hosted server that kept the socket
+    (and keepalive) up but stopped sending hung the prompt forever. It now
+    defaults to 10 minutes (COPPER_PILOT_IDLE_TIMEOUT_SECONDS, 0 disables)
+    and raises the existing retryable CHAT_IDLE_TIMEOUT with the silence
+    length in the message. The hosted side heartbeats every 25 s.
+  - A failed hosted final (success false) still waited, unbounded, for
+    background shells and then ran a continuation turn. A runaway background
+    command held the hosted error back until the caller timed out, and a
+    continuation that succeeded still reported the stale error. A failed
+    final now ends the turn and kills leftover background processes.
+  - The hosted copy "CopperPilot ran into an error." carries no detail. The
+    ACP error now names the hosted turn id, and the client logs the failing
+    final frame's keys, so the server-side cause can be found.
+- Guard the state lock with sys.platform so ty passes on Windows.
+  [AdityaNG, Claude Opus 5.5]
+- Stop concurrent sessions racing on recent-projects state. [AdityaNG,
+  Claude Opus 5.5]
+
+  Every process wrote recent-projects.json (and config.json) through the
+  same fixed temp name, so parallel `copper-pilot acp` session starts moved
+  or clobbered each other's temp file and session/new failed with
+  FileNotFoundError on os.replace.
+
+  Writes now go through a per-write mkstemp temp file, the recent-projects
+  read-modify-write holds a POSIX flock so no entry is dropped, and the
+  bookkeeping logs instead of raising so it can never fail a session.
+
+Other
+~~~~~
+- Merge pull request #37 from CopperPilot/fix/stream-byte-budget.
+  [Aditya]
+
+  fix: do not count echoed request fields toward the stream byte budget
+- Merge pull request #35 from CopperPilot/fix/long-response-truncation.
+  [Aditya]
+
+  fix: stop cutting long hosted answers at the 16 KB status limit
+- Merge pull request #33 from CopperPilot/fix/hosted-stream-stall.
+  [Aditya]
+
+  fix: surface stalled or failed hosted turns instead of hanging
+- Merge pull request #34 from CopperPilot/fix/validate-hierarchical-
+  nets. [Aditya]
+
+  fix(validate): ground findings that cite label names of hierarchical nets
+- Fix(validate): ground findings that cite label names of hierarchical
+  nets. [AdityaNG, Claude Opus 5.5]
+
+  KiCad names local and hierarchical label nets with their sheet path
+  ("/RAIL_IO_3", "/power/RAIL_IO_3"), but reviewers cite the label
+  ("RAIL_IO_3"). Grounding compared the cited name to the full net name
+  only, so every real finding on such a board was marked UNGROUNDED and
+  could never fail a blocking check (WARN / exit 3 instead of FAIL).
+
+  A cited net now grounds when it equals a design net name or is a
+  "/"-boundary suffix of one; invented names still do not.
+- Merge pull request #32 from CopperPilot/fix/recent-projects-race.
+  [Aditya]
+
+  fix: stop concurrent ACP sessions racing on recent-projects state
+
+
+0.1.11 (2026-10-25)
+-------------------
+
+Fix
+~~~
+- Do not block turn cancellation on loading-widget removal. [Cursor,
+  Naveen_Copperpilot]
+
+  Textual defers widget pruning to its message loop. Awaiting that removal during a cancelled turn could leave the turn task pending on Windows, so the cancellation cleanup test timed out.
+- Require Pillow 13 so the security audit passes. [Cursor,
+  Naveen_Copperpilot]
+
+  Pillow 12.3.0 is the newest release the old pin allowed, and pip-audit fails the CI job on four advisories fixed in 13.0.0.
+- Tell the type checker these widgets are Static. [Cursor,
+  Naveen_Copperpilot]
+
+  query() is typed as a generic widget, so ty rejected update() on the working line, the mode icon, and the input rules. CI stopped there before the tests ran.
+- Retry a reconnect the server refuses with HTTP 503. [AdityaNG, Claude
+  Fable 5.1]
+
+  Every "server rejected WebSocket connection: HTTP 503" failure seen from
+  T3 Code follows the same sequence: the hosted pod restarts mid-stream
+  (no close frame), the stitched resume reconnects 5 s later while the
+  backend is still coming back, and the load balancer answers the upgrade
+  with 503. websockets raises InvalidStatus for that, which classify_error
+  did not know, so the turn was typed "unknown", non-retryable, and the
+  remaining attempt was never used.
+
+  - classify InvalidStatus by HTTP status (5xx/429 retry; auth and other
+    4xx fail fast) and InvalidHandshake without a status as a connection
+    drop
+  - include InvalidHandshake in the transport's pre-first-event retry
+  - stretch the turn budget to four attempts (5/10/20/30 s) so it outlasts
+    a typical pod restart
+  - regression tests for the drop-then-503 sequence and the transport retry
+
+Other
+~~~~~
+- Release: version 0.1.11 🚀 [AdityaNG]
+- Merge pull request #31 from naveen-
+  forkd/feat/cli_chat_chrome_2026_10_24. [Aditya]
+
+  Redraw the CLI chat screen, add themes, and make typing faster
+- Test: wait until a tool is active before cancelling. [Cursor,
+  Naveen_Copperpilot]
+- Test: wait for the loading widget to leave after cancel. [Cursor,
+  Naveen_Copperpilot]
+
+  Textual drops the widget on a later prune tick, so an immediate check still sees it on Windows.
+- Test: run the suite in a UTF-8 locale. [Cursor, Naveen_Copperpilot]
+
+  Windows CI has no UTF-8 locale, so the app drew the ASCII fallback and the Unicode snapshots failed. The suite now sets a UTF-8 locale, and a test still checks that a C locale or COPPERPILOT_ASCII selects the fallback.
+- Test: cover theme switching and the input hot path.
+  [Naveen_Copperpilot]
+
+  Check the presets, /theme persistence, idle typing, the pruned file index, and streamed Markdown that keeps closed blocks.
+- Perf: keep typing, file completion, and streaming off the hot path.
+  [Naveen_Copperpilot]
+
+  Skip completion repaints when the matches did not change, and apply a pending @ filter before tab or enter. Build the file list in the background, skip ignored folders, and refresh it when it is stale. Append assistant Markdown only while a block is still open, so a finished paragraph or code fence is not replaced.
+- Perf: import deepagents the first time a tool runs.
+  [Naveen_Copperpilot]
+
+  Opening the UI was paying for the tool stack at import. Load it on the first tool call instead.
+- Test: keep the saved theme out of the suite. [Naveen_Copperpilot]
+
+  Point each test at a temporary CLI home and reset the shared palette. Live tests keep the real home so they can still load the device credential.
+- Feat: let /theme switch presets and remember the choice.
+  [Naveen_Copperpilot]
+
+  /theme opens a picker or takes a name, writes it to config.json, and repaints the chrome that bakes colours into text.
+- Feat: make near-black the default and add theme presets.
+  [Naveen_Copperpilot]
+
+  The warm stone background is now one preset. Black is the default, with warm, light, and high-contrast beside it. Snapshot colours read the active tokens, and the locale encoding is cached so glyph checks do not call locale.getencoding on every paint.
+- Feat: redraw the prompt and bind shift+tab and ctrl+e.
+  [Naveen_Copperpilot]
+
+  Rules replace the rounded box, and one tip sits above them until the first message. shift+tab and ctrl+e were taken by focus movement and end-of-line, so those bindings now take priority and cycle mode and effort while the prompt is focused.
+- Feat: replace the boxed header with a flat welcome and one status
+  line. [Naveen_Copperpilot]
+
+  Drop version, full path, and model from the header. Show the wordmark, repo, and quick start, and put mode and effort on the line under the prompt.
+- Feat: add the plain-text layout for the chat chrome.
+  [Naveen_Copperpilot]
+
+  Welcome, status, slash rows, the working line, and tips are content the widgets render. Only commands, modes, and keys the CLI already has are included.
+- Feat: draw the CopperPilot cube as a Braille mark.
+  [Naveen_Copperpilot]
+
+  Six rows of thirteen cells, one orange. The welcome omits it when the terminal is narrow, uncolored, or ASCII.
+- Feat: switch the CLI theme to the warm orange palette.
+  [Naveen_Copperpilot]
+
+  One orange and warm neutrals, with the same layout in truecolor, 256-color, and NO_COLOR. Status green and red stay limited to tool results.
+- Merge pull request #27 from
+  CopperPilot/feat/disable_model_selector_19_oct_2026. [Aditya]
+
+  feat: hide Intelligence model selection behind ENABLE_MODEL_SELECTOR (off)
+- Feat: hide Intelligence model selection behind ENABLE_MODEL_SELECTOR
+  (off) [AdityaNG, Claude Opus 5.5]
+
+  Add ENABLE_MODEL_SELECTOR to copper_models, set to False. While it is off
+  no surface names a model or offers a choice, and every Intelligence turn
+  asks for the default model (Gemini 4 Argon), including threads saved with
+  another model. Balanced still sends no model. No server change.
+
+  - TUI: no /model command or completion, /context and /help omit the model.
+  - Headless: --model is not registered.
+  - MCP: no models tool, the model argument is dropped from the ask/plan/
+    run/resume schemas, and results omit model/answered_model.
+  - ACP: only mode and effort config options, no /model command, a model
+    config change is rejected, and effort copy names no model.
+  - Fallback notices use a generic "switched to a backup model" message.
+
+  Flipping the constant to True restores the previous behaviour; the
+  existing model-selection tests run with it on via a fixture.
+- Merge pull request #28 from
+  CopperPilot/feat/agent_latency_cli_19_oct_2026. [Aditya]
+
+  Run tool_requests batches concurrently (parallel_tool_requests capability)
+- Keep batched tool calls on one assistant message; test ACP overlap.
+  [AdityaNG, Claude Opus 5.5]
+
+  The transcript records a batch's calls on a single AIMessage so every
+  call is followed by its result whatever the completion order. ACP already
+  keys tool_call / tool_call_update by id; a test now covers three
+  overlapping calls completing out of order.
+- Execute tool_requests batches concurrently over the chat socket.
+  [AdityaNG, Claude Opus 5.5]
+
+  chat_start advertises the parallel_tool_requests capability (disable with
+  COPPER_PILOT_PARALLEL_TOOLS=0). A batch frame yields one TOOL_REQUEST per
+  call, runs them with the scheduler and sends each tool_result, matched by
+  tool_call_id, as soon as it completes. Single tool_request frames are
+  unchanged. The hosted attempt is now closed deterministically so a
+  consumer that stops listening cancels running batch members, and the
+  local broker serializes approval and question prompts.
+- Add a scheduler for parallel tool-request batches. [AdityaNG, Claude
+  Opus 5.5]
+
+  Classifies each hosted tool request as READ, MUTATING (keyed by path) or
+  EXCLUSIVE and runs a batch with model-order dependencies: reads overlap
+  (capped at 8), same-path mutations run in order, shell commands that are
+  not provably read-only run alone. Failures are reported per tool and
+  closing the batch cancels unfinished members.
+- Merge pull request #26 from CopperPilot/feat/acp-usage-limit-reset.
+  [Aditya]
+
+  feat(acp): explain usage limits with their reset time
+- Merge remote-tracking branch 'origin/main' into feat/acp-usage-limit-
+  reset. [AdityaNG]
+
+  # Conflicts:
+  #	docs/cli.md
+  #	src/copper_pilot_cli/copper_acp.py
+  #	tests/test_acp.py
+- Merge pull request #25 from CopperPilot/t3/intelligence-mode-model-
+  selection. [Aditya]
+
+  feat: Intelligence model selection across TUI, CLI, MCP, and ACP
+- Feat: default Intelligence to Gemini 4 Argon, Gemini models first.
+  [AdityaNG, Claude Fable 5.1]
+
+  Mirror copper-pilot-client #98: the bundled catalog now lists the Gemini
+  models first and defaults Intelligence to gemini-4-argon. The server's
+  catalog order and default still win whenever it is reachable.
+- Feat: Intelligence model selection across TUI, CLI, MCP, and ACP.
+  [AdityaNG, Claude Fable 5.1]
+
+  Mirror the desktop client's Intelligence model picker (copper-pilot#97):
+  Balanced always runs on the server's Balanced model; Intelligence turns
+  may pick one model from the hosted catalog (Claude Opus 5.5 default).
+
+  - copper_models: catalog fetched once per process from
+    GET /api/copperpilot/chat/models with the bundled list as fallback,
+    plus model_fallback status-event helpers.
+  - ChatRequest.model is sent only on Intelligence turns; the thread
+    checkpoint persists copper_model next to copper_effort.
+  - CLI --model (implies --effort intelligence), TUI /model and /context,
+    and model_fallback notices in the transcript and headless output.
+  - MCP: model argument on ask/plan/run/resume, a models tool, and
+    model/answered_model in results and the digest.
+  - ACP: a model config option (category model) next to effort
+    (thought_level); choosing a model selects Intelligence, Balanced pins
+    the option to the Balanced model, /model slash command, and fallback
+    notices as agent messages.
+- Test(acp): accept a usage reset that falls after midnight. [AdityaNG,
+  Claude Opus 5.5]
+- Feat(acp): explain usage limits with their reset time. [AdityaNG,
+  Claude Opus 5.5]
+
+  A turn refused by the usage window or weekly limit reached ACP clients as a
+  generic -32603 error whose text carried a raw UTC timestamp, or for a refused
+  handshake only "HTTP 402".
+
+  - Keep the reset time from the hosted error frame's detail
+    (window_ends_at / week_ends_at) on ProtocolError and the error event.
+  - ACP fails such a turn with code -32003 and a message naming the spent
+    limit and its local reset time ("It resets at 3:20 AM (in 2h 23m).");
+    data carries class=usage_limit, blockReason and resetAt. Without a reset
+    time in the frame, the token-limits endpoint fills it in; a bare 402 the
+    account view does not confirm (the Intelligence plan gate) is unchanged.
+  - The graph keeps a refused handshake's HTTP status on its error event.
+  - ACP drops the terminal "Attempt N failed" thought that repeated the error.
+  - New ACP /usage command shows the window, weekly balance and reset times.
+  - The TUI renders usage blocks with the same local reset time.
+- Merge pull request #24 from CopperPilot/fix/retry-refused-handshake.
+  [Aditya]
+
+  fix: retry a reconnect the server refuses with HTTP 503
+
+
+0.1.10 (2026-10-18)
+-------------------
+
 Fix
 ~~~
 - Skip the killed-background resume test on Windows. [AdityaNG, Cursor]
@@ -17,6 +328,7 @@ Fix
 
 Other
 ~~~~~
+- Release: version 0.1.10 🚀 [AdityaNG]
 - Merge pull request #23 from CopperPilot/feat/acp-image-prompts.
   [Aditya]
 

{copper_pilot_cli-0.1.10 → copper_pilot_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copper-pilot-cli
-Version: 0.1.10
+Version: 1.0.0
 Summary: CopperPilot hosted agent for the terminal and LangChain
 Project-URL: Homepage, https://copperpilot.ai
 Project-URL: Repository, https://github.com/CopperPilot/copper-pilot-cli
@@ -29,7 +29,7 @@ Requires-Dist: langgraph<2,>=1.2
 Requires-Dist: markdownify<2,>=1.2
 Requires-Dist: mcp<2,>=1.21
 Requires-Dist: packaging<27,>=25
-Requires-Dist: pillow<13,>=12
+Requires-Dist: pillow<14,>=13
 Requires-Dist: pydantic<3,>=2.12
 Requires-Dist: pyperclip<2,>=1.11
 Requires-Dist: pyyaml<7,>=6
@@ -118,7 +118,9 @@ Both `copper-pilot` and `copper-pilot-cli` run the same program.
 command reference.
 
 Balanced effort is the default. Paid-plan users can select Intelligence with
-`--effort intelligence` or interactive `/effort`. Intelligence uses
+`--effort intelligence` or interactive `/effort`; Intelligence runs on Gemini 4
+Argon. Picking another model (`--model <id>`, `/model`) is turned off for now
+(`ENABLE_MODEL_SELECTOR` in `copper_models.py`). Intelligence uses
 server-owned survey subagents and shows their lifecycle through the existing
 Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
 
@@ -183,6 +185,7 @@ PLAN = CopperMode.PLAN
 copper_pilot = CopperPilotAgent(
     workspace="esp32",
     effort=CopperEffort.INTELLIGENCE,
+    model="claude-opus-5-5",  # optional; Intelligence defaults to Gemini 4 Argon
 )
 
 run(copper_pilot, "Build me an ESP32 dev board.", PLAN)

{copper_pilot_cli-0.1.10 → copper_pilot_cli-1.0.0}/README.md

@@ -64,7 +64,9 @@ Both `copper-pilot` and `copper-pilot-cli` run the same program.
 command reference.
 
 Balanced effort is the default. Paid-plan users can select Intelligence with
-`--effort intelligence` or interactive `/effort`. Intelligence uses
+`--effort intelligence` or interactive `/effort`; Intelligence runs on Gemini 4
+Argon. Picking another model (`--model <id>`, `/model`) is turned off for now
+(`ENABLE_MODEL_SELECTOR` in `copper_models.py`). Intelligence uses
 server-owned survey subagents and shows their lifecycle through the existing
 Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
 
@@ -129,6 +131,7 @@ PLAN = CopperMode.PLAN
 copper_pilot = CopperPilotAgent(
     workspace="esp32",
     effort=CopperEffort.INTELLIGENCE,
+    model="claude-opus-5-5",  # optional; Intelligence defaults to Gemini 4 Argon
 )
 
 run(copper_pilot, "Build me an ESP32 dev board.", PLAN)

copper_pilot_cli-1.0.0/VERSION

@@ -0,0 +1 @@
+1.0.0

{copper_pilot_cli-0.1.10 → copper_pilot_cli-1.0.0}/docs/cli.md

@@ -33,6 +33,7 @@ valid.
 | `--json` | Emit JSON events (or a final JSON document with `--no-stream`). |
 | `--mode {agent,plan,ask}` | Hosted chat mode. Default: `agent`. |
 | `--effort {balanced,intelligence}` | Hosted effort. Default: `balanced`; Intelligence requires a paid plan. |
+| `--model MODEL` | Intelligence model id (see below). Implies `--effort intelligence`; rejected with `--effort balanced`. |
 | `-y`, `--auto-approve` | Auto approval: routine writes and known-safe shell still run; unknown actions prompt. |
 | `--yolo` | Permit local side effects without prompting. Must be set explicitly. |
 | `--version` | Print the package version. |
@@ -45,6 +46,7 @@ copper-pilot --resume
 copper-pilot -n -m "Review this board" --json
 copper-pilot ./my-board --mode plan -m "Propose a power tree"
 copper-pilot ./my-board --mode plan --effort intelligence -m "Survey and plan the power tree"
+copper-pilot ./my-board --model gpt-6.1-sol -m "Review the USB-C front end"
 ```
 
 Headless mode is also used when `--message` is set and stdout is not a TTY.
@@ -97,15 +99,18 @@ write to stdout; the protocol owns it.
 | Tool | Role |
 |------|------|
 | `status` | Login state and discovered schematic/PCB paths. No hosted call. |
-| `ask` | `--mode ask`. Auto approval. Optional `thread_id` and `effort`. |
-| `plan` | `--mode plan`. Auto approval. Optional `effort`. |
-| `run` | `--mode agent`. Optional `effort`; `approval` is `auto` (default) or `yolo`. |
-| `resume` | Continue `thread_id`. Optional `mode`, `effort`, and the same approval as `run`. |
+| `models` | Intelligence model ids, labels, prices, and the Balanced model. No hosted turn. |
+| `ask` | `--mode ask`. Auto approval. Optional `thread_id`, `effort`, `model`. |
+| `plan` | `--mode plan`. Auto approval. Optional `effort`, `model`. |
+| `run` | `--mode agent`. Optional `effort`, `model`; `approval` is `auto` (default) or `yolo`. |
+| `resume` | Continue `thread_id`. Optional `mode`, `effort`, `model`, and the same approval as `run`. |
 | `threads_list` | List threads for this workspace (`limit`, `all_workspaces`). |
 | `validate` | Read-only stage-gated review; returns `verdict`, `exit_code`, `report_path`, `next_actions`. |
 
 Workspace is the tool argument, else `CLAUDE_PROJECT_DIR`, else the process
-current directory. Manual approval is TUI-only. See [harness.md](harness.md).
+current directory. Manual approval is TUI-only. Passing `model` selects
+Intelligence on that model; the result carries `model` (requested) and
+`answered_model` (after any server fallback). See [harness.md](harness.md).
 
 ## ACP
 
@@ -125,14 +130,15 @@ advertises a terminal auth method that runs `copper-pilot auth login`.
 | ACP feature | CopperPilot behavior |
 |-------------|----------------------|
 | Session modes | `ask`, `plan`, `agent` (default `agent`) |
-| Config options | `mode` and `effort` (`balanced` default, `intelligence` paid) |
+| Config options | `mode`, `effort` (`balanced` default, `intelligence` paid), and `model` (category `model`; the Intelligence catalog) |
 | `session/load` | Resumes an existing thread id and replays its history |
 | `session/request_permission` | Auto approval; non-routine writes and shell prompt the editor |
 | `elicitation/create` | Clarifying questions (options or free text) when the client advertises form elicitation |
 | `session/cancel` | Cancels the hosted turn and local tools |
 | `usage_update` | Prompt tokens of the latest hosted turn; window size is unknown (0) |
 | `plan` | Hosted todo list events and `.copperpilot/plans/*.plan.md` todos |
-| `available_commands_update` | `/effort balanced\|intelligence`, answered locally |
+| `available_commands_update` | `/effort balanced\|intelligence`, `/model [id]`, and `/usage`, answered locally |
+| Prompt error `-32003` | A usage limit refused the turn; see below |
 
 "Allow all for this session" switches that session to YOLO until the server
 exits; it is never saved. Clarifying questions use ACP form elicitation when
@@ -146,7 +152,29 @@ Intelligence survey workers appear as `think` tool calls named
 `Survey: <task>` whose status and output track the worker.
 See [harness.md](harness.md).
 
-## Effort and Intelligence
+A turn refused by a usage limit fails with JSON-RPC error `-32003` (the code
+xAI's Grok ACP agent uses for the same condition). The message names the
+spent limit and when it lifts in local time, for example `CopperPilot usage
+limit reached: the current usage window is used up. It resets at 3:20 AM (in
+2h 23m).` `data` repeats it for clients that render a usage-limit notice:
+
+```json
+{
+  "details": "CopperPilot usage limit reached: ...",
+  "class": "usage_limit",
+  "blockReason": "window",
+  "resetAt": "2026-10-19T21:50:00Z",
+  "canPurchaseOverage": false,
+  "retryable": false
+}
+```
+
+When the hosted error carries no reset time (a refused handshake), the server
+reads it from the token-limits endpoint. A team cost cap, billing, or busy
+block has no reset time and keeps the hosted wording. `/usage` prints the
+current window, weekly balance, and reset times without a hosted turn.
+
+## Effort, Intelligence, and models
 
 Balanced is the default. Intelligence is available on paid plans and lets the
 hosted parent run one to four survey subagents. Intelligence Plan turns survey
@@ -154,10 +182,41 @@ before creating or revising a plan. Workers are server-owned, survey-only, and
 appear in the TUI through the existing Deep Agents task rows; they do not open
 nested chats or execute through the local tool broker.
 
-The interactive `/effort` command changes effort for the current thread.
-Resuming that thread restores it; a new thread starts Balanced. In headless
-text mode, worker state changes print as compact lines. `--json` retains raw
-`status_event` objects.
+> **Model selection is currently off.** `ENABLE_MODEL_SELECTOR` in
+> `src/copper_pilot_cli/copper_models.py` is `False`: every Intelligence turn
+> runs on Gemini 4 Argon, no surface names a model, and `--model`, `/model`,
+> the MCP `models` tool and `model` argument, and the ACP `model` config option
+> are not offered. A fallback notice reads "Switched this chat to a backup
+> model." The rest of this section describes the behaviour when it is `True`.
+
+Balanced always runs on the server's Balanced model (Google Gemini 3.8 Flash);
+there is no model choice on a free account. Intelligence runs on one model
+from the catalog, Gemini 4 Argon by default (the server's catalog order and
+default win when it is reachable):
+
+| Id | Model |
+|----|-------|
+| `gemini-4-argon` | Google Gemini 4 Argon (Intelligence default) |
+| `gemini-3.8-flash` | Google Gemini 3.8 Flash (Balanced model) |
+| `claude-opus-5-5` | Claude Opus 5.5 |
+| `claude-sonnet-5-5` | Claude Sonnet 5.5 |
+| `gpt-6-astra` | OpenAI GPT-6 Astra |
+| `gpt-6.1-sol` | OpenAI GPT-6.1 Sol |
+
+The list is fetched from `GET /api/copperpilot/chat/models` once per process
+and falls back to this bundled copy when the deployment does not publish it.
+Choosing a model selects Intelligence, the same rule as the desktop picker;
+`--effort balanced` together with `--model` is an error. The model is sent
+only on Intelligence turns and the server resolves unknown ids to the default.
+
+The interactive `/effort` and `/model [id]` commands change effort and model
+for the current thread; `/context` shows the model the next turn will use.
+Resuming a thread restores both; a new thread starts Balanced. When the
+selected model is unavailable the server falls back to a Gemini model and
+sends a `model_fallback` status event; the TUI posts its message in the
+transcript, headless mode prints it in yellow, and `--json` retains the raw
+`status_event`. In headless text mode, worker state changes print as compact
+lines.
 
 Interactive clarification can offer suggested answers, custom text, or Skip
 and waits without a client timeout. Headless and MCP calls cannot present that
@@ -219,14 +278,16 @@ Every front-end (TUI, headless, MCP, ACP) runs a hosted turn through the same
 checkpointed graph node, which mirrors the desktop client's chat manager:
 
 - A stream that drops before the final frame (socket close, timeout, 5xx, 429)
-  is retried up to three times with 5 s, 10 s, and 20 s backoff. The retry
+  or a reconnect that the server refuses at the websocket handshake (HTTP 503
+  while a backend restarts, 429, other 5xx) is retried up to four times with
+  5 s, 10 s, 20 s, and 30 s backoff. The retry
   re-prompts the hosted agent with the partial transcript and
   `Resume where we left off: <original message>` so it continues rather than
   restarting. Deterministic failures (4xx other than 429, invalid or oversized
   requests, plan refusals, auth) fail immediately.
 - Retry progress is visible: the TUI status bar and a notification, a yellow
   line in headless text mode, MCP progress, and ACP agent thoughts
-  (`Retrying (1/2) in 5s: …`). `--json` emits `copper.retry` events.
+  (`Retrying (1/3) in 5s: …`). `--json` emits `copper.retry` events.
 - The websocket close code and reason are carried into the error message
   (`close code 1011 received: …`) and the log file.
 - Whatever a failed turn produced before the error (assistant text, tool calls
@@ -266,15 +327,18 @@ as an object:
     "status": 402,
     "block_reason": "weekly",
     "can_purchase_overage": true,
-    "retryable": false
+    "retryable": false,
+    "resets_at": "2026-10-21T02:56:47Z"
   }
 }
 ```
 
-`block_reason` is `window`, `weekly`, `cost_cap`, `busy`, or `billing` when
+`resets_at` is present for a `window` or `weekly` block when the server sends
+the reset time. `block_reason` is `window`, `weekly`, `cost_cap`, `busy`, or `billing` when
 the server sends one. A `busy` block and an ordinary rate limit use status
 `429` with `retryable: true`. `can_purchase_overage` only says whether the
-billing page can offer additional usage. The Textual UI prints `message`.
+billing page can offer additional usage. The Textual UI prints `message`,
+with a window or weekly reset time in local time (`It resets at 3:20 AM (in 2h 23m).`).
 
 ## Configuration
 

{copper_pilot_cli-0.1.10 → copper_pilot_cli-1.0.0}/docs/development.md

@@ -88,7 +88,9 @@ the object.
 `classify_error` in `copper_protocol.py` ports the desktop client's error
 categories (`timeout`, `connection`, `server`, `rate_limit`, `usage_limit`,
 `authentication`, `invalid_request`, `payload_too_large`, `protocol`,
-`network`, `aborted`, `unknown`) with a `retryable` flag. The graph node in
+`network`, `aborted`, `unknown`) with a `retryable` flag, including websocket
+handshakes the server refuses with an HTTP status (`InvalidStatus`: 5xx and
+429 retry, auth and other 4xx do not). The graph node in
 `copper_graph.py` owns the retry loop, the stitched "Resume where we left off"
 re-prompt, partial-progress checkpointing, and the background shell wait;
 `copper_background.py` owns the foreground-to-background shell contract.