agentic-engineering-harness 0.6.4 → 0.6.6

package/docs/PASEO.md

@@ -2,71 +2,212 @@
 
 Paseo is AEH's default interactive orchestration surface. The integration separates **Paseo communication/session lifecycle** from **AEH deterministic workflow ownership**.
 
+## Visible operation graph
+
+A managed conversational lead does not own a long-running shell process. Long AUDIT/RUN workflows are first-class detached AEH operations:
+
+```bash
+aeh operation start audit "Review the repository architecture and security"
+aeh operation start run TASK-123
+```
+
+`start` returns an operation id promptly. The deterministic controller persists state in `.harness/operations/<id>.json`, then performs the sealed workflow independently of the lead conversation:
+
+```text
+Paseo UI
+   │
+   ▼
+AEH Lead (semantic orchestrator)
+   │ operation tools / short status calls
+   ▼
+AEH Operation Controller (deterministic, not an LLM agent)
+   ├── seals / validators / state machines
+   ├── local orchestration workspace
+   └── Paseo SDK
+          ├── planner/reviewer/worker agent
+          ├── planner/reviewer/worker agent
+          └── ...
+```
+
+The controller is deliberately **not** represented by a fake Paseo agent. Only real LLM participants become Paseo sessions.
+
+Observe or control an operation with:
+
+```bash
+aeh operation status <operation-id>
+aeh operation wait <operation-id> --timeout 1800
+aeh operation cancel <operation-id>
+aeh paseo agents --operation <operation-id>
+aeh paseo agents --operation <operation-id> --phase review
+```
+
+Synchronous `aeh audit` / `aeh run` remain valid compatibility entrypoints for non-interactive automation.
+
 ## SDK-first control plane
 
 AEH uses Paseo's published TypeScript client package, `@getpaseo/client`, as the primary control surface for agent creation, follow-up turns, status lookup and directory queries. Paseo currently documents that package as public but **not yet a stable public SDK**, so AEH deliberately resolves the copy bundled with the active `@getpaseo/cli` installation first instead of independently selecting a client version.
 
-The resolver supports normal PATH installations and mise-managed npm tools. In particular, mise may expose a shim through `command -v`; AEH also asks `mise which paseo` for the real binary and `mise where npm:@getpaseo/cli` for the synthetic npm installation root, then resolves `@getpaseo/client` from that package tree. A direct project-level SDK import is retained only as a compatibility fallback.
+The resolver supports normal PATH installations and mise-managed npm tools, including non-hoisted/store layouts. AEH asks `command -v paseo`, `mise which paseo`, and `mise where npm:@getpaseo/cli`, then resolves or bounded-scans the active installation for its exact `@getpaseo/client` entry. A direct project-level SDK import is retained only as a compatibility fallback.
 
-The CLI remains responsible for daemon bootstrap/recovery and is retained as a compatibility fallback when the SDK cannot be resolved or connected:
+Normal lifecycle is always SDK-first unless `AEH_PASEO_FORCE_CLI=1` is explicitly set:
 
 ```text
 AEH
-├── daemon/bootstrap/recovery -> Paseo CLI
-└── normal agent lifecycle    -> @getpaseo/client bundled with active CLI
+├── daemon/bootstrap/recovery          -> Paseo CLI
+├── normal agent lifecycle             -> active @getpaseo/client
+└── explicit/recoverable compatibility -> Paseo CLI
 ```
 
-Set `AEH_PASEO_FORCE_CLI=1` only when the compatibility path is deliberately required. `PASEO_DAEMON_URL` overrides the default SDK endpoint `ws://127.0.0.1:6767/ws`; `PASEO_DAEMON_PASSWORD` supplies daemon authentication when configured.
+`PASEO_DAEMON_URL` overrides the default SDK endpoint `ws://127.0.0.1:6767/ws`; `PASEO_DAEMON_PASSWORD` supplies daemon authentication when configured.
 
 A system-prompt-only idle agent is an SDK-only invariant. If the SDK is unavailable, AEH refuses to degrade that lead creation into a CLI user turn because doing so would expose the bootstrap as conversational input.
 
+## Agent lifecycle
+
+AEH separates visible agent lifecycle into three phases:
+
+```text
+materialize -> dispatch -> wait
+```
+
+- **materialize** creates an idle top-level Paseo agent so it is visible immediately;
+- **dispatch** sends the bounded prompt when deterministic prerequisites/evidence are ready;
+- **wait** collects completion/result without conflating creation with execution.
+
+For AUDIT, AEH materializes the selected read-only reviewers before running deterministic validators. They remain visible/idle while validation runs, then AEH dispatches them with the completed validator evidence. This preserves deterministic evidence precedence without the earlier “silent terminal” UX.
+
+The adapter follows the Paseo 0.3.1 create contract: `cwd` remains present even when `workspaceId` controls placement, `initialPrompt` is used for the first turn, and provider/model remain separate session-config fields. It supports current handles through `send`, `refetch`, timeline polling and compatible legacy helpers where present.
+
 ## Conversational lead
 
-`aeh start` creates the lead as an idle Paseo agent. The AEH bootstrap is passed through the SDK's `systemPrompt`; it is no longer sent as the first user message and there is no synthetic `AEH READY` turn.
+`aeh start` creates the lead as an idle Paseo agent. The AEH bootstrap is passed through the SDK's `systemPrompt`; it is not sent as a user message and there is no synthetic readiness turn.
+
+The bootstrap is intentionally thin. `AGENTS.md`, `.harness/skills/engineering-workflow/SKILL.md`, and the resolved AEH agent topology are authoritative for roles, charters, permissions and delegation.
+
+When `orchestration.interactive.usePaseoTools` is enabled, AEH derives the exact command vector that launched the current package and injects an `aeh-control` stdio MCP server into the lead session. A normal installed launch therefore becomes conceptually:
+
+```text
+mcp server: aeh-control
+command: <exact Node executable>
+args: [<exact dist/main.js>, operation, mcp]
+```
+
+Only four MCP tools are preapproved:
+
+```text
+aeh_operation_start_audit
+aeh_operation_start_run
+aeh_operation_status
+aeh_operation_cancel
+```
+
+Paseo's `toolPolicy.preapproved` is scoped to those exact MCP server/tool identities; native shell/edit tools are not broadened by this configuration. If the AEH invocation cannot be parsed as a safe command vector, MCP injection is skipped rather than evaluating shell syntax, and the short `aeh operation ...` CLI surface remains the fallback.
+
+The lead bootstrap version is incremented when this managed-session contract changes, so explicit resume cannot silently reuse an older lead that lacks the current operation-control surface.
+
+Paseo native orchestration tools remain preferred for bounded conversational delegation and `/paseo-handoff`. Deterministic multi-agent workflows are owned by the detached AEH operation controller, so the lead remains available to the user.
 
-The bootstrap is intentionally thin. `AGENTS.md`, `.harness/skills/engineering-workflow/SKILL.md`, and the resolved AEH agent topology are authoritative for roles, charters, permissions and delegation. This avoids duplicating a role map inside every Paseo conversation and prevents prompt/configuration drift.
+## Operation MCP server
+
+The same control surface can be started directly for any MCP-capable host:
+
+```bash
+aeh operation mcp
+```
 
-When the lead is running inside Paseo and Paseo exposes its orchestration tools, it may still use the native/MCP conversational surface and `/paseo-handoff`. Deterministic Harness-owned work, however, is created externally by AEH through the SDK.
+It is a stdio JSON-RPC server and calls the same persistent controller used by the CLI. It does not duplicate workflow logic and does not become a normative engineering source.
 
 ## Independent AEH agents
 
-AEH-managed workers are created without the Paseo SDK `parent` option. A worker may be placed in a delivery workspace, but workspace placement does not establish parentage. This makes each worker a top-level Paseo agent rather than a child whose lifecycle belongs to the current lead conversation.
+AEH-managed workers are created without Paseo `parent` ownership. Workers are independent top-level sessions so lead context rotation cannot terminate or orphan their lifecycle.
 
-Workflow ownership is represented by labels instead:
+Workflow ownership and visibility use labels:
 
 ```text
 aeh.project=<project>
 aeh.kind=lead|worker
 aeh.role=<logical-agent>
-aeh.task=<task-id>        # workers
+aeh.task=<task-id>
+aeh.operation=<operation-id>
+aeh.operation.kind=audit|run|quick|...
+aeh.operation.phase=queued|planning|review|implementation|diagnosis|...
+aeh.workspace.kind=orchestration|delivery
 aeh.profile=<profile>     # when selected
 aeh.generation=<n>        # leads
 ```
 
-The shared Paseo runtime exposes list/inspect primitives over those labels. This lets AEH determine which logical agent is active for a task without scraping assistant prose or relying on parent/child nesting. The same labels survive lead context rotation, so a fresh lead can correlate existing workers with durable AEH run state.
+The operation/task labels are durable correlation keys; Paseo parent/subagent nesting is not the workflow source of truth.
 
 ### Observe active agents
 
-Use the top-level AEH command to inspect the live Paseo directory. The project label is applied automatically; filters are additive:
-
 ```bash
 aeh paseo agents
 aeh paseo agents --status working
 aeh paseo agents --kind worker --role backend-implementer
 aeh paseo agents --task TASK-123 --json
+aeh paseo agents --operation AUDIT-... --phase review
 ```
 
-The tabular view reports status, logical role, task, kind, stable Paseo agent ID and title. `--json` returns the same normalized fields plus the complete AEH label set. This is the preferred way to answer which AEH agent is currently working without depending on Paseo parent/subagent nesting.
+The operation-aware view reports stable Paseo IDs, role, operation, phase, task, status and title.
+
+## Orchestration workspace vs delivery workspace
+
+Paseo workspaces and Git delivery isolation are separate concepts.
+
+For each detached operation AEH attempts to create a **local Paseo workspace** pointing at the existing repository directory. Its purpose is UI/execution grouping: multiple agents for the same audit/run appear together. It does not create or imply a Git branch/worktree.
+
+When delivery policy creates an issue-linked worktree workspace, that delivery workspace takes precedence for implementation/review agents:
+
+```text
+operation workspace -> local grouping, no Git isolation
+
+delivery workspace  -> branch/worktree isolation and delivery lifecycle
+```
+
+This lets audits and non-delivery operations have coherent Paseo grouping even when `delivery.paseo.enabled` is false.
 
 ## Runtime consolidation
 
-Lead startup, `PaseoWorkerExecutor`, and generic `agentPrompt` execution all use the same managed Paseo runtime. That runtime owns SDK-first create/run/probe/list behavior and the CLI fallback. Individual worker paths should not add new hand-written `paseo run/send/wait/logs` loops.
+`PaseoWorkerExecutor` and generic `agentPrompt` no longer independently reconstruct provider/model/title/workspace/labels. Both consume one launch-spec compiler. This is the single boundary for:
+
+- provider/model selection;
+- title;
+- operation/task labels;
+- semantic phase;
+- orchestration-vs-delivery workspace;
+- timeout.
+
+This prevents launch-path drift such as provider/model or cwd/workspace serialization mismatches.
 
-Structured output is passed through the SDK `outputSchema` field. The compatibility CLI path continues to negotiate `--output-schema` and background capabilities dynamically.
+## Operation/session metadata
+
+Worker/reviewer execution records retain lifecycle metadata in addition to stdout/stderr:
+
+```text
+id
+transport
+workspaceId
+title
+operationId
+operationKind
+phase
+status
+startedAt
+finishedAt
+logicalAgent / runtime / model
+```
 
-## Session policy
+Audit/run reports can therefore distinguish a real Paseo SDK session from CLI/direct/Podman execution without inferring it from logs.
 
-Default:
+Operation phase is durable even when optional telemetry export is disabled. Harness lifecycle events update `.harness/operations/<id>.json` through phases such as `validating`, `planning`, `implementation`, `remediation`, `review`, `delivery`, and `finished`.
+
+## Cancellation
+
+`aeh operation cancel <id>` terminates the detached controller and then discovers real Paseo agents by `aeh.operation=<id>`. Each active agent is interrupted through Paseo's supported `paseo agent stop <id>` lifecycle. Cleanup failures are retained as `cleanupWarnings` in operation state rather than silently ignored.
+
+## Session policy and context rotation
+
+Default lead policy remains:
 
 ```yaml
 orchestration:
@@ -79,16 +220,10 @@ aeh start          # fresh idle lead
 aeh start --resume # explicit compatible reuse
 ```
 
-Workspaces and durable AEH state remain reusable even though normal conversational context starts clean.
-
-## Context rotation
-
-Default pressure policy is 70/80/90 percent. `aeh context guard` consumes a context ratio only when Paseo exposes a usable field; AEH does not guess.
-
-At the handoff threshold it writes a deterministic `.harness/paseo/handoffs/*.json` artifact. From a managed Paseo lead it also creates the replacement lead automatically and bootstraps it from the handoff artifact and referenced sealed/run/audit/delivery state. Workers remain independent top-level agents associated through AEH labels and durable task/run state rather than lead parentage.
+Default context pressure policy is 70/80/90 percent. At the handoff threshold AEH writes `.harness/paseo/handoffs/*.json` and rotates responsibility to a fresh lead. Detached operations and independent worker agents continue; durable operation/run/audit/delivery state allows the replacement lead to correlate them without replaying the old conversation.
 
 ## Trust boundary
 
-Paseo owns communication, process and session lifecycle. It is not normative engineering truth. AEH TaskContracts, seals, deterministic reports, evidence graphs and quality gates continue to decide acceptance.
+Paseo owns communication, UI grouping, process and session lifecycle. It is not normative engineering truth. AEH TaskContracts, seals, deterministic reports, operation state, evidence graphs and quality gates decide acceptance.
 
 For stronger direct process isolation configure Podman sandboxing where appropriate; Paseo orchestration and worker sandboxing remain separate policy axes.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": {
-    "engineering-harness": "./dist/entry.js",
-    "aeh": "./dist/entry.js"
+    "engineering-harness": "./dist/main.js",
+    "aeh": "./dist/main.js"
   },
   "files": [
     "dist",
@@ -14,11 +14,15 @@
     "policies",
     "schemas",
     "skills",
-    "docs"
+    "docs",
+    "scripts/link-self-bin.mjs"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/entry.ts",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepare": "npm run build && node scripts/link-self-bin.mjs",
+    "aeh": "node ./dist/main.js",
+    "dev": "tsx src/main.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/scripts/link-self-bin.mjs

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const binDir = path.join(root, "node_modules", ".bin");
+const entry = path.join(root, "dist", "main.js");
+
+try {
+  await fs.access(entry);
+} catch {
+  throw new Error(`Cannot link AEH self-development bin because ${entry} does not exist. Run npm run build first.`);
+}
+
+await fs.mkdir(binDir, { recursive: true });
+for (const name of ["aeh", "engineering-harness"]) await writeBin(name);
+
+async function writeBin(name) {
+  const sh = path.join(binDir, name);
+  const cmd = `${sh}.cmd`;
+  const ps1 = `${sh}.ps1`;
+  const relative = "../../dist/main.js";
+
+  await fs.rm(sh, { force: true });
+  await fs.writeFile(sh, `#!/bin/sh\nexec node \"$(dirname \"$0\")/${relative}\" \"$@\"\n`);
+  await fs.chmod(sh, 0o755);
+
+  await fs.rm(cmd, { force: true });
+  await fs.writeFile(cmd, `@ECHO OFF\r\nnode \"%~dp0\\..\\..\\dist\\main.js\" %*\r\n`);
+
+  await fs.rm(ps1, { force: true });
+  await fs.writeFile(ps1, `#!/usr/bin/env pwsh\n& node \"$PSScriptRoot/../../dist/main.js\" $args\nexit $LASTEXITCODE\n`);
+}
+
+if (process.env.AEH_SELF_BIN_VERBOSE === "1") console.log(`Linked repo-local AEH bins in ${binDir}`);

package/skills/engineering-workflow/SKILL.md

@@ -25,16 +25,29 @@ Delegate everything else to the narrowest bounded role:
 - SPEC authoring -> `spec-manager` using OpenSpec;
 - implementation/validation/review -> Harness-selected workers.
 
-Use the `paseo-orchestration` skill. Prefer injected Paseo tools (`create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, lifecycle tools) and `/paseo-handoff` over shell orchestration when available. AEH's Paseo CLI adapter is the compatibility fallback. Do not create hand-written `paseo run` loops from the lead.
+Use the `paseo-orchestration` skill. Prefer injected Paseo tools (`create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, lifecycle tools) and `/paseo-handoff` for bounded conversational delegation. For deterministic multi-agent AEH workflows, use the first-class operation controller rather than holding the lead inside a long shell process. AEH's Paseo CLI adapter is a compatibility fallback; do not create hand-written `paseo run` loops from the lead.
+
+The AEH operation controller is deterministic infrastructure, not an LLM agent. Do not create a fake controller/session merely to make it visible in Paseo. Real LLM participants are materialized as independent top-level Paseo agents and are correlated through AEH operation/task labels.
 
 ## Persistent interactive entry
 
 When the conversation was created by `aeh start`, its bootstrap is a standing instruction. Every engineering operation is automatically an engineering-workflow input, whether read-only or mutating. Only a purely informational question may bypass AEH.
 
-A normal `aeh start` creates a fresh lead. `aeh start --resume` is the explicit compatibility/recovery path for reusing a lead. Do not assume old conversational context is normative; Git, sealed artifacts, AuditReports, run state and delivery state are the durable sources.
+A normal `aeh start` creates a fresh lead. `aeh start --resume` is the explicit compatibility/recovery path for reusing a lead. Do not assume old conversational context is normative; Git, sealed artifacts, AuditReports, operation state, run state and delivery state are the durable sources.
 
 The bootstrap may provide an exact AEH invocation. Use it whenever this skill writes `aeh`.
 
+## Interactive operation boundary
+
+Inside a managed Paseo lead, long deterministic workflows must be started detached:
+
+- audit: `aeh operation start audit "<request>" ...`
+- sealed task execution: `aeh operation start run <taskId> ...`
+
+The start command must return promptly with an `operationId`. Report that identifier and the meaningful phase to the user instead of waiting in an interactive shell. Observe with `aeh operation status <operationId>` and, when useful, `aeh paseo agents --operation <operationId>`. Use `aeh operation wait` only when synchronous waiting is explicitly required by a non-interactive caller or bounded recovery flow. Cancel with `aeh operation cancel <operationId>` when the user requests cancellation.
+
+Direct synchronous commands such as `aeh audit` and `aeh run` remain valid non-interactive/compatibility entrypoints, but a conversational Paseo lead should not use them for a long-running operation when the detached controller is available.
+
 ## Context pressure before broad work
 
 Do not wait for model compaction as the normal context lifecycle.
@@ -44,14 +57,14 @@ Do not wait for model compaction as the normal context lifecycle.
 - >=80%: proactive handoff to a fresh lead;
 - >=90%: mandatory handoff before additional engineering work.
 
-Use Paseo's current status/tool data when it exposes context usage, otherwise use `aeh context guard --agent "$PASEO_AGENT_ID"`. When AEH writes a `.harness/paseo/handoffs/*.json` artifact, use `/paseo-handoff` (preferred) or a fresh `create_agent`, point the new lead at that artifact and stop continuing the workflow in the old lead. Deterministic artifacts, not a prose replay of the whole chat, carry state across the handoff.
+Use Paseo's current status/tool data when it exposes context usage, otherwise use `aeh context guard --agent "$PASEO_AGENT_ID"`. When AEH writes a `.harness/paseo/handoffs/*.json` artifact, use `/paseo-handoff` (preferred) or a fresh `create_agent`, point the new lead at that artifact and stop continuing the workflow in the old lead. Deterministic artifacts, not a prose replay of the whole chat, carry state across the handoff. Detached AEH operations and their top-level worker agents survive lead rotation.
 
 ## Intent layer
 
 Classify every request as:
 
 - `INFORMATIONAL`: explanation/lookup only. May be answered directly and must remain non-mutating.
-- `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis. Must use `aeh audit`.
+- `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis. Must use the Harness audit path.
 - `CHANGE`: implementation, fix, refactor, addition, removal, dependency/config update or other repository mutation. Must continue through deterministic QUICK/SPEC triage.
 
 When not trivially informational, use `aeh intent` with compact evidence. Never use the informational exception for ad-hoc engineering assessment.
@@ -72,15 +85,16 @@ Do not invoke sudo or silently install unmanaged host prerequisites.
 
 ## AUDIT path
 
-1. Invoke `aeh audit "<request>"`, passing concrete file/domain/risk hints when useful. Repository-wide scope is valid.
-2. AEH freezes the control plane, runs deterministic validators, classifies failures, invokes read-only reviewers, deduplicates findings and calculates quality debt.
-3. Validator failures remain evidence; do not reinterpret them as PASS.
-4. Persisted reports under `.harness/audits/` are durable input for later remediation.
-5. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
+1. From an interactive Paseo lead, invoke `aeh operation start audit "<request>"`, passing concrete file/domain/risk/reviewer hints when useful. Repository-wide scope is valid. A non-interactive caller may use synchronous `aeh audit`.
+2. AEH freezes the control plane and materializes the selected read-only reviewers as visible Paseo agents before deterministic validation begins. The agents remain idle until validator evidence is ready.
+3. AEH runs deterministic validators, classifies failures, dispatches the materialized reviewers with that evidence, deduplicates findings and calculates quality debt.
+4. Validator failures remain evidence; do not reinterpret them as PASS.
+5. Persisted reports under `.harness/audits/` and `.harness/operations/` are durable input for later remediation and recovery.
+6. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
 
 ## Issue-driven CHANGE path
 
-For an existing GitHub issue, use `aeh issue implement <number>` (or `aeh run --issue <number>`). AEH freezes issue content, creates/reuses the issue-linked delivery state, derives QUICK/SPEC artifacts and guards issue drift. Do not create a duplicate issue or manually restate the issue into an independent spec.
+For an existing GitHub issue, use the issue intake flow to freeze and derive the task. `aeh issue implement <number>` remains a synchronous compatibility shortcut. From an interactive lead, once the resulting QuickContract/TaskContract is validated and sealed, execute it through `aeh operation start run <taskId>`. AEH guards issue drift and reuses the issue-linked delivery state. Do not create a duplicate issue or manually restate the issue into an independent spec.
 
 ## Non-issue CHANGE discovery and triage
 
@@ -97,8 +111,8 @@ For a CHANGE classified QUICK:
 
 1. Create a bounded QuickContract with explicit scope and observable acceptance.
 2. `aeh quick validate <id>`.
-3. `aeh run <id>`.
-4. Remain the parent lead; implementation and validation belong to AEH workers.
+3. From an interactive lead, start `aeh operation start run <id>`; use synchronous `aeh run <id>` only for non-interactive compatibility.
+4. Remain the semantic parent lead; implementation, validation and review belong to AEH workers and the deterministic controller.
 
 ## SPEC path — OpenSpec authoring
 
@@ -109,14 +123,24 @@ The lead must not write proposal/spec/design/tasks/Gherkin itself.
 3. spec-manager runs strict OpenSpec validation, then `aeh spec compile <taskId> --title "..." --change <change>`.
 4. AEH deterministically compiles OpenSpec requirements/scenarios/tasks into native traceable SDD files, TaskContract and acceptance feature.
 5. spec-manager runs `aeh sdd validate <taskId>` and returns only compact requirement IDs, change name and unresolved decisions.
-6. The lead proceeds with normal seal/run/handoff. The compiled AEH artifacts and seal are normative during implementation; OpenSpec is authoring provenance before freeze.
+6. The lead proceeds with normal seal/handoff, then starts `aeh operation start run <taskId>` when interactive. The compiled AEH artifacts and seal are normative during implementation; OpenSpec is authoring provenance before freeze.
 7. Do not use OpenSpec apply commands to implement product code. AEH owns implementation, validation, review convergence and delivery.
 
 If OpenSpec cannot express a true product decision without guessing, return `REQUIRES_PRODUCT_DECISION`; otherwise author and validate autonomously.
 
+## Operation observation
+
+Use durable operation state for progress rather than narrating terminal silence:
+
+- `aeh operation status <id>` -> controller status/phase/result/error;
+- `aeh paseo agents --operation <id>` -> real LLM participants and their roles/phases;
+- `aeh operation wait <id>` -> synchronous boundary only when necessary.
+
+Paseo workspaces used for operation grouping are local orchestration containers and do not imply Git branch/worktree delivery. Delivery workspaces remain a separate isolation decision and take precedence for workers when present.
+
 ## Quality convergence and recovery
 
-After a sealed run starts, do not reimplement Harness state machines in the lead. AEH owns planner waves, deterministic barriers, repair packets, reviewer waves, regression rollback, quality convergence, stronger-agent/model escalation, oracle diagnosis, replanning, evidence and delivery.
+After a sealed operation starts, do not reimplement Harness state machines in the lead. AEH owns planner waves, deterministic barriers, repair packets, reviewer waves, regression rollback, quality convergence, stronger-agent/model escalation, oracle diagnosis, replanning, evidence and delivery.
 
 Default acceptance remains: critical/high/medium = 0, low <= 3, DebtScore <= 3. Do not stop because an arbitrary remediation count elapsed.
 
@@ -133,8 +157,8 @@ Request human input only for:
 
 ## Self-modification
 
-If the repository is AEH itself or the task changes topology, toolchain, skills, policies, validators or orchestration, the active run remains governed by the frozen controller from run start. New rules activate only on a later run.
+If the repository is AEH itself or the task changes topology, toolchain, skills, policies, validators or orchestration, the active operation remains governed by the frozen controller from operation start. New rules activate only on a later operation.
 
 ## User-facing communication
 
-Keep status concise. Do not narrate every shell command or subagent read. Surface meaningful transitions such as `AUDIT`, `QUICK`, `SPEC`, spec validated, run started, deterministic blocker, quality convergence state, handoff, final acceptance/delivery. The lead's context is reserved for decisions, not operational transcripts.
+Keep status concise. Do not narrate every shell command or subagent read. Surface meaningful transitions such as operation started, `AUDIT`, `QUICK`, `SPEC`, spec validated, deterministic blocker, quality convergence state, handoff, final acceptance/delivery. A useful update names the operation id and phase and, when relevant, the visible worker roles. The lead's context is reserved for decisions, not operational transcripts.

package/skills/paseo-orchestration/SKILL.md

@@ -9,7 +9,7 @@ Use this skill whenever an AEH lead, planner or coordinator delegates work throu
 
 ## Preferred control surface
 
-When Paseo tools are injected into the current agent, prefer them over shell commands:
+When Paseo tools are injected into the current agent, prefer them over shell commands for bounded conversational delegation:
 
 - `create_agent` for a bounded subagent;
 - `send_agent_prompt` for follow-up work;
@@ -17,9 +17,24 @@ When Paseo tools are injected into the current agent, prefer them over shell com
 - `cancel_agent` / `archive_agent` for lifecycle cleanup;
 - `update_agent` / `set_agent_mode` for supported runtime changes.
 
+When the optional AEH operation MCP server (`aeh operation mcp`) is injected, use its tools for long deterministic Harness workflows:
+
+- `aeh_operation_start_audit`;
+- `aeh_operation_start_run`;
+- `aeh_operation_status`;
+- `aeh_operation_cancel`.
+
+These MCP tools call the same persistent detached operation controller as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` is the short non-blocking compatibility surface; do not replace it with a long synchronous `aeh audit`/`aeh run` from the conversational lead.
+
 Load `/paseo` when the exact current Paseo surface is needed. Use `/paseo-handoff` when responsibility, not merely a subtask, should move to a fresh agent. `/paseo-committee` and `/paseo-advisor` are analysis-only escalation tools and must not replace deterministic AEH gates.
 
-The Harness CLI/daemon adapter remains a deterministic fallback when native tools are unavailable. Do not hand-write `paseo run` shell loops from the lead unless AEH explicitly reports that it is using the CLI fallback.
+The Harness CLI/daemon adapter remains a deterministic compatibility path when native tools/SDK are unavailable. Do not hand-write `paseo run` shell loops from the lead unless AEH explicitly reports that it is using the CLI fallback.
+
+## Visible execution graph
+
+Real planner/reviewer/implementer/oracle sessions should be top-level Paseo agents labeled with their AEH operation/task/role. The deterministic operation controller remains outside the agent graph. Operation-local Paseo workspaces are grouping containers; delivery worktree workspaces are a separate Git-isolation concern.
+
+Use `aeh paseo agents --operation <id>` (or Paseo's corresponding directory/status tools) to observe real participants without scraping terminal output.
 
 ## Lead discipline
 
@@ -35,4 +50,4 @@ Return compact structured summaries to the lead. Do not paste raw logs or entire
 
 ## Context pressure
 
-Before broad engineering work, inspect the current agent status if Paseo exposes context usage. At the configured handoff threshold, create a deterministic AEH handoff artifact and use `/paseo-handoff` (preferred) or `create_agent` to continue in a fresh lead. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.
+Before broad engineering work, inspect the current agent status if Paseo exposes context usage. At the configured handoff threshold, create a deterministic AEH handoff artifact and use `/paseo-handoff` (preferred) or `create_agent` to continue in a fresh lead. Detached operations and their top-level workers remain valid across lead rotation. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.

package/templates/AGENTS.md

@@ -14,7 +14,7 @@ Do not use the informational exception for an ad-hoc engineering review. `aeh st
 
 ## Lead agent — thin orchestrator
 
-The lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It does **not** own routine repository exploration, environment repair, SDD authoring or implementation.
+The lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It does **not** own routine repository exploration, environment repair, SDD authoring, implementation or a long-running controller shell.
 
 Delegate by default:
 
@@ -24,18 +24,20 @@ Delegate by default:
 - SPEC authoring -> `spec-manager` using OpenSpec;
 - implementation/validation/review -> Harness-selected workers.
 
-Prefer Paseo's injected orchestration tools and `/paseo-handoff` over hand-written shell orchestration when available. Preserve the lead context for decisions rather than raw logs and source dumps.
+Prefer Paseo's injected orchestration tools and `/paseo-handoff` for bounded conversational delegation. Long deterministic AUDIT/RUN workflows use the detached AEH operation controller. The controller is deterministic infrastructure, not an LLM agent; real planner/reviewer/worker sessions appear independently in Paseo and are correlated by AEH operation/task labels.
 
 For engineering work:
 
 1. Check context pressure before broad work. Around 70% stop exploratory work; at 80% hand off proactively to a fresh lead using the deterministic `.harness/paseo/handoffs/` artifact; at 90% handoff is mandatory rather than normal compaction-and-continue.
 2. Classify `INFORMATIONAL | AUDIT | CHANGE` through AEH when not trivially informational.
-3. AUDIT -> `aeh audit`.
+3. Interactive AUDIT -> `aeh operation start audit "<request>"`; use `aeh operation status <id>` and `aeh paseo agents --operation <id>` for progress. Synchronous `aeh audit` remains a non-interactive compatibility path.
 4. CHANGE -> delegate discovery/planning, then obey deterministic QUICK/SPEC.
-5. QUICK -> bounded QuickContract and AEH run.
-6. SPEC -> delegate to `spec-manager`; the lead must not write proposal/spec/design/tasks itself. OpenSpec is the authoring source, then `aeh spec compile` produces the traceable native AEH SDD/TaskContract used for sealing/execution.
+5. QUICK -> bounded QuickContract; interactive execution -> `aeh operation start run <taskId>`.
+6. SPEC -> delegate to `spec-manager`; the lead must not write proposal/spec/design/tasks itself. OpenSpec is the authoring source, then `aeh spec compile` produces the traceable native AEH SDD/TaskContract used for sealing/execution; interactive execution then uses `aeh operation start run <taskId>`.
 7. Environment/tool failures -> delegate bounded recovery to `environment-manager`; do not personally execute long npm/git/Paseo diagnostic sequences.
 
+Operation-local Paseo workspaces are only UI/execution grouping. They do not imply a Git branch/worktree; delivery isolation remains a separate policy. Detached operations and their top-level agents survive lead context rotation.
+
 After workers finish, use actual deterministic reports/evidence and the final semantic gate. Never accept work solely from a worker summary.
 
 ## Worker agent
@@ -55,7 +57,7 @@ If the plan conflicts with reality, report the blocker instead of silently redes
 ## Source-of-truth order
 
 1. Current Git-versioned code and schemas.
-2. Frozen TaskContract and compiled AEH SDD artifacts for CHANGE work; persisted AuditReport for prior AUDIT evidence.
+2. Frozen TaskContract and compiled AEH SDD artifacts for CHANGE work; persisted AuditReport and operation record for prior AUDIT evidence.
 3. OpenSpec source artifacts as pre-freeze authoring provenance.
 4. ADRs and project policy.
 5. Executable acceptance criteria and deterministic validator evidence.