monomind 2.1.3 → 2.1.4

package/packages/@monomind/cli/.claude/skills/mastermind-skills/org-settings.md

@@ -1,6 +1,6 @@
 ---
 name: mastermind-org-settings
-description: Mastermind org-settings — edit org configuration (name, goal, topology, governance, budget), export org as portable JSON, and import an org from a previously exported file.
+description: Mastermind org-settings — edit Org Runtime v2 configuration (name, goal, schedule, budget_tokens, memory_namespace, max_turns_per_message), export org as portable JSON, and import an org from a previously exported file.
 type: domain-skill
 default_mode: confirm
 ---
@@ -9,6 +9,8 @@ default_mode: confirm
 
 This skill is invoked by `mastermind:org-settings` or directly via `/mastermind:org-settings`.
 
+It edits `.monomind/orgs/<org_name>.json` in place, and only ever touches fields that `OrgDefSchema` (`packages/@monomind/cli/src/orgrt/types.ts`) actually defines — every field listed below is read by the daemon (`org.ts`/`daemon.ts`/`session.ts`) at `monomind org run`/`serve` time. There is no `topology`, `governance`, `alert_threshold`, or `ceo_adapter` in Org Runtime v2 — those were v1 board/prompt-orchestration fields with no runtime effect and have been removed from this skill.
+
 ---
 
 ## Inputs
@@ -16,7 +18,7 @@ This skill is invoked by `mastermind:org-settings` or directly via `/mastermind:
 - `brain_context`: BRAIN CONTEXT block (injected by command, or loaded below if standalone)
 - `org_name`: org to configure (required)
 - `action`: show | edit | export | import
-- `field`: field to edit (name, goal, topology, governance, budget_tokens, alert_threshold, ceo_adapter)
+- `field`: field to edit (name, goal, schedule, budget_tokens, memory_namespace, max_turns_per_message)
 - `value`: new value for the field
 - `export_path`: path to write exported JSON (default: `.monomind/exports/<org_name>-<timestamp>.json`)
 - `import_path`: path to JSON file to import from
@@ -49,19 +51,18 @@ Display current org config in a readable format:
 echo "ORG SETTINGS — ${org_name}"
 echo "──────────────────────────────────────────"
 jq -r '
-  "  Name:         \(.name // .org_name // "-")",
-  "  Goal:         \(.goal // "-")",
-  "  Topology:     \(.topology // "hierarchical")",
-  "  Max Agents:   \(.max_agents // 8)",
-  "  Governance:   \(.governance.policy // "auto")",
-  "  Budget:       \(.run_config.budget_tokens // 0) tokens",
-  "  Alert at:     \((.run_config.alert_threshold // 0.8) * 100 | floor)%",
-  "  CEO Adapter:  \(.run_config.ceo_adapter // "claude-sonnet-4-6")",
-  "  Roles:        \(.roles | length) agents"
+  "  Name:              \(.name // "-")",
+  "  Goal:              \(.goal // "-")",
+  "  Status:            \(.status // "stopped")",
+  "  Schedule:          \(.schedule // "manual (no auto-schedule)")",
+  "  Budget:            \(.run_config.budget_tokens // 1000000) tokens",
+  "  Memory namespace:  \(.run_config.memory_namespace // ("org:" + (.name // "-")))",
+  "  Max turns/message: \(.run_config.max_turns_per_message // 30)",
+  "  Roles:             \(.roles | length) agents"
 ' "$orgFile"
 echo ""
 echo "  Run /mastermind:org-settings --org ${org_name} --action edit --field <field> --value <value>"
-echo "  Fields: name | goal | topology | governance | budget_tokens | alert_threshold | ceo_adapter"
+echo "  Fields: name | goal | schedule | budget_tokens | memory_namespace | max_turns_per_message"
 ```
 
 ### edit
@@ -79,23 +80,30 @@ case "$field" in
     echo "$value" | grep -qE '^[a-z0-9][a-z0-9-]{0,63}$' || { echo "ERROR: name must match ^[a-z0-9][a-z0-9-]{0,63}$"; exit 1; }
     newOrgFile=".monomind/orgs/${value}.json"
     [ -f "$newOrgFile" ] && { echo "ERROR: An org named '${value}' already exists."; exit 1; }
+    # Refuse to rename while the daemon has this org running — it holds the old
+    # name's paths (defPath, cwd, runtime.json) in memory; a rename mid-run would
+    # orphan that live state instead of moving it.
+    runtime_status=$(jq -r '.status // "stopped"' ".monomind/orgs/${org_name}/runtime.json" 2>/dev/null || echo "stopped")
+    [ "$runtime_status" = "running" ] && { echo "ERROR: org '${org_name}' is running — stop it first: monomind org stop ${org_name}"; exit 1; }
     # Update the name field inside the JSON
     jq --arg v "$value" '.name = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
     # Rename the main config file
     mv "$orgFile" "$newOrgFile"
-    # Rename all side-car data files
-    for suffix in -state -goals -routines -approvals -activity -issues -members -projects -workspaces -worktrees -environments -plugins -adapters -threads -budgets -project-workspaces -approval-comments -bootstrap -secrets; do
+    # Rename all side-car artifact files — same suffix list as ORG_ARTIFACT_SUFFIXES
+    # in packages/@monomind/cli/src/commands/org.ts (single source of truth for what
+    # counts as an org-internal artifact vs. the org's own config file).
+    for suffix in -state -goals -threads -activity -approvals -members -secrets -budgets \
+                  -routines -issues -projects -workspaces -worktrees -environments \
+                  -plugins -adapters -join-requests -bootstrap -project-workspaces \
+                  -approval-comments -skills; do
       old_file=".monomind/orgs/${org_name}${suffix}.json"
       [ -f "$old_file" ] && mv "$old_file" ".monomind/orgs/${value}${suffix}.json" || true
       old_jsonl=".monomind/orgs/${org_name}${suffix}.jsonl"
       [ -f "$old_jsonl" ] && mv "$old_jsonl" ".monomind/orgs/${value}${suffix}.jsonl" || true
     done
-    # Rename loop prompt file if present (scheduled orgs)
-    old_loop=".monomind/loops/${org_name}.md"
-    [ -f "$old_loop" ] && mv "$old_loop" ".monomind/loops/${value}.md" || true
-    # Rename stop file if present
-    old_stop=".monomind/orgs/.stops/${org_name}.stop"
-    [ -f "$old_stop" ] && mv "$old_stop" ".monomind/orgs/.stops/${value}.stop" || true
+    # Rename the org's runtime subdirectory (runs/, workspace/, stop file) if present
+    old_dir=".monomind/orgs/${org_name}"
+    [ -d "$old_dir" ] && mv "$old_dir" ".monomind/orgs/${value}" || true
     echo "Renamed org '${org_name}' → '${value}'"
     org_name="$value"
     orgFile="$newOrgFile"
@@ -104,42 +112,33 @@ case "$field" in
     jq --arg v "$value" '.goal = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
     echo "Updated: goal → $value"
     ;;
-  topology)
-    case "$value" in hierarchical|mesh|hierarchical-mesh|adaptive|star|ring) : ;; *)
-      echo "ERROR: topology must be one of: hierarchical, mesh, hierarchical-mesh, adaptive, star, ring"; exit 1 ;;
-    esac
-    jq --arg v "$value" '.topology = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
-    echo "Updated: topology → $value"
-    ;;
-  governance)
-    case "$value" in auto|board|strict) : ;; *)
-      echo "ERROR: governance must be one of: auto, board, strict"; exit 1 ;;
-    esac
-    jq --arg v "$value" '.governance.policy = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
-    echo "Updated: governance → $value"
+  schedule)
+    # daemon format (parseSchedule in orgrt/scheduler.ts): "<N>s" | "<N>m" | "<N>h", or "none"/"" to clear
+    if [ "$value" = "none" ] || [ -z "$value" ]; then
+      jq '.schedule = null' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+      echo "Updated: schedule → none (manual — run with monomind org run ${org_name})"
+    else
+      echo "$value" | grep -qE '^[0-9]+(s|m|h)$' || { echo "ERROR: schedule must match ^[0-9]+(s|m|h)$ (e.g. 30m, 2h) or 'none'"; exit 1; }
+      jq --arg v "$value" '.schedule = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+      echo "Updated: schedule → $value (pick up with: monomind org serve)"
+    fi
     ;;
   budget_tokens)
     [[ "$value" =~ ^[0-9]+$ ]] || { echo "ERROR: budget_tokens must be a positive integer"; exit 1; }
     jq --argjson v "$value" '.run_config.budget_tokens = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
     echo "Updated: budget_tokens → $value"
     ;;
-  alert_threshold)
-    # accept 0.0–1.0 or 0–100
-    if [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -gt 1 ]; then
-      value=$(awk "BEGIN{printf \"%.2f\",$value/100}")
-    fi
-    jq --argjson v "$value" '.run_config.alert_threshold = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
-    echo "Updated: alert_threshold → $value"
+  memory_namespace)
+    jq --arg v "$value" '.run_config.memory_namespace = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+    echo "Updated: memory_namespace → $value"
     ;;
-  ceo_adapter)
-    case "$value" in claude-sonnet-4-6|claude-opus-4-7|claude-haiku-4-5) : ;; *)
-      echo "ERROR: ceo_adapter must be one of: claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5"; exit 1 ;;
-    esac
-    jq --arg v "$value" '.run_config.ceo_adapter = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
-    echo "Updated: ceo_adapter → $value"
+  max_turns_per_message)
+    [[ "$value" =~ ^[0-9]+$ ]] || { echo "ERROR: max_turns_per_message must be a positive integer"; exit 1; }
+    jq --argjson v "$value" '.run_config.max_turns_per_message = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+    echo "Updated: max_turns_per_message → $value"
     ;;
   *)
-    echo "ERROR: Unknown field '$field'. Valid fields: name, goal, topology, governance, budget_tokens, alert_threshold, ceo_adapter"
+    echo "ERROR: Unknown field '$field'. Valid fields: name, goal, schedule, budget_tokens, memory_namespace, max_turns_per_message"
     exit 1
     ;;
 esac

package/packages/@monomind/cli/.claude/skills/mastermind-skills/runorg.md

@@ -1,12 +1,15 @@
 ---
 name: mastermind-runorg
-description: Mastermind runorg — load a saved org definition and start it as a persistent autonomous agent organization. The boss agent coordinates all roles, agents pick up tasks from a shared board, and the org runs until stopped.
+description: "DEPRECATED (2026-07): superseded by `monomind org run <name>` (SDK Org Runtime v2). Mastermind runorg — load a saved org definition and start it as a persistent, prompt-orchestrated agent organization. The boss agent coordinates all roles, agents pick up tasks from a shared board, and the org runs until stopped."
 type: domain-skill
 default_mode: auto
 ---
 
 # Mastermind Run Org
 
+> **DEPRECATED (2026-07): superseded by `monomind org run <name>` (SDK Org Runtime v2).**
+> This prompt-orchestrated path (Task-tool-spawned boss, monotask board, `ORG_VARS`/`runcontext.json`-style variable threading, manual dashboard-event curl calls) has no delivery guarantees and no ground-truth event stream — the v2 daemon spawns every role as its own live SDK session, routes messages directly via the `org_send` tool, and forwards dashboard events itself. It remains only for orgs not yet migrated off the v1 `topology`/`communication`/`board_id` config shape. New orgs created with `/mastermind:createorg` are already v2-shaped and MUST be started with `monomind org run <name>` — do not route them through this skill.
+
 This skill is invoked by `mastermind:runorg` or directly via `/mastermind:runorg`.
 
 ---
@@ -40,6 +43,14 @@ fi
 ```
 Return `status: blocked` with message: "Org '<org_name>' not found. Run /mastermind:createorg to define it."
 
+**v2 config guard — check this before anything else.** `/mastermind:createorg` now writes v2-shaped configs with no `topology`/`board_id`/`communication` field at all:
+```bash
+is_v2=$(jq -r 'if has("topology") or has("board_id") then "no" else "yes" end' ".monomind/orgs/${org_name}.json")
+```
+If `is_v2 == "yes"`, **stop and return `status: blocked`** with message: "Org '<org_name>' is a v2 config (Org Runtime v2) — this skill only understands the deprecated v1 board/topology shape. Start it with: `monomind org run <org_name>` (or `monomind org serve` if it has a `schedule`)." Do not attempt to derive a topology, spawn a boss via Task tool, or touch a monotask board for a v2 config — every field this skill reads from Step 2 onward (`topology`, `board_id`, `todo_col_id`, `communication`) is simply absent there.
+
+Only proceed past this guard for a genuine legacy v1 config (has `topology` and/or `board_id`).
+
 Validate the config has at minimum: `name`, `goal`, `roles` (non-empty array). The `communication` field is optional; fall back to `edges` if absent (both have the same schema: `from`, `to`, `type`).
 
 ---

package/packages/@monomind/cli/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.png" alt="Monomind" width="600" />
+  <img src="https://raw.githubusercontent.com/monoes/monomind/main/assets/banner.png" alt="Monomind" width="600" />
 </p>
 
 <h1 align="center">Monomind</h1>
@@ -38,9 +38,9 @@ Monomind is an **open-source CLI and MCP server** that plugs into Claude Code vi
 - **Reusable slash commands** — 30+ development workflows (build, review, debug, TDD, architecture) available as `/mastermind:*` commands inside Claude Code.
 
 ```bash
-npm install -g monomind        # MIT licensed, 0 external API calls
+npm install -g monomind        # MIT licensed, runs entirely on your machine
 cd your-project && monomind init
-claude mcp add monomind npx monomind mcp start
+claude mcp add monomind -- npx -y monomind@latest mcp start
 ```
 
 ### Trust & Security
@@ -48,8 +48,8 @@ claude mcp add monomind npx monomind mcp start
 | Concern | Answer |
 |---|---|
 | **License** | [MIT](LICENSE) — use it however you want |
-| **Data privacy** | Everything runs locally. No telemetry, no phone-home, no external API calls from Monomind itself. Your code stays on your machine. |
-| **Dependencies** | Standard npm packages (tree-sitter, sql.js, zod). No native binaries. No post-install scripts that download code. |
+| **Data privacy** | Everything runs locally — your code and memory store never leave your machine. The one exception: crash reporting is on by default (`monomind crash-reporting disable` to opt out) — a hard crash in monomind/mono-agent/monotask/mono-clip files a GitHub issue on that tool's own repo via the GitHub API. That's the only network call Monomind itself makes; it never phones a monoes-controlled server. |
+| **Dependencies** | Standard npm packages (tree-sitter, better-sqlite3, sql.js, zod). tree-sitter and better-sqlite3 are native (prebuilt) Node addons, not pure JS/WASM — sql.js is WASM. No post-install scripts that download code. |
 | **Permissions** | Registers as an MCP server — Claude Code controls what tools are available and prompts you before executing anything sensitive. |
 | **Source** | Fully open. Read every line at [github.com/monoes/monomind](https://github.com/monoes/monomind). |
 | **Maintenance** | Active development, regular releases on npm. |
@@ -62,7 +62,7 @@ claude mcp add monomind npx monomind mcp start
 
 ### The idea
 
-Every business function needs a team. Define the org once as a JSON file — goal, roles, who reports to whom, per-role tool/file/budget policy — then run it as a real background daemon backed by the Claude Agent SDK. It persists across sessions, serves a live WebSocket dashboard, and can discover and message other Monomind orgs running on the same machine.
+Every business function needs a team. Define the org once as a JSON file — goal, roles, who reports to whom, per-role tool/file/budget policy — then run it as a real background daemon backed by the Claude Agent SDK. It persists across sessions, streams live into the dashboard Claude Code auto-starts for the project, and can discover and message other Monomind orgs running on the same machine.
 
 ```mermaid
 flowchart TD
@@ -73,14 +73,14 @@ flowchart TD
     W["Writer"]
     S["SEO Specialist"]
     R["Reviewer"]
-    DASH[("Live Dashboard\n:4243")]
+    DASH[("Dashboard\n:4242\nauto-started by\nClaude Code hook")]
     XORG[("Other orgs\ncross-process")]
 
     U --> DEF --> RUN --> BOSS
     BOSS -->|spawns| W
     BOSS -->|spawns| S
     BOSS -->|spawns| R
-    RUN <-->|serves| DASH
+    RUN -->|forwards events| DASH
     RUN <-.->|--cross-process| XORG
 
     style BOSS fill:#00D2AA22,stroke:#00D2AA
@@ -93,13 +93,14 @@ flowchart TD
 ```bash
 # .monomind/orgs/<name>.json defines the org: goal, roles, policy.
 # See .monomind/orgs/sample-team.json in a fresh `monomind init` for a working example.
+# Open the project in Claude Code first — a SessionStart hook auto-launches
+# the dashboard at http://localhost:4242 if it isn't already running.
 
 monomind org run content-team --task "Build and publish 3 blog posts per week"
 
-# ✓ Live dashboard: http://localhost:4243
 # ✓ Boss agent (Claude Agent SDK session) spawns, reads the org goal,
 #   assigns work to role agents, coordinates until the task completes
-#   or you stop it.
+#   or you stop it. Every event streams into the dashboard above.
 
 monomind org status content-team    # runtime state
 monomind org stop content-team      # request a graceful stop
@@ -112,18 +113,18 @@ monomind org list                   # every org + status
 |---|---|
 | **OrgDaemon** | Hosts one or more orgs in a single process; real Claude Agent SDK sessions per role, not simulated |
 | **PolicyEngine** | Per-role gates on tool access, file read/write scope, web access, token budget — enforced, with a full audit trail |
-| **Live dashboard** | WebSocket-served at `:4243` by default (`--port` to change, `--serve=false` to disable) |
+| **Dashboard** | `org run` forwards every event to the control server on `:4242` (found via `.monomind/control.json`) — that server is auto-launched by a Claude Code SessionStart hook, not by any CLI command; there's no separate per-org dashboard process |
 | **Cross-process comms** | `--cross-process` (default on) lets orgs on different `monomind` processes/projects discover and message each other |
 | **Scheduling** | `monomind org serve` hosts orgs whose definition has a `schedule` field, running them on interval |
 
 ### Org management commands
 
 ```bash
-monomind org run <name> [--task "..."] [--port N] [--cross-process]  # start a daemon
+monomind org run <name> [--task "..."] [--cross-process]  # start a daemon
 monomind org stop <name>            # request a running org to stop
 monomind org status [name]          # runtime state for one or all orgs
 monomind org list                   # list every org + status
-monomind org serve [--port N]       # host-only mode, runs scheduled orgs
+monomind org serve [--cross-process]  # host-only mode, runs scheduled orgs
 monomind org delete <name>          # remove an org
 ```
 
@@ -179,13 +180,13 @@ cd your-project
 monomind init
 
 # 3. Wire into Claude Code as an MCP server
-claude mcp add monomind npx monomind mcp start
+claude mcp add monomind -- npx -y monomind@latest mcp start
 
 # 4. Health check
 monomind doctor --fix
 ```
 
-Open Claude Code. You now have 60+ slash commands available:
+Open Claude Code. You now have 49 `/mastermind:*` workflows available:
 
 ```bash
 /mastermind:autodev --tillend     # start autonomous code loop
@@ -275,7 +276,7 @@ const result = await fence.detect(userInput);
 
 ---
 
-## 📋 60+ Slash Commands
+## 📋 49 Mastermind Commands
 
 Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
 
@@ -308,7 +309,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 | `/mastermind:finance` | Budgets, invoicing, modeling |
 | `/mastermind:ops` | Operations and workflow automation |
 
-**[→ Full reference (60+ commands)](https://monoes.github.io/monomind/#slash)**
+**[→ Full reference (49 commands)](https://monoes.github.io/monomind/#slash)**
 
 ---
 

package/packages/@monomind/cli/dist/src/orgrt/daemon.d.ts

@@ -76,6 +76,24 @@ export declare class OrgDaemon {
         error: string;
     };
     private hasOrgDef;
+    private questionsPath;
+    private readQuestions;
+    private writeQuestions;
+    /** Agent-initiated human question (ask_human tool). Persists to questions.json (survives
+     *  process/dashboard restarts) and emits a 'question' BusEvent so the dashboard's SSE
+     *  stream and global inbox pick it up in real time. Returns a receipt string for the tool call. */
+    askHuman(org: string, role: string, question: string): Promise<string>;
+    /** Delivers a human's answer to a pending ask_human question. If the org is still
+     *  running, pushes straight into the role's live mailbox (picked up on its very next
+     *  generator tick — see Mailbox.stream()). If the org has since stopped, queues the
+     *  answer via the same offline fallback deliver()/receiveRemote() already use
+     *  (inbox.ts + autoWake) and it's delivered when the org next starts. */
+    answerQuestion(org: string, role: string, questionId: string, answer: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
     /** Start an offline org in the background so queued messages get drained.
      *  Fire-and-forget — errors are logged but don't propagate to the sender. */
     private autoWake;

package/packages/@monomind/cli/dist/src/orgrt/daemon.js

@@ -1,6 +1,6 @@
 // packages/@monomind/cli/src/orgrt/daemon.ts
 // monolean: single-process inter-org — upgrade path = daemon-to-daemon HTTP when multi-host is real
-import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, writeFileSync, existsSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { OrgBus } from './bus.js';
 import { PolicyEngine } from './policy.js';
@@ -70,6 +70,7 @@ export class OrgDaemon {
                 org: name, role, bus, policy, mailbox, cwd, def,
                 maxTurns: def.run_config.max_turns_per_message,
                 deliver: (from, to, subject, body) => this.deliver(name, from, to, subject, body),
+                askHuman: (role, question) => this.askHuman(name, role, question),
                 queryFn: this.opts.queryFn,
             }).then(() => { runtime.status = 'ended'; })
                 .catch((err) => {
@@ -223,6 +224,80 @@ export class OrgDaemon {
     hasOrgDef(name) {
         return existsSync(join(this.root, ORG_DIR, `${name}.json`));
     }
+    questionsPath(org) {
+        return join(this.root, ORG_DIR, org, 'questions.json');
+    }
+    readQuestions(org) {
+        try {
+            return JSON.parse(readFileSync(this.questionsPath(org), 'utf8'));
+        }
+        catch {
+            return { questions: [] };
+        }
+    }
+    writeQuestions(org, data) {
+        const dest = this.questionsPath(org);
+        mkdirSync(join(this.root, ORG_DIR, org), { recursive: true });
+        const tmp = `${dest}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2));
+        renameSync(tmp, dest);
+    }
+    /** Agent-initiated human question (ask_human tool). Persists to questions.json (survives
+     *  process/dashboard restarts) and emits a 'question' BusEvent so the dashboard's SSE
+     *  stream and global inbox pick it up in real time. Returns a receipt string for the tool call. */
+    async askHuman(org, role, question) {
+        const running = this.orgs.get(org);
+        const questionId = `q-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+        const data = this.readQuestions(org);
+        data.questions.push({ questionId, role, question, ts: Date.now(), answer: null, answeredAt: null });
+        this.writeQuestions(org, data);
+        running?.bus.emit({ type: 'question', from: role, data: { questionId, question } });
+        return `Question recorded (id ${questionId}) — a human will answer it; you'll receive the answer as a new message.`;
+    }
+    /** Delivers a human's answer to a pending ask_human question. If the org is still
+     *  running, pushes straight into the role's live mailbox (picked up on its very next
+     *  generator tick — see Mailbox.stream()). If the org has since stopped, queues the
+     *  answer via the same offline fallback deliver()/receiveRemote() already use
+     *  (inbox.ts + autoWake) and it's delivered when the org next starts. */
+    async answerQuestion(org, role, questionId, answer) {
+        const data = this.readQuestions(org);
+        const idx = data.questions.findIndex(q => q.questionId === questionId);
+        if (idx === -1)
+            return { ok: false, error: `question "${questionId}" not found for org "${org}"` };
+        if (data.questions[idx].answer !== null)
+            return { ok: false, error: `question "${questionId}" already answered` };
+        data.questions[idx] = { ...data.questions[idx], answer, answeredAt: Date.now() };
+        this.writeQuestions(org, data);
+        const running = this.orgs.get(org);
+        if (running) {
+            // Org IS running — deliver or report a real error, but never fall through to the
+            // offline queue+autoWake path below: autoWake() no-ops when this.orgs already has
+            // the org (see its own guard), so a role-specific delivery failure here (mailbox
+            // closed, role unknown) would otherwise queue the answer forever with no real error
+            // and no delivery. Mirrors deliver()'s existing "shutting down" error for the same
+            // mid-shutdown-mailbox-closed race.
+            const agent = running.agents.get(role);
+            if (!agent)
+                return { ok: false, error: `role "${role}" not found in org "${org}"` };
+            if (agent.mailbox.isClosed)
+                return { ok: false, error: `role "${role}" in org "${org}" is shutting down — answer not delivered` };
+            running.bus.emit({ type: 'status', from: role, msg: 'question answered', data: { questionId } });
+            agent.mailbox.push(`[answer from human] question: ${data.questions[idx].question}\n\nanswer: ${answer}`);
+            return { ok: true };
+        }
+        // Org not running at all — queue for delivery on next start, matching deliver()'s
+        // existing offline fallback exactly (inbox.ts + autoWake).
+        if (!this.hasOrgDef(org))
+            return { ok: false, error: `org "${org}" not found (no saved definition)` };
+        queueMessage(this.root, org, {
+            fromQualified: 'human', toRole: role,
+            subject: `answer:${questionId}`,
+            body: `question: ${data.questions[idx].question}\n\nanswer: ${answer}`,
+            ts: Date.now(),
+        });
+        this.autoWake(org);
+        return { ok: true };
+    }
     /** Start an offline org in the background so queued messages get drained.
      *  Fire-and-forget — errors are logged but don't propagate to the sender. */
     autoWake(name) {

package/packages/@monomind/cli/dist/src/orgrt/forwarder.js

@@ -3,7 +3,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { basename, extname, dirname, join } from 'node:path';
 /**
  * Forwards every bus event to the running mastermind control server
- * (dist/src/ui/server.mjs, POST /api/mastermind/event) so the existing
+ * (src/ui/server.mjs, POST /api/mastermind/event) so the existing
  * dashboard shows org activity. Best-effort: failures are dropped.
  *
  * Events are translated into the dashboard's native vocabulary
@@ -16,7 +16,7 @@ import { basename, extname, dirname, join } from 'node:path';
  * companionEvents() additionally emits session:start/session:complete: the
  * dashboard's client-side Chat tab only lists a run in its session dropdown
  * once it has seen a session:start for that session id — org:start alone is
- * NOT enough (verified against dist/src/ui/orgs.html's handleMmEvent, which
+ * NOT enough (verified against src/ui/orgs.html's handleMmEvent, which
  * creates the chatSessions entry solely on session:start). Companions are
  * sent before the primary translate() payload for the same bus event so the
  * client-side session record exists before anything tries to append to it.
@@ -51,7 +51,7 @@ export function attachForwarder(bus, controlJsonPath = '.monomind/control.json')
             return null;
         }
     };
-    // dist/src/ui/server.mjs's startServer() writes a per-process auth credential
+    // src/ui/server.mjs's startServer() writes a per-process auth credential
     // to 'dashboard-token' next to control.json (same .monomind dir) and requires
     // it via a header on every non-GET request. Read fresh each POST since the
     // credential rotates whenever the server restarts.
@@ -146,6 +146,10 @@ export function translate(e) {
                 },
             };
         }
+        case 'question': {
+            const q = e.data ?? {};
+            return { ...base, type: 'org:question', from: e.from, questionId: q.questionId, question: q.question };
+        }
         case 'status': {
             const msg = e.msg ?? '';
             const kind = classifyStatus(msg);

package/packages/@monomind/cli/dist/src/orgrt/server.js

@@ -27,6 +27,30 @@ export async function startOrgServer(daemon, port = 0) {
                 }
             });
         }
+        else if (req.method === 'POST' && req.url === '/api/answer-question') {
+            let body = '';
+            req.on('data', c => { body += c; });
+            req.on('end', () => {
+                (async () => {
+                    try {
+                        const payload = JSON.parse(body || '{}');
+                        if (!payload.org || !payload.role || !payload.questionId || payload.answer === undefined) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: false, error: 'org, role, questionId, answer are required' }));
+                            return;
+                        }
+                        const result = await daemon.answerQuestion(payload.org, payload.role, payload.questionId, payload.answer);
+                        res.writeHead(result.ok ? 200 : 404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify(result));
+                    }
+                    catch (err) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: err instanceof Error ? err.message : 'bad request' }));
+                    }
+                })();
+            });
+            return;
+        }
         else {
             res.writeHead(404);
             res.end('not found');

package/packages/@monomind/cli/dist/src/orgrt/session.d.ts

@@ -12,6 +12,7 @@ export interface SessionOpts {
     mailbox: Mailbox;
     cwd: string;
     deliver: DeliverFn;
+    askHuman?: (role: string, question: string) => Promise<string>;
     def?: OrgDef;
     maxTurns?: number;
     queryFn?: typeof query;

package/packages/@monomind/cli/dist/src/orgrt/session.js

@@ -12,6 +12,7 @@ export function buildRolePrompt(role, def, roster) {
         `## Communication protocol`,
         `The ONLY way to communicate with other agents is the org_send tool.`,
         `Roster: ${roster.join(', ')}. Address another org's agent as "<org-name>:<role-id>".`,
+        `If you need a human decision, call ask_human with your question, then end your turn — you'll receive the human's answer as a new message when it arrives. Do not call ask_human for anything you can resolve yourself.`,
         `When you receive a message, act on it, then org_send your result to the requester.`,
         `When your current work is complete and no reply is needed, end your turn without further tool calls.`,
     ].filter(Boolean).join('\n\n');
@@ -51,6 +52,13 @@ async function runOneSession(opts) {
                 const receipt = await deliver(role.id, args.to, args.subject, args.message);
                 return { content: [{ type: 'text', text: receipt }] };
             }),
+            tool('ask_human', 'Ask a human a free-form question and pause for their answer. Use only when you genuinely need human judgment.', { question: z.string() }, async (args) => {
+                if (!opts.askHuman) {
+                    return { content: [{ type: 'text', text: 'ask_human is not available in this session' }] };
+                }
+                const receipt = await opts.askHuman(role.id, args.question);
+                return { content: [{ type: 'text', text: receipt }] };
+            }),
         ],
     });
     bus.emit({ type: 'status', from: role.id, msg: 'session starting' });

package/packages/@monomind/cli/dist/src/orgrt/types.d.ts

@@ -832,7 +832,7 @@ export interface BusEvent {
     ts: number;
     org: string;
     run: string;
-    type: 'message' | 'xorg' | 'tool' | 'asset' | 'chat' | 'status' | 'audit' | 'usage';
+    type: 'message' | 'xorg' | 'tool' | 'asset' | 'chat' | 'status' | 'audit' | 'usage' | 'question';
     from?: string;
     to?: string;
     subject?: string;

package/packages/@monomind/cli/dist/src/pricing/model-pricing.d.ts

@@ -7,7 +7,7 @@
  *   cw  — cache-write tokens
  *   cr  — cache-read tokens
  *
- * Consumers: dist/src/ui/collector.mjs and dist/src/ui/server.mjs both
+ * Consumers: src/ui/collector.mjs and src/ui/server.mjs both
  * derive their inline pricing tables from this canonical list.
  */
 export interface ModelPrice {

package/packages/@monomind/cli/dist/src/ui/collector.mjs

@@ -640,15 +640,30 @@ function slugToPath(slug) {
 }
 
 // Reconstruct the real filesystem path from a Claude project slug.
-// Slugs encode the path with every '/' replaced by '-', which is lossy when
-// directory names contain literal hyphens (e.g. /Desktop/agent-f/accounting).
-// Strategy: naive replace first; if not found, greedy DFS through the filesystem
-// trying longest-possible segment (with embedded hyphens) at each level.
+// Slugs encode the path with every '/' AND '.' replaced by '-' (so a hidden
+// directory like '.claude' shows up as a bare '--claude', i.e. an empty split
+// token immediately before 'claude' — e.g. the real path
+// '/monomind/.claude/worktrees/foo' slugs to '-monomind--claude-worktrees-foo').
+// Also lossy when directory names contain literal hyphens (e.g.
+// /Desktop/agent-f/accounting). Strategy: naive replace first; if not found,
+// greedy DFS through the filesystem trying longest-possible segment (with
+// embedded hyphens) at each level.
 function resolveSlugPath(slug) {
   const naive = '/' + slug.replace(/^-/, '').replace(/-/g, '/');
   try { if (fs.existsSync(naive)) return naive; } catch {}
 
-  const tokens = slug.replace(/^-/, '').split('-').filter(Boolean);
+  // An empty token between two hyphens marks a collapsed '.' — reattach it to
+  // the following token instead of dropping it, so hidden directories survive
+  // reconstruction (dropping it silently turns '.claude' into 'claude', which
+  // never exists on disk, sending the walk down the wrong path entirely).
+  const rawTokens = slug.replace(/^-/, '').split('-');
+  const tokens = [];
+  let pendingDot = false;
+  for (const part of rawTokens) {
+    if (part === '') { pendingDot = true; continue; }
+    tokens.push(pendingDot ? '.' + part : part);
+    pendingDot = false;
+  }
 
   function walk(idx, dir) {
     if (idx === tokens.length) return dir;