|
|
|
@@ -1,555 +0,0 @@
|
|
|
|
|
---
|
|
|
|
|
title: feat: Add durable live session recovery
|
|
|
|
|
type: feat
|
|
|
|
|
status: active
|
|
|
|
|
date: 2026-04-28
|
|
|
|
|
deepened: 2026-04-28
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# feat: Add durable live session recovery
|
|
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
|
|
|
|
Impeccable live mode should remain recoverable when the browser changes live-session state while the agent is not actively polling, after the agent is interrupted, or after the helper server/page reloads. The change adds a durable live-session journal, a resumable server/browser state contract, and an agent-facing status command so a fresh agent can reconstruct the active session and continue from the correct next action.
|
|
|
|
|
|
|
|
|
|
This plan does not change the core source-first live-mode architecture from `docs/adr-live-variant-mode.md`: variants are still written to source, the browser still previews through HMR or `/source`, and the agent still uses long-poll. It makes the state machine durable and inspectable instead of relying on chat memory plus in-process queues.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Problem Frame
|
|
|
|
|
|
|
|
|
|
The observed failure mode was: the user accepted and tuned a live variant in the browser while the agent was not listening continuously. The browser moved forward, source entered a transitional state, and the agent no longer had authoritative context for what the user had done. Current code already has useful browser `localStorage` resume behavior and server in-memory queues, but neither is sufficient as a recovery source after interruption, server restart, browser cleanup, or missed polling.
|
|
|
|
|
|
|
|
|
|
The product expectation is stronger: if the user changes live-mode state in the browser, a later agent should be able to ask, “what happened and what do I need to do next?” and receive a complete, durable answer.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Requirements Trace
|
|
|
|
|
|
|
|
|
|
- R1. Browser live-session changes are durably recorded outside browser memory and chat context.
|
|
|
|
|
- R2. A new or interrupted agent can reconstruct the current live session, selected variant, parameter values, source file, and next required action.
|
|
|
|
|
- R3. Accept/discard events are not silently lost when the agent is not polling or when the helper server restarts.
|
|
|
|
|
- R4. Browser resume behavior treats source markers and durable session state as recoverable truth rather than hiding unfinished work behind a local handled flag.
|
|
|
|
|
- R5. Durable replay is idempotent: duplicate, late, or conflicting events must not corrupt source.
|
|
|
|
|
- R6. Carbonize-required accepts are represented as an explicit incomplete state until cleanup is done, and can reconcile to complete when source markers prove cleanup already happened.
|
|
|
|
|
- R7. Existing browser/agent event transport remains self-contained, zero-dependency, token-protected, and compatible with the current SSE plus long-poll protocol. Status/resume may be implemented as a separate CLI/file-reader API.
|
|
|
|
|
- R8. Agent delivery uses an explicit lease/ack model so a poll response is not treated as completed work until the agent reports a result.
|
|
|
|
|
- R9. Annotated screenshots and generated-file fallback metadata remain recoverable while a session is incomplete.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Scope Boundaries
|
|
|
|
|
|
|
|
|
|
- This plan does not replace long-poll with WebSockets or a harness-specific integration.
|
|
|
|
|
- This plan does not make accept fully atomic in one step. It records and resumes the incomplete state first; a later plan may remove carbonize as a manual cleanup stage.
|
|
|
|
|
- This plan does not redesign generated variant quality or CSS specificity behavior, except where preview state metadata needs to be captured.
|
|
|
|
|
- This plan does not introduce a database or external service. Durable state should live in project-local files managed by the helper server.
|
|
|
|
|
- This plan does not support multiple simultaneous browser tabs editing different sessions as a first-class collaboration mode. It should avoid corrupting them, but single active session remains the baseline.
|
|
|
|
|
|
|
|
|
|
### Deferred to Follow-Up Work
|
|
|
|
|
|
|
|
|
|
- Atomic accept/carbonize: a later plan can make `live-accept.mjs` produce permanent clean source in one deterministic step.
|
|
|
|
|
- Safer generated-preview layout defaults: a later plan can harden wrapper sizing, overflow, and scoped selector guidance.
|
|
|
|
|
- Multi-user or multi-tab collaboration semantics: out of scope until live mode intentionally supports collaborative sessions.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Context & Research
|
|
|
|
|
|
|
|
|
|
### Relevant Code and Patterns
|
|
|
|
|
|
|
|
|
|
- `skill/scripts/live-server.mjs` owns `/events`, `/poll`, `/source`, `/health`, token validation, in-memory `pendingEvents`, and browser SSE clients.
|
|
|
|
|
- `skill/scripts/live-browser.js` owns picker state, variant cycling, parameter controls, `localStorage` session resume, handled-session sentinels, and accept/discard browser behavior.
|
|
|
|
|
- `skill/scripts/live-poll.mjs` is the agent-facing poll client and auto-runs `live-accept.mjs` for accept/discard events.
|
|
|
|
|
- `skill/scripts/live-accept.mjs` deterministically accepts/discards variant wrappers and can emit carbonize-required results.
|
|
|
|
|
- `skill/scripts/live-wrap.mjs` creates source markers and original/variant wrapper structure.
|
|
|
|
|
- `tests/live-server.test.mjs`, `tests/live-accept.test.mjs`, `tests/live-wrap.test.mjs`, and `tests/live-e2e.test.mjs` are the relevant verification surfaces.
|
|
|
|
|
- `docs/adr-live-variant-mode.md` documents the current architecture and should be updated if the durable journal changes the lifecycle contract.
|
|
|
|
|
|
|
|
|
|
### Institutional Learnings
|
|
|
|
|
|
|
|
|
|
- `docs/adr-live-variant-mode.md` explicitly values source modification over DOM patching, zero-dependency scripts, SSE plus fetch, long-poll for agent compatibility, and `display: contents` wrappers.
|
|
|
|
|
- `skill/reference/live.md` currently encodes the operational assumption that the agent continuously polls and performs carbonize cleanup before the next poll.
|
|
|
|
|
|
|
|
|
|
### External References
|
|
|
|
|
|
|
|
|
|
- External research skipped. This is a repo-owned local protocol and the existing architecture is well documented; local patterns are more authoritative than generic event-sourcing guidance.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Key Technical Decisions
|
|
|
|
|
|
|
|
|
|
- Add a project-local durable live-session store rather than relying on browser `localStorage` or server memory alone: this is the minimum change that lets any future agent reconstruct state.
|
|
|
|
|
- Use append-only session events plus a compact session snapshot: append-only events preserve the audit trail for recovery; the snapshot makes status reads fast and simple. The append-only journal and source markers are canonical; snapshots are rebuildable caches.
|
|
|
|
|
- Treat poll delivery as a leased work item, not queue removal: an event becomes terminal only after the agent posts a result/ack, and stale leases are redelivered idempotently.
|
|
|
|
|
- Keep browser `localStorage` as a UI convenience, not the source of truth: source markers plus durable server journal should win when they disagree.
|
|
|
|
|
- Add explicit server-side session states instead of ad hoc flags: states make accept/discard replay, stale checkpoint rejection, and invalid transitions enforceable.
|
|
|
|
|
- Make accept/discard delivery acknowledged before the browser clears recoverable state: this prevents “browser thinks handled, source did not change” split-brain.
|
|
|
|
|
- Add agent-facing status/resume scripts instead of requiring agents to inspect raw files: live mode needs a stable agent API, not folklore.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Open Questions
|
|
|
|
|
|
|
|
|
|
### Resolved During Planning
|
|
|
|
|
|
|
|
|
|
- Should the first fix be durable resumability or atomic accept? Durable resumability comes first because it solves missed polling, interrupted agents, and transitional source states without requiring a full accept rewrite.
|
|
|
|
|
- Should durability depend on external storage? No. Live mode is intentionally self-contained and should use project-local files.
|
|
|
|
|
|
|
|
|
|
### Deferred to Implementation
|
|
|
|
|
|
|
|
|
|
- Exact file naming inside the session store: implementation should choose a simple structure after reviewing how `.impeccable-live.json` is currently managed.
|
|
|
|
|
- Exact retention policy defaults: implementation should start conservative and prune old completed sessions only after tests cover recovery.
|
|
|
|
|
- Exact browser UI copy for pending accept/reconnect states: copy should be short and can be refined during implementation.
|
|
|
|
|
- Exact helper-server restart UX: auto-rebind across token/port rotation is out of scope for this plan unless implementation discovers a safe lightweight path. The default recovery is `live-status` plus asking the user to reload/reopen the instrumented page when needed.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Output Structure
|
|
|
|
|
|
|
|
|
|
skill/scripts/
|
|
|
|
|
live-session-store.mjs
|
|
|
|
|
live-status.mjs
|
|
|
|
|
live-resume.mjs
|
|
|
|
|
live-server.mjs
|
|
|
|
|
live-browser.js
|
|
|
|
|
live-poll.mjs
|
|
|
|
|
live-accept.mjs
|
|
|
|
|
tests/
|
|
|
|
|
live-session-store.test.mjs
|
|
|
|
|
live-server.test.mjs
|
|
|
|
|
live-browser-recovery.test.mjs
|
|
|
|
|
live-poll.test.mjs
|
|
|
|
|
live-status.test.mjs
|
|
|
|
|
live-e2e.test.mjs
|
|
|
|
|
package.json
|
|
|
|
|
docs/
|
|
|
|
|
adr-live-variant-mode.md
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## High-Level Technical Design
|
|
|
|
|
|
|
|
|
|
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
stateDiagram-v2
|
|
|
|
|
[*] --> configuring
|
|
|
|
|
configuring --> generating: browser Go
|
|
|
|
|
generating --> source_wrapped: agent wrapped source; file known
|
|
|
|
|
source_wrapped --> variants_written: agent wrote variants
|
|
|
|
|
variants_written --> cycling: agent replies done or browser sees wrapper
|
|
|
|
|
cycling --> accept_pending: browser Accept
|
|
|
|
|
cycling --> discard_pending: browser Discard
|
|
|
|
|
accept_pending --> accepted_source_pending: agent/live-accept wrote accepted variant with carbonize markers
|
|
|
|
|
accepted_source_pending --> complete: carbonize cleanup done
|
|
|
|
|
discard_pending --> complete: source restored
|
|
|
|
|
generating --> stranded: server/page/agent interruption
|
|
|
|
|
cycling --> stranded: server/page/agent interruption
|
|
|
|
|
accept_pending --> stranded: server/page/agent interruption
|
|
|
|
|
stranded --> generating: resume pending leased event
|
|
|
|
|
stranded --> source_wrapped: resume wrapper/original-only source
|
|
|
|
|
stranded --> cycling: resume from durable journal + source markers
|
|
|
|
|
stranded --> accepted_source_pending: resume from carbonize markers
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
|
sequenceDiagram
|
|
|
|
|
participant B as Browser
|
|
|
|
|
participant S as Live server
|
|
|
|
|
participant J as Session journal
|
|
|
|
|
participant A as Agent
|
|
|
|
|
participant F as Source files
|
|
|
|
|
|
|
|
|
|
B->>S: POST /events accept_intent(session, variant, params)
|
|
|
|
|
S->>J: append event; rebuild/atomically update snapshot(accept_pending)
|
|
|
|
|
S-->>B: 202 accepted + durable sequence
|
|
|
|
|
A->>S: GET /poll or live-status
|
|
|
|
|
S->>J: lease next pending event
|
|
|
|
|
S-->>A: accept event + recovery context + lease id
|
|
|
|
|
A->>F: live-accept / cleanup
|
|
|
|
|
A->>S: POST /poll done + file/result + lease id
|
|
|
|
|
S->>J: append agent_result; mark lease acked; update snapshot
|
|
|
|
|
S-->>B: SSE done/committed
|
|
|
|
|
B->>B: clear local pending state only after committed
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Implementation Units
|
|
|
|
|
|
|
|
|
|
- U1. **Define durable session store**
|
|
|
|
|
|
|
|
|
|
**Goal:** Add a small storage module that can append events, update snapshots, read active sessions, and recover pending work after process restart.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R1, R2, R3, R5, R7, R8, R9
|
|
|
|
|
|
|
|
|
|
**Dependencies:** None
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Create: `skill/scripts/live-session-store.mjs`
|
|
|
|
|
- Create: `tests/live-session-store.test.mjs`
|
|
|
|
|
- Modify: `skill/scripts/live-server.mjs`
|
|
|
|
|
- Modify: `package.json`
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Store state under a project-local live directory, separate from `.impeccable-live.json` but discoverable from the same project root.
|
|
|
|
|
- Write append-only JSONL events per session and a compact JSON snapshot per session. The JSONL journal is authoritative; snapshots are derived and must be rebuildable when missing, stale, or contradictory.
|
|
|
|
|
- Include session id, event sequence, event type, phase, source file when known, visible variant, param values, timestamps, delivery lease/ack metadata, checkpoint revision, generated-file fallback mode, and annotation artifact paths.
|
|
|
|
|
- Persist annotation screenshot assets for incomplete sessions when generate events include annotations; status should report missing artifacts as diagnostics.
|
|
|
|
|
- Keep the module dependency-free and synchronous or simple async Node filesystem code consistent with current scripts.
|
|
|
|
|
- Route browser checkpoints through `/events` as a first-class `checkpoint` event type, with monotonic client revision and session owner metadata.
|
|
|
|
|
- Wire new non-E2E tests into the default test script, because `package.json` enumerates test files explicitly rather than globbing all `tests/*.test.mjs`.
|
|
|
|
|
- Treat malformed journal entries as recoverable diagnostics rather than crashing the helper server when possible.
|
|
|
|
|
|
|
|
|
|
**Execution note:** Start test-first for the storage module because it is the new source of truth.
|
|
|
|
|
|
|
|
|
|
**Technical design:** Directional event shape:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
SessionSnapshot = {
|
|
|
|
|
id,
|
|
|
|
|
phase,
|
|
|
|
|
pageUrl,
|
|
|
|
|
sourceFile,
|
|
|
|
|
expectedVariants,
|
|
|
|
|
arrivedVariants,
|
|
|
|
|
visibleVariant,
|
|
|
|
|
paramValues,
|
|
|
|
|
pendingEventSeq,
|
|
|
|
|
deliveryLease,
|
|
|
|
|
checkpointRevision,
|
|
|
|
|
activeOwner,
|
|
|
|
|
sourceMarkers,
|
|
|
|
|
fallbackMode,
|
|
|
|
|
annotationArtifacts,
|
|
|
|
|
diagnostics,
|
|
|
|
|
updatedAt
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- `skill/scripts/live-server.mjs` for project-root PID file handling.
|
|
|
|
|
- `tests/live-server.test.mjs` for temp-directory test isolation.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Happy path: appending `generate`, `variants_ready`, and `accept_intent` events for one session yields a snapshot with the latest phase and selected variant.
|
|
|
|
|
- Happy path: reading active sessions after constructing a new store instance returns the session written by the previous store instance.
|
|
|
|
|
- Edge case: duplicate event id or sequence is idempotent and does not append conflicting state twice.
|
|
|
|
|
- Edge case: a completed session remains readable for audit but is not returned as the active session by default.
|
|
|
|
|
- Edge case: journal and snapshot disagree after a simulated crash; status rebuilds the snapshot from the journal and records a repair diagnostic.
|
|
|
|
|
- Edge case: annotated generate event keeps its screenshot artifact available until the session completes.
|
|
|
|
|
- Error path: corrupted JSONL line is reported in diagnostics while valid prior events still reconstruct the snapshot.
|
|
|
|
|
- Error path: storage directory creation failure returns a structured error to the caller.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- Durable state survives module re-instantiation and can answer “what is the active session and next action?” without browser or server memory.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U2. **Journal browser events and enforce session transitions**
|
|
|
|
|
|
|
|
|
|
**Goal:** Make `/events` persist generate/accept/discard and checkpoint events before they are exposed to agent polling.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R1, R3, R5, R7, R8
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U1
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Modify: `skill/scripts/live-server.mjs`
|
|
|
|
|
- Modify: `tests/live-server.test.mjs`
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- On `POST /events`, validate generate/accept/discard/checkpoint events, assign or validate a durable event sequence, append to the session journal, then enqueue actionable events for polling. Checkpoints update durable state but do not necessarily create agent work.
|
|
|
|
|
- Add a server-side session state machine that accepts valid transitions and treats duplicate valid events idempotently.
|
|
|
|
|
- Add an at-least-once poll delivery model: pending events are leased to a poll response, redelivered after lease expiry, and marked complete only when the agent posts a matching result.
|
|
|
|
|
- Keep `exit` as lower priority than real session events so queued generate/accept/discard work is not masked by tab disconnect.
|
|
|
|
|
- Preserve current token validation and in-memory fast path, but make disk the replayable source.
|
|
|
|
|
- On server startup, rebuild pending work from the journal into the in-memory queue. `/poll` may consult the store when memory is empty, but the journal remains canonical.
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- Existing `validateEvent()` and `enqueueEvent()` in `skill/scripts/live-server.mjs`.
|
|
|
|
|
- Existing `/events` and `/poll` tests in `tests/live-server.test.mjs`.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Happy path: `POST /events` for generate persists an event before a poll consumes it.
|
|
|
|
|
- Happy path: if the server object is recreated with the same project store, `/poll` returns the previously unconsumed generate event.
|
|
|
|
|
- Edge case: duplicate accept for the same session and variant returns the same durable state without creating conflicting queue entries.
|
|
|
|
|
- Edge case: discard after accept-pending is rejected or ignored according to the state machine and returns a diagnostic response.
|
|
|
|
|
- Error path: invalid transition returns a clear JSON error and does not append to the journal.
|
|
|
|
|
- Integration: queued real events are delivered before synthetic `exit` events.
|
|
|
|
|
- Integration: event delivered to a poll but never acked is redelivered after lease timeout and remains idempotent when eventually completed.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- Browser events are not lost by an idle agent or helper server restart as long as the project-local journal remains.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U3. **Add browser checkpoints and acknowledged accept/discard**
|
|
|
|
|
|
|
|
|
|
**Goal:** Have the browser record current live state durably and stop clearing recoverable local state until the server acknowledges the state change.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R1, R2, R3, R4, R5
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U1, U2
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Modify: `skill/scripts/live-browser.js`
|
|
|
|
|
- Modify: `tests/live-e2e.test.mjs`
|
|
|
|
|
- Create: `tests/live-browser-recovery.test.mjs`
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Add a browser checkpoint helper that sends current session state to `/events` as `type: "checkpoint"` whenever variant, parameter values, phase, or selected source file context changes.
|
|
|
|
|
- Include monotonic client revisions and an active-session owner/epoch so stale checkpoints from old tabs cannot regress a newer accepted/discarded phase.
|
|
|
|
|
- Change accept/discard from fire-and-forget to acknowledged durable receipt before `markSessionHandled()` and before local session cleanup. Agent completion remains a later state.
|
|
|
|
|
- Keep a local pending state if acknowledgement fails, with a visible “waiting for agent/server” or “reconnect to recover” state instead of silently resetting.
|
|
|
|
|
- Preserve existing `localStorage` resume as a UI fast path, but do not let its single handled key suppress recovery when source markers or durable server state indicate pending work.
|
|
|
|
|
- Capture current parameter values on every change, not only at accept time, so resume can reconstruct user tuning even before Accept.
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- Existing `saveSession()`, `resumeSession()`, `paramsCurrentValues`, and `handleAccept()` in `skill/scripts/live-browser.js`.
|
|
|
|
|
- Existing scroll restoration and MutationObserver recovery patterns in `skill/scripts/live-browser.js`.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Happy path: moving a parameter slider sends a checkpoint with updated param values and does not reset the tune panel.
|
|
|
|
|
- Happy path: clicking Accept receives server acknowledgement, then transitions the browser to confirmed/pending-agent state.
|
|
|
|
|
- Edge case: Accept POST fails due to server down; browser keeps session recoverable and shows a reconnect/retry state.
|
|
|
|
|
- Edge case: page reload after accept acknowledgement but before agent completion resumes as pending cleanup rather than picking mode.
|
|
|
|
|
- Edge case: local handled flag exists but source wrapper still exists; browser resumes or reports pending cleanup instead of hiding the session.
|
|
|
|
|
- Edge case: stale checkpoint from a background tab arrives after accept-pending; server rejects it or records it as stale without changing snapshot phase.
|
|
|
|
|
- Integration: after HMR inserts variants, browser checkpoint records arrived variant count and visible variant.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- The browser never becomes the only place where selected variant and tune values exist.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U4. **Expose agent status and resume commands**
|
|
|
|
|
|
|
|
|
|
**Goal:** Give agents a stable CLI/API to inspect and continue live state without manually reading raw journal files or source markers.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R2, R4, R6, R7
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U1, U2
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Create: `skill/scripts/live-status.mjs`
|
|
|
|
|
- Create: `skill/scripts/live-resume.mjs`
|
|
|
|
|
- Create: `skill/scripts/live-complete.mjs`
|
|
|
|
|
- Modify: `skill/scripts/live-server.mjs`
|
|
|
|
|
- Modify: `skill/reference/live.md`
|
|
|
|
|
- Modify: `tests/live-server.test.mjs`
|
|
|
|
|
- Create: `tests/live-status.test.mjs`
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Add a status endpoint or direct store reader that returns active session snapshots, pending events, source marker status, and recommended next action.
|
|
|
|
|
- Add `live-status.mjs` for human/agent-readable JSON status.
|
|
|
|
|
- Add `live-resume.mjs` if the status command should also requeue pending events or print a normalized next event for the agent.
|
|
|
|
|
- Include source-marker scanning for `impeccable-variants-start`, `impeccable-carbonize-start`, and `impeccable-param-values` so source truth can repair journal/browser drift. The scan domain should include resolved live config targets, journal-known files, and existing source roots used by marker helpers; generated/served files covered by live config must be diagnosable.
|
|
|
|
|
- Consult the generated-file guard before recommending deterministic `live-accept`; generated/served-file fallback sessions should return `persist_fallback_to_true_source`.
|
|
|
|
|
- Distinguish generate recovery phases: pending event only, wrapper/original-only source, variants partially/fully written, and browser not yet confirmed cycling.
|
|
|
|
|
- Keep output JSON stable and agent-readable: explicit `nextAction`, `reason`, `file`, `sessionId`, `paramValues`, `lease`, and `diagnostics` fields.
|
|
|
|
|
- After completion acknowledgement, completed sessions return `no_active_session` by default unless an include-completed flag is requested.
|
|
|
|
|
|
|
|
|
|
**Technical design:** Directional `nextAction` values:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
poll_for_pending_event
|
|
|
|
|
write_variants
|
|
|
|
|
continue_writing_variants
|
|
|
|
|
run_accept_cleanup
|
|
|
|
|
run_carbonize_cleanup
|
|
|
|
|
acknowledge_completion
|
|
|
|
|
persist_fallback_to_true_source
|
|
|
|
|
restore_discard
|
|
|
|
|
ask_user_to_reopen_browser
|
|
|
|
|
no_active_session
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- `skill/scripts/live-poll.mjs` for CLI JSON output style.
|
|
|
|
|
- `skill/scripts/live-accept.mjs` marker parsing helpers where reusable.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Happy path: status with a pending accept event returns `run_accept_cleanup` and includes variant id and param values.
|
|
|
|
|
- Happy path: status with carbonize markers in source returns `run_carbonize_cleanup` even if no browser is connected.
|
|
|
|
|
- Edge case: status with no active journal but source variant markers returns a recoverable source-marker session.
|
|
|
|
|
- Edge case: status with stale completed sessions returns `no_active_session` by default and can include completed sessions only when requested.
|
|
|
|
|
- Edge case: source markers exist in a generated/served file covered by live config; status recommends fallback true-source persistence rather than deterministic accept.
|
|
|
|
|
- Edge case: wrapper exists with only original content; status recommends continuing variant writing rather than accept cleanup.
|
|
|
|
|
- Error path: missing or unreadable source file appears as a structured diagnostic, not an unhandled exception.
|
|
|
|
|
- Integration: `live-resume.mjs` can requeue or emit the pending event after a helper server restart.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- A fresh agent can run one command and know exactly what happened in live mode and what to do next.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U5. **Make poll/accept acknowledge durable completion**
|
|
|
|
|
|
|
|
|
|
**Goal:** Ensure agent-side handling updates durable session state after source writes and carbonize cleanup so browser and future agents know whether the session is complete.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R2, R5, R6
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U1, U2, U4
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Modify: `skill/scripts/live-poll.mjs`
|
|
|
|
|
- Modify: `skill/scripts/live-accept.mjs`
|
|
|
|
|
- Modify: `skill/scripts/live-server.mjs`
|
|
|
|
|
- Modify: `tests/live-accept.test.mjs`
|
|
|
|
|
- Modify: `tests/live-server.test.mjs`
|
|
|
|
|
- Create: `tests/live-poll.test.mjs`
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Have `live-poll.mjs` report auto-accept/discard results back to the server/session store, not only print `_acceptResult` to stdout.
|
|
|
|
|
- Complete the delivery lease only after this result is durably recorded; failed source writes should release or mark the lease recoverable with diagnostics.
|
|
|
|
|
- Represent `carbonize: true` as `accepted_source_pending` until cleanup is confirmed.
|
|
|
|
|
- Add `live-complete.mjs` as the canonical completion acknowledgement path after carbonize cleanup. `live-status.mjs` reports that completion is needed; `live-resume.mjs` helps recover pending work; only `live-complete.mjs` marks carbonize cleanup complete.
|
|
|
|
|
- Reconcile lost completion acknowledgements from source truth: if carbonize markers are gone and accepted content is materialized, status can idempotently record a synthetic completion event.
|
|
|
|
|
- Make duplicate completion acknowledgements idempotent.
|
|
|
|
|
- Preserve the stderr warning as a human attention signal, but do not rely on warning text as the state machine.
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- Current `_acceptResult` attachment in `skill/scripts/live-poll.mjs`.
|
|
|
|
|
- Current carbonize marker output in `skill/scripts/live-accept.mjs`.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Happy path: accept event processed by `live-poll.mjs` updates durable session to `accepted_source_pending` when carbonize is required.
|
|
|
|
|
- Happy path: discard event processed by `live-poll.mjs` updates durable session to complete.
|
|
|
|
|
- Happy path: a `live-poll.mjs` CLI/integration test processes an accept event and records the durable lease/result acknowledgement through the real poll script path.
|
|
|
|
|
- Edge case: running accept twice for the same event returns the same final durable phase without rewriting source twice.
|
|
|
|
|
- Error path: `live-accept.mjs` failure records an agent error in the session journal and leaves next action recoverable.
|
|
|
|
|
- Integration: browser reload after agent accept but before carbonize can be diagnosed by `live-status.mjs`.
|
|
|
|
|
- Integration: completion acknowledgement is lost after source cleanup; status detects the condition and recommends `acknowledge_completion`, then `live-complete.mjs` resolves the session complete.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- Durable state reflects what happened to source, not only what browser requested.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U6. **Update live-mode guidance and recovery UX**
|
|
|
|
|
|
|
|
|
|
**Goal:** Teach both agents and users the new recovery contract and make recovery visible in live mode.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R2, R4, R6, R7
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U3, U4, U5
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Modify: `skill/reference/live.md`
|
|
|
|
|
- Modify: `docs/adr-live-variant-mode.md`
|
|
|
|
|
- Modify: `skill/scripts/live-browser.js`
|
|
|
|
|
- Modify: `README.md` if live command usage is documented there
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Update `reference/live.md` to start with a status check when resuming a session or when the agent suspects it missed events.
|
|
|
|
|
- Document the durable journal and session states in the ADR.
|
|
|
|
|
- Add concise browser states for pending accept, reconnect/recover, and agent cleanup pending.
|
|
|
|
|
- Keep chat overhead low: the agent should use status JSON instead of asking the user to describe browser state.
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- Existing `reference/live.md` contract sections for poll loop, accept, carbonize, and cleanup.
|
|
|
|
|
- Existing toast and bar state patterns in `skill/scripts/live-browser.js`.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Test expectation: mostly documentation and UX copy. Behavioral coverage belongs to U3-U5; this unit should be verified through review plus any snapshot/E2E assertions added for visible pending states.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- A new agent reading `reference/live.md` knows to recover state before making assumptions after interruption.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- U7. **Add restart and interruption E2E coverage**
|
|
|
|
|
|
|
|
|
|
**Goal:** Prove the durable recovery contract in realistic browser/server/agent flows.
|
|
|
|
|
|
|
|
|
|
**Requirements:** R1, R2, R3, R4, R5, R6
|
|
|
|
|
|
|
|
|
|
**Dependencies:** U1, U2, U3, U4, U5
|
|
|
|
|
|
|
|
|
|
**Files:**
|
|
|
|
|
- Modify: `tests/live-e2e.test.mjs`
|
|
|
|
|
- Modify: `tests/framework-fixtures/README.md` if new fixture expectations are needed
|
|
|
|
|
- Modify: `tests/live-e2e/agent.mjs` if deterministic agent hooks need to simulate interruption
|
|
|
|
|
|
|
|
|
|
**Approach:**
|
|
|
|
|
- Add focused E2E cases for missed polling, helper server restart, browser reload, accept before agent resumes, and carbonize-pending status.
|
|
|
|
|
- Prefer one or two compact fixtures over broad matrix explosion.
|
|
|
|
|
- Keep deterministic fake agent path as the primary verification route; LLM agent remains opt-in.
|
|
|
|
|
|
|
|
|
|
**Patterns to follow:**
|
|
|
|
|
- Existing live-mode E2E setup in `tests/live-e2e.test.mjs`.
|
|
|
|
|
- Fixture authoring guidance in `tests/framework-fixtures/README.md`.
|
|
|
|
|
|
|
|
|
|
**Test scenarios:**
|
|
|
|
|
- Integration: user clicks Go while no poll is active; later poll receives durable generate event and completes variants.
|
|
|
|
|
- Integration: user changes Tune values, reloads browser, and status/resume reports the same values.
|
|
|
|
|
- Integration: user clicks Accept, agent is interrupted, new agent runs status and sees `run_accept_cleanup` with variant id and params.
|
|
|
|
|
- Integration: helper server restarts after queued generate; resumed server can still surface the pending event.
|
|
|
|
|
- Integration: agent receives a poll event through the real `live-poll.mjs` path and then crashes before posting result; a resumed poll redelivers the leased event after timeout.
|
|
|
|
|
- Integration: source contains carbonize markers; status returns cleanup pending even without an active browser tab.
|
|
|
|
|
- Integration: out-of-order checkpoint after accept does not regress pending accept state.
|
|
|
|
|
- Error path: duplicate accept and late discard do not corrupt final source.
|
|
|
|
|
|
|
|
|
|
**Verification:**
|
|
|
|
|
- E2E coverage demonstrates recovery from the exact “agent was not listening” failure mode.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## System-Wide Impact
|
|
|
|
|
|
|
|
|
|
- **Interaction graph:** Browser `live-browser.js` posts events/checkpoints to `live-server.mjs`; server persists them through `live-session-store.mjs`; agent observes them through `live-poll.mjs`, `live-status.mjs`, or `live-resume.mjs`; source mutations still happen through `live-wrap.mjs` and `live-accept.mjs`.
|
|
|
|
|
- **Error propagation:** Failed event persistence must be visible to the browser before it clears state. Failed source cleanup must be visible in status output and kept recoverable.
|
|
|
|
|
- **State lifecycle risks:** The key risk is split-brain among browser localStorage, server journal, in-memory queue, snapshots, and source markers. The plan makes source markers plus durable journal canonical, snapshots rebuildable, in-memory queues cache-only, and browser localStorage only an optimization.
|
|
|
|
|
- **API surface parity:** The new status/resume scripts become agent-facing APIs and should be reflected in `reference/live.md` and tests.
|
|
|
|
|
- **Integration coverage:** Unit tests alone will not prove recovery. E2E must cover browser reload, server restart, missed poll, duplicate events, and carbonize pending states.
|
|
|
|
|
- **Unchanged invariants:** Live mode remains source-first, self-contained, zero-dependency, token-protected, and transport-compatible with current AI harnesses.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Risks & Dependencies
|
|
|
|
|
|
|
|
|
|
| Risk | Mitigation |
|
|
|
|
|
|------|------------|
|
|
|
|
|
| Durable journal becomes another state source that can drift | Make source markers plus journal reconciliation explicit in `live-status.mjs`; keep browser localStorage advisory. |
|
|
|
|
|
| Event replay causes duplicate source rewrites | Add idempotency keys, state-machine validation, leased delivery, and tests for duplicate accept/discard. |
|
|
|
|
|
| Browser waits forever after accept if agent is absent | Show explicit pending/reconnect state and provide status/resume command for the agent. |
|
|
|
|
|
| Poll delivery is mistaken for completion | Model leased delivery separately from completion acknowledgement and redeliver expired leases. |
|
|
|
|
|
| Snapshot contradicts journal after crash | Treat journal as canonical and rebuild/repair snapshots on startup/status reads. |
|
|
|
|
|
| Annotated screenshot path goes stale before recovery | Store annotation artifacts with the incomplete session and retain them until completion cleanup. |
|
|
|
|
|
| Disk writes fail in restricted environments | Return structured server errors and do not clear browser state until persistence succeeds. |
|
|
|
|
|
| Tests become slow or brittle | Keep most coverage in store/server tests and add only targeted E2E cases for true cross-process recovery. |
|
|
|
|
|
| Backward compatibility with existing installed skill output drifts | Update source skill files first, then run the project build to regenerate provider outputs in a separate execution phase. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Documentation / Operational Notes
|
|
|
|
|
|
|
|
|
|
- Update `docs/adr-live-variant-mode.md` because durability changes the architecture from memory queue plus localStorage to journaled sessions.
|
|
|
|
|
- Update `skill/reference/live.md` so agents know to run status/resume after interruption or before assuming no pending work.
|
|
|
|
|
- If generated provider skill outputs are tracked, implementation should regenerate them with the existing build process after changing `skill/`.
|
|
|
|
|
- Because the default test script enumerates test files, implementation must update `package.json` when adding new non-E2E test files.
|
|
|
|
|
- Consider adding `.impeccable-live/` or the chosen session-store directory to gitignore if it is not already ignored.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Sources & References
|
|
|
|
|
|
|
|
|
|
- Related architecture: `docs/adr-live-variant-mode.md`
|
|
|
|
|
- Live instructions: `skill/reference/live.md`
|
|
|
|
|
- Browser live implementation: `skill/scripts/live-browser.js`
|
|
|
|
|
- Server transport: `skill/scripts/live-server.mjs`
|
|
|
|
|
- Agent poll client: `skill/scripts/live-poll.mjs`
|
|
|
|
|
- Accept/discard source cleanup: `skill/scripts/live-accept.mjs`
|
|
|
|
|
- Live-mode tests: `tests/live-server.test.mjs`, `tests/live-accept.test.mjs`, `tests/live-e2e.test.mjs`
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Surgical Overhaul Follow-Ups (2026-04-29)
|
|
|
|
|
|
|
|
|
|
- Dependency audit is now Bun-native via `bun run audit`, but the gate currently fails on transitive advisories:
|
|
|
|
|
- `archiver -> archiver-utils -> lodash` and `brace-expansion`
|
|
|
|
|
- optional `puppeteer -> @puppeteer/browsers -> basic-ftp`
|
|
|
|
|
- Decision: keep the audit script honest and failing instead of adding ignores before exploitability and replacement cost are reviewed.
|
|
|
|
|
- Recommended next dependency work: evaluate whether release ZIP creation still needs `archiver`, and whether optional Puppeteer screenshot tooling can be replaced, isolated, or upgraded without bloating install size.
|
Paul Bakaus