agentopology 0.2.4 → 0.3.0

package/dist/bindings/__tests__/hybrid-e2e.test.js

@@ -0,0 +1,94 @@
+/**
+ * Hybrid end-to-end test.
+ *
+ * Unit tests check each binding in isolation. THIS test compiles BOTH bindings
+ * from the SAME .at file and proves they COMPOSE into one coherent hybrid:
+ *   - the host (claude-code) and the rung (claude-workflow) partition the agents
+ *     with no overlap and no gap,
+ *   - they agree on the seam (workflow filename, Blackboard root, SEAM doc),
+ *   - the generated workflow.js is syntactically valid JavaScript,
+ *   - nothing is silently dropped (the LOSSY report exists).
+ *
+ * This is the real "does the hybrid work end to end" gate.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, writeFileSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { parse } from "../../parser/index.js";
+import { claudeCodeBinding, claudeWorkflowBinding } from "../index.js";
+import { seamFiles, isWorkflowSeamAgent, isHybridTopology } from "../lib/seam.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixturePath = path.resolve(here, "../../../examples/matchmat-ship.at");
+const ast = parse(readFileSync(fixturePath, "utf-8"));
+const name = ast.topology.name;
+const hostFiles = claudeCodeBinding.scaffold(ast);
+const wfFiles = claudeWorkflowBinding.scaffold(ast);
+const hostPaths = hostFiles.map((f) => f.path);
+const wfPaths = wfFiles.map((f) => f.path);
+const agents = ast.nodes.filter((n) => n.type === "agent");
+const wfAgents = agents.filter(isWorkflowSeamAgent).map((a) => a.id);
+const hostAgents = agents.filter((a) => !isWorkflowSeamAgent(a)).map((a) => a.id);
+describe("hybrid e2e: matchmat-ship.at → claude-code + claude-workflow", () => {
+    it("the fixture is a hybrid topology", () => {
+        expect(isHybridTopology(ast)).toBe(true);
+        expect(wfAgents.length).toBeGreaterThan(0);
+        expect(hostAgents.length).toBeGreaterThan(0);
+    });
+    it("agents partition cleanly: workflow agents NOT in host, host agents NOT in workflow.js", () => {
+        const wfScript = wfFiles.find((f) => f.path === seamFiles.workflowScript(name)).content;
+        // workflow-marked agents must NOT have a host AGENT.md
+        for (const id of wfAgents) {
+            expect(hostPaths).not.toContain(`.claude/agents/${id}/AGENT.md`);
+            expect(wfScript).toContain(id); // and they DO appear in the rung
+        }
+        // host agents must have a host AGENT.md and must NOT be agent() calls in the rung
+        for (const id of hostAgents) {
+            expect(hostPaths).toContain(`.claude/agents/${id}/AGENT.md`);
+        }
+    });
+    it("both halves agree on the seam (filename, SEAM doc, Blackboard root)", () => {
+        const wfFile = seamFiles.workflowScript(name);
+        const seamDoc = seamFiles.seamDoc(name);
+        // workflow binding emits the rung + the SEAM contract + the LOSSY report
+        expect(wfPaths).toContain(wfFile);
+        expect(wfPaths).toContain(seamDoc);
+        expect(wfPaths).toContain(seamFiles.lossyDoc(name));
+        // host references the same workflow filename + seam doc in its CLAUDE.md
+        const claudeMd = hostFiles.find((f) => f.path === ".claude/CLAUDE.md").content;
+        expect(claudeMd).toContain(wfFile);
+        expect(claudeMd).toContain(seamDoc);
+    });
+    it("the generated workflow.js is syntactically valid JavaScript (ESM)", () => {
+        const wfScript = wfFiles.find((f) => f.path === seamFiles.workflowScript(name)).content;
+        // The rung is an ES module (export const meta / export default). vm.Script is
+        // CommonJS-mode and rejects `export`, so validate via `node --check` on a temp
+        // .mjs file (the real syntax gate; we never execute it).
+        const tmp = path.join(os.tmpdir(), `at-e2e-${process.pid}.mjs`);
+        writeFileSync(tmp, wfScript);
+        try {
+            const res = spawnSync("node", ["--check", tmp], { encoding: "utf-8" });
+            expect(res.status, res.stderr).toBe(0);
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+        // sanity: pure-literal meta + at least one parallel fan-out
+        expect(wfScript).toContain("export const meta");
+        expect(wfScript).toMatch(/parallel\(/);
+    });
+    it("the host wires concurrent observability over the Blackboard (the hybrid's point)", () => {
+        const settings = hostFiles.find((f) => f.path === ".claude/settings.json");
+        expect(settings).toBeDefined();
+        // a PostToolUse observer must exist when the topology has a Blackboard
+        expect(settings.content).toMatch(/PostToolUse|observe/i);
+    });
+    it("nothing is silently dropped: the LOSSY report names the human split", () => {
+        const lossy = wfFiles.find((f) => f.path === seamFiles.lossyDoc(name)).content;
+        expect(lossy).toMatch(/human/i);
+        expect(lossy).toMatch(/UNREPRESENTABLE/);
+    });
+});
+//# sourceMappingURL=hybrid-e2e.test.js.map

package/dist/bindings/__tests__/hybrid-e2e.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-e2e.test.js","sourceRoot":"","sources":["../../../src/bindings/__tests__/hybrid-e2e.test.ts"],"names":[],"mappings":"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"}

package/dist/bindings/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAs8E/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aA0F/B,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAu4F/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -7,7 +7,8 @@
  * @module
  */
 import { deduplicateFiles } from "./types.js";
-import { shellStub } from "./lib/stub.js";
+import { shellStub, STUB_MARKER } from "./lib/stub.js";
+import { isWorkflowSeamAgent, seamFiles } from "./lib/seam.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -106,6 +107,142 @@ function getDelegationMode(ast) {
 function gitkeep(dirPath) {
     return { path: `${dirPath}/.gitkeep`, content: "", category: "machine" };
 }
+// ---------------------------------------------------------------------------
+// HYBRID AWARENESS (host + embedded claude-workflow rung)
+//
+// A topology can mark an agent/phase `extensions { claude-workflow { execution:
+// workflow } }`. The claude-workflow binding compiles those phases into a
+// `<topology>.workflow.js` rung. THIS (claude-code) binding is the HOST: it must
+// NOT emit a subagent AGENT.md for a workflow-marked agent — in the hybrid, the
+// host does not run that agent as a subagent; it LAUNCHES the workflow rung that
+// contains it and OBSERVES the Blackboard writes.
+//
+// The seam vocabulary here MUST stay in sync with src/bindings/claude-workflow.ts:
+//   - workflow.js filename:  `<topology>.workflow.js`
+//   - seam contract doc:     `<topology>-SEAM.md`
+//   - human-split README:    `<topology>-README.md`
+//   - Blackboard root:       `memory.workspace.path` (e.g. "workspace/")
+//   - run order: host runs host phases in-session, LAUNCHES the workflow.js for
+//     the workflow-marked phase(s), host hooks observe the writes LIVE.
+// ---------------------------------------------------------------------------
+// Seam constants/helpers (SEAM_NS, isWorkflowSeamAgent, seamFiles, workspaceRoot)
+// are the single source of truth shared with the claude-workflow binding —
+// imported from ./lib/seam.js. Do NOT re-hardcode the namespace or filenames here.
+/** Resolve an agent's phase (defaults to a large value so unphased trails). */
+function agentPhase(agent) {
+    return agent.phase ?? Number.MAX_SAFE_INTEGER;
+}
+/**
+ * The standard meaning of each custody maintenance verb. The verb NAMES are
+ * language vocabulary (public); these one-line charters tell the agent what each
+ * verb means operationally. The deeper "how to do it brilliantly" stays in the
+ * skill repo (MOAT) — these are intentionally the safe, obvious definitions.
+ */
+const CUSTODY_VERBS = {
+    link: "find mentions of existing notes and turn them into `[[wikilinks]]` (add-only — never delete a human's links)",
+    tag: "assign `#nested/tags` consistent with the tag hierarchy already present in the vault",
+    index: "update the relevant hub note (a Map-of-Content that `[[links]]` the cluster) so the new note is reachable",
+    backlink: "rely on computed backlinks from the `[[links]]` you write — never author backlinks by hand",
+    dedupe: "flag near-duplicate notes for human review — never auto-merge or delete",
+    summarize: "keep a short synthesized summary at the top of hub notes, refreshed when the cluster changes",
+    heal: "repair broken links after renames and surface ghost nodes (`[[links]]` to notes that don't exist yet)",
+};
+/**
+ * Generate the custody charter section for an agent that is `custodian-of` one
+ * or more stores. This is what makes custody a real binding behavior: the agent
+ * gets a standing instruction set to MAINTAIN the store(s), not just read them.
+ */
+function generateCustodyCharter(agent, storeMap) {
+    const out = [];
+    out.push("## Custody — you maintain these stores");
+    out.push("");
+    out.push("You are the **custodian** of the store(s) below: you own their upkeep, not just read access. " +
+        "Humans drop raw notes; your job is to wire them into the graph and keep it healthy.");
+    out.push("");
+    for (const storeId of agent.custodianOf ?? []) {
+        const store = storeMap.get(storeId);
+        out.push(`### ${storeId}`);
+        if (store?.path) {
+            out.push(`The vault lives at \`${store.path}\`. Maintain it with \`Read\`, \`Write\`, \`Edit\`, \`Grep\`, \`Glob\` — no database, just files.`);
+        }
+        if (store?.format === "obsidian") {
+            out.push("It is **Obsidian-format** markdown: only ever write `[[wikilinks]]`, `#tags`, `![[embeds]]`, and YAML frontmatter — nothing custom — so the vault round-trips in Obsidian.");
+        }
+        out.push("");
+        // Maintenance verbs — declared ones, or the safe default set.
+        const verbs = (agent.custodianDoes && agent.custodianDoes.length > 0)
+            ? agent.custodianDoes
+            : ["link", "tag", "index", "heal", "dedupe"];
+        out.push("When a note is added or changed, perform these maintenance steps:");
+        for (const verb of verbs) {
+            const meaning = CUSTODY_VERBS[verb] ?? `apply the \`${verb}\` maintenance step`;
+            out.push(`- **${verb}** — ${meaning}`);
+        }
+        out.push("");
+        out.push("Wire add-only and conservatively: prefer leaving a human's content untouched over a risky rewrite. When unsure, flag for review rather than edit.");
+        out.push("");
+    }
+    return out;
+}
+/**
+ * The set of phases that compile into the embedded workflow rung — every phase
+ * that contains ≥1 agent marked `execution: workflow`. (Matches the
+ * claude-workflow binding's `workflowPhases`: an agent sharing a workflow phase
+ * is folded into the rung too.)
+ */
+function workflowPhaseSet(ast) {
+    const phases = new Set();
+    for (const n of ast.nodes) {
+        if (n.type === "agent" && isWorkflowSeamAgent(n)) {
+            phases.add(agentPhase(n));
+        }
+    }
+    return phases;
+}
+/** Does this topology have ≥1 workflow-marked phase (i.e. is it a hybrid)? */
+function isHybridTopology(ast) {
+    return workflowPhaseSet(ast).size > 0;
+}
+/**
+ * The Blackboard root path from `memory.workspace.path`, or null. Both bindings
+ * key the seam off this path.
+ */
+function workspaceRoot(ast) {
+    const ws = ast.memory?.workspace;
+    return ws?.path ?? null;
+}
+/**
+ * Group the workflow-marked phases into contiguous runs (by sorted phase
+ * number). Each contiguous run is ONE launch directive (the host launches the
+ * workflow.js once for that span). Returns a list of phase-number arrays.
+ */
+function contiguousWorkflowPhaseRuns(ast) {
+    const sorted = [...workflowPhaseSet(ast)].sort((a, b) => a - b);
+    const runs = [];
+    let current = [];
+    for (const p of sorted) {
+        if (current.length === 0 || p === current[current.length - 1] + 1) {
+            current.push(p);
+        }
+        else {
+            runs.push(current);
+            current = [p];
+        }
+    }
+    if (current.length > 0)
+        runs.push(current);
+    return runs;
+}
+/** A short, stable label for a phase run (used in stub filenames). */
+function workflowRunLabel(ast, run) {
+    // Prefer the first workflow-marked agent id in the run's lowest phase — that
+    // reads naturally (e.g. "build" from `builder`). Fall back to phase numbers.
+    const lowest = run[0];
+    const agentInPhase = ast.nodes.find((n) => n.type === "agent" && agentPhase(n) === lowest && isWorkflowSeamAgent(n));
+    if (agentInPhase)
+        return agentInPhase.id;
+    return run.length === 1 ? `phase-${run[0]}` : `phases-${run[0]}-${run[run.length - 1]}`;
+}
 /**
  * Map topology permission strings to Claude Code permissionMode values.
  * Returns undefined when the permission mode should be omitted (default/autonomous).
@@ -242,6 +379,13 @@ function generateAgents(ast) {
         if (node.type !== "agent")
             continue;
         const agent = node;
+        // HYBRID SEAM: an agent marked `execution: workflow` is owned by the
+        // embedded workflow rung (claude-workflow binding → <topology>.workflow.js),
+        // NOT by the host. The host does not run it as a subagent — it launches the
+        // workflow rung and observes its Blackboard writes. So do NOT emit a
+        // .claude/agents/<name>/AGENT.md for it. See generateWorkflowLaunchArtifacts.
+        if (isWorkflowSeamAgent(agent))
+            continue;
         // Build frontmatter fields
         const fm = {};
         fm.name = agent.id;
@@ -430,6 +574,13 @@ function generateAgents(ast) {
                 sections.push("");
             }
         }
+        // Custody — the agent OWNS the upkeep of these stores (the `brain` pattern).
+        // Generated even when the agent has no hand-written prompt, so custody is a
+        // real binding behavior, not just prose the author happened to write.
+        if (agent.custodianOf && agent.custodianOf.length > 0) {
+            const storeMap = new Map((ast.stores ?? []).map(s => [s.id, s]));
+            sections.push(...generateCustodyCharter(agent, storeMap));
+        }
         // Retrieval strategy — rich details
         if (agent.retrieval) {
             const retrieval = (ast.retrievals ?? []).find(r => r.id === agent.retrieval);
@@ -1227,6 +1378,12 @@ function generateTopologySkill(ast) {
             sections.push("");
         }
     }
+    // HYBRID run order — mirrors the claude-workflow SEAM.md so the host playbook
+    // knows where it launches the embedded workflow rung and observes its writes.
+    const hybridRunOrder = buildHybridRunOrderSection(ast);
+    if (hybridRunOrder) {
+        sections.push(hybridRunOrder);
+    }
     files.push({
         path: `.claude/skills/${name}/SKILL.md`,
         content: sections.join("\n") + "\n",
@@ -1330,13 +1487,52 @@ function generateMemory(ast) {
     if (memory.workspace) {
         files.push(gitkeep(`.claude/skills/${name}/runs`));
     }
-    // Store directory markers
+    // Store directory markers. A `brain` store is a real, user-facing Obsidian
+    // vault — it lives at its declared `path:` (e.g. `brain/`), not buried under
+    // `.claude/stores/`, so a human can open the folder directly in Obsidian.
+    // We seed it with a root Map-of-Content note so the vault opens to something.
     const stores = ast.stores ?? [];
     for (const store of stores) {
-        files.push(gitkeep(`.claude/stores/${store.id}`));
+        if (store.type === "brain") {
+            const vault = (store.path ?? `${store.id}/`).replace(/\/+$/, "");
+            files.push(brainVaultSeed(store, vault));
+        }
+        else {
+            files.push(gitkeep(`.claude/stores/${store.id}`));
+        }
     }
     return files;
 }
+/**
+ * Seed a brain vault with a root index note (`_brain.md`) — an Obsidian Map-of-
+ * Content the librarian grows over time. Gives the vault a home page and proves
+ * the format contract (wikilinks, tags, frontmatter) from the first commit.
+ */
+function brainVaultSeed(store, vault) {
+    const lines = [
+        "---",
+        "tags:",
+        "  - brain/index",
+        "---",
+        "",
+        `# ${toTitle(store.id)}`,
+        "",
+        store.description ? `> ${store.description}` : "> The company brain.",
+        "",
+        "This is the root index of the brain — a Map of Content the librarian maintains.",
+        "Drop new notes into this folder and run `/wire-in <file>` to fold them in.",
+        "",
+        "## Clusters",
+        "",
+        "_New hub notes appear here as the brain grows._",
+        "",
+    ];
+    return {
+        path: `${vault}/_brain.md`,
+        content: lines.join("\n"),
+        category: "machine",
+    };
+}
 /**
  * Generate memory command files for each store.
  *
@@ -1763,6 +1959,21 @@ function generateSettings(ast) {
         };
         hooksByEvent[eventName].push(hookEntry);
     }
+    // HYBRID: host-layer concurrent Blackboard observer.
+    //
+    // The topology's bare-event `hooks { PostToolUse { matcher: "Write" ... } }`
+    // block is not surfaced into ast.hooks (only the named `hook <name> {}` form is
+    // parsed). We don't change the parser (out of scope); instead, when this is a
+    // hybrid topology WITH a Blackboard, we synthesize the observe-hook: a
+    // Blackboard implies a host-side observer that watches the workflow rung's
+    // Write tool-calls LIVE. This is the host's piece of the hybrid's concurrent
+    // observability (the deterministic workflow rung cannot express it).
+    const observeHook = buildHybridObserveHook(ast, topologyName);
+    if (observeHook) {
+        if (!hooksByEvent[observeHook.event])
+            hooksByEvent[observeHook.event] = [];
+        hooksByEvent[observeHook.event].push(observeHook.entry);
+    }
     // Write hooksByEvent to settings if any hooks or gates were registered
     if (Object.keys(hooksByEvent).length > 0) {
         settings.hooks = hooksByEvent;
@@ -2319,12 +2530,198 @@ function generateContextFile(ast) {
         }
         sections.push("");
     }
+    // HYBRID run order — when this topology composes with an embedded
+    // claude-workflow rung, document who runs/launches/observes what.
+    const hybridRunOrder = buildHybridRunOrderSection(ast);
+    if (hybridRunOrder) {
+        sections.push(hybridRunOrder);
+    }
     return {
         path: fileName,
         content: sections.join("\n") + "\n",
         category: "machine",
     };
 }
+/**
+ * HYBRID: emit a host-side "launch the workflow rung" skill stub for each
+ * contiguous workflow-marked phase run.
+ *
+ * In the hybrid model the host does NOT run the workflow-marked agents as
+ * subagents. At the corresponding point in the flow, the host LAUNCHES the
+ * embedded deterministic workflow rung (`<topology>.workflow.js`, emitted by the
+ * sibling claude-workflow binding). These stubs are the documented launch
+ * directives, scoped into the topology's skill scripts directory next to the
+ * gate/hook stubs (same AGENTOPOLOGY_STUB mechanism so CI can detect them).
+ */
+function generateWorkflowLaunchArtifacts(ast) {
+    const files = [];
+    if (!isHybridTopology(ast))
+        return files;
+    const name = ast.topology.name;
+    const workflowFile = seamFiles.workflowScript(name);
+    const seamDoc = seamFiles.seamDoc(name);
+    const root = workspaceRoot(ast);
+    const runs = contiguousWorkflowPhaseRuns(ast);
+    for (const run of runs) {
+        const label = workflowRunLabel(ast, run);
+        // Agents that this rung owns (for documentation in the stub body).
+        const ownedAgents = ast.nodes
+            .filter((n) => n.type === "agent" && run.includes(agentPhase(n)) && isWorkflowSeamAgent(n))
+            .map((a) => a.id);
+        const phaseLabel = run.length === 1 ? `phase ${run[0]}` : `phases ${run[0]}–${run[run.length - 1]}`;
+        const body = [
+            "#!/usr/bin/env bash",
+            `# Launch the embedded workflow rung for ${phaseLabel} (${ownedAgents.join(", ")}).`,
+            "# Auto-generated by agentopology scaffold — edit as needed.",
+            STUB_MARKER,
+            "set -euo pipefail",
+            "",
+            `# HYBRID SEAM (host -> embedded workflow). This step does NOT run`,
+            `# ${ownedAgents.join(", ")} as host subagent(s). Instead the host LAUNCHES the`,
+            `# deterministic workflow rung that owns ${phaseLabel}, emitted by the`,
+            `# claude-workflow binding as: ${workflowFile}`,
+            "#",
+            "# The rung reads its inputs from the Blackboard (seeded by the host's prior",
+            `# phase) and writes its results back so host hooks observe them LIVE.`,
+            root ? `# Blackboard root (shared by host + rung): ${root}` : "# Blackboard root: (memory.workspace.path not declared)",
+            `# Seam contract both bindings honor: ${seamDoc}`,
+            "#",
+            "# Claude Workflows are launched IN-SESSION via the /workflow keyword, not as a",
+            "# detached process. The orchestrator invokes the workflow at this step:",
+            "#",
+            `#     /workflow ${workflowFile}`,
+            "#",
+            "# If your harness launches workflows out-of-process instead, replace the line",
+            `# below with the real launcher (e.g. \`claude workflow ${workflowFile}\`).`,
+            "",
+            `echo "TODO: launch the workflow rung — invoke '/workflow ${workflowFile}' in-session (${phaseLabel}: ${ownedAgents.join(", ")})."`,
+            "",
+        ].join("\n");
+        files.push({
+            path: `.claude/skills/${name}/scripts/launch-${label}-workflow.sh`,
+            content: body,
+            category: "script",
+            executable: true,
+        });
+    }
+    return files;
+}
+/**
+ * HYBRID: build the "Hybrid run order" markdown block appended to the generated
+ * context file (.claude/CLAUDE.md) and the topology SKILL.md. It states the
+ * host's interleaving with the embedded workflow rung, in the SAME run-order
+ * vocabulary the claude-workflow binding's SEAM.md uses, so the two bindings
+ * stay in sync. Returns null when the topology is not a hybrid.
+ */
+function buildHybridRunOrderSection(ast) {
+    if (!isHybridTopology(ast))
+        return null;
+    const name = ast.topology.name;
+    const workflowFile = seamFiles.workflowScript(name);
+    const seamDoc = seamFiles.seamDoc(name);
+    const root = workspaceRoot(ast);
+    const wfPhases = workflowPhaseSet(ast);
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    const human = ast.nodes.find((n) => n.type === "human") ?? null;
+    const allPhases = [...new Set(agents.map(agentPhase))].sort((a, b) => a - b);
+    const idsInPhase = (p) => agents.filter((a) => agentPhase(a) === p).map((a) => a.id).join(", ");
+    const lines = [];
+    lines.push("## Hybrid run order");
+    lines.push("");
+    lines.push(`This topology is a **hybrid**: it composes the host (this \`.claude/\` tree) with an embedded deterministic workflow rung emitted by the \`claude-workflow\` binding as \`${workflowFile}\`. The host runs the host phases in-session; for the workflow-marked phase(s) it **launches the rung** and **observes** its Blackboard writes. Both sides honor the seam contract in \`${seamDoc}\`.`);
+    lines.push("");
+    if (root) {
+        lines.push(`**Blackboard root** (shared by host + rung): \`${root}\``);
+        lines.push("");
+    }
+    lines.push("Run order:");
+    lines.push("");
+    let step = 1;
+    for (const p of allPhases) {
+        if (wfPhases.has(p)) {
+            lines.push(`${step}. **Host launches \`${workflowFile}\`** for phase ${p} (${idsInPhase(p)}) — the deterministic rung. It reads the Blackboard inputs the host seeded, does the work, and writes its results back. Host hooks observe those writes LIVE (the concurrent observability the workflow rung itself cannot express). Launch via \`.claude/skills/${name}/scripts/launch-${workflowRunLabel(ast, [p])}-workflow.sh\` (i.e. \`/workflow ${workflowFile}\`).`);
+        }
+        else {
+            lines.push(`${step}. **Host (in-session)** runs phase ${p} (${idsInPhase(p)}) — writes its outputs to the Blackboard so the next rung can read them.`);
+        }
+        step++;
+    }
+    if (human) {
+        lines.push(`${step}. **Host** presents the Blackboard artifacts to the human \`${human.id}\`, who acts (e.g. promotes). Promotion triggers the SEPARATE downstream workflow.`);
+    }
+    lines.push("");
+    lines.push(`> This run order MUST match \`${seamDoc}\`'s "Run order" section (emitted by the claude-workflow binding). If you change one, change the other.`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * HYBRID: emit the host-layer concurrent Blackboard observer hook into
+ * settings.json.
+ *
+ * Rationale: the topology's `hooks { PostToolUse { matcher: "Write" ... } }`
+ * block is the bare-event form, which the parser does NOT currently surface into
+ * `ast.hooks` (only the named `hook <name> {}` form is parsed; changing the
+ * parser is out of scope). So we synthesize the observer hook from the presence
+ * of a Blackboard (`memory.workspace`): a Blackboard in a hybrid topology IMPLIES
+ * a host-side observer that watches the workflow rung's Write tool-calls live.
+ *
+ * Returns the hook entry to merge into settings.hooks.PostToolUse, or null.
+ */
+function buildHybridObserveHook(ast, topologyName) {
+    if (!isHybridTopology(ast))
+        return null;
+    if (!workspaceRoot(ast))
+        return null; // no Blackboard → no observer
+    // If a real ast.hook already targets PostToolUse/Write, the generic hook path
+    // emits it — don't double up.
+    const alreadyEmitted = ast.hooks.some((h) => h.on === "PostToolUse" && (h.matcher === "Write" || !h.matcher));
+    if (alreadyEmitted)
+        return null;
+    const scriptPath = `.claude/skills/${topologyName}/scripts/observe-blackboard.sh`;
+    return {
+        event: "PostToolUse",
+        scriptPath,
+        entry: {
+            matcher: "Write",
+            hooks: [
+                {
+                    type: "command",
+                    command: `bash ${scriptPath}`,
+                },
+            ],
+        },
+    };
+}
+/** HYBRID: the observe-blackboard.sh stub the observe-hook points at. */
+function generateObserveBlackboardScript(ast) {
+    const hook = buildHybridObserveHook(ast, ast.topology.name);
+    if (!hook)
+        return null;
+    const root = workspaceRoot(ast) ?? "workspace/";
+    const body = [
+        "#!/usr/bin/env bash",
+        "# Host-layer concurrent Blackboard observer.",
+        "# Auto-generated by agentopology scaffold — edit as needed.",
+        STUB_MARKER,
+        "set -euo pipefail",
+        "",
+        "# HYBRID SEAM (host observability for the embedded workflow rung).",
+        "# Wired as a PostToolUse(Write) hook in .claude/settings.json. It fires on every",
+        `# Write tool-call so the host can watch the Blackboard (${root}) the workflow`,
+        "# rung's agents write — that IS the concurrent observability the deterministic",
+        "# workflow rung itself cannot express. Stdin JSON payload is on FD 0.",
+        "",
+        "PAYLOAD=$(cat)",
+        `echo "TODO: observe Blackboard write under ${root} — inspect the payload and log/notify."`,
+        "",
+    ].join("\n");
+    return {
+        path: hook.scriptPath,
+        content: body,
+        category: "script",
+        executable: true,
+    };
+}
 /**
  * Merge `ast.env` into the settings.json output under an `env` key.
  *
@@ -2438,6 +2835,13 @@ export const claudeCodeBinding = {
         files.push(...generateHookScripts(ast));
         // Hook scripts (per-agent)
         files.push(...generateAgentHookScripts(ast));
+        // HYBRID: host-side launch directives for the embedded workflow rung(s).
+        files.push(...generateWorkflowLaunchArtifacts(ast));
+        // HYBRID: host-layer concurrent Blackboard observer script (paired with the
+        // synthesized PostToolUse(Write) hook in settings.json).
+        const observeScript = generateObserveBlackboardScript(ast);
+        if (observeScript)
+            files.push(observeScript);
         // Tool scripts
         files.push(...generateToolScripts(ast));
         // Schedule scripts