@zq-silk/yui 0.15.7 → 0.15.8

package/dist/runtime/sessionOwnerIdentity.js

@@ -1,5 +1,9 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { requireSafeIdentity, requireText, requireTimestamp } from "./validation.js";
+/** A concrete OS process identity, not an Agent launch identity. */
+export function sessionOwnerProcessKey(record) {
+    return `${record.providerRoot.pid}-${record.providerRoot.startIdentity}`;
+}
 /** Validates and freezes one physical owner record; fails closed on malformed input. */
 export function createSessionOwnerIdentity(input) {
     const owner = input.owner;
@@ -13,6 +17,9 @@ export function createSessionOwnerIdentity(input) {
         throw new TypeError("Global session owner must not carry a task id.");
     }
     const providerRoot = input.providerRoot;
+    if (!["launch-env", "pane-pid", "owned-child"].includes(providerRoot.attribution)) {
+        throw new TypeError("Session owner process attribution is invalid.");
+    }
     if (!Number.isSafeInteger(providerRoot.pid) || providerRoot.pid <= 0) {
         throw new TypeError("Session owner provider root pid is invalid.");
     }
@@ -38,7 +45,6 @@ export function createSessionOwnerIdentity(input) {
         }),
         agentId: requireSafeIdentity(input.agentId, "Agent id"),
         adapterId: requireText(input.adapterId, "Adapter id"),
-        runtimeGenerationId: requireSafeIdentity(input.runtimeGenerationId, "Runtime generation id"),
         ...(input.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") }),
@@ -133,59 +139,6 @@ export function isLinuxProcessLive(pid, startIdentity) {
         return false;
     return current.startIdentity === startIdentity;
 }
-/**
- * Discovers the Provider root for one launch by the exact YUI_RUNTIME_GENERATION_ID
- * environment fence. Returns undefined when no same-user process carries the
- * fence — the caller must not guess from a process name or cwd.
- */
-export function discoverProviderRootByLaunchEnv(runtimeGenerationId) {
-    const matches = listLaunchFencedProcesses(runtimeGenerationId);
-    for (const pid of matches) {
-        const identity = readLinuxProcessIdentity(pid);
-        if (identity !== undefined)
-            return { pid, identity };
-    }
-    return undefined;
-}
-/**
- * Lists every live process whose initial environment carries the exact
- * `YUI_RUNTIME_GENERATION_ID=<runtimeGenerationId>` fence. The fence is inherited by Provider
- * children, so this is the exact, PID-reuse-safe attribution for a surviving
- * child after its root has exited: a recycled PID never carries the fence.
- * Processes without the fence are unattributed and must never be signaled.
- */
-export function listLaunchFencedProcesses(runtimeGenerationId) {
-    if (!Number.isSafeInteger(runtimeGenerationId) && !/^[A-Za-z0-9_.:-]+$/u.test(runtimeGenerationId)) {
-        return [];
-    }
-    let entries;
-    try {
-        entries = readdirSync("/proc", { encoding: "utf8" });
-    }
-    catch {
-        return [];
-    }
-    const needle = `YUI_RUNTIME_GENERATION_ID=${runtimeGenerationId}`;
-    const matches = [];
-    for (const entry of entries) {
-        if (!/^[0-9]+$/u.test(entry))
-            continue;
-        const pid = Number(entry);
-        if (!Number.isSafeInteger(pid) || pid <= 0)
-            continue;
-        let environment;
-        try {
-            environment = readFileSync(`/proc/${pid}/environ`, "utf8");
-        }
-        catch {
-            continue;
-        }
-        if (!environment.includes(needle))
-            continue;
-        matches.push(pid);
-    }
-    return matches;
-}
 /**
  * Lists the process tree owned by one Provider root: the root itself plus
  * descendants proven by process-group membership or an ancestor chain. A

package/dist/runtime/sessionOwnerRegistry.js

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { createSessionOwnerIdentity } from "./sessionOwnerIdentity.js";
+import { createSessionOwnerIdentity, sessionOwnerProcessKey } from "./sessionOwnerIdentity.js";
 /**
- * Durable, enumerable physical owner records for runtime generations.
+ * Durable, enumerable physical owner records for runtime Sessions.
  *
- * One JSON file per runtime generation id under `<home>/runtime/session-owners/`. The
+ * One JSON file per process identity under `<home>/runtime/session-owners/`. The
  * directory is runtime state (like the tmux socket), not aggregate domain
  * state, so it needs no schema migration; it survives a Controller restart and
  * stays enumerable after the durable Session map or history is cleared, which
@@ -19,19 +19,19 @@ export class FileSessionOwnerRegistry {
     get directory() {
         return this.#directory;
     }
-    /** Atomically records (or replaces) one generation's owner identity. */
+    /** Atomically records (or replaces) one Session's owner identity. */
     record(identity) {
         mkdirSync(this.#directory, { recursive: true, mode: 0o700 });
-        const target = this.#path(identity.runtimeGenerationId);
+        const target = this.#path(sessionOwnerProcessKey(identity));
         const temporary = `${target}.tmp-${process.pid}`;
         writeFileSync(temporary, JSON.stringify(identity, null, 2) + "\n", { mode: 0o600 });
         renameSync(temporary, target);
     }
-    get(runtimeGenerationId) {
-        if (!isSafeRuntimeGenerationId(runtimeGenerationId))
+    get(processKey) {
+        if (!isSafeProcessKey(processKey))
             return null;
         try {
-            return parseOwnerRecord(readFileSync(this.#path(runtimeGenerationId), "utf8"));
+            return parseOwnerRecord(readFileSync(this.#path(processKey), "utf8"));
         }
         catch {
             return null;
@@ -66,11 +66,11 @@ export class FileSessionOwnerRegistry {
             && record.owner.roleName === owner.roleName));
     }
     /** Removes a record whose physical resources were proven absent. */
-    remove(runtimeGenerationId) {
-        if (!isSafeRuntimeGenerationId(runtimeGenerationId))
+    remove(processKey) {
+        if (!isSafeProcessKey(processKey))
             return;
         try {
-            rmSync(this.#path(runtimeGenerationId), { force: true });
+            rmSync(this.#path(processKey), { force: true });
         }
         catch {
             // A stale record is harmless: reconciliation re-verifies physical
@@ -80,12 +80,14 @@ export class FileSessionOwnerRegistry {
     exists() {
         return existsSync(this.#directory);
     }
-    #path(runtimeGenerationId) {
-        return join(this.#directory, `${runtimeGenerationId}.json`);
+    #path(processKey) {
+        if (!isSafeProcessKey(processKey))
+            throw new Error("Invalid process key.");
+        return join(this.#directory, `${processKey}.json`);
     }
 }
-function isSafeRuntimeGenerationId(runtimeGenerationId) {
-    return /^[A-Za-z0-9_.:-]+$/u.test(runtimeGenerationId);
+function isSafeProcessKey(processKey) {
+    return /^[1-9][0-9]*-[0-9]+$/u.test(processKey);
 }
 function parseOwnerRecord(raw) {
     const parsed = JSON.parse(raw);
@@ -96,6 +98,9 @@ function parseOwnerRecord(raw) {
     const owner = record.owner;
     const tmux = record.tmux;
     const providerRoot = record.providerRoot;
+    if (!["launch-env", "pane-pid", "owned-child"].includes(String(providerRoot.attribution))) {
+        throw new Error("Session owner process attribution is invalid.");
+    }
     return createSessionOwnerIdentity({
         owner: {
             scope: owner.scope === "global" ? "global" : "task",
@@ -104,7 +109,6 @@ function parseOwnerRecord(raw) {
         },
         agentId: String(record.agentId),
         adapterId: String(record.adapterId),
-        runtimeGenerationId: String(record.runtimeGenerationId),
         ...(record.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: String(record.nativeSessionId) }),
@@ -124,7 +128,8 @@ function parseOwnerRecord(raw) {
             ...(providerRoot.processSessionId === undefined
                 ? {}
                 : { processSessionId: Number(providerRoot.processSessionId) }),
-            attribution: providerRoot.attribution === "pane-pid" ? "pane-pid" : "launch-env"
+            attribution: providerRoot.attribution === "pane-pid" ? "pane-pid"
+                : providerRoot.attribution === "owned-child" ? "owned-child" : "launch-env"
         },
         ...(record.runtimeRoot === undefined ? {} : { runtimeRoot: String(record.runtimeRoot) }),
         recordedAt: new Date(String(record.recordedAt))

package/dist/runtime/sessionReconciliation.js

@@ -1,11 +1,11 @@
 /**
- * Bidirectional durable <-> physical reconciliation for Runtime generations.
+ * Bidirectional durable <-> physical reconciliation for Runtime Sessions.
  *
  * Durable -> physical: every owner record's Provider root must be absent once
  * its durable Session is terminal; a live root with a terminal durable state
  * is the exact leak the audit found. Physical -> durable: the owner registry
  * stays enumerable after the durable Session map or history is cleared, so a
- * live generation can always be re-attributed and reported.
+ * live Session can always be re-attributed and reported.
  *
  * Pure: all I/O is injected. Unknown owners are reported, never cleaned.
  * An entry is archive-blocking when its durable state is terminal but the
@@ -34,7 +34,7 @@ function reconcileOne(record, input) {
         ? input.taskStatus(owner.taskId)
         : undefined;
     const tmuxPane = input.inspectPane(owner.taskId, owner.roleName);
-    const lastStopOutcome = input.lastStopOutcome(owner.taskId, owner.roleName, record.runtimeGenerationId);
+    const lastStopOutcome = input.lastStopOutcome(owner.taskId, owner.roleName);
     let mismatch;
     let verificationGap;
     if (physical?.identityConflict === true) {
@@ -52,7 +52,7 @@ function reconcileOne(record, input) {
         mismatch = "durable-live-physical-absent";
     }
     const terminalTask = taskStatus === "completed"
-        || taskStatus === "retired"
+        || taskStatus === "cancelled"
         || taskStatus === "archived";
     const archiveBlocked = mismatch === "durable-terminal-physical-live"
         && terminalTask;
@@ -64,7 +64,6 @@ function reconcileOne(record, input) {
         },
         agentId: record.agentId,
         adapterId: record.adapterId,
-        runtimeGenerationId: record.runtimeGenerationId,
         ...(record.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: record.nativeSessionId }),
@@ -83,9 +82,6 @@ function matchDurable(record, durable) {
         && fact.roleName === record.owner.roleName
         && (record.owner.scope === "global" || fact.taskId === record.owner.taskId)
         && fact.agentId === record.agentId));
-    const byLaunch = candidates.find((fact) => fact.runtimeGenerationId !== undefined && fact.runtimeGenerationId === record.runtimeGenerationId);
-    if (byLaunch !== undefined)
-        return byLaunch;
     const byNative = candidates.find((fact) => fact.nativeSessionId !== undefined
         && record.nativeSessionId !== undefined
         && fact.nativeSessionId === record.nativeSessionId);

package/dist/runtime/sessionTerminationGuard.js

@@ -2,279 +2,90 @@ export const DEFAULT_GRACEFUL_GRACE_MS = 3_000;
 export const DEFAULT_FORCED_GRACE_MS = 2_000;
 export const DEFAULT_TERMINATION_POLL_MS = 100;
 /**
- * Stops one Role owner with physical exit proof.
- *
- * Sequence: graceful exact-owner tmux stop -> bounded grace -> forced
- * SIGTERM/SIGKILL of the exact Provider root and its process group -> final
- * /proc re-verification. Only when every owned root is absent (PID gone or
- * start identity changed) does the result become `stop-confirmed`; otherwise
- * the Session stays non-terminal and the caller must not commit `stopped`.
- *
- * PID reuse is handled structurally: liveness always pairs the PID with its
- * recorded start identity, so a recycled PID is treated as absent and never
- * signaled.
+ * Stop only recorded Host roots. Descendants remain observable resources;
+ * neither a shared environment nor a process group authorizes killing them.
  */
 export async function terminateSessionOwners(owner, records, ports, options = {}) {
-    const gracefulGraceMs = positiveDuration(options.gracefulGraceMs, DEFAULT_GRACEFUL_GRACE_MS, "gracefulGraceMs");
-    const forcedGraceMs = positiveDuration(options.forcedGraceMs, DEFAULT_FORCED_GRACE_MS, "forcedGraceMs");
-    const pollMs = positiveDuration(options.pollMs, DEFAULT_TERMINATION_POLL_MS, "pollMs");
-    const now = ports.now();
-    ports.emit({ stage: "stop-requested", owner, at: now });
-    // Persist one exact launch receipt before any graceful stop can kill the
-    // Host. The owner-wide event remains for compatibility and summary display.
-    for (const record of records) {
-        ports.emit({
-            stage: "stop-requested",
-            owner,
-            runtimeGenerationId: record.runtimeGenerationId,
-            ...(record.nativeSessionId === undefined
-                ? {}
-                : { nativeSessionId: record.nativeSessionId }),
-            at: now
-        });
-    }
-    // A launch-fence scan is a point-in-time observation, not a durable owner
-    // inventory: /proc entries can disappear between the directory and
-    // environment reads. Retain every exact child identity observed during the
-    // stop so one later scan miss cannot be mistaken for physical zero.
-    const trackedChildren = new Map(records.map((record) => [record.runtimeGenerationId, new Map()]));
+    const emit = (stage, detail) => {
+        try {
+            ports.emit({ stage, owner, at: ports.now(), ...(detail ? { detail } : {}) });
+        }
+        catch { /* Audit failure never broadens process authority. */ }
+    };
+    const state = (record) => {
+        const { pid, startIdentity } = record.providerRoot;
+        const observed = ports.processIdentity(pid);
+        if (observed === undefined)
+            return ports.procEntryExists(pid) ? "unknown" : "absent";
+        return observed.startIdentity !== startIdentity || observed.state === "Z"
+            ? "absent" : "live";
+    };
     for (const record of records) {
-        refreshTrackedFencedChildren(record, ports, trackedChildren);
-    }
-    let gracefulOk = true;
-    try {
-        gracefulOk = await ports.gracefulStop(owner);
-    }
-    catch (error) {
-        gracefulOk = false;
-        ports.emit({
-            stage: "graceful-stop",
-            owner,
-            detail: error instanceof Error ? error.message : String(error),
-            at: ports.now()
-        });
-    }
-    if (gracefulOk) {
-        ports.emit({ stage: "graceful-stop", owner, at: ports.now() });
+        if (record.owner.scope !== owner.scope || record.owner.roleName !== owner.roleName
+            || (owner.scope === "task" && record.owner.taskId !== owner.taskId)) {
+            throw new Error("Process record does not belong to the requested Role.");
+        }
     }
+    emit("stop-requested");
     if (records.length === 0) {
-        // No physical owner record: tmux-level cleanup is the only proof
-        // available. Report the gap rather than claiming physical zero.
+        // Without a recorded root only the exact Role pane can be stopped.
+        const stopped = await ports.gracefulStop(owner);
+        const outcome = stopped ? "stop-confirmed" : "stop-blocked";
+        emit(outcome);
         return {
-            outcome: gracefulOk ? "stop-confirmed" : "stop-blocked",
-            owner,
-            confirmed: [],
-            remaining: [],
-            ...(gracefulOk
-                ? {}
-                : { verificationGap: "no-owner-record: tmux stop unconfirmed" })
+            outcome, owner, confirmed: [], remaining: [],
+            ...(stopped ? {} : { verificationGap: "Role pane stop is unconfirmed." })
         };
     }
-    // Bounded graceful grace: poll the exact owned trees for exit.
-    if (await waitForTreesAbsent(records, ports, trackedChildren, gracefulGraceMs, pollMs)) {
-        ports.emit({ stage: "stop-confirmed", owner, at: ports.now() });
-        return {
-            outcome: "stop-confirmed",
-            owner,
-            confirmed: records,
-            remaining: []
-        };
-    }
-    // Forced escalation against the exact roots only. A root whose identity
-    // cannot be verified (verification gap) is never signaled: PID reuse
-    // safety requires pairing the PID with its start identity.
-    ports.emit({ stage: "forced-stop", owner, at: ports.now() });
-    for (const record of records) {
-        escalateRecord(record, ports, trackedChildren, "SIGTERM");
-    }
-    await waitForTreesAbsent(records, ports, trackedChildren, forcedGraceMs, pollMs);
-    for (const record of records) {
-        escalateRecord(record, ports, trackedChildren, "SIGKILL");
-    }
-    await waitForTreesAbsent(records, ports, trackedChildren, forcedGraceMs, pollMs);
-    const remaining = [];
-    const confirmed = [];
-    let verificationGap;
-    for (const record of records) {
-        const verdict = treeVerdict(record, ports, trackedChildren);
-        if (verdict.kind === "absent") {
-            confirmed.push(record);
-            continue;
-        }
-        if (verdict.kind === "gap") {
-            verificationGap = `/proc unreadable for launch ${record.runtimeGenerationId}`;
-            remaining.push({ record, detail: verificationGap });
-            continue;
-        }
-        const root = rootVerdict(record, ports);
-        remaining.push({
-            record,
-            detail: root.kind === "live"
-                ? `provider root pid ${record.providerRoot.pid} still live`
-                : `provider children still live for launch ${record.runtimeGenerationId}`
-        });
-    }
-    const outcome = remaining.length === 0 ? "stop-confirmed" : "stop-blocked";
-    ports.emit({
-        stage: outcome === "stop-confirmed" ? "stop-confirmed" : "stop-blocked",
-        owner,
-        ...(outcome === "stop-blocked"
-            ? {
-                detail: remaining
-                    .map(({ record, detail }) => `${record.runtimeGenerationId}: ${detail}`)
-                    .join("; ")
-            }
-            : {}),
-        at: ports.now()
-    });
-    return {
-        outcome,
-        owner,
-        confirmed,
-        remaining,
-        ...(verificationGap === undefined ? {} : { verificationGap })
-    };
-}
-function rootVerdict(record, ports) {
-    const { pid, startIdentity } = record.providerRoot;
-    const current = ports.processIdentity(pid);
-    if (current === undefined) {
-        // /proc unreadable or entry gone. Gone is absent; unreadable is a gap.
-        return ports.procEntryExists(pid) ? { kind: "gap" } : { kind: "absent" };
-    }
-    // A zombie has already exited; only the unreaped task struct remains. It
-    // cannot execute or hold resources, so it counts as absent for physical
-    // exit proof (the parent reaping the zombie does not change liveness).
-    if (current.state === "Z")
-        return { kind: "absent" };
-    return current.startIdentity === startIdentity
-        ? { kind: "live" }
-        : { kind: "absent" };
-}
-/**
- * Verdict for the whole owned tree: the Provider root plus any surviving
- * child carrying the exact launch fence. A verification gap counts as
- * present: the grace polls must not short-circuit to `stop-confirmed` while
- * `/proc` is unreadable, because that would claim physical zero without
- * proof. The final verdict turns a persistent gap into `stop-blocked`.
- */
-function treeVerdict(record, ports, trackedChildren) {
-    const scanGap = refreshTrackedFencedChildren(record, ports, trackedChildren);
-    const root = rootVerdict(record, ports);
-    const children = trackedChildrenVerdict(record, ports, trackedChildren);
-    if (root.kind === "live" || children.kind === "live")
-        return { kind: "live" };
-    if (root.kind === "gap" || children.kind === "gap" || scanGap)
-        return { kind: "gap" };
-    return { kind: "absent" };
-}
-function refreshTrackedFencedChildren(record, ports, trackedChildren) {
-    const tracked = trackedChildren.get(record.runtimeGenerationId);
-    if (tracked === undefined)
-        return true;
-    let verificationGap = false;
-    for (const pid of ports.listLaunchFencedProcesses(record.runtimeGenerationId)) {
-        if (pid === record.providerRoot.pid)
-            continue;
-        const identity = ports.processIdentity(pid);
-        if (identity === undefined) {
-            if (ports.procEntryExists(pid))
-                verificationGap = true;
-            continue;
-        }
-        if (identity.state === "Z")
-            continue;
-        tracked.set(pid, identity.startIdentity);
-    }
-    return verificationGap;
-}
-function trackedChildrenVerdict(record, ports, trackedChildren) {
-    const tracked = trackedChildren.get(record.runtimeGenerationId);
-    if (tracked === undefined)
-        return { kind: "gap" };
-    let verificationGap = false;
-    for (const [pid, startIdentity] of tracked) {
-        const current = ports.processIdentity(pid);
-        if (current === undefined) {
-            if (ports.procEntryExists(pid)) {
-                verificationGap = true;
-            }
-            else {
-                tracked.delete(pid);
-            }
-            continue;
-        }
-        if (current.state === "Z" || current.startIdentity !== startIdentity) {
-            tracked.delete(pid);
-            continue;
-        }
-        return { kind: "live" };
-    }
-    return verificationGap ? { kind: "gap" } : { kind: "absent" };
-}
-/**
- * Signals the exact root (only when its identity is verified) and, while the
- * root is live, its process group. When the root has already exited but a
- * fenced child survives, each fenced child is signaled individually: the
- * group can no longer be proven ours once its leader is gone.
- */
-function escalateRecord(record, ports, trackedChildren, signal) {
-    const root = rootVerdict(record, ports);
-    if (root.kind === "live") {
-        try {
-            ports.signalProcess(record.providerRoot.pid, signal);
-        }
-        catch {
-            // The root may have exited between verdict and signal; the final
-            // verification is authoritative.
-        }
-        const { processGroupId } = record.providerRoot;
-        if (processGroupId !== undefined) {
+    const pollMs = duration(options.pollMs, DEFAULT_TERMINATION_POLL_MS);
+    for (const [signal, grace] of [
+        ["SIGTERM", duration(options.gracefulGraceMs, DEFAULT_GRACEFUL_GRACE_MS)],
+        ["SIGKILL", duration(options.forcedGraceMs, DEFAULT_FORCED_GRACE_MS)]
+    ]) {
+        for (const record of records) {
+            // The dedicated execution supervisor reaps its descendants before exit.
+            // Killing the supervisor would discard that custody proof.
+            if (signal === "SIGKILL" && record.providerRoot.attribution === "owned-child")
+                continue;
+            if (state(record) !== "live")
+                continue;
             try {
-                ports.signalProcessGroup(processGroupId, signal);
+                ports.signalProcess(record.providerRoot.pid, signal);
             }
-            catch {
-                // Group may already be gone or the root may not be its leader.
+            catch (error) {
+                if (error.code !== "ESRCH") {
+                    emit("stop-blocked", error instanceof Error ? error.message : String(error));
+                }
             }
         }
-        return;
-    }
-    if (root.kind !== "absent")
-        return;
-    refreshTrackedFencedChildren(record, ports, trackedChildren);
-    const tracked = trackedChildren.get(record.runtimeGenerationId);
-    if (tracked === undefined)
-        return;
-    for (const [pid, startIdentity] of tracked) {
-        const current = ports.processIdentity(pid);
-        if (current === undefined
-            || current.state === "Z"
-            || current.startIdentity !== startIdentity) {
-            continue;
-        }
-        try {
-            ports.signalProcess(pid, signal);
-        }
-        catch {
-            // A child may have exited between scan and signal.
+        emit(signal === "SIGTERM" ? "graceful-stop" : "forced-stop");
+        const deadline = Date.now() + grace;
+        while (records.some((record) => state(record) === "live") && Date.now() < deadline) {
+            await ports.sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
         }
+        if (records.every((record) => state(record) === "absent"))
+            break;
     }
-}
-async function waitForTreesAbsent(records, ports, trackedChildren, timeoutMs, pollMs) {
-    const start = Date.now();
-    for (;;) {
-        if (records.every((record) => treeVerdict(record, ports, trackedChildren).kind === "absent")) {
-            return true;
-        }
-        if (Date.now() - start >= timeoutMs)
-            return false;
-        await ports.sleep(Math.min(pollMs, Math.max(1, timeoutMs - (Date.now() - start))));
+    const confirmed = [];
+    const remaining = [];
+    for (const record of records) {
+        const observed = state(record);
+        if (observed === "absent")
+            confirmed.push(record);
+        else
+            remaining.push({
+                record,
+                detail: observed === "unknown" ? "Host process identity is unreadable." : "Host process is still live."
+            });
     }
+    const outcome = remaining.length === 0 ? "stop-confirmed" : "stop-blocked";
+    emit(outcome);
+    return { outcome, owner, confirmed, remaining };
 }
-function positiveDuration(value, fallback, label) {
-    const resolved = value ?? fallback;
-    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
-        throw new TypeError(`${label} must be a positive integer.`);
-    }
-    return resolved;
+function duration(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error("Stop duration must be non-negative.");
+    return value;
 }

package/dist/runtime/sessionTokenMetrics.js

@@ -2,12 +2,7 @@ import { builtinDriverIdForAdapter } from "./builtinAgentDrivers.js";
 import { isRuntimeTokenEvidence, runtimeObservationFromTaskEvent } from "./runtimeObservation.js";
 const UNOBSERVED = Object.freeze({ status: "unobserved" });
 export function resolveSessionTokenIdentity(input) {
-    if (input?.taskId === undefined
-        || input.roleName === undefined
-        || input.agentId === undefined
-        || input.adapterId === undefined
-        || input.runtimeGenerationId === undefined
-        || input.nativeSessionId === undefined)
+    if (input?.taskId === undefined || input.roleName === undefined || input.agentId === undefined || input.adapterId === undefined || input.nativeSessionId === undefined)
         return null;
     let driverId;
     try {
@@ -21,7 +16,6 @@ export function resolveSessionTokenIdentity(input) {
         roleName: input.roleName,
         agentId: input.agentId,
         driverId,
-        runtimeGenerationId: input.runtimeGenerationId,
         nativeSessionId: input.nativeSessionId
     });
 }
@@ -36,12 +30,12 @@ export function projectSessionTokenMetrics(events, identity) {
         .map(runtimeObservationFromTaskEvent)
         .filter((observation) => (observation !== null
         && isRuntimeTokenEvidence(observation)
-        && matchesSessionGeneration(observation, identity)))
+        && matchesSessionIdentity(observation, identity)))
         .sort(compareObservations);
     const incompleteBoundaries = observations.filter(({ payload }) => (payload.usage === undefined));
     const request = observations.filter(({ payload }) => (payload.usage?.semantics === "request-context"));
     const cumulative = observations.filter(({ payload }) => (payload.usage?.semantics === "cumulative-session"));
-    // A generation cannot switch counter semantics without an explicit fact
+    // A Session cannot switch counter semantics without an explicit fact
     // explaining how the two streams overlap. Remaining-context is capacity,
     // not consumption, and is intentionally absent from both metrics.
     if (request.length > 0 && cumulative.length > 0) {
@@ -149,14 +143,9 @@ function projectCumulativeSnapshots(identity, observations, hasIncompleteBoundar
             : Object.freeze({ status: "observed", inputTokens: maximumRequestInput })
     });
 }
-function matchesSessionGeneration(observation, identity) {
+function matchesSessionIdentity(observation, identity) {
     const fence = observation.fence;
-    return fence.taskId === identity.taskId
-        && fence.roleName === identity.roleName
-        && fence.agentId === identity.agentId
-        && fence.driverId === identity.driverId
-        && fence.runtimeGenerationId === identity.runtimeGenerationId
-        && fence.nativeSessionId === identity.nativeSessionId;
+    return fence.taskId === identity.taskId && fence.roleName === identity.roleName && fence.agentId === identity.agentId && fence.driverId === identity.driverId && fence.nativeSessionId === identity.nativeSessionId;
 }
 function compareObservations(left, right) {
     return left.receivedAt.localeCompare(right.receivedAt)