devharness 0.9.15 → 0.9.17

package/build/tools/replay-typed-text-variables.test.js

@@ -0,0 +1,119 @@
+/**
+ * The `variables` key is BUILT from the selector, not quoted from it:
+ * `var_<0-based step index>_<selector, non-alphanumerics replaced by _>`. A
+ * step 2 typing into `#email` is `var_2__email` - two underscores, one from
+ * the separator and one from the `#`.
+ *
+ * A key that matches nothing is dropped in silence and the step runs on its
+ * recorded text, so a wrong key reads as an override while the recorded value
+ * reaches the live app. `docs/replay.md` and the skill's sequences reference
+ * both carried `var_2_#email` in their examples with nothing to catch it -
+ * these pin the two producers against each other so a doc example can be
+ * copied from a passing test.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { executeSteps } from './replay-executor.js';
+import { extractTextVariables } from './replay-formatters.js';
+import { configManager } from '../config.js';
+import { productionShaped } from '../test-support/fake-execute-tool-call.js';
+const commands = [
+    { tool: 'navigate', params: { action: 'goto', url: 'https://app.example.com/login' } },
+    { tool: 'input', params: { action: 'click', selector: '#open' } },
+    { tool: 'input', params: { action: 'type', selector: '#email', text: 'original@example.com' } },
+    { tool: 'input', params: { action: 'type', selector: '#password', text: 'recorded-secret' } },
+    { tool: 'input', params: { action: 'type', text: 'no selector here' } },
+];
+const seq = () => ({ id: 'seq-login', name: 'login', commands, createdAt: 1 });
+function makeHarness() {
+    const typed = [];
+    // After a `type` step the executor reads the field back through
+    // inspect.evaluateExpression and fails the step when it does not match, so
+    // the stub has to hold the value the field would now carry.
+    const fieldValues = new Map();
+    const executeToolCall = vi.fn(productionShaped(async (tool, params) => {
+        if (tool === 'input' && params.action === 'type') {
+            typed.push({ selector: params.selector, text: String(params.text) });
+            if (params.selector)
+                fieldValues.set(String(params.selector), String(params.text));
+        }
+        if (tool === 'inspect' && params.action === 'evaluateExpression') {
+            const selector = String(params.expression).match(/querySelector\('([^']*)'\)/)?.[1] ?? '';
+            const value = fieldValues.get(selector) ?? '';
+            return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(value)}\n\`\`\`` }] };
+        }
+        return { content: [{ type: 'text', text: '' }] };
+    }));
+    const ctx = {
+        executeToolCall,
+        commandRecorder: { recordCommand: vi.fn(), getCurrentHistoryIndex: () => 0, listSequences: () => [] },
+        connectionReason: 'device-a',
+        logPrefix: 'test',
+        variableStore: {},
+    };
+    return { typed, ctx };
+}
+beforeEach(() => {
+    vi.spyOn(configManager, 'getClickValidationConfig').mockReturnValue({
+        enabled: false, validateNavigation: false, requireDomChanges: false,
+        domChangesFailMode: 'warn', failOnConsoleErrors: false,
+        consoleErrorsFailMode: 'error', validateNetworkPayload: false,
+        networkFailMode: 'warn', postClickDelayMs: 0,
+    });
+    vi.spyOn(configManager, 'getReplayConfig').mockReturnValue({
+        maxConditionalDepth: 10, maxRegexLength: 500, showCursor: false,
+        playwrightExportPath: './x', puppeteerExportPath: './y', maxDelayMs: 0,
+    });
+});
+describe('typed-text variable keys', () => {
+    it('replaces every non-alphanumeric in the selector, giving two underscores after the index', () => {
+        expect(Object.keys(extractTextVariables(commands))).toEqual([
+            'var_2__email',
+            'var_3__password',
+            'var_4_text',
+        ]);
+    });
+    it('carries the recorded value alongside each key, so `get` shows what a run would type', () => {
+        expect(extractTextVariables(commands)['var_3__password'].value).toBe('recorded-secret');
+    });
+    it('substitutes on the key the extractor displays', async () => {
+        const { typed, ctx } = makeHarness();
+        await executeSteps({
+            sequence: seq(),
+            ctx,
+            startStep: 0,
+            variables: { var_2__email: 'fresh@example.com', var_3__password: 'supplied-secret' },
+        });
+        expect(typed).toEqual([
+            { selector: '#email', text: 'fresh@example.com' },
+            { selector: '#password', text: 'supplied-secret' },
+            { selector: undefined, text: 'no selector here' },
+        ]);
+    });
+    // The failure the doc examples produced: no error, no warning, and the
+    // recorded credential reaches the app.
+    it('drops a key that matches nothing and types the recorded text', async () => {
+        const { typed, ctx } = makeHarness();
+        const result = await executeSteps({
+            sequence: seq(),
+            ctx,
+            startStep: 0,
+            variables: { 'var_3_#password': 'supplied-secret' },
+        });
+        expect(result.results.every(r => r.success)).toBe(true);
+        expect(typed[1]).toEqual({ selector: '#password', text: 'recorded-secret' });
+    });
+    it('keys off the absolute command index, so startFrom does not shift them', async () => {
+        const { typed, ctx } = makeHarness();
+        await executeSteps({
+            sequence: seq(),
+            ctx,
+            startStep: 3,
+            variables: { var_3__password: 'supplied-secret' },
+        });
+        expect(typed).toEqual([
+            { selector: '#password', text: 'supplied-secret' },
+            { selector: undefined, text: 'no selector here' },
+        ]);
+    });
+});
+//# sourceMappingURL=replay-typed-text-variables.test.js.map

package/build/tools/replay-typed-text-variables.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-typed-text-variables.test.js","sourceRoot":"","sources":["../../src/tools/replay-typed-text-variables.test.ts"],"names":[],"mappings":"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"}

package/build/tools/replay-variable-key-validation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=replay-variable-key-validation.test.d.ts.map

package/build/tools/replay-variable-key-validation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-variable-key-validation.test.d.ts","sourceRoot":"","sources":["../../src/tools/replay-variable-key-validation.test.ts"],"names":[],"mappings":""}

package/build/tools/replay-variable-key-validation.test.js

@@ -0,0 +1,124 @@
+/**
+ * A `variables` key that names no typed-text step is a typo the caller has to
+ * hear about before anything runs.
+ *
+ * The executor matches keys exactly and nothing else looks at them, so an
+ * unmatched key was dropped in silence and the step ran on its RECORDED text
+ * while the call read as an override - a recorded credential reaching the live
+ * app with the run reporting success. The `connections` rebinding already
+ * rejects a reference that names no recorded step for the same reason.
+ *
+ * Two scopes, because the map means different things:
+ *  - `run` checks against the sequence plus everything it nests into;
+ *  - `runAll` holds ONE map for the whole suite, so a key is a typo only when
+ *    it matches no member. A per-sequence check there would reject a key meant
+ *    for a different one.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { CommandRecorder } from '../command-recorder.js';
+import { createReplayTools } from './replay-tools.js';
+import { productionShaped } from '../test-support/fake-execute-tool-call.js';
+let dir;
+let recorder;
+let replay;
+let typed;
+const write = async (name, commands) => {
+    await fs.writeFile(join(dir, `${name}.json`), JSON.stringify({
+        id: `seq-${name}`, name, createdAt: 1, commands,
+    }));
+};
+const typeStep = (selector, text) => ({ tool: 'input', params: { action: 'type', selector, text, connectionReason: 'suite' } });
+beforeEach(async () => {
+    dir = await fs.mkdtemp(join(tmpdir(), 'cdp-varkeys-'));
+    recorder = new CommandRecorder();
+    typed = [];
+    vi.spyOn(recorder, 'getSequencesDir').mockReturnValue(dir);
+    const fieldValues = new Map();
+    ({ replay } = createReplayTools(recorder, vi.fn(productionShaped(async (tool, params) => {
+        if (tool === 'input' && params.action === 'type') {
+            typed.push({ selector: params.selector, text: String(params.text) });
+            if (params.selector)
+                fieldValues.set(String(params.selector), String(params.text));
+        }
+        if (tool === 'inspect' && params.action === 'evaluateExpression') {
+            const selector = String(params.expression).match(/querySelector\('([^']*)'\)/)?.[1] ?? '';
+            return { content: [{ type: 'text', text: '```json\n' + JSON.stringify(fieldValues.get(selector) ?? '') + '\n```' }] };
+        }
+        return { content: [{ type: 'text', text: '' }] };
+    })), async () => null, async () => 9222, undefined));
+});
+afterEach(async () => {
+    recorder.stopSequenceWatch();
+    await fs.rm(dir, { recursive: true, force: true });
+});
+const text = (res) => res.content.map((c) => c.text).join('\n');
+describe('run rejects a key that names no step', () => {
+    beforeEach(async () => {
+        await write('login', [typeStep('#password', 'recorded-secret')]);
+        await recorder.loadSequenceFromDisk(join(dir, 'login.json'));
+    });
+    it('names the key, states the transform, and lists what is substitutable', async () => {
+        const res = await replay.handler({
+            action: 'run', wait: true, name: 'login', connectionReason: 'suite',
+            variables: { 'var_0_#password': 'supplied' },
+        });
+        expect(res.isError).toBe(true);
+        expect(text(res)).toContain('var_0_#password');
+        expect(text(res)).toContain('var_0__password');
+        expect(typed).toEqual([]);
+    });
+    it('accepts the key the executor actually builds', async () => {
+        const res = await replay.handler({
+            action: 'run', wait: true, name: 'login', connectionReason: 'suite',
+            variables: { var_0__password: 'supplied' },
+        });
+        expect(res.isError).toBeUndefined();
+        expect(typed).toEqual([{ selector: '#password', text: 'supplied' }]);
+    });
+    it('accepts a key that names a step in a sequence it nests into', async () => {
+        await write('outer', [{ tool: 'conditional', params: { if: '{{localStorage:x}}', then: 'login' } }]);
+        await recorder.loadSequenceFromDisk(join(dir, 'outer.json'));
+        const res = await replay.handler({
+            action: 'run', wait: true, name: 'outer', connectionReason: 'suite',
+            variables: { var_0__password: 'supplied' },
+        });
+        expect(res.isError).toBeUndefined();
+    });
+    it('accepts an empty map, which is how a caller keeps the recorded values', async () => {
+        const res = await replay.handler({
+            action: 'run', wait: true, name: 'login', connectionReason: 'suite', variables: {},
+        });
+        expect(res.isError).toBeUndefined();
+        expect(typed).toEqual([{ selector: '#password', text: 'recorded-secret' }]);
+    });
+});
+describe('runAll checks the map against the whole suite', () => {
+    beforeEach(async () => {
+        await write('a-first', [typeStep('#email', 'recorded@example.com')]);
+        await write('b-second', [typeStep('#password', 'recorded-secret')]);
+    });
+    it('accepts a key that matches only one member, and leaves the other on its recorded text', async () => {
+        const res = await replay.handler({
+            action: 'runAll', connectionReason: 'suite',
+            variables: { var_0__password: 'supplied' },
+        });
+        expect(res.isError).toBeUndefined();
+        expect(typed).toEqual([
+            { selector: '#email', text: 'recorded@example.com' },
+            { selector: '#password', text: 'supplied' },
+        ]);
+    });
+    it('rejects a key that matches no member, before anything runs', async () => {
+        const res = await replay.handler({
+            action: 'runAll', connectionReason: 'suite',
+            variables: { var_0__nosuchfield: 'supplied' },
+        });
+        expect(res.isError).toBe(true);
+        expect(text(res)).toContain('var_0__nosuchfield');
+        expect(typed).toEqual([]);
+    });
+});
+//# sourceMappingURL=replay-variable-key-validation.test.js.map

package/build/tools/replay-variable-key-validation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-variable-key-validation.test.js","sourceRoot":"","sources":["../../src/tools/replay-variable-key-validation.test.ts"],"names":[],"mappings":"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"}

package/docs/instructions.md

@@ -209,6 +209,9 @@ runs against (see Quick Start).
 **HTTP / assertions**: `request`, `assert`, `saveToDisk`
 - `request`: HTTP request as a sequence step. `destination: 'node'` sends it from the MCP server process (no browser, no CORS/cookies); `destination: 'browser'` runs `fetch()` in a connected tab (that page's cookies/session/origin). `saveAs` captures the response for later steps
 - `assert`: assert a condition as a sequence step, failing the sequence if false - use `{{var:name.path}}` templates against values captured by a prior `saveAs`
+- **`variables` on `run`/`runAll`**: replaces the text of recorded `input type` steps. Keys are BUILT from the selector - `var_<0-based step index>_<selector, non-alphanumerics replaced by _>` - so `#password` at step 3 is `var_3__password`, two underscores; read them off `get` or off the prompt a run returns rather than composing them by hand. A key naming no typed-text step is rejected before anything runs, with the substitutable keys listed. Substitutions reach the sequences a `conditional` or `forEach` nests into, so a key naming a step in a shared login helper lands there; `runAll` holds one map for the whole suite and accepts a key matching any member
+- **`{{env:NAME}}`**: any step param may hold it, resolved from `process.env` when the step runs. This is how a credential stays OUT of the sequence file - the file holds the token, the value lives in the environment, and neither the file nor the tool call carries the secret. An unset or empty variable fails the step and names the variable; an empty value would otherwise be typed as-is. The name must match `[A-Za-z_][A-Za-z0-9_]*`. A token-bearing step does not hold the run open for a `variables` answer, and an explicitly supplied `variables` value still wins over the environment
+- **`envFile` on `run`/`runAll`**: a KEY=value file supplying the `{{env:NAME}}` tokens for that run - `replay({ action: 'run', name: 'login', envFile: 'sequences.env' })`. A relative path resolves against the project directory (the one holding `.devharness`), absolute is used as-is. The file's values win over the server's own environment and a name it omits falls through to `process.env`; `process.env` is never written, so two background runs may name different files and changing the file needs no client restart. A missing file, or a line that is neither blank, a `#` comment, nor `NAME=value`, fails as a parameter error before any step runs. No `$VAR` expansion inside values
 - **Capturing values with `saveAs`**: supported on `request` and on `inspect({ action: 'evaluateExpression' })`. They store different shapes - `request` stores the whole response object (so `{{var:login.body.token}}`), `inspect` stores the evaluated value itself (so `{{var:pairingUrl}}` is the string). A `saveAs` that cannot be honoured now fails the step rather than silently capturing nothing. Async expressions work: a returned Promise is awaited and the settled value is captured exactly (JSON-serializable values are captured by value, not from display text)
 
 **Wait**: `wait` (exactly one of: selector, selectorGone, expression, ms)
@@ -236,13 +239,13 @@ runs against (see Quick Start).
 
 **Replay**: `replay` (actions: history, create, list, get, delete, export, load, listSaved, deleteSaved, run, runAll, step, finish, insert, addConditional, status, cancel, repeat, runFromLog, recordInteraction)
 - `recordInteraction`: record mouse, keyboard, and navigation events with a visual overlay
-- `runAll`: run every sequence in a folder and report one line each - `replay({ action: 'runAll', folder: 'spine', connectionReason: 'my-app' })`. Sequences may live in SUBFOLDERS of the sequences dir (`spine/`, `story/`, `_helpers/`); filenames are relative to that root (`spine/spine-01.json`) and `load` still accepts the bare basename. The whole tree is LOADED before anything runs, so a sequence in one folder can still reference a helper in another by name (a conditional's `then`, a forEach's `do`) - those resolve by sequence name, not by path. Folders whose name starts with `_` are loaded but never run by a bare `runAll`, which is where preamble guards and forEach bodies belong; naming such a folder explicitly runs it anyway. A failure is recorded and the suite continues (`continueOnFailure`, default true). Scoped to one root: the project sequences dir, or the global one with `global: true`. Accepts `baseUrl`, so one call runs a suite against any deployment
+- `runAll`: run every sequence in a folder and report one line each - `replay({ action: 'runAll', folder: 'spine', connectionReason: 'my-app' })`. Sequences may live in SUBFOLDERS of the sequences dir (`spine/`, `story/`, `_helpers/`); filenames are relative to that root (`spine/spine-01.json`) and `load` still accepts the bare basename. The whole tree is LOADED before anything runs, so a sequence in one folder can still reference a helper in another by name (a conditional's `then`, a forEach's `do`) - those resolve by sequence name, not by path. Folders whose name starts with `_` are loaded but never run by a bare `runAll`, which is where preamble guards and forEach bodies belong; naming such a folder explicitly runs it anyway. A failure is recorded and the suite continues (`continueOnFailure`, default true). Scoped to one root: the project sequences dir, or the global one with `global: true`. Accepts `baseUrl`, so one call runs a suite against any deployment - it reaches the nested sequences a conditional or forEach names, too. Accepts `killChromeOnFinish`, which means the SUITE's finish: only the last sequence carries it, so a preamble's browser survives between sequences
 - `addConditional`: add a guarded branch step - `replay({ action: 'addConditional', name: 'flow', condition: '{{selector:.cookie-banner}}', thenSequence: 'dismiss-banner', insertAfterStep: 2 })`. `conditional` is virtual, never recorded, so this is its only authoring route. Syntax and branch target are validated up front; a sequence already on disk is rewritten in place
 - `forEach`: a second virtual step - enumerate a source and run a sequence per item: `{ tool: 'forEach', params: { in: '{{var:shares}}', as: 'share', do: 'revoke-one-share', where: 'item.name !== "Employees"', maxItems: 50 } }`. `in` is either an array a prior `saveAs` captured or `{{selectorAll:CSS}}`; `where` is JavaScript with `item`/`index` in scope, not the condition grammar. Conditions probe one named thing, so this is what expresses "for everything that is there". An empty source is a success and the count is reported
 - `teardown`: an optional command array beside a sequence's `commands`, run when the main steps reach a terminal state - success, a failed step, an abort, or the total timeout - but not when the run pauses. It has its own timeout budget and does not receive the run's abort signal, so a cancelled or timed-out run still cleans up; it shares the variable store, so it can revoke what setup minted. A failing teardown step never changes the run's verdict. Best-effort: a killed server takes pending teardown with it
 - `export`: export a sequence to file - `format: sequence | playwright | puppeteer`
 - `repeat`: instantly re-execute commands by history index - `replay({ action: 'repeat', indices: [0, 1, 2] })`. Each tool response shows its history index in the "Repeat" hint
-- `run`: does not block - returns a `runId` immediately and executes in the background; poll `status({ runId })` for progress and the final result (kept 30 min in memory), `cancel({ runId })` interrupts the step in flight where the tool allows it (`wait` and `request` are genuinely cancelled, `navigate`/`inspect`/`content` stop waiting, `input` stops dispatching further events, the rest stop at the next step boundary - table in `docs/replay.md`). `wait: true` blocks for the full result (pre-0.7 behaviour). `startUrl` overrides the stored start URL for one run; `baseUrl` retargets every absolute URL at another deployment's origin
+- `run`: does not block - returns a `runId` immediately and executes in the background; poll `status({ runId })` for progress and the final result (kept 30 min in memory), `cancel({ runId })` interrupts the step in flight where the tool allows it (`wait` and `request` are genuinely cancelled, `navigate`/`inspect`/`content` stop waiting, `input` stops dispatching further events, the rest stop at the next step boundary - table in `docs/replay.md`). `wait: true` blocks for the full result (pre-0.7 behaviour). `startUrl` overrides the stored start URL for one run; `baseUrl` retargets every absolute URL at another deployment's origin - the sequence's own steps, a declared connection's launch url, and every sequence it reaches through a conditional or forEach
 - Use `global: true` with `export` to save to ~/.devharness/sequences/ instead of the working directory
 
 **Dashboard**: `dashboard` (actions: open, status, stop)

package/docs/replay.md

@@ -456,11 +456,19 @@ replay({ action: 'run', name: 'magic-link-login', startUrl: 'https://app.example
 ```
 
 - **`baseUrl`** rewrites the origin of *every absolute* `http(s)` URL in the
-  sequence - the stored `startUrl` and any string param in any step (a
-  `navigate goto` url, a `request` url, ...) - keeping path, query and hash.
-  Relative URLs are untouched. The stored sequence is never mutated.
+  sequence - the stored `startUrl`, any string param in any step (a
+  `navigate goto` url, a `request` url, ...), and the launch `url` of any
+  connection the sequence declares - keeping path, query and hash. Relative
+  URLs are untouched. The stored sequence is never mutated.
+- The retarget travels **into nested sequences**: a `conditional`'s `then` and
+  a `forEach`'s `do` load from the recorder in their recorded form, and the
+  run's origin is applied to each as it loads, at every depth. Without that a
+  retargeted run drives two origins at once - the parent on the target
+  deployment, the shared login/setup helper on the recorded one.
+- **`runAll`** takes `baseUrl` too, and applies it to every sequence in the
+  suite, so one call runs a recorded set against any deployment.
 - **`startUrl`** replaces the sequence's start URL wholesale for this run,
-  applied after any rebasing.
+  applied after any rebasing. It is per-sequence, so `runAll` ignores it.
 - Neither is preserved across a mid-run pause and `step`/`finish` resume, which
   re-reads the stored sequence.
 
@@ -555,6 +563,11 @@ browsers down too. The run says so instead: *"Chrome left running (port 9224
 also serves duo-member-two, killChromeOnFinish)"*. Disconnect or close the other
 connections first if you want the instance gone.
 
+On `runAll` the flag means the **suite's** finish: only the last sequence
+carries it. A teardown between sequences would destroy the state a `_helpers`
+preamble just established, and a suite that stops early (`continueOnFailure:
+false`, a cancel) leaves the browsers up for the failure to be read in.
+
 ### Preview Sequence
 
 ```javascript
@@ -580,6 +593,14 @@ Every recorded `input({ action: 'type' })` step gets an auto-generated key of
 the form `var_<0-based step index>_<selector, non-alphanumerics replaced by _>`
 (or `var_<i>_text` when the step has no selector).
 
+The selector is transformed, not quoted: `#email` becomes `_email`, so step 2
+against `#email` is keyed `var_2__email` - **two** underscores, one from the
+separator and one from the `#`. A key that names no typed-text step is
+rejected before anything runs, with the substitutable keys listed - the same
+rule `connections` applies to a reference naming no recorded step, and for the
+same reason: an ignored key would leave the step on its recorded text while
+the call read as an override.
+
 ```javascript
 // Original recording had: input({ action: 'type', selector: '#email', text: 'original@email.com' })
 replay({
@@ -587,12 +608,84 @@ replay({
   sequenceId: 'seq-login-flow',
   connectionReason: 'test-session',
   variables: {
-    'var_2_#email': 'new@email.com',
-    'var_3_#password': 'newpassword'
+    'var_2__email': 'new@email.com',
+    'var_3__password': 'newpassword'
   }
 })
 ```
 
+`replay({ action: 'get', name: '<sequence>' })` prints the keys as the executor
+builds them, and so does the prompt a `run` returns when typed text is present
+and `variables` is omitted. Read them from there rather than composing them by
+hand.
+
+The substitutions reach **nested sequences** - a `conditional`'s `then` and a
+`forEach`'s `do`, at every depth - so a key naming a step in a shared login
+helper lands there. `runAll` holds one map for the whole suite and validates it
+against the union of the selected sequences: a key matching any member is
+accepted, and each sequence substitutes on the keys that name its own steps.
+
+A supplied value does not remove the recorded literal, which stays in the
+sequence file under `.devharness/sequences/` (gitignored, still plaintext on
+disk). For a credential, use `{{env:NAME}}` instead - see below.
+
+### Keeping a secret out of the sequence file: `{{env:NAME}}`
+
+Any step param may hold `{{env:NAME}}`, resolved from `process.env` when the
+step runs. The file holds the token, the value lives in the environment, and
+neither the file nor the tool call carries the secret.
+
+```javascript
+// In the sequence file:
+{ tool: 'input', params: { action: 'type', selector: '#password', text: '{{env:APP_PASSWORD}}' } }
+
+// The run needs nothing else:
+replay({ action: 'run', name: 'login', connectionReason: 'app' })
+```
+
+- An **unset or empty** variable fails the step, naming the variable. Resolving
+  to `''` would submit a blank password and surface as a confusing downstream
+  failure instead of the missing configuration that caused it.
+- The name must match `[A-Za-z_][A-Za-z0-9_]*`. `{{env:app-password}}` is not a
+  token and passes through as literal text.
+- A token-bearing step does **not** hold the run open for a `variables`
+  answer - its value arrives at run time by definition. It stays substitutable,
+  and an explicitly supplied `variables` value **wins over** the environment,
+  because interpolation runs first and the substitution overwrites it.
+- Environment values are strings, so a whole-string `{{env:PORT}}` yields
+  `"3000"`, not `3000`.
+
+#### Pointing a run at a file: `envFile`
+
+```javascript
+replay({ action: 'run', name: 'login', connectionReason: 'app',
+         envFile: 'sequences.env' })
+```
+
+```bash
+# sequences.env
+APP_PASSWORD=hunter2
+export APP_USER="alice"   # export prefix and surrounding quotes are accepted
+```
+
+- A **relative** path resolves against the project directory (the one holding
+  `.devharness`); an absolute path is used as-is.
+- The file's values **win** over the server's own environment. The caller named
+  this file for this run; a stale ambient variable shadowing it would
+  substitute a different credential with nothing in the output to say so. A
+  name the file omits falls through to `process.env`.
+- `process.env` is **never written**. Two background runs may name different
+  files, and a global write would let one run's credentials resolve inside the
+  other. It follows that changing the file needs no client restart, unlike the
+  environment of a running server, which is fixed when it starts.
+- A **missing file**, or a line that is neither blank, a `#` comment, nor
+  `NAME=value` with a name matching `[A-Za-z_][A-Za-z0-9_]*`, fails as a
+  parameter error before any step runs - not halfway through a flow that has
+  already logged in. A skipped line would read as a set variable.
+- There is **no `$VAR` expansion** inside values. A password containing `$` is
+  ordinary, and expanding it would type something else.
+- `runAll` takes it too, applying the same file to every sequence in the suite.
+
 **If the sequence contains any typed text and you omit `variables` entirely,
 `run` does not execute** - it returns a prompt listing the substitutable keys
 and their recorded values. Pass `variables: {}` to accept the recorded values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devharness",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "description": "MCP server that connects AI assistants to Chrome DevTools Protocol for runtime debugging - set breakpoints, inspect variables, monitor network traffic, and automate browser interactions",
   "type": "module",
   "main": "build/index.js",

package/plugin/skills/devharness/SKILL.md

@@ -2,7 +2,7 @@
 name: devharness
 description: Drive and debug a running app via the devharness MCP server - launch or attach to Chrome and Node.js, set breakpoints and logpoints, inspect call stacks and variables, watch console and network, manage dev servers, replay any earlier tool call by its history index, and record reproduction sequences that verify a fix. Use whenever a task involves running or debugging a live app, reproducing or verifying a bug, re-driving setup you already did (relaunching, re-logging in, refilling a form), or the user mentions breakpoints, Chrome DevTools, CDP, replay sequences, or devharness tools (launchChrome, navigate, breakpoint, inspect, replay, server, issues, etc.).
 compatibility: Requires the devharness MCP server to be connected (tools such as launchChrome, breakpoint, inspect, replay, server, issues). The shell commands need `devharness` on PATH (`npm i -g devharness`); without it use `npx -y devharness@<version> <command>`. Previously published as cdp-tools-mcp.
-version: 0.9.15
+version: 0.9.17
 ---
 
 # devharness
@@ -153,4 +153,4 @@ Restart kills Chrome instances this session launched (relaunch with `launchChrom
 ## Load on demand
 
 - Full tool/action catalogue: [references/tool-categories.md](references/tool-categories.md)
-- Recording/replaying sequences — `saveAs`, per-step `connectionReason`, conditionals, verifying an issue fix: [references/sequences.md](references/sequences.md)
+- Recording/replaying sequences — `saveAs`, per-step `connectionReason`, conditionals, `variables`, keeping a password out of the sequence file with `{{env:NAME}}`, verifying an issue fix: [references/sequences.md](references/sequences.md)

package/plugin/skills/devharness/references/sequences.md

@@ -225,12 +225,42 @@ use `runId` to address a specific background run.
 
 ## Two different "variables" - don't confuse them
 
-**1. `variables` on `run` replaces recorded typed text.** Keyed by the recorded
-input, for replaying a signup with a fresh email:
+**1. `variables` on `run` replaces recorded typed text.** Keyed
+`var_<0-based step index>_<selector, non-alphanumerics replaced by _>`, so a
+step 2 typing into `#email` is `var_2__email` - two underscores, one from the
+separator and one from the `#`. Read the keys off `replay({ action: 'get' })`
+or off the prompt a `run` returns when typed text is present and `variables`
+is omitted; a key that names no typed-text step is rejected before anything
+runs, with the substitutable keys listed. Substitutions reach nested sequences
+(a `conditional`'s `then`, a `forEach`'s `do`) at every depth, so a key naming
+a step in a shared login helper lands there. `runAll` holds one map for the
+whole suite and accepts a key that matches any member. The recorded literal
+stays in the sequence file either way.
+
+**For a credential, use `{{env:NAME}}` in the step instead.** Any step param
+may hold it; it resolves from `process.env` when the step runs, so the file
+holds the token and neither the file nor the tool call carries the secret. An
+unset or empty variable fails the step, naming the variable - an empty value
+would be typed as-is. A token-bearing step does not prompt for `variables`,
+and an explicitly supplied value still wins over the environment.
+
+```
+{ tool: 'input', params: { action: 'type', selector: '#password',
+                           text: '{{env:APP_PASSWORD}}' } }
+```
+
+`envFile` names a KEY=value file for the run - `replay({ action: 'run', name:
+'login', envFile: 'sequences.env' })`. A relative path resolves against the
+project directory (the one holding `.devharness`); its values win over the
+server's own environment, a name it omits falls through to `process.env`, and
+`process.env` is never written, so concurrent runs may name different files and
+changing the file needs no client restart. A missing file or a line that is not
+blank, a `#` comment, or `NAME=value` fails before any step runs. No `$VAR`
+expansion inside values. `runAll` takes it too.
 
 ```
 replay({ action: 'run', sequenceId: 'seq-signup',
-         variables: { 'var_2_#email': 'new@example.com' } })
+         variables: { 'var_2__email': 'new@example.com' } })
 ```
 
 **2. `saveAs` captures a value mid-run for later steps.** Supported on