comisai 1.0.44 → 1.0.46

package/node_modules/@comis/daemon/dist/api/video-handlers.js

@@ -1,26 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
 // @allow-throw: RPC handler module — all throws are caught and converted to JSON-RPC error responses by rpc-dispatch.ts.
 /**
- * Video generation RPC handler module (Phase 188 baseline → Phase 189 async switch).
+ * Video generation RPC handler module.
  *
  * Provides the `video.generate` handler that bridges the agent `video_generate`
  * tool to the boot-selected `VideoGenerationPort`. It validates, rate-limits,
- * gates the PRE-SUBMIT worst-case cost estimate (SEC-02 / DIVERGENCE 3), and
- * resolves an optional SSRF-safe `image_url` (SEC-03 — text-to-video baseline;
- * the i2v variant-select is Phase 191).
+ * gates the PRE-SUBMIT worst-case cost estimate, and resolves an optional
+ * SSRF-safe `image_url` reference image.
  *
- * PHASE 189 (JOB-04 / JOB-02 — inline→submit): the handler no longer runs the
- * blocking inline `port.execute()` + persist/deliver/base64 tail (which held the
- * agent turn for the full 30 s–5 min render). It now `port.submit()`s, persists a
+ * ASYNC SUBMIT (never inline execute): the handler does not run a blocking
+ * inline `port.execute()` + persist/deliver/base64 tail (which would hold the
+ * agent turn for the full 30 s–5 min render). It `port.submit()`s, persists a
  * `pending` `VideoJobStore` row (the durable spine the background poller resumes
  * against across the turn AND a daemon restart), hands the FULL in-memory record
- * to the poller via `videoPoller.track(record)` (WR-02/WR-06 — so the poller
- * drives delivery from in-memory routing and an insert-failure is delivered
- * in-memory rather than orphaned), and returns `{jobId, state:"submitted",
+ * to the poller via `videoPoller.track(record)` (so the poller drives delivery
+ * from in-memory routing and an insert-failure is delivered in-memory rather
+ * than orphaned), and returns `{jobId, state:"submitted",
  * estimatedCostUsd}` PROMPTLY. The completion tail (poll→fetchResult→persist→
  * deliver→markDone→record(actualCost)) lives in `setup-video-poller.ts`.
  *
- * WARNING-3 / I8 (Pitfall 5): the row carries a `traceId` captured HERE from the
+ * Trace stitching: the row carries a `traceId` captured HERE from the
  * in-turn ALS context (`tryGetContext()`) — the media-tool RPC producer injects
  * no `_traceId` (image-handlers.ts:470), and the off-turn poller has no ALS frame,
  * so the trace MUST be persisted at submit for the poller to stitch the later
@@ -30,16 +29,17 @@
  * so the bidirectional 1:1 contract↔handler parity gate resolves it through
  * `defineContract({ method, ... })` in `packages/core/src/api-contracts/media.ts`.
  *
- * OBSERVABILITY SCOPE (logger-only): the handler's troubleshootability is
- * structured Pino logger lines per the §2.7 matrix — an INFO submit line on
- * success + an ERROR/WARN carrying `errorKind` + `hint` on EVERY failure branch
- * (the I8 baseline). It emits NO `video.*` trajectory events; that bridge is
- * OBS-04 / Phase 192 (the poller emits the off-turn completion lines).
+ * OBSERVABILITY SCOPE: the handler's troubleshootability is structured Pino
+ * logger lines per the §2.7 matrix — an INFO submit line on success + an
+ * ERROR/WARN carrying `errorKind` + `hint` on EVERY failure branch. Its
+ * trajectory footprint is the in-turn `video.requested`/`video.submitted`/
+ * `video.failed` records via `createVideoObsEmitter`; the poller emits the
+ * off-turn completion records.
  *
- * RES-01 lockstep (I4): the handler resolves the agent's main provider for the
+ * Provider lockstep: the handler resolves the agent's main provider for the
  * obs line ONLY — the provider INSTANCE was selected ONCE at boot
- * (setup-video-provider.ts). It is NEVER re-derived here (the v2.20
- * keyless-summarizer two-source firewall).
+ * (setup-video-provider.ts). It is NEVER re-derived here (a second selection
+ * source of truth could silently diverge from the wired port).
  *
  * @module
  */
@@ -49,7 +49,7 @@ import { createVideoObsEmitter } from "./video-obs-emit.js";
 /**
  * Read an operator-facing `hint` off a provider error if it carries one. The FAL
  * adapter surfaces failures as a typed `VideoGenError` carrying a knob-naming
- * `hint` (the RES-03/FAL-02 carrier). Narrow duck-type guard (not `instanceof`)
+ * `hint`. Narrow duck-type guard (not `instanceof`)
  * so the handler does not import the adapter module — mirrors `extractImageHint`.
  */
 function extractVideoHint(error) {
@@ -68,19 +68,19 @@ export function createVideoHandlers(deps) {
             // (not Date.now() — the globals gate forbids it).
             const startMs = systemNowMs();
             const agentId = rawParams._agentId ?? "default";
-            // RES-01 keystone (I4 lockstep): resolve the agent's main provider in
-            // lockstep with the completion + image paths. This is OBS-only (the obs
-            // line + the lockstep proof); the provider INSTANCE was selected at wiring
-            // time (setup-video-provider.ts) — do NOT re-derive selection here (a
-            // second source of truth is the v2.20 keyless-summarizer failure class).
+            // Resolve the agent's main provider in lockstep with the completion +
+            // image paths. This is OBS-only (the obs line + the lockstep proof); the
+            // provider INSTANCE was selected at wiring time (setup-video-provider.ts)
+            // — do NOT re-derive selection here (a second source of truth can
+            // silently diverge from the wired port).
             const main = deps.resolveAgentMainProvider(agentId);
             deps.logger.debug({ agentId, mainProvider: main.providerId, step: "video_resolve" }, "Video request resolved main provider");
-            // OBS-04 (Phase 192): construct the trajectory emitter — this fires the
+            // Construct the trajectory emitter — this fires the
             // `video.requested` entry record onto the per-session trajectory (resolved
             // by the dispatcher-injected `_callerSessionKey`). It is trajectory-only +
             // null-safe: a boot mode without a registry / no session key no-ops (the
             // §2.7 logger floor below still fires). The off-turn poller emits the
-            // generated/delivered records; the OFFLINE assembler (Plan 02) is the
+            // generated/delivered records; the OFFLINE assembler is the
             // binding reconstruction oracle. `sessionKey` is also persisted on the row
             // below so the off-turn poller can resolve the recorder for the completion.
             const callerSessionKey = typeof rawParams._callerSessionKey === "string" ? rawParams._callerSessionKey : undefined;
@@ -90,7 +90,7 @@ export function createVideoHandlers(deps) {
                 agentId,
                 requested: { provider: deps.provider.id, mainProvider: main.providerId },
             });
-            // WR-05 precedent: `main.providerId` is the CALLER's provider, resolved
+            // `main.providerId` is the CALLER's provider, resolved
             // per-request for obs/lockstep only; `deps.provider` is the boot-selected
             // port (the DEFAULT agent's selection). A NON-default agent whose main
             // provider DIFFERS runs the default's port — a documented scope boundary
@@ -119,28 +119,28 @@ export function createVideoHandlers(deps) {
             if (!prompt) {
                 return { success: false, error: "Missing required parameter: prompt" };
             }
-            // WR-02: resolve the config defaults ONCE, here, so the worst-case
+            // Resolve the config defaults ONCE, here, so the worst-case
             // estimate and the port input AGREE on the duration/resolution/audio. If
             // the input only carried explicitly-supplied fields, the provider would
             // apply its OWN defaults (which need not match Comis's config defaults) —
             // and the estimate, computed against the config defaults, could UNDER-count
             // the actual render (e.g. config 720p but a provider default of 1080p/4k).
-            // SEC-02's contract is a worst-case UPPER bound; aligning estimate↔request
+            // The cost-ceiling contract is a worst-case UPPER bound; aligning estimate↔request
             // restores it. `audio` stays undefined when neither param nor config sets
             // it (→ provider default; the estimate uses no audio surcharge to match).
             const resolvedDurationSecs = params.duration ?? deps.config.defaultDurationSecs;
             const resolvedResolution = params.resolution ?? deps.config.defaultResolution;
             const resolvedAspectRatio = params.aspect_ratio ?? deps.config.defaultAspectRatio;
             const resolvedAudio = params.audio ?? deps.config.generateAudio;
-            // SEC-02 / DIVERGENCE 3 — the PRE-SUBMIT worst-case cost ceiling. Compute
-            // the estimate FIRST (a video clip is ALREADY rendering once submitted, I6,
+            // The PRE-SUBMIT worst-case cost ceiling. Compute
+            // the estimate FIRST (a video clip is ALREADY rendering once submitted,
             // so the gate cannot wait for the actual cost), then gate the SUM
             // (accumulated + estimate) BEFORE port.execute. Optional: undefined when
             // `maxCostPerHourUsd` is unset → the ceiling is skipped (count-only, no
             // regression). Exceeding it blocks with quota_exceeded (logger-only WARN +
             // a hint naming the knob), and port.execute is NOT called.
             //
-            // WR-03 ordering: the cost ceiling is checked BEFORE the count rate limit
+            // Ordering: the cost ceiling is checked BEFORE the count rate limit
             // (tryAcquire) so a cost-blocked request does NOT burn a count slot for a
             // render that never happened (which would exhaust maxPerHour without ever
             // rendering, and surface the less-actionable count error). The count limit
@@ -163,14 +163,14 @@ export function createVideoHandlers(deps) {
                     estimatedCostUsd,
                     hint,
                 }, "Video generation blocked: per-hour cost ceiling reached");
-                // OBS-04 (Phase 192): record video.failed{quota_exceeded} on the
+                // Record video.failed{quota_exceeded} on the
                 // trajectory BESIDE the WARN above (the emitter is trajectory-only — the
-                // WARN is the single §2.7 line; no double-log, SEC-02 step unchanged).
+                // WARN is the single §2.7 line; no double-log).
                 obs.failed({ errorKind: "quota_exceeded", provider: deps.provider.id });
                 return { success: false, error: "Video generation cost ceiling exceeded", hint };
             }
-            // Count rate limit (SEC-02, RETAINED) — checked AFTER the cost ceiling
-            // (WR-03) but still BEFORE the submit. tryAcquire is an atomic
+            // Count rate limit — checked AFTER the cost ceiling
+            // but still BEFORE the submit. tryAcquire is an atomic
             // check-and-increment (cannot be raced), so it bounds the blast radius for
             // the soft cost ceiling above. A block is a quota-style guard: WARN with
             // the closed-union log errorKind + the domain videoErrorKind + a hint
@@ -186,7 +186,7 @@ export function createVideoHandlers(deps) {
                     videoErrorKind: "quota_exceeded",
                     hint,
                 }, "Video generation blocked: per-hour count rate limit reached");
-                // OBS-04 (Phase 192): record video.failed{quota_exceeded} beside the WARN
+                // Record video.failed{quota_exceeded} beside the WARN
                 // (trajectory-only — the WARN is the single §2.7 line).
                 obs.failed({ errorKind: "quota_exceeded", provider: deps.provider.id });
                 return {
@@ -194,36 +194,35 @@ export function createVideoHandlers(deps) {
                     error: `Rate limit exceeded: max ${deps.config.maxPerHour} videos per hour`,
                 };
             }
-            // SEC-03 image_url resolution (text-to-video baseline). Resolve ONLY when
+            // image_url resolution. Resolve ONLY when
             // supplied; absence keeps the request text-only. The resolution reuses the
             // SHARED SSRF + path-traversal resolver (the image guard verbatim —
-            // workspace-confined + DNS-pinned + size-capped). The full i2v
-            // variant-select is Phase 191 — here the resolved referenceImage is just
-            // threaded to the port.
+            // workspace-confined + DNS-pinned + size-capped). The resolved
+            // referenceImage is threaded to the port as-is.
             let referenceImage;
             if (params.image_url) {
                 referenceImage = await resolveReferenceImage(params.image_url, { workspaceDirs: deps.workspaceDirs, defaultWorkspaceDir: deps.defaultWorkspaceDir }, rawParams._agentId);
             }
-            // (reference_images[] multi-ref resolution is the LOCKED deferral — the
-            // handler resolves ONLY the singular image_url above; Plan 03 adds no array
-            // tool param either, so there is no params.reference_images to read.)
-            // IN-02 validation (I3 honest, BEFORE submit — mirrors image-handlers.ts:249-268):
+            // (reference_images[] multi-ref resolution is deliberately unsupported —
+            // the handler resolves ONLY the singular image_url above; the tool schema
+            // declares no array param either, so there is no params.reference_images to read.)
+            // Capability validation (honest, BEFORE submit — mirrors image-handlers.ts:249-268):
             // validate the resolved params against the ACTIVE model's VIDEO_MODELS caps
             // and reject an unsupported value with a hint LISTING the valid set + a
             // precondition WARN, rather than letting it surface as an opaque provider 4xx.
             //
-            // WR-05 / multi-agent anti-pattern: validate against the EXECUTING
+            // Multi-agent anti-pattern: validate against the EXECUTING
             // `deps.provider.id` (the boot-selected DEFAULT agent's port), NEVER the
             // caller's `main.providerId` — they can differ (the divergence WARN above);
             // validating against the caller would PASS a value the caller's main allows
             // but the executor then rejects LATE at the provider. The model passed to
-            // the accessor is untrusted but SEC-04-guarded inside listVideoModelCaps
+            // the accessor is untrusted but prototype-pollution-guarded inside listVideoModelCaps
             // (isBlockedObjectKey precedes the index) — no raw VIDEO_MODELS index here.
             const mode = referenceImage ? "i2v" : "t2v";
             const activeModel = params.model ?? deps.config.model;
             const caps = listVideoModelCaps(deps.provider.id, mode, activeModel);
             if (!caps) {
-                // CAP-02 (b): the requested mode is unsupported by this backend (e.g. i2v
+                // The requested mode is unsupported by this backend (e.g. i2v
                 // on a t2v-only model). List the supported modes; for an i2v miss, point
                 // the agent at text-to-video (drop image_url).
                 const modes = supportedModes(deps.provider.id);
@@ -232,13 +231,13 @@ export function createVideoHandlers(deps) {
                 deps.logger.warn({ agentId, step: "video_mode_reject", errorKind: "precondition", hint }, "Video generation rejected: mode unsupported for the executing provider");
                 return { success: false, error: `${mode} is not supported by provider "${deps.provider.id}"`, hint };
             }
-            // WR-02 (CAP-02): the matrix declares `maxReferenceImages` on every cell —
+            // The matrix declares `maxReferenceImages` on every cell —
             // ENFORCE it. An i2v request (image present) resolving to a cell that
             // accepts no reference image (e.g. `veo-2.0-generate-001` with
             // `maxReferenceImages: 0`) returns a NON-undefined caps object, so the
             // `if (!caps)` mode-reject above does NOT fire; without this guard the image
             // ships to a model the matrix itself says cannot take one → a guaranteed
-            // provider 4xx (the exact class IN-02 exists to close). Reject pre-submit
+            // provider 4xx (the exact class this pre-submit validation exists to close). Reject pre-submit
             // with a hint pointing the agent at text-to-video (drop image_url).
             if (mode === "i2v" && caps.maxReferenceImages < 1) {
                 const modelLabel = activeModel ? ` (${activeModel})` : "";
@@ -269,18 +268,18 @@ export function createVideoHandlers(deps) {
                     hint,
                 };
             }
-            // Pitfall 2 (Veo cross-field): 1080p/4k REQUIRE duration 8 — honest reject
+            // Veo cross-field constraint: 1080p/4k REQUIRE duration 8 — honest reject
             // over a provider 4xx the matrix exists to prevent.
             if (caps.requires8sFor &&
                 resolvedResolution &&
                 caps.requires8sFor.includes(resolvedResolution) &&
                 resolvedDurationSecs !== 8) {
-                // WR-01: the hint states ONLY the constraint actually enforced here — the
-                // resolution→8s rule keyed on `requires8sFor` (1080p/4k). The previous
-                // "(and reference images)" clause claimed a ref-image→8s rule the
-                // validator never enforces and the native-Veo-SDK research does not
-                // document (durationSeconds is a free number for i2v there), so it is
-                // dropped to keep the honest-rejection contract truthful (§2.7).
+                // The hint states ONLY the constraint actually enforced here — the
+                // resolution→8s rule keyed on `requires8sFor` (1080p/4k). Do not extend
+                // it to claim a ref-image→8s rule: the validator enforces none and the
+                // native Veo SDK documents none (durationSeconds is a free number for
+                // i2v there) — the honest-rejection contract (§2.7) requires the hint
+                // to match exactly what is enforced.
                 const hint = `${deps.provider.id} requires duration 8 for ${resolvedResolution}; set duration: 8.`;
                 deps.logger.warn({ agentId, step: "video_duration_constraint_reject", errorKind: "precondition", hint }, "Video generation rejected: resolution requires 8s");
                 return {
@@ -289,14 +288,14 @@ export function createVideoHandlers(deps) {
                     hint,
                 };
             }
-            // Pitfall 3: SNAP (enum) / CLAMP (range) the resolved duration via the matrix
+            // SNAP (enum) / CLAMP (range) the resolved duration via the matrix
             // so the wire value is in-enum (an out-of-enum raw duration reaching FAL/Veo
-            // would otherwise be a provider error). Round-half-up on enum ties (Plan 01).
+            // would otherwise be a provider error). Round-half-up on enum ties.
             // NOTE: the cost estimate above stays on the PRE-snap resolvedDurationSecs —
             // snapping only lowers-or-equals (never raises) the duration, so the estimate
             // remains a conservative worst-case ceiling; do NOT re-order it after the snap.
             const snappedDurationSecs = resolvedDurationSecs !== undefined ? snapDuration(caps, resolvedDurationSecs) : resolvedDurationSecs;
-            // WR-02: build the port input with the RESOLVED duration/resolution/
+            // Build the port input with the RESOLVED duration/resolution/
             // aspectRatio (param OR config default) — the same values the estimate
             // above used — so the provider renders exactly what was priced and cannot
             // apply a higher-cost default the estimate never saw. `audio` is sent only
@@ -313,18 +312,18 @@ export function createVideoHandlers(deps) {
                 ...(referenceImage ? { referenceImage } : {}),
                 ...(params.model !== undefined ? { model: params.model } : {}),
             };
-            // JOB-04 (189) — submit, do NOT execute. `submit()` captures the durable
+            // Submit, do NOT execute. `submit()` captures the durable
             // opaque jobId WITHOUT blocking the turn on the full 30 s–5 min render. The
             // completion tail (poll→fetchResult→persist→deliver→record→markDone) is the
-            // background poller's job (setup-video-poller.ts) — see Q3/O2 LOCKED (fully
-            // async; no inline fast-path).
+            // background poller's job (setup-video-poller.ts) — fully
+            // async; there is deliberately no inline fast-path.
             const submitted = await deps.provider.submit(input);
             if (!submitted.ok) {
-                // SAME classified-error WARN path as the 188 !result.ok branch: the typed
+                // Classified-error WARN path: the typed
                 // VideoGenError carries the domain videoErrorKind; an untyped plain Error
                 // has none → the untyped fallback is the domain empty_response. The closed
                 // 10-member log ErrorKind rides the Pino line via VIDEO_ERR_TO_LOG. NEVER
-                // log the raw provider message beyond the typed hint (SEC-03 — the hint is
+                // log the raw provider message beyond the typed hint (the hint is
                 // the knob-naming carrier, never a key).
                 const videoErrorKind = submitted.error.videoErrorKind;
                 const domainKind = typeof videoErrorKind === "string" ? videoErrorKind : "empty_response";
@@ -336,13 +335,13 @@ export function createVideoHandlers(deps) {
                     step: "video_submit",
                     errorKind: VIDEO_ERR_TO_LOG[domainKind] ?? "dependency",
                     videoErrorKind: domainKind,
-                    // SEC-03 (defense-in-depth): the hint is a knob-naming carrier the
+                    // Defense-in-depth: the hint is a knob-naming carrier the
                     // adapter builds to be secret-free, but a provider that wrongly echoes
                     // a key/bearer/keyed-URL into it must still not leak into the log —
                     // scrub the LOGGED hint (the caller-facing return keeps the contract).
                     ...(hint ? { hint: sanitizeLogString(hint) } : {}),
                 }, "Video generation submit failed");
-                // OBS-04 (Phase 192): record video.failed{domainKind} beside the WARN
+                // Record video.failed{domainKind} beside the WARN
                 // (trajectory-only — the WARN is the single §2.7 line; the raw provider
                 // message never rides the trajectory payload, only the typed kind).
                 obs.failed({ errorKind: domainKind, provider: deps.provider.id });
@@ -351,7 +350,7 @@ export function createVideoHandlers(deps) {
                     : { success: false, error: submitted.error.message };
             }
             const job = submitted.value;
-            // WARNING-3 / I8 (Pitfall 5): capture the trace HERE, in-turn, from the ALS
+            // Capture the trace HERE, in-turn, from the ALS
             // context, and PERSIST it on the row. The media-tool RPC producer injects no
             // `_traceId` into rawParams (setup-tools.ts:336-343 — only `_agentId` /
             // `_callerChannel*`), and the off-turn poller has NO ALS frame, so the only
@@ -360,13 +359,13 @@ export function createVideoHandlers(deps) {
             // `undefined` outside a request scope (a unit-test call), so the column is
             // nullable and the field is always threaded.
             const traceId = tryGetContext()?.traceId;
-            // JOB-01 (189): build the durable `pending` record ONCE — it is both the
+            // Build the durable `pending` record ONCE — it is both the
             // row persisted to the store (the spine the poller resumes against across
             // the turn AND a daemon restart) AND the in-memory record handed to
-            // `track()` (WR-02/WR-06: the poller drives delivery from this record
-            // directly, with no listPending scan). The routing is the SAME source the
-            // 188 deliver path read (`_callerChannel*`); a NON-default agent's job is
-            // recorded under its own agentId (T-189-06 — the poller delivers only to
+            // `track()` (the poller drives delivery from this record
+            // directly, with no listPending scan). The routing comes from the
+            // dispatcher-injected `_callerChannel*` fields; a NON-default agent's job is
+            // recorded under its own agentId (the poller delivers only to
             // the recorded channel/agent, never a silent default).
             const nowSubmitMs = systemNowMs();
             const record = {
@@ -378,9 +377,9 @@ export function createVideoHandlers(deps) {
                 ...(typeof rawParams._callerChannelId === "string" ? { channelId: rawParams._callerChannelId } : {}),
                 // Always thread the traceId KEY (value may be undefined outside an ALS
                 // scope) so the off-turn poller's stitching contract is explicit (the
-                // store maps `?? null`). WARNING-3 / I8 / Pitfall 5.
+                // store maps `?? null`).
                 traceId,
-                // OBS-04 (Phase 192): persist the formatted session key (the
+                // Persist the formatted session key (the
                 // dispatcher-injected `_callerSessionKey`, captured in-turn at entry) so
                 // the OFF-TURN poller resolves the per-session trajectory recorder
                 // (getRecorder(record.sessionKey)) to stitch the background completion to
@@ -389,14 +388,14 @@ export function createVideoHandlers(deps) {
                 ...(callerSessionKey !== undefined ? { sessionKey: callerSessionKey } : {}),
                 state: "pending",
                 ...(estimatedCostUsd !== undefined ? { estimatedCostUsd } : {}),
-                // CR-01: a freshly-submitted job starts at zero delivery attempts.
+                // A freshly-submitted job starts at zero delivery attempts.
                 deliverAttempts: 0,
                 submittedAtMs: nowSubmitMs,
                 updatedAtMs: nowSubmitMs,
             };
             const insertResult = await deps.videoJobStore.insert(record);
             if (!insertResult.ok) {
-                // WR-02: the job IS submitted (rendering) but the row could not be
+                // The job IS submitted (rendering) but the row could not be
                 // persisted, so it will NOT survive a daemon restart — the boot-resume
                 // scan has no row to find. It is NOT orphaned, though: `track(record)`
                 // below drives the completion tail (poll→fetch→persist→deliver) IN-MEMORY
@@ -414,13 +413,13 @@ export function createVideoHandlers(deps) {
                     step: "video_persist_row",
                 }, "Video job row persistence failed (submitted, delivered in-memory, restart-durability degraded)");
             }
-            // JOB-02 (189): hand the FULL record to the background poller, which drives
-            // the completion tail off-turn (kicks a `pollUntilDone` per job). WR-02/
-            // WR-06: passing the record (not the bare job) means the poller delivers
+            // Hand the FULL record to the background poller, which drives
+            // the completion tail off-turn (kicks a `pollUntilDone` per job).
+            // Passing the record (not the bare job) means the poller delivers
             // from in-memory routing — no listPending scan, and the insert-failure path
             // above is genuinely delivered rather than silently orphaned.
             deps.videoPoller.track(record);
-            // §2.7 I8: the submit completion line. traceId rides the Pino ALS mixin
+            // §2.7: the submit completion line. traceId rides the Pino ALS mixin
             // in-turn (it is also persisted above for the off-turn poller).
             deps.logger.info({
                 agentId,
@@ -431,15 +430,14 @@ export function createVideoHandlers(deps) {
                 durationMs: systemNowMs() - startMs,
                 step: "video_submitted",
             }, "Video generation submitted (async)");
-            // OBS-04 (Phase 192): record video.submitted{provider, jobId} on the
+            // Record video.submitted{provider, jobId} on the
             // trajectory AFTER the row persist + track() + the §2.7 INFO line above
             // (trajectory-only — the INFO is the §2.7 line). With the entry
             // video.requested (fired at construction), this is the in-turn record pair
             // the OFFLINE assembler reads to reconstruct a background-completed turn.
             obs.submitted({ provider: deps.provider.id, jobId: job.jobId });
-            // The job handle. A3: validates against the EXISTING loose-record
-            // VideoGenerateContract.response (`z.record(z.string(), z.unknown())`) — no
-            // contract change for video.generate (only video.status is new, Plan 03).
+            // The job handle validates against the loose-record
+            // VideoGenerateContract.response (`z.record(z.string(), z.unknown())`).
             const handle = {
                 success: true,
                 jobId: job.jobId,

package/node_modules/@comis/daemon/dist/api/video-obs-emit.d.ts

@@ -1,5 +1,5 @@
 /**
- * OBS-04 (Phase 192): the video-turn trajectory direct-emit helper.
+ * The video-turn trajectory direct-emit helper.
  *
  * The daemon video RPC handler (`video.generate`, in-turn) AND the off-turn
  * background poller (`setup-video-poller.ts`) record a video turn's lifecycle
@@ -12,25 +12,25 @@
  * NO-OPs every emit when no recorder resolved — a session that closed (the agent
  * destroyed it) or a daemon restart leaves the in-memory session registry empty,
  * so `getRecorder` returns null/undefined and the live off-turn emit is
- * best-effort. The BINDING OBS-04 oracle is the OFFLINE assembler (Plan 02's
+ * best-effort. The BINDING oracle is the OFFLINE assembler (pinned by the
  * reconstruct test), which reads the persisted trajectory + the job store
  * independent of any live recorder — so a no-op here is correct, never a crash.
  *
  * DIVERGENCE FROM `createVisionObsEmitter` (vision-obs-emit.ts): the vision twin
  * FUSES the trajectory record AND the §2.7 log line per call, because the vision
- * handler had NO prior structured logging. The video handler (188) + poller
- * (189/190) ALREADY carry the complete §2.7 logger floor — an INFO completion
+ * handler carries no structured logging of its own. The video handler + poller
+ * ALREADY carry the complete §2.7 logger floor — an INFO completion
  * line + an ERROR/WARN with errorKind+hint on EVERY branch, with branch-specific
- * `step` tags the SEC-02 / poller-step tests pin. So THIS emitter is
+ * `step` tags their tests pin. So THIS emitter is
  * trajectory-RECORD-focused: it adds ONLY the per-session trajectory records and
  * does NOT re-log (a fused log would DOUBLE-emit the §2.7 line). The handler/
  * poller keep their existing logger lines and call these methods beside them.
  *
- * CONTENT-FREE (T-192-01): every recorded payload carries ids / labels / counts /
+ * CONTENT-FREE: every recorded payload carries ids / labels / counts /
  * `costUsd` / `outcome` / `errorKind` / booleans ONLY — NEVER the prompt, the
  * video bytes, a credential, the Veo keyed-download-URL, or a raw provider
  * message. `costUsd`/`model`/`sizeBytes`/`durationSecs` ride `video.generated`
- * presence-conditionally (FAL reports no actual cost — Pitfall 4 — so an absent
+ * presence-conditionally (FAL reports no actual cost, so an absent
  * value never appears as an `undefined` key). The domain `VideoErrorKind` rides
  * `video.failed.errorKind` verbatim (the redaction-safe detail + the closed log
  * union via VIDEO_ERR_TO_LOG ride the structured Pino LOG, not the trajectory).
@@ -54,7 +54,8 @@ export interface VideoObsEmitter {
         jobId: string;
     }): void;
     /** A render SUCCEEDED (off-turn): record video.generated with the cost-carry
-     *  (model/costUsd/sizeBytes/durationSecs presence-conditional — Pitfall 4). */
+     *  (model/costUsd/sizeBytes/durationSecs presence-conditional — some
+     *  providers report no actual cost). */
     generated(args: {
         provider: string;
         model?: string;

package/node_modules/@comis/daemon/dist/api/video-obs-emit.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * OBS-04 (Phase 192): the video-turn trajectory direct-emit helper.
+ * The video-turn trajectory direct-emit helper.
  *
  * The daemon video RPC handler (`video.generate`, in-turn) AND the off-turn
  * background poller (`setup-video-poller.ts`) record a video turn's lifecycle
@@ -13,25 +13,25 @@
  * NO-OPs every emit when no recorder resolved — a session that closed (the agent
  * destroyed it) or a daemon restart leaves the in-memory session registry empty,
  * so `getRecorder` returns null/undefined and the live off-turn emit is
- * best-effort. The BINDING OBS-04 oracle is the OFFLINE assembler (Plan 02's
+ * best-effort. The BINDING oracle is the OFFLINE assembler (pinned by the
  * reconstruct test), which reads the persisted trajectory + the job store
  * independent of any live recorder — so a no-op here is correct, never a crash.
  *
  * DIVERGENCE FROM `createVisionObsEmitter` (vision-obs-emit.ts): the vision twin
  * FUSES the trajectory record AND the §2.7 log line per call, because the vision
- * handler had NO prior structured logging. The video handler (188) + poller
- * (189/190) ALREADY carry the complete §2.7 logger floor — an INFO completion
+ * handler carries no structured logging of its own. The video handler + poller
+ * ALREADY carry the complete §2.7 logger floor — an INFO completion
  * line + an ERROR/WARN with errorKind+hint on EVERY branch, with branch-specific
- * `step` tags the SEC-02 / poller-step tests pin. So THIS emitter is
+ * `step` tags their tests pin. So THIS emitter is
  * trajectory-RECORD-focused: it adds ONLY the per-session trajectory records and
  * does NOT re-log (a fused log would DOUBLE-emit the §2.7 line). The handler/
  * poller keep their existing logger lines and call these methods beside them.
  *
- * CONTENT-FREE (T-192-01): every recorded payload carries ids / labels / counts /
+ * CONTENT-FREE: every recorded payload carries ids / labels / counts /
  * `costUsd` / `outcome` / `errorKind` / booleans ONLY — NEVER the prompt, the
  * video bytes, a credential, the Veo keyed-download-URL, or a raw provider
  * message. `costUsd`/`model`/`sizeBytes`/`durationSecs` ride `video.generated`
- * presence-conditionally (FAL reports no actual cost — Pitfall 4 — so an absent
+ * presence-conditionally (FAL reports no actual cost, so an absent
  * value never appears as an `undefined` key). The domain `VideoErrorKind` rides
  * `video.failed.errorKind` verbatim (the redaction-safe detail + the closed log
  * union via VIDEO_ERR_TO_LOG ride the structured Pino LOG, not the trajectory).

package/node_modules/@comis/daemon/dist/api/video-status-handlers.d.ts

@@ -1,13 +1,13 @@
 /**
- * Video status RPC handler module (Phase 189 Plan 03 — JOB-04).
+ * Video status RPC handler module.
  *
  * Provides the `video.status` handler that reads the durable `VideoJobStore` and
  * reports `{state, progress?, mediaPath?, costUsd?, error?}` for a job. This
- * closes the JOB-04 loop: `video.generate` returns a handle (Plan 02), the
- * background poller drives the render off-turn (Plan 02), and `video.status`
+ * closes the async-job loop: `video.generate` returns a handle, the
+ * background poller drives the render off-turn, and `video.status`
  * reports the durable terminal state the poller wrote.
  *
- * AGENT-SCOPED (JOB-04 / TARGET-01 / Pitfall 6 / threat T-189-10): the handler
+ * AGENT-SCOPED (cross-agent read is a data leak): the handler
  * resolves the calling agent EXPLICITLY (`?? "default"`, never silent) and reads
  * the agent-scoped `videoJobStore.get(job_id, agentId)` — which filters by BOTH
  * the jobId AND the agentId. A job belonging to ANOTHER agent matches no row and
@@ -16,18 +16,18 @@
  * is `ok(undefined)` (distinct from a real lookup error), so this handler answers
  * "no such job for this agent" rather than throwing.
  *
- * RES-01 / single-source: this handler is a PURE consumer of the boot-selected
+ * Single-source: this handler is a PURE consumer of the boot-selected
  * store (the SAME `videoJobStore` the poller writes — `buildVideoGenBundle`
- * constructs one instance). It re-derives nothing (the v2.20 keyless-summarizer
- * two-source firewall).
+ * constructs one instance). It re-derives nothing (a second source of truth
+ * can silently diverge from what the poller wrote).
  *
  * The handler key is the computed-property name `[VideoStatusContract.method]`
  * so the bidirectional 1:1 contract↔handler parity gate resolves it through
  * `defineContract({ method, ... })` in `packages/core/src/api-contracts/media.ts`.
  *
  * OBSERVABILITY SCOPE (logger-only): a content-free DEBUG on the not-found branch
- * naming the resolved agentId (TARGET-01) — never the other agent's data. No
- * `video.*` trajectory events (that bridge is OBS-04 / Phase 192).
+ * naming the resolved agentId — never the other agent's data. No
+ * `video.*` trajectory events (the generate handler + poller own that bridge).
  *
  * @module
  */

package/node_modules/@comis/daemon/dist/api/video-status-handlers.js

@@ -3,15 +3,15 @@
 // a malformed request) are caught and converted to JSON-RPC error responses by
 // rpc-dispatch.ts.
 /**
- * Video status RPC handler module (Phase 189 Plan 03 — JOB-04).
+ * Video status RPC handler module.
  *
  * Provides the `video.status` handler that reads the durable `VideoJobStore` and
  * reports `{state, progress?, mediaPath?, costUsd?, error?}` for a job. This
- * closes the JOB-04 loop: `video.generate` returns a handle (Plan 02), the
- * background poller drives the render off-turn (Plan 02), and `video.status`
+ * closes the async-job loop: `video.generate` returns a handle, the
+ * background poller drives the render off-turn, and `video.status`
  * reports the durable terminal state the poller wrote.
  *
- * AGENT-SCOPED (JOB-04 / TARGET-01 / Pitfall 6 / threat T-189-10): the handler
+ * AGENT-SCOPED (cross-agent read is a data leak): the handler
  * resolves the calling agent EXPLICITLY (`?? "default"`, never silent) and reads
  * the agent-scoped `videoJobStore.get(job_id, agentId)` — which filters by BOTH
  * the jobId AND the agentId. A job belonging to ANOTHER agent matches no row and
@@ -20,18 +20,18 @@
  * is `ok(undefined)` (distinct from a real lookup error), so this handler answers
  * "no such job for this agent" rather than throwing.
  *
- * RES-01 / single-source: this handler is a PURE consumer of the boot-selected
+ * Single-source: this handler is a PURE consumer of the boot-selected
  * store (the SAME `videoJobStore` the poller writes — `buildVideoGenBundle`
- * constructs one instance). It re-derives nothing (the v2.20 keyless-summarizer
- * two-source firewall).
+ * constructs one instance). It re-derives nothing (a second source of truth
+ * can silently diverge from what the poller wrote).
  *
  * The handler key is the computed-property name `[VideoStatusContract.method]`
  * so the bidirectional 1:1 contract↔handler parity gate resolves it through
  * `defineContract({ method, ... })` in `packages/core/src/api-contracts/media.ts`.
  *
  * OBSERVABILITY SCOPE (logger-only): a content-free DEBUG on the not-found branch
- * naming the resolved agentId (TARGET-01) — never the other agent's data. No
- * `video.*` trajectory events (that bridge is OBS-04 / Phase 192).
+ * naming the resolved agentId — never the other agent's data. No
+ * `video.*` trajectory events (the generate handler + poller own that bridge).
  *
  * @module
  */
@@ -44,19 +44,19 @@ import { VideoStatusContract, stripInternalFields } from "@comis/core";
 export function createVideoStatusHandlers(deps) {
     return {
         [VideoStatusContract.method]: async (rawParams) => {
-            // Resolve the agent EXPLICITLY (never a silent default — TARGET-01).
+            // Resolve the agent EXPLICITLY (never a silent default).
             const agentId = rawParams._agentId ?? "default";
             // Validate the request (a malformed request — missing job_id — throws here
-            // and is converted to a JSON-RPC error by rpc-dispatch; T-189-12).
+            // and is converted to a JSON-RPC error by rpc-dispatch).
             const { job_id } = VideoStatusContract.request.parse(stripInternalFields(rawParams));
-            // Agent-scoped read — filters by BOTH job_id AND agentId (Pitfall 6 /
-            // T-189-10). A cross-agent jobId matches no row → ok(undefined) → not-found.
+            // Agent-scoped read — filters by BOTH job_id AND agentId.
+            // A cross-agent jobId matches no row → ok(undefined) → not-found.
             const result = await deps.videoJobStore.get(job_id, agentId);
             const job = result.ok ? result.value : undefined;
             if (!job) {
-                // Content-free not-found (TARGET-01: state the resolved agentId; the
+                // Content-free not-found (state the resolved agentId; the
                 // job_id is the opaque, secret-free provider id — echoing it leaks
-                // nothing, T-189-12). A real lookup error also lands here as not-found —
+                // nothing). A real lookup error also lands here as not-found —
                 // honest "no such job for this agent" rather than a thrown 500.
                 deps.logger.debug({ agentId, step: "video_status_not_found", ...(result.ok ? {} : { errorKind: "internal" }) }, "video.status: no job for this agent");
                 return { state: "failed", error: `No video job ${job_id} for this agent` };