@evoclock/pi-agentic-driver 0.8.4 → 0.9.1

package/README.md

@@ -1,4 +1,4 @@
-# pi-agentic-driver v0.8.0
+# pi-agentic-driver v0.9.0
 
 <p align="center">
   <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver, Yamagane origami mark" width="140"/>
@@ -7,7 +7,7 @@
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat" alt="License: AGPL v3"/></a>
   <a href="https://www.npmjs.com/package/@evoclock/pi-agentic-driver"><img src="https://img.shields.io/npm/v/@evoclock/pi-agentic-driver?style=flat" alt="npm version"/></a>
-  <img src="https://img.shields.io/badge/version-0.8.0-blue?style=flat" alt="Version 0.8.0"/>
+  <img src="https://img.shields.io/badge/version-0.9.0-blue?style=flat" alt="Version 0.9.0"/>
   <img src="https://img.shields.io/badge/status-active%20development%20%26%20testing-orange?style=flat" alt="Status"/>
   <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat&logo=javascript&logoColor=black" alt="JavaScript"/>
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript"/>
@@ -51,6 +51,8 @@ proofs for agentic workflows.
 | `agentic_worker_dispatch` | Runs controlled worker journeys and observes worker liveness. | shipped |
 | `agentic_kanban_board` | Shows the workspace task board: lanes, flags, priorities, dependencies, and which cards can run. | shipped |
 | `agentic_kanban_board_write` | Adds cards to the board through the trusted writer, which records who authorized the work. | shipped |
+| `agentic_kanban_board_update` | Moves, closes, flags, edits, or removes cards on the board, always recording who authorized the change. | shipped |
+| `agentic_kanban_board_dispatch` | Claims an eligible board card for automated contained work and creates its assignment envelope. | shipped |
 
 **Status: active development and testing.** Each extension ships only after
 it passes fixture-based acceptance, native tests, live-session checks, and
@@ -190,30 +192,56 @@ silently, and return results as untrusted evidence.
 
 
 <details>
-<summary><strong>task board, planned work you can see</strong> <em>(released, 0.8.0)</em></summary>
+<summary><strong>task board, planned and automated work you can see</strong> <em>(released, 0.9.0)</em></summary>
 
-Keep planned work on a Kanban board. You read and edit the board in
-Obsidian or in the Vogelkop Task Board pane (our upcoming Scientific and
-Research Workbench). Agents read the same board and add cards to it.
+Keep planned work in canonical `TASKS.md`. You can read it directly or use
+the generated `board.md` view in Obsidian. Agents use the same canonical
+record through natural-language board tools.
 
-The board appears only when a `board.md` or `TASKS.md` file exists in the
-workspace. With no board file, the tools do not appear and nothing changes.
+You can tell an agent to add, edit, move, block, propose, close, or remove a
+card. The trusted writer assigns its ID, checks its fields, records your
+instruction, and protects its dispatch provenance.
 
-When an agent adds a card, a trusted writer does the bookkeeping: it
-assigns the card ID, computes the integrity hash, checks the card, and
-records who authorized the work. The record comes from you: your
-instruction, or your approval of an agent's proposal. A card without that
-record cannot be dispatched. A hand-edited card cannot fake the record, and
-a tampered card refuses to run.
+Agents cannot invent additional work or complete a card on their own. An
+agent report is evidence for your review. Only your clear instruction or
+direct board action completes the card.
 
-Only you complete a card. Move it to done in your board UI, or tell an
-agent to close it. An agent report that says the work is finished is
-evidence for your review. It is never the completion itself.
+For automated work, you set an explicit policy for the board. It defines:
 
-The card format is shared. The same board renders in Obsidian, with
-optional Tasks-plugin emoji, and in the Vogelkop Task Board pane. The
-machine-readable fields are the single source of truth, so there is no
-second copy to keep in sync.
+- allowed roles and repositories;
+- contained placement;
+- the maximum concurrent work;
+- the policy expiry; and
+- the risk ceiling.
+
+Without a valid policy, automated dispatch is refused.
+
+`agentic_kanban_board_dispatch` claims the highest-priority eligible card and
+creates a single-attempt assignment envelope. The envelope binds the card,
+repository, starting revision, assigned branch, allowed paths, stopping
+point, expiry, and interaction profile.
+
+Blocked, altered, expired, reused, or unauthorized assignments fail closed.
+The journey validates the authenticated envelope before each consequential
+step. It runs on the assigned branch and consumes the envelope when the
+attempt ends.
+
+Consuming an envelope releases the claim. It does not mark the card done.
+
+Claims and envelopes are kept in authenticated state beside `TASKS.md`. The
+derived `board.md` view shows active claims but never becomes an authority
+source.
+
+`agentic_kanban_pulse` checks the board for ready work and available capacity.
+A check only reports which work is ready to run. It does not claim cards. Interactive host
+work needs explicit policy and one native confirmation for the batch. Automated
+work requires containment and never falls back to the host.
+
+Coming next:
+
+- contained Pulse execution through Testudo;
+- Vogelkop support for the shared card fields; and
+- our own Obsidian plugin for canonical `TASKS.md`.
 
 </details>
 
@@ -388,10 +416,10 @@ end" or "don't wait for me" and the journey runs in autonomous mode. Say
 "do these two things" and it runs in the normal mode, pausing for you
 between steps. The mode is recorded in the report either way.
 
-The journeys run work you dispatch in natural language: work that is real
-and authorized but not yet formally placed on a kanban board. A task board
-integration is planned, and once it ships, planned journeys will execute
-board-managed work with the same containment and safety guarantees.
+Autonomous journeys can run work you dispatch directly or work claimed from
+a task board. Board-managed journeys use the card's authenticated assignment
+envelope and the board's automation policy. Direct journeys continue to work
+without a board.
 
 ### The cast
 
@@ -520,7 +548,7 @@ pi install npm:@evoclock/pi-agentic-driver
 Or from Git at a pinned tag:
 
 ```sh
-pi install git:github.com/evoclock/pi-agentic-driver@v0.8.0
+pi install git:github.com/evoclock/pi-agentic-driver@v0.9.0
 ```
 
 Released extensions load standalone; neither requires the other.
@@ -534,7 +562,7 @@ extensions you want with the object form in your Pi settings:
 {
   "packages": [
     {
-      "source": "npm:@evoclock/pi-agentic-driver@0.8.0",
+      "source": "npm:@evoclock/pi-agentic-driver@0.9.0",
       "extensions": [
         "extensions/aidr.ts",
         "extensions/code-phage.js"

package/extensions/herdr-communication.ts

@@ -1,7 +1,14 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+import { statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 export default async function herdrCommunicationPi(pi) {
-  const module = await import(new URL("../scripts/enforcement/herdr_communication_pi.js", import.meta.url).href);
+  const moduleUrl = new URL("../scripts/enforcement/herdr_communication_pi.js", import.meta.url);
+  // Native ESM retains transitive modules across Pi's Jiti extension reload.
+  // Bind this import to the current file revision so /reload cannot reuse it.
+  moduleUrl.searchParams.set("mtime", String(statSync(fileURLToPath(moduleUrl)).mtimeMs));
+  const module = await import(moduleUrl.href);
   return module.registerHerdrCommunicationInterface(pi);
 }

package/extensions/herdr-lifecycle.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-export default async function herdrLifecyclePi(pi) {
-  const module = await import(new URL("../scripts/enforcement/herdr_lifecycle_pi.js", import.meta.url).href);
-  return module.registerHerdrLifecycleInterface(pi);
+import { registerHerdrLifecycleInterface } from "../scripts/enforcement/herdr_lifecycle_pi.js";
+
+export default function herdrLifecyclePi(pi) {
+  return registerHerdrLifecycleInterface(pi);
 }

package/extensions/pulse.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Board Pulse provider extension. Registers the deterministic
+// agentic_kanban_pulse tool and owns the optional fixed-interval timer. The
+// board is resolved per tool call from the calling session's working
+// directory; a workspace with no board file gets a structured
+// board-unavailable result. Board Pulse is capacity scheduling; it is
+// distinct from Herdr worker liveness pulse.
+//
+// No resources start in the extension factory: the timer is created and
+// started only on session_start and cleared idempotently on session_shutdown
+// (PULSE_DESIGN_v3 §8). The worker spawn seam is the existing guarded
+// herdr-lifecycle boundary — native confirmation, trusted repository,
+// installed model roll, fixed argv, shell:false — never raw pane management.
+
+import { executeHerdrSpawnWorker } from "../scripts/enforcement/herdr_lifecycle_pi.js";
+import { resolveBoardPath, registerPulseTools, createPulseTimer, pulseTick, pulseWorkerSpawnSeam } from "../scripts/enforcement/pulse_scheduler_pi.js";
+
+export default function pulsePi(pi) {
+
+  // Guarded worker-creation seam (§2.5): every Pulse spawn goes through
+  // pulseWorkerSpawnSeam, which is placement-aware and fails closed — host
+  // placements route to executeHerdrSpawnWorker (native confirmation,
+  // verification); container/microvm placements are denied before any host
+  // worker is ever started. No other creation path exists.
+  const spawnWorker = pulseWorkerSpawnSeam({ executeHerdrSpawnWorker });
+
+  const result = registerPulseTools(pi, {
+    resolveBoardPath: (ctx) => resolveBoardPath(typeof ctx === "string" ? ctx : ctx?.cwd || process.cwd()),
+    spawnWorker,
+  });
+
+  // Optional timer (§8): created only after session_start, only when the
+  // resolved workspace policy enables Pulse in automated mode with a valid
+  // interval. fillOnStart queues one tick after startup; it is not catch-up.
+  // Ticks never overlap and missed ticks are never replayed. Reload/new/
+  // resume/fork emit session_shutdown first, so exactly one fresh runtime
+  // exists at a time and no in-memory single-flight state is inherited.
+  let timer = null;
+  const clearTimer = () => {
+    if (timer) {
+      timer.clear();
+      timer = null;
+    }
+  };
+  const setupTimer = async (_event, ctx) => {
+    clearTimer();
+    try {
+      const boardPath = resolveBoardPath(ctx?.cwd || process.cwd());
+      if (!boardPath) return;
+      const { readAutomationPolicy, checkAutomationPolicy } = await import(new URL("../scripts/enforcement/task_board_core_pi.js", import.meta.url).href);
+      const policy = readAutomationPolicy(boardPath);
+      const check = checkAutomationPolicy(policy, { boardPath });
+      const pulse = check.ok ? check.policy.pulse : null;
+      if (!pulse || pulse.enabled !== true || pulse.mode !== "automated") return;
+      timer = createPulseTimer({
+        intervalSeconds: pulse.intervalSeconds,
+        fillOnStart: pulse.fillOnStart === true,
+        tick: () => pulseTick({ boardPath, spawnWorker, context: ctx }),
+      });
+      timer.start();
+    } catch {
+      // No-board/no-policy/disabled policy produce zero scheduling effects.
+      clearTimer();
+    }
+  };
+  if (typeof pi?.on === "function") {
+    pi.on("session_start", setupTimer);
+    pi.on("session_shutdown", clearTimer);
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.8.4",
+  "version": "0.9.1",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -40,6 +40,7 @@
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",
     "extensions/task-board.ts",
+    "extensions/pulse.ts",
     "lib/adapters/diff-scope.mjs",
     "lib/adapters/evidence.mjs",
     "lib/adapters/narrative.mjs",
@@ -66,7 +67,10 @@
     "extensions/aidr.ts",
     "scripts/aidr_writing_review.js",
     "templates/AGENTS.md",
-    "scripts/enforcement/task_board_core_pi.js"
+    "scripts/enforcement/task_board_core_pi.js",
+    "scripts/enforcement/pulse_core_pi.js",
+    "scripts/enforcement/pulse_scheduler_pi.js",
+    "skills/pulse/SKILL.md"
   ],
   "pi": {
     "extensions": [

package/scripts/enforcement/herdr_async_dispatch_pi.js

@@ -16,6 +16,9 @@ import {
   HERDR_COMMUNICATION_ACTIONS,
 } from "./herdr_communication_pi.js";
 import { isNativeTuiContext } from "./native_tui_context.js";
+import { prepareEnvelopeForExecution, validateEnvelopeForExecution, consumeEnvelope, gitHead } from "./task_board_core_pi.js";
+import { sha256Hex } from "./task_board_core_pi.js";
+import { execFileSync } from "node:child_process";
 
 export const WORKER_DISPATCH_TOOL = "agentic_worker_dispatch";
 export const WORKER_DISPATCH_SCHEMA = "agentic-driver.worker-dispatch.v1";
@@ -28,10 +31,17 @@ const MAX_JOURNEY_STEPS = 200;
 const MAX_REPORT_BYTES = 32 * 1024;
 const REGISTRATIONS = new WeakSet();
 
+// The worker-side review-request marker. An implementation journey whose last
+// complete report carries this marker terminates as review_requested (§6.3):
+// it projects review readiness without approval. The board lane transition
+// remains a human/writer decision; Pulse never infers it.
+export const REVIEW_REQUEST_MARKER = "[REVIEW_REQUESTED]";
+
 // Terminal journey states. Only `cancelled` and `failed` are failures; every
 // other terminal state is an observed outcome, and no state is retried.
 export const WORKER_DISPATCH_TERMINAL_STATES = Object.freeze([
   "completed", "exhausted", "role-blocked", "cancelled", "failed", "waiting-approval", "worker-unresponsive",
+  "review_requested",
 ]);
 
 export const WORKER_DISPATCH_PARAMETERS = Object.freeze({
@@ -224,6 +234,46 @@ function journeyReceipt(journey) {
   return body;
 }
 
+// §10.2 progress snapshot: a compact observation attached to the journey
+// step/terminal evidence it belongs to. Not authority, not persisted
+// separately, and not written on every timer tick — only at assignment start
+// and meaningful checkpoints. Repository observations are read-only.
+function progressSnapshot({ taskId = null, envelope = null, repository = null, workerStatus = null, lastReportAt = null }) {
+  const snapshot = {
+    schema: "agentic-driver.progress-snapshot.v1",
+    taskId,
+    at: new Date().toISOString(),
+  };
+  if (envelope) {
+    snapshot.envelopeId = envelope.envelopeId ?? null;
+    snapshot.cardId = envelope.cardId ?? null;
+    snapshot.branch = envelope.branch ?? null;
+  }
+  if (repository) {
+    snapshot.repository = repository;
+    snapshot.head = gitHead(repository);
+    const diff = scopedDiffHash(repository);
+    snapshot.scopedDiffHash = diff.hash;
+    snapshot.changedPaths = diff.paths;
+  }
+  if (workerStatus !== null) snapshot.workerStatus = workerStatus;
+  if (lastReportAt !== null) snapshot.lastCompleteReportAt = lastReportAt;
+  return snapshot;
+}
+
+// Hash of the repository's uncommitted diff (scoped work-in-progress signal).
+// Returns {hash, paths}; a repository where git is unavailable yields nulls.
+function scopedDiffHash(repository) {
+  try {
+    const paths = execFileSync("git", ["status", "--porcelain"], { cwd: repository, encoding: "utf8" })
+      .split("\n").map((line) => line.slice(3).trim()).filter(Boolean);
+    const diff = execFileSync("git", ["diff", "HEAD"], { cwd: repository, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { hash: sha256Hex(diff), paths: paths.slice(0, 64) };
+  } catch {
+    return { hash: null, paths: [] };
+  }
+}
+
 // One continuous journey. Each step: pulse (liveness + eligibility), observe
 // the next dispatchable item, one prompt exchange (no retry on any failure),
 // read the marked report, collate. Bounded by maxSteps, never wall-clock.
@@ -246,24 +296,53 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   const communicationOptions = options.communication ?? options;
   const replacementRole = options.replacementRole ?? role;
   const replacementModel = options.replacementModel ?? options.model ?? params.model;
-  const finish = (status) => ({
-    schema: WORKER_DISPATCH_SCHEMA,
-    ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
-    action: "dispatch",
-    mode,
-    autonomy,
-    ...(journey.cast ? { cast: journey.cast } : {}),
-    role,
-    status,
-    steps: journey.steps,
-    stepCount: journey.steps.filter((step) => step.status === "done").length,
-    code: journey.code,
-    report: journeyReceipt(journey),
-    reportMarkers: { open: "[WORKER_JOURNEY_REPORT_BEGIN]", close: "[WORKER_JOURNEY_REPORT_END]" },
-    handoff: journey.handoff,
-    nonAuthorizing: true,
-    persisted: false,
-  });
+  const board = options.board && typeof options.board === "object"
+    && typeof options.board.boardPath === "string" && options.board.envelope
+    ? options.board
+    : null;
+  let boardAttemptStarted = false;
+  let envelopeConsumed = false;
+  const finish = async (requestedStatus) => {
+    let status = requestedStatus;
+    if (board && boardAttemptStarted && !envelopeConsumed) {
+      const reason = ["completed", "exhausted", "cancelled", "failed", "waiting-approval", "role-blocked", "worker-unresponsive", "review_requested"].includes(status)
+        ? status
+        : status.startsWith("worker-unresponsive") ? "worker-unresponsive" : "failed";
+      let consumed;
+      try {
+        consumed = consumeEnvelope({ boardPath: board.boardPath, envelopeId: board.envelope.envelopeId, reason });
+      } catch (error) {
+        consumed = { ok: false, code: error?.code, reason: String(error?.message || error) };
+      }
+      if (consumed?.ok !== true) {
+        status = "failed";
+        journey.status = "failed";
+        journey.code = consumed?.code || "envelope-consume-failed";
+        journey.steps.push({ step: journey.steps.length + 1, taskId: null, status: "failed", error: consumed?.reason || "envelope consumption failed closed" });
+      } else {
+        envelopeConsumed = true;
+      }
+    }
+    journey.status = status;
+    return {
+      schema: WORKER_DISPATCH_SCHEMA,
+      ok: status === "completed" || status === "exhausted" || status === "waiting-approval" || status === "review_requested",
+      action: "dispatch",
+      mode,
+      autonomy,
+      ...(journey.cast ? { cast: journey.cast } : {}),
+      role,
+      status,
+      steps: journey.steps,
+      stepCount: journey.steps.filter((step) => step.status === "done").length,
+      code: journey.code,
+      report: journeyReceipt(journey),
+      reportMarkers: { open: "[WORKER_JOURNEY_REPORT_BEGIN]", close: "[WORKER_JOURNEY_REPORT_END]" },
+      handoff: journey.handoff,
+      nonAuthorizing: true,
+      persisted: false,
+    };
+  };
 
   // Explicit unstuck path: with native confirmation, spin up a replacement
   // worker for the same trusted repository/role through the existing
@@ -375,6 +454,35 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   }
   if (signal?.aborted) return finish("cancelled");
 
+  // Board-planned journey: authenticate the persisted envelope, prepare its
+  // assigned branch exactly once, then validate again. Every consequential
+  // prompt below repeats validation so mid-journey drift fails closed.
+  const checkBoardEnvelope = () => board
+    ? validateEnvelopeForExecution({ boardPath: board.boardPath, envelope: board.envelope })
+    : { ok: true };
+  if (board) {
+    let guard;
+    try {
+      const prepared = prepareEnvelopeForExecution({ boardPath: board.boardPath, envelope: board.envelope });
+      if (!prepared.ok) guard = prepared;
+      else {
+        boardAttemptStarted = true;
+        guard = checkBoardEnvelope();
+      }
+    } catch (error) {
+      journey.status = "failed";
+      journey.code = error?.code || "envelope-invalid";
+      journey.steps.push({ step: 0, taskId: null, status: "failed", error: String(error?.message || error).slice(0, 256) });
+      return finish("failed");
+    }
+    if (!guard.ok) {
+      journey.status = "failed";
+      journey.code = guard.code || "envelope-invalid";
+      journey.steps.push({ step: 0, taskId: null, status: "failed", error: guard.reason });
+      return finish("failed");
+    }
+  }
+
   for (let stepIndex = 1; stepIndex <= maxSteps; stepIndex += 1) {
     if (signal?.aborted) { journey.status = "cancelled"; return finish("cancelled"); }
 
@@ -452,6 +560,19 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       }
     }
 
+    // Revalidate immediately before the consequential prompt. This catches
+    // expiry, card/claim changes, and repository/branch/revision drift that
+    // occurred during pulse, queue observation, or confirmation.
+    if (board) {
+      const guard = checkBoardEnvelope();
+      if (!guard.ok) {
+        journey.status = "failed";
+        journey.code = guard.code || "envelope-invalid";
+        journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: guard.reason });
+        return finish("failed");
+      }
+    }
+
     // One prompt exchange. Any failure is terminal for the journey; there is
     // no invisible retry or resend.
     const exchange = await executeHerdrCommunication(
@@ -518,8 +639,21 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       status: "done",
       workerStatus: exchange.agentStatus,
       report: exchange.report,
+      // §10.2 progress snapshot at the meaningful checkpoint (step completion).
+      progress: progressSnapshot({
+        taskId: task.id,
+        envelope: board?.envelope ?? null,
+        repository: options.repository ?? null,
+        workerStatus: exchange.agentStatus ?? null,
+        lastReportAt: new Date().toISOString(),
+      }),
     });
     dispatched.add(task.id);
+    // §6.3 review routing: the last complete report requests review.
+    if (typeof exchange.report === "string" && exchange.report.includes(REVIEW_REQUEST_MARKER)) {
+      journey.status = "review_requested";
+      return finish("review_requested");
+    }
   }
 
   journey.status = "completed";

package/scripts/enforcement/herdr_communication_pi.js

@@ -42,6 +42,10 @@ const MAX_IDENTITY_FIELD_BYTES = 4 * 1024;
 const MAX_MARKER_HORIZONTAL_WHITESPACE = 128;
 const MAX_PROMPT_CONTRACT_ECHO_BYTES = 4 * 1024;
 const MAX_READ_LINES = 400;
+// A valid 32 KiB report can contain more than 400 short lines. A second,
+// finite read may cover one line per byte plus framing without relaxing the
+// existing 128 KiB process-output ceiling.
+const MAX_REPORT_READ_LINES = MAX_REPORT_BYTES + 16;
 const MAX_WAIT_TIMEOUT_MS = 300_000;
 const MAX_IMPLEMENTER_PROMPT_TIMEOUT_MS = 120_000;
 const COMMAND_TIMEOUT_MS = 15_000;
@@ -397,6 +401,14 @@ function validateParams(params) {
     if (!isReviewerRole(params.role) && params.timeoutMs > MAX_IMPLEMENTER_PROMPT_TIMEOUT_MS) {
       throw communicationError("implementer_prompt_timeout_exceeded", "worker prompts are limited to one two-minute atomic step", "denied");
     }
+    // Prompt freshness: each explicit prompt carries its own task scope and
+    // contract framing built from THAT call's prompt text. A stale or reused
+    // prompt text never binds a later exchange — provenance requires the
+    // echoed contract to match the current prompt exactly (provenancedReport
+    // Segment), so a prior exchange's scope cannot silently cover this one.
+    if (params.prompt.includes(REPORT_CONTRACT_LINE)) {
+      throw communicationError("prompt_preformatted", "the prompt must carry task scope only; the report contract is added by the transport (fails closed)", "denied");
+    }
   }
   if (action === "wait") {
     if (!Number.isInteger(params.timeoutMs) || params.timeoutMs < 1 || params.timeoutMs > MAX_WAIT_TIMEOUT_MS) {
@@ -458,7 +470,7 @@ function fixedArgv(action, params) {
     case "read":
       return [
         "agent", "read", params.role,
-        "--source", "recent-unwrapped", "--lines", String(MAX_READ_LINES),
+        "--source", "recent-unwrapped", "--lines", String(params.readLines ?? MAX_READ_LINES),
         "--format", "text",
       ];
     default:
@@ -468,11 +480,11 @@ function fixedArgv(action, params) {
 
 function promptWithReportRequirement(role, prompt) {
   const marker = reportMarkersForRole(role);
+  // Communication adds transport framing only. Task scope and role behaviour
+  // belong to the caller's current prompt; injecting either here would make a
+  // task-scoped instruction silently bind every later exchange for that role.
   const requirement = [
     "",
-    ...(isReviewerRole(role) ? ["Remain strictly read-only; do not modify files, state, or Git."] : [
-      "MANDATORY ATOMIC EXECUTION CONTRACT: execute one acceptance-checked step only; do not continue to a second file, test group, or follow-up; stop and report incomplete work as CHANGES_REQUIRED before the two-minute boundary.",
-    ]),
     REPORT_CONTRACT_LINE,
     marker.open,
     marker.close,
@@ -1223,11 +1235,23 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       if (waitedStatus === "blocked") {
         return errorResult(operation, communicationError("role_blocked", "the prompted role reached blocked state", "blocked"));
       }
-      const rawReport = await invokeHerdr("read", { action: "read", role }, context, options, signal);
-      const post = readText(rawReport);
+      let post = readText(await invokeHerdr("read", { action: "read", role }, context, options, signal));
       const sentPrompt = promptWithReportRequirement(role, request.prompt);
-      const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
-      const report = extractReportFromSegment(post, role, boundary.end);
+      let report;
+      let reportReadCount = 1;
+      try {
+        const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+        report = extractReportFromSegment(post, role, boundary.end);
+      } catch (error) {
+        if (!(error instanceof HerdrCommunicationError)
+            || !["report_scope_unavailable", "report_reversed"].includes(error.code)) throw error;
+        // The ordinary terminal tail can begin inside a valid current report.
+        // Expand once; never resend the prompt and never retry indefinitely.
+        post = readText(await invokeHerdr("read", { action: "read", role, readLines: MAX_REPORT_READ_LINES }, context, options, signal));
+        reportReadCount = 2;
+        const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+        report = extractReportFromSegment(post, role, boundary.end);
+      }
       return successResult(operation, {
         status: "complete",
         role,
@@ -1237,7 +1261,7 @@ export async function executeHerdrCommunication(params, context, options = {}, s
         promptSent: true,
         invocationCount: 1,
         waitCount: 1,
-        readCount: 1,
+        readCount: reportReadCount,
         report,
         reportMarkers: reportMarkersForRole(role),
       });
@@ -1250,8 +1274,15 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       }
       return successResult(operation, { role, status, agentStatus: status, repository });
     }
-    const raw = await invokeHerdr(operation, request, context, options, signal);
-    const report = extractLatestHerdrReport(readText(raw), role);
+    let raw = await invokeHerdr(operation, request, context, options, signal);
+    let report;
+    try {
+      report = extractLatestHerdrReport(readText(raw), role);
+    } catch (error) {
+      if (!(error instanceof HerdrCommunicationError) || error.code !== "report_reversed") throw error;
+      raw = await invokeHerdr("read", { action: "read", role, readLines: MAX_REPORT_READ_LINES }, context, options, signal);
+      report = extractLatestHerdrReport(readText(raw), role);
+    }
     return successResult(operation, {
       role,
       report,