@ponythewhite/base-context 1.0.15 → 1.0.16

package/dist/core/job-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-watch.d.ts","sourceRoot":"","sources":["../../src/core/job-watch.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { normalizeHeartbeatSchedule, parseAgentCronSchedule } from \"./cron-jobs.js\";\n\nexport const JOB_WATCH_STATE = \"job_watch_state\";\nexport const JOB_WATCH_CAPABILITY = \"job_watch_probe_v1\";\nconst TERMINAL = new Set([\"succeeded\", \"failed\", \"cancelled\"]);\nconst MAX_WATCHES = 16;\nconst MAX_VISIBLE_BYTES = 2048;\nconst MAX_STATE_BYTES = 64 * 1024;\nconst STATE_REFUSAL_RESERVE = 4096;\n\ntype CompletionSource = \"handle\" | \"probe\";\nexport interface JobWatchProbeRequest {\n\tid: string;\n\tgeneration: string;\n\tresource_id: string;\n\tjob_id: string;\n\tcompletion_source: CompletionSource;\n\tcommand?: string;\n\ttimeout_ms: number;\n}\nexport interface JobObservation {\n\tobserved_at: string;\n\tjob_id: string;\n\tstate: string;\n\tprogress: Record<string, unknown>;\n\tattention: string[];\n\tevidence: string[];\n\tobservation_error?: string;\n}\nexport interface WatchDeclaration {\n\tid: string;\n\tgeneration: string;\n\tresource_id: string;\n\tjob_id: string;\n\tcompletion_source: CompletionSource;\n\tprobe_command?: string;\n\ttimeout_ms: number;\n\tinterval_ms: number;\n\treport_ms?: number;\n\tnext_check: number;\n\tnext_report?: number;\n\tdeadline?: number;\n\tdeadline_reported?: boolean;\n\tnotify: \"terminal\" | \"changes\";\n\tfields: string[];\n\tactive: boolean;\n\tgoal_id?: string;\n\tlatest: JobObservation;\n\tcompared?: string;\n\tlast_problem?: string;\n\tlast_attention?: string;\n\tlast_admitted?: string;\n\tpending: Array<{ id: string; text: string; admitted?: boolean; uncertain?: boolean; reconcile?: boolean }>;\n}\nexport interface JobWatchSnapshot {\n\tversion: 1;\n\tsession_id: string;\n\tsession_file?: string;\n\twatches: WatchDeclaration[];\n\tparked?: { ids: string[]; goal_id?: string };\n\tunavailable?: string;\n}\ninterface WatchHooks {\n\tsessionId: string;\n\tsessionFile?: string;\n\tcurrent: () => boolean;\n\tgoalId: () => string | undefined;\n\tprobe: (request: JobWatchProbeRequest) => Promise<void>;\n\tcancelProbe: (id: string, generation: string) => void;\n\tpersist: (state: JobWatchSnapshot) => Promise<void>;\n\tadmit: (text: string, eventId: string) => boolean;\n\twaitForDelivery?: boolean;\n\tstateBudgetBytes?: number;\n\tretain?: (text: string) => Promise<string | undefined>;\n\tonError: (error: unknown) => void;\n\tnow?: () => number;\n}\nfunction record(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\nfunction text(value: unknown, name: string, max = 512): string {\n\tif (typeof value !== \"string\" || !value.length || Buffer.byteLength(value) > max)\n\t\tthrow new Error(`${name} must be a nonempty string of at most ${max} bytes`);\n\treturn value;\n}\nfunction strings(value: unknown, name: string): string[] {\n\tif (value === undefined) return [];\n\tif (!Array.isArray(value) || value.length > 16) throw new Error(`${name} must contain at most 16 strings`);\n\treturn value.map((v) => text(v, name));\n}\nfunction interval(value: unknown, name: string): number {\n\tconst schedule = parseAgentCronSchedule(normalizeHeartbeatSchedule(text(value, name))).schedule;\n\tif (schedule.kind !== \"interval\" || !schedule.intervalMs) throw new Error(`${name} must be a recurring interval`);\n\treturn schedule.intervalMs;\n}\nfunction bounded(value: Record<string, unknown>): string {\n\tconst out = { ...value };\n\tif (Buffer.byteLength(JSON.stringify(out)) > MAX_VISIBLE_BYTES) {\n\t\tdelete out.progress;\n\t\tout.omitted = \"progress exceeds notification budget; inspect evidence\";\n\t}\n\tif (Buffer.byteLength(JSON.stringify(out)) > MAX_VISIBLE_BYTES) {\n\t\tout.attention = [\"attention exceeds notification budget; inspect evidence\"];\n\t\tout.evidence = Array.isArray(out.evidence) ? out.evidence.slice(0, 1) : [];\n\t}\n\treturn JSON.stringify(out);\n}\n\n/** Session-owned waiting state. Timers never invoke a model or execute notebook code. */\nexport class JobWatchController {\n\tprivate watches = new Map<string, WatchDeclaration>();\n\tprivate parked?: JobWatchSnapshot[\"parked\"];\n\tprivate timer?: ReturnType<typeof setTimeout>;\n\tprivate busy = new Set<string>();\n\tprivate queued = new Set<string>();\n\tprivate flushing?: Promise<void>;\n\tprivate tail: Promise<unknown> = Promise.resolve();\n\tprivate stopped = false;\n\tprivate unavailable?: string;\n\tconstructor(private readonly hooks: WatchHooks) {}\n\tprivate now(): number {\n\t\treturn this.hooks.now?.() ?? Date.now();\n\t}\n\tprivate owned(): boolean {\n\t\treturn !this.stopped && this.hooks.current();\n\t}\n\tprivate serialize<T>(work: () => Promise<T>): Promise<T> {\n\t\tconst operation = this.tail.then(work);\n\t\tthis.tail = operation.catch(() => undefined);\n\t\treturn operation;\n\t}\n\tisCurrent(): boolean {\n\t\treturn this.owned();\n\t}\n\tsnapshot(): JobWatchSnapshot {\n\t\treturn structuredClone({\n\t\t\tversion: 1,\n\t\t\tsession_id: this.hooks.sessionId,\n\t\t\tsession_file: this.hooks.sessionFile,\n\t\t\twatches: [...this.watches.values()],\n\t\t\tparked: this.parked,\n\t\t\tunavailable: this.unavailable,\n\t\t});\n\t}\n\tprivate stateBudget(): number {\n\t\treturn Math.min(MAX_STATE_BYTES, this.hooks.stateBudgetBytes ?? MAX_STATE_BYTES);\n\t}\n\tprivate stateBytes(state = this.snapshot()): number {\n\t\treturn Buffer.byteLength(\n\t\t\tJSON.stringify({\n\t\t\t\t...state,\n\t\t\t\twatches: state.watches.map((watch) => ({\n\t\t\t\t\t...watch,\n\t\t\t\t\tpending: watch.pending.map((event) => ({ ...event, admitted: true, uncertain: true, reconcile: true })),\n\t\t\t\t})),\n\t\t\t}),\n\t\t);\n\t}\n\tprivate async refusePendingBudget(watch: WatchDeclaration, previous: WatchDeclaration): Promise<void> {\n\t\tconst rejected = JSON.stringify({\n\t\t\tobservation: watch.latest,\n\t\t\tpending: watch.pending.slice(previous.pending.length),\n\t\t});\n\t\tObject.assign(watch, previous);\n\t\tthis.unavailable =\n\t\t\t\"Job-watch pending-state budget exhausted; monitoring is unavailable and further checks cannot continue under this hold. Resume delivery and explicitly register again.\";\n\t\tfor (const current of this.watches.values()) {\n\t\t\tcurrent.active = false;\n\t\t\tthis.hooks.cancelProbe(current.id, current.generation);\n\t\t}\n\t\tconst retained = await this.hooks.retain?.(rejected);\n\t\tif (!this.owned()) return;\n\t\tconst locator = retained ?? this.hooks.sessionFile ?? `job_watch.status(${JSON.stringify(watch.id)})`;\n\t\tconst id = randomUUID();\n\t\twatch.pending.push({\n\t\t\tid,\n\t\t\ttext: bounded({\n\t\t\t\tevent_id: id,\n\t\t\t\twatch_id: watch.id,\n\t\t\t\tgoal_id: watch.goal_id,\n\t\t\t\tjob_id: watch.job_id,\n\t\t\t\tstate: \"unknown\",\n\t\t\t\tprevious_state: previous.latest.state,\n\t\t\t\treasons: [\"monitoring_unavailable\"],\n\t\t\t\tobservation_error: this.unavailable,\n\t\t\t\tevidence: [locator],\n\t\t\t}),\n\t\t});\n\t\tawait this.save();\n\t\tawait this.flushPending();\n\t\tthis.schedule();\n\t\tthis.hooks.onError(new Error(`${this.unavailable} Evidence: ${locator}`));\n\t}\n\tprivate async save(): Promise<void> {\n\t\tif (this.owned()) await this.hooks.persist(this.snapshot());\n\t}\n\tasync watch(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n\t\treturn this.serialize(async () => {\n\t\t\tif (!this.owned()) throw new Error(\"Watch owner changed\");\n\t\t\tif (this.unavailable) throw new Error(this.unavailable);\n\t\t\tconst resource = text(input.resource_id, \"resource_id\");\n\t\t\tconst existing = [...this.watches.values()].find((w) => w.resource_id === resource && w.active);\n\t\t\tif (existing) {\n\t\t\t\tif (existing.goal_id !== this.hooks.goalId())\n\t\t\t\t\tthrow new Error(\"Watch belongs to a different goal; unregister it first\");\n\t\t\t\treturn this.status(existing.id);\n\t\t\t}\n\t\t\tif (this.watches.size >= MAX_WATCHES)\n\t\t\t\tthrow new Error(\"Unregister an old watch before registering more than 16 watches\");\n\t\t\tconst source = input.completion_source;\n\t\t\tif (source !== \"handle\" && source !== \"probe\")\n\t\t\t\tthrow new Error('completion_source must be \"handle\" or \"probe\"');\n\t\t\tconst command = input.probe_command == null ? undefined : text(input.probe_command, \"probe_command\", 8192);\n\t\t\tif (source === \"probe\" && !command) throw new Error(\"Probe completion requires a read-only probe_command\");\n\t\t\tconst notify = input.notify ?? \"terminal\";\n\t\t\tif (notify !== \"terminal\" && notify !== \"changes\") throw new Error('notify must be \"terminal\" or \"changes\"');\n\t\t\tconst fields = strings(input.fields, \"fields\");\n\t\t\tif (fields.includes(\"observed_at\"))\n\t\t\t\tthrow new Error(\"Observation timestamps are not meaningful comparison fields\");\n\t\t\tif (notify === \"changes\" && fields.length === 0) throw new Error(\"changes requires explicit progress fields\");\n\t\t\tconst now = this.now();\n\t\t\tconst intervalMs = interval(input.interval ?? \"5m\", \"interval\");\n\t\t\tconst reportMs = input.report_every == null ? undefined : interval(input.report_every, \"report_every\");\n\t\t\tconst timeout = input.timeout_ms ?? 30000;\n\t\t\tif (typeof timeout !== \"number\" || !Number.isFinite(timeout) || timeout < 1 || timeout > 300000)\n\t\t\t\tthrow new Error(\"timeout_ms must be between 1 and 300000\");\n\t\t\tconst deadline = input.deadline == null ? undefined : Date.parse(text(input.deadline, \"deadline\"));\n\t\t\tif (deadline !== undefined && !Number.isFinite(deadline)) throw new Error(\"deadline must be an ISO date\");\n\t\t\tconst jobId = text(input.job_id ?? resource, \"job_id\", 256);\n\t\t\tconst watch: WatchDeclaration = {\n\t\t\t\tid: randomUUID(),\n\t\t\t\tgeneration: randomUUID(),\n\t\t\t\tresource_id: resource,\n\t\t\t\tjob_id: jobId,\n\t\t\t\tcompletion_source: source,\n\t\t\t\tprobe_command: command,\n\t\t\t\ttimeout_ms: timeout,\n\t\t\t\tinterval_ms: intervalMs,\n\t\t\t\treport_ms: reportMs,\n\t\t\t\tnext_check: now + intervalMs,\n\t\t\t\tnext_report: reportMs ? now + reportMs : undefined,\n\t\t\t\tdeadline,\n\t\t\t\tnotify,\n\t\t\t\tfields,\n\t\t\t\tactive: true,\n\t\t\t\tpending: [],\n\t\t\t\tgoal_id: this.hooks.goalId(),\n\t\t\t\tlatest: {\n\t\t\t\t\tobserved_at: new Date(now).toISOString(),\n\t\t\t\t\tjob_id: jobId,\n\t\t\t\t\tstate: \"running\",\n\t\t\t\t\tprogress: {},\n\t\t\t\t\tattention: [],\n\t\t\t\t\tevidence: strings(input.evidence, \"evidence\"),\n\t\t\t\t},\n\t\t\t};\n\t\t\tif (\n\t\t\t\tthis.stateBytes({ ...this.snapshot(), watches: [...this.watches.values(), watch] }) >\n\t\t\t\tMath.min(48 * 1024, this.stateBudget() - STATE_REFUSAL_RESERVE)\n\t\t\t)\n\t\t\t\tthrow new Error(\"Job watch declaration budget exceeded; unregister obsolete watches\");\n\t\t\tthis.watches.set(watch.id, watch);\n\t\t\tawait this.save();\n\t\t\tthis.schedule();\n\t\t\treturn this.status(watch.id);\n\t\t});\n\t}\n\tstatus(id?: string): Record<string, unknown> {\n\t\tconst values = id === undefined ? [...this.watches.values()] : [this.require(id)];\n\t\tconst statuses = values.map((w) => ({\n\t\t\tid: w.id,\n\t\t\tgeneration: w.generation,\n\t\t\tactive: w.active,\n\t\t\tcompletion_source: w.completion_source,\n\t\t\t...w.latest,\n\t\t\t...(this.unavailable\n\t\t\t\t? { state: \"unknown\", last_observed_state: w.latest.state, monitoring_error: this.unavailable }\n\t\t\t\t: {}),\n\t\t\tlast_admitted: w.last_admitted,\n\t\t\tpending_events: w.pending.length,\n\t\t}));\n\t\treturn id === undefined ? { watches: statuses, parked: this.isParked() } : statuses[0];\n\t}\n\tprivate require(id: string): WatchDeclaration {\n\t\tconst watch = this.watches.get(id);\n\t\tif (!watch) throw new Error(`Unknown watch ${id}`);\n\t\treturn watch;\n\t}\n\tasync park(ids: string[]): Promise<Record<string, unknown>> {\n\t\treturn this.serialize(async () => {\n\t\t\tif (this.unavailable) return { parked: false, reason: \"monitoring_unavailable\" };\n\t\t\tif (!ids.length) throw new Error(\"park requires at least one watch\");\n\t\t\tconst selected = ids.map((id) => this.require(id));\n\t\t\tif (!this.owned() || selected.some((w) => w.goal_id !== this.hooks.goalId()))\n\t\t\t\tthrow new Error(\"Watch owner changed\");\n\t\t\t// A completion racing registration/park is already actionable; do not wait forever.\n\t\t\tif (selected.some((w) => !w.active || w.pending.length > 0))\n\t\t\t\treturn { parked: false, reason: \"event_available\" };\n\t\t\tthis.parked = { ids: [...new Set(ids)], goal_id: this.hooks.goalId() };\n\t\t\tawait this.save();\n\t\t\treturn { parked: true, ids: this.parked.ids };\n\t\t});\n\t}\n\tisParked(): boolean {\n\t\treturn (\n\t\t\tthis.owned() &&\n\t\t\tthis.parked !== undefined &&\n\t\t\tthis.parked.goal_id === this.hooks.goalId() &&\n\t\t\tthis.parked.ids.some((id) => this.watches.has(id))\n\t\t);\n\t}\n\tasync unregister(id: string): Promise<Record<string, unknown>> {\n\t\treturn this.serialize(async () => {\n\t\t\tconst watch = this.watches.get(id);\n\t\t\tif (watch) {\n\t\t\t\tthis.hooks.cancelProbe(watch.id, watch.generation);\n\t\t\t\tthis.watches.delete(id);\n\t\t\t\tif (!this.watches.size) this.unavailable = undefined;\n\t\t\t\tif (this.parked?.ids.includes(id)) this.parked = undefined;\n\t\t\t\tawait this.save();\n\t\t\t}\n\t\t\tthis.schedule();\n\t\t\treturn { id, unregistered: true };\n\t\t});\n\t}\n\tprivate schedule(): void {\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tif (!this.owned() || this.unavailable) return;\n\t\tconst times = [...this.watches.values()]\n\t\t\t.filter((w) => w.active && w.goal_id === this.hooks.goalId() && !this.busy.has(w.id))\n\t\t\t.flatMap((w) => [\n\t\t\t\tw.next_check,\n\t\t\t\tw.next_report ?? Infinity,\n\t\t\t\tw.deadline_reported ? Infinity : (w.deadline ?? Infinity),\n\t\t\t]);\n\t\tif (!times.length) return;\n\t\tthis.timer = setTimeout(\n\t\t\t() => {\n\t\t\t\tvoid this.runDue().catch(this.hooks.onError);\n\t\t\t},\n\t\t\tMath.max(0, Math.min(2147483647, Math.min(...times) - this.now())),\n\t\t);\n\t\tthis.timer.unref?.();\n\t}\n\tasync runDue(): Promise<void> {\n\t\tif (!this.owned() || this.unavailable) return;\n\t\tconst now = this.now();\n\t\tconst probes: Promise<void>[] = [];\n\t\tfor (const watch of this.watches.values()) {\n\t\t\tif (!watch.active || watch.goal_id !== this.hooks.goalId() || this.busy.has(watch.id)) continue;\n\t\t\tif (\n\t\t\t\tMath.min(\n\t\t\t\t\twatch.next_check,\n\t\t\t\t\twatch.next_report ?? Infinity,\n\t\t\t\t\twatch.deadline_reported ? Infinity : (watch.deadline ?? Infinity),\n\t\t\t\t) > now\n\t\t\t)\n\t\t\t\tcontinue;\n\t\t\tthis.busy.add(watch.id);\n\t\t\t// Skip stale checks, not requested reports. Reports retain their own scheduled timestamps.\n\t\t\tif (watch.next_check <= now)\n\t\t\t\twatch.next_check += (Math.floor((now - watch.next_check) / watch.interval_ms) + 1) * watch.interval_ms;\n\t\t\tprobes.push(\n\t\t\t\t(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait this.hooks.probe({\n\t\t\t\t\t\t\tid: watch.id,\n\t\t\t\t\t\t\tgeneration: watch.generation,\n\t\t\t\t\t\t\tresource_id: watch.resource_id,\n\t\t\t\t\t\t\tjob_id: watch.job_id,\n\t\t\t\t\t\t\tcompletion_source: watch.completion_source,\n\t\t\t\t\t\t\tcommand: watch.probe_command,\n\t\t\t\t\t\t\ttimeout_ms: watch.timeout_ms,\n\t\t\t\t\t\t});\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tawait this.observe({\n\t\t\t\t\t\t\tid: watch.id,\n\t\t\t\t\t\t\tgeneration: watch.generation,\n\t\t\t\t\t\t\tsource: \"probe\",\n\t\t\t\t\t\t\terror: String(error),\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t})(),\n\t\t\t);\n\t\t}\n\t\tawait Promise.all(probes);\n\t\tthis.schedule();\n\t}\n\tasync observe(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n\t\treturn this.serialize(async () => {\n\t\t\tconst watch = typeof input.id === \"string\" ? this.watches.get(input.id) : undefined;\n\t\t\tif (\n\t\t\t\t!watch ||\n\t\t\t\tinput.generation !== watch.generation ||\n\t\t\t\t!this.owned() ||\n\t\t\t\t!watch.active ||\n\t\t\t\twatch.goal_id !== this.hooks.goalId()\n\t\t\t)\n\t\t\t\treturn { ignored: true };\n\t\t\tif (input.source === \"handle\" && watch.completion_source !== \"handle\") return { ignored: true };\n\t\t\tthis.busy.delete(watch.id);\n\t\t\tconst now = this.now();\n\t\t\tconst previous = watch.latest.state;\n\t\t\tconst error = typeof input.error === \"string\" ? input.error : undefined;\n\t\t\tconst observed: unknown = input.observation;\n\t\t\tlet evidence: string | undefined;\n\t\t\tif (typeof input.output === \"string\" && this.hooks.retain) evidence = await this.hooks.retain(input.output);\n\t\t\tif (!this.owned() || this.watches.get(watch.id) !== watch || watch.goal_id !== this.hooks.goalId())\n\t\t\t\treturn { ignored: true };\n\t\t\tconst before = structuredClone(watch);\n\t\t\tlet observation: JobObservation;\n\t\t\ttry {\n\t\t\t\tif (error) throw new Error(error);\n\t\t\t\tif (!record(observed)) throw new Error(\"Probe observation is unavailable\");\n\t\t\t\tconst jobId = text(observed.job_id, \"job_id\", 256);\n\t\t\t\tif (jobId !== watch.job_id) throw new Error(\"Probe job identity does not match this watch\");\n\t\t\t\tconst state = text(observed.state, \"state\", 32);\n\t\t\t\tif (![\"running\", \"pending\", \"unknown\", ...TERMINAL].includes(state))\n\t\t\t\t\tthrow new Error(\"Unrecognized job state\");\n\t\t\t\tconst observedAt = text(observed.observed_at, \"observed_at\", 64);\n\t\t\t\tif (!Number.isFinite(Date.parse(observedAt))) throw new Error(\"Invalid observation time\");\n\t\t\t\tif (!record(observed.progress ?? {})) throw new Error(\"progress must be an object\");\n\t\t\t\tobservation = {\n\t\t\t\t\tobserved_at: observedAt,\n\t\t\t\t\tjob_id: jobId,\n\t\t\t\t\tstate,\n\t\t\t\t\tprogress: (observed.progress as Record<string, unknown>) ?? {},\n\t\t\t\t\tattention: strings(observed.attention, \"attention\"),\n\t\t\t\t\tevidence: strings(observed.evidence, \"evidence\"),\n\t\t\t\t};\n\t\t\t\t// Handle authority is explicit: progress probes cannot finish a live local handle.\n\t\t\t\tif (input.source !== \"handle\" && watch.completion_source === \"handle\" && TERMINAL.has(state)) {\n\t\t\t\t\tif (state !== \"succeeded\")\n\t\t\t\t\t\tobservation.attention.push(`Probe reports job ${state}; waiting for authoritative handle`);\n\t\t\t\t\tobservation.state = \"running\";\n\t\t\t\t}\n\t\t\t} catch (failure) {\n\t\t\t\tobservation = {\n\t\t\t\t\tobserved_at: new Date(now).toISOString(),\n\t\t\t\t\tjob_id: watch.job_id,\n\t\t\t\t\tstate: \"unknown\",\n\t\t\t\t\tprogress: {},\n\t\t\t\t\tattention: [],\n\t\t\t\t\tevidence: watch.latest.evidence,\n\t\t\t\t\tobservation_error: String(failure).slice(0, 256),\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (evidence) observation.evidence = [evidence, ...observation.evidence].slice(0, 16);\n\t\t\tconst problem =\n\t\t\t\tobservation.observation_error ?? (observation.state === \"unknown\" ? \"Job state unknown\" : undefined);\n\t\t\tconst selected: Record<string, unknown> = {};\n\t\t\tfor (const field of [...new Set([...watch.fields, \"exit_code\", \"duration_seconds\"])]) {\n\t\t\t\tconst value = observation.progress[field];\n\t\t\t\tif (value === undefined) continue;\n\t\t\t\tif (Buffer.byteLength(JSON.stringify(value)) > 512) {\n\t\t\t\t\tselected[field] = { unavailable: \"value exceeds 512-byte watch field budget; inspect evidence\" };\n\t\t\t\t\tobservation.attention.push(`Oversized selected field: ${field}`);\n\t\t\t\t} else selected[field] = value;\n\t\t\t}\n\t\t\tconst compared = JSON.stringify(watch.fields.map((field) => [field, selected[field]]));\n\t\t\tconst attention = JSON.stringify(observation.attention);\n\t\t\tconst reasons: string[] = [];\n\t\t\tif (TERMINAL.has(observation.state)) {\n\t\t\t\treasons.push(observation.state === \"succeeded\" ? \"terminal\" : \"failure\");\n\t\t\t\twatch.active = false;\n\t\t\t}\n\t\t\tif (input.source === \"handle\" && typeof input.error === \"string\" && input.error.includes(\"handle unavailable\"))\n\t\t\t\twatch.active = false;\n\t\t\tif (problem && problem !== watch.last_problem) reasons.push(\"observability\");\n\t\t\tif (observation.attention.length && attention !== watch.last_attention) reasons.push(\"attention\");\n\t\t\tif (watch.notify === \"changes\" && watch.compared !== undefined && compared !== watch.compared)\n\t\t\t\treasons.push(\"progress\");\n\t\t\tif (watch.deadline !== undefined && now >= watch.deadline && !watch.deadline_reported) {\n\t\t\t\treasons.push(\"deadline\");\n\t\t\t\twatch.deadline_reported = true;\n\t\t\t}\n\t\t\twatch.latest = { ...observation, progress: selected };\n\t\t\twatch.compared = compared;\n\t\t\twatch.last_problem = problem;\n\t\t\twatch.last_attention = attention;\n\t\t\tconst emit = (eventReasons: string[], due?: number) => {\n\t\t\t\tconst id = randomUUID();\n\t\t\t\tconst value = {\n\t\t\t\t\twatch_id: watch.id,\n\t\t\t\t\tgoal_id: watch.goal_id,\n\t\t\t\t\tevent_id: id,\n\t\t\t\t\t...watch.latest,\n\t\t\t\t\tprevious_state: previous,\n\t\t\t\t\treasons: eventReasons,\n\t\t\t\t\t...(due === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { scheduled_for: new Date(due).toISOString(), late_by_ms: Math.max(0, now - due) }),\n\t\t\t\t};\n\t\t\t\twatch.pending.push({ id, text: bounded(value) });\n\t\t\t};\n\t\t\tif (reasons.length) emit(reasons);\n\t\t\tif (watch.report_ms && watch.next_report !== undefined && watch.next_report <= now) {\n\t\t\t\twhile (watch.next_report <= now) {\n\t\t\t\t\temit([\"report\"], watch.next_report);\n\t\t\t\t\twatch.next_report += watch.report_ms;\n\t\t\t\t\tif (this.stateBytes() > this.stateBudget() - STATE_REFUSAL_RESERVE) {\n\t\t\t\t\t\tawait this.refusePendingBudget(watch, before);\n\t\t\t\t\t\treturn { accepted: false, reason: \"monitoring_unavailable\" };\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (this.stateBytes() > this.stateBudget() - STATE_REFUSAL_RESERVE) {\n\t\t\t\tawait this.refusePendingBudget(watch, before);\n\t\t\t\treturn { accepted: false, reason: \"monitoring_unavailable\" };\n\t\t\t}\n\t\t\t// Persist prepared evidence before native queue admission.\n\t\t\tawait this.save();\n\t\t\tawait this.flushPending();\n\t\t\tawait this.save();\n\t\t\tthis.schedule();\n\t\t\treturn { accepted: true };\n\t\t});\n\t}\n\tflushPending(): Promise<void> {\n\t\tif (!this.flushing)\n\t\t\tthis.flushing = this.flushPrepared().finally(() => {\n\t\t\t\tthis.flushing = undefined;\n\t\t\t});\n\t\treturn this.flushing;\n\t}\n\tprivate async flushPrepared(): Promise<void> {\n\t\tif (!this.owned()) return;\n\t\tlet changed = false;\n\t\tfor (const watch of this.watches.values()) {\n\t\t\tfor (const event of [...watch.pending]) {\n\t\t\t\tif (!this.owned()) return;\n\t\t\t\tif ((!event.admitted && watch.goal_id !== this.hooks.goalId()) || this.queued.has(event.id)) continue;\n\t\t\t\tlet deliveryText = event.text;\n\t\t\t\tif (event.reconcile) {\n\t\t\t\t\tlet original: Record<string, unknown> = {};\n\t\t\t\t\ttry {\n\t\t\t\t\t\toriginal = JSON.parse(event.text);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t/* unavailable prior body */\n\t\t\t\t\t}\n\t\t\t\t\tdeliveryText = bounded({\n\t\t\t\t\t\t...original,\n\t\t\t\t\t\tevent_id: `${event.id}:delivery-unknown`,\n\t\t\t\t\t\toriginal_event_id: event.id,\n\t\t\t\t\t\toriginal_state: original.state,\n\t\t\t\t\t\tstate: \"unknown\",\n\t\t\t\t\t\treasons: [\"delivery_unknown\"],\n\t\t\t\t\t\tobservation_error:\n\t\t\t\t\t\t\t\"Delivery before interrupted shutdown is uncertain; reconcile evidence before repeating actions\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tif (this.hooks.waitForDelivery) {\n\t\t\t\t\tevent.uncertain = true;\n\t\t\t\t\tawait this.save();\n\t\t\t\t}\n\t\t\t\tif (!this.owned() || (!event.admitted && watch.goal_id !== this.hooks.goalId())) return;\n\t\t\t\tif (!this.hooks.admit(deliveryText, event.id)) {\n\t\t\t\t\tevent.uncertain = false;\n\t\t\t\t\tawait this.save();\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (this.hooks.waitForDelivery) {\n\t\t\t\t\tevent.admitted = true;\n\t\t\t\t\tthis.queued.add(event.id);\n\t\t\t\t} else {\n\t\t\t\t\twatch.last_admitted = event.id;\n\t\t\t\t\twatch.pending.splice(watch.pending.indexOf(event), 1);\n\t\t\t\t}\n\t\t\t\tchanged = true;\n\t\t\t\tif (watch.goal_id === this.hooks.goalId() && this.parked?.ids.includes(watch.id)) this.parked = undefined;\n\t\t\t}\n\t\t}\n\t\tif (changed) {\n\t\t\tawait this.save();\n\t\t\tthis.schedule();\n\t\t}\n\t}\n\tacknowledge(id: string): Promise<void> {\n\t\treturn this.serialize(async () => {\n\t\t\tif (this.stopped) return;\n\t\t\tthis.queued.delete(id);\n\t\t\tfor (const watch of this.watches.values()) {\n\t\t\t\tconst index = watch.pending.findIndex((event) => event.id === id);\n\t\t\t\tif (index >= 0) {\n\t\t\t\t\twatch.pending.splice(index, 1);\n\t\t\t\t\twatch.last_admitted = id;\n\t\t\t\t}\n\t\t\t}\n\t\t\tawait this.save();\n\t\t});\n\t}\n\treleaseDelivery(id: string, knownUndelivered: boolean): Promise<void> {\n\t\treturn this.serialize(async () => {\n\t\t\tthis.queued.delete(id);\n\t\t\tfor (const watch of this.watches.values()) {\n\t\t\t\tconst event = watch.pending.find((item) => item.id === id);\n\t\t\t\tif (event && knownUndelivered) event.uncertain = false;\n\t\t\t}\n\t\t\tawait this.save();\n\t\t});\n\t}\n\t/** Called only after native request/agent settlement during clean async shutdown. */\n\tasync settleShutdown(undelivered: Set<string>): Promise<void> {\n\t\tawait this.flushing;\n\t\treturn this.serialize(async () => {\n\t\t\tfor (const watch of this.watches.values())\n\t\t\t\tfor (const event of watch.pending) if (undelivered.has(event.id)) event.uncertain = false;\n\t\t\tthis.dispose();\n\t\t\tawait this.hooks.persist(this.snapshot());\n\t\t});\n\t}\n\tasync restore(value: unknown): Promise<void> {\n\t\tif (\n\t\t\t!record(value) ||\n\t\t\tvalue.version !== 1 ||\n\t\t\tvalue.session_id !== this.hooks.sessionId ||\n\t\t\tvalue.session_file !== this.hooks.sessionFile ||\n\t\t\t!Array.isArray(value.watches) ||\n\t\t\tvalue.watches.length > MAX_WATCHES\n\t\t)\n\t\t\treturn;\n\t\tthis.unavailable = typeof value.unavailable === \"string\" ? value.unavailable : undefined;\n\t\t// Only host-persisted declarations reach here; PID/process objects are deliberately absent.\n\t\tfor (const item of value.watches as WatchDeclaration[]) {\n\t\t\tif (\n\t\t\t\t!record(item) ||\n\t\t\t\ttypeof item.id !== \"string\" ||\n\t\t\t\ttypeof item.generation !== \"string\" ||\n\t\t\t\ttypeof item.resource_id !== \"string\" ||\n\t\t\t\ttypeof item.job_id !== \"string\" ||\n\t\t\t\t![\"handle\", \"probe\"].includes(item.completion_source) ||\n\t\t\t\t!Number.isFinite(item.interval_ms) ||\n\t\t\t\titem.interval_ms <= 0 ||\n\t\t\t\t!Number.isFinite(item.next_check) ||\n\t\t\t\t!Number.isFinite(item.timeout_ms) ||\n\t\t\t\titem.timeout_ms < 1 ||\n\t\t\t\titem.timeout_ms > 300000 ||\n\t\t\t\t(item.report_ms !== undefined && (!Number.isFinite(item.report_ms) || item.report_ms <= 0)) ||\n\t\t\t\t(item.probe_command !== undefined &&\n\t\t\t\t\t(typeof item.probe_command !== \"string\" || Buffer.byteLength(item.probe_command) > 8192)) ||\n\t\t\t\t!Array.isArray(item.fields) ||\n\t\t\t\titem.fields.some((field) => typeof field !== \"string\") ||\n\t\t\t\t!record(item.latest) ||\n\t\t\t\t!Array.isArray(item.pending) ||\n\t\t\t\titem.pending.some((event) => !event || typeof event.id !== \"string\" || typeof event.text !== \"string\")\n\t\t\t)\n\t\t\t\tcontinue;\n\t\t\tconst restored = structuredClone(item);\n\t\t\tfor (const event of restored.pending) {\n\t\t\t\tif (event.uncertain) {\n\t\t\t\t\tevent.reconcile = true;\n\t\t\t\t\tevent.admitted = true;\n\t\t\t\t}\n\t\t\t}\n\t\t\tthis.watches.set(item.id, restored);\n\t\t}\n\t\tthis.parked =\n\t\t\trecord(value.parked) &&\n\t\t\tArray.isArray(value.parked.ids) &&\n\t\t\tvalue.parked.ids.every((id) => typeof id === \"string\")\n\t\t\t\t? (value.parked as JobWatchSnapshot[\"parked\"])\n\t\t\t\t: undefined;\n\t\tawait this.flushPending();\n\t\tfor (const watch of this.watches.values()) {\n\t\t\tif (!watch.active) continue;\n\t\t\twatch.generation = randomUUID();\n\t\t\tif (watch.completion_source === \"probe\" && watch.probe_command) {\n\t\t\t\twatch.next_check = this.now();\n\t\t\t} else {\n\t\t\t\tawait this.observe({\n\t\t\t\t\tid: watch.id,\n\t\t\t\t\tgeneration: watch.generation,\n\t\t\t\t\terror: \"Kernel/session restored without an authoritative probe; handle identity is unknown\",\n\t\t\t\t});\n\t\t\t\twatch.active = false;\n\t\t\t}\n\t\t}\n\t\tawait this.save();\n\t\tthis.schedule();\n\t}\n\tdispose(): void {\n\t\tthis.stopped = true;\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tfor (const watch of this.watches.values()) this.hooks.cancelProbe(watch.id, watch.generation);\n\t}\n}\n"]}