@merchantduo/code 0.2.0-beta.2 → 0.2.0-beta.3

package/README.md

@@ -1,66 +1,27 @@
 # MerchantDuo
 
-MerchantDuo is a Pi coding agent for Magento teams that works from the store's real environment, Magento version, deployment mode, and theme context.
+MerchantDuo is a Pi coding agent for Magento 2.4 teams. It starts from the store's selected environment, Magento version, deployment mode, and theme context instead of treating a Magento project as a generic repository.
 
-## Main features
+## Overview
 
-- Magento-aware coding sessions
-- Local, Warden, and SSH environments
-- Developer-store provisioning
-- Magento 2.4, Luma, Hyva, Mage2Gen, and testing skills
-- Magento workflows and focused test tools
-- Version, edition, deployment-mode, and theme detection
-- Remote-write and operational safety controls
+- Works with local checkouts, Warden, and SSH environments.
+- Detects Magento edition, version, PHP version, deployment mode, cache types, and registered theme inheritance.
+- Ships Magento 2.4, Luma, Hyva, Mage2Gen, and testing skills.
+- Provides guided local/Warden store provisioning.
+- Keeps remote writes and Magento operations behind explicit execution boundaries.
 
-## Details
+At session start, MerchantDuo produces a Magento snapshot from the selected environment. Frontend and admin URLs are discovered but remain unverified until an explicit test. The compact status line shows MerchantDuo and Magento versions, environment lifecycle, write access, an explicit theme scope when one is selected, and the frontend URL when available.
 
-MerchantDuo gives Magento developers a coding-agent workspace that starts with the project context they need. It runs on Pi, inspects the selected Magento environment, keeps theme scope visible, and exposes Magento-specific tools for the work that usually slows an agency team down.
+## Commands and tools
 
-It is built for Magento 2.4 development, not as a generic chat wrapper with a few shell commands attached. A session knows whether it is working locally, in Warden, or through SSH. It can identify the Magento edition, version, PHP version, deployment mode, enabled module count, cache types, and real registered themes before it suggests framework-specific work.
+Extension slash commands are namespaced with `duo-` to avoid collisions with other Pi extensions.
 
-MerchantDuo is currently beta software for development teams.
+- [Command reference](docs/commands.md) covers `/duo-switch-theme`, lifecycle, and navigation commands.
+- [Tool reference](docs/tools.md) covers workspace, environment, Magento workflow, magerun2, testing, PHP-console, and optional knowledge tools, including parameters and confirmation boundaries.
 
-## What agencies get
+## Environments
 
-- A Pi coding-agent package with Magento context from the start of each session.
-- Local, Warden, and SSH environments selected per project or command.
-- A guided `provision` command for preparing a local or Warden developer store.
-- Native Magento 2.4, Luma, Hyva, Mage2Gen, and testing skills.
-- Magento-aware file, search, edit, module-generation, workflow, HTTP, browser, and PHP-console tools.
-- Theme discovery based on registered themes in `vendor` and `app/design`, including parent chains and Luma or Hyva classification.
-- Deployment-mode guidance that changes for developer, default, and production installations.
-- Guardrails around remote writes, Magento operations, credentials, and browser access.
-
-The result is less time re-explaining a store to an agent and fewer generic recommendations that do not fit Magento.
-
-## Magento context before the first change
-
-At session startup, MerchantDuo creates a Magento snapshot for the selected environment. It reads `composer.lock` and `bin/magento --version` when available, then reports disagreements instead of silently choosing one. The snapshot includes:
-
-- Magento Open Source or Adobe Commerce edition and version
-- PHP version and deployment mode
-- Enabled module count and cache types
-- Registered themes, inheritance chains, and Luma or Hyva classification
-- Available frontend and admin URLs, marked unverified until explicitly tested
-- Whether the selected environment is writable
-
-Theme discovery only scans real Magento theme roots: package roots under `vendor` and themes under `app/design`. It does not search arbitrary vendor fixtures. Use `/theme` to select `all`, `any`, or a detected theme code. `all` keeps every detected theme in scope, while `any` tells the agent to identify the relevant theme before it edits theme-specific code.
-
-## Curated Magento knowledge
-
-MerchantDuo ships focused Pi skills instead of relying on broad, generic instructions:
-
-- `magento-24x` guides Magento 2.4 work toward service contracts, dependency injection, declarative schema and data patches, layout XML, and the right deployment-mode workflow.
-- `luma` covers Magento fallback, layout XML, RequireJS, UI components, Knockout, LESS, and static assets.
-- `hyva` directs work toward Hyva templates, Alpine, Tailwind, and Hyva UI components. The package also vendors the relevant Hyva skills.
-- `mage2gen` makes vendored Mage2Gen the standard starting point for new modules.
-- `magento-testing` keeps testing explicit, targeted, and unauthenticated.
-
-The current package provides this curated knowledge locally through Pi skills. `merchantduo doctor` reports knowledge-service status and currently shows that no external knowledge connection is configured. That prevents the agent from presenting an unavailable MCP source as project knowledge.
-
-## Environments that match agency work
-
-Define the environments your team actually uses in `.merchantduo.yaml`, then select one at launch with `--env`.
+Define the environments your team uses in `.merchantduo.yaml`, then select one at launch with `--env`.
 
 ```yaml
 defaultEnvironment: local
@@ -88,9 +49,7 @@ environments:
     writable: false
 ```
 
-Local work uses the Magento checkout directly. Warden work routes file and Magento commands through the selected service. SSH starts read-only unless you set `writable: true`, and writable remote file or shell work requires confirmation.
-
-For SSH user names, ports, and identities, use an OpenSSH alias rather than extra YAML keys:
+Local uses the checkout directly. Warden routes project and Magento execution through its configured service. SSH is read-only by default; configure its user, port, and key using an OpenSSH host alias:
 
 ```sshconfig
 Host shop-stage
@@ -100,89 +59,37 @@ Host shop-stage
   IdentityFile ~/.ssh/id_ed25519
 ```
 
-Use the alias as `host: shop-stage` in `.merchantduo.yaml`.
+Use that alias as `host: shop-stage`. `merchantduo init` offers local first and Warden when its project `.env` is detected; it prints an SSH example instead of writing an unused remote environment.
 
-`merchantduo init` offers the local checkout first. When the project `.env` contains Warden routing markers, it also offers a Warden environment. It writes only the environments you accept and then prints the remote SSH example instead of adding a fake remote entry. Local development certificates are accepted by default; set `testing.allowInsecureTls: false` when the selected URLs have publicly trusted certificates.
+## Provisioning
 
-## Provision a developer store
-
-Run provisioning from an empty directory or an existing Magento project:
+Provision a local or Warden developer store from an empty directory or an existing Magento checkout:
 
 ```sh
 merchantduo provision
 merchantduo provision --env warden --source https://git.example.test/store.git --database ./backup.sql.gz --yes
 ```
 
-Provisioning supports local and Warden environments. It inspects available services, Magento source, database dumps, and existing web-server routing. The interactive flow asks only for choices it cannot resolve, prints an ordered plan, and asks once before it changes anything.
-
-With `--yes`, every decision must already be explicit or unambiguous. The command fails rather than guessing a source, database, web server, or environment.
-
-Sources can be an existing checkout, Git URL, local archive, or HTTPS archive. Databases can be the current database, a local SQL or compressed SQL dump, or an HTTPS URL. Downloaded archives are staged below `MERCHANTDUO_HOME/provisions`, checked for path traversal, and removed after extraction.
-
-Input precedence is command flags, then a discovered Magento checkout or the only SQL dump in the project root, then the interactive interview.
-
-For Warden, MerchantDuo runs Warden lifecycle and database commands on the host, then runs Composer and Magento commands in the configured PHP service. Local provisioning requires PHP, Composer, the MySQL client, and an active nginx or Apache service. If no matching virtual host exists, the approved plan can add a minimal `pub` vhost and an `/etc/hosts` entry for the selected local domain. It does not replace an existing matching vhost.
-
-If `MERCHANTDUO_LLM_TOKEN` is set, provisioning can ask a narrow OpenAI-compatible advisor to choose from its already generated action plan. Its built-in endpoint and model are mock wiring, not a hosted AI service. Invalid advisor output falls back to the deterministic plan. MerchantDuo never sends the token, database credentials, or `app/etc/env.php` contents to the advisor.
-
-## Tools that respect Magento boundaries
-
-MerchantDuo uses direct Pi extensions for context, permissions, workspace work, themes, Mage2Gen, workflows, and testing. The package manifest is the source of truth for both extensions and skills.
-
-| Capability | What it does |
-| --- | --- |
-| Workspace tools | Read, search, write, and edit inside the selected environment. |
-| `mage2gen_generate_module` | Previews or generates a module under the selected local or Warden project's `app/code`. It refuses existing destinations and does not run over SSH. |
-| `magento_workflow` | Previews Magento operations such as cache cleaning, setup upgrade, DI compilation, static-content deployment, reindexing, and tests. Use `execute: true` to request the single in-tool confirmation. |
-| `magento_http_test` | Runs an explicit unauthenticated GET or HEAD request against a discovered Magento URL. |
-| `magento_browser_test` | Captures a screenshot or DOM dump with an isolated Chromium profile. Artifacts are stored under `MERCHANTDUO_HOME/artifacts/<project-id>/`. |
-| `magento_php_repl` | Runs one PHP snippet through a one-shot `n98-magerun2` console. |
-| `/navigate-frontend` and `/navigate-adminhtml` | Open a discovered same-origin frontend or admin URL without handling login credentials. |
-
-No lifecycle hook runs tests, cache actions, deployments, or browser commands because a session started or a file changed. Those operations remain explicit. Testing and navigation are direct user-request boundaries, so they do not ask for the MerchantDuo confirmation.
-
-## Magento workflows without blind deployment commands
-
-MerchantDuo tracks changed files and recommends the smallest relevant operation. It does not assume every edit needs a full Magento deployment.
-
-| Detected mode | Typical module-change sequence |
-| --- | --- |
-| Developer | `setup:upgrade`, then clean relevant cache types. |
-| Default | `setup:upgrade`, then clean relevant cache types. Compile DI or deploy static content only when the change requires it. |
-| Production | Enable maintenance mode, run `setup:upgrade`, compile DI, deploy static content, clean relevant cache types, then disable maintenance mode. |
-
-If the deployment mode cannot be determined, MerchantDuo reports that fact instead of inventing a sequence.
+The interactive flow discovers available source, database, and service evidence, shows an ordered plan, and asks once before mutations. `--yes` requires all decisions to be explicit or unambiguous.
 
 ## Install and start
 
-MerchantDuo requires Node.js 22.19 or later, Bash, Python 3, curl, and Chromium or Chrome. Warden environments require Warden. SSH environments require OpenSSH. A remote PHP console needs `n98-magerun2` on that environment.
-
-Linux navigation also needs `xdg-open`. Browser discovery accepts `chromium-browser`, `chromium`, `google-chrome`, and `google-chrome-stable`.
-
-Install the package through your team's npm registry, then create the project configuration:
+MerchantDuo requires Node.js 22.19 or later, Bash, and Python 3. HTTP/browser testing additionally needs curl and Chrome or Chromium; Warden and SSH environments need Warden and OpenSSH respectively.
 
 ```sh
+pnpm install --frozen-lockfile
 merchantduo init
 merchantduo doctor --env local
 merchantduo --env local
 ```
 
-`merchantduo init` creates `.merchantduo.yaml`. Review it before the first agent session. MerchantDuo requires an explicit one-time trust decision for a project configuration. Set `MERCHANTDUO_TRUST_CONFIG=1` only after reviewing that file.
-
-Testing URLs can be configured at the top level or per environment. Configured URLs take precedence over discovery. Local discovery reads Magento base URLs and the admin URI. Warden reads `TRAEFIK_DOMAIN` and `TRAEFIK_SUBDOMAIN` from the project `.env`. MerchantDuo does not contact discovered URLs until an explicit testing request.
-
-For SSH, MerchantDuo uses configured URLs or reads Magento remotely when URLs are absent. HTTP tests, browser tests, navigation, temporary browser profiles, and test artifacts always run on and belong to the host, including for Warden. MerchantDuo finds and invokes the host `curl` and Chrome/Chromium, never their container copies. Local TLS exceptions apply consistently to both curl and the browser. The PHP REPL remains Magento-side because it executes application code and therefore needs Warden's PHP service, project files, configuration, and database. When local `n98-magerun2` is unavailable, MerchantDuo looks in `vendor/bin`, `bin`, and `PATH`, then can use a verified official PHAR cache under `MERCHANTDUO_HOME/tools/n98-magerun2` without modifying the Magento project. Failure to obtain that cache does not stop the session.
+Review the generated `.merchantduo.yaml` before the first session. MerchantDuo requires a one-time configuration trust decision; set `MERCHANTDUO_TRUST_CONFIG=1` only after review.
 
-## Safety model
+## Safety and optional services
 
-Magento projects carry more operational risk than ordinary application repositories. MerchantDuo keeps the boundaries simple:
+MerchantDuo does not load `app/etc/env.php`, credentials, or tokens into agent context. It does not run background tests, cache commands, deployment actions, browser operations, or PHP code. Explicit operations use the confirmation rules described in the [tool reference](docs/tools.md).
 
-- It does not read `app/etc/env.php`, credentials, or tokens for agent context.
-- It treats discovered URLs as unverified until you run an explicit HTTP or browser test.
-- It performs no background cache, deployment, browser, HTTP, PHP-console, or workflow action.
-- Module generation and Magento workflows preview first. Execution requires `execute: true` and one harness confirmation.
-- Read-only SSH blocks write, edit, and shell operations. Writable SSH asks for confirmation before those operations.
-- SSH testing uses the publicly reachable URL and never creates a tunnel.
+Set `MERCHANTDUO_MCP_TOKEN` to enable the built-in read-only knowledge tool. Set `MERCHANTDUO_LLM_TOKEN` to enable the built-in MerchantDuo provider. Neither endpoint is project configuration.
 
 ## Development
 
@@ -190,7 +97,7 @@ Magento projects carry more operational risk than ordinary application repositor
 pnpm install --frozen-lockfile
 pnpm check
 pnpm test
-pnpm pack --dry-run
+npm pack --dry-run
 ```
 
 For the extension layout, provisioning boundary, and session lifecycle, see [the architecture notes](docs/architecture.md).

package/dist/app/runtime.d.ts

@@ -1,9 +1,11 @@
 import { type MerchantConfig } from "#config/index";
 import { EnvironmentBackend } from "#environments/backend";
 import type { Environment } from "#environments/model";
+import type { EnvironmentStatus } from "#environments/model";
 import { type MagentoInspector, type MagentoSnapshot } from "#magento/index";
 import { ChangeTracker } from "#workflows/change-tracker";
 import type { TestingSnapshot } from "#testing/model";
+import type { Magerun2Capability } from "#features/magerun2/index";
 export type SessionState = {
     config: MerchantConfig;
     configPath?: string;
@@ -12,8 +14,10 @@ export type SessionState = {
         environment: Environment;
     };
     backend: EnvironmentBackend;
+    environmentStatus: EnvironmentStatus;
     magento: MagentoSnapshot;
     testing?: TestingSnapshot;
+    magerun2?: Magerun2Capability;
 };
 export declare class MerchantDuoRuntime {
     #private;
@@ -27,4 +31,8 @@ export declare class MerchantDuoRuntime {
     changeTheme(cwd: string, activeTheme: string): Promise<SessionState>;
     writable(state: SessionState): boolean;
     setTesting(snapshot: TestingSnapshot): void;
+    setMagerun2(capability: Magerun2Capability): void;
+    setEnvironmentStatus(status: EnvironmentStatus): SessionState;
+    startEnvironment(cwd: string): Promise<SessionState>;
+    stopEnvironment(cwd: string): Promise<SessionState>;
 }

package/dist/app/runtime.js

@@ -20,11 +20,13 @@ export class MerchantDuoRuntime {
         });
         const selected = selectEnvironment(loaded.config, cwd, process.env.MERCHANTDUO_SELECTED_ENV);
         const backend = new EnvironmentBackend(selected.environment, cwd);
+        const environmentStatus = await backend.status();
         this.#state = {
             ...loaded,
             selected,
             backend,
-            magento: await this.inspector.inspect(backend),
+            environmentStatus,
+            magento: environmentStatus === "running" ? await this.inspector.inspect(backend) : stoppedMagentoSnapshot(),
         };
         return this.#state;
     }
@@ -53,4 +55,46 @@ export class MerchantDuoRuntime {
             throw new Error("Session has not started");
         this.#state.testing = snapshot;
     }
+    setMagerun2(capability) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.magerun2 = capability;
+    }
+    setEnvironmentStatus(status) {
+        if (!this.#state)
+            throw new Error("Session has not started");
+        this.#state.environmentStatus = status;
+        if (status === "stopped") {
+            this.#state.magento = stoppedMagentoSnapshot();
+            this.#state.testing = undefined;
+            this.#state.magerun2 = undefined;
+        }
+        return this.#state;
+    }
+    async startEnvironment(cwd) {
+        const state = await this.boot(cwd);
+        const result = await state.backend.start();
+        if (result && result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || "Could not start environment");
+        state.environmentStatus = await state.backend.status();
+        if (state.environmentStatus === "running")
+            state.magento = await this.inspector.inspect(state.backend);
+        return state;
+    }
+    async stopEnvironment(cwd) {
+        const state = await this.boot(cwd);
+        const result = await state.backend.stop();
+        if (result && result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || "Could not stop environment");
+        state.environmentStatus = await state.backend.status();
+        if (state.environmentStatus === "stopped") {
+            state.magento = stoppedMagentoSnapshot();
+            state.testing = undefined;
+            state.magerun2 = undefined;
+        }
+        return state;
+    }
+}
+function stoppedMagentoSnapshot() {
+    return { cacheTypes: [], warnings: ["Environment is stopped"], evidence: [], themes: [] };
 }

package/dist/app/status.js

@@ -2,8 +2,16 @@ export function refreshStatus(ctx, state) {
     const environment = state.selected.environment;
     const writePolicy = environment.type === "ssh"
         ? environment.writable
-            ? "write + approve"
-            : "read-only + approve"
-        : "write + approve";
-    ctx.ui.setStatus("merchantduo", `MerchantDuo ${process.env.MERCHANTDUO_PACKAGE_VERSION ?? "?"} | Magento ${state.magento.version ?? "?"} | ${state.selected.name}/${environment.type} | ${writePolicy} | Theme: ${state.config.activeTheme} | URLs: ${state.testing?.frontendUrl ?? "unavailable"} (unverified)`);
+            ? "✎+?"
+            : "RO"
+        : "✎";
+    const parts = [
+        `MerchantDuo ${process.env.MERCHANTDUO_PACKAGE_VERSION ?? "?"}`,
+        `M${state.magento.version ?? "?"}`,
+        `${state.selected.name} (${state.environmentStatus})`,
+        writePolicy,
+        ...(state.config.activeTheme === "all" ? [] : [state.config.activeTheme]),
+        ...(state.testing?.frontendUrl ? [state.testing.frontendUrl] : []),
+    ];
+    ctx.ui.setStatus("merchantduo", parts.join(" · "));
 }

package/dist/app/system-prompt.js

@@ -11,5 +11,9 @@ For every request to create a new Magento module, call the \`mage2gen_generate_m
 
 After every change, inspect the changed module and files and choose the smallest applicable post-change workflow from Magento conventions; never apply a full sequence blindly. Ordinary PHP or template edits normally need only the relevant targeted cache clean, if any. Module registration, schema, declarative configuration, or dependency changes trigger mode-aware guidance from the detected snapshot mode: developer recommends \`setup:upgrade\` then targeted cache clean and does not normally compile DI or deploy static content; default recommends \`setup:upgrade\` then targeted cache clean, with compile or static deploy only when the task specifically requires them; production recommends maintenance enable, \`setup:upgrade\`, DI compile, static-content deploy, targeted cache clean, then maintenance disable. If the mode is unknown, report that and do not infer a deployment sequence.
 
-For cache clean/flush, maintenance enable/disable, static content deployment, compilation, setup upgrade, indexing, tests, or deployment: when the user directly requests execution, invoke \`magento_workflow\` with \`execute: true\` immediately. Use only this workflow tool for operational Magento commands. Do not ask the user for a separate conversational confirmation: the harness dialog is the sole authoritative confirmation. When execution was not requested, explain the operation and offer a preview. Never inspect app/etc/env.php or credentials.`;
+For cache clean/flush, maintenance enable/disable, static content deployment, compilation, setup upgrade, indexing, tests, or deployment: when the user directly requests execution, invoke \`magento_workflow\` with \`execute: true\` immediately. Use only this workflow tool for operational Magento commands. Do not ask the user for a separate conversational confirmation: the harness dialog is the sole authoritative confirmation. When execution was not requested, explain the operation and offer a preview.
+
+For a supported cache, deploy, indexing, or test operation, prefer \`magento_workflow\`. For a different n98-magerun2 subcommand, use \`magerun2\` with an exact \`args: string[]\` vector, never a shell command or interpolation. When the user did not directly request execution, return its preview without \`execute: true\`; an executed generic magerun2 call requires \`execute: true\` and uses the same sole harness confirmation. Never send \`dev:console\` through \`magerun2\`: use the typed \`magento_php_repl\` tool instead.
+
+Environment lifecycle is explicit. Warden has known direct controls. SSH is always reported running and must never be started, stopped, or restarted. A local environment is agent-directed: when the user requests a start or stop, inspect the actual project lifecycle first, then call \`environment_start\` or \`environment_stop\` with the exact smallest command. Never guess a generic Docker, Compose, npm, or service command, and never affect unrelated host services. Use \`environment_set_status\` after a status inspection that does not itself start or stop the stack. Never inspect app/etc/env.php or credentials.`;
 }

package/dist/environments/adapter.d.ts

@@ -2,4 +2,5 @@ import type { CommandSpec } from "#environments/executor";
 export interface EnvironmentAdapter {
     path(path: string): string;
     command(argv: string[], target?: string): CommandSpec;
+    lifecycleCommand?(action: "status" | "start" | "stop"): CommandSpec;
 }

package/dist/environments/adapters/warden.d.ts

@@ -10,4 +10,9 @@ export declare class WardenAdapter implements EnvironmentAdapter {
         args: string[];
         cwd: string;
     };
+    lifecycleCommand(action: "status" | "start" | "stop"): {
+        file: string;
+        args: string[];
+        cwd: string;
+    };
 }

package/dist/environments/adapters/warden.js

@@ -21,4 +21,11 @@ export class WardenAdapter {
             cwd: resolve(this.cwd, this.environment.projectRoot),
         };
     }
+    lifecycleCommand(action) {
+        // Lifecycle commands run on the host in the Warden project, never in php-fpm.
+        const actionArgs = action === "status"
+            ? ["env", "ps", "--status", "running", "--services"]
+            : ["env", action];
+        return { file: "warden", args: actionArgs, cwd: resolve(this.cwd, this.environment.projectRoot) };
+    }
 }

package/dist/environments/backend.d.ts

@@ -1,4 +1,5 @@
 import type { Environment } from "#environments/model";
+import type { EnvironmentStatus } from "#environments/model";
 import type { CommandExecutor, CommandResult, CommandSpec, RunOptions } from "#environments/executor";
 export { contain } from "#environments/path-policy";
 /** Concrete local/Warden/SSH command adapter selected once for a session. */
@@ -10,4 +11,10 @@ export declare class EnvironmentBackend implements CommandExecutor {
     path(path: string): string;
     command(argv: string[], target?: string): CommandSpec;
     run(argv: string[], options?: RunOptions): Promise<CommandResult>;
+    lifecycleCommand(action: "status" | "start" | "stop"): CommandSpec | undefined;
+    status(): Promise<EnvironmentStatus>;
+    start(): Promise<CommandResult | undefined>;
+    stop(): Promise<CommandResult | undefined>;
 }
+/** `warden env ps --status running --services` prints one service per running container. */
+export declare function wardenRunning(stdout: string): boolean;

package/dist/environments/backend.js

@@ -22,6 +22,33 @@ export class EnvironmentBackend {
     }
     async run(argv, options = {}) {
         const spec = this.command(argv, options.target);
+        return this.#runSpec(spec, options);
+    }
+    lifecycleCommand(action) {
+        return this.#adapter.lifecycleCommand?.(action);
+    }
+    async status() {
+        if (this.environment.type === "ssh")
+            return "running";
+        if (this.environment.type === "local")
+            return "unknown";
+        const spec = this.lifecycleCommand("status");
+        if (!spec)
+            return "stopped";
+        const output = await this.#runSpec(spec);
+        return output.exitCode === 0 && wardenRunning(output.stdout) ? "running" : "stopped";
+    }
+    async start() {
+        return this.#lifecycle("start");
+    }
+    async stop() {
+        return this.#lifecycle("stop");
+    }
+    async #lifecycle(action) {
+        const spec = this.lifecycleCommand(action);
+        return spec ? this.#runSpec(spec) : undefined;
+    }
+    #runSpec(spec, options = {}) {
         return new Promise((resolveResult) => {
             const child = spawn(spec.file, spec.args, {
                 cwd: spec.cwd,
@@ -71,3 +98,7 @@ export class EnvironmentBackend {
         });
     }
 }
+/** `warden env ps --status running --services` prints one service per running container. */
+export function wardenRunning(stdout) {
+    return stdout.split("\n").some((line) => line.trim().length > 0);
+}

package/dist/environments/model.d.ts

@@ -3,6 +3,8 @@ type EnvironmentTesting = {
     adminUrl?: string;
     allowInsecureTls?: boolean;
 };
+/** Unknown is valid for a local stack until the agent has identified its actual lifecycle. */
+export type EnvironmentStatus = "running" | "stopped" | "unknown";
 export type LocalEnvironment = {
     type: "local";
     root: string;

package/dist/features/magerun2/index.d.ts

@@ -0,0 +1,2 @@
+export * from "#features/magerun2/model";
+export * from "#features/magerun2/service";

package/dist/features/magerun2/index.js

@@ -0,0 +1,2 @@
+export * from "#features/magerun2/model";
+export * from "#features/magerun2/service";

package/dist/features/magerun2/model.d.ts

@@ -0,0 +1,10 @@
+export type Magerun2Capability = {
+    available: boolean;
+    executable?: string;
+    diagnostic?: string;
+};
+export type Magerun2Result = {
+    output: string;
+    exitCode: number;
+    truncated: boolean;
+};

package/dist/features/magerun2/model.js

@@ -0,0 +1 @@
+export {};

package/dist/features/magerun2/service.d.ts

@@ -0,0 +1,12 @@
+import type { EnvironmentBackend } from "#environments/backend";
+import type { Environment } from "#environments/model";
+import { type HostProcessRunner } from "#testing/host";
+import type { Magerun2Capability, Magerun2Result } from "#features/magerun2/model";
+/** Resolve magerun once for the selected Magento environment without altering the project. */
+export declare function discoverMagerun2(environment: Environment, backend: EnvironmentBackend, cwd: string): Promise<Magerun2Capability>;
+/** Run a structured argument vector. Local commands are host processes; Warden and SSH use their selected backend. */
+export declare function runMagerun2(capability: Magerun2Capability, environment: Environment, backend: EnvironmentBackend, cwd: string, args: string[], stdin?: string, signal?: AbortSignal, host?: HostProcessRunner): Promise<Magerun2Result>;
+/** Stable display only: this is never passed to a shell. */
+export declare function quotedMagerunPreview(executable: string, args: string[]): string;
+/** Install the official PHAR outside the Magento project; verify its release SHA-256 before publishing it. */
+export declare function installMagerun2(home: string, _cwd: string, request?: typeof fetch): Promise<string>;

package/dist/{testing/magerun.js → features/magerun2/service.js}

@@ -2,30 +2,53 @@ import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promise
 import { join } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { merchantHome } from "#config/paths";
+import { NodeHostProcessRunner } from "#testing/host";
 const RELEASE_URL = "https://api.github.com/repos/netz98/n98-magerun2/releases/latest";
-export async function discoverMagerun(environment, backend, cwd) {
+const MAX_OUTPUT = 64 * 1024;
+/** Resolve magerun once for the selected Magento environment without altering the project. */
+export async function discoverMagerun2(environment, backend, cwd) {
     if (environment.type === "warden")
-        return { executable: "/usr/local/bin/mr" };
+        return { available: true, executable: "/usr/local/bin/mr" };
     const candidates = environment.type === "local"
         ? ["vendor/bin/n98-magerun2", "bin/n98-magerun2", "n98-magerun2", "magerun2"]
         : ["n98-magerun2", "magerun2"];
     for (const candidate of candidates) {
-        const result = await backend.run(["sh", "-lc", `command -v ${candidate} 2>/dev/null || test -x ${candidate} && printf '%s' ${candidate}`]);
+        const result = await backend.run(["sh", "-lc", `command -v -- ${candidate} 2>/dev/null || { test -x ${candidate} && printf '%s' ${candidate}; }`]);
         const executable = result.stdout.trim();
         if (executable)
-            return { executable };
+            return { available: true, executable };
     }
     if (environment.type === "ssh")
-        return { diagnostic: environment.writable ? "Install n98-magerun2 on the remote host to enable PHP REPL." : "PHP REPL is disabled for read-only SSH." };
+        return { available: false, diagnostic: environment.writable ? "Install n98-magerun2 on the remote host." : "Magerun2 is disabled for read-only SSH." };
     try {
-        return { executable: await installMagerun(merchantHome(), cwd) };
+        return { available: true, executable: await installMagerun2(merchantHome(), cwd) };
     }
     catch (error) {
-        return { diagnostic: `Could not install n98-magerun2: ${error.message}` };
+        return { available: false, diagnostic: `Could not install n98-magerun2: ${error.message}` };
     }
 }
-/** Install the official PHAR outside the Magento project; verify the release API SHA-256 digest before publishing it. */
-export async function installMagerun(home, _cwd, request = fetch) {
+/** Run a structured argument vector. Local commands are host processes; Warden and SSH use their selected backend. */
+export async function runMagerun2(capability, environment, backend, cwd, args, stdin, signal, host = new NodeHostProcessRunner()) {
+    if (!capability.executable)
+        throw new Error(capability.diagnostic ?? "n98-magerun2 is unavailable.");
+    if (environment.type === "local") {
+        const command = backend.command([capability.executable, ...args]);
+        const result = await host.run(command.file, command.args, { cwd: command.cwd ?? cwd, signal, input: stdin });
+        return boundedResult(result.output, result.code, result.truncated);
+    }
+    const result = await backend.run([capability.executable, ...args], { input: stdin, signal });
+    return boundedResult(`${result.stdout}${result.stderr}`, result.exitCode, result.truncated);
+}
+/** Stable display only: this is never passed to a shell. */
+export function quotedMagerunPreview(executable, args) {
+    return [executable, ...args].map((value) => `'${value.replace(/'/g, "'\\''")}'`).join(" ");
+}
+function boundedResult(output, exitCode, alreadyTruncated = false) {
+    const truncated = alreadyTruncated || output.length > MAX_OUTPUT;
+    return { output: truncated ? `${output.slice(0, MAX_OUTPUT)}\n[output truncated]` : output, exitCode, truncated };
+}
+/** Install the official PHAR outside the Magento project; verify its release SHA-256 before publishing it. */
+export async function installMagerun2(home, _cwd, request = fetch) {
     const directory = join(home, "tools", "n98-magerun2");
     const destination = join(directory, "n98-magerun2.phar");
     const digestPath = `${destination}.sha256`;
@@ -49,11 +72,10 @@ export async function installMagerun(home, _cwd, request = fetch) {
     if (!phar.ok)
         throw new Error("official PHAR download failed");
     const bytes = new Uint8Array(await phar.arrayBuffer());
-    const actual = sha256(bytes);
-    if (!expected || actual !== expected)
+    if (sha256(bytes) !== expected)
         throw new Error("PHAR SHA-256 verification failed");
     const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
-    await BunOrNode.write(temporary, bytes);
+    await writeFile(temporary, bytes, { mode: 0o700, flag: "wx" });
     await chmod(temporary, 0o700);
     try {
         await rename(temporary, destination);
@@ -70,4 +92,3 @@ export async function installMagerun(home, _cwd, request = fetch) {
     return destination;
 }
 function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
-const BunOrNode = { async write(path, bytes) { const { writeFile } = await import("node:fs/promises"); await writeFile(path, bytes, { mode: 0o700, flag: "wx" }); } };

package/dist/integrations/pi/context.js

@@ -1,13 +1,20 @@
 import { refreshStatus } from "#app/status";
 import { merchantDuoSystemPrompt } from "#app/system-prompt";
-import { discoverTesting, discoverMagerun } from "#testing/index";
+import { discoverTesting } from "#testing/index";
+import { discoverMagerun2 } from "#features/magerun2/index";
 import { discoverHostExecutable } from "#testing/host";
 import { runtime, sessionEvents } from "#integrations/pi/session";
 export default function context(pi) {
     pi.on("session_start", async (_event, ctx) => {
         runtime.resetInjection();
         const state = await runtime.boot(ctx.cwd);
-        const magerun = await discoverMagerun(state.selected.environment, state.backend, ctx.cwd);
+        if (state.environmentStatus === "stopped") {
+            refreshStatus(ctx, state);
+            sessionEvents.emit("merchantduo.context", state);
+            pi.appendEntry("merchantduo.context", { environment: state.selected.name, environmentStatus: state.environmentStatus });
+            return;
+        }
+        const magerun2 = await discoverMagerun2(state.selected.environment, state.backend, ctx.cwd);
         // HTTP and Chromium deliberately run on the host against Warden's routed URL.
         // Do not use EnvironmentBackend here: its Warden adapter would probe php-fpm.
         // Prefer non-Snap Chrome: Snap Chromium cannot write MerchantDuo artifacts
@@ -16,12 +23,11 @@ export default function context(pi) {
             discoverHostExecutable(["curl"]),
             discoverHostExecutable(["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]),
         ]);
-        runtime.setTesting(await discoverTesting(state.selected.environment, state.backend, ctx.cwd, { ...state.config.testing, ...state.selected.environment.testing, allowInsecureTls: state.selected.environment.testing?.allowInsecureTls ?? state.config.testing.allowInsecureTls }, { http, browser, magerun: magerun.executable }));
-        if (magerun.diagnostic)
-            state.testing?.diagnostics.push(magerun.diagnostic);
+        runtime.setMagerun2(magerun2);
+        runtime.setTesting(await discoverTesting(state.selected.environment, state.backend, ctx.cwd, { ...state.config.testing, ...state.selected.environment.testing, allowInsecureTls: state.selected.environment.testing?.allowInsecureTls ?? state.config.testing.allowInsecureTls }, { http, browser }));
         refreshStatus(ctx, state);
         sessionEvents.emit("merchantduo.context", state);
-        pi.appendEntry("merchantduo.context", { environment: state.selected.name, testing: state.testing });
+        pi.appendEntry("merchantduo.context", { environment: state.selected.name, environmentStatus: state.environmentStatus, testing: state.testing, magerun2: state.magerun2 });
     });
     pi.on("session_compact", () => runtime.resetInjection());
     pi.on("session_shutdown", () => sessionEvents.clear());
@@ -41,6 +47,6 @@ export default function context(pi) {
     pi.on("before_agent_start", async (event, ctx) => {
         const state = await runtime.boot(ctx.cwd);
         const testing = state.testing;
-        return { systemPrompt: `${event.systemPrompt}\n${merchantDuoSystemPrompt()}\nTesting URLs are discovered but unverified. Frontend: ${testing?.frontendUrl ?? "unavailable"}; Admin: ${testing?.adminUrl ?? "unavailable"}. HTTP, browser, navigation, and test artifacts are host-only; never use environment bash to locate or repair their host paths. Use explicit test tools only when relevant.` };
+        return { systemPrompt: `${event.systemPrompt}\n${merchantDuoSystemPrompt()}\nEnvironment: ${state.selected.name} is ${state.environmentStatus}. ${state.environmentStatus === "stopped" ? "Use environment_start only after the user directly asks to start it; do not use project tools until it is running." : "Testing URLs are discovered but unverified. Frontend: " + (testing?.frontendUrl ?? "unavailable") + "; Admin: " + (testing?.adminUrl ?? "unavailable") + ". HTTP, browser, navigation, and test artifacts are host-only; never use environment bash to locate or repair their host paths. Use explicit test tools only when relevant."}` };
     });
 }

package/dist/integrations/pi/environment.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Warden is managed directly; a local project's lifecycle is selected by the agent from live project evidence. */
+export default function environment(pi: ExtensionAPI): void;

package/dist/integrations/pi/environment.js

@@ -0,0 +1,64 @@
+import { Type } from "typebox";
+import { refreshStatus } from "#app/status";
+import { runtime, text } from "#integrations/pi/session";
+/** Warden is managed directly; a local project's lifecycle is selected by the agent from live project evidence. */
+export default function environment(pi) {
+    pi.registerTool({ name: "environment_status", label: "Environment status", description: "Report whether the selected MerchantDuo environment is running or stopped.", parameters: Type.Object({}), async execute(_id, _params, _signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_start", label: "Start environment", description: "Start Warden directly, or run the agent-selected local lifecycle command after inspection.", parameters: Type.Object({ command: Type.Optional(Type.String({ minLength: 1 })) }), async execute(_id, params, signal, _update, ctx) {
+            const state = await change("start", ctx.cwd, params.command, signal);
+            refreshStatus(ctx, state);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_stop", label: "Stop environment", description: "Stop Warden directly, or run the agent-selected local lifecycle command after inspection.", parameters: Type.Object({ command: Type.Optional(Type.String({ minLength: 1 })) }), async execute(_id, params, signal, _update, ctx) {
+            const state = await change("stop", ctx.cwd, params.command, signal);
+            refreshStatus(ctx, state);
+            return text(environmentMessage(state));
+        } });
+    pi.registerTool({ name: "environment_set_status", label: "Set environment status", description: "Record the local environment lifecycle status after inspecting or running its project-specific commands. Include concise command/output evidence.", parameters: Type.Object({ status: Type.Union([Type.Literal("running"), Type.Literal("stopped")]), evidence: Type.String({ minLength: 1 }) }), async execute(_id, params, _signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            if (state.selected.environment.type !== "local")
+                throw new Error("Only local environment status is agent-reported.");
+            refreshStatus(ctx, runtime.setEnvironmentStatus(params.status));
+            return text(`Local environment marked ${params.status}: ${params.evidence}`);
+        } });
+    registerCommand(pi, "duo-env-start", "start");
+    registerCommand(pi, "duo-env-stop", "stop");
+}
+function registerCommand(pi, name, action) {
+    pi.registerCommand(name, { description: `${action === "start" ? "Start" : "Stop"} the selected environment. Warden is direct; local is agent-directed.`, handler: async (_args, ctx) => {
+            const state = await runtime.boot(ctx.cwd);
+            if (state.selected.environment.type === "local") {
+                pi.sendUserMessage(localLifecyclePrompt(action));
+                ctx.ui.notify(`Asked the agent to ${action} the local environment from project evidence.`, "info");
+                return;
+            }
+            const changed = await change(action, ctx.cwd);
+            refreshStatus(ctx, changed);
+            ctx.ui.notify(environmentMessage(changed), "info");
+        } });
+}
+async function change(action, cwd, command, signal) {
+    const state = await runtime.boot(cwd);
+    if (state.selected.environment.type === "ssh")
+        throw new Error("SSH is always reported running; MerchantDuo never controls remote services.");
+    if (state.selected.environment.type === "local") {
+        if (!command)
+            throw new Error(`Inspect the local project first, then call environment_${action} with its exact lifecycle command.`);
+        const result = await state.backend.run(["sh", "-lc", command], { signal });
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr || result.stdout || `Could not ${action} local environment`);
+        return runtime.setEnvironmentStatus(action === "start" ? "running" : "stopped");
+    }
+    return action === "start" ? runtime.startEnvironment(cwd) : runtime.stopEnvironment(cwd);
+}
+function localLifecyclePrompt(action) {
+    return `The user directly requested that you ${action} the selected local environment. This local stack is not assumed to use any one runtime. Inspect the project documentation, package scripts, Compose files, service configuration, and existing process state first. Determine the smallest correct ${action} command, explain the evidence and intended effect, then execute it through environment_${action} with the exact command. Do not use a generic command, do not stop unrelated host services, and if the project lifecycle cannot be determined safely, ask the user. After a successful command, the tool records ${action === "start" ? "running" : "stopped"}.`;
+}
+function environmentMessage(state) {
+    const environment = state.selected.environment;
+    const managed = environment.type === "warden" ? "Warden-managed" : environment.type === "local" ? "agent-directed" : "remote unmanaged";
+    return `${state.selected.name} (${environment.type}): ${state.environmentStatus} [${managed}]`;
+}

package/dist/integrations/pi/magerun2.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Generic magerun2 is intentionally separate from the typed PHP console. */
+export default function magerun2(pi: ExtensionAPI): void;
+export declare function magerun2Refusal(args: string[], readOnlySsh: boolean): string | undefined;

package/dist/integrations/pi/magerun2.js

@@ -0,0 +1,37 @@
+import { Type } from "typebox";
+import { quotedMagerunPreview, runMagerun2 } from "#features/magerun2/index";
+import { runtime, text } from "#integrations/pi/session";
+/** Generic magerun2 is intentionally separate from the typed PHP console. */
+export default function magerun2(pi) {
+    pi.registerTool({
+        name: "magerun2",
+        label: "n98-magerun2",
+        description: "Preview or explicitly run one structured n98-magerun2 subcommand in the selected environment. Use magento_php_repl for dev:console.",
+        parameters: Type.Object({
+            args: Type.Array(Type.String(), { minItems: 1 }),
+            stdin: Type.Optional(Type.String()),
+            execute: Type.Optional(Type.Boolean()),
+        }),
+        async execute(_id, params, signal, _update, ctx) {
+            const state = await runtime.boot(ctx.cwd);
+            const refusal = magerun2Refusal(params.args, state.selected.environment.type === "ssh" && !state.selected.environment.writable);
+            if (refusal)
+                return text(refusal);
+            const capability = state.magerun2;
+            if (!capability?.executable)
+                return text(capability?.diagnostic ?? "n98-magerun2 is unavailable.");
+            const preview = quotedMagerunPreview(capability.executable, params.args);
+            if (!params.execute)
+                return text(`Preview: ${preview}\nSet execute=true only after the user directly requests execution.`);
+            const result = await runMagerun2(capability, state.selected.environment, state.backend, ctx.cwd, params.args, params.stdin, signal);
+            return text(`Exit status: ${result.exitCode}${result.truncated ? " (output truncated)" : ""}\n${result.output}`);
+        },
+    });
+}
+export function magerun2Refusal(args, readOnlySsh) {
+    if (args.includes("dev:console"))
+        return "Refused: dev:console belongs to magento_php_repl, which accepts a typed snippet and optional area.";
+    if (readOnlySsh)
+        return "Refused: generic magerun2 is unavailable for read-only SSH because arbitrary subcommands cannot be classified safely.";
+    return undefined;
+}

package/dist/integrations/pi/optional-services.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+/** Change these constants when MerchantDuo's hosted services change; never expose URL configuration. */
+export declare const KNOWLEDGE_MCP_BASE_URL = "https://merchantduo.invalid/mcp";
+export declare const MERCHANTDUO_LLM_BASE_URL = "https://merchantduo.invalid/v1";
+export declare const MERCHANTDUO_LLM_PROVIDER = "merchantduo";
+export declare const MERCHANTDUO_LLM_MODEL = "merchantduo-mock";
+export declare function mcpToken(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function llmProviderConfig(env?: NodeJS.ProcessEnv): ProviderConfig | undefined;
+export default function optionalServices(pi: ExtensionAPI): void;

package/dist/integrations/pi/optional-services.js

@@ -0,0 +1,79 @@
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { Type } from "typebox";
+import { text } from "#integrations/pi/session";
+/** Change these constants when MerchantDuo's hosted services change; never expose URL configuration. */
+export const KNOWLEDGE_MCP_BASE_URL = "https://merchantduo.invalid/mcp";
+export const MERCHANTDUO_LLM_BASE_URL = "https://merchantduo.invalid/v1";
+export const MERCHANTDUO_LLM_PROVIDER = "merchantduo";
+export const MERCHANTDUO_LLM_MODEL = "merchantduo-mock";
+export function mcpToken(env = process.env) {
+    return env.MERCHANTDUO_MCP_TOKEN || undefined;
+}
+export function llmProviderConfig(env = process.env) {
+    if (!env.MERCHANTDUO_LLM_TOKEN)
+        return undefined;
+    return {
+        name: "MerchantDuo",
+        baseUrl: MERCHANTDUO_LLM_BASE_URL,
+        apiKey: "$MERCHANTDUO_LLM_TOKEN",
+        api: "openai-completions",
+        models: [{
+                id: MERCHANTDUO_LLM_MODEL,
+                name: "MerchantDuo",
+                input: ["text"],
+                reasoning: false,
+                contextWindow: 32_768,
+                maxTokens: 4_096,
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            }],
+    };
+}
+async function withKnowledgeClient(token, run) {
+    const transport = new StreamableHTTPClientTransport(new URL(KNOWLEDGE_MCP_BASE_URL), {
+        authProvider: { token: async () => token },
+    });
+    const client = new Client({ name: "merchantduo", version: "0.2.0" });
+    try {
+        await client.connect(transport);
+        return await run(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+export default function optionalServices(pi) {
+    const provider = llmProviderConfig();
+    if (provider)
+        pi.registerProvider(MERCHANTDUO_LLM_PROVIDER, provider);
+    const token = mcpToken();
+    if (!token)
+        return;
+    pi.registerTool({
+        name: "merchantduo_knowledge",
+        label: "MerchantDuo knowledge",
+        description: "Use the built-in read-only MerchantDuo knowledge MCP. Omit tool to list its tools, then pass a listed tool name and a JSON object of arguments.",
+        parameters: Type.Object({ tool: Type.Optional(Type.String()), arguments: Type.Optional(Type.String()) }),
+        async execute(_id, params) {
+            try {
+                const result = await withKnowledgeClient(token, async (client) => {
+                    if (!params.tool)
+                        return await client.listTools();
+                    const tools = await client.listTools();
+                    const selected = tools.tools.find((tool) => tool.name === params.tool);
+                    if (!selected)
+                        throw new Error(`unknown MCP tool: ${params.tool}`);
+                    if (!selected.annotations?.readOnlyHint)
+                        throw new Error(`refused non-read-only MCP tool: ${params.tool}`);
+                    const arguments_ = params.arguments ? JSON.parse(params.arguments) : {};
+                    if (!arguments_ || Array.isArray(arguments_) || typeof arguments_ !== "object")
+                        throw new Error("arguments must be a JSON object");
+                    return await client.callTool({ name: params.tool, arguments: arguments_ });
+                });
+                return text(JSON.stringify(result));
+            }
+            catch (error) {
+                return text(`MerchantDuo knowledge MCP unavailable: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/integrations/pi/permissions.js

@@ -1,6 +1,6 @@
 import { runtime } from "#integrations/pi/session";
 export function requiresExecuteConfirmation(toolName, input) {
-    return (toolName === "mage2gen_generate_module" || toolName === "magento_workflow") && input.execute === true;
+    return ["environment_start", "environment_stop"].includes(toolName) || ((toolName === "mage2gen_generate_module" || toolName === "magento_workflow" || toolName === "magerun2") && input.execute === true);
 }
 export function requiresSshConfirmation(environment, toolName) {
     return environment.type === "ssh" && environment.writable && ["write", "edit", "bash"].includes(toolName);
@@ -10,6 +10,8 @@ export default function permissions(pi) {
     pi.on("tool_call", async (event, ctx) => {
         const state = await runtime.boot(ctx.cwd);
         const input = event.input;
+        if (state.environmentStatus === "stopped" && !["environment_status", "environment_start", "environment_stop", "environment_set_status"].includes(event.toolName))
+            return { block: true, reason: "MerchantDuo: selected environment is stopped. Start it first." };
         if (requiresExecuteConfirmation(event.toolName, input)) {
             const ok = ctx.hasUI && await ctx.ui.confirm("Confirm Magento action", `Execute ${event.toolName}?`);
             return ok ? undefined : { block: true, reason: "Cancelled: confirmation required." };

package/dist/integrations/pi/testing.js

@@ -58,21 +58,22 @@ export default function testing(pi) {
             const state = await runtime.boot(ctx.cwd);
             if (state.selected.environment.type === "ssh" && !state.selected.environment.writable)
                 return text("PHP REPL is unavailable for read-only SSH.");
-            const executable = state.testing?.phpRepl.executable;
+            const executable = state.magerun2?.executable;
             if (!executable)
-                return text(state.testing?.phpRepl.reason ?? "PHP REPL unavailable.");
-            const args = [executable, "dev:console"];
+                return text(state.magerun2?.diagnostic ?? "PHP REPL unavailable.");
+            const args = ["dev:console"];
             if (params.area)
                 args.push(`--area=${params.area}`);
             if (state.selected.environment.type === "local") {
-                const result = await host.run("sh", ["-lc", `${quote(executable)} dev:console${params.area ? ` --area=${params.area}` : ""}`], { cwd: ctx.cwd, signal, input: params.snippet });
+                const command = state.backend.command([executable, ...args]);
+                const result = await host.run(command.file, command.args, { cwd: command.cwd ?? ctx.cwd, signal, input: params.snippet });
                 return text(bound(result.output));
             }
-            const result = await state.backend.run(args, { input: params.snippet, signal });
+            const result = await state.backend.run([executable, ...args], { input: params.snippet, signal });
             return text(bound(`${result.stdout}${result.stderr}`));
         } });
-    registerNavigate(pi, "navigate-frontend", "frontend");
-    registerNavigate(pi, "navigate-adminhtml", "adminhtml");
+    registerNavigate(pi, "duo-navigate-frontend", "frontend");
+    registerNavigate(pi, "duo-navigate-adminhtml", "adminhtml");
 }
 function registerNavigate(pi, name, target) { pi.registerCommand(name, { description: `Open the discovered Magento ${target} URL in the default browser.`, handler: async (args, ctx) => { const state = await runtime.boot(ctx.cwd); const base = target === "frontend" ? state.testing?.frontendUrl : state.testing?.adminUrl; const url = targetUrl(base, args.trim() || "/"); if (!url) {
         ctx.ui.notify("URL unavailable or path is not same-origin.", "error");
@@ -84,5 +85,4 @@ function registerNavigate(pi, name, target) { pi.registerCommand(name, { descrip
 function targetUrl(base, path) { if (!relativePath(path))
     return undefined; const url = joinedUrl(base, path); return url && sameOrigin(base, url) ? url : undefined; }
 function projectId(cwd) { return cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").slice(-80) || "project"; }
-function quote(value) { return `'${value.replace(/'/g, "'\\''")}'`; }
 const BunOrNode = { async write(path, value) { const { writeFile } = await import("node:fs/promises"); await writeFile(path, value, "utf8"); } };

package/dist/integrations/pi/theme.js

@@ -1,6 +1,6 @@
 import { refreshStatus } from "#app/status";
 import { runtime } from "#integrations/pi/session";
-export default function theme(pi) { pi.registerCommand("theme", { description: "Select all, any, or a detected Magento theme.", handler: async (args, ctx) => { const state = await runtime.boot(ctx.cwd); const value = args.trim(); const choices = ["all", "any", ...state.magento.themes.map((theme) => theme.code)]; if (!choices.includes(value)) {
+export default function theme(pi) { pi.registerCommand("duo-switch-theme", { description: "Select all, any, or a detected Magento theme.", handler: async (args, ctx) => { const state = await runtime.boot(ctx.cwd); const value = args.trim(); const choices = ["all", "any", ...state.magento.themes.map((theme) => theme.code)]; if (!choices.includes(value)) {
         ctx.ui.notify(`Choose one of: ${choices.join(", ")}`, "error");
         return;
     } const changed = await runtime.changeTheme(ctx.cwd, value); refreshStatus(ctx, changed); ctx.ui.notify(`Theme scope set to ${value}.`, "info"); } }); }

package/dist/integrations/pi/workflows.js

@@ -6,7 +6,7 @@ export default function workflows(pi) {
     pi.registerTool({ name: "magento_workflow", label: "Magento workflow", description: "Preview or explicitly execute a supported Magento operational action.", parameters: Type.Object({ action: Type.String(), execute: Type.Optional(Type.Boolean()) }), async execute(_id, params, _signal, _update, ctx) {
             const state = await runtime.boot(ctx.cwd);
             if (params.action === "status")
-                return text(JSON.stringify({ snapshot: state.magento, testing: state.testing, pendingFiles: runtime.changes.files(), workflows: builtInWorkflows.map(({ id, description }) => ({ id, description })) }, null, 2));
+                return text(JSON.stringify({ snapshot: state.magento, testing: state.testing, magerun2: state.magerun2, pendingFiles: runtime.changes.files(), workflows: builtInWorkflows.map(({ id, description }) => ({ id, description })) }, null, 2));
             if (params.action === "syntax-check")
                 return text((await syntaxCheck(state.backend, runtime.changes.files())).join("\n") || "No supported changed files require syntax checks.");
             const workflow = builtInWorkflows.find(({ id }) => id === params.action);

package/dist/testing/discovery.d.ts

@@ -4,7 +4,6 @@ import type { TestingOptions, TestingSnapshot } from "#testing/model";
 export declare function discoverTesting(environment: Environment, backend: EnvironmentBackend, cwd: string, options: TestingOptions, tools?: {
     http?: string;
     browser?: string;
-    magerun?: string;
 }): Promise<TestingSnapshot>;
 export declare function wardenRouting(projectRoot: string): Promise<string | undefined>;
 export declare function findExecutable(candidates: string[]): Promise<string | undefined>;

package/dist/testing/discovery.js

@@ -32,16 +32,13 @@ export async function discoverTesting(environment, backend, cwd, options, tools
     const browser = tools.browser
         ? { available: true, executable: tools.browser }
         : { available: false, reason: "Install Chromium or Chrome." };
-    const phpRepl = tools.magerun
-        ? { available: true, executable: tools.magerun }
-        : { available: false, reason: "n98-magerun2 is unavailable." };
     if (!frontendUrl)
         diagnostics.push("Frontend URL unavailable.");
     if (!adminUrl)
         diagnostics.push("Admin URL unavailable.");
     diagnostics.push("URLs are discovered but unverified; no startup HTTP request was made.");
     const http = tools.http ? { available: true, executable: tools.http } : { available: false, reason: "Install curl." };
-    return { frontendUrl, adminUrl, http, browser, phpRepl, diagnostics };
+    return { frontendUrl, adminUrl, http, browser, diagnostics };
 }
 export async function wardenRouting(projectRoot) {
     try {

package/dist/testing/host.d.ts

@@ -1,6 +1,7 @@
 export type HostProcessResult = {
     output: string;
     code: number;
+    truncated?: boolean;
 };
 export interface HostProcessRunner {
     run(file: string, args: string[], options: {

package/dist/testing/host.js

@@ -7,16 +7,27 @@ export class NodeHostProcessRunner {
         return new Promise((done) => {
             const child = spawn(file, args, { cwd: options.cwd, signal: options.signal });
             let output = "";
+            let truncated = false;
             let settled = false;
             const finish = (result) => { if (!settled) {
                 settled = true;
                 done(result);
             } };
-            const add = (data) => { output = bound(output + data.toString()); };
+            const add = (data) => {
+                if (truncated)
+                    return;
+                const next = output + data.toString();
+                if (next.length > MAX_OUTPUT) {
+                    output = `${next.slice(0, MAX_OUTPUT)}\n[output truncated]`;
+                    truncated = true;
+                }
+                else
+                    output = next;
+            };
             child.stdout.on("data", add);
             child.stderr.on("data", add);
-            child.on("error", (error) => finish({ output: error.message, code: 127 }));
-            child.on("close", (code) => finish({ output, code: code ?? 1 }));
+            child.on("error", (error) => finish({ output: error.message, code: 127, truncated }));
+            child.on("close", (code) => finish({ output, code: code ?? 1, truncated }));
             if (options.input !== undefined)
                 child.stdin.end(options.input);
         });

package/dist/testing/index.d.ts

@@ -1,5 +1,4 @@
 export * from "#testing/model";
 export * from "#testing/url";
 export * from "#testing/discovery";
-export * from "#testing/magerun";
 export * from "#testing/host";

package/dist/testing/index.js

@@ -1,5 +1,4 @@
 export * from "#testing/model";
 export * from "#testing/url";
 export * from "#testing/discovery";
-export * from "#testing/magerun";
 export * from "#testing/host";

package/dist/testing/model.d.ts

@@ -8,7 +8,6 @@ export type TestingSnapshot = {
     adminUrl?: string;
     http: Capability;
     browser: Capability;
-    phpRepl: Capability;
     diagnostics: string[];
 };
 export type TestingOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merchantduo/code",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.3",
   "private": false,
   "description": "Magento-native Pi-based Coding Agent",
   "type": "module",
@@ -40,11 +40,14 @@
   "pi": {
     "extensions": [
       "./dist/integrations/pi/context.js",
+      "./dist/integrations/pi/optional-services.js",
       "./dist/integrations/pi/permissions.js",
       "./dist/integrations/pi/workspace.js",
+      "./dist/integrations/pi/environment.js",
       "./dist/integrations/pi/theme.js",
       "./dist/integrations/pi/mage2gen.js",
       "./dist/integrations/pi/workflows.js",
+      "./dist/integrations/pi/magerun2.js",
       "./dist/integrations/pi/testing.js"
     ],
     "skills": [
@@ -54,6 +57,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.1",
+    "@modelcontextprotocol/client": "2.0.0",
     "typebox": "1.3.7",
     "yaml": "^2.8.1",
     "zod": "^3.24.4"

package/skills/magerun2/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: magerun2
+description: Use structured n98-magerun2 commands for Magento operations that MerchantDuo does not model as a workflow.
+---
+
+# Universal magerun2
+
+MerchantDuo discovers magerun2 once for the selected environment. Local uses a project binary, PATH binary, or a verified official PHAR cache; Warden uses its PHP service; SSH uses its remote binary. The capability and diagnostic appear in `magento_workflow` status.
+
+Use `magento_workflow` for its supported cache, deployment, indexing, and test operations. Use `magerun2` only for a command that the workflow does not model. Pass exact structured arguments, never a shell command string. For example:
+
+```json
+{"args":["list"]}
+```
+
+```json
+{"args":["help","sys:cron:list"]}
+```
+
+Without `execute: true`, the tool returns an exact quoted preview. Set `execute: true` only after the user directly asks to run the command; MerchantDuo then provides its one confirmation dialog. `stdin` is optional for subcommands that require it.
+
+Do not call `dev:console` through this tool. Use `magento_php_repl` with its typed `snippet` and optional `area`. Generic magerun2 is refused on read-only SSH because arbitrary subcommands cannot be safely classified.

package/dist/testing/magerun.d.ts

@@ -1,8 +0,0 @@
-import type { EnvironmentBackend } from "#environments/backend";
-import type { Environment } from "#environments/model";
-export declare function discoverMagerun(environment: Environment, backend: EnvironmentBackend, cwd: string): Promise<{
-    executable?: string;
-    diagnostic?: string;
-}>;
-/** Install the official PHAR outside the Magento project; verify the release API SHA-256 digest before publishing it. */
-export declare function installMagerun(home: string, _cwd: string, request?: typeof fetch): Promise<string>;