@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/ai/sync.js

@@ -0,0 +1,256 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { claudeDenyRules, codexRules, parsePolicy } from "./policy.js";
+import { claudeAgentMarkdown, claudeMcpEntry, codexAgentToml, codexMcpTable, isGeneratedText, parseAgent, skillProblems, withMarkdownBanner, GENERATED_MARKER, } from "./render.js";
+import { exampleKitOutputs, exampleLabs } from "./examples.js";
+import { loadKit } from "./kit.js";
+export const CODEX_PROJECT_DOC_BYTES = 32 * 1024;
+export const AGENTS_MD_LIMIT = 24 * 1024;
+const REGENERATE = "bun run ai:sync";
+function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walk(path));
+        else if (entry.isFile())
+            out.push(path);
+    }
+    return out.sort();
+}
+const posix = (path) => path.split(sep).join("/");
+export function agentsMdFiles(root, commands) {
+    try {
+        const result = commands.run({ command: "git", args: ["ls-files", "-co", "--exclude-standard", "--", "AGENTS.md", "**/AGENTS.md"], cwd: root, timeoutMs: 15_000 });
+        if (result.code !== 0)
+            throw new Error(result.stderr || `git ls-files exited ${result.code}`);
+        return [...new Set(result.stdout.split("\n").filter(Boolean))].filter((path) => existsSync(join(root, path))).sort();
+    }
+    catch {
+        return existsSync(join(root, "AGENTS.md")) ? ["AGENTS.md"] : [];
+    }
+}
+export function measureAgentsMd(root, commands) {
+    const files = agentsMdFiles(root, commands).map((path) => ({ path, bytes: statSync(join(root, path)).size }));
+    const totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
+    let longestChain = { path: ".", bytes: 0 };
+    for (const file of files) {
+        const dir = posix(dirname(file.path));
+        const bytes = files
+            .filter((other) => {
+            const otherDir = posix(dirname(other.path));
+            return otherDir === "." || dir === otherDir || dir.startsWith(otherDir + "/");
+        })
+            .reduce((sum, other) => sum + other.bytes, 0);
+        if (bytes > longestChain.bytes)
+            longestChain = { path: dir, bytes };
+    }
+    return { files, totalBytes, longestChain };
+}
+export function plannedOutputs(root, commands) {
+    const ai = join(root, "ai");
+    const outputs = new Map();
+    const problems = [];
+    const notes = [];
+    const read = (path) => readFileSync(join(root, path), "utf8");
+    const skillsDir = join(ai, "skills");
+    const skills = existsSync(skillsDir) ? readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()) : [];
+    for (const skill of skills) {
+        const dir = join(skillsDir, skill.name);
+        const skillFile = join(dir, "SKILL.md");
+        if (!existsSync(skillFile)) {
+            problems.push(`ai/skills/${skill.name} has no SKILL.md`);
+            continue;
+        }
+        problems.push(...skillProblems(skill.name, readFileSync(skillFile, "utf8")).map((problem) => `ai/skills/${problem}`));
+        for (const file of walk(dir)) {
+            const rel = posix(relative(dir, file));
+            const source = posix(relative(root, file));
+            let content = readFileSync(file, "utf8");
+            if (rel === "SKILL.md")
+                content = withMarkdownBanner(content, `from ${source}; edit the source and run ${REGENERATE}`);
+            outputs.set(`.claude/skills/${skill.name}/${rel}`, content);
+            outputs.set(`.agents/skills/${skill.name}/${rel}`, content);
+        }
+    }
+    const agentsDir = join(ai, "agents");
+    for (const file of existsSync(agentsDir) ? readdirSync(agentsDir).filter((name) => /\.ya?ml$/.test(name)).sort() : []) {
+        const source = `ai/agents/${file}`;
+        try {
+            const spec = parseAgent(read(source), source);
+            if (`${spec.name}` !== file.replace(/\.ya?ml$/, ""))
+                problems.push(`${source}: name "${spec.name}" must equal the file name`);
+            const banner = `from ${source}; edit the source and run ${REGENERATE}`;
+            outputs.set(`.claude/agents/${spec.name}.md`, claudeAgentMarkdown(spec, banner));
+            outputs.set(`.codex/agents/${spec.name}.toml`, codexAgentToml(spec, banner));
+        }
+        catch (error) {
+            problems.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    let deny = [];
+    if (existsSync(join(ai, "policy.json"))) {
+        try {
+            const policy = parsePolicy(read("ai/policy.json"), "ai/policy.json");
+            deny = claudeDenyRules(policy);
+            outputs.set(".codex/rules/safety.rules", codexRules(policy, `from ai/policy.json; edit the source and run ${REGENERATE}`));
+        }
+        catch (error) {
+            problems.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (existsSync(join(ai, "claude", "settings.json"))) {
+        const settings = JSON.parse(read("ai/claude/settings.json"));
+        settings.permissions = { ...settings.permissions, deny: [...new Set([...(settings.permissions?.deny ?? []), ...deny])] };
+        outputs.set(".claude/settings.json", JSON.stringify(settings, null, 2) + "\n");
+    }
+    if (existsSync(join(ai, "codex", "hooks.json")))
+        outputs.set(".codex/hooks.json", JSON.stringify(JSON.parse(read("ai/codex/hooks.json")), null, 2) + "\n");
+    const servers = existsSync(join(ai, "mcp.json"))
+        ? (JSON.parse(read("ai/mcp.json")).mcpServers ?? {})
+        : {};
+    if (Object.keys(servers).length)
+        outputs.set(".mcp.json", JSON.stringify({ mcpServers: Object.fromEntries(Object.entries(servers).map(([name, server]) => [name, claudeMcpEntry(server)])) }, null, 2) + "\n");
+    const codexBase = existsSync(join(ai, "codex", "config.toml")) ? read("ai/codex/config.toml").trimEnd() : "";
+    if (codexBase || Object.keys(servers).length) {
+        const tables = Object.entries(servers).map(([name, server]) => codexMcpTable(name, server).trimEnd());
+        outputs.set(".codex/config.toml", [`# ${GENERATED_MARKER}: from ai/codex/config.toml and ai/mcp.json; edit the sources and run ${REGENERATE}`, codexBase, ...tables]
+            .filter(Boolean)
+            .join("\n\n") + "\n");
+    }
+    for (const agents of agentsMdFiles(root, commands)) {
+        const claude = posix(join(dirname(agents), "CLAUDE.md"));
+        outputs.set(claude, "@AGENTS.md\n");
+    }
+    if (exampleLabs(root).length) {
+        try {
+            for (const [rel, content] of exampleKitOutputs(root, loadKit()))
+                outputs.set(rel, content);
+        }
+        catch (error) {
+            problems.push(`the consumer kit for the examples: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!skills.length)
+        notes.push("ai/skills has no skills");
+    return { outputs, problems, notes };
+}
+function staleOutputs(root, outputs) {
+    const stale = [];
+    const places = ["", ...exampleLabs(root).map((example) => `examples/${example}/`)];
+    for (const base of places.flatMap((place) => [`${place}.claude/skills`, `${place}.agents/skills`])) {
+        const dir = join(root, base);
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const skillFile = join(dir, entry.name, "SKILL.md");
+            if (!existsSync(skillFile) || !isGeneratedText(readFileSync(skillFile, "utf8")))
+                continue;
+            for (const file of walk(join(dir, entry.name))) {
+                const rel = posix(relative(root, file));
+                if (!outputs.has(rel))
+                    stale.push(rel);
+            }
+        }
+    }
+    for (const [base, extension] of places.flatMap((place) => [
+        [`${place}.claude/agents`, ".md"],
+        [`${place}.codex/agents`, ".toml"],
+    ])) {
+        const dir = join(root, base);
+        if (!existsSync(dir))
+            continue;
+        for (const name of readdirSync(dir).filter((file) => file.endsWith(extension))) {
+            const rel = `${base}/${name}`;
+            if (!outputs.has(rel) && isGeneratedText(readFileSync(join(root, rel), "utf8")))
+                stale.push(rel);
+        }
+    }
+    return stale;
+}
+function guardProblems(root, commands) {
+    const script = join(root, "ai", "guard.sh");
+    const module = join(root, "ai", "guard.mjs");
+    if (!existsSync(script) || !existsSync(module))
+        return { problems: [], notes: [] };
+    const problems = [];
+    const run = (command, args, input) => {
+        try {
+            return commands.run({ command, args, input, timeoutMs: 15_000 });
+        }
+        catch (error) {
+            return { code: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    const self = run(process.execPath, [module, "--self-test"]);
+    if (self.code !== 0)
+        problems.push(`ai/guard.mjs --self-test failed:\n${self.stderr.trim()}`);
+    const payload = (command) => JSON.stringify({ tool_name: "Bash", tool_input: { command } });
+    const blocked = run(script, [], payload("git push origin main"));
+    if (blocked.code !== 2 || !/Blocked by ai\/guard\.sh/.test(blocked.stderr))
+        problems.push(`ai/guard.sh did not block "git push origin main" with exit 2 (exit ${blocked.code}): ${blocked.stderr.trim()}`);
+    const allowed = run(script, [], payload("git status"));
+    if (allowed.code !== 0)
+        problems.push(`ai/guard.sh blocked "git status" (exit ${allowed.code}): ${allowed.stderr.trim()}`);
+    return { problems, notes: [self.stdout.trim()].filter(Boolean) };
+}
+export function syncRepository(root, commands, options = {}) {
+    const { outputs, problems, notes } = plannedOutputs(root, commands);
+    const changes = [];
+    for (const [path, content] of outputs) {
+        const file = join(root, path);
+        const current = existsSync(file) ? readFileSync(file, "utf8") : undefined;
+        if (current === content)
+            continue;
+        changes.push({ path, action: "write" });
+        if (!options.check) {
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, content);
+        }
+    }
+    for (const path of staleOutputs(root, outputs)) {
+        changes.push({ path, action: "delete" });
+        if (!options.check)
+            rmSync(join(root, path));
+    }
+    if (!options.check) {
+        for (const base of [".claude/skills", ".agents/skills"]) {
+            const dir = join(root, base);
+            if (!existsSync(dir))
+                continue;
+            for (const entry of readdirSync(dir, { withFileTypes: true }))
+                if (entry.isDirectory() && walk(join(dir, entry.name)).length === 0)
+                    rmSync(join(dir, entry.name), { recursive: true });
+        }
+    }
+    const guard = guardProblems(root, commands);
+    problems.push(...guard.problems);
+    notes.push(...guard.notes);
+    const agentsMd = measureAgentsMd(root, commands);
+    if (agentsMd.longestChain.bytes > AGENTS_MD_LIMIT)
+        problems.push(`The AGENTS.md files Codex reads from ${agentsMd.longestChain.path} total ${agentsMd.longestChain.bytes} bytes; keep every chain under ${AGENTS_MD_LIMIT} (Codex budget ${CODEX_PROJECT_DOC_BYTES})`);
+    return { root, changes, problems, notes, agentsMd };
+}
+export function formatSyncReport(report, check) {
+    const lines = [];
+    for (const change of report.changes)
+        lines.push(`${check ? "drift" : change.action === "write" ? "wrote" : "deleted"}: ${change.path}${check && change.action === "delete" ? " (stale, would be deleted)" : ""}`);
+    for (const problem of report.problems)
+        lines.push(`problem: ${problem}`);
+    for (const note of report.notes)
+        lines.push(note);
+    lines.push(`AGENTS.md: ${report.agentsMd.files.length} files, ${report.agentsMd.totalBytes} bytes in total; longest chain ${report.agentsMd.longestChain.bytes} bytes (${report.agentsMd.longestChain.path}); Codex budget ${CODEX_PROJECT_DOC_BYTES}`);
+    if (check)
+        lines.push(report.changes.length || report.problems.length
+            ? `ai:check failed: ${report.changes.length} generated file(s) out of date, ${report.problems.length} problem(s). Run ${REGENERATE}.`
+            : "ai:check passed: generated AI files match ai/.");
+    else
+        lines.push(report.changes.length ? `ai:sync: ${report.changes.length} change(s).` : "ai:sync: everything up to date.");
+    return lines.join("\n");
+}

package/entrypoints/cli/src/bisect-command.d.ts

@@ -0,0 +1,4 @@
+import type { BisectRunReport, LabRuntime } from "@parity/product-lab/ports/driving";
+export declare const BISECT_USAGE = "Usage: product-lab bisect <previous> <current> [--change <key> | --row <id> --scenario <name>] [--runs <n>]\n                         [--max-probes <n>] [--budget <minutes>] [--out <dir>] [--dry-run] [--config lab.config.ts] [--json]\n\nFind where a regression came in. <previous> and <current> are two suite runs (their report directories or\nproduct-lab-suite.json), as `product-lab report compare` takes them: the scenario passed in the first and fails in the\nsecond. The components that differ are the axes: the lab's own commits (the app), or the published releases of a\nruntime or host between the two versions. Each probe runs the one scenario as its row ran it, every other component\nat its good value, and the ends are run again first: when they do not pass and fail as recorded, the regression did\nnot reproduce and nothing is halved. A recovery, an infrastructure failure, a change with no recorded cause, a change\nonly the combination carries, a binary or an added component is refused by name.\n  --change <key>        the change to bisect, by its key in `report compare` (needed when the compare finds several)\n  --row <id>            or name it by row and scenario\n  --scenario <name>\n  --runs <n>            runs per probe (default 2, at most 5); they must agree, or the scenario is flaky there and the\n                        bisect stops\n  --max-probes <n>      probes besides the ends (default enough to halve, and two to step past untestable values)\n  --budget <minutes>    start no probe after this long\n  --out <dir>           where product-lab-bisect.json, summary.md and each probe's records go\n                        (default .product-lab/bisect/<time> in the lab's directory)\n  --dry-run             the axes, their values and the most probes it would take; nothing runs\n  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)\n  --json                print the report as JSON\n  Exit code: 0 found (or a dry run); 1 otherwise (refused, not reproduced, flaky, untested or out of budget);\n  2 a usage error.\nA probe of the lab's commits runs from a worktree under the lab's cache, its dependencies installed frozen from its own\nlockfile; every worktree is removed at the end. Nothing starts with less than 15 GB of free disk.";
+export declare function renderBisect(report: BisectRunReport, summary: string): string;
+export declare function runBisectCommand(runtime: LabRuntime, argv: string[], signal?: AbortSignal, out?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/bisect-command.js

@@ -0,0 +1,109 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+export const BISECT_USAGE = `Usage: product-lab bisect <previous> <current> [--change <key> | --row <id> --scenario <name>] [--runs <n>]
+                         [--max-probes <n>] [--budget <minutes>] [--out <dir>] [--dry-run] [--config lab.config.ts] [--json]
+
+Find where a regression came in. <previous> and <current> are two suite runs (their report directories or
+product-lab-suite.json), as \`product-lab report compare\` takes them: the scenario passed in the first and fails in the
+second. The components that differ are the axes: the lab's own commits (the app), or the published releases of a
+runtime or host between the two versions. Each probe runs the one scenario as its row ran it, every other component
+at its good value, and the ends are run again first: when they do not pass and fail as recorded, the regression did
+not reproduce and nothing is halved. A recovery, an infrastructure failure, a change with no recorded cause, a change
+only the combination carries, a binary or an added component is refused by name.
+  --change <key>        the change to bisect, by its key in \`report compare\` (needed when the compare finds several)
+  --row <id>            or name it by row and scenario
+  --scenario <name>
+  --runs <n>            runs per probe (default 2, at most 5); they must agree, or the scenario is flaky there and the
+                        bisect stops
+  --max-probes <n>      probes besides the ends (default enough to halve, and two to step past untestable values)
+  --budget <minutes>    start no probe after this long
+  --out <dir>           where product-lab-bisect.json, summary.md and each probe's records go
+                        (default .product-lab/bisect/<time> in the lab's directory)
+  --dry-run             the axes, their values and the most probes it would take; nothing runs
+  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)
+  --json                print the report as JSON
+  Exit code: 0 found (or a dry run); 1 otherwise (refused, not reproduced, flaky, untested or out of budget);
+  2 a usage error.
+A probe of the lab's commits runs from a worktree under the lab's cache, its dependencies installed frozen from its own
+lockfile; every worktree is removed at the end. Nothing starts with less than 15 GB of free disk.`;
+export function renderBisect(report, summary) {
+    return `${summary}\nReport: ${report.files.report}\nSummary: ${report.files.summary}\n`;
+}
+export async function runBisectCommand(runtime, argv, signal, out = (text) => process.stdout.write(text)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            config: { type: "string" },
+            json: { type: "boolean" },
+            change: { type: "string" },
+            row: { type: "string" },
+            scenario: { type: "string" },
+            runs: { type: "string" },
+            "max-probes": { type: "string" },
+            budget: { type: "string" },
+            out: { type: "string" },
+            "dry-run": { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        out(BISECT_USAGE + "\n");
+        return 0;
+    }
+    const usage = (message) => {
+        out(`${message}\n${BISECT_USAGE}\n`);
+        return 2;
+    };
+    if (positionals.length !== 2)
+        return usage(positionals.length > 2 ? `Unexpected arguments: ${positionals.slice(2).join(" ")}` : "Name the previous and the current suite run");
+    if (values.change && (values.row || values.scenario))
+        return usage("Name the change by --change or by --row and --scenario, not both");
+    const whole = (text, low, high) => {
+        if (text === undefined)
+            return undefined;
+        const value = Number(text);
+        return Number.isInteger(value) && value >= low && value <= high ? value : null;
+    };
+    const runs = whole(values.runs, 1, 5);
+    if (runs === null)
+        return usage(`--runs takes a whole number from 1 to 5, not ${values.runs}`);
+    const maxProbes = whole(values["max-probes"], 0, 64);
+    if (maxProbes === null)
+        return usage(`--max-probes takes a whole number from 0 to 64, not ${values["max-probes"]}`);
+    const budget = values.budget === undefined ? undefined : Number(values.budget);
+    if (budget !== undefined && !(budget > 0))
+        return usage(`--budget takes a number of minutes above 0, not ${values.budget}`);
+    if (!runtime.bisect) {
+        out("This runtime cannot bisect\n");
+        return 1;
+    }
+    const lab = await runtime.load();
+    const directory = resolve(values.out ?? join(lab.root, ".product-lab", "bisect", new Date().toISOString().replace(/[:.]/g, "-")));
+    try {
+        const report = await runtime.bisect({
+            previous: resolve(positionals[0]),
+            current: resolve(positionals[1]),
+            ...(values.change ? { change: values.change } : {}),
+            ...(values.row ? { row: values.row } : {}),
+            ...(values.scenario ? { scenario: values.scenario } : {}),
+            ...(runs !== undefined ? { runs } : {}),
+            ...(maxProbes !== undefined ? { maxProbes } : {}),
+            ...(budget !== undefined ? { budgetMs: Math.round(budget * 60_000) } : {}),
+            ...(values["dry-run"] ? { dryRun: true } : {}),
+            directory,
+            onOutput: values.json ? (text) => process.stderr.write(text) : out,
+            ...(signal ? { signal } : {}),
+        });
+        out(values.json ? JSON.stringify(report, null, 2) + "\n" : renderBisect(report, readFileSync(report.files.summary, "utf8")));
+        return report.status === "found" || report.status === "planned" ? 0 : 1;
+    }
+    finally {
+        if (runtime.environmentState().state !== "stopped")
+            await runtime.stopEnvironment({ interruptRun: true });
+    }
+}

package/entrypoints/cli/src/breakpoints-command.d.ts

@@ -0,0 +1,4 @@
+import type { LabRuntime, StepBreakpointView } from "@parity/product-lab/ports/driving";
+export declare const BREAKPOINTS_USAGE = "Usage: product-lab breakpoints [list] [<feature>] [--scenario <name>] [--json]\n       product-lab breakpoints set <feature> --scenario <name> --step <n>\n       product-lab breakpoints clear <feature> --scenario <name> [--step <n>]\n\nBreakpoints pause a feature run before a step, to inspect the chain and the apps (the lab panel, or MCP run_report),\nthen Continue, Step or Cancel. They are the lab's local state (.product-lab/breakpoints.json), never the feature file.\nRuns in the lab panel (Watch and Background) and MCP run_scenario inProcess runs stop at them; product-lab test does not.\n  <feature>             a feature file relative to lab.config.ts (product-lab lint lists them)\n  --scenario <name>     the scenario's name as the feature file writes it\n  --step <n>            the step number from 1, Background steps first (as the panel numbers them)\n  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)\n  --json                print JSON\nA breakpoint whose step changed since it was set is listed as stale, with why; a run reports it and does not stop there.";
+export declare function renderBreakpoints(items: readonly StepBreakpointView[]): string;
+export declare function runBreakpointsCommand(runtime: LabRuntime, argv: string[], out?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/breakpoints-command.js

@@ -0,0 +1,67 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { parseArgs } from "node:util";
+export const BREAKPOINTS_USAGE = `Usage: product-lab breakpoints [list] [<feature>] [--scenario <name>] [--json]
+       product-lab breakpoints set <feature> --scenario <name> --step <n>
+       product-lab breakpoints clear <feature> --scenario <name> [--step <n>]
+
+Breakpoints pause a feature run before a step, to inspect the chain and the apps (the lab panel, or MCP run_report),
+then Continue, Step or Cancel. They are the lab's local state (.product-lab/breakpoints.json), never the feature file.
+Runs in the lab panel (Watch and Background) and MCP run_scenario inProcess runs stop at them; product-lab test does not.
+  <feature>             a feature file relative to lab.config.ts (product-lab lint lists them)
+  --scenario <name>     the scenario's name as the feature file writes it
+  --step <n>            the step number from 1, Background steps first (as the panel numbers them)
+  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)
+  --json                print JSON
+A breakpoint whose step changed since it was set is listed as stale, with why; a run reports it and does not stop there.`;
+export function renderBreakpoints(items) {
+    if (!items.length)
+        return "No breakpoints.\n";
+    return items.map((item) => `${item.path}  "${item.scenario}"  step ${item.index + 1}: ${item.text}${item.line ? ` (line ${item.line})` : ""}${item.stale ? `\n  stale: ${item.stale}` : ""}`).join("\n") + "\n";
+}
+export async function runBreakpointsCommand(runtime, argv, out = (text) => process.stdout.write(text)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: { help: { type: "boolean", short: "h" }, config: { type: "string" }, json: { type: "boolean" }, scenario: { type: "string" }, step: { type: "string" } },
+    });
+    if (values.help) {
+        out(BREAKPOINTS_USAGE + "\n");
+        return 0;
+    }
+    const [first, ...rest] = positionals;
+    const action = first === "set" || first === "clear" || first === "list" ? first : "list";
+    const args = first === "set" || first === "clear" || first === "list" ? rest : positionals;
+    const refuse = (message) => {
+        out(`${message}\n${BREAKPOINTS_USAGE}\n`);
+        return 2;
+    };
+    if (args.length > 1)
+        return refuse(`Unexpected arguments: ${args.slice(1).join(" ")}`);
+    const step = values.step === undefined ? undefined : Number(values.step);
+    if (step !== undefined && (!Number.isInteger(step) || step < 1))
+        return refuse(`--step must be a step number from 1, not ${values.step}`);
+    const [path] = args;
+    if (action !== "list" && (!path || values.scenario === undefined))
+        return refuse(`breakpoints ${action} needs a feature file and --scenario`);
+    if (action === "set" && step === undefined)
+        return refuse("breakpoints set needs --step");
+    if (action === "list" && step !== undefined)
+        return refuse("--step is for set and clear");
+    await runtime.load();
+    const breakpoints = runtime.breakpoints();
+    if (action === "set") {
+        const set = await breakpoints.set({ path: path, scenario: values.scenario, index: step - 1 });
+        out(values.json ? JSON.stringify(set, null, 2) + "\n" : `Breakpoint set: ${renderBreakpoints([set])}`);
+        return 0;
+    }
+    if (action === "clear") {
+        const cleared = await breakpoints.clear({ path: path, scenario: values.scenario, ...(step !== undefined ? { index: step - 1 } : {}) });
+        out(values.json ? JSON.stringify(cleared, null, 2) + "\n" : `Removed ${cleared.removed} breakpoint${cleared.removed === 1 ? "" : "s"}.\n`);
+        return 0;
+    }
+    const items = await breakpoints.list({ ...(path ? { path } : {}), ...(values.scenario !== undefined ? { scenario: values.scenario } : {}) });
+    out(values.json ? JSON.stringify(items, null, 2) + "\n" : renderBreakpoints(items));
+    return 0;
+}

package/entrypoints/cli/src/bundle-command.d.ts

@@ -0,0 +1,5 @@
+import type { LabRuntime, RunBundleExportReport, RunBundleOpened } from "@parity/product-lab/ports/driving";
+export declare const BUNDLE_USAGE = "Usage: product-lab bundle <recording-id> [--out <file>] [--config lab.config.ts] [--json]\n       product-lab bundle open <file> [--dir <directory>] [--config lab.config.ts] [--json]\n\nA run bundle is one file (<id>.plbundle, a zstd-compressed tar any tar opens) that holds a recorded feature scenario:\nthe recording, the feature file as it ran, the lab lock, the run manifest and the state it started on (its fixture,\nexactly as fixture export writes it, or nothing for an environment rebuilt from its versions), with every file's sha256.\nAn identity whose key comes from a lab secret is never bundled: it is named, and the bundle cannot be reproduced.\n  <recording-id>        a feature scenario's recording (product-lab recordings lists them)\n  --out <file>          the bundle (default <lab>/.product-lab/bundles/<recording-id>.plbundle)\n  open <file>           check and extract a bundle, show its run read-only, and say whether it could be reproduced\n                        here, naming every reason it could not\n  --dir <directory>     with open: where to extract it (default under <lab>/.product-lab/bundles/opened/)\n  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)\n  --json                print JSON";
+export declare function renderExport(report: RunBundleExportReport): string;
+export declare function renderOpened(opened: RunBundleOpened): string;
+export declare function runBundleCommand(runtime: LabRuntime, argv: string[], out?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/bundle-command.js

@@ -0,0 +1,74 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { parseArgs } from "node:util";
+export const BUNDLE_USAGE = `Usage: product-lab bundle <recording-id> [--out <file>] [--config lab.config.ts] [--json]
+       product-lab bundle open <file> [--dir <directory>] [--config lab.config.ts] [--json]
+
+A run bundle is one file (<id>.plbundle, a zstd-compressed tar any tar opens) that holds a recorded feature scenario:
+the recording, the feature file as it ran, the lab lock, the run manifest and the state it started on (its fixture,
+exactly as fixture export writes it, or nothing for an environment rebuilt from its versions), with every file's sha256.
+An identity whose key comes from a lab secret is never bundled: it is named, and the bundle cannot be reproduced.
+  <recording-id>        a feature scenario's recording (product-lab recordings lists them)
+  --out <file>          the bundle (default <lab>/.product-lab/bundles/<recording-id>.plbundle)
+  open <file>           check and extract a bundle, show its run read-only, and say whether it could be reproduced
+                        here, naming every reason it could not
+  --dir <directory>     with open: where to extract it (default under <lab>/.product-lab/bundles/opened/)
+  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)
+  --json                print JSON`;
+const kib = (bytes) => `${(bytes / 1024).toFixed(1)} KiB`;
+export function renderExport(report) {
+    return [
+        `Bundled ${report.id} → ${report.file} (${kib(report.bytes)}, ${report.files} file(s), ${report.ms} ms, sha256 ${report.sha256})`,
+        `Verdict: ${report.verdict} · starting state: ${report.state.kind}${"reason" in report.state ? ` (${report.state.reason})` : ` (fixture ${report.state.fixture})`}`,
+        report.reproducible.ok ? "Reproducible: yes" : `Reproducible: no\n${report.reproducible.reasons.map((reason) => `  - ${reason}`).join("\n")}`,
+        ...report.withheld.map((item) => `Withheld identity ${item.identity}: ${item.reason}`),
+        ...report.notices.map((notice) => `Note: ${notice}`),
+    ].join("\n") + "\n";
+}
+export function renderOpened(opened) {
+    const { bundle, here } = opened;
+    const first = bundle.attempts[0];
+    const lines = [
+        `Run bundle ${bundle.id} (read-only) · ${bundle.scenario.name} · ${bundle.scenario.feature}${bundle.scenario.line ? `:${bundle.scenario.line}` : ""}`,
+        `Made ${bundle.createdAt} on ${bundle.platform.os}/${bundle.platform.arch} · lab ${bundle.lab.name} · environment ${bundle.environment.label} (${bundle.environment.id})`,
+        `Verdict: ${bundle.verdict} · ${bundle.attempts.length} attempt(s) · starting state: ${bundle.state.kind}`,
+        ...(first?.failure ? [`Failed at step ${first.failure.featureStep ?? "?"}: ${first.failure.step}`, `  ${first.failure.error.split("\n")[0]}`, `  marker: ${JSON.stringify(first.failure.marker)}`] : []),
+        `Extracted to ${opened.directory}`,
+    ];
+    for (const view of opened.recordings)
+        for (const step of view.recording.steps)
+            lines.push(`${String(step.index + 1).padStart(3)}. ${step.status.padEnd(8)} ${step.title}${step.error ? ` · ${step.error.split("\n")[0]}` : ""}`);
+    if (here.refusals.length)
+        lines.push("Reproduce here: refused", ...here.refusals.map((problem) => `  - ${problem.message}`));
+    else
+        lines.push(here.rechecks.length ? "Reproduce here: only as a recheck (--against-current)" : "Reproduce here: possible");
+    lines.push(...here.rechecks.map((problem) => `  recheck: ${problem.message}`), ...bundle.notices.map((notice) => `Note: ${notice}`));
+    return lines.join("\n") + "\n";
+}
+export async function runBundleCommand(runtime, argv, out = (text) => process.stdout.write(text)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: { help: { type: "boolean", short: "h" }, config: { type: "string" }, json: { type: "boolean" }, out: { type: "string" }, dir: { type: "string" } },
+    });
+    if (values.help) {
+        out(BUNDLE_USAGE + "\n");
+        return 0;
+    }
+    const opening = positionals[0] === "open";
+    const [target, ...extra] = opening ? positionals.slice(1) : positionals;
+    if (!target || extra.length || (opening && values.out !== undefined) || (!opening && values.dir !== undefined)) {
+        out(`${!target ? (opening ? "open needs a bundle file" : "Name the recording to bundle") : extra.length ? `Unexpected arguments: ${extra.join(" ")}` : opening ? "--out is for bundling, not open" : "--dir is for open"}\n${BUNDLE_USAGE}\n`);
+        return 2;
+    }
+    await runtime.load();
+    if (opening) {
+        const opened = await runtime.runBundles().openBundle({ file: target, ...(values.dir ? { directory: values.dir } : {}) });
+        out(values.json ? JSON.stringify(opened, null, 2) + "\n" : renderOpened(opened));
+        return 0;
+    }
+    const report = await runtime.runBundles().bundleRecording({ recording: target, ...(values.out ? { out: values.out } : {}) });
+    out(values.json ? JSON.stringify(report, null, 2) + "\n" : renderExport(report));
+    return 0;
+}

package/entrypoints/cli/src/checkout.d.ts

@@ -0,0 +1,6 @@
+/** The workspace root's package name in product-lab's checkout; the installed package is `@parity/product-lab`. */
+export declare const CHECKOUT_PACKAGE_NAME = "product-lab-workspace";
+/** Whether `root` (default: this CLI's own root) is product-lab's checkout rather than an installed package. */
+export declare function insideProductLabCheckout(root?: string): boolean;
+/** The upstream change a released truAPI CLI host needs before a product can run it on a local environment (`localNetwork`). */
+export declare const CLI_HOST_UPSTREAM = "https://github.com/paritytech/host-rust-core/pull/1166";

package/entrypoints/cli/src/checkout.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const CHECKOUT_PACKAGE_NAME = "product-lab-workspace";
+const PACKAGE_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+export function insideProductLabCheckout(root = PACKAGE_ROOT) {
+    const manifest = join(root, "package.json");
+    return existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === CHECKOUT_PACKAGE_NAME;
+}
+export const CLI_HOST_UPSTREAM = "https://github.com/paritytech/host-rust-core/pull/1166";

package/entrypoints/cli/src/cli-app.d.ts

@@ -0,0 +1,57 @@
+import type { KeepPolicy, LabRuntime } from "@parity/product-lab/ports/driving";
+import type { CommandRunner, EnvironmentVariables, StdioWorker, SyncCommandRunner, TerminalCommandRunner } from "@parity/product-lab/ports/system";
+/** The value of `--name <value>` or `--name=<value>` before a command parses its own flags. */
+export declare function flagValue(argv: readonly string[], name: string): string | undefined;
+/**
+ * What the runtime for an invocation loads: the lab `--config` names (default
+ * ./lab.config.ts); `env` only inspects it. `host`, `ai`, `init`, `mcp` and `report` load no lab
+ * here (`host`'s `--config` is a targets or tools module; `mcp` builds its own
+ * runtime in its worker; `report` reads suite records). The CLI starts whichever environment it is asked
+ * for, local or not.
+ */
+export declare function runtimeOptions(argv: readonly string[], env?: EnvironmentVariables): {
+    config?: string;
+    inspect?: boolean;
+    allowPublic: boolean;
+    keepBetweenStarts?: KeepPolicy;
+    runningRecord?: string | false;
+    reload?: boolean;
+};
+/** `product-lab` over one LabRuntime. */
+export declare class CliApp {
+    private readonly runtime;
+    private readonly syncCommands;
+    private readonly stdioWorker;
+    private readonly env;
+    private readonly processes;
+    /** `env`: the variables the commands read (main.ts passes the process's, through the EnvironmentVariables port). */
+    /**
+     * `processes`: what opens an agent beside the lab from the terminal app (`a`) and the window's Tools (lane agents
+     * beside the lab): one-shot commands (a tmux split, a terminal's new tab) and a command on this terminal. Without
+     * them no agent opens from here.
+     */
+    constructor(runtime: LabRuntime, syncCommands: SyncCommandRunner, stdioWorker: StdioWorker, env: EnvironmentVariables, processes?: {
+        commands?: CommandRunner;
+        terminal?: TerminalCommandRunner;
+    });
+    /** Claude Code and Codex beside this lab, in its folder (the lab's root once it is read). */
+    private agents;
+    run(argv: readonly string[]): Promise<number>;
+    /** The command's own notices, kept so run() can stop their registry check when the command is done. */
+    private releases;
+    private runCommand;
+    /** The release notice this command announced, for the lab window (`dev`). */
+    private release;
+    /** Print what is new (and, on a terminal, a newer version) on stderr, and record them as told; returns what was said. */
+    private static announce;
+    private devOrCheck;
+    /**
+     * B1 (e): when this lab's window runs in another process, the terminal app shows and drives its lab (nothing starts
+     * here) until the person leaves, which keeps the window running; false when no window runs (plain lines still refuse
+     * beside one, in startDev). Its state is read again every half second; the window closing ends it, saying so.
+     */
+    private besideWindow;
+    /** Run a command with SIGINT, SIGTERM and SIGHUP turned into an abort signal; close the runtime afterwards. */
+    private withSignals;
+    private closing;
+}