@zq-silk/yui 0.15.7 → 0.15.9

package/dist/storage/sqliteStore.js

@@ -38,21 +38,33 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
+import { validatePluginValidation } from "../plugins/pluginPackage.js";
+import { validatePluginIntent, validatePluginIntentFailure } from "../plugins/pluginIntent.js";
+import { validateLocalResource, validateEnvironmentPreparation } from "../resources/projectResource.js";
+import { validateConfiguredAgent } from "../agent/agent.js";
+import { validateTaskBrief } from "../brief/taskBrief.js";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
 import { validateContextSnapshot } from "../context/contextSnapshot.js";
+import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { compareRuntimeSessionCandidates, projectRuntimeSessionCandidate } from "../runtime/runtimeSessionCandidate.js";
+import { sessionOwnerProcessKey } from "../runtime/sessionOwnerIdentity.js";
 import { validateReviewRound } from "../review/reviewRound.js";
+import { validateProject } from "../repository/project.js";
 import { generateHomeIdentity, validateHomeIdentity } from "../repository/homeIdentity.js";
 import { validateIntegrationQueueEntry } from "../integration/integrationQueueEntry.js";
 import { validDurableJobTransition, validateDurableJob } from "../job/durableJob.js";
+import { validateGlobalRole, validateTaskRole } from "../role/role.js";
 import { validateTaskWake } from "../scheduler/taskWake.js";
+import { validateTask } from "../task/task.js";
+import { pendingCompletionMessages } from "../task/completionReadiness.js";
 import { operationalTaskRecords, TASK_RECORD_RETIRED_EVENT } from "../task/taskRecordRetirement.js";
 import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
+import { validateWorkItem } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
-import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveTurnKey, executionLaneActiveTurnKeyParts, StorageConflictError, StorageCancelledError, StorageRecordError, storedCapabilityGrant, storedPublicationReference, storedReleaseWorkflow, isValidCapabilityGrantTransition, isValidReleaseWorkflowTransition, pendingWakeupProjection, validateYuiConfig } from "./taskStore.js";
+import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveRunKey, executionLaneActiveRunKeyParts, StorageConflictError, StorageCancelledError, StorageRecordError, storedCapabilityGrant, storedPublicationReference, storedReleaseWorkflow, isValidCapabilityGrantTransition, isValidReleaseWorkflowTransition, pendingWakeupProjection, validateYuiConfig } from "./taskStore.js";
 import { publicationExternalKey } from "../task/publicationReference.js";
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
-import { inspectSqliteSchemaMigrations, migrateSqliteSchema, SqliteSchemaMigrationError, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_TURN_CAP } from "./sqliteSchema.js";
+import { inspectSqliteSchemaMigrations, migrateSqliteSchema, SqliteSchemaMigrationError, TELEMETRY_KEEP_PER_RUN, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
 import { StorageSchemaError } from "./storageSchema.js";
 /** Read the immutable Home identity without opening a writable Store connection. */
 export function readSqliteHomeIdentity(rootDir, databaseFilename = "yui.db") {
@@ -113,6 +125,12 @@ function isUniqueConstraint(error) {
         && error.code === "SQLITE_CONSTRAINT_PRIMARYKEY"
         || error?.code === "SQLITE_CONSTRAINT_UNIQUE";
 }
+/** One admission rule for every active-Turn write path in this store. */
+function assertRunAdmission(task, run) {
+    if (task === null || !runPurposeAdmitsTaskState(run.purpose, task)) {
+        throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
+    }
+}
 export class SqliteTaskStore {
     #db;
     #rootDir;
@@ -508,11 +526,29 @@ export class SqliteTaskStore {
     // -- generic payload helpers ------------------------------------------------
     #getPayload(table, where, params) {
         const row = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).get(...params);
-        return row === undefined ? null : this.#parse(row.payload);
+        return row === undefined ? null : this.#validateTaskPayload(table, row.payload);
     }
     #listPayload(table, where, params) {
         const rows = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).all(...params);
-        return rows.map((row) => this.#parse(row.payload));
+        return rows.map((row) => this.#validateTaskPayload(table, row.payload));
+    }
+    #validateTaskPayload(table, payload) {
+        const record = this.#parse(payload);
+        if (table === "task_records")
+            validateTask(record);
+        if (table === "work_items")
+            validateWorkItem(record);
+        // Agents and Roles carry the execution component, and their validators
+        // refuse a record that lost it. Reading them unchecked defeated that: a
+        // component-less row reached display and rendered `undefined` as if it
+        // were a product, and reached launch as a binding nothing had vetted.
+        if (table === "configured_agents")
+            validateConfiguredAgent(record);
+        if (table === "task_roles")
+            validateTaskRole(record);
+        if (table === "global_roles")
+            validateGlobalRole(record);
+        return record;
     }
     #sortById(rows, idOf) {
         return [...rows].sort((left, right) => numericCompare(idOf(left), idOf(right)));
@@ -578,24 +614,130 @@ export class SqliteTaskStore {
         });
     }
     // -- projects ---------------------------------------------------------------
+    savePluginValidation(validation) {
+        validatePluginValidation(validation);
+        this.#mutate(() => {
+            const previous = this.getPluginValidation(validation.taskId, validation.id);
+            if (previous !== null) {
+                if (!isDeepStrictEqual(previous, validation))
+                    throw new StorageRecordError("Plugin validation is immutable.");
+                return;
+            }
+            this.#db.prepare("INSERT INTO plugin_validations (task_id, id, payload) VALUES (?, ?, ?)")
+                .run(validation.taskId, validation.id, this.#json(validation));
+        });
+    }
+    savePluginIntent(intent) {
+        validatePluginIntent(intent);
+        this.#mutate(() => {
+            const previous = this.getPluginIntent(intent.taskId, intent.pluginId);
+            if (intent.revision !== (previous?.revision ?? 0) + 1 || intent.lastFailure !== undefined) {
+                throw new StorageRecordError("Plugin intent must be a new explicit choice without historical failure.");
+            }
+            if (intent.validationId !== undefined) {
+                const validation = this.getPluginValidation(intent.taskId, intent.validationId);
+                if (validation?.package.manifest.id !== intent.pluginId)
+                    throw new StorageRecordError("Plugin validation is outside this intent.");
+            }
+            this.#db.prepare(`INSERT INTO plugin_intents (task_id, plugin_id, payload) VALUES (?, ?, ?)
+        ON CONFLICT(task_id, plugin_id) DO UPDATE SET payload = excluded.payload`)
+                .run(intent.taskId, intent.pluginId, this.#json(intent));
+        });
+    }
+    getPluginIntent(taskId, pluginId) {
+        const value = this.#getPayload("plugin_intents", "task_id = ? AND plugin_id = ?", [taskId, pluginId]);
+        return value === null ? null : validatePluginIntent(value);
+    }
+    listPluginIntents(taskId) {
+        return this.#listPayload("plugin_intents", "task_id = ?", [taskId]).map(validatePluginIntent);
+    }
+    recordPluginIntentFailure(taskId, pluginId, revision, failure) {
+        validatePluginIntentFailure(failure);
+        return this.transaction(() => {
+            const current = this.getPluginIntent(taskId, pluginId);
+            if (current === null || current.revision !== revision)
+                return false;
+            this.#mutate(() => {
+                this.#db.prepare("UPDATE plugin_intents SET payload = ? WHERE task_id = ? AND plugin_id = ?")
+                    .run(this.#json({ ...current, lastFailure: failure }), taskId, pluginId);
+            });
+            return true;
+        });
+    }
+    getPluginValidation(taskId, id) {
+        const value = this.#getPayload("plugin_validations", "task_id = ? AND id = ?", [taskId, id]);
+        return value === null ? null : validatePluginValidation(value);
+    }
+    saveLocalResource(resource) {
+        validateLocalResource(resource);
+        this.#mutate(() => {
+            const previous = this.getLocalResource(resource.id);
+            if (previous !== null) {
+                if (!isDeepStrictEqual(previous, resource))
+                    throw new StorageRecordError("Resource identity is immutable.");
+                return;
+            }
+            this.#db.prepare("INSERT INTO local_resources (id, canonical_identity, payload) VALUES (?, ?, ?)")
+                .run(resource.id, `${resource.device}:${resource.inode}`, this.#json(resource));
+        });
+    }
+    getLocalResource(resourceId) {
+        const resource = this.#getPayload("local_resources", "id = ?", [resourceId]);
+        return resource === null ? null : validateLocalResource(resource);
+    }
+    listLocalResources() {
+        return this.#listPayload("local_resources", "1=1", []).map(validateLocalResource);
+    }
+    saveEnvironmentPreparation(preparation) {
+        validateEnvironmentPreparation(preparation);
+        this.#mutate(() => {
+            const previous = this.getEnvironmentPreparation(preparation.taskId, preparation.id);
+            if (previous) {
+                const { disposition: before, updatedAt: _beforeTime, releaseEvidence: _beforeEvidence, ...identity } = previous;
+                const { disposition: after, updatedAt: _afterTime, releaseEvidence: _afterEvidence, ...nextIdentity } = preparation;
+                if (!isDeepStrictEqual(identity, nextIdentity)
+                    || (before === "released" && !isDeepStrictEqual(previous, preparation))
+                    || (before === "adopted" && after === "prepared")) {
+                    throw new StorageRecordError("Preparation ownership/identity cannot be rewritten.");
+                }
+            }
+            else if (preparation.disposition !== "prepared") {
+                throw new StorageRecordError("Environment must be prepared before adoption.");
+            }
+            this.#db.prepare(`INSERT INTO environment_preparations (task_id, id, payload) VALUES (?, ?, ?)
+        ON CONFLICT(task_id, id) DO UPDATE SET payload = excluded.payload`)
+                .run(preparation.taskId, preparation.id, this.#json(preparation));
+        });
+    }
+    getEnvironmentPreparation(taskId, preparationId) {
+        const preparation = this.#getPayload("environment_preparations", "task_id = ? AND id = ?", [taskId, preparationId]);
+        return preparation === null ? null : validateEnvironmentPreparation(preparation);
+    }
+    listEnvironmentPreparations(taskId) {
+        return this.#listPayload("environment_preparations", "task_id = ?", [taskId])
+            .map(validateEnvironmentPreparation);
+    }
     nextProjectId() { return this.#nextGlobalId("project"); }
     saveProject(project) {
+        validateProject(project);
         this.#mutate(() => {
             this.#db.prepare(`INSERT INTO projects (id, name, path, payload, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)
          ON CONFLICT(id) DO UPDATE SET name = excluded.name, path = excluded.path, payload = excluded.payload, updated_at = excluded.updated_at`).run(project.id, project.name, project.path, this.#json(project), project.createdAt, project.updatedAt);
         });
     }
     createProjectIfAbsent(project) {
+        validateProject(project);
         return this.#mutate(() => {
             const result = this.#db.prepare("INSERT OR IGNORE INTO projects (id, name, path, payload, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)").run(project.id, project.name, project.path, this.#json(project), project.createdAt, project.updatedAt);
             return result.changes > 0 ? project : null;
         });
     }
     listProjects() {
-        return this.#sortById(this.#listPayload("projects", "1=1", []), (project) => project.id);
+        return this.#sortById(this.#listPayload("projects", "1=1", []).map(validateProject), (project) => project.id);
     }
     getProject(id) {
-        return this.#getPayload("projects", "id = ?", [id]);
+        const project = this.#getPayload("projects", "id = ?", [id]);
+        return project === null ? null : validateProject(project);
     }
     removeProject(id) {
         return this.#mutate(() => {
@@ -609,17 +751,17 @@ export class SqliteTaskStore {
         const boundTasks = this.listTasks().filter((task) => task.projectBindings.some((binding) => binding.projectId === projectId));
         const activeTasks = boundTasks.filter((task) => task.status === "active");
         const unresolvedWorkItemRefs = [];
-        const activeTurnRefs = [];
+        const activeRunRefs = [];
         const unresolvedIntegrationRefs = [];
         for (const task of activeTasks) {
             for (const workItem of this.listWorkItems(task.id)) {
-                if (workItem.status !== "completed" && workItem.status !== "retired") {
+                if (workItem.status !== "accepted" && workItem.status !== "retired") {
                     unresolvedWorkItemRefs.push(`${task.id}/${workItem.id}`);
                 }
             }
-            for (const run of this.listTurns(task.id)) {
+            for (const run of this.listRuns(task.id)) {
                 if (run.status === "active")
-                    activeTurnRefs.push(`${task.id}/${run.id}`);
+                    activeRunRefs.push(`${task.id}/${run.id}`);
             }
             for (const attempt of this.listIntegrationAttempts(task.id)) {
                 if (attempt.status === "running" || attempt.status === "blocked") {
@@ -632,7 +774,7 @@ export class SqliteTaskStore {
             boundTaskIds: boundTasks.map(({ id }) => id),
             activeTaskIds: activeTasks.map(({ id }) => id),
             unresolvedWorkItemRefs,
-            activeTurnRefs,
+            activeRunRefs,
             unresolvedIntegrationRefs
         };
     }
@@ -716,6 +858,7 @@ export class SqliteTaskStore {
     // -- tasks ------------------------------------------------------------------
     nextTaskId() { return this.#nextGlobalId("task"); }
     saveTask(task) {
+        validateTask(task);
         if (typeof task.id !== "string" || task.id.length === 0) {
             throw new StorageRecordError("Task id is required.");
         }
@@ -747,13 +890,13 @@ export class SqliteTaskStore {
         if (task === null)
             return null;
         // One indexed query (idx_turns_role_status) covers both the active
-        // Turns the projection waits on and the Leader Turns the budget consumes.
+        // AgentRuns the projection waits on and the Leader AgentRuns the budget consumes.
         const events = this.#sortById(this.#listPayload("events", "task_id = ? AND type IN (?, ?)", [
             taskId,
             TASK_RECORD_RETIRED_EVENT,
             "review.completed"
         ]), (event) => event.id);
-        const runs = operationalTaskRecords(this.#sortById(this.#listPayload("turns", "task_id = ? AND (status = 'active' OR role_name = 'leader')", [taskId]), (run) => run.id), events, "turn");
+        const runs = operationalTaskRecords(this.#sortById(this.#listPayload("turns", "task_id = ? AND (status = 'active' OR role_name = 'leader')", [taskId]), (run) => run.id), events, "run");
         return {
             task: {
                 id: task.id,
@@ -765,14 +908,17 @@ export class SqliteTaskStore {
             workItems: this.#sortById(this.#listPayload("work_items", "task_id = ?", [taskId]), (item) => item.id),
             changeSets: this.#sortById(this.#listPayload("change_sets", "task_id = ?", [taskId]), (changeSet) => changeSet.id),
             integrations: this.#sortById(this.#listPayload("integration_attempts", "task_id = ?", [taskId]), (attempt) => attempt.id),
+            integrationJobs: this.listDurableJobs(taskId)
+                .filter(job => job.owner.kind === "integration-attempt")
+                .map(job => ({ id: job.id, status: job.status })),
             integrationQueueEntries: this.#sortById(this.#listPayload("integration_queue", "task_id = ?", [taskId]), (entry) => entry.id),
             reviewRounds: this.#sortById(this.#listPayload("review_rounds", "task_id = ?", [taskId]), (round) => round.id),
             reviewConfig: this.getReviewConfig(),
             openInputRequests: this.#sortById(this.#listPayload("input_requests", "task_id = ? AND status = 'open'", [taskId]), (request) => request.id),
-            activeTurns: runs.filter((run) => run.status === "active"),
-            leaderTurns: runs.filter((run) => run.roleName === "leader"),
+            activeRuns: runs.filter((run) => run.status === "active"),
+            leaderRuns: runs.filter((run) => run.roleName === "leader"),
             reviewOutcomeEvidence: {
-                turns: this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]).filter((run) => run.purpose === "review"), (run) => run.id)
+                runs: this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]).filter((run) => run.purpose === "review"), (run) => run.id)
             }
         };
     }
@@ -782,6 +928,7 @@ export class SqliteTaskStore {
             return null;
         return {
             ...base,
+            pendingUserMessages: pendingCompletionMessages(this, taskId),
             managedWorkspaces: this.#sortById(this.#listPayload("managed_workspaces", "task_id = ?", [taskId]), (workspace) => managedWorkspaceKey(workspace.owner)),
             durableJobs: this.#sortById(this.#listPayload("durable_jobs", "task_id = ?", [taskId]), (job) => job.id),
             integrationQueueEntries: this.#sortById(this.#listPayload("integration_queue", "task_id = ?", [taskId]), (entry) => entry.id),
@@ -792,13 +939,41 @@ export class SqliteTaskStore {
         const rows = this.#db.prepare("SELECT task_id FROM tasks_catalog WHERE is_active = 1 ORDER BY task_id").all();
         return rows.map((row) => row.task_id);
     }
+    /**
+     * Draft Task ids that carry an active planning Turn.
+     *
+     * Bounded by the active-Turn pointers rather than Task history: a Draft
+     * appears only while one of its Roles actually holds an admitted planning
+     * Turn, so an ordinary Draft is never selected for execution phases.
+     */
+    listPlanningDraftTaskIds() {
+        const rows = this.#db.prepare(`SELECT DISTINCT catalog.task_id AS task_id
+         FROM tasks_catalog AS catalog
+         JOIN active_turns AS pointers ON pointers.task_id = catalog.task_id
+         JOIN turns ON turns.task_id = pointers.task_id AND turns.turn_id = pointers.turn_id
+        WHERE catalog.status = 'draft'
+          AND turns.status = 'active'
+          AND json_extract(turns.payload, '$.purpose') = 'planning'
+        ORDER BY catalog.task_id`).all();
+        return rows.map((row) => row.task_id);
+    }
+    listPendingActivationRequestTaskIds() {
+        const rows = this.#db.prepare(`SELECT records.task_id AS task_id
+         FROM task_records AS records
+         JOIN tasks_catalog AS catalog ON catalog.task_id = records.task_id
+        WHERE catalog.status = 'draft'
+          AND json_extract(records.payload, '$.activationRequest.disposition') = 'pending'
+        ORDER BY records.task_id`).all();
+        return rows.map((row) => row.task_id);
+    }
     getTaskBrief(taskId) {
         const row = this.#db.prepare("SELECT brief FROM task_records WHERE task_id = ?").get(taskId);
         if (row === undefined || row.brief === null)
             return null;
-        return this.#parse(row.brief);
+        return validateTaskBrief(this.#parse(row.brief));
     }
     saveTaskBrief(taskId, brief) {
+        validateTaskBrief(brief);
         this.#requireTask(taskId);
         this.#mutate(() => {
             this.#db.prepare("UPDATE task_records SET brief = ?, updated_at = ? WHERE task_id = ?")
@@ -932,40 +1107,24 @@ export class SqliteTaskStore {
         const row = this.#db.prepare("SELECT 1 FROM durable_jobs WHERE status IN ('queued', 'running') LIMIT 1").get();
         return row !== undefined;
     }
-    // -- job caller key hashes (rr13) -------------------------------------------
-    getJobCallerKeyHash(taskId, roleName, agentId) {
-        const row = this.#db.prepare("SELECT hash FROM job_caller_key_hashes WHERE task_id = ? AND role_name = ? AND agent_id = ?").get(taskId, roleName, agentId);
-        return row === undefined ? null : row.hash;
-    }
-    setJobCallerKeyHash(taskId, roleName, agentId, hash) {
-        this.#requireTask(taskId);
-        if (!/^[a-f0-9]{64}$/u.test(hash)) {
-            throw new StorageRecordError(`Job caller key hash is invalid: ${taskId}/${roleName}.`);
-        }
-        this.#mutate(() => {
-            this.#db.prepare(`INSERT INTO job_caller_key_hashes (task_id, role_name, agent_id, hash, updated_at)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(task_id, role_name, agent_id) DO UPDATE SET hash = excluded.hash, updated_at = excluded.updated_at`).run(taskId, roleName, agentId, hash, this.#now());
-        });
-    }
     // -- session owners (Issue 03) ----------------------------------------------
     saveSessionOwner(identity) {
         const owner = identity.owner;
         this.#mutate(() => {
             this.#db.prepare(`INSERT INTO session_owners
-           (launch_id, scope, task_id, role_name, agent_id, native_session_id,
+           (process_key, scope, task_id, role_name, agent_id, native_session_id,
             provider_root_pid, payload, recorded_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-         ON CONFLICT(launch_id) DO UPDATE SET
+         ON CONFLICT(process_key) DO UPDATE SET
            scope = excluded.scope, task_id = excluded.task_id,
            role_name = excluded.role_name, agent_id = excluded.agent_id,
            native_session_id = excluded.native_session_id,
            provider_root_pid = excluded.provider_root_pid,
-           payload = excluded.payload, recorded_at = excluded.recorded_at`).run(identity.runtimeGenerationId, owner.scope, owner.scope === "task" ? owner.taskId : null, owner.roleName, identity.agentId, identity.nativeSessionId ?? null, identity.providerRoot.pid, this.#json(identity), identity.recordedAt);
+           payload = excluded.payload, recorded_at = excluded.recorded_at`).run(sessionOwnerProcessKey(identity), owner.scope, owner.scope === "task" ? owner.taskId : null, owner.roleName, identity.agentId, identity.nativeSessionId ?? null, identity.providerRoot.pid, this.#json(identity), identity.recordedAt);
         });
     }
-    getSessionOwner(runtimeGenerationId) {
-        const row = this.#db.prepare("SELECT payload FROM session_owners WHERE launch_id = ?").get(runtimeGenerationId);
+    getSessionOwner(processKey) {
+        const row = this.#db.prepare("SELECT payload FROM session_owners WHERE process_key = ?").get(processKey);
         return row === undefined ? null : this.#parse(row.payload);
     }
     listSessionOwners() {
@@ -977,9 +1136,9 @@ export class SqliteTaskStore {
         }
         return this.#listPayload("session_owners", "scope = 'task' AND task_id = ? AND role_name = ?", [owner.taskId, owner.roleName]);
     }
-    removeSessionOwner(runtimeGenerationId) {
+    removeSessionOwner(processKey) {
         this.#mutate(() => {
-            this.#db.prepare("DELETE FROM session_owners WHERE launch_id = ?").run(runtimeGenerationId);
+            this.#db.prepare("DELETE FROM session_owners WHERE process_key = ?").run(processKey);
         });
     }
     // -- task roles -------------------------------------------------------------
@@ -1078,8 +1237,6 @@ export class SqliteTaskStore {
         }
         const predicates = [];
         const parameters = [];
-        if (query.cleanupRequiredOnly)
-            predicates.push("cleanup_required = 1");
         if (taskIds !== undefined) {
             predicates.push("scope = 'task'");
             predicates.push(`task_id IN (${taskIds.map(() => "?").join(", ")})`);
@@ -1093,8 +1250,7 @@ export class SqliteTaskStore {
             ? ""
             : ` WHERE ${predicates.join(" AND ")}`;
         const rows = this.#db.prepare(`SELECT scope, task_id, role_name, agent_id, adapter_id,
-              native_session_id, launch_id AS runtime_generation_id, session_updated_at,
-              cleanup_required
+              native_session_id, session_updated_at
        FROM runtime_session_candidates${where}`).all(...parameters);
         const candidates = rows.map((row) => ({
             owner: row.scope === "task"
@@ -1103,9 +1259,7 @@ export class SqliteTaskStore {
             agentId: row.agent_id,
             adapterId: row.adapter_id,
             nativeSessionId: row.native_session_id,
-            ...(row.runtime_generation_id === null ? {} : { runtimeGenerationId: row.runtime_generation_id }),
-            sessionUpdatedAt: row.session_updated_at,
-            cleanupRequired: row.cleanup_required === 1
+            sessionUpdatedAt: row.session_updated_at
         })).sort(compareRuntimeSessionCandidates);
         for (const candidate of candidates) {
             if (!this.#runtimeSessionCandidateMatchesSource(candidate)) {
@@ -1158,17 +1312,11 @@ export class SqliteTaskStore {
            json_extract(active_session, '$.agentId') AS agent_id,
            json_extract(active_session, '$.adapterId') AS adapter_id,
            json_extract(active_session, '$.nativeSessionId') AS native_session_id,
-           json_extract(active_session, '$.runtimeGenerationId') AS runtime_generation_id,
            CASE
              WHEN json_extract(active_session, '$.status') = 'active'
              THEN 1 ELSE 0
            END AS is_active,
-           json_extract(active_session, '$.updatedAt') AS session_updated_at,
-           CASE
-             WHEN json_extract(active_session, '$.status') = 'active'
-               AND json_type(active_session, '$.runtimeGenerationId') = 'text'
-             THEN 1 ELSE 0
-           END AS cleanup_required
+           json_extract(active_session, '$.updatedAt') AS session_updated_at
          FROM active`).get(...source.parameters);
         }
         catch (error) {
@@ -1179,17 +1327,7 @@ export class SqliteTaskStore {
         }
         if (row === undefined)
             return false;
-        return row.owner_scope === candidate.owner.scope
-            && row.owner_task_id === (candidate.owner.scope === "task" ? candidate.owner.taskId : null)
-            && row.owner_role_name === candidate.owner.roleName
-            && row.active_agent_id === candidate.agentId
-            && row.agent_id === candidate.agentId
-            && row.adapter_id === candidate.adapterId
-            && row.native_session_id === candidate.nativeSessionId
-            && (row.runtime_generation_id ?? undefined) === candidate.runtimeGenerationId
-            && row.is_active === 1
-            && row.session_updated_at === candidate.sessionUpdatedAt
-            && row.cleanup_required === (candidate.cleanupRequired ? 1 : 0);
+        return row.owner_scope === candidate.owner.scope && row.owner_task_id === (candidate.owner.scope === "task" ? candidate.owner.taskId : null) && row.owner_role_name === candidate.owner.roleName && row.active_agent_id === candidate.agentId && row.agent_id === candidate.agentId && row.adapter_id === candidate.adapterId && row.native_session_id === candidate.nativeSessionId && row.is_active === 1 && row.session_updated_at === candidate.sessionUpdatedAt;
     }
     saveRoleSessionSet(sessions) {
         const taskId = sessions.owner.taskId;
@@ -1219,15 +1357,13 @@ export class SqliteTaskStore {
         const taskId = candidate.owner.scope === "task" ? candidate.owner.taskId : "";
         this.#db.prepare(`INSERT INTO runtime_session_candidates (
          scope, task_id, role_name, agent_id, adapter_id, native_session_id,
-         launch_id, session_updated_at, cleanup_required
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         session_updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(scope, task_id, role_name) DO UPDATE SET
          agent_id = excluded.agent_id,
          adapter_id = excluded.adapter_id,
          native_session_id = excluded.native_session_id,
-         launch_id = excluded.launch_id,
-         session_updated_at = excluded.session_updated_at,
-         cleanup_required = excluded.cleanup_required`).run(candidate.owner.scope, taskId, candidate.owner.roleName, candidate.agentId, candidate.adapterId, candidate.nativeSessionId, candidate.runtimeGenerationId ?? null, candidate.sessionUpdatedAt, candidate.cleanupRequired ? 1 : 0);
+         session_updated_at = excluded.session_updated_at`).run(candidate.owner.scope, taskId, candidate.owner.roleName, candidate.agentId, candidate.adapterId, candidate.nativeSessionId, candidate.sessionUpdatedAt);
     }
     #deleteRuntimeSessionCandidate(owner) {
         this.#db.prepare(`DELETE FROM runtime_session_candidates
@@ -1242,6 +1378,7 @@ export class SqliteTaskStore {
         return this.#sortById(this.#listPayload("work_items", "task_id = ?", [taskId]), (item) => item.id);
     }
     saveWorkItem(taskId, item) {
+        validateWorkItem(item);
         if (item.taskId !== taskId)
             throw new StorageRecordError(`Work item belongs to another Task: ${item.taskId}`);
         this.#requireTask(taskId);
@@ -1495,34 +1632,34 @@ export class SqliteTaskStore {
         });
     }
     // -- turns -----------------------------------------------------------------
-    nextTurnId(taskId) { return this.#nextTaskRecordId(taskId, "turn"); }
-    peekNextTurnId(taskId) { return this.#peekTaskRecordId(taskId, "turn"); }
-    getTurn(taskId, turnId) {
-        return this.#getPayload("turns", "task_id = ? AND turn_id = ?", [taskId, turnId]);
-    }
-    listTurns(taskId) {
-        return this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]), (turn) => turn.id);
-    }
-    saveTurn(turn) {
-        if (turn.taskId !== undefined)
-            this.#requireTask(turn.taskId);
-        if (turn.reviewRoundId !== undefined) {
-            const round = this.getReviewRound(turn.taskId, turn.reviewRoundId);
+    nextRunId(taskId) { return this.#nextTaskRecordId(taskId, "run"); }
+    peekNextRunId(taskId) { return this.#peekTaskRecordId(taskId, "run"); }
+    getRun(taskId, runId) {
+        return this.#getPayload("turns", "task_id = ? AND turn_id = ?", [taskId, runId]);
+    }
+    listRuns(taskId) {
+        return this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]), (run) => run.id);
+    }
+    saveRun(run) {
+        if (run.taskId !== undefined)
+            this.#requireTask(run.taskId);
+        if (run.reviewRoundId !== undefined) {
+            const round = this.getReviewRound(run.taskId, run.reviewRoundId);
             if (round === null) {
-                throw new StorageRecordError(`Turn ReviewRound not found: ${turn.reviewRoundId}.`);
+                throw new StorageRecordError(`AgentRun ReviewRound not found: ${run.reviewRoundId}.`);
             }
             const roundWorkItemId = round.workItemId;
             const laneRole = round.executionGroup?.lanes
-                .find(({ id }) => id === turn.executionLaneId)?.roleName;
-            if (roundWorkItemId !== turn.workItemId
-                || (round.reviewerRoleName !== turn.roleName && laneRole !== turn.roleName)) {
-                throw new StorageRecordError(`Turn does not match ReviewRound: ${turn.id}.`);
+                .find(({ id }) => id === run.executionLaneId)?.roleName;
+            if (roundWorkItemId !== run.workItemId
+                || (round.reviewerRoleName !== run.roleName && laneRole !== run.roleName)) {
+                throw new StorageRecordError(`AgentRun does not match ReviewRound: ${run.id}.`);
             }
         }
         this.#mutate(() => {
             this.#db.prepare(`INSERT INTO turns (task_id, turn_id, role_name, status, payload, updated_at) VALUES (?, ?, ?, ?, ?, ?)
          ON CONFLICT(task_id, turn_id) DO UPDATE SET role_name = excluded.role_name, status = excluded.status,
-           payload = excluded.payload, updated_at = excluded.updated_at`).run(turn.taskId, turn.id, turn.roleName, turn.status, this.#json(turn), this.#now());
+           payload = excluded.payload, updated_at = excluded.updated_at`).run(run.taskId, run.id, run.roleName, run.status, this.#json(run), this.#now());
         });
     }
     // -- review rounds ----------------------------------------------------------
@@ -1545,180 +1682,178 @@ export class SqliteTaskStore {
         });
     }
     // -- active turns ----------------------------------------------------------
-    #saveActiveTurn(taskId, pointer, turnId) {
+    #saveActiveRun(taskId, pointer, runId) {
         this.#mutate(() => {
-            const payload = this.#json({ schemaVersion: 3, turnId });
+            const payload = this.#json({ schemaVersion: 3, runId });
             this.#db.prepare(`INSERT INTO active_turns (task_id, pointer, turn_id, payload, updated_at) VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(task_id, pointer) DO UPDATE SET turn_id = excluded.turn_id, payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, pointer, turnId, payload, this.#now());
+         ON CONFLICT(task_id, pointer) DO UPDATE SET turn_id = excluded.turn_id, payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, pointer, runId, payload, this.#now());
         });
     }
-    #readActiveTurnPointer(taskId, pointer) {
+    #readActiveRunPointer(taskId, pointer) {
         const row = this.#db.prepare("SELECT turn_id FROM active_turns WHERE task_id = ? AND pointer = ?").get(taskId, pointer);
         if (row === undefined)
             return null;
         return {
-            turnId: row.turn_id,
-            turn: this.getTurn(taskId, row.turn_id)
+            runId: row.turn_id,
+            run: this.getRun(taskId, row.turn_id)
         };
     }
-    #assertActiveTurnForWrite(turn, lane) {
-        if (turn.status !== "active") {
-            throw new StorageRecordError(`Active Turn must have active status: ${turn.id}`);
+    #assertActiveRunForWrite(run, lane) {
+        if (run.status !== "active") {
+            throw new StorageRecordError(`Active AgentRun must have active status: ${run.id}`);
         }
-        const hasGroup = turn.executionGroupId !== undefined;
-        const hasLane = turn.executionLaneId !== undefined;
+        const hasGroup = run.executionGroupId !== undefined;
+        const hasLane = run.executionLaneId !== undefined;
         if (hasGroup !== hasLane) {
-            throw new StorageRecordError(`Turn execution lineage is incomplete: ${turn.id}.`);
+            throw new StorageRecordError(`AgentRun execution lineage is incomplete: ${run.id}.`);
         }
         if (lane !== undefined
-            && (turn.executionGroupId !== lane.executionGroupId
-                || turn.executionLaneId !== lane.executionLaneId)) {
-            throw new StorageRecordError(`Active Turn execution lineage does not match its Lane: ${turn.id}`);
+            && (run.executionGroupId !== lane.executionGroupId
+                || run.executionLaneId !== lane.executionLaneId)) {
+            throw new StorageRecordError(`Active AgentRun execution lineage does not match its Lane: ${run.id}`);
         }
     }
-    #getActiveRoleTurn(taskId, roleName) {
-        const pointer = this.#readActiveTurnPointer(taskId, roleName);
+    #getActiveRoleRun(taskId, roleName) {
+        const pointer = this.#readActiveRunPointer(taskId, roleName);
         if (pointer === null)
             return null;
         const task = this.getTask(taskId);
         if (task === null) {
-            throw new StorageRecordError(`Active Turn Task is missing: ${taskId}/${roleName}`);
+            throw new StorageRecordError(`Active AgentRun Task is missing: ${taskId}/${roleName}`);
         }
-        if (pointer.turn === null) {
+        if (pointer.run === null) {
             // Retired Tasks are an explicit historical isolation boundary. Their
-            // retained pointer rows may intentionally reference a missing Turn.
-            if (task.status === "retired")
+            // retained pointer rows may intentionally reference a missing AgentRun.
+            if (task.status === "cancelled" && task.retirementIsolation === true)
                 return null;
-            throw new StorageRecordError(`Active Turn pointer is dangling: ${taskId}/${roleName}`);
-        }
-        const turn = pointer.turn;
-        if (task.status === "retired")
-            return turn;
-        if (turn.id !== pointer.turnId
-            || turn.taskId !== taskId
-            || turn.roleName !== roleName
-            || turn.status !== "active"
-            || (turn.executionGroupId === undefined) !== (turn.executionLaneId === undefined)) {
-            throw new StorageRecordError(`Active Turn pointer is invalid: ${taskId}/${roleName}`);
-        }
-        return turn;
-    }
-    #getActiveLaneTurn(taskId, executionGroupId, executionLaneId) {
-        const pointerKey = executionLaneActiveTurnKey(executionGroupId, executionLaneId);
-        const pointer = this.#readActiveTurnPointer(taskId, pointerKey);
+            throw new StorageRecordError(`Active AgentRun pointer is dangling: ${taskId}/${roleName}`);
+        }
+        const run = pointer.run;
+        if (task.status === "cancelled" && task.retirementIsolation === true)
+            return run;
+        if (run.id !== pointer.runId
+            || run.taskId !== taskId
+            || run.roleName !== roleName
+            || run.status !== "active"
+            || (run.executionGroupId === undefined) !== (run.executionLaneId === undefined)) {
+            throw new StorageRecordError(`Active AgentRun pointer is invalid: ${taskId}/${roleName}`);
+        }
+        return run;
+    }
+    #getActiveLaneRun(taskId, executionGroupId, executionLaneId) {
+        const pointerKey = executionLaneActiveRunKey(executionGroupId, executionLaneId);
+        const pointer = this.#readActiveRunPointer(taskId, pointerKey);
         if (pointer === null)
             return null;
         const task = this.getTask(taskId);
         if (task === null) {
-            throw new StorageRecordError(`Active Turn Task is missing: ${taskId}/${pointerKey}`);
+            throw new StorageRecordError(`Active AgentRun Task is missing: ${taskId}/${pointerKey}`);
         }
-        if (pointer.turn === null) {
-            if (task.status === "retired")
+        if (pointer.run === null) {
+            if (task.status === "cancelled" && task.retirementIsolation === true)
                 return null;
-            throw new StorageRecordError(`Active Turn pointer is dangling: ${taskId}/${pointerKey}`);
+            throw new StorageRecordError(`Active AgentRun pointer is dangling: ${taskId}/${pointerKey}`);
         }
-        const turn = pointer.turn;
-        if (task.status === "retired")
-            return turn;
-        if (turn.id !== pointer.turnId
-            || turn.taskId !== taskId
-            || turn.status !== "active"
-            || turn.executionGroupId !== executionGroupId
-            || turn.executionLaneId !== executionLaneId) {
-            throw new StorageRecordError(`Active Turn pointer is invalid: ${taskId}/${pointerKey}`);
+        const run = pointer.run;
+        if (task.status === "cancelled" && task.retirementIsolation === true)
+            return run;
+        if (run.id !== pointer.runId
+            || run.taskId !== taskId
+            || run.status !== "active"
+            || run.executionGroupId !== executionGroupId
+            || run.executionLaneId !== executionLaneId) {
+            throw new StorageRecordError(`Active AgentRun pointer is invalid: ${taskId}/${pointerKey}`);
         }
-        return turn;
+        return run;
     }
-    #clearActiveTurn(taskId, pointer) {
+    #clearActiveRun(taskId, pointer) {
         this.#mutate(() => {
             this.#db.prepare("DELETE FROM active_turns WHERE task_id = ? AND pointer = ?").run(taskId, pointer);
         });
     }
-    getActiveTurn(taskId, roleName) {
-        return this.#getActiveRoleTurn(taskId, roleName);
+    getActiveRun(taskId, roleName) {
+        return this.#getActiveRoleRun(taskId, roleName);
     }
-    saveActiveTurn(turn) {
-        if (turn.executionGroupId !== undefined || turn.executionLaneId !== undefined) {
-            this.saveActiveExecutionLaneTurn(turn);
+    saveActiveRun(run) {
+        if (run.executionGroupId !== undefined || run.executionLaneId !== undefined) {
+            this.saveActiveExecutionLaneRun(run);
             return;
         }
         this.transaction((store) => {
-            const task = store.getTask(turn.taskId);
-            if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
-                throw new StorageRecordError(`Task execution is not enabled: ${turn.taskId}.`);
+            const task = store.getTask(run.taskId);
+            assertRunAdmission(task, run);
+            this.#assertActiveRunForWrite(run);
+            const current = store.getActiveRun(run.taskId, run.roleName);
+            if (current !== null && current.id !== run.id) {
+                throw new StorageRecordError(`Role already has an active AgentRun: ${run.taskId}/${run.roleName}`);
             }
-            this.#assertActiveTurnForWrite(turn);
-            const current = store.getActiveTurn(turn.taskId, turn.roleName);
-            if (current !== null && current.id !== turn.id) {
-                throw new StorageRecordError(`Role already has an active Turn: ${turn.taskId}/${turn.roleName}`);
-            }
-            // Keep the Turn row and its active pointer in the same transaction. The
+            // Keep the AgentRun row and its active pointer in the same transaction. The
             // adapter may have already written the row; this upsert remains
             // intentionally idempotent for that backend-neutral path.
-            store.saveTurn(turn);
-            this.#saveActiveTurn(turn.taskId, turn.roleName, turn.id);
+            store.saveRun(run);
+            this.#saveActiveRun(run.taskId, run.roleName, run.id);
         });
     }
-    clearActiveTurn(taskId, roleName) {
-        // A Role key can point at a lane-backed Turn. Remove the matching lane
+    clearActiveRun(taskId, roleName) {
+        // A Role key can point at a lane-backed AgentRun. Remove the matching lane
         // pointer too while preserving every other lane for the same Role.
         this.transaction(() => {
-            const rolePointer = this.#readActiveTurnPointer(taskId, roleName);
-            this.#clearActiveTurn(taskId, roleName);
+            const rolePointer = this.#readActiveRunPointer(taskId, roleName);
+            this.#clearActiveRun(taskId, roleName);
             if (rolePointer === null)
                 return;
             const laneRows = this.#db.prepare("SELECT pointer, turn_id FROM active_turns WHERE task_id = ?").all(taskId);
             for (const row of laneRows) {
-                if (executionLaneActiveTurnKeyParts(row.pointer) !== null
-                    && row.turn_id === rolePointer.turnId) {
-                    this.#clearActiveTurn(taskId, row.pointer);
+                if (executionLaneActiveRunKeyParts(row.pointer) !== null
+                    && row.turn_id === rolePointer.runId) {
+                    this.#clearActiveRun(taskId, row.pointer);
                 }
             }
         });
     }
-    getActiveExecutionLaneTurn(taskId, executionGroupId, executionLaneId) {
-        return this.#getActiveLaneTurn(taskId, executionGroupId, executionLaneId);
+    getActiveExecutionLaneRun(taskId, executionGroupId, executionLaneId) {
+        return this.#getActiveLaneRun(taskId, executionGroupId, executionLaneId);
     }
-    saveActiveExecutionLaneTurn(turn) {
-        if (turn.executionGroupId === undefined || turn.executionLaneId === undefined) {
-            throw new StorageRecordError(`Active execution-lane Turn requires group and lane ids: ${turn.id}`);
+    saveActiveExecutionLaneRun(run) {
+        if (run.executionGroupId === undefined || run.executionLaneId === undefined) {
+            throw new StorageRecordError(`Active execution-lane AgentRun requires group and lane ids: ${run.id}`);
         }
         this.transaction((store) => {
-            const task = store.getTask(turn.taskId);
+            const task = store.getTask(run.taskId);
             if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
-                throw new StorageRecordError(`Task execution is not enabled: ${turn.taskId}.`);
+                throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
             }
-            const key = executionLaneActiveTurnKey(turn.executionGroupId, turn.executionLaneId);
-            this.#assertActiveTurnForWrite(turn, {
-                executionGroupId: turn.executionGroupId,
-                executionLaneId: turn.executionLaneId
+            const key = executionLaneActiveRunKey(run.executionGroupId, run.executionLaneId);
+            this.#assertActiveRunForWrite(run, {
+                executionGroupId: run.executionGroupId,
+                executionLaneId: run.executionLaneId
             });
-            const current = store.getActiveExecutionLaneTurn(turn.taskId, turn.executionGroupId, turn.executionLaneId);
-            if (current !== null && current.id !== turn.id) {
-                throw new StorageRecordError(`Execution Lane already has an active Turn: ${turn.taskId}/${key}`);
+            const current = store.getActiveExecutionLaneRun(run.taskId, run.executionGroupId, run.executionLaneId);
+            if (current !== null && current.id !== run.id) {
+                throw new StorageRecordError(`Execution Lane already has an active AgentRun: ${run.taskId}/${key}`);
             }
-            const rolePointer = this.#readActiveTurnPointer(turn.taskId, turn.roleName);
-            store.saveTurn(turn);
-            this.#saveActiveTurn(turn.taskId, key, turn.id);
+            const rolePointer = this.#readActiveRunPointer(run.taskId, run.roleName);
+            store.saveRun(run);
+            this.#saveActiveRun(run.taskId, key, run.id);
             // Keep the Role pointer for the single-lane delivery path, but never
             // replace it when another Lane already owns that Role.
             if (rolePointer === null) {
-                this.#saveActiveTurn(turn.taskId, turn.roleName, turn.id);
+                this.#saveActiveRun(run.taskId, run.roleName, run.id);
             }
         });
     }
-    clearActiveExecutionLaneTurn(taskId, executionGroupId, executionLaneId) {
+    clearActiveExecutionLaneRun(taskId, executionGroupId, executionLaneId) {
         this.transaction(() => {
-            const key = executionLaneActiveTurnKey(executionGroupId, executionLaneId);
-            const lanePointer = this.#readActiveTurnPointer(taskId, key);
-            this.#clearActiveTurn(taskId, key);
+            const key = executionLaneActiveRunKey(executionGroupId, executionLaneId);
+            const lanePointer = this.#readActiveRunPointer(taskId, key);
+            this.#clearActiveRun(taskId, key);
             if (lanePointer === null)
                 return;
             const roleRows = this.#db.prepare("SELECT pointer, turn_id FROM active_turns WHERE task_id = ?").all(taskId);
             for (const row of roleRows) {
-                if (executionLaneActiveTurnKeyParts(row.pointer) === null
-                    && row.turn_id === lanePointer.turnId) {
-                    this.#clearActiveTurn(taskId, row.pointer);
+                if (executionLaneActiveRunKeyParts(row.pointer) === null
+                    && row.turn_id === lanePointer.runId) {
+                    this.#clearActiveRun(taskId, row.pointer);
                 }
             }
         });
@@ -1862,7 +1997,7 @@ export class SqliteTaskStore {
            turn_id = excluded.turn_id,
            reasons = excluded.reasons,
            payload = excluded.payload,
-           consumed_at = excluded.consumed_at`).run(taskId, wake.id, wake.seq, wake.status, wake.turnId ?? null, wake.fromCursor, wake.toCursor, this.#json([...wake.reasons]), this.#json(wake), wake.createdAt, wake.consumedAt ?? null);
+           consumed_at = excluded.consumed_at`).run(taskId, wake.id, wake.seq, wake.status, wake.runId ?? null, wake.fromCursor, wake.toCursor, this.#json([...wake.reasons]), this.#json(wake), wake.createdAt, wake.consumedAt ?? null);
             this.#observeHighWater(taskId, "taskWake", seq);
         });
     }
@@ -1880,7 +2015,8 @@ export class SqliteTaskStore {
     // -- high-water maintenance ---------------------------------------------------
     /** Extract the numeric suffix of a `<prefix>-<n>` record id. */
     #idSequence(id, kind) {
-        const match = new RegExp(`^${TASK_RECORD_ID_PREFIXES[kind]}-(\\d+)$`).exec(id);
+        const prefix = kind === "run" ? "(?:run|turn)" : TASK_RECORD_ID_PREFIXES[kind];
+        const match = new RegExp(`^${prefix}-(\\d+)$`).exec(id);
         if (match === null)
             throw new StorageRecordError(`Task-local ${kind} id is invalid: ${id}.`);
         return Number.parseInt(match[1], 10);
@@ -2050,76 +2186,75 @@ export class SqliteTaskStore {
     }
     // -- telemetry (§4.4) -----------------------------------------------------------
     /**
-     * Upsert one progress row. The PK is (task_id, role_name, turn_id, generation,
+     * Upsert one progress row. The PK is (task_id, role_name, turn_id,
      * progress_id): a repeated progress id updates in place, so a high-frequency
      * runtime telemetry observation is a single-row write that never
      * rewrites global state or another Task's rows.
      */
     upsertTelemetryProgress(entry) {
         this.#mutate(() => {
-            this.#db.prepare(`INSERT INTO telemetry (task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-         ON CONFLICT(task_id, role_name, turn_id, generation, progress_id)
-         DO UPDATE SET sequence = excluded.sequence, payload = excluded.payload, received_at = excluded.received_at`).run(entry.taskId, entry.roleName, entry.turnId, entry.generation, entry.progressId, entry.sequence ?? null, this.#json(entry.payload), entry.receivedAt);
+            this.#db.prepare(`INSERT INTO telemetry (task_id, role_name, turn_id, progress_id, sequence, payload, received_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name, turn_id, progress_id)
+         DO UPDATE SET sequence = excluded.sequence, payload = excluded.payload, received_at = excluded.received_at`).run(entry.taskId, entry.roleName, entry.runId, entry.progressId, entry.sequence ?? null, this.#json(entry.payload), entry.receivedAt);
         });
     }
-    listTelemetry(taskId, turnId) {
-        const rows = turnId === undefined
-            ? this.#db.prepare("SELECT task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at").all(taskId)
-            : this.#db.prepare("SELECT task_id, role_name, turn_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? AND turn_id = ? ORDER BY received_at").all(taskId, turnId);
+    listTelemetry(taskId, runId) {
+        const rows = runId === undefined
+            ? this.#db.prepare("SELECT task_id, role_name, turn_id, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at").all(taskId)
+            : this.#db.prepare("SELECT task_id, role_name, turn_id, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? AND turn_id = ? ORDER BY received_at").all(taskId, runId);
         return rows
             .map((row) => ({
             taskId: row.task_id,
             roleName: row.role_name,
-            turnId: row.turn_id,
-            generation: row.generation,
+            runId: row.turn_id,
             progressId: row.progress_id,
             sequence: row.sequence ?? undefined,
             payload: this.#parse(row.payload),
             receivedAt: row.received_at
         }));
     }
-    countTelemetry(taskId, turnId) {
-        const row = turnId === undefined
+    countTelemetry(taskId, runId) {
+        const row = runId === undefined
             ? this.#db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ?").get(taskId)
-            : this.#db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND turn_id = ?").get(taskId, turnId);
+            : this.#db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND turn_id = ?").get(taskId, runId);
         return row.n;
     }
     /**
      * Bounded retention (§4.4): keep the newest `keep` rows per
-     * (task, role, run, generation) and delete older ones. The DELETE is scoped
+     * (task, role, AgentRun) and delete older ones. The DELETE is scoped
      * by task_id; it never rewrites global rows or other Tasks. Returns the number
      * of rows deleted. Terminal/semantic events go to `events` and are never pruned.
      */
-    pruneTelemetry(taskId, roleName, turnId, generation, keep = TELEMETRY_KEEP_PER_GENERATION) {
+    pruneTelemetry(taskId, roleName, runId, keep = TELEMETRY_KEEP_PER_RUN) {
         return this.#mutate(() => {
             const result = this.#db.prepare(`DELETE FROM telemetry
-         WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?
-           AND (task_id, role_name, turn_id, generation, progress_id) NOT IN (
-             SELECT task_id, role_name, turn_id, generation, progress_id
+         WHERE task_id = ? AND role_name = ? AND turn_id = ?
+           AND (task_id, role_name, turn_id, progress_id) NOT IN (
+             SELECT task_id, role_name, turn_id, progress_id
              FROM telemetry
-             WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?
-             ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+             WHERE task_id = ? AND role_name = ? AND turn_id = ?
+             ORDER BY received_at DESC, COALESCE(sequence, -1) DESC, progress_id ASC
              LIMIT ?
-           )`).run(taskId, roleName, turnId, generation, taskId, roleName, turnId, generation, keep);
+           )`).run(taskId, roleName, runId, taskId, roleName, runId, keep);
             return result.changes;
         });
     }
     /**
-     * Hard cap for an active Turn (§4.4): trim oldest rows across the Turn beyond
+     * Hard cap for an active AgentRun (§4.4): trim oldest rows across the AgentRun beyond
      * `cap` (default 50k). Returns the number of rows deleted.
      */
-    capTelemetryTurn(taskId, turnId, cap = TELEMETRY_TURN_CAP) {
+    capTelemetryRun(taskId, runId, cap = TELEMETRY_RUN_CAP) {
         return this.#mutate(() => {
             const result = this.#db.prepare(`DELETE FROM telemetry
          WHERE task_id = ? AND turn_id = ?
-           AND (task_id, role_name, turn_id, generation, progress_id) NOT IN (
-             SELECT task_id, role_name, turn_id, generation, progress_id
+           AND (task_id, role_name, turn_id, progress_id) NOT IN (
+             SELECT task_id, role_name, turn_id, progress_id
              FROM telemetry
              WHERE task_id = ? AND turn_id = ?
-             ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+             ORDER BY received_at DESC, COALESCE(sequence, -1) DESC, progress_id ASC
              LIMIT ?
-           )`).run(taskId, turnId, taskId, turnId, cap);
+           )`).run(taskId, runId, taskId, runId, cap);
             return result.changes;
         });
     }