@zq-silk/yui 0.15.7 → 0.15.8

package/docs/architecture/capabilities-and-resources.md

@@ -0,0 +1,79 @@
+# 能力、资源与 Surface
+
+## 唯一入口与原始事实
+
+Controller 承载 CapabilityRegistry 和 InstanceHost。`capability search`、
+`describe`、`call` 使用同一认证入口，先解析当前 Session 身份和 Task 范围，
+再检查能力与资源权限。输入中的 actor 或自称的 user scope 不能授予权限。
+
+描述符包含名称、合同版本、Provider、scope、输入输出 schema、effect 和
+requiredPermissions。查询只展示获授权的目录；同名 Provider 或版本有歧义时，
+调用者明确选择，不按加载顺序决定。Schema 是有界方言，未知关键词拒绝。
+
+当前目录覆盖 context、message、artifact、environment、resource、project、
+plugin 和部分 task/job 操作。Task 生命周期与部分 CLI/Web 写入直接共享
+领域命令；这些不是另一份业务状态，也不假称已经通过 Registry 执行。
+
+## 效果与操作事实
+
+能力返回值与真实效果分开。一次调用即使输出校验失败，也可能已产生确认的
+子操作；返回结果必须保留原 owner 的 operationRef 和 receipt。Unknown
+不能解释为未执行，不进行自动 fallback。
+
+嵌套调用重新检查当前权限，不能扩大父调用声明的权限与效果。requestId 标识
+调用，不自动提供所有业务的通用幂等性；Job 等 owner 执行自己的精确幂等合同。
+错误后先读取原操作事实再决定下一步。
+
+## 实现实例
+
+InstanceHost 管理 attach、acquire、release、detach 与实际引用。替换发布后，
+新调用选择新实现；已有引用继续绑定原实现，排空后才能 dispose。查询是观察，
+不启动或恢复代码。清理失败保留诊断，不把新发布反转为失败，也不伪造排空。
+
+Session 的长引用由实际 AgentHost 固定到所加载实现。Controller 传递已有 pin，
+不把活 Session 静默搬到另一份代码。结束客户端与共享 Provider 物理静止分别判断。
+
+## Project 与工作区
+
+Project 保存参考 checkout、Knowledge 与资源引用。稳定 checkout 只读；Task
+交付发生在受管 worktree。多 Project Task 使用独立 Git 根和明确写范围。
+工作区 owner 属于 Task、WorkItem、ReviewRound 或 IntegrationAttempt。
+Role 仅选择执行配置，不独立拥有另一份工作区状态。
+
+Git 集成捕获精确 ChangeSet，在候选 worktree 检查后 CAS 推进目标。
+冲突、检查失败、目标移动与拒绝都不更新目标，Agent 决定下一次操作。
+
+## Artifact 与环境
+
+- `artifact.save/read/list` 保存不可变内容、外部版本证据、Job 回执或引用资料。
+  Reference 不等于固定交付成果；最终结果不能选择缺失或跨 Task Artifact。
+- `environment.prepare` 准备 empty、scratch 或获授权 local 目录，不自动采用。
+- `environment.adopt` 复核身份、资源意图、权限与冲突后保存所有权。
+- `environment.bind` 选择 Role 下一次原生执行环境；`null` 返回 managed workspace。
+- `environment.release` 检查真实引用和静止证据，不删除用户目录。
+
+Adopted native launch 保留目录身份、access、isolation 与 preparation 引用，
+在 launch、resume 和 Yui 输入边界复核。撤权不能靠新 grant 静默重新采用旧环境。
+Read-only 环境的支持取决于实现；不能将目录 access 标签视为通用 OS 沙箱。
+
+## 插件与自扩展
+
+Task Leader 或 global Operator 可以管理该 Task 的插件；Worker/Reviewer 不能
+自行管理或授信。声明式插件不执行任意代码；trusted-local 插件执行还需要精确
+源码或产物摘要、环境和阶段的 grant。
+
+Store 保存 enabled 意图及验证产物，Host 保存实际实例。重启后 enabled 仍可读，
+actual 可以为空，必须显式激活。原 Task 可以发现并调用新能力，不必修改自身
+原生工具 schema。业务结果应保存为 Artifact，而不是依赖插件继续存活。
+
+完整作者、授权及失败合同见[插件 SDK](../plugin-sdk.md)。
+
+## CLI 与 Web
+
+Surface contribution 由 Registry 当前获授权目录派生，没有第二份目录或 Host。
+CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
+JSON query 描述，不接受作者脚本或任意 HTML。
+
+Web listener 由 Controller 启停，仅允许 loopback。浏览器写入通过现有领域
+事务，错误区分确定未提交与提交结果未知。查询面板不能借浏览器身份执行 mutation
+或插件管理。终端连接只 attach 客户端，不接管原生对话的持久所有权。

package/docs/managed-turn-and-session-runtime.md

@@ -0,0 +1,222 @@
+# Session, AgentRun and notifications
+
+## Authority
+
+Task, WorkItem, Message, Decision, Artifact and Project Knowledge preserve
+durable work. Session identifies a native conversation and its captured
+authority. AgentRun records an explicitly requested execution and original
+result. AgentHost is a disposable attachment, not the owner of Task truth.
+
+A current, non-revoked Leader Session can read Context and save scoped Task
+facts, including a formal InputRequest, without an active Run. Its exact
+Session is the request's origin; an actual Run is included when present.
+The question survives that execution ending and remains open until answered
+or cancelled. Worker and Reviewer commands retain exact
+Assignment checks. Session replacement, Role binding, Task scope and resource
+grants are checked at their respective boundaries. An active Run pointer is not
+proof that an unrelated command in the same Session came from that Run.
+
+Native chat, Goal continuations and ordinary Leader notifications do not
+automatically create Runs. Explicit dispatch loads one exact Run Context Pack.
+
+## Context
+
+```sh
+yui task context <task> --json
+yui task context delta <task> --after <coreCursor>
+yui task context inspect <task> --store <store> --ref <id>
+yui task run context <task/run> --json
+```
+
+Task Context is a bounded authorized working set with a current core cursor.
+Delta pages immutable events through a fixed upper bound; inspect expands a
+current record and can require an exact digest. Runtime observations state their
+own coverage and do not become another durable snapshot.
+
+Run Context freezes Assignment, source references, effective configuration and
+workspace boundaries. A Role edit does not rewrite an existing Assignment.
+Reading either Context does not acknowledge input or create execution authority.
+Every managed input points to the exact Session Manifest and CLI entry. The
+Run Pack is a reference directory: read the relevant requirement and message
+bodies before acting, rather than treating a successful load as the deliverable.
+Planning Packs expose no Project write scope or Task-completion permission.
+
+Current Task reads also expose untargeted user/Operator messages to the Task's
+current Worker and Reviewer Sessions, including requirements added after their
+Run snapshot was frozen. Use `task message list/show` or Task Context inspect
+to read those original records. This does not rewrite the frozen Assignment or
+grant delivery authority. Directed messages, other Roles' results and other
+Tasks remain outside the caller's scope unless its Assignment authorizes them.
+
+## Dispatch and notification
+
+An explicit dispatch persists execution intent before native submission.
+Ordinary Leader wake instead claims a fixed TaskWake/mailbox batch and submits
+a notification through the same Host/Endpoint. Confirmed acceptance consumes
+only that batch; later input remains pending. A notification requires no final
+execution report and does not force steer into a busy native conversation.
+
+Leader-local edits preserve durable events but do not create self-wakes.
+Other sources' input remains durable while the Leader is busy or unavailable.
+Operator notifications likewise carry TaskEvent/InputRequest read pointers,
+not duplicated Task narrative.
+Human input, explicit execution entry and activation failure are delivered
+promptly through the existing wake mechanism. Worker results retain their
+aggregation window. Busy native input still preserves pending messages.
+
+| Evidence | Disposition |
+| --- | --- |
+| Busy with proven non-acceptance | Preserve input; a new transport attempt may use the same Session |
+| Native acceptance | Never resend; wait for the exact terminal if this is an execution |
+| Transport write only | Retain transport evidence; do not claim native acceptance |
+| Explicit rejection | Retain the original cause and settle the corresponding admission |
+| Unknown acceptance/effect | Retain the attempt and conflicting-resource fences; do not replay or switch Session |
+
+Missing receipt after a crash is not proof of non-acceptance. Structured
+`SESSION_BUSY` is evidence; text containing “busy” is not a retry contract.
+
+## Continue existing work
+
+```sh
+yui task message send <task> "Continue with the clarified requirement" \
+  --to <role> --work-item <work-item>
+yui task message handoff <task/message> --to <successor-role>
+```
+
+Review clarification uses `--review-round` instead of `--work-item`.
+Message retains recipient, work association and owner Run. When the Role is
+busy, saving returns without interrupting it. Once it becomes available, a
+bounded ordered batch can create a continuation Run atomically associated with
+those messages. The existing Assignment, effective permissions, workspace and
+unfinished files remain; the snapshot adds authorized messages and the preceding
+original result. Duplicate terminals cannot assign the messages twice.
+
+Ownership changes, incompatible Sessions, terminal work and obsolete Review
+candidates retain visible nondelivery reasons. Explicit handoff only targets an
+already-dispatched successor for the same work. Replicated Producer/synthesis
+lineage is not silently rewritten by a message.
+
+Unknown Leader notifications preserve their wake and input window:
+
+```sh
+yui task wake show <task> <wake>
+yui task wake resolve <task> <wake> --reason <quiescence-evidence>
+```
+
+Resolve releases the claim after native-effect fences are clear. It neither
+replays the notification nor invents acceptance or completion. Independent
+Role work and legal local facts are not a Task-wide recovery lock.
+
+## Exact results
+
+The native terminal settles only the matching execution. Known native Turn IDs
+must match; a serialized stream may use proven local attempt correlation.
+Message UUIDs are not native Turn IDs. Unrelated native chat in the same Session
+cannot complete the pending Yui request.
+
+The terminal transaction saves one AgentRunResult and a reference Message.
+`resultRef: { type: "agent-run-result", runId: "run-12" }` expands the original
+report rather than copying it. Candidate and ReviewRound retain provenance;
+Core does not derive semantic acceptance from prose.
+
+Cancellation requests do not prove physical quiescence. Exact terminal evidence
+preserves partial output and settles the original execution only. Host exit
+does not imply shared Provider or descendant processes have stopped.
+
+## Draft planning and activation
+
+`EffectiveLaunchSnapshot.executionAuthority` captures `planning | delivery`.
+It is not recalculated from the Task's current lifecycle. Planning permits
+local planning facts, not delivery dispatch, candidate adoption, integration or
+delivery workspace Jobs.
+
+The initial Draft planning dispatch creates a planning Run and binds only its
+initial message batch. Acceptance or an exact terminal consumes that batch;
+failure does not repeatedly recreate the same planning execution. Subsequent ordinary
+messages in the existing planning Session remain notifications. Operator submit
+and direct Task messages both reach that Session. Draft plan/WorkItem edits
+preserve execution history; external edits notify the Leader, while its own
+planning edits do not create a self-wake.
+
+New Draft Roles use a Task-specific planning directory under
+`<YUI_HOME>.task-runtimes/planning`, outside the control Home and delivery trees.
+A planning Run can use `task activation request` to persist intent and return an
+`afterPlanningRun` reference immediately. Its terminal releases the request for
+Controller admission; cancelled intent is not resurrected.
+The Leader can also request activation during ordinary discussion without an
+AgentRun: the Controller adopts its durable intent once the native input is
+settled. No synthetic Run or extra user “continue” is required.
+
+For bound Git Projects, `--environment empty` means no additional environment:
+the Projects still receive managed worktrees. `scratch` selects a Task-owned
+directory. `local` requires a registered local Resource and its grant; a Project
+ID is not a local Resource ID.
+
+Resource preparation precedes the atomic adoption of Task status and workspace
+ownership. A failed adoption records a failed request and notifies the Leader
+with durable facts; it does not repeatedly prepare resources on unchanged
+failure. The Leader chooses an explicit retry or corrected request. Successful
+activation likewise leaves a delivery notification for the Leader.
+Activation never mutates the live Session into delivery authority. A changed
+launch must pass the existing Session replacement/environment boundary.
+Planning authority is a CLI guarantee, not a hostile-code filesystem sandbox.
+
+## Inspection and lifecycle
+
+```sh
+yui task run list <task>
+yui task run show <task/run> --json
+yui task message show <task/message>
+yui task role session inspect <task> <role>
+yui task execution start <task>
+yui task execution stop <task> --force --reason <reason>
+```
+
+Task execution start/stop controls Task admission, not Task acceptance.
+Stop first fences new Yui work, then interrupts each exact owned native input
+and confirms its terminal before removing the attachment. This also covers
+ordinary Leader notifications without Runs. Unknown native state blocks cleanup;
+stopping a proxy alone never proves a shared Turn ended. Start preserves durable
+progress and admits new input after the old occupancy is settled.
+Draft planning can be paused/resumed, and a failed planning Run retries with
+planning authority. An authorized user/Operator can stop an idle Draft Session
+through `task role session stop`; it need not activate the Task merely to recover.
+`task role session new <task> <role> --reason <reason>` persists an explicit
+replacement request. Reuse is a preference, not a requirement to prove the old
+conversation unrecoverable. The request is legal while an AgentRun is active,
+the Session is ended, or previous cleanup is pending. A Leader may also request
+its own replacement and end its current turn.
+
+`task role session stop` can also stop a running Role without first changing
+its Run status. It retains the native conversation for possible reuse. Pending
+Messages remain intent and may start a continuation after the stop; use Task
+execution stop when the whole Task must remain paused. For self-replacement,
+use the asynchronous `session new` request rather than a synchronous self-stop.
+
+The existing runtime cleanup path stops the exact native execution, closes this
+Role's remaining engineering attempts as cancelled, retains Session/Run history
+and workspaces, and selects a fresh conversation. Other Roles and Task acceptance
+remain unchanged. The Leader receives a new context notification; it decides
+which Worker/Reviewer attempts to retry. Pending input references survive the
+replacement, including records older than the new notification's time window.
+
+An absent Host does not remove the recovery entry point. Codex can be inspected
+and interrupted through a disposable native control connection without starting
+a model. Dedicated Claude process custody is persisted independently of the
+Host. Real unconfirmed execution still prevents conflicting resource reuse;
+cleanup failure is a durable diagnostic routed to the supervisor, not a reason
+to invent acceptance or delete the Task. A preallocated ID alone is not proof
+a conversation exists.
+Codex may retain `systemError` after a failed native Turn. That label alone
+neither proves activity nor authorizes cleanup: Yui checks the latest native
+Turn's terminal metadata and drains background execution before replacing the
+Session. Unknown or still-running native work remains protected.
+
+Released Leaders retain scoped diagnostic reads of their own Task and context,
+but cannot mutate it or read another Task. Operator diagnostics and Controller
+restart do not first require a healthy Controller; explicit restart can stop
+only the exact same-Home process using PID/start identity when RPC is unavailable.
+Operator storage diagnosis/upgrade also reaches the dedicated migration entry
+without first requiring the Home to already have the target storage version.
+Completion, cancellation and archive have distinct authority and resource
+boundaries. Storage changes use the single [upgrade contract](sqlite-control-plane-design.md).

package/docs/observability/README.md

@@ -0,0 +1,81 @@
+# Runtime observations and diagnostics
+
+Read-only projections help an Agent distinguish durable intent, actual runtime
+activity and unknown effects. They do not add a second scheduling or acceptance
+authority.
+
+## Inspection
+
+```sh
+yui controller status
+yui execution audit --task <task-id> --json
+yui task next-action <task-id>
+yui task role session inspect <task-id> <role>
+yui task run show <task-id>/<run-id> --json
+```
+
+Controller status exposes the current process and Home identity. Session inspect
+separates desired binding, effective launch, actual connection and Agent-reported
+configuration. Run inspection exposes original input, disposition, exact result
+and diagnostics. A status read does not start another Agent or acknowledge work.
+
+## Meaning of evidence
+
+- Task and WorkItem lifecycle describe intent and acceptance.
+- AgentRun lifecycle describes explicitly requested execution.
+- Provider acceptance and native activity describe the actual input/connection.
+- Host PID, tmux and resource inventory describe process observations.
+- Runtime configuration distinguishes requested values from reported values.
+- Tokens, durations and orchestration costs are advisory observations.
+
+For a dedicated Claude stream, a main assistant response confirms processing
+of the one current local input before its terminal result. Controller and Role
+reads therefore show accepted/running once that response arrives. Startup,
+echoed user input, child output and repeated old messages do not establish new
+acceptance; message UUIDs are never used as native Turn IDs.
+
+Ordinary Leader notifications are TaskWake/mailbox delivery, not Leader Runs.
+Role status includes their native admission/activity even when no AgentRun is
+open, and shows a retained Session's actual workspace rather than substituting
+Task main when its WorkItem is terminal.
+Unknown evidence remains unknown; process exit does not prove a shared Provider
+stopped, and successful transport does not prove native acceptance.
+
+Engineering control evidence can outlive the attached Session cache. Such a
+Role reports retained native input as needing attention, not idle merely because
+the cache is empty. Scoped Task/Session inspection remains available for diagnosis.
+Replacement and native cleanup failures are durable events routed to the
+supervisor, and pending input references remain readable after replacement.
+
+Exact tool start/result events project `tool-active`, while model activity
+projects `model-active`; quiet intervals do not imply a hung or finished Agent.
+Tool failures are operation outcomes, not automatic Run failures. An owned
+Claude execution process dying closes its exact input and marks its Session
+failed, even while the supervising Host remains alive. A deliberately stopped
+Session with settled native input is idle rather than a false runtime failure.
+
+## Execution audit
+
+`execution audit` aggregates existing Task, Run, wake, Session, Review,
+Integration, Publication, event, WorkItem, storage and orchestration evidence.
+`--since` and `--until` bound the time window. Sections report their own read
+errors without inventing values for missing data.
+
+Fault classification uses Core-owned failure reasons or explicitly identified
+Core diagnostic evidence. Agent-authored report prose is not parsed into
+verdicts or severity. Native Agent errors retain their original payload and
+standard category for the Agent to interpret with current Task context.
+
+Cost and repeated-work advisories do not prevent a legal action, set a Review
+budget or choose a recovery topology. `task next-action` is decision support,
+not an automatically executed plan.
+
+## Privacy and resource boundary
+
+Telemetry and caches are diagnostic material, not Task truth or a transcript
+backup. Do not collect or publish credentials, private environment values or
+raw Provider history merely to explain a status.
+
+Start with exact read-only records. Process changes, cancellation, grant updates
+and resource cleanup require the relevant explicit action and scope. A generic
+diagnostic request does not authorize live-model, shared or production tests.