comisai 1.0.45 → 1.0.46

package/node_modules/@comis/memory/dist/video-job-store.d.ts

@@ -1,6 +1,5 @@
 /**
- * VideoJobStore — SQLite persistence for the Phase-189 durable async video-job
- * lifecycle (JOB-01/JOB-03/JOB-04).
+ * VideoJobStore — SQLite persistence for the durable async video-job lifecycle.
  *
  * Factory-function pattern (modeled on `createSqliteDeliveryQueue`): prepares
  * fixed SQL statements once in the closure, returns a frozen `VideoJobStore`.
@@ -10,18 +9,18 @@
  *
  * The job row is the durable spine the background poller resumes against across
  * a daemon restart: a row survives the agent turn AND a restart because it lives
- * on disk in the shared `memory.db` (Q1/O3 LOCKED: shared db, not an own .db).
+ * on disk in the shared `memory.db` (shared db, not an own .db).
  *
  * WHERE IT DIFFERS FROM THE DELIVERY QUEUE:
- *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns — JOB-04 /
- *     Pitfall 6). A bare `get(jobId)` is FORBIDDEN: it would leak another
- *     agent's job. A cross-agent jobId returns not-found (`ok(undefined)`).
+ *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns). A bare
+ *     `get(jobId)` is FORBIDDEN: it would leak another agent's job. A cross-agent
+ *     jobId returns not-found (`ok(undefined)`).
  *  2. Carries a video path + cost + progress columns (the queue carries text).
  *  3. State domain is `pending | done | failed` (the queue's is broader).
  *  4. ZERO fd-based fs (no explicit file-sync/chmod-by-fd) — better-sqlite3 +
- *     the shared `db` are permission-model-safe by construction (Pitfall 2 / A4).
+ *     the shared `db` are permission-model-safe by construction.
  *
- * SECURITY (T-189-02): the persisted columns carry NO secret — the `jobId` is
+ * SECURITY: the persisted columns carry NO secret — the `jobId` is
  * the opaque provider request id; the credential is held by the boot-bound
  * adapter and is never written here.
  *
@@ -29,11 +28,11 @@
  */
 import type Database from "better-sqlite3";
 import type { Result } from "@comis/shared";
-/** The state machine for a video job (JOB-01). */
+/** The state machine for a video job. */
 export type VideoJobState = "pending" | "done" | "failed";
 /** A persisted video-generation job (camelCase domain view of a `video_jobs` row). */
 export interface VideoJobRecord {
-    /** Opaque, durable provider request id (secret-free — T-189-02). */
+    /** Opaque, durable provider request id (secret-free). */
     readonly jobId: string;
     readonly provider: string;
     readonly model?: string;
@@ -41,7 +40,7 @@ export interface VideoJobRecord {
     readonly channelType?: string;
     readonly channelId?: string;
     readonly traceId?: string;
-    /** OBS-04 (Phase 192): the formatted session key — the off-turn poller resolves
+    /** The formatted session key — the off-turn poller resolves
      *  the per-session trajectory recorder by this to stitch a background-completed
      *  render to its originating turn. Nullable in the row (old rows are NULL). */
     readonly sessionKey?: string;
@@ -51,13 +50,13 @@ export interface VideoJobRecord {
     readonly mediaPath?: string;
     readonly progress?: number;
     readonly lastError?: string;
-    /** CR-01: count of delivery/completion attempts; bounds the poller's
+    /** Count of delivery/completion attempts; bounds the poller's
      *  redelivery loop (dead-letter once it exceeds maxDeliveryAttempts). */
     readonly deliverAttempts: number;
     readonly submittedAtMs: number;
     readonly updatedAtMs: number;
 }
-/** Insert payload — the JOB-01 fields recorded at submit. */
+/** Insert payload — the fields recorded at submit. */
 export interface VideoJobInsert {
     readonly jobId: string;
     readonly provider: string;
@@ -66,7 +65,7 @@ export interface VideoJobInsert {
     readonly channelType?: string;
     readonly channelId?: string;
     readonly traceId?: string;
-    /** OBS-04 (Phase 192): the formatted session key persisted at submit (the
+    /** The formatted session key persisted at submit (the
      *  off-turn recorder fold key). Optional — `undefined` outside a request scope. */
     readonly sessionKey?: string;
     readonly state: VideoJobState;
@@ -74,7 +73,7 @@ export interface VideoJobInsert {
     readonly submittedAtMs: number;
     readonly updatedAtMs: number;
 }
-/** The completion payload for `markDone` (the poller's `done` tail — JOB-02). */
+/** The completion payload for `markDone` (the poller's `done` tail). */
 export interface VideoJobDoneInput {
     readonly mediaPath: string;
     readonly actualCostUsd?: number;
@@ -89,26 +88,26 @@ export interface VideoJobStore {
     /** All rows in state 'pending', oldest first (the poller's boot-resume scan). */
     listPending(): Promise<Result<VideoJobRecord[], Error>>;
     /**
-     * Read a job scoped to BOTH jobId AND agentId (JOB-04 / Pitfall 6).
+     * Read a job scoped to BOTH jobId AND agentId.
      * Not-found (no such job for this agent) is `ok(undefined)` — distinct from a
      * real error, so the status handler can answer "no such job" vs "lookup failed".
      */
     get(jobId: string, agentId: string): Promise<Result<VideoJobRecord | undefined, Error>>;
-    /** Transition to 'done' + record the delivered path + actual cost (JOB-02). */
+    /** Transition to 'done' + record the delivered path + actual cost. */
     markDone(jobId: string, input: VideoJobDoneInput): Promise<Result<void, Error>>;
     /**
-     * Transition to 'failed' + record `last_error` (JOB-02).
+     * Transition to 'failed' + record `last_error`.
      *
-     * WR-02 (Phase 190): pass the optional `lastError` to persist an ACTIONABLE
-     * operator hint (what `video.status` returns as `error`) instead of the bare
-     * `errorKind` enum token. When omitted, `errorKind` is written verbatim (the
-     * pre-190 behavior — preserved for callers/tests that pass only the kind).
+     * Pass the optional `lastError` to persist an ACTIONABLE operator hint (what
+     * `video.status` returns as `error`) instead of the bare `errorKind` enum token.
+     * When omitted, `errorKind` is written verbatim (preserved for callers/tests
+     * that pass only the kind).
      */
     markFailed(jobId: string, errorKind: string, lastError?: string): Promise<Result<void, Error>>;
-    /** Update the optional progress fraction (JOB-02). */
+    /** Update the optional progress fraction. */
     updateProgress(jobId: string, progress: number): Promise<Result<void, Error>>;
     /**
-     * CR-01: atomically `deliver_attempts = deliver_attempts + 1` and return the
+     * Atomically `deliver_attempts = deliver_attempts + 1` and return the
      * NEW count. The poller calls this on each delivery/completion attempt and
      * dead-letters the row to `failed` once the count exceeds maxDeliveryAttempts,
      * so a persistent delivery failure converges instead of re-polling +

package/node_modules/@comis/memory/dist/video-job-store.js

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * VideoJobStore — SQLite persistence for the Phase-189 durable async video-job
- * lifecycle (JOB-01/JOB-03/JOB-04).
+ * VideoJobStore — SQLite persistence for the durable async video-job lifecycle.
  *
  * Factory-function pattern (modeled on `createSqliteDeliveryQueue`): prepares
  * fixed SQL statements once in the closure, returns a frozen `VideoJobStore`.
@@ -11,18 +10,18 @@
  *
  * The job row is the durable spine the background poller resumes against across
  * a daemon restart: a row survives the agent turn AND a restart because it lives
- * on disk in the shared `memory.db` (Q1/O3 LOCKED: shared db, not an own .db).
+ * on disk in the shared `memory.db` (shared db, not an own .db).
  *
  * WHERE IT DIFFERS FROM THE DELIVERY QUEUE:
- *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns — JOB-04 /
- *     Pitfall 6). A bare `get(jobId)` is FORBIDDEN: it would leak another
- *     agent's job. A cross-agent jobId returns not-found (`ok(undefined)`).
+ *  1. `get(jobId, agentId)` is agent-scoped (filters BOTH columns). A bare
+ *     `get(jobId)` is FORBIDDEN: it would leak another agent's job. A cross-agent
+ *     jobId returns not-found (`ok(undefined)`).
  *  2. Carries a video path + cost + progress columns (the queue carries text).
  *  3. State domain is `pending | done | failed` (the queue's is broader).
  *  4. ZERO fd-based fs (no explicit file-sync/chmod-by-fd) — better-sqlite3 +
- *     the shared `db` are permission-model-safe by construction (Pitfall 2 / A4).
+ *     the shared `db` are permission-model-safe by construction.
  *
- * SECURITY (T-189-02): the persisted columns carry NO secret — the `jobId` is
+ * SECURITY: the persisted columns carry NO secret — the `jobId` is
  * the opaque provider request id; the credential is held by the boot-bound
  * adapter and is never written here.
  *
@@ -80,8 +79,8 @@ export function createVideoJobStore(db) {
       progress, last_error, submitted_at_ms, updated_at_ms
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?)
   `);
-    // Agent-scoped read — filters by BOTH columns (the must-differ point 1;
-    // JOB-04 / Pitfall 6). A cross-agent jobId matches no row → not-found.
+    // Agent-scoped read — filters by BOTH columns (the must-differ point 1).
+    // A cross-agent jobId matches no row → not-found.
     const getStmt = db.prepare(`
     SELECT * FROM video_jobs WHERE job_id = ? AND agent_id = ?
   `);
@@ -101,7 +100,7 @@ export function createVideoJobStore(db) {
     const updateProgressStmt = db.prepare(`
     UPDATE video_jobs SET progress = ?, updated_at_ms = ? WHERE job_id = ?
   `);
-    // CR-01: atomic redelivery-counter bump. better-sqlite3 is synchronous +
+    // Atomic redelivery-counter bump. better-sqlite3 is synchronous +
     // single-connection, so the UPDATE and the paired read below run in the SAME
     // event-loop turn — no interleaving, so the read sees this UPDATE's value.
     const incrementAttemptStmt = db.prepare(`
@@ -159,7 +158,7 @@ export function createVideoJobStore(db) {
         },
         markFailed(jobId, errorKind, lastError) {
             try {
-                // WR-02: persist the actionable hint when supplied; else the bare kind.
+                // Persist the actionable hint when supplied; else the bare kind.
                 markFailedStmt.run(lastError ?? errorKind, systemNowMs(), jobId);
                 return Promise.resolve(ok(undefined));
             }

package/node_modules/@comis/memory/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/memory",
   "private": true,
-  "version": "1.0.45",
+  "version": "1.0.46",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "SQLite memory, embeddings, and RAG storage for Comis agents",

package/node_modules/@comis/observability/dist/activity/activity-stream.d.ts

@@ -1,8 +1,8 @@
 /**
- * activity-stream — the canonical, redacted `ActivityEvent` source (spec §5).
+ * activity-stream — the canonical, redacted `ActivityEvent` source.
  *
  * Subscribes to the typed EventBus (consume only — `core/event-bus/bus.ts` is
- * frozen, §17.7) and maps each real `tool:*` / `model:*` / `approval:*` event to
+ * frozen) and maps each real `tool:*` / `model:*` / `approval:*` event to
  * an `ActivityEvent` via the core helpers (`resolveLabel`/`applyTemplate`/
  * `classifySemanticPhase` + `redactValue` defense-in-depth), validates the
  * output with `parseActivityEvent`, and delivers it to per-turn subscribers
@@ -10,10 +10,10 @@
  * `cache-trace/event-bus-bridge.ts` subscription-bag + single-`unsubscribe()`
  * idiom (the canonical EventBus-subscriber pattern).
  *
- * Canonical + UNFILTERED (spec §5.0): zero verbosity / coalescing / maxLines
+ * Canonical + UNFILTERED: zero verbosity / coalescing / maxLines
  * here — projections (in `core/activity/projections`) apply consumer policy.
  *
- * Correlation index (spec §4.2): an in-memory `requestId → { activityId, … }`
+ * Correlation index: an in-memory `requestId → { activityId, … }`
  * map populated from `approval:requested` lets `approval:resolved` (which
  * carries only `requestId`) close the matching activity. A resolved event with
  * no matching index entry is ignored for live activity (the durable approval
@@ -21,12 +21,12 @@
  * stable `activityId` across `tool:started` → `tool:executed`.
  *
  * Subagent lifecycle events (`session:sub_agent_spawned`/`completed`) map to
- * `kind:"subagent"` ActivityEvents (§17.3). The spawn payload carries
+ * `kind:"subagent"` ActivityEvents. The spawn payload carries
  * `{runId, parentSessionKey, agentId, task}` — NO `traceId` and NO parent
  * `activityId` — so subagent events are delivered to every turn subscriber whose
  * `{agentId, sessionKey}` match `{agentId, parentSessionKey}`, stamping that
  * subscriber's `traceId` onto the delivered copy. `parentActivityId` is left
- * unset here: the per-turn coordinator (the §4.5 single owner) annotates the
+ * unset here: the per-turn coordinator (the single owner) annotates the
  * parent link from its active-subagent stack. The free-text `task` is never
  * reflected into the rendered label (only `agentId` + the `🤖` marker).
  *
@@ -37,9 +37,9 @@
  * when a mapped event's `redactionsApplied` is non-empty (a tool tried to
  * substitute a secret-keyed value); a `parseActivityEvent` failure logs ERROR.
  *
- * Counters (spec §20.1): there is no metrics-sink primitive in
+ * Counters: there is no metrics-sink primitive in
  * `@comis/observability` (the package logs + emits on the bus — see
- * `health-aggregator`). The §20.1 counters are therefore kept as an in-process
+ * `health-aggregator`). The counters are therefore kept as an in-process
  * counter snapshot (`counters()`) — incremented on each emit/drop/redaction and
  * surfaced for the daemon's metrics scrape + the test harness. Per-event emit is
  * traced at DEBUG.
@@ -72,7 +72,7 @@ export interface CreateActivityStreamDeps {
     /** Override "now" (ms) for deterministic tests. Defaults to the sanctioned `systemNowMs`. */
     readonly nowMs?: () => number;
 }
-/** In-process counter snapshot mirroring the spec §20.1 activity counters. */
+/** In-process counter snapshot mirroring the activity counters. */
 export interface ActivityCounters {
     /** `activity.events.emitted` total. */
     readonly emitted: number;

package/node_modules/@comis/observability/dist/activity/activity-stream.js

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * activity-stream — the canonical, redacted `ActivityEvent` source (spec §5).
+ * activity-stream — the canonical, redacted `ActivityEvent` source.
  *
  * Subscribes to the typed EventBus (consume only — `core/event-bus/bus.ts` is
- * frozen, §17.7) and maps each real `tool:*` / `model:*` / `approval:*` event to
+ * frozen) and maps each real `tool:*` / `model:*` / `approval:*` event to
  * an `ActivityEvent` via the core helpers (`resolveLabel`/`applyTemplate`/
  * `classifySemanticPhase` + `redactValue` defense-in-depth), validates the
  * output with `parseActivityEvent`, and delivers it to per-turn subscribers
@@ -11,10 +11,10 @@
  * `cache-trace/event-bus-bridge.ts` subscription-bag + single-`unsubscribe()`
  * idiom (the canonical EventBus-subscriber pattern).
  *
- * Canonical + UNFILTERED (spec §5.0): zero verbosity / coalescing / maxLines
+ * Canonical + UNFILTERED: zero verbosity / coalescing / maxLines
  * here — projections (in `core/activity/projections`) apply consumer policy.
  *
- * Correlation index (spec §4.2): an in-memory `requestId → { activityId, … }`
+ * Correlation index: an in-memory `requestId → { activityId, … }`
  * map populated from `approval:requested` lets `approval:resolved` (which
  * carries only `requestId`) close the matching activity. A resolved event with
  * no matching index entry is ignored for live activity (the durable approval
@@ -22,12 +22,12 @@
  * stable `activityId` across `tool:started` → `tool:executed`.
  *
  * Subagent lifecycle events (`session:sub_agent_spawned`/`completed`) map to
- * `kind:"subagent"` ActivityEvents (§17.3). The spawn payload carries
+ * `kind:"subagent"` ActivityEvents. The spawn payload carries
  * `{runId, parentSessionKey, agentId, task}` — NO `traceId` and NO parent
  * `activityId` — so subagent events are delivered to every turn subscriber whose
  * `{agentId, sessionKey}` match `{agentId, parentSessionKey}`, stamping that
  * subscriber's `traceId` onto the delivered copy. `parentActivityId` is left
- * unset here: the per-turn coordinator (the §4.5 single owner) annotates the
+ * unset here: the per-turn coordinator (the single owner) annotates the
  * parent link from its active-subagent stack. The free-text `task` is never
  * reflected into the rendered label (only `agentId` + the `🤖` marker).
  *
@@ -38,9 +38,9 @@
  * when a mapped event's `redactionsApplied` is non-empty (a tool tried to
  * substitute a secret-keyed value); a `parseActivityEvent` failure logs ERROR.
  *
- * Counters (spec §20.1): there is no metrics-sink primitive in
+ * Counters: there is no metrics-sink primitive in
  * `@comis/observability` (the package logs + emits on the bus — see
- * `health-aggregator`). The §20.1 counters are therefore kept as an in-process
+ * `health-aggregator`). The counters are therefore kept as an in-process
  * counter snapshot (`counters()`) — incremented on each emit/drop/redaction and
  * surfaced for the daemon's metrics scrape + the test harness. Per-event emit is
  * traced at DEBUG.
@@ -54,7 +54,7 @@ import { applyTemplate, parseActivityEvent, resolveLabelSpec, systemDateFrom, sy
 import { randomUUID } from "node:crypto";
 import { createBoundedQueue } from "./bounded-queue.js";
 import { clampLabel, compressLabel } from "./label-compressor.js";
-/** A failure event bypasses the bounded-queue drop policy (spec §5.1). */
+/** A failure event bypasses the bounded-queue drop policy. */
 function isFailureEvent(e) {
     return e.status === "failed" || e.kind === "approval";
 }
@@ -74,8 +74,8 @@ const SUBSCRIBED_EVENTS = [
 /**
  * The status markers used when no theme is supplied (or a markerless theme is
  * passed). These mirror the `default` theme bundle byte-for-byte so the
- * no-theme / default-theme output is identical to the historical hardcoded
- * glyphs — existing channel golden fixtures do not regress.
+ * no-theme / default-theme output matches the exact glyphs the
+ * channel golden fixtures assert.
  * Only `subagent` is read today (the event-produced marker baked
  * into `defaultLabel`); the closing-line `success`/`failure` markers are
  * RENDERER-derived from the `TurnOutcome` and are themed separately (a
@@ -104,7 +104,7 @@ export function createActivityStream(deps) {
     const subscribers = new Set();
     // toolCallId/requestId → minted activityId (stable across start↔end).
     const activityIds = new Map();
-    // requestId → correlation context (spec §4.2 approval index).
+    // requestId → correlation context (approval index).
     const approvalIndex = new Map();
     // runId → parentSessionKey: the spawn payload carries the session, the
     // completed payload does NOT, so remember it to scope the close event.
@@ -135,7 +135,7 @@ export function createActivityStream(deps) {
      * the compressor runs AFTER `redactValue` (which `applyTemplate` already
      * applied), so it never lets a raw URL/path escape redaction and never
      * re-compacts an already-compacted (`~`-rooted / ≤2-segment) path (it is a
-     * fixed point — see Pitfall 2). It is NOT called inside `applyTemplate`
+     * fixed point). It is NOT called inside `applyTemplate`
      * (a `core` redaction-only primitive) and NOT on the subagent/model marker
      * labels (those bypass `buildLabel` — short static `markers.subagent`/
      * "switching model provider" strings; compressing them is a needless no-op).
@@ -156,7 +156,7 @@ export function createActivityStream(deps) {
         }
         if (result.value.redactionsApplied.length > 0) {
             redactionReplacements += result.value.redactionsApplied.length;
-            // §10.1: exactly one WARN when a tool tried to substitute a
+            // Exactly one WARN when a tool tried to substitute a
             // secret-keyed value. Object-first; module-identity field never set.
             childLogger?.warn?.({
                 toolName,
@@ -215,7 +215,7 @@ export function createActivityStream(deps) {
             });
         }
         // Deliver to every turn subscriber whose ids match (turn-scoped filter).
-        // The per-consumer bounded queue (§5.1) absorbs backpressure: push then
+        // The per-consumer bounded queue absorbs backpressure: push then
         // drain synchronously to the consumer. A push that drops (main-ring or
         // failure-overflow overflow) increments the `dropped` counter.
         for (const sub of subscribers) {
@@ -317,13 +317,14 @@ export function createActivityStream(deps) {
             semanticPhase,
             toolName: p.toolName,
             ...(p.action !== undefined ? { action: p.action } : {}),
-            // §3.1: mirror subagent precedent at lines 602/621.
+            // Prepend the themed running marker to the start-phase label, consistent
+            // with the subagent labels below.
             // The running marker is themed (default: 🔧, ascii: [..]) and resolved
-            // once at construction (line 198). DO NOT apply to onToolExecuted
-            // (phase:"end") — that violates Pitfall 7 (the running marker conveys
-            // in-flight status only). Clamp the marker-prepended label to the schema
-            // cap (FIX 3): the marker is added AFTER compressLabel, so without this a
-            // near-cap label would exceed 120 and the event would be DROPPED.
+            // once at construction. DO NOT apply to onToolExecuted
+            // (phase:"end") — the running marker conveys in-flight status only. Clamp
+            // the marker-prepended label to the schema cap: the marker is added AFTER
+            // compressLabel, so without this a near-cap label would exceed 120 and the
+            // event would be DROPPED.
             defaultLabel: clampLabel(`${markers.running} ${defaultLabel}`),
         });
     }
@@ -389,15 +390,14 @@ export function createActivityStream(deps) {
             status: "running",
             kind: "model",
             semanticPhase: "thinking",
-            // §3.1: themed running marker on the static label.
-            // Mirrors the subagent precedent at lines 602/621. Clamped to the cap (FIX 3)
-            // — consistent with the tool path; a custom theme could supply a long marker.
+            // Themed running marker on the static label, consistent with the tool path.
+            // Clamped to the cap because a custom theme could supply a long marker.
             defaultLabel: clampLabel(`${markers.running} switching model provider`),
         });
     }
     function onApprovalRequested(p) {
         if (p.traceId === undefined)
-            return; // trace-less restored approvals: not live activity (§4.2)
+            return; // trace-less restored approvals: not live activity
         const activityId = activityIdFor(`approval:${p.requestId}`);
         dispatch({
             schemaVersion: 1,
@@ -426,7 +426,7 @@ export function createActivityStream(deps) {
     function onApprovalResolved(p) {
         const entry = approvalIndex.get(p.requestId);
         if (entry === undefined)
-            return; // no matching index → ignore for live activity (§4.2)
+            return; // no matching index → ignore for live activity
         approvalIndex.delete(p.requestId);
         dispatch({
             schemaVersion: 1,
@@ -458,7 +458,7 @@ export function createActivityStream(deps) {
         // The label uses only agentId + the resolved subagent marker
         // (`markers.subagent`; 🤖 for default/no theme, [SUB] for ascii) — never the
         // free-text `task` (which could echo user content). parentActivityId is set
-        // by the coordinator (§4.5), not here.
+        // by the coordinator, not here.
         subagentSessions.set(p.runId, p.parentSessionKey);
         dispatchSubagent({
             schemaVersion: 1,

package/node_modules/@comis/observability/dist/activity/bounded-queue.d.ts

@@ -1,8 +1,8 @@
 /**
  * bounded-queue — the per-consumer backpressure ring at the ActivityStream
- * subscription boundary (spec §5.1).
+ * subscription boundary.
  *
- * Spec §5.1: every consumer downstream of ActivityStream uses a bounded queue
+ * Every consumer downstream of ActivityStream uses a bounded queue
  * with a documented drop policy so the agent loop never blocks on a slow
  * consumer:
  *
@@ -17,7 +17,7 @@
  *
  * Pure data structure. No logger here — the *consumer* (ActivityStream /
  * coordinator) reads `droppedCount()` / `highWater()` and emits the
- * `activity.events.dropped` + `queue_high_water` counters (spec §20.1).
+ * `activity.events.dropped` + `queue_high_water` counters.
  *
  * The optional `timer: TimerPort` is accepted only so a test can assert the
  * producer schedules NO timer (it does not — `push` is synchronous). It is
@@ -27,9 +27,9 @@
  * @module
  */
 import type { TimerPort } from "@comis/core";
-/** Default main-ring capacity (spec §5.1 — per-channel renderer). */
+/** Default main-ring capacity (per-channel renderer). */
 export declare const DEFAULT_QUEUE_CAPACITY = 64;
-/** Default high-priority failure-overflow capacity (spec §5.1). */
+/** Default high-priority failure-overflow capacity. */
 export declare const DEFAULT_FAILURE_OVERFLOW = 16;
 /** Options for {@link createBoundedQueue}. */
 export interface BoundedQueueOptions<T> {
@@ -69,6 +69,6 @@ export interface BoundedQueue<T> {
     highWater(): number;
 }
 /**
- * Create a per-consumer bounded queue per spec §5.1.
+ * Create a per-consumer bounded queue.
  */
 export declare function createBoundedQueue<T>(opts?: BoundedQueueOptions<T>): BoundedQueue<T>;

package/node_modules/@comis/observability/dist/activity/bounded-queue.js

@@ -1,9 +1,9 @@
-/** Default main-ring capacity (spec §5.1 — per-channel renderer). */
+/** Default main-ring capacity (per-channel renderer). */
 export const DEFAULT_QUEUE_CAPACITY = 64;
-/** Default high-priority failure-overflow capacity (spec §5.1). */
+/** Default high-priority failure-overflow capacity. */
 export const DEFAULT_FAILURE_OVERFLOW = 16;
 /**
- * Create a per-consumer bounded queue per spec §5.1.
+ * Create a per-consumer bounded queue.
  */
 export function createBoundedQueue(opts = {}) {
     const capacity = opts.capacity ?? DEFAULT_QUEUE_CAPACITY;
@@ -38,7 +38,7 @@ export function createBoundedQueue(opts = {}) {
             else {
                 main.push(item);
                 if (main.length > capacity) {
-                    // Drop the OLDEST non-failure (FIFO drop, spec §5.1).
+                    // Drop the OLDEST non-failure (FIFO drop).
                     main.shift();
                     dropped += 1;
                     droppedByThisPush = 1;

package/node_modules/@comis/observability/dist/activity/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * @comis/observability — activity substrate barrel.
  *
- * The observability-side of the activity pipeline (spec §5): the
+ * The observability-side of the activity pipeline: the
  * `ActivityStream` EventBus subscriber that maps real events to canonical,
  * redacted `ActivityEvent`s, the per-consumer `bounded-queue`, the typed-first
- * `label-resolver`, the OpenClaw `shell-label-parser`, and the SEP `plan-stream`.
+ * `label-resolver`, the `shell-label-parser`, and the SEP `plan-stream`.
  *
  * Boundary: this surface imports `@comis/core` only — never the channels
  * package (the hexagonal constraint, enforced by a durable guard test).

package/node_modules/@comis/observability/dist/activity/index.js

@@ -2,10 +2,10 @@
 /**
  * @comis/observability — activity substrate barrel.
  *
- * The observability-side of the activity pipeline (spec §5): the
+ * The observability-side of the activity pipeline: the
  * `ActivityStream` EventBus subscriber that maps real events to canonical,
  * redacted `ActivityEvent`s, the per-consumer `bounded-queue`, the typed-first
- * `label-resolver`, the OpenClaw `shell-label-parser`, and the SEP `plan-stream`.
+ * `label-resolver`, the `shell-label-parser`, and the SEP `plan-stream`.
  *
  * Boundary: this surface imports `@comis/core` only — never the channels
  * package (the hexagonal constraint, enforced by a durable guard test).

package/node_modules/@comis/observability/dist/activity/label-compressor.d.ts

@@ -1,9 +1,9 @@
 /**
  * label-compressor — pure, one-pass, idempotent display-shortener for activity
- * labels (spec §8.4). Consumes strings that redactValue has already
+ * labels. Consumes strings that redactValue has already
  * sanitized and path-compacted: it does NOT mask secrets (redactValue owns that
  * upstream) and does NOT re-compact paths (a `~`-rooted or ≤2-segment path is a
- * fixed point — Pitfall 2). It handles ONLY three display categories:
+ * fixed point). It handles ONLY three display categories:
  *
  *   - URLs:       `https://api.tavily.com/v1/search?q=…` → `tavily.com/search`
  *   - Timestamps: `2025-05-22T18:42:00.123Z`            → `18:42:00`

package/node_modules/@comis/observability/dist/activity/label-compressor.js

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * label-compressor — pure, one-pass, idempotent display-shortener for activity
- * labels (spec §8.4). Consumes strings that redactValue has already
+ * labels. Consumes strings that redactValue has already
  * sanitized and path-compacted: it does NOT mask secrets (redactValue owns that
  * upstream) and does NOT re-compact paths (a `~`-rooted or ≤2-segment path is a
- * fixed point — Pitfall 2). It handles ONLY three display categories:
+ * fixed point). It handles ONLY three display categories:
  *
  *   - URLs:       `https://api.tavily.com/v1/search?q=…` → `tavily.com/search`
  *   - Timestamps: `2025-05-22T18:42:00.123Z`            → `18:42:00`
@@ -114,7 +114,7 @@ export function compressLabel(label) {
     //     absolute paths to their last 2 segments; a `~`-rooted or ≤2-segment path
     //     is a fixed point here, and none of the regexes above match one.
     //
-    // (5) CLAMP: hard-cap the produced label to the schema bound (FIX 3). The
+    // (5) CLAMP: hard-cap the produced label to the schema bound. The
     //     category transforms never grow the input, but the input itself can exceed
     //     120 chars (a long static label / a verbose template render). Clamping last
     //     keeps every direct consumer + the buildLabel returns within the cap.

package/node_modules/@comis/observability/dist/activity/label-resolver.d.ts

@@ -1,12 +1,11 @@
 /**
- * label-resolver — the typed-first, ActivityStream-side label producer
- * (spec §6.1).
+ * label-resolver — the typed-first, ActivityStream-side label producer.
  *
- * Resolution is typed-first, deterministic-second (spec §6.1):
+ * Resolution is typed-first, deterministic-second:
  *
  *   1. `metadata.suppressActivity === true` → `null` (the tool produces NO
  *      activity at all — e.g. `memory_search` from consolidation,
- *      `discover_tools`, cron poll ticks; spec §10.3).
+ *      `discover_tools`, cron poll ticks).
  *   2. `resolveLabelSpec(toolName, { action, theme })` → the effective LabelSpec
  *      (theme override > registered spec > semantic fallback — resolved in core).
  *   3. `applyTemplate(spec, params, { homeDir })` → the redacted, length-capped
@@ -20,7 +19,7 @@
  * (`resolveLabelSpec` + `applyTemplate`, themselves pure). Redaction-WARN
  * ownership: the resolver does NOT log the redaction WARN. {@link resolveLabelDetailed} returns
  * `redactionsApplied` upward so the ActivityStream (which holds the injected
- * logger) emits the single WARN when non-empty (spec §10.1). It never imports
+ * logger) emits the single WARN when non-empty. It never imports
  * `channels` (the hexagonal boundary).
  *
  * @module
@@ -33,7 +32,7 @@ import { type ActivityTheme, type RedactionReason } from "@comis/core";
  * metadata interface.
  */
 export interface ResolveLabelMetadata {
-    /** When true the tool produces no activity (spec §10.3). */
+    /** When true the tool produces no activity. */
     readonly suppressActivity?: boolean;
 }
 /** Options for {@link resolveLabel} / {@link resolveLabelDetailed}. */

package/node_modules/@comis/observability/dist/activity/label-resolver.js

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * label-resolver — the typed-first, ActivityStream-side label producer
- * (spec §6.1).
+ * label-resolver — the typed-first, ActivityStream-side label producer.
  *
- * Resolution is typed-first, deterministic-second (spec §6.1):
+ * Resolution is typed-first, deterministic-second:
  *
  *   1. `metadata.suppressActivity === true` → `null` (the tool produces NO
  *      activity at all — e.g. `memory_search` from consolidation,
- *      `discover_tools`, cron poll ticks; spec §10.3).
+ *      `discover_tools`, cron poll ticks).
  *   2. `resolveLabelSpec(toolName, { action, theme })` → the effective LabelSpec
  *      (theme override > registered spec > semantic fallback — resolved in core).
  *   3. `applyTemplate(spec, params, { homeDir })` → the redacted, length-capped
@@ -21,7 +20,7 @@
  * (`resolveLabelSpec` + `applyTemplate`, themselves pure). Redaction-WARN
  * ownership: the resolver does NOT log the redaction WARN. {@link resolveLabelDetailed} returns
  * `redactionsApplied` upward so the ActivityStream (which holds the injected
- * logger) emits the single WARN when non-empty (spec §10.1). It never imports
+ * logger) emits the single WARN when non-empty. It never imports
  * `channels` (the hexagonal boundary).
  *
  * @module
@@ -44,7 +43,7 @@ export function resolveLabel(toolName, params, opts = {}) {
  * @returns the resolved label + redaction records, or `null` under suppression.
  */
 export function resolveLabelDetailed(toolName, params, opts = {}) {
-    // (1) suppressActivity short-circuit — no activity at all (spec §10.3).
+    // (1) suppressActivity short-circuit — no activity at all.
     if (opts.metadata?.suppressActivity === true)
         return null;
     // (2) The action discriminator (if present) selects a per-action spec.

package/node_modules/@comis/observability/dist/activity/plan-stream.d.ts

@@ -1,6 +1,6 @@
 /**
  * plan-stream — derives plan-update events from the Silent Execution Planner
- * (SEP) without introducing a new tool (spec §16.7).
+ * (SEP) without introducing a new tool.
  *
  * SEP is the canonical plan-state source. The bus already emits
  * `sep:plan_extracted` whenever the agent extracts a plan, and the live
@@ -10,8 +10,8 @@
  *     and emits a {@link PlanUpdate} whose entries map from `ExecutionPlan.steps`.
  *   - subscribes `tool:executed` → re-reads the plan and re-emits, so checkbox
  *     transitions (derived by SEP via `PlanStep.completedBy`) surface as the
- *     tools complete. `completedBy: undefined` ⇒ "no completions yet" (§16.7).
- *   - registers NO new plan-state tool (the reviewer's blocking finding); SEP
+ *     tools complete. `completedBy: undefined` ⇒ "no completions yet".
+ *   - registers NO new plan-state tool; SEP
  *     remains the single source of truth.
  *
  * Mirrors the cache-trace `event-bus-bridge.ts` subscription-bag idiom: a
@@ -62,6 +62,6 @@ export interface PlanStream {
     subscribe(onPlanUpdate: (update: PlanUpdate) => void): () => void;
 }
 /**
- * Create the SEP plan-stream. NO new tool is registered (§16.7).
+ * Create the SEP plan-stream. NO new tool is registered.
  */
 export declare function createPlanStream(deps: CreatePlanStreamDeps): PlanStream;