agentic-engineering-harness 0.6.7 → 0.6.9

package/docs/PASEO_NATIVE.md

@@ -12,6 +12,7 @@ AEH treats Paseo as the authority for agent runtime state and generic agent orch
 | Provider/model availability | Paseo | provider snapshot/listModels/diagnostic |
 | Generic create/send/status/activity tools | Paseo | injected native/MCP Paseo tools |
 | AUDIT/RUN operation state | AEH | `aeh-control` / operation state |
+| Detached operation completion wake-up | AEH + Paseo dispatch | durable completion target + follow-up to existing lead |
 | Context thresholds and handoff policy | AEH | `aeh_context_status` / `context guard` |
 | SDD, contracts, seals, validation | AEH | deterministic Harness core |
 | Quality convergence/acceptance | AEH | deterministic Harness core |
@@ -51,9 +52,11 @@ HARD_HANDOFF
   ratio >= hardHandoffThreshold (default 90%)
 ```
 
-Managed leads receive the preapproved `aeh_context_status` tool. `aeh context guard --agent ...` remains the CLI compatibility/non-interactive surface and owns handoff-artifact/rotation side effects.
+Managed leads receive the preapproved `aeh_context_status` tool. A normal managed lead calls it without an `agentId`. AEH resolves the context target in strict order: explicit diagnostic `agentId`, host-provided `PASEO_AGENT_ID`, then the compatible project-local `lead-session.json` written by `aeh start`. The durable fallback respects configured `orchestration.interactive.stateDir` and validates the lead-state schema version, current bootstrap/runtime version, project root, project name and agent id before use. It fails closed on stale or mismatched state and never guesses by listing agents. The selected identity source is traced as `harness.paseo.context.identity`.
 
-## Event-driven completion
+`aeh context guard --agent ...` remains the CLI compatibility/non-interactive surface and owns handoff-artifact/rotation side effects.
+
+## Event-driven agent completion
 
 Agent waiting is:
 
@@ -64,10 +67,17 @@ subscribe(agent_update)
         |
         +--> updates trigger refetch
         |
-        `--> terminal state -> read recent timeline -> complete
+        `--> terminal state + turn evidence -> read recent timeline -> complete
 ```
 
-Subscription is installed **before** the first refetch so a transition cannot fall between the snapshot and listener setup. A freshly observed `idle` state is not treated as completion until the wait has observed activity/update evidence, avoiding a send/wait race.
+Subscription is installed **before** the first refetch so a transition cannot fall between the snapshot and listener setup.
+
+For a newly created agent, an assistant response in the fresh timeline can prove that a very fast turn completed before the subscription was installed. For a continued/reused agent, AEH captures the last assistant response **before dispatch** and uses it as a baseline. An `idle` snapshot is accepted only when at least one of these is true:
+
+- AEH observed an active-turn status (`working`, `running`, `streaming`, `starting`) or `activeTurn` before returning to terminal state;
+- the latest assistant response differs from the pre-dispatch baseline.
+
+A subscription notification by itself is **not** turn activity. This prevents metadata-only updates plus stale timeline output from making AEH conclude that a reviewer finished before its current turn actually did.
 
 Fallback order:
 
@@ -81,6 +91,38 @@ Paseo CLI wait/log compatibility
 
 The selected path is emitted in Paseo integration traces.
 
+## Detached operation completion wake-up
+
+A detached AUDIT/RUN deliberately outlives the conversational turn that starts it. The initiating lead is therefore not required to remain active or poll until all reviewers/workers finish.
+
+For a managed-lead MCP start, AEH resolves the current lead identity and persists a completion target beside the operation:
+
+```text
+.harness/operations/<operation-id>.completion.json
+```
+
+The completion target has an independent lifecycle:
+
+```text
+PENDING -> SENT
+        -> FAILED
+        -> DISABLED
+```
+
+When the engineering operation becomes `SUCCEEDED`, `FAILED`, or `CANCELLED`, the controller first persists that terminal engineering state, then sends a non-blocking follow-up to the existing Paseo lead. The message starts with:
+
+```text
+[AEH_OPERATION_COMPLETED]
+```
+
+and includes the operation id/status plus the durable result/report path when available. The callback tells the lead to continue the original pending user request, read the existing operation/report, and **not** start a duplicate operation.
+
+This solves the case where the lead's original turn ends while reviewers are still running. The reviewers remain independent top-level Paseo agents; the completion callback reactivates the lead only after the controller's full completion barrier has resolved and the operation is terminal.
+
+Callback delivery does not participate in engineering acceptance. If the follow-up cannot be delivered, the callback sidecar becomes `FAILED` and the failure is traced, but a successful AUDIT/RUN remains successful. `aeh_operation_status` is therefore a recovery/diagnostic surface, not the normal mechanism for keeping a conversational turn alive.
+
+Cancellation uses the same terminal callback path after worker cleanup. A synchronous controller spawn failure disables a callback that could otherwise arrive as a confusing continuation after the start tool itself already failed.
+
 ## Provider/model preflight
 
 Before creating or materializing an agent, AEH attempts a public-SDK preflight:
@@ -150,11 +192,19 @@ harness.paseo.agent.launch
 harness.paseo.agent.materialize
 harness.paseo.agent.dispatch
 harness.paseo.agent.snapshot
+harness.paseo.agent.turn.baseline
+harness.paseo.agent.turn.baseline.skipped
 harness.paseo.agent.wait
 harness.paseo.agent.wait.completed
 harness.paseo.agent.wait.fallback
+harness.paseo.context.identity
 harness.paseo.context.status
 harness.paseo.context.handoff
+harness.paseo.operation.callback.target
+harness.paseo.operation.callback.registered
+harness.paseo.operation.callback.sent
+harness.paseo.operation.callback.failed
+harness.paseo.operation.callback.disabled
 harness.paseo.fallback.cli
 harness.paseo.workspace.cli.*
 harness.paseo.cleanup.cli.*
@@ -164,6 +214,9 @@ A useful trace answers:
 
 - which transport was selected (`sdk` or `cli`);
 - which observation source was used (`subscription`, snapshot, sdk-wait, cli-wait);
+- how the managed lead identity was resolved (`argument`, `environment`, `lead-state`);
+- whether an `idle` completion had real turn evidence rather than a metadata-only update;
+- whether a detached completion callback was registered and delivered;
 - whether a fallback was exceptional or an intentional SDK parity gap;
 - why the fallback occurred;
 - the associated agent/operation/provider/model/workspace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": {

package/skills/engineering-workflow/SKILL.md

@@ -44,7 +44,11 @@ Inside a managed Paseo lead, long deterministic workflows must be started detach
 - 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.
+The start command must return promptly with an `operationId`. Report that identifier and the meaningful starting phase to the user, then allow the current lead turn to end if there is no additional semantic work to do. The controller durably registers the initiating managed lead as a completion target. When the operation becomes `SUCCEEDED`, `FAILED` or `CANCELLED`, AEH sends that lead an `[AEH_OPERATION_COMPLETED]` follow-up so it can consume the durable result and finish the original user request.
+
+Do **not** keep the lead alive by repeatedly calling `aeh operation status` or `aeh_operation_status`. Those are explicit diagnostics/manual-recovery surfaces. 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; cancellation also follows the completion-callback path after cleanup.
+
+When `[AEH_OPERATION_COMPLETED]` arrives, treat it as an internal continuation event, not a new user task. Do not create another AUDIT/RUN. Read the existing operation state and cited report/result artifact, then complete the original user-facing response.
 
 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.
 
@@ -89,10 +93,12 @@ Do not invoke sudo or silently install unmanaged host prerequisites.
 
 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.
+3. AEH runs deterministic validators, classifies failures, dispatches the materialized reviewers with that evidence, waits for the complete reviewer barrier, deduplicates findings and calculates quality debt.
+4. The lead is allowed to finish its initiating conversational turn while step 3 continues. It must not infer that the AUDIT ended merely because its own turn ended or because some reviewers have replied.
+5. Only after the controller reaches terminal operation state does it send `[AEH_OPERATION_COMPLETED]` back to the initiating lead. The lead then reads the persisted AuditReport and completes the original user-facing audit response.
+6. Validator failures remain evidence; do not reinterpret them as PASS.
+7. Persisted reports under `.harness/audits/` and `.harness/operations/` are durable input for later remediation and recovery.
+8. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
 
 ## Issue-driven CHANGE path
 
@@ -115,6 +121,7 @@ For a CHANGE classified QUICK:
 2. `aeh quick validate <id>`.
 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.
+5. The lead may end its current turn after the detached operation starts; AEH's completion callback will reactivate it after the full run/review/delivery state machine is terminal.
 
 ## SPEC path — OpenSpec authoring
 
@@ -130,17 +137,20 @@ The lead must not write proposal/spec/design/tasks/Gherkin itself.
 
 If OpenSpec cannot express a true product decision without guessing, return `REQUIRES_PRODUCT_DECISION`; otherwise author and validate autonomously.
 
-## Operation observation
+## Operation observation and recovery
+
+Durable operation state remains authoritative, but normal managed-lead continuation is callback-driven rather than polling-driven:
 
-Use durable operation state for progress rather than narrating terminal silence:
+- `[AEH_OPERATION_COMPLETED]` -> normal wake-up/continuation after terminal state;
+- `aeh operation status <id>` -> explicit diagnostic controller status/phase/result/error;
+- `aeh paseo agents --operation <id>` -> manual inspection of real LLM participants and their roles/phases;
+- `aeh operation wait <id>` -> synchronous non-interactive/recovery boundary only.
 
-- `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.
+If a completion callback is known to have failed, inspect the `.harness/operations/<id>.completion.json` sidecar and Paseo traces, then recover by reading the terminal operation/report directly. Do not launch a duplicate operation solely because the callback failed.
 
 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.
 
-Paseo lifecycle/provider/context integration decisions are recorded under `.harness/telemetry/paseo.ndjson`; normal telemetry/OTLP receives the same events when enabled. Use these traces to distinguish SDK-native paths, negotiated fallbacks and intentional public-SDK parity gaps rather than inferring behavior from terminal output.
+Paseo lifecycle/provider/context/integration decisions are recorded under `.harness/telemetry/paseo.ndjson`; normal telemetry/OTLP receives the same events when enabled. Use these traces to distinguish SDK-native paths, reviewer turn-barrier evidence, completion callback delivery, negotiated fallbacks and intentional public-SDK parity gaps rather than inferring behavior from terminal output.
 
 ## Quality convergence and recovery
 
@@ -165,4 +175,4 @@ If the repository is AEH itself or the task changes topology, toolchain, skills,
 
 ## User-facing communication
 
-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.
+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. For a detached operation, one start acknowledgement is normally enough; do not emit a stream of status polls. When the completion callback arrives, provide the actual consolidated result. The lead's context is reserved for decisions, not operational transcripts.

package/skills/paseo-orchestration/SKILL.md

@@ -33,6 +33,21 @@ When the AEH control MCP server (`aeh operation mcp`) is injected, use its tools
 
 These MCP tools call the same persistent detached operation controller/policy code as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` and `aeh context guard` are short compatibility surfaces; do not replace them with long synchronous `aeh audit`/`aeh run` from the conversational lead.
 
+## Detached operation completion
+
+Managed AUDIT/RUN operations are callback-driven. When `aeh_operation_start_audit` or `aeh_operation_start_run` succeeds, the deterministic controller durably records the initiating managed lead as the completion target. The lead may end its current conversational turn while reviewers/workers continue independently.
+
+Do **not** repeatedly poll `aeh_operation_status` in the normal path. When the operation reaches `SUCCEEDED`, `FAILED` or `CANCELLED`, AEH sends an `[AEH_OPERATION_COMPLETED]` follow-up to the same lead. Treat that message as an internal continuation of the still-pending user request:
+
+- do not start a duplicate AUDIT/RUN;
+- inspect the existing operation record and the durable report/result artifact named by the callback;
+- finish the original user-facing request from those durable results;
+- use `aeh_operation_status` only for explicit diagnostics, manual inspection, or recovery when callback delivery is known to have failed.
+
+Callback delivery state is persisted separately from the engineering result. A failed callback must never rewrite a successful engineering operation as failed. Relevant integration traces are `harness.paseo.operation.callback.registered`, `.target`, `.sent`, `.failed`, and `.disabled`.
+
+This wake-up mechanism is intentionally independent of Paseo parent/child ownership. AEH reviewers/workers remain top-level agents so a lead rotation does not terminate them.
+
 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.
 
 ## SDK-first lifecycle
@@ -45,6 +60,8 @@ AEH should use the public `@getpaseo/client` surface first for semantic operatio
 - agent subscriptions for event-driven completion, with subscribe-before-refetch race closure;
 - provider snapshot/model/diagnostic APIs for early configuration failures.
 
+For a continued/reused agent turn, capture the last assistant response **before** dispatch. An `idle` snapshot is not sufficient proof that the new turn finished: accept it only after a real active-turn transition or assistant output that differs from the pre-dispatch baseline. Metadata-only subscription updates are not turn activity.
+
 The CLI remains a compatibility/parity-gap surface, not a parallel source of truth. Two intentional external-controller CLI uses currently remain for Paseo 0.3.1:
 
 1. operation workspace creation requiring `--isolation local` plus user-visible `--title`, which the public SDK create contract does not yet expose with equivalent parity;
@@ -60,9 +77,9 @@ Use `aeh paseo agents --operation <id>` (or Paseo's corresponding directory/stat
 
 ## Observability
 
-AEH persists integration decisions under `.harness/telemetry/paseo.ndjson` even when remote OTLP export is disabled. Relevant events include provider preflight, agent snapshot/context source, lifecycle transport, event-driven wait, SDK-to-CLI fallback, intentional workspace CLI use and cleanup CLI use. When normal Harness telemetry is enabled the same events also flow through the standard telemetry/OTLP path.
+AEH persists integration decisions under `.harness/telemetry/paseo.ndjson` even when remote OTLP export is disabled. Relevant events include provider preflight, agent snapshot/context source, lifecycle transport, event-driven wait, resumed-turn baseline, detached-operation callback delivery, SDK-to-CLI fallback, intentional workspace CLI use and cleanup CLI use. When normal Harness telemetry is enabled the same events also flow through the standard telemetry/OTLP path.
 
-A trace should answer: which transport was used, which source supplied state, whether a fallback was intentional or exceptional, why it happened, and which operation/agent/provider/model was affected.
+A trace should answer: which transport was used, which source supplied state, whether a fallback was intentional or exceptional, why it happened, which operation/agent/provider/model was affected, and whether completion notification reached the initiating lead.
 
 ## Lead discipline