@zq-silk/yui 0.7.1 → 0.8.2

package/ARCHITECTURE.md

@@ -201,34 +201,33 @@ context.
 
 ## Runtime ownership
 
-tmux owns Agent process lifetimes and observable output. The Controller owns
-mailbox delivery, wakeups, Role liveness, and reconciliation. Task attachment
-surfaces only attach to an existing pane and cannot create, resume, wake, or
-deliver to a managed runtime. Global interactive entry remains an explicit
-session-lifecycle operation.
-
-Task observation is read-only by default. Explicit write access publishes a
-Role-scoped tmux lease before revalidating durable Run state. The managed host
-also checks that lease before planning or process creation, so either the Run
-claim or the writer lease wins and they never share a pane. Writer contention
-is transient backpressure rather than a delivery failure: it does not consume
-bounded delivery retries, and lease release signals only existing durable work.
-Global interactive entry uses the same mechanism at tmux-host scope and
-automatically falls back to read-only when another writer already exists.
-
-Managed Task Claude execution is process-per-Run: the exact Run input is a
-stream-json stdin frame submitted at process launch, while native session IDs
-carry conversation continuity across processes. The lifecycle binding records
-the exact Run submitted at launch. A Controller restart may recover only the
-same reserved launch/Run as uncertain until its Provider Hook arrives; a newly
-reserved Run cannot reuse an older live Role pane, so its provisional launch
-is released, the old owner is fenced through the durable cleanup lane, and the
-same Run is retried only after cleanup; pending cleanup prevents a successor
-generation from starting early.
-Terminal key injection is therefore an interactive compatibility mechanism,
-not a managed Claude delivery protocol. Operator and Leader Sessions remain
-fixed Task/global Roles; Task Worker Sessions are selected through Role Agent
-bindings.
+tmux owns the persistent Agent Host lifetime and observable output. The
+Controller owns mailbox delivery, wakeups, Role liveness, recovery decisions,
+and a durable single-writer authority epoch. The Agent Host owns one structured
+Provider child process and mirrors its output to the pane. Managed prompts are
+never terminal bytes: both Controller and human takeover input become fenced
+Provider-native Turn requests.
+
+Run, Conversation, Activation, and Turn identities are independent. A
+Conversation can span Runs and Provider processes; one Activation identifies
+one live process; one Turn identifies one pre-recorded input attempt. A live
+Activation is retained when a later Run reuses the Conversation. Process exit
+ends that Activation, and a resumed process receives a new Activation and a
+higher authority epoch.
+
+Task observation uses `task role view`. Explicit takeover requires a live
+managed Run, atomically transfers authority to a human holder, synchronizes the
+same fence to the Host, and only then exposes the PTY input gateway. Detach
+releases authority; `task role release` is an idempotent repair path even after
+the Run has ended. Global interactive entry remains a native session-lifecycle
+operation outside this managed Provider contract.
+
+Codex uses a persistent App Server JSON-RPC transport. Claude uses a persistent
+stream-json transport with exact user-message replay acknowledgement. In both
+cases, Yui records Turn intent before writing, accepts only exact Provider
+evidence, and maps an uncertain write to `delivery-unknown` without automatic
+resubmission. Conversation replacement requires exact missing evidence and no
+unsettled input, Turn, Activation, or writer authority.
 
 Role desired revisions and Run/Session effective snapshots keep configuration
 history explicit. Resume compares the complete effective snapshot and

package/README.md

@@ -21,21 +21,37 @@ yui setup
 yui doctor
 ```
 
-`setup` is interactive. It detects installed Agent CLIs, asks which Agents to configure, selects the default and Operator Agent, and probes each selected CLI for its current models. It configures the Leader and Operator, then explains that the global Worker configuration is copied into new Task Roles and asks whether Worker should reuse Leader or be configured separately. Model selection is followed by that model's supported reasoning efforts. Setup also confirms the Project workspace outside Yui home and offers shell-completion setup. The picker includes the native CLI default and a custom-value option. Running setup again preserves existing Tasks, Roles, and the installation's Project workspace while allowing safe configuration changes. A successful setup ensures the current Home's detached Controller is running before it returns.
-
-Model and effort are per-Agent Role settings, so Operator, Leader, and the global Worker can use different values even when they share an Agent CLI. Interactive Role flows validate those settings against the selected Agent runtime. Worker Profile model and effort fields are provider-neutral child-execution hints and therefore remain explicit, scriptable values rather than Agent capability selections.
-
-Setup gives every managed Agent binding the explicit `bypass` permission
-strategy. Later Role updates may select `default`, `bypass`, or `configured`;
-the last choice exposes that adapter's native permission enums and tool rules.
-
-Runtime catalogs are refreshed per command and cached under Yui home. If a live probe times out or fails, Yui shows the last cache for the same Agent launch context and clearly marks it as potentially stale; without a matching cache, it offers CLI defaults and custom values. `yui agent capabilities <id>` exposes the same one-pass catalog, including models, model-specific efforts, and other runtime choices such as permissions, search availability, profiles, settings sources, and service tiers.
+`setup` is intentionally minimal. It verifies tmux, reuses or creates one
+available Agent, creates the default workspace outside Yui home, and configures
+both Operator and Leader so the user can start Yui and execute Tasks. It does
+not create Worker, Reviewer, Profile, or review-policy configuration, and does
+not ask for model/effort, permission, or shell completion. The required
+Operator and Leader bindings use Yui's adapter default permission strategy
+(`bypass`); further changes belong under `config role`. Running setup again
+preserves already usable Operator and Leader Roles. A successful setup starts
+the current Home's detached Controller before it returns.
+
+All persistent configuration is under `yui config`. `config show` reports the
+complete effective state, while `config --help` introduces each domain and
+shows examples. The Operator can read the same structured catalog with
+`config describe`, explain current values, effects, choices, and activation
+behavior, then apply only changes the user confirms.
+
+Durable settings are grouped by responsibility: `config system` for Home
+defaults and presentation, `config runtime` for Controller health, concurrency,
+launch, delivery, and Provider retry, `config workflow` for Leader/context/review
+policy, `config resources` for quarantine and GC, and `config tools` for tmux
+and diagnostic telemetry. Configured Agents, global Roles, Profiles, and shell
+completion remain the sibling `config agent|role|profile|completion` domains.
+Use `show`, `set`, and `clear` consistently within each durable-settings domain.
+
+Runtime catalogs are refreshed per command and cached under Yui home. If a live probe times out or fails, Yui shows the last cache for the same Agent launch context and clearly marks it as potentially stale; without a matching cache, it offers CLI defaults and custom values. `yui config agent capabilities <id>` exposes the same one-pass catalog, including models, model-specific efforts, and other runtime choices such as permissions, search availability, profiles, settings sources, and service tiers.
 
 `completion` is also interactive, with or without an explicit shell:
 
 ```sh
-yui completion
-yui completion zsh
+yui config completion
+yui config completion zsh
 ```
 
 Both forms confirm the generated script, installation path, and shell startup-file change. The installed completion is generated from the command catalog, including nested subcommands.
@@ -214,7 +230,8 @@ record-schema change, the integrating branch must supply the complete adjacent
 path (including an explicit `0->1` introduction for a new family) and re-test to
 convergence.
 
-Setup also seeds four reusable Worker Profiles:
+Yui provides four reusable Worker Profile definitions through
+`yui config profile reset`; minimum setup leaves them unconfigured:
 
 ```text
 worker  explorer  implementer  reviewer
@@ -270,16 +287,16 @@ timezone with:
 
 ```sh
 yui config show
-yui config set time-zone Europe/London
+yui config system set time-zone Europe/London
 ```
 
 WorkItem review is one global, optional rule that reuses an existing Global
 Role's Agent, model, permissions, prompt, and Skills:
 
 ```sh
-yui config set review --role reviewer --trigger always
+yui config workflow set review --role reviewer --trigger always
 yui config show
-yui config clear review
+yui config workflow clear review
 ```
 
 For Project-backed software delivery, use `--trigger final` to keep WorkItem
@@ -287,7 +304,7 @@ acceptance and Integration independent and run one fresh ReviewRound over the
 complete frozen integrated Task candidate before completion:
 
 ```sh
-yui config set review --role reviewer --trigger final
+yui config workflow set review --role reviewer --trigger final
 ```
 
 Every result entering Leader acceptance is one explicit candidate on its
@@ -467,7 +484,7 @@ Create a Task-bound Worker instance from the configured global Worker, apply a
 Profile, and dispatch a WorkItem:
 
 ```sh
-yui role show worker
+yui config role show worker
 yui task role add <task-id> implementer --profile implementer
 yui task role show <task-id> implementer
 
@@ -538,7 +555,7 @@ yui task work create <task-id> "Review the implementation" \
   --objective "Return source-backed findings" \
   --accept "Every finding identifies an affected path"
 yui task work update <task-id>/<work-item-id> running
-yui profile show reviewer
+yui config profile show reviewer
 ```
 
 Subagent creation and result delivery happen inside the Leader's native Agent
@@ -642,55 +659,46 @@ yui task complete <task-id> --summary-file delivery.txt --refresh-remote
 yui task reopen <task-id>
 ```
 
-Completed Tasks reject messages, dispatch, enter, retry, and late yields until explicitly reopened, while retaining Task main for inspection or integration. Every isolated WorkItem worktree must be explicitly cleaned as integrated or abandoned before archive; that cleanup also removes its managed branch. Archive requires `--integrated` or `--abandon` to state the Task main outcome and is allowed only after Task main is clean. It removes managed worktrees but retains Task and WorkItem records. The Task main branch is retained as a recovery artifact instead of being silently deleted.
+Completed Tasks reject messages, dispatch, Provider authority changes, retry, and late yields until explicitly reopened, while retaining Task main for inspection or integration. Every isolated WorkItem worktree must be explicitly cleaned as integrated or abandoned before archive; that cleanup also removes its managed branch. Archive requires `--integrated` or `--abandon` to state the Task main outcome and is allowed only after Task main is clean. It removes managed worktrees but retains Task and WorkItem records. The Task main branch is retained as a recovery artifact instead of being silently deleted.
 Task lifecycle completion/selection only suggests valid source states: Draft for activate, active for complete, and completed for reopen.
 
 ## Sessions and tmux
 
-tmux owns Agent process lifetimes and their observable output. Global Operator
-and global Role sessions remain native interactive CLIs. A managed Task Claude
-Run instead starts one finite Claude process with `--print`, stream-json input
-and stream-json output. Yui writes the exact Run prompt as one newline-delimited
-JSON user frame on stdin, drains output concurrently, and carries native
-continuity with Claude's session ID. Startup and delivery therefore never
-depend on a TUI composer, readiness glyph, paste delay, or a synthetic Enter
-key. Codex keeps its adapter-native launch-prompt and structured callback path.
-
-`task enter` and `task role enter` are pure attachments to an existing Task
-Role pane. They do not start the Controller, prepare a workspace, create or
-resume an Agent, wake a Role, or deliver input. Task attachments default to
-`--read-only`; `--read-write` is explicit and is rejected while that Role owns
-an active managed Run, a managed Claude process is still exiting, or another
-writer owns the same pane. A read-write attach first publishes a Role-scoped
-tmux writer lease and then revalidates durable Run state, closing the race with
-Controller launch. While the lease exists, managed delivery for that Role is
-paused without consuming its bounded delivery retries; detach releases the
-lease and signals only already-durable Role work for reconsideration. Other
-Roles in the same Task continue independently. Before any attach Yui closes
-readline, leaves raw mode, pauses its stdin, and synchronously hands the terminal
-to tmux. The attach uses the real outer terminal capabilities and a clean alternate
-screen; mouse scrolling stays in the Agent pane's
-100,000-line tmux history instead of mixing with earlier shell or IDE terminal
-history. A read-write attachment exposes whatever native interaction the
-existing pane supports, but it is never part of managed startup or delivery.
-
-tmux fixes a pane's history capacity when that pane is created. Roles created
-before this limit was configured keep their earlier capacity; Yui warns on
-Terminal attach and in Web so the user can exit and re-enter that Role once to
-create a 100,000-line pane while retaining the native Agent conversation.
-
-Global interactive entry remains writable when no writer exists and
-automatically downgrades to read-only when another writer is present; global
-Web keeps one writer per tmux session. Task Web is always read-only. Task CLI
-entry is read-only unless `--read-write` is requested, preventing observation
-from changing Agent execution.
-
-```sh
-yui role enter <global-role>
-yui task enter <task-id> [role] [--read-only | --read-write]
-yui task role enter <task-id> <role> [--read-only | --read-write]
+Managed Task Agents use the [hybrid Provider runtime](docs/provider-runtime.md).
+The Controller and Agent Host send Provider-native structured requests; tmux
+and PTY keep the Host alive, show output, and provide an explicit human input
+gateway. Managed prompts are never delivered as terminal bytes.
+
+Codex uses a persistent App Server JSON-RPC process. Claude Code uses a
+persistent stream-json process with exact user-message replay acknowledgement.
+Both follow the same Conversation, Activation, Turn, and authority-epoch
+contract. A timeout or uncertain write becomes `delivery-unknown` and is never
+automatically retried.
+
+Task Role observation and takeover are explicit:
+
+```sh
+yui task role view <task-id> <role>
+yui task role takeover <task-id> <role>
+yui task role release <task-id> <role>
 ```
 
+`view` is read-only. `takeover` transfers the durable writer authority to the
+human before enabling the Host PTY gateway and requires a live managed Run;
+detach returns it to the Controller. `release` remains available without a live
+Run and idempotently repairs a stranded or partially synchronized takeover.
+Authority cannot transfer while a Provider Turn or input delivery is unsettled.
+
+Global Operator and global Role sessions remain native interactive CLIs:
+
+```sh
+yui session enter <global-role>
+```
+
+tmux fixes a pane's history capacity when that pane is created. Existing panes
+retain their configured capacity; managed runtime output remains observable in
+the Agent Host pane without becoming lifecycle or acknowledgement evidence.
+
 Each Role, including a Task-bound Worker instance, can bind multiple configured Agents, has one active Agent, and keeps
 a separate native session per Agent binding. Operator narrows this to at most
 one Agent per adapter—for example, one Codex and one Claude—so its bindings are
@@ -710,14 +718,12 @@ the terminal Session's immutable effective snapshot in history. Until that
 process terminates, exact control-plane wakes continue through its actual
 snapshot instead of applying desired drift as a hot change.
 
-Use `yui role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
+Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
 
-Claude session IDs are preallocated at launch. Every managed Task Claude Run
-uses a new finite process; resume starts a new process against the fixed native
-session instead of reusing an interactive pane. Codex discovers its native
-thread identity from structured lifecycle events. Managed Task Runs use one
-Agent Driver Hook ingress for both CLIs. Global interactive Codex sessions may
-still use its structured `notify` callback for conversation presentation.
+Claude session IDs are preallocated at launch. Codex discovers its native
+thread identity from App Server responses. Managed Task Runs use structured
+Provider observations for both CLIs. Global interactive Codex sessions may
+still use its `notify` callback for conversation presentation.
 
 Automated lifecycle and delivery decisions use structured Hook payloads,
 persisted identities, usage snapshots, tmux process state, receipts, and pane
@@ -847,9 +853,11 @@ The restored management surface includes:
 ```sh
 yui update
 yui upgrade [--dry-run]
-yui agent add|list|show|capabilities|update|remove
-yui role add|list|show|update|remove|bind|enter
-yui role session record|replace
+yui config agent add|list|show|capabilities|update|remove
+yui config role add|list|show|update|remove|bind|unbind
+yui config profile add|list|show|update|remove|reset
+yui config completion [bash|zsh|fish]
+yui session enter|record|replace|reconcile
 yui project add|clone|refresh|update|discover|list|show|knowledge
 ```