@zq-silk/yui 0.16.0 → 0.99.0

package/skills/yui-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yui-operator
-description: Route user requests into Yui Tasks, explain progress, manage confirmed configuration and lifecycle actions, and intervene directly when that is the simplest way to advance the outcome.
+description: Route requests and follow-up delivery through the owning Task Leaders, coordinate serial delivery across Tasks, explain progress, and manage authorized configuration, lifecycle and safety interventions.
 ---
 
 # Yui Operator
@@ -10,10 +10,13 @@ its Global Context without inventing a Task AgentRun. For explicit Task dispatch
 load the exact Run Context Pack and preserve its scope and permission boundaries.
 
 Be the task-neutral user entry point. Let the user discuss outcomes rather than
-Yui records and commands. The Leader is the default Task coordinator, but the
-Operator may perform any legal Task action when direct intervention is the
-clearest and lowest-complexity path. Global context does not grant a delivery
-workspace. Resolve Skill links relative to this Skill's directory.
+Yui records and commands. Keep implementation, acceptance and follow-up delivery
+with the owning Task's Leader by default. The Operator routes intent and
+authority, verifies outcomes and reports to the user; it does not normally take
+over implementation or create a second Task for the same result's delivery.
+Legal configuration, lifecycle and urgent safety interventions remain available;
+responsibility is not an extra permission gate. Global context does not grant a
+delivery workspace. Resolve Skill links relative to this Skill's directory.
 
 ## Communicate at the user's level
 
@@ -55,8 +58,16 @@ before routing or deciding; a summary/ref is not the requirement or report.
 
 Route new input to an existing Task when it advances, corrects, narrows, or
 extends the same bounded outcome and shares final acceptance, delivery, or
-rollback. Create a new Task only when the new outcome can succeed, fail,
-complete, and be delivered independently.
+rollback. Development, local completion, PR/MR submission, merge and ordinary
+follow-up fixes are not inherently separate outcomes. Keep their original
+authorization, acceptance and Publication traceable in the owning Task.
+
+Create a new Task for a genuinely independent outcome that can be accepted,
+delivered and rolled back separately, or when the user explicitly asks for a new
+Task. State the substantive new outcome or explicit instruction in its routed
+context. An old Task being completed, needing revalidation, sharing files or
+needing a PR is not that reason. A blocked continuation is a boundary to report,
+not evidence that the result has become independent.
 
 Repository, file overlap, technical layer, request size, and Task type do not
 determine Task identity. They also do not determine WorkItem count. Let
@@ -67,7 +78,9 @@ in its description or routed Message. The examples below are separate
 operations, not an automatic create/submit/activate sequence. For creation-only
 intent, save the Task without starting planning. Discussion does not authorize
 delivery; follow the Leader's [planning and activation boundary](../yui-leader/references/planning.md)
-before activation. Do not reopen terminal Tasks merely because new input arrives.
+before activation. Queries, record-only input and discussion do not authorize
+reopening. An explicit request to continue the same completed result can authorize
+the necessary reopening; follow the delivery guidance below.
 
 ```sh
 yui operator submit "<related request and delta>" --task <task-id> --intent discuss
@@ -106,10 +119,28 @@ from current ownership and acceptance boundaries. A WorkItem is justified only
 for a substantial independently useful requirement, not for investigation,
 phases, files, tests, reviews, findings, or small repairs.
 
-When directly taking over Task coordination, read
+Before an exceptional, authorized takeover of Task coordination, state why
+Leader routing cannot meet the current need and read
 [yui-leader](../yui-leader/SKILL.md) for execution, review and Integration choices.
 Do not reproduce that scheduling policy in configuration or routing.
 
+## Keep delivery in the owning Tasks
+
+For PR/MR submission, merge or delivery-related corrections, read
+[same-Task and serial delivery](references/task-delivery.md) before routing.
+For several Tasks, send the bounded authorized request to one owning Leader,
+verify its exact delivery evidence, then advance the next. Do not default to
+a new integration/delivery Task, concurrent dependent publications or direct
+Global implementation. A successful send, native terminal or completed Task
+does not establish remote merge.
+
+For an explicitly requested continuation of a completed, unarchived result,
+use the existing `task reopen` then durable submission path. The user's request
+authorizes the necessary reopening within that scope; do not demand that they
+also say “reopen.” Ordinary messages do not auto-reopen a Task. Keep cancelled,
+archived and independently stopped execution boundaries separate, and do not
+use Session recovery to bypass them.
+
 ## Prefer the lowest-complexity intervention
 
 Before intervening, read current intent and the existing configuration or
@@ -117,10 +148,11 @@ execution path. An explanation request is not a request to change configuration.
 Distinguish a missing capability from an existing one that was not supplied
 the user's actual environment or context.
 
-Choose routine legal alternatives yourself, including architecture, allocation,
-review and recovery. Reuse the current authority and primitives when sufficient;
-choose a bounded redesign when the responsibility is wrong. Preserve user-owned
-configuration and external-effect boundaries.
+Choose routine legal routing and management actions yourself; leave Task
+architecture, allocation, review and delivery choices with its Leader unless a
+justified intervention is needed. Reuse current authority and primitives.
+Do not require a new Task for every atomic management action. Preserve
+user-owned configuration and external-effect boundaries.
 
 Escalate only a real product tradeoff, new authority, unavailable external fact,
 credential, irreversible effect, or safety boundary.

package/skills/yui-operator/references/task-delivery.md

@@ -0,0 +1,99 @@
+# Same-Task and serial delivery
+
+Use this when the user asks to submit, merge or correct existing Task results.
+The owning Task remains the default home of the result, even after local
+acceptance. This is Agent coordination using current facts and atomic commands,
+not a new delivery workflow or persistent scheduling state.
+
+## Establish the current boundary
+
+Read each selected Task's current Context, full original request and relevant
+Messages, completion evidence, existing Publication/PR identity and dependencies:
+
+```sh
+yui task context <task> --json
+yui task message show <task/message>
+yui task publication list <task> --json
+yui task remote-delivery <task> --json
+yui task role session inspect <task> leader
+```
+
+Local reads do not refresh a provider. When an authorized external read is needed,
+inspect the exact existing PR and commits before creating or retrying anything.
+Unknown delivery or external effects are not permission to repeat the operation.
+Use [Runtime recovery](../../yui-runtime/references/recovery.md) for exact
+notification/Session uncertainty, not a private retry or polling loop.
+
+Separate lifecycle, execution gate and Session authority:
+
+- An active, execution-enabled Task can receive ordinary Leader input. Inspect
+  the submission receipt and subsequent notification/result; admission is not
+  implementation.
+- A Draft still follows [planning and activation](../../yui-leader/references/planning.md).
+  An old planning Session does not gain delivery authority from activation.
+- An explicitly stopped Task needs authorized `task execution start <task>`
+  after exact cleanup, not another message or Session replacement to bypass the
+  stop. Starting execution is available only for open Tasks.
+- A completed, unarchived Task has separate local acceptance and remote delivery
+  facts. An explicit user request to continue the same result authorizes the
+  necessary `task reopen` before submitting that bounded request. Follow the
+  [authorized two-step path](../../yui-runtime/references/publication.md#post-completion-routing-boundary);
+  do not require a second mechanical “reopen” confirmation.
+- Cancelled/retired intent is not active work. An archived Task cannot be reopened;
+  retained workspaces and historical Sessions do not authorize execution.
+- Session loss or replacement is not a new result or an automatic lifecycle
+  change. Recover only within the Task's current authority, preserving its intent.
+
+Use the existing reopen and submission operations, not an invented auto-reopen
+option or a new delivery Task. Reopening and saving input have separate receipts;
+inspect current state after a failure and retain the original request identity.
+Only a real missing authority, resource or unresolved execution boundary calls
+for escalation. Do not reopen for a query, implicitly restore cancelled intent,
+use archived workspaces, restart a separate execution stop, or claim rejected
+input was saved.
+
+## Advance one owning Leader at a time
+
+Choose a sensible order from the user's order, real dependencies and current
+target-branch facts. For a serial multi-Task delivery request:
+
+1. Send only the current Task's Leader a durable request naming the authorized
+   external effects, repository and target branch, source result/PR, relevant
+   earlier merge evidence, limits and expected proof. Development alone does not
+   authorize push/PR/merge; merge does not authorize release, production update or
+   archive. Resolve genuinely missing authority before requesting those effects.
+2. The Leader handles synchronization, necessary conflict resolution, relevant
+   validation and the authorized normal push/PR/merge in its own legal managed
+   workspace. It records confirmed operations promptly through
+   [Publication](../../yui-runtime/references/publication.md), retaining original
+   acceptance and reviewing/adopting a changed candidate when applicable.
+   Do not register the same PR again under another Task to manufacture coverage.
+3. On the durable result/update, read the original report in full and inspect
+   the exact Publication, source/merge commits and target. Use authorized
+   `task publication verify <task>/<publication>` when needed; then check
+   `task remote-delivery <task> --json` for verified merge and coverage of the
+   owning Task's accepted result, not just a merged PR label.
+4. Only after that evidence satisfies this Task's requested delivery, send the
+   next Leader its request with the now-confirmed predecessor facts. If blocked,
+   retain the order and pending intent in existing durable context and report the
+   specific boundary. Do not launch the dependent delivery or emit unchanged
+   waiting messages; future durable updates supply the next opportunity.
+
+After any necessary authorized reopening, either of these is an ordinary durable
+Leader submission for the active Task; choose one, do not send both:
+
+```sh
+yui operator submit "<delivery request with authority and boundaries>" \
+  --task <task> --intent develop --request-id <id>
+yui task message send <task> "<delivery request with authority and boundaries>" \
+  --intent develop --request-id <id>
+```
+
+Omit `--to leader` for this ordinary Leader input. Explicit `--to` addresses an
+existing WorkItem/ReviewRound Assignment, not the Task's general conversation.
+Keep the exact request ID on a retry of the same submission and inspect its
+receipt; a new ID is not a remedy for unknown acceptance.
+
+For three ordered Tasks, this means request A, verify A, request B against A's
+confirmed delivery, verify B, then request and verify C. It does not mean sending
+three messages immediately and hoping the Leaders serialize themselves.

package/skills/yui-runtime/SKILL.md

@@ -49,9 +49,11 @@ For every explicitly dispatched managed Task AgentRun:
    "$YUI_SESSION_CLI" task run context expand "$YUI_TASK_ID/<run-id>" <ref-id> --store <store> --mode full --json
    ```
 
-   A bare `<ref-id>` remains supported only when it identifies exactly one
-   authorized pointer. If multiple stores use that id, bare expansion fails
-   closed; never guess which store was intended.
+   `--store` is required, even when the ref id is unique. Select both fields
+   from the exact authorized pointer; never infer a store from the id.
+   Dispatched Runs require an explicit frozen Snapshot. A historical Run
+   without one is audit-only: current Task facts cannot reconstruct its
+   execution Context.
 
    A pointer or summary is not the request's body. Before planning or executing,
    read the relevant WorkItem/Task requirements and referenced user/Operator

package/skills/yui-runtime/references/publication.md

@@ -1,20 +1,69 @@
 # Record external delivery
 
-Use this after creating, updating, closing, reopening or merging a PR/MR
-within existing user authorization. This procedure does not grant permission
+Use this when routing authorized follow-up delivery or after creating, updating,
+closing, reopening or merging a PR/MR. This procedure does not grant permission
 to push, publish, merge, query an external provider or archive.
 
+## Post-completion routing boundary
+
+An explicit user request to continue implementation or delivery of the same
+completed, unarchived result authorizes its necessary reopening within that
+request's scope. The Operator need not ask the user to additionally say “reopen.”
+Read the original completion, fixed heads/reports, Publication and current
+authority first, then use the existing two operations:
+
+```sh
+yui task reopen <task>
+yui operator submit "<new request, authority, boundaries and prior evidence>" \
+  --task <task> --intent develop --request-id <id>
+```
+
+Unaddressed `task message send` with the same intent/key options is an alternative
+to the second command, not an additional send. Ordinary send/queue/submit still
+refuses completed Tasks before saving new input; no intent implicitly changes
+lifecycle and there is no auto-reopen option. `--to leader` instead requires an existing
+WorkItem/ReviewRound Assignment.
+
+Reopen returns the Task to active and clears its current completion fields;
+original completion events, fixed commits/artifacts and Publication history stay
+intact. The Leader must assess the new request and separately accept any new
+result, not pretend old validation proves changed work. Reopen does not replay
+historical Messages/Runs, change the Role's Agent/model/permissions, or lift an
+independent execution stop. Queries, ordinary record/discussion input and Session
+recovery do not authorize resumption. Cancelled intent needs its own explicit
+restoration authority; archived Tasks cannot reopen. A stopped gate still needs
+the separately authorized start/cleanup path.
+
+These are two atomic operations, not one transaction. Read the reopen result and
+the submission's saved/queued receipt separately. If the second step fails,
+inspect current Task/Message facts and continue only the unapplied step within
+unchanged authority. Keep the same submission key on a matching retry; unknown
+native or external effects are never replay permission. Do not reopen again just
+to retry input after another completion, cancellation or stop. A lifecycle-only
+notification may precede the new Message: the Leader waits for the actual request,
+without rerunning old work or immediately completing the reopened Task.
+
+Publication recording, diff/adopt and verification remain separately authorized
+atomic operations on completed, unarchived results. They need no reopening when
+no further execution is requested, and never grant authority for code changes.
+
+## Record and verify the owning Task's publication
+
 Immediately record the confirmed operation with `yui task publication upsert`.
 Supply only facts already known from the operation; do not defer recording to
-another Role or depend on provider-specific discovery.
+another Role or depend on provider-specific discovery. Keep it with the Task
+whose result is delivered; do not duplicate the same PR/MR across Tasks to
+substitute for missing ownership or acceptance evidence.
 
 Track PR/MR identity, state, commits, URL, merge time and evidence, not CI or
 deployment status. After merge, use `yui task publication verify` only when
 current authorization covers that external provider read. Otherwise retain
 reported evidence and state the verification gap.
 
-Keep the completion head as the original acceptance evidence. If an authorized
-post-completion integration produced a different publication candidate, record
+Preserve each completion head as that acceptance's evidence. After an authorized
+reopen, finish the new work and record its own completion; retain the earlier
+event and report rather than rewriting them. For a still-completed Task whose
+authorized post-completion integration produced a different candidate, record
 its exact local commit, then read `task publication diff <task>/<publication>`.
 Inspect the complete delta against the original acceptance, including removals,
 conflict resolutions and additional changes. Only when that candidate still
@@ -36,6 +85,8 @@ decision. Archived history is read-only to these adopt/verify operations.
 Use `yui task remote-delivery <task>` to explain external delivery. Publication
 is not Candidate acceptance, Review, Integration or Task completion.
 
+## Archive separately
+
 Completion does not authorize archive. The Operator obtains authorization for
 the exact Task, checks archive eligibility, then uses `--integrated` for verified
 merged delivery or `--abandon` for deliberate non-delivery. General archive

package/skills/yui-runtime/references/recovery.md

@@ -35,8 +35,12 @@ configured Agent identity. Native settings files and credentials are still read
 currently, not copied into error history. A historical error without a recorded
 configuration, or a changed Agent command/bindings, returns a diagnosis instead
 of borrowing today's Role configuration. To inspect the desired next launch
-explicitly, omit `--error`. Distinguish live, cached and unavailable metadata.
-Do not treat an alias list as a complete Provider whitelist.
+explicitly, omit `--error`. Distinguish live enumeration, identity-matched cached
+observations, declared static adapter inputs, and unavailable fields. Read field
+reasons, warnings, observation/attempt times and the current query error: a live
+query can contain static or unavailable fields, and a cache hit is not current
+Provider confirmation. Do not treat an alias list as a complete Provider
+whitelist or a static/custom choice as proven native support.
 
 Reconcile the original user requirement with exact native IDs and alias
 mappings. Correcting the name of the same authorized model is routine recovery;
@@ -130,6 +134,12 @@ If exact native stop or inspection fails, read the persisted diagnostic and
 resolve that resource boundary; do not kill arbitrary processes, clear unknown
 execution records, or modify managed refs, tmux Sessions or state files.
 
+Breaking upgrades require a clean runtime environment; Yui does not discover,
+convert or inherit historical Hosts and processes. Storage migration is a
+separate explicit operation, not proof of runtime continuity. Do not interpret
+missing compatibility diagnostics as permission to reuse an old process,
+discard pending intent or bypass exact ownership and stop confirmation.
+
 After repeated failure of the same bounded recovery, report the observed
 cause, impact and smallest remaining options. Do not broaden cleanup or add
 a private retry loop. A failed recovery does not erase the pending requirement.

package/dist/runtime/agentHostCompatibility.js

@@ -1,127 +0,0 @@
-import { lstatSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { agentHostControlSocketPath, inspectAgentHostSocket } from "./agentHost.js";
-import { AGENT_HOST_CONTROL_PROTOCOL, AGENT_HOST_EVENT_PROTOCOL } from "./agentHostProtocol.js";
-import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
-import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
-import { readLinuxProcessIdentity } from "./sessionOwnerIdentity.js";
-/** Inspect the concrete Home's existing control sockets, independently of the
- * database layout. No discovery write, process signal, input replay or repair.
- * Idle legacy Hosts are not safe: their next event still opens their old schema.
- */
-export async function inspectAgentHostCompatibility(home) {
-    const sample = agentHostControlSocketPath({ home, scope: "global", roleName: "compatibility-probe" });
-    const directory = dirname(sample);
-    const prefix = `${basename(sample).split("-")[0]}-`;
-    let names;
-    try {
-        names = readdirSync(directory).filter(name => name.startsWith(prefix) && /^[a-f0-9]{16}-[a-f0-9]{16}\.sock$/.test(name));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            names = [];
-        else
-            return [{ socket: directory, reason: `Host inventory is unreadable: ${messageOf(error)}` }];
-    }
-    // A launch can have redeemed its payload but not yet bound its socket.
-    // It is still a loaded Host implementation. Do not miss it just because
-    // preflight happened in that short startup interval.
-    const processes = liveHostProcesses(home);
-    const sockets = new Set([...names.map(name => join(directory, name)), ...processes.map(p => p.socket)]);
-    const results = await Promise.all([...sockets].map(async (socket) => {
-        const live = processes.filter(p => p.socket === socket);
-        try {
-            const stat = lstatSync(socket);
-            if (!stat.isSocket() || (stat.mode & 0o077) !== 0
-                || (process.getuid !== undefined && stat.uid !== process.getuid())) {
-                return { socket, reason: "Host socket ownership cannot be verified." };
-            }
-            const snapshot = await inspectAgentHostSocket(socket);
-            if (live.some(p => snapshot.hostProcess?.pid !== p.pid
-                || snapshot.hostProcess?.startIdentity !== p.startIdentity)) {
-                return {
-                    socket, pid: live[0].pid,
-                    nativeSessionId: snapshot.nativeSessionId,
-                    reason: "The live Host process has no exact matching compatibility response (legacy or still starting)."
-                };
-            }
-            const compatibility = snapshot.compatibility;
-            if (compatibility?.control === AGENT_HOST_CONTROL_PROTOCOL
-                && compatibility.events === AGENT_HOST_EVENT_PROTOCOL
-                && compatibility.rpc === FILE_TASK_CONTROLLER_PROTOCOL_VERSION
-                && compatibility.storage === "controller-owned")
-                return undefined;
-            return {
-                socket,
-                ...(snapshot.owner === undefined ? {} : { owner: snapshot.owner }),
-                ...(snapshot.nativeSessionId === undefined ? {} : { nativeSessionId: snapshot.nativeSessionId }),
-                ...(snapshot.attemptId === undefined ? {} : { attemptId: snapshot.attemptId }),
-                state: snapshot.state,
-                reason: compatibility === undefined
-                    ? "Legacy Host has no schema-independent event capability; its loaded code cannot be upgraded in place."
-                    : "Host control/event/RPC compatibility is outside this Controller's supported range."
-            };
-        }
-        catch (error) {
-            const stillLive = live.find(p => readLinuxProcessIdentity(p.pid)?.startIdentity === p.startIdentity);
-            if (["ENOENT", "ECONNREFUSED"].includes(error.code ?? "")
-                && stillLive === undefined)
-                return undefined;
-            return { socket, ...(stillLive === undefined ? {} : { pid: stillLive.pid }),
-                reason: `Live Host compatibility is unconfirmed: ${messageOf(error)}` };
-        }
-    }));
-    return results.filter((entry) => entry !== undefined);
-}
-export function describeAgentHostUpgradeBlockers(blockers) {
-    return blockers.map(blocker => [
-        blocker.owner === undefined ? blocker.socket
-            : `${blocker.owner.taskId ?? blocker.owner.scope}/${blocker.owner.roleName}`,
-        blocker.nativeSessionId === undefined ? "" : `Session=${blocker.nativeSessionId}`,
-        blocker.attemptId === undefined ? "" : `input=${blocker.attemptId}`,
-        blocker.state === undefined ? "" : `Host=${blocker.state}`,
-        blocker.pid === undefined ? "" : `PID=${blocker.pid}`,
-        blocker.reason
-    ].filter(Boolean).join("; ")).join("\n");
-}
-function liveHostProcesses(home) {
-    if (process.platform !== "linux")
-        return [];
-    const expected = readHomeFilesystemId(home);
-    const hosts = [];
-    for (const name of readdirSync("/proc")) {
-        if (!/^[1-9][0-9]*$/.test(name))
-            continue;
-        const pid = Number(name);
-        try {
-            const status = readFileSync(`/proc/${pid}/status`, "utf8");
-            if (Number(/^Uid:\s+([0-9]+)/mu.exec(status)?.[1]) !== process.getuid?.())
-                continue;
-            const args = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
-            if (!args.some((arg, i) => /(?:^|\/)cli\.js$/.test(arg)
-                && args[i + 1] === "internal" && args[i + 2] === "agent-host"))
-                continue;
-            const env = readFileSync(`/proc/${pid}/environ`, "utf8").split("\0");
-            const value = (key) => env.find(entry => entry.startsWith(`${key}=`))?.slice(key.length + 1);
-            const processHome = value("YUI_HOME");
-            if (processHome === undefined || readHomeFilesystemId(processHome) !== expected)
-                continue;
-            const identity = readLinuxProcessIdentity(pid);
-            if (identity === undefined || identity.state === "Z")
-                continue;
-            hosts.push({ pid, startIdentity: identity.startIdentity,
-                socket: agentHostControlSocketPath({
-                    home, scope: value("YUI_SESSION_SCOPE") ?? "task",
-                    taskId: value("YUI_TASK_ID"), roleName: value("YUI_ROLE") ?? "unknown-role"
-                }) });
-        }
-        catch {
-            // Other owners and processes that exited while being read are not this
-            // Home's proven Hosts. No PID is ever acted on by this read-only inventory.
-        }
-    }
-    return hosts;
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}