@zq-silk/yui 2.10.0 → 2.12.0

package/docs/job-runs.md

@@ -2,11 +2,78 @@
 
 A Job is a stable, scoped definition. A JobRun is one execution, with its own
 ID, configuration revision, trigger, immutable execution specification,
-process identity, artifacts and terminal result. Changing a definition never
+process or exact Agent execution identity, artifacts and terminal result. Changing a definition never
 changes an admitted Run. No Schedule is needed for immediate execution.
 
 ## CLI and ownership
 
+### Optional Agent execution
+
+An Agent configuration selects a logical target, never a permanent native
+Session: `{kind:"operator"}`, `{kind:"task",taskId,roleName,ownerRunId?}`, or
+`{kind:"job",agentId}`. Non-Leader Task targets require the current Assignment's
+exact `ownerRunId`; this does not create or delegate a Task. Task-owned Jobs
+cannot target Operator or another Task. Job-owned Agents reuse ordinary Global
+Role transport but have only their own Job's read/report authority, not
+Operator or Project authority.
+
+```sh
+yui job define --global --job analyze --title "Saved analysis" \
+  --input '{"kind":"agent","target":{"kind":"job","agentId":"codex"},"input":"Analyze the saved evidence."}'
+yui job session-create --global --job analyze
+yui job run --global --job analyze --request-id first
+yui job run-context --global --job analyze --run <run-id>
+yui job run-evidence --global --job analyze --run <run-id>
+yui job session-inspect --global --job analyze
+```
+
+`session-create` prepares the logical Role; the normal Host creates its Session
+on delivery. Launch messages contain exact context pointers. The executing Agent
+uses `run-claim`, reads `run-context`, then `run-report --result <JSON>` with the
+normal `JobBusinessResult` envelope (`schemaVersion`, exact `sourceRun`,
+`outcome`, `summary`, `evidence`). Reports require that caller's current accepted
+native Turn to own the original message. The Provider observation path retains
+actual attempts and terminals even when no report is returned. Delivery, native
+terminal and explicit business result remain separate facts. `run-confirm`
+only collects existing evidence; it never replays work.
+
+Default execution is serial per Job, reusing its Role Session across Runs.
+Explicit `concurrency:"isolated"` is supported only for Job-owned Agents and
+creates a distinct Role/workspace for each Run; sibling Run contexts remain
+inaccessible to that executor. Existing Provider single-writer and bounded
+classified retry rules still apply. Agent Jobs currently use explicit
+manual/retry admission; a Schedule service grant for engineering actions is
+not authority to execute an Agent.
+
+`run-cancel` records a cooperative request on that exact Run. It does not
+interrupt a shared Operator/Task Role or imply that work stopped. Check
+`cancelRequestedAt` before effects and report the actual outcome. An unfinished
+business Run can use `run-continue --expected-attempt <prior-attempt-id>` only
+after its exact native terminal; this
+adds an original continuation message to the same Run, not a new failed-Run
+retry. Repeating the same expected attempt returns the existing successor
+without submitting another message. Inspect prior effects first: terminal does not undo them.
+
+For a Job-owned Session, `session-stop --expected-session <native-id>` requests
+existing lifecycle cleanup only after the current native Turn is terminal.
+It returns acceptance, not proof of stop. Inspect until the original Session
+is ended, then `session-new --expected-session <native-id>` preserves its
+history and clears the current Session for the next normal launch.
+Isolated Jobs also require `--run <run-id>` on Session operations.
+Unknown delivery and unproven old writers block replacement/continuation;
+replacement never resubmits input. Definition snapshots, Run requirements,
+explicit results and fixed artifact references survive independently of the
+transcript. Shared targets use their existing Role lifecycle, not Job-owned
+Session operations. CLI and `job.definition` RPC expose the same operations.
+Changing the executor kind requires a new Job ID; revisions can change its
+configuration without hiding another executor's original history.
+Task-owned Agent Jobs participate in Task completion/ordinary archive settlement.
+Archive also requires exact native-terminal evidence; an explicit business
+report alone never proves quiescence. Idle Job-owned Role Sessions and their
+separate scratch workspaces are retained, not silently deleted by Task archive.
+
+### Engineering execution
+
 Commands operate through the Controller's `job.definition` RPC:
 
 ```sh
@@ -15,6 +82,9 @@ yui job define --global --job probe --title "Local probe" \
 yui job run --global --job probe --request-id first
 yui job runs --global --job probe
 yui job run-get --global --job probe --run <exact-run-id>
+yui job run-result --global --job probe --run <exact-run-id>
+yui job run-evidence --global --job probe --run <exact-run-id>
+yui job run-confirm --global --job probe --run <exact-run-id>
 yui job logs --global --job probe --run <exact-run-id>
 yui job run-cancel --global --job probe --run <exact-run-id>
 ```
@@ -27,11 +97,23 @@ with `job show`, listed with `job list`, and revised with `job update --revision
 <observed-revision> --title ... --input ...`. A definition ID is required on
 creation; replaying an identical creation is idempotent. Scope cannot be updated.
 
-Global Job management requires the current authenticated Operator Session.
+Global Job management accepts public local callers or the current authenticated
+Operator Session. A public caller uses `scope:user` with no managed identity
+fields. The normal CLI first resolves native conversation identity against the
+selected Home: unknown provider conversations remain public, while known
+managed, historical, partial or revoked identities never fall back to user.
+The local Controller socket is a single-user Home boundary, not a remote
+authentication endpoint; `scope:user` is not a token granting Task or shell access.
 Other GlobalRoles cannot inspect or manage Task Job definitions either, matching
 the existing Task Context authorization boundary.
-Users can request it through Operator. Literal `caller.scope=user` is not a
-credential on the existing Controller socket. Task Sessions cannot inspect,
+Public immediate admissions bind the exact Home, Run, definition revision,
+target/input and trigger; they need no Agent configuration, Operator, Session
+or empty Task. They do not enqueue an Agent wake on completion. This is not a
+persistent Schedule grant: public `source:schedule` admission is rejected.
+The separate [Schedule management API](schedules.md) offers an explicit
+revocable service grant without an Operator Session; existing plans retain
+their Session authority until deliberately rebound.
+Task Sessions cannot inspect,
 create, modify or run global Jobs. The initial global action is `system.noop`,
 a fixed local no-op implemented by the same standalone runner. It accepts only
 empty input and no Project; it does not call a model or external service.
@@ -67,7 +149,8 @@ authoritative Task Run table, with `definitionId`, `definitionRevision` and
 `trigger` added to each payload. This retains every Task-local Run ID and
 artifact location. Global Runs have `scope:"global"` and no `taskId`, Task or
 Assignment. They use the same execution state machine and supervisor; their
-terminal notices enter the Operator mailbox, never a Task Leader mailbox.
+Operator-admitted terminal notices enter the Operator mailbox, never a Task
+Leader mailbox. Public immediate Runs are read directly without Agent delivery.
 
 The centralized transactional migration maps each old DurableJob to one
 definition with the same local ID and one preserved Run. Equal commands are
@@ -79,6 +162,135 @@ dual-format reader. A failed migration rolls back without advancing storage.
 Actual Home upgrades require their own authorization and backup; this change
 does not authorize or perform one.
 
+Storage **1.14 → 1.15** adds `businessResult` to terminal Run payloads and public
+immediate authority bindings to new Runs. Original terminal payload bytes are
+archived under migration 15; the migration derives only the recorded outcome
+and a versioned reference to the unchanged process result. It never parses logs,
+invents domain data, rewrites Integration references or changes active Run
+identities. Ordinary readers use only the current contract.
+
+## Business outcome and evidence
+
+`run-result` returns the admitted snapshot, `acceptedAt`, `startedAt`,
+`confirmedAt`, current `status` and nullable `result`. Acceptance is not start;
+start is not confirmation. The snapshot is derived exclusively from the immutable
+Run fields, never a mutable current Job definition. Scope, executor (`shell` or
+controlled `builtin`, or `task`), target and trigger are separate concepts. Task
+delegation is available in either management scope; shell remains Task-only and
+builtin remains global-only. There is no extensible empty
+executor/plugin configuration or arbitrary global shell.
+
+## Delegating delivery to a Task
+
+Job scope answers **who manages the definition**, Run delegation answers **which
+delivery is requested**, and immutable `Task.source` answers **why it was created**.
+Neither relation is an authority parent. A global Job remains global; a Job
+owned by A can create B without appearing in B's managed Jobs list.
+
+An explicit Task executor configuration creates a new Draft per independent Run:
+
+```json
+{"kind":"task","goal":"delivery","target":{"kind":"new","title":"Deliver report","description":"Requirements and acceptance here.","projectBindings":[]}}
+```
+
+`target.type` is optional business metadata, not an automation discriminator.
+Project bindings use the ordinary Draft `{projectId,directory,baseRef}` contract.
+`goal:"task-created"` is the explicit alternative when creation really is the
+entire goal. It must never be used as a shortcut for delivery.
+
+Use ordinary `job define` / `job run`. Task, configured Leader, exact scoped
+Run and its immutable relation are committed in the **same SQLite transaction**.
+Repeating the same admitted trigger returns the original Run/Task, including
+after restart or completion; conflicting definition revisions are refused.
+New independent Runs create new Tasks, never reopen an old cycle.
+Missing Leader configuration or failed persistence rolls back the whole admission.
+Creation does not authorize execution: the target starts Draft; use existing
+Task submit/develop and Activation with the caller's own target authority.
+The Task owns its Leader, optional WorkItems, acceptance, Integration and archive.
+There is no Job Leader, JobWorkItem or second delivery state.
+
+For an existing ordinary Task, first create an explicit open WorkItem through
+its ordinary authorized interface, then bind it precisely:
+
+```json
+{"kind":"task","goal":"work-item","target":{"kind":"work-item","taskId":"task-12","workItemId":"work-item-3","revision":1}}
+```
+
+The Job does not rewrite the Task's source. Admission captures the WorkItem's
+requirements digest and observed revision. Execution/candidate revisions can
+advance; changed requirements yield `unknown-needs-attention`, never guessed
+acceptance. Only its exact accepted Candidate settles the Run, not an Agent
+terminal, an unaccepted Candidate or the entire shared Task.
+Unscoped actions, arbitrary existing-Task completion waits and ambiguous targets
+are rejected. A Task Leader can bind only its own Task's exact WorkItem under
+its current writable delivery Session. Cross-Task creation/selection requires
+the existing Operator authority; public immediate global requests use actual
+user scope, never an invented Operator. Schedule service grants for builtin
+actions do not authorize Task delegation.
+
+The supervisor and `job run-confirm` collect existing delivery facts only.
+Delivery success pins the first exact `task.completed` event of the new target;
+WorkItem success pins its accepted Candidate. `task-result`/`work-item-result`
+evidence retains source Run, Task owner, relative locator and SHA256 of the
+original JSON object. Later reopen cannot rewrite a settled Run. These are result
+references, not copied Task bodies or an authorization to read arbitrary Context.
+Task executors use a distinct Run variant without process configuration,
+workspace or process evidence. They never spawn a runner and expose
+`execution:null` in snapshots.
+
+Select formal materials separately using the existing `artifact-register`
+interface and its source-Task plus Run authorization. Artifacts remain in their
+Task repository and pin owner, commit, path, digest and consuming Run. Only
+selected immutable objects become readable; no HEAD, directory or source-Task
+write access is inherited.
+
+`job run-delegation (--global|--task A) --job ID --run RUN` reports the exact
+target, state, open-input count and result reference. `task show B --json` exposes
+immutable source and a bounded incoming-delegation projection (with `complete`);
+`task list --source ordinary|job` filters creation origin. Incoming Run waits and
+uncertainty join the existing catalog `pendingOperations`/`unknownOperations`
+attention; target InputRequests remain in `openInputs`. These are current
+projections, not independent lifecycle records. Complete UI belongs elsewhere.
+
+`run-cancel` requests cancellation of this Run's delegation. Confirmation
+settles that wait as cancelled and explicitly reports **target resources not
+stopped**. It does not cancel/retire the shared WorkItem, stop the target Leader,
+or prove quiescence. Inspect/stop exact target resources through their normal
+authority if needed. Disabling a Schedule still affects future admissions only.
+Source never grants merge, publishing, cleanup or archive authority.
+
+Storage **1.18 → 1.19** adds optional immutable Task provenance and Run delegation
+and the new result-reference kinds without changing SQL layout or historical
+payload bytes. Ordinary historical Tasks remain source-less; unknown process
+effects, fixed artifacts and existing Schedule authorization stay untouched.
+
+`JobBusinessResult` has `schemaVersion:1`, exact `sourceRun:{scope,runId}`, an
+`outcome`, human-readable `summary`, optional JSON `data`, and `evidence`.
+Each evidence reference carries `kind`, `owner`, `sourceRun`, a SHA-256 `version`
+of the referenced bytes, and `locator`. These are evidence references, not a file
+artifact library; future file artifacts must preserve their own owner/version
+and source Run rather than treating a path as identity. Results are bounded to
+256 KiB. Shell results describe the process contract only; they cannot infer
+domain success from arbitrary log text. `system.noop` reports its controlled
+action. Project refresh reports observed commits/tracking and domain failures.
+
+`run-evidence` returns the exact operation receipts, PID/start identity,
+checkpoint, `processResult` and artifact location. The existing Run `result`
+field remains the original process evidence for Integration and existing readers;
+`businessResult` and `status` represent business outcome. A successful process
+does not prove a builtin business effect: missing/invalid business receipts yield
+`unknown-needs-attention` and block overlap/retry. Historical results contain
+only what their saved evidence proved, without invented structured data.
+
+The Project action writes `business-result.json` separately from stdout.
+Failure to save it after an effect is unknown, not an automatically retryable
+failure. A database collection failure leaves the original receipt and active Run
+available for later collection. `run-confirm` authenticates the exact Run and
+collects only retained ready/exit/checkpoint/business evidence; it never admits,
+spawns, retries or cancels an action. Repeated confirmation is idempotent.
+Terminal outcomes remain immutable; acknowledging an unknown is not success
+and does not authorize replay. There is no caller-supplied outcome override.
+
 IntegrationAttempt and verification consumers still use
 `getDurableJob(taskId, exactRunId)`. Existing Task Context `job` entries,
 execution audit, readiness/archive checks and HTTP preview tickets likewise
@@ -87,13 +299,123 @@ Task completion. Started Runs and retained unknown process evidence keep the
 existing Task lifecycle and physical-cleanup boundaries. The management UI
 retains exact references rather than replacing them with latest.
 
+## Formal file artifacts
+
+Jobs can save formal material without a Task or Session. The existing
+`job.definition` RPC also accepts `artifact-save`, `artifact-list`,
+`artifact-read`, `artifact-preview` and `artifact-register`, with the same
+`scope`, definition `id`, exact `runId` and authenticated `caller` boundaries.
+The CLI resolves that caller; do not supply or fabricate one:
+
+```sh
+yui job artifact-save --global --job probe --run <run-id> \
+  --artifact '{"relativePath":"reports/result.md","content":"# Result\n\nEvidence","message":"Record result"}'
+yui job artifact-list --global --job probe --run <run-id>
+yui job artifact-read --global --job probe --run <run-id> \
+  --reference '<exact reference object returned by save/list>'
+yui job artifact-preview --global --job probe --run <run-id> \
+  --reference '<exact registered reference object>' --offset 0
+yui job artifact-register --global --job probe --run <run-id> \
+  --reference '<exact already-saved reference object>'
+```
+
+Save input also accepts `expectedHead` for optimistic concurrency and
+`encoding:"base64"` for static PNG/JPEG/WebP. The shared repository accepts
+text up to 8 MiB and decoded images up to 4 MiB, with dimension/format
+validation; Job reference paths are limited to 512 characters.
+The **Job CLI/RPC save payload is additionally limited to 256 KiB of encoded
+JSON; read/preview responses allow 512 KiB** to include the added reference and
+presentation metadata. Both count JSON escaping/base64 inside the Controller's
+1 MiB envelope. The CLI checks saves before
+transmission. Larger producer-saved or delegated Task material may still be
+registered by its small exact reference: use paged preview for large text,
+or the owning Task's surface for larger images. No file is truncated.
+Preview otherwise shares the Task preview rules: whole Markdown up to
+256 KiB, paged text (12,000 characters with `nextOffset`), static raster
+metadata/base64, and no SVG or executable HTML. HTML is text data, never
+executed; clients must use the existing safe renderer.
+
+Save/register returns `{status:"registered",reference}` only after the file is
+committed **and** the Run reference is recorded. If the commit exists but
+publication fails, it instead returns
+`{status:"saved-unregistered",reference,error,recovery}`. This is partial
+success, not a published result. Inspect the exact Run and `artifact-list`,
+then explicitly register the retained reference. Never retry the business
+action to repair missing material registration. A lost RPC reply is unknown:
+inspect first. Git save failures preserve written working files and existing
+commits; expected-HEAD conflicts write nothing.
+
+A reference is:
+
+```json
+{
+  "kind": "artifact",
+  "owner": {"kind": "job", "scope": {"kind": "global"}, "jobId": "probe"},
+  "sourceRun": {"scope": {"kind": "global"}, "runId": "<exact-run-id>"},
+  "version": "<full Git commit>",
+  "relativePath": "reports/result.md",
+  "digest": "<SHA-256 of file bytes>"
+}
+```
+
+Unlike process-evidence `version` (SHA-256), an artifact's `version` is a full
+Git commit; its separate `digest` checks content. Reads require a registered
+exact reference, never HEAD, an ambient Task, or a bare filename. A Run's
+`artifacts` is an append-only list: later saves cannot replace earlier entries.
+The original `businessResult`, `result`, outcome and terminal evidence remain
+unchanged when material is collected after execution.
+
+Repositories live under
+`YUI_HOME/job-artifacts/global/<job-id>/<run-id>/` or
+`YUI_HOME/job-artifacts/task/<task-id>/<job-id>/<run-id>/`.
+Each Run has a distinct worktree and scoped commit lock, so even the same
+definition/path in concurrent Runs or different scopes cannot overwrite one
+another. They reuse the Task repository's local-only Git, path/symlink guards,
+size limits and commit protocol. Task repositories stay at their existing
+`task-artifacts/<task-id>` paths; all old commit-pinned Candidate, Review and
+completion references remain valid.
+
+`artifact-list.artifacts` lists **published** references.
+`repository.saved` describes the retained current Git snapshot for diagnosis
+and explicit registration; it is not publication. `repository.workingChanges`
+distinguishes uncommitted files. `job runs` and `run-result.artifacts` retain
+history; `job show`/`list` derive `results.latest` and
+`results.latestSuccessful` independently from readable Runs. A later failure
+does not hide the last success. Same-name versions are the entries with that
+`relativePath` across these Run histories, not a separately writable final file.
+
+For delegated Task material, an authorized Leader or Operator explicitly
+registers `owner:{"kind":"task","taskId":"task-N"}` with the selected original
+commit/path/digest and the consuming Run's `sourceRun`. Registration must pass
+both the Run's existing Assignment checks and the source Task's authorization.
+An Assignment reader cannot mint this selection. Subsequent Run readers may
+read **only that selected immutable object**, not the Task's HEAD, other
+files, or writes. The file stays in the Task repository; no copy or authority
+transfer occurs. The old same-Task `git:<commit>:<path>` shorthand is not
+accepted as a cross-entity reference. Task delegation admission itself belongs
+to its separate feature; this is the selected-material seam.
+
+Storage **1.16 → 1.17** declares the optional append-only Run references and
+Job-owned repository layout. It preserves existing payload bytes, process
+history, Task repositories and frozen references, and invents no historical
+artifacts. This is not a package-version release or an automatic Home upgrade.
+
+Formal repositories and referenced objects are retained by default. Replacing
+a Session, removing execution workspaces/logs, disabling a Schedule or ordinary
+Task archive does not delete them. There is no automated artifact GC or delete
+command. Manual cleanup requires separately authorized inspection of exact
+owners and references; do not remove repositories/commits still referenced by
+Runs, Candidates, Reviews or completion evidence. Retain uncertain ownership
+and unregistered/dirty evidence for diagnosis. This does not turn logs,
+heartbeats, checkpoints, Knowledge or Project state into formal artifacts.
+
 ## Extension seams for Schedule, Project refresh and management UI
 
 - `src/job/jobDefinition.ts`: `JobDefinition`, `JobScope`, `JobConfiguration`
   and `JobTrigger`. Definition revision is optimistic concurrency, not a Run
   status. Project targets stay in configuration.
 - `src/controller/jobDefinitionControl.ts`: `admitJobRun(store, home, scope,
-  definitionId, caller, trigger, now, retryOf?)` returns `RunAdmission`.
+  definitionId, caller, trigger, now, retryOf?, service?)` returns `RunAdmission`.
   It authenticates current scope, rechecks domain prerequisites, finds exact
   trigger replay and excludes overlap inside the Store transaction. Schedule
   can call it inside its own `store.transaction` with advancement in that same
@@ -101,7 +423,11 @@ retains exact references rather than replacing them with latest.
   A rollback discards both. `source:"schedule"` is an internal seam, not an
   accepted manual RPC assertion. Schedule must supply a legitimate current
   authority; it must not invent a Session or reuse a revoked identity. Any
-  additional durable scheduled-intent authorization belongs to that feature.
+  service reference is internal only and must match a current stored Schedule
+  grant; RPC never accepts it. `instantiateJobRun` owns deterministic instance
+  creation from an exact definition revision and composes the same admission
+  inside the caller's transaction. Instance creation, first Run and Schedule
+  advancement either all commit or all roll back.
 - `src/job/builtinJob.ts`: controlled action compilation. Add a narrowly
   validated builtin here; snapshot its target/input and compile runner steps
   from trusted code, never caller-supplied shell. Revalidate before spawn.
@@ -120,7 +446,7 @@ daemon, cross-Task dependency engine or release behavior.
 
 ## Controlled Project refresh
 
-An authenticated Operator can explicitly install one maintenance definition
+A public local caller or authenticated Operator can explicitly install one maintenance definition
 per registered managed Project, inspect it, and request independent Runs:
 
 ```sh
@@ -185,8 +511,9 @@ remote observation. Missing exit evidence, timeout or cancellation must not be
 presented as successful synchronization; inspect retained evidence before retry.
 The Run's all-zero `head` is not a Project revision; use the action's observations.
 
-No persistent envelope/table change is needed: action input and output use the
-existing JobDefinition/JobRun JSON and logs. Schedule should reference this same
+Action input uses the existing JobDefinition configuration; structured output
+uses the 1.15 business result alongside unchanged process evidence/logs.
+Schedule should reference this same
 global definition and use its existing admission seam, never a second Project
 automation state. The isolated core scenario covers interval-triggered refresh
 Runs, missed-period coalescing and disable behavior against a local Git remote.
@@ -197,9 +524,12 @@ This does not enable a cadence for any real Project.
 The Task's **Jobs** tab manages only that Task. **Settings → Jobs & schedules**
 manages global definitions. Both use the same component and public services.
 Create/edit a definition, run it immediately, select an exact historical Run
-and read its snapshot/results/logs, or request cancellation of that Run.
+and read its snapshot/results/diagnostics, or request cancellation of that Run.
 Task shell configuration uses the same explicit managed-workspace specification
-as the CLI; global creation offers only `system.noop` and `project.refresh`.
+as the CLI. Global controlled actions remain `system.noop` and `project.refresh`;
+Task-delegation and Agent definitions use their documented configuration, without
+inventing process fields. Executor kind cannot be changed on an existing definition.
+Builtin definitions have no arbitrary configuration editor.
 Creating or reading a Job never executes it.
 
 The HTTP routes are `/api/tasks/:taskId/jobs|schedules` and
@@ -207,11 +537,10 @@ The HTTP routes are `/api/tasks/:taskId/jobs|schedules` and
 takes the corresponding public operation fields, with `requestId` for manual
 Run admission. Routes fix scope. Browser-supplied `caller`, `scope` or trigger
 authority is rejected. The loopback token authenticates the local-user ingress,
-and writes additionally require an exact same Origin. The adapter resolves the
-current Operator Session from the server store on every call; if none is
-available, management reports that prerequisite rather than fabricating one.
-Its accepted Jobs/Schedules retain the normal Operator binding/revocation
-semantics. Managed RPC callers retain their existing authentication and cannot
+and writes additionally require an exact same Origin. Global management uses the
+authenticated local user, without requiring an Operator Session. Task-scoped
+management resolves the current Operator binding, preserving existing Task and
+Assignment checks. Managed RPC callers retain their authentication and cannot
 borrow this local-user adapter.
 
 Schedule forms support once, anchored interval and five-field cron with an
@@ -222,3 +551,49 @@ successful. Errors retain the draft; an unknown write is not automatically
 resent. Refresh only reads facts and keeps the selected Run exact. No new
 tables, scheduling loop, Project switch, implicit refresh or deletion semantics
 are introduced.
+
+### Product navigation and fixed evidence
+
+The daily Task list defaults to ordinary Tasks. Its ordinary / Job execution /
+all selector uses the existing server-side `source` catalog filter. Searching
+or opening an attention category searches across both categories; source is
+creation provenance, not Task business type. The CLI and Operator catalog
+defaults are unchanged.
+
+An execution Task links back to its immutable `Task.source` Job/Run. A delegated
+Run links to its actual target Task, whose Jobs tab still lists only definitions
+owned by that target. Links use `/?task=A&section=jobs&job=J&jobRun=R` or
+`/settings/jobs?job=J&jobRun=R`. A Schedule's last admission links to the recorded
+instance Job, which can differ from its template.
+
+Run details separate business results, structured evidence, registered artifacts
+and process logs. Agent diagnostics use Agent-aware evidence, not process logs;
+a diagnostic failure does not hide the Run's business result. Most recent Run,
+most recent successful Run, Project refresh observations and Schedule admission
+checks remain distinct. Refresh errors label retained facts as stale.
+
+Read-only `artifact-list` and `artifact-preview` are exposed on the same
+scope-fixed GET route. Preview requires `runId`, a JSON `reference`, and optional
+nonnegative `offset`; duplicate/unknown query fields are rejected. The existing
+artifact controller rechecks authorization after Git I/O and reads only a
+registered exact owner/Run/commit/path/digest. Text pagination, raster validation,
+Markdown limits and transport bounds are unchanged. The shared Task viewer
+renders Job evidence, but linked images must also be individually registered;
+there is no directory or HEAD fallback. Selected artifact references survive
+refresh/reload in the `artifact` view parameter and are matched against the
+selected Run's registered references before reading.
+
+`artifact-register` POST publishes one explicit saved reference. Inspecting
+unregistered saved files does not make them formal results. A partial
+`saved-unregistered` receipt is shown as such; it never starts business work.
+Artifact I/O runs outside synchronous SQLite transactions, retaining the
+controller's short publication transaction and original partial-result contract.
+
+`session-inspect` GET and `session-stop`/`session-new` POST are only offered for
+Job-owned Agent targets. Mutations include the observed `expectedSessionId`
+(and exact Run for isolated execution); the domain rejects unknown writers,
+unsettled input or stale identities. Stop requests cleanup, replacement requires
+confirmed termination, and neither replays input. Run cancellation is cooperative
+and does not stop a delegated Task or interrupt a shared Operator/Leader.
+Task stopping remains an explicit action on the target Task. Archive/cleanup
+are separate operations, not consequences of disabling, cancelling or replacing.

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

@@ -42,14 +42,19 @@ automatically create Runs. Explicit dispatch loads one exact Run Context Pack.
 ### Current caller and durable handling
 
 Desktop and TUI use the same current-Session authority. A Desktop command carrying
-only `CODEX_THREAD_ID` resolves its owner from the selected Home's existing active
-Session inventory, then verifies the current Role/Agent binding, revocation and
+only `CODEX_THREAD_ID` resolves its owner from the selected Home's current and
+historical Session records, then verifies the current Role/Agent binding, revocation and
 captured workspace. Codex's native ID takes precedence over an inherited transport
-ID, so a native child cannot borrow its parent's identity. Unknown native IDs,
-wrong Homes and conflicting hints fail closed; only a terminal with no managed or
-native identity is a plain user. Environment variables and a Manifest locate
+ID, so a native child carrying inherited Yui hints cannot borrow its parent's identity.
+An unknown provider ID alone is an ordinary public caller; partial Yui identity,
+known historical identities and conflicting hints fail closed. A wrong Home with
+Yui hints is rejected. A thread known only in another Home cannot be distinguished
+from an ordinary thread without those hints; Yui does not scan other Homes.
+Environment variables and a Manifest locate
 context, not continuing authority. A replaced Session retains only its bounded
 self-diagnostic reads, not inbox or mutation permission.
+See [authorization responsibilities and matrix](authorization.md) for the public
+surface, discovery semantics and resource boundaries.
 
 `yui inbox list` exposes the current identity, delivery evidence, handling state
 and blockers separately. Reads never consume input. Automatically accepted

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

@@ -5,11 +5,18 @@
 ## 当前身份与持久处理回执
 
 桌面与 TUI 使用相同的当前 Session 授权。只有 `CODEX_THREAD_ID` 的桌面命令
-先在所选 Home 的现有活动 Session 索引中定位角色，再校验当前绑定、撤销状态、
-工作域和 Assignment。Codex 原生线程 ID 优先于继承的 transport ID，原生子
-Agent 不能借用父身份。错误 Home、未知线程和冲突提示会明确拒绝，不降为公共
-用户；只有不带受管或原生身份的终端才是普通用户。环境变量和 Manifest 是
-定位提示，不是持续授权。旧 Session 仅保留限定的自身诊断读取。
+先在所选 Home 的当前及历史 Session 记录中定位角色，再校验当前绑定、撤销状态、
+工作域和 Assignment。Codex 原生线程 ID 优先于继承的 transport ID，携带父会话
+Yui 提示的原生子 Agent 不能借用父身份。只有未知原生线程 ID、没有 Yui 专属身份
+提示的普通会话，与用户终端共享现有公共入口，无需 Manifest 即可读取公共信息和
+创建 Draft；不会因此启动讨论／开发，也不会获得内部受管能力。
+部分受管身份、已知历史身份、冲突提示，以及带 Yui 提示的错误 Home 保持拒绝。
+仅在其他 Home 登记、当前 Home 完全未知的裸线程 ID 无法与普通线程区分，必须
+保留受管会话的正确 Home／Manifest 上下文，不能清空身份字段或切换 Home 绕权。
+环境变量和 Manifest 是定位提示，不是持续授权。旧 Session 仅保留限定的自身诊断读取。
+完整角色提示仍可生成离线帮助模板；只有原生 ID 时需只读查询本地登记，失败则显示
+有限的 unbound 模板。帮助均不是精确授权。职责和权限矩阵见
+[authorization.md](authorization.md)。
 
 `yui inbox list` 分别返回当前身份、投递事实、处理状态和阻断原因。自动接受的
 Global 消息、已投递的 Leader 窗口及当前 Assignment 续接消息仍须显式 claim，

package/docs/release-workflow.md

@@ -51,6 +51,85 @@ merely to avoid a version decision. Package versions remain distinct from protoc
 and persistent-storage contracts: their compatibility checks and required migrations
 are unchanged, and the storage rules below do not authorize a package release.
 
+### 2.12.0 compatibility and migration notes
+
+This minor completes the scoped Job platform: explicit business results and fixed
+artifacts, Schedule targets and service authorization, controlled Project refresh,
+Task delegation, optional Agent execution, and shared Task/global Web management.
+The Task Jobs tab and Settings → Jobs & schedules expose exact historical Runs,
+their immutable configuration, execution evidence and authorized artifact previews.
+
+Consumers must distinguish definition ownership, execution target, process/native
+terminal evidence and the explicit `businessResult`; delivery or exit alone is
+not business success. Branch on the executor kind instead of assuming every Run
+is a shell process. Fixed artifact references retain their exact source identity
+and scope; a readable preview is not execution authority. Task delegation preserves
+immutable provenance and does not implicitly activate a Draft Task. Agent Session
+replacement preserves Run requirements/results without replaying input; unknown
+delivery or unproven old writers still block replacement.
+See [Jobs and Runs](job-runs.md).
+
+Schedules retain their existing admission path, not a second execution state.
+Service authorization is explicit and does not inherit an old Session's authority
+or authorize Agent execution. Controlled `project.refresh` binds the current
+managed Project target and uses the existing clean, verified fast-forward path;
+publication does not enable synchronization for any registered Project.
+See [Schedules](schedules.md).
+
+Storage advances from **1.14 to 1.20** through the centralized contiguous chain:
+**1.15** business results; **1.16** Schedule targets/service authorization;
+**1.17** fixed Run artifacts; **1.18** controlled Project refresh;
+**1.19** Task delegation/provenance; **1.20** Agent Run/Session evidence.
+Supported **1.0–1.19** Homes use the declared same-major migrations, preserving
+historical evidence rather than inventing results or grants. With separate update
+authorization, use `yui update --version 2.12.0`; the updater owns preflight,
+backup, migration and Controller handover. Do not open upgraded Homes with an
+older binary or edit storage manually. Minor numbering is not a SemVer
+backward-compatibility promise.
+
+Release gates require exact-commit Core CI and fresh installation of the same
+runtime tarball on Linux x64 and macOS x64/arm64 with Node 20/22/24/26 before
+publication. These are deterministic isolated checks, not real-model validation.
+Publishing does not update the global CLI, migrate a production Home, replace
+its Controller or run a real Project synchronization.
+
+### 2.11.0 compatibility and migration notes
+
+This minor lets ordinary, unmanaged native Agent conversations use the same
+public operations as a local terminal, including general information reads and
+Draft Task creation. A native thread ID alone is a lookup hint, not proof of a
+managed Role. Draft creation preserves configured Agent, model, permissions and
+Profile inheritance; it does not start discussion or development.
+
+Current ID-only managed Desktop conversations retain their Role, Task,
+Assignment and Grant checks. Known historical, stopped, conflicting or
+incompletely specified managed identities are refused, never downgraded to
+public authority. Unbinding a Session or deleting a Role retains stopped
+identity history. Help and completion share caller discovery; offline Role
+templates are guidance, not authorization. Exact capability assessment and
+execution continue to use current resource and Grant boundaries.
+See the [authorization responsibility and permission matrices](authorization.md).
+
+Identity lookup is local to the selected Home. A bare ID known only in another
+Home, or whose history was already deleted by an older version, cannot be
+distinguished from an ordinary thread without Yui hints. Managed conversations
+must retain the correct Home/Manifest; this release neither scans other Homes
+nor reconstructs deleted history.
+
+Storage advances from **1.13 to 1.14** through an explicit centralized migration
+that allows global Session history to survive Role deletion while preserving
+existing payloads. Supported **1.0–1.13** Homes use the contiguous same-major
+upgrade path. With separate update authorization, use
+`yui update --version 2.11.0`; the updater owns preflight, backup, migration and
+Controller handover. Do not open upgraded Homes with an older binary or edit
+storage manually. Package minor numbering is not a compatibility promise.
+
+Release gates reuse exact-commit Core CI and exercise one runtime tarball on
+Linux x64 and macOS x64/arm64 with Node 20/22/24/26 before npm publication.
+These are deterministic, isolated checks, not real-model validation. Publication
+does not update a global CLI, migrate a production Home, replace a production
+Session or start a Web listener.
+
 ### 2.10.0 compatibility and migration notes
 
 This stable minor includes exact-turn inbox handling and successor recovery