@zq-silk/yui 0.16.1 → 1.0.0-alpha

package/dist/repository/taskWorkspacePreparer.js

@@ -545,7 +545,7 @@ export class FileTaskWorkspacePreparer {
         const taskSegment = taskWorkspaceRefSegment(workspaceIdentity === undefined ? task : { ...task, workspaceIdentity });
         const root = this.#taskWorkspaceRoot(task.id);
         const prepared = [];
-        const createdClonePaths = new Set();
+        const createdClones = [];
         const baselines = new Map();
         try {
             // Resolve every remote baseline before creating any Task clone. A later
@@ -595,7 +595,14 @@ export class FileTaskWorkspacePreparer {
                     })
                     : await this.git.inspect(previous.path, "HEAD");
                 if (previous === undefined)
-                    createdClonePaths.add(physical.root);
+                    createdClones.push({
+                        project,
+                        entry: {
+                            projectId: project.id, directory: binding.directory, access: "write",
+                            path: destination, branch: identity.branch,
+                            baseRef: baseline.recordedBaseRef, baseCommit: physical.baseCommit
+                        }
+                    });
                 const physicalBranch = await this.git.headRef(physical.root);
                 if (physical.root !== (previous?.path ?? destination)
                     || physicalBranch !== (previous?.branch ?? identity.branch)) {
@@ -794,16 +801,7 @@ export class FileTaskWorkspacePreparer {
             // A failed or conflicted preparation owns no durable record: drop the
             // branches too, so a retry mints a clean identity without half-created
             // refs behind. Adopted (already catalogued) worktrees are never touched.
-            await this.#discardUnadoptedEntries(task, taskSegment, prepared, MAIN_WORKTREE, true);
-            const recorded = new Set(prepared.map(({ entry }) => entry.path));
-            for (const path of createdClonePaths) {
-                if (recorded.has(path))
-                    continue;
-                const removal = await this.git.removeStrandedWorktree(path);
-                if (removal === "dirty") {
-                    throw new Error(`Unadopted Task clone is dirty and was retained at ${path}; inspect it and retry.`);
-                }
-            }
+            await this.#discardUnadoptedEntries(task, taskSegment, createdClones, MAIN_WORKTREE, true, undefined, error);
             if (activate)
                 await removeWorkspaceView(root);
             throw error;
@@ -1125,7 +1123,7 @@ export class FileTaskWorkspacePreparer {
                 });
             }
             catch (error) {
-                await this.#discardUnadoptedEntries(lockedTask, taskSegment, prepared, item.id);
+                await this.#discardUnadoptedEntries(lockedTask, taskSegment, prepared, item.id, false, undefined, error);
                 throw error;
             }
         }
@@ -1276,7 +1274,7 @@ export class FileTaskWorkspacePreparer {
                 return workspace;
             }
             catch (error) {
-                await this.#discardUnadoptedEntries(lockedTask, taskSegment, prepared, managedWorktreeName(owner), true);
+                await this.#discardUnadoptedEntries(lockedTask, taskSegment, prepared, managedWorktreeName(owner), true, undefined, error);
                 throw error;
             }
         }
@@ -1354,48 +1352,39 @@ export class FileTaskWorkspacePreparer {
             return "missing";
         const task = requireTask(this.store, workspace.owner.taskId);
         const taskSegment = this.#taskSegment(task);
+        const root = this.#executionLaneWorkspaceRoot(task.id, workspace.owner.executionGroupId, workspace.owner.executionLaneId);
+        if (workspace.root !== root)
+            throw new Error("Unadopted Lane root does not match its managed owner.");
         const writable = workspace.entries.filter(({ access }) => access === "write");
-        let state;
+        const completed = [];
+        let target = root;
         try {
-            state = await this.#inspectEntries(task.id, taskSegment, managedWorktreeName(workspace.owner), writable);
-        }
-        catch (error) {
-            // A `project migrate` between preparation and compensation switches the
-            // catalog, so the worktree's common-dir no longer matches the Project's
-            // current repository. Fall back to removing the stranded worktree
-            // through its own Git identity.
-            if (!(error instanceof Error && error.message.includes("belongs to another project"))) {
-                throw error;
-            }
-            let removed = false;
+            // This owner was never adopted. Its captured identity is sufficient to
+            // inspect its own Git; no catalog-error matching or filesystem fallback.
             for (const entry of writable) {
-                const result = await this.git.removeStrandedWorktree(entry.path);
-                if (result === "dirty")
-                    return "dirty";
-                removed ||= result === "removed";
+                target = entry.path;
+                const result = await this.git.removeStrandedWorktree(entry.path, {
+                    container: root, directory: entry.directory, taskSegment,
+                    roleName: managedWorktreeName(workspace.owner), expectedCommit: entry.baseCommit,
+                    deleteBranch: true
+                });
+                if (result === "dirty") {
+                    if (completed.length === 0)
+                        return "dirty";
+                    throw new Error(`Unadopted Lane is dirty and retained at ${entry.path}.`);
+                }
+                completed.push({ path: entry.path, result });
             }
-            await removeWorkspaceView(workspace.root);
-            return removed ? "removed" : "missing";
+            target = root;
+            await removeWorkspaceView(root);
+            return completed.some(({ result }) => result === "removed") ? "removed" : "missing";
         }
-        if (state === "dirty")
-            return "dirty";
-        let removed = false;
-        for (const entry of writable) {
-            const project = requireProject(this.store, entry.projectId);
-            const result = await this.git.removeWorktree({
-                repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: dirname(entry.path),
-                directory: entry.directory,
-                taskSegment,
-                roleName: managedWorktreeName(workspace.owner),
-                deleteBranch: true
-            });
-            if (result === "dirty")
-                return "dirty";
-            removed ||= result === "removed";
+        catch (error) {
+            const result = { completed, failedPath: target,
+                remaining: writable.map(({ path }) => path).filter(path => !completed.some(done => done.path === path)) };
+            throw Object.assign(new Error(`Unadopted Lane cleanup failed: ${errorText(error)}. Effects: ${JSON.stringify(result)}. `
+                + "Failed-command effects are unknown; inspect the exact target before continuing.", { cause: error }), { result });
         }
-        await removeWorkspaceView(workspace.root);
-        return removed ? "removed" : "missing";
     }
     async cleanupExecutionLaneWorkspacesForWorkItem(taskId, workItemId) {
         let result = "missing";
@@ -1754,7 +1743,7 @@ export class FileTaskWorkspacePreparer {
                 });
             }
             catch (error) {
-                await this.#discardUnadoptedEntries(task, taskSegment, prepared, this.#reviewWorktreeName(round), existing === null, new Set([...retained.values()].map(({ entry }) => entry.path)));
+                await this.#discardUnadoptedEntries(task, taskSegment, prepared, this.#reviewWorktreeName(round), existing === null, new Set([...retained.values()].map(({ entry }) => entry.path)), error);
                 throw error;
             }
         }
@@ -2243,28 +2232,43 @@ export class FileTaskWorkspacePreparer {
         return this.store.getConfig().defaultWorkspace ?? process.cwd();
     }
     async #discardUnadoptedEntries(task, taskSegment, prepared, roleName, deleteBranch = false, adoptedPaths = new Set(this.store.listManagedWorkspaces(task.id)
-        .flatMap((workspace) => workspace.entries.map(({ path }) => path)))) {
-        for (const { project, entry } of prepared.filter(({ entry }) => entry.access === "write" && !adoptedPaths.has(entry.path))) {
-            if (roleName === MAIN_WORKTREE) {
-                const removal = await this.git.removeStrandedWorktree(entry.path);
+        .flatMap((workspace) => workspace.entries.map(({ path }) => path))), originalError) {
+        const candidates = prepared.filter(({ entry }) => entry.access === "write" && !adoptedPaths.has(entry.path));
+        const completed = [];
+        for (const { project, entry } of candidates) {
+            try {
+                const removal = roleName === MAIN_WORKTREE
+                    ? await this.git.removeTaskClone({
+                        path: entry.path, container: this.#taskWorkspaceRoot(task.id),
+                        directory: entry.directory, taskSegment, branch: entry.branch,
+                        expectedCommit: entry.baseCommit
+                    })
+                    : await this.git.removeWorktree({
+                        repositoryPath: this.#taskRepositoryPath(task.id, project.id),
+                        container: dirname(entry.path),
+                        directory: entry.directory,
+                        taskSegment,
+                        roleName,
+                        ...(deleteBranch ? { deleteBranch: true } : {})
+                    });
                 if (removal === "dirty") {
-                    throw new Error(`Unadopted Task clone is dirty and was retained at ${entry.path}; inspect it and retry.`);
+                    throw new Error(`Unadopted workspace is dirty and was retained at ${entry.path}.`);
                 }
+                completed.push({ path: entry.path, result: removal });
                 this.#resourceRegistrar().markPathsDeleted([entry.path]);
-                continue;
             }
-            const removal = await this.git.removeWorktree({
-                repositoryPath: this.#taskRepositoryPath(task.id, project.id),
-                container: dirname(entry.path),
-                directory: entry.directory,
-                taskSegment,
-                roleName,
-                ...(deleteBranch ? { deleteBranch: true } : {})
-            });
-            if (removal === "dirty") {
-                throw new Error(`Unadopted managed worktree is dirty and was retained at ${entry.path}; inspect it and retry.`);
+            catch (cleanupError) {
+                const remaining = candidates.map(({ entry }) => entry.path)
+                    .filter(path => !completed.some(done => done.path === path));
+                const result = { completed, failedPath: entry.path, remaining };
+                throw Object.assign(new AggregateError([originalError, cleanupError], `Workspace preparation failed: ${errorText(originalError)}. Compensation failed: ${errorText(cleanupError)}. `
+                    + `Effects: ${JSON.stringify(result)}. Remaining paths may be partially changed; inspect before retrying.`), { result });
             }
-            this.#resourceRegistrar().markPathsDeleted([entry.path]);
+        }
+        if (originalError instanceof Error && completed.length > 0) {
+            // Preserve the original error class (notably a safe CAS retry), while
+            // making completed compensation visible to the caller's existing report.
+            originalError.message += ` Workspace compensation: ${JSON.stringify(completed)}.`;
         }
     }
     #taskRepositoryPath(taskId, projectId) {
@@ -2653,3 +2657,6 @@ function errorCode(error) {
         ? String(error.code)
         : undefined;
 }
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/resources/liveReferences.js

@@ -91,7 +91,7 @@ export async function scanLiveReferences(input) {
     diagnostics.push(...tmuxResult.diagnostics);
     // 3. Controller discovery: a running Controller protects only its own
     //    discovery record. Its cwd and open files are covered by the /proc
-    //    scan above, so a live Controller does not blanket-protect legacy
+    //    scan above, so a live Controller does not blanket-protect unattributed
     //    deployments and worktrees that no descriptor references — automatic
     //    GC (which runs inside the Controller) would otherwise be a no-op.
     const discovery = readControllerDiscovery(home);

package/dist/resources/resourceRegistry.js

@@ -43,7 +43,7 @@ export function listResourceRecords(state) {
     return Object.values(state.records);
 }
 export function parseResourceRegistryState(value) {
-    if (typeof value !== "object" || value === null) {
+    if (!isRecord(value)) {
         throw new Error("Resource registry root is not an object.");
     }
     const record = value;
@@ -51,15 +51,12 @@ export function parseResourceRegistryState(value) {
         throw new Error(`Resource registry schemaVersion is ${String(record.schemaVersion)}; `
             + `expected ${RESOURCE_REGISTRY_SCHEMA_VERSION}.`);
     }
-    if (typeof record.records !== "object" || record.records === null) {
+    if (!isRecord(record.records)) {
         throw new Error("Resource registry records is not an object.");
     }
     const records = {};
     for (const [key, entry] of Object.entries(record.records)) {
-        const parsed = parseResourceRecord(entry);
-        if (parsed === undefined) {
-            throw new Error(`Resource registry record ${key} is malformed.`);
-        }
+        const parsed = parseResourceRecord(entry, key);
         if (parsed.id !== key) {
             throw new Error(`Resource registry record key ${key} does not match id ${parsed.id}.`);
         }
@@ -70,47 +67,96 @@ export function parseResourceRegistryState(value) {
         records: Object.freeze(records)
     });
 }
-function parseResourceRecord(value) {
-    if (typeof value !== "object" || value === null)
-        return undefined;
-    const record = value;
+function parseResourceRecord(value, key) {
+    const invalid = (field) => {
+        throw new Error(`Resource registry record ${key} is malformed at ${field}; stored evidence was not repaired.`);
+    };
+    const object = (value, field) => isRecord(value) ? value : invalid(field);
+    const text = (value, field) => {
+        if (typeof value !== "string" || value.trim().length === 0)
+            invalid(field);
+    };
+    const timestamp = (value, field) => {
+        text(value, field);
+        if (!Number.isFinite(Date.parse(value)))
+            invalid(field);
+    };
+    const member = (value, choices, field) => {
+        if (typeof value !== "string" || !choices.includes(value))
+            invalid(field);
+    };
+    const optionalText = (record, fields, prefix = "") => {
+        for (const field of fields) {
+            if (record[field] !== undefined)
+                text(record[field], `${prefix}${field}`);
+        }
+    };
+    const record = object(value, "record");
     if (record.schemaVersion !== RESOURCE_REGISTRY_SCHEMA_VERSION)
-        return undefined;
-    if (typeof record.id !== "string" || typeof record.kind !== "string"
-        || typeof record.path !== "string" || typeof record.disposition !== "string"
-        || typeof record.updatedAt !== "string") {
-        return undefined;
+        invalid("schemaVersion");
+    text(record.id, "id");
+    text(record.path, "path");
+    timestamp(record.updatedAt, "updatedAt");
+    member(record.kind, ["worktree", "deployment", "runtime-artifact"], "kind");
+    member(record.disposition, ["active", "releasable", "quarantined", "deleted",
+        "retained-dirty", "retained-unowned", "retained-unproven", "cleanup-failed"], "disposition");
+    member(record.cleanliness, ["clean", "dirty", "unknown", "n/a"], "cleanliness");
+    if (!Array.isArray(record.activeRefs))
+        invalid("activeRefs");
+    record.activeRefs.forEach((ref, index) => text(ref, `activeRefs[${index}]`));
+    const owner = object(record.owner, "owner");
+    text(owner.home, "owner.home");
+    member(owner.basis, ["durable-record", "marker", "descriptor", "naming-convention", "unattributed"], "owner.basis");
+    optionalText(owner, ["projectId", "taskId", "workItemId", "reviewRoundId", "integrationAttemptId"], "owner.");
+    for (const field of ["createdAt", "lastReferencedAt"]) {
+        if (record[field] !== undefined)
+            timestamp(record[field], field);
     }
-    if (!Number.isFinite(Date.parse(record.updatedAt)))
-        return undefined;
-    if (typeof record.owner !== "object" || record.owner === null)
-        return undefined;
-    const owner = record.owner;
-    if (typeof owner.home !== "string" || typeof owner.basis !== "string") {
-        return undefined;
+    if (record.sizeBytes !== undefined
+        && (typeof record.sizeBytes !== "number" || !Number.isFinite(record.sizeBytes) || record.sizeBytes < 0)) {
+        invalid("sizeBytes");
     }
+    if (record.blocker !== undefined && typeof record.blocker !== "string")
+        invalid("blocker");
+    if (record.git !== undefined) {
+        const git = object(record.git, "git");
+        text(git.repositoryPath, "git.repositoryPath");
+        optionalText(git, ["commonDir", "branch", "head"], "git.");
+    }
+    if (record.quarantine !== undefined) {
+        const quarantine = object(record.quarantine, "quarantine");
+        text(quarantine.path, "quarantine.path");
+        text(quarantine.originalPath, "quarantine.originalPath");
+        timestamp(quarantine.movedAt, "quarantine.movedAt");
+        member(quarantine.method, ["move", "git-worktree-remove"], "quarantine.method");
+        if (quarantine.gitRestore !== undefined) {
+            const restore = object(quarantine.gitRestore, "quarantine.gitRestore");
+            text(restore.repositoryPath, "quarantine.gitRestore.repositoryPath");
+            optionalText(restore, ["branch", "head"], "quarantine.gitRestore.");
+        }
+    }
+    if (record.cleanupReceipt !== undefined) {
+        const receipt = object(record.cleanupReceipt, "cleanupReceipt");
+        timestamp(receipt.removedAt, "cleanupReceipt.removedAt");
+        member(receipt.method, ["git-worktree-remove", "quarantine-purge", "runtime-cleanup"], "cleanupReceipt.method");
+    }
+    // Validation enforces the existing persisted contract, without defaults,
+    // filtering, or a second historical reader. Constructors own new values.
+    const parsed = record;
     return Object.freeze({
-        schemaVersion: RESOURCE_REGISTRY_SCHEMA_VERSION,
-        id: record.id,
-        kind: record.kind,
-        path: record.path,
-        owner: Object.freeze({ ...owner }),
-        ...(record.git === undefined ? {} : { git: record.git }),
-        ...(typeof record.createdAt === "string" ? { createdAt: record.createdAt } : {}),
-        ...(typeof record.lastReferencedAt === "string"
-            ? { lastReferencedAt: record.lastReferencedAt }
-            : {}),
-        ...(typeof record.sizeBytes === "number" ? { sizeBytes: record.sizeBytes } : {}),
-        cleanliness: (record.cleanliness ?? "unknown"),
-        activeRefs: Array.isArray(record.activeRefs)
-            ? Object.freeze(record.activeRefs.filter((ref) => typeof ref === "string"))
-            : Object.freeze([]),
-        disposition: record.disposition,
-        ...(typeof record.blocker === "string" ? { blocker: record.blocker } : {}),
-        ...(record.quarantine === undefined ? {} : { quarantine: record.quarantine }),
-        ...(record.cleanupReceipt === undefined
-            ? {}
-            : { cleanupReceipt: record.cleanupReceipt }),
-        updatedAt: record.updatedAt
+        ...parsed,
+        owner: Object.freeze({ ...parsed.owner }),
+        activeRefs: Object.freeze([...parsed.activeRefs]),
+        ...(parsed.git === undefined ? {} : { git: Object.freeze({ ...parsed.git }) }),
+        ...(parsed.quarantine === undefined ? {} : { quarantine: Object.freeze({
+                ...parsed.quarantine,
+                ...(parsed.quarantine.gitRestore === undefined ? {} : {
+                    gitRestore: Object.freeze({ ...parsed.quarantine.gitRestore })
+                })
+            }) }),
+        ...(parsed.cleanupReceipt === undefined ? {} : { cleanupReceipt: Object.freeze({ ...parsed.cleanupReceipt }) })
     });
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/resources/sqliteResourceRegistry.js

@@ -14,7 +14,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
-import { migrateSqliteSchema } from "../storage/sqliteSchema.js";
+import { validateSqliteSchema } from "../storage/sqliteSchema.js";
 import { emptyResourceRegistry, parseResourceRegistryState } from "./resourceRegistry.js";
 import { RESOURCE_REGISTRY_SCHEMA_VERSION } from "./resourceTypes.js";
 export const SQLITE_RESOURCE_REGISTRY_TABLE = "resource_registry";
@@ -31,10 +31,10 @@ export class SqliteResourceRegistry {
         }
         this.#db = new Database(dbPath);
         try {
+            validateSqliteSchema(this.#db);
             this.#db.pragma("journal_mode = WAL");
             this.#db.pragma("foreign_keys = ON");
             this.#db.pragma("busy_timeout = 5000");
-            migrateSqliteSchema(this.#db, { mode: "validate" });
         }
         catch (error) {
             this.#db.close();
@@ -42,7 +42,7 @@ export class SqliteResourceRegistry {
         }
     }
     load() {
-        const rows = this.#db.prepare(`SELECT payload FROM ${SQLITE_RESOURCE_REGISTRY_TABLE}`).all();
+        const rows = this.#db.prepare(`SELECT id, payload FROM ${SQLITE_RESOURCE_REGISTRY_TABLE}`).all();
         if (rows.length === 0)
             return emptyResourceRegistry();
         const records = {};
@@ -52,14 +52,12 @@ export class SqliteResourceRegistry {
                 parsed = JSON.parse(row.payload);
             }
             catch (error) {
-                throw new Error(`SQLite resource registry has a corrupt payload: `
+                throw new Error(`SQLite resource registry record ${row.id} has a corrupt payload: `
                     + `${error instanceof Error ? error.message : "unknown error"}.`, { cause: error });
             }
             const state = parseResourceRegistryState({
                 schemaVersion: RESOURCE_REGISTRY_SCHEMA_VERSION,
-                records: { [typeof parsed === "object" && parsed !== null && "id" in parsed
-                        ? String(parsed.id)
-                        : ""]: parsed }
+                records: { [row.id]: parsed }
             });
             Object.assign(records, state.records);
         }

package/dist/review/reviewRound.js

@@ -5,7 +5,7 @@ import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 import { assertExecutionGroupTransition, retryFailedExecutionLanes, validateExecutionGroup, validateReviewExecutionAssignment } from "../execution/workItemExecution.js";
 export function createReviewRound(id, taskId, workItemId, candidateId, reviewerRoleName, requestedBy, reviewBaseCommit, now, executionGroup) {
     return validateReviewRound({
-        schemaVersion: 8,
+        schemaVersion: 1,
         id: requireIdentity(id, "ReviewRound id"),
         taskId: requireIdentity(taskId, "Task id"),
         workItemId: requireIdentity(workItemId, "Work Item id"),
@@ -22,7 +22,7 @@ export function createReviewRound(id, taskId, workItemId, candidateId, reviewerR
 export function createTaskReviewRound(id, taskId, reviewerRoleName, requestedBy, taskCandidate, now, taskFinalReviewContract, executionGroup) {
     const candidate = validateTaskReviewCandidate(taskCandidate);
     return validateReviewRound({
-        schemaVersion: 8,
+        schemaVersion: 1,
         id: requireIdentity(id, "ReviewRound id"),
         taskId: requireIdentity(taskId, "Task id"),
         reviewerRoleName: requireIdentity(reviewerRoleName, "Reviewer Role"),
@@ -48,7 +48,7 @@ export function createTaskReviewRound(id, taskId, reviewerRoleName, requestedBy,
 export function createTaskDeltaReviewRound(id, taskId, reviewerRoleName, requestedBy, taskCandidate, deltaRecheck, now, taskFinalReviewContract, executionGroup) {
     const candidate = validateTaskReviewCandidate(taskCandidate);
     return validateReviewRound({
-        schemaVersion: 8,
+        schemaVersion: 1,
         id: requireIdentity(id, "ReviewRound id"),
         taskId: requireIdentity(taskId, "Task id"),
         reviewerRoleName: requireIdentity(reviewerRoleName, "Reviewer Role"),
@@ -285,8 +285,8 @@ export function validateReviewRound(round) {
         "createdAt",
         "endedAt"
     ], "ReviewRound");
-    if (round.schemaVersion !== 8)
-        throw new Error("ReviewRound must use schemaVersion 8.");
+    if (round.schemaVersion !== 1)
+        throw new Error("ReviewRound must use schemaVersion 1.");
     validateTaskRecordReference({ taskId: round.taskId, localId: round.id }, "reviewRound");
     requireIdentity(round.reviewerRoleName, "Reviewer Role");
     requireCommit(round.reviewBaseCommit, "Review base commit");

package/dist/role/role.js

@@ -30,14 +30,14 @@ export function createRole(taskId, name, bindings, activeAgentId, workspace, now
     const owner = createRoleOwner(name, bindings, activeAgentId, workspace, now, profile, defaultAccess);
     return validateTaskRole({
         ...owner,
-        schemaVersion: 4,
+        schemaVersion: 1,
         taskId: requireSafeIdentity(taskId, "Task id")
     });
 }
 export function createGlobalRole(name, bindings, activeAgentId, workspace, now, profile = {}, defaultAccess = "write") {
     return validateGlobalRole({
         ...createRoleOwner(name, bindings, activeAgentId, workspace, now, profile, defaultAccess),
-        schemaVersion: 3
+        schemaVersion: 1
     });
 }
 export function copyGlobalRoleToTaskRole(globalRole, taskId, now, name = globalRole.name) {
@@ -45,7 +45,7 @@ export function copyGlobalRoleToTaskRole(globalRole, taskId, now, name = globalR
     const timestamp = now.toISOString();
     return validateTaskRole({
         ...cloneProfile(globalRole),
-        schemaVersion: 4,
+        schemaVersion: 1,
         launchRevision: 1,
         defaultAccess: globalRole.defaultAccess,
         taskId: requireSafeIdentity(taskId, "Task id"),
@@ -189,6 +189,8 @@ export function unbindRoleAgent(role, sessions, agentId, now) {
     return { role: updatedRole, sessions: updatedSessions };
 }
 export function validateGlobalRole(role) {
+    if (Object.hasOwn(role, "taskId"))
+        throw new Error("Global Role cannot carry a Task identity.");
     return validateRoleOwner(role);
 }
 export function validateTaskRole(role) {
@@ -218,8 +220,7 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile,
     };
 }
 function validateRoleOwner(role) {
-    const expectedSchemaVersion = "taskId" in role ? 4 : 3;
-    if (role.schemaVersion !== expectedSchemaVersion) {
+    if (role.schemaVersion !== 1) {
         throw new Error("Role schema version is invalid.");
     }
     if (!Number.isSafeInteger(role.launchRevision) || role.launchRevision < 1) {
@@ -256,9 +257,7 @@ function validateRoleOwner(role) {
 function validateRoleAgentBinding(binding) {
     const agentId = requireSafeIdentity(binding.agentId, "Role Agent id");
     const adapterId = requireSupportedAdapterId(binding.adapterId);
-    // Storage 10 backfilled every stored binding, so a missing component here is
-    // a corrupt record rather than an old one. Defaulting it would invent a
-    // product identity for data that never lost one.
+    // The current contract requires an explicit execution component.
     if (binding.component === undefined) {
         throw new Error(`Role Agent binding is missing its execution component: ${agentId}.`);
     }

package/dist/runtime/acpProtocol.js

@@ -126,9 +126,8 @@ export function acpPromptRequest(sessionId, text) {
 /**
  * Read a `configOptions` array from a session setup or set-option result.
  *
- * Returns undefined when the field is absent, which is how an Agent that
- * predates config options answers; that is a different fact from an Agent
- * answering with an empty list, which offers nothing configurable. Callers must
+ * Returns undefined when the field is absent: configuration support is then
+ * unobserved. An explicit empty list instead offers nothing configurable. Callers must
  * be able to tell those apart, so the absence is not flattened to `[]`.
  */
 export function readAcpConfigOptions(value) {

package/dist/runtime/acpSession.js

@@ -5,6 +5,7 @@ import { ACP_CONFIGURATION_ORDER, acpRunConfigurationOptions, confirmAcpConfigur
 import { handshakeObservationFrom, unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { JsonLineChannel, terminateProcessGroup } from "./jsonLineChannel.js";
 import { ProviderDeliveryUnknownError, ProviderTurnRejectedError } from "./providerErrors.js";
+import { providerDeliveryFailureFrom } from "./agentError.js";
 /**
  * One Agent Client Protocol Session over an Agent's stdio.
  *
@@ -86,9 +87,24 @@ export class AcpStructuredProviderSession {
         this.mirror = mirror;
     }
     static async open(input) {
-        const channel = new JsonLineChannel(input.child, input.mirror);
+        let receivingAttemptId;
+        const channel = new JsonLineChannel(input.child, input.mirror, error => {
+            // Before session/new has answered, the opening caller owns the failure.
+            if (!session.#sessionId)
+                return;
+            input.onDiagnostic?.({
+                nativeSessionId: session.#sessionId,
+                ...((receivingAttemptId ?? session.#activeAttemptId) === undefined
+                    ? {} : { attemptId: receivingAttemptId ?? session.#activeAttemptId }),
+                failure: providerDeliveryFailureFrom(error, { phase: "turn-reconcile", inputDisposition: "unknown" })
+            });
+        });
         const session = new AcpStructuredProviderSession(input.child, input.exit, input.processInstanceId, channel, input.onTerminal, input.mirror);
-        channel.onMessage((message) => session.#receive(message));
+        channel.onMessage((message) => {
+            receivingAttemptId = session.#activeAttemptId;
+            session.#receive(message);
+            receivingAttemptId = undefined;
+        });
         channel.onClose((error) => session.#fail(error));
         const negotiated = readAcpInitializeResult(await session.#request("initialize", acpInitializeRequest(input.clientVersion)));
         session.#negotiated = negotiated;
@@ -463,7 +479,7 @@ export class AcpStructuredProviderSession {
         if (message.id === undefined)
             this.#notification(method, message.params);
         else
-            void this.#serve(method, message);
+            void this.#serve(method, message).catch(error => this.#fail(error));
     }
     #response(message) {
         const id = typeof message.id === "number" ? message.id : undefined;
@@ -638,8 +654,8 @@ export class AcpStructuredProviderSession {
                 ...(error === undefined ? { result: result ?? {} } : { error })
             });
         }
-        catch {
-            // The pipe is gone; the closure path already reports that fact.
+        catch (error) {
+            this.#fail(error instanceof Error ? error : new Error(String(error)));
         }
     }
     #fail(error) {

package/dist/runtime/agentDriverObservation.js

@@ -40,7 +40,7 @@ function observation(input, mapped) {
     const eventId = hookEventId(input, mapped, requestOccurrenceId);
     const fence = { ...input.fence, ...mapped.fence };
     return createRuntimeObservation({
-        schemaVersion: 4,
+        schemaVersion: 1,
         eventId,
         semanticKey: requestOccurrenceId === undefined
             ? runtimeObservationSemanticKey({

package/dist/runtime/agentEndpoint.js

@@ -46,6 +46,7 @@ export function createAgentEndpointFactory(start = startStructuredProviderSessio
             onStarted: (value) => emit({ type: "started", value }),
             onTerminal: (value) => emit({ type: "terminal", value }),
             onInput: (value) => emit({ type: "input", value }),
+            onDiagnostic: (value) => emit({ type: "diagnostic", value }),
             onGoal: (value) => emit({ type: "goal", value })
         });
         endpoint = new BuiltinAgentEndpoint(opened.session, configuration, opened.recoveredTerminal);
@@ -193,7 +194,9 @@ class BuiltinAgentEndpoint {
         });
     }
     observe(value) {
-        if (value.type !== "goal"
+        if (value.type === "diagnostic" && value.value.nativeSessionId !== this.nativeSessionId)
+            return;
+        if (value.type !== "goal" && value.type !== "diagnostic"
             && (value.value.nativeSessionId !== this.nativeSessionId || value.value.conversationId !== this.conversationId))
             return;
         if (value.type === "goal" && value.value !== null && value.value.conversationId !== this.conversationId)