letmeknow-cli 0.4.11 → 0.6.0

package/README.md

@@ -1,78 +1,107 @@
 # LetMeKnow
 
-LetMeKnow gives an agent-managed folder a public, live static preview and receives browser form submissions. The CLI serves files directly and makes only an outbound WebSocket connection to the relay; it does not listen on a network port.
+LetMeKnow gives an agent a temporary public browser surface and structured human feedback. The agent edits an ordinary folder, explicitly publishes coherent revisions, and pulls form submissions as JSON. The CLI connects outbound to the hosted relay and does not listen on a network port.
 
-## Start
+## Start a session
 
-Node.js 22.12 or newer is required.
+Node.js 22.12 or newer is required. Create a dedicated directory containing only public files, then keep the server running:
 
 ```bash
-npx letmeknow-cli ./workspace
+npx letmeknow-cli serve ./preview
 ```
 
-The CLI prints JSON lines to stdout. The first line contains the public preview URL:
+The server prints one JSON line containing the public bearer URL and initial workspace revision:
 
 ```json
-{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","workspace":"…","workspace_sequence":1}
 ```
 
-Open that URL in one browser. The directory defaults to the current working directory. Set `LETMEKNOW_URL` to use another compatible relay:
+Anyone with the URL can view the published workspace and submit its forms. A graceful stop closes the session; an unexpected relay disconnect can reconnect for up to ten minutes. Diagnostics go to stderr.
+
+## Publish revisions
+
+`serve` snapshots the initial folder. Later filesystem changes remain private until explicitly published:
 
 ```bash
-LETMEKNOW_URL=https://letmeknow.dev npx letmeknow-cli ./workspace
+npx letmeknow-cli pull ./preview --wait 30
+npx letmeknow-cli push ./preview --based-on <batch-token>
 ```
 
-There are no `--host` or `--port` options because the CLI intentionally has no listening network socket. Diagnostics go to stderr. `--skill` prints the agent instructions without starting a session.
+`pull` returns pending browser interactions, the current workspace, and an opaque batch token:
 
-## File workflow
+```json
+{
+  "ok": true,
+  "type": "batch",
+  "token": "…",
+  "workspace": "…",
+  "workspace_sequence": 1,
+  "frontier": 1,
+  "events": [
+    {
+      "type": "submit",
+      "id": "…",
+      "form_id": "decision",
+      "values": {"decision":"approve"},
+      "based_on": "…",
+      "context": {"based_on":"…","current":"…","relationship":"current"}
+    }
+  ]
+}
+```
 
-The CLI does not receive file commands. The agent reads and writes the directory directly. Keep an `index.html` at the root, plus ordinary JavaScript, CSS, images, and other static assets.
+A repeated pull returns uncommitted events again. `push` atomically snapshots the folder, commits the batch, and reloads connected browsers once. Events arriving while the agent works remain for the next pull. A push can also publish independent work from an empty batch.
 
-The preview serves exact files and `index.html` for directory paths. It supports GET and HEAD, redirects directory paths to a trailing slash, and has no application-shell fallback. HTML responses include the live-preview client inline. Use relative asset URLs so previews also work on path-based session URLs.
+If a batch requires no workspace change, commit it without publishing:
 
-The client continuously saves form values, checked controls, selections, focus, text selection, scroll position, and open `<details>` elements for each page in the tab's session storage. It restores them after file-triggered and user-triggered reloads. CSS changes cache-bust matching stylesheets without navigating, while changes to the current HTML route or another asset reload the page. Changes to a different HTML route do not disturb the current page. Arbitrary JavaScript heap state cannot be preserved.
+```bash
+npx letmeknow-cli ack ./preview --based-on <batch-token>
+```
 
-An optional element can display submission status:
+`push` and `ack` are idempotent for a token. They fail if another command has moved the workspace or event cursor first.
 
-```html
-<p data-letmeknow-status aria-live="polite"></p>
-```
+The commands communicate with `serve` through a private local Unix socket. `--skill` prints agent instructions without starting a session.
+
+## Workspace behavior
+
+A published workspace is an immutable temporary snapshot of the selected folder. It may contain HTML, CSS, JavaScript, images, data, and linked pages. The relay injects a small runtime into HTML and serves all files from the same workspace revision.
 
-## Form submissions
+A successful push sends one revision notification. Browsers reload and preserve scroll position plus the values, checked state, and selected state of controls with stable unique IDs. Missing pages and connection-status pages remain live and recover on a later publication or reconnect.
 
-Forms are submitted without navigation. GET and POST forms are sent through the relay to the CLI, which prints each submission as one JSON line on stdout. The agent can read that line and edit the folder in response.
+## Forms
+
+Use native same-origin GET or POST forms:
 
 ```html
 <form id="decision" action="/decide" method="post">
-  <label>Comment <textarea name="comment"></textarea></label>
+  <label>Comment <textarea id="comment" name="comment"></textarea></label>
   <button name="decision" value="approve">Approve</button>
   <button name="decision" value="reject">Reject</button>
 </form>
 ```
 
-Submitting `Approve` prints an event like:
+Before delivery, the runtime gives each logical submission an opaque UUID and persists the serialized request in IndexedDB. Network retries and page reloads reuse that UUID. The CLI deduplicates accepted events, so a transport retry does not become another interaction. Distinct intentional submissions receive distinct IDs.
 
-```json
-{"type":"submit","id":"…","method":"POST","action":"/decide","form_id":"decision","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}
-```
+The runtime displays **Sending…** or **Uploading…**, followed by **Sent. Waiting for an update…** or an error. Add `[data-letmeknow-status]` to choose the status location. Native validation runs before submission. Repeated field names become arrays.
 
-Repeated field names become arrays. Native browser validation still runs before a submission is sent. File inputs and cross-origin form actions are not supported. Forms can use a submitter's standard `formaction`, `formmethod`, and `name`/`value` attributes.
+POST forms may include files within the 1 MiB total request limit. `pull` events contain attachment metadata and private temporary paths. Attachments remain available until `serve` stops and are not public unless deliberately copied into the workspace and pushed.
 
-The event ID identifies the submission. It is not a request/response handle: update the files and let the live preview show the result.
+Every submission records the exact workspace revision shown to the user. Its derived `context.relationship` is `current`, `stale`, or `unknown`, allowing the agent to decide whether to apply, rebase, or reject old feedback.
 
 ## Security
 
-The preview URL is a bearer capability. The relay receives the served files and submitted values. Do not put secrets in the preview folder or submit credentials unless that is intentional. The folder is trusted executable code from the browser's perspective.
+The URL is a bearer capability. The relay receives published files and submitted values. Keep secrets and unrelated files outside the preview directory.
 
-The selected folder is resolved with real paths. Requests that would leave that folder through a symlink are denied. `.env` files, `.git`, private-key files, database files, and their descendants are denied. The CLI itself still requires an outbound network connection to the relay. It does not accept inbound browser connections.
+The CLI excludes `.env`, `.git`, SSH keys, private-key files, and database files, and prevents symlink escapes. Processes that can write the workspace and invoke `push` are trusted publishers. Browser values, filenames, media types, and attachment contents remain untrusted input.
 
 ## Development
 
 ```bash
 npm install
 npm test
+npm run test:browser
 npm run dev
 npm run deploy
 ```
 
-`npm run dev` and `npm run deploy` operate the Cloudflare relay.
+The browser test requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay.

package/SKILL.md

@@ -1,98 +1,89 @@
 ---
 name: letmeknow
-description: Give a human a live public preview of an agent-managed folder and receive browser form submissions as JSON lines.
+description: Publish a temporary browser workspace, pull structured human feedback, and push coherent agent revisions.
 ---
 
 # LetMeKnow
 
-Use LetMeKnow when one human needs to inspect or interact with a temporary page, report, dashboard, approval form, quiz, table, or status view. The agent owns the files in a folder. The CLI serves that folder directly, connects to the public relay over an outbound WebSocket, and reports browser submissions on stdout.
-
-The CLI does **not** listen on a local network port.
+Use LetMeKnow when a human should inspect or interact with an agent-managed page, report, dashboard, approval, quiz, table, or prototype.
 
 ## Start
 
-Run the CLI as a long-lived child process with the folder you will edit:
+Create a dedicated directory containing only public files and keep the server running:
 
 ```bash
-npx letmeknow-cli ./workspace
+npx letmeknow-cli serve ./preview
 ```
 
-Node.js 22.12 or newer is required. Read stdout and stderr separately. Stdout is JSONL; the first event is:
+Node.js 22.12 or newer is required. The first stdout JSON line contains the bearer URL and initial workspace revision:
 
 ```json
-{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","workspace":"…","workspace_sequence":1}
 ```
 
-Open that URL for the human. The directory defaults to the current working directory. Set `LETMEKNOW_URL` to use another compatible relay. There are no host or port options: the CLI intentionally has no listening socket.
+Give the URL to the human. Anyone with it can view the workspace and submit forms. The CLI connects outbound and opens no network port. Diagnostics go to stderr.
 
-Do not send file commands to stdin. Read and write the folder directly. Keep the process running while the human uses the page.
+## Agent loop
 
-## Build the page
+Filesystem writes are private drafts. Explicitly pull feedback and publish coherent revisions:
 
-Create an ordinary static page in the folder, usually `index.html`, plus any CSS, JavaScript, images, or other assets it needs. Use relative asset URLs so path-based preview URLs work. Use semantic HTML and accessible labels, headings, sections, tables, and controls.
+```bash
+npx letmeknow-cli pull ./preview --wait 30
+# validate feedback and edit files
+npx letmeknow-cli push ./preview --based-on <batch-token>
+```
 
-The relay serves exact files and directory `index.html` files. It supports GET and HEAD, redirects directory paths to a trailing slash, and does not provide an application-shell fallback. HTML responses include the live-preview client inline.
+`pull` returns pending events, their derived causal context, the current workspace, and an opaque token. Pulling does not consume events; they are returned again after a crash. A successful `push` atomically snapshots the folder, commits that batch, and reloads connected browsers once. Feedback that arrives while you work remains for the next pull.
 
-The preview continuously saves each page's form values, checked controls, selections, focus, text selection, scroll position, and open `<details>` elements in the tab's session storage. It restores them after file-triggered and user-triggered reloads.
+When a batch needs no visible workspace change:
 
-The preview is live:
+```bash
+npx letmeknow-cli ack ./preview --based-on <batch-token>
+```
 
-- A change to the current HTML route reloads the page with its saved state.
-- CSS changes cache-bust matching linked stylesheets without navigating.
-- Changes to a different HTML route do not disturb the current page.
-- Changes to other assets reload the page. Arbitrary JavaScript heap state cannot be preserved.
+Both commands are idempotent for a token. Do not edit while `push` is snapshotting. Do not write commands to the long-running server's stdin.
 
-An optional status element gives the human feedback after a form submission:
+A push may publish independent work from an empty batch. Use the token returned by an empty `pull`.
 
-```html
-<p data-letmeknow-status aria-live="polite"></p>
-```
+## Build the workspace
 
-## Receive form submissions
+Use ordinary HTML, CSS, JavaScript, images, and relative links. Give forms stable IDs and controls meaningful names. Give editable controls stable unique IDs so values and scroll position survive published revisions.
 
-GET and POST forms are intercepted before navigation and sent through the relay to the CLI. Read stdout for a `submit` event:
+Use native same-origin GET or POST forms:
 
 ```html
-<form id="search" action="/search" method="post">
-  <label>Query <input name="query" required></label>
-  <button name="scope" value="all">Search all</button>
+<form id="review" action="/review" method="post">
+  <label>Comment <textarea id="comment" name="comment"></textarea></label>
+  <button name="decision" value="approve">Approve</button>
+  <button name="decision" value="reject">Reject</button>
 </form>
 ```
 
-The event is:
+The browser persists each serialized submission before delivery and retries it with the same opaque UUID after network failures or reloads. The CLI deduplicates retries. Distinct intentional submissions remain distinct. Native validation and repeated field names work normally.
+
+A pulled event includes the workspace the human saw:
 
 ```json
-{"type":"submit","id":"…","method":"POST","action":"/search","form_id":"search","trigger":{"id":null,"name":"scope","value":"all"},"values":{"query":"quarterly report","scope":"all"}}
+{
+  "type": "submit",
+  "id": "…",
+  "form_id": "review",
+  "values": {"comment":"Looks good","decision":"approve"},
+  "based_on": "…",
+  "context": {
+    "based_on": "…",
+    "current": "…",
+    "relationship": "current"
+  }
+}
 ```
 
-Rules:
-
-- Give interactive forms a stable, meaningful `id`.
-- Give controls meaningful `name` values.
-- Use normal relative or same-origin actions.
-- Use `formaction` and `formmethod` on submitters when different buttons have different intents.
-- Native `required`, input types, ranges, and patterns validate in the browser before the event is sent.
-- Repeated names become string arrays.
-- File inputs and cross-origin actions are not supported.
-
-The event ID identifies the submission. There is no response packet. Validate its values, edit the files, and let the live preview show the result. Do not write JSON commands to stdin.
-
-## Example response workflow
-
-1. Render the initial state in `index.html`.
-2. Wait for a `submit` event on stdout.
-3. Validate its `values` and `action`.
-4. Rewrite the relevant HTML or data file in the workspace.
-5. The agent updates the live preview.
-
-Escape untrusted values before placing them in HTML. Treat browser input as untrusted even though the folder is local to the agent.
-
-## Security
+Treat `stale` feedback deliberately: apply its intent to current state when safe, or show that the artifact changed and ask the human to review again. Never reconstruct the workspace from stale form values.
 
-The public URL is a bearer capability. The relay receives the served files and submitted values. Do not put secrets in the preview folder or submit credentials unless that is intentional. The folder is trusted executable code from the browser's perspective.
+POST forms may upload files within the 1 MiB request limit. Attachment events contain private temporary paths valid until `serve` stops. Validate names, media types, sizes, contents, actions, and IDs. Copy only deliberate outputs into the public workspace.
 
-The selected folder is resolved with real paths, and requests cannot escape it through symlinks. `.env` files, `.git`, private-key files, and database files are denied. The CLI makes outbound relay connections only; it does not accept inbound browser connections.
+Escape untrusted text before placing it in HTML.
 
 ## Stop
 
-Send `SIGINT` or `SIGTERM` to stop the CLI. The relay session expires after producer disconnect. `--skill` prints these instructions without starting a session.
+Send `SIGINT` or `SIGTERM` to `serve`. A graceful stop closes the public session and removes temporary snapshots, attachments, and the local control socket. `--skill` prints these instructions.

package/bin/letmeknow.js

@@ -1,20 +1,25 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync, statSync, writeSync } from "node:fs";
-import { readFile, realpath, stat } from "node:fs/promises";
-import { dirname, extname, relative, resolve, sep } from "node:path";
+import { constants, existsSync, readFileSync, statSync, writeSync } from "node:fs";
+import { chmod, copyFile, lstat, mkdtemp, mkdir, open, readdir, readlink, realpath, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import net from "node:net";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
 import { parseArgs } from "node:util";
-import chokidar from "chokidar";
-import ignore from "ignore";
 import { lookup } from "mrmime";
 
 const MAX_BODY_BYTES = 1024 * 1024;
 const GRACE_SECONDS = 10 * 60;
 const CONNECTION_TIMEOUT = 10_000;
+const CONTROL_TIMEOUT = 35_000;
 const MAX_RETRY_DELAY = 5_000;
+const CONTROL_PREFIX = "letmeknow-control-";
+const SNAPSHOT_PREFIX = "letmeknow-snapshot-";
+const CONTROL_URL = "https://letmeknow.dev";
 const credentialPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const ig = ignore().add([".env", ".env.*", ".git", "*.key", "*.pem", "*.p12", "*.sqlite", "*.db"]);
-const privateFilePattern = /\.(?:key|pem|p12|sqlite|db)$/i;
+const privateNames = new Set([".env", ".git", ".ssh", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"]);
+const privateFilePattern = /^\.env\.|\.(?:key|pem|p12|ppk|p8|sqlite|sqlite3|db|db3)$|-(?:wal|shm|journal)$/i;
 
 function getMimeType(filename) {
   const type = lookup(filename);
@@ -23,92 +28,6 @@ function getMimeType(filename) {
     ? `${type}; charset=utf-8`
     : type;
 }
-const client = String.raw`
-const sessionMatch=location.pathname.match(/^\/s\/[a-f0-9]{20}(?:\/|$)/);
-const sessionBase=sessionMatch?(sessionMatch[0].endsWith("/")?sessionMatch[0]:sessionMatch[0]+"/"):"/";
-const credentialKey="letmeknow-credential:"+location.origin+sessionBase;
-const snapshotKey=()=>credentialKey+":state:"+pageIdentity();
-let credential;
-try{credential=sessionStorage.getItem(credentialKey)}catch{}
-let socket;
-let retryTimer;
-let updateTimer;
-let reloadTimer;
-let terminal=false;
-const controls=()=>[...document.querySelectorAll("button,input,select,textarea")];
-const details=()=>[...document.querySelectorAll("details")];
-const uniqueId=(element,all)=>element.id&&all.filter(candidate=>candidate.id===element.id).length===1?element.id:null;
-const formIdentity=form=>form?.id||form?.getAttribute("name")||form?.getAttribute("action")||"document";
-const controlKey=(control,index,all=controls())=>{const id=uniqueId(control,all);if(id)return"id:"+id;const form=control.form;const identity=formIdentity(form)+":"+(control.type||control.localName)+":"+(control.name||"");const occurrence=all.slice(0,index).filter(candidate=>!uniqueId(candidate,all)&&formIdentity(candidate.form)+":"+(candidate.type||candidate.localName)+":"+(candidate.name||"")===identity).length;return"control:"+identity+":"+occurrence};
-const detailKey=(element,index,all=details())=>{const id=uniqueId(element,all);return id?"id:"+id:"detail:"+index};
-const pageIdentity=()=>location.pathname+location.search+location.hash;
-const snapshot=()=>{const all=controls();return{version:1,page:pageIdentity(),controls:all.map((control,index)=>({key:controlKey(control,index,all),value:control.value,checked:control.checked,indeterminate:control.indeterminate,selected:control instanceof HTMLSelectElement?[...control.options].map((option,optionIndex,options)=>option.selected?[option.value,options.slice(0,optionIndex).filter(candidate=>candidate.value===option.value).length]:null).filter(Boolean):undefined,start:typeof control.selectionStart==="number"?control.selectionStart:undefined,end:typeof control.selectionEnd==="number"?control.selectionEnd:undefined,direction:control.selectionDirection||undefined})),active:document.activeElement instanceof Element?controlKey(document.activeElement,all.indexOf(document.activeElement),all):undefined,details:details().map((element,index)=>({key:detailKey(element,index),open:element.open})),x:scrollX,y:scrollY}};
-const status=message=>{const element=document.querySelector("[data-letmeknow-status]");if(element)element.textContent=message};
-const stripSessionPath=path=>{if(sessionBase==="/")return path;if(path===sessionBase.slice(0,-1))return "/";return path.startsWith(sessionBase)?"/"+path.slice(sessionBase.length):path};
-const routePath=()=>{let path=stripSessionPath(location.pathname);return path.endsWith("/")?path+"index.html":path};
-const pagePath=path=>{path=path.split("?",1)[0];return stripSessionPath(path)||"/"};
-const save=()=>{try{sessionStorage.setItem(snapshotKey(),JSON.stringify(snapshot()))}catch{}};
-const restore=()=>{let raw;try{raw=sessionStorage.getItem(snapshotKey())}catch{return}if(!raw)return;let saved;try{saved=JSON.parse(raw)}catch{return}if(saved.version!==1||saved.page!==pageIdentity())return;const all=controls();const savedControls=new Map((Array.isArray(saved.controls)?saved.controls:[]).map(state=>[state.key,state]));let active;for(const [index,control] of all.entries()){const state=savedControls.get(controlKey(control,index,all));if(!state)continue;if(control instanceof HTMLSelectElement&&Array.isArray(state.selected)){const selectedIndexes=new Set(state.selected.filter(Number.isInteger));const selectedValues=new Set(state.selected.filter(Array.isArray).map(entry=>entry.join("\u0000")));for(const [optionIndex,option] of [...control.options].entries()){const occurrence=[...control.options].slice(0,optionIndex).filter(candidate=>candidate.value===option.value).length;option.selected=selectedIndexes.has(optionIndex)||selectedValues.has([option.value,occurrence].join("\u0000"))}}else if(control.type==="checkbox"||control.type==="radio"){control.checked=state.checked;control.indeterminate=state.indeterminate}else{control.value=state.value;if(typeof state.start==="number"&&typeof control.setSelectionRange==="function")control.setSelectionRange(state.start,state.end,state.direction||"none")}if(controlKey(control,index,all)===saved.active)active=control}const savedDetails=new Map((Array.isArray(saved.details)?saved.details:[]).map(state=>[state.key,state]));for(const [index,element] of details().entries()){const state=savedDetails.get(detailKey(element,index));if(state)element.open=state.open}active?.focus({preventScroll:true});scrollTo(saved.x||0,saved.y||0)};
-const reload=()=>{if(reloadTimer)return;reloadTimer=setTimeout(()=>{save();location.reload()},75)};
-const linkedStylesheet=path=>{for(const link of document.querySelectorAll('link[rel~="stylesheet"]')){let url;try{url=new URL(link.href,location.href)}catch{continue}if(url.origin!==location.origin)continue;if(sessionBase!=="/"&&!url.pathname.startsWith(sessionBase))continue;if(pagePath(url.pathname)===path)return link}return null};
-const refreshStylesheet=link=>{const url=new URL(link.href,location.href);url.searchParams.set("_letmeknow",crypto.randomUUID());link.href=url.href};
-const flushUpdates=()=>{updateTimer=undefined;const paths=[...pendingUpdates];pendingUpdates.clear();let shouldReload=false;const styles=[];for(const path of paths){if(/\.html?$/i.test(path)){if(path===routePath())shouldReload=true}else if(/\.css$/i.test(path)){const link=linkedStylesheet(path);if(link)styles.push([path,link]);else shouldReload=true}else shouldReload=true}if(shouldReload){reload();return}for(const [,link] of styles)refreshStylesheet(link)};
-const pendingUpdates=new Set();
-const update=path=>{if(typeof path!=="string")return;path=pagePath(path);pendingUpdates.add(path);if(!updateTimer)updateTimer=setTimeout(flushUpdates,75)};
-let saveTimer;
-const scheduleSave=()=>{if(!saveTimer)saveTimer=setTimeout(()=>{saveTimer=undefined;save()},100)};
-addEventListener("input",scheduleSave,true);
-addEventListener("change",scheduleSave,true);
-addEventListener("toggle",scheduleSave,true);
-addEventListener("focusin",scheduleSave,true);
-addEventListener("selectionchange",scheduleSave,true);
-addEventListener("scroll",scheduleSave,{passive:true});
-addEventListener("pagehide",save);
-addEventListener("load",()=>requestAnimationFrame(restore),{once:true});
-document.addEventListener("reset",()=>setTimeout(save));
-const connect=()=>{
-  clearTimeout(retryTimer);retryTimer=undefined;
-  const url=new URL(sessionBase+"_letmeknow/client",location.href);url.protocol=url.protocol==="https:"?"wss:":"ws:";
-  const current=credential?new WebSocket(url,credential):new WebSocket(url);
-  socket=current;
-  current.onmessage=event=>{
-    if(socket!==current||typeof event.data!=="string")return;
-    let message;try{message=JSON.parse(event.data)}catch{return}
-    if(message.type==="credential"){credential=message.credential;try{sessionStorage.setItem(credentialKey,credential)}catch{}return}
-    if(message.type==="challenge"){if(current.readyState===WebSocket.OPEN)try{current.send(JSON.stringify({type:"alive",nonce:message.nonce}))}catch{}return}
-    if(message.type==="busy"){status("This session is open elsewhere");retryTimer=setTimeout(connect,message.retry_after*1000);return}
-    if(message.type==="file_update"){update(message.path);return}
-    if(message.type==="closed"){terminal=true;try{sessionStorage.removeItem(credentialKey)}catch{}status(message.message)}
-  };
-  current.onclose=()=>{if(socket!==current||terminal)return;if(!retryTimer){status("Reconnecting…");retryTimer=setTimeout(connect,1000)}};
-  current.onerror=()=>{};
-};
-document.addEventListener("submit",async event=>{
-  const form=event.target;
-  if(!(form instanceof HTMLFormElement))return;
-  event.preventDefault();
-  const submitter=event.submitter;
-  const method=(submitter?.getAttribute("formmethod")??form.getAttribute("method")??"get").toLowerCase();
-  if(method!=="get"&&method!=="post"){status("Only GET and POST forms are supported");return}
-  if(!form.checkValidity()){form.reportValidity();return}
-  let target;
-  try{const action=submitter?.getAttribute("formaction")??form.getAttribute("action")??location.href;const base=sessionBase!=="/"&&location.pathname===sessionBase.slice(0,-1)?new URL(sessionBase,location.href):location.href;target=new URL(action,base)}catch{status("Invalid form action");return}
-  if(target.origin!==location.origin){status("Form actions must stay on this site");return}
-  if(sessionBase!=="/"){
-    const sessionPath=sessionBase.slice(0,-1);
-    if(target.pathname===sessionPath)target.pathname=sessionBase;
-    else if(!target.pathname.startsWith(sessionBase))target.pathname=sessionBase+target.pathname.replace(/^\//,"");
-  }
-  const values=new URLSearchParams();
-  for(const [name,value] of new FormData(form,submitter)){if(typeof value!=="string"){status("File inputs are not supported");return}values.append(name,value)}
-  const actionPath=sessionBase!=="/"?target.pathname.slice(sessionBase.length-1)||"/":target.pathname;
-  const metadata={id:crypto.randomUUID(),form_id:form.id||null,action:actionPath+target.search,trigger:{id:submitter?.id||null,name:submitter?.getAttribute("name"),value:submitter?.getAttribute("value")}};
-  const headers={"X-LetMeKnow-Submission":"1","X-LetMeKnow-ID":encodeURIComponent(metadata.id),"X-LetMeKnow-Form-ID":encodeURIComponent(metadata.form_id??""),"X-LetMeKnow-Action":encodeURIComponent(metadata.action),"X-LetMeKnow-Trigger-ID":encodeURIComponent(metadata.trigger.id??""),"X-LetMeKnow-Trigger-Name":encodeURIComponent(metadata.trigger.name??""),"X-LetMeKnow-Trigger-Value":encodeURIComponent(metadata.trigger.value??"")};
-  if(method==="get")for(const [name,value] of values)target.searchParams.append(name,value);
-  try{const response=await fetch(target,{method:method.toUpperCase(),headers,...(method==="post"?{body:values}:{})});if(!response.ok)throw new Error();status("Submitted")}catch{status("The submission failed")}
-});
-connect();
-`;
 
 function header(packet, name) {
   const entry = Object.entries(packet.headers || {}).find(([key]) => key.toLowerCase() === name);
@@ -139,8 +58,7 @@ function errorResponse(packet, status, message) {
 }
 
 function deniedPath(pathname) {
-  const normalized = pathname.replace(/^\/+/, "");
-  return normalized !== "" && (ig.ignores(normalized) || pathname.split("/").filter(Boolean).some(part => ig.ignores(part) || privateFilePattern.test(part)));
+  return pathname.split("/").filter(Boolean).some(part => privateNames.has(part) || privateFilePattern.test(part));
 }
 
 function inside(root, target) {
@@ -175,14 +93,8 @@ function requestUrl(packet) {
   return { pathname, encodedPathname: url.pathname, search: url.search };
 }
 
-function htmlWithClient(body) {
-  const text = body.toString("utf8");
-  const script = `<script type="module" data-letmeknow-client>${client}</script>`;
-  const closingBody = text.search(/<\/body\s*>/i);
-  return Buffer.from(closingBody < 0 ? text + script : text.slice(0, closingBody) + script + text.slice(closingBody), "utf8");
-}
-
-async function staticResponse(root, packet) {
+async function staticResponse(root, packet, workspaceId) {
+  const published = (status, body = Buffer.alloc(0), headers = {}) => response(packet, status, body, { ...headers, "X-LetMeKnow-Workspace": workspaceId });
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
   if (method !== "GET" && method !== "HEAD") return errorResponse(packet, 405, "method not allowed");
   let request;
@@ -202,9 +114,9 @@ async function staticResponse(root, packet) {
     return errorResponse(packet, 500, "preview request failed");
   }
   if (info.isDirectory()) {
-    if (!request.pathname.endsWith("/")) {
-      const location = request.encodedPathname + "/" + request.search;
-      return response(packet, 301, Buffer.from(`Redirecting to ${location}`), { Location: location, "Content-Type": "text/plain; charset=utf-8" });
+    if (!request.encodedPathname.endsWith("/")) {
+      const location = request.encodedPathname.slice(request.encodedPathname.lastIndexOf("/") + 1) + "/" + request.search;
+      return published(301, Buffer.from(`Redirecting to ${location}`), { Location: location, "Content-Type": "text/plain; charset=utf-8" });
     }
     const index = resolve(target, "index.html");
     try { target = await realpath(index); } catch (cause) {
@@ -213,95 +125,204 @@ async function staticResponse(root, packet) {
     }
     if (!inside(root, target)) return errorResponse(packet, 403, "forbidden");
     if (deniedPath("/" + relative(root, target).split(sep).join("/"))) return errorResponse(packet, 403, "forbidden");
+    try { info = await stat(target); } catch (cause) {
+      if (cause?.code === "ENOENT" || cause?.code === "ENOTDIR") return errorResponse(packet, 404, "not found");
+      if (cause?.code === "EACCES" || cause?.code === "EPERM") return errorResponse(packet, 403, "forbidden");
+      return errorResponse(packet, 500, "preview request failed");
+    }
   } else if (request.pathname.endsWith("/")) return errorResponse(packet, 404, "not found");
-  let body;
-  try { body = await readFile(target); } catch (cause) {
+  let file;
+  try { file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW); } catch (cause) {
     if (cause?.code === "ENOENT" || cause?.code === "ENOTDIR") return errorResponse(packet, 404, "not found");
-    if (cause?.code === "EACCES" || cause?.code === "EPERM") return errorResponse(packet, 403, "forbidden");
+    if (cause?.code === "EACCES" || cause?.code === "EPERM" || cause?.code === "ELOOP") return errorResponse(packet, 403, "forbidden");
+    return errorResponse(packet, 500, "preview request failed");
+  }
+  try {
+    info = await file.stat();
+    if (!info.isFile()) return errorResponse(packet, 404, "not found");
+    if (info.size > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
+    const body = await file.readFile();
+    if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
+    return published(200, body, { "Content-Type": getMimeType(target) });
+  } catch {
     return errorResponse(packet, 500, "preview request failed");
+  } finally {
+    await file.close();
   }
-  if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
-  if (extname(target).toLowerCase() === ".html") body = htmlWithClient(body);
-  if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
-  return response(packet, 200, body, { "Content-Type": getMimeType(target) });
 }
 
-async function submission(packet) {
+async function multipartSubmission(body, contentType, getAttachmentInbox) {
+  const formData = await new Request("http://letmeknow.local", {
+    method: "POST",
+    headers: { "Content-Type": contentType },
+    body
+  }).formData();
+  const values = Object.create(null);
+  const attachments = [];
+  for (const [name, value] of formData) {
+    if (typeof value === "string") {
+      addValue(values, name, value);
+      continue;
+    }
+    if (value.name === "") continue;
+    const bytes = Buffer.from(await value.arrayBuffer());
+    const path = join(await getAttachmentInbox(), randomUUID());
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    attachments.push({ field: name, name: value.name, type: value.type, size: bytes.byteLength, path });
+  }
+  return { values, attachments };
+}
+
+async function submission(packet, getAttachmentInbox, recordInteraction) {
   const url = requestUrl(packet);
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
   const values = Object.create(null);
+  let attachments;
   if (method === "GET") {
     for (const [name, value] of new URLSearchParams(url.search)) addValue(values, name, value);
   } else if (method === "POST") {
     const body = Buffer.from(typeof packet.body === "string" ? packet.body : "", "base64");
     if (body.byteLength > MAX_BODY_BYTES) throw new Error("submission is too large");
-    const contentType = header(packet, "content-type")?.split(";", 1)[0].trim().toLowerCase();
-    if (contentType !== "application/x-www-form-urlencoded") throw new Error("unsupported submission encoding");
-    for (const [name, value] of new URLSearchParams(body.toString("utf8"))) addValue(values, name, value);
+    const contentTypeHeader = header(packet, "content-type");
+    const contentType = contentTypeHeader?.split(";", 1)[0].trim().toLowerCase();
+    if (contentType === "application/x-www-form-urlencoded") {
+      for (const [name, value] of new URLSearchParams(body.toString("utf8"))) addValue(values, name, value);
+    } else if (contentType === "multipart/form-data" && contentTypeHeader) {
+      const parsed = await multipartSubmission(body, contentTypeHeader, getAttachmentInbox);
+      Object.assign(values, parsed.values);
+      attachments = parsed.attachments;
+    } else throw new Error("unsupported submission encoding");
   } else throw new Error("unsupported submission method");
   const event = {
     type: "submit",
-    id: encodedHeader(packet, "x-letmeknow-id"),
+    id: encodedHeader(packet, "x-letmeknow-id") || randomUUID(),
     method,
     action: encodedHeader(packet, "x-letmeknow-action") || url.pathname,
     form_id: encodedHeader(packet, "x-letmeknow-form-id"),
     trigger: { id: encodedHeader(packet, "x-letmeknow-trigger-id"), name: encodedHeader(packet, "x-letmeknow-trigger-name"), value: encodedHeader(packet, "x-letmeknow-trigger-value") },
     values
   };
-  process.stdout.write(`${JSON.stringify(event)}\n`);
-  return response(packet, 204);
+  const basedOn = encodedHeader(packet, "x-letmeknow-based-on");
+  if (basedOn !== null) event.based_on = basedOn;
+  if (attachments?.length) event.attachments = attachments;
+  await recordInteraction(event);
+  return response(packet, 202);
 }
 
-async function handleRequest(root, packet) {
+async function handleRequest(root, workspaceId, packet, getAttachmentInbox, recordInteraction) {
   if (header(packet, "x-letmeknow-submission") === "1") {
-    try { return await submission(packet); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
+    try { return await submission(packet, getAttachmentInbox, recordInteraction); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
   }
-  return staticResponse(root, packet);
+  return staticResponse(root, packet, workspaceId);
 }
 
 function options(directory) {
-  const root = resolve(directory || process.cwd());
+  const root = resolve(directory);
   if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`directory does not exist: ${root}`);
   return realpath(root).then(root => ({ root }));
 }
 
-function endpoint(control, credential, sessionUrl) {
-  const url = new URL(control);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  url.pathname = "/v1/connect";
-  url.search = "";
-  url.hash = "";
-  if (credential && sessionUrl) {
-    const publicUrl = new URL(sessionUrl);
-    const hostCode = publicUrl.hostname.match(/^([a-f0-9]{20})\.letmeknow\.dev$/);
-    const pathCode = publicUrl.pathname.match(/^\/s\/([a-f0-9]{20})(?:\/|$)/);
-    const code = hostCode?.[1] || pathCode?.[1];
-    if (code) url.searchParams.set("code", code);
+function controlPath(root) {
+  const key = createHash("sha256").update(root).digest("hex").slice(0, 32);
+  return join(tmpdir(), `${CONTROL_PREFIX}${key}.sock`);
+}
+
+async function copyDirectory(source, target, root, visited = new Set()) {
+  const sourceReal = await realpath(source);
+  if (visited.has(sourceReal)) return;
+  visited.add(sourceReal);
+  await mkdir(target, { recursive: true });
+  for (const entry of await readdir(sourceReal, { withFileTypes: true })) {
+    const candidate = join(sourceReal, entry.name);
+    const pathname = "/" + relative(root, candidate).split(sep).join("/");
+    if (deniedPath(pathname)) continue;
+    const targetPath = join(target, entry.name);
+    const targetReal = await safeRealpath(root, candidate);
+    if (targetReal === null) {
+      if ((await lstat(candidate)).isSymbolicLink()) await symlink(await readlink(candidate), targetPath);
+      continue;
+    }
+    if (targetReal === undefined) continue;
+    if (deniedPath("/" + relative(root, targetReal).split(sep).join("/"))) continue;
+    const info = await stat(targetReal);
+    if (info.isDirectory()) await copyDirectory(targetReal, targetPath, root, visited);
+    else if (info.isFile()) await copyFile(targetReal, targetPath);
   }
-  return url;
 }
 
-function validSessionUrl(value) {
-  if (typeof value !== "string") return false;
-  let url;
-  try { url = new URL(value); } catch { return false; }
-  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
-  if (/^[a-f0-9]{20}\.letmeknow\.dev$/.test(url.hostname)) return true;
-  return /^\/s\/[a-f0-9]{20}(?:\/|$)/.test(url.pathname);
+async function snapshotDirectory(root) {
+  const snapshot = await mkdtemp(join(tmpdir(), SNAPSHOT_PREFIX));
+  try {
+    await copyDirectory(root, snapshot, root);
+    return snapshot;
+  } catch (cause) {
+    await rm(snapshot, { recursive: true, force: true });
+    throw cause;
+  }
+}
+
+function mutateQueue() {
+  let chain = Promise.resolve();
+  return operation => {
+    const previous = chain;
+    let release;
+    chain = new Promise(resolve => { release = resolve; });
+    return previous.then(operation).finally(release);
+  };
+}
+
+function connectControl(root, packet) {
+  const timeout = Math.max(CONTROL_TIMEOUT, ((packet.wait_seconds || 0) + 5) * 1_000);
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(controlPath(root));
+    let output = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error("control request timed out"));
+    }, timeout);
+    const finish = (cause, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (cause) reject(cause);
+      else resolve(value);
+    };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(JSON.stringify(packet) + "\n"));
+    socket.on("data", chunk => {
+      output += chunk;
+      const newline = output.indexOf("\n");
+      if (newline < 0) return;
+      try { finish(null, JSON.parse(output.slice(0, newline))); } catch (cause) { finish(cause); }
+      socket.destroy();
+    });
+    socket.on("error", cause => finish(new Error(`serve is not running: ${cause.message}`)));
+    socket.on("close", () => { if (!settled) finish(new Error("serve closed the control connection")); });
+  });
 }
 
 async function start(directory) {
   const { root } = await options(directory);
-  const control = process.env.LETMEKNOW_URL || "https://letmeknow.dev";
+  let attachmentInboxPromise;
+  const getAttachmentInbox = () => {
+    attachmentInboxPromise ??= mkdtemp(join(tmpdir(), "letmeknow-attachments-"));
+    return attachmentInboxPromise;
+  };
+  const socketPath = controlPath(root);
+  let publishedRoot = await snapshotDirectory(root);
+  let workspaceId = randomUUID();
+  let workspaceSequence = 1;
+  const workspaceIds = new Set([workspaceId]);
+  const eventLog = [];
+  let committedCursor = 0;
+  const seenEvents = new Set();
+  const tokens = new Map();
+  const pendingTokens = new Map();
+  const pullWaiters = new Set();
+  const mutate = mutateQueue();
+  let controlServer;
   let send = () => false;
-  const watcher = chokidar.watch(root, { ignoreInitial: true });
-  watcher.on("all", (_event, filename) => {
-    if (!filename) { send({ type: "file_update", path: "/" }); return; }
-    const file = resolve(root, String(filename));
-    const path = relative(root, file).split(sep).join("/");
-    if (!path || path.startsWith("../") || path === ".." || deniedPath("/" + path)) return;
-    send({ type: "file_update", path: "/" + path.split("/").map(encodeURIComponent).join("/") });
-  });
   let socket;
   let credential;
   let sessionUrl;
@@ -311,13 +332,144 @@ async function start(directory) {
   let retryUntil = 0;
   let stopped = false;
   let ready = false;
+  let initialPublished = false;
+
+  const batch = () => {
+    const start = committedCursor;
+    const end = eventLog.length;
+    const key = `${workspaceId}:${start}:${end}`;
+    const existing = pendingTokens.get(key);
+    if (existing) return existing;
+    const token = randomUUID();
+    const events = eventLog.slice(start, end).map(event => ({
+      ...event,
+      context: {
+        based_on: event.based_on ?? null,
+        current: workspaceId,
+        relationship: event.based_on === workspaceId ? "current" : workspaceIds.has(event.based_on) ? "stale" : "unknown"
+      }
+    }));
+    tokens.set(token, { start, end, parent: workspaceId, status: "pending", key });
+    const result = { ok: true, type: "batch", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: end, events };
+    pendingTokens.set(key, result);
+    return result;
+  };
+
+  const notifyPullWaiters = () => {
+    for (const waiter of [...pullWaiters]) {
+      if (eventLog.length === committedCursor) continue;
+      pullWaiters.delete(waiter);
+      clearTimeout(waiter.timer);
+      waiter.resolve(batch());
+    }
+  };
+
+  const pull = waitSeconds => {
+    if (eventLog.length > committedCursor || waitSeconds <= 0) return Promise.resolve(batch());
+    return new Promise(resolve => {
+      const waiter = { resolve, timer: setTimeout(() => { pullWaiters.delete(waiter); resolve(batch()); }, waitSeconds * 1_000) };
+      pullWaiters.add(waiter);
+    });
+  };
+
+  const commit = async (token, publish) => {
+    const record = tokens.get(token);
+    if (!record) return { ok: false, error: "unknown batch token" };
+    if (record.status !== "pending") return record.result;
+    if (record.start < committedCursor && record.end <= committedCursor) {
+      pendingTokens.delete(record.key);
+      record.status = "committed";
+      record.result = { ok: true, type: "already_committed", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: committedCursor };
+      return record.result;
+    }
+    if (record.parent !== workspaceId || record.start !== committedCursor) {
+      pendingTokens.delete(record.key);
+      record.status = "failed";
+      record.result = { ok: false, error: "batch is based on an old workspace or cursor", current_workspace: workspaceId, frontier: committedCursor };
+      return record.result;
+    }
+    if (publish) {
+      const nextRoot = await snapshotDirectory(root);
+      const previousRoot = publishedRoot;
+      publishedRoot = nextRoot;
+      workspaceId = randomUUID();
+      workspaceIds.add(workspaceId);
+      workspaceSequence += 1;
+      record.result = { ok: true, type: "published", token, workspace: workspaceId, workspace_sequence: workspaceSequence, parent: record.parent, frontier: record.end, events: eventLog.slice(record.start, record.end).map(event => event.id) };
+      void rm(previousRoot, { recursive: true, force: true }).catch(() => {});
+    } else {
+      record.result = { ok: true, type: "acknowledged", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: record.end, events: eventLog.slice(record.start, record.end).map(event => event.id) };
+    }
+    committedCursor = record.end;
+    pendingTokens.delete(record.key);
+    record.status = "committed";
+    if (publish) send({ type: "revision" });
+    return record.result;
+  };
+
+  const dispatchControl = async request => {
+    if (!request || typeof request !== "object") return { ok: false, error: "invalid control request" };
+    if (request.type === "pull") return pull(Number.isFinite(request.wait_seconds) ? Math.max(0, request.wait_seconds) : 0);
+    if (request.type === "push") return commit(typeof request.token === "string" ? request.token : "", true);
+    if (request.type === "ack") return commit(typeof request.token === "string" ? request.token : "", false);
+    return { ok: false, error: "unknown control request" };
+  };
+
+  const controlConnections = new Set();
+  controlServer = net.createServer(connection => {
+    controlConnections.add(connection);
+    connection.setEncoding("utf8");
+    let input = "";
+    let handled = false;
+    connection.on("data", async chunk => {
+      input += chunk;
+      if (input.length > MAX_BODY_BYTES || handled) return;
+      const newline = input.indexOf("\n");
+      if (newline < 0) return;
+      handled = true;
+      let result;
+      try {
+        const request = JSON.parse(input.slice(0, newline));
+        result = request.type === "pull" ? await dispatchControl(request) : await mutate(() => dispatchControl(request));
+      } catch (cause) { result = { ok: false, error: cause instanceof Error ? cause.message : "control request failed" }; }
+      connection.end(JSON.stringify(result) + "\n");
+    });
+    connection.on("close", () => controlConnections.delete(connection));
+    connection.on("error", () => controlConnections.delete(connection));
+  });
+  await new Promise((resolveListen, reject) => {
+    controlServer.once("error", reject);
+    controlServer.listen(socketPath, async () => {
+      try { await chmod(socketPath, 0o600); } catch (cause) { controlServer.close(() => reject(cause)); return; }
+      controlServer.off("error", reject);
+      resolveListen();
+    });
+  }).catch(async cause => {
+    await rm(publishedRoot, { recursive: true, force: true });
+    throw new Error(`cannot start local control channel: ${cause.message}`);
+  });
+
+  const recordInteraction = event => mutate(async () => {
+    if (seenEvents.has(event.id)) return;
+    seenEvents.add(event.id);
+    eventLog.push(event);
+    notifyPullWaiters();
+  });
+
   const stop = async code => {
     if (stopped) return;
     stopped = true;
     clearTimeout(retryTimer);
     clearTimeout(connectionTimer);
+    send({ type: "close" });
     try { socket?.close(); } catch {}
-    await watcher.close();
+    for (const connection of controlConnections) connection.destroy();
+    await new Promise(resolveClose => controlServer.close(() => resolveClose()));
+    await unlink(socketPath).catch(() => {});
+    await rm(publishedRoot, { recursive: true, force: true });
+    if (attachmentInboxPromise) {
+      try { await rm(await attachmentInboxPromise, { recursive: true, force: true }); } catch {}
+    }
     process.exit(code);
   };
   process.once("SIGINT", () => void stop(0));
@@ -332,11 +484,11 @@ async function start(directory) {
   const connect = () => {
     if (stopped) return;
     const reconnecting = Boolean(credential && sessionUrl);
-    const current = socket = reconnecting ? new WebSocket(endpoint(control, credential, sessionUrl), credential) : new WebSocket(endpoint(control));
+    const current = socket = reconnecting ? new WebSocket(endpoint(credential, sessionUrl), credential) : new WebSocket(endpoint());
     connectionTimer = setTimeout(() => {
       if (socket !== current || current.readyState === WebSocket.OPEN || stopped) return;
       try { current.close(); } catch {}
-      if (reconnecting) retry(); else void stop(1);
+      if (!reconnecting) void stop(1);
     }, CONNECTION_TIMEOUT);
     current.addEventListener("open", () => {
       if (socket !== current || stopped) return;
@@ -359,9 +511,15 @@ async function start(directory) {
       } else if (packet.type === "session") {
         if (!validSessionUrl(packet.url)) return void stop(1);
         sessionUrl = packet.url;
-        if (!ready) { ready = true; process.stdout.write(`${JSON.stringify({ type: "ready", url: sessionUrl })}\n`); }
+        if (!initialPublished) {
+          initialPublished = true;
+          send({ type: "revision" });
+        }
+        if (!ready) { ready = true; process.stdout.write(`${JSON.stringify({ type: "ready", url: sessionUrl, workspace: workspaceId, workspace_sequence: workspaceSequence })}\n`); }
       } else if (packet.type === "http_request") {
-        void handleRequest(root, packet).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
+        const requestRoot = publishedRoot;
+        const requestWorkspace = workspaceId;
+        void handleRequest(requestRoot, requestWorkspace, packet, getAttachmentInbox, recordInteraction).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
       } else if (packet.type === "closed") {
         void stop(0);
       } else if (packet.type === "error") {
@@ -384,29 +542,79 @@ async function start(directory) {
   await new Promise(() => {});
 }
 
-let parsed;
-try {
-  parsed = parseArgs({
-    args: process.argv.slice(2),
-    options: {
-      skill: { type: "boolean" },
-      help: { type: "boolean", short: "h" }
-    },
-    allowPositionals: true
-  });
-} catch (cause) {
-  process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "invalid arguments"}\n`);
-  process.exit(1);
+function endpoint(credential, sessionUrl) {
+  const url = new URL(CONTROL_URL);
+  url.protocol = "wss:";
+  url.pathname = "/v2/connect";
+  if (credential && sessionUrl) {
+    const publicUrl = new URL(sessionUrl);
+    const code = publicUrl.hostname.match(/^([a-f0-9]{20})\.letmeknow\.dev$/)?.[1];
+    if (!code) throw new Error("invalid session URL");
+    url.searchParams.set("code", code);
+  }
+  return url;
+}
+
+function validSessionUrl(value) {
+  if (typeof value !== "string") return false;
+  let url;
+  try { url = new URL(value); } catch { return false; }
+  return url.protocol === "https:" && /^[a-f0-9]{20}\.letmeknow\.dev$/.test(url.hostname) && url.pathname === "/" && !url.search && !url.hash;
+}
+
+function usage() {
+  return "Usage:\n  npx letmeknow-cli serve <directory>\n  npx letmeknow-cli pull <directory> [--wait <seconds>]\n  npx letmeknow-cli push <directory> --based-on <token>\n  npx letmeknow-cli ack <directory> --based-on <token>\n";
 }
 
-if (parsed.values.skill) {
-  if (parsed.positionals.length > 0) { process.stderr.write("Usage: npx letmeknow-cli --skill\n"); process.exit(1); }
-  writeSync(1, readFileSync(new URL("../SKILL.md", import.meta.url)));
-} else if (parsed.values.help) {
-  process.stdout.write("Usage: npx letmeknow-cli [directory]\n\nServe a folder through the hosted LetMeKnow relay. The CLI does not listen on a network port. Form submissions are JSON lines on stdout.\n");
-} else if (parsed.positionals.length > 1) {
-  process.stderr.write("letmeknow: only one directory may be provided\n");
-  process.exit(1);
-} else {
-  try { await start(parsed.positionals[0]); } catch (cause) { process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "server failed"}\n`); process.exitCode = 1; }
+function commandArgs() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        skill: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        wait: { type: "string" },
+        "based-on": { type: "string" }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (cause) {
+    throw new Error(cause instanceof Error ? cause.message : "invalid arguments");
+  }
+  if (parsed.values.skill || parsed.values.help) {
+    if (parsed.positionals.length || parsed.values.wait !== undefined || parsed.values["based-on"] !== undefined) throw new Error(usage());
+    return { command: parsed.values.skill ? "skill" : "help" };
+  }
+  const [command, directory, ...extra] = parsed.positionals;
+  if (!command || !directory || extra.length) throw new Error(usage());
+  if (command === "serve" && (parsed.values.wait !== undefined || parsed.values["based-on"] !== undefined)) throw new Error(usage());
+  if (command === "pull" && parsed.values["based-on"] !== undefined) throw new Error(usage());
+  if ((command === "push" || command === "ack") && parsed.values.wait !== undefined) throw new Error(usage());
+  if (!["serve", "pull", "push", "ack"].includes(command)) throw new Error(usage());
+  let wait = 0;
+  if (parsed.values.wait !== undefined) {
+    wait = Number(parsed.values.wait);
+    if (!Number.isFinite(wait) || wait < 0) throw new Error("--wait must be a non-negative number");
+  }
+  if ((command === "push" || command === "ack") && typeof parsed.values["based-on"] !== "string") throw new Error("--based-on is required");
+  return { command, directory, wait, token: parsed.values["based-on"] };
+}
+
+let command;
+try {
+  command = commandArgs();
+  if (command.command === "skill") writeSync(1, readFileSync(new URL("../SKILL.md", import.meta.url)));
+  else if (command.command === "help") process.stdout.write(usage());
+  else if (command.command === "serve") await start(command.directory);
+  else {
+    const { root } = await options(command.directory);
+    const result = await connectControl(root, command.command === "pull" ? { type: "pull", wait_seconds: command.wait } : { type: command.command, token: command.token });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.ok) process.exitCode = 1;
+  }
+} catch (cause) {
+  process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "command failed"}\n`);
+  process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.4.11",
+  "version": "0.6.0",
   "description": "A live static preview with agent-readable form submissions.",
   "files": [
     "bin",
@@ -17,7 +17,8 @@
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run check && vitest run && node --test tests/cli.test.js tests/integration.test.js"
+    "test": "npm run check && vitest run && node --test tests/cli.test.js",
+    "test:browser": "node --test tests/browser.test.js"
   },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.1.0",
@@ -29,8 +30,6 @@
     "ws": "^8.21.3"
   },
   "dependencies": {
-    "chokidar": "^5.0.0",
-    "ignore": "^7.0.6",
     "mrmime": "^2.0.1"
   }
 }