@heretek-ai/epistemic-swarm 0.7.2 → 0.7.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/.omp/commands/domainexpansion.md

@@ -6,4 +6,4 @@ Run the IUMBTEMS domain-expansion loop for `$1` loops (max 10):
 
 Bypasses per-loop gates; stops on count OR `.factory/STOP` file OR user kill.
 Each loop: agents propose direction, quick swarm check, implement, dual-QA verify.
-Enforce via `python3 skills/factory/scripts/factory.py expansion --run <run> --loops $1`.
+Enforce via the `iumbtems_factory` tool (expansion command with loops/max_loops).

package/.omp/commands/factory.md

@@ -6,4 +6,4 @@ Run the IUMBTEMS coding-factory Manager loop for `$1`:
 
 1. Grill until `.factory/frontier.json` is settled (max 5 swarm cycles per gate); explicit user approve advances each gate.
 2. Per gate: `python3 runner/research_swarm.py --mode brainstorm` plus `--mode darkharvest` (mock-first), then synthesize `.roadmap/<phase>/` GOAL.md + dossier.json.
-3. Programmer subagent per phase; qa-a plus qa-b per phase; retries tracked via `python3 skills/factory/scripts/factory.py` (3 failures escalate).
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries tracked via the `iumbtems_factory` tool (phase-add / qa-record; 3 failures escalate). Never invoke factory helper scripts by relative path.

package/extensions/pi/index.js

@@ -210,8 +210,7 @@ export default function initPiExtension(pi) {
     } catch { /* alias is best-effort across pi/omp versions */ }
 
     // /darkharvest: Product competitor teardown with harvest verdicts
-    pi.registerCommand('darkharvest', {
-      description: 'Product competitor teardown: seed inspirations, expand to adjacents, emit harvest verdicts',
+    pi.registerCommand('darkharvest', {      description: 'Product competitor teardown: seed inspirations, expand to adjacents, emit harvest verdicts',
       usage: '/darkharvest <product-arena> [--seeds <urls>]',
       handler: async (args, ctx) => {
         const objective = args.trim();
@@ -316,6 +315,33 @@ export default function initPiExtension(pi) {
         return { content: [{ type: 'text', text: r.text }] };
       }
     });
+
+    // Tool: iumbtems_factory (run-state helper, no script paths)
+    pi.registerTool({
+      name: 'iumbtems_factory',
+      description: 'Drive factory run state: init / phase-add / qa-record / expansion / stop',
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', enum: ['init', 'phase-add', 'qa-record', 'expansion', 'stop'] },
+          run: { type: 'string', description: 'Factory run name' },
+          phase: { type: 'string' },
+          goal: { type: 'string' },
+          accept: { type: 'string' },
+          seat: { type: 'string' },
+          verdict: { type: 'string', enum: ['pass', 'fail', 'conditional'] },
+          reason: { type: 'string' },
+          loops: { type: 'integer' },
+          max_loops: { type: 'integer' },
+          project_dir: { type: 'string' }
+        },
+        required: ['command']
+      },
+      execute: async (args = {}) => {
+        const r = callMcp('iumbtems_factory', args, {});
+        return { content: [{ type: 'text', text: r.text }] };
+      }
+    });
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/factory/skills/factory/SKILL.md

@@ -13,6 +13,16 @@ description: Coding-factory Manager loop. Use when user invokes /factory or /dom
 - **qa-a / qa-b** (subagents): same model, DIVERGED prompts (functional-correctness vs adversarial edge-case). Read-only plus test execution; never edit.
 - **researcher** = existing `iumbtems_brainstorm` + `iumbtems_darkharvest` swarms (no new profile).
 
+## 1b. Driving run state (no filesystem paths)
+
+Use the **`iumbtems_factory` MCP tool** for all run-state changes — never a
+relative `skills/factory/scripts/factory.py` path (the toolchain lives in the
+npm cache in consuming projects, and relative paths broke live: the manager
+agent ran `find / -name factory.py`). The tool wraps the same helper and
+resolves the project via `project_dir` argument, `IUMBTEMS_PROJECT_DIR`, or
+the session cwd. It supports `init`, `phase-add`, `qa-record`, `expansion`,
+`stop`, and returns `status: escalated` (exit 2) on the 3rd QA failure.
+
 ## 2. Gate protocol (max 5 swarm cycles per gate)
 
 1. Grill until `.factory/frontier.json` settled (grilling skill).

package/plugins/factory/skills/factory/scripts/factory.py

@@ -2,8 +2,13 @@
 """
 Factory run-state helper: phase dossiers, QA retry bounds, expansion loop guard.
 
-All state lives under .factory/ (gitignored runtime state). Phase output goes
-to .roadmap/<phase>/. Evidence stays in .research/. Read-only w.r.t. repo code.
+All state lives under <project>/.factory/ (gitignored runtime state). Phase
+output goes to <project>/.roadmap/<phase>/. Evidence stays in <project>/
+.research/. Read-only w.r.t. repo code.
+
+Project directory resolution: --project-dir > IUMBTEMS_PROJECT_DIR env > the
+toolchain repo root (local-dev default). A consuming project must never leak
+state into the IUMBTEMS checkout.
 
 Usage:
   python3 skills/factory/scripts/factory.py init --run <name>
@@ -15,13 +20,25 @@ Usage:
 
 import argparse
 import json
+import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
-FACTORY_DIR = PROJECT_ROOT / ".factory"
-ROADMAP_DIR = PROJECT_ROOT / ".roadmap"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+def resolve_project_root(cli_value=None):
+    """--project-dir > IUMBTEMS_PROJECT_DIR > repo root (local-dev default)."""
+    for candidate in (cli_value, os.environ.get("IUMBTEMS_PROJECT_DIR")):
+        if candidate and Path(candidate).is_dir():
+            return Path(candidate).resolve()
+    return REPO_ROOT
+
+
+PROJECT_DIR = resolve_project_root()
+FACTORY_DIR = PROJECT_DIR / ".factory"
+ROADMAP_DIR = PROJECT_DIR / ".roadmap"
 
 MAX_QA_RETRIES = 3
 MAX_EXPANSION_LOOPS = 10
@@ -173,31 +190,48 @@ def cmd_stop(args):
     print(f"🛑 STOP file written for run '{args.run}'.")
 
 
+def _add_common(parser):
+    parser.add_argument(
+        "--project-dir",
+        default=None,
+        help="Project the factory state belongs to (default: IUMBTEMS_PROJECT_DIR env, else repo root)",
+    )
+
+
 def main():
+    global FACTORY_DIR, ROADMAP_DIR
     ap = argparse.ArgumentParser(description="Factory run-state helper")
     sub = ap.add_subparsers(dest="command", required=True)
 
     p = sub.add_parser("init")
     p.add_argument("--run", required=True)
+    _add_common(p)
     p = sub.add_parser("phase-add")
     p.add_argument("--run", required=True)
     p.add_argument("--phase", required=True)
     p.add_argument("--goal", required=True)
     p.add_argument("--accept", default="")
+    _add_common(p)
     p = sub.add_parser("qa-record")
     p.add_argument("--run", required=True)
     p.add_argument("--phase", required=True)
     p.add_argument("--seat", required=True)
     p.add_argument("--verdict", required=True)
     p.add_argument("--reason", default="")
+    _add_common(p)
     p = sub.add_parser("expansion")
     p.add_argument("--run", required=True)
     p.add_argument("--loops", type=int, required=True)
     p.add_argument("--max-loops", type=int, default=MAX_EXPANSION_LOOPS)
+    _add_common(p)
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
+    _add_common(p)
 
     args = ap.parse_args()
+    root = resolve_project_root(args.project_dir)
+    FACTORY_DIR = root / ".factory"
+    ROADMAP_DIR = root / ".roadmap"
     code = {
         "init": cmd_init,
         "phase-add": cmd_phase_add,

package/plugins/gemini/commands/domainexpansion.toml

@@ -3,5 +3,5 @@ prompt = """Run the IUMBTEMS domain-expansion loop for {{args}} loops (max 10).
 
 Bypasses per-loop gates; stops on count OR .factory/STOP file OR user kill.
 Each loop: agents propose direction, quick swarm check, implement, dual-QA verify.
-Enforce via: python3 skills/factory/scripts/factory.py expansion --run <run> --loops {{args}}.
+Enforce via the iumbtems_factory tool (command: expansion, with loops/max_loops).
 """

package/plugins/gemini/commands/factory.toml

@@ -3,6 +3,6 @@ prompt = """Run the IUMBTEMS coding-factory Manager loop for: {{args}}.
 
 1. Grill until .factory/frontier.json is settled (max 5 swarm cycles per gate); explicit user approve advances each gate.
 2. Per gate: python3 runner/research_swarm.py --mode brainstorm plus --mode darkharvest (mock-first), then synthesize .roadmap/<phase>/ GOAL.md + dossier.json.
-3. Programmer subagent per phase; qa-a plus qa-b per phase; retries via python3 skills/factory/scripts/factory.py (3 failures escalate).
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries via the iumbtems_factory tool (phase-add / qa-record; 3 failures escalate). Never invoke factory helper scripts by relative path.
 Report: .roadmap/ phases plus .factory/state.json.
 """

package/plugins/opencode/index.js

@@ -102,6 +102,7 @@ export const IUMBTEMS_TOOL_NAMES = [
   'iumbtems_oss_scout',
   'iumbtems_brainstorm',
   'iumbtems_darkharvest',
+  'iumbtems_factory',
   'iumbtems_verify_quote',
   'iumbtems_socratic_frontier',
   'iumbtems_reindex_claims',
@@ -291,6 +292,31 @@ const TOOL_CATALOG = [
       required: ['objective'],
     },
   },
+  {
+    name: 'iumbtems_factory',
+    description:
+      'Drive factory run state: init / phase-add / qa-record / expansion / stop. State goes to <project>/.factory and <project>/.roadmap; no helper-script path needed.',
+    input: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          enum: ['init', 'phase-add', 'qa-record', 'expansion', 'stop'],
+        },
+        run: { type: 'string', description: 'Factory run name' },
+        phase: { type: 'string', description: 'Phase id (e.g. 01-auth)' },
+        goal: { type: 'string' },
+        accept: { type: 'string', description: 'Semicolon-separated acceptance criteria' },
+        seat: { type: 'string', description: 'QA seat (qa-a | qa-b)' },
+        verdict: { type: 'string', enum: ['pass', 'fail', 'conditional'] },
+        reason: { type: 'string' },
+        loops: { type: 'integer', description: 'Expansion loop count (1-10)' },
+        max_loops: { type: 'integer' },
+        project_dir: { type: 'string', description: 'Project root (default: IUMBTEMS_PROJECT_DIR or cwd)' },
+      },
+      required: ['command'],
+    },
+  },
   {
     name: 'iumbtems_verify_quote',
     description:
@@ -558,7 +584,7 @@ export const OPENCODE_COMMANDS = [
       'If $ARGUMENTS is empty, ask the user what to build first; never proceed on placeholder input.',
       '1. Grill the user until .factory/frontier.json is settled (max 5 brainstorm+darkharvest swarm cycles per gate); explicit user approve advances each gate.',
       '2. Per gate run iumbtems_brainstorm and iumbtems_darkharvest (mock_mode only for dry runs), then synthesize .roadmap/<phase>/ GOAL.md + dossier.json (goal/evidence/acceptance/brief/verdict/hashes; every claim needs a VERIFIED hash).',
-      '3. Spawn the programmer subagent per phase with the phase dossier (cite phase hashes); run qa-a and qa-b (diverged prompts) per phase; track retries with skills/factory/scripts/factory.py (3 failures escalate to manager).',
+      '3. Spawn the programmer subagent per phase with the phase dossier (cite phase hashes); run qa-a and qa-b (diverged prompts) per phase; track retries with the iumbtems_factory tool (command: phase-add / qa-record; 3 failures escalate to manager). Never invoke factory helper scripts by relative path.',
       '4. Manager tiebreaks QA disagreements; explicit user sign-off closes each phase.',
     ].join('\n'),
   },
@@ -572,7 +598,7 @@ export const OPENCODE_COMMANDS = [
       'Run the IUMBTEMS domain-expansion loop as the manager agent.',
       'Loops: $ARGUMENTS (integer count, max 10)',
       'If $ARGUMENTS is not a positive integer, ask the user for the loop count first.',
-      '1. Bypass per-loop gates; stop on count OR .factory/STOP file OR user kill, whichever first (enforce via skills/factory/scripts/factory.py expansion).',
+      '1. Bypass per-loop gates; stop on count OR .factory/STOP file OR user kill, whichever first (enforce via the iumbtems_factory tool, command: expansion, with loops/max_loops).',
       '2. Each loop: agents propose direction, quick iumbtems_brainstorm/iumbtems_darkharvest check, implement via programmer spawn, dual-QA verify.',
       '3. All expansion proposals carry the strict VERIFIED evidence bar; log every loop to .factory/state.json.',
     ].join('\n'),
@@ -598,8 +624,14 @@ export function commandCatalog() {
   return out;
 }
 
-/** Tool map (object form) for the server hook; array catalog stays canonical. */
-function buildToolMap() {
+/** Tool map (object form) for the server hook; array catalog stays canonical.
+ *
+ * `hostRoot` is the host-reported project directory (host.location.directory).
+ * The tool context's own cwd is absent on some host builds — observed live:
+ * every dispatch fell back to process.cwd() (/home/john) and evidence escaped
+ * the project tree. Prefer toolContext.cwd, then hostRoot, then process.cwd().
+ */
+function buildToolMap(hostRoot = undefined) {
   return Object.fromEntries(
     TOOL_CATALOG.map((tool) => [
       tool.name,
@@ -607,7 +639,11 @@ function buildToolMap() {
         ...tool,
         options: { codemode: false },
         execute: async (args = {}, toolContext = undefined) =>
-          callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
+          callMcp(
+            tool.name,
+            normalizeArgs(tool.name, args),
+            toolContext?.cwd || hostRoot
+          ),
       },
     ])
   );
@@ -892,15 +928,25 @@ async function registerHostTools(host) {
   // cannot be intercepted the way Claude Code's hooks/hooks.json does.
   // Steering lives in command templates (epistemic search first); a host API
   // for pre-execution guards would close this for real.
+  //
+  // hostRoot: the host's project directory. toolContext.cwd is absent on
+  // some host builds (observed live: dispatches fell back to process.cwd()
+  // = /home/john and evidence escaped the project tree), so capture the
+  // host-reported directory here as the fallback.
+  const hostRoot = host?.location?.directory || undefined;
   const registration = await host.tool.transform((draft) => {
-    for (const [name, spec] of Object.entries(buildToolMap())) {
+    for (const [name, spec] of Object.entries(buildToolMap(hostRoot))) {
       draft.add({
         name,
         description: spec.description,
         input: spec.input,
         options: { codemode: false },
         execute: async (args = {}, toolContext = undefined) => {
-          const r = await callMcp(name, normalizeArgs(name, args), toolContext?.cwd);
+          const r = await callMcp(
+            name,
+            normalizeArgs(name, args),
+            toolContext?.cwd || hostRoot
+          );
           return { content: r.content };
         },
       });

package/runner/mcp_server.py

@@ -192,6 +192,87 @@ def _handle_darkharvest(args: Dict[str, Any]) -> str:
     return _run_swarm_mode("darkharvest", args)
 
 
+def _handle_factory(args: Dict[str, Any]) -> str:
+    """Drive factory run state (init / phase-add / qa-record / expansion / stop).
+
+    Wraps skills/factory/scripts/factory.py so agents never need a filesystem
+    path to the helper: the npm-installed toolchain lives outside the project,
+    and relative `skills/...` paths broke in consuming projects (observed
+    live: the manager agent ran `find / -name factory.py`).
+    """
+    import subprocess
+
+    command = str(args.get("command") or "").strip()
+    if command not in ("init", "phase-add", "qa-record", "expansion", "stop"):
+        raise ValueError(
+            "command must be one of: init, phase-add, qa-record, expansion, stop"
+        )
+    script = Path(PROJECT_ROOT) / "skills" / "factory" / "scripts" / "factory.py"
+    if not script.is_file():
+        raise FileNotFoundError(f"factory helper not found at {script}")
+
+    project = (
+        args.get("project_dir") or os.environ.get("IUMBTEMS_PROJECT_DIR") or os.getcwd()
+    )
+    cmd = [sys.executable, str(script), command, "--project-dir", str(project)]
+    if command == "init":
+        cmd += ["--run", str(args.get("run") or "")]
+    elif command == "phase-add":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--phase",
+            str(args.get("phase") or ""),
+            "--goal",
+            str(args.get("goal") or ""),
+            "--accept",
+            str(args.get("accept") or ""),
+        ]
+    elif command == "qa-record":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--phase",
+            str(args.get("phase") or ""),
+            "--seat",
+            str(args.get("seat") or ""),
+            "--verdict",
+            str(args.get("verdict") or ""),
+        ]
+        if args.get("reason"):
+            cmd += ["--reason", str(args["reason"])]
+    elif command == "expansion":
+        cmd += [
+            "--run",
+            str(args.get("run") or ""),
+            "--loops",
+            str(int(args.get("loops") or 1)),
+        ]
+        if args.get("max_loops"):
+            cmd += ["--max-loops", str(int(args["max_loops"]))]
+    elif command == "stop":
+        cmd += ["--run", str(args.get("run") or "")]
+
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        shell=False,
+        stdin=subprocess.DEVNULL,
+        cwd=str(project),
+    )
+    payload = {
+        "status": "ok" if proc.returncode == 0 else "error",
+        "command": command,
+        "returncode": proc.returncode,
+        "project_dir": str(project),
+        "output": (proc.stdout or proc.stderr or "").strip()[-4000:],
+    }
+    if proc.returncode == 2:
+        payload["status"] = "escalated"
+    return _tool_text(payload)
+
+
 def _handle_verify_quote(args: Dict[str, Any]) -> str:
     """Verify a verbatim quote against the content-addressed source cache."""
     from skills.research_cache.hasher import SourceHasher
@@ -541,6 +622,46 @@ def build_tools() -> List[ToolSpec]:
             },
             handler=_handle_darkharvest,
         ),
+        ToolSpec(
+            name="iumbtems_factory",
+            description="Drive factory run state: init / phase-add / qa-record / expansion / stop. State goes to <project>/.factory and <project>/.roadmap; no filesystem path to helper scripts required.",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "enum": ["init", "phase-add", "qa-record", "expansion", "stop"],
+                    },
+                    "run": {"type": "string", "description": "Factory run name"},
+                    "phase": {
+                        "type": "string",
+                        "description": "Phase id (e.g. 01-auth)",
+                    },
+                    "goal": {"type": "string"},
+                    "accept": {
+                        "type": "string",
+                        "description": "Semicolon-separated acceptance criteria",
+                    },
+                    "seat": {"type": "string", "description": "QA seat (qa-a | qa-b)"},
+                    "verdict": {
+                        "type": "string",
+                        "enum": ["pass", "fail", "conditional"],
+                    },
+                    "reason": {"type": "string"},
+                    "loops": {
+                        "type": "integer",
+                        "description": "Expansion loop count (1-10)",
+                    },
+                    "max_loops": {"type": "integer"},
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project root (default: IUMBTEMS_PROJECT_DIR or cwd)",
+                    },
+                },
+                "required": ["command"],
+            },
+            handler=_handle_factory,
+        ),
         ToolSpec(
             name="iumbtems_verify_quote",
             description="Audit a verbatim citation against the SHA-256 source cache (.research/sources/<hash>.md).",

package/runner/research_swarm.py

@@ -43,17 +43,6 @@ OPENCODE_RUN_BASE = ["opencode", "run"]
 # Fenced JSON block marker shared by orchestrator/dossier stdout parsers.
 _JSON_FENCE = "```json"
 
-# Swarm mode -> OpenCode agent carrying the equivalent system prompt
-# (`opencode run` has no --system-prompt flag; the prompt rides on --agent).
-MODE_OPENCODE_AGENT = {
-    "research": "alpha-thesis",
-    "audit": "code-auditor",
-    "scout": "oss-scout",
-    "hybrid": "alpha-thesis",
-    "brainstorm": "brainstormer",
-    "darkharvest": "darkharvester",
-}
-
 
 def _default_backend_cmd(config_host: Optional[str] = None) -> List[str]:
     """Host-native default backend argv.
@@ -99,7 +88,17 @@ _TEXT_EVENT_MARKERS = ("message", "text", "result", "output", "content")
 
 
 def _event_text(obj: Dict[str, Any]) -> Optional[str]:
-    """Text payload of one parsed event line, or None."""
+    """Text payload of one parsed event line, or None.
+
+    Handles the real `opencode run --format json` shape
+    ({"type":"text", "part":{"type":"text","text":"..."}}) plus top-level
+    variants for tolerance.
+    """
+    part = obj.get("part")
+    if isinstance(part, dict):
+        val = part.get("text")
+        if isinstance(val, str) and val.strip():
+            return val
     kind = str(obj.get("type", "")).lower()
     if kind and not any(m in kind for m in _TEXT_EVENT_MARKERS):
         return None
@@ -237,14 +236,16 @@ class SwarmRunner:
         return list(backend), model
 
     def _resolve_opencode_agent(self, role: str) -> Optional[str]:
-        """OpenCode agent carrying the system prompt for this mode/role."""
-        agents_cfg = self.config.get("agents") or {}
-        role_cfg = agents_cfg.get(role) or {}
-        if role_cfg.get("opencode_agent"):
-            return role_cfg["opencode_agent"]
-        if self.mode == "research" and role == "beta":
-            return "beta-redteam"
-        return MODE_OPENCODE_AGENT.get(self.mode)
+        """Explicitly configured OpenCode agent for this role, else None.
+
+        Default is None: the system prompt is inlined into the message because
+        `--agent <name>` fails hard ("Agent not found") unless the user
+        installed the snippet agent profiles — observed live, so the backend
+        must not depend on them. Set `agents.<role>.opencode_agent` (or the
+        top-level `opencode_agent` config key) to opt in.
+        """
+        role_cfg = (self.config.get("agents") or {}).get(role) or {}
+        return role_cfg.get("opencode_agent") or self.config.get("opencode_agent")
 
     def build_agent_cmd(
         self,
@@ -270,9 +271,16 @@ class SwarmRunner:
                 "backend (CLI flag injection)"
             )
         if _backend_family(backend) == "opencode":
-            return _build_opencode_cmd(
-                backend, prompt, model, self._resolve_opencode_agent(role)
-            )
+            agent = self._resolve_opencode_agent(role)
+            # No --system-prompt flag exists on `opencode run`, and --agent
+            # only works when the user installed the profile. Inline the
+            # system prompt into the message so runs never depend on
+            # host-side agent configuration.
+            if system_prompt_file and system_prompt_file.exists():
+                prompt = (
+                    system_prompt_file.read_text(encoding="utf-8") + "\n\n" + prompt
+                )
+            return _build_opencode_cmd(backend, prompt, model, agent)
         cmd = list(backend) + [prompt, "--tools", tools]
         if model:
             cmd.extend(["--model", str(model)])
@@ -303,6 +311,11 @@ class SwarmRunner:
                 text=True,
                 check=True,
                 cwd=str(PROJECT_ROOT),
+                # stdin MUST be DEVNULL: `opencode run` reads piped stdin to
+                # EOF before starting, and the MCP server's inherited stdin
+                # pipe is held open by the harness — every agent hung forever
+                # (observed live: 10+ min, 1s CPU, no network I/O).
+                stdin=subprocess.DEVNULL,
                 shell=False,
             )
             if family == "opencode":

package/runner/tests/test_backends.py

@@ -103,13 +103,29 @@ class TestRunnerBackendWiring(unittest.TestCase):
             r = self._runner(mode="scout")
             cmd = r.build_agent_cmd("obj")
             self.assertEqual(cmd[:2], ["opencode", "run"])
-            self.assertIn("oss-scout", cmd)
+            # No --agent by default: named agents fail hard unless the user
+            # installed the profile ("Agent not found", observed live).
+            self.assertNotIn("--agent", cmd)
+            self.assertIn("--format", cmd)
+
+    def test_explicit_opencode_agent_config_opt_in(self):
+        with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
+            r = self._runner(agent_overrides=None)
+            r.config["opencode_agent"] = "brainstormer"
+            cmd = r.build_agent_cmd("obj")
+            self.assertIn("--agent", cmd)
+            self.assertIn("brainstormer", cmd)
+
+    def test_system_prompt_inlined_for_opencode(self):
+        import tempfile as _tf
 
-    def test_research_beta_maps_to_beta_redteam(self):
         with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
             r = self._runner(mode="research")
-            self.assertIn("beta-redteam", r.build_agent_cmd("obj", role="beta"))
-            self.assertIn("alpha-thesis", r.build_agent_cmd("obj", role="alpha"))
+            spf = Path(_tf.mkdtemp()) / "sys.md"
+            spf.write_text("SYSTEM PROMPT BODY", encoding="utf-8")
+            cmd = r.build_agent_cmd("obj", system_prompt_file=spf)
+            self.assertIn("SYSTEM PROMPT BODY", cmd[2])
+            self.assertNotIn("--system-prompt", cmd)
 
     def test_explicit_override_beats_host_env(self):
         with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
@@ -119,6 +135,17 @@ class TestRunnerBackendWiring(unittest.TestCase):
 
 
 class TestOpencodeOutputParsing(unittest.TestCase):
+    def test_extracts_real_part_text_events(self):
+        """Live shape: {"type":"text","part":{"type":"text","text":"..."}}."""
+        raw = "\n".join(
+            [
+                '{"type":"step_start","timestamp":1,"sessionID":"s","part":{"type":"step-start"}}',
+                '{"type":"text","timestamp":2,"sessionID":"s","part":{"id":"p1","type":"text","text":"pong"}}',
+                '{"type":"text","timestamp":3,"sessionID":"s","part":{"id":"p2","type":"text","text":"second"}}',
+            ]
+        )
+        self.assertEqual(_extract_opencode_text(raw), "pong\nsecond")
+
     def test_extracts_text_events(self):
         raw = "\n".join(
             [
@@ -139,6 +166,24 @@ class TestOpencodeOutputParsing(unittest.TestCase):
         self.assertEqual(_extract_opencode_text(raw), "verdict: clean-room")
 
 
+class TestSpawnHardening(unittest.TestCase):
+    def test_stdin_is_devnull_for_backend_spawns(self):
+        """Regression: held-open stdin pipe made `opencode run` hang forever."""
+        import tempfile
+        from runner.research_swarm import SwarmRunner
+
+        r = SwarmRunner(
+            base_dir=Path(tempfile.mkdtemp()), mock_mode=False, mode="research"
+        )
+        fake = mock.Mock()
+        fake.stdout = "ok"
+        with mock.patch("subprocess.run", return_value=fake) as run_mock:
+            r.run_claude_process("objective text")
+        kwargs = run_mock.call_args.kwargs
+        self.assertEqual(kwargs.get("stdin"), subprocess.DEVNULL)
+        self.assertEqual(kwargs.get("shell"), False)
+
+
 class TestDossierStdoutFallback(unittest.TestCase):
     def _runner(self):
         import tempfile

package/runner/tests/test_factory.py

@@ -2,6 +2,7 @@
 """Tests for the factory loop: run-state helper, QA retry bounds, plugin surface."""
 
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -164,6 +165,52 @@ class TestFactoryHelper(unittest.TestCase):
         self.assertIn("./skills/factory", pkg["pi"]["skills"])
         self.assertIn("./skills/factory", pkg["omp"]["skills"])
 
+    def test_project_dir_env_resolution(self):
+        """Factory state must land in the target project, never the checkout."""
+        with tempfile.TemporaryDirectory() as tmp:
+            env = dict(os.environ, IUMBTEMS_PROJECT_DIR=tmp)
+            r = subprocess.run(
+                [
+                    sys.executable,
+                    "skills/factory/scripts/factory.py",
+                    "init",
+                    "--run",
+                    "env-run",
+                ],
+                capture_output=True,
+                text=True,
+                cwd=str(PROJECT_ROOT),
+                env=env,
+            )
+            self.assertEqual(r.returncode, 0, r.stderr)
+            self.assertTrue(
+                (Path(tmp) / ".factory" / "env-run" / "state.json").exists()
+            )
+
+    def test_mcp_factory_tool_project_dir(self):
+        """iumbtems_factory drives state in the given project (no script path)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            r = subprocess.run(
+                [
+                    sys.executable,
+                    "runner/mcp_server.py",
+                    "call",
+                    "iumbtems_factory",
+                    json.dumps(
+                        {"command": "init", "run": "mcp-run", "project_dir": tmp}
+                    ),
+                ],
+                capture_output=True,
+                text=True,
+                cwd=str(PROJECT_ROOT),
+            )
+            self.assertEqual(r.returncode, 0, r.stderr)
+            payload = json.loads(r.stdout)
+            self.assertEqual(payload["status"], "ok")
+            self.assertTrue(
+                (Path(tmp) / ".factory" / "mcp-run" / "state.json").exists()
+            )
+
     def test_snippet_factory_roster(self):
         with open(PROJECT_ROOT / "config" / "opencode-snippet.json") as f:
             snippet = json.load(f)

package/runner/tests/test_mcp_server.py

@@ -28,6 +28,7 @@ EXPECTED_TOOLS = [
     "iumbtems_oss_scout",
     "iumbtems_brainstorm",
     "iumbtems_darkharvest",
+    "iumbtems_factory",
     "iumbtems_verify_quote",
     "iumbtems_socratic_frontier",
     "iumbtems_reindex_claims",

package/runner/tests/test_opencode_ux.py

@@ -214,7 +214,7 @@ class TestOpenCodeCommandCatalog(unittest.TestCase):
         self.assertEqual(res.returncode, 0, f"tool map test failed: {res.stderr}")
         data = last_json_object(res.stdout)
         self.assertEqual(sorted(data["keys"]), sorted(data["canonical"]))
-        self.assertEqual(len(data["keys"]), 14)
+        self.assertEqual(len(data["keys"]), 15)
         self.assertTrue(all(data["ok"]))
 
 
@@ -618,7 +618,7 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
             self.assertIn(c, data["commands"])
         self.assertNotIn("goal", data["commands"])
         self.assertEqual(data["cmdExec"], "function")
-        self.assertEqual(len(data["tools"]), 14)
+        self.assertEqual(len(data["tools"]), 15)
         self.assertIn("iumbtems_brainstorm", data["tools"])
         self.assertIn("iumbtems_darkharvest", data["tools"])
         self.assertEqual(data["toolExec"], "function")

package/runner/tests/test_swarm.py

@@ -381,6 +381,7 @@ In our experiments, the 70B parameter model was trained on 15.0 trillion tokens.
             "iumbtems_oss_scout",
             "iumbtems_brainstorm",
             "iumbtems_darkharvest",
+            "iumbtems_factory",
             "iumbtems_verify_quote",
             "iumbtems_socratic_frontier",
             "iumbtems_reindex_claims",

package/skills/factory/SKILL.md

@@ -13,6 +13,16 @@ description: Coding-factory Manager loop. Use when user invokes /factory or /dom
 - **qa-a / qa-b** (subagents): same model, DIVERGED prompts (functional-correctness vs adversarial edge-case). Read-only plus test execution; never edit.
 - **researcher** = existing `iumbtems_brainstorm` + `iumbtems_darkharvest` swarms (no new profile).
 
+## 1b. Driving run state (no filesystem paths)
+
+Use the **`iumbtems_factory` MCP tool** for all run-state changes — never a
+relative `skills/factory/scripts/factory.py` path (the toolchain lives in the
+npm cache in consuming projects, and relative paths broke live: the manager
+agent ran `find / -name factory.py`). The tool wraps the same helper and
+resolves the project via `project_dir` argument, `IUMBTEMS_PROJECT_DIR`, or
+the session cwd. It supports `init`, `phase-add`, `qa-record`, `expansion`,
+`stop`, and returns `status: escalated` (exit 2) on the 3rd QA failure.
+
 ## 2. Gate protocol (max 5 swarm cycles per gate)
 
 1. Grill until `.factory/frontier.json` settled (grilling skill).

package/skills/factory/scripts/factory.py

@@ -2,8 +2,13 @@
 """
 Factory run-state helper: phase dossiers, QA retry bounds, expansion loop guard.
 
-All state lives under .factory/ (gitignored runtime state). Phase output goes
-to .roadmap/<phase>/. Evidence stays in .research/. Read-only w.r.t. repo code.
+All state lives under <project>/.factory/ (gitignored runtime state). Phase
+output goes to <project>/.roadmap/<phase>/. Evidence stays in <project>/
+.research/. Read-only w.r.t. repo code.
+
+Project directory resolution: --project-dir > IUMBTEMS_PROJECT_DIR env > the
+toolchain repo root (local-dev default). A consuming project must never leak
+state into the IUMBTEMS checkout.
 
 Usage:
   python3 skills/factory/scripts/factory.py init --run <name>
@@ -15,13 +20,25 @@ Usage:
 
 import argparse
 import json
+import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
-FACTORY_DIR = PROJECT_ROOT / ".factory"
-ROADMAP_DIR = PROJECT_ROOT / ".roadmap"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+
+def resolve_project_root(cli_value=None):
+    """--project-dir > IUMBTEMS_PROJECT_DIR > repo root (local-dev default)."""
+    for candidate in (cli_value, os.environ.get("IUMBTEMS_PROJECT_DIR")):
+        if candidate and Path(candidate).is_dir():
+            return Path(candidate).resolve()
+    return REPO_ROOT
+
+
+PROJECT_DIR = resolve_project_root()
+FACTORY_DIR = PROJECT_DIR / ".factory"
+ROADMAP_DIR = PROJECT_DIR / ".roadmap"
 
 MAX_QA_RETRIES = 3
 MAX_EXPANSION_LOOPS = 10
@@ -173,31 +190,48 @@ def cmd_stop(args):
     print(f"🛑 STOP file written for run '{args.run}'.")
 
 
+def _add_common(parser):
+    parser.add_argument(
+        "--project-dir",
+        default=None,
+        help="Project the factory state belongs to (default: IUMBTEMS_PROJECT_DIR env, else repo root)",
+    )
+
+
 def main():
+    global FACTORY_DIR, ROADMAP_DIR
     ap = argparse.ArgumentParser(description="Factory run-state helper")
     sub = ap.add_subparsers(dest="command", required=True)
 
     p = sub.add_parser("init")
     p.add_argument("--run", required=True)
+    _add_common(p)
     p = sub.add_parser("phase-add")
     p.add_argument("--run", required=True)
     p.add_argument("--phase", required=True)
     p.add_argument("--goal", required=True)
     p.add_argument("--accept", default="")
+    _add_common(p)
     p = sub.add_parser("qa-record")
     p.add_argument("--run", required=True)
     p.add_argument("--phase", required=True)
     p.add_argument("--seat", required=True)
     p.add_argument("--verdict", required=True)
     p.add_argument("--reason", default="")
+    _add_common(p)
     p = sub.add_parser("expansion")
     p.add_argument("--run", required=True)
     p.add_argument("--loops", type=int, required=True)
     p.add_argument("--max-loops", type=int, default=MAX_EXPANSION_LOOPS)
+    _add_common(p)
     p = sub.add_parser("stop")
     p.add_argument("--run", required=True)
+    _add_common(p)
 
     args = ap.parse_args()
+    root = resolve_project_root(args.project_dir)
+    FACTORY_DIR = root / ".factory"
+    ROADMAP_DIR = root / ".roadmap"
     code = {
         "init": cmd_init,
         "phase-add": cmd_phase_add,