crewswarm 0.8.1-beta

package/lib/runtime/logger.mjs

@@ -0,0 +1,58 @@
+/**
+ * logger.mjs — structured log utility for crewswarm
+ *
+ * By default emits human-readable prefixed lines.
+ * Set LOG_FORMAT=json to emit newline-delimited JSON (machine-parseable).
+ *
+ * Usage:
+ *   import { log } from "../lib/runtime/logger.mjs";
+ *   log("info",  "crew-lead", "RT connected", { port: 18889 });
+ *   log("warn",  "wave-dispatcher", "queue full", { depth: 50, agent: "crew-coder" });
+ *   log("error", "pipeline-state", "save failed", { pipelineId, error: e.message });
+ */
+
+const JSON_MODE = process.env.LOG_FORMAT === "json";
+
+const LEVEL_PREFIX = {
+  info:  "",
+  warn:  "⚠️  ",
+  error: "❌ ",
+  debug: "🔍 ",
+};
+
+/**
+ * @param {"info"|"warn"|"error"|"debug"} level
+ * @param {string} component  e.g. "crew-lead", "wave-dispatcher", "pipeline-state"
+ * @param {string} msg        Human-readable message
+ * @param {object} [data]     Optional structured fields (correlationId, agent, taskId, …)
+ */
+export function log(level, component, msg, data = {}) {
+  if (JSON_MODE) {
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      component,
+      msg,
+      ...data,
+    };
+    process.stdout.write(JSON.stringify(entry) + "\n");
+  } else {
+    const prefix = LEVEL_PREFIX[level] ?? "";
+    const extras = Object.keys(data).length
+      ? " " + Object.entries(data).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(" ")
+      : "";
+    const line = `[${component}] ${prefix}${msg}${extras}`;
+    if (level === "error") console.error(line);
+    else console.log(line);
+  }
+}
+
+/**
+ * Convenience wrappers
+ */
+export const logger = {
+  info:  (component, msg, data) => log("info",  component, msg, data),
+  warn:  (component, msg, data) => log("warn",  component, msg, data),
+  error: (component, msg, data) => log("error", component, msg, data),
+  debug: (component, msg, data) => log("debug", component, msg, data),
+};

package/lib/runtime/memory.mjs

@@ -0,0 +1,421 @@
+/**
+ * lib/runtime/memory.mjs
+ * Shared memory bundle loading, agent prompt loading, and task prompt assembly.
+ * Extracted from gateway-bridge.mjs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { CREWSWARM_REPO_ROOT } from "./config.mjs";
+import {
+  applySharedChatPromptOverlay,
+  getSharedChatPromptOverlay,
+} from "../chat/shared-chat-prompt-overlay.mjs";
+import { loadProjectMessages } from "../chat/project-messages.mjs";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+export const SHARED_MEMORY_DIR = path.join(CREWSWARM_REPO_ROOT, "memory");
+export const SHARED_MEMORY_MAX_FILE_CHARS = 8000;
+export const SHARED_MEMORY_MAX_TOTAL_CHARS = 40000;
+export const SHARED_MEMORY_FILES = [
+  "law.md", // Crew laws — no harm, no unauthorized access, don't break machine, create value
+  "current-state.md", // System overview — what crewswarm is, CRITICAL task guidance
+  "agent-handoff.md", // Current status, last completed work, agent rules
+  "orchestration-protocol.md", // Agent roster, tool permissions, dispatch syntax
+  "brain.md", // Accumulated project knowledge — read this to avoid repeating mistakes
+  // "decisions.md"            // Architectural decisions — only load when needed
+  // "telegram-context.md"     // Telegram chat history — too noisy for code tasks
+];
+
+// Extra memory files injected for specific agents (static) + dynamic agents by _role
+export const _AGENT_EXTRA_MEMORY_STATIC = {
+  "crew-fixer": ["lessons.md"],
+  "crew-coder": ["lessons.md"],
+  "crew-coder-front": ["lessons.md"],
+  "crew-coder-back": ["lessons.md"],
+};
+export const _EXTRA_MEMORY_BY_ROLE = {
+  coder: ["lessons.md"],
+  ops: ["lessons.md"],
+};
+
+// ── Injected dependencies ────────────────────────────────────────────────────
+
+let _telemetry = () => {};
+let _ensureSharedMemoryFiles = () => ({ created: [], error: null });
+let _loadAgentList = () => [];
+let _loadAgentToolPermissions = () => new Set();
+let _buildToolInstructions = () => "";
+let _getOpencodeProjectDir = () => "";
+
+export function initMemory({
+  telemetry,
+  ensureSharedMemoryFiles,
+  loadAgentList,
+  loadAgentToolPermissions,
+  buildToolInstructions,
+  getOpencodeProjectDir,
+}) {
+  if (telemetry) _telemetry = telemetry;
+  if (ensureSharedMemoryFiles)
+    _ensureSharedMemoryFiles = ensureSharedMemoryFiles;
+  if (loadAgentList) _loadAgentList = loadAgentList;
+  if (loadAgentToolPermissions)
+    _loadAgentToolPermissions = loadAgentToolPermissions;
+  if (buildToolInstructions) _buildToolInstructions = buildToolInstructions;
+  if (getOpencodeProjectDir) _getOpencodeProjectDir = getOpencodeProjectDir;
+}
+
+// ── Functions ────────────────────────────────────────────────────────────────
+
+export function getAgentExtraMemory(agentId) {
+  const bareId = agentId.startsWith("crew-")
+    ? `crew-${agentId.slice(5)}`
+    : agentId;
+  if (_AGENT_EXTRA_MEMORY_STATIC[agentId])
+    return _AGENT_EXTRA_MEMORY_STATIC[agentId];
+  if (_AGENT_EXTRA_MEMORY_STATIC[bareId])
+    return _AGENT_EXTRA_MEMORY_STATIC[bareId];
+  try {
+    const agents = _loadAgentList();
+    const cfg = agents.find((a) => a.id === agentId);
+    if (cfg?._role && _EXTRA_MEMORY_BY_ROLE[cfg._role])
+      return _EXTRA_MEMORY_BY_ROLE[cfg._role];
+  } catch {}
+  return [];
+}
+
+export function loadSharedMemoryBundle() {
+  try {
+    const ensureResult = _ensureSharedMemoryFiles();
+    if (ensureResult.error) {
+      return {
+        text: "",
+        missing: SHARED_MEMORY_FILES,
+        included: [],
+        files: {},
+        bytes: 0,
+        loadFailed: true,
+        bootstrapCreated: ensureResult.created,
+      };
+    }
+
+    if (!fs.existsSync(SHARED_MEMORY_DIR)) {
+      return {
+        text: "",
+        missing: SHARED_MEMORY_FILES,
+        included: [],
+        files: {},
+        bytes: 0,
+        loadFailed: true,
+        bootstrapCreated: ensureResult.created,
+      };
+    }
+
+    const included = [];
+    const missing = [];
+    const files = {};
+    const sections = [];
+    let totalChars = 0;
+
+    for (const fileName of SHARED_MEMORY_FILES) {
+      const fullPath = path.join(SHARED_MEMORY_DIR, fileName);
+      if (!fs.existsSync(fullPath)) {
+        missing.push(fileName);
+        continue;
+      }
+
+      let content = fs.readFileSync(fullPath, "utf8");
+      if (content.length > SHARED_MEMORY_MAX_FILE_CHARS) {
+        // For append-only files keep the TAIL (newest entries); for others keep the HEAD
+        const TAIL_FIRST_FILES = new Set([
+          "brain.md",
+          "session-log.md",
+          "telegram-context.md",
+        ]);
+        if (TAIL_FIRST_FILES.has(fileName)) {
+          content = `[…older entries trimmed]\n\n${content.slice(-SHARED_MEMORY_MAX_FILE_CHARS)}`;
+        } else {
+          content = `${content.slice(0, SHARED_MEMORY_MAX_FILE_CHARS)}\n\n[truncated]`;
+        }
+      }
+
+      files[fileName] = content;
+      const section = `### ${fileName}\n${content}`;
+      if (totalChars + section.length > SHARED_MEMORY_MAX_TOTAL_CHARS) break;
+
+      sections.push(section);
+      included.push(fileName);
+      totalChars += section.length;
+    }
+
+    if (!sections.length) {
+      return {
+        text: "",
+        missing,
+        included,
+        files,
+        bytes: 0,
+        loadFailed: false,
+        bootstrapCreated: ensureResult.created,
+      };
+    }
+
+    const text = [
+      "Persistent shared memory (load this before answering):",
+      ...sections,
+      "End persistent memory.",
+    ].join("\n\n");
+    return {
+      text,
+      missing,
+      included,
+      files,
+      bytes: Buffer.byteLength(text, "utf8"),
+      loadFailed: false,
+      bootstrapCreated: ensureResult.created,
+    };
+  } catch (err) {
+    _telemetry("shared_memory_load_error", {
+      message: err?.message ?? String(err),
+    });
+    return {
+      text: "",
+      missing: SHARED_MEMORY_FILES,
+      included: [],
+      files: {},
+      bytes: 0,
+      loadFailed: true,
+      bootstrapCreated: [],
+    };
+  }
+}
+
+export function getLastHandoffTimestamp(sharedMemory) {
+  const handoff = sharedMemory?.files?.["agent-handoff.md"] || "";
+  const match = handoff.match(/^Last updated:\s*(.+)$/m);
+  return match ? match[1].trim() : "unknown";
+}
+
+export function loadAgentPrompts() {
+  const candidates = [
+    path.join(os.homedir(), ".crewswarm", "agent-prompts.json"),
+    path.join(os.homedir(), ".openclaw", "agent-prompts.json"),
+  ];
+  for (const p of candidates) {
+    try {
+      const prompts = JSON.parse(fs.readFileSync(p, "utf8"));
+      if (Object.keys(prompts).length > 0) {
+        const augmented = {};
+        for (const [key, value] of Object.entries(prompts)) {
+          augmented[key] = applySharedChatPromptOverlay(value, key);
+        }
+        return augmented;
+      }
+    } catch {}
+  }
+  return {};
+}
+
+function buildExecutionGuardrails(agentId = "") {
+  if (!agentId || agentId === "crew-lead") return "";
+
+  const isPM = agentId.startsWith("crew-pm");
+  const isQA = agentId === "crew-qa";
+  const isCoder =
+    agentId === "crew-coder" ||
+    agentId === "crew-coder-front" ||
+    agentId === "crew-coder-back" ||
+    agentId === "crew-fixer" ||
+    agentId === "crew-frontend";
+
+  const lines = [
+    "## Execution Guardrails",
+    "",
+    "OPERATING PRINCIPLES:",
+    "- Read before acting: @@READ_FILE any file before modifying or claiming its contents. Never guess what's in a file.",
+    "- Simplest approach first: do what was asked. Don't refactor surrounding code, add features, or over-engineer beyond the task.",
+    "- Match the request: a bug fix is just a bug fix. Don't clean up adjacent code, add docstrings to unchanged functions, or suggest a rewrite.",
+    "- Own mistakes: if something fails or you got it wrong, say so briefly and try a different approach. Don't repeat the same failing action.",
+    "",
+    "QUALITY:",
+    "- Retrieval-first: before a long or technical answer, gather real context from files/tool output first; do not rely on recollection.",
+    "- No stale claims: never assert runtime/model/service status unless verified in this turn by tool output or injected snapshot.",
+    "- Anti-loop: if the same failure pattern repeats twice, switch strategy (different tool path / narrower scope / fallback) and state the switch briefly.",
+    "- Never fabricate file contents, command output, or tool results. If you don't have data, use a tool to get it.",
+    "",
+    "STYLE:",
+    "- Lead with the answer or action, not the reasoning. Skip preamble and filler.",
+    "- Concise execution-first output (max 5 lines) unless the user or task asks for detail.",
+  ];
+
+  if (isPM) {
+    lines.push(
+      "- PM has two modes:",
+      "  - Conversational mode (research/ideation): personality and exploratory reasoning are encouraged.",
+      "  - Execution mode (artifact-producing): strict, structured output required.",
+      "- Enter PM execution mode when task includes concrete delivery signals (e.g. file paths, `@@WRITE_FILE`, roadmap/spec updates, explicit acceptance criteria, 'deliver/finalize/write').",
+      "- PM execution mode contract: end with `Deliverables:` (exact file paths) and `Acceptance Criteria:` (testable bullets).",
+    );
+  }
+  if (isQA) {
+    lines.push(
+      "- QA output contract: findings must include Severity, Repro steps, and concrete fix suggestion.",
+    );
+  }
+  if (isCoder) {
+    lines.push(
+      "- Coding output contract: include changed file paths and verification command output (`@@RUN_CMD` result) before completion.",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function buildTaskPrompt(taskText, sourceLabel, agentId, options = {}) {
+  const { projectDir: taskProjectDir, projectId: taskProjectId } = options;
+  const sharedMemory = loadSharedMemoryBundle();
+  if (sharedMemory.loadFailed) {
+    return { finalPrompt: "MEMORY_LOAD_FAILED", sharedMemory };
+  }
+  const lastHandoffTimestamp = getLastHandoffTimestamp(sharedMemory);
+
+  const contextNote = `[Shared memory loaded — UTC: ${new Date().toISOString().slice(0, 16).replace("T", " ")} | Last handoff: ${lastHandoffTimestamp.slice(0, 16) || "none"}]`;
+
+  // Inject agent-specific system prompt if one exists
+  const agentPrompts = loadAgentPrompts();
+  const bareId = agentId ? agentId.replace(/^crew-/, "") : null;
+  const agentSystemPrompt =
+    (agentId && agentPrompts[agentId]) ||
+    (bareId && agentPrompts[bareId]) ||
+    (agentId ? getSharedChatPromptOverlay(agentId) : null);
+
+  const agentAllowed = _loadAgentToolPermissions(agentId || "crew-main");
+  const toolInstructions = _buildToolInstructions(agentAllowed);
+
+  // Load global rules — injected into every agent if the file exists
+  const globalRulesPath = path.join(
+    os.homedir(),
+    ".crewswarm",
+    "global-rules.md",
+  );
+  const globalRules = (() => {
+    try {
+      const txt = fs.readFileSync(globalRulesPath, "utf8").trim();
+      return txt ? `## Global Rules (apply to all agents)\n${txt}` : "";
+    } catch {
+      return "";
+    }
+  })();
+
+  // Load agent-specific extra memory (e.g. lessons.md for coders + fixer)
+  const extraMemoryFiles = getAgentExtraMemory(agentId);
+  const extraMemorySections = [];
+  for (const fileName of extraMemoryFiles) {
+    const fullPath = path.join(SHARED_MEMORY_DIR, fileName);
+    if (!fs.existsSync(fullPath)) continue;
+    try {
+      let content = fs.readFileSync(fullPath, "utf8").trim();
+      if (content.length > 6000) content = content.slice(-6000); // tail-trim
+      if (content) extraMemorySections.push(`### ${fileName}\n${content}`);
+    } catch {}
+  }
+
+  // Inject agent identity — name, model, and ID so every agent knows who it is
+  let identityHeader = "";
+  if (agentId) {
+    const agentList = _loadAgentList();
+    const agentCfg = agentList.find((a) => a.id === agentId);
+    if (agentCfg) {
+      const displayName = agentCfg.identity?.name || agentCfg.name || agentId;
+      const emoji = agentCfg.identity?.emoji || agentCfg.emoji || "";
+      const role = agentCfg.identity?.theme || "";
+      const model = agentCfg.model || "unknown model";
+      identityHeader = `You are ${emoji ? emoji + " " : ""}${displayName} (agent ID: ${agentId}${role ? ", role: " + role : ""}, model: ${model}).`;
+    }
+  }
+
+  // Fixer: when a path in the task doesn't exist, discover it by searching the project (so wrong paths like src/api/routers/main.py → find src/api/main.py)
+  const projectRoot =
+    taskProjectDir ||
+    (agentId === "crew-fixer" ? _getOpencodeProjectDir() : null);
+  const desktopProjectsHint = path.join(
+    os.homedir(),
+    "Desktop",
+    "<project-name>",
+  );
+  let projectDiscoveryRule = "";
+  if (agentId === "crew-fixer") {
+    if (projectRoot) {
+      projectDiscoveryRule = `## Project discovery (apply when a path in the task is missing or wrong)\nProject root: ${projectRoot}\n- If a path in the task does not exist, search the project first: use @@RUN_CMD find "${projectRoot}" -name '<filename>' (e.g. main.py) or ls to locate the file. Do not report "file not found" until you have tried to resolve the path within this project.`;
+    } else {
+      projectDiscoveryRule = `## Project discovery (external projects)\n- External projects (e.g. polymarket-ai-strat) are NOT inside the crewswarm repo. Their root is typically ${desktopProjectsHint}. If a path contains "crewswarm/<project-name>/", replace that with "${path.join(os.homedir(), "Desktop")}/<project-name>/". Example: polymarket-ai-strat main.py is at ${path.join(os.homedir(), "Desktop", "polymarket-ai-strat", "src/api/main.py")} (not under crewswarm, and not src/api/routers/main.py). Use @@RUN_CMD find to locate files if unsure.`;
+    }
+  }
+
+  // Load per-project memory from <projectDir>/.crewswarm/context.md and brain.md
+  // context.md = static facts (GitHub, tech stack, danger zones) — human-authored
+  // brain.md   = accumulated knowledge — agents append via @@BRAIN when project selected
+  const projectMemorySections = [];
+  if (taskProjectDir) {
+    const projectMemoryDir = path.join(taskProjectDir, ".crewswarm");
+    for (const fname of ["context.md", "brain.md"]) {
+      const fpath = path.join(projectMemoryDir, fname);
+      try {
+        let content = fs.readFileSync(fpath, "utf8").trim();
+        if (content.length > 8000) content = content.slice(-8000);
+        if (content)
+          projectMemorySections.push(
+            `### Project ${fname} (${taskProjectDir})\n${content}`,
+          );
+      } catch {
+        /* file doesn't exist — skip silently */
+      }
+    }
+  }
+
+  const executionGuardrails = buildExecutionGuardrails(agentId);
+
+  const parts = [];
+  if (identityHeader) parts.push(identityHeader);
+  if (agentSystemPrompt) parts.push(agentSystemPrompt);
+  if (globalRules) parts.push(globalRules);
+  if (toolInstructions) parts.push(toolInstructions);
+  if (executionGuardrails) parts.push(executionGuardrails);
+  if (projectDiscoveryRule) parts.push(projectDiscoveryRule);
+  if (sharedMemory.text) parts.push(sharedMemory.text);
+  if (extraMemorySections.length > 0)
+    parts.push(extraMemorySections.join("\n\n"));
+  if (projectMemorySections.length > 0)
+    parts.push(projectMemorySections.join("\n\n"));
+
+  // Inject recent project conversation history so agents have context
+  if (taskProjectId) {
+    try {
+      const recentMessages = loadProjectMessages(taskProjectId, { limit: 20 });
+      if (recentMessages.length > 0) {
+        const historyLines = recentMessages.map((msg) => {
+          const who = msg.agent ? `[${msg.agent}]` : msg.role === "user" ? "[user]" : "[assistant]";
+          const text = String(msg.content || "").slice(0, 500);
+          return `${who} ${text}`;
+        });
+        // Cap total history to ~4000 chars to avoid blowing context
+        let historyText = historyLines.join("\n");
+        if (historyText.length > 4000) {
+          historyText = historyText.slice(-4000);
+        }
+        parts.push(`## Recent conversation history (project: ${taskProjectId})\n${historyText}`);
+      }
+    } catch {
+      /* project messages unavailable — skip silently */
+    }
+  }
+
+  parts.push(contextNote);
+  parts.push(taskText);
+
+  const finalPrompt = parts.join("\n\n");
+
+  return { finalPrompt, sharedMemory };
+}

package/lib/runtime/paths.mjs

@@ -0,0 +1,76 @@
+/**
+ * Centralized path resolution for crewswarm config and state directories.
+ * Supports test mode via environment variables for hermetic testing.
+ * 
+ * Environment variables:
+ * - CREWSWARM_CONFIG_DIR: Override config directory (default: ~/.crewswarm)
+ * - CREWSWARM_STATE_DIR: Override state directory (default: ~/.crewswarm)
+ * - CREWSWARM_TEST_MODE: Set to "true" to automatically use temp directories
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+let _configDir = null;
+let _stateDir = null;
+
+/**
+ * Get the crewswarm configuration directory.
+ * Used for: crewswarm.json, config.json, etc.
+ */
+export function getConfigDir() {
+  if (_configDir) return _configDir;
+  
+  if (process.env.CREWSWARM_TEST_MODE === "true") {
+    // Use a consistent temp dir for the entire test process (not per-call)
+    _configDir = path.join(os.tmpdir(), `crewswarm-test-${process.pid}`);
+  } else {
+    _configDir = process.env.CREWSWARM_CONFIG_DIR || path.join(os.homedir(), ".crewswarm");
+  }
+  
+  fs.mkdirSync(_configDir, { recursive: true });
+  return _configDir;
+}
+
+/**
+ * Get the crewswarm state directory.
+ * Used for: chat-history, spending.json, token-usage.json, logs, etc.
+ */
+export function getStateDir() {
+  if (_stateDir) return _stateDir;
+  
+  if (process.env.CREWSWARM_TEST_MODE === "true") {
+    // Use a consistent temp dir for the entire test process (not per-call)
+    _stateDir = path.join(os.tmpdir(), `crewswarm-test-${process.pid}`);
+  } else {
+    _stateDir = process.env.CREWSWARM_STATE_DIR || path.join(os.homedir(), ".crewswarm");
+  }
+  
+  fs.mkdirSync(_stateDir, { recursive: true });
+  return _stateDir;
+}
+
+/**
+ * Get a path within the config directory.
+ * @param {...string} parts - Path components to join
+ */
+export function getConfigPath(...parts) {
+  return path.join(getConfigDir(), ...parts);
+}
+
+/**
+ * Get a path within the state directory.
+ * @param {...string} parts - Path components to join
+ */
+export function getStatePath(...parts) {
+  return path.join(getStateDir(), ...parts);
+}
+
+/**
+ * Reset cached paths (useful for testing).
+ */
+export function resetPaths() {
+  _configDir = null;
+  _stateDir = null;
+}

package/lib/runtime/project-dir.mjs

@@ -0,0 +1,127 @@
+/**
+ * Normalize user-supplied project / output directory paths.
+ * Fixes common dashboard typos (e.g. ~Desktop/foo instead of ~/Desktop/foo).
+ */
+
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * @param {string|null|undefined} raw
+ * @returns {string|null} Absolute normalized path, or null if empty/invalid
+ */
+export function normalizeProjectDir(raw) {
+  if (raw == null) return null;
+  let s = String(raw).trim();
+  if (!s) return null;
+
+  const home = os.homedir();
+
+  // Typo: "~/Desktop/foo" pasted without slash → "~Desktop/foo"
+  if (/^~Desktop\//i.test(s)) {
+    s = path.join(home, "Desktop", s.replace(/^~Desktop\//i, ""));
+  } else if (/^~desktop$/i.test(s)) {
+    s = path.join(home, "Desktop");
+  }
+
+  // Standard tilde expansion
+  if (s === "~") {
+    s = home;
+  } else if (s.startsWith("~/") || s.startsWith("~\\")) {
+    s = path.join(home, s.slice(2));
+  }
+
+  try {
+    if (path.isAbsolute(s)) {
+      return path.normalize(s);
+    }
+    // Relative paths: resolve from cwd (last resort)
+    return path.normalize(path.resolve(process.cwd(), s));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * LLMs / sandboxes often embed the mistaken path `…/<repo>/~Desktop/<project>/` (missing `/` after `~`).
+ * Planning files land there while builds use the real `~/Desktop/<project>/`. Rewrite task text to the
+ * canonical project directory so @@READ_FILE paths resolve.
+ *
+ * @param {string} text
+ * @param {string} canonicalDir absolute project root (e.g. /Users/you/Desktop/stinky-1)
+ * @returns {string}
+ */
+export function rewriteWrongDesktopMirrorPaths(text, canonicalDir) {
+  if (!text || typeof text !== "string" || !canonicalDir) return text;
+  const canon = path.resolve(String(canonicalDir).trim()).replace(/\\/g, "/");
+  const base = path.basename(canon);
+  if (!base || base === "." || base === "..") return text;
+
+  const wrongUnderCwd = path
+    .join(process.cwd(), "~Desktop", base)
+    .replace(/\\/g, "/");
+  const wrongUnderCwdNorm = path
+    .normalize(path.join(process.cwd(), "~Desktop", base))
+    .replace(/\\/g, "/");
+
+  let out = text;
+  const pairs = [
+    [wrongUnderCwd, canon],
+    [wrongUnderCwdNorm, canon],
+  ];
+  for (const [w, c] of pairs) {
+    if (w && w !== c && out.includes(w)) out = out.split(w).join(c);
+  }
+
+  // Any absolute path segment `.../~Desktop/<basename>` (typo) → canon (keep suffix after basename)
+  const escapedBase = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(
+    String.raw`([A-Za-z]:)?(?:/[^/\s"']*)*/\~Desktop/` + escapedBase + String.raw`(?=/|\s|"|'|$)`,
+    "gi",
+  );
+  out = out.replace(re, () => canon);
+
+  return out;
+}
+
+/**
+ * OpenCode (and similar sandboxes) treat absolute paths outside the active session root as
+ * `external_directory` and auto-reject in non-interactive mode. When cwd/projectDir is already
+ * the project root, rewrite obvious absolute/~/ paths to ./ so tools stay in-workspace.
+ *
+ * @param {string} taskText
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function rewriteTaskPathsRelativeToProjectRoot(taskText, projectDir) {
+  if (!taskText || typeof taskText !== "string" || !projectDir) return taskText;
+  let canon;
+  try {
+    canon = path.resolve(String(projectDir).trim()).replace(/\\/g, "/");
+  } catch {
+    return taskText;
+  }
+  const noTrail = canon.replace(/\/+$/, "");
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  let out = taskText;
+  out = out.replace(new RegExp(esc(noTrail) + "/", "g"), "./");
+  const base = path.basename(noTrail);
+  if (base && base !== "." && base !== "..") {
+    const homeDesk = path.join(os.homedir(), "Desktop", base).replace(/\\/g, "/");
+    if (homeDesk === noTrail) {
+      out = out.replace(
+        new RegExp(`~\\/Desktop\\/${esc(base)}\\/`, "g"),
+        "./",
+      );
+      out = out.replace(
+        new RegExp(`~/Desktop/${esc(base)}/`, "g"),
+        "./",
+      );
+      out = out.replace(
+        new RegExp(`~/Desktop/${esc(base)}(?=[/\\s"'\\)\\]>|$])`, "g"),
+        ".",
+      );
+    }
+  }
+  return out;
+}