@phenx-inc/ctlsurf 0.17.2 → 0.17.3

package/README.md

@@ -1,6 +1,6 @@
 # ctlsurf worker
 
-The terminal that remembers. Run Claude Code, Codex, or any coding agent inside it, and everything about the session lands in your [ctlsurf](https://ctlsurf.com) project automatically: live transcript, time attribution, tickets, and an observer digest. The agent does not have to cooperate, or even know.
+The terminal that remembers. Run Claude Code, Codex, or any coding agent inside it, and everything about the session lands in your [ctlsurf](https://ctlsurf.com) project automatically: live transcript, time attribution, and tickets. The agent does not have to cooperate, or even know.
 
 ```bash
 npx @phenx-inc/ctlsurf
@@ -14,7 +14,6 @@ Works as a desktop app (macOS, Windows) or fully headless on a server.
 - **Watch and drive it from anywhere.** The session streams live to your project at [app.ctlsurf.com](https://app.ctlsurf.com); open a browser on another machine to watch the agent work, and type back into the session remotely.
 - **Automatic time tracking.** Each session becomes rows in the project's time-tracking datastore. The billing report reads straight from it.
 - **Tickets from the terminal.** File a ticket without leaving the session; it lands on a cross-project board.
-- **The Observer.** A supervision layer that tails the agent's transcript and the terminal's activity into an append-only local ledger, producing findings and time spans, with a session-end digest written to your project. Advisory only: every code path is wrapped so observation can never block or slow the working agent.
 
 ## Why outside-in recording
 
@@ -34,3 +33,27 @@ Docs: [ctlsurf.com/docs](https://ctlsurf.com/docs) · Free tier includes 1 conne
 ## Requirements
 
 Node.js 18+. A ctlsurf account (free tier works).
+
+## Development status
+
+**Live work map.** Open **Work map** in the titlebar (Ctrl+Shift+M), choose **Clef-Flash · local** or **Rules · lightweight**, and turn the map on. One chronological thread combines stated choices, hypotheses, readable thinking, actions, and results. Choice cards show the selected excerpt and its stated reason; following actions remain underneath in the same thread. Collapsible groups keep the semantic topics while preserving event order when Clef updates their placement. Expanding a thinking card loads the complete readable source block on demand and highlights the selected choice and reason. Full source text stays out of live map snapshots. Scrolling up pauses following; **Follow latest** returns to the newest activity. Closing the pane hides it; its On/Off switch controls collection for all local tabs.
+
+Work map is currently limited to the **desktop app on Apple Silicon Macs with an available Metal GPU**. npm installation performs a lightweight hardware check, without downloading or loading a model. Desktop startup checks the hardware again and verifies that Electron can access the Apple GPU. The option stays disabled during detection and on unsupported machines, including when saved preferences previously enabled it. GPU detection never blocks installation or other app features. The terminal/headless version does not start map collection or inference. HTTP and Cloudflare providers are not enabled in this release.
+
+Claude Code's readable `thinking` blocks and Codex's public reasoning summaries (response items, completed reasoning items, and legacy `agent_reasoning` events) feed the same pipeline. Candidate segments come from the complete readable block before the source preview is shortened; Clef selects the important choice and a supporting reason, rather than only a type label. Public agent updates can also state decisions and are labelled as updates. The recent stated reasoning informs placement of following actions. Encrypted, redacted, or omitted reasoning is never treated as readable thinking. The panel reports when summaries are unavailable, rather than inferring private decisions from tool output. Some models/sessions omit readable summaries entirely. [Claude thinking format](https://platform.claude.com/docs/en/build-with-claude/thinking), [Codex reasoning summaries](https://learn.chatgpt.com/docs/app-server).
+
+Clef-Flash suggests branch placement and activity types. Titles come from transcript text and tool inputs; execution status comes from linked runtime results. Unknown results remain unverified. This is a map of recorded activity, not a claim that the overall task succeeded. Maps stay in memory, retain at most 240 nodes per tab, and reset when the session is replaced or the app exits. The map does not upload transcripts or turn on Observer. Session discovery follows recent transcript files by agent and directory; it cannot reliably distinguish simultaneous independent agent processes in the same directory.
+
+The local engine uses one shared, offline Python/MLX worker on Apple Silicon. It processes at most two events per request, caps input at 2,048 tokens, limits the pending queue to 24 events per tab, applies MLX allocation/cache limits, and unloads after 60 seconds idle or when mapping is turned off. A watchdog unloads a process exceeding 16 GiB RSS. These are resource guards, not a guarantee against system-wide memory pressure. Requests that fail leave the transcript-based map available and surface an error with a Retry control.
+
+This checkout automatically reuses the local pilot's downloaded Clef-Flash runtime. On another Mac, install `uv` and prepare only Clef-Flash (approximately 11 GB of model weights):
+
+```sh
+python3 scripts/prepare-work-map.py
+```
+
+The script prints the Python executable and model folder for **Local model setup**. These paths can also be supplied with `CTLSURF_CLEF_PYTHON` and `CTLSURF_CLEF_MODEL` before launch. Selecting an engine or opening the pane does not download model files. Rules needs no model or Python installation.
+
+Validation: `npm run test:workmap`, `npm run test:workmap:ui`. To also load the pilot's actual weights for one offline decision-extraction inference and unload check: `node scripts/test-work-map.cjs --real-clef`. Optional `--replay-claude /path/session.jsonl` and `--replay-codex /path/rollout.jsonl` replay local files and print only diagnostic counts, never transcript text.
+
+**Observer — on hold.** Its supervision engine, IPC, saved settings and panel code are retained for future work. It is removed from the app's controls and Settings, and runtime is disabled in the orchestrator, including for previously enabled installations.