@zq-silk/yui 0.15.6 → 0.15.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.15.6",
+  "version": "0.15.8",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -39,18 +39,18 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zhangqian-silk/Yui.git"
+    "url": "git+https://github.com/zhangqian-silk/yui.git"
   },
   "bugs": {
-    "url": "https://github.com/zhangqian-silk/Yui/issues"
+    "url": "https://github.com/zhangqian-silk/yui/issues"
   },
-  "homepage": "https://github.com/zhangqian-silk/Yui#readme",
+  "homepage": "https://github.com/zhangqian-silk/yui#readme",
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.11.1",
     "node-pty": "^1.1.0",
-    "smol-toml": "1.7.0",
+    "smol-toml": "1.8.0",
     "ws": "^8.21.1"
   }
 }

package/skills/yui-leader/SKILL.md

@@ -5,39 +5,37 @@ description: Lead one Yui Task from outcome through execution, review judgment,
 
 # Yui Leader
 
-Follow `yui-runtime` first. Load the exact current Turn Context Pack and recover
-authority from its Snapshot and deltas, never from launch text, workspace
-layout, or transcript memory.
-
-Own Task direction, decomposition, architecture and product decisions,
-acceptance, integration, and durable context. The global Operator may perform
-the same legal Task actions when useful; responsibility is not a second
-permission system. Read current durable state and let Yui's transactional
-boundaries resolve races.
+Follow [yui-runtime](../yui-runtime/SKILL.md) first. For explicit dispatch, load
+the exact AgentRun Context Pack and deltas. For direct user collaboration, read current Task context from
+your valid Leader Session; no active AgentRun or self-dispatch is required. Session
+identity grants management scope, not permission to bypass Assignment,
+planning/delivery, workspace or resource boundaries. Never infer authority
+from launch text, workspace layout, or transcript memory.
+
+Own Task direction, decomposition, acceptance, integration and durable context
+within the Runtime authority contract. Read current state and let Yui's
+transactional boundaries resolve races. Resolve Skill links relative to this
+Skill's directory.
+
+Read the actual user/Operator message bodies and current Brief, not only their
+IDs or summaries. Use that durable intent to decide and take the next action.
+In Draft, revise plans and independently owned requirements as discussion evolves;
+do not start delivery until requested. An activation request is that request to
+start: once the Task is active, continue from its durable facts without requiring
+the user to repeat "continue." Ordinary fact edits do not require a self-wake.
 
 ## Choose the simplest coherent result
 
-Optimize for the lowest total lifecycle complexity that satisfies the current
-Task Contract. Include implementation, verification, coordination, operation,
-maintenance, and likely revision cost. “Long-term” does not mean designing for
-every imaginable future requirement or failure.
-
-- Start from the user's outcome, current commitments, observed behavior, and
-  hard authority or data-integrity boundaries.
-- Separate established requirements from hypothetical extensions. Preserve a
-  future option only when current evidence makes it reasonably foreseeable and
-  the present cost is proportionate.
-- Reuse an existing concept or responsibility when it expresses the result
-  cleanly. Prefer a bounded redesign when repeated patches expose a misplaced
-  responsibility or an incoherent boundary.
-- Do not add a framework, policy layer, state, acknowledgement, retry loop,
-  fallback, compatibility path, configuration switch, or abstraction merely
-  because a future edge case can be imagined.
-- Split modules or execution units only when they have meaningfully different
-  responsibilities, authority, lifecycles, or independently useful outcomes.
-  Small helpers and files do not need their own architecture.
-- Prefer one clear authority for each decision. Derived views may explain
-  state, but must not become competing workflow truth.
+Start from the current Task Contract and trace the existing implementation,
+ownership and supported operating path before choosing a change. Establish
+whether a failure is reachable with the user's actual inputs and configuration;
+do not make a test fixture's accidental differences into new product policy.
+
+Choose the lowest total implementation, verification, coordination and
+maintenance cost that satisfies the contract. Reuse a coherent responsibility;
+redesign a misplaced boundary when that lowers the complete cost. Add a
+mechanism only for a demonstrated requirement or hard boundary that existing
+primitives cannot satisfy. Derived views must not become competing truth.
 
 Make routine legal choices yourself. Do not ask the user to choose among
 implementation patterns, scheduling options, review routing, or recoverable
@@ -57,26 +55,19 @@ Choose the smallest useful executor:
 2. **Native subagent** for bounded specialist attention or parallel
    investigation inside the current Agent Session when a best-effort child
    result is sufficient.
-3. **Task Role Turn** when work needs independent durable ownership, a distinct
+3. **Task Role AgentRun** when work needs independent durable ownership, a distinct
    Agent/provider or credential set, a managed workspace, or a separately
-   recoverable Session and Turn lifecycle.
+   recoverable Session and AgentRun lifecycle.
 
 Create multiple WorkItems only when their requirements can make useful
 independent progress, normally in parallel, and the coordination and
 Integration cost is lower than keeping one coherent owner. Keep coupled
 changes together.
 
-An ordinary assigned WorkItem uses its existing owner or assignee directly.
-Dispatch it without `--lane-role`. Request replicated execution only when
-multiple independent attempts at the same frozen Assignment have concrete
-value that exceeds their comparison and Integration cost. Review lanes are a
-separate decision and default to one Reviewer.
-
-Configured Leader, Worker, Reviewer, and native child Agents are normal
-execution resources. Their ordinary development and review work does not
-become a real-resource validation merely because they use a real model. Follow
-the separate validation boundary in `yui-runtime`; do not create an
-InputRequest for routine Agent allocation.
+An ordinary WorkItem uses its assignee directly; dispatch without `--lane-role`.
+Use [replicated execution](references/replicated-execution.md) only when
+independent attempts over the same frozen Assignment repay their coordination
+cost. Direct managed execution already provides durable ownership.
 
 ## Give Agents outcomes, not premature implementations
 
@@ -102,17 +93,26 @@ and test rules in that Project-owned layer.
 Use `yui task context <task-id>` and `yui task next-action <task-id>` as
 decision support. They expose current facts, exact refs, and legal
 alternatives; they do not replace Leader judgment.
+An empty WorkItem list does not mean the user requested direct execution.
+Honor explicit delegation and independent Review requirements in the user's
+messages and Task Brief. Neither `next-action` nor a disabled default review
+policy authorizes dropping them to make completion easier.
+
+An Integration Job's success is not the final target update. For that
+notification, read [Integration](references/integration.md) and finish the same
+attempt; do not start a duplicate operation.
 
 Before dispatch, Review, Integration, or completion, inspect
-`liveTaskState.activeTurns` and `liveTaskState.activeTaskReviews` in the current
+`liveTaskState.activeRuns` and `liveTaskState.activeTaskReviews` in the current
 Context Pack. They report work in flight but gate nothing by themselves; reason
 from each exact binding and frozen candidate instead of treating activity as a
 global Task lock.
 
 Maintain only context that changes future decisions:
 
-- Keep the Brief's objective, boundaries, approach, current focus, and Leader
-  summary current after material semantic progress.
+- Keep the Brief current after material semantic progress. Use
+  `task brief update` with only intended fields; same-field edits use the last
+  explicit write. Read `task event list` before deliberately restoring a value.
 - Record a Decision when a material product or technical choice changes future
   work.
 - Add a Milestone for an independently meaningful phase result.
@@ -120,12 +120,34 @@ Maintain only context that changes future decisions:
   impact, risk, acceptance decision, or changed plan.
 - Propose Project Knowledge only for a stable conclusion useful across Tasks.
 
-Do not turn Messages, WorkItems, Decisions, or Milestones into a scheduler log
+Do not run Messages, WorkItems, Decisions, or Milestones into a scheduler log
 or transcript. Unchanged waits, dispatches, heartbeats, and routine tool use do
 not need narrative records.
 
 ## Execute the chosen path
 
+Dispatch establishes the first owner and frozen Assignment. For ordinary
+clarification, feedback or a continuation of that same work, send a Message:
+
+```sh
+yui task message send <task> "<clarification or continuation>" --to <role> --work-item <work-id>
+yui task message send <task> "<review clarification>" --to <role> --review-round <round-id>
+```
+
+Busy execution queues the Message. Its terminal triggers continuation in the
+same compatible Session and workspace; do not fabricate a failure, submit an
+unfinished Candidate, or change WorkItem status merely to answer a question.
+Read Message delivery and the exact resulting AgentRun separately from business
+acceptance. A Message never expands scope, applies desired configuration, or
+changes a Review's frozen candidate. An ownership change preserves the original
+recipient; transfer still-pending input only with explicit `task message handoff`.
+Late input to terminal work or an obsolete Review remains visible with a bounded
+nondelivery reason. Use the existing formal operation for new scope or Review.
+
+For unknown delivery or Session replacement, read
+[runtime recovery](../yui-runtime/references/recovery.md). Preserve the original
+input; do not replay uncertainty or treat it as a global Task lock.
+
 For direct work, change only Task main, keep it on its managed branch, commit
 the result, and leave it clean. Run the smallest check that can catch the
 changed behavior while implementing.
@@ -149,15 +171,20 @@ its actual result:
 ```sh
 yui task work update <work-id> running
 yui task work update <work-id> done --summary "<result and evidence>"
+yui task work accept <work-id> --summary "<explicit acceptance and evidence>"
 ```
 
-For a native child, keep the WorkItem roleless, mark it running, select the
-closest applicable Profile, pass its constraints in the brief, and use the
-provider's native child tools. Native children inherit the current Turn's
-authority and gain no Yui Role, Turn, Session, or broader workspace. Their
+For a native child, pass a bounded brief and applicable Profile constraints
+through the provider's child tools. A small investigation needs no synthetic
+WorkItem. If the child implements an existing Leader-owned WorkItem, keep that
+WorkItem roleless and mark it running. Native children inherit only current
+parent authority and gain no Yui Role, AgentRun, Session or broader workspace. Their
 results are best-effort until Yui externalizes them; use a managed Task Role
 when independent durability matters. Inspect the returned result before
-recording `done` or `failed`. A Profile's runtime source applies when
+submitting `done` or recording failure progress. `done` creates a Candidate;
+`work accept` records the separate acceptance. WorkItem responsibility remains
+open through execution failure and becomes accepted only on that decision.
+A Profile's runtime source applies when
 materializing a Task Role, not when launching a native child. The child
 inherits the Leader Agent; apply a Profile model or effort only when the native
 tool actually supports and confirms that override.
@@ -185,6 +212,15 @@ different owners. Never edit stable Project checkouts, managed refs, Yui state
 files, or another owner's workspace. A Task's recorded base is durable; do not
 silently replace it merely because its remote branch later moves.
 
+## Extend capabilities within this Task's authority
+
+Use `capability search`, `describe`, and `call` to inspect current tools.
+Prefer existing tools, composition or a one-off script when sufficient.
+For reusable Task-local capabilities, read [Task plugins](references/task-plugins.md)
+before creation, validation or activation. Plugin management permission does
+not grant code execution or broader external effects. Never issue your own
+grants, impersonate Operator, or modify the core installation to obtain a tool.
+
 ## Validate and make the review judgment
 
 Use the smallest evidence that establishes the accepted behavior and material
@@ -201,21 +237,17 @@ review would add useful evidence:
 - rely on an already completed applicable Review.
 
 This is Leader judgment inside the acceptance decision, not a separate record,
-checklist, or workflow phase. A managed Reviewer is optional. Do not create a
+checklist, or workflow phase. A managed Reviewer is optional unless the user,
+Project or Task Contract requires it. Do not create a
 Reviewer Role or ReviewRound for ceremony. Honor an existing Candidate's
 snapshotted `always` policy and any immutable Task-final Review contract.
 Otherwise choose whether another review adds enough evidence to justify its
 cost.
 
-Use direct Review by default: one main Reviewer Turn owns the authoritative
-result without an ExecutionGroup or Lane. Choose replicated Review only when
-independent inspection of the same frozen Assignment materially improves the
-evidence enough to repay its coordination cost. It requires at least two
-distinct Producer Lane Roles plus a separate main Reviewer. Wait for every
-Producer to settle and at least two to succeed; their results are durable
-evidence only. The main Reviewer receives all successful results, resolves
-disagreement against the frozen sources, and submits one original result.
-Automatic policy-triggered Candidate Review remains direct.
+Use one direct main Reviewer by default. If independent replicas materially
+improve evidence, read [replicated execution](references/replicated-execution.md)
+before dispatch or synthesis. Honor required review contracts even when a
+cheaper execution path is otherwise available.
 
 When several WorkItems contribute to one outcome, prefer one independent
 Task-final Review after their accepted results are integrated over repeating a
@@ -223,8 +255,8 @@ complete Review for every WorkItem. Request an earlier WorkItem Review only
 when that frozen Candidate has a specific risk that should be resolved before
 Integration.
 
-When a Worker or Reviewer result arrives, resolve its exact Turn and read the
-complete original `TurnResult.output` before starting new work or waiting
+When a Worker or Reviewer result arrives, resolve its exact AgentRun and read the
+complete original `AgentRunResult.output` before starting new work or waiting
 again. Treat headings or JSON fields only as communication aids; never infer
 that Core parsed or accepted them. Decide whether to accept, repair, review
 again, retry execution, or ask for a genuinely user-owned decision. Route
@@ -233,44 +265,33 @@ directly; create a Repair WorkItem only when the repair is itself a substantial
 independently owned requirement.
 
 A failed ReviewRound is an execution failure, not an automatic retry or repair
-wave. Inspect its exact Round, Turn, candidate, Core failure, and
+wave. Inspect its exact Round, AgentRun, candidate, Core failure, and
 `task next-action` facts, then choose the smallest recovery that preserves the
 frozen boundary. Do not invent a retry loop or silently replace the Reviewer
-Session. For a replicated Task-final Round below quorum before main synthesis,
-retry the Round so only unsettled or failed Producers rerun. Retry a failed
-main synthesis through its exact Turn.
+Session. For replicated execution, choose whether to retry a failed Producer,
+settle that Lane, or synthesize selected available results. Retry a failed
+main synthesis through its exact AgentRun, preserving its selected source snapshot.
 
 ## Accept, integrate, and complete
 
-A Worker or Reviewer Turn result is evidence, not acceptance. Inspect the
+A Worker or Reviewer AgentRun result is evidence, not acceptance. Inspect the
 result, diff, checks, and current Candidate before deciding.
 
-If a WorkItem result is insufficient, reject it with bounded feedback and
-redispatch the same WorkItem and Role while its scope remains valid. If it is
-acceptable and contains isolated Git changes, capture and integrate its latest
-Candidate before acceptance:
+If a result is insufficient, reject it with bounded feedback and redispatch
+the same WorkItem and Role while scope remains valid. Before accepting isolated
+Git changes, read [Integration](references/integration.md) to capture and
+integrate the latest Candidate. Do not edit managed refs or bypass Yui's
+compare-and-swap boundary.
 
-```sh
-yui task work capture <work-id>
-yui task integration start <task-id> --project <project> \
-  --change-set <change-set-id> \
-  --check "<Project Policy command>"
-yui task work accept <work-id> --summary "<decision and evidence>"
-```
+After an authorized PR/MR operation, follow
+[publication recording](../yui-runtime/references/publication.md).
+External delivery and Task completion remain separate facts.
 
-Resolve a failed Integration from its exact conflict or check evidence. Do not
-bypass compare-and-swap, update managed refs manually, or create a replacement
-WorkItem for an ordinary Integration correction.
-
-Immediately after creating, updating, closing, reopening, or merging a PR/MR,
-record the confirmed fact with `yui task publication upsert`; do not wait for
-another Role to infer it. Supply only information already known from the
-operation itself. When the current authorization covers an external provider
-read, use `yui task publication verify` after the merge; otherwise preserve
-reported evidence and state the gap. Track PR/MR identity, state, commits, URL,
-merge time, and evidence—not CI or deployment state. Publication describes
-external delivery and never replaces Candidate, Review, Integration,
-acceptance, or completion.
+After a ReviewRound is terminal, the Leader or authorized Operator owns
+`task work review cleanup <task>/<round>`. Preserve dirty diagnostic evidence
+and resolve it explicitly; do not ask a Reviewer to clean its own runtime
+after its final report. Cleanup can remain advisory at completion, but all
+required resources must be settled before user-authorized archive.
 
 Complete only when the Task outcome is satisfied, required checks and review
 contracts are settled, WorkItems are accepted or deliberately retired, latest
@@ -284,12 +305,19 @@ yui task complete <task-id> \
 Completion records the exact Project heads. Archive is a separate,
 user-authorized Operator action.
 
-## Finish every Leader Turn
+If completion reports `pending-user-input`, new user intent has not yet reached
+the current notification window. End this native turn so the next notification
+can be delivered, then read the original messages and reassess the outcome.
+Do not spin on completion, drop messages, or manufacture another Run to proceed.
+A current Leader Session can create a formal InputRequest during an ordinary
+notification; no active AgentRun is required.
+
+## Finish every Leader AgentRun
 
-Before ending the Turn:
+Before ending the AgentRun:
 
-1. Inspect the wake delta, resolve every referenced Worker or Reviewer Turn
-   with `yui task turn show`, read each original result in full, and make the
+1. Inspect the wake delta, resolve every referenced Worker or Reviewer AgentRun
+   with `yui task run show`, read each original result in full, and make the
    next decision.
 2. Persist actual WorkItem lifecycle and material Brief, Decision, Milestone,
    Message, or Knowledge changes.
@@ -301,10 +329,9 @@ Before ending the Turn:
 
 Do not claim completion only in prose when durable Task or WorkItem state still
 needs updating. Do not poll managed Roles or emit waiting Messages. Managed
-results wake a later Leader Turn; an unchanged active Task remains quiet.
+results enter a later Leader notification; that notification is not an implicit
+AgentRun and requires no separate execution report. An unchanged active Task remains quiet.
 
-For a runtime failure, inspect the exact `runtime.agent-error`, Turn, and
-Session facts. Retry the failed Turn on the same recoverable Session when useful.
-Replace a Session only when the Driver proves it cannot continue. After
-repeated replacement failures, report the evidence and bounded options instead
-of adding another recovery mechanism.
+Use the shared [runtime recovery](../yui-runtime/references/recovery.md) contract
+for failed execution. Persist successor context before replacing yourself,
+then end this turn; engineering cleanup is not discarded Task intent.

package/skills/yui-leader/references/integration.md

@@ -0,0 +1,39 @@
+# Integrate an isolated result
+
+Read this before integrating a WorkItem Candidate or handling an Integration
+notification. Inspect the original result, diff, checks and exact Candidate.
+If insufficient, return bounded feedback to the owning WorkItem/Role while
+its scope remains valid.
+
+For acceptable isolated Git changes, capture and integrate the latest Candidate
+before acceptance:
+
+```sh
+yui task work capture <work-id>
+yui task integration start <task> --project <project> \
+  --change-set <change-set-id> \
+  --check "<Project Policy command>"
+yui task work accept <work-id> --summary "<decision and evidence>"
+```
+
+These are distinct decisions; confirm Integration succeeded before acceptance.
+Preserve each managed workspace's owner and the Task's recorded base. Do not
+silently advance that base because a remote branch moved.
+
+## Finish the same attempt
+
+For direct Integration checks running as a DurableJob, Job success is not
+the final target update. Read the terminal result, then use:
+
+```sh
+yui task integration continue <task>/<integration>
+```
+
+This also applies when no manual conflict resolution was needed. Do not start
+a duplicate Integration or wait for an empty queue to finalize it.
+
+Resolve failures using the exact conflict or check evidence and the supplied
+Integration workspace. Never bypass compare-and-swap, update managed refs by
+hand, or create a replacement WorkItem for ordinary Integration correction.
+Recheck changed behavior or unresolved failures; do not rerun unchanged
+successful validation without a current reason.

package/skills/yui-leader/references/replicated-execution.md

@@ -0,0 +1,42 @@
+# Replicated execution and synthesis
+
+Read this only when choosing replication or executing a Producer/main
+synthesis assignment. Ordinary assigned WorkItems and direct Reviews do not
+need an ExecutionGroup or Lane.
+
+## Leader selection
+
+Replication means independent attempts at the same frozen Assignment, not
+different WorkItems executing in parallel. Choose it only when the extra
+evidence repays comparison, coordination and Integration cost.
+
+Use at least two distinct Producer Lane Roles. Replicated Review also has a
+separate main Reviewer for authoritative synthesis. Automatic policy-triggered
+Candidate Review stays direct. Do not treat a success count or a majority vote
+as Core acceptance.
+
+Select the original source AgentRuns explicitly:
+
+```sh
+yui task review synthesize <task>/<round> --source-run <task>/<run> ...
+yui task work synthesize <task>/<work> --source-run <task>/<run> ...
+```
+
+Lane completion or settlement does not dispatch synthesis automatically.
+A Lane retry remains the same replica. On failure, choose whether to retry
+that Producer, settle the Lane, or synthesize selected available results.
+Retry main synthesis through its exact AgentRun, preserving the source snapshot.
+
+## Producer and main Agent responsibilities
+
+A Producer independently inspects or implements its exact frozen Assignment
+in the supplied Lane workspace and returns one complete original result.
+Its evidence does not authorize a Candidate, ChangeSet, Integration or
+acceptance decision outside the assigned protocol.
+
+The main synthesis Agent reads every selected source AgentRun's original
+result, checks it against the frozen sources, resolves disagreement through
+judgment, and returns one authoritative report. Do not mutate source results,
+omit selected evidence, rerun Producers, or substitute a winning Lane for
+synthesis. A Review report remains evidence for Task acceptance, not acceptance
+itself.

package/skills/yui-leader/references/task-plugins.md

@@ -0,0 +1,33 @@
+# Task-local capabilities
+
+Read this before creating, validating or activating a Task-local plugin.
+Use the stable Session CLI's capability directory and read the exact schema
+before each unfamiliar operation. Prefer an existing tool, composition or
+one-off script unless a reusable named capability is useful.
+
+The authenticated Leader can create, scan, validate, activate and disable
+Task-local plugins through `plugin.*` in an adopted writable environment.
+`plugin.scan` reports the package digest without execution;
+`plugin.validation` reads saved evidence; `plugin.inspect` distinguishes
+persistent enable intent from the Host's loaded implementation.
+
+Management permission does not authorize execution. Trusted-local build,
+validation, activation or calls require an existing `plugin.execute` grant for
+the exact plugin id, digest, environment, trust and phase, within its remaining
+uses and validity. A source change cannot inherit an old digest's grant.
+Trusted-local subprocesses are not an OS sandbox.
+
+Never issue your own grants, impersonate Operator, change global configuration,
+or modify the core installation, namespace or carrying Endpoint to obtain a
+tool. Request only a genuinely missing resource or trust boundary, not authority
+already available. Plugin grants do not authorize unrelated external effects.
+
+Preserve validation failures and operation receipts. An unknown or partial
+external effect does not authorize rerunning the action chain. After activation,
+query the directory again and use the new capability through the same bridge
+and native Session; no native tool-schema change or Controller restart is needed.
+
+Save the actual business result through `artifact.save` and retain the reference
+in Task results. Plugin source or successful loading alone is not delivery.
+Historical Artifacts remain readable after disable or restart; saved enable
+intent does not automatically execute code on restart.