Repository navigation
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.
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.
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 andglobal. 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_sessionandend_browserare 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.dirin 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=ghahad never worked because buildx runs from a shell step that gets noACTIONS_RUNTIME_TOKEN(§F1.41, #22). -
ROUTE_PREFIXbecame the mount point of the whole server and/browserstopped moving (§F1.11, E5), built in #35./openapi.yamlsits 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.
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_scriptcan 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
writebinds a secret.execute_scriptwould be an exfiltration API,navigatewould 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.
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.mdkeeps rules (§F1.15), and the skill getsreferences/FLOWS.md(§F1.16).
Held by admin-ui and saved-flows.
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
Literalin the tool schema, so the client sees an enum (§F2.1).press_keystays free text. The tools show their choices (#25). -
execute_scriptpoints back at cheaper tools before it accepts the job (§F2.2). - The server remembers the pointer. A move jumps unless
glideis asked for, anddragis 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. -
assertis JavaScript that must come back true (§F2.5, #26). A flow has nowhen: 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.outlineis 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).
xpathandcssbecame oneselector(§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
outlineputs 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.
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 onehttp.answer, and the 1,443-lineopenapi.pybecame schema data and a builder. The regenerated OpenAPI document was byte-identical to the onemainproduced. - 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
.coreinsidesession/had silently stopped the status reportingin_frame).errors.messagestrips credentials on every path. The design's tree putjs/insidecore/, and that is only safe because thepackage-dirkey moves with it. - Overtaken:
session/isworkspace/;http/mount.pywas never built;GET /secretsbuilds 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).
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
resourcesdefault is decided by who is calling.?resources=orX-MCP-Resourceswins, 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()andread_resource(uri), replaced seven specific ones, in the vocabularymcp-kbuses (§F3.6). FastMCP'sResourcesAsToolswas driven over HTTP by two callers before it was chosen. - No backward compatibility while one person uses the server (§F3.7). This took
--statelesswith 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_pdfwithprint(§F3.8).
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://filesis a folder and the sections are paths (§F4.6, nowworkspace://files). Screenshots are stored inscreenshots/besidefiles/,keep_filetakes 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_fileis 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'sstable_foris 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
keptflag, thesession://spellings (nowworkspace://files), and the Secrets tab's used-by rows. - Held by: workspace-files (FILE-2 to FILE-44), admin-ui, surfaces.
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 andpython -m buildfails. A shell comment swallowed its own__CSS__placeholders and blanked the page, sopage()strips shell comments before it substitutes. A{#each}key built fromflow + sessionwith no separator collided and left a pane on Loading forever; every keyed list was swept for it. A scoped@keyframeswould put a class on every element, so the live badge's pulse lives inapp.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
WorkspacesViewwith 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.
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
filetoconfigon 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.storeandsession.ttlareworkspace.storeandworkspace.ttl. The file is validated alone before the merge. - Held by: config (CFG-1 to CFG-61).
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_datasaves 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, andurlbecamehistory[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).
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,httpsandabout:blank.upload_filelost itspathsource. A secret cannot be typed into an element that hosts a frame. The admin page can be framed only by origins insecurity.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.timeoutwas deleted rather than wired to config. #53 fixed four rough edges found by the live test of this round. - Overtaken:
core/actions.pyhas sixteen page actions, not fourteen;core/recipe.pystill importsworkspace.locks. - Held by: browser-actions (ACT-2 to ACT-42), workspaces-and-sessions, surfaces.
Design: OIDC groundwork. Pull request #54, merged
2026-10-04. #55 made X-Workspace name the session too.
- Shipped:
/mcpaccepts a JWT from an OIDC issuer beside the server token and verifies signature,iss,aud,expand 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).
Design: show. Pull request #56, merged 2026-10-05.
- Shipped: one MCP App tool,
show(uri), draws a resource in the app shell.session_filesis 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_fileslisting tests moved totest_show.py. - Overtaken:
showdraws every URI the server serves (next entries, 2026-10-09). - Held by: surfaces (SURF-26 to SURF-30), admin-ui.
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/listandskills/getand 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 inmcp/frontmatter.py. - Held by: plugin (PLG-13 to PLG-22).
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 intoworkspaces/<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
.tmpis skipped as well as.partialand.part;smbfspolls. - Held by: workspace-files (FILE-45 to FILE-61).
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 approvedandplan approvedlabels, 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.
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-Keyand?session=became silent ignoring (2026-10-29). Thesession://refusal was narrowed by the session URIs round. - Held by: workspaces-and-sessions (WS-1 to WS-10, WS-17, WS-45, WS-46).
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 /statuslisting 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.finishedis emitted; "the Grid reaps" is the keep-alive (2026-11-14). - Held by: workspaces-and-sessions (WS-15 to WS-33).
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_byrecords who opened a browser. - Not built: a
script-srcpolicy, RP-initiated logout, a backend-for-frontend, sign-in in a frame. - Held by: auth-and-roles (AUTH-15 to AUTH-47).
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://downloadsbecame its own scheme. - Held by: surfaces (SURF-26 to SURF-30, SURF-44).
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_bodyisPOST /browser/network-bodywith{"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.markreturns 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_bodyis 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).
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.
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.
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.
.flowlistisdisplay: contentsand the panel spans from the picked row to a final1frtrack, 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.
Design: session capabilities. Issue #82, pull request #87, merged 2026-10-27.
- Shipped:
open_sessiontakesversionand a rawcapabilitiesobject. An operator'ssession.capabilitiesrides 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, andlatestresolves with its browser. - Overtaken: a workspace keeps only what a caller passed, and each stored setting records its source
(touch-ups, below).
X-VersionisSf-Version. - Held by: session-settings (SET-2 to SET-48).
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
byand 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).
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
Controlled409 until the person hands back.await_controlwaits for the hand-back. A once-only structured notice reports it. - Built:
mcp/waiting.pyis the helper for the next waiting tool. Control is granted only after the pages are followed, so a viewer is toldrequestedfirst even when no call is running. - Held by: live-view-and-control (LIVE-15 to LIVE-35).
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.
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 remembersinsecure.record=trueon 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 measuredwhere 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).
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 oldX-name is refused in one 400 that names each new header.X-MCP-Resourcesstays.X-Session-Keyand?session=are no longer known at all. The carried private header issf-carried-workspace. - Overtaken:
X-Workspaceis an alias again (2026-11-12). - Held by: surfaces (SURF-8 to SURF-14), WS-4 and WS-5.
Design: session URIs. Issue #99, pull request #100, merged 2026-11-04.
- Shipped:
workspace://is for what the workspace keeps andsession://is for the live browser. Downloads aresession://downloads[/{name}]andGET /browser/downloads. With no session open they say so, and the oldworkspace://files/downloadsspelling is refused. - Not built: ruling 12, a resource prefix for a merged gateway.
- Held by: workspaces-and-sessions (WS-44, WS-45), workspace-files.
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.
Design: plugin agents. Issue #115, pull requests #126 and #130, merged 2026-11-13.
- Shipped:
skills/andprompts/moved into oneplugin/folder that ships whole in the wheel,.claude-plugin/plugin.jsonincluded. The server declaresio.modelcontextprotocol/agentsand answersagents/listandagents/getfromplugin/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).
Design: flow sites and paths. Issue #114, pull request #122, merged 2026-11-13.
- Shipped: a flow can declare
sitesandpaths. A result that leaves the browser on one of them names the flow inflows_here, and so doopen_session, a run's report,workspace://currentandGET /browser. The hint holds at most ten entries, with the workspace's own first, and aglobalflow 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 aFlowStore.cataloguethat were not built. - Held by: saved-flows (FLOW-19 to FLOW-29).
Design: X-Workspace alias. Issue #103, pull request #120, merged 2026-11-13.
- Shipped:
X-Workspacenames the workspace as the one alias ofSf-Workspace, because a Claude.ai connector can send only allowlisted headers andsf-workspaceis not on the list.Sf-Workspacewins when both are sent. A task's worker ignores a savedX-Workspace. - Held by: surfaces (SURF-9 to SURF-11, SURF-14), WS-5.
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_coverwording. - Other fixes that day:
save_flowno longer says thatparametersis a JSON Schema object (#123); failures read alike and logs no longer cut every error at 80 characters (#125);press_keywith 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.jswithreceiver.js,usable.jsandusables.js. - Held by: browser-actions (ACT-7 to ACT-22).
Design: explorer agent. Issue #121, pull request #129, merged 2026-11-13.
- Shipped:
plugin/agents/explorer.mdships, soagents/listnamesexplorerandagents/getreturns its instructions with amediumrouting 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).
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_herehints on a route change,url=moves between routes, History keeps a route, and a flow'spathscan 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.
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.
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 issession.keep_alive, 900 seconds by default and 3,600 at most, with 0 off. - Built:
Grid.pingretries 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.
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).
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.
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.
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
4603a3ais 23,934 code lines, 3,594 comment lines and 6,299 docstring lines inkubed/selenium_flowandscripts, 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.
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).
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.
- 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.urldefaults tohttp://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 isalex.
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. |
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network