Skip to content
Dr K edited this page Nov 14, 2026 · 3 revisions

Ledger

This file is the history of selenium-flow, oldest first: what each round did, when, and what of it still matters. Each dated design in this folder holds the reasoning and the rulings of one round. The living spec in specs holds what is true now. This file holds what the two leave out: the order of events, the pull requests, the decisions taken while building, and which round overtook which.

The implementation plans (the step-by-step task lists written before each build) and the four saga chapters in docs/saga/ are not kept, except the docs round's and the refactor round's plans, which carry a History header. The rest are in git history. To read one, check out the docs repository at commit 2ae3705 or earlier, for example git -C docs show 2ae3705:saga/Chapter_1_The_Flight_Plan.md. A plan has the same name as its design without -design.

Pull request numbers are #n, and where a round has an issue the entry says so. A number is left out where the match was not certain. Several entries name a spec requirement id such as SURF-37; the id is in the area file named beside it.

2026-09-10 The first release

Pull requests #1 to #8, merged 2026-09-10. There is no design or plan for these.

  • Shipped: a CI flow with static analysis, audits and a package step (#1); tests that run on Python 3.10 after the matrix showed they never had (#3); a quality pass over code, tests and lint (#4); the first release (#5, #7); and HTTP failures classified by what the caller should do (#8, now SURF-40 to SURF-42 in surfaces).
  • Chapter 1 of the saga opened with #9 the same day. The next entry is that chapter.

2026-09-10 Saga, chapter 1: saved flows

Pull requests #9 to #15 and #20 to #23, merged 2026-09-10 to 2026-09-12. The chapter closed on 2026-09-12 as v0.1.0. Chapter 1 was written as a design first and kept its reasoning after the build; the epics E0 to E11 below are its plan.

Problem: every browser step cost the model one inference, and a twelve-step task cost twelve. The saving from a saved flow is the inferences. It is not the round trips: Grid.reconnect does not talk to the Grid, so batching saves no network (§F1.1).

Decided and still standing:

  • A flow is a document of steps. Each step names its tool and nests the tool's arguments, a discriminated union derived from the tool schemas, so a step's own keys cannot collide with a tool's arguments (§F1.6). Held by saved-flows.
  • Parameters are a JSON Schema object (§F1.7). Dr K withdrew the {{name}} form on 2026-09-11. On 2026-09-12 a parameter became text, written ${name} into any argument, and a secret stayed structural: two mechanisms where there had been one (§F1.38).
  • Flows are stored per name as <flow>.yaml, served as JSON and edited as YAML (§F1.14). Names are validated and never sanitised: a bad name is a 400 (§F1.4, FLOW-13 onward).
  • An unnamed caller gets a reserved library called global, and a named caller sees its own library and global. Dr K overruled the first draft, which refused unnamed callers (§F1.2). The shared library became read-only to every agent in #17.
  • Reads are resources and writes are tools, with a mirror tool for clients that read no resources (§F1.5).
  • open_session and end_browser are not steps, so one flow runs unedited on Chrome and Firefox (§F1.9).
  • The codebase sees one directory, and the installer decides what is behind it (§F1.12). That is data.dir in config.
  • A flow declares where it applies, and the page the browser is on decides what is shown (§F1.33 to §F1.35). Built in the 2026-11-12 sites and paths round.
  • The worst defect of the chapter did not raise: after a login flow, Chrome's save-password offer took the input focus, and every later click and keystroke went to the offer while the tools reported success (§F1.37). The fix is browser prefs that remove every prompt, under the rule that nobody is there to answer a browser prompt. Held by SET-28 in session-settings, which lists the prefs sent.
  • Findings by flying it against the live Grid, not by tests: the password offer, a screenshot that did not report its file name, an admin panel that did not repaint its flows, and a file count that disagreed with the grid (§F1.39).
  • The image build went from 9.5 minutes to 2. The runner installed dependencies twice, and cache-to: type=gha had never worked because buildx runs from a shell step that gets no ACTIONS_RUNTIME_TOKEN (§F1.41, #22).
  • ROUTE_PREFIX became the mount point of the whole server and /browser stopped moving (§F1.11, E5), built in #35. /openapi.yaml sits under the mount and the probes answer at the root and under it. See surfaces and config.

Built differently from the plan: E5 was planned to keep /health and /openapi.* at the root and ended with the probes in both places and the schema under the mount. The chapter closed with E5 outstanding on purpose, because the version is the seam and the rollout is not.

Overtaken: a step's arguments are args (§F1.6 named them params), and a step has no timeout, which is the flow's; the structural valueFrom reference of §F1.7 gave way to ${name} (§F1.38); one file list with a kept flag that keep_file flipped (§F1.10) became the Hangar's sections; the urls field of §F1.33 became sites and paths; sessions became workspaces and the X-Session-Key header became Sf-Workspace; the flow://here resource and GET /flows?url= were never built.

Not carried forward and still unbuilt: secrets from Kubernetes (E8, §F1.20 and §F1.21, a source that needs no dependency), a step reading another step's output, and control flow. The chapter's answer to the last two is that n8n composes.

2026-09-11 Saga, chapter 1: secrets

Pull requests #13 (catalogue, "three leaks the last round missed"), #14 (binding), #15 (the skill that teaches flows and secrets). The doctrine is §F1.17 to §F1.32 and the epics E7 and E9.

Decided and still standing:

  • The credential never enters the conversation (§F1.17). No tool, debug flag or admin endpoint returns a value (§F1.24). The honest limit is in the same section: once a secret is typed into a page, execute_script can read it back. Held by secrets-and-scope.
  • A secret is a directory of files: the directory name is the secret, each file is a key (§F1.18). Filesystem metadata rides in reserved keys beginning with _ (§F1.19). The same code reads a Kubernetes mount and a folder made by hand.
  • The catalogue (names, keys, description, allowed URLs) is cached with a short TTL. A value is never cached: it is read when bound and dropped (§F1.23).
  • Allowed URLs are enforced, matched by origin and never by substring (§F1.27).
  • Only write binds a secret. execute_script would be an exfiltration API, navigate would put the value in history and referrers (§F1.28). A binding names the secret and the key as two fields, because Kubernetes key names contain dots (§F1.26).
  • The surfaces are one resource, one mirror tool and GET /secrets (§F1.31). The use of a secret is audited and the value is not (§F1.30).

Built differently: write first returned what it typed and that leak was closed before the binding landed (§F1.25, #13).

Overtaken: the 2026-11-14 secret scope round made allowed URLs a required leash and scrubbed values from every result; see that entry. The mirror tool is the generic read_resource (chapter 3).

Not built: Kubernetes secrets scoped to a session by label (§F1.22), which needed the Kubernetes source of the previous entry. Filesystem secrets are global.

2026-09-12 Saga, chapter 1: the admin UI, kept files and the wiki

Pull requests #16 (kept files), #18 (the admin page, built from its Penpot design), #19 (the wiki), #21 and #22 (flows go live, a flow shows what it takes).

Decided and still standing:

  • Kept files outlive the browser that made them (E4, #16). A file is kept by name with keep_file.
  • The admin UI was designed in Penpot on 2026-09-11 and redrawn on 2026-09-12 (§F1.36, §F1.40). The rule from that day: the design follows the app, except where Dr K decides otherwise. The flows panel is three columns, and status is not an action.
  • Rationale moves to the design record and AGENTS.md keeps rules (§F1.15), and the skill gets references/FLOWS.md (§F1.16).

Held by admin-ui and saved-flows.

2026-09-14 Saga, chapter 2: pilot reports

Pull requests #25 to #31 on 2026-09-14 and 2026-09-15, then #32 to #38, released as v0.2.0 on 2026-09-16. The chapter opened on 2026-09-14 from one agent's report after four hours of flying v0.1.0 against a single-page app. It lists what to keep and what cost time.

Decided and still standing:

  • A closed set of values is a Literal in the tool schema, so the client sees an enum (§F2.1). press_key stays free text. The tools show their choices (#25).
  • execute_script points back at cheaper tools before it accepts the job (§F2.2).
  • The server remembers the pointer. A move jumps unless glide is asked for, and drag is its own tool and glides by default (§F2.3, §F2.4, #31). Firefox interpolates a pointer drag and Chrome makes a real HTML5 drag (§F2.11). Held by browser-actions.
  • assert is JavaScript that must come back true (§F2.5, #26). A flow has no when: Dr K held the line against branching, because a flow that copes with the wrong page passes on it (§F2.6). A step's report names its URL when it differs from the step before (§F2.7).
  • One probe answers whether an element can be used, read by the error and by outline. outline is a discovery tool for the agent that builds a flow and is never a step (§F2.8, #29).
  • Screenshots save by default and no other file changes (§F2.9, #28).
  • One session, always named by the caller, with no ids in the contract (§F2.12). The HTTP surface is REST, with paths declared per capability in a route table and the session set by header (§F2.13, #34, #35). xpath and css became one selector (§F2.14).
  • A long run reports progress and can be cancelled, and a flow sets its own budget. A client had aborted at 300 seconds a flow that had succeeded (§F2.15, #37). No status tools were added.
  • A refused call names the shape it wanted, and outline puts content first (§F2.16, #38).

Overtaken: session names became workspace names (2026-10-09). X-Session-Key and ?session= are now ignored (2026-10-29). The two-header 400 of §F2.13 went with them.

Not built: a flow used as a contract in FLOWS.md, a kept file exercised from the admin UI, and a drag flown against a sortable list on a real site. The admin UI's items (E17) moved to a later round.

2026-09-16 The package refit

Design: package restructure. Pull request #36, merged 2026-09-16.

  • Shipped: 29 flat modules became packages (core/, session/, flows/, http/, mcp/, spec/) with the app on top, four request wrappers became one http.answer, and the 1,443-line openapi.py became schema data and a builder. The regenerated OpenAPI document was byte-identical to the one main produced.
  • Built: three faults that no test saw, each then guarded. A data directory must be packaged beside the module that reads it. A relative import must resolve (a .core inside session/ had silently stopped the status reporting in_frame). errors.message strips credentials on every path. The design's tree put js/ inside core/, and that is only safe because the package-dir key moves with it.
  • Overtaken: session/ is workspace/; http/mount.py was never built; GET /secrets builds its own response (SURF-37). The refactor round planned for 2026-11-14 is the next time that shared wrapper is looked at.
  • Held by: surfaces (SURF-2, SURF-7, SURF-36 to SURF-42).

2026-09-16 Saga, chapter 3: other aircraft

Pull requests #39 and #40, merged 2026-09-16 and 2026-09-17. Built in one pull request on the day it was planned.

Problem: Dr K flew selenium-flow from VS Code Copilot, which treats resources as the user's and not the model's.

Decided and still standing:

  • The resources default is decided by who is calling. ?resources= or X-MCP-Resources wins, then a table of known clients (Visual Studio Code does not read resources), then the assumption that an unknown client does (§F3.1). Held by surfaces.
  • The instructions point each client at what it can read (§F3.2). Every stale tool description was hunted and a test guards the next one (§F3.3). Resources have human names and templates have completions (§F3.4). Tool descriptions are trimmed to what a model needs to call the tool (§F3.5).
  • Two generic mirrors, list_resources() and read_resource(uri), replaced seven specific ones, in the vocabulary mcp-kb uses (§F3.6). FastMCP's ResourcesAsTools was driven over HTTP by two callers before it was chosen.
  • No backward compatibility while one person uses the server (§F3.7). This took --stateless with it and still governs: old shapes are purged, never migrated.
  • n8n reaches resources through mcp-kb, and not through this server.
  • The live check of #39 found saved files going missing (a PDF from a plain-http page was held as an insecure download), and two other faults. All were built in #40, which replaced save_pdf with print (§F3.8).

2026-09-24 The Hangar

Pull request #41, merged 2026-09-25. Plan and rulings were written in chapter 4 of the saga; there is no separate design file.

  • Shipped: a workspace's files split into Downloads, Screenshots and Files, in storage, in the MCP surface, in the admin API and on the admin page. Files and Flows are tabs. A lightbox steps through a row. A Secrets tab lists each secret with the flows that use it, and never a value.
  • Decided: three sections and no delete-all (§F4.1), the third section is Files (§F4.2), newest first (§F4.3), session://files is a folder and the sections are paths (§F4.6, now workspace://files). Screenshots are stored in screenshots/ beside files/, keep_file takes a file's URI and moves a screenshot or copies a download, and no agent tool clears or deletes anything (§F4.7).
  • A Redis that is configured and unusable stops the boot (§F4.12). On 21 September the pod had started while Redis refused connections and kept every record in memory for three days.
  • Built, and not in the saga's rulings: the admin's keep never opens a browser; a screenshot keep moves the file or changes nothing; keep_file is marked destructive; the lightbox ignores keys while a confirm is open above it; a name a flow uses that no secret answers to is shown even if a hand edit made it a ${...} reference. The whole-branch review found the new integration flow could never pass, because the plan's stable_for is in seconds and was written in milliseconds. Hand-tracing found a lightbox that closed the next viewer, and a confirm that listed one session's files and deleted another's.
  • Overtaken: the Files section's kept flag, the session:// spellings (now workspace://files), and the Secrets tab's used-by rows.
  • Held by: workspace-files (FILE-2 to FILE-44), admin-ui, surfaces.

2026-09-25 The admin UI on Svelte

Design: svelte admin UI. Pull request #42, merged 2026-09-25; the libyaml fix is #45 (2026-09-26); dependency updates #43 and #44.

  • Shipped: the admin page rebuilt as Svelte 5 components under ui/, built by Vite into one script and one stylesheet that the server inlines. The npm build is separate and its output is never committed (§F4.15, UI-2 to UI-4). A source install is a whole server: with no UI build the admin URL answers a page that says Selenium Flow and the MCP App is not offered (§F4.17, UI-6, UI-13, UI-14).
  • Built: a traceability table mapped 120 page-grepping tests before the page moved. 93 were mapped to component or visual tests and 27 retired because they pinned the old page's source. The table found two spec gaps, Files with no clear action and a Flows tab with no accordion. build/ cannot be the build output, because setuptools prunes it from the sdist and python -m build fails. A shell comment swallowed its own __CSS__ placeholders and blanked the page, so page() strips shell comments before it substitutes. A {#each} key built from flow + session with no separator collided and left a pane on Loading forever; every keyed list was swept for it. A scoped @keyframes would put a class on every element, so the live badge's pulse lives in app.css. The MCP App's SDK is pinned at 2.0.0.
  • The Secrets tab loaded in 1.2 to 1.5 seconds. Reading 26 flow files took 15 ms and PyYAML's pure-Python parser took 1.1 s under a 500m CPU limit (§F4.19). #45 uses libyaml and caches parsed flows by content.
  • Overtaken: the list is WorkspacesView with a push from a shared task; the page is not a pure refactor any more; the Files tab has four sections.
  • Held by: admin-ui.

2026-09-26 Configuration

Design: configuration. Pull request #47, merged 2026-09-27.

  • Shipped: every setting can come from a YAML config file, the environment or arguments under one naming rule, with precedence default, config, env, args. The config file can declare secrets.entries. The admin UI has a read-only Settings tab. Boot stops with the reason when the file is wrong.
  • Built: Dr K renamed the layer file to config on 2026-09-26, and decided that the Settings tab shows values and does not explain them. A sensitive value is shown as dots when set.
  • Overtaken: session.store and session.ttl are workspace.store and workspace.ttl. The file is validated alone before the merge.
  • Held by: config (CFG-1 to CFG-61).

2026-09-30 Site data

Design: site data. Pull requests #49 (merged 2026-10-01), #50 (2026-10-01) and #51 (2026-10-02). #48 (2026-09-30) fixed screenshot links beforehand.

  • Shipped: save_site_data saves cookies, local storage and session storage as a snapshot, and a browser opened for the workspace has it back before its first page, so a session comes back signed in. Round 2 added a History tab and made one save cover every site the workspace visited.
  • Built: round 1 went to the live cluster and found bugs that round 1 shipped with, which #50 fixed. An insecure browser restores nothing. Round 2 changed the record: it gained history, one entry per origin newest first, and url became history[0].url. A record written before round 2 reads as one that has been nowhere. The plan states the rule that governs this: no backward compatibility, old shapes are purged, never migrated.
  • Overtaken: the session is the workspace; history also keeps a hash route (SITE-44); a silent reopen always says reopened.
  • Held by: site-data (SITE-2 to SITE-63).

2026-10-02 The optimal shape

Design: optimal shape. Pull requests #52 and #53, merged 2026-10-04.

  • Shipped: a feature freeze round. Every capability is one call through five owned stages (Caller, Capability, Recipe, Settle, Surface). Checking happens before the browser is touched. A per-workspace lock serialises calls. Navigation admits only http, https and about:blank. upload_file lost its path source. A secret cannot be typed into an element that hosts a frame. The admin page can be framed only by origins in security.frame_ancestors.
  • Built: the plan locked behaviour first with characterisation tests, goldens and a parity check, then moved pure rules into modules behind a boundary test. Golden files changed only in the commit for a shape change Dr K had ruled. Grid.timeout was deleted rather than wired to config. #53 fixed four rough edges found by the live test of this round.
  • Overtaken: core/actions.py has sixteen page actions, not fourteen; core/recipe.py still imports workspace.locks.
  • Held by: browser-actions (ACT-2 to ACT-42), workspaces-and-sessions, surfaces.

2026-10-04 OIDC groundwork

Design: OIDC groundwork. Pull request #54, merged 2026-10-04. #55 made X-Workspace name the session too.

  • Shipped: /mcp accepts a JWT from an OIDC issuer beside the server token and verifies signature, iss, aud, exp and role. The cluster's selenium-flow sits behind agentgateway.
  • Built: the plan left a principal that decides nothing yet, as a carrier for the next round. Dr K's rule that round: the cluster repository gets no commits from this work.
  • Overtaken: the admin UI, the admin API and the live list admit an admin-UI JWT (2026-10-09). The verifier also refuses a token with no numeric exp. Ownership and per-tool roles are still unbuilt (2026-11-14 ownership design).
  • Held by: auth-and-roles (AUTH-2 to AUTH-23).

2026-10-04 show(uri)

Design: show. Pull request #56, merged 2026-10-05.

  • Shipped: one MCP App tool, show(uri), draws a resource in the app shell. session_files is gone and the tool is listed by the client's own MCP Apps declaration.
  • Built: Dr K approved the pull request on 2026-10-04. The two session_files listing tests moved to test_show.py.
  • Overtaken: show draws every URI the server serves (next entries, 2026-10-09).
  • Held by: surfaces (SURF-26 to SURF-30), admin-ui.

2026-10-05 The skills extension

Design: skills extension. Pull request #57, merged 2026-10-05.

  • Shipped: a client that speaks the MCP Skills extension finds the embedded skill with skills/list and skills/get and verifies each file against the entry's digests. The server declares the extension and does so unconditionally.
  • Built: Dr K added the secrets view to the MCP App during the run: the value is never passed over the call, and the view is read-only like the admin UI.
  • Overtaken: the skill folder is plugin/skills/selenium-flow; the shared header parse is in mcp/frontmatter.py.
  • Held by: plugin (PLG-13 to PLG-22).

2026-10-08 Recordings

Design: recordings. Pull request #59, merged 2026-10-09.

  • Shipped: open_session(record=true) records the browser's life on the Grid. A bounded collector files the finished video into workspaces/<name>/recordings/, where it follows the screenshot lifecycle: ephemeral, cleared in bulk, kept into Files. The operator delivers the video to an inbox directory, recording.dir, under the new data root.
  • Built: the plan began with a spike on the live Grid and said to stop and tell Dr K if a measurement contradicted the spec (no Grid id in the file name, no mfro). Measured items were range requests, the compose mount and a media-only content policy for video.
  • Overtaken: a name ending .tmp is skipped as well as .partial and .part; smbfs polls.
  • Held by: workspace-files (FILE-45 to FILE-61).

2026-10-09 The workspaces programme

Design: workspaces and observability. The plan was a programme plan that sequenced six epics into issues and gates.

  • Shipped: E1 (rename), E2 (session monitor), E3 (capture), E5 (OIDC for the admin), E7 (show). E4 (telemetry, R12) and E6 (ownership and roles, R14) were never built.
  • Built: the plan's pre-flight made the agent, spec approved and plan approved labels, recorded that Copilot was out of credits and that a subagent holds the reviewer's seat, and had AGENTS.md call the saga deprecated, folded into E1 (#67).
  • Held by: workspaces-and-sessions, the glossary in Specification.

2026-10-09 Workspaces: the rename

Design: workspaces rename. Issue #60, pull request #67, merged 2026-10-09.

  • Shipped: what a caller names is a workspace, and a session is the browser open in it. The store, routes, URIs, config names and the data directory moved with the word.
  • Overtaken: the 400 for X-Session-Key and ?session= became silent ignoring (2026-10-29). The session:// refusal was narrowed by the session URIs round.
  • Held by: workspaces-and-sessions (WS-1 to WS-10, WS-17, WS-45, WS-46).

2026-10-09 The session monitor

Design: session monitor. Issue #61, pull request #68, merged 2026-10-09.

  • Shipped: one monitor and one event bus in the process. They know which sessions this server opened, which ended and why (ended, gone, lost), and which it still owes. The Grid's idle timeout is read at every open and shown on the workspace. The admin has an End action.
  • Built: the plan measured that a held BiDi socket survives its session's end and that its hub still answers a ping, so a socket is a channel and never a liveness signal. Liveness is one GET /status listing per tick, because a WebDriver command counts as activity and would stop the Grid reaping. Events carry no values.
  • Overtaken: the socket holder moved to bidi/; call.finished is emitted; "the Grid reaps" is the keep-alive (2026-11-14).
  • Held by: workspaces-and-sessions (WS-15 to WS-33).

2026-10-09 Admin OIDC

Design: admin OIDC. Pull request #69, merged 2026-10-09.

  • Shipped: a person whose issuer account holds an admin role signs in to the admin UI with Authorization Code and PKCE in the page, with no server callback. Tokens stay in memory. The server token stays as the admin login. opened_by records who opened a browser.
  • Not built: a script-src policy, RP-initiated logout, a backend-for-frontend, sign-in in a frame.
  • Held by: auth-and-roles (AUTH-15 to AUTH-47).

2026-10-09 show draws every resource

Design: show everything. Issue #63, pull request #70, merged 2026-10-10.

  • Shipped: show(uri) draws every URI form the server serves, with one view per resource URI and a guard that holds every URI to a view (SURF-44). A document's data is its text, JSON or a fenced block.
  • Overtaken: console, network and request later gained views, and session://downloads became its own scheme.
  • Held by: surfaces (SURF-26 to SURF-30, SURF-44).

2026-10-10 Console and network capture

Design: capture. Issue #64, pull request #72, merged 2026-10-10.

  • Shipped: open_session(capture=true) keeps what the page logs and fetches in a bounded buffer read by URI. A call that caused a page error says so. One body is fetched on demand. Everything streams to the admin page. Every BiDi conversation goes over one connection with a clean close. The floor is Python 3.11.
  • Built: the plan carries twenty rulings for where the design was silent. The ones that stand: network_body is POST /browser/network-body with {"id": "3.7"}, because every browser action is a POST. The intercept rule moved from never to only the spare tab of site data. Capture attaches after a site-data restore and before the first navigation. Capture.mark returns counters, so eviction cannot confuse it. A call that raises carries the hint as a note on the error. With capture on, the session's lock is held for the whole call. network_body is not a flow step, because a request id belongs to one page load. The capture cache holds 256 workspaces.
  • Overtaken: body fetch goes over a private channel; a header limit of 16,384 bytes a side replaced 32 headers of 4 kB.
  • Held by: capture (CAP-2 to CAP-80).

2026-10-10 docs/ is the wiki

Pull request #73, merged 2026-10-10. Rounds in this folder date from here: the design record moved into docs/superpowers/, replacing the saga. The saga was frozen in the 2026-11-14 docs round and is replaced by this file.

2026-10-11 Defects and repairs

Pull requests #74 (2026-10-11, "Spotless: every known defect after E3, and a credential masker that holds up"), #75 (2026-10-12, a URL whose host does not resolve is a 400 naming the host), #71 (tests on Python 3.10 to 3.12 again) and #79 (CODEOWNERS, 2026-10-22). There is no design or plan.

2026-10-22 The flows panel at the picked row

Issue #80, pull request #81, merged 2026-10-24. The plan was its own spec, with no design draft on the branch, and is not kept.

  • Shipped: on the Flows tab the panel opens level with the picked row, and a link to a flow scrolls to it once. Every workspace file read returns its real media type.
  • Built: the layout is pure CSS. .flowlist is display: contents and the panel spans from the picked row to a final 1fr track, because a spanning item gives its extra size only to flexible tracks. A click never scrolls and a listing refresh never scrolls.
  • Held by: the Flows tab in admin-ui, and the media type rule in workspace-files.

2026-10-26 Session capabilities

Design: session capabilities. Issue #82, pull request #87, merged 2026-10-27.

  • Shipped: open_session takes version and a raw capabilities object. An operator's session.capabilities rides under every open. Each capability sent is recorded with its source. The admin has a Session tab. Four layers merge, the Grid's refusals name who is to blame, and latest resolves with its browser.
  • Overtaken: a workspace keeps only what a caller passed, and each stored setting records its source (touch-ups, below). X-Version is Sf-Version.
  • Held by: session-settings (SET-2 to SET-48).

2026-10-27 Live view

Design: live view. Issue #83, pull request #88, merged 2026-10-27.

  • Shipped: a Live tab shows a workspace's browser through noVNC. The Grid's own VNC is reached through the hub only. A signed link is bound to a viewer with by and lives 60 seconds. A proxy enforces Watch and gates what a viewer may send.
  • Built: Paste goes through WebDriver at the focused element, because x11vnc drops non-ASCII keystrokes once its spare keycodes run out (measured on the cluster). The agent's reopen report survives a paste. A pasted newline can submit a form, so a paste's page is withheld from the answer. Paste text is never kept and a driver failure is answered by type alone.
  • Overtaken: ruling 35 (nothing refused while a person has control) by the control round.
  • Held by: live-view-and-control (LIVE-2 to LIVE-14, LIVE-36 to LIVE-41).

2026-10-27 Live control

Design: live control. Issue #91, pull request #93, merged 2026-10-27.

  • Shipped: a person takes control as a workspace state. The running call finishes first. Every surface is then refused with a Controlled 409 until the person hands back. await_control waits for the hand-back. A once-only structured notice reports it.
  • Built: mcp/waiting.py is the helper for the next waiting tool. Control is granted only after the pages are followed, so a viewer is told requested first even when no call is running.
  • Held by: live-view-and-control (LIVE-15 to LIVE-35).

2026-10-27 Session touch-ups

Design: touch-ups. Issue #92, pull request #95, merged 2026-10-28. Also #96 (a leaner skill, "the mistakes agents actually make").

  • Shipped: a workspace remembers only what a caller passed and records where each stored setting came from. A version stays with its browser. A node refusal blames only the caller's version. An untrusted certificate is a 400 that says so.
  • Held by: session-settings.

2026-10-28 Headless

Design: headless. Issue #86, pull request #97, merged 2026-10-28.

  • Shipped: open_session(headless=true) opens a browser that draws nothing on the node. The workspace remembers it as it remembers insecure. record=true on it is a 400 saying where headless came from, and its live view is refused. A headless flag in raw or config capabilities is refused.
  • Built: the plan's first task measured two claims and wrote not measured where Docker was not available. Ruling 8 (the window is not capped by the screen) was never borne out and is not in the spec. Ruling 9's no-display error was never measured.
  • Held by: session-settings (SET-23 to SET-25, SET-30, SET-35).

2026-10-29 Request headers

Design: Sf headers. Issue #90, pull request #98, merged 2026-10-29.

  • Shipped: the seven client headers are spelt Sf-..., in step with mcp-kb. Every old X- name is refused in one 400 that names each new header. X-MCP-Resources stays. X-Session-Key and ?session= are no longer known at all. The carried private header is sf-carried-workspace.
  • Overtaken: X-Workspace is an alias again (2026-11-12).
  • Held by: surfaces (SURF-8 to SURF-14), WS-4 and WS-5.

2026-10-29 Session and workspace URIs

Design: session URIs. Issue #99, pull request #100, merged 2026-11-04.

  • Shipped: workspace:// is for what the workspace keeps and session:// is for the live browser. Downloads are session://downloads[/{name}] and GET /browser/downloads. With no session open they say so, and the old workspace://files/downloads spelling is refused.
  • Not built: ruling 12, a resource prefix for a merged gateway.
  • Held by: workspaces-and-sessions (WS-44, WS-45), workspace-files.

2026-11-04 Agents from the plugin

Pull requests #105 (the roles come from the kubed-runner plugin), #108 (drop the relay leftovers) and #109 (take sub-issue-accepted), merged 2026-11-04. #110 and #111 (2026-11-05) are Copilot and auto-assign fixes to the issue-to-pull-request flow. There is no design or plan. They belong to the CI and agent flow and not to the server.

2026-11-12 A plugin folder and the agents extension

Design: plugin agents. Issue #115, pull requests #126 and #130, merged 2026-11-13.

  • Shipped: skills/ and prompts/ moved into one plugin/ folder that ships whole in the wheel, .claude-plugin/plugin.json included. The server declares io.modelcontextprotocol/agents and answers agents/list and agents/get from plugin/agents/.
  • Overtaken: plugin/agents/ is no longer empty: the explorer shipped (next entry).
  • Held by: plugin (PLG-2 to PLG-7, PLG-30 to PLG-40).

2026-11-12 Flows know where they apply

Design: flow sites and paths. Issue #114, pull request #122, merged 2026-11-13.

  • Shipped: a flow can declare sites and paths. A result that leaves the browser on one of them names the flow in flows_here, and so do open_session, a run's report, workspace://current and GET /browser. The hint holds at most ten entries, with the workspace's own first, and a global flow yields to a same-named own flow. A missing axis means any, never a leash.
  • Built: the plan's out-of-scope list names flow://here, GET /flows?url=, any admin change and any change to the secret leash. The matcher is pure (flows/places.py) and the cache is keyed on the library's revision with no time limit.
  • Overtaken: a page is host, port, path and route (2026-11-13). The plan names a store.version() and a FlowStore.catalogue that were not built.
  • Held by: saved-flows (FLOW-19 to FLOW-29).

2026-11-12 X-Workspace again

Design: X-Workspace alias. Issue #103, pull request #120, merged 2026-11-13.

  • Shipped: X-Workspace names the workspace as the one alias of Sf-Workspace, because a Claude.ai connector can send only allowlisted headers and sf-workspace is not on the list. Sf-Workspace wins when both are sent. A task's worker ignores a saved X-Workspace.
  • Held by: surfaces (SURF-9 to SURF-11, SURF-14), WS-5.

2026-11-13 Clicks that report where they landed

Design: click matches. Pull requests #124 (2026-11-13) and #140 (2026-11-14), plus #123, #125, #132, #136 and #142 the same days.

  • Shipped: every action that acts on an element uses the first match that can be used and says which one. A click says what received it, and warns when that is probably not what was meant. A failed click says what is at the point instead. Waits are bounded at 50 matches. #140 changed the invisible_cover wording.
  • Other fixes that day: save_flow no longer says that parameters is a JSON Schema object (#123); failures read alike and logs no longer cut every error at 80 characters (#125); press_key with no selector presses at the body (#136); a same-document navigation no longer reports the previous screen's title (#142).
  • Overtaken: the page's half is js/helpers.js with receiver.js, usable.js and usables.js.
  • Held by: browser-actions (ACT-7 to ACT-22).

2026-11-13 The explorer agent

Design: explorer agent. Issue #121, pull request #129, merged 2026-11-13.

  • Shipped: plugin/agents/explorer.md ships, so agents/list names explorer and agents/get returns its instructions with a medium routing hint. It tries a saved flow first, never overwrites one, opens no browser with arguments, stops and reports by default, and shares the caller's browser until a session of its own exists. A test holds the file to the rulings.
  • Held by: plugin (PLG-44 to PLG-53).

2026-11-13 Hash routes

Design: hash routes. Issue #137 under #134, pull requests #141 (2026-11-13) and #145 (2026-11-14).

  • Shipped: a page is host, port, path and hash route. flows_here hints on a route change, url= moves between routes, History keeps a route, and a flow's paths can name a route after #. The Move to global dialog says when a flow will never be hinted. #145 made titles and outlines follow the route in single-page apps.
  • Overtaken: this round revised the 2026-11-12 sites and paths rulings 10, 18, 21 and 23.
  • Held by: saved-flows (FLOW-21 to FLOW-24), site-data (SITE-44), browser-actions.

2026-11-13 Multiplayer workspaces

Design: multiplayer sessions. Issue #94, open.

  • Nothing is built. The sixteen rulings are in the spec as proposed requirements: WS-47 to WS-54, SURF-45, SURF-46, ACT-43, ACT-44, LIVE-42, CAP-81, UI-64, UI-65, FLOW-50, FLOW-51.
  • The one open section is taken with Dr K one question at a time.

2026-11-14 A reaped browser comes back with a word

Design: reopen notice and keep-alive. Issue #133, pull request #146, merged 2026-11-14.

  • Shipped: two fixes in this order. The notice: a reaped browser reopens with a notice and not silently. The keep-alive: the monitor's loop sends one GET /session/{id}/url (Grid.ping) per tick, so an idle gap of five minutes no longer loses the browser. The window is session.keep_alive, 900 seconds by default and 3,600 at most, with 0 off.
  • Built: Grid.ping retries once when the Grid has dropped a pooled connection, where ruling 21 said to send once (WS-41). The AGENTS.md recordings rule became: liveness is read off the listing, and the keep-alive is the only session command.
  • Overtaken: the "Grid reaps" claim of the session monitor round.
  • Held by: workspaces-and-sessions (WS-21 to WS-25, WS-35 to WS-38), config.

2026-11-14 Secret scope

Design: secret scope. Pull request #144, merged 2026-11-14.

  • Shipped: no result or error on any agent-facing surface returns the value of a secret allowed on the site it came from, typed or not; each comes back as [secret:name/key]. Every secret declares where it may be used. The scrubber is armed by scope, not by use, and runs at one fail-closed choke point.
  • Built differently from the design: the scrub applies every set built for the browser, forms are parked and carried by a reopen, and a leash edit is a rotation (SEC-33 to SEC-37, SEC-48, SEC-57, SEC-63).
  • Held by: secrets-and-scope (SEC-1 to SEC-73).

2026-11-14 Workspace ownership

Design: workspace ownership. Issue #66, open.

  • Nothing is built. The one ruling is in the spec as AUTH-50 to AUTH-54 and SURF-47, proposed. It meets the multiplayer design, where a different caller is a different session.

2026-11-14 The docs round

Plan: docs round. Pull request #163, merged 2026-11-14.

  • Shipped: the dated designs became a living spec of fifteen files in docs/superpowers/specs/ with 790 numbered requirements, 25 of them proposed. Designs moved to this folder with a History header each. README went from 430 lines to 174, AGENTS.md from 1,498 to 86, and CONTRIBUTING.md grew from 272 to 344 because the scattered rules moved there. The ten hand-written wiki pages are plain English and link to the spec.
  • Built: 756 requirements were checked against the code. The plan keeps the drift each area found and the places the wiki repeated or contradicted the spec. A design's silent corrections went to the History headers, which is why they can be trusted.
  • The plan carries the History header, so it stays. Its drift list names what looked like bugs; the refactor round says each needs Dr K's read and its own issue.

2026-11-14 The refactor round

Plan: refactor round, which carries a History header and stays. Issue #147 with sub-issues #148 to #159. Not started.

  • Planned: less code and fewer comments with every feature as it was. The baseline at 4603a3a is 23,934 code lines, 3,594 comment lines and 6,299 docstring lines in kubed/selenium_flow and scripts, with 4,579 unit tests and 97% coverage. R1 stabilises the suite, R2 to R9 take one package each, R10 and R11 take the tests, R12 compares with mcp-kb. A behaviour change is a stop.

2026-11-14 Flow tags and a config for each workspace

Designs: flow tags, issue #160, and workspace config, issue #161. Neither is built.

  • Dr K named both on 11-14 while the docs round ran. A flow carries tags and the admin UI filters by them. A workspace can have a config file in its folder that the admin UI edits live, which makes the workspace kept, and is the home for its roles.
  • Held by, as proposed: saved flows (FLOW-52, FLOW-53), workspaces and sessions (WS-61 to WS-63) and the admin UI (UI-70, UI-71).

2026-11-14 The docs round, second pass

Pull request #164, merged 2026-11-14. Record: the docs round.

  • Shipped: four spec areas an audit found missing (protocol, errors and logging, grid, runtime); this ledger, in place of 33 implementation plans and the four saga chapters; the plugin's skill checked against the code.

2026-11-14 The docs round, the audit

  • Shipped: the spec read as one document for the first time. About 70 rules stated in two areas became one statement and a pointer, and ten disagreements between areas were settled against the code. The plugin's skill, references and prompts lost about a third of their tokens. The README, CONTRIBUTING, AGENTS.md and the hand-written wiki pages were edited for flow.
  • Changed in the code: grid.url defaults to http://localhost:4444, and the OpenAPI document's first server is /. Both were one cluster's in-cluster addresses. The example viewer in tests and docs is alex.

Saga section numbers still cited in code

The code cites sections of the four saga chapters as §F1.27. The chapters are deleted, and this table says what each cited section decided, so a citation can still be looked up. git -C docs show 2ae3705:saga/<chapter> shows the section. 53 distinct numbers are cited.

Number What the section decided
§F1.1 A flow is one clearance. The saving is the model's inferences, one per step, and not network round trips.
§F1.2 Flows are stored per session name. An unnamed caller gets the reserved global library, and stdio has its own.
§F1.4 Names are validated against ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ and never sanitised. A bad name is a 400.
§F1.5 Reads are resources and writes are tools. A mirror tool serves clients that read no resources.
§F1.6 A step is nested {tool, params}, a discriminated union derived from the tool schemas.
§F1.7 Parameters are a JSON Schema object and every reference is structural. There is no templating.
§F1.9 open_session and end_browser are not flow steps, so one flow runs on any browser.
§F1.10 One file list with a kept flag, and keep_file flips it.
§F1.11 ROUTE_PREFIX mounts the whole server and /browser is fixed.
§F1.12 The code sees one directory, and the installer decides what is behind it.
§F1.14 Flows are stored as YAML, served as JSON and edited as YAML. safe_dump drops comments.
§F1.18 A secret is a directory of files: the directory is the name and each file is a key.
§F1.22 A Kubernetes secret is scoped by label. Filesystem secrets are global.
§F1.23 The catalogue is cached with a short TTL. A value is never cached and is read when bound.
§F1.24 No tool returns a value. The limits: execute_script can read a typed value back, and the leash check and the typing are not atomic.
§F1.26 A binding names the secret and the key as two fields, because key names contain dots.
§F1.27 Allowed URLs are enforced at bind time and matched by origin, never by substring.
§F1.28 Only write binds a secret. execute_script, navigate and press_key are refused.
§F1.31 The secret surfaces: a resource, a mirror tool and GET /secrets. ConfigMaps are the same machinery later.
§F1.37 The browser that accepts everything and does nothing: Chrome's save-password offer took focus. The fix is prefs that remove every prompt.
§F1.38 A parameter is text and a secret is structural. They were one mechanism and are two.
§F1.39 What flying it taught: four defects were found by driving the live server and no unit test could see them.
§F1.40 The flows panel redrawn: three columns, status is not an action. The design follows the app unless Dr K decides otherwise.
§F1.41 Release day: the image build went from 9.5 minutes to 2, and the last flight found two gaps.
§F2 Not a section in the saga. The code cites it for the frame check on a typed secret (a frame can forge the page check). No chapter text states it; see SEC-41 and ACT-26 in the spec.
§F2.1 A closed set of values is a Literal in the tool schema. An open set does not pretend to be closed.
§F2.2 execute_script points back at cheaper tools before accepting the job.
§F2.3 The server remembers the pointer. A move jumps unless glide is true.
§F2.4 drag is its own tool, with a source and a destination, and glides by default.
§F2.5 assert is JavaScript that must come back true.
§F2.6 A flow has no when. A flow owns where it starts and stops when it is not there.
§F2.7 A step's report names its URL when it differs from the previous step's.
§F2.8 One probe says whether an element can be used, read by the error and by outline. outline is not a step.
§F2.9 Screenshots save by default. No other file changes.
§F2.10 What the second sortie found: outline and assert worked and three faults followed.
§F2.12 One session, always named by the caller, with no ids in the contract.
§F2.13 The HTTP surface is REST with declared routes, and the session is who is calling (a header).
§F2.14 xpath and css became one selector object.
§F2.15 A long run reports progress, can be cancelled and sets its own budget. No status tools.
§F3.1 The resources default is decided by who is calling. An explicit value wins.
§F3.2 The instructions point each client at what it can read.
§F3.3 Every stale tool, resource and prompt description is found, and a test guards the next.
§F3.4 Resources have human names and templates offer completions for the caller's own names.
§F3.5 Tool descriptions are trimmed to what a model needs to call the tool.
§F3.6 Two generic mirrors, list_resources and read_resource, replace seven specific ones.
§F3.8 What the live check of #39 found: saved files went missing, among three faults fixed in #40.
§F4.1 The file grid is three sections, Downloads, Screenshots and Files, with no delete-all.
§F4.6 session://files is a folder and the sections are paths beneath it.
§F4.7 What an agent sees: screenshots in screenshots/, keep_file(uri) moves a screenshot and copies a download, no agent tool clears anything.
§F4.12 A Redis that is configured and unusable stops the boot.
§F4.15 The npm build is separate and its output is never committed.
§F4.17 The UI is optional. Without a build the admin URL answers a title page and the MCP App is not offered.
§F4.19 The Secrets tab was slow because of PyYAML's parser. The fix is libyaml and a parse cache by content.

Clone this wiki locally