lastlight 0.15.0 → 0.16.1

package/docker-compose.yml

@@ -1,274 +0,0 @@
-services:
-  agent:
-    build: .
-    # Pin the built image tag so it's independent of the compose project name
-    # (which otherwise defaults to the checkout directory's basename). The
-    # `egress-init` service references this exact tag, so without the pin the
-    # stack only worked when the directory happened to be named `lastlight`.
-    image: lastlight-agent
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:8644:8644"
-    dns:
-      - 8.8.8.8
-      - 1.1.1.1
-    volumes:
-      # Single private deployment folder: overlay config.yaml + asset overrides
-      # plus a gitignored secrets/ subdir (.env, *.pem). LASTLIGHT_OVERLAY_DIR
-      # points the harness at /app/instance; the entrypoint reads secrets from
-      # /app/instance/secrets. This is the only deployment-specific input, read
-      # at startup — no image rebuild. To APPLY an edit: `config.yaml` and
-      # adding/changing an `.env` value apply on `docker compose restart agent`
-      # (the entrypoint re-sources .env). REMOVING an `.env` value needs a
-      # RECREATE — `docker compose up -d agent` (or `lastlight server start
-      # agent`) — because compose injects env_file vars at container creation
-      # and a restart can't unset them. Built-in assets (config/, workflows/,
-      # skills/, agent-context/) stay baked into the image; they're lastlight
-      # source and change via a normal rebuild.
-      - ./instance:/app/instance:ro
-      - agent-data:/app/data
-      - /var/run/docker.sock:/var/run/docker.sock   # spawn sandbox containers
-    # Env comes from the consolidated overlay (instance/secrets/.env). The
-    # entrypoint also sources it inside the container; this env_file is the
-    # belt-and-suspenders copy. required: false so a fresh checkout (no
-    # instance/ yet) doesn't error. No repo-root .env is needed.
-    env_file:
-      - path: ./instance/secrets/.env
-        required: false
-    environment:
-      # V8's default old-space cap (~1.5 GB on 64-bit) is well below the 2g
-      # cgroup limit, so Node would OOM before docker did. Raise it close to
-      # the container limit so transient bursts have somewhere to land.
-      - NODE_OPTIONS=--max-old-space-size=1800
-    # Steady-state ~150 MB; bursts during webhook fan-out, the in-process
-    # chat skill (full Agent SDK), and the dispatch screening call. 2 GB
-    # gives headroom for those bursts while still preventing a runaway leak
-    # from taking the host down.
-    mem_limit: 2g
-    memswap_limit: 2g
-    networks:
-      - internal
-
-  # Shared heavy base for the sandbox images (fnm + Node + semgrep/gitleaks + uv
-  # + the agent user). Both sandbox and sandbox-qa build FROM it, so it must be
-  # built FIRST:
-  #   docker compose --profile build-only build sandbox-base sandbox sandbox-qa
-  # Split out so the frequently-changing agentic-pi/agent-context tail (and, in
-  # sandbox-qa, ~300 MB of Chromium) stays cached across ordinary releases.
-  sandbox-base:
-    build:
-      context: .
-      dockerfile: sandbox-base.Dockerfile
-    image: lastlight-sandbox-base:latest
-    profiles:
-      - build-only     # never started as a service, just built
-
-  # Build the sandbox image (used by the harness to spawn per-task containers).
-  # FROM lastlight-sandbox-base:latest — build sandbox-base first.
-  sandbox:
-    build:
-      context: .
-      dockerfile: sandbox.Dockerfile
-    image: lastlight-sandbox:latest
-    profiles:
-      - build-only     # never started as a service, just built
-
-  # Build the enriched browser-QA sandbox image (Tier B). Separate + heavier
-  # (Playwright + a baked Chromium), built only when QA is enabled. Its FROM
-  # depends on lastlight-sandbox-base:latest existing first, so build in that order:
-  #   docker compose --profile build-only build sandbox-base sandbox-qa
-  sandbox-qa:
-    build:
-      context: .
-      dockerfile: sandbox-qa.Dockerfile
-    image: lastlight-sandbox-qa:latest
-    profiles:
-      - build-only     # never started as a service, just built
-
-  # ── Egress firewall (replaces the earlier tinyproxy CONNECT-proxy) ────
-  #
-  # See src/sandbox/egress-firewall-config.ts for the architecture rationale.
-  # Two pairs: (coredns-strict + nginx-egress-strict) and
-  # (coredns-open + nginx-egress-open). Sandbox containers spawn with
-  # `--dns <coredns-ip>` and dial allowlisted hosts directly — coredns
-  # resolves the hostname to the nginx IP, nginx peeks SNI and tunnels.
-  #
-  # The sandbox sees no proxy at all. Works for any SDK regardless of
-  # whether it honours HTTP(S)_PROXY env vars.
-
-  # One-shot init that writes nginx-strict.conf / nginx-open.conf /
-  # Corefile.strict / Corefile.open into the agent-data volume before
-  # coredns + nginx try to read them. Without this, the firewall
-  # services boot first, fail to find the configs, and run with empty
-  # state (returning NXDOMAIN for everything) — even after the harness
-  # later writes the files, the running processes never re-read them.
-  # `condition: service_completed_successfully` on the firewalls below
-  # makes them wait for this to exit 0.
-  egress-init:
-    image: lastlight-agent
-    restart: "no"
-    # Mounts the same overlay + secrets the agent does and runs the SAME
-    # config loader, so the collector config it pre-writes is computed from
-    # the effective config (env AND instance/config.yaml) — identical to what
-    # the harness writes at boot. This is what keeps the running collector's
-    # forwarding gate from diverging from the harness when OTEL is enabled via
-    # YAML rather than env.
-    env_file:
-      - path: ./instance/secrets/.env
-        required: false
-    volumes:
-      - ./instance:/app/instance:ro
-      - agent-data:/app/data
-    command:
-      ["node", "-e",
-       "const c=require('/app/dist/config/config.js').loadConfig();const m=require('/app/dist/sandbox/egress-firewall-config.js');const d=c.stateDir;m.writeEgressFirewallConfigs(d);m.writeOtelCollectorConfig(d,{active:c.otel.enabled&&c.otel.forwardToSandbox})"]
-    depends_on:
-      - agent          # ensures the image has been built when init runs
-
-  coredns-strict:
-    image: coredns/coredns:1.11.3
-    restart: unless-stopped
-    command: ["-conf", "/app/data/proxy/Corefile.strict"]
-    volumes:
-      - agent-data:/app/data:ro
-    depends_on:
-      egress-init:
-        condition: service_completed_successfully
-    networks:
-      sandbox-egress:
-        ipv4_address: 172.30.0.10
-
-  coredns-open:
-    image: coredns/coredns:1.11.3
-    restart: unless-stopped
-    command: ["-conf", "/app/data/proxy/Corefile.open"]
-    volumes:
-      - agent-data:/app/data:ro
-    depends_on:
-      egress-init:
-        condition: service_completed_successfully
-    networks:
-      sandbox-egress:
-        ipv4_address: 172.30.0.11
-
-  nginx-egress-strict:
-    image: nginx:alpine
-    restart: unless-stopped
-    command:
-      ["nginx", "-c", "/app/data/proxy/nginx-strict.conf", "-g", "daemon off;"]
-    volumes:
-      - agent-data:/app/data:ro
-    depends_on:
-      egress-init:
-        condition: service_completed_successfully
-    # Deliberately NOT on `internal`. Splitting ingress (sandbox-egress)
-    # and egress (proxy-egress) onto separate networks that don't include
-    # harness services keeps compose-internal hostnames unresolvable to
-    # the firewall — so an `unrestricted_egress` phase can't ask nginx to
-    # tunnel to `agent:8644` or similar.
-    networks:
-      sandbox-egress:
-        ipv4_address: 172.30.0.20
-      proxy-egress: {}
-
-  nginx-egress-open:
-    image: nginx:alpine
-    restart: unless-stopped
-    command:
-      ["nginx", "-c", "/app/data/proxy/nginx-open.conf", "-g", "daemon off;"]
-    volumes:
-      - agent-data:/app/data:ro
-    depends_on:
-      egress-init:
-        condition: service_completed_successfully
-    networks:
-      sandbox-egress:
-        ipv4_address: 172.30.0.21
-      proxy-egress: {}
-
-  # In-network OTEL collector. Sandboxes export telemetry here (by IP, on
-  # sandbox-egress) and it re-exports to the configured backend over
-  # proxy-egress. This is why the strict SNI firewall doesn't need to know
-  # about collector hosts or non-443 ports: the sandbox only ever dials this
-  # fixed internal endpoint, and the backend hop runs from a trusted,
-  # harness-controlled service that can use any port/scheme/headers. Backend
-  # auth headers live in the generated config (mode 0600 on the host volume)
-  # and are never forwarded into a sandbox.
-  #
-  # Dual-homed like the nginx firewalls — sandbox-egress (ingress) +
-  # proxy-egress (outbound). Deliberately NOT on `internal`, so it can't
-  # bridge a sandbox into harness services.
-  otel-collector:
-    image: otel/opentelemetry-collector:0.115.0
-    restart: unless-stopped
-    # Runs as the image's default non-root UID (10001). The harness `lastlight`
-    # user is pinned to that same UID (Dockerfile `useradd -u 10001`), so the
-    # collector reads the mode-0600 config the harness writes as its owner —
-    # no root, no world-readable secret. The image tag and that pinned UID must
-    # move together if a future image changes its user.
-    command: ["--config=/app/data/proxy/otel-collector.yaml"]
-    volumes:
-      - agent-data:/app/data:ro
-    depends_on:
-      egress-init:
-        condition: service_completed_successfully
-    networks:
-      sandbox-egress:
-        ipv4_address: 172.30.0.30
-      proxy-egress: {}
-
-  caddy:
-    image: caddy:2-alpine
-    restart: unless-stopped
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - ./Caddyfile:/etc/caddy/Caddyfile:ro
-      - caddy-data:/data
-      - caddy-config:/config
-    # Caddyfile uses `{$DOMAIN:localhost}` (Caddy's own env substitution), so
-    # DOMAIN just needs to be in the container env. Read it from the overlay
-    # secrets file directly — no repo-root .env / ${DOMAIN} interpolation.
-    env_file:
-      - path: ./instance/secrets/.env
-        required: false
-    # Caddy's memory footprint is tiny (typically <50 MB even under load).
-    mem_limit: 256m
-    memswap_limit: 256m
-    networks:
-      - internal
-
-volumes:
-  agent-data:       # contains: lastlight.db, agent-sessions/, sandboxes/, secrets/, logs/, proxy/
-  # Shared package-manager download cache (npm/pnpm/yarn), mounted at /cache in
-  # every dynamically-created sandbox container by src/sandbox/docker.ts so
-  # repeated installs reuse already-fetched tarballs (issue #107). Declared
-  # here so the stack manages its lifecycle; the agent service does not mount
-  # it. Override the name with LASTLIGHT_PKG_CACHE_VOLUME (defaults to the
-  # compose-prefixed `lastlight_pkg-cache`).
-  pkg-cache:
-  caddy-data:
-  caddy-config:
-
-networks:
-  internal:
-  # Sandbox containers (created dynamically by src/sandbox/docker.ts) attach
-  # to this network only with `--dns 172.30.0.10` (or .11 for open mode).
-  # `internal: true` disables direct host egress, so the only path to the
-  # public internet is through the nginx firewalls, which receive sandbox
-  # traffic on this network. Static subnet so the coredns + nginx IPs
-  # baked into the generated configs are stable.
-  sandbox-egress:
-    internal: true
-    ipam:
-      config:
-        - subnet: 172.30.0.0/24
-  # Egress-only network for the nginx firewalls. Regular bridge (has a
-  # default route to the host's network, so nginx can reach the public
-  # internet). Critically: NO other compose services attach here. That way
-  # docker's embedded DNS on this network resolves only public names — the
-  # harness service names (`agent`, `caddy`) are not reachable from the
-  # firewall's perspective, so an unrestricted sandbox can't ask nginx to
-  # bridge into the compose-internal services.
-  proxy-egress:

package/sandbox.Dockerfile

@@ -1,68 +0,0 @@
-# Sandbox image for Last Light agent tasks (LASTLIGHT_SANDBOX=docker
-# fallback only — the default production sandbox is gondolin, invoked
-# in-process by agentic-pi without docker).
-#
-# The heavy, stable toolchain (Debian deps, fnm + Node versions, semgrep/
-# gitleaks, uv, the `agent` user) lives in the shared sandbox-base image so it
-# stays cached across releases. This file adds only the THIN, frequently-changing
-# tail: the pinned agentic-pi install + the baked agent-context + the entrypoint.
-# Keep it that way — the same tail is duplicated in sandbox-qa.Dockerfile so
-# Chromium stays a cached child of the base rather than of this churn.
-#
-# Build order matters (sandbox-base must exist first):
-#   docker compose --profile build-only build sandbox-base sandbox
-#
-# BASE_IMAGE defaults to the local tag (host `--local` builds + docker compose
-# resolve it from the local image store). CI overrides it to the just-pushed
-# GHCR ref (`--build-arg BASE_IMAGE=ghcr.io/nearform/lastlight-sandbox-base:<tag>`)
-# because the buildx docker-container driver resolves FROM from a registry, not
-# the local store. See .github/workflows/docker-publish.yml.
-ARG BASE_IMAGE=lastlight-sandbox-base:latest
-FROM ${BASE_IMAGE}
-
-# Install agentic-pi globally so the harness can `docker exec ...
-# agentic-pi run ...` against this container. The version + integrity come from
-# `sandbox/agentic-pi.pin` (regenerated from lastlight's package-lock.json by
-# scripts/agentic-pi-pin.sh, drift-guarded by tests/agentic-pi-pin.test.ts). We
-# COPY that tiny two-line file rather than the whole package-lock.json on
-# purpose: the lockfile's hash changes on every release and would rebust this
-# layer (and sandbox-qa's Chromium) on every version bump; the pin changes only
-# when agentic-pi actually does. `npm install -g <tarball>` doesn't consult a
-# lockfile, hence the explicit integrity verification.
-COPY sandbox/agentic-pi.pin /tmp/agentic-pi.pin
-RUN version=$(sed -n '1p' /tmp/agentic-pi.pin) \
- && expected=$(sed -n '2p' /tmp/agentic-pi.pin) \
- && echo "Installing agentic-pi@${version} (${expected})" \
- && curl -fsSL "https://registry.npmjs.org/agentic-pi/-/agentic-pi-${version}.tgz" -o /tmp/agentic-pi.tgz \
- && actual="sha512-$(node -e "const c=require('crypto'),f=require('fs');process.stdout.write(c.createHash('sha512').update(f.readFileSync('/tmp/agentic-pi.tgz')).digest('base64'))")" \
- && if [ "$actual" != "$expected" ]; then \
-      echo "agentic-pi tarball integrity mismatch:" >&2; \
-      echo "  expected: $expected" >&2; \
-      echo "  actual:   $actual" >&2; \
-      exit 1; \
-    fi \
- && npm install -g --no-audit --no-fund /tmp/agentic-pi.tgz \
- && rm /tmp/agentic-pi.tgz /tmp/agentic-pi.pin
-
-# Agent context (baked at /app/ — entrypoint cats into workspace/AGENTS.md)
-COPY agent-context/ /app/agent-context/
-
-# Entrypoint
-COPY deploy/sandbox-entrypoint.sh /app/sandbox-entrypoint.sh
-RUN chmod +x /app/sandbox-entrypoint.sh
-
-# Own app dir for agent user
-RUN chown -R agent:agent /app /home/agent
-
-WORKDIR /home/agent/workspace
-
-# Image-level env so every `docker exec` (the entrypoint just runs once at
-# container start) sees these. Exporting them in sandbox-entrypoint.sh only
-# affects PID 1 — subsequent `docker exec agentic-pi run …` calls get a
-# fresh environment and would otherwise miss these paths.
-ENV LASTLIGHT_WORKSPACE=/home/agent/workspace
-ENV LASTLIGHT_GIT_CREDENTIALS=/home/agent/.lastlight-git-credentials
-
-# Entrypoint runs as root, fixes permissions, then drops to agent via gosu
-ENTRYPOINT ["/app/sandbox-entrypoint.sh"]
-CMD ["sleep", "infinity"]

package/skills/README.md

@@ -1,42 +0,0 @@
-# Skills
-
-Skill directories staged into the sandbox per workflow phase (and a subset into
-chat). A phase declares `skill: <name>` / `skills: [<name>, …]`; the runner
-stages the whole directory into `<agentCwd>/.agents/skills/<name>/` and
-pi-coding-agent surfaces `name` + `description` in the system prompt. The agent
-reads SKILL.md (and any `references/`) on demand via its `read` tool.
-
-**Authoring guide:** [`docs/agents/writing-skills.md`](../docs/agents/writing-skills.md)
-— the loading contract, the craft, and house conventions. Read it before adding
-or editing a skill.
-
-## Skills
-
-| Skill | Used by | Purpose |
-|-------|---------|---------|
-| [`chat`](chat/) | chat | Conversational assistant for Slack/Discord threads — answer repo/PR/issue questions, guide to natural-language triggers. |
-| [`issue-triage`](issue-triage/) | `issue-triage.yaml`, chat | Move issues through the canonical triage state machine — categorise, label, dedupe, manage stale, write a problem-statement summary (not a solution design), re-triage on reporter replies. |
-| [`issue-comment`](issue-comment/) | `issue-comment.yaml` | Handle non-build maintainer comments on issues/PRs — close, label, answer briefly, redirect build requests. |
-| [`pr-review`](pr-review/) | `pr-review.yaml`, chat | Review a PR with precision-first, tiered feedback and post a formal review. A pure code review — no building (CI validates the change). |
-| [`pr-comment`](pr-comment/) | `pr-comment.yaml` | Answer a maintainer's question about an open PR with concrete, code-cited evidence (not a full review). |
-| [`repo-health`](repo-health/) | `repo-health.yaml`, chat | Generate a repository health report — open issues, PR backlog, CI status, action items. |
-| [`security-review`](security-review/) | `security-review.yaml` | Diff-scoped SDLC security review; file one dated summary issue with a task-list of findings. |
-| [`security-feedback`](security-feedback/) | `security-feedback.yaml` | Process a maintainer's comment on a security scan summary — break findings into issues or record suppressions. |
-| [`building`](building/) | build (executor, reviewer), `pr-fix.yaml` | Shared craft: install-first + package-manager detection, the test/lint/typecheck gate, and TDD discipline in the sandbox. |
-| [`code-review`](code-review/) | build (reviewer), `pr-review.yaml` | Shared rubric: finding tiers (Critical/Important/Suggestions/Nits) and what-to-check. Referenced by both the branch-diff reviewer and the PR reviewer. |
-| [`verify`](verify/) | `verify.yaml` | Test a behaviour claim as an investigator — CONFIRMED / REFUTED / INCONCLUSIVE with bash-captured evidence. |
-| [`qa-test`](qa-test/) | `qa-test.yaml` | Run an automated QA flow against a CLI or locally-served app and report step-level pass/fail with evidence. |
-| [`browser-qa`](browser-qa/) | `verify.yaml`, `qa-test.yaml`, `demo.yaml` | Drive a real headless browser against a locally-served web UI and capture screenshot (and, for `demo`, video) evidence. Gated to the docker QA image. |
-| [`demo`](demo/) | `demo.yaml` | Record a short demo VIDEO of a PR/feature — drive the web UI, screen-record, and composite a titled, size-capped mp4 with ffmpeg. Gated to the docker QA image. |
-
-`building` and `code-review` are **shared building blocks** so the install
-gate and the review rubric each live in one place. `building` is staged by the
-build cycle (executor + reviewer) and `pr-fix`; `code-review` by the build
-reviewer and `pr-review` (which stages `code-review` but **not** `building` — a
-pure code review). They're staged alongside the phase's primary skill/prompt and
-read on demand.
-
-The live set is enforced at startup: `validateAssets()` (`src/workflows/loader.ts`)
-resolves every workflow `skill:` reference and `CHAT_SKILL_NAMES`
-(`src/engine/chat-skills.ts`). Adding a skill here does nothing until a phase or
-the chat list references it.

package/skills/browser-qa/SKILL.md

@@ -1,208 +0,0 @@
----
-name: browser-qa
-description: Drive a real headless browser against a locally-served web UI and capture screenshot evidence, reporting step-level PASS/FAIL/BLOCKED with extracted DOM text and console errors. Use when a phase on the docker QA image must exercise a rendered UI and attach screenshots — it complements the text-evidence verify/qa-test skills.
-version: 1.0.0
-tags: [browser, qa, screenshots, evidence]
----
-
-# Browser QA
-
-Drive a web UI with a real headless Chromium and report **step-level
-pass/fail with evidence**: extracted DOM text, assertion results, console
-errors, and screenshot files. The deliverable is a QA report — partial
-coverage with documented failures is the expected output.
-
-This skill is the **browser/screenshot path** that `verify` and `qa-test`
-scope out to "a separate docker-gated capability". It only works on the
-`lastlight-sandbox-qa:latest` docker image, which bakes in Playwright +
-Chromium. You have bash + file tools but **no vision** — you reason over the
-driver's JSON stdout (extracted text, assertion results, console errors).
-The PNG screenshots are **human evidence only**; you never see them.
-
-This skill uses the **building** skill for installing dependencies and
-starting the repo's dev-server.
-
-## When this applies
-
-A phase running on the docker QA image whose target is a **web app** the
-repo serves on `localhost` and where rendered-UI behaviour or visual
-evidence matters. For a CLI or a curl-able API, use `qa-test`/`verify`
-instead — don't launch a browser you don't need.
-
-## FIRST — probe for a browser
-
-The driver lives in this skill's bundle at
-`<skill-dir>/scripts/agent-browser.mjs`. Resolve `<skill-dir>` from the
-available-skills catalogue (it gives the absolute staged path of this
-skill); do not assume a relative path from `$PWD` — the agent's cwd is the
-checked-out repo, the bundle is a sibling.
-
-Run the runtime probe before anything else:
-
-```bash
-node <skill-dir>/scripts/agent-browser.mjs doctor
-```
-
-- Exit 0 with `{"ok":true,"chromium":"..."}` → Chromium is available; proceed.
-- Exit non-zero (e.g. `playwright not available …`, or no Chromium — the lean
-  default image, or a gondolin run) → **DO NOT attempt browser QA.** Fall back
-  to the text path (`verify`/`qa-test` style: curl the dev-server, capture
-  stdout) and **say in your report that the browser path was unavailable** and
-  you used the text path.
-
-## Start the app
-
-Follow the **building** skill to install dependencies, then start the repo's
-dev-server **in the background** and wait until it is listening on
-`localhost:PORT` (poll with `curl` until it answers). Note the port — you
-pass it as `--base-url`.
-
-## Author a flow
-
-Write a `flow.json` describing the QA flow. Shape:
-
-```json
-{
-  "baseUrl": "http://localhost:3000",
-  "viewport": { "width": 1280, "height": 800 },
-  "steps": [
-    { "name": "home", "goto": "/" },
-    { "click": "text=Login" },
-    { "fill": ["#email", "a@b.com"] },
-    { "type": ["#password", "hunter2"] },
-    { "press": "Enter" },
-    { "waitFor": "#dashboard" },
-    { "assertText": "Welcome" },
-    { "text": "h1" },
-    { "screenshot": "after-login" }
-  ]
-}
-```
-
-Step keys (a step may combine an action **plus** a trailing `screenshot`):
-
-| Key          | Value                | Effect                                                            |
-|--------------|----------------------|------------------------------------------------------------------|
-| `goto`       | path or URL          | Navigate (resolved against `baseUrl`). **Failure is fatal.**      |
-| `click`      | selector             | Click the element.                                               |
-| `fill`       | `[selector, value]`  | Set an input's value.                                            |
-| `type`       | `[selector, value]`  | Type key-by-key into an input.                                   |
-| `press`      | key (e.g. `Enter`)   | Press a keyboard key.                                            |
-| `waitFor`    | selector             | Wait until the element is visible (~10s timeout).                |
-| `assertText` | string               | Pass if the text is visible anywhere on the page; else step FAIL.|
-| `text`       | selector             | Extract `textContent` into the step result (for you to read).    |
-| `pause`      | milliseconds         | Hold for N ms — a readable beat after a state change (demo videos).|
-| `screenshot` | basename             | Write `<out-dir>/<basename>.png` (full page).                    |
-
-The whole flow runs in **one Chromium session** — login state, cookies, and
-navigation persist across steps.
-
-### Demo mode (recording only)
-
-When the session is **recorded** (`--record-dir`, `"record": true`, or an
-explicit `--demo`), the driver switches on "demo mode" so the capture is
-watchable — headless Chromium otherwise paints no cursor and fires actions
-instantly. Demo mode adds a **synthetic cursor overlay** that animates to each
-target, types `type` steps **character-by-character**, and holds a beat
-**between steps**. For screenshot QA (no recording) these are all no-ops, so
-QA runs stay fast. Prefer `type` over `fill` in a recorded flow so the typing is
-visible, and use `pause` for deliberate holds. Tunables:
-`--step-delay MS` (default 700), `--type-delay MS` (default 70),
-`--move-steps N` (default 25), `--no-cursor` to drop the overlay (env:
-`LASTLIGHT_STEP_DELAY_MS`, `LASTLIGHT_TYPE_DELAY_MS`, `LASTLIGHT_MOVE_STEPS`).
-
-## Run the flow
-
-```bash
-node <skill-dir>/scripts/agent-browser.mjs run flow.json \
-  --base-url http://localhost:PORT \
-  --out-dir <artifact-dir>
-```
-
-The driver prints a single JSON report:
-
-```json
-{ "ok": false,
-  "baseUrl": "http://localhost:3000",
-  "steps": [
-    { "index": 0, "action": "goto", "ok": true, "ms": 412 },
-    { "index": 6, "action": "assertText", "ok": false, "ms": 10003,
-      "error": "assertText not found: \"Welcome\"" },
-    { "index": 7, "action": "text", "ok": true, "ms": 5, "text": "Dashboard" },
-    { "index": 8, "action": "screenshot", "ok": true, "ms": 88,
-      "screenshot": "/…/after-login.png" }
-  ],
-  "consoleErrors": ["Uncaught TypeError: …"],
-  "screenshots": ["/…/after-login.png"] }
-```
-
-- A step error (selector not found, assertion miss, timeout) is recorded
-  `ok:false` and the run **continues** — best-effort coverage. The exception
-  is a `goto` that fails: that is fatal and the remaining steps are skipped.
-- `ok` at the top level is true only when **every** step passed. The process
-  exits 0 even when steps failed — judge from the JSON, not the exit code.
-  A non-zero exit means a fatal harness error (bad flow file, launch failure).
-
-## Screenshots & artifacts
-
-Pass `--out-dir <artifact-dir>` pointing at the run's artifact directory the
-**prompt provides** (commonly the run's `.lastlight/<issueKey>/` dir,
-referenced as the template variable the prompt passes in). Saving there lets
-the harness **harvest** the PNGs into the dashboard Artifacts view. Reference
-each screenshot path in your report.
-
-Screenshot delivery requires **server-mode build-assets**. If the PNGs can't
-be persisted (no artifact dir was provided, or build-assets is repo-mode),
-still report the text/DOM observations and console errors, and say the
-screenshots were **not retained**.
-
-## Evidence rules
-
-Mirror `verify`/`qa-test` — you are an investigator, not an advocate:
-
-- **Never fake a pass.** Don't hardcode expected text or edit the code under
-  test to force a green step.
-- **Report real failures.** A step that genuinely fails is a finding — record
-  it `FAIL` with the assertion/selector and the driver's error, and don't bury
-  it.
-- **Treat `consoleErrors` and page errors as findings**, even if the visible
-  flow "worked" — surface them in the report.
-- If the browser is unavailable (probe failed), fall back to text and say so —
-  don't pretend a UI step ran.
-
-## Report
-
-Produce your report as your **final message** — the workflow posts it for you
-(don't `github_add_issue_comment` yourself; that would double-post).
-
-**Be concise, and stay in the browser.** The deliverable is short: a one-line
-environment summary, the results table, the screenshots, console errors, and a
-one-line coverage note. Do **not** read or analyse the repo's source code (the
-text pass already did) and do **not** narrate every step or dump extracted DOM
-text — surface a `text`/assertion value only when it's the actual evidence for a
-row (e.g. a FAIL).
-
-```
-## Browser QA: <target>
-
-**Environment:** <branch / commit, package manager, how served, Chromium version>
-
-### Results
-| Step | Status | Evidence |
-|------|--------|----------|
-| <step description> | PASS / FAIL / BLOCKED | <terse evidence + inline screenshot if any> |
-
-### Console errors
-- <each consoleErrors / pageerror entry, or "none observed">
-
-### Coverage
-<one or two lines: what was driven, and anything not tested and why>
-```
-
-Reference screenshots **inline** as raw Markdown images when the prompt gives
-you a public artifact base URL — write `![caption](<base>/<name>.png)` directly
-in the report body (or table cell), **never** wrapped in backticks or a code
-fence (inside a code span it renders as literal text, not an image). Otherwise
-reference them by filename. Every step in the flow must
-have a row and a result. Never report a flow as "passed" with steps you didn't
-actually run — list them as untested instead.