u-foo 1.0.6 → 1.2.0

package/README.md

@@ -1,32 +1,159 @@
 # ufoo
 
-Multi-agent AI collaboration toolkit for Claude Code and OpenAI Codex.
+🤖 Multi-agent AI collaboration framework for orchestrating Claude Code, OpenAI Codex, and custom AI agents.
+
+[![npm version](https://img.shields.io/npm/v/u-foo.svg)](https://www.npmjs.com/package/u-foo)
+[![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![Platform](https://img.shields.io/badge/platform-macOS-blue.svg)](https://www.apple.com/macos)
+
+## Why ufoo?
+
+ufoo solves the challenge of coordinating multiple AI coding agents:
+
+- **🔗 Unified Interface** - One chat UI to manage all your AI agents
+- **📬 Message Routing** - Agents can communicate and collaborate via event bus
+- **🧠 Context Sharing** - Shared decisions and knowledge across agents
+- **🚀 Auto-initialization** - Agent wrappers handle setup automatically
+- **📝 Decision Tracking** - Record architectural decisions and trade-offs
+- **⚡ Real-time Updates** - See agent status and messages instantly
 
 ## Features
 
+- **Chat Interface** - Interactive multi-agent chat UI (`ufoo chat`)
+  - Real-time agent communication and status monitoring
+  - Dashboard with agent list, online status, and quick actions
+  - Direct messaging to specific agents with `@agent-name`
 - **Event Bus** - Real-time inter-agent messaging (`ufoo bus`)
 - **Context Sharing** - Shared decisions and project context (`ufoo ctx`)
-- **Agent Wrappers** - Auto-initialization for Claude Code (`uclaude`) and Codex (`ucodex`)
+- **Agent Wrappers** - Auto-initialization for Claude Code (`uclaude`), Codex (`ucodex`), and ucode assistant (`ucode`)
   - **PTY Wrapper** - Intelligent terminal emulation with ready detection
   - **Smart Probe Injection** - Waits for agent initialization before injecting commands
+  - **Consistent Branding** - Unified agent naming (e.g., ucode-1, claude-1, codex-1)
 - **Skills System** - Extensible agent capabilities (`ufoo skills`)
 
-## Quick Start
+## Installation
 
 ```bash
-# Clone and link globally
-git clone <repo> ~/.ufoo
+# Install globally from npm
+npm install -g u-foo
+
+# Or clone from source
+git clone https://github.com/Icyoung/ufoo.git ~/.ufoo
 cd ~/.ufoo && npm link
+```
 
+## Quick Start
+
+```bash
 # Initialize a project
 cd your-project
 ufoo init
 
-# Or use agent wrappers (auto-init + bus join)
-uclaude   # instead of 'claude'
-ucodex    # instead of 'codex'
+# Launch chat interface (default command)
+ufoo chat
+# or just
+ufoo
+
+# Use agent wrappers (auto-init + bus join)
+uclaude   # Claude Code wrapper
+ucodex    # Codex wrapper
+ucode     # ucode assistant (self-developed AI coding agent)
+```
+
+## Example Workflow
+
+```bash
+# 1. Start the chat interface
+$ ufoo
+
+# 2. Launch agents from chat
+> /launch claude
+> /launch ucode
+
+# 3. Send tasks to agents
+> @claude-1 Please analyze the current codebase structure
+> @ucode-1 Fix the bug in authentication module
+
+# 4. Agents communicate via bus
+claude-1: Analysis complete. Found 3 areas needing refactoring...
+ucode-1: Bug fixed. Running tests...
+
+# 5. Check decisions made
+> /decisions
 ```
 
+To import a local `pi-mono` checkout as a reference snapshot (reference-only):
+
+```bash
+npm run import:pi-mono -- /path/to/pi-mono
+```
+
+Native self-developed implementation lives under `src/code`.
+
+Prepare and verify `ucode` runtime wiring:
+
+```bash
+ufoo ucode doctor
+ufoo ucode prepare
+ufoo ucode build
+```
+
+Try native core queue runtime (WIP):
+
+```bash
+ucode-core submit --tool read --args-json '{"path":"README.md"}'
+ucode-core run-once --json
+ucode-core list --json
+```
+
+## Agent Configuration
+
+Configure AI providers in `.ufoo/config.json`:
+
+### ucode Configuration (Self-developed Assistant)
+```json
+{
+  "ucodeProvider": "openai",          // or "anthropic", "azure", etc.
+  "ucodeModel": "gpt-4-turbo-preview",
+  "ucodeBaseUrl": "https://api.openai.com/v1",
+  "ucodeApiKey": "sk-***"
+}
+```
+
+### Claude Configuration
+```json
+{
+  "claudeProvider": "claude-cli",     // Uses Claude CLI
+  "claudeModel": "claude-3-opus"      // or "claude-3-sonnet"
+}
+```
+
+### Codex Configuration
+```json
+{
+  "codexProvider": "codex-cli",       // Uses Codex CLI
+  "codexModel": "gpt-4"               // or "gpt-4-turbo-preview"
+}
+```
+
+### Complete Example
+```json
+{
+  "launchMode": "internal",
+  "ucodeProvider": "openai",
+  "ucodeModel": "gpt-4-turbo-preview",
+  "ucodeBaseUrl": "https://api.openai.com/v1",
+  "ucodeApiKey": "sk-***",
+  "claudeProvider": "claude-cli",
+  "claudeModel": "claude-3-opus",
+  "codexProvider": "codex-cli",
+  "codexModel": "gpt-4"
+}
+```
+
+`ucode` writes these into a dedicated runtime directory (`.ufoo/agent/ucode/pi-agent`) and uses them for native planner/engine calls.
+
 ## Architecture
 
 ```
@@ -51,21 +178,43 @@ Bus state lives in `.ufoo/agent/all-agents.json` (metadata), `.ufoo/bus/*` (queu
 
 ## Commands
 
+### Core Commands
 | Command | Description |
 |---------|-------------|
+| `ufoo` | Launch chat interface (default) |
+| `ufoo chat` | Launch interactive multi-agent chat UI |
 | `ufoo init` | Initialize .ufoo in current project |
 | `ufoo status` | Show banner, unread bus messages, open decisions |
-| `ufoo daemon --start|--stop|--status` | Manage ufoo daemon |
-| `ufoo chat` | Launch ufoo chat UI (also default when no args) |
-| `ufoo resume [nickname]` | Resume agent sessions (optional nickname) |
-| `ufoo bus join` | Join event bus (auto by uclaude/ucodex) |
+| `ufoo doctor` | Check installation health |
+
+### Agent Management
+| Command | Description |
+|---------|-------------|
+| `ufoo daemon start` | Start ufoo daemon |
+| `ufoo daemon stop` | Stop ufoo daemon |
+| `ufoo daemon status` | Check daemon status |
+| `ufoo resume [nickname]` | Resume agent sessions |
+
+### Event Bus
+| Command | Description |
+|---------|-------------|
+| `ufoo bus join` | Join event bus (auto by agent wrappers) |
 | `ufoo bus send <id> <msg>` | Send message to agent |
 | `ufoo bus check <id>` | Check pending messages |
-| `ufoo bus status` | Show bus status |
+| `ufoo bus status` | Show bus status and online agents |
+
+### Context & Decisions
+| Command | Description |
+|---------|-------------|
 | `ufoo ctx decisions -l` | List all decisions |
 | `ufoo ctx decisions -n 1` | Show latest decision |
+| `ufoo ctx decisions new <title>` | Create new decision |
+
+### Skills
+| Command | Description |
+|---------|-------------|
 | `ufoo skills list` | List available skills |
-| `ufoo doctor` | Check installation health |
+| `ufoo skills show <skill>` | Show skill details |
 
 Notes:
 - Claude CLI headless agent uses `--dangerously-skip-permissions`.
@@ -78,12 +227,14 @@ ufoo/
 │   ├── ufoo         # Main CLI entry (bash)
 │   ├── ufoo.js      # Node wrapper
 │   ├── uclaude      # Claude Code wrapper
-│   └── ucodex       # Codex wrapper
+│   ├── ucodex       # Codex wrapper
+│   └── ucode        # ucode assistant wrapper
 ├── SKILLS/          # Global skills (uinit, ustatus)
 ├── src/
 │   ├── bus/         # Event bus implementation (JS)
 │   ├── daemon/      # Daemon + chat bridge
-│   └── agent/       # Agent launch/runtime
+│   ├── agent/       # Agent launch/runtime
+│   └── code/        # Native ucode core implementation
 ├── scripts/         # Legacy helpers (bash, deprecated)
 ├── modules/
 │   ├── context/     # Decision/context protocol
@@ -112,6 +263,37 @@ your-project/
 └── CLAUDE.md            # → AGENTS.md
 ```
 
+## Chat Interface
+
+The interactive chat UI provides a centralized hub for agent management:
+
+### Features
+- **Real-time Communication** - See all agent messages in one place
+- **Agent Dashboard** - Monitor online status, session IDs, and nicknames
+- **Direct Messaging** - Use `@agent-name` to target specific agents
+- **Command Completion** - Tab completion for commands and agent names
+- **Mouse Support** - Toggle with `Ctrl+M` for scrolling vs text selection
+- **Session History** - Persistent message history across sessions
+
+### Keyboard Shortcuts
+| Key | Action |
+|-----|--------|
+| `Tab` | Auto-complete commands/agents |
+| `Ctrl+C` | Exit chat |
+| `Ctrl+M` | Toggle mouse mode |
+| `Ctrl+L` | Clear screen |
+| `Ctrl+R` | Refresh agent list |
+| `↑/↓` | Navigate command history |
+
+### Chat Commands
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/agents` | List online agents |
+| `/clear` | Clear chat history |
+| `/settings` | Configure chat preferences |
+| `@agent-name <message>` | Send to specific agent |
+
 ## Agent Communication
 
 Agents communicate via the event bus:
@@ -138,9 +320,10 @@ Built-in skills triggered by slash commands:
 
 ## Requirements
 
-- macOS (for Terminal.app/iTerm2 injection features)
-- Node.js >= 18 (optional, for npm global install)
-- Bash 4+
+- **macOS** - Required for Terminal.app/iTerm2 integration
+- **Node.js >= 18** - For npm installation and JavaScript runtime
+- **Bash 4+** - For shell scripts and command execution
+- **Terminal** - iTerm2 or Terminal.app for agent launching
 
 ## Codex CLI Notes
 
@@ -155,21 +338,62 @@ ufoo chat  # daemon auto-starts
 
 ## Development
 
+### Setup
 ```bash
-# Local development
-./bin/ufoo --help
+# Clone the repository
+git clone https://github.com/Icyoung/ufoo.git
+cd ufoo
 
-# Or via Node
+# Install dependencies
+npm install
+
+# Link for local development
 npm link
-ufoo --help
+
+# Run tests
+npm test
 ```
 
+### Contributing
+- Fork the repository
+- Create a feature branch (`git checkout -b feature/amazing-feature`)
+- Commit your changes (`git commit -m 'Add amazing feature'`)
+- Push to the branch (`git push origin feature/amazing-feature`)
+- Open a Pull Request
+
+### Project Structure
+- `src/` - Core JavaScript implementation
+- `bin/` - CLI entry points
+- `modules/` - Modular features (bus, context, etc.)
+- `test/` - Unit and integration tests
+- `SKILLS/` - Agent skill definitions
+
 ## License
 
 UNLICENSED (Private)
 
 ## Recent Changes
 
+### 🎨 UCode Branding & UI Improvements (2026-02-15)
+
+Enhanced ucode agent branding consistency and fixed UI rendering issues:
+
+**Features:**
+- **Consistent Branding** - ucode agents now display as "ucode-1" instead of "ufoo-code-1"
+- **Banner Normalization** - Agent type shows "ucode" in launch banners
+- **UI Width Fix** - Resolved terminal width inconsistency causing background overflow
+- **Immediate Prompt Display** - ucode TUI now shows incoming prompts instantly (not waiting for response)
+
+**Technical Details:**
+- `src/bus/nickname.js` - Maps ufoo-code → ucode for nickname generation
+- `src/utils/banner.js` - Normalized agent type display
+- `src/chat/layout.js` - Fixed blessed log component width handling
+- `src/code/tui.js` - Added onMessageReceived callback for instant display
+
+**Version:** v1.1.9
+
+---
+
 ### 🚀 Smart Ready Detection & PTY Wrapper (2026-02-06)
 
 Added intelligent agent initialization detection for reliable probe injection:

package/SKILLS/ufoo/SKILL.md

@@ -2,7 +2,7 @@
 name: ufoo
 description: |
   Unified ufoo agent protocol: context decisions, event bus, and initialization.
-  Use when: (1) input starts with "/ufoo", (2) agent session startup, (3) any ufoo-related operation.
+  Use when: (1) input starts with "/ufoo" or "$ufoo", (2) agent session startup, (3) any ufoo-related operation.
   Combines uctx (decisions), ubus (messaging), and uinit (initialization).
 ---
 
@@ -16,7 +16,7 @@ ufoo is the multi-agent coordination layer. It provides three capabilities:
 
 ## Session Marker
 
-When you see `/ufoo <marker>` (e.g., `/ufoo claude-9`), this is a daemon probe for session tracking. **Do not reply.** Silently ignore it and wait for the next user input.
+When you see a probe marker command like `/ufoo <marker>` (Claude) or `$ufoo <marker>` (Codex), this is daemon session tracking. **Do not reply.** Silently ignore it and wait for the next user input.
 
 ---
 
@@ -88,6 +88,21 @@ ufoo bus broadcast "<message>"               # Broadcast to all
 ufoo bus status                              # Show bus status
 ```
 
+### Runtime Report (Unified for assistant/ucodex/uclaude)
+
+Use the same report contract for runtime progress sync:
+
+```bash
+ufoo report start "<task>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report progress "<detail>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report done "<summary>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report error "<reason>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+```
+
+Notes:
+- Use `--scope private` for helper-internal reports (assistant-like private channel).
+- `--controller ufoo-agent` routes report events to the ufoo-agent private inbox.
+
 ### Target Resolution
 
 - Exact ID: `claude-code:abc123`

package/SKILLS/uinit/SKILL.md

@@ -46,8 +46,13 @@ ufoo init --modules <selected_modules> --project $(pwd)
 ### 3. If bus module selected, auto-join bus
 
 ```bash
-SUBSCRIBER=$(ufoo bus join | tail -1)
-echo "Joined event bus: $SUBSCRIBER"
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+if [ -n "$SUBSCRIBER" ]; then
+  echo "Using existing subscriber ID: $SUBSCRIBER"
+else
+  SUBSCRIBER=$(ufoo bus join | tail -1)
+  echo "Joined event bus: $SUBSCRIBER"
+fi
 ```
 
 ### 4. Report initialization result
@@ -69,5 +74,5 @@ Next steps:
 ## Notes
 
 - If .ufoo/context, .ufoo/bus, or .ufoo/agent already exists, skip creation
-- After initialization, auto-join event bus (if bus enabled)
+- After initialization, reuse existing subscriber ID first, join only as fallback (if bus enabled)
 - AGENTS.md will have protocol description block injected

package/bin/ucode-core.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const { runUcodeCoreCli } = require("../src/code/cli");
+
+(async () => {
+  const argv = process.argv.slice(2);
+  const result = await runUcodeCoreCli({ argv, projectRoot: process.cwd() });
+  if (result && typeof result.output === "string" && result.output) {
+    process.stdout.write(result.output);
+  }
+  process.exit(typeof result.exitCode === "number" ? result.exitCode : 0);
+})().catch((err) => {
+  process.stderr.write(`${err && err.message ? err.message : "ucode-core failed"}\n`);
+  process.exit(1);
+});

package/bin/ucode.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * ucode: Launch ufoo self-developed coding agent core
+ *
+ * Usage: ucode [core args...]
+ *
+ * Command resolution order:
+ * 1) UFOO_UCODE_CMD / UFOO_UFOO_CODE_CMD
+ * 2) .ufoo/config.json -> ucodeCommand / ufooCodeCommand
+ * 3) fallback: bundled native core entry
+ */
+
+const fs = require("fs");
+const AgentLauncher = require("../src/agent/launcher");
+const { resolveUcodeLaunch } = require("../src/agent/ucode");
+const { prepareUcodeBootstrap } = require("../src/agent/ucodeBootstrap");
+const { prepareUcodeRuntimeConfig } = require("../src/agent/ucodeRuntimeConfig");
+
+function stripAppendSystemPromptArgs(args = [], targetFile = "") {
+  const normalizedTarget = String(targetFile || "").trim();
+  if (!Array.isArray(args) || args.length === 0) return { args: [], removed: false };
+  const nextArgs = [];
+  let removed = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const item = String(args[i] || "");
+    if (!item) continue;
+    if (item === "--append-system-prompt") {
+      const value = String(args[i + 1] || "");
+      if (!normalizedTarget || value === normalizedTarget) {
+        removed = true;
+        i += 1;
+        continue;
+      }
+      nextArgs.push(item, value);
+      i += 1;
+      continue;
+    }
+    if (item.startsWith("--append-system-prompt=")) {
+      const value = item.slice("--append-system-prompt=".length);
+      if (!normalizedTarget || value === normalizedTarget) {
+        removed = true;
+        continue;
+      }
+    }
+    nextArgs.push(item);
+  }
+  return { args: nextArgs, removed };
+}
+
+function shouldPreserveAppendTarget({
+  appendTarget = "",
+  bootstrapFile = "",
+} = {}) {
+  const append = String(appendTarget || "").trim();
+  if (!append) return false;
+  const bootstrap = String(bootstrapFile || "").trim();
+  if (!bootstrap) return fs.existsSync(append);
+  if (append === bootstrap) return false;
+  return fs.existsSync(append);
+}
+
+const resolved = resolveUcodeLaunch({
+  argv: process.argv.slice(2),
+  env: process.env,
+  cwd: process.cwd(),
+});
+
+if (resolved && resolved.env && typeof resolved.env === "object") {
+  for (const [key, value] of Object.entries(resolved.env)) {
+    if (!key) continue;
+    process.env[key] = String(value);
+  }
+}
+
+try {
+  const runtimePrepared = prepareUcodeRuntimeConfig({
+    projectRoot: process.cwd(),
+    env: process.env,
+  });
+  if (runtimePrepared && runtimePrepared.env && typeof runtimePrepared.env === "object") {
+    for (const [key, value] of Object.entries(runtimePrepared.env)) {
+      if (!key) continue;
+      process.env[key] = String(value);
+    }
+  }
+} catch {
+  // runtime config preparation is best-effort
+}
+
+try {
+  prepareUcodeBootstrap({
+    projectRoot: process.cwd(),
+    promptFile: process.env.UFOO_UCODE_PROMPT_FILE || "",
+    targetFile: process.env.UFOO_UCODE_BOOTSTRAP_FILE || "",
+  });
+} catch (err) {
+  const mode = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT_MODE || "auto").trim().toLowerCase();
+  const bootstrapFile = String(process.env.UFOO_UCODE_BOOTSTRAP_FILE || "").trim();
+  const appendTarget = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT || bootstrapFile).trim();
+  const preserveCustomAppend = shouldPreserveAppendTarget({ appendTarget, bootstrapFile });
+  if (mode !== "always" && !preserveCustomAppend) {
+    const stripped = stripAppendSystemPromptArgs(resolved.args, appendTarget);
+    resolved.args = stripped.args;
+    if (stripped.removed) {
+      console.error(`[ucode] Warning: bootstrap prepare failed; launching without --append-system-prompt (${err && err.message ? err.message : "unknown error"})`);
+    }
+  } else if (preserveCustomAppend) {
+    console.error(`[ucode] Warning: bootstrap prepare failed; preserving custom --append-system-prompt (${err && err.message ? err.message : "unknown error"})`);
+  }
+}
+
+const mode = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT_MODE || "auto").trim().toLowerCase();
+const bootstrapFile = String(process.env.UFOO_UCODE_BOOTSTRAP_FILE || "").trim();
+const appendTarget = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT || bootstrapFile).trim();
+const preserveCustomAppend = shouldPreserveAppendTarget({ appendTarget, bootstrapFile });
+if (mode !== "always" && bootstrapFile && !fs.existsSync(bootstrapFile) && !preserveCustomAppend) {
+  const stripped = stripAppendSystemPromptArgs(resolved.args, appendTarget);
+  resolved.args = stripped.args;
+  if (stripped.removed) {
+    console.error("[ucode] Warning: bootstrap file missing; launching without --append-system-prompt");
+  }
+}
+
+const launcher = new AgentLauncher(resolved.agentType, resolved.command);
+launcher.launch(resolved.args);

package/bin/ufoo-assistant-agent.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runAssistantStdio } = require("../src/assistant/stdio");
+
+runAssistantStdio();

package/bin/ufoo-engine.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const { runUfooEngineCli } = require("../src/assistant/ufooEngineCli");
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.resume();
+  });
+}
+
+(async () => {
+  const stdinText = await readStdin();
+  const result = await runUfooEngineCli({
+    argv: process.argv.slice(2),
+    stdinText,
+  });
+  process.stdout.write(result.output);
+  process.exitCode = result.exitCode;
+})();

package/bin/ufoo.js

@@ -27,6 +27,10 @@ async function main() {
     try {
       await runPtyRunner({ projectRoot: process.cwd(), agentType });
     } catch (err) {
+      const normalized = String(agentType || "").trim().toLowerCase();
+      if (normalized === "ufoo" || normalized === "ucode" || normalized === "ufoo-code") {
+        throw err;
+      }
       // Fallback to headless runner if PTY is unavailable
       // eslint-disable-next-line no-console
       console.error(`[pty-runner] ${err.message || err}. Falling back to headless internal runner.`);

package/modules/AGENTS.template.md

@@ -27,10 +27,17 @@ ufoo ctx decisions -l          # List all decisions
 ufoo ctx decisions -n 1        # Show latest decision
 
 # Bus
-ufoo bus join                  # Join bus (auto by uclaude/ucodex)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -1)
 ufoo bus check $SUBSCRIBER     # Check pending messages
 ufoo bus send "<id>" "<msg>"   # Send message
 ufoo bus status                # Show bus status
+
+# Runtime report (shared contract for assistant/ucodex/uclaude)
+ufoo report start "<task>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report progress "<detail>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report done "<summary>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report error "<reason>" --task <id> --agent "$SUBSCRIBER" --scope public
 ```
 
 ---
@@ -67,9 +74,12 @@ ufoo ctx decisions new "Short descriptive title"
 ### CRITICAL: `ubus` Command Behavior
 
 **When you receive `ubus`, you MUST:**
-1. Check pending messages: `ufoo bus check $SUBSCRIBER`
-2. **EXECUTE each task immediately** - Do NOT ask the user
-3. Reply to sender: `ufoo bus send "<publisher>" "<result>"`
+1. Resolve subscriber ID first (reuse existing ID, join only as fallback):
+   `SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"; [ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -1)`
+2. Check pending messages: `ufoo bus check $SUBSCRIBER`
+3. **EXECUTE each task immediately** - Do NOT ask the user
+4. Reply to sender: `ufoo bus send "<publisher>" "<result>"`
+5. **CRITICAL: Acknowledge messages after handling**: `ufoo bus ack $SUBSCRIBER`
 
 **Rules:**
 - Execute tasks immediately without asking

package/modules/bus/README.md

@@ -40,8 +40,9 @@ ufoo init --modules context,bus
 ### Join Bus
 
 ```bash
-SUBSCRIBER=$(ufoo bus join | tail -n 1)
-# Output: claude-code:a1b2c3
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
+# Output: claude-code:a1b2c3 (or codex:def456)
 ```
 
 ### Check Pending Messages
@@ -74,7 +75,8 @@ ufoo bus status
 If you want to receive "new message alerts" while running Codex/Claude in another terminal, use **agent-side alert/listen** (avoids IME/accessibility permission/window positioning fragmentation issues):
 
 ```bash
-SUBSCRIBER=$(ufoo bus join | tail -n 1)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
 
 # Background alert: title badge + bell + optional macOS notification center
 ufoo bus alert "$SUBSCRIBER" 1 --notify --daemon
@@ -87,10 +89,11 @@ ufoo bus listen "$SUBSCRIBER" --from-beginning
 
 If you need **Claude A to notify Claude B / Codex C and have the target auto-execute** (e.g., auto-trigger `/ubus`), use the bus daemon:
 
-1) First `join` in each terminal session (records `tty`, also records `TMUX_PANE` if in tmux):
+1) Resolve subscriber in each terminal session first (records `tty`, also records `TMUX_PANE` if in tmux). Join only as fallback:
 
 ```bash
-SUBSCRIBER=$(ufoo bus join | tail -n 1)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
 ```
 
 2) Start the bus daemon in the project (runs as background daemon):