registry / peaks-loop / 3.0.2

peaks-loop@3.0.2

Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration

AI Security Review

scanned 1d ago · by lpm-firewall-ai

The package mutates AI-agent control surfaces during npm lifecycle installation. The behavior is disclosed in docs and aligned with the package's AI workflow-tool purpose, but it is still unconsented install-time agent/skill deployment across user home IDE directories.

Static reason

High-risk behavior combination matched malicious policy.

Trigger

npm install/npm install -g runs postinstall

Impact

Package-supplied prompts/agents can influence future AI assistant behavior in supported IDEs

Mechanism

lifecycle AI-agent skill/agent installation

Attack narrative

On package installation, npm runs scripts/install-skills.mjs. That script resolves user-home AI IDE directories and installs bundled skills, output styles, and agents into them, including Claude/Codex/Cursor/Trae-style control surfaces. These files can later steer AI agent workflows without the user invoking the peaks CLI at that moment.

Rationale

Source inspection confirms concrete install-time AI-agent control-surface mutation via package lifecycle, which LPM policy treats as blockable even though it is package-aligned and lacks exfiltration. Other high-risk primitives reviewed appear user-invoked CLI functionality rather than hidden malware. Product guard normalized a non-low false-positive publish_block request to warn-only suspicious.

Evidence

package.jsonscripts/install-skills.mjsagents/karpathy-reviewer.mdskills/peaks-solo/SKILL.mdskills/peaks-ui/SKILL.mddist/src/shared/process.jsdist/src/services/upgrade/upgrade-service.js~/.claude/skills~/.claude/output-styles~/.claude/agents~/.codex/skills~/.codex/output-styles~/.codex/agents~/.cursor/skills~/.cursor/output-styles~/.trae/skills~/.trae/output-styles

Decision evidence

public snapshot

AI called this Suspicious at 86.0% confidence as Dangerous Capability with medium false-positive risk.

Evidence for block

package.json postinstall runs scripts/install-skills.mjs on install
scripts/install-skills.mjs installs package-supplied skills/output-styles/agents into ~/.claude, ~/.codex, ~/.cursor, ~/.trae, ~/.qoder, etc.
scripts/install-skills.mjs has explicit policy goal: npm install -g should symlink skills to every supported AI IDE
agents/karpathy-reviewer.md says postinstall copies it to ~/.claude/agents/karpathy-reviewer.md on every install
Bundled skills contain agent workflow instructions that change AI assistant behavior, not just passive library data

Evidence against

Install script uses marker files, symlink/copy checks, path validation, and atomic writes
No credential exfiltration or remote payload download found in inspected install script
Network URLs observed are repository/readme/registry/localhost documentation links, not exfiltration endpoints
Child_process usage in dist appears tied to user-invoked CLI/audit/git workflows

Behavioral surface

Source

ChildProcessCryptoDynamicRequireEnvironmentVarsFilesystemShell

Supply chain

HighEntropyStringsUrlStrings

ManifestNo manifest risk signals triggered.

scanned 443 file(s), 2.89 MB of source, external domains: api.anthropic.com, api.example.com, api.openai.com, github.com, gitlab.com, reactbits.dev, www.google.com, www.pulsemcp.com

Source & flagged code

6 flagged

package.jsonView file

Lines 29-69json

29 "scripts/sync-version.mjs",

30 "scripts/install-skills.mjs",

31 "scripts/watch.mjs",

32 "skills/**",

33 "!skills/**/test-prompts.json",

34 "!skills/**/.DS_Store",

35 "output-styles/**",

36 "agents/**",

37 "schemas/*.json",

38 ".claude-plugin/**",

39 "README.md",

40 "README-en.md",

41 "CHANGELOG.md",

42 "LICENSE"

43 ],

44 "scripts": {

45 "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",

46 "prepack": "npm run build",

47 "prepublishOnly": "node scripts/prepublish-build.mjs",

48 "prepublish": "node ./scripts/sync-version.mjs",

49 "postinstall": "node ./scripts/install-skills.mjs",

High

Install Time Lifecycle Scripts

Package defines install-time lifecycle scripts.

package.jsonView on unpkg · L49

50 "predev": "node ./scripts/sync-version.mjs",

51 "dev": "tsx src/cli/index.ts",

52 "dev:watch": "node ./scripts/watch.mjs",

53 "pretest": "node ./scripts/sync-version.mjs",

54 "test": "node ./scripts/lint/silent-warning-detector.mjs && vitest run",

55 "lint:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",

56 "test:race": "vitest run --no-file-parallelism tests/unit/g8-shared-channel.test.ts tests/unit/dispatch-record-writer.test.ts tests/unit/services/retrospective/heartbeat.test.ts tests/unit/cli/commands/share-commands.test.ts",

57 "test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/replay tests/unit/fixture",

58 "fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",

59 "test:coverage": "vitest run --coverage",

60 "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",

61 "pretest:coverage": "node ./scripts/pretest-coverage.mjs",

62 "schema:generate": "node scripts/generate-context-schema.mjs",

63 "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",

64 "mut:run": "peaks mut run --project . --out mut-report.json",

65 "mut:scan": "peaks mut asserts --in mut-report.json",

66 "audit:prose-ratio": "peaks audit prose-ratio --project ."

67 },

68 "engines": {

69 "node": ">=20.0.0"

dist/src/shared/process.jsView file

Lines 1-13javascript

1import { execFile } from 'node:child_process';

2export async function execCommand(command, args, options) {

High

Child Process

Package source references child process execution.

dist/src/shared/process.jsView on unpkg · L1

3 return new Promise((resolve, reject) => {

4 execFile(command, args, { cwd: options?.cwd, env: options?.env }, (error, stdout) => {

5 if (error) {

6 reject(error);

7 return;

8 }

9 resolve(stdout.trim());

10 });

11 });

12}

dist/src/services/upgrade/upgrade-service.jsView file

Lines 131-171javascript

131function read1xVersion(cwd) {

132 const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';

133 if (home.length === 0)

134 return null;

135 const global = join(home, '.peaks', 'config.json');

136 if (!existsSync(global))

137 return null;

138 try {

139 const raw = JSON.parse(readFileSync(global, 'utf8'));

140 if (typeof raw.version === 'string')

141 return raw.version;

142 }

143 catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)

144 // ignore

145 }

146 return null;

147}

148function runStep(peaksBin, name, args, timeoutMs = 60_000) {

149 const start = Date.now();

150 // The global `peaks` shim is a `/bin/sh` symlink script (the

151 // npm install postinstall creates `peaks` → `peaks.sh` on

152 // Windows). cmd.exe (the default Windows shell) cannot run

153 // `.sh` scripts directly, so the shim fails with "unknown

High

Shell

Package source references shell execution.

dist/src/services/upgrade/upgrade-service.jsView on unpkg · L151

154 // command 'migrate'" etc. The fix: prefer the local node

155 // binary + the peaks.js script path. The umbrella resolves

156 // the script path at startup; only falls back to `peaks` if

157 // no script path is available (Unix-only).

158 let command;

159 let spawnArgs;

160 if (peaksBin.includes('\\') || peaksBin.includes('/')) {

161 // peaksBin is a real path (e.g. /c/.../bin/peaks.js);

162 // invoke directly via node.

163 command = process.execPath;

164 spawnArgs = [peaksBin, ...args];

165 }

166 else {

167 // peaksBin is just "peaks" — best-effort shell exec.

168 command = peaksBin;

169 spawnArgs = args;

170 }

171 try {

dist/src/cli/commands/loop-eval-commands.jsView file

Lines 458-498javascript

458 cycles: result.cycles,

459 finalReport: result.finalReport,

460 finalReportCode,

461 summary: result.summary

462 }, nextActionsForCode(result.code, r2, sid, result.summary)), options.json);

463 process.exitCode = exitCode;

464 }

465 catch (error) {

466 printResult(io, fail('loop.run', 'RUN_FAILED', getErrorMessage(error), { rid }, ['Verify the rid and session binding.']), options.json);

467 process.exitCode = 1;

468 }

469 });

470}

471/** Test seam: pick the next cycle-N.json number for capture-score

472 * writes. The run-driver also writes to the same dir; the next

473 * index = max(prior)+1, or 1. */

474function nextEvalCaptureIndex(projectRoot, sid, rid) {

475 const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');

476 if (!existsSync(dir))

477 return 1;

478 // eslint-disable-next-line @typescript-eslint/no-var-requires

479 const fs = require('node:fs');

480 let entries;

Medium

Dynamic Require

Package source references dynamic require/import behavior.

dist/src/cli/commands/loop-eval-commands.jsView on unpkg · L478

481 try {

482 entries = fs.readdirSync(dir);

483 }

484 catch {

485 return 1;

486 }

487 let best = null;

488 for (const entry of entries) {

489 const m = entry.match(/^cycle-(\d+)\.json$/);

490 if (m === null)

491 continue;

492 const n = parseInt(m[1] ?? '0', 10);

493 if (best === null || n > best)

494 best = n;

495 }

496 return (best ?? 0) + 1;

497}

498/** Map a run-driver code to a process exit code. */

scripts/install-skills.mjsView file

Lines 1-21javascript

1#!/usr/bin/env node

2import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';

3import { spawnSync } from 'node:child_process';

Critical

Ai Agent Control Hijack

Install-time source drops package-supplied AI-agent/MCP control files or instructions.

scripts/install-skills.mjsView on unpkg · L1

4import { createHash, randomUUID } from 'node:crypto';

5import { homedir } from 'node:os';

6import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';

7import { fileURLToPath, pathToFileURL } from 'node:url';

9function getPathStats(path) {

10 try {

11 return lstatSync(path);

12 } catch {

13 return null;

14 }

15}

17function isBrokenSymlink(stats, targetPath) {

18 return stats.isSymbolicLink() && !existsSync(targetPath);

19}

21function validateManagedMarkerPath(markerPath) {

dist/src/cli/commands/playwright-commands.jsView file

Lines 7-47javascript

7 * dir. This command:

8 *

9 * 1. `peaks playwright start [--port N] [--browser <chromium|firefox|webkit>]`

10 * Allocates a unique port (default 8931; walks 8931→8949 if busy),

11 * spawns `npx playwright-mcp@latest` with the chosen port, and

12 * writes a session file at

13 * `<projectRoot>/.peaks/_runtime/playwright-sessions/<terminal-id>.json`

14 * with `{ port, userDataDir, startedAt, pid }`.

15 *

16 * 2. `peaks playwright ls` — lists all running sessions (reads

17 * `.peaks/_runtime/playwright-sessions/*.json`).

18 *

19 * 3. `peaks playwright stop [--terminal <id>]` — best-effort kills

20 * the server process and removes the session file.

21 *

22 * Terminal ID derivation (R4):

23 * 1. process.env.TERM_SESSION_ID (macOS Terminal / iTerm2)

24 * 2. process.env.WT_SESSION (Windows Terminal)

25 * 3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')

26 *

27 * The CLI does NOT bundle `playwright-mcp`; it shells out to

28 * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle

29 * orchestrator, not the install medium.

30 */

31import { createHash } from 'node:crypto';

32import { spawn } from 'node:child_process';

33import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';

High

Runtime Package Install

Package source invokes a package manager install command at runtime.

dist/src/cli/commands/playwright-commands.jsView on unpkg · L27

34import { join, dirname, resolve } from 'node:path';

35import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';

36import { getErrorMessage } from '../cli-helpers.js';

37import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';

38export const DEFAULT_PORT = 8931;

39export const MAX_PORT = 8949;

40const BROWSERS = ['chromium', 'firefox', 'webkit'];

41export const PLAYWRIGHT_SESSIONS_DIR = 'playwright-sessions';

42export function playwrightSessionsDir(projectRoot) {

43 return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);

44}

45export function sessionFilePath(projectRoot, terminalId) {

46 return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);

47}

Source & flagged code

6 flagged · loading source

package.jsonView file

•scripts.postinstall = node ./scripts/install-skills.mjs

High

Install Time Lifecycle Scripts

Package defines install-time lifecycle scripts.

package.jsonView on unpkg

dist/src/shared/process.jsView file

1import { execFile } from 'node:child_process'; L2: export async function execCommand(command, args, options) {

High

Child Process

Package source references child process execution.

dist/src/shared/process.jsView on unpkg · L1

dist/src/services/upgrade/upgrade-service.jsView file

151// npm install postinstall creates `peaks` → `peaks.sh` on L152: // Windows). cmd.exe (the default Windows shell) cannot run L153: // `.sh` scripts directly, so the shim fails with "unknown

High

Shell

Package source references shell execution.

dist/src/services/upgrade/upgrade-service.jsView on unpkg · L151

dist/src/cli/commands/loop-eval-commands.jsView file

478// eslint-disable-next-line @typescript-eslint/no-var-requires L479: const fs = require('node:fs'); L480: let entries;

Medium

Dynamic Require

Package source references dynamic require/import behavior.

dist/src/cli/commands/loop-eval-commands.jsView on unpkg · L478

scripts/install-skills.mjsView file

1Install-time AI-agent control hijack evidence: L1: #!/usr/bin/env node L2: import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, symlinkSync, un... L3: import { spawnSync } from 'node:child_process'; ... L291: fchmodSync(fd, 0o600); L292: writeFileSync(fd, content, 'utf8'); L293: const writeFd = fd; ... L320: fchmodSync(fd, 0o600); L321: writeFileSync(fd, content, 'utf8'); L322: const writeFd = fd; ... L372: * cannot import the TS service at runtime. The dispatch: L373: * - Look for `.claude`, `.trae`, `.codex`, `.cursor`, `.qoder`, L374: * `.tongyi-lingma` in the project root in that insertion order Payload evidence from schemas/mcp-install-spec.schema.json: L1: { L2: "$schema": "https://json-schema.org/draft/2020-12/schema", L3: "title": "Peaks MCP Install Spec", ... L25: "items": { "type": "string" }, L26: "description": "Required env var names. Values are sourced from process.env at runtime and written as ${VAR} placeholders into settings.json." L27: }

Critical

Ai Agent Control Hijack

Install-time source drops package-supplied AI-agent/MCP control files or instructions.

scripts/install-skills.mjsView on unpkg · L1

dist/src/cli/commands/playwright-commands.jsView file

27* The CLI does NOT bundle `playwright-mcp`; it shells out to L28: * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle L29: * orchestrator, not the install medium. ... L31: import { createHash } from 'node:crypto'; L32: import { spawn } from 'node:child_process'; L33: import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';

High

Runtime Package Install

Package source invokes a package manager install command at runtime.

dist/src/cli/commands/playwright-commands.jsView on unpkg · L27

Findings

1 Critical4 High3 Medium5 Low

CriticalAi Agent Control Hijackscripts/install-skills.mjs

HighInstall Time Lifecycle Scriptspackage.json

HighChild Processdist/src/shared/process.js

HighShelldist/src/services/upgrade/upgrade-service.js

HighRuntime Package Installdist/src/cli/commands/playwright-commands.js

MediumDynamic Requiredist/src/cli/commands/loop-eval-commands.js

MediumEnvironment Vars

MediumStructural Risk Force Deep Review

LowNon Install Lifecycle Scripts

LowScripts Present

LowFilesystem

LowHigh Entropy Strings

LowUrl Strings

Source & flagged code

6 flagged

package.jsonView file

Lines 29-69json

29 "scripts/sync-version.mjs",

30 "scripts/install-skills.mjs",

31 "scripts/watch.mjs",

32 "skills/**",

33 "!skills/**/test-prompts.json",

34 "!skills/**/.DS_Store",

35 "output-styles/**",

36 "agents/**",

37 "schemas/*.json",

38 ".claude-plugin/**",

39 "README.md",

40 "README-en.md",

41 "CHANGELOG.md",

42 "LICENSE"

43 ],

44 "scripts": {

45 "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",

46 "prepack": "npm run build",

47 "prepublishOnly": "node scripts/prepublish-build.mjs",

48 "prepublish": "node ./scripts/sync-version.mjs",

49 "postinstall": "node ./scripts/install-skills.mjs",

High

Install Time Lifecycle Scripts

Package defines install-time lifecycle scripts.

package.jsonView on unpkg · L49

50 "predev": "node ./scripts/sync-version.mjs",

51 "dev": "tsx src/cli/index.ts",

52 "dev:watch": "node ./scripts/watch.mjs",

53 "pretest": "node ./scripts/sync-version.mjs",

54 "test": "node ./scripts/lint/silent-warning-detector.mjs && vitest run",

55 "lint:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",

57 "test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/replay tests/unit/fixture",

58 "fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",

59 "test:coverage": "vitest run --coverage",

60 "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",

61 "pretest:coverage": "node ./scripts/pretest-coverage.mjs",

62 "schema:generate": "node scripts/generate-context-schema.mjs",

63 "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",

64 "mut:run": "peaks mut run --project . --out mut-report.json",

65 "mut:scan": "peaks mut asserts --in mut-report.json",

66 "audit:prose-ratio": "peaks audit prose-ratio --project ."

67 },

68 "engines": {

69 "node": ">=20.0.0"

dist/src/shared/process.jsView file

Lines 1-13javascript

1import { execFile } from 'node:child_process';

2export async function execCommand(command, args, options) {

High

Child Process

Package source references child process execution.

dist/src/shared/process.jsView on unpkg · L1

3 return new Promise((resolve, reject) => {

4 execFile(command, args, { cwd: options?.cwd, env: options?.env }, (error, stdout) => {

5 if (error) {

6 reject(error);

7 return;

8 }

9 resolve(stdout.trim());

10 });

11 });

12}

dist/src/services/upgrade/upgrade-service.jsView file

Lines 131-171javascript

131function read1xVersion(cwd) {

132 const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';

133 if (home.length === 0)

134 return null;

135 const global = join(home, '.peaks', 'config.json');

136 if (!existsSync(global))

137 return null;

138 try {

139 const raw = JSON.parse(readFileSync(global, 'utf8'));

140 if (typeof raw.version === 'string')

141 return raw.version;

142 }

143 catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)

144 // ignore

145 }

146 return null;

147}

148function runStep(peaksBin, name, args, timeoutMs = 60_000) {

149 const start = Date.now();

150 // The global `peaks` shim is a `/bin/sh` symlink script (the

151 // npm install postinstall creates `peaks` → `peaks.sh` on

152 // Windows). cmd.exe (the default Windows shell) cannot run

153 // `.sh` scripts directly, so the shim fails with "unknown

High

Shell

Package source references shell execution.

dist/src/services/upgrade/upgrade-service.jsView on unpkg · L151

154 // command 'migrate'" etc. The fix: prefer the local node

155 // binary + the peaks.js script path. The umbrella resolves

156 // the script path at startup; only falls back to `peaks` if

157 // no script path is available (Unix-only).

158 let command;

159 let spawnArgs;

160 if (peaksBin.includes('\\') || peaksBin.includes('/')) {

161 // peaksBin is a real path (e.g. /c/.../bin/peaks.js);

162 // invoke directly via node.

163 command = process.execPath;

164 spawnArgs = [peaksBin, ...args];

165 }

166 else {

167 // peaksBin is just "peaks" — best-effort shell exec.

168 command = peaksBin;

169 spawnArgs = args;

170 }

171 try {

dist/src/cli/commands/loop-eval-commands.jsView file

Lines 458-498javascript

458 cycles: result.cycles,

459 finalReport: result.finalReport,

460 finalReportCode,

461 summary: result.summary

462 }, nextActionsForCode(result.code, r2, sid, result.summary)), options.json);

463 process.exitCode = exitCode;

464 }

465 catch (error) {

466 printResult(io, fail('loop.run', 'RUN_FAILED', getErrorMessage(error), { rid }, ['Verify the rid and session binding.']), options.json);

467 process.exitCode = 1;

468 }

469 });

470}

471/** Test seam: pick the next cycle-N.json number for capture-score

472 * writes. The run-driver also writes to the same dir; the next

473 * index = max(prior)+1, or 1. */

474function nextEvalCaptureIndex(projectRoot, sid, rid) {

475 const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');

476 if (!existsSync(dir))

477 return 1;

478 // eslint-disable-next-line @typescript-eslint/no-var-requires

479 const fs = require('node:fs');

480 let entries;

Medium

Dynamic Require

Package source references dynamic require/import behavior.

dist/src/cli/commands/loop-eval-commands.jsView on unpkg · L478

481 try {

482 entries = fs.readdirSync(dir);

483 }

484 catch {

485 return 1;

486 }

487 let best = null;

488 for (const entry of entries) {

489 const m = entry.match(/^cycle-(\d+)\.json$/);

490 if (m === null)

491 continue;

492 const n = parseInt(m[1] ?? '0', 10);

493 if (best === null || n > best)

494 best = n;

495 }

496 return (best ?? 0) + 1;

497}

498/** Map a run-driver code to a process exit code. */

scripts/install-skills.mjsView file

Lines 1-21javascript

1#!/usr/bin/env node

3import { spawnSync } from 'node:child_process';

Critical

Ai Agent Control Hijack

Install-time source drops package-supplied AI-agent/MCP control files or instructions.

scripts/install-skills.mjsView on unpkg · L1

4import { createHash, randomUUID } from 'node:crypto';

5import { homedir } from 'node:os';

6import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';

7import { fileURLToPath, pathToFileURL } from 'node:url';

9function getPathStats(path) {

10 try {

11 return lstatSync(path);

12 } catch {

13 return null;

14 }

15}

17function isBrokenSymlink(stats, targetPath) {

18 return stats.isSymbolicLink() && !existsSync(targetPath);

19}

21function validateManagedMarkerPath(markerPath) {

dist/src/cli/commands/playwright-commands.jsView file

Lines 7-47javascript

7 * dir. This command:

8 *

9 * 1. `peaks playwright start [--port N] [--browser <chromium|firefox|webkit>]`

10 * Allocates a unique port (default 8931; walks 8931→8949 if busy),

11 * spawns `npx playwright-mcp@latest` with the chosen port, and

12 * writes a session file at

13 * `<projectRoot>/.peaks/_runtime/playwright-sessions/<terminal-id>.json`

14 * with `{ port, userDataDir, startedAt, pid }`.

15 *

16 * 2. `peaks playwright ls` — lists all running sessions (reads

17 * `.peaks/_runtime/playwright-sessions/*.json`).

18 *

19 * 3. `peaks playwright stop [--terminal <id>]` — best-effort kills

20 * the server process and removes the session file.

21 *

22 * Terminal ID derivation (R4):

23 * 1. process.env.TERM_SESSION_ID (macOS Terminal / iTerm2)

24 * 2. process.env.WT_SESSION (Windows Terminal)

25 * 3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')

26 *

27 * The CLI does NOT bundle `playwright-mcp`; it shells out to

28 * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle

29 * orchestrator, not the install medium.

30 */

31import { createHash } from 'node:crypto';

32import { spawn } from 'node:child_process';

33import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';

High

Runtime Package Install

Package source invokes a package manager install command at runtime.

dist/src/cli/commands/playwright-commands.jsView on unpkg · L27

34import { join, dirname, resolve } from 'node:path';

35import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';

36import { getErrorMessage } from '../cli-helpers.js';

37import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';

38export const DEFAULT_PORT = 8931;

39export const MAX_PORT = 8949;

40const BROWSERS = ['chromium', 'firefox', 'webkit'];

41export const PLAYWRIGHT_SESSIONS_DIR = 'playwright-sessions';

42export function playwrightSessionsDir(projectRoot) {

43 return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);

44}

45export function sessionFilePath(projectRoot, terminalId) {

46 return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);

47}