@promptbook/cli 0.114.0-2 → 0.114.0-20

package/README.md

@@ -215,8 +215,6 @@ Respond to incoming legal inquiries via email and keep the company website updat
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 <br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
 <br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
@@ -305,7 +303,7 @@ GOAL Keep the company website updated with the latest legal policies and complia
 
 #### `Use` commitments
 
-Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
+Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE CALENDAR` lets the agent work with a calendar, `USE PROJECT` gives it access to a code repository, `USE MCP` connects any external Model Context Protocol server, and many more.
 
 These are what turn a chatbot into a persistent agent that actually does work.
 
@@ -322,9 +320,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -345,9 +340,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
@@ -534,7 +526,7 @@ Or you can install them separately:
 
 Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
 
--   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
 -   optional shared repo context loaded from a file such as `AGENTS.md`
 -   automatic `git add`, commit, and push after each successful prompt
@@ -549,11 +541,11 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
-4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind, and `--git-changes continue` resumes exactly that prompt with its uncommitted changes still in place.
 
 #### Features
 
@@ -561,7 +553,7 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 -   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
 -   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
--   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
+-   **Git safety:** clean working tree check by default, or `--git-changes ignore` to keep the changes and `--git-changes continue` to resume an interrupted prompt
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
 -   **Failure logging:** failed runs write a neighboring `.error.log`
@@ -582,7 +574,7 @@ npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gp
 
 npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --git-changes ignore
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -608,7 +600,7 @@ ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh -
 
 ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --git-changes ignore
 
 ptbk coder find-refactor-candidates
 
@@ -640,7 +632,7 @@ ptbk coder verify
 | `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
 | `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
+| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                 |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
 | `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |

package/agents/default/developer.book

@@ -2,6 +2,7 @@ Developer
 
 
 
+META VISUAL ascii-octopus
 META VISIBILITY PRIVATE
 
 RULE

package/apps/agents-server/README.md

@@ -45,7 +45,7 @@ ptbk agents-server start --harness github-copilot --model gpt-5.4 --thinking-lev
 -   `SESSION_SECRET`: HMAC signing key used to sign the session cookie. Must be set explicitly in production — the server refuses to start session signing when missing instead of falling back to a hardcoded default. Use a long random string, for example the output of `openssl rand -hex 32`. Keep it separate from `ADMIN_PASSWORD` so a leak of either credential cannot forge the other.
 
 <a id="agents-server-env-ptbk-agents-server-user-chat-worker-token"></a>
--   `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN`: Shared internal token used to authorize background worker routes (`/api/internal/user-chat-jobs/run`, `/api/internal/user-chat-timeouts/run`, and `/api/internal/agent-runner-limits`). Must be set explicitly in production — the server refuses to resolve the worker token when missing instead of falling back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or a hardcoded constant. Use a long random string, for example the output of `openssl rand -hex 32`. The CLI launcher (`ptbk agents-server start`) generates a per-process value automatically when the variable is empty so local development works without configuration.
+-   `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN`: Shared internal token used to authorize managed-agent and background worker routes (including `/api/internal/user-chat-jobs/run`, `/api/internal/user-chat-timeouts/run`, `/api/internal/agent-goal-chat-planned-messages`, and `/api/internal/agent-runner-limits`). Must be set explicitly in production — the server refuses to resolve the worker token when missing instead of falling back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or a hardcoded constant. Use a long random string, for example the output of `openssl rand -hex 32`. The CLI launcher (`ptbk agents-server start`) generates a per-process value automatically when the variable is empty so local development works without configuration.
 
 <a id="agents-server-env-promptbook-team-agent-access-token"></a>
 -   `PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN`: Dedicated secret used by same-server `TEAM` calls to authorize access to private teammate agents. Must be a dedicated random string — falling back to `ADMIN_PASSWORD` or `SUPABASE_SERVICE_ROLE_KEY` would let a leak of one credential compromise both authentication boundaries. When not configured, same-server team access stays disabled (the integration fails closed) so leaving the variable empty is safe but disables the feature. Use a long random string, for example the output of `openssl rand -hex 32`.

package/apps/agents-server/{USE_TIMEOUT_CHIP_QA.md → TIMEOUT_CHIP_QA.md}

@@ -1,4 +1,4 @@
-# USE TIMEOUT Chip QA
+# Timeout Chip QA
 
 -   Friendly default popup:
     Trigger a `set_timeout` tool call in an agent chat, click the timeout chip under the assistant message, and confirm the first view shows friendly copy (for example `Will retry in ...`) plus local time, relative time, and timezone.

package/apps/agents-server/next.config.ts

@@ -22,6 +22,11 @@ const agentsServerNodeModulesPath = process.env.PTBK_AGENTS_SERVER_NODE_MODULES_
  */
 const isNextValidationIgnored = process.env.PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION === 'true';
 
+/**
+ * Whether one isolated CLI production build should avoid writing a webpack filesystem cache that no later release can reuse.
+ */
+const isWebpackFilesystemCacheDisabled = process.env.PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE === 'true';
+
 /**
  * Optional worker count override for CLI-owned production builds on memory-constrained VPS hosts.
  */
@@ -29,6 +34,15 @@ const AGENTS_SERVER_BUILD_WORKER_COUNT = parseAgentsServerBuildWorkerCount(
     process.env.PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT,
 );
 
+/**
+ * Whether this build has to stay inside a small memory budget.
+ *
+ * Standalone VPS self-updates request a single build worker because they compile the replacement
+ * server while the current one is still serving traffic, so such a build must not start additional
+ * concurrent work either.
+ */
+const IS_MEMORY_CONSTRAINED_BUILD = AGENTS_SERVER_BUILD_WORKER_COUNT === 1;
+
 /**
  * Whether Sentry source maps can be uploaded during production builds.
  */
@@ -64,6 +78,19 @@ const nextConfig: NextConfig = {
 
     experimental: {
         externalDir: true,
+
+        // Note: Next.js turns its build workers off as soon as a `webpack` function is configured, and
+        //       that also turns off the parallel output file tracing pass. The `webpack` function below
+        //       only adds aliases, fallbacks and loaders, so the workers are asked for explicitly.
+        //       Compiling each target in a separate short-lived process also releases its memory as
+        //       soon as that target is done.
+        webpackBuildWorker: true,
+
+        // Note: Collecting the output file traces takes about two minutes and used to run alone between
+        //       the compilation and the static generation. It now runs next to the remaining compilation
+        //       and page generation - except for a build which has to save memory rather than time.
+        parallelServerBuildTraces: !IS_MEMORY_CONSTRAINED_BUILD,
+
         ...(AGENTS_SERVER_BUILD_WORKER_COUNT ? { cpus: AGENTS_SERVER_BUILD_WORKER_COUNT } : {}),
     },
 
@@ -79,6 +106,12 @@ const nextConfig: NextConfig = {
     },
 
     webpack(config, { isServer, nextRuntime }) {
+        if (isWebpackFilesystemCacheDisabled) {
+            // Versioned VPS releases build into a fresh checkout. Persisting the multi-gigabyte webpack cache there
+            // adds substantial disk I/O but cannot accelerate the next release, which has a different checkout.
+            config.cache = false;
+        }
+
         config.resolve.alias = {
             ...config.resolve.alias,
             '@': path.resolve(__dirname),
@@ -104,6 +137,12 @@ const nextConfig: NextConfig = {
                 tls: false,
                 dns: false,
                 child_process: false,
+                // Note: The startup hooks of `instrumentation.ts` only run in the Node.js runtime, but the
+                //       whole graph behind them is still compiled into the edge bundle as dead code. Agent
+                //       project runtimes hash and identify processes and serve built projects over plain
+                //       HTTP, so both modules have to be stubbed there just like the other Node.js-only ones.
+                crypto: false,
+                http: false,
                 // jsdom and related dependencies that require Node.js APIs
                 canvas: false,
                 // Standalone VPS SQLite backend is Node-only; edge middleware never runs it

package/apps/agents-server/package.json

@@ -1,19 +1,19 @@
 {
     "name": "promptbook-agents-server",
     "scripts": {
-        "generate-reserved-paths": "ts-node ./scripts/generate-reserved-paths/generate-reserved-paths.ts",
-        "prebuild": "npm run generate-reserved-paths && node ./scripts/clearNextGeneratedTypes.js && npx kill-port 4440 ||  exit 0",
-        "predev": "npm run generate-reserved-paths && npx kill-port 4440 ||  exit 0",
+        "generate-reserved-paths": "ts-node --transpile-only ./scripts/generate-reserved-paths/generate-reserved-paths.ts",
+        "prebuild": "npm run generate-reserved-paths && node ./scripts/clearNextGeneratedTypes.js && node ./scripts/kill-port.js 4440",
+        "predev": "npm run generate-reserved-paths && node ./scripts/kill-port.js 4440",
         "dev": "next dev -p 4440",
         "test": "npm run test-e2e",
         "test-e2e": "node ./scripts/run-e2e-tests.js",
-        "pretest-build": "npx kill-port 4021 4440 || exit 0",
+        "pretest-build": "node ./scripts/kill-port.js 4021 4440",
         "test-build": "npm run build",
-        "pretest-e2e": "npx kill-port 4021 4440 || exit 0",
+        "pretest-e2e": "node ./scripts/kill-port.js 4021 4440",
         "build": "node ./scripts/build-agents-server.js",
         "build-e2e": "node ./scripts/build-e2e.js",
         "start": "next start -p 4440",
-        "lint": "eslint src/ --max-warnings=0",
+        "lint": "eslint src/ --max-warnings=0 --cache --cache-location ./node_modules/.cache/eslint/agents-server-src.json",
         "postinstall": "node ./scripts/ensure-root-dependencies.js"
     }
 }

package/apps/agents-server/scripts/build-agents-server.js

@@ -8,6 +8,11 @@ const path = require('node:path');
  */
 const APP_ROOT = path.resolve(__dirname, '..');
 
+/**
+ * Root directory of the repository, which owns the shared build and test scripts.
+ */
+const PROJECT_ROOT = path.resolve(APP_ROOT, '..', '..');
+
 /**
  * Maximum Node.js heap size used by the Next.js production build.
  */
@@ -17,13 +22,14 @@ const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 8192;
  * Runs the shared Agents Server production build and its homepage prerender step.
  *
  * The optional `--no-lint` argument is used by the E2E runner after the same app
- * lint command has already completed successfully.
+ * lint command has already completed successfully. The optional `--no-homepage-prerender`
+ * argument is used by builds whose caller starts the very same production server right
+ * afterwards, which makes the extra prerender server a repetition of that work.
  */
 function buildAgentsServer() {
     const nextBuildArguments = [
-        `--max-old-space-size=${AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB}`,
         '-r',
-        path.join(APP_ROOT, 'scripts', 'ignore-kill-eperm.js'),
+        path.join(PROJECT_ROOT, 'scripts', 'ignore-kill-eperm.js'),
         path.join(APP_ROOT, 'scripts', 'next-cli.js'),
         'build',
     ];
@@ -32,8 +38,34 @@ function buildAgentsServer() {
         nextBuildArguments.push('--no-lint');
     }
 
-    runChildProcess(process.execPath, nextBuildArguments);
-    runChildProcess(process.execPath, [path.join(APP_ROOT, 'scripts', 'prerender-homepage.js')]);
+    runChildProcess(process.execPath, nextBuildArguments, {
+        // Note: Next.js compiles each webpack target in its own build worker process, and a worker
+        //       inherits the heap limit only through `NODE_OPTIONS` - not through the command line of
+        //       the build process which spawned it. The same merge is done for the CLI-owned
+        //       production build in `src/cli/cli-commands/agents-server/buildAgentsServer/runNextBuild.ts`.
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(process.env.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    });
+
+    if (!process.argv.includes('--no-homepage-prerender')) {
+        runChildProcess(process.execPath, [path.join(APP_ROOT, 'scripts', 'prerender-homepage.js')]);
+    }
+}
+
+/**
+ * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
+ *
+ * @param existingNodeOptions - Inherited `NODE_OPTIONS` value.
+ * @param maxOldSpaceMib - Maximum Node.js heap size in MiB.
+ * @returns `NODE_OPTIONS` value for the build process.
+ */
+function mergeNodeOptionsWithHeapSize(existingNodeOptions, maxOldSpaceMib) {
+    if (existingNodeOptions !== undefined && /--max-old-space-size[= ]/u.test(existingNodeOptions)) {
+        return existingNodeOptions;
+    }
+
+    const heapFlag = `--max-old-space-size=${maxOldSpaceMib}`;
+
+    return existingNodeOptions ? `${heapFlag} ${existingNodeOptions}` : heapFlag;
 }
 
 /**
@@ -41,11 +73,15 @@ function buildAgentsServer() {
  *
  * @param executablePath - Executable to run.
  * @param argumentsList - Arguments passed to the executable.
+ * @param environmentOverrides - Environment variables added on top of the inherited environment.
  */
-function runChildProcess(executablePath, argumentsList) {
+function runChildProcess(executablePath, argumentsList, environmentOverrides = {}) {
     const result = spawnSync(executablePath, argumentsList, {
         cwd: APP_ROOT,
-        env: process.env,
+        env: {
+            ...process.env,
+            ...environmentOverrides,
+        },
         stdio: 'inherit',
     });
 

package/apps/agents-server/scripts/build-e2e.js

@@ -9,6 +9,16 @@ const { runNpm } = require('./run-npm.js');
  */
 const APP_ROOT = path.resolve(__dirname, '..');
 
+/**
+ * Production build arguments which every E2E build applies.
+ *
+ * The homepage prerender starts one more production server only to download `/` into an HTML
+ * snapshot which nothing reads afterwards. Every E2E build is started by Playwright right after it
+ * is compiled, and the tests open the homepage against that very same server, so the snapshot would
+ * only repeat work the tests already do.
+ */
+const E2E_BUILD_ARGUMENTS = ['--no-homepage-prerender'];
+
 /**
  * Builds the production bundle used by the Agents Server E2E tests.
  *
@@ -16,10 +26,10 @@ const APP_ROOT = path.resolve(__dirname, '..');
  * mocked Supabase URL are embedded consistently in browser bundles.
  */
 function buildE2eServer() {
-    const buildArguments = ['run', 'build'];
+    const buildArguments = ['run', 'build', '--', ...E2E_BUILD_ARGUMENTS];
 
     if (process.argv.includes('--no-lint')) {
-        buildArguments.push('--', '--no-lint');
+        buildArguments.push('--no-lint');
     }
 
     runNpm(buildArguments, {

package/apps/agents-server/scripts/generate-reserved-paths/generate-reserved-paths.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import fs from 'fs';
 import path from 'path';
 import { GENERATOR_WARNING } from '../../../../src/config';
@@ -58,18 +59,20 @@ const allReservedPaths = [...new Set([...reservedPaths, ...publicPaths, ...addit
 /**
  * Constant for content.
  */
-const content = `/**
- * Reserved paths that should not be treated as agent names.
- * This file is auto-generated by scripts/generate-reserved-paths.js
- *
- * ${GENERATOR_WARNING}
- *
- * @see /apps/agents-server/src/app - source directory for routes
- * @see /apps/agents-server/public - source directory for static files
- * @see /apps/agents-server/src/middleware.ts - where this is used
- */
-export const RESERVED_PATHS: readonly string[] = ${JSON.stringify(allReservedPaths, null, 4)} as const;
-`;
+const content = spaceTrim(
+    (block) => `/**
+     * Reserved paths that should not be treated as agent names.
+     * This file is auto-generated by scripts/generate-reserved-paths.js
+     *
+     * ${GENERATOR_WARNING}
+     *
+     * @see /apps/agents-server/src/app - source directory for routes
+     * @see /apps/agents-server/public - source directory for static files
+     * @see /apps/agents-server/src/middleware.ts - where this is used
+     */
+    export const RESERVED_PATHS: readonly string[] = ${block(JSON.stringify(allReservedPaths, null, 4))} as const;
+    `,
+);
 
 // Ensure the generated directory exists
 /**
@@ -80,8 +83,19 @@ if (!fs.existsSync(generatedDir)) {
     fs.mkdirSync(generatedDir, { recursive: true });
 }
 
-// Write the file
-fs.writeFileSync(outputFile, content, 'utf-8');
+// Note: Rewriting an unchanged file would only move its modification time forward, which invalidates
+//       the webpack and TypeScript caches of every build and every development server start.
+/**
+ * Constant for current content.
+ */
+const currentContent = fs.existsSync(outputFile) ? fs.readFileSync(outputFile, 'utf-8') : null;
 
-console.log(`Generated ${outputFile} with ${allReservedPaths.length} reserved paths:`);
-console.log(allReservedPaths.join(', '));
+if (currentContent === content) {
+    console.log(`Kept ${outputFile} unchanged with ${allReservedPaths.length} reserved paths.`);
+} else {
+    // Write the file
+    fs.writeFileSync(outputFile, content, 'utf-8');
+
+    console.log(`Generated ${outputFile} with ${allReservedPaths.length} reserved paths:`);
+    console.log(allReservedPaths.join(', '));
+}

package/apps/agents-server/scripts/kill-port.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+/**
+ * Frees the given TCP ports before a build, a development server, or an E2E run binds them again.
+ *
+ * This replaces `npx kill-port`, which resolved an undeclared package through the npm registry on
+ * every single invocation. Freeing a port is a best-effort cleanup step, so nothing here may ever
+ * fail the surrounding command.
+ *
+ * Usage: `node ./scripts/kill-port.js 4021 4440`
+ */
+function killPorts() {
+    for (const port of parsePortArguments(process.argv.slice(2))) {
+        const listeningProcessIds = resolveListeningProcessIds(port);
+
+        if (listeningProcessIds.length === 0) {
+            console.log(`No process is listening on port ${port}.`);
+            continue;
+        }
+
+        for (const processId of listeningProcessIds) {
+            if (killProcess(processId)) {
+                console.log(`Freed port ${port} by stopping process ${processId}.`);
+            } else {
+                console.log(`Could not stop process ${processId} listening on port ${port}.`);
+            }
+        }
+    }
+}
+
+/**
+ * Reads the TCP ports from the command line arguments.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Raw command line arguments.
+ * @returns {Array<number>} Valid TCP ports.
+ */
+function parsePortArguments(argumentsList) {
+    return argumentsList.map((argument) => Number(argument)).filter(isPort);
+}
+
+/**
+ * Returns whether one value is a usable TCP port number.
+ *
+ * @param {number} value - Parsed command line argument.
+ * @returns {boolean} Whether the value can be freed.
+ */
+function isPort(value) {
+    return Number.isInteger(value) && value > 0 && value <= 65535;
+}
+
+/**
+ * Resolves the process ids currently listening on one TCP port.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolveListeningProcessIds(port) {
+    if (process.platform === 'win32') {
+        return resolveWindowsListeningProcessIds(port);
+    }
+
+    return resolvePosixListeningProcessIds(port);
+}
+
+/**
+ * Resolves listeners of one TCP port through the Windows `netstat` utility.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolveWindowsListeningProcessIds(port) {
+    const netstatResult = spawnSync('netstat', ['-a', '-n', '-o', '-p', 'TCP'], { encoding: 'utf8' });
+
+    if (typeof netstatResult.stdout !== 'string') {
+        return [];
+    }
+
+    return dedupeProcessIds(
+        netstatResult.stdout
+            .split(/\r?\n/u)
+            .filter((line) => line.includes('LISTENING'))
+            .map((line) => line.trim().split(/\s+/u))
+            .filter((columns) => columns.length >= 5 && isAddressOnPort(columns[1], port))
+            .map((columns) => Number(columns[columns.length - 1])),
+    );
+}
+
+/**
+ * Resolves listeners of one TCP port through the POSIX `lsof` utility.
+ *
+ * @param {number} port - TCP port to inspect.
+ * @returns {Array<number>} Process ids of the listeners.
+ */
+function resolvePosixListeningProcessIds(port) {
+    const listOpenFilesResult = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+        encoding: 'utf8',
+    });
+
+    if (typeof listOpenFilesResult.stdout !== 'string') {
+        return [];
+    }
+
+    return dedupeProcessIds(listOpenFilesResult.stdout.split(/\s+/u).map((value) => Number(value)));
+}
+
+/**
+ * Returns whether one `netstat` local address belongs to the inspected port.
+ *
+ * The address is printed as `0.0.0.0:4440`, `127.0.0.1:4440`, or `[::]:4440`.
+ *
+ * @param {string} address - Local address column of one `netstat` row.
+ * @param {number} port - TCP port to inspect.
+ * @returns {boolean} Whether the row belongs to the port.
+ */
+function isAddressOnPort(address, port) {
+    return address.endsWith(`:${port}`);
+}
+
+/**
+ * Keeps only distinct process ids which are safe to stop.
+ *
+ * The current process and its parent are excluded so that freeing a port can never stop the build,
+ * the test runner, or the shell which started them.
+ *
+ * @param {ReadonlyArray<number>} processIds - Raw process ids.
+ * @returns {Array<number>} Distinct stoppable process ids.
+ */
+function dedupeProcessIds(processIds) {
+    return Array.from(
+        new Set(
+            processIds.filter(
+                (processId) =>
+                    Number.isInteger(processId) &&
+                    processId > 0 &&
+                    processId !== process.pid &&
+                    processId !== process.ppid,
+            ),
+        ),
+    );
+}
+
+/**
+ * Stops one process which holds an inspected port.
+ *
+ * @param {number} processId - Process id of the listener.
+ * @returns {boolean} Whether the process was stopped.
+ */
+function killProcess(processId) {
+    if (process.platform === 'win32') {
+        return spawnSync('taskkill', ['/F', '/PID', String(processId)], { stdio: 'ignore' }).status === 0;
+    }
+
+    try {
+        process.kill(processId, 'SIGKILL');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+killPorts();

package/apps/agents-server/scripts/run-e2e-tests.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('node:path');
-const { runNpm } = require('./run-npm.js');
+const { runNpm, startNpm, startNpmWithCollectedOutput } = require('./run-npm.js');
 
 /**
  * Root directory of the Agents Server app.
@@ -11,17 +11,30 @@ const APP_ROOT = path.resolve(__dirname, '..');
 /**
  * Runs the complete Agents Server E2E verification flow.
  *
- * App linting remains an explicit test phase. The production build then skips
- * its duplicate lint pass, and Playwright starts that same build instead of
- * compiling a second `.next-e2e` output through `webServer`.
+ * App linting remains an explicit test phase, but it reads only the sources and therefore does not
+ * depend on the production build. Both run at the same time and the flow waits for the slower one,
+ * which is always the build. The build then skips its duplicate lint pass, and Playwright starts
+ * that same build instead of compiling a second `.next-e2e` output through `webServer`.
  */
-function runE2eTests() {
+async function runE2eTests() {
     const commandOptions = {
         cwd: APP_ROOT,
     };
 
-    runNpm(['run', 'lint'], commandOptions);
-    runNpm(['run', 'build-e2e', '--', '--no-lint'], commandOptions);
+    const lintCompletion = startNpmWithCollectedOutput(['run', 'lint'], commandOptions);
+    const buildStatus = await startNpm(['run', 'build-e2e', '--', '--no-lint'], commandOptions);
+    const lintResult = await lintCompletion;
+
+    console.log('\n> lint (ran next to the production build)\n');
+    process.stdout.write(lintResult.output);
+
+    if (lintResult.status !== 0) {
+        process.exit(lintResult.status);
+    }
+
+    if (buildStatus !== 0) {
+        process.exit(buildStatus);
+    }
 
     runNpm(['exec', '--', 'playwright', 'test', ...process.argv.slice(2)], {
         ...commandOptions,
@@ -31,4 +44,4 @@ function runE2eTests() {
     });
 }
 
-runE2eTests();
+void runE2eTests();