@aefree/pi-unity 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.9.3] - 2026-08-10
+
+### Added
+
+- Added an optional `automated` parameter to `unity_open_editor`, forwarding Unity Editor's `-automated` flag through both Unity CLI and direct Editor launch paths.
+
+## [0.9.2] - 2026-08-08
+
+### Changed
+
+- Allow connected Pipeline tools to exit Play Mode by default when required, while retaining session-scoped opt-out control and verified lifecycle transitions.
+
 ## [0.9.1] - 2026-08-05
 
 ### Added

package/README.md

@@ -1,110 +1,142 @@
 # Pi Unity
 
-Pi skill and tool package for reusable Unity workflows.
-
-## Contents
-
-- skill: `unity-debugging`
-- skill: `unity-pipeline-workflows`
-- skill: `unity-batchmode-tests`
-- skill: `unity-interactive-playmode-authoring`
-- skill: `auditing-unity-agent-guidance`
-- tool: `unity_guidance_audit`
-- tool: `unity_project_status`
-- tool: `unity_pipeline_recompile`
-- tool: `unity_pipeline_run_tests`
-- tool: `unity_pipeline_eval`
-- tool: `unity_pipeline_inspect`
-- tool: `unity_inspect_artifacts`
-- tool: `unity_open_editor`
-- tool: `unity_launch_batchmode`
-- tool: `unity_run_test_batch`
-- commands: `/unity-open`, `/unity-playmode-exit`
-
-## Skill boundaries
-
-Each packaged skill owns a distinct kind of Unity work:
-
-- `unity-debugging` owns reusable diagnostic strategy across Editor, runtime, package, asset, lifecycle, callback, and feature-activation problems.
-- `unity-pipeline-workflows` owns connected compilation and focused test execution through an already-running exact-copy Pipeline Editor.
-- `unity-batchmode-tests` owns isolated or report-producing Unity Test Framework execution.
-- `unity-interactive-playmode-authoring` owns explicit temporary inspection and tuning of live runtime state, followed by deliberate persistence when requested.
-- `auditing-unity-agent-guidance` owns review and migration of project-local Unity automation instructions.
-
-Operation-specific failure handling remains with the owning operational skill. `unity-debugging` owns reusable diagnostic strategy, not every troubleshooting instruction associated with Unity operations.
+Pi tools and skills for reliable Unity Editor, Pipeline, batchmode, testing, and project-guidance workflows.
 
 ## Install
 
+From npm:
+
+```bash
+pi install npm:@aefree/pi-unity
+```
+
 From GitHub:
 
 ```bash
 pi install git:git@github.com:aefreedman/pi-unity.git
 ```
 
-Local development install:
+For local development:
 
 ```bash
 pi install <path-to-pi-unity>
+pi install -l <path-to-pi-unity> # project-local
 ```
 
-Project-local install:
+Pi discovers the extension from `index.ts` and packaged skills from `skills/`.
 
-```bash
-pi install -l <path-to-pi-unity>
-```
+## Included tools
+
+### Connected Pipeline
+
+Use these tools with an already-open exact Unity project copy that has a reachable `com.unity.pipeline` instance:
+
+- `unity_project_status` — inspect lockfiles, matching Unity processes, Pipeline reachability, package version, and advertised commands without launching Unity.
+- `unity_pipeline_recompile` — recompile through Pipeline with exact-copy preflight, bounded polling, and compact compiler evidence.
+- `unity_pipeline_run_tests` — run one focused EditMode or PlayMode selection with bounded polling and aggregate results.
+- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL.
+- `unity_pipeline_inspect` — dispatch supported package-owned inspection commands and return structured evidence.
+
+Connected recompilation follows Unity's Script Changes While Playing policy and never preemptively sends `editor_stop`. Connected tests may exit Play Mode through advertised `editor_stop` when necessary, then verify Edit Mode before dispatch. Play Mode exit is allowed by default; `/unity-playmode-exit allow|disallow|status` controls the current session.
+
+A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode.
+
+### Editor and batchmode
+
+- `unity_open_editor` — open the Unity Editor GUI. Pass `automated: true` to add the Unity Editor `-automated` flag; this is distinct from the Unity CLI's own `--non-interactive` option.
+- `unity_launch_batchmode` — run a bounded batchmode command through Unity CLI or the direct Editor executable.
+- `unity_run_test_batch` — run one isolated or report-producing Unity Test Framework platform with generated XML and log paths.
+- `unity_inspect_artifacts` — summarize existing Unity Test Framework XML and Unity logs without launching Unity.
+
+Use connected tests when the exact project is already open and Pipeline testing is reachable. Use `unity_run_test_batch` for closed projects, CI-style isolation, categories or multiple filters, graphics-dependent PlayMode tests, or required NUnit XML/log evidence.
+
+Batchmode runs use `-nographics` by default. Set `useGraphics: true` only for screenshots, visual capture, render checks, or graphics-dependent tests. Unity permits only one process per project folder, so all launch routes verify the exact project and use a per-project mutex.
+
+### Guidance audit
+
+- `unity_guidance_audit` — inspect AGENTS.md, CLAUDE.md, Copilot, and Cursor instructions for outdated or unsafe Unity automation guidance without editing them.
+
+### Commands
+
+- `/unity-open` — open the current Unity project copy or choose a nearby copy.
+- `/unity-playmode-exit` — allow, disallow, or inspect Play Mode exit behavior for the current session.
+
+## Included skills
 
-## Notes
-
-- Pi discovers packaged skills from `skills/` and extensions from `index.ts`.
-- `unity-debugging` provides general-purpose, evidence-first Unity diagnosis. For inactive features it routes agents through exact-version documentation, documented feature gates, and observable activation signals before project code, reflection, assembly searches, or Unity internals. Its UI Toolkit example checks the Game View Live Reload setting before callback diagnosis.
-- `@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery` are independent optional peer integrations. When their Pi tools are active, pi-unity uses the capability contracts' global registry rendezvous to register a Unity solution-artifact profile candidate and/or generated-directory file-discovery filter. It never resolves optional peers from pi-unity's own module root, so separately installed Git/local packages compose correctly. Core Unity tools load without them; an advertised malformed registry contract fails visibly. Registrations are scoped, reverse-load-order safe, transactional across active integrations, and a delayed old-session shutdown cannot remove another scope's current records. Project artifacts remains schema-open: the Unity profile contributes applicability, definitions, validation, and confidence only; Unity metadata remains raw-filterable when this provider is absent. Provider development follows the [project-artifacts profile-provider contract](https://github.com/aefreedman/pi-project-artifacts/blob/main/docs/artifact-profile-providers.md).
-- The Unity filter recommends excluding `Library`, `Temp`, `Logs`, `obj`, `Build`, `Builds`, `UserSettings`, and `.vs` from broad project-root discovery. Broad exclusions declare `filterDecision: "applied"` with decision code `unity_broad_generated_directories_applied`; an exact generated or `Library/PackageCache/...` root is searched with the explicit `filterDecision: "bypassed"` code `unity_exact_generated_root_bypassed`, rather than a compatibility sentinel glob. File-discovery filter failures degrade discovery filtering rather than authorizing or blocking inspection; the canonical file-discovery package remains Unity-neutral.
-- The optional artifact profile describes `engine`, `unity_version`, `unity_packages`, `render_pipeline`, and `platforms` for solution and memory artifacts. Every field is optional; present fields receive type/enum validation while undeclared project metadata remains open. Artifact paths already distinguish solutions from memories, and evolving project vocabulary belongs in generic `tags`, `module`, or `component` fields rather than a Unity-owned document taxonomy. The profile contributes only when the workspace has Unity `ProjectVersion.txt` evidence, so a conventional artifact path never selects it by itself.
-- `unity_guidance_audit` performs a bounded, read-only scan of AGENTS.md, CLAUDE.md, Copilot, and Cursor guidance for outdated Unity CLI/Pipeline, batchmode, test, lifecycle, and exact-project-copy instructions. The `auditing-unity-agent-guidance` skill owns contextual migration and user-authorized edits.
-- `unity_open_editor` launches the full Unity Editor GUI.
-- `unity_open_editor` prefers the installed `unity open` CLI when available, falling back to direct editor executable launch.
-- `unity_project_status` reports native Unity lockfile state, Unity CLI status output, running Unity processes, the locally declared `com.unity.pipeline` version, exact-project-copy Pipeline instances, and bounded live advertised commands without launching Unity. Pipeline discovery has distinct `absent`, `timeout`, and `unavailable` states; a timeout is startup uncertainty rather than proof of absence. Rendered process command lines redact access tokens and credential-like values.
-- `unity_inspect_artifacts` summarizes existing Unity Test Framework XML results and Unity logs without launching Unity, reducing ad hoc shell parsing after failures.
-- Planning and test routing preserve the exact project copy: a reachable Pipeline Editor is a positive connected inspection surface, and the project should run connected tests without closing the Editor or replacing it with a second Editor. Other connected operations use that same exact copy. `unity_pipeline_eval` rechecks canonical identity and advertised `eval` immediately before dispatch and is the general REPL escape hatch for project-specific properties and questions that registered commands did not anticipate. `unity_pipeline_inspect` exposes the package-owned purpose-built inspection commands when their structured results fit the question. Tooling should bound the request and result, preserve exact-copy evidence, and distinguish reads from mutations—not maintain a brittle API-property allowlist or pretend arbitrary C# can be proven read-only from syntax alone.
-- `unity-pipeline-workflows` routes focused connected work through `unity_pipeline_recompile` and `unity_pipeline_run_tests`. Each performs exact-copy preflight, advertised-command checks, lifecycle inspection, identity-aware bounded internal polling, and compact output in one model-visible call. `unity_pipeline_recompile` never preemptively sends `editor_stop`: while Play Mode is active it honors Unity's Script Changes While Playing policy (continue, stop-and-recompile, or defer) when future `editor_status` payloads expose it, and reports unavailable policy as uncertainty. Connected tests retain a separate explicit lifecycle guard. Pipeline `no_tests`/idle status is treated as safe pre-dispatch inactivity rather than uncertainty. Timeouts are uncertain and do not cancel, retry, close Unity, or switch to batchmode. Connected tests do not inherently produce NUnit XML.
-- `unity_run_test_batch` is the preferred isolated/report-producing Unity Test Framework entry point, not a reason to close a reachable Pipeline Editor. Choose it for a closed project, intentional CI isolation, category/multiple filters unsupported by the single connected test-name filter, or required NUnit XML/log artifacts. It runs exactly one EditMode or PlayMode batch, combines filter/category arrays into one launch, creates collision-safe absolute XML/log paths under the project `Logs` directory, omits `-quit`, and uses the same guarded launcher as `unity_launch_batchmode`.
-- `unity_launch_batchmode` prefers the installed `unity run` CLI when available, falling back to direct editor executable batchmode launch; use it when custom raw Editor arguments are required.
-- `unity_launch_batchmode` adds `-nographics` by default to avoid unnecessary graphics initialization and reduce focus stealing; set `useGraphics: true` only for screenshots, visual capture, render checks, or graphics-dependent PlayMode tests.
-- Unity GUI, generic batchmode, and test-batch tools expose `launcher` (`auto`, `unity-cli`, or `editor-executable`) so workflows can force direct Editor execution when Unity CLI argument handling differs from `Unity.exe`/`Unity`. Every launch route keeps same-project process verification and a per-project mutex; unknown process state blocks launch. Direct Editor execution blocks native lockfiles, while Unity CLI may handle a stale lockfile only after pi-unity verifies no matching project process.
-- In Unity CLI mode, `unity_launch_batchmode` forwards args after `unity run <project> --` and strips direct-Editor flags managed by the CLI (`-batchmode`, `-projectPath`, `-quit`).
-- `unity_run_test_batch`, `unity_launch_batchmode`, and `unity_inspect_artifacts` require parsed Unity Test Framework results to report a known positive executed-test count and no failures before treating them as passing evidence. Zero-test, unknown-total, missing-result, malformed-result, and failing batches are non-passing; full artifacts remain on disk while session details retain bounded excerpts and byte counts.
-- Validation guidance treats explicit user/project PlayMode skips as authoritative, distinguishes baseline compile/EditMode evidence from optional PlayMode evidence, and stops unchanged relaunch loops after hangs or infrastructure failures in favor of one inspection of the exact current-run artifact paths.
-- `unity_launch_batchmode` uses Unity CLI status and direct process scans before launch. In Unity CLI mode, stale native `Temp/UnityLockfile` detection is delegated to `unity run`; direct Editor executable mode still blocks on the native lockfile for safety. A Pi-side project mutex prevents duplicate packaged batchmode calls from spawning Unity concurrently.
-- `unity_launch_batchmode` can close a same-project blocking Unity process only when isolated execution was deliberately selected, the tool call sets `closeBlockingUnityProcess: true`, and Pi settings enable `piUnity.allowCloseRunningUnityProcess`. Do not use this to replace reachable connected Pipeline testing. The tool re-scans and selects matching Unity processes itself; it never accepts a model-supplied PID.
-- After a guarded same-call close, `unity_launch_batchmode` may remove the exact resolved project's stale `Temp/UnityLockfile` only after verifying no matching Unity process remains. It still refuses general lockfile deletion outside that guarded continuation.
-- When using `closeBlockingUnityProcess: true`, prefer `launcher: "auto"` or `launcher: "unity-cli"`; force `launcher: "editor-executable"` only when direct Editor execution is explicitly required.
-- If a Unity launch is blocked by a lockfile, run `unity_project_status` before asking a user to remove anything.
-- `/unity-open` is the user-facing GUI launcher helper.
-- The package resolves Unity project copies from a direct project root, a coordination root containing multiple copies, or another nearby folder. Pipeline routing validates canonical project-path identity after CLI discovery so similarly named copies are not treated as interchangeable; connected commands always receive the exact resolved project path.
-- Installing and starting `com.unity.pipeline@0.3.1-exp.1` is a broader project mutation than adding its manifest entry: its server startup assigns `Application.runInBackground = true`, which Unity persists as `PlayerSettings.runInBackground` in `ProjectSettings/ProjectSettings.asset`. Review that tracked change alongside `manifest.json` and `packages-lock.json`.
-- Unity install probing is OS-aware and avoids machine-specific assumptions by using the project's `ProjectSettings/ProjectVersion.txt`, the optional `unity` CLI, standard per-OS install locations, and optional `UNITY_EDITOR_PATH` overrides.
-- Unity allows only one process per project folder; GUI and batchmode both count.
-- The `unity-batchmode-tests` skill is intended for Unity Test Framework CLI runs.
-- Keep skill-specific references and helper assets under the skill directory beside `SKILL.md`.
-
-## Connected Pipeline and `eval` policy
-
-Registered Pipeline commands are ergonomic shortcuts for anticipated workflows. Advertised `eval` covers the operations and inspections that were not anticipated: it compiles C# with Roslyn, runs it on the connected Editor's main thread, and returns the result. This is a live REPL into the exact running project, not merely a restricted planning expression evaluator.
-
-Use the registered `unity_pipeline_eval` tool with bounded C# `code`, for example:
+Each skill owns a distinct workflow:
+
+- `unity-debugging` — evidence-first diagnosis of Editor, runtime, package, asset, lifecycle, callback, and feature-activation problems.
+- `unity-pipeline-workflows` — connected compilation and focused tests through an already-running exact-copy Pipeline Editor.
+- `unity-batchmode-tests` — isolated or report-producing Unity Test Framework execution.
+- `unity-interactive-playmode-authoring` — temporary live runtime inspection and tuning followed by deliberate persistence when requested.
+- `auditing-unity-agent-guidance` — review and migration of project-local Unity automation instructions.
+
+Operation-specific recovery belongs to the operational skill. `unity-debugging` supplies the reusable diagnostic strategy rather than duplicating every workflow's failure handling.
+
+## Choosing a workflow
+
+| Situation | Preferred route |
+| --- | --- |
+| Open exact-copy Editor with reachable Pipeline | Connected Pipeline tools |
+| Closed project or intentional CI isolation | `unity_run_test_batch` or `unity_launch_batchmode` |
+| Required NUnit XML or Unity log evidence | `unity_run_test_batch` |
+| Existing failed-run artifacts | `unity_inspect_artifacts` |
+| Project-specific C# query or operation | `unity_pipeline_eval` |
+| Supported structured project inspection | `unity_pipeline_inspect` |
+| Open the GUI explicitly | `unity_open_editor` or `/unity-open` |
+
+Pass an explicit project `path` when multiple copies may be discovered. Pipeline routing compares canonical paths so similarly named copies are not treated as interchangeable.
+
+## Pipeline safety and evidence
+
+The connected compile and test tools:
+
+- require advertised commands before dispatch;
+- verify the exact project copy and Pipeline identity;
+- poll internally with fixed deadlines and bounded backoff;
+- reject malformed or semantically failing nested results;
+- require a known positive test count and zero failures before reporting a pass;
+- discard passing-test records while retaining bounded failure diagnostics;
+- detect pre-existing or clearly displaced test runs when available correlation fields permit it.
+
+Another connected client is not a project lock. When Pipeline returns stable correlation fields, conflicting status is reported as displaced and uncertain. If Pipeline omits stable run identity, a competing same-mode, same-filter run may be indistinguishable from the requested run; the tool cannot prove exclusive ownership from shared Editor status alone.
+
+### Pipeline eval
+
+`unity_pipeline_eval` compiles C# with Roslyn and runs it on the connected Editor main thread. It is a live REPL, not an expression-only or statically read-only evaluator.
 
 ```text
 { code: "return UnityEditor.EditorSettings.scriptChangesDuringPlay;" }
 { code: "var s = UnityEngine.Application.dataPath; return s.Length;" }
 ```
 
-Use `unity_pipeline_inspect` for purpose-built connected reads such as `editor_status` or `get_scene_hierarchy`; eval is intentionally owned only by `unity_pipeline_eval`.
+Use `unity_pipeline_inspect` when a purpose-built structured command fits. Use eval for bounded project-specific work that matches the user's intent. Prefer typed tools when they provide stronger lifecycle, polling, validation, or recovery semantics.
+
+## Launch and process safeguards
+
+`unity_open_editor` and batchmode tools prefer the installed Unity CLI and can fall back to the direct Editor executable. Set `launcher` to `auto`, `unity-cli`, or `editor-executable` when explicit routing is needed.
+
+Before launching, pi-unity checks:
+
+- running Unity processes targeting the exact project;
+- Unity CLI status and Pipeline instances;
+- native `Temp/UnityLockfile` state;
+- the package-owned per-project launch mutex.
 
-Because `eval` reaches the same engine and Editor APIs as project code, its security token and exact-copy identity are meaningful trust boundaries. A static snippet allowlist is not: ordinary property getters can call code, while apparently simple expressions can still have side effects. Pi-unity therefore treats declared task intent as the boundary: regular inspection through `unity_pipeline_eval` is allowed; mutations must match the user's request; lifecycle, destructive, persistent-setting, asset, scene-save, package, build, and test changes require the same explicit authorization they would through a typed command. Typed tools remain preferred when they provide better validation, polling, compact evidence, or recovery semantics, but they are assistance rather than exclusive gateways. Results and diagnostics remain bounded, and an uncertain dispatch is never silently retried through another route.
+Unknown process state blocks launch. Direct Editor execution blocks native lockfiles. Unity CLI may handle a stale lockfile only after pi-unity verifies that no matching Unity process remains.
+
+A batchmode call may close a matching Unity process only when all of the following are true:
+
+1. isolated execution was deliberately selected;
+2. the call sets `closeBlockingUnityProcess: true`;
+3. `piUnity.allowCloseRunningUnityProcess` is enabled;
+4. any configured test-only restriction permits the operation.
+
+The package selects and revalidates the process itself; it never accepts a model-supplied PID. It may remove only the exact project's stale lockfile after a same-call guarded closure and verification that no matching process remains.
 
 ## Settings
 
-`pi-unity` reads optional package-specific settings from global `~/.pi/agent/settings.json` and, for trusted projects, project `.pi/settings.json`:
+Pi-unity reads optional settings from global `~/.pi/agent/settings.json` and, for trusted projects, project `.pi/settings.json`:
 
 ```json
 {
@@ -116,22 +148,43 @@ Because `eval` reaches the same engine and Editor APIs as project code, its secu
 }
 ```
 
-- `allowCloseRunningUnityProcess` defaults to `false`. When enabled, `unity_launch_batchmode` may close only Unity processes that target the resolved project and only when the tool call explicitly sets `closeBlockingUnityProcess: true`.
-- `closeRunningUnityProcessOnlyForTests` defaults to `true`, limiting process closure to Unity Test Framework launches (`-runTests`).
-- `closeRunningUnityProcessTimeoutMs` defaults to `30000` and is clamped between 1000 and 120000 milliseconds.
+- `allowCloseRunningUnityProcess` defaults to `false`.
+- `closeRunningUnityProcessOnlyForTests` defaults to `true`.
+- `closeRunningUnityProcessTimeoutMs` defaults to `30000` and is clamped from 1000 to 120000 milliseconds.
 
-Autonomous Play Mode exit is a separate session-scoped toggle and defaults to disallowed. Use `/unity-playmode-exit allow` only to authorize package-owned typed lifecycle operations that may exit Play Mode, `/unity-playmode-exit disallow` to restore the default, or `/unity-playmode-exit status` to inspect it. `unity_pipeline_recompile` never sends `editor_stop` and does not override Unity's Script Changes While Playing preference: a known continue/defer policy needs no exit authorization, a known stop-and-recompile policy does, and a missing policy is conservatively treated as potentially exiting. `unity_pipeline_run_tests` retains its separate verified `editor_stop` lifecycle path when authorized. The choice is recorded in the current session branch so it survives reload/resume, but it is not a global or project setting. Output/details identify explicit agent exit separately from Unity-policy-driven or unavailable-policy behavior; pi-unity never enters Play Mode autonomously.
+## Optional integrations
 
-## Skill evaluation
+`@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery` are optional peer integrations. Core Unity tools work without them.
 
-The `auditing-unity-agent-guidance` skill has an opt-in behavioral eval under `evals/auditing-unity-agent-guidance/`. It runs isolated fixtures through Pi, checks triggering, filesystem outcomes, instruction fidelity, and tool-call efficiency, and can compare skill-enabled runs with a no-skill baseline. Because it invokes an agent and may incur provider costs, it is not part of `npm test`.
+Pi-unity uses a global registry rendezvous so independently installed Git, local, or npm packages can compose without sibling source paths:
 
-```bash
-npm run eval:guidance-skill -- --cases audit_legacy_instructions,migrate_mixed_harness_guidance,unrelated_typescript_review
-npm run eval:guidance-skill -- --condition both --trials 3
+- The project-artifacts integration contributes an optional Unity profile for solution and memory metadata.
+- The file-discovery integration recommends excluding generated Unity directories from broad searches while preserving exact searches inside those directories.
+
+The optional peer integrations are session-scoped, reverse-load-order safe, and transactional. A malformed advertised integration contract fails visibly; an unavailable optional package does not prevent the Unity extension from loading.
+
+### Optional artifact metadata
+
+When project artifacts are active, solution and memory Markdown may use:
+
+```yaml
+---
+engine: unity
+unity_version: "6000.0"
+unity_packages:
+  - com.unity.inputsystem
+render_pipeline: urp
+platforms:
+  - windows
+  - android
+---
 ```
 
-See `evals/auditing-unity-agent-guidance/README.md` for the rubric.
+Supported `render_pipeline` values are `builtin`, `urp`, `hdrp`, `custom`, and `agnostic`. All fields are optional, and undeclared project metadata remains open and raw-filterable.
+
+### File-discovery filtering
+
+Broad Unity project searches may exclude `Library`, `Temp`, `Logs`, `obj`, `Build`, `Builds`, `UserSettings`, and `.vs`. An exact generated root—including `Library/PackageCache/...`—remains searchable. Filter failures degrade filtering rather than blocking inspection.
 
 ## Package layout
 
@@ -139,58 +192,42 @@ See `evals/auditing-unity-agent-guidance/README.md` for the rubric.
 pi-unity/
   index.ts
   src/
-    unity-core.ts
+    unity-artifact-profile.ts
     unity-batchmode.ts
     unity-cli.ts
+    unity-core.ts
+    unity-file-discovery-filter.ts
+    unity-guidance-audit.ts
     unity-launch.ts
+    unity-pipeline.ts
     unity-processes.ts
     unity-project-lock.ts
     unity-projects.ts
+    unity-test-batch.ts
   skills/
-    unity-debugging/
-      SKILL.md
     auditing-unity-agent-guidance/
-      SKILL.md
-      references/
-      assets/
-    unity-pipeline-workflows/
-      SKILL.md
     unity-batchmode-tests/
-      SKILL.md
+    unity-debugging/
+    unity-interactive-playmode-authoring/
+    unity-pipeline-workflows/
   tests/
 ```
 
-## Optional artifact metadata
-
-When `@aefree/pi-project-artifacts` is also active in a Unity workspace, solution and memory Markdown may use the following profile-enriched fields:
-
-```yaml
----
-engine: unity
-unity_version: "6000.0"
-unity_packages:
-  - com.unity.inputsystem
-render_pipeline: urp
-platforms:
-  - windows
-  - android
----
-```
-
-Supported `render_pipeline` values are `builtin`, `urp`, `hdrp`, `custom`, and `agnostic`. Keep `unity_version` quoted because Unity versions are identifiers rather than numeric values. Omit inapplicable fields instead of adding placeholders. These fields improve exact retrieval and diagnostics but are not required for indexing or raw filtering.
-
-## Testing
+## Development and validation
 
 ```bash
+npm ci
 npm test
-npm pack --dry-run
+npm pack --dry-run --json
 ```
 
-The package declares optional peer integrations for `@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery`; install only the integrations needed for artifact profiles or file-discovery filtering. The standalone Unity tools and skills do not require them. The package archive contains no copied dependency tree, sibling `file:` path, or workspace link.
+The auditing skill also has an opt-in provider-backed behavioral eval under `evals/auditing-unity-agent-guidance/`; it is intentionally not part of `npm test`.
+
+The registry-clean `package-lock.json` is committed. Optional development packages resolve from the public registry, and the npm archive contains no copied dependency tree, sibling `file:` dependency, or workspace link.
 
-## Release status
+## Unity Pipeline project side effect
 
-A registry-clean `package-lock.json` is committed, optional development packages resolve from the public registry, and the manifest is prepared for public scoped publication. Publishing remains a separate manual operation requiring npm authentication and explicit authorization.
+Starting `com.unity.pipeline@0.3.1-exp.1` assigns `Application.runInBackground = true`, which Unity persists as `PlayerSettings.runInBackground` in `ProjectSettings/ProjectSettings.asset`. Review that tracked change alongside `manifest.json` and `packages-lock.json` when installing Pipeline in a Unity project.
 
 ## License
 

package/index.ts

@@ -103,6 +103,7 @@ type UnityLauncherPreference = "auto" | "unity-cli" | "editor-executable";
 const OPEN_EDITOR_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
   unityEditorPath: Type.Optional(Type.String({ description: "Optional explicit Unity executable path override." })),
+  automated: Type.Optional(Type.Boolean({ default: false, description: "Pass Unity Editor's -automated flag when opening the project. Defaults to false." })),
   launcher: LAUNCHER_SCHEMA,
 });
 
@@ -571,7 +572,7 @@ async function buildProjectStatusReport(
   ctx: ExtensionContext,
   candidate: UnityProjectCandidate,
   signal?: AbortSignal,
-  allowAutonomousPlayModeExit = false,
+  allowAutonomousPlayModeExit = true,
 ): Promise<{ text: string; details: UnityToolDetails }> {
   const lockState = await inspectUnityProjectBusyState(candidate.projectRoot);
   const cliStatus = await listRunningUnityCliEditorsForProject(candidate.projectRoot);
@@ -597,7 +598,7 @@ async function buildProjectStatusReport(
     `- Pipeline command discovery: ${cliCapabilities.commandDiscoverySucceeded ? `${cliCapabilities.advertisedCommands.length}/${cliCapabilities.advertisedCommandCount} command(s) reported${cliCapabilities.advertisedCommandsTruncated ? " (bounded/truncated)" : ""}` : cliCapabilities.commandDiscovery}`,
     `- piUnity.allowCloseRunningUnityProcess: ${piUnitySettings.allowCloseRunningUnityProcess ? "enabled" : "disabled"}`,
     `- piUnity.closeRunningUnityProcessOnlyForTests: ${piUnitySettings.closeRunningUnityProcessOnlyForTests ? "enabled" : "disabled"}`,
-    `- Session autonomous Play Mode exit: ${allowAutonomousPlayModeExit ? "allowed" : "disallowed (default)"}`,
+    `- Session Play Mode exit: ${allowAutonomousPlayModeExit ? "allowed" : "disabled"}`,
   ];
 
   if (runningProcesses.length > 0) {
@@ -1192,9 +1193,9 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   // Lifecycle handles are session-scoped.
   const registrations = new WeakMap<object, ScopeRegistrations>();
   const playModeExitAuthorization = new WeakMap<object, boolean>();
-  const sessionAllowsAutonomousPlayModeExit = (ctx: ExtensionContext): boolean => playModeExitAuthorization.get(ctx.sessionManager) ?? false;
+  const sessionAllowsAutonomousPlayModeExit = (ctx: ExtensionContext): boolean => playModeExitAuthorization.get(ctx.sessionManager) ?? true;
   const restoreSessionSettings = (ctx: ExtensionContext): void => {
-    let allowed = false;
+    let allowed = true;
     const getBranch = (ctx.sessionManager as { getBranch?: () => Array<{ type: string; customType?: string; data?: unknown }> }).getBranch;
     for (const entry of getBranch?.call(ctx.sessionManager) ?? []) {
       if (entry.type !== "custom" || entry.customType !== "pi-unity-session-settings-v1") continue;
@@ -1202,7 +1203,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       if (typeof data?.allowAutonomousPlayModeExit === "boolean") allowed = data.allowAutonomousPlayModeExit;
     }
     playModeExitAuthorization.set(ctx.sessionManager, allowed);
-    ctx.ui.setStatus?.("pi-unity-playmode-exit", allowed ? "Unity Play Mode exit: allowed" : undefined);
+    ctx.ui.setStatus?.("pi-unity-playmode-exit", allowed ? undefined : "Unity Play Mode exit: disabled");
   };
   const unregisterScope = (current: ScopeRegistrations | undefined): boolean => {
     if (current === undefined) return false;
@@ -1264,7 +1265,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     if (changed) pi.events.emit("pi-unity:capabilities-changed", { scope, contractVersion: 1, action: "unregistered" });
   });
   pi.registerCommand("unity-playmode-exit", {
-    description: "Allow, disallow, or show autonomous Play Mode exit for this Pi session (default: disallowed).",
+    description: "Allow, disable, or show Play Mode exit behavior for this Pi session (default: allowed).",
     getArgumentCompletions: (prefix: string) => ["allow", "disallow", "status"]
       .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
       .map((value) => ({ value, label: value })),
@@ -1278,8 +1279,8 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       }
       const allowed = sessionAllowsAutonomousPlayModeExit(ctx);
       if (action !== "status") pi.appendEntry("pi-unity-session-settings-v1", { allowAutonomousPlayModeExit: allowed });
-      ctx.ui.setStatus?.("pi-unity-playmode-exit", allowed ? "Unity Play Mode exit: allowed" : undefined);
-      ctx.ui.notify(`Autonomous Unity Play Mode exit is ${allowed ? "allowed" : "disallowed"} for this session.`, allowed ? "warning" : "info");
+      ctx.ui.setStatus?.("pi-unity-playmode-exit", allowed ? undefined : "Unity Play Mode exit: disabled");
+      ctx.ui.notify(`Unity Play Mode exit is ${allowed ? "allowed" : "disabled"} for this session.`, allowed ? "info" : "warning");
     },
   });
 
@@ -1397,7 +1398,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     promptSnippet: "Recompile an already-open Unity Pipeline project in one bounded connected call without shell polling.",
     promptGuidelines: [
       "Use unity_pipeline_recompile for connected recompilation of an already-open exact Unity project copy instead of raw Unity CLI status loops.",
-      "unity_pipeline_recompile never sends editor_stop. In Play Mode it honors Unity's Script Changes While Playing policy; /unity-playmode-exit allow is required only when that policy may exit Play Mode or Pipeline does not expose it.",
+      "unity_pipeline_recompile never sends editor_stop. In Play Mode it honors Unity's Script Changes While Playing policy, including policies that may exit Play Mode.",
       "unity_pipeline_recompile never launches, closes, saves, retries, cancels Unity, or overrides Unity's script-change policy; its timeout means the operation may still be running.",
     ],
     parameters: PIPELINE_RECOMPILE_PARAMS,
@@ -1424,7 +1425,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
     promptSnippet: "Run focused connected Unity EditMode or PlayMode tests in one bounded call without shell polling; aggregate passing results stay compact.",
     promptGuidelines: [
       "Use unity_pipeline_run_tests for one focused connected Unity test platform when the exact Editor is already open and reachable.",
-      "unity_pipeline_run_tests retains a separate lifecycle guard: it exits Play Mode only when the user enabled /unity-playmode-exit allow for the current session; autonomous exit is disallowed by default.",
+      "unity_pipeline_run_tests may exit Play Mode through advertised editor_stop when needed, then verifies Edit Mode before dispatching tests.",
       "Use unity_run_test_batch instead of unity_pipeline_run_tests for closed projects, isolation, complex filters/categories, or required NUnit XML/log evidence.",
       "unity_pipeline_run_tests does not cancel uncertain work or switch to batchmode after timeout; report that the connected run may still be running.",
     ],
@@ -1578,7 +1579,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   pi.registerTool({
     name: "unity_open_editor",
     label: "Unity Open Editor",
-    description: "Open the Unity Editor GUI for a Unity project copy.",
+    description: "Open the Unity Editor GUI for a Unity project copy, optionally passing Unity Editor's -automated flag.",
     promptSnippet: "Open the Unity Editor GUI for a resolved Unity project when the user explicitly asks for the editor to open.",
     promptGuidelines: [
       "Use this tool only when the user explicitly wants the Unity Editor GUI opened.",
@@ -1605,11 +1606,12 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         launch = launchUnityCliOpenDetached(candidate.projectRoot, {
           editorVersion: candidate.unityVersion,
           editorPath: params.unityEditorPath,
+          automated: params.automated,
         });
       } else {
         await assertUnityProjectNotBusy(candidate.projectRoot);
         editorPath = await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath });
-        launch = launchUnityEditorDetached(editorPath, candidate.projectRoot);
+        launch = launchUnityEditorDetached(editorPath, candidate.projectRoot, { automated: params.automated });
       }
       const text = buildEditorLaunchSummary(ctx.cwd, candidate, editorPath, discoveryWarning, launcher);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "type": "module",
   "exports": {
     ".": "./index.ts"

package/skills/unity-interactive-playmode-authoring/SKILL.md

@@ -71,7 +71,7 @@ A request to persist authorizes the durable source/asset edit, but lifecycle cha
 1. Capture the final runtime values and the owning coordinate space, dimensions, scale, or other context needed to convert them into authored values.
 2. Identify the authoritative source or serialized field and trace how it becomes the runtime value. Do not write a visual coordinate into a guessed representation.
 3. Determine whether persistence triggers asset import, script compilation, domain reload, or runtime reconstruction, and whether the current instance can consume the change.
-4. Inspect `editor_status`. If Play Mode must stop, obtain lifecycle authorization unless already explicit (including the current session's `/unity-playmode-exit allow` toggle), dispatch the advertised `editor_stop`, and verify Play Mode exited.
+4. Inspect `editor_status`. If Play Mode must stop, dispatch the advertised `editor_stop` and verify Play Mode exited.
 5. Apply the durable edit with the owning file/asset tool.
 6. Use the `unity-pipeline-workflows` skill for any required connected compilation and terminal status validation.
 7. Re-enter Play Mode only when requested. Report temporary live confirmation and durable verification as separate evidence.

package/skills/unity-pipeline-workflows/SKILL.md

@@ -22,7 +22,7 @@ A timeout or malformed response is uncertain: the Unity operation may still be r
 
 1. Pass an explicit `path` when multiple project copies may be found; paths identify copies, not display names.
 2. The typed tools require a reachable exact-copy Pipeline and advertised `editor_status` plus operation commands. A different connected client is not itself a project lock.
-3. Autonomous Play Mode exit is disallowed by default. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference: known recompile-and-continue and defer policies may proceed without exit authorization; known stop-and-recompile and unavailable policy require `/unity-playmode-exit allow` because the recompile may exit Play Mode. Pipeline 0.4 does not currently expose that preference, so absence is reported as uncertainty rather than a claim that Unity cannot compile in Play Mode. `unity_pipeline_run_tests` has separate lifecycle semantics and may dispatch advertised `editor_stop` only after that same authorization, then verifies Edit Mode. `/unity-playmode-exit disallow` restores the default. The tools never enter Play Mode, pause, save, launch, or close Unity autonomously; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
+3. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference. Known recompile-and-continue, stop-and-recompile, and defer policies proceed according to Unity's configured behavior. Pipeline 0.4 does not currently expose that preference, so the tool reports the unavailable policy while allowing recompilation to proceed. `unity_pipeline_run_tests` may dispatch advertised `editor_stop` when needed, then verifies Edit Mode before running tests. The tools never enter Play Mode, pause, save, launch, or close Unity; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
 4. Test success requires a well-formed terminal result, a known positive executed count, and zero failures. An asynchronous initiation with `Total: 0` and `running` is nonterminal.
 5. Passing test records are intentionally discarded. Failures retain only a bounded set of failed/inconclusive names, messages, and stack excerpts.
 

package/src/unity-cli.ts

@@ -18,6 +18,8 @@ export type UnityCliLaunchOptions = {
   timeoutSeconds?: number;
   cliCommand?: string;
   useGraphics?: boolean;
+  /** Forward Unity Editor's -automated flag through `unity open --args`. */
+  automated?: boolean;
 };
 
 export type UnityCliPipelineInstance = {
@@ -80,6 +82,7 @@ function appendUnityCliEditorOptions(args: string[], options: UnityCliLaunchOpti
 export function createUnityCliOpenCommand(projectRoot: string, options: UnityCliLaunchOptions = {}): UnityCliCommand {
   const args = [...unityCliBaseArgs(), "open", projectRoot];
   appendUnityCliEditorOptions(args, options);
+  if (options.automated) args.push("--args", "-automated");
   return {
     command: resolveUnityCliCommand(options),
     args,

package/src/unity-core.ts

@@ -64,8 +64,13 @@ export function buildUnityEditorCandidates(
   ];
 }
 
-export function buildUnityOpenEditorArgs(projectRoot: string): string[] {
-  return ["-projectPath", projectRoot];
+export type UnityOpenEditorArgsOptions = {
+  /** Pass Unity Editor's -automated flag. */
+  automated?: boolean;
+};
+
+export function buildUnityOpenEditorArgs(projectRoot: string, options: UnityOpenEditorArgsOptions = {}): string[] {
+  return ["-projectPath", projectRoot, ...(options.automated ? ["-automated"] : [])];
 }
 
 export type UnityBatchmodeArgsOptions = {

package/src/unity-launch.ts

@@ -7,6 +7,7 @@ import {
   buildUnityOpenEditorArgs,
   normalizeUnityEditorOverride,
   type SupportedPlatform,
+  type UnityOpenEditorArgsOptions,
 } from "./unity-core";
 import { createUnityCliOpenCommand, type UnityCliLaunchOptions } from "./unity-cli";
 
@@ -47,8 +48,12 @@ export async function resolveUnityEditorPath(
   );
 }
 
-export function launchUnityEditorDetached(editorPath: string, projectRoot: string): { pid: number | undefined; args: string[]; command: string } {
-  const args = buildUnityOpenEditorArgs(projectRoot);
+export function launchUnityEditorDetached(
+  editorPath: string,
+  projectRoot: string,
+  options: UnityOpenEditorArgsOptions = {},
+): { pid: number | undefined; args: string[]; command: string } {
+  const args = buildUnityOpenEditorArgs(projectRoot, options);
   const child = spawn(editorPath, args, {
     detached: true,
     stdio: "ignore",

package/src/unity-pipeline.ts

@@ -316,7 +316,7 @@ async function executeCommand(deps: PipelineDependencies, projectRoot: string, c
   if (deadline !== undefined) ensureBeforeDeadline(deadline, now, command);
   return result;
 }
-async function requirePreflight(deps: PipelineDependencies, projectRoot: string, unityVersion: string, commands: string[], operation: "recompile" | "tests", signal: AbortSignal | undefined, deadline: number, now: () => number, allowAutonomousExitPlayMode = false): Promise<{ capabilities: UnityCliProjectCapabilities; exitedPlayMode: boolean; playModeHandling: UnityPipelinePlayModeHandling; scriptChangesWhilePlaying?: UnityScriptChangesWhilePlayingPolicy }> {
+async function requirePreflight(deps: PipelineDependencies, projectRoot: string, unityVersion: string, commands: string[], operation: "recompile" | "tests", signal: AbortSignal | undefined, deadline: number, now: () => number, allowAutonomousExitPlayMode = true): Promise<{ capabilities: UnityCliProjectCapabilities; exitedPlayMode: boolean; playModeHandling: UnityPipelinePlayModeHandling; scriptChangesWhilePlaying?: UnityScriptChangesWhilePlayingPolicy }> {
   const capabilities = await inspectWithDeadline(deps, projectRoot, unityVersion, signal, deadline, now, "preflight");
   const error = capabilityError(capabilities, commands); if (error) throw new Error(error);
   let editor = await executeCommand(deps, projectRoot, "editor_status", [], signal, deadline, now);
@@ -335,13 +335,13 @@ async function requirePreflight(deps: PipelineDependencies, projectRoot: string,
       const policyDescription = policy === "stop_and_recompile"
         ? "Unity's Script Changes While Playing policy may stop Play Mode to recompile"
         : "Pipeline editor_status does not expose Unity's Script Changes While Playing policy, so recompilation may continue, defer, or stop Play Mode";
-      if (!allowAutonomousExitPlayMode) throw new Error(`${policyDescription}; autonomous Play Mode exit is disallowed for this session, so recompile was not started.`);
+      if (!allowAutonomousExitPlayMode) throw new Error(`${policyDescription}; Play Mode exit is disabled for this session, so recompile was not started.`);
       // RecompileCommand owns AssetDatabase.Refresh. Do not preempt it with editor_stop or override Unity's policy.
       playModeHandling = policy === "stop_and_recompile" ? "unity_policy_may_exit" : "policy_unknown";
     }
   } else if (status.lifecycle !== "compatible") {
-    // Test execution has separate lifecycle semantics: stop explicitly only with session authorization.
-    if (!allowAutonomousExitPlayMode) throw new Error("Unity Editor is in Play Mode or paused; autonomous Play Mode exit is disallowed for this session, so tests were not started.");
+    // Test execution has separate lifecycle semantics: stop explicitly, then verify Edit Mode.
+    if (!allowAutonomousExitPlayMode) throw new Error("Unity Editor is in Play Mode or paused; Play Mode exit is disabled for this session, so tests were not started.");
     const stopError = capabilityError(capabilities, ["editor_stop"]); if (stopError) throw new Error(stopError);
     const stopped = await executeCommand(deps, projectRoot, "editor_stop", [], signal, deadline, now);
     if (stopped.error) throw new Error("Unity Pipeline editor_stop failed; tests were not started and Play Mode state is uncertain.");