feat: harness v2 foundation and durable task orchestration

.gitignore

@@ -9,3 +9,6 @@
 /threadlane-updater.key.pub
 theadline_private_key_password
 .tokensave
+.makepad
+
+.worktrees/

AGENTS.md

@@ -46,7 +46,7 @@ cargo test --workspace
 # Build and deploy WASI extensions
 ./scripts/build_extensions.sh
 
-# Run the desktop app
+# Run the desktop app directly only for non-visual debugging
 cargo run -p threadlane
 
 # Check patch whitespace
@@ -63,6 +63,45 @@ cargo run -p threadlane
 
 A normal `cargo run` may be unsuitable for testing installation: update installation and relaunch are intentionally restricted to a packaged `.app`.
 
+### Makepad Studio runtime debugging
+
+Use Makepad Studio for Threadlane UI/runtime verification. The repository root
+contains `makepad.splash`, which exposes the `threadlane` Cargo package as a
+Studio runnable item.
+
+Install and start Studio once on a machine with a working Metal device:
+
+```bash
+cargo install --git https://github.com/makepad/makepad makepad-studio --locked
+makepad-studio --mounts=makepad:$PWD
+```
+
+In a second terminal, start the localhost bridge and keep it running for the
+whole interaction:
+
+```bash
+cargo-makepad studio --studio=127.0.0.1:8001
+```
+
+Send newline-delimited JSON requests to the bridge. For a fresh visual run:
+
+1. Send `{"ListBuilds":[]}` and clear any existing Threadlane build with
+   `{"ClearBuild":{"build_id":[N]}}`.
+2. Launch the current source with
+   `{"RunItem":{"mount":"makepad","name":"threadlane"}}`.
+3. Wait for `BuildStarted` and application startup before inspecting the app.
+4. Use `{"WidgetTreeDump":{"build_id":[N]}}` for widget IDs and coordinates,
+   `{"Screenshot":{"build_id":[N]}}` for visual evidence, and `Click`,
+   `TypeText`, and `Return` for interaction checks.
+5. After every UI/runtime edit, clear the old build and start a new Studio run;
+   never validate a stale build. Inspect Studio build logs for script type-check
+   errors because Makepad DSL failures can occur after Rust compilation.
+
+Keep the bridge and Studio bound to localhost. Do not use `ObserveMount` or
+bind Studio to `0.0.0.0` for ordinary debugging. Studio may create a local
+`.makepad/` state directory; it is generated runtime state and must not be
+edited or committed.
+
 ## Validation Expectations
 
 1. Start with the narrowest relevant test or check.
@@ -235,6 +274,7 @@ If changing ordering, row height, popup padding, or selected-item behavior, upda
 ## Session and Context-Menu Behavior
 
 - Project terminal groups are keyed by canonical project work directory, not by session ID. Each project can own multiple independent shell tabs; switching sessions in one project must retain its shells, active tab, and output, while switching projects selects that project's terminal group.
+- The GPUI terminal is a persistent `portable-pty` shell parsed through `vt100`, not a command-by-command `sh -lc` console. Keep PTY reads off the UI thread, apply parser updates through GPUI entity updates, forward focused keyboard input directly to the PTY, and retain terminal entities by project when switching workspaces.
 - Model-managed todo plans are session-scoped and persisted as complete `session_plan` records in the existing session JSONL. Show only the active session's plan above the project-wide task groups; do not derive plan state from compactable tool-call history or merge it into supervisor task state.
 
 - The project attach button appears while hovering the `PROJECTS` header. It is the only sidebar action synchronized from `App::sync_sidebar_action_visibility` and the retained app-level pointer.
@@ -267,11 +307,17 @@ If changing ordering, row height, popup padding, or selected-item behavior, upda
 
 ## Background Tasks and Capabilities
 
-- `HarnessSupervisor` owns only explicit background tasks (currently `/task <prompt>`). Ordinary chat sessions continue to use the existing `SessionRuntime` path and must not be mirrored into supervisor tasks.
-- Harness side effects are intent-first: persist `OperationStarted`, `TaskAttempt`, `ToolStarted`, and `QueueEnqueued` under the lane lock before starting the corresponding model/tool work or mutating the in-memory queue. `ToolExecutionStart` is observational only.
-- Child intent is durable before model/tool work; checkpoints use `WriteDeferred`; safe replay is automatic and unsafe interruption aborts.
-- Model subagents execute with short-lived child `Agent`s but persist as passive sibling branches on the parent `SessionTree`; only the formatted final tool result enters the parent active branch.
+- `HarnessSupervisor` owns only explicit background tasks (currently `/task <prompt>`). Ordinary chat sessions continue to use the existing `SessionRuntime` path and must not be mirrored into supervisor tasks. Supervisor task status is derived from canonical harness snapshots and events; it does not own a second operation log or lane-recovery authority.
+- `CodingSessionHarness` (`coding_agent/harness.rs`) is the canonical session adapter. Production code must route foreground, `/task`, and model subagent durable operations through it. No production caller may directly append session or operation-log records outside this harness path.
+- Durable operations are intent-first: persist `OperationStarted`, `StepAttempt`, `ToolStarted`, and `QueueEnqueued` through `CodingSessionHarness`/`SessionAgent` before starting provider/tool work. `ToolExecutionStart` is observational only.
+- Child intent is durable before model/tool work; checkpoints use `WriteDeferred`; safe replay is automatic and unsafe interruption aborts. Child subagent lanes use the canonical `SessionAgent` path with deterministic identity derived from parent session + tool-call ID.
+- Concurrent child lanes can hold independently opened JSONL stores. Reload and rebase stale sequence inputs while holding the shared writer gate at the append boundary; sequence numbers allocated from an earlier snapshot are not authoritative.
 - Forward supervisor events through `GuiAgentEvent`; update `BackgroundTaskState` and widgets only on the Makepad event thread.
+- GPUI model mutations must call `cx.notify()` inside the `Entity::update` callback when observers need to redraw; mutating `AppState` without notification leaves optimistic messages and streamed updates invisible until another interaction causes a render.
+- In the GPUI chat path, `CodingAgent` is the sole owner of durable prompt persistence. Show an accepted prompt optimistically in `AppState.messages`, but do not also append it directly to `SessionTree` before `handle_input_with_images`, which would persist the same user message twice. Forward `AgentEvent`s to the GPUI thread and reconcile from the session file only when the run finishes.
+- GPUI sessions reuse one `SessionRuntime`/`CodingAgent` per durable session on a shared Tokio executor. Register each spawned turn with `CodingAgentCancellation::track_active_run` before exposing cancellation, and call `finish_active_run` after normal completion; `cancel()` records durable abort intent before aborting the registered task.
+- GPUI message queue and steer actions must use the active runtime's `CodingAgentWorkHandle` (`try_queue_follow_up_with_images` and `queue_steer_with_images`). Stage composer text per session, persist queue intent before optimistic presentation, and let `CodingAgent::run_scheduled_agent_work` consume it rather than creating a GUI-only queue.
+- `CodingAgent::new` opens `CodingSessionHarness` against the supplied session JSONL itself. Harness V2 records and legacy session records intentionally coexist in that canonical file; do not invent a GPUI-only `.harness.jsonl` sidecar. Existing `.harness.jsonl` filtering remains for legacy sidecars.
 - Threadlane extensions are compiled WASI modules with an exported
   `extension_info` manifest. The settings picker installs a `.wasm` into either
   `~/.threadlane/extensions/` or `<project>/.threadlane/extensions/`; it never