@zq-silk/yui 0.15.7 → 0.15.9

package/dist/task/taskSubmission.js

@@ -0,0 +1,236 @@
+import { SYSTEM_LEADER_ROLE } from "../role/systemRoles.js";
+/**
+ * Requirement A phase and routing derivation (task-32 §2.1, §2.2).
+ *
+ * `Task.status` stays the only lifecycle statement. "Entered planning" is a
+ * derived fact, never a writable second state: this module reads it from the
+ * durable evidence a legitimate planning entry leaves behind, so idleness, a
+ * failed or replaced Session, a Controller restart, or a trimmed Context can
+ * never reset it to "not planned".
+ */
+/**
+ * The never-compacted event that records a Draft was routed into planning by an
+ * accepted user/operator submission, inside the same transaction that saved the
+ * message. It is one of the three independent derivation sources below, and the
+ * only one the shared submission service itself writes; the others are produced
+ * by the planning Run and its Session. Migration appends the same event for
+ * legitimate historical discussions so a post-upgrade develop cannot snatch a
+ * mid-discussion Draft into auto-activation.
+ */
+export const TASK_PLANNING_ENTERED_EVENT = "task.planning-entered";
+/**
+ * Whether this Draft has already entered planning (task-32 §2.2).
+ *
+ * Derived — never a stored flag — from any of three independent, monotonic
+ * sources, each of which only ever comes into existence and never legitimately
+ * disappears:
+ *
+ *  (a) a persisted planning-entered event, written in the message-save
+ *      transaction the first time an accepted submission routed to planning;
+ *  (b) a Leader planning AgentRun in history (the first-discuss Run, once the
+ *      Controller has created it);
+ *  (c) a Leader Session whose frozen launch carried planning authority.
+ *
+ * A role being configured, a non-empty body, or a non-empty Brief are
+ * deliberately NOT evidence: none of them proves the user's submission was ever
+ * accepted and routed. Only a Draft can be "in planning"; an active or terminal
+ * Task is past the question and answers false.
+ */
+export function draftHasEnteredPlanning(store, task) {
+    if (task.status !== "draft")
+        return false;
+    return hasPlanningEnteredEvent(store.listEvents(task.id))
+        || hasLeaderPlanningRun(store, task.id)
+        || hasLeaderPlanningSession(store, task.id);
+}
+function hasPlanningEnteredEvent(events) {
+    return events.some((event) => event.type === TASK_PLANNING_ENTERED_EVENT);
+}
+function hasLeaderPlanningRun(store, taskId) {
+    return store.listRuns(taskId).some((run) => run.roleName === SYSTEM_LEADER_ROLE && run.purpose === "planning");
+}
+function hasLeaderPlanningSession(store, taskId) {
+    const sessions = store.getTaskRoleSessionSet(taskId, SYSTEM_LEADER_ROLE);
+    if (sessions === null)
+        return false;
+    const candidates = [
+        ...Object.values(sessions.sessions ?? {}),
+        ...(sessions.history ?? [])
+    ];
+    return candidates.some((session) => session.effective.executionAuthority === "planning");
+}
+export function draftActivationState(request) {
+    if (request === undefined)
+        return "none";
+    switch (request.disposition) {
+        case "pending": return "pending";
+        case "failed": return "failed";
+        case "adopted": return "adopted";
+        case "cancelled": return "none";
+        default: return "none";
+    }
+}
+/**
+ * Decide how a user/operator submission routes, given its normalized intent and
+ * the phase/activation facts read inside the save transaction.
+ *
+ * This is a pure decision over already-read facts, kept separate from the
+ * transaction that saves the message and enqueues work so it can be unit-tested
+ * exhaustively against the §2.1 table without a Store. The winner of a race is
+ * decided by which submission's transaction commits first: the second one reads
+ * the phase/activation the first one already wrote and routes accordingly.
+ *
+ * `executionEnabled` is the Task's own gate, read in the same transaction. It
+ * only ever gates a *fresh* develop activation: recording an activation request
+ * against a stopped Draft is refused at the activation boundary, so routing that
+ * case to `activate` would abort the whole transaction and lose the saved
+ * message. Planning and already-open activation obligations are unaffected — the
+ * gate is enforced later at dispatch, exactly as it is for a plain message.
+ */
+export function decideSubmissionRouting(input) {
+    // record never wakes anything, in any state (§2.1 first column).
+    if (input.intent === "record")
+        return { kind: "record" };
+    if (input.status === "active") {
+        // Neither discuss nor develop re-activates or downgrades an active Task.
+        return { kind: "active-context" };
+    }
+    // Only Draft remains: terminal statuses are refused before routing (§2.1 last
+    // row) by the caller's assertTaskOpen, so this function is never asked about
+    // them.
+    if (input.activation === "pending") {
+        return input.intent === "develop"
+            // A compatible pending request already exists; reference it, never a
+            // second request (§2.3 "重复 develop 不产生第二个兼容激活请求").
+            ? { kind: "await-activation", state: "pending" }
+            // discuss becomes post-activation input; it does not start new planning.
+            : { kind: "await-activation", state: "pending" };
+    }
+    if (input.activation === "failed") {
+        // develop never auto-retries or downgrades to planning; discuss reports the
+        // original failure and the explicit retry/cancel next step. Both save only.
+        return { kind: "await-activation", state: "failed" };
+    }
+    if (input.intent === "develop") {
+        // develop on an already-planned Draft never auto-activates — it needs
+        // explicit manual activation. On an unplanned Draft with no open activation
+        // it records the request and routes to activation, unless execution is
+        // stopped: then the message is saved but no activation is recorded.
+        if (input.enteredPlanning)
+            return { kind: "planned-needs-manual-activation" };
+        return input.executionEnabled
+            ? { kind: "activate", environmentPlan: input.developEnvironmentPlan }
+            : { kind: "activation-blocked-execution-stopped" };
+    }
+    // discuss (the default): first discussion records the planning entry; later
+    // discussion continues the existing planning conversation.
+    return input.enteredPlanning
+        ? { kind: "continue-planning" }
+        : { kind: "enter-planning" };
+}
+/**
+ * Normalize a possibly-absent submission intent to its effective value.
+ *
+ * An absent intent is `discuss` (task-32 §2.5: "默认/旧客户端都按 discuss"), so
+ * every old client and every message saved before the field existed keeps its
+ * historical Leader-waking behaviour. Body text is never inspected.
+ *
+ * A legacy `--wake-policy none` carried the "save only, do not wake" meaning that
+ * `record` now names, so a caller that supplied only that older signal maps to
+ * `record` rather than silently becoming a Leader-waking `discuss`. An explicit
+ * intent always wins over the wake-policy shorthand.
+ */
+export function normalizeSubmissionIntent(intent, wakePolicy) {
+    if (intent !== undefined)
+        return intent;
+    if (wakePolicy === "none")
+        return "record";
+    return "discuss";
+}
+/**
+ * Whether a retry aims at the same target the key was first bound to (§2.3). An
+ * absent prior target (a keyed Message from before receipts existed) never
+ * matches, so such a Message is treated as a conflict rather than replayed from
+ * a fabricated disposition.
+ */
+export function sameSubmissionTarget(prior, next) {
+    if (prior === undefined || prior.kind !== next.kind)
+        return false;
+    if (prior.kind === "task" && next.kind === "task")
+        return prior.taskId === next.taskId;
+    return true;
+}
+/**
+ * Derive the §2.5 feedback for one committed submission from its routing and the
+ * facts read in the save transaction.
+ *
+ * Pure over already-read facts, so it is unit-testable against the whole table
+ * without a Store. `enteredPlanning` and `activationState` are the values read
+ * before routing executed; the routing itself names what the transaction then
+ * did, and phase is derived to reflect the post-commit truth (a just-entered
+ * planning Draft reports `draft-planning`).
+ */
+export function describeSubmissionFeedback(input) {
+    const { routing } = input;
+    const phase = input.status === "active"
+        ? "active"
+        : routing.kind === "enter-planning"
+            || routing.kind === "continue-planning"
+            || routing.kind === "planned-needs-manual-activation"
+            || input.enteredPlanning
+            ? "draft-planning"
+            : "draft-unplanned";
+    const planning = routing.kind === "enter-planning"
+        ? "entered"
+        : routing.kind === "continue-planning"
+            ? "continued"
+            : "none";
+    const activation = routing.kind === "activate"
+        ? "requested"
+        : routing.kind === "planned-needs-manual-activation"
+            ? "manual-required"
+            : routing.kind === "activation-blocked-execution-stopped"
+                ? "execution-stopped"
+                : routing.kind === "await-activation"
+                    ? routing.state
+                    // record and the planning routes report the existing obligation, if
+                    // any, truthfully without acting on it.
+                    : input.activationState === "pending"
+                        ? "pending"
+                        : input.activationState === "failed"
+                            ? "failed"
+                            : "none";
+    const delivery = routing.kind === "enter-planning"
+        || routing.kind === "continue-planning"
+        || routing.kind === "active-context"
+        ? "queued"
+        : "none";
+    const nextStep = submissionNextStep(input);
+    return {
+        saved: { taskId: input.taskId, messageId: input.messageId },
+        phase,
+        planning,
+        activation,
+        delivery,
+        ...(nextStep === undefined ? {} : { nextStep })
+    };
+}
+function submissionNextStep(input) {
+    if (input.routing.kind === "planned-needs-manual-activation") {
+        return { kind: "activate-manually", taskId: input.taskId };
+    }
+    if (input.routing.kind === "activation-blocked-execution-stopped") {
+        return { kind: "start-execution", taskId: input.taskId };
+    }
+    if (input.routing.kind === "await-activation") {
+        if (input.routing.state === "failed") {
+            return {
+                kind: "resolve-failed-activation",
+                activationRef: input.activationRef ?? "",
+                failure: input.activationFailure ?? "activation failed"
+            };
+        }
+        return { kind: "await-pending-activation", activationRef: input.activationRef ?? "" };
+    }
+    return undefined;
+}

package/dist/telemetry/sqliteTelemetryStore.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import Database from "better-sqlite3";
-import { DEFAULT_TURN_CAP, DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
+import { DEFAULT_RUN_CAP, DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
 import { migrateSqliteSchema } from "../storage/sqliteSchema.js";
 import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../storage/currentTaskStore.js";
 /**
@@ -18,7 +18,7 @@ import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../sto
  *
  * The telemetry tables are maintained by the centralized schema baseline:
  * `telemetry` holds the bounded latest-per-key window and
- * `telemetry_aggregate` holds the authoritative per-Turn/generation
+ * `telemetry_aggregate` holds the authoritative per-AgentRun
  * summary, maintained by triggers so it survives window pruning.
  */
 const MAX_PAGE_LIMIT = 500;
@@ -41,7 +41,7 @@ export class SqliteTelemetryStore {
         this.mode = options.mode ?? "on";
         this.#path = join(home, COMMITTED_DATABASE_FILENAME);
         this.#terminalKeep = options.terminalKeep ?? DEFAULT_TERMINAL_KEEP;
-        this.#turnCap = options.turnCap ?? DEFAULT_TURN_CAP;
+        this.#turnCap = options.runCap ?? DEFAULT_RUN_CAP;
         this.#maxPending = options.maxPending ?? 10_000;
     }
     // -- TelemetrySink -------------------------------------------------------------
@@ -89,53 +89,52 @@ export class SqliteTelemetryStore {
         this.#db = null;
     }
     // -- TelemetryReader -----------------------------------------------------------
-    count(taskId, turnId) {
+    count(taskId, runId) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         if (taskId === undefined) {
             return db.prepare("SELECT COUNT(*) AS n FROM telemetry").get().n;
         }
-        if (turnId === undefined) {
+        if (runId === undefined) {
             return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ?").get(taskId).n;
         }
-        return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND turn_id = ?").get(taskId, turnId).n;
+        return db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND turn_id = ?").get(taskId, runId).n;
     }
-    list(taskId, turnId, page = { limit: 100, offset: 0 }) {
+    list(taskId, runId, page = { limit: 100, offset: 0 }) {
         const db = this.#ensureDb();
         if (db === null)
             return { items: [], nextOffset: null };
         const limit = Math.min(Math.max(1, Math.trunc(page.limit)), MAX_PAGE_LIMIT);
         const offset = Math.max(0, Math.trunc(page.offset));
-        const rows = turnId === undefined
-            ? 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, progress_id LIMIT ? OFFSET ?").all(taskId, limit, offset)
-            : 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, progress_id LIMIT ? OFFSET ?").all(taskId, turnId, limit, offset);
+        const rows = runId === undefined
+            ? db.prepare("SELECT task_id, role_name, turn_id, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at, progress_id LIMIT ? OFFSET ?").all(taskId, limit, offset)
+            : 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, progress_id LIMIT ? OFFSET ?").all(taskId, runId, limit, offset);
         const items = rows.map(rowToEntry);
-        const total = this.count(taskId, turnId);
+        const total = this.count(taskId, runId);
         const nextOffset = offset + items.length < total ? offset + items.length : null;
         return { items, nextOffset };
     }
-    aggregate(taskId, turnId) {
+    aggregate(taskId, runId) {
         const db = this.#ensureDb();
         if (db === null)
             return null;
-        const rows = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND turn_id = ?").all(taskId, turnId);
+        const rows = db.prepare("SELECT task_id, role_name, turn_id, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND turn_id = ?").all(taskId, runId);
         if (rows.length === 0)
             return null;
         return mergeAggregates(rows);
     }
-    aggregateGeneration(taskId, roleName, turnId, generation) {
+    aggregateRoleRun(taskId, roleName, runId) {
         const db = this.#ensureDb();
         if (db === null)
             return null;
-        const row = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND role_name = ? AND turn_id = ? AND generation = ?").get(taskId, roleName, turnId, generation);
+        const row = db.prepare("SELECT task_id, role_name, turn_id, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? AND role_name = ? AND turn_id = ?").get(taskId, roleName, runId);
         if (row === undefined)
             return null;
         return {
             taskId: row.task_id,
             roleName: row.role_name,
-            turnId: row.turn_id,
-            generation: row.generation,
+            runId: row.turn_id,
             firstAt: row.first_at,
             lastAt: row.last_at,
             count: row.count,
@@ -143,16 +142,15 @@ export class SqliteTelemetryStore {
             errorCount: row.error_count
         };
     }
-    listTurnAggregates(taskId) {
+    listRunAggregates(taskId) {
         const db = this.#ensureDb();
         if (db === null)
             return [];
-        const rows = db.prepare("SELECT task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? ORDER BY turn_id, generation").all(taskId);
+        const rows = db.prepare("SELECT task_id, role_name, turn_id, first_at, last_at, count, max_sequence, error_count FROM telemetry_aggregate WHERE task_id = ? ORDER BY turn_id").all(taskId);
         return rows.map((row) => ({
             taskId: row.task_id,
             roleName: row.role_name,
-            turnId: row.turn_id,
-            generation: row.generation,
+            runId: row.turn_id,
             firstAt: row.first_at,
             lastAt: row.last_at,
             count: row.count,
@@ -164,52 +162,51 @@ export class SqliteTelemetryStore {
         return this.#applied;
     }
     // -- retention -----------------------------------------------------------------
-    pruneGeneration(taskId, roleName, turnId, generation, keep = this.#terminalKeep) {
+    pruneRun(taskId, roleName, runId, keep = this.#terminalKeep) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         const result = 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 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 = ?
+         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 = ?
+           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;
     }
-    capTurn(taskId, turnId, cap = this.#turnCap) {
+    capRun(taskId, runId, cap = this.#turnCap) {
         const db = this.#ensureDb();
         if (db === null)
             return 0;
         const result = 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 FROM telemetry
+         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;
     }
-    importGeneration(entries, aggregate) {
+    importRun(entries, aggregate) {
         const db = this.#ensureDb();
         if (db === null) {
             this.#dropped += entries.length;
             return;
         }
-        const upsert = 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
+        const upsert = 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
-       WHERE COALESCE(excluded.sequence, -1) > COALESCE(telemetry.sequence, -1)
-          OR (excluded.sequence IS telemetry.sequence AND excluded.received_at >= telemetry.received_at)`);
+       WHERE excluded.received_at >= telemetry.received_at`);
         const upsertAggregate = db.prepare(`INSERT INTO telemetry_aggregate
-         (task_id, role_name, turn_id, generation, first_at, last_at, count, max_sequence, error_count, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(task_id, role_name, turn_id, generation) DO UPDATE SET
+         (task_id, role_name, turn_id, first_at, last_at, count, max_sequence, error_count, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(task_id, role_name, turn_id) DO UPDATE SET
          first_at = excluded.first_at,
          last_at = excluded.last_at,
          count = excluded.count,
@@ -218,9 +215,9 @@ export class SqliteTelemetryStore {
          updated_at = excluded.updated_at`);
         db.transaction(() => {
             for (const entry of entries) {
-                upsert.run(entry.taskId, entry.roleName, entry.turnId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
+                upsert.run(entry.taskId, entry.roleName, entry.runId, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
             }
-            upsertAggregate.run(aggregate.taskId, aggregate.roleName, aggregate.turnId, aggregate.generation, aggregate.firstAt, aggregate.lastAt, aggregate.count, aggregate.maxSequence, aggregate.errorCount, aggregate.lastAt);
+            upsertAggregate.run(aggregate.taskId, aggregate.roleName, aggregate.runId, aggregate.firstAt, aggregate.lastAt, aggregate.count, aggregate.maxSequence, aggregate.errorCount, aggregate.lastAt);
         })();
         this.#applied += entries.length;
     }
@@ -277,26 +274,25 @@ export class SqliteTelemetryStore {
         }
         const batch = new Map(this.#pending);
         this.#pending.clear();
-        const upsert = 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
+        const upsert = 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
-       WHERE COALESCE(excluded.sequence, -1) > COALESCE(telemetry.sequence, -1)
-          OR (excluded.sequence IS telemetry.sequence AND excluded.received_at >= telemetry.received_at)`);
+       WHERE excluded.received_at >= telemetry.received_at`);
         try {
-            const touchedTurns = new Map();
+            const touchedRuns = new Map();
             db.transaction(() => {
                 for (const entry of batch.values()) {
-                    upsert.run(entry.taskId, entry.roleName, entry.turnId, entry.generation, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
-                    touchedTurns.set(`${entry.taskId}\0${entry.turnId}`, {
+                    upsert.run(entry.taskId, entry.roleName, entry.runId, entry.progressId, entry.sequence ?? null, JSON.stringify(entry.payload), entry.receivedAt);
+                    touchedRuns.set(`${entry.taskId}\0${entry.runId}`, {
                         taskId: entry.taskId,
-                        turnId: entry.turnId
+                        runId: entry.runId
                     });
                 }
-                for (const { taskId, turnId } of touchedTurns.values()) {
-                    this.capTurn(taskId, turnId);
+                for (const { taskId, runId } of touchedRuns.values()) {
+                    this.capRun(taskId, runId);
                 }
             })();
             this.#applied += batch.size;
@@ -308,25 +304,17 @@ export class SqliteTelemetryStore {
     }
 }
 function pendingKey(entry) {
-    return `${entry.taskId}\u0000${entry.roleName}\u0000${entry.turnId}\u0000${entry.generation}\u0000${entry.progressId}`;
+    return `${entry.taskId}\u0000${entry.roleName}\u0000${entry.runId}\u0000${entry.progressId}`;
 }
-/** True when `candidate` should replace `current` (sequence/receivedAt only move forward). */
+/** Transport counters may restart; the later recorded observation wins. */
 function isNewer(candidate, current) {
-    if (candidate.sequence !== undefined && current.sequence !== undefined) {
-        return candidate.sequence > current.sequence;
-    }
-    if (candidate.sequence !== undefined)
-        return true;
-    if (current.sequence !== undefined)
-        return false;
     return Date.parse(candidate.receivedAt) >= Date.parse(current.receivedAt);
 }
 function rowToEntry(row) {
     return {
         taskId: row.task_id,
         roleName: row.role_name,
-        turnId: row.turn_id,
-        generation: row.generation,
+        runId: row.turn_id,
         progressId: row.progress_id,
         ...(row.sequence === null ? {} : { sequence: row.sequence }),
         payload: JSON.parse(row.payload),
@@ -356,8 +344,7 @@ function mergeAggregates(rows) {
     return {
         taskId: rows[0].task_id,
         roleName,
-        turnId: rows[0].turn_id,
-        generation: "*",
+        runId: rows[0].turn_id,
         firstAt,
         lastAt,
         count,

package/dist/telemetry/telemetryConfig.js

@@ -6,34 +6,34 @@
  * never changes canonical runtime-state persistence. Retention defaults are
  * the schema's own constants (§4.4); the environment only overrides them.
  */
-import { TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_TURN_CAP } from "../storage/sqliteSchema.js";
+import { TELEMETRY_KEEP_PER_RUN, TELEMETRY_RUN_CAP } from "../storage/sqliteSchema.js";
 export const DEFAULT_TELEMETRY_MODE = "off";
-/** Terminal Turn/generation progress rows retained after prune. */
-export const DEFAULT_TERMINAL_KEEP = TELEMETRY_KEEP_PER_GENERATION;
-/** Hard cap of progress rows per Turn while it is still active. */
-export const DEFAULT_TURN_CAP = TELEMETRY_TURN_CAP;
+/** Terminal AgentRun progress rows retained after prune. */
+export const DEFAULT_TERMINAL_KEEP = TELEMETRY_KEEP_PER_RUN;
+/** Hard cap of progress rows per AgentRun while it is still active. */
+export const DEFAULT_RUN_CAP = TELEMETRY_RUN_CAP;
 /**
- * Absolute ceiling for the configurable Turn cap. Retention can be tuned but
+ * Absolute ceiling for the configurable AgentRun cap. Retention can be tuned but
  * never disabled: every Home keeps a computable upper bound on telemetry
- * rows (Tasks × Turns × cap).
+ * rows (Tasks × AgentRuns × cap).
  */
-export const MAX_TURN_CAP = 10_000_000;
+export const MAX_RUN_CAP = 10_000_000;
 /**
- * Resolve the terminal-Turn retention window from the durable config value
+ * Resolve the terminal-AgentRun retention window from the durable config value
  * (default 200). Must be a positive integer.
  */
 export function resolveTerminalKeep(value) {
     return resolvePositiveInteger(value, DEFAULT_TERMINAL_KEEP, "telemetryTerminalKeep");
 }
 /**
- * Resolve the active-Turn hard cap from the durable config value (default
+ * Resolve the active-AgentRun hard cap from the durable config value (default
  * 50,000). Must be a positive integer not exceeding {@link MAX_TURN_CAP};
  * the cap cannot be disabled.
  */
-export function resolveTurnCap(value) {
-    const cap = resolvePositiveInteger(value, DEFAULT_TURN_CAP, "telemetryTurnCap");
-    if (cap > MAX_TURN_CAP) {
-        throw new TypeError(`telemetryTurnCap must not exceed ${MAX_TURN_CAP.toLocaleString("en-US")} (retention cannot be disabled).`);
+export function resolveRunCap(value) {
+    const cap = resolvePositiveInteger(value, DEFAULT_RUN_CAP, "telemetryRunCap");
+    if (cap > MAX_RUN_CAP) {
+        throw new TypeError(`telemetryTurnCap must not exceed ${MAX_RUN_CAP.toLocaleString("en-US")} (retention cannot be disabled).`);
     }
     return cap;
 }

package/dist/telemetry/telemetryWiring.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { resolveTurnCap, resolveTerminalKeep } from "./telemetryConfig.js";
+import { resolveRunCap, resolveTerminalKeep } from "./telemetryConfig.js";
 import { resolveTelemetryEnabled } from "../config/yuiConfig.js";
 import { SqliteTelemetryStore } from "./sqliteTelemetryStore.js";
 import { CURRENT_DATABASE_FILENAME as COMMITTED_DATABASE_FILENAME } from "../storage/currentTaskStore.js";
@@ -22,7 +22,7 @@ export function openSchedulerTelemetry(home, config) {
     const store = new SqliteTelemetryStore(home, {
         mode,
         terminalKeep: resolveTerminalKeep(config.telemetryTerminalKeep),
-        turnCap: resolveTurnCap(config.telemetryTurnCap)
+        runCap: resolveRunCap(config.telemetryRunCap)
     });
     return { mode, sink: store, reader: store, retention: store };
 }

package/dist/web/assets/assetManifest.js

@@ -8,6 +8,7 @@ import { I18N_SCRIPT } from "./client/i18n.js";
 import { MARKDOWN_SCRIPT } from "./client/markdown.js";
 import { THEME_SCRIPT } from "./client/theme.js";
 import { VIEW_SCRIPT } from "./client/view.js";
+import { TASK_SURFACE_SCRIPT } from "./client/taskSurface.js";
 import { DASHBOARD_HTML } from "./shell.js";
 import { FONT_FACE_STYLES } from "./fonts.js";
 import { FONT_WOFF2_BASE64 } from "./fontData.js";
@@ -33,6 +34,7 @@ export const WEB_ASSETS = Object.freeze({
     "/assets/js/theme.js": { contentType: "text/javascript; charset=utf-8", body: THEME_SCRIPT },
     "/assets/js/components.js": { contentType: "text/javascript; charset=utf-8", body: COMPONENTS_SCRIPT },
     "/assets/js/view.js": { contentType: "text/javascript; charset=utf-8", body: VIEW_SCRIPT },
+    "/assets/js/task-surface.js": { contentType: "text/javascript; charset=utf-8", body: TASK_SURFACE_SCRIPT },
     "/assets/app.js": { contentType: "text/javascript; charset=utf-8", body: APP_SCRIPT },
     ...fontAssets(),
     "/assets/vendor/xterm.mjs": vendorAsset("@xterm/xterm/lib/xterm.mjs", "text/javascript; charset=utf-8"),