@zq-silk/yui 0.16.1 → 1.0.0-alpha

package/dist/commands/taskUpstreamCommands.js

@@ -61,71 +61,110 @@ async function integrateUpstream(args, store, home, options) {
     }
     const service = new GitIntegrationService(store.rootDirectory(), store, git, now, options.environment, undefined, options.jobPort);
     const results = [];
-    for (const binding of task.projectBindings) {
-        if (projectRef !== undefined && binding.projectId !== projectRef)
-            continue;
-        const project = store.getProject(binding.projectId);
-        if (project === null)
-            throw usageError(`Project not found: ${binding.projectId}.`);
-        if (project.remoteUrl === undefined) {
-            throw usageError(`Project has no remote URL: ${project.id}.`);
-        }
-        if (binding.baseCommit === undefined || binding.currentCommit === undefined) {
-            throw usageError(`Task Project has no activated commit boundary: ${task.id}/${project.id}.`);
-        }
-        const entry = workspaceProjectEntry(workspace, project.id);
-        if (entry === undefined) {
-            throw usageError(`Task workspace has no entry for Project: ${project.id}.`);
-        }
-        const head = (await git.inspect(entry.path, entry.branch)).baseCommit;
-        if (head !== binding.currentCommit) {
-            throw usageError(`Task Project current commit diverged from its main clone: ${task.id}/${project.id}.`);
+    let failure;
+    const selected = task.projectBindings.filter(binding => projectRef === undefined || binding.projectId === projectRef);
+    if (projectRef !== undefined && selected.length === 0) {
+        throw usageError(`Task Project not found: ${task.id}/${projectRef}.`);
+    }
+    for (const binding of selected) {
+        let phase = "prepare";
+        let integrationId;
+        try {
+            const project = store.getProject(binding.projectId);
+            if (project === null)
+                throw usageError(`Project not found: ${binding.projectId}.`);
+            if (project.remoteUrl === undefined) {
+                throw usageError(`Project has no remote URL: ${project.id}.`);
+            }
+            if (binding.baseCommit === undefined || binding.currentCommit === undefined) {
+                throw usageError(`Task Project has no activated commit boundary: ${task.id}/${project.id}.`);
+            }
+            const entry = workspaceProjectEntry(workspace, project.id);
+            if (entry === undefined) {
+                throw usageError(`Task workspace has no entry for Project: ${project.id}.`);
+            }
+            const head = (await git.inspect(entry.path, entry.branch)).baseCommit;
+            if (head !== binding.currentCommit) {
+                throw usageError(`Task Project current commit diverged from its main clone: ${task.id}/${project.id}.`);
+            }
+            phase = "resolve-remote";
+            const remote = await git.resolveRemoteHead({
+                remoteUrl: project.remoteUrl,
+                branch: binding.baseRef
+            });
+            const attempt = store.transaction((tx) => {
+                const created = createIntegrationAttempt({
+                    id: tx.nextIntegrationAttemptId(task.id),
+                    taskId: task.id,
+                    projectId: project.id,
+                    targetRef: entry.branch,
+                    beforeCommit: binding.currentCommit,
+                    source: {
+                        kind: "upstream",
+                        branch: remote.branch,
+                        remoteCommit: remote.commit,
+                        taskBaseCommit: binding.baseCommit,
+                        strategy: "rebase"
+                    },
+                    checkCommands: parsed.many.get("--check") ?? [],
+                    rerunChecks: parsed.one.has("--rerun-checks")
+                }, now());
+                tx.saveIntegrationAttempt(task.id, created);
+                return created;
+            });
+            integrationId = attempt.id;
+            phase = "integrate";
+            const result = await service.integrate(task.id, attempt.id);
+            results.push(result);
+            // Each Project has an independent candidate and Job. --latest admits all
+            // requested Projects, then the Agent continues the returned exact attempts.
+            if (result.status !== "committed" && result.status !== "checks-running")
+                break;
         }
-        const remote = await git.resolveRemoteHead({
-            remoteUrl: project.remoteUrl,
-            branch: binding.baseRef
-        });
-        const attempt = store.transaction((tx) => {
-            const created = createIntegrationAttempt({
-                id: tx.nextIntegrationAttemptId(task.id),
-                taskId: task.id,
-                projectId: project.id,
-                targetRef: entry.branch,
-                beforeCommit: binding.currentCommit,
-                source: {
-                    kind: "upstream",
-                    branch: remote.branch,
-                    remoteCommit: remote.commit,
-                    taskBaseCommit: binding.baseCommit,
-                    strategy: "rebase"
-                },
-                checkCommands: parsed.many.get("--check") ?? [],
-                rerunChecks: parsed.one.has("--rerun-checks")
-            }, now());
-            tx.saveIntegrationAttempt(task.id, created);
-            return created;
-        });
-        const result = await service.integrate(task.id, attempt.id);
-        results.push(result);
-        // Each Project has an independent candidate and Job. --latest admits all
-        // requested Projects, then the Agent continues the returned exact attempts.
-        if (result.status !== "committed" && result.status !== "checks-running")
+        catch (error) {
+            // Earlier Projects may already have advanced HEAD or admitted a Job.
+            // Preserve those receipts and the exact uncertain attempt; never turn a
+            // partially executed batch into a usage error or replay it automatically.
+            failure = {
+                projectId: binding.projectId,
+                phase,
+                message: error instanceof Error ? error.message : String(error),
+                ...(integrationId === undefined ? {} : { integrationId }),
+                effect: integrationId === undefined ? "not-started" : "inspect-required"
+            };
             break;
+        }
     }
-    if (projectRef !== undefined && results.length === 0) {
-        throw usageError(`Task Project not found: ${task.id}/${projectRef}.`);
-    }
+    const attempted = new Set([
+        ...results.map(result => result.attempt.projectId),
+        ...(failure === undefined ? [] : [failure.projectId])
+    ]);
+    const remainingProjectIds = selected.map(binding => binding.projectId)
+        .filter(id => !attempted.has(id));
+    const stage = failure !== undefined
+        || results.some(result => result.status !== "committed" && result.status !== "checks-running")
+        ? "integration-blocked"
+        : results.some(result => result.status === "checks-running")
+            ? "checks-running" : "integrated";
     const lines = results.flatMap(result => {
         const { attempt, status } = result;
         return [
-            `  ${attempt.id} ${attempt.projectId}: ${attempt.beforeCommit.slice(0, 12)} -> ${(attempt.afterCommit ?? attempt.candidateCommit ?? attempt.beforeCommit).slice(0, 12)} (${status})`,
+            `  ${attempt.id} ${attempt.projectId}: ${status} (rebase)`,
+            `    Expected HEAD: ${attempt.beforeCommit}; committed HEAD: ${attempt.afterCommit ?? "not committed"}`,
+            `    Candidate: ${attempt.candidateCommit ?? "not prepared"}`,
             ...(status === "checks-running" ? [
                 `    Job ${result.job.id}; continue with yui task integration continue ${task.id}/${attempt.id}`
             ] : [])
         ];
     });
     return {
-        output: `Upstream Integration results for Task ${task.id}:\n${lines.join("\n")}\n`,
-        data: { taskId: task.id, integrations: results }
+        output: `Upstream Integration results for Task ${task.id} (${stage}):\n${lines.join("\n")}\n`
+            + (failure === undefined ? "" : (`  ${failure.projectId} stopped during ${failure.phase}: ${failure.message}\n`
+                + (failure.integrationId === undefined
+                    ? "  No Integration was started for this Project.\n"
+                    : `  Inspect yui task integration show ${task.id}/${failure.integrationId}; effects require inspection, not batch replay.\n`)))
+            + (remainingProjectIds.length === 0 ? "" : `  Not attempted: ${remainingProjectIds.join(", ")}\n`),
+        data: { taskId: task.id, stage, strategy: "rebase", integrations: results,
+            remainingProjectIds, ...(failure === undefined ? {} : { failure }) }
     };
 }

package/dist/context/runContextPack.js

@@ -1,7 +1,8 @@
 import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
 import { TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT } from "../task/publicationReference.js";
-import { RUN_INPUT_MAX_DELTAS } from "./runInputContract.js";
+import { RUN_INPUT_MAX_DELTAS, requireRunContextSnapshotRef } from "./runInputContract.js";
+import { requireIdentity } from "../domain/validation.js";
 import { assertWorkItemDependenciesCompleted } from "../workItem/dependencyGate.js";
 import { governingWorkItemCandidate, workItemExecutionGroupById } from "../workItem/workItem.js";
 import { formatGitArtifactRef, validateGitArtifactRef } from "../artifacts/gitArtifactRef.js";
@@ -209,26 +210,14 @@ export function contextSnapshotDeltaRefIds(store, snapshot) {
 }
 export function buildRunContextPack(store, taskId, runId) {
     const run = requireExactRun(store, taskId, runId);
-    const current = collectAuthorizedContext(store, run);
-    let pointers = current.map(({ ref }) => ref);
-    let snapshotRef;
-    if (run.inputs[0].input.contextSnapshotRef !== undefined) {
-        const expected = run.inputs[0].input.contextSnapshotRef;
-        const snapshot = store.getContextSnapshot(taskId, expected.id);
-        if (snapshot === null)
-            throw new Error(`AgentRun Context Snapshot is missing: ${expected.id}.`);
-        validateContextSnapshot(snapshot);
-        if (snapshot.digest !== expected.digest || snapshot.taskId !== taskId) {
-            throw new Error(`AgentRun Context Snapshot identity drifted: ${expected.id}.`);
-        }
-        pointers = snapshot.refs;
-        snapshotRef = contextSnapshotRef(snapshot);
-    }
+    const snapshot = readRunContextSnapshot(store, run);
+    const pointers = snapshot.refs;
     if (pointers.length > RUN_CONTEXT_PACK_MAX_REFS) {
         throw new Error(`AgentRun Context exceeds ${RUN_CONTEXT_PACK_MAX_REFS} authorized refs.`);
     }
     const view = contextView(run);
-    const writableProjectIds = writableProjects(store, run, view);
+    const writableProjectIds = run.effective.executionAuthority === "planning"
+        ? [] : run.effective.writeProjectIds;
     const summaries = pointers.map((ref) => Object.freeze({
         refId: ref.refId,
         store: ref.store,
@@ -246,7 +235,7 @@ export function buildRunContextPack(store, taskId, runId) {
             adapterId: run.effective.adapterId,
             workspace: run.effective.workspace.root
         }),
-        ...(snapshotRef === undefined ? {} : { snapshot: snapshotRef }),
+        snapshot: contextSnapshotRef(snapshot),
         input: run.inputs[0].input,
         authority: Object.freeze({ view, readableRefs: pointers, writableProjectIds }),
         pointers,
@@ -302,17 +291,15 @@ function readLiveTaskState(store, taskId) {
     });
 }
 export function expandRunContextRef(store, taskId, runId, refId, refStore) {
-    const pack = buildRunContextPack(store, taskId, runId);
-    const authorized = pack.pointers.filter((ref) => (ref.refId === refId && (refStore === undefined || ref.store === refStore)));
-    const selector = refStore === undefined ? refId : `${refStore}/${refId}`;
+    requireIdentity(refStore, "Context ref store");
+    const run = requireExactRun(store, taskId, runId);
+    const snapshot = readRunContextSnapshot(store, run);
+    const authorized = snapshot.refs.filter((ref) => (ref.refId === refId && ref.store === refStore));
+    const selector = `${refStore}/${refId}`;
     if (authorized.length !== 1) {
         throw new Error(`AgentRun Context ref is not uniquely authorized: ${selector}.`);
     }
-    const run = requireExactRun(store, taskId, runId);
-    const snapshotRef = run.inputs[0].input.contextSnapshotRef;
-    const materialized = snapshotRef === undefined
-        ? collectAuthorizedContext(store, run).find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])))
-        : store.getContextSnapshot(taskId, snapshotRef.id)?.resources.find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])));
+    const materialized = snapshot.resources.find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])));
     if (materialized === undefined || materialized.ref.digest !== authorized[0].digest) {
         throw new Error(`AgentRun Context ref is unavailable or drifted: ${selector}.`);
     }
@@ -329,15 +316,12 @@ export function expandRunContextRef(store, taskId, runId, refId, refStore) {
 /** Fail-closed delta cursor resolution for one immutable AgentRun lineage. */
 export function buildRunContextDelta(store, taskId, runId, after) {
     const pack = buildRunContextPack(store, taskId, runId);
-    if (after === pack.digest || after === pack.snapshot?.digest) {
+    if (after === pack.digest || after === pack.snapshot.digest) {
         return Object.freeze({ schemaVersion: 1, after, cursor: pack.digest, refs: [] });
     }
     const run = requireExactRun(store, taskId, runId);
-    const snapshotRef = run.inputs[0].input.contextSnapshotRef;
-    const snapshot = snapshotRef === undefined
-        ? null
-        : store.getContextSnapshot(taskId, snapshotRef.id);
-    const parentDigest = snapshot?.parentRef?.digest;
+    const snapshot = readRunContextSnapshot(store, run);
+    const parentDigest = snapshot.parentRef?.digest;
     if (!((parentDigest !== undefined && after === parentDigest)
         || (parentDigest === undefined && after === "none"))) {
         throw new Error("AgentRun Context delta cursor is outside the frozen Snapshot lineage.");
@@ -356,6 +340,19 @@ function requireExactRun(store, taskId, runId) {
     }
     return run;
 }
+export function readRunContextSnapshot(store, run) {
+    const expected = requireRunContextSnapshotRef(run.inputs[0].input);
+    const snapshot = store.getContextSnapshot(run.taskId, expected.id);
+    if (snapshot === null)
+        throw new Error(`AgentRun Context Snapshot is missing: ${expected.id}.`);
+    if (snapshot.id !== expected.id || snapshot.taskId !== run.taskId
+        || expected.taskId !== run.taskId || snapshot.digest !== expected.digest
+        || snapshot.sequence !== expected.sequence || snapshot.scope !== expected.scope
+        || snapshot.scopeRef !== expected.scopeRef) {
+        throw new Error(`AgentRun Context Snapshot identity drifted: ${expected.id}.`);
+    }
+    return validateContextSnapshot(snapshot);
+}
 function collectAuthorizedContext(store, run) {
     const task = store.getTask(run.taskId);
     if (task === null)
@@ -575,16 +572,7 @@ function collectSourceRunContext(store, run, sourceRunIds) {
 }
 /** The frozen refs, not the Group's changing lane state, define provenance. */
 export function synthesisSourceRunIds(store, run) {
-    const ref = run.inputs[0].input.contextSnapshotRef;
-    if (ref === undefined)
-        throw new Error(`Synthesis AgentRun has no Context Snapshot: ${run.id}.`);
-    const snapshot = store.getContextSnapshot(run.taskId, ref.id);
-    if (snapshot === null || snapshot.digest !== ref.digest
-        || snapshot.sequence !== ref.sequence || snapshot.scope !== ref.scope
-        || snapshot.scopeRef !== ref.scopeRef || snapshot.taskId !== run.taskId) {
-        throw new Error(`Synthesis Context Snapshot is missing or drifted: ${ref.id}.`);
-    }
-    validateContextSnapshot(snapshot);
+    const snapshot = readRunContextSnapshot(store, run);
     return snapshot.resources.filter(({ ref: entry, value }) => (entry.store === "source-run"
         && value.executionGroupId === run.sourceExecutionGroupId)).map(({ ref: entry }) => entry.refId);
 }
@@ -621,18 +609,6 @@ function contextView(run) {
         return "operator";
     return "worker";
 }
-function writableProjects(store, run, view) {
-    if (run.effective.executionAuthority === "planning")
-        return Object.freeze([]);
-    if (view === "leader")
-        return Object.freeze(store.getTask(run.taskId)?.projectBindings.map(({ projectId }) => projectId) ?? []);
-    if (view === "reviewer") {
-        return Object.freeze(run.workspace?.entries.filter(({ access }) => access === "write").map(({ projectId }) => projectId) ?? []);
-    }
-    if (run.workItemId === undefined)
-        return Object.freeze([]);
-    return Object.freeze(store.getWorkItem(run.taskId, run.workItemId)?.writeProjectIds ?? []);
-}
 function completionActions(view, authority) {
     if (authority === "planning")
         return Object.freeze(["finish-turn", "request-input", "request-activation"]);

package/dist/context/runInputContract.js

@@ -33,6 +33,13 @@ export function validateRunInput(value) {
     }
     return value;
 }
+/** Execution must never substitute current Task facts for missing frozen evidence. */
+export function requireRunContextSnapshotRef(input) {
+    if (input.contextSnapshotRef === undefined) {
+        throw new Error("AgentRun Context Snapshot is required for this execution. Inspect the Run and retire or explicitly retry it; original evidence is never reconstructed.");
+    }
+    return validateContextSnapshotRef(input.contextSnapshotRef);
+}
 export function createRunInputEnvelope(context, input) {
     validateRunInput(input);
     const normalized = normalizeEnvelopeContext(context, input);
@@ -65,6 +72,8 @@ export function serializeRunInputEnvelope(value) {
         throw new Error("AgentRun input protocol is unsupported.");
     }
     const normalized = normalizeEnvelope(value);
+    if (normalized.purpose !== "global")
+        requireRunContextSnapshotRef(normalized);
     const subject = Object.entries(normalized.subject)
         .map(([key, id]) => `${key}:${id}`)
         .join(",");

package/dist/context/sessionBootstrapManifest.js

@@ -4,7 +4,6 @@ import { dirname, join, resolve } from "node:path";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
-const ordinarySessionCli = ["#!/bin/sh", "exec yui \"$@\"", ""].join("\n");
 /** Portable read pointers accompany every managed input, including the first
  * notification on a fresh Session. No Task content or credentials are copied. */
 export function withSessionContextPointer(text, environment) {
@@ -24,9 +23,8 @@ export function withSessionContextPointer(text, environment) {
 /**
  * A managed Session wrapper answers exactly one question: which installation
  * runs this command. It therefore carries only the resolved entry point, never
- * a package or build identity. Version identity changes on every release while
- * a Session legitimately outlives it, so embedding it here would turn an
- * ordinary update into a broken Session.
+ * a package or build identity. Current Sessions may survive a compatible
+ * installation relocation; this is not a cross-version runtime adapter.
  */
 function renderSessionCli(entryPoint) {
     return [
@@ -108,8 +106,8 @@ export function materializeSessionBootstrap(input) {
     // Provider command runners may rebuild PATH independently of the managed
     // process environment, so a bare `yui` could resolve to another install or
     // Home. The wrapper pins the resolved entry point instead. Package identity
-    // stays out of it: the compatible continuity preflight and the Session's
-    // caller key already authorize the command.
+    // stays out of it: current Session authority and the CLI/Controller protocol
+    // boundary authorize the command.
     const sessionCliContent = renderSessionCli(input.entryPoint);
     const sessionCliDigest = digest(sessionCliContent);
     const sessionCliPath = resolve(join(home, "runtime", "session-cli", `yui-${sessionCliDigest}.sh`));
@@ -185,11 +183,9 @@ function quoteShellWord(value) {
     return `'${value.replaceAll("'", "'\"'\"'")}'`;
 }
 /**
- * Retargets known managed wrappers to the current resolved control plane after
- * a compatible update. Only a valid Session Manifest may nominate a wrapper,
- * and only Yui's own two-line wrapper shapes are changed. A wrapper written by
- * an earlier release may still pin a control-plane digest; retargeting it here
- * is what removes that stale pin from a live Home.
+ * Retargets current managed wrappers to the resolved installation entry point.
+ * Only a valid Session Manifest may nominate a wrapper, and only the exact
+ * two-argument shell form generated here is changed.
  */
 export function refreshManagedSessionCliWrappers(homeInput, entryPoint) {
     const home = resolve(homeInput);
@@ -217,8 +213,7 @@ export function refreshManagedSessionCliWrappers(homeInput, entryPoint) {
             wrapperPaths.add(wrapperPath);
         }
         catch {
-            // Historical or incomplete manifests are audit material. They must not
-            // block current Sessions or an otherwise compatible package update.
+            // An invalid Manifest cannot nominate a wrapper for mutation.
             skipped += 1;
         }
     }
@@ -234,7 +229,7 @@ export function refreshManagedSessionCliWrappers(homeInput, entryPoint) {
             current += 1;
             continue;
         }
-        if (content !== ordinarySessionCli && !isManagedSessionCli(content)) {
+        if (!isManagedSessionCli(content)) {
             skipped += 1;
             continue;
         }
@@ -244,12 +239,9 @@ export function refreshManagedSessionCliWrappers(homeInput, entryPoint) {
     }
     return Object.freeze({ refreshed, current, skipped });
 }
-/**
- * Both wrapper shapes Yui has written: the current entry-point-only form and
- * the earlier form that also pinned a control-plane digest.
- */
+/** Match exactly the two shell-quoted words emitted by renderSessionCli. */
 function isManagedSessionCli(content) {
-    return /^#!\/bin\/sh\nexec [^\n]+(?: '--yui-control' '[a-f0-9]{64}')? "\$@"\n$/u.test(content);
+    return /^#!\/bin\/sh\nexec '(?:[^'\n]|'"'"')*' '(?:[^'\n]|'"'"')*' "\$@"\n$/u.test(content);
 }
 function writeImmutableText(path, content) {
     writeTextFileAtomically(path, content);

package/dist/controller/agentHostObservation.js

@@ -16,7 +16,7 @@ export function resolveAgentHostObservation(store, event) {
         "conversation.observed", "goal.updated", "goal.cleared",
         "turn.accepted", "turn.completed", "turn.failed", "turn.cancelled",
         "input.accepted", "input.rejected", "input.delivery-unknown",
-        "operation.started", "operation.completed", "operation.failed", "activity.observed"
+        "operation.started", "operation.completed", "operation.failed", "activity.observed", "observer.health"
     ];
     if (!hostKinds.includes(kind)
         || (kind === "host.observed" ? input.authority !== "host"
@@ -44,7 +44,9 @@ export function resolveAgentHostObservation(store, event) {
     const directStart = kind === "turn.accepted" && fence.receiptId === `direct:${fence.nativeTurnId}`;
     const additionalInput = kind.startsWith("input.") && (fence.receiptId?.startsWith("native-input:") || fence.receiptId?.startsWith("turn-input:")
         || fence.receiptId?.startsWith("steer:"));
-    const terminal = ["turn.completed", "turn.failed", "turn.cancelled", "session.ended", "session.failed"].includes(kind);
+    // Post-execution diagnostics may describe an already-terminal exact input.
+    // This permits evidence collection, never a terminal transition.
+    const terminal = ["turn.completed", "turn.failed", "turn.cancelled", "session.ended", "session.failed", "observer.health"].includes(kind);
     if (fence.taskId === undefined) {
         if (host.startupRunId !== undefined)
             throw new RuntimeHookRunFenceError("Global Host cannot carry a startup Run.");

package/dist/controller/agentRuntimeObserver.js

@@ -102,7 +102,7 @@ export class AgentRuntimeObserver {
                         ? tokenObservationIdentity("baseline", fence, source.sourceId, baselineKey)
                         : usageObservationIdentity(fence, source.sourceId, latestOccurrence);
                     this.inbox.enqueueObservation(createRuntimeObservation({
-                        schemaVersion: 4,
+                        schemaVersion: 1,
                         eventId: identity.eventId,
                         semanticKey: identity.semanticKey,
                         kind: "activity.observed",
@@ -137,7 +137,7 @@ export class AgentRuntimeObserver {
             const health = JSON.stringify([sample.status, sample.detail ?? null]);
             if (state.health !== health) {
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 4,
+                    schemaVersion: 1,
                     eventId: observationId("health", fence, source.sourceId, health),
                     semanticKey: observationId("health", fence, source.sourceId, health),
                     kind: "observer.health",
@@ -183,7 +183,7 @@ export class AgentRuntimeObserver {
             usages.forEach((occurrence, usageIndex) => {
                 const identity = usageObservationIdentity(fence, source.sourceId, occurrence);
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 4,
+                    schemaVersion: 1,
                     eventId: identity.eventId,
                     semanticKey: identity.semanticKey,
                     kind: "activity.observed",
@@ -213,7 +213,7 @@ export class AgentRuntimeObserver {
             });
             if (activityChanged && state.cursor !== undefined) {
                 this.inbox.enqueueObservation(createRuntimeObservation({
-                    schemaVersion: 4,
+                    schemaVersion: 1,
                     eventId: observationId("activity", fence, source.sourceId, sample.activityId),
                     semanticKey: observationId("activity", fence, source.sourceId, sample.activityId),
                     kind: "activity.observed",

package/dist/controller/clientRuntime.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { findLiveControllerProcessForHome, inspectLiveControllerProcess } from "../core/controllerProcessIdentity.js";
 import { readHomeFilesystemId } from "../core/homeFilesystemIdentity.js";
+import { parseControllerIdentity } from "../core/controllerIdentity.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
 import { callController, ControllerClientError, readControllerDiscovery, stopOrphanedFileTaskController } from "../core/controllerClient.js";
 import { FILE_TASK_CONTROLLER_PROTOCOL_VERSION } from "../core/protocol.js";
@@ -53,7 +54,7 @@ export async function ensureFileTaskController(home, options = {}) {
     await waitForForeignHandover(home, options);
     try {
         const status = await call(home, "controller.status", {});
-        assertCompatibleControllerStatus(status, options.expectedVersion);
+        assertCompatibleControllerStatus(status, options.expectedIdentity);
         return status;
     }
     catch (error) {
@@ -78,7 +79,7 @@ export async function ensureFileTaskController(home, options = {}) {
     for (;;) {
         try {
             const status = await call(home, "controller.status", {});
-            assertCompatibleControllerStatus(status, options.expectedVersion);
+            assertCompatibleControllerStatus(status, options.expectedIdentity);
             return status;
         }
         catch (error) {
@@ -95,10 +96,10 @@ export async function ensureFileTaskController(home, options = {}) {
 }
 /** Start and await readiness for a captured Controller identity. */
 export async function ensureFileTaskControllerIdentity(home, identity, options = {}) {
-    assertExpectedControllerRuntimeProcessIdentity(identity);
+    const captured = parseControllerIdentity(identity);
     const status = await ensureFileTaskController(home, {
         ...options,
-        expectedVersion: identity.version
+        expectedIdentity: captured
     });
     // A same-version status is not an identity proof: another Controller binary
     // may own the Home after a restart or a stale discovery race. Authenticate
@@ -109,39 +110,24 @@ export async function ensureFileTaskControllerIdentity(home, identity, options =
     const actual = await call(home, "controller.identity", {}, {
         timeoutMs: options.requestTimeoutMs
     });
-    assertControllerRuntimeProcessIdentity(actual, identity);
+    assertControllerRuntimeProcessIdentity(actual, captured);
     return status;
 }
-function assertExpectedControllerRuntimeProcessIdentity(identity) {
-    if (typeof identity.executablePath !== "string"
-        || identity.executablePath.length === 0
-        || !Array.isArray(identity.args)
-        || identity.args.some((arg) => typeof arg !== "string")
-        || typeof identity.version !== "string"
-        || identity.version.length === 0) {
-        throw new Error("Expected Controller runtime identity is malformed; refusing to start or accept a Controller.");
-    }
-}
-function assertControllerRuntimeProcessIdentity(actual, expected) {
-    if (!isJsonRecord(actual)) {
-        throw new Error("Authenticated Controller runtime identity is malformed; refusing to accept readiness.");
-    }
+function assertControllerRuntimeProcessIdentity(value, expected) {
+    const actual = parseControllerIdentity(value);
     const actualArgs = actual.args;
-    if (typeof actual.executablePath !== "string"
-        || !Array.isArray(actualArgs)
-        || actualArgs.some((arg) => typeof arg !== "string")
-        || typeof actual.version !== "string") {
-        throw new Error("Authenticated Controller runtime identity is malformed; refusing to accept readiness.");
-    }
     const argsMatch = actualArgs.length === expected.args.length
         && actualArgs.every((arg, index) => arg === expected.args[index]);
     if (actual.executablePath !== expected.executablePath
         || !argsMatch
-        || actual.version !== expected.version) {
-        throw new Error("Authenticated Controller runtime identity does not match the captured executable, argv, and version; refusing readiness.");
+        || actual.version !== expected.version
+        || actual.controllerProtocolVersion !== expected.controllerProtocolVersion
+        || actual.storageVersion !== expected.storageVersion
+        || actual.minimumStorageVersion !== expected.minimumStorageVersion) {
+        throw new Error("Authenticated Controller runtime identity does not match the captured executable, argv, package, protocol and storage versions; refusing readiness.");
     }
 }
-function assertCompatibleControllerStatus(status, expectedVersion) {
+function assertCompatibleControllerStatus(status, expectedIdentity) {
     const statusRecord = isJsonRecord(status) && status.running === true ? status : null;
     const actual = statusRecord?.protocolVersion;
     if (statusRecord === null || actual !== FILE_TASK_CONTROLLER_PROTOCOL_VERSION) {
@@ -149,22 +135,11 @@ function assertCompatibleControllerStatus(status, expectedVersion) {
             + "Run `yui controller restart` before writing new task records.");
     }
     const actualVersion = statusRecord.version;
-    if (expectedVersion !== undefined && actualVersion !== expectedVersion) {
-        throw new Error(`Controller version is incompatible (expected ${expectedVersion}, found ${typeof actualVersion === "string" ? actualVersion : "unknown"}). `
-            + "Run `yui controller restart` before writing new task records.");
-    }
-    // Ordinary callers must authenticate the complete control-plane identity.
-    // An update/upgrade restore instead targets a previously captured Controller
-    // binary, which may predate the current storage-layout status fields; that
-    // path authenticates its executable, argv, and version immediately after
-    // readiness in ensureFileTaskControllerIdentity.
-    if (expectedVersion === undefined) {
-        const identity = yuiVersionIdentity();
-        assertControllerStatusIdentity(status, {
-            ...identity,
-            version: typeof actualVersion === "string" ? actualVersion : identity.version
-        });
-    }
+    const current = yuiVersionIdentity();
+    assertControllerStatusIdentity(status, expectedIdentity === undefined ? {
+        ...current,
+        version: typeof actualVersion === "string" ? actualVersion : current.version
+    } : parseControllerIdentity(expectedIdentity));
 }
 function spawnDetachedFileTaskController(_home, environment) {
     const child = spawn(process.execPath, [fileURLToPath(new URL("./controllerMain.js", import.meta.url))], {