@symerian/symi 3.0.21 → 3.0.22

package/docs/experiments/onboarding-config-protocol.md

@@ -1,40 +0,0 @@
----
-summary: "RPC protocol notes for onboarding wizard and config schema"
-read_when: "Changing onboarding wizard steps or config schema endpoints"
-title: "Onboarding and Config Protocol"
----
-
-# Onboarding + Config Protocol
-
-Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.
-
-## Components
-
-- Wizard engine (shared session + prompts + onboarding state).
-- CLI onboarding uses the same wizard flow as the UI clients.
-- Gateway RPC exposes wizard + config schema endpoints.
-- macOS onboarding uses the wizard step model.
-- Web UI renders config forms from JSON Schema + UI hints.
-
-## Gateway RPC
-
-- `wizard.start` params: `{ mode?: "local"|"remote", workspace?: string }`
-- `wizard.next` params: `{ sessionId, answer?: { stepId, value? } }`
-- `wizard.cancel` params: `{ sessionId }`
-- `wizard.status` params: `{ sessionId }`
-- `config.schema` params: `{}`
-
-Responses (shape)
-
-- Wizard: `{ sessionId, done, step?, status?, error? }`
-- Config schema: `{ schema, uiHints, version, generatedAt }`
-
-## UI Hints
-
-- `uiHints` keyed by path; optional metadata (label/help/group/order/advanced/sensitive/placeholder).
-- Sensitive fields render as password inputs; no redaction layer.
-- Unsupported schema nodes fall back to the raw JSON editor.
-
-## Notes
-
-- This doc is the single place to track protocol refactors for onboarding/config.

package/docs/experiments/plans/browser-evaluate-cdp-refactor.md

@@ -1,229 +0,0 @@
----
-summary: "Plan: isolate browser act:evaluate from Playwright queue using CDP, with end-to-end deadlines and safer ref resolution"
-owner: "symi"
-status: "draft"
-last_updated: "2026-02-10"
-title: "Browser Evaluate CDP Refactor"
----
-
-# Browser Evaluate CDP Refactor Plan
-
-## Context
-
-`act:evaluate` executes user provided JavaScript in the page. Today it runs via Playwright
-(`page.evaluate` or `locator.evaluate`). Playwright serializes CDP commands per page, so a
-stuck or long running evaluate can block the page command queue and make every later action
-on that tab look "stuck".
-
-PR #13498 adds a pragmatic safety net (bounded evaluate, abort propagation, and best-effort
-recovery). This document describes a larger refactor that makes `act:evaluate` inherently
-isolated from Playwright so a stuck evaluate cannot wedge normal Playwright operations.
-
-## Goals
-
-- `act:evaluate` cannot permanently block later browser actions on the same tab.
-- Timeouts are single source of truth end to end so a caller can rely on a budget.
-- Abort and timeout are treated the same way across HTTP and in-process dispatch.
-- Element targeting for evaluate is supported without switching everything off Playwright.
-- Maintain backward compatibility for existing callers and payloads.
-
-## Non-goals
-
-- Replace all browser actions (click, type, wait, etc.) with CDP implementations.
-- Remove the existing safety net introduced in PR #13498 (it remains a useful fallback).
-- Introduce new unsafe capabilities beyond the existing `browser.evaluateEnabled` gate.
-- Add process isolation (worker process/thread) for evaluate. If we still see hard to recover
-  stuck states after this refactor, that is a follow-up idea.
-
-## Current Architecture (Why It Gets Stuck)
-
-At a high level:
-
-- Callers send `act:evaluate` to the browser control service.
-- The route handler calls into Playwright to execute the JavaScript.
-- Playwright serializes page commands, so an evaluate that never finishes blocks the queue.
-- A stuck queue means later click/type/wait operations on the tab can appear to hang.
-
-## Proposed Architecture
-
-### 1. Deadline Propagation
-
-Introduce a single budget concept and derive everything from it:
-
-- Caller sets `timeoutMs` (or a deadline in the future).
-- The outer request timeout, route handler logic, and the execution budget inside the page
-  all use the same budget, with small headroom where needed for serialization overhead.
-- Abort is propagated as an `AbortSignal` everywhere so cancellation is consistent.
-
-Implementation direction:
-
-- Add a small helper (for example `createBudget({ timeoutMs, signal })`) that returns:
-  - `signal`: the linked AbortSignal
-  - `deadlineAtMs`: absolute deadline
-  - `remainingMs()`: remaining budget for child operations
-- Use this helper in:
-  - `src/browser/client-fetch.ts` (HTTP and in-process dispatch)
-  - `src/node-host/runner.ts` (proxy path)
-  - browser action implementations (Playwright and CDP)
-
-### 2. Separate Evaluate Engine (CDP Path)
-
-Add a CDP based evaluate implementation that does not share Playwright's per page command
-queue. The key property is that the evaluate transport is a separate WebSocket connection
-and a separate CDP session attached to the target.
-
-Implementation direction:
-
-- New module, for example `src/browser/cdp-evaluate.ts`, that:
-  - Connects to the configured CDP endpoint (browser level socket).
-  - Uses `Target.attachToTarget({ targetId, flatten: true })` to get a `sessionId`.
-  - Runs either:
-    - `Runtime.evaluate` for page level evaluate, or
-    - `DOM.resolveNode` plus `Runtime.callFunctionOn` for element evaluate.
-  - On timeout or abort:
-    - Sends `Runtime.terminateExecution` best-effort for the session.
-    - Closes the WebSocket and returns a clear error.
-
-Notes:
-
-- This still executes JavaScript in the page, so termination can have side effects. The win
-  is that it does not wedge the Playwright queue, and it is cancelable at the transport
-  layer by killing the CDP session.
-
-### 3. Ref Story (Element Targeting Without A Full Rewrite)
-
-The hard part is element targeting. CDP needs a DOM handle or `backendDOMNodeId`, while
-today most browser actions use Playwright locators based on refs from snapshots.
-
-Recommended approach: keep existing refs, but attach an optional CDP resolvable id.
-
-#### 3.1 Extend Stored Ref Info
-
-Extend the stored role ref metadata to optionally include a CDP id:
-
-- Today: `{ role, name, nth }`
-- Proposed: `{ role, name, nth, backendDOMNodeId?: number }`
-
-This keeps all existing Playwright based actions working and allows CDP evaluate to accept
-the same `ref` value when the `backendDOMNodeId` is available.
-
-#### 3.2 Populate backendDOMNodeId At Snapshot Time
-
-When producing a role snapshot:
-
-1. Generate the existing role ref map as today (role, name, nth).
-2. Fetch the AX tree via CDP (`Accessibility.getFullAXTree`) and compute a parallel map of
-   `(role, name, nth) -> backendDOMNodeId` using the same duplicate handling rules.
-3. Merge the id back into the stored ref info for the current tab.
-
-If mapping fails for a ref, leave `backendDOMNodeId` undefined. This makes the feature
-best-effort and safe to roll out.
-
-#### 3.3 Evaluate Behavior With Ref
-
-In `act:evaluate`:
-
-- If `ref` is present and has `backendDOMNodeId`, run element evaluate via CDP.
-- If `ref` is present but has no `backendDOMNodeId`, fall back to the Playwright path (with
-  the safety net).
-
-Optional escape hatch:
-
-- Extend the request shape to accept `backendDOMNodeId` directly for advanced callers (and
-  for debugging), while keeping `ref` as the primary interface.
-
-### 4. Keep A Last Resort Recovery Path
-
-Even with CDP evaluate, there are other ways to wedge a tab or a connection. Keep the
-existing recovery mechanisms (terminate execution + disconnect Playwright) as a last resort
-for:
-
-- legacy callers
-- environments where CDP attach is blocked
-- unexpected Playwright edge cases
-
-## Implementation Plan (Single Iteration)
-
-### Deliverables
-
-- A CDP based evaluate engine that runs outside the Playwright per-page command queue.
-- A single end-to-end timeout/abort budget used consistently by callers and handlers.
-- Ref metadata that can optionally carry `backendDOMNodeId` for element evaluate.
-- `act:evaluate` prefers the CDP engine when possible and falls back to Playwright when not.
-- Tests that prove a stuck evaluate does not wedge later actions.
-- Logs/metrics that make failures and fallbacks visible.
-
-### Implementation Checklist
-
-1. Add a shared "budget" helper to link `timeoutMs` + upstream `AbortSignal` into:
-   - a single `AbortSignal`
-   - an absolute deadline
-   - a `remainingMs()` helper for downstream operations
-2. Update all caller paths to use that helper so `timeoutMs` means the same thing everywhere:
-   - `src/browser/client-fetch.ts` (HTTP and in-process dispatch)
-   - `src/node-host/runner.ts` (node proxy path)
-   - CLI wrappers that call `/act` (add `--timeout-ms` to `browser evaluate`)
-3. Implement `src/browser/cdp-evaluate.ts`:
-   - connect to the browser-level CDP socket
-   - `Target.attachToTarget` to get a `sessionId`
-   - run `Runtime.evaluate` for page evaluate
-   - run `DOM.resolveNode` + `Runtime.callFunctionOn` for element evaluate
-   - on timeout/abort: best-effort `Runtime.terminateExecution` then close the socket
-4. Extend stored role ref metadata to optionally include `backendDOMNodeId`:
-   - keep existing `{ role, name, nth }` behavior for Playwright actions
-   - add `backendDOMNodeId?: number` for CDP element targeting
-5. Populate `backendDOMNodeId` during snapshot creation (best-effort):
-   - fetch AX tree via CDP (`Accessibility.getFullAXTree`)
-   - compute `(role, name, nth) -> backendDOMNodeId` and merge into the stored ref map
-   - if mapping is ambiguous or missing, leave the id undefined
-6. Update `act:evaluate` routing:
-   - if no `ref`: always use CDP evaluate
-   - if `ref` resolves to a `backendDOMNodeId`: use CDP element evaluate
-   - otherwise: fall back to Playwright evaluate (still bounded and abortable)
-7. Keep the existing "last resort" recovery path as a fallback, not the default path.
-8. Add tests:
-   - stuck evaluate times out within budget and the next click/type succeeds
-   - abort cancels evaluate (client disconnect or timeout) and unblocks subsequent actions
-   - mapping failures cleanly fall back to Playwright
-9. Add observability:
-   - evaluate duration and timeout counters
-   - terminateExecution usage
-   - fallback rate (CDP -> Playwright) and reasons
-
-### Acceptance Criteria
-
-- A deliberately hung `act:evaluate` returns within the caller budget and does not wedge the
-  tab for later actions.
-- `timeoutMs` behaves consistently across CLI, agent tool, node proxy, and in-process calls.
-- If `ref` can be mapped to `backendDOMNodeId`, element evaluate uses CDP; otherwise the
-  fallback path is still bounded and recoverable.
-
-## Testing Plan
-
-- Unit tests:
-  - `(role, name, nth)` matching logic between role refs and AX tree nodes.
-  - Budget helper behavior (headroom, remaining time math).
-- Integration tests:
-  - CDP evaluate timeout returns within budget and does not block the next action.
-  - Abort cancels evaluate and triggers termination best-effort.
-- Contract tests:
-  - Ensure `BrowserActRequest` and `BrowserActResponse` remain compatible.
-
-## Risks And Mitigations
-
-- Mapping is imperfect:
-  - Mitigation: best-effort mapping, fallback to Playwright evaluate, and add debug tooling.
-- `Runtime.terminateExecution` has side effects:
-  - Mitigation: only use on timeout/abort and document the behavior in errors.
-- Extra overhead:
-  - Mitigation: only fetch AX tree when snapshots are requested, cache per target, and keep
-    CDP session short lived.
-- Extension relay limitations:
-  - Mitigation: use browser level attach APIs when per page sockets are not available, and
-    keep the current Playwright path as fallback.
-
-## Open Questions
-
-- Should the new engine be configurable as `playwright`, `cdp`, or `auto`?
-- Do we want to expose a new "nodeRef" format for advanced users, or keep `ref` only?
-- How should frame snapshots and selector scoped snapshots participate in AX mapping?

package/docs/experiments/plans/cron-add-hardening.md

@@ -1,62 +0,0 @@
----
-summary: "Harden cron.add input handling, align schemas, and improve cron UI/agent tooling"
-owner: "symi"
-status: "complete"
-last_updated: "2026-01-05"
-title: "Cron Add Hardening"
----
-
-# Cron Add Hardening & Schema Alignment
-
-## Context
-
-Recent gateway logs show repeated `cron.add` failures with invalid parameters (missing `sessionTarget`, `wakeMode`, `payload`, and malformed `schedule`). This indicates that at least one client (likely the agent tool call path) is sending wrapped or partially specified job payloads. Separately, there is drift between cron provider enums in TypeScript, gateway schema, CLI flags, and UI form types, plus a UI mismatch for `cron.status` (expects `jobCount` while gateway returns `jobs`).
-
-## Goals
-
-- Stop `cron.add` INVALID_REQUEST spam by normalizing common wrapper payloads and inferring missing `kind` fields.
-- Align cron provider lists across gateway schema, cron types, CLI docs, and UI forms.
-- Make agent cron tool schema explicit so the LLM produces correct job payloads.
-- Fix the Control UI cron status job count display.
-- Add tests to cover normalization and tool behavior.
-
-## Non-goals
-
-- Change cron scheduling semantics or job execution behavior.
-- Add new schedule kinds or cron expression parsing.
-- Overhaul the UI/UX for cron beyond the necessary field fixes.
-
-## Findings (current gaps)
-
-- `CronPayloadSchema` in gateway excludes `signal` + `imessage`, while TS types include them.
-- Control UI CronStatus expects `jobCount`, but gateway returns `jobs`.
-- Agent cron tool schema allows arbitrary `job` objects, enabling malformed inputs.
-- Gateway strictly validates `cron.add` with no normalization, so wrapped payloads fail.
-
-## What changed
-
-- `cron.add` and `cron.update` now normalize common wrapper shapes and infer missing `kind` fields.
-- Agent cron tool schema matches the gateway schema, which reduces invalid payloads.
-- Provider enums are aligned across gateway, CLI, UI, and macOS picker.
-- Control UI uses the gateway’s `jobs` count field for status.
-
-## Current behavior
-
-- **Normalization:** wrapped `data`/`job` payloads are unwrapped; `schedule.kind` and `payload.kind` are inferred when safe.
-- **Defaults:** safe defaults are applied for `wakeMode` and `sessionTarget` when missing.
-
-See [Cron jobs](/automation/cron-jobs) for the normalized shape and examples.
-
-## Verification
-
-- Watch gateway logs for reduced `cron.add` INVALID_REQUEST errors.
-- Confirm Control UI cron status shows job count after refresh.
-
-## Optional Follow-ups
-
-- Manual Control UI smoke: add a cron job per provider + verify status job count.
-
-## Open Questions
-
-- Should `cron.add` accept explicit `state` from clients (currently disallowed by schema)?
-- Should we allow `webchat` as an explicit delivery provider (currently filtered in delivery resolution)?

package/docs/experiments/plans/group-policy-hardening.md

@@ -1,40 +0,0 @@
----
-summary: "Telegram allowlist hardening: prefix + whitespace normalization"
-read_when:
-  - Reviewing historical Telegram allowlist changes
-title: "Telegram Allowlist Hardening"
----
-
-# Telegram Allowlist Hardening
-
-**Date**: 2026-01-05  
-**Status**: Complete  
-**PR**: #216
-
-## Summary
-
-Telegram allowlists now accept `telegram:` and `tg:` prefixes case-insensitively, and tolerate
-accidental whitespace. This aligns inbound allowlist checks with outbound send normalization.
-
-## What changed
-
-- Prefixes `telegram:` and `tg:` are treated the same (case-insensitive).
-- Allowlist entries are trimmed; empty entries are ignored.
-
-## Examples
-
-All of these are accepted for the same ID:
-
-- `telegram:123456`
-- `TG:123456`
-- `tg:123456`
-
-## Why it matters
-
-Copy/paste from logs or chat IDs often includes prefixes and whitespace. Normalizing avoids
-false negatives when deciding whether to respond in DMs or groups.
-
-## Related docs
-
-- [Group Chats](/channels/groups)
-- [Telegram Provider](/channels/telegram)

package/docs/experiments/plans/openresponses-gateway.md

@@ -1,123 +0,0 @@
----
-summary: "Plan: Add OpenResponses /v1/responses endpoint and deprecate chat completions cleanly"
-owner: "symi"
-status: "draft"
-last_updated: "2026-01-19"
-title: "OpenResponses Gateway Plan"
----
-
-# OpenResponses Gateway Integration Plan
-
-## Context
-
-Symi Gateway currently exposes a minimal OpenAI-compatible Chat Completions endpoint at
-`/v1/chat/completions` (see [OpenAI Chat Completions](/gateway/openai-http-api)).
-
-Open Responses is an open inference standard based on the OpenAI Responses API. It is designed
-for agentic workflows and uses item-based inputs plus semantic streaming events. The OpenResponses
-spec defines `/v1/responses`, not `/v1/chat/completions`.
-
-## Goals
-
-- Add a `/v1/responses` endpoint that adheres to OpenResponses semantics.
-- Keep Chat Completions as a compatibility layer that is easy to disable and eventually remove.
-- Standardize validation and parsing with isolated, reusable schemas.
-
-## Non-goals
-
-- Full OpenResponses feature parity in the first pass (images, files, hosted tools).
-- Replacing internal agent execution logic or tool orchestration.
-- Changing the existing `/v1/chat/completions` behavior during the first phase.
-
-## Research Summary
-
-Sources: OpenResponses OpenAPI, OpenResponses specification site, and the Hugging Face blog post.
-
-Key points extracted:
-
-- `POST /v1/responses` accepts `CreateResponseBody` fields like `model`, `input` (string or
-  `ItemParam[]`), `instructions`, `tools`, `tool_choice`, `stream`, `max_output_tokens`, and
-  `max_tool_calls`.
-- `ItemParam` is a discriminated union of:
-  - `message` items with roles `system`, `developer`, `user`, `assistant`
-  - `function_call` and `function_call_output`
-  - `reasoning`
-  - `item_reference`
-- Successful responses return a `ResponseResource` with `object: "response"`, `status`, and
-  `output` items.
-- Streaming uses semantic events such as:
-  - `response.created`, `response.in_progress`, `response.completed`, `response.failed`
-  - `response.output_item.added`, `response.output_item.done`
-  - `response.content_part.added`, `response.content_part.done`
-  - `response.output_text.delta`, `response.output_text.done`
-- The spec requires:
-  - `Content-Type: text/event-stream`
-  - `event:` must match the JSON `type` field
-  - terminal event must be literal `[DONE]`
-- Reasoning items may expose `content`, `encrypted_content`, and `summary`.
-- HF examples include `OpenResponses-Version: latest` in requests (optional header).
-
-## Proposed Architecture
-
-- Add `src/gateway/open-responses.schema.ts` containing Zod schemas only (no gateway imports).
-- Add `src/gateway/openresponses-http.ts` (or `open-responses-http.ts`) for `/v1/responses`.
-- Keep `src/gateway/openai-http.ts` intact as a legacy compatibility adapter.
-- Add config `gateway.http.endpoints.responses.enabled` (default `false`).
-- Keep `gateway.http.endpoints.chatCompletions.enabled` independent; allow both endpoints to be
-  toggled separately.
-- Emit a startup warning when Chat Completions is enabled to signal legacy status.
-
-## Deprecation Path for Chat Completions
-
-- Maintain strict module boundaries: no shared schema types between responses and chat completions.
-- Make Chat Completions opt-in by config so it can be disabled without code changes.
-- Update docs to label Chat Completions as legacy once `/v1/responses` is stable.
-- Optional future step: map Chat Completions requests to the Responses handler for a simpler
-  removal path.
-
-## Phase 1 Support Subset
-
-- Accept `input` as string or `ItemParam[]` with message roles and `function_call_output`.
-- Extract system and developer messages into `extraSystemPrompt`.
-- Use the most recent `user` or `function_call_output` as the current message for agent runs.
-- Reject unsupported content parts (image/file) with `invalid_request_error`.
-- Return a single assistant message with `output_text` content.
-- Return `usage` with zeroed values until token accounting is wired.
-
-## Validation Strategy (No SDK)
-
-- Implement Zod schemas for the supported subset of:
-  - `CreateResponseBody`
-  - `ItemParam` + message content part unions
-  - `ResponseResource`
-  - Streaming event shapes used by the gateway
-- Keep schemas in a single, isolated module to avoid drift and allow future codegen.
-
-## Streaming Implementation (Phase 1)
-
-- SSE lines with both `event:` and `data:`.
-- Required sequence (minimum viable):
-  - `response.created`
-  - `response.output_item.added`
-  - `response.content_part.added`
-  - `response.output_text.delta` (repeat as needed)
-  - `response.output_text.done`
-  - `response.content_part.done`
-  - `response.completed`
-  - `[DONE]`
-
-## Tests and Verification Plan
-
-- Add e2e coverage for `/v1/responses`:
-  - Auth required
-  - Non-stream response shape
-  - Stream event ordering and `[DONE]`
-  - Session routing with headers and `user`
-- Keep `src/gateway/openai-http.e2e.test.ts` unchanged.
-- Manual: curl to `/v1/responses` with `stream: true` and verify event ordering and terminal
-  `[DONE]`.
-
-## Doc Updates (Follow-up)
-
-- Add a new docs page for `/v1/responses` usage and examples.
-- Update `/gateway/openai-http-api` with a legacy note and pointer to `/v1/responses`.

package/docs/experiments/plans/pty-process-supervision.md

@@ -1,192 +0,0 @@
----
-summary: "Production plan for reliable interactive process supervision (PTY + non-PTY) with explicit ownership, unified lifecycle, and deterministic cleanup"
-owner: "symi"
-status: "in-progress"
-last_updated: "2026-02-15"
-title: "PTY and Process Supervision Plan"
----
-
-# PTY and Process Supervision Plan
-
-## 1. Problem and goal
-
-We need one reliable lifecycle for long-running command execution across:
-
-- `exec` foreground runs
-- `exec` background runs
-- `process` follow up actions (`poll`, `log`, `send-keys`, `paste`, `submit`, `kill`, `remove`)
-- CLI agent runner subprocesses
-
-The goal is not just to support PTY. The goal is predictable ownership, cancellation, timeout, and cleanup with no unsafe process matching heuristics.
-
-## 2. Scope and boundaries
-
-- Keep implementation internal in `src/process/supervisor`.
-- Do not create a new package for this.
-- Keep current behavior compatibility where practical.
-- Do not broaden scope to terminal replay or tmux style session persistence.
-
-## 3. Implemented in this branch
-
-### Supervisor baseline already present
-
-- Supervisor module is in place under `src/process/supervisor/*`.
-- Exec runtime and CLI runner are already routed through supervisor spawn and wait.
-- Registry finalization is idempotent.
-
-### This pass completed
-
-1. Explicit PTY command contract
-
-- `SpawnInput` is now a discriminated union in `src/process/supervisor/types.ts`.
-- PTY runs require `ptyCommand` instead of reusing generic `argv`.
-- Supervisor no longer rebuilds PTY command strings from argv joins in `src/process/supervisor/supervisor.ts`.
-- Exec runtime now passes `ptyCommand` directly in `src/agents/bash-tools.exec-runtime.ts`.
-
-2. Process layer type decoupling
-
-- Supervisor types no longer import `SessionStdin` from agents.
-- Process local stdin contract lives in `src/process/supervisor/types.ts` (`ManagedRunStdin`).
-- Adapters now depend only on process level types:
-  - `src/process/supervisor/adapters/child.ts`
-  - `src/process/supervisor/adapters/pty.ts`
-
-3. Process tool lifecycle ownership improvement
-
-- `src/agents/bash-tools.process.ts` now requests cancellation through supervisor first.
-- `process kill/remove` now use process-tree fallback termination when supervisor lookup misses.
-- `remove` keeps deterministic remove behavior by dropping running session entries immediately after termination is requested.
-
-4. Single source watchdog defaults
-
-- Added shared defaults in `src/agents/cli-watchdog-defaults.ts`.
-- `src/agents/cli-backends.ts` consumes the shared defaults.
-- `src/agents/cli-runner/reliability.ts` consumes the same shared defaults.
-
-5. Dead helper cleanup
-
-- Removed unused `killSession` helper path from `src/agents/bash-tools.shared.ts`.
-
-6. Direct supervisor path tests added
-
-- Added `src/agents/bash-tools.process.supervisor.test.ts` to cover kill and remove routing through supervisor cancellation.
-
-7. Reliability gap fixes completed
-
-- `src/agents/bash-tools.process.ts` now falls back to real OS-level process termination when supervisor lookup misses.
-- `src/process/supervisor/adapters/child.ts` now uses process-tree termination semantics for default cancel/timeout kill paths.
-- Added shared process-tree utility in `src/process/kill-tree.ts`.
-
-8. PTY contract edge-case coverage added
-
-- Added `src/process/supervisor/supervisor.pty-command.test.ts` for verbatim PTY command forwarding and empty-command rejection.
-- Added `src/process/supervisor/adapters/child.test.ts` for process-tree kill behavior in child adapter cancellation.
-
-## 4. Remaining gaps and decisions
-
-### Reliability status
-
-The two required reliability gaps for this pass are now closed:
-
-- `process kill/remove` now has a real OS termination fallback when supervisor lookup misses.
-- child cancel/timeout now uses process-tree kill semantics for default kill path.
-- Regression tests were added for both behaviors.
-
-### Durability and startup reconciliation
-
-Restart behavior is now explicitly defined as in-memory lifecycle only.
-
-- `reconcileOrphans()` remains a no-op in `src/process/supervisor/supervisor.ts` by design.
-- Active runs are not recovered after process restart.
-- This boundary is intentional for this implementation pass to avoid partial persistence risks.
-
-### Maintainability follow-ups
-
-1. `runExecProcess` in `src/agents/bash-tools.exec-runtime.ts` still handles multiple responsibilities and can be split into focused helpers in a follow-up.
-
-## 5. Implementation plan
-
-The implementation pass for required reliability and contract items is complete.
-
-Completed:
-
-- `process kill/remove` fallback real termination
-- process-tree cancellation for child adapter default kill path
-- regression tests for fallback kill and child adapter kill path
-- PTY command edge-case tests under explicit `ptyCommand`
-- explicit in-memory restart boundary with `reconcileOrphans()` no-op by design
-
-Optional follow-up:
-
-- split `runExecProcess` into focused helpers with no behavior drift
-
-## 6. File map
-
-### Process supervisor
-
-- `src/process/supervisor/types.ts` updated with discriminated spawn input and process local stdin contract.
-- `src/process/supervisor/supervisor.ts` updated to use explicit `ptyCommand`.
-- `src/process/supervisor/adapters/child.ts` and `src/process/supervisor/adapters/pty.ts` decoupled from agent types.
-- `src/process/supervisor/registry.ts` idempotent finalize unchanged and retained.
-
-### Exec and process integration
-
-- `src/agents/bash-tools.exec-runtime.ts` updated to pass PTY command explicitly and keep fallback path.
-- `src/agents/bash-tools.process.ts` updated to cancel via supervisor with real process-tree fallback termination.
-- `src/agents/bash-tools.shared.ts` removed direct kill helper path.
-
-### CLI reliability
-
-- `src/agents/cli-watchdog-defaults.ts` added as shared baseline.
-- `src/agents/cli-backends.ts` and `src/agents/cli-runner/reliability.ts` now consume same defaults.
-
-## 7. Validation run in this pass
-
-Unit tests:
-
-- `pnpm vitest src/process/supervisor/registry.test.ts`
-- `pnpm vitest src/process/supervisor/supervisor.test.ts`
-- `pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts`
-- `pnpm vitest src/process/supervisor/adapters/child.test.ts`
-- `pnpm vitest src/agents/cli-backends.test.ts`
-- `pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts`
-- `pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts`
-- `pnpm vitest src/agents/bash-tools.process.supervisor.test.ts`
-- `pnpm vitest src/process/exec.test.ts`
-
-E2E targets:
-
-- `pnpm test:e2e src/agents/cli-runner.e2e.test.ts`
-- `pnpm test:e2e src/agents/bash-tools.exec.pty-fallback.e2e.test.ts src/agents/bash-tools.exec.background-abort.e2e.test.ts src/agents/bash-tools.process.send-keys.e2e.test.ts`
-
-Typecheck note:
-
-- `pnpm tsgo` currently fails in this repo due to a pre-existing UI typing dependency issue (`@vitest/browser-playwright` resolution), unrelated to this process supervision work.
-
-## 8. Operational guarantees preserved
-
-- Exec env hardening behavior is unchanged.
-- Approval and allowlist flow is unchanged.
-- Output sanitization and output caps are unchanged.
-- PTY adapter still guarantees wait settlement on forced kill and listener disposal.
-
-## 9. Definition of done
-
-1. Supervisor is lifecycle owner for managed runs.
-2. PTY spawn uses explicit command contract with no argv reconstruction.
-3. Process layer has no type dependency on agent layer for supervisor stdin contracts.
-4. Watchdog defaults are single source.
-5. Targeted unit and e2e tests remain green.
-6. Restart durability boundary is explicitly documented or fully implemented.
-
-## 10. Summary
-
-The branch now has a coherent and safer supervision shape:
-
-- explicit PTY contract
-- cleaner process layering
-- supervisor driven cancellation path for process operations
-- real fallback termination when supervisor lookup misses
-- process-tree cancellation for child-run default kill paths
-- unified watchdog defaults
-- explicit in-memory restart boundary (no orphan reconciliation across restart in this pass)