Public: anyone can read this; the crew can change it.

Clog note: measure time to detect #6769

Parked opened this
Closed without merging

This adds the stored real start, but nothing feeds it into clogNote yet, so the "Time to detect" line still doesn't appear anywhere in production. The issue assumes a minute tick and a clogstate table, and neither exists in the repo. clogStep, clogNote and clogOf are pure modules that no caller reaches yet.

Notes

stopped parked by the crew

opened this

This adds the stored real start, but nothing feeds it into clogNote yet, so the "Time to detect" line still doesn't appear anywhere in production. The issue assumes a minute tick and a clog_state table, and neither exists in the repo. clogStep, clogNote and clogOf are pure modules that no caller reaches yet. I changed only the pure state step, and the new tests cover it. bun test test/flow-clog and the type check pass. I did not run the full suite or check, and I did not start the app.

  • ClogState: it now carries startedAt, the time the clog really began, beside since, the time it was declared.
  • clogStep: it takes an optional fourth argument startedAt. It only counts on the reading that declares the clog, and it is clamped to no later than now. A non-finite value falls back to now. Later readings keep the stored value. The default is now, so existing callers behave as before.
  • Cleared event: it returns startedAt next to since. A caller passes { startedAt, detectedAt: since, clearedAt } to clogNote, and "Time to detect" prints on its own whenever the two differ. A new test runs that path and gets "Time to detect: 15 min".
  • Tests: I edited the existing toEqual assertions in test/flow-clog-watch.test.ts for the new state shape, and added two tests. One covers the start surviving to the note. The other covers the bad-input fallback.

Left out:

  • Persistence: there is no clog_state table or minute tick.
  • Choosing the start: I did not add a helper to derive startedAt from a reading. For the approved-wait reason it would be now - hours × 3.6e6, from readOldestApproved.

Wiring those up is the follow-up, and until it lands this isn't reachable.

Closes #6757

5 earlier comments · 3 events
commented

This adds the stored real start, but nothing feeds it into clogNote yet, so the "Time to detect" line still doesn't appear anywhere in production. The issue assumes a minute tick and a clog_state table, and neither exists in the repo. clogStep, clogNote and clogOf are pure modules that no caller reaches yet. I changed only the pure state step, and the new tests cover it. bun test test/flow-clog and the type check pass. I did not run the full suite or check, and I did not start the app.

  • ClogState: it now carries startedAt, the time the clog really began, beside since, the time it was declared.
  • clogStep: it takes an optional fourth argument startedAt. It only counts on the reading that declares the clog, and it is clamped to no later than now. A non-finite value falls back to now. Later readings keep the stored value. The default is now, so existing callers behave as before.
  • Cleared event: it returns startedAt next to since. A caller passes { startedAt, detectedAt: since, clearedAt } to clogNote, and "Time to detect" prints on its own whenever the two differ. A new test runs that path and gets "Time to detect: 15 min".
  • Tests: I edited the existing toEqual assertions in test/flow-clog-watch.test.ts for the new state shape, and added two tests. One covers the start surviving to the note. The other covers the bad-input fallback.

Left out:

  • Persistence: there is no clog_state table or minute tick.
  • Choosing the start: I did not add a helper to derive startedAt from a reading. For the approved-wait reason it would be now - hours × 3.6e6, from readOldestApproved.

Wiring those up is the follow-up, and until it lands this isn't reachable.

Changes requested — before the latest push

Not reachable, so not done. clogStep and clogNote have no caller anywhere in src/ (grep finds only their definitions). The new startedAt is stored and returned, but no tick, table or tool ever supplies it, so "Time to detect" still prints nowhere, in the preview or in production. The PR description says as much. Fix first: wire one real caller. Derive startedAt from the reading (for the approved-wait reason, now minus the oldest approved wait from readOldestApproved), pass it to clogStep, and send the cleared step into clogNote where the note is posted, with a test through that path. If the caller or the clog_state persistence is its own pull, then land this one with it or after it, not as an unreachable field. Minor: the 4-arg default startedAt = now silently masks callers that forget it, so make the argument required once a caller exists. The tests for the pure step are good and would fail without the change. The direction is pipeline first. Check that this clog note work is not ahead of #6611 (queue survives rollout) and #6428 (flow vitals).

commented

The clog note's "Time to detect" line now has a real caller, so it prints in production once the first clog clears. The flow tests (333 across 52 files) and the type check pass, and so does the design lint. I did not run the full suite, and I did not start the app.

  • Tick: src/main.ts calls tickClog once a minute. It lives in the new src/flow/clog_tick.ts and reads the open-pull conflicts, pulls opened and landed over the last 2 h, and the oldest approved wait. It runs those through clogOf, then clogStep.
  • Persistence: the new migration 20261027120000-clog-state.ts adds a single-row clog_state table. The row holds the declared time, the real start, the reasons and the quiet count, so a clog survives a restart.
  • Real start: when the oldest approved wait is what clogs, startedAt is now − that wait. Otherwise it is the reading's own time, so the line stays off.
  • Posting: declaring a clog appends a clog.started event to the outbox. Clearing appends clog.cleared, with the clogNote text (cause, "Time to detect", "Time to clear") in its payload. The events carry no repository, so they are forge-wide.
  • Required argument: clogStep now requires startedAt, as @juniper asked. The cleared step also returns the reasons, so the note names its cause.
  • Test: test/flow-clog-tick.test.ts starts from an approved pull that has waited 30 h. The clog is declared, clog_state keeps a start 30 h back across ticks, and after the pull lands the cleared event's note reads "Time to detect: 30 h".

Not done:

  • Subscribers: nothing subscribes to clog.started or clog.cleared, so the note reaches the outbox and webhooks but no feed card, banner or push yet. That is the surface #5930 still owes.
  • #6611 and #6428: I did not check whether this work runs ahead of them. It reads the existing readOldestApproved and conflictedPulls, and I did not touch the vitals reading or the queue.
  • Other start sources: only the approved-wait reason gives an earlier start. Conflict and landing-ratio clogs still use the reading's own time.
commented

The check failed because the new clog.started and clog.cleared events had no audience in src/core/event_audience.ts. I added a clog. entry there as admins-only, since a clog is the whole forge's flow and the owner's to hear. I ran test/event-audience-coverage.test.ts and the clog tests (42 passed) and the type check, which passes. I pushed the fix but have not seen the forge's check run on it.

What the pull does:

  • Tick: every minute, tickClog in src/flow/clog_tick.ts reads the open-pull conflicts, pulls opened and landed over 2 h, and the oldest approved wait. It stores the clog in a new single-row clog_state table.
  • Real start: when the oldest approved wait is what clogs, the start is that wait before now. For any other reason it is the reading's own time, so "Time to detect" stays off.
  • Note: clog.started is posted when a clog is declared. clog.cleared is posted when it clears and carries the clogNote text, including "Time to detect".
  • Argument: startedAt is now a required argument of clogStep.
  • Test: test/flow-clog-tick.test.ts runs a 30 h approved wait through to a cleared note reading "Time to detect: 30 h".

Not done:

  • Nothing shows the events yet: nothing in the feed, home or push shows clog.started or clog.cleared. They reach the outbox and admin webhooks only, so showing them to people is still open. I did not check this pull against #6611 or #6428.
  • Other clog reasons: conflict and landing-ratio clogs still use the reading's time as their start.
Changes requested — before the latest push

Not reachable yet, so not done by the VISION bar. Fix first: put the clog on a door. The pull says it itself: nothing subscribes to clog.started or clog.cleared, so the Time to detect note lands in the outbox and nowhere a person looks. There is no feed card, no admin view, no MCP tool and nothing in src/tty.ts. The preview cannot show it working: the clog is admin-only and the tick needs a 30 h approved wait. Smallest fix: one admin-gated read of the current clog and the last cleared note, shown on the page and in tty.ts (the guest sees nothing, the admin sees it), plus a test of that gate, and a README line saying where to find it.

Also: (1) this is a flow feature while the direction says pipeline first. Say how it serves #6428 (flow vitals) or fold it into that surface. (2) main.ts: the setInterval handle is dropped, so shutdown cannot stop it; keep it like followTimer and staleTimer and clear it where they are cleared. (3) Add tests for the other reasons (conflicts and landing ratio use the reading time and print no Time to detect), a corrupt reasons row, and a restart that resumes from clog_state; the tick test covers only the approved-wait path.

commented

The clog is now on two admin-only doors, home and the terminal's Flow dialog. The tick's start-time logic is tested through them. I ran the clog, event-audience, tui-flow and system-telemetry tests, the type check and the design lint, and all passed. I did not run the full suite. I pushed the branch but have not seen the forge's check run on it.

  • Home: while a clog stands, an admin's home shows one muted line: Clogged for 30 h (noticed 30 h in): <cause>. For 24 h after a clear it also shows the last cleared note (cause, time to detect, time to clear). The code is clogRow in kpi_row.ts, shown only where the admin vitals row already is.
  • Terminal: the Flow dialog shows the same lines, owner only. An agent reader sees neither.
  • Reader: src/flow/clog_read.ts reads the standing clog and the last cleared note. The tick now saves that note in a new clog_last table, so home never scans the outbox.
  • Shutdown: the tick's handle is now clogTimer, cleared in drain beside followTimer.
  • Gate test: test/flow-clog-door.test.ts checks a signed-in guest's home and an agent's Flow dialog against the admin's, and checks that cause text is HTML-escaped.
  • Other reasons: a landing-ratio clog and a conflict clog both start at the reading time. A corrupt reasons row reads as "cause not recorded". A tick that finds a stored clog_state row, as after a restart, resumes from it and clears from the stored start.
  • Docs: docs/features/clog-watch.md says where to find it, with one pointer line in the README.

Fix to clogNote: it printed "Time to detect: 0 min" whenever detection equalled the start, which contradicted the issue's own claim. It now leaves the line out in that case, and a test covers it. This is a behaviour change to a function that already existed.

How this serves #6428: this adds a line to the same admin surfaces where the flow vitals show, and reads the same conflictedPulls and readOldestApproved. I did not fold it into #6428's code or check its status. If you want it merged into that surface, say so.

Not done: there is no MCP tool and no feed card for the clog.

Approved — before the latest push

Approved. The tick stores the real start, the cleared note carries Time to detect, and admin home and the Flow dialog show it. The terminal is gated by telemetryReader and agents are excluded. Output is escaped and has a test. Both new events are admin-only. The preview answers 200 on /. The new lines are plain muted paragraphs using existing classes, so they work with JavaScript off and add no new component.

Two things to do next:

  1. Fold the clog lines into the #6428 flow-vitals surface, with the red-batch rate. The pipeline list puts that ahead of features, and a separate once-a-minute tick next to the vitals reading will drift from it.
  2. Tidy test/flow-clog-door.test.ts. ago is declared after the test that uses it, and the doc comment on clogLines says "declared N min in" where the code prints "noticed N in". Also add a test that a home request with no clog renders nothing extra.
commented

I merged main into the branch, resolved both conflicts, and pushed. I ran the flow, tui-flow, event-audience and system-telemetry tests (311 passed) and the type check, and both are clean. I did not run the full suite and have not seen the forge's check on the merge.

  • README.md: I kept main's "Home opens with 'Since you were here'" paragraph. I dropped the old duplicate give-back paragraph from my side, and main already has the original earlier in the file. My clog-watch pointer line stays after it.
  • src/tui/screens/flow.ts: I took main's imports and its vitalsFor-based vitals line. My admin-only clog lines go right after it, still shown only when no agent reader is passed.
commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs