From c35b531014ffe4aa9fab2809e01f5a9eb2262289 Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:50 -0300 Subject: [PATCH 1/7] fix: stream event plans in headless runs Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- src/lib/file-watcher.ts | 83 +++++++++++++++++ .../__tests__/event-plan-watcher.test.ts | 89 ++++++++++++++++++ .../__tests__/task-stream-push.test.ts | 30 +++++++ src/lib/task-stream/event-plan-watcher.ts | 58 ++++++++++++ src/lib/task-stream/task-stream-push.ts | 10 ++- src/ui/headless-ui.ts | 5 +- src/ui/tui/hooks/file-watcher.ts | 90 +------------------ src/ui/tui/screens/RunScreen.tsx | 21 ----- 8 files changed, 274 insertions(+), 112 deletions(-) create mode 100644 src/lib/file-watcher.ts create mode 100644 src/lib/task-stream/__tests__/event-plan-watcher.test.ts create mode 100644 src/lib/task-stream/event-plan-watcher.ts diff --git a/src/lib/file-watcher.ts b/src/lib/file-watcher.ts new file mode 100644 index 000000000..5e5b3bec0 --- /dev/null +++ b/src/lib/file-watcher.ts @@ -0,0 +1,83 @@ +/** + * JSON file watcher shared by runner and UI machinery. + * + * `fs.watch` alone is unreliable for atomic-rename writes, so the watcher + * pairs it with a continuous mtime-polled re-read. The poll catches missed + * events; the watch keeps latency low when it does fire. + */ + +import * as fs from 'fs'; + +const DEFAULT_POLL_INTERVAL_MS = 5000; +const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; + +export interface FileWatcherHandle { + stop(): void; +} + +export interface FileWatcherOptions { + /** ms between mtime checks once the file exists. */ + pollIntervalMs?: number; + /** ms between attach attempts while waiting for the file to appear. */ + attachRetryIntervalMs?: number; +} + +/** Watch `path` for JSON updates and call `onUpdate(parsed)` whenever the + * file's mtime changes and the contents are valid JSON. Caller must invoke + * `handle.stop()` to release the watcher. */ +export function startFileWatcher( + path: string, + onUpdate: (parsed: unknown) => void, + options: FileWatcherOptions = {}, +): FileWatcherHandle { + const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS; + const attachRetryIntervalMs = + options.attachRetryIntervalMs ?? DEFAULT_ATTACH_RETRY_INTERVAL_MS; + + const watchers: fs.FSWatcher[] = []; + const intervals: Array> = []; + let lastMtimeMs = 0; + + const read = (force = false) => { + try { + const stat = fs.statSync(path); + if (!force && stat.mtimeMs === lastMtimeMs) return; + lastMtimeMs = stat.mtimeMs; + const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); + onUpdate(parsed); + } catch { + // File missing or not yet valid JSON. + } + }; + + intervals.push(setInterval(() => read(), pollIntervalMs)); + + try { + watchers.push(fs.watch(path, () => read(true))); + read(true); + } catch { + // File doesn't exist yet — retry attaching the watch periodically until + // it appears. The poll above already covers updates; this just upgrades + // latency once the file shows up. + const attachInterval = setInterval(() => { + try { + fs.accessSync(path); + clearInterval(attachInterval); + const idx = intervals.indexOf(attachInterval); + if (idx >= 0) intervals.splice(idx, 1); + watchers.push(fs.watch(path, () => read(true))); + read(true); + } catch { + // Still waiting. + } + }, attachRetryIntervalMs); + intervals.push(attachInterval); + } + + return { + stop() { + for (const watcher of watchers) watcher.close(); + for (const interval of intervals) clearInterval(interval); + }, + }; +} diff --git a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts new file mode 100644 index 000000000..216d445c9 --- /dev/null +++ b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts @@ -0,0 +1,89 @@ +import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { + EventPlanWatcher, + normalizeEventPlan, +} from '@lib/task-stream/event-plan-watcher'; +import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; +import type { PlannedEvent, WizardStore } from '@ui/tui/store'; + +const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); + +function createStore(installDir: string) { + let eventPlan: PlannedEvent[] = []; + return { + session: { installDir }, + get eventPlan() { + return eventPlan; + }, + setEventPlan(events: PlannedEvent[]) { + eventPlan = events; + }, + } as WizardStore; +} + +describe('EventPlanWatcher', () => { + let installDir: string; + let watcher: EventPlanWatcher | undefined; + + beforeEach(() => { + installDir = mkdtempSync(join(tmpdir(), 'wizard-event-plan-')); + }); + + afterEach(() => { + watcher?.stop(); + watcher = undefined; + rmSync(installDir, { recursive: true, force: true }); + }); + + it('normalizes canonical fields and legacy fallbacks', () => { + expect( + normalizeEventPlan([ + { event_name: 'signed_up', event_description: 'User signs up' }, + { name: 'invited_user', description: 'User sends an invite' }, + { event: 'created_team' }, + { description: 'missing name' }, + ]), + ).toEqual([ + { name: 'signed_up', description: 'User signs up' }, + { name: 'invited_user', description: 'User sends an invite' }, + { name: 'created_team', description: '' }, + ]); + }); + + it('captures the plan when the file is written after startup', async () => { + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, { + pollIntervalMs: 30, + attachRetryIntervalMs: 20, + }); + watcher.start(); + + writeFileSync( + join(installDir, EVENT_PLAN_FILE), + JSON.stringify([{ event_name: 'completed_onboarding' }]), + ); + await wait(120); + + expect(store.eventPlan).toEqual([ + { name: 'completed_onboarding', description: '' }, + ]); + }); + + it('keeps the last captured plan after the file is deleted', async () => { + const path = join(installDir, EVENT_PLAN_FILE); + writeFileSync(path, JSON.stringify([{ event_name: 'created_report' }])); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, { pollIntervalMs: 30 }); + watcher.start(); + await wait(40); + + unlinkSync(path); + await wait(80); + + expect(store.eventPlan).toEqual([ + { name: 'created_report', description: '' }, + ]); + }); +}); diff --git a/src/lib/task-stream/__tests__/task-stream-push.test.ts b/src/lib/task-stream/__tests__/task-stream-push.test.ts index ebdc3c611..26de251ef 100644 --- a/src/lib/task-stream/__tests__/task-stream-push.test.ts +++ b/src/lib/task-stream/__tests__/task-stream-push.test.ts @@ -6,6 +6,10 @@ import type { } from '@lib/task-stream/types'; import type { WizardStore, TaskItem } from '@ui/tui/store'; import { RunPhase } from '@lib/wizard-session'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; type Listener = () => void; @@ -14,6 +18,7 @@ interface MockStoreState { skillId: string | null; tasks: TaskItem[]; eventPlan: unknown[]; + installDir?: string; } function createMockStore(overrides: Partial = {}) { @@ -32,6 +37,7 @@ function createMockStore(overrides: Partial = {}) { runPhase: state.runPhase, skillId: state.skillId, outroData: null, + installDir: state.installDir, }; }, get tasks() { @@ -40,6 +46,10 @@ function createMockStore(overrides: Partial = {}) { get eventPlan() { return state.eventPlan; }, + setEventPlan(eventPlan: unknown[]) { + state.eventPlan = eventPlan; + for (const cb of listeners) cb(); + }, subscribe(cb: Listener) { listeners.push(cb); return () => { @@ -103,6 +113,26 @@ describe('TaskStreamPush', () => { // ── Existing event-sequencing behaviour ──────────────────────── + it('populates the event plan when destination delivery is disabled', () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-headless-plan-')); + writeFileSync( + join(installDir, EVENT_PLAN_FILE), + JSON.stringify([{ event_name: 'created_workspace' }]), + ); + const store = createMockStore({ installDir }); + const { push, dest } = createPush(store, { enabled: false }); + + push.attach(); + + expect(store.eventPlan).toEqual([ + { name: 'created_workspace', description: '' }, + ]); + expect(dest.calls).toHaveLength(0); + + push.detach(); + rmSync(installDir, { recursive: true, force: true }); + }); + describe('event ordering (imperative push)', () => { it('first push sends CREATE', async () => { const store = createMockStore(); diff --git a/src/lib/task-stream/event-plan-watcher.ts b/src/lib/task-stream/event-plan-watcher.ts new file mode 100644 index 000000000..0bff48dbf --- /dev/null +++ b/src/lib/task-stream/event-plan-watcher.ts @@ -0,0 +1,58 @@ +import { join } from 'node:path'; +import type { PlannedEvent, WizardStore } from '@ui/tui/store'; +import { + startFileWatcher, + type FileWatcherHandle, + type FileWatcherOptions, +} from '@lib/file-watcher'; +import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; + +export function normalizeEventPlan(parsed: unknown): PlannedEvent[] | null { + if (!Array.isArray(parsed)) return null; + + return parsed + .map((value) => { + const entry = + value && typeof value === 'object' + ? (value as Record) + : {}; + return { + name: (entry.event_name ?? entry.name ?? entry.event ?? '') as string, + description: (entry.event_description ?? + entry.description ?? + '') as string, + }; + }) + .filter((event) => event.name); +} + +export class EventPlanWatcher { + private handle: FileWatcherHandle | null = null; + + constructor( + private readonly store: WizardStore, + private readonly options: FileWatcherOptions = {}, + ) {} + + start(): void { + if (this.handle) return; + + const installDir = this.store.session.installDir; + if (!installDir) return; + + const path = join(installDir, EVENT_PLAN_FILE); + this.handle = startFileWatcher( + path, + (parsed) => { + const events = normalizeEventPlan(parsed); + if (events) this.store.setEventPlan(events); + }, + this.options, + ); + } + + stop(): void { + this.handle?.stop(); + this.handle = null; + } +} diff --git a/src/lib/task-stream/task-stream-push.ts b/src/lib/task-stream/task-stream-push.ts index 028154199..7f21d46b7 100644 --- a/src/lib/task-stream/task-stream-push.ts +++ b/src/lib/task-stream/task-stream-push.ts @@ -27,6 +27,7 @@ import { StreamTaskStatus, StreamEvent, } from './types'; +import { EventPlanWatcher } from './event-plan-watcher'; /** Trailing-edge debounce window for non-phase-change emits. */ const DEBOUNCE_MS = 250; @@ -91,6 +92,7 @@ export class TaskStreamPush { private readonly startedAt: string; private readonly programId: string; private readonly sessionId: string; + private readonly eventPlanWatcher: EventPlanWatcher; private enabled: boolean; private created = false; @@ -107,6 +109,7 @@ export class TaskStreamPush { this.programId = sanitizeChannelId(opts.programId); this.destinations = opts.destinations; this.enabled = opts.enabled ?? true; + this.eventPlanWatcher = new EventPlanWatcher(this.store); this.startedAt = secondPrecisionIso(new Date()); // skillId may not be set yet — fall back to programId so the // session_id is stable for the whole run regardless of when the @@ -118,10 +121,12 @@ export class TaskStreamPush { } /** - * Subscribe to store changes. No-op when `enabled === false`. - * Idempotent — repeat calls are ignored. + * Mirror the event plan and subscribe to store changes. Destination delivery + * remains disabled when `enabled === false`, but the plan still populates the + * store for local and headless consumers. */ attach(store?: WizardStore): void { + this.eventPlanWatcher.start(); if (!this.enabled) return; if (this.unsubscribe) return; const target = store ?? this.store; @@ -130,6 +135,7 @@ export class TaskStreamPush { /** Stop subscribing. Does not flush. */ detach(): void { + this.eventPlanWatcher.stop(); if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; diff --git a/src/ui/headless-ui.ts b/src/ui/headless-ui.ts index 6d1a8da28..1d53f44cf 100644 --- a/src/ui/headless-ui.ts +++ b/src/ui/headless-ui.ts @@ -6,8 +6,9 @@ import type { WizardStore } from './tui/store'; * wizard-session sync (`TaskStreamPush`) can observe a headless run. We extend * `LoggingUI` (not `InkUI`) because its blocking/gate methods would wait on a * TUI that never renders; the runner drives phase transitions on the store - * directly, so only the per-run updates (today: the task list) tee through here. - * To stream more later, override `setEventPlan` / `setStage` the same way. + * directly, so only UI-originated per-run updates tee through here. Runner + * machinery mirrors agent-authored artifacts such as the event plan directly + * into the store. */ export class HeadlessUI extends LoggingUI { constructor(private readonly store: WizardStore) { diff --git a/src/ui/tui/hooks/file-watcher.ts b/src/ui/tui/hooks/file-watcher.ts index 1167a3acb..5dd272aa0 100644 --- a/src/ui/tui/hooks/file-watcher.ts +++ b/src/ui/tui/hooks/file-watcher.ts @@ -1,92 +1,8 @@ -/** - * File watcher (UI concern). - * - * `fs.watch` alone is unreliable for atomic-rename writes (which is how Claude - * rewrites JSON files), so the watcher pairs `fs.watch` with a continuous - * mtime-polled re-read. The poll catches missed events; the watch keeps - * latency low when it does fire. We dedupe with `mtimeMs` so steady-state - * polls cost a single `stat`. - * - * Screens that need to mirror an agent-emitted JSON file into the store call - * `useFileWatcher(absolutePath, onUpdate)`; the watcher starts on mount and - * tears down on unmount. - */ - -import * as fs from 'fs'; import { useEffect } from 'react'; +import { startFileWatcher, type FileWatcherOptions } from '@lib/file-watcher'; -const DEFAULT_POLL_INTERVAL_MS = 5000; -const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; - -export interface FileWatcherHandle { - stop(): void; -} - -export interface FileWatcherOptions { - /** ms between mtime checks once the file exists. */ - pollIntervalMs?: number; - /** ms between attach attempts while waiting for the file to appear. */ - attachRetryIntervalMs?: number; -} - -/** Watch `path` for JSON updates and call `onUpdate(parsed)` whenever the - * file's mtime changes and the contents are valid JSON. Caller must invoke - * `handle.stop()` to release the watcher. */ -export function startFileWatcher( - path: string, - onUpdate: (parsed: unknown) => void, - options: FileWatcherOptions = {}, -): FileWatcherHandle { - const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS; - const attachRetryIntervalMs = - options.attachRetryIntervalMs ?? DEFAULT_ATTACH_RETRY_INTERVAL_MS; - - const watchers: fs.FSWatcher[] = []; - const intervals: Array> = []; - let lastMtimeMs = 0; - - const read = (force = false) => { - try { - const stat = fs.statSync(path); - if (!force && stat.mtimeMs === lastMtimeMs) return; - lastMtimeMs = stat.mtimeMs; - const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); - onUpdate(parsed); - } catch { - // File missing or not yet valid JSON. - } - }; - - intervals.push(setInterval(() => read(), pollIntervalMs)); - - try { - watchers.push(fs.watch(path, () => read(true))); - read(true); - } catch { - // File doesn't exist yet — retry attaching the watch periodically until - // it appears. The poll above already covers updates; this just upgrades - // latency once the file shows up. - const attachInterval = setInterval(() => { - try { - fs.accessSync(path); - clearInterval(attachInterval); - const idx = intervals.indexOf(attachInterval); - if (idx >= 0) intervals.splice(idx, 1); - watchers.push(fs.watch(path, () => read(true))); - } catch { - // Still waiting. - } - }, attachRetryIntervalMs); - intervals.push(attachInterval); - } - - return { - stop() { - for (const w of watchers) w.close(); - for (const i of intervals) clearInterval(i); - }, - }; -} +export { startFileWatcher } from '@lib/file-watcher'; +export type { FileWatcherHandle, FileWatcherOptions } from '@lib/file-watcher'; /** React hook wrapping `startFileWatcher`. Starts on mount, stops on unmount * or when `path` changes. `onUpdate` and `options` are captured at mount diff --git a/src/ui/tui/screens/RunScreen.tsx b/src/ui/tui/screens/RunScreen.tsx index da78ce378..ecb10c175 100644 --- a/src/ui/tui/screens/RunScreen.tsx +++ b/src/ui/tui/screens/RunScreen.tsx @@ -7,7 +7,6 @@ */ import { useMemo, useSyncExternalStore } from 'react'; -import { join } from 'node:path'; import { Box } from 'ink'; import type { WizardStore } from '@ui/tui/store'; import { @@ -23,8 +22,6 @@ import { ADDITIONAL_FEATURE_LABELS } from '@lib/wizard-session'; import { LearnCard } from '@ui/tui/components/LearnCard'; import { TipsCard } from '@ui/tui/components/TipsCard'; import { useStdoutDimensions } from '@ui/tui/hooks/useStdoutDimensions'; -import { useFileWatcher } from '@ui/tui/hooks/file-watcher'; -import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/index'; import { getProgramConfig } from '@lib/programs/program-registry'; import { getContentBlocks as getSkillContentBlocks } from '@lib/programs/agent-skill/content/index'; @@ -41,24 +38,6 @@ export const RunScreen = ({ store }: RunScreenProps) => { () => store.getSnapshot(), ); - // Mirror the agent's `.posthog-events.json` plan into the store so the - // Event plan tab appears as soon as the agent emits the file. The skill - // tells the agent to use `event_name`/`event_description` (the canonical - // form); `name`/`event`/`description` are legacy fallbacks for skills or - // one-off runs that drift. Drop any entry that still ends up nameless so - // the outro never shows blank bullets. - useFileWatcher(join(store.session.installDir, EVENT_PLAN_FILE), (parsed) => { - if (!Array.isArray(parsed)) return; - store.setEventPlan( - parsed - .map((e: Record) => ({ - name: (e.event_name ?? e.name ?? e.event ?? '') as string, - description: (e.event_description ?? e.description ?? '') as string, - })) - .filter((e) => e.name), - ); - }); - const [columns] = useStdoutDimensions(); const progressItems: ProgressItem[] = store.tasks.map((t) => ({ From dbae635407aa6da98062b6f8571aa09e2bb4d889 Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:52 -0300 Subject: [PATCH 2/7] test: verify final event plan push Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- .../__tests__/task-stream-push.test.ts | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/lib/task-stream/__tests__/task-stream-push.test.ts b/src/lib/task-stream/__tests__/task-stream-push.test.ts index 26de251ef..8a16ce5df 100644 --- a/src/lib/task-stream/__tests__/task-stream-push.test.ts +++ b/src/lib/task-stream/__tests__/task-stream-push.test.ts @@ -471,6 +471,42 @@ describe('TaskStreamPush', () => { }); describe('spec: shutdown flushes terminal phase', () => { + it('includes the captured event plan in the final Completed push', async () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-final-plan-')); + const plan = [ + { name: 'created_dashboard', description: 'User creates a dashboard' }, + ]; + writeFileSync( + join(installDir, EVENT_PLAN_FILE), + JSON.stringify([ + { + event_name: plan[0].name, + event_description: plan[0].description, + }, + ]), + ); + const store = createMockStore({ + installDir, + runPhase: RunPhase.Running, + }); + const { push, dest } = createPush(store); + + try { + push.attach(); + store._emit(); + await flushMicrotasks(); + + store._setAndEmit({ runPhase: RunPhase.Completed }); + await push.shutdown(2000); + + expect(dest.calls.at(-1)?.[0]).toBe(StreamEvent.Complete); + expect(dest.calls.at(-1)?.[1].event_plan).toEqual({ events: plan }); + } finally { + push.detach(); + rmSync(installDir, { recursive: true, force: true }); + } + }); + it('shutdown awaits one final push when phase is terminal', async () => { const store = createMockStore({ runPhase: RunPhase.Completed }); const { push, dest } = createPush(store); From f12cc8a4985691c27eac92ad90716d4b9351d992 Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:53 -0300 Subject: [PATCH 3/7] docs: add QA review report Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- QAREPORT.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 QAREPORT.md diff --git a/QAREPORT.md b/QAREPORT.md new file mode 100644 index 000000000..2f87e30b5 --- /dev/null +++ b/QAREPORT.md @@ -0,0 +1,75 @@ +# 🔍 QA Team Review Report + +| Key | Value | +| ------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **Branch** | `posthog-code/stream-event-plan-headless` | +| **Base** | `main` | +| **Files changed** | 8 | +| **Agents deployed** | 🔒 security, 🔄 reliability, ⚡ performance, 🎨 frontend, 🔗 compatibility, ✏️ copy, 🧑‍💻 generalist-a, 🕵️ generalist-b | +| **Date** | 2026-07-14 | + +--- + +## 📋 Summary + +- Moves `.posthog-events.json` watching from the TUI into shared task-stream + machinery. +- Streams normalized event plans during headless/cloud runs and retains captured + plans after deletion. +- Adds coverage for normalization, file deletion, disabled delivery, and + terminal payloads. +- Reviewers found lifecycle, stale-artifact, and input-bounding risks in the + shared watcher. + +### Key findings + +- 🟡 **High-confidence convergence:** a plan written immediately before + completion can be missed by the terminal push. +- 🟡 **High-confidence convergence:** every program can ingest a stale plan left + by an earlier or unrelated run. +- 🟡 Malformed or oversized plan files are synchronously parsed without runtime + bounds. +- 🟢 Internal `enabled: false` documentation still claims `attach()` is a + complete no-op. + +--- + +## 🏁 Verdict + +> 💬 **APPROVE WITH NITS** + +Overall risk is **MEDIUM** under the QA scoring rules because multiple +independent reviewers found medium-severity issues. The two convergent +correctness findings should be resolved before relying on terminal event-plan +delivery in production. + +--- + +## 👥 Agent summaries + +| Agent | Risk | Summary | +| ---------------- | --------- | ------------------------------------------------------------------------------------------- | +| 🔒 security | 🟡 MEDIUM | Stale repository-controlled plans and unbounded fields cross an authenticated API boundary. | +| 🔄 reliability | 🟡 MEDIUM | Shutdown can stop observation before a late plan write is captured. | +| ⚡ performance | 🟡 MEDIUM | Synchronous unbounded reads and polling broaden resource costs across programs. | +| 🎨 frontend | 🟡 MEDIUM | Global watching can show stale plans, while terminal timing can leave the UI empty. | +| 🔗 compatibility | 🟡 MEDIUM | Payload shape is compatible, but late writes can silently disappear from the final update. | +| ✏️ copy | 🟢 LOW | One internal behavior comment and test name are now misleading. | +| 🧑‍💻 generalist-a | 🟡 MEDIUM | Reproduced the final-read race and flagged stale plans from unrelated runs. | +| 🕵️ generalist-b | 🟡 MEDIUM | Confirmed stale-plan, unbounded-input, and terminal-race breakability. | + +**Note:** ✏️ copy findings are non-blocking nits. 🧑‍💻 generalist-a and 🕵️ +generalist-b are independent generalist reviewers used for convergence +validation. + +--- + +## 📝 Findings + +| # | Status | Priority | Finding | Location | Agents | Reasoning | Suggested fix | +| --- | ------- | --------- | ---------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| 1 | ⬜ Open | 🟡 Medium | Final push can miss a late plan write | `src/lib/task-stream/task-stream-push.ts:162` | reliability, frontend, compatibility, generalist-a, generalist-b | Shutdown stops the watcher before an authoritative final read; retry and polling delays can outlive the run. | Add `EventPlanWatcher.refresh()` and call it before detaching and flushing; test immediate write then shutdown. | +| 2 | ⬜ Open | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/task-stream/task-stream-push.ts:129` | security, frontend, performance, generalist-a, generalist-b | Every task stream reads pre-existing artifacts, so interrupted runs or repository files can be misattributed. | Scope watching through program configuration and ignore/remove files that predate the current qualifying run. | +| 3 | ⬜ Open | 🟡 Medium | Plan input is unbounded and unvalidated | `src/lib/task-stream/event-plan-watcher.ts:20` | security, performance, generalist-b | Type casts provide no runtime safety; large or malformed values can block the event loop or cause rejected pushes. | Enforce regular-file and size limits, string validation, event-count caps, and bounded field lengths. | +| 4 | ⬜ Open | 🟡 Medium | Watch events amplify synchronous parsing | `src/lib/file-watcher.ts:46` | performance | Filesystems may emit duplicate events, and every forced read synchronously reparses the entire file. | Debounce watch events, preserve deduplication, and consider asynchronous bounded reads. | +| 5 | ⬜ Open | 🟢 Low | Disabled-mode contract is outdated | `src/lib/task-stream/task-stream-push.ts:10` | copy | Comments and a test name say `attach()` is a no-op even though local event-plan watching now starts. | Clarify that only destination subscription/delivery is disabled; local artifact watching remains active. | From bc839d14ba76eae0e15ae26c1f434530400632ec Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:55 -0300 Subject: [PATCH 4/7] fix: harden event plan streaming Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- QAREPORT.md | 43 ++++++----- src/lib/file-watcher.ts | 72 +++++++++++++++++-- src/lib/programs/posthog-integration/index.ts | 2 + src/lib/programs/program-step.ts | 7 ++ src/lib/runners/run-non-interactive.ts | 4 ++ src/lib/runners/run-wizard.ts | 4 ++ .../__tests__/event-plan-watcher.test.ts | 66 +++++++++++++++-- .../__tests__/task-stream-push.test.ts | 58 ++++++++++----- src/lib/task-stream/event-plan-watcher.ts | 64 +++++++++++------ src/lib/task-stream/task-stream-push.ts | 24 +++++-- .../tui/hooks/__tests__/file-watcher.test.ts | 31 ++++++++ 11 files changed, 294 insertions(+), 81 deletions(-) diff --git a/QAREPORT.md b/QAREPORT.md index 2f87e30b5..8b42ffcc1 100644 --- a/QAREPORT.md +++ b/QAREPORT.md @@ -18,30 +18,29 @@ plans after deletion. - Adds coverage for normalization, file deletion, disabled delivery, and terminal payloads. -- Reviewers found lifecycle, stale-artifact, and input-bounding risks in the - shared watcher. +- Follow-up fixes resolve the lifecycle, stale-artifact, input-bounding, and + documentation findings. ### Key findings -- 🟡 **High-confidence convergence:** a plan written immediately before - completion can be missed by the terminal push. -- 🟡 **High-confidence convergence:** every program can ingest a stale plan left - by an earlier or unrelated run. -- 🟡 Malformed or oversized plan files are synchronously parsed without runtime - bounds. -- 🟢 Internal `enabled: false` documentation still claims `attach()` is a - complete no-op. +- ✅ Terminal shutdown performs a final authoritative plan refresh before + flushing. +- ✅ Event-plan watching is opt-in through `ProgramConfig` and ignores files + predating the run. +- ✅ Files, event counts, names, descriptions, and file types are bounded and + validated. +- ✅ Directory watch events are debounced and disabled-mode documentation + matches behavior. --- ## 🏁 Verdict -> 💬 **APPROVE WITH NITS** +> ✅ **APPROVE** -Overall risk is **MEDIUM** under the QA scoring rules because multiple -independent reviewers found medium-severity issues. The two convergent -correctness findings should be resolved before relying on terminal event-plan -delivery in production. +All actionable findings from the initial **MEDIUM**-risk review are resolved +with regression coverage. The final implementation is scoped to +event-plan-producing programs and guarantees bounded terminal capture. --- @@ -66,10 +65,10 @@ validation. ## 📝 Findings -| # | Status | Priority | Finding | Location | Agents | Reasoning | Suggested fix | -| --- | ------- | --------- | ---------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| 1 | ⬜ Open | 🟡 Medium | Final push can miss a late plan write | `src/lib/task-stream/task-stream-push.ts:162` | reliability, frontend, compatibility, generalist-a, generalist-b | Shutdown stops the watcher before an authoritative final read; retry and polling delays can outlive the run. | Add `EventPlanWatcher.refresh()` and call it before detaching and flushing; test immediate write then shutdown. | -| 2 | ⬜ Open | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/task-stream/task-stream-push.ts:129` | security, frontend, performance, generalist-a, generalist-b | Every task stream reads pre-existing artifacts, so interrupted runs or repository files can be misattributed. | Scope watching through program configuration and ignore/remove files that predate the current qualifying run. | -| 3 | ⬜ Open | 🟡 Medium | Plan input is unbounded and unvalidated | `src/lib/task-stream/event-plan-watcher.ts:20` | security, performance, generalist-b | Type casts provide no runtime safety; large or malformed values can block the event loop or cause rejected pushes. | Enforce regular-file and size limits, string validation, event-count caps, and bounded field lengths. | -| 4 | ⬜ Open | 🟡 Medium | Watch events amplify synchronous parsing | `src/lib/file-watcher.ts:46` | performance | Filesystems may emit duplicate events, and every forced read synchronously reparses the entire file. | Debounce watch events, preserve deduplication, and consider asynchronous bounded reads. | -| 5 | ⬜ Open | 🟢 Low | Disabled-mode contract is outdated | `src/lib/task-stream/task-stream-push.ts:10` | copy | Comments and a test name say `attach()` is a no-op even though local event-plan watching now starts. | Clarify that only destination subscription/delivery is disabled; local artifact watching remains active. | +| # | Status | Priority | Finding | Location | Agents | Resolution | Validation | +| --- | ----------- | --------- | ---------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| 1 | ✅ Resolved | 🟡 Medium | Final push can miss a late plan write | `src/lib/task-stream/task-stream-push.ts:164` | reliability, frontend, compatibility, generalist-a, generalist-b | Shutdown refreshes the bounded plan reader before detaching and flushing. | Immediate write → completion → shutdown regression test. | +| 2 | ✅ Resolved | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/programs/program-step.ts:226` | security, frontend, performance, generalist-a, generalist-b | Watching is an explicit program capability and files older than the run are ignored. | Unconfigured and stale-artifact tests. | +| 3 | ✅ Resolved | 🟡 Medium | Plan input is unbounded and unvalidated | `src/lib/task-stream/event-plan-watcher.ts:8` | security, performance, generalist-b | Runtime validation caps file size, event count, name length, and description length; symlinks are rejected. | Invalid-field, oversized-file, count, length, and symlink tests. | +| 4 | ✅ Resolved | 🟡 Medium | Watch events amplify synchronous parsing | `src/lib/file-watcher.ts:81` | performance | Parent-directory events are coalesced before bounded reads, while polling retains mtime deduplication. | Atomic rename, recreation, synchronous refresh, and bounds tests. | +| 5 | ✅ Resolved | 🟢 Low | Disabled-mode contract is outdated | `src/lib/task-stream/task-stream-push.ts:10` | copy | Comments and test names distinguish local watching from destination delivery. | Focused task-stream tests. | diff --git a/src/lib/file-watcher.ts b/src/lib/file-watcher.ts index 5e5b3bec0..1e6de563e 100644 --- a/src/lib/file-watcher.ts +++ b/src/lib/file-watcher.ts @@ -7,11 +7,14 @@ */ import * as fs from 'fs'; +import { basename, dirname } from 'node:path'; const DEFAULT_POLL_INTERVAL_MS = 5000; const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; +const DEFAULT_WATCH_DEBOUNCE_MS = 25; export interface FileWatcherHandle { + refresh(): void; stop(): void; } @@ -20,6 +23,12 @@ export interface FileWatcherOptions { pollIntervalMs?: number; /** ms between attach attempts while waiting for the file to appear. */ attachRetryIntervalMs?: number; + /** ms to coalesce duplicate filesystem events. */ + watchDebounceMs?: number; + /** Ignore files older than this timestamp. */ + minMtimeMs?: number; + /** Refuse to read files larger than this many bytes. */ + maxFileSizeBytes?: number; } /** Watch `path` for JSON updates and call `onUpdate(parsed)` whenever the @@ -33,14 +42,32 @@ export function startFileWatcher( const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS; const attachRetryIntervalMs = options.attachRetryIntervalMs ?? DEFAULT_ATTACH_RETRY_INTERVAL_MS; + const watchDebounceMs = options.watchDebounceMs ?? DEFAULT_WATCH_DEBOUNCE_MS; const watchers: fs.FSWatcher[] = []; const intervals: Array> = []; + const targetDir = dirname(path); + const targetName = basename(path); let lastMtimeMs = 0; + let watchDebounceTimer: ReturnType | null = null; + let stopped = false; const read = (force = false) => { try { - const stat = fs.statSync(path); + const stat = fs.lstatSync(path); + if (!stat.isFile() || stat.isSymbolicLink()) return; + if ( + options.minMtimeMs !== undefined && + stat.mtimeMs < options.minMtimeMs + ) { + return; + } + if ( + options.maxFileSizeBytes !== undefined && + stat.size > options.maxFileSizeBytes + ) { + return; + } if (!force && stat.mtimeMs === lastMtimeMs) return; lastMtimeMs = stat.mtimeMs; const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); @@ -50,22 +77,40 @@ export function startFileWatcher( } }; + const scheduleRead = () => { + if (stopped) return; + if (watchDebounceTimer) clearTimeout(watchDebounceTimer); + watchDebounceTimer = setTimeout(() => { + watchDebounceTimer = null; + read(true); + }, watchDebounceMs); + }; + + const attachWatch = () => { + watchers.push( + fs.watch(targetDir, (_eventType, filename) => { + if (filename == null || filename.toString() === targetName) { + scheduleRead(); + } + }), + ); + }; + intervals.push(setInterval(() => read(), pollIntervalMs)); try { - watchers.push(fs.watch(path, () => read(true))); + attachWatch(); read(true); } catch { - // File doesn't exist yet — retry attaching the watch periodically until - // it appears. The poll above already covers updates; this just upgrades - // latency once the file shows up. + // Parent directory does not exist yet. Polling still covers a later file; + // retry attaching the low-latency directory watcher until it appears. const attachInterval = setInterval(() => { try { - fs.accessSync(path); + fs.accessSync(targetDir); clearInterval(attachInterval); const idx = intervals.indexOf(attachInterval); if (idx >= 0) intervals.splice(idx, 1); - watchers.push(fs.watch(path, () => read(true))); + attachWatch(); read(true); } catch { // Still waiting. @@ -75,7 +120,20 @@ export function startFileWatcher( } return { + refresh() { + if (stopped) return; + if (watchDebounceTimer) { + clearTimeout(watchDebounceTimer); + watchDebounceTimer = null; + } + read(true); + }, stop() { + stopped = true; + if (watchDebounceTimer) { + clearTimeout(watchDebounceTimer); + watchDebounceTimer = null; + } for (const watcher of watchers) watcher.close(); for (const interval of intervals) clearInterval(interval); }, diff --git a/src/lib/programs/posthog-integration/index.ts b/src/lib/programs/posthog-integration/index.ts index 02e10b4d1..1b504349c 100644 --- a/src/lib/programs/posthog-integration/index.ts +++ b/src/lib/programs/posthog-integration/index.ts @@ -21,6 +21,7 @@ import type { HostResolution } from '@lib/host-resolution'; import { POSTHOG_INTEGRATION_PROGRAM } from './steps.js'; import { getContentBlocks } from './content/index.js'; import { buildCodingAgentPrompt } from './handoff.js'; +import { EVENT_PLAN_FILE } from './constants.js'; const DASHBOARD_DEEP_LINK_KEY = 'dashboardDeepLink'; @@ -42,6 +43,7 @@ export const posthogIntegrationConfig: ProgramConfig = { description: 'Set up PostHog SDK integration', id: 'posthog-integration', agentFlow: 'integration-v2', + eventPlanFile: EVENT_PLAN_FILE, steps: POSTHOG_INTEGRATION_PROGRAM, getContentBlocks, // Basic integration runs without structured user input; drop wizard_ask diff --git a/src/lib/programs/program-step.ts b/src/lib/programs/program-step.ts index 42a28a92c..532ae74e1 100644 --- a/src/lib/programs/program-step.ts +++ b/src/lib/programs/program-step.ts @@ -241,6 +241,13 @@ export interface ProgramConfig { * read it synchronously without resolving a deferred `run` function. */ reportFile?: string; + /** + * Agent-authored event-plan artifact to mirror into the wizard session. + * Relative to `session.installDir`. Programs that do not produce an event + * plan leave this unset, so generic runner machinery does not inspect a + * stale or unrelated `.posthog-events.json` file. + */ + eventPlanFile?: string; /** * LearnCard deck rendered in the shared `RunScreen` while the agent * runs. Lives at `/content/index.tsx` by convention. diff --git a/src/lib/runners/run-non-interactive.ts b/src/lib/runners/run-non-interactive.ts index 1c2f2395d..702c0e3e9 100644 --- a/src/lib/runners/run-non-interactive.ts +++ b/src/lib/runners/run-non-interactive.ts @@ -6,6 +6,7 @@ import { analytics } from '@utils/analytics'; import { resolveNoTelemetry } from './resolve-no-telemetry'; import type { WizardStore } from '@ui/tui/store'; import type { TaskStreamPush } from '@lib/task-stream/task-stream-push'; +import { join } from 'node:path'; import type { OutroData, RunPhase as RunPhaseT } from '@lib/wizard-session'; /** @@ -153,6 +154,9 @@ export function runNonInteractive( onError: (e) => logToFile('[headless task-stream]', e.message), }), ], + eventPlanPath: config.eventPlanFile + ? join(session.installDir, config.eventPlanFile) + : undefined, enabled: !session.noTelemetry, }); taskStream.attach(); diff --git a/src/lib/runners/run-wizard.ts b/src/lib/runners/run-wizard.ts index 7885220d3..3b4a2bbef 100644 --- a/src/lib/runners/run-wizard.ts +++ b/src/lib/runners/run-wizard.ts @@ -10,6 +10,7 @@ import type { WizardSession } from '@lib/wizard-session'; import type { TaskStreamPush as TaskStreamPushClass } from '@lib/task-stream/task-stream-push'; import { resolveNoTelemetry } from './resolve-no-telemetry'; import { runCleanups } from '@utils/wizard-abort'; +import { join } from 'node:path'; const WIZARD_VERSION = VERSION; @@ -121,6 +122,9 @@ export function runWizard( onError: (err) => logToFile('[task-stream-push]', err.message), }), ], + eventPlanPath: config.eventPlanFile + ? join(session.installDir, config.eventPlanFile) + : undefined, enabled: taskStreamEnabled, }); const activeStream = taskStream; diff --git a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts index 216d445c9..91bb88d78 100644 --- a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts +++ b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts @@ -1,4 +1,10 @@ -import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'; +import { + mkdtempSync, + rmSync, + symlinkSync, + unlinkSync, + writeFileSync, +} from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { @@ -43,25 +49,41 @@ describe('EventPlanWatcher', () => { { event_name: 'signed_up', event_description: 'User signs up' }, { name: 'invited_user', description: 'User sends an invite' }, { event: 'created_team' }, + { event_name: 42, name: 'valid_fallback' }, + { event_name: 'x'.repeat(401) }, + { event_name: ' ' }, { description: 'missing name' }, ]), ).toEqual([ { name: 'signed_up', description: 'User signs up' }, { name: 'invited_user', description: 'User sends an invite' }, { name: 'created_team', description: '' }, + { name: 'valid_fallback', description: '' }, ]); }); + it('caps event count and description length', () => { + const events = Array.from({ length: 60 }, (_, index) => ({ + event_name: `event_${index}`, + event_description: 'x'.repeat(5000), + })); + + const normalized = normalizeEventPlan(events); + + expect(normalized).toHaveLength(50); + expect(normalized?.[0].description).toHaveLength(4000); + }); + it('captures the plan when the file is written after startup', async () => { const store = createStore(installDir); - watcher = new EventPlanWatcher(store, { + const path = join(installDir, EVENT_PLAN_FILE); + watcher = new EventPlanWatcher(store, path, Date.now(), { pollIntervalMs: 30, - attachRetryIntervalMs: 20, }); watcher.start(); writeFileSync( - join(installDir, EVENT_PLAN_FILE), + path, JSON.stringify([{ event_name: 'completed_onboarding' }]), ); await wait(120); @@ -73,10 +95,12 @@ describe('EventPlanWatcher', () => { it('keeps the last captured plan after the file is deleted', async () => { const path = join(installDir, EVENT_PLAN_FILE); - writeFileSync(path, JSON.stringify([{ event_name: 'created_report' }])); const store = createStore(installDir); - watcher = new EventPlanWatcher(store, { pollIntervalMs: 30 }); + watcher = new EventPlanWatcher(store, path, Date.now(), { + pollIntervalMs: 30, + }); watcher.start(); + writeFileSync(path, JSON.stringify([{ event_name: 'created_report' }])); await wait(40); unlinkSync(path); @@ -86,4 +110,34 @@ describe('EventPlanWatcher', () => { { name: 'created_report', description: '' }, ]); }); + + it('ignores a plan file that predates the current run', () => { + const path = join(installDir, EVENT_PLAN_FILE); + writeFileSync(path, JSON.stringify([{ event_name: 'stale_event' }])); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, path, Date.now() + 1); + + watcher.start(); + watcher.refresh(); + + expect(store.eventPlan).toEqual([]); + }); + + it('rejects oversized and symbolic-link plan files', () => { + const path = join(installDir, EVENT_PLAN_FILE); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, path, Date.now()); + watcher.start(); + + writeFileSync(path, JSON.stringify([{ event_name: 'x'.repeat(300_000) }])); + watcher.refresh(); + expect(store.eventPlan).toEqual([]); + + unlinkSync(path); + const target = join(installDir, 'external-plan.json'); + writeFileSync(target, JSON.stringify([{ event_name: 'linked_event' }])); + symlinkSync(target, path); + watcher.refresh(); + expect(store.eventPlan).toEqual([]); + }); }); diff --git a/src/lib/task-stream/__tests__/task-stream-push.test.ts b/src/lib/task-stream/__tests__/task-stream-push.test.ts index 8a16ce5df..2e6155078 100644 --- a/src/lib/task-stream/__tests__/task-stream-push.test.ts +++ b/src/lib/task-stream/__tests__/task-stream-push.test.ts @@ -94,6 +94,7 @@ function createPush( opts: { dest?: ReturnType; enabled?: boolean; + eventPlanPath?: string; } = {}, ) { const dest = opts.dest ?? createMockDestination(); @@ -101,6 +102,7 @@ function createPush( store, programId: 'test-program', destinations: [dest], + eventPlanPath: opts.eventPlanPath, enabled: opts.enabled, }); return { push, dest }; @@ -113,22 +115,43 @@ describe('TaskStreamPush', () => { // ── Existing event-sequencing behaviour ──────────────────────── - it('populates the event plan when destination delivery is disabled', () => { + it('populates the event plan when destination delivery is disabled', async () => { const installDir = mkdtempSync(join(tmpdir(), 'wizard-headless-plan-')); - writeFileSync( - join(installDir, EVENT_PLAN_FILE), - JSON.stringify([{ event_name: 'created_workspace' }]), - ); + const eventPlanPath = join(installDir, EVENT_PLAN_FILE); const store = createMockStore({ installDir }); - const { push, dest } = createPush(store, { enabled: false }); + const { push, dest } = createPush(store, { + enabled: false, + eventPlanPath, + }); push.attach(); + writeFileSync( + eventPlanPath, + JSON.stringify([{ event_name: 'created_workspace' }]), + ); + await push.shutdown(2000); expect(store.eventPlan).toEqual([ { name: 'created_workspace', description: '' }, ]); expect(dest.calls).toHaveLength(0); + rmSync(installDir, { recursive: true, force: true }); + }); + + it('does not inspect event-plan artifacts unless explicitly configured', () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-unrelated-plan-')); + writeFileSync( + join(installDir, EVENT_PLAN_FILE), + JSON.stringify([{ event_name: 'stale_event' }]), + ); + const store = createMockStore({ installDir }); + const { push } = createPush(store); + + push.attach(); + + expect(store.eventPlan).toEqual([]); + push.detach(); rmSync(installDir, { recursive: true, force: true }); }); @@ -331,7 +354,7 @@ describe('TaskStreamPush', () => { }); describe('spec: enabled=false', () => { - it('attach is a no-op and no destination ever fires', () => { + it('does not subscribe or deliver to destinations', () => { const store = createMockStore({ runPhase: RunPhase.Running }); const { push, dest } = createPush(store, { enabled: false }); @@ -473,29 +496,30 @@ describe('TaskStreamPush', () => { describe('spec: shutdown flushes terminal phase', () => { it('includes the captured event plan in the final Completed push', async () => { const installDir = mkdtempSync(join(tmpdir(), 'wizard-final-plan-')); + const eventPlanPath = join(installDir, EVENT_PLAN_FILE); const plan = [ { name: 'created_dashboard', description: 'User creates a dashboard' }, ]; - writeFileSync( - join(installDir, EVENT_PLAN_FILE), - JSON.stringify([ - { - event_name: plan[0].name, - event_description: plan[0].description, - }, - ]), - ); const store = createMockStore({ installDir, runPhase: RunPhase.Running, }); - const { push, dest } = createPush(store); + const { push, dest } = createPush(store, { eventPlanPath }); try { push.attach(); store._emit(); await flushMicrotasks(); + writeFileSync( + eventPlanPath, + JSON.stringify([ + { + event_name: plan[0].name, + event_description: plan[0].description, + }, + ]), + ); store._setAndEmit({ runPhase: RunPhase.Completed }); await push.shutdown(2000); diff --git a/src/lib/task-stream/event-plan-watcher.ts b/src/lib/task-stream/event-plan-watcher.ts index 0bff48dbf..374dfe843 100644 --- a/src/lib/task-stream/event-plan-watcher.ts +++ b/src/lib/task-stream/event-plan-watcher.ts @@ -1,29 +1,43 @@ -import { join } from 'node:path'; import type { PlannedEvent, WizardStore } from '@ui/tui/store'; import { startFileWatcher, type FileWatcherHandle, type FileWatcherOptions, } from '@lib/file-watcher'; -import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; + +const MAX_EVENT_PLAN_FILE_BYTES = 256 * 1024; +const MAX_EVENT_COUNT = 50; +const MAX_EVENT_NAME_LENGTH = 400; +const MAX_EVENT_DESCRIPTION_LENGTH = 4000; + +function firstString(...values: unknown[]): string | null { + const value = values.find((candidate) => typeof candidate === 'string'); + return typeof value === 'string' ? value : null; +} export function normalizeEventPlan(parsed: unknown): PlannedEvent[] | null { if (!Array.isArray(parsed)) return null; - return parsed - .map((value) => { - const entry = - value && typeof value === 'object' - ? (value as Record) - : {}; - return { - name: (entry.event_name ?? entry.name ?? entry.event ?? '') as string, - description: (entry.event_description ?? - entry.description ?? - '') as string, - }; - }) - .filter((event) => event.name); + const events: PlannedEvent[] = []; + for (const value of parsed) { + if (events.length >= MAX_EVENT_COUNT) break; + + const entry = + value && typeof value === 'object' + ? (value as Record) + : {}; + const name = firstString(entry.event_name, entry.name, entry.event); + if (!name || !name.trim() || name.length > MAX_EVENT_NAME_LENGTH) continue; + + const description = + firstString(entry.event_description, entry.description) ?? ''; + events.push({ + name, + description: description.slice(0, MAX_EVENT_DESCRIPTION_LENGTH), + }); + } + + return events; } export class EventPlanWatcher { @@ -31,26 +45,32 @@ export class EventPlanWatcher { constructor( private readonly store: WizardStore, + private readonly path: string, + private readonly startedAtMs: number, private readonly options: FileWatcherOptions = {}, ) {} start(): void { if (this.handle) return; - const installDir = this.store.session.installDir; - if (!installDir) return; - - const path = join(installDir, EVENT_PLAN_FILE); this.handle = startFileWatcher( - path, + this.path, (parsed) => { const events = normalizeEventPlan(parsed); if (events) this.store.setEventPlan(events); }, - this.options, + { + minMtimeMs: this.startedAtMs, + maxFileSizeBytes: MAX_EVENT_PLAN_FILE_BYTES, + ...this.options, + }, ); } + refresh(): void { + this.handle?.refresh(); + } + stop(): void { this.handle?.stop(); this.handle = null; diff --git a/src/lib/task-stream/task-stream-push.ts b/src/lib/task-stream/task-stream-push.ts index 7f21d46b7..a5eb672e4 100644 --- a/src/lib/task-stream/task-stream-push.ts +++ b/src/lib/task-stream/task-stream-push.ts @@ -7,7 +7,7 @@ * - task updates debounced 250ms (trailing edge) * - phase transitions flush immediately, bypass debounce * - RunPhase.Idle skipped (no push) - * - enabled === false attach is a no-op + * - enabled === false destination delivery is disabled * - shutdown(timeoutMs) cancel pending, flush terminal phase * with timeout, never throw * @@ -82,7 +82,9 @@ export interface TaskStreamPushOptions { store: WizardStore; programId: string; destinations: TaskStreamDestination[]; - /** When false, `attach` is a no-op and no destination ever fires. */ + /** Optional absolute event-plan path to mirror into the store. */ + eventPlanPath?: string; + /** When false, destination subscription/delivery remains disabled. */ enabled?: boolean; } @@ -92,7 +94,7 @@ export class TaskStreamPush { private readonly startedAt: string; private readonly programId: string; private readonly sessionId: string; - private readonly eventPlanWatcher: EventPlanWatcher; + private readonly eventPlanWatcher: EventPlanWatcher | null; private enabled: boolean; private created = false; @@ -109,8 +111,15 @@ export class TaskStreamPush { this.programId = sanitizeChannelId(opts.programId); this.destinations = opts.destinations; this.enabled = opts.enabled ?? true; - this.eventPlanWatcher = new EventPlanWatcher(this.store); - this.startedAt = secondPrecisionIso(new Date()); + const startedAt = new Date(); + this.eventPlanWatcher = opts.eventPlanPath + ? new EventPlanWatcher( + this.store, + opts.eventPlanPath, + startedAt.getTime(), + ) + : null; + this.startedAt = secondPrecisionIso(startedAt); // skillId may not be set yet — fall back to programId so the // session_id is stable for the whole run regardless of when the // program metadata is populated. @@ -126,7 +135,7 @@ export class TaskStreamPush { * store for local and headless consumers. */ attach(store?: WizardStore): void { - this.eventPlanWatcher.start(); + this.eventPlanWatcher?.start(); if (!this.enabled) return; if (this.unsubscribe) return; const target = store ?? this.store; @@ -135,7 +144,7 @@ export class TaskStreamPush { /** Stop subscribing. Does not flush. */ detach(): void { - this.eventPlanWatcher.stop(); + this.eventPlanWatcher?.stop(); if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; @@ -155,6 +164,7 @@ export class TaskStreamPush { timeoutMs: number = DEFAULT_SHUTDOWN_TIMEOUT_MS, ): Promise { this.shuttingDown = true; + this.eventPlanWatcher?.refresh(); if (this.debounceTimer) { clearTimeout(this.debounceTimer); this.debounceTimer = null; diff --git a/src/ui/tui/hooks/__tests__/file-watcher.test.ts b/src/ui/tui/hooks/__tests__/file-watcher.test.ts index 8a467d254..f67b15baa 100644 --- a/src/ui/tui/hooks/__tests__/file-watcher.test.ts +++ b/src/ui/tui/hooks/__tests__/file-watcher.test.ts @@ -132,4 +132,35 @@ describe('startFileWatcher', () => { await wait(150); expect(onUpdate.mock.calls.at(-1)?.[0]).toEqual({ v: 2 }); }); + + it('refreshes synchronously before shutdown', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + handle = startFileWatcher(target, onUpdate, { pollIntervalMs: 10_000 }); + writeFileSync(target, JSON.stringify({ final: true })); + + handle.refresh(); + + expect(onUpdate).toHaveBeenCalledWith({ final: true }); + }); + + it('enforces mtime and file-size bounds', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + writeFileSync(target, JSON.stringify({ stale: true })); + handle = startFileWatcher(target, onUpdate, { + minMtimeMs: Date.now() + 1, + maxFileSizeBytes: 20, + }); + + handle.refresh(); + expect(onUpdate).not.toHaveBeenCalled(); + + handle.stop(); + writeFileSync(target, JSON.stringify({ oversized: 'x'.repeat(100) })); + handle = startFileWatcher(target, onUpdate, { maxFileSizeBytes: 20 }); + handle.refresh(); + + expect(onUpdate).not.toHaveBeenCalled(); + }); }); From 5541f2d0bf87e5bb5905a01b6dbc3ff90a68e29a Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:57 -0300 Subject: [PATCH 5/7] fix: make stale plan detection filesystem-safe Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- QAREPORT.md | 6 ++--- src/lib/file-watcher.ts | 27 ++++++++++++++----- .../__tests__/event-plan-watcher.test.ts | 8 +++--- src/lib/task-stream/event-plan-watcher.ts | 3 +-- src/lib/task-stream/task-stream-push.ts | 6 +---- .../tui/hooks/__tests__/file-watcher.test.ts | 15 ++++++++--- 6 files changed, 40 insertions(+), 25 deletions(-) diff --git a/QAREPORT.md b/QAREPORT.md index 8b42ffcc1..8e3912018 100644 --- a/QAREPORT.md +++ b/QAREPORT.md @@ -25,8 +25,8 @@ - ✅ Terminal shutdown performs a final authoritative plan refresh before flushing. -- ✅ Event-plan watching is opt-in through `ProgramConfig` and ignores files - predating the run. +- ✅ Event-plan watching is opt-in through `ProgramConfig` and ignores an + unchanged artifact present when the run starts. - ✅ Files, event counts, names, descriptions, and file types are bounded and validated. - ✅ Directory watch events are debounced and disabled-mode documentation @@ -68,7 +68,7 @@ validation. | # | Status | Priority | Finding | Location | Agents | Resolution | Validation | | --- | ----------- | --------- | ---------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | 1 | ✅ Resolved | 🟡 Medium | Final push can miss a late plan write | `src/lib/task-stream/task-stream-push.ts:164` | reliability, frontend, compatibility, generalist-a, generalist-b | Shutdown refreshes the bounded plan reader before detaching and flushing. | Immediate write → completion → shutdown regression test. | -| 2 | ✅ Resolved | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/programs/program-step.ts:226` | security, frontend, performance, generalist-a, generalist-b | Watching is an explicit program capability and files older than the run are ignored. | Unconfigured and stale-artifact tests. | +| 2 | ✅ Resolved | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/programs/program-step.ts:226` | security, frontend, performance, generalist-a, generalist-b | Watching is an explicit program capability and an unchanged file present at startup is ignored. | Unconfigured and stale-artifact tests. | | 3 | ✅ Resolved | 🟡 Medium | Plan input is unbounded and unvalidated | `src/lib/task-stream/event-plan-watcher.ts:8` | security, performance, generalist-b | Runtime validation caps file size, event count, name length, and description length; symlinks are rejected. | Invalid-field, oversized-file, count, length, and symlink tests. | | 4 | ✅ Resolved | 🟡 Medium | Watch events amplify synchronous parsing | `src/lib/file-watcher.ts:81` | performance | Parent-directory events are coalesced before bounded reads, while polling retains mtime deduplication. | Atomic rename, recreation, synchronous refresh, and bounds tests. | | 5 | ✅ Resolved | 🟢 Low | Disabled-mode contract is outdated | `src/lib/task-stream/task-stream-push.ts:10` | copy | Comments and test names distinguish local watching from destination delivery. | Focused task-stream tests. | diff --git a/src/lib/file-watcher.ts b/src/lib/file-watcher.ts index 1e6de563e..0dfacf642 100644 --- a/src/lib/file-watcher.ts +++ b/src/lib/file-watcher.ts @@ -25,8 +25,8 @@ export interface FileWatcherOptions { attachRetryIntervalMs?: number; /** ms to coalesce duplicate filesystem events. */ watchDebounceMs?: number; - /** Ignore files older than this timestamp. */ - minMtimeMs?: number; + /** Ignore the file that exists when the watcher starts until it changes. */ + ignoreInitialFile?: boolean; /** Refuse to read files larger than this many bytes. */ maxFileSizeBytes?: number; } @@ -49,18 +49,31 @@ export function startFileWatcher( const targetDir = dirname(path); const targetName = basename(path); let lastMtimeMs = 0; + let ignoredInitialSignature: string | null = null; let watchDebounceTimer: ReturnType | null = null; let stopped = false; + const signature = (stat: fs.Stats): string => + `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`; + + if (options.ignoreInitialFile) { + try { + const stat = fs.lstatSync(path); + if (stat.isFile() && !stat.isSymbolicLink()) { + ignoredInitialSignature = signature(stat); + } + } catch { + // No initial file to ignore. + } + } + const read = (force = false) => { try { const stat = fs.lstatSync(path); if (!stat.isFile() || stat.isSymbolicLink()) return; - if ( - options.minMtimeMs !== undefined && - stat.mtimeMs < options.minMtimeMs - ) { - return; + if (ignoredInitialSignature) { + if (signature(stat) === ignoredInitialSignature) return; + ignoredInitialSignature = null; } if ( options.maxFileSizeBytes !== undefined && diff --git a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts index 91bb88d78..b8c6653eb 100644 --- a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts +++ b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts @@ -77,7 +77,7 @@ describe('EventPlanWatcher', () => { it('captures the plan when the file is written after startup', async () => { const store = createStore(installDir); const path = join(installDir, EVENT_PLAN_FILE); - watcher = new EventPlanWatcher(store, path, Date.now(), { + watcher = new EventPlanWatcher(store, path, { pollIntervalMs: 30, }); watcher.start(); @@ -96,7 +96,7 @@ describe('EventPlanWatcher', () => { it('keeps the last captured plan after the file is deleted', async () => { const path = join(installDir, EVENT_PLAN_FILE); const store = createStore(installDir); - watcher = new EventPlanWatcher(store, path, Date.now(), { + watcher = new EventPlanWatcher(store, path, { pollIntervalMs: 30, }); watcher.start(); @@ -115,7 +115,7 @@ describe('EventPlanWatcher', () => { const path = join(installDir, EVENT_PLAN_FILE); writeFileSync(path, JSON.stringify([{ event_name: 'stale_event' }])); const store = createStore(installDir); - watcher = new EventPlanWatcher(store, path, Date.now() + 1); + watcher = new EventPlanWatcher(store, path); watcher.start(); watcher.refresh(); @@ -126,7 +126,7 @@ describe('EventPlanWatcher', () => { it('rejects oversized and symbolic-link plan files', () => { const path = join(installDir, EVENT_PLAN_FILE); const store = createStore(installDir); - watcher = new EventPlanWatcher(store, path, Date.now()); + watcher = new EventPlanWatcher(store, path); watcher.start(); writeFileSync(path, JSON.stringify([{ event_name: 'x'.repeat(300_000) }])); diff --git a/src/lib/task-stream/event-plan-watcher.ts b/src/lib/task-stream/event-plan-watcher.ts index 374dfe843..3184395be 100644 --- a/src/lib/task-stream/event-plan-watcher.ts +++ b/src/lib/task-stream/event-plan-watcher.ts @@ -46,7 +46,6 @@ export class EventPlanWatcher { constructor( private readonly store: WizardStore, private readonly path: string, - private readonly startedAtMs: number, private readonly options: FileWatcherOptions = {}, ) {} @@ -60,7 +59,7 @@ export class EventPlanWatcher { if (events) this.store.setEventPlan(events); }, { - minMtimeMs: this.startedAtMs, + ignoreInitialFile: true, maxFileSizeBytes: MAX_EVENT_PLAN_FILE_BYTES, ...this.options, }, diff --git a/src/lib/task-stream/task-stream-push.ts b/src/lib/task-stream/task-stream-push.ts index a5eb672e4..5a30a95b6 100644 --- a/src/lib/task-stream/task-stream-push.ts +++ b/src/lib/task-stream/task-stream-push.ts @@ -113,11 +113,7 @@ export class TaskStreamPush { this.enabled = opts.enabled ?? true; const startedAt = new Date(); this.eventPlanWatcher = opts.eventPlanPath - ? new EventPlanWatcher( - this.store, - opts.eventPlanPath, - startedAt.getTime(), - ) + ? new EventPlanWatcher(this.store, opts.eventPlanPath) : null; this.startedAt = secondPrecisionIso(startedAt); // skillId may not be set yet — fall back to programId so the diff --git a/src/ui/tui/hooks/__tests__/file-watcher.test.ts b/src/ui/tui/hooks/__tests__/file-watcher.test.ts index f67b15baa..933eb3eed 100644 --- a/src/ui/tui/hooks/__tests__/file-watcher.test.ts +++ b/src/ui/tui/hooks/__tests__/file-watcher.test.ts @@ -144,19 +144,26 @@ describe('startFileWatcher', () => { expect(onUpdate).toHaveBeenCalledWith({ final: true }); }); - it('enforces mtime and file-size bounds', () => { + it('ignores a pre-existing file until it changes', () => { const onUpdate = vi.fn(); const target = path.join(workdir, 'data.json'); writeFileSync(target, JSON.stringify({ stale: true })); handle = startFileWatcher(target, onUpdate, { - minMtimeMs: Date.now() + 1, - maxFileSizeBytes: 20, + ignoreInitialFile: true, }); handle.refresh(); expect(onUpdate).not.toHaveBeenCalled(); - handle.stop(); + writeFileSync(target, JSON.stringify({ current: true })); + handle.refresh(); + expect(onUpdate).toHaveBeenCalledWith({ current: true }); + }); + + it('enforces file-size bounds', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + writeFileSync(target, JSON.stringify({ oversized: 'x'.repeat(100) })); handle = startFileWatcher(target, onUpdate, { maxFileSizeBytes: 20 }); handle.refresh(); From f04b2819f9c9adf406ce6a5f5cac7c716655c298 Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:24:58 -0300 Subject: [PATCH 6/7] fix: load event plans once Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- .../__tests__/event-plan-watcher.test.ts | 20 +++++++++++++++++++ src/lib/task-stream/event-plan-watcher.ts | 10 ++++++++-- src/lib/task-stream/task-stream-push.ts | 4 ++-- src/ui/headless-ui.ts | 2 +- 4 files changed, 31 insertions(+), 5 deletions(-) diff --git a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts index b8c6653eb..81bde5be2 100644 --- a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts +++ b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts @@ -93,6 +93,26 @@ describe('EventPlanWatcher', () => { ]); }); + it('captures the first non-empty plan once', async () => { + const store = createStore(installDir); + const path = join(installDir, EVENT_PLAN_FILE); + watcher = new EventPlanWatcher(store, path, { + pollIntervalMs: 30, + }); + watcher.start(); + + writeFileSync(path, JSON.stringify([])); + await wait(40); + expect(store.eventPlan).toEqual([]); + + writeFileSync(path, JSON.stringify([{ event_name: 'first_event' }])); + await wait(40); + writeFileSync(path, JSON.stringify([{ event_name: 'later_event' }])); + watcher.refresh(); + + expect(store.eventPlan).toEqual([{ name: 'first_event', description: '' }]); + }); + it('keeps the last captured plan after the file is deleted', async () => { const path = join(installDir, EVENT_PLAN_FILE); const store = createStore(installDir); diff --git a/src/lib/task-stream/event-plan-watcher.ts b/src/lib/task-stream/event-plan-watcher.ts index 3184395be..d04cee77c 100644 --- a/src/lib/task-stream/event-plan-watcher.ts +++ b/src/lib/task-stream/event-plan-watcher.ts @@ -42,6 +42,7 @@ export function normalizeEventPlan(parsed: unknown): PlannedEvent[] | null { export class EventPlanWatcher { private handle: FileWatcherHandle | null = null; + private captured = false; constructor( private readonly store: WizardStore, @@ -50,13 +51,17 @@ export class EventPlanWatcher { ) {} start(): void { - if (this.handle) return; + if (this.handle || this.captured) return; this.handle = startFileWatcher( this.path, (parsed) => { const events = normalizeEventPlan(parsed); - if (events) this.store.setEventPlan(events); + if (!events || events.length === 0) return; + + this.captured = true; + this.store.setEventPlan(events); + this.stop(); }, { ignoreInitialFile: true, @@ -67,6 +72,7 @@ export class EventPlanWatcher { } refresh(): void { + if (this.captured) return; this.handle?.refresh(); } diff --git a/src/lib/task-stream/task-stream-push.ts b/src/lib/task-stream/task-stream-push.ts index 5a30a95b6..054004cd7 100644 --- a/src/lib/task-stream/task-stream-push.ts +++ b/src/lib/task-stream/task-stream-push.ts @@ -82,7 +82,7 @@ export interface TaskStreamPushOptions { store: WizardStore; programId: string; destinations: TaskStreamDestination[]; - /** Optional absolute event-plan path to mirror into the store. */ + /** Optional absolute event-plan path to load into the store once. */ eventPlanPath?: string; /** When false, destination subscription/delivery remains disabled. */ enabled?: boolean; @@ -126,7 +126,7 @@ export class TaskStreamPush { } /** - * Mirror the event plan and subscribe to store changes. Destination delivery + * Load the event plan and subscribe to store changes. Destination delivery * remains disabled when `enabled === false`, but the plan still populates the * store for local and headless consumers. */ diff --git a/src/ui/headless-ui.ts b/src/ui/headless-ui.ts index 1d53f44cf..740056634 100644 --- a/src/ui/headless-ui.ts +++ b/src/ui/headless-ui.ts @@ -7,7 +7,7 @@ import type { WizardStore } from './tui/store'; * `LoggingUI` (not `InkUI`) because its blocking/gate methods would wait on a * TUI that never renders; the runner drives phase transitions on the store * directly, so only UI-originated per-run updates tee through here. Runner - * machinery mirrors agent-authored artifacts such as the event plan directly + * machinery loads agent-authored artifacts such as the event plan directly * into the store. */ export class HeadlessUI extends LoggingUI { From cc23e5bcd366f477233af5db894180dc854b0535 Mon Sep 17 00:00:00 2001 From: Fernando Gomes Date: Thu, 16 Jul 2026 09:25:00 -0300 Subject: [PATCH 7/7] fix: address event plan watcher review feedback Generated-By: PostHog Code Task-Id: 479c28e8-6980-43b3-88a1-71cfdc39fbce --- QAREPORT.md | 74 ------------------- src/lib/file-watcher.ts | 40 ++++++++-- .../tui/hooks/__tests__/file-watcher.test.ts | 25 +++++++ 3 files changed, 59 insertions(+), 80 deletions(-) delete mode 100644 QAREPORT.md diff --git a/QAREPORT.md b/QAREPORT.md deleted file mode 100644 index 8e3912018..000000000 --- a/QAREPORT.md +++ /dev/null @@ -1,74 +0,0 @@ -# 🔍 QA Team Review Report - -| Key | Value | -| ------------------- | --------------------------------------------------------------------------------------------------------------------- | -| **Branch** | `posthog-code/stream-event-plan-headless` | -| **Base** | `main` | -| **Files changed** | 8 | -| **Agents deployed** | 🔒 security, 🔄 reliability, ⚡ performance, 🎨 frontend, 🔗 compatibility, ✏️ copy, 🧑‍💻 generalist-a, 🕵️ generalist-b | -| **Date** | 2026-07-14 | - ---- - -## 📋 Summary - -- Moves `.posthog-events.json` watching from the TUI into shared task-stream - machinery. -- Streams normalized event plans during headless/cloud runs and retains captured - plans after deletion. -- Adds coverage for normalization, file deletion, disabled delivery, and - terminal payloads. -- Follow-up fixes resolve the lifecycle, stale-artifact, input-bounding, and - documentation findings. - -### Key findings - -- ✅ Terminal shutdown performs a final authoritative plan refresh before - flushing. -- ✅ Event-plan watching is opt-in through `ProgramConfig` and ignores an - unchanged artifact present when the run starts. -- ✅ Files, event counts, names, descriptions, and file types are bounded and - validated. -- ✅ Directory watch events are debounced and disabled-mode documentation - matches behavior. - ---- - -## 🏁 Verdict - -> ✅ **APPROVE** - -All actionable findings from the initial **MEDIUM**-risk review are resolved -with regression coverage. The final implementation is scoped to -event-plan-producing programs and guarantees bounded terminal capture. - ---- - -## 👥 Agent summaries - -| Agent | Risk | Summary | -| ---------------- | --------- | ------------------------------------------------------------------------------------------- | -| 🔒 security | 🟡 MEDIUM | Stale repository-controlled plans and unbounded fields cross an authenticated API boundary. | -| 🔄 reliability | 🟡 MEDIUM | Shutdown can stop observation before a late plan write is captured. | -| ⚡ performance | 🟡 MEDIUM | Synchronous unbounded reads and polling broaden resource costs across programs. | -| 🎨 frontend | 🟡 MEDIUM | Global watching can show stale plans, while terminal timing can leave the UI empty. | -| 🔗 compatibility | 🟡 MEDIUM | Payload shape is compatible, but late writes can silently disappear from the final update. | -| ✏️ copy | 🟢 LOW | One internal behavior comment and test name are now misleading. | -| 🧑‍💻 generalist-a | 🟡 MEDIUM | Reproduced the final-read race and flagged stale plans from unrelated runs. | -| 🕵️ generalist-b | 🟡 MEDIUM | Confirmed stale-plan, unbounded-input, and terminal-race breakability. | - -**Note:** ✏️ copy findings are non-blocking nits. 🧑‍💻 generalist-a and 🕵️ -generalist-b are independent generalist reviewers used for convergence -validation. - ---- - -## 📝 Findings - -| # | Status | Priority | Finding | Location | Agents | Resolution | Validation | -| --- | ----------- | --------- | ---------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| 1 | ✅ Resolved | 🟡 Medium | Final push can miss a late plan write | `src/lib/task-stream/task-stream-push.ts:164` | reliability, frontend, compatibility, generalist-a, generalist-b | Shutdown refreshes the bounded plan reader before detaching and flushing. | Immediate write → completion → shutdown regression test. | -| 2 | ✅ Resolved | 🟡 Medium | Stale plans leak into unrelated runs | `src/lib/programs/program-step.ts:226` | security, frontend, performance, generalist-a, generalist-b | Watching is an explicit program capability and an unchanged file present at startup is ignored. | Unconfigured and stale-artifact tests. | -| 3 | ✅ Resolved | 🟡 Medium | Plan input is unbounded and unvalidated | `src/lib/task-stream/event-plan-watcher.ts:8` | security, performance, generalist-b | Runtime validation caps file size, event count, name length, and description length; symlinks are rejected. | Invalid-field, oversized-file, count, length, and symlink tests. | -| 4 | ✅ Resolved | 🟡 Medium | Watch events amplify synchronous parsing | `src/lib/file-watcher.ts:81` | performance | Parent-directory events are coalesced before bounded reads, while polling retains mtime deduplication. | Atomic rename, recreation, synchronous refresh, and bounds tests. | -| 5 | ✅ Resolved | 🟢 Low | Disabled-mode contract is outdated | `src/lib/task-stream/task-stream-push.ts:10` | copy | Comments and test names distinguish local watching from destination delivery. | Focused task-stream tests. | diff --git a/src/lib/file-watcher.ts b/src/lib/file-watcher.ts index 0dfacf642..1d3d07cc8 100644 --- a/src/lib/file-watcher.ts +++ b/src/lib/file-watcher.ts @@ -8,6 +8,7 @@ import * as fs from 'fs'; import { basename, dirname } from 'node:path'; +import { logToFile } from '@utils/debug'; const DEFAULT_POLL_INTERVAL_MS = 5000; const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; @@ -51,6 +52,7 @@ export function startFileWatcher( let lastMtimeMs = 0; let ignoredInitialSignature: string | null = null; let watchDebounceTimer: ReturnType | null = null; + let lastReadErrorSignature: string | null = null; let stopped = false; const signature = (stat: fs.Stats): string => @@ -67,26 +69,48 @@ export function startFileWatcher( } } + const logReadError = (errorSignature: string, message: string) => { + if (lastReadErrorSignature === errorSignature) return; + lastReadErrorSignature = errorSignature; + logToFile(`[file-watcher] ${message}: ${path}`); + }; + const read = (force = false) => { + let stat: fs.Stats; + try { + stat = fs.lstatSync(path); + } catch { + return; + } + + if (!stat.isFile() || stat.isSymbolicLink()) return; + const fileSignature = signature(stat); + try { - const stat = fs.lstatSync(path); - if (!stat.isFile() || stat.isSymbolicLink()) return; if (ignoredInitialSignature) { - if (signature(stat) === ignoredInitialSignature) return; + if (fileSignature === ignoredInitialSignature) return; ignoredInitialSignature = null; } if ( options.maxFileSizeBytes !== undefined && stat.size > options.maxFileSizeBytes ) { + logReadError( + `oversized:${fileSignature}`, + `refusing oversized JSON file (${stat.size} bytes, limit ${options.maxFileSizeBytes} bytes)`, + ); return; } if (!force && stat.mtimeMs === lastMtimeMs) return; lastMtimeMs = stat.mtimeMs; const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); + lastReadErrorSignature = null; onUpdate(parsed); - } catch { - // File missing or not yet valid JSON. + } catch (error) { + logReadError( + `invalid:${fileSignature}:${String(error)}`, + `could not read valid JSON (${String(error)})`, + ); } }; @@ -113,7 +137,11 @@ export function startFileWatcher( try { attachWatch(); - read(true); + // Defer the initial callback until the caller has received the handle, so + // callbacks that stop their watcher cannot race handle assignment. + queueMicrotask(() => { + if (!stopped) read(true); + }); } catch { // Parent directory does not exist yet. Polling still covers a later file; // retry attaching the low-latency directory watcher until it appears. diff --git a/src/ui/tui/hooks/__tests__/file-watcher.test.ts b/src/ui/tui/hooks/__tests__/file-watcher.test.ts index 933eb3eed..4d764222b 100644 --- a/src/ui/tui/hooks/__tests__/file-watcher.test.ts +++ b/src/ui/tui/hooks/__tests__/file-watcher.test.ts @@ -5,6 +5,11 @@ import { startFileWatcher, type FileWatcherHandle, } from '@ui/tui/hooks/file-watcher'; +import { logToFile } from '@utils/debug'; + +vi.mock('@utils/debug', () => ({ + logToFile: vi.fn(), +})); const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); @@ -14,6 +19,7 @@ describe('startFileWatcher', () => { beforeEach(() => { workdir = mkdtempSync(path.join(tmpdir(), 'wizard-fw-')); + vi.mocked(logToFile).mockClear(); }); afterEach(() => { @@ -97,6 +103,22 @@ describe('startFileWatcher', () => { await wait(100); expect(onUpdate).not.toHaveBeenCalled(); + expect(logToFile).toHaveBeenCalledWith( + expect.stringContaining('could not read valid JSON'), + ); + }); + + it('allows an initial update callback to stop its watcher', async () => { + const target = path.join(workdir, 'data.json'); + writeFileSync(target, JSON.stringify({ a: 1 })); + const onUpdate = vi.fn(() => handle?.stop()); + + handle = startFileWatcher(target, onUpdate, { pollIntervalMs: 30 }); + await wait(20); + writeFileSync(target, JSON.stringify({ a: 2 })); + await wait(100); + + expect(onUpdate).toHaveBeenCalledTimes(1); }); it('stop() halts polling and watchers', async () => { @@ -169,5 +191,8 @@ describe('startFileWatcher', () => { handle.refresh(); expect(onUpdate).not.toHaveBeenCalled(); + expect(logToFile).toHaveBeenCalledWith( + expect.stringContaining('refusing oversized JSON file'), + ); }); });