pi-amq 0.1.1

package/integration/launch-preview.ts

@@ -0,0 +1,396 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { WorkerRolePreset } from "../workflow/worker-role-presets.js";
+import { workerRoleContract } from "../workflow/worker-role-presets.js";
+import type {
+  EditedWorkerProposal,
+  LaunchPreviewDecision,
+} from "../workflow/spawn-confirmation.js";
+import type {
+  ModelSpec,
+  WorkerBudget,
+  WorkerProposalEditableField,
+  WorkerRequest,
+} from "../workflow/workflow-types.js";
+
+export interface LaunchPreviewRoleOption {
+  readonly preset: WorkerRolePreset;
+  readonly defaultModel: ModelSpec;
+}
+
+export interface LaunchPreviewModelOptions {
+  readonly requests: readonly WorkerRequest[];
+  readonly roles: readonly LaunchPreviewRoleOption[];
+  readonly models: readonly ModelSpec[];
+  readonly difficultyModels: Readonly<Record<"easy" | "medium" | "hard", ModelSpec>>;
+  readonly normalizeModel?: (requestKey: string, roleName: string, model: ModelSpec) => ModelSpec;
+}
+
+interface EditableProposal {
+  request: WorkerRequest;
+  readonly originalBudget: WorkerBudget;
+  readonly edited: Set<WorkerProposalEditableField>;
+}
+
+export type BudgetDimension = keyof WorkerBudget;
+
+const EDITABLE_FIELDS = ["role", "task", "model", "difficulty", "budget"] as const;
+const BUDGET_DIMENSIONS = [
+  "maxAttempts",
+  "maxWallClockMs",
+  "maxTokens",
+  "maxCostUsd",
+  "maxOutputBytes",
+] as const satisfies readonly BudgetDimension[];
+const DIFFICULTIES = ["easy", "medium", "hard"] as const;
+
+export class LaunchPreviewModel {
+  readonly #proposals: EditableProposal[];
+  readonly #roles: readonly LaunchPreviewRoleOption[];
+  readonly #models: readonly ModelSpec[];
+  readonly #difficultyModels: LaunchPreviewModelOptions["difficultyModels"];
+  readonly #normalizeModel: (requestKey: string, roleName: string, model: ModelSpec) => ModelSpec;
+
+  constructor(options: LaunchPreviewModelOptions) {
+    if (options.requests.length === 0) throw new TypeError("Launch preview requires a proposal");
+    if (options.roles.length === 0) throw new TypeError("Launch preview requires role options");
+    if (options.models.length === 0) throw new TypeError("Launch preview requires live model options");
+    this.#proposals = options.requests.map((request) => ({
+      request: cloneRequest(request),
+      originalBudget: cloneBudget(request.budget),
+      edited: new Set(),
+    }));
+    this.#roles = [...options.roles];
+    this.#models = [...options.models];
+    this.#difficultyModels = options.difficultyModels;
+    this.#normalizeModel = options.normalizeModel ?? ((_requestKey, _roleName, model) => model);
+  }
+
+  get count(): number {
+    return this.#proposals.length;
+  }
+
+  request(index: number): WorkerRequest {
+    return cloneRequest(this.#entry(index).request);
+  }
+
+  editedFields(index: number): readonly WorkerProposalEditableField[] {
+    const edited = this.#entry(index).edited;
+    return EDITABLE_FIELDS.filter((field) => edited.has(field));
+  }
+
+  cycleRole(index: number, delta: -1 | 1): void {
+    const entry = this.#entry(index);
+    const current = this.#roles.findIndex((option) => option.preset.name === entry.request.role?.name);
+    const selected = this.#roles[wrap(current < 0 ? 0 : current, delta, this.#roles.length)]!;
+    entry.request = {
+      ...entry.request,
+      role: workerRoleContract(selected.preset),
+      difficulty: selected.preset.difficulty,
+      capabilities: selected.preset.capabilities,
+      model: this.#normalizeModel(entry.request.requestKey, selected.preset.name, selected.defaultModel),
+    };
+    entry.edited.add("role");
+  }
+
+  cycleModel(index: number, delta: -1 | 1): void {
+    const entry = this.#entry(index);
+    const current = this.#models.findIndex((model) => sameModel(model, entry.request.model));
+    entry.request = {
+      ...entry.request,
+      model: this.#normalizeModel(
+        entry.request.requestKey,
+        entry.request.role?.name ?? "worker",
+        this.#models[wrap(current < 0 ? 0 : current, delta, this.#models.length)]!,
+      ),
+    };
+    entry.edited.add("model");
+  }
+
+  cycleDifficulty(index: number, delta: -1 | 1): void {
+    const entry = this.#entry(index);
+    const current = DIFFICULTIES.indexOf(entry.request.difficulty ?? "medium");
+    const difficulty = DIFFICULTIES[wrap(current, delta, DIFFICULTIES.length)]!;
+    entry.request = {
+      ...entry.request,
+      difficulty,
+      model: this.#normalizeModel(
+        entry.request.requestKey,
+        entry.request.role?.name ?? "worker",
+        this.#difficultyModels[difficulty],
+      ),
+    };
+    entry.edited.add("difficulty");
+  }
+
+  replaceTask(index: number, goal: string): void {
+    const normalized = goal.trim();
+    if (normalized.length === 0) throw new TypeError("Worker task must not be empty");
+    const entry = this.#entry(index);
+    entry.request = { ...entry.request, goal: normalized };
+    entry.edited.add("task");
+  }
+
+  lowerBudget(index: number, dimension: BudgetDimension, value: number): void {
+    if (!Number.isFinite(value) || value <= 0) throw new TypeError("Budget value must be positive");
+    if (dimension !== "maxCostUsd" && !Number.isSafeInteger(value)) {
+      throw new TypeError(`${dimension} must be a positive integer`);
+    }
+    const entry = this.#entry(index);
+    const original = entry.originalBudget[dimension];
+    if (original.kind === "limited" && value > original.value) {
+      throw new TypeError(`${dimension} may only stay at or below its proposed value ${original.value}`);
+    }
+    entry.request = {
+      ...entry.request,
+      budget: { ...entry.request.budget, [dimension]: { kind: "limited", value } },
+    };
+    entry.edited.add("budget");
+  }
+
+  accepted(): LaunchPreviewDecision {
+    return {
+      kind: "accepted",
+      proposals: this.#proposals.map((entry): EditedWorkerProposal => ({
+        request: cloneRequest(entry.request),
+        humanEditedFields: EDITABLE_FIELDS.filter((field) => entry.edited.has(field)),
+      })),
+    };
+  }
+
+  #entry(index: number): EditableProposal {
+    const entry = this.#proposals[index];
+    if (!entry) throw new RangeError(`Unknown proposal index ${index}`);
+    return entry;
+  }
+}
+
+export async function openLaunchPreview(
+  ctx: ExtensionContext,
+  options: LaunchPreviewModelOptions,
+): Promise<LaunchPreviewDecision> {
+  if (ctx.mode !== "tui" || !ctx.hasUI) {
+    throw new Error("Launch preview requires an interactive TUI");
+  }
+  const model = new LaunchPreviewModel(options);
+  return ctx.ui.custom<LaunchPreviewDecision>((tui, _theme, _keys, done) => {
+    return new LaunchPreviewComponent(model, done, () => tui.requestRender());
+  }, { overlay: true });
+}
+
+class LaunchPreviewComponent {
+  readonly #model: LaunchPreviewModel;
+  readonly #done: (decision: LaunchPreviewDecision) => void;
+  readonly #invalidate: () => void;
+  #worker = 0;
+  #field = 0;
+  #budgetDimension = 0;
+  #editing: "task" | "budget" | undefined;
+  #buffer = "";
+  #diagnostic = "";
+
+  constructor(
+    model: LaunchPreviewModel,
+    done: (decision: LaunchPreviewDecision) => void,
+    invalidate: () => void,
+  ) {
+    this.#model = model;
+    this.#done = done;
+    this.#invalidate = invalidate;
+  }
+
+  handleInput(data: string): void {
+    if (data === "\u001b") {
+      this.#done({ kind: "cancelled" });
+      return;
+    }
+    if (this.#editing) {
+      if (isEnter(data)) {
+        try {
+          if (this.#editing === "task") this.#model.replaceTask(this.#worker, this.#buffer);
+          else this.#model.lowerBudget(
+            this.#worker,
+            BUDGET_DIMENSIONS[this.#budgetDimension]!,
+            Number(this.#buffer),
+          );
+          this.#editing = undefined;
+          this.#buffer = "";
+          this.#diagnostic = "";
+        } catch (error) {
+          this.#diagnostic = error instanceof Error ? error.message : String(error);
+        }
+        this.#invalidate();
+        return;
+      }
+      if (data === "\u007f" || data === "\b") this.#buffer = this.#buffer.slice(0, -1);
+      else if (!data.startsWith("\u001b") && [...data].every((character) => character >= " ")) {
+        this.#buffer += data;
+      }
+      this.#invalidate();
+      return;
+    }
+    if (isEnter(data)) {
+      this.#done(this.#model.accepted());
+      return;
+    }
+    if (isUp(data)) this.#worker = Math.max(0, this.#worker - 1);
+    else if (isDown(data)) this.#worker = Math.min(this.#model.count - 1, this.#worker + 1);
+    else if (data === "\t") this.#field = wrap(this.#field, 1, EDITABLE_FIELDS.length);
+    else if (data === "\u001b[Z") this.#field = wrap(this.#field, -1, EDITABLE_FIELDS.length);
+    else if (data === "[" && EDITABLE_FIELDS[this.#field] === "budget") {
+      this.#budgetDimension = wrap(this.#budgetDimension, -1, BUDGET_DIMENSIONS.length);
+    } else if (data === "]" && EDITABLE_FIELDS[this.#field] === "budget") {
+      this.#budgetDimension = wrap(this.#budgetDimension, 1, BUDGET_DIMENSIONS.length);
+    } else if (isLeft(data)) this.#cycle(-1);
+    else if (isRight(data)) this.#cycle(1);
+    else if ((data === "e" || data === "E") && (
+      EDITABLE_FIELDS[this.#field] === "task" || EDITABLE_FIELDS[this.#field] === "budget"
+    )) {
+      this.#editing = EDITABLE_FIELDS[this.#field] as "task" | "budget";
+      this.#buffer = "";
+      this.#diagnostic = "Type a replacement value, then Enter. Esc cancels the entire launch.";
+    }
+    this.#invalidate();
+  }
+
+  render(width: number): string[] {
+    const request = this.#model.request(this.#worker);
+    const field = EDITABLE_FIELDS[this.#field]!;
+    const dimension = BUDGET_DIMENSIONS[this.#budgetDimension]!;
+    const lines = [
+      `Launch preview · ${this.#model.count} proposed worker${this.#model.count === 1 ? "" : "s"}`,
+      "↑↓ worker · Tab field · ←→ cycle · [ ] budget dimension · e edit · Enter launch all · Esc cancel all",
+      "",
+      ...Array.from({ length: this.#model.count }, (_, index) => {
+        const candidate = this.#model.request(index);
+        const edited = this.#model.editedFields(index).length > 0 ? " edited" : "";
+        return `${index === this.#worker ? ">" : " "} ${index + 1}. ${candidate.role?.name ?? "worker"} · ${candidate.goal}${edited}`;
+      }),
+      "",
+      row("role", request.role?.name ?? "worker", field),
+      row("task", request.goal, field),
+      row("model", renderModel(request.model), field),
+      ...(request.modelFallbacks && request.modelFallbacks.length > 0
+        ? [`  fallback chain: ${request.modelFallbacks.map(renderModel).join(" → ")}`]
+        : []),
+      row("difficulty", request.difficulty ?? "medium", field),
+      row(`budget.${budgetLabel(dimension)}`, renderLimit(request.budget[dimension]), field),
+      `  context: ${request.context ?? "fresh"}${request.forkSource
+        ? ` · ${request.forkSource.inheritedEntries} entries · ${request.forkSource.inheritedBytes} bytes · leaf ${request.forkSource.branchPointId}`
+        : ""}`,
+      `  capabilities: ${request.capabilities.join(", ") || "none"}`,
+      ...peerGrantLines(request.capabilities),
+      ...(this.#editing ? [`  ${this.#editing}> ${this.#buffer}_`] : []),
+      ...(this.#diagnostic ? [`  ${this.#diagnostic}`] : []),
+    ];
+    return lines.map((line) => truncate(line, Math.max(20, width)));
+  }
+
+  invalidate(): void {}
+
+  #cycle(delta: -1 | 1): void {
+    switch (EDITABLE_FIELDS[this.#field]) {
+      case "role":
+        this.#model.cycleRole(this.#worker, delta);
+        return;
+      case "model":
+        this.#model.cycleModel(this.#worker, delta);
+        return;
+      case "difficulty":
+        this.#model.cycleDifficulty(this.#worker, delta);
+        return;
+      case "task":
+      case "budget":
+        this.#diagnostic = "Press e to replace this value";
+        return;
+    }
+  }
+}
+
+function cloneRequest(request: WorkerRequest): WorkerRequest {
+  return {
+    ...request,
+    acceptance: [...request.acceptance],
+    constraints: [...request.constraints],
+    budget: cloneBudget(request.budget),
+    model: { ...request.model },
+    ...(request.modelFallbacks
+      ? { modelFallbacks: request.modelFallbacks.map((model) => ({ ...model })) }
+      : {}),
+    capabilities: [...request.capabilities],
+    workspace: { ...request.workspace },
+    contextRefs: request.contextRefs.map((reference) => ({ ...reference })),
+    ...(request.role ? { role: { ...request.role } } : {}),
+    ...(request.proposal ? {
+      proposal: {
+        ...request.proposal,
+        humanEditedFields: [...request.proposal.humanEditedFields],
+      },
+    } : {}),
+  };
+}
+
+function cloneBudget(budget: WorkerBudget): WorkerBudget {
+  return {
+    maxAttempts: { ...budget.maxAttempts },
+    maxWallClockMs: { ...budget.maxWallClockMs },
+    maxTokens: { ...budget.maxTokens },
+    maxCostUsd: { ...budget.maxCostUsd },
+    maxOutputBytes: { ...budget.maxOutputBytes },
+  };
+}
+
+function renderModel(model: ModelSpec): string {
+  return `${model.provider}/${model.id}${model.thinkingLevel ? ` (${model.thinkingLevel})` : ""}`;
+}
+
+function peerGrantLines(capabilities: readonly string[]): readonly string[] {
+  const grants = capabilities.filter((capability) => capability.startsWith("message_worker:"));
+  return grants.length === 0 ? [] : [`  peer grants: ${grants.join(", ")}`];
+}
+
+function sameModel(left: ModelSpec, right: ModelSpec): boolean {
+  return left.provider === right.provider
+    && left.id === right.id;
+}
+
+function renderLimit(limit: WorkerBudget[BudgetDimension]): string {
+  return limit.kind === "unlimited" ? "unlimited" : String(limit.value);
+}
+
+function budgetLabel(dimension: BudgetDimension): string {
+  return dimension.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+function row(label: string, value: string, selected: string): string {
+  return `${selected === label.split(".")[0] ? ">" : " "} ${label}: ${value}`;
+}
+
+function wrap(index: number, delta: -1 | 1, length: number): number {
+  return (index + delta + length) % length;
+}
+
+function isEnter(data: string): boolean {
+  return data === "\r" || data === "\n";
+}
+
+function isUp(data: string): boolean {
+  return data === "\u001b[A";
+}
+
+function isDown(data: string): boolean {
+  return data === "\u001b[B";
+}
+
+function isRight(data: string): boolean {
+  return data === "\u001b[C";
+}
+
+function isLeft(data: string): boolean {
+  return data === "\u001b[D";
+}
+
+function truncate(value: string, width: number): string {
+  const characters = [...value];
+  return characters.length <= width ? value : `${characters.slice(0, Math.max(1, width - 1)).join("")}…`;
+}

package/integration/transport-port.ts

@@ -0,0 +1,29 @@
+export type TransportState =
+  | { readonly kind: "dormant"; readonly reason: string }
+  | { readonly kind: "send-only"; readonly binding: unknown }
+  | {
+      readonly kind: "receiving";
+      readonly binding: unknown;
+      readonly receiverGeneration: string;
+    };
+
+export type TransportResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: TransportError };
+
+export type TransportError =
+  | {
+      readonly code: "unavailable" | "invalid-request" | "context-mismatch";
+      readonly committed: false;
+      readonly cause?: unknown;
+    }
+  | { readonly code: "cancelled"; readonly committed: false; readonly cause?: unknown }
+  | { readonly code: "commit-indeterminate"; readonly committed: "unknown"; readonly cause: unknown };
+
+/** Internal cross-domain stub; concrete command/result types arrive with their owning phases. */
+export interface TransportPort {
+  state(): TransportState;
+  send(command: unknown, signal: AbortSignal): Promise<TransportResult<unknown>>;
+  reply(command: unknown, signal: AbortSignal): Promise<TransportResult<unknown>>;
+  waitForReceipt(query: unknown, signal: AbortSignal): Promise<TransportResult<unknown>>;
+}

package/integration/worker-completion-notifier.ts

@@ -0,0 +1,98 @@
+import type { RunProjectionV2, WorkerId } from "../workflow/workflow-types.js";
+
+export interface WorkerNotice {
+  readonly level: "info" | "warning" | "error";
+  readonly message: string;
+}
+
+export interface CompletionTimerScheduler {
+  schedule(delayMs: number, callback: () => void): { cancel(): void };
+}
+
+export class WorkerCompletionNotifier {
+  readonly #publish: (notice: WorkerNotice) => void;
+  readonly #timers: CompletionTimerScheduler;
+  readonly #windowMs: number;
+  readonly #states = new Map<WorkerId, string>();
+  readonly #successful = new Set<WorkerId>();
+  #flush: { cancel(): void } | undefined;
+
+  constructor(options: {
+    readonly publish: (notice: WorkerNotice) => void;
+    readonly timers?: CompletionTimerScheduler;
+    readonly windowMs?: number;
+  }) {
+    this.#publish = options.publish;
+    this.#timers = options.timers ?? new NodeCompletionTimers();
+    this.#windowMs = options.windowMs ?? 350;
+  }
+
+  baseline(run: RunProjectionV2): void {
+    for (const worker of Object.values(run.workers)) {
+      this.#states.set(worker.workerId, worker.state);
+    }
+  }
+
+  observe(run: RunProjectionV2): void {
+    for (const worker of Object.values(run.workers)) {
+      const previous = this.#states.get(worker.workerId);
+      this.#states.set(worker.workerId, worker.state);
+      if (previous === undefined || previous === worker.state) continue;
+      switch (worker.state) {
+        case "done":
+          this.#successful.add(worker.workerId);
+          this.#scheduleSuccessFlush();
+          break;
+        case "failed":
+          this.#emit({ level: "error", message: `Worker ${worker.workerId} failed.` });
+          break;
+        case "blocked":
+          this.#emit({ level: "warning", message: `Worker ${worker.workerId} paused for typed input.` });
+          break;
+        case "ambiguous":
+          this.#emit({ level: "warning", message: `Worker ${worker.workerId} requires reconciliation.` });
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  dispose(): void {
+    this.#flush?.cancel();
+    this.#flush = undefined;
+    this.#successful.clear();
+  }
+
+  #scheduleSuccessFlush(): void {
+    if (this.#flush) return;
+    this.#flush = this.#timers.schedule(this.#windowMs, () => {
+      this.#flush = undefined;
+      const ids = [...this.#successful].sort();
+      this.#successful.clear();
+      if (ids.length === 0) return;
+      this.#emit({
+        level: "info",
+        message: ids.length === 1
+          ? `Worker ${ids[0]} completed.`
+          : `Workers completed: ${ids.join(", ")}.`,
+      });
+    });
+  }
+
+  #emit(notice: WorkerNotice): void {
+    try {
+      this.#publish(notice);
+    } catch {
+      // UI delivery is advisory and cannot invalidate committed ledger truth.
+    }
+  }
+}
+
+class NodeCompletionTimers implements CompletionTimerScheduler {
+  schedule(delayMs: number, callback: () => void): { cancel(): void } {
+    const timer = setTimeout(callback, Math.max(0, delayMs));
+    timer.unref();
+    return { cancel: () => clearTimeout(timer) };
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "pi-amq",
+  "version": "0.1.1",
+  "description": "A daemonless AMQ bridge and governed worker runtime for pi",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "amq",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "extension",
+    "integration",
+    "scripts",
+    "skills",
+    "roles",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "transport",
+    "workflow",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test:compile": "tsc --project tsconfig.test.json",
+    "test": "npm run test:compile && node --test .test-dist/test/*.test.js",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@types/node": "24.12.4",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "typebox": "^1.3.7"
+  }
+}

package/roles/oracle.md

@@ -0,0 +1,9 @@
+---
+name: oracle
+tier: premium
+difficulty: hard
+capabilities:
+  - repo.read
+  - shell
+---
+Resolve a high-consequence ambiguity from authoritative evidence. State the strongest supported judgment, competing explanations, falsifiers, and the smallest next check that would change the decision.

package/roles/researcher.md

@@ -0,0 +1,8 @@
+---
+name: researcher
+tier: workhorse
+difficulty: medium
+capabilities:
+  - repo.read
+---
+Research the bounded question against primary sources. Separate sourced facts from inference, retain precise citations or local evidence paths, and identify material uncertainty without padding the report.

package/roles/reviewer.md

@@ -0,0 +1,9 @@
+---
+name: reviewer
+tier: workhorse
+difficulty: medium
+capabilities:
+  - repo.read
+  - shell
+---
+Review independently from implementation. Lead with verdict and source-backed findings, rerun decisive checks when authorized, and do not edit unless the contract explicitly requests remediation.

package/roles/scout.md

@@ -0,0 +1,8 @@
+---
+name: scout
+tier: economy
+difficulty: easy
+capabilities:
+  - repo.read
+---
+Map the requested surface quickly. Return exact paths, relevant symbols, and unresolved questions. Do not edit files or turn adjacent observations into scope.

package/roles/worker.md

@@ -0,0 +1,10 @@
+---
+name: worker
+tier: workhorse
+difficulty: medium
+capabilities:
+  - repo.read
+  - repo.write
+  - shell
+---
+Implement one bounded contract end to end. Preserve unrelated work, validate at the nearest stable seam, and report the changed artifacts, evidence, and residual risk.

package/scripts/demo-two-terminal.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AMQ_BIN="${AMQ_BIN:-/opt/homebrew/bin/amq}"
+DEMO_OWNED=0
+if [[ -n "${PI_AMQ_DEMO_DIR:-}" ]]; then
+  DEMO_DIR="${PI_AMQ_DEMO_DIR}"
+else
+  DEMO_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pi-amq-demo.XXXXXX")"
+  DEMO_OWNED=1
+fi
+DEMO_ROOT="${DEMO_DIR}/mail"
+
+amq_demo() {
+  env \
+    -u AM_ROOT -u AM_ROOT_ID -u AM_BASE_ROOT -u AM_BASE_ROOT_ID \
+    -u AM_SESSION -u AM_ME \
+    "${AMQ_BIN}" "$@"
+}
+
+json_id() {
+  node -e 'let value=""; process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => process.stdout.write(JSON.parse(value).id));'
+}
+
+mkdir -p "${DEMO_DIR}"
+(
+  cd "${DEMO_DIR}"
+  amq_demo coop init --root "${DEMO_ROOT}" --agents terminal-a,terminal-b,user --no-gitignore --json >/dev/null
+)
+
+echo "demo_root=${DEMO_ROOT}"
+echo "[terminal-a] publish status and send urgent/normal/low"
+amq_demo presence set --root "${DEMO_ROOT}" --me terminal-a --status busy --note "sending demo cohort" --json
+URGENT_ID="$(amq_demo send --root "${DEMO_ROOT}" --me terminal-a --to terminal-b --priority urgent --kind todo --subject urgent --body "urgent demo" --json | json_id)"
+NORMAL_ID="$(amq_demo send --root "${DEMO_ROOT}" --me terminal-a --to terminal-b --priority normal --kind question --subject normal --body "normal demo question" --json | json_id)"
+LOW_ID="$(amq_demo send --root "${DEMO_ROOT}" --me terminal-a --to terminal-b --priority low --kind status --subject low --body "low demo status" --json | json_id)"
+printf 'sent urgent=%s normal=%s low=%s\n' "${URGENT_ID}" "${NORMAL_ID}" "${LOW_ID}"
+
+echo "[terminal-b] inspect priority order, claim exact IDs, and reply"
+amq_demo list --root "${DEMO_ROOT}" --me terminal-b --new --limit 10 --json
+amq_demo read --root "${DEMO_ROOT}" --me terminal-b --id "${URGENT_ID}" --json
+amq_demo read --root "${DEMO_ROOT}" --me terminal-b --id "${NORMAL_ID}" --json
+amq_demo read --root "${DEMO_ROOT}" --me terminal-b --id "${LOW_ID}" --json
+REPLY_ID="$(amq_demo reply --root "${DEMO_ROOT}" --me terminal-b --id "${NORMAL_ID}" --kind answer --body "normal demo answer" --json | json_id)"
+printf 'reply=%s\n' "${REPLY_ID}"
+amq_demo presence set --root "${DEMO_ROOT}" --me terminal-b --status idle --note "demo cohort drained" --json
+
+echo "[terminal-a] claim reply, inspect receipts, and list status"
+amq_demo read --root "${DEMO_ROOT}" --me terminal-a --id "${REPLY_ID}" --json
+amq_demo receipts list --root "${DEMO_ROOT}" --me terminal-b --msg-id "${URGENT_ID}" --json
+amq_demo receipts list --root "${DEMO_ROOT}" --me terminal-b --msg-id "${NORMAL_ID}" --json
+amq_demo receipts list --root "${DEMO_ROOT}" --me terminal-a --msg-id "${REPLY_ID}" --json
+amq_demo presence list --root "${DEMO_ROOT}" --me terminal-a --json
+
+if [[ "${DEMO_OWNED}" == "1" && "${KEEP_DEMO:-0}" != "1" ]]; then
+  rm -rf -- "${DEMO_DIR}"
+else
+  echo "kept_demo_dir=${DEMO_DIR}"
+fi